Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

feature/Pipelex-hosted-client-problem · L-261019-58fcf6 (#1484)

Louis Choquel11dac14130f0
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index 3692532e8..977a4a470 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:5e8e0e791107e17b9da7c48df71037ac92ea1d0c87e69a172e03eae2d3126556"
+digest = "sha256:197170f0ab55d758506727daadfedcd91777769b1d964a49a81b6b3ca5c91970"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-10-22T15:31:43Z"
-rationale = "real-catch: a hosted run's failed tree upload now carries pipelex-sdk's verdict as the agent CLI problem's retry and step kind, and a lost connection reads as client.outcome_unknown only when pipelex-sdk says the run may have started; docs/tools/cli/run.md, agent-cli.md and pipelex/cli/agent_cli/CLAUDE.md now say so. No flag or output format changed."
+reviewed_at = "2026-10-24T04:25:12Z"
+rationale = "real-catch: both CLIs now report a hosted failure as the problem pipelex-sdk carries, the human CLI printing its rows, items and the run's own problem; the former-shape readings are gone, a bare 401/403/404 is read by the key sent, a run past the wait is client.follow_failed and a failed tree upload reads by its reason; docs/tools/cli/run.md, agent-cli.md and pipelex/cli/agent_cli/CLAUDE.md now say so. No flag or output format changed."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -38,7 +38,7 @@ rationale = "real-catch: a hosted run's failed tree upload now carries pipelex-s
"pipelex/cli/agent_cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/run/_output_helpers.py" = "blob:40ed1700e0d5e86d7696eadd7f9887baeb8059f6"
"pipelex/cli/agent_cli/commands/run/_run_core.py" = "blob:6190638f8542dd39db5458bc47a2da332fb39726"
-"pipelex/cli/agent_cli/commands/run/_run_hosted.py" = "blob:96803db7f0a09728ebaa8aa9d099461fec0e9105"
+"pipelex/cli/agent_cli/commands/run/_run_hosted.py" = "blob:5668f5017aa075d9ff1c658733a92028c4a989b5"
"pipelex/cli/agent_cli/commands/run/app.py" = "blob:7546d9b31ea2dc22b1ddae538edfbc8e7f7d08df"
"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:7a30bb003770fec1db0c4b839017c50f7e6959a2"
"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:41e1060693568363d922fad1f8663c05bfdab351"
@@ -112,7 +112,7 @@ rationale = "real-catch: a hosted run's failed tree upload now carries pipelex-s
"pipelex/cli/commands/run/_inputs_path_resolver.py" = "blob:c8ec89d98718e18af7aaaded44c9f545be60adab"
"pipelex/cli/commands/run/_main_stuff_file.py" = "blob:ca806e55085aa2e5748492751521296ce1f42960"
"pipelex/cli/commands/run/_run_core.py" = "blob:c70b6f445b2961cbd0eda878f23900ece290dfd8"
-"pipelex/cli/commands/run/_run_hosted.py" = "blob:31a956c8fdde89bb83382f0153c5092a60af60da"
+"pipelex/cli/commands/run/_run_hosted.py" = "blob:15fb46c9e30307ba4e72df0e0deafcada1d868f3"
"pipelex/cli/commands/run/_run_output_folder.py" = "blob:6f3b237849d9b6498a4dbf5cb81ceea948c91782"
"pipelex/cli/commands/run/app.py" = "blob:e312b159625e0a72bc9a18d3bfd2c73e7ac59f24"
"pipelex/cli/commands/run/bundle_cmd.py" = "blob:a33dc6bd6c08715d880a587da54114055e9d5e1b"
@@ -130,7 +130,7 @@ rationale = "real-catch: a hosted run's failed tree upload now carries pipelex-s
"pipelex/cli/commands/validate/pipe_cmd.py" = "blob:ab8cca9c5c8c5d7dce005deba6d2d8b32dc2e81e"
"pipelex/cli/commands/which_cmd.py" = "blob:5febd14510603f09ef0fb29d5ef97c35b7a6692f"
"pipelex/cli/deck_notice.py" = "blob:542877125e89e35b02bc969cfee952155b0d7c2c"
-"pipelex/cli/error_handlers.py" = "blob:6f208c35d91cecaef82927634df9c58553dd181e"
+"pipelex/cli/error_handlers.py" = "blob:649461025ca7a84b2e73bfe63cd2649d472f4088"
"pipelex/cli/exceptions.py" = "blob:5c66f20b0a06c8ae8c20b94f92e2c30b78f5b6c5"
"pipelex/cli/installed_methods.py" = "blob:7e7f289d50ca6bc446b6891cbc846dc4a8cee6e2"
"pipelex/cli/judged_target.py" = "blob:626ccf65bc3b15e06422d9f16c0b1a8083041b59"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 41b64c91d..5568b3a81 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,15 +19,17 @@
- **The refusal of a package the request did not send**: the message of the `unresolved_package_dependency` refusal a static resolution gives, such as the one behind `/v1/resolve`, `/v1/codegen` and `/v1/pipe-io`, tells its reader to send the package's files in `dependencies`, keyed by its address, beside the method's own files in `files`, where it spoke of an in-memory resolve and the host filesystem and advised directory-based resolution; it still carries the words `address-based dependency '<address>'`.
- **A run lists each method tree once (Breaking)**: the method trees a run reads, the method's own, its library directories' and its dependency packages', are each listed once, and the run loads the trees its caller listed, so the `method_tree_digest` a run records is the digest of the tree it loaded: `PipelexMTHDSProtocol.execute`, `pipeline_run_setup`, `acquire_library`, `acquire_library_async`, `validate_bundle`, `validate_bundles_in_process`, `fix_bundle_file`, `fix_method_folder`, and `LibraryManagerAbstract.load_libraries` and `load_from_blueprints` take `tree_listing`, a `MethodTreeListing` (`pipelex.libraries.method_tree_listing`) holding the trees already listed, which `run bundle`, `validate bundle` and `fix bundle` on both CLIs hand down from the listing that resolved their target. The listing reads a path as the standard's lister does before it takes anything from what it holds: a folder and a symbolic link naming it are one listing, since the lister follows such a link, a bundle file named alone inside a library directory shares the listing of the tree that directory roots, and a symbolic link to a bundle file, named alone, is refused as the lister refuses it, even once the run listed the file it points to. Loads of one run running at the same time list each tree once and list different trees side by side. The API server's run routes and `/v1/validate` load the trees their check of the method's requirements listed, which `ensure_served_method_requirements_met` now lists through `tree_listing` in place of its `limits`, and which reaches the in-process validator through `scoped_tree_listing`, so the bundle-validator plugin contract is unchanged. `list_library_trees` and `list_library_dir_trees` (`pipelex.libraries.method_trees`) take the lister of a directory's own tree or of its trees (`own_tree_of`, `trees_of`), through which the listing lists them, and `tree_bundle_of_lone_file` is removed: a bundle file named alone is placed in its tree with `MethodTreeListing.lone_file_bundle`.
- **A run asks the PipeFunc package-offer factory once per tree**: the run's `MethodTreeListing` keeps each method tree and each dependency package whose `requirements.txt` a check found met, with the execution mode and the factory it was judged against (`PipeFuncEnvironmentSource`, `current_pipe_func_environment_source` in `pipelex.libraries.package_environments`), so a run judges each tree once against them however many of its steps and loads read it, two loads judging one tree at the same moment ask once (`MethodTreeListing.judge_requirements_once`), and on the API server the load serving a request takes the verdict of the runner's check of the served method instead of asking the factory again. A check against another mode or factory, a refused tree and every new run ask again: pipelex keeps a verdict for one run alone, so a factory whose answer takes time keeps its own cache across runs, by the requirements' texts. `ensure_method_requirements_met` and `ensure_package_requirements_met` take the listing as `tree_listing`.
-- **`mthds` 0.25.0 and `pipelex-sdk` 0.48.0 (Breaking)**: pipelex pins `mthds==0.25.0` and `pipelex-sdk==0.48.0`, so it implements the MTHDS standard 8.0.0 and the protocol 2.0.0, which the version handshake reports, and a method tree never holds a run's inputs file, `inputs.json` or `inputs.toml` at any depth, so a method folder holding one is listed, and digested, without it.
+- **`mthds` 0.25.0 and `pipelex-sdk` 0.53.0 (Breaking)**: pipelex pins `mthds==0.25.0` and `pipelex-sdk==0.53.0`, the release whose errors carry the hosted API's problem document, so it implements the MTHDS standard 8.0.0 and the protocol 2.0.0, which the version handshake reports, and a method tree never holds a run's inputs file, `inputs.json` or `inputs.toml` at any depth, so a method folder holding one is listed, and digested, without it.
- **`PipelexMTHDSProtocol` takes the protocol's `files` (Breaking)**: `execute`, `start` and `validate` take the MTHDS protocol's `files` map in the position the protocol gives it, and the local runtime refuses a map holding a file with `request.unsupported` and the reason `method_files_on_local_runtime`, `METHOD_FILES_UNSUPPORTED_REASON` in `pipelex.errors.unsupported_reasons`; `mthds_contents` is a keyword-only argument, which `validate` requires. The API server's `ApiRunner` takes the same arguments, and its routes, which write a method sent in `files` out as a tree before they run it, are unchanged.
- **A hosted run sends its method as a tree (Breaking)**: `pipelex run --hosted` and `pipelex-agent run --runner hosted` send a local method to `/v1/pipe-io`, `/v1/start` and `/v1/execute` as the MTHDS protocol's `files` map, each `.mthds` bundle under its path in the method's tree and each library directory beside the method under a top-level folder named after it, inline up to 256 KiB and by hash beyond, where the run took the bundles' bare contents and pipe-io a list the runner now refuses with a `422`, so a hosted run whose inputs name a local file reads the signature again, and a method that does not load is reported by the tree path of each faulty file. `HostedRunRequest` (`pipelex.hosted.hosted_run`) takes `contents`, each bundle's bytes by tree path, in place of `mthds_files`. A file of the tree that cannot be uploaded stops the run before anything starts, as pipelex-sdk's `MethodFileTransferError`, which both CLIs report with the SDK's verdict and a next step: run again, or report a file the storage refused. A bundle file given with `-L` that the membership rule keeps out of its tree, a hidden one under a dot segment or one `.gitignore` excludes, is refused before anything is sent, as a local run refuses it, where it was sent as it was.
-- **A hosted run's lost connection follows pipelex-sdk's reading**: `pipelex run --hosted` and `pipelex-agent run --runner hosted` report a connection lost on the start or the execute request as `HostedRunOutcomeUnknownError` (`client.outcome_unknown`) whenever pipelex-sdk reads it as one that may have started the run (`run_may_have_started`), a proxy's failure and a TLS handshake that was dropped included, which read as an unreachable API, while a connection lost on a request sent before the run's, such as the blob check of a tree sent by hash, stays pipelex-sdk's `ApiUnreachableError`.
+- **A hosted run's lost connection follows pipelex-sdk's reading**: `pipelex run --hosted` and `pipelex-agent run --runner hosted` report a connection lost on the start or the execute request as `HostedRunOutcomeUnknownError` (`client.outcome_unknown`) whenever pipelex-sdk reads it as one that may have started the run (its problem's retry verdict `outcome_unknown`), a proxy's failure and a TLS handshake that was dropped included, which read as an unreachable API, while a connection lost on a request sent before the run's, such as the blob check of a tree sent by hash, stays pipelex-sdk's `ApiUnreachableError`.
+- **Both CLIs report a hosted failure as its problem (Breaking)**: `pipelex run --hosted` prints the problem `pipelex-agent run --runner hosted` reports, its title, detail, next step, code with its domain and retry verdict, request id, run and items, and a failed run's own problem below it, both read from pipelex-sdk's `exc.problem` through `describe_hosted_error`, which now takes `credential_sent` and returns the problem, the error's own sentence and pipelex's advice. The readers of the hosted API's answers in the shape that predates the problem document are removed: an answer that is no problem document keeps pipelex-sdk's reading by its status, except a bare `401` or `403`, which reads as `auth.missing_credential` when no key was sent and `auth.invalid_credential` when one was, and a bare `404`, `request.not_found`, each with the next step that names the CLI's settings. `HostedMethodInvalidError` carries the items of the pipe-io verdict as `errors`, the standard's problem items, where it carried `validation_errors`, and a run past the wait reports pipelex-sdk's `client.follow_failed`.
- **`pipelex-agent validate bundle` and `fix bundle` exit 2 on a configuration refused before the boot**: a configuration that does not validate, which these commands read before the boot for the limits a method's folder is listed under, exits 2, no verdict, where it exited 1, as `pipelex validate bundle` and `pipelex fix bundle` exit on it; the problem is unchanged, and `run bundle` and `inputs bundle` still exit 1.
- **The development Python is pinned in `.python-version`**: the library's `.venv` and the API server's `api/.venv` are built on the version the root `.python-version` names, and the Makefiles hand that version to every uv command, so `PYTHON_VERSION=<version> make install` now moves an existing environment to the version asked for, where it used to keep the environment's own Python without a word. The CI jobs that run another version set it for the whole job, and the matrix jobs check that each cell ran the version it names.
### Fixed
+- **A hosted run refusing a local file names its reason**: the `request.unsupported` problem `pipelex run --hosted` and `pipelex-agent run --runner hosted` report when the inputs name a local file and the method calls another by its address carries the parameters its code requires, `field` (`inputs`) and `reason` (`local_file_with_address_dependency`, `LOCAL_FILE_WITH_ADDRESS_DEPENDENCY_UNSUPPORTED_REASON` in `pipelex.errors.unsupported_reasons`), so a client can tell this refusal apart.
- **A file name's type is the same on every Python**: `mime_type_of_file_name` answers `text/markdown` for `.md` and `.markdown`, `application/yaml` for `.yaml` and `.yml`, and the OpenDocument types for `.odt`, `.ods` and `.odp` on every supported Python, where Python 3.11's table knew no Markdown and only 3.14's knew the others, so a file of these types has the format key `md`, `yaml`, `odt`, `ods` or `odp` whatever the Python, and a bare zip named `.odt`, `.ods` or `.odp` is identified as that OpenDocument type.
- **A method edited between its listing and its load is refused**: a run read its method's files again after listing them, so a file edited in between was loaded under a digest that named other bytes. Every file a load reads from a tree listed on this host, a bundle it parses, the `requirements.txt` it judges and the Python it scans, is now read against the hash the listing recorded, a load reads every file of a tree the run listed before it again, once per run, as it takes the tree, and the bundle text a CLI read for its run is checked against the listed file, so a bundle, a template or any other file of the tree edited, replaced or removed since the listing is refused before anything of the method is parsed, imported or run, with `MethodTreeChangedError` (`pipelex.libraries.exceptions`), coded `method.package_invalid` with the new reason `tree_changed` and the file's `path` in the tree; `run`, `validate` and `fix` report it as an invalid method whose item names that file. A `requirements.txt` that can no longer be read is this refusal too, where it was `requirements_invalid`. The checked reads are `read_tree_file_as_listed`, `read_tree_bundle_as_listed`, `ensure_tree_files_as_listed` and `ensure_bundle_text_as_listed` in `pipelex.libraries.method_trees`, `MethodTreeListing.loading()` marks a load reading a listing and `ensure_unchanged()` checks a tree a caller placed a bundle in, and `MthdsParser.make_pipelex_bundle_blueprint` takes the bytes it parses as `bundle_data`, beside the `bundle_path` that names them.
- **Method loads leave the event loop**: every method load pipelex reaches from asynchronous code, a run's, a validation's and those of the commands that run a loop, runs in the method-load pool, where it ran on the event loop, the reading and parsing of the bundles it loads included, so listing and hashing a method's files, a sandbox's judgment of its `requirements.txt` and a fetch of a package it calls by address no longer hold up the other requests or activities the loop serves; the API server's run routes and `/v1/validate` also write a request's method tree to disk and remove it there, and judge its requirements there, so a client that disconnects never has the tree removed while the check still reads it, the crate routes resolve and project there, and the in-process validator reads a tree's entry pipe for its graph there too. A module imported by file while a method loads, such as one defining a structure class, is published and executed under a lock that the load's class discovery also holds, so two loads in parallel never take a module half executed, and a module that fails to execute leaves `sys.modules` rather than stay there half imported. `/v1/validate` of a method tree calling a package nothing shipped still resolves it as a run does, from the methods installed on the server and by a fetch on a miss, so its verdict matches the run's, and the fetch now runs off the event loop.
diff --git a/docs/building-methods/pipes/running-on-the-hosted-api.md b/docs/building-methods/pipes/running-on-the-hosted-api.md
index 34dc8e68f..a860418de 100644
--- a/docs/building-methods/pipes/running-on-the-hosted-api.md
+++ b/docs/building-methods/pipes/running-on-the-hosted-api.md
@@ -77,34 +77,38 @@ Two cases where `pipelex run --hosted` goes further than `prepare_inputs`:
## Errors
-A failure is one of the SDK's typed errors, from `pipelex_sdk.errors`, all subclasses of the protocol's `PipelineRequestError`:
+A failure is one of the SDK's typed errors, from `pipelex_sdk.errors`, all subclasses of the protocol's `PipelineRequestError`, and every one carries what went wrong as the MTHDS standard's problem document, `exc.problem`. Branch on `exc.problem.code`, the stable name of the case in the [error registry](../../errors/index.md), never on an HTTP status or the wording of a message. Beside its code, the problem says who acts on the failure (`exc.problem.effective_domain`), whether sending the same thing again can help (`exc.problem.effective_retry`: `yes`, `no`, or `outcome_unknown` when a run may have started), how long to wait first when the answer said (`retry_after`, in seconds), what to do next (`next_step.kind` and `next_step.detail`), and the faults one by one when there are several (`errors`, each with its own `code`, `detail` and `location`).
-- `ApiResponseError` is a refusal the hosted API answered: `status`, the reason in `server_message`, the next step in `user_action.detail` when the server advised one, and `validation_errors` locating the faults of a bundle it refused to load.
-- `RunFailedError` is a run that started and failed; `error` holds the error the hosted API stored for the run, with the runner's `error_type`, `message`, `error_domain` and `user_action`.
-- `RunTimeoutError` is a run that outlived the wait; it keeps running, and `run_id` reads its result later with `wait_for_result`.
-- `ApiUnreachableError` is a request that got no answer, on every route, `start` and `execute` included. Its `__cause__` is httpx's exception, and its `code` names the failure: `ABORT_TIMEOUT` for a read or a write that timed out, otherwise httpx's class name, such as `ConnectError`, `ConnectTimeout`, `ReadError` or `RemoteProtocolError`.
+- `ApiResponseError` is an answer the hosted API, or a server in front of it, gave. Its problem is the answer's own problem document, as the hosted API answers every refusal, with the runner's own code and next step. An answer that is no problem document, such as a gateway's error page, is read from its status: `auth.missing_credential` for a `401`, `auth.invalid_credential` for a `403`, `request.not_found` for a `404`, `runtime.unavailable` with `retry` `yes` for a `408`, a `429`, a `502`, a `503` or a `504`, `runtime.unexpected` for a `500`, and `client.response_unreadable` naming the status for any other. `status` is the answer's HTTP status and `request_id` the id to quote to support.
+- `RunFailedError` is a run that started and failed. Its problem is `run.failed`, naming the run and its terminal status, and `run_error` is the run's own problem, why it did not succeed, under its own code, with its own retry verdict and next step, or `None` when the run stored none.
+- `RunTimeoutError` is a run that outlived the wait. Its problem is `client.follow_failed`: the run keeps running, and `run_id` reads its result later with `wait_for_result`.
+- `ApiUnreachableError` is a request that got no answer, on every route, `start` and `execute` included. Its problem is `client.unreachable` naming the base URL, or `client.timeout` naming the time limit for a request whose time ran out. Its `__cause__` is httpx's exception, and its `network_code` names the failure: `ABORT_TIMEOUT` for a read or a write that timed out, otherwise httpx's class name, such as `ConnectError`, `ConnectTimeout`, `ReadError` or `RemoteProtocolError`.
- `InputPreparationError` and its subclasses are a local file that could not be read or uploaded.
-- `MethodFileTransferError` is a file of a tree sent by hash that could not be uploaded to the hosted API's storage before the request, so nothing was started. Its `code` says why, `unreachable`, `storage_error` or `refused`, and `retryable` whether the same call can succeed later, which holds for every code but `refused`.
+- `MethodFileTransferError` is a file of a tree sent by hash that could not be uploaded to the hosted API's storage before the request, so nothing was started. Its `reason` says why, `unreachable`, `storage_error`, `refused` or `mismatch`, and its problem's retry verdict whether the same call can succeed later, which holds for `unreachable` and `storage_error`.
### A Start That Got No Answer
-An `ApiUnreachableError` raised by `start` or `execute` says whether the run may have been created, in `run_may_have_started`. pipelex-sdk sets it only on the start or the execute request itself, and only when the transport failure does not prove the request never left your machine. It is `False` for a connection that could not be made, and for a failure on a request the call sends before the run's, such as the blob check of a tree sent by hash, so no run exists and starting again is safe. It is `True` for a read or a write that failed or timed out, a connection closed once the request had left, a proxy's failure or a TLS handshake that was dropped, any of which can come after the hosted API received the request: a run may exist with no id returned, so check the run history on app.pipelex.com before starting it again.
+A failure of `start` or `execute` says whether the run may have been created: its problem is then `client.outcome_unknown`, whose retry verdict is `outcome_unknown`. pipelex-sdk reads it on the start or the execute request alone. An `ApiUnreachableError` reads so unless the transport failure proves the request never left your machine: a connection that could not be made, or a failure on a request the call sends before the run's, such as the blob check of a tree sent by hash, created no run, so starting again is safe. A read or a write that failed or timed out, a connection closed once the request had left, a proxy's failure or a TLS handshake that was dropped can each come after the hosted API received the request. So can a gateway's bare answer to the start, a `408` or a `5xx` other than `501`, which arrives as an `ApiResponseError`. In those cases a run may exist with no id returned, so check the run history on app.pipelex.com before starting it again.
```python
-from pipelex_sdk.errors import ApiUnreachableError
+from mthds.protocol.problem.registry import RetryVerdict
+from pipelex_sdk.errors import PipelexRequestError
try:
started = await client.start(method_ref="github.com/Pipelex/methods/[email protected]", inputs={"text": "Hello world."})
-except ApiUnreachableError as exc:
- if exc.run_may_have_started:
- ... # A run may exist: look it up in the run history before starting again.
- else:
- ... # No run was created: check the network and the origin, then start again.
+except PipelexRequestError as exc:
+ match exc.problem.effective_retry:
+ case RetryVerdict.OUTCOME_UNKNOWN:
+ ... # A run may exist: look it up in the run history before starting again.
+ case RetryVerdict.YES:
+ ... # No run was created: wait `exc.problem.retry_after` seconds when it says, then start again.
+ case RetryVerdict.NO:
+ ... # Starting again changes nothing: do what `exc.problem.next_step.detail` says first.
```
-`start_and_wait` sends more than the start, so tell its requests apart with its two callbacks. `on_starting` is called right before each request that may create a run is sent, and `on_started` with the acknowledgement once the run exists. A failure before `on_starting` was called started nothing, a failure after `on_started` concerns a run whose id you hold, which `wait_for_result` follows, and only a failure in between needs `run_may_have_started` read as above.
+`start_and_wait` sends more than the start, so tell its requests apart with its two callbacks. `on_starting` is called right before each request that may create a run is sent, and `on_started` with the acknowledgement once the run exists. A failure before `on_starting` was called started nothing, a failure after `on_started` concerns a run whose id you hold, which `wait_for_result` follows, and only a failure in between needs its retry verdict read as above.
-`pipelex run --hosted` and `pipelex-agent run --runner hosted` draw the same line, and report the second case as pipelex's own `HostedRunOutcomeUnknownError`. `PipelexAPIClient` never raises that error, so a program that calls the client directly reads the cause itself.
+`pipelex run --hosted` and `pipelex-agent run --runner hosted` draw the same line, and report a connection lost on the run request as pipelex's own `HostedRunOutcomeUnknownError`. `PipelexAPIClient` never raises that error, so a program that calls the client directly reads the problem itself.
## Related Documentation
diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.md
index aba7ad935..33ac2b134 100644
--- a/docs/tools/cli/agent-cli.md
+++ b/docs/tools/cli/agent-cli.md
@@ -225,7 +225,7 @@ JSON commands return the result object directly. They are not wrapped in a `stat
For the structured commands, exactly one problem is written to stderr per failure, so the stream parses as a single JSON document.
-Branch on `code`, the stable name of the case in the [error registry](../../errors/index.md), and on what it decides: `domain`, who acts on the failure (`input`, `method`, `account`, `operator` or `runtime`), `retry`, whether sending the same thing again can help (`yes`, `no`, `after`, or `unknown`), and `next_step`, whose `kind` an agent can branch on and whose `detail` says what to do. `params` holds the code's parameters, `location` where the fault is (the pipe and its path from the entry pipe, the input, the field, the file, the line), `errors` the faults one by one when there are several, each with its own `code`, `detail`, `params`, `location`, `suggestions` and `suggested_fix`, `request_id` and `pipeline_run_id` what to quote when there is a request or a run behind it, and `diagnostics` the operator's facts: the class of the error behind the failure, its message capped, its causes, the model and the provider of a failed inference call, and a pending configuration migration. Every member that has nothing to say is left out. Beside the problem, `message` is the command's own sentence about the failure, and a command adds its own members, such as `is_valid` on an invalid verdict. A refusal the command makes itself has a code of its own: `client.argument_invalid` for an argument (`params.argument` and `params.reason`), `client.file_unreadable` for a file it cannot read (`params.path` and `params.reason`, which is `not found` or the system's own reason, such as `permission denied` or `is a directory`, for the bundle file of `validate bundle`, `inputs bundle`, `fix bundle` and `run bundle`, and `not UTF-8 text` too for an `--inputs` file and `init --config`'s file), `client.tool_missing` when `plxt` is not installed, and `pipelex.config.file_missing` when `init` finds a configuration file it should have written missing. An error of the system that names no file, such as a refused connection or a timeout met while a bundle command runs, refuses no file: it is `runtime.unexpected`. A bundle file that is not UTF-8 text does not parse, so every bundle command reports it as `validate bundle` does: the invalid verdict, its item `method.syntax`, located at the first byte that does not decode. A failure that is no Pipelex error, which is a bug, is `runtime.unexpected`.
+Branch on `code`, the stable name of the case in the [error registry](../../errors/index.md), and on what it decides: `domain`, who acts on the failure (`input`, `method`, `account`, `operator` or `runtime`), `retry`, whether sending the same thing again can help (`yes`, `no`, or `outcome_unknown` when a run may have started and should be looked up rather than started again), and `next_step`, whose `kind` an agent can branch on and whose `detail` says what to do. `params` holds the code's parameters, `location` where the fault is (the pipe and its path from the entry pipe, the input, the field, the file, the line), `errors` the faults one by one when there are several, each with its own `code`, `detail`, `params`, `location`, `suggestions` and `suggested_fix`, `request_id` and `pipeline_run_id` what to quote when there is a request or a run behind it, and `diagnostics` the operator's facts: the class of the error behind the failure, its message capped, its causes, the model and the provider of a failed inference call, and a pending configuration migration. Every member that has nothing to say is left out. Beside the problem, `message` is the command's own sentence about the failure, and a command adds its own members, such as `is_valid` on an invalid verdict. A refusal the command makes itself has a code of its own: `client.argument_invalid` for an argument (`params.argument` and `params.reason`), `client.file_unreadable` for a file it cannot read (`params.path` and `params.reason`, which is `not found` or the system's own reason, such as `permission denied` or `is a directory`, for the bundle file of `validate bundle`, `inputs bundle`, `fix bundle` and `run bundle`, and `not UTF-8 text` too for an `--inputs` file and `init --config`'s file), `client.tool_missing` when `plxt` is not installed, and `pipelex.config.file_missing` when `init` finds a configuration file it should have written missing. An error of the system that names no file, such as a refused connection or a timeout met while a bundle command runs, refuses no file: it is `runtime.unexpected`. A bundle file that is not UTF-8 text does not parse, so every bundle command reports it as `validate bundle` does: the invalid verdict, its item `method.syntax`, located at the first byte that does not decode. A failure that is no Pipelex error, which is a bug, is `runtime.unexpected`.
In Markdown, the default, the problem reads as a `## <title>` heading, the detail, the command's own sentence when it says more, the `**Next step**` with its kind, the advice the error gives as a `💡` tip when it says more than the next step (a boot that fails with no advice of its own tips the recovery path: `pipelex-agent doctor`, then `pipelex-agent migrate --dry-run --format json`, shown to the user, and `--yes`, or `pipelex-agent init`, `--global` for the home configuration, which writes a fresh configuration and discards its settings, while the problem, its code and `diagnostics.error_class` included, stays the failure's own), then the code with its domain and retry verdict, the request, the run and the location, the faults under `### Errors`, one per line with the item's code, its sentence and its location, then its suggestions and its suggested fix (an unsafe fix says to confirm it before applying it), the same items the JSON's `errors` lists, a `### Diagnostics` section and the command's own members under `### Details`. No stack frame is printed in either format.
@@ -233,13 +233,12 @@ In Markdown, the default, the problem reads as a `## <title>` heading, the detai
**A run on a runner** (`--runner hosted`, on the hosted Pipelex API or on the runner `--base-url` names) that fails reports the problem the runner answered or the client decided, as it came, in the caller's view, since the runner is someone else's runtime: no `diagnostics`, and the next step the runner gave its caller. It is Markdown by default and JSON with `--error-format json`, like any other failure. What this CLI refuses before anything is sent, a `--runner` that contradicts `--hosted`, a `--base-url` on a local run, a local-only flag, a configuration that cannot be read, is a problem like any local refusal, in the operator's view. The method itself is the exception: `run bundle` reads its bundle before it sends it, and a bundle that does not parse or does not validate (`method.invalid`, its faults in `errors`, each with its file and its place in it), or a bundle file or folder with no pipe to start at (`request.pipe_unspecified`, its `params.candidates` the pipes it could start at), is refused then, in the caller's view, as the runner would refuse the same method: no `diagnostics` and no `message`, so no class name and none of the text only an operator reads, while the code, the items, their locations and the next step stay. A run on this machine reports the same refusal in the operator's view, with the command's own sentence. The failures of the run itself read as follows.
-- **A run the runner refuses** reports the runner's problem document by the members the standard and Pipelex declare: its `code`, `domain`, `retry`, `next_step`, `params`, `location`, its `errors` items, each with its `code`, `detail`, `params`, `location`, `suggestions` and `suggested_fix`, its `status` and its `request_id`, which is what to quote when the fault is the runner's. A member no reader declares, at any level, such as the `error_type`, `error_domain` and `retryable` a runner's own refusals may still carry, is left out, and so is a member of Pipelex's (`request_id`, `run_error`) in a shape this version does not read, alone, so the problem around it is still reported. An answer that carries `diagnostics`, which a runner answers only to its operator, is projected onto the caller's view, its next step re-aimed at the caller, and so is the run's problem an answer nests as `run_error`, which is the run's stored record, whatever view the answer around it is in. A run that failed at a pipe is located there, `location.pipe` and `location.path`. A method refused before any pipe ran is `method.invalid`, its faults in `errors`.
-- **A refusal the hosted plane answers in its own shape**, which predates the standard's problem document, reads as the core code its status and the plane's own `code` name, with the plane's own `detail`, its `request_id` and the next step `pipelex run --hosted` gives: `auth.missing_credential` for a `401` or a `403` when no key was sent, telling how to get one with `pipelex login`; `auth.invalid_credential` for a `401`, and for the bare `403` the hosted API's edge answers without a reason, an unknown key among its causes, telling to run `pipelex login` or correct `PIPELEX_API_KEY`; `auth.forbidden` for a `403` the platform answers with one of its authorization codes, `forbidden` or `role_not_permitted`, for a key it accepted and an operation that key may not do, while a `403` with any other code, such as one for a key that expired, is `auth.invalid_credential`; `run.not_found` or `method.not_found` for a `404` whose code names the run or the method's version, and `request.not_found` for any other, telling to check the method's address and the origin; and `account.rate_limited` for a `429`, with `retry: yes` and the delay its `Retry-After` header or its body states as `retry_after`.
-- **A runner that cannot be reached** is `client.unreachable`, naming the base URL in `params.base_url`, with `retry: yes`: check the network connection and the origin, `--base-url`, else `PIPELEX_BASE_URL`, then run again. A connection lost on the start or the execute request, unless it proves that request never left, is `client.outcome_unknown`, since a run may exist with no id returned; one lost on a request sent before the run's, such as the check of which files of a large tree the runner holds, reads as a runner that cannot be reached.
-- **A file of the method's tree that could not be uploaded**, a tree past 256 KiB travelling by the hash of each file, stops the run before anything starts. Its problem is the one the client read for the upload, `client.unreachable` naming the storage's host when no answer came, else the one the storage's status reads as, and its `retry` verdict and its next step's kind are pipelex-sdk's own verdict: `retry: yes` with a `retry` step to run again, or, for a file the storage refused, `retry: no` with a `report` step. `message` names the file's SHA-256, never the upload link.
-- **Any other answer that is no problem document**, such as a gateway's error page, is read from its status by the client: `client.response_unreadable` naming the status. When the answer gives its reason, as a runner's own refusal in the former shape does (the `422` an older runner answers for a reserved input key), that reason is the problem's `detail`, and its next step is the one `pipelex run --hosted` gives: the advice the answer gave, of the kind that advice names (`check_account` for an advice to check the billing, for instance), else, for a `4xx`, to change what the reason names. **A runner's own refusal in the former shape that lists validation items**, the `422` a runner answers `/v1/start` and `/v1/execute` with for a method that does not validate, is `method.invalid` with those items as its `errors`, each coded as a local verdict codes it and located in the file it was sent as, its reason as the `detail` and its advice as the next step, as a failed run's stored report in the same shape reads. **A server fault on the run request**, any 5xx but a `501` and a `503` coded `pipeline_start_unavailable`, is `client.outcome_unknown` whatever its body, because the runner may have started the run before it failed to answer: check the run history before running again, since running again can repeat a paid run.
-- **A run that started and failed** is `run.failed`, naming the run and the status it ended with in `params` and `pipeline_run_id`, and `message` quotes the reason the hosted API stored for it. The run's own problem rides as `run_error`, in the caller's view, rendered in Markdown under `### The run's own problem` as a problem is, one heading level down. A stored report that is a problem document is read as a runner's answer is; one in the shape the hosted plane wrote before it stored problem documents names no code, so it reads as `method.invalid` with its validation items as `errors` when it lists some, and as `runtime.unexpected` otherwise, its message as the `detail`, its advice as the next step and its `retryable` as the `retry` verdict, which is what `pipelex run --hosted` tells of the same run.
-- **A run that failed on the way** carries the code of what happened: `run.not_finished` for a run that keeps going past the wait, `client.response_unreadable` for a completed run that delivered no main output, `client.follow_failed` for a run that started and whose result could not be read (it may still be running and is paid for, so look it up rather than run again), `method.invalid` for a method the hosted API found does not load before any run starts, when the inputs name a local file (its `errors` coded as a local verdict codes them, each naming its file in `location.file`), `request.unsupported` when the inputs name a local file and the method calls another one by its address (give the file as an `https://` URL), and `client.not_configured` for a base URL that is not an origin, refused before anything is sent. Every failure met once the hosted API acknowledged the run carries its `pipeline_run_id`. pipelex's own failures add their sentence as `message` and their advice as the Markdown's `💡` tip, and so do the client's own, whose sentence says what the code's parameters cannot, such as how long it waited for a run that did not finish. A failure the client meets on its own side takes the next step `pipelex run --hosted` tailors for it, in place of its code's: where to find a run that did not finish, that a blocking run cut off may still be going, that the server takes no uploads, which file path to check.
+- **A run the runner refuses** reports the runner's problem document by the members the standard and Pipelex declare: its `code`, `domain`, `retry`, `next_step`, `params`, `location`, its `errors` items, each with its `code`, `detail`, `params`, `location`, `suggestions` and `suggested_fix`, its `status` and its `request_id`, which is what to quote when the fault is the runner's. A member no reader declares, at any level, is left out, and so is a member of Pipelex's (`request_id`, `run_error`) in a shape this version does not read, alone, so the problem around it is still reported. An answer that carries `diagnostics`, which a runner answers only to its operator, is projected onto the caller's view, its next step re-aimed at the caller, and so is the run's problem an answer nests as `run_error`, which is the run's stored record, whatever view the answer around it is in. A run that failed at a pipe is located there, `location.pipe` and `location.path`. A method refused before any pipe ran is `method.invalid`, its faults in `errors`.
+- **An answer that is no problem document**, the bare answer of the hosted API's edge, a gateway or a proxy in front of the runner, is read from its status by pipelex-sdk, and this CLI reads the refusals of a credential and of a route itself, with the next step `pipelex run --hosted` gives. A bare `401` or `403` is `auth.missing_credential` when the request carried no key, telling how to get one with `pipelex login`, and `auth.invalid_credential` when it carried one, telling to run `pipelex login` or correct `PIPELEX_API_KEY`, a `403` adding that a valid key may also be refused a route it may not call. A bare `404` is `request.not_found`, telling to check the origin, `--base-url`, else `PIPELEX_BASE_URL`. Every other bare answer keeps pipelex-sdk's reading: `runtime.unavailable` with `retry: yes` for a `408`, a `429`, a `502`, a `503` or a `504`, with the delay its `Retry-After` header states as `retry_after`, `runtime.unexpected` for a `500`, and `client.response_unreadable` naming the status for any other. **A server fault on the run request**, a bare `408` or any bare `5xx` but a `501` answered to the start or the execute request, is `client.outcome_unknown`, because the runner may have started the run before it failed to answer: check the run history before running again, since running again can repeat a paid run. A problem document the runner answered is reported as it came, whatever its status, so a runner's own fault on the run request keeps its own code.
+- **A runner that cannot be reached** is `client.unreachable`, naming the base URL in `params.base_url`, or `client.timeout`, naming the time limit, for a request whose time limit ran out, both with `retry: yes`: check the network connection and the origin, `--base-url`, else `PIPELEX_BASE_URL`, then run again. A connection lost on the start or the execute request, unless it proves that request never left, is `client.outcome_unknown`, since a run may exist with no id returned; one lost on a request sent before the run's, such as the check of which files of a large tree the runner holds, reads as a runner that cannot be reached.
+- **A file of the method's tree that could not be uploaded**, a tree past 256 KiB travelling by the hash of each file, stops the run before anything starts. Its problem is pipelex-sdk's reading of why the upload failed: `runtime.unavailable` with `retry: yes` and a `retry` step to run again when the storage could not be reached, timed out, throttled the upload or failed, and `client.response_unreadable` naming the status with `retry: no` and a `report` step when the storage refused it. `message` names the file's SHA-256, never the upload link.
+- **A run that started and failed** is `run.failed`, naming the run and the status it ended with in `params` and `pipeline_run_id`, and `message` is the client's sentence about it. The run's own problem rides as `run_error`, read as a runner's answer is, by its declared members alone, and in the caller's view, since it is the run's stored record: its code, its next step and its items say why the run did not succeed. Markdown renders it under `### The run's own problem` as a problem is, one heading level down, which is what `pipelex run --hosted` tells of the same run.
+- **A run that failed on the way** carries the code of what happened: `client.follow_failed` for a run that keeps going past the wait, or that started and whose result could not be read (it may still be running and is paid for, so look it up rather than run again), `client.response_unreadable` for a completed run that delivered no main output, `method.invalid` for a method the hosted API found does not load before any run starts, when the inputs name a local file (its `errors` the items the hosted API's verdict lists, as they came, by their declared members, so an item under a code newer than this CLI keeps the runner's sentence and parameters), `request.unsupported` with `params.reason` `local_file_with_address_dependency` when the inputs name a local file and the method calls another one by its address (give the file as an `https://` URL), and `client.not_configured` for a base URL that is not an origin, refused before anything is sent. Every failure met once the hosted API acknowledged the run carries its `pipeline_run_id`. pipelex's own failures add their sentence as `message` and their advice as the Markdown's `💡` tip, and so do the client's own, whose sentence says what the code's parameters cannot, such as how long it waited for a run that did not finish. A failure the client meets on its own side takes the next step `pipelex run --hosted` tailors for it, in place of its code's: where to find a run that did not finish, that a blocking run cut off may still be going, that the server takes no uploads, which file path to check.
- **An interrupted run** (Ctrl-C) exits with `130`: `client.follow_failed` naming the run the hosted API had acknowledged, which keeps going and is paid for, or `client.outcome_unknown` with no `pipeline_run_id` when it was interrupted before the acknowledgement, so check the run history before running again.
- **Any other failure of the run** is this process's own and is reported as a local one is, in the operator's view: a Pipelex error under its own code, any other exception, such as a results body that drifted, as `runtime.unexpected`.
diff --git a/docs/tools/cli/run.md b/docs/tools/cli/run.md
index 43cff6946..d439eedc1 100644
--- a/docs/tools/cli/run.md
+++ b/docs/tools/cli/run.md
@@ -214,7 +214,7 @@ Only the `.mthds` files are sent. A PipeFunc's Python function, Python structure
**Local files in the inputs** are uploaded before the run. A path at a document or image input (compact, as `"invoice.pdf"`, or as the `url` of a document or image object, in a list or nested in a structure) is uploaded, and the run receives its storage URI instead. A relative path written in an inputs file resolves against that file's directory, as on a local run, and a `file://` URI is read as the path it names. A text that reads like a file name at any other input is left as text, and that includes a `.csv` path given to a structured-list input: it is not uploaded, the hosted runner receives a path it cannot read, so give the rows as a JSON list instead, or run with `--local`. `http(s)://` URLs, whatever the case of the scheme, are passed through for the hosted API to fetch, and an explicit `null`, such as an optional image left out, reaches the run as `null`.
-The method's signature, which says where a file sits, is read from the hosted API only when some value of the inputs, at any depth, names an existing file on this machine (from the inputs file's directory or the working directory). Inputs naming none go straight to the run. When the signature is read, a method that does not load is refused there, before any run starts, with validation errors that name each faulty file by its path in the tree sent. A method that calls another method by its address (`github.com/…`) cannot have its signature read yet, since the signature is read with only the packages the request sends and a hosted run sends none, so a local file cannot be uploaded for it: the run is refused before it starts, naming the package, and the file has to be given as an `https://` URL instead. The same method runs with inputs that name no local file, the hosted API fetching the package itself.
+The method's signature, which says where a file sits, is read from the hosted API only when some value of the inputs, at any depth, names an existing file on this machine (from the inputs file's directory or the working directory). Inputs naming none go straight to the run. When the signature is read, a method that does not load is refused there, before any run starts, with the faults the hosted API lists, each located by its file's path in the tree sent. A method that calls another method by its address (`github.com/…`) cannot have its signature read yet, since the signature is read with only the packages the request sends and a hosted run sends none, so a local file cannot be uploaded for it: the run is refused before it starts, naming the package, and the file has to be given as an `https://` URL instead. The same method runs with inputs that name no local file, the hosted API fetching the package itself.
**What it saves** goes where a local run saves its outputs, in `<output-dir>/<label>_output_NN/`: `main_stuff.json` (and `main_stuff.md` when the main output is text), `working_memory.json`, and `graphspec.json` when the hosted API returned the run's graph, which [`pipelex graph render`](../../features/execution-graph.md) turns into a viewer. The label is the pipe that ran, or, for a method run by its address or its catalog id without `--pipe`, the last segment of the address or the id itself, as in `mt_abc123_output_01/`. The run id is printed as soon as the hosted API acknowledges the run, as `Run <id> started on the hosted API`, and again with the recap.
@@ -222,7 +222,7 @@ The method's signature, which says where a file sits, is read from the hosted AP
**What it refuses**: `--dry-run`, `--mock-inputs`, `--orchestrator`, `--save-csv`, `--costs` / `--no-costs` and `--graph-full-data` / `--graph-no-data` steer this machine's runtime, which a hosted run never boots, so each is refused with a message pointing at `--local`. `--base-url` on a run that executes locally is refused too.
-**When it fails**, the message gives the hosted API's reason and a next step: the one the server advised when it gave one, else one that follows the status (a refused key points at `PIPELEX_API_KEY` and `pipelex login`, an unknown method or route at the method's address and the base URL, a rate limit says to wait). A bundle the hosted API refuses lists its validation errors, and so does a run that started and failed on them. Once the hosted API has acknowledged the run, the failure also prints the run id: a run that failed, one that outlived the wait, one that completed without a main output, and one whose result could not be read, because the network or the hosted API failed while the run was being followed. That last one may still be running and is paid for, so look it up by its id on app.pipelex.com rather than running the command again. A connection lost on the request that runs the method is not reported as a network failure either, unless it proves that request never left this machine: the hosted API may have created the run before the connection failed, and its id never arrived, so check the run history before running again. Only a failure that proves no run was asked for points at the network and the base URL: a connection that could not be made, or one lost on a request sent before the run's, such as the check of which files of a large tree the hosted API holds. A server that keeps no runs to poll, such as a self-hosted runner, is run on the blocking route, and when the connection is cut before its result comes back, the run may still be going there: running the command again runs the method again, so raise the timeout of the proxy in front of that server, or point the base URL at a server that keeps runs. The exit code is `1`.
+**When it fails**, the command prints the failure's problem, the one `pipelex-agent run --runner hosted` reports: its title and its detail, the next step, its code with the domain that acts on it and whether running again can help, the request id to quote, the run, and the faults it lists, one per line with their location. The problem is the hosted API's own when it answered one, with its own next step. An answer that is no problem document, such as a gateway's, is read from its status: a refused or missing key points at `PIPELEX_API_KEY` and `pipelex login`, a route the server does not serve at the base URL, and a throttle or an unavailable server says to run again later. A run that started and failed prints its own problem below, as "The run's own problem", with the faults of a method refused as it loaded, and pipelex's own advice prints as the tip. Once the hosted API has acknowledged the run, the failure also prints the run id: a run that failed, one that outlived the wait, one that completed without a main output, and one whose result could not be read, because the network or the hosted API failed while the run was being followed. That last one may still be running and is paid for, so look it up by its id on app.pipelex.com rather than running the command again. A connection lost on the request that runs the method is not reported as a network failure either, unless it proves that request never left this machine: the hosted API may have created the run before the connection failed, and its id never arrived, so check the run history before running again. Only a failure that proves no run was asked for points at the network and the base URL: a connection that could not be made, or one lost on a request sent before the run's, such as the check of which files of a large tree the hosted API holds. A server that keeps no runs to poll, such as a self-hosted runner, is run on the blocking route, and when the connection is cut before its result comes back, the run may still be going there: running the command again runs the method again, so raise the timeout of the proxy in front of that server, or point the base URL at a server that keeps runs. The exit code is `1`.
**A self-hosted Pipelex API server**, such as the [Pipelex API server](../../api-server/index.md) run from its Docker image, is reached the same way, by pointing `--base-url` or `PIPELEX_BASE_URL` at its origin (`http://localhost:8081`, without `/v1`). `PIPELEX_API_KEY` is sent to it as the bearer token, so set it to the key that server expects when it requires one. Such a server runs your methods, but it does less than the hosted Pipelex API:
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index 7618319f0..41179e946 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -507,7 +507,7 @@ A refusal is reported once per process, however many of these boundaries it cros
### CLI
-The agent CLI (`pipelex-agent`) reports a failure on **stderr** as its problem in the operator's view, markdown by default and JSON with `--error-format json`: the problem document's members, `code`, `domain`, `retry`, `next_step`, `params`, `location`, `errors`, `request_id`, `pipeline_run_id` and `diagnostics` (a pending configuration migration in `diagnostics.migration`), and beside them the command's own `message` and members. The error format is the command's `--error-format`, else the program's `--error-format` given before the command, else the command's `--format` (so `--format json` still flips both as it did before the split), else JSON. The Markdown reads the same problem as a `## <title>` heading, the detail, the next step, the advice the error's chain gives as a `💡` tip, the code with its domain and verdict, the location, the faults one per line with their code, sentence, location, suggestions and suggested fix, and the diagnostics. A refusal the command makes itself is coded too, `client.argument_invalid`, `client.file_unreadable` or `client.tool_missing`, and an exception that is no Pipelex error is `runtime.unexpected`. A run on a runner (`--runner hosted`) that fails reports the problem the runner answered or the client decided (`exc.problem`), as it came, by its declared members alone, in the caller's view: the runner's own problem document with its items, `client.unreachable` for a runner that cannot be reached, `client.outcome_unknown` for a server fault on the run request, `run.failed` for a run that started and failed; an answer in a shape that predates the standard's reads as the core code its status and the hosted plane's own code name (`auth.invalid_credential`, `auth.missing_credential`, `auth.forbidden`, `request.not_found`, `run.not_found`, `method.not_found`, `account.rate_limited`), lists its validation items under `method.invalid`, or keeps the client's `client.response_unreadable` with the reason it gave, with the next step the human CLI gives, as does a failure the client meets on its own side; a failed run's own problem rides as `run_error` in the caller's view, a stored report in the former shape included; the refusals this CLI makes before anything is sent stay in the operator's view, except a refusal of the method it would send, a bundle that does not parse or validate or a bundle file or folder with no pipe to start at, which is the refusal the runner would answer for it and reads in the caller's view.
+The agent CLI (`pipelex-agent`) reports a failure on **stderr** as its problem in the operator's view, markdown by default and JSON with `--error-format json`: the problem document's members, `code`, `domain`, `retry`, `next_step`, `params`, `location`, `errors`, `request_id`, `pipeline_run_id` and `diagnostics` (a pending configuration migration in `diagnostics.migration`), and beside them the command's own `message` and members. The error format is the command's `--error-format`, else the program's `--error-format` given before the command, else the command's `--format` (so `--format json` still flips both as it did before the split), else JSON. The Markdown reads the same problem as a `## <title>` heading, the detail, the next step, the advice the error's chain gives as a `💡` tip, the code with its domain and verdict, the location, the faults one per line with their code, sentence, location, suggestions and suggested fix, and the diagnostics. A refusal the command makes itself is coded too, `client.argument_invalid`, `client.file_unreadable` or `client.tool_missing`, and an exception that is no Pipelex error is `runtime.unexpected`. A run on a runner (`--runner hosted`) that fails reports the problem the runner answered or the client decided (`exc.problem`), as it came, by its declared members alone, in the caller's view: the runner's own problem document with its items, `client.unreachable` for a runner that cannot be reached, `client.outcome_unknown` for a server fault on the run request, `run.failed` for a run that started and failed; an answer that is no problem document, the bare answer of an edge or a gateway, reads as pipelex-sdk reads its status, except a refused credential, which is `auth.missing_credential` when no key was sent and `auth.invalid_credential` when one was, and a route the server does not serve, `request.not_found`, both with the next step the human CLI gives, as does a failure the client meets on its own side; a failed run's own problem rides as `run_error` in the caller's view; the human CLI (`pipelex run --hosted`) prints the same problem (`pipelex/hosted/error_rendering.py`, `describe_hosted_error`); the refusals this CLI makes before anything is sent stay in the operator's view, except a refusal of the method it would send, a bundle that does not parse or validate or a bundle file or folder with no pipe to start at, which is the refusal the runner would answer for it and reads in the caller's view.
| Command | Error output |
|---------|--------------|
diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.md
index d0242fa5a..ca812bc8c 100644
--- a/pipelex/cli/agent_cli/CLAUDE.md
+++ b/pipelex/cli/agent_cli/CLAUDE.md
@@ -107,8 +107,8 @@ commands/
- **Validate refusals of the method are verdicts**: the `validate` commands run their library load inside `translate_to_validate_bundle_error` (`pipelex/pipeline/validate_bundle_translation.py`), so every refusal raised while loading a bundle whose code is in the `method` domain, the unknown model (`PipeOperatorModelChoiceError`, an `unknown_model` item) included, reaches the command as a `ValidateBundleError` and leaves with the invalid verdict's problem and exit 1. A refusal of another actor, the request's or the input's included, keeps its own class and code, and so does a dry run none of whose failures is the method's. No `validate` command keeps an arm of its own for a model-choice error; exit 2 stays for a failure of the tool or its environment (config, runtime, security).
- **Run refusals are verdicts too**: a run loads its bundle inside the same translation (`acquire_library`), so an invalid bundle leaves `run pipe` / `run bundle` / `run method` as a `ValidateBundleError` with exit 1, through the generic `agent_error` arm (`run bundle`'s own reading of its bundle through `agent_error_method_refusal()`, in the caller's view on a runner), and its problem (`method.invalid`) carries the verdict's items as `errors`, and the Markdown lists the same errors one per line, so both formats list the one problem's errors and a foreign exception raised while handling an earlier verdict lists none of its items. `run_pipeline_core` sets `library_dirs_are_callers=True`, so a refusal in a `-L` directory (or the bundle's own directory) is the same verdict; `run bundle`'s own parse of a bundle without `--pipe` goes through the translation too, and so does its reading of the method tree: a folder resolves through `pipelex/cli/bundle_target_resolution.py` (`resolve_method_folder_run`, the protocol's entry rule in `pipelex/pipeline/method_entry.py`) and a lone file through `list_bundle_file_tree`, listed before the file is read, through the `MethodTreeListing` the command hands to `run_pipeline_core` so the run loads the tree it listed rather than listing it again (`pipelex/libraries/method_tree_listing.py`; `validate bundle` and `fix bundle` hand theirs down through `JudgedBundleTarget.tree_listing`), so a tree past its limits, a symbolic link or a special file such as a FIFO is a `ValidateBundleError` too, refused unread, and so is a tree a file of which changed after that listing (`MethodTreeChangedError`, reason `tree_changed`, whose item names the file), and a bundle file the listing cannot read is `client.file_unreadable`, while a folder with no single `main_pipe` is the run's own refusal, a `MethodEntryError` coded `request.pipe_unspecified` or `request.pipe_ambiguous`, no verdict on a method that may be valid. So no `run` command keeps an arm of its own for a model-choice error either: an unknown model reaches it as the verdict's `unknown_model` item.
- **Two readings of a folder, one resolution path**: `run bundle`, `validate bundle`, `fix bundle` and `inputs bundle` read a folder through `pipelex/cli/bundle_target_resolution.py` (`run` through `resolve_method_folder_run`, the others through `resolve_bundle_target_core`, validate and fix by way of `pipelex/cli/judged_target.py`, whose `JudgedBundleTarget.judged_path` is the path the verdict names and whose `fix_judged_target` is the one fix dispatch both CLIs call, and of `commands/bundle_path_resolver.py`), as its method tree, but with the `FolderReading` their job asks for. `validate` and `fix` take `WHOLE_TREE`, the MTHDS protocol's validation (`mthds/docs/spec/protocol.md`): every bundle of the tree is judged (`validate_bundle(method_dir=..., library_dirs_are_callers=True)`, `fix_method_folder`), with no pipe to start at, so a folder whose bundles declare several `main_pipe`s, or none, is validated like any other; mthds-js's local runner calls `pipelex validate bundle <dir>` to validate a whole method at install and relies on this. `--pipe` there only narrows the dry run, and `--graph` / `--view` draw from the pipe named, else from the entry (`locate_folder_pipe`), or, when the folder decides none, put `graph_unavailable` in the envelope and leave the verdict alone. `run` and `inputs` take `ENTRY_PIPE`, acting on one pipe: the one `--pipe` names, else the protocol's entry (`select_method_entry` in `pipelex/pipeline/method_entry.py`); no single `main_pipe` is the `MethodEntryError` with exit 1 on both, coded `request.pipe_unspecified` or `request.pipe_ambiguous`, the message the same, and no verdict on a method that may be valid. A folder holding no bundle is `EmptyMethodTreeError` with exit 2 on `validate` and `fix`, and a `MethodEntryError` saying it has no pipe to start at on the others, each problem coded `method.invalid`. A folder whose tree is refused at resolution (past its limits, a symbolic link) is the invalid verdict: `ValidateBundleError` on `validate`, and on `fix` the still-invalid `method.invalid` problem of a fix that could not start (`unfixable_method_result`, through `agent_error_fix_bundle`), exit 1 both. A fix of a folder writes anywhere in its method tree, from the root (`method_tree_root`) down, and the human `--diff` preview mirrors that root, so a fix landing in a bundle above the folder named is proposed and written alike. Only the tree's own pipes are judged: `validate_bundle(method_dir=...)` keeps the blueprints its tree lists (`_is_member_blueprint`), so a nested package, a dependency or a `-L` directory loads without being judged; `dirs_beside_method` is the one place the `-L` directories naming the folder itself are dropped, compared resolved. Reading the tree's limits loads the configuration before the boot, so each resolution site catches `PipelexConfigError` and reports it through `report_agent_init_failure` (`agent_cli_factory.py`), the problem a failed boot gives: with exit 2 on `validate` and `fix`, whose resolver passes `exit_code=2` since the refusal gives no verdict, as the human `pipelex validate bundle` and `fix bundle` exit, and with the boot's exit 1 on `run` and `inputs`. `validate` and `fix` do not list a lone `.mthds` file before the boot, so for a file the same configuration surfaces only at the boot, which exits 1.
-- **Hosted runs**: every `run` subcommand takes `--runner local|hosted`, `--hosted/--local` and `--base-url`; `resolve_agent_run_execution()` (`run/_run_hosted.py`) settles them through `pipelex.hosted.execution.resolve_run_execution` (the flag, then `[run] execution`, then local), refusing a `--runner` that contradicts the flag pair and a `--base-url` on a local run as `client.argument_invalid` problems; a configuration that cannot be read there reports its own problem, as a failed boot does (`agent_cli_factory.py`). Every refusal made before anything is sent is a problem in the operator's view, except a refusal of the method the run would send; what the run itself fails with is the problem the runner or the client produced, in the caller's view (below). `run bundle` reads its bundle before it runs it, wherever it runs, so it settles where the run executes first (`resolve_agent_run_execution()`, then `refuse_local_only_flags()`), and reports a bundle that does not parse or validate (`ValidateBundleError`) or a bundle file or folder with no pipe to start at (`MethodEntryError`, `request.pipe_unspecified`, which a lone file with no `main_pipe` raises too, naming its pipes as `candidates`) through `agent_error_method_refusal()` (`run/_run_hosted.py`): on this machine's runtime through `agent_error`, in the operator's view with the command's sentence; on a runner as the refusal the runner would answer for the same method, `to_problem(view=ProblemView.CALLER)` printed through `agent_error_problem()`, with no `diagnostics` and no `message`, since both carry the raise site's classes and text, the items, their locations, the caller's step and the Markdown tip kept. A hosted run boots nothing: it builds a `HostedRunRequest` from what `pipelex/cli/commands/run/_hosted_sources.py` resolves (the bundle and its library's `.mthds` files, a pipe's library, or a method's files, as `contents`, one tree's bytes by tree path that `method_tree_contents` keys from the method's own tree; an address or a catalog id as `method_ref` / `method_id`, never fetched) and `run_hosted_for_agent()` runs it through `pipelex.hosted.hosted_run.run_hosted`, which reads the signature and uploads local input files only when some input string names an existing local file, so a method with an address-based dependency runs with any other inputs. To read the signature it hands `contents` to `client.pipe_io` (`PipeIORequest(contents=…)`, `pipelex/hosted/hosted_inputs.py`), and it hands the same `contents` again to `client.start` or `client.execute` (`pipelex/hosted/hosted_run.py`). pipelex-sdk prepares the tree as the protocol's `files` map in each call, inline up to 256 KiB and by hash past that, so a blob uploaded for the signature read is found held for the run and nothing is uploaded twice; a public preparation that would let pipelex prepare the tree once is L-261022-18cca3. `run_hosted` then drives the lifecycle `start_and_wait` drives step by step (the `/v1/version` handshake, `start`, `wait_for_result`, and the blocking `execute` on a server with no run store), so a failure while following an acknowledged run is a `HostedRunPollingError` naming the run, and a transport failure pipelex-sdk reads as one that may have started the run (`run_may_have_started`, set only on the start or the execute request itself, so never on the version handshake or the blob requests of a tree sent by hash) is a `HostedRunOutcomeUnknownError` rather than an `ApiUnreachableError`. `run_hosted`'s `on_started` callback records the acknowledged run's id, so Ctrl-C (`KeyboardInterrupt`, or the `CancelledError` of a cancelled task) leaves as the problem of a `HostedRunInterruptedError`, `client.follow_failed` carrying `pipeline_run_id` once the run was acknowledged and `client.outcome_unknown` before, with exit code 130. `run bundle` on a file with no `-L` sends `PIPELEXPATH`'s files (`hosted_library_dirs`), and an installed method named like a catalog id is that method. An exception no hosted arm names is this process's own failure and leaves through the command-boundary catch-all as a local run's does, in the operator's view: a Pipelex error under its own code, any other exception as `runtime.unexpected`. Its success envelope is `build_run_output()`'s, with the main output's content as `json`, an empty `markdown`, the working memory dump and `pipeline_run_id`; nothing is written to disk. `--dry-run` / `--mock-inputs` are refused on it, while `--graph` and `--costs` are accepted and ignored. There is no global `--runner` any more, and no `ctx.obj`.
-- **A run on a runner that fails** reports the problem the runner or the client produced, in the caller's view, as it came: `agent_error_hosted()` (`run/_run_hosted.py`) builds it with `hosted_failure_problem()` and prints it through `agent_error_problem()` (`agent_output.py`), which neither rebuilds nor reclassifies it, in Markdown by default and JSON with `--error-format json`. A refusal the runner answered (pipelex-sdk's `ApiResponseError`), a runner that cannot be reached (`ApiUnreachableError`, `client.unreachable` naming `params.base_url`) and every other request error of pipelex-sdk or the MTHDS client carries the standard client's problem as `exc.problem`: the runner's own problem document when the answer is one, its `errors` items, its next step and its `request_id` included (`received_problem()`, which keeps only the members the standard and Pipelex declare, at every level, leaves out alone one of Pipelex's members that does not read, fills `request_id` from the answer when the document names none, and projects an answer carrying diagnostics onto the caller's view, deciding it from the document as it came, and a nested `run_error` always, since it is the run's stored record), else the code the client reads from the answer, such as `client.response_unreadable` naming the status, or `client.outcome_unknown` for an answer that leaves a run possibly started, which pipelex-sdk reads for every 5xx on the run request but a 501 and a 503 coded `pipeline_start_unavailable`, whatever the body. An answer in a shape that predates the standard's, which the client reads by its status alone, goes through `hosted_refusal_problem()` (`pipelex/hosted/error_rendering.py`): a refusal of the hosted plane reads as the core code its status and the plane's own `code` name, built by `make_problem` in the caller's view, `auth.missing_credential` for a `401` or `403` with no key sent (`HOSTED_MISSING_KEY_NEXT_STEP`), `auth.invalid_credential` for a `401` and for the edge's bare `403`, `auth.forbidden` for a `403` the platform codes with one of its authorization codes, `forbidden` or `role_not_permitted` (`HOSTED_FORBIDDEN_NEXT_STEP`), and `auth.invalid_credential` for a `403` with any other code, `run.not_found` or `method.not_found` for a `404` coded `run_not_found` or `method_version_not_found` and `request.not_found` for any other, `account.rate_limited` with its `retry_after` for a `429`, with the plane's own `detail` and the next step the human CLI gives (`HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS`); a runner's own refusal in the former shape that lists validation items, the `422` of a method that does not validate on `/v1/start` or `/v1/execute`, is read first, by `_former_refusal_problem()` in `run/_run_hosted.py`, as `method.invalid` with those items, its reason, its advice and its status, through the builder a stored report in the same shape goes through (`_former_problem()`); any other such answer that gives its reason, a runner's own `422` for a reserved input key included, keeps the client's `client.response_unreadable`, read by the standard's members alone so a member beside them that does not read never stops it (`_client_reading()`), with that reason as its `detail` and the human CLI's step (`hosted_refusal_next_step()`), of the kind its advice names through `FORMER_ADVICE_KINDS` (`pipelex/hosted/error_rendering.py`), else `change_input` for a `4xx`; an answer that may have started a run keeps its `client.outcome_unknown`. A run that started and failed (`RunFailedError`) is `run.failed` naming the run and its status, with the client's sentence as `message`, which quotes the stored report's reason, and nests the run's own problem as `run_error`: a stored report that is a problem document is read as a runner's answer is, so a member it holds beside the problem is left out, and one in the former `RunErrorReport` shape is `method.invalid` with its validation items (`hosted_method_problem_items()`) or `runtime.unexpected`, its message, its advice (kind through `FORMER_ADVICE_KINDS`) and its `retryable` carried (`_former_run_problem()`). Markdown renders the nested problem with the head `render_problem_markdown` uses, one heading level down (`_problem_head_lines`). Every error of pipelex-sdk's own but an answer's refusal and an unreachable runner adds its sentence as `message`, since it says what its code's parameters cannot (how long the client waited, that a completed run delivered no main output), and every one but an answer's refusal and a failed run takes the next step the human CLI tailors for it (`tailored_next_step()`, the step `describe_hosted_error()` gives when it is not `HOSTED_RUN_REQUEST_NEXT_STEP`), keeping its code's kind, except a file of the method's tree that could not be uploaded (`MethodFileTransferError`), whose problem the SDK reads off storage's status alone, so it carries the SDK's verdict as its `retry` and its step's kind, `retry` for every code but `refused`, which is `report` (`_transfer_verdict_problem()`). pipelex's own `HostedRunError`s report their problem in the caller's view with their sentence as `message` and their advice as the Markdown tip, `pipeline_run_id` included for `HostedRunPollingError` and `HostedRunInterruptedError`; a `HostedMethodInvalidError` lists pipe-io's items as `errors`, each coded as a local verdict codes it (`hosted_method_problem_items()`, through `validation_item_code` and `problem_item_of`, `method.schema_violation` with the item's sentence as its finding for an item of a type this version does not read, each item read by the fields this version declares, so a field it does not keeps nothing from being typed, and a declared field whose value it cannot read, such as a newer runner's fix, is left out alone, so the item keeps its type, its locators and its dependency facts), its file in `location.file`. Nothing of the envelope this CLI wrote before it reported problems is left (`error`, `error_type`, `error_source`, `hint`, `error_domain`, `retryable`, `error_code`, `http_status`, …), which `tests/unit/pipelex/cli/test_agent_output_drift.py` guards in the source and in the emitted document.
+- **Hosted runs**: every `run` subcommand takes `--runner local|hosted`, `--hosted/--local` and `--base-url`; `resolve_agent_run_execution()` (`run/_run_hosted.py`) settles them through `pipelex.hosted.execution.resolve_run_execution` (the flag, then `[run] execution`, then local), refusing a `--runner` that contradicts the flag pair and a `--base-url` on a local run as `client.argument_invalid` problems; a configuration that cannot be read there reports its own problem, as a failed boot does (`agent_cli_factory.py`). Every refusal made before anything is sent is a problem in the operator's view, except a refusal of the method the run would send; what the run itself fails with is the problem the runner or the client produced, in the caller's view (below). `run bundle` reads its bundle before it runs it, wherever it runs, so it settles where the run executes first (`resolve_agent_run_execution()`, then `refuse_local_only_flags()`), and reports a bundle that does not parse or validate (`ValidateBundleError`) or a bundle file or folder with no pipe to start at (`MethodEntryError`, `request.pipe_unspecified`, which a lone file with no `main_pipe` raises too, naming its pipes as `candidates`) through `agent_error_method_refusal()` (`run/_run_hosted.py`): on this machine's runtime through `agent_error`, in the operator's view with the command's sentence; on a runner as the refusal the runner would answer for the same method, `to_problem(view=ProblemView.CALLER)` printed through `agent_error_problem()`, with no `diagnostics` and no `message`, since both carry the raise site's classes and text, the items, their locations, the caller's step and the Markdown tip kept. A hosted run boots nothing: it builds a `HostedRunRequest` from what `pipelex/cli/commands/run/_hosted_sources.py` resolves (the bundle and its library's `.mthds` files, a pipe's library, or a method's files, as `contents`, one tree's bytes by tree path that `method_tree_contents` keys from the method's own tree; an address or a catalog id as `method_ref` / `method_id`, never fetched) and `run_hosted_for_agent()` runs it through `pipelex.hosted.hosted_run.run_hosted`, which reads the signature and uploads local input files only when some input string names an existing local file, so a method with an address-based dependency runs with any other inputs. To read the signature it hands `contents` to `client.pipe_io` (`PipeIORequest(contents=…)`, `pipelex/hosted/hosted_inputs.py`), and it hands the same `contents` again to `client.start` or `client.execute` (`pipelex/hosted/hosted_run.py`). pipelex-sdk prepares the tree as the protocol's `files` map in each call, inline up to 256 KiB and by hash past that, so a blob uploaded for the signature read is found held for the run and nothing is uploaded twice; a public preparation that would let pipelex prepare the tree once is L-261022-18cca3. `run_hosted` then drives the lifecycle `start_and_wait` drives step by step (the `/v1/version` handshake, `start`, `wait_for_result`, and the blocking `execute` on a server with no run store), so a failure while following an acknowledged run is a `HostedRunPollingError` naming the run, and a transport failure pipelex-sdk reads as one that may have started the run (its problem's retry verdict `outcome_unknown`, `client.outcome_unknown`, read only on the start or the execute request itself, so never on the version handshake or the blob requests of a tree sent by hash) is a `HostedRunOutcomeUnknownError` rather than an `ApiUnreachableError`. `run_hosted`'s `on_started` callback records the acknowledged run's id, so Ctrl-C (`KeyboardInterrupt`, or the `CancelledError` of a cancelled task) leaves as the problem of a `HostedRunInterruptedError`, `client.follow_failed` carrying `pipeline_run_id` once the run was acknowledged and `client.outcome_unknown` before, with exit code 130. `run bundle` on a file with no `-L` sends `PIPELEXPATH`'s files (`hosted_library_dirs`), and an installed method named like a catalog id is that method. An exception no hosted arm names is this process's own failure and leaves through the command-boundary catch-all as a local run's does, in the operator's view: a Pipelex error under its own code, any other exception as `runtime.unexpected`. Its success envelope is `build_run_output()`'s, with the main output's content as `json`, an empty `markdown`, the working memory dump and `pipeline_run_id`; nothing is written to disk. `--dry-run` / `--mock-inputs` are refused on it, while `--graph` and `--costs` are accepted and ignored. There is no global `--runner` any more, and no `ctx.obj`.
+- **A run on a runner that fails** reports the problem the runner or the client produced, in the caller's view, as it came, the same problem `pipelex run --hosted` prints: `agent_error_hosted()` (`run/_run_hosted.py`) reads it with `describe_hosted_error()` (`pipelex/hosted/error_rendering.py`, which both CLIs share and which imports no Rich) and prints it through `agent_error_problem()` (`agent_output.py`), which neither rebuilds nor reclassifies it, in Markdown by default and JSON with `--error-format json`. `hosted_failure_problem()` builds it, and every error of pipelex-sdk carries the standard's problem as `exc.problem`. An answer the runner gave (`ApiResponseError`) whose body is a problem document is reported as it came (`received_problem()`, which keeps only the members the standard and Pipelex declare, at every level, leaves out alone one of Pipelex's members that does not read, fills `request_id` from the answer when the document names none, and projects an answer carrying diagnostics onto the caller's view, deciding it from the document as it came, and a nested `run_error` always, since it is the run's stored record). An answer that is no problem document, the bare answer of the hosted edge, a gateway or a proxy, keeps pipelex-sdk's reading by its status, `client.outcome_unknown` included for a bare answer that leaves a run possibly started, except the readings this client makes itself (`_answered_problem()`, `_bare_answer_reading()`): a bare `401` or `403` is `auth.missing_credential` when the request carried no key (`HOSTED_MISSING_KEY_NEXT_STEP`) and `auth.invalid_credential` when it carried one, and a bare `404` is `request.not_found`, each with the next step that names this client's settings (`HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS`); this reading stays written by hand until the registry records it. A run that started and failed (`RunFailedError`) is pipelex-sdk's `run.failed` naming the run and its status, nesting the run's own problem as `run_error`, read as a runner's answer is; Markdown renders the nested problem with the head `render_problem_markdown` uses, one heading level down (`_problem_head_lines`), and the human CLI prints its rows below the failure's. Every other error of pipelex-sdk's carries the problem the client decided, such as `client.unreachable` naming `params.base_url`, with the next step this client tailors for it (`tailored_next_step()`) in place of its code's, keeping its code's kind: a runner that cannot be reached but may have received the run request keeps its code's step, and a file of the method's tree that could not be uploaded (`MethodFileTransferError`) takes the step its `reason` names, its retry verdict pipelex-sdk's. Every error of pipelex-sdk's own but an answer and an unreachable runner adds its sentence as `message`, since it says what its code's parameters cannot (how long the client waited, that a completed run delivered no main output). pipelex's own `HostedRunError`s report their problem in the caller's view with their sentence as `message` and their advice as the Markdown tip, `pipeline_run_id` included for `HostedRunPollingError` and `HostedRunInterruptedError`; a `HostedMethodInvalidError` lists the items of pipe-io's verdict (`HostedMethodInvalidError.errors`) as its `errors` as they came, by their declared members alone and never projected onto a view again (`_method_invalid_problem()`), so an item under a code newer than this client keeps the runner's sentence and parameters. Nothing of the envelope this CLI wrote before it reported problems is left (`error`, `error_type`, `error_source`, `hint`, `error_domain`, `retryable`, `error_code`, `http_status`, …), which `tests/unit/pipelex/cli/test_agent_output_drift.py` guards in the source and in the emitted document, the items of a pipe-io verdict included.
- **Method-reference failures**: the `run`/`validate`/`inputs` method commands call `resolve_method_target(..., raise_ref_errors=True)` and report the typed `MethodRefError` subclasses through `agent_error(...)` themselves, each with its own code (validate uses `exit_code=2`, its no-verdict convention) — the human CLI's red-text rendering stays in `resolve_method_target`'s default arm.
- **Usage statistics**: the root callback runs every command through `run_with_usage_stats` (`pipelex/cli/usage_stats_cli.py`) with surface `pipelex-agent`, which reads the switches before the command does anything and sends one `command_completed` when it ends. Stderr is a machine contract when the invocation's errors are JSON (the command's `--error-format json`, else the program's given before the command, else a presentation `--format json`, as `use_agent_cli_error_format` resolves it), so the anonymous-statistics notice is then neither printed nor recorded, though the events are still sent. `_emit_problem` notes the problem's code and domain as the command's error (`note_command_error(error=usage_stats_error_of_problem(...))`); a run on a runner notes its problem's code too, except a refusal a server answered, noted by the code and domain its body sent alone (`sent_usage_stats_error`) and not at all when it sent none, never by the client's reading of its status. `fmt` and `lint` start `plxt` with `PIPELEX_USAGE_STATS=0`, since the command's statistics are this CLI's own. There is no `usage-stats` group here: `pipelex usage-stats` serves both CLIs. The contract is `conformance/specs/usage-statistics.md`; the user docs are `docs/setup/usage-statistics.md`.
- **TOML handling**: Uses `tomlkit` (not `tomllib`) to preserve formatting and inline tables.
diff --git a/pipelex/cli/agent_cli/commands/run/_run_hosted.py b/pipelex/cli/agent_cli/commands/run/_run_hosted.py
index 96803db7f..5668f5017 100644
--- a/pipelex/cli/agent_cli/commands/run/_run_hosted.py
+++ b/pipelex/cli/agent_cli/commands/run/_run_hosted.py
@@ -7,30 +7,25 @@ its result is reported in, and the problem its failure is reported as. Nothing h
A refusal decided here, before anything is sent, is a problem like any local failure, in the operator's view, except a
refusal of the method the run would send, a bundle that does not parse or validate or a bundle file or folder with no
pipe to start at: that is the refusal the runner would answer for the same method, and it is reported in the caller's view
-(:func:`agent_error_method_refusal`). A failure
-of the run itself is the problem the runner answered or the client decided, in the caller's view, since the runner is
-someone else's runtime: pipelex-sdk's errors and the MTHDS client's carry it, by its declared members alone, with the
-next step the human CLI tailors for a failure of the client's own; an answer in a shape that predates the standard's
-reads as the core code its status names, lists its validation items under `method.invalid`, or keeps its reason; and
-pipelex's own `HostedRunError`s give theirs. A
-failure no arm names is this process's own and is reported as a local one is, in the operator's view: a Pipelex error
-under its own code, any other exception as `runtime.unexpected`.
+(:func:`agent_error_method_refusal`). A failure of the run itself is the problem the runner answered or the client
+decided, in the caller's view, since the runner is someone else's runtime, read as the human CLI reads it
+(`pipelex.hosted.error_rendering.describe_hosted_error`): pipelex-sdk's errors and the MTHDS client's carry it, by its
+declared members alone, with the next step this client tailors for a failure of its own side and for a bare answer of
+the hosted edge, and pipelex's own `HostedRunError`s give theirs. A failure no arm names is this process's own and is
+reported as a local one is, in the operator's view: a Pipelex error under its own code, any other exception as
+`runtime.unexpected`.
"""
from __future__ import annotations
import asyncio
import functools
-from collections.abc import Mapping
from typing import TYPE_CHECKING, Any, NoReturn, cast
from mthds.protocol.exceptions import PipelineRequestError
-from mthds.protocol.problem.models import NextStep, Problem, ProblemItem, ProblemLocation, SuggestedFix
-from mthds.protocol.problem.registry import CoreCode, RetryVerdict, StepKind
-from pipelex_sdk.errors import ApiResponseError, ApiUnreachableError, MethodFileTransferError, PipelexRequestError, RunFailedError
-from pydantic import BaseModel, ValidationError
+from pipelex_sdk.errors import ApiResponseError
-from pipelex.base_exceptions import PipelexError, ValidationErrorCategory, ValidationErrorItem
+from pipelex.base_exceptions import PipelexError
from pipelex.cli.agent_cli.commands.agent_output import (
CliOutputFormat,
agent_argument_error,
@@ -39,26 +34,17 @@ from pipelex.cli.agent_cli.commands.agent_output import (
agent_success_formatted,
)
from pipelex.cli.agent_cli.commands.run._output_helpers import build_run_output, format_run_markdown
-from pipelex.errors.problem import PipelexProblem, ProblemView, caller_view_of, make_problem
+from pipelex.errors.problem import ProblemView
from pipelex.hosted.client_factory import make_hosted_client
-from pipelex.hosted.error_rendering import (
- FORMER_ADVICE_KINDS,
- answered_in_former_shape,
- hosted_refusal_problem,
- sent_verdict,
- tailored_next_step,
-)
-from pipelex.hosted.exceptions import HostedMethodInvalidError, HostedRunError, HostedRunInterruptedError, HostedRunPollingError
+from pipelex.hosted.error_rendering import describe_hosted_error
+from pipelex.hosted.exceptions import HostedRunError, HostedRunInterruptedError
from pipelex.hosted.execution import resolve_run_execution
from pipelex.hosted.hosted_run import HostedRunOutcome, HostedRunRequest, RunStartedCallback, run_hosted
from pipelex.hosted.run_config import RunExecution
-from pipelex.pipeline.validation_errors import problem_item_of, validation_item_code
from pipelex.system.usage_stats.usage_stats_runs import sent_usage_stats_error, usage_stats_error
if TYPE_CHECKING:
from pipelex_sdk.client import PipelexAPIClient
- from pipelex_sdk.error_models import RunErrorReport
- from pipelex_sdk.validation_models import ValidationErrorItem as SentValidationErrorItem
#: The `--runner` help, shared by the run commands. Typer renders help as Rich markup, which drops an unescaped `[run]`,
#: so the bracket is escaped as `\[`.
@@ -136,331 +122,18 @@ def agent_error_method_refusal(*, error: PipelexError, message: str, execution:
agent_error_problem(problem=problem, cause=error, noted_error=usage_stats_error(error=error))
-#: The parts of a problem, each read against the model that declares its members, so that a member neither the standard
-#: nor Pipelex declares is left out at every level. A problem's `params` and a fix's `ops` are the code's and the
-#: operation's own and are kept whole; the nested `run_error` and Pipelex's other members are read apart.
-PROBLEM_PARTS: dict[type[BaseModel], dict[str, type[BaseModel]]] = {
- PipelexProblem: {"next_step": NextStep, "location": ProblemLocation, "errors": ProblemItem},
- ProblemItem: {"location": ProblemLocation, "suggested_fix": SuggestedFix},
-}
-#: Pipelex's members beside the standard's, each of which a problem a runner sent may carry in a shape this version does
-#: not read: it is read apart and left out alone when it does not read, never losing the problem around it.
-_PIPELEX_PROBLEM_MEMBERS: tuple[str, ...] = ("request_id", "run_error", "diagnostics")
-
-
-def _declared_members(*, members: Mapping[str, Any], shape: type[BaseModel]) -> dict[str, Any]:
- """The members of ``members`` that ``shape`` declares, each part it nests read the same way (:data:`PROBLEM_PARTS`)."""
- declared: dict[str, Any] = {}
- parts = PROBLEM_PARTS.get(shape, {})
- for name in shape.model_fields:
- if name not in members:
- continue
- value = members[name]
- part_shape = parts.get(name)
- if part_shape is not None and isinstance(value, Mapping):
- declared[name] = _declared_members(members=cast("Mapping[str, Any]", value), shape=part_shape)
- elif part_shape is not None and isinstance(value, list):
- declared[name] = [
- _declared_members(members=cast("Mapping[str, Any]", item), shape=part_shape) if isinstance(item, Mapping) else item
- for item in cast("list[Any]", value)
- ]
- else:
- declared[name] = value
- return declared
-
-
-def _holds_diagnostics(*, members: Mapping[str, Any]) -> bool:
- """Whether a document, or the run's problem it nests, carries diagnostics, whatever their shape: only an operator reads them."""
- if "diagnostics" in members:
- return True
- run_error = members.get("run_error")
- return isinstance(run_error, Mapping) and _holds_diagnostics(members=cast("Mapping[str, Any]", run_error))
-
-
-def _readable_problem(*, members: Mapping[str, Any]) -> PipelexProblem | None:
- """The problem a document's declared members make, each of Pipelex's members kept only when it reads.
-
- The standard's members are read first, by their declared members alone; then ``request_id`` is added when it is a
- text, and ``run_error`` when it reads the same way, so a nested problem whose own members do not all read is kept
- without them. ``diagnostics`` is never kept: the problem is reported to a caller, who reads none.
-
- Returns:
- The problem, or ``None`` when the standard's members do not make one.
- """
- declared = _declared_members(members=members, shape=PipelexProblem)
- extensions = {name: declared.pop(name) for name in _PIPELEX_PROBLEM_MEMBERS if name in declared}
- try:
- readable = PipelexProblem.model_validate(declared)
- except ValidationError:
- return None
- run_error = extensions.get("run_error")
- if isinstance(run_error, Mapping):
- nested = _readable_problem(members=cast("Mapping[str, Any]", run_error))
- if nested is not None:
- readable = readable.model_copy(update={"run_error": nested})
- request_id = extensions.get("request_id")
- if isinstance(request_id, str) and request_id:
- readable = readable.model_copy(update={"request_id": request_id})
- return readable
-
-
-def received_problem(*, problem: Problem, request_id: str | None = None, stored: bool = False) -> PipelexProblem:
- """A problem a runner answered or a client decided, as this CLI reports it: as it came, in the caller's view.
-
- A runner answers its caller in the caller's view already, so the problem is kept as it came, the runner's own next
- step included, by the members the standard and Pipelex declare alone (:func:`_readable_problem`): a member no reader
- declares, such as the `error_type`, `error_domain` and `retryable` a runner may still write, is left out at every
- level, and one of Pipelex's members that does not read is left out alone. An answer that carries diagnostics, which
- a runner answers only to its operator, is projected onto the caller's view (:func:`caller_view_of`), decided from
- the document as it came, before any member is left out, since this machine is not the runner's operator; so is a
- stored record of a run, which is the operator's, and so is the run's problem an answer nests (`run_error`), which is
- that record, whatever view the answer around it is in.
-
- The reading never fails: a problem the standard's client validated always makes one, and the last resort for one
- that would not is `runtime.unexpected`, so the command always prints a problem.
-
- Args:
- problem: The problem as the standard's client reads it.
- request_id: The request the answer belongs to, when the client read it off the answer and the problem names none.
- stored: The problem is a stored record of a run, in its operator's view.
-
- Returns:
- The problem, in the caller's view.
- """
- members = problem.as_wire()
- received = _readable_problem(members=members)
- if received is None:
- return make_problem(code=CoreCode.RUNTIME_UNEXPECTED, view=ProblemView.CALLER, request_id=request_id)
- if request_id and received.request_id is None:
- received = received.model_copy(update={"request_id": request_id})
- if stored or _holds_diagnostics(members=members):
- return caller_view_of(problem=received)
- if received.run_error is not None:
- # A runner's caller-view answer may still nest the run's record as it was stored, in its operator's view, with an
- # operator-only next step and nothing that tells its view, so the record is projected whatever the answer's view.
- return received.model_copy(update={"run_error": caller_view_of(problem=received.run_error)})
- return received
-
-
-def _stored_run_problem(*, report: RunErrorReport | None) -> PipelexProblem | None:
- """The failed run's own problem, read off the report the hosted API stored for it; ``None`` when it stored none.
-
- A report that is a problem document is read as a runner's answer is (:func:`received_problem`), in the caller's
- view, so a member it holds beside the problem, such as its `message` or its `error_type`, is left out, and so is one
- of Pipelex's members that does not read, never the whole problem. A report in the shape the hosted plane wrote before
- it stored problem documents is read by :func:`_former_run_problem`.
- """
- if report is None:
- return None
- try:
- stored = Problem.model_validate(report.model_dump(mode="json", exclude_none=True))
- except ValidationError:
- return _former_run_problem(report=report)
- return received_problem(problem=stored, stored=True)
-
-
-def _former_run_problem(*, report: RunErrorReport) -> PipelexProblem:
- """The failed run's own problem, read off a report in the shape the hosted plane wrote before it stored problem documents.
-
- Such a report names no code: one that lists validation items is `method.invalid`, its items coded as a local verdict
- codes them (:func:`hosted_method_problem_items`), and any other is `runtime.unexpected` (:func:`_former_problem`).
- Its `error_category`, `model` and `provider` are not carried: neither code declares a parameter for them, and the
- hosted read's projection drops the model and the provider.
- """
- advice = report.user_action
- return _former_problem(
- validation_errors=report.validation_errors or [],
- message=report.message,
- advice_kind=advice.kind if advice is not None else None,
- advice_detail=advice.detail if advice is not None else None,
- retryable=report.retryable,
- )
-
-
-def _former_refusal_problem(*, error: ApiResponseError) -> PipelexProblem | None:
- """A refusal in the shape that predates the standard's that lists validation items: the method sent does not validate.
-
- A runner answered `/v1/start` and `/v1/execute` so before it answered problem documents, and the standard's client
- reads such an answer by its status alone. It is `method.invalid`, read as a stored report in the same shape is
- (:func:`_former_problem`), with the answer's reason, advice and retry verdict, its status and its request id, so
- this CLI lists what the human CLI lists (`describe_hosted_error`).
-
- Returns:
- The problem, or ``None`` when the answer lists no item or is not in that shape
- (`pipelex.hosted.error_rendering.answered_in_former_shape`).
- """
- if not error.validation_errors or not answered_in_former_shape(error=error):
- return None
- advice = error.user_action
- problem = _former_problem(
- validation_errors=error.validation_errors,
- message=error.server_message,
- advice_kind=advice.kind if advice is not None else None,
- advice_detail=advice.detail if advice is not None else None,
- retryable=sent_verdict(error=error).retryable,
- )
- updates: dict[str, Any] = {"status": error.status}
- if error.request_id:
- updates["request_id"] = error.request_id
- return problem.model_copy(update=updates)
-
-
-def _former_problem(
- *,
- validation_errors: list[SentValidationErrorItem],
- message: str | None,
- advice_kind: str | None,
- advice_detail: str | None,
- retryable: bool | None,
-) -> PipelexProblem:
- """The problem a report or an answer in the shape that predates the standard's makes, in the caller's view.
-
- It names no code: one that lists validation items is `method.invalid`, its items coded as a local verdict codes them
- (:func:`hosted_method_problem_items`), and any other is `runtime.unexpected`. Its message is the problem's detail,
- its advice the next step, of the kind `FORMER_ADVICE_KINDS` reads, else its code's, and its `retryable` the retry verdict, so
- this CLI tells what the human CLI tells of the same failure (`describe_hosted_error`).
- """
- items = hosted_method_problem_items(validation_errors=validation_errors)
- problem = make_problem(code=CoreCode.METHOD_INVALID if items else CoreCode.RUNTIME_UNEXPECTED, view=ProblemView.CALLER, errors=items or None)
- updates: dict[str, Any] = {}
- if message:
- updates["detail"] = message
- if advice_detail:
- updates["next_step"] = NextStep(kind=FORMER_ADVICE_KINDS.get(advice_kind or "", problem.next_step.kind), detail=advice_detail)
- if isinstance(retryable, bool):
- updates["retry"] = RetryVerdict.YES if retryable else RetryVerdict.NO
- return problem.model_copy(update=updates)
-
-
-def _typed_sent_item(*, sent: SentValidationErrorItem) -> ValidationErrorItem:
- """A validation item the hosted API sent, typed as this version reads one, by the fields this version declares.
-
- A field this version does not declare is left out, so an item of a type it reads keeps its type. A declared field
- whose value this version does not read, as a newer runner may send one, is left out alone, so the item keeps every
- other field, its type, its locators and its dependency facts included: an item whose type this version does not
- know becomes the item no stage classified, its sentence the finding, one whose fix it does not read loses only its
- fix, and one whose category it does not know is read as a blueprint's, the one field an item cannot go without.
- """
- sent_fields = sent.model_dump(mode="json", exclude_none=True)
- declared = {name: value for name, value in sent_fields.items() if name in ValidationErrorItem.model_fields}
- try:
- return ValidationErrorItem.model_validate(declared)
- except ValidationError as exc:
- # Every field that did not read is named by an error, so the fields left all read.
- unread = {error["loc"][0] for error in exc.errors() if error["loc"]}
- readable = {name: value for name, value in declared.items() if name not in unread}
- if "category" in unread:
- readable["category"] = ValidationErrorCategory.BLUEPRINT_VALIDATION
- return ValidationErrorItem.model_validate(readable)
-
-
-def hosted_method_problem_items(*, validation_errors: list[SentValidationErrorItem]) -> list[ProblemItem]:
- """The problem items of the hosted API's verdict that a method does not load, as a local verdict codes its items.
-
- Each item takes the code its type gives it, and ``method.schema_violation``, whose sentence quotes the item's own
- finding, when it has no type this version reads. Each item's ``source``, the label the file was sent under, is its
- location's ``file``.
- """
- items: list[ProblemItem] = []
- for sent in validation_errors:
- item = _typed_sent_item(sent=sent)
- items.append(problem_item_of(item=item, code=validation_item_code(item=item, residual_code=CoreCode.METHOD_SCHEMA_VIOLATION)))
- return items
-
-
-def hosted_failure_problem(*, error: PipelineRequestError | HostedRunError, credential_sent: bool) -> PipelexProblem:
- """The problem of a run on a runner that failed, in the caller's view: the runner's, the client's, or pipelex's own.
-
- - A refusal the runner answered, a runner that cannot be reached and every other failure the client meets carries
- the problem the standard's client decided (`exc.problem`), reported as it came (:func:`received_problem`): the
- runner's own problem document when the answer is one, and otherwise the code the client reads, such as
- `client.unreachable` naming the base URL, or `client.outcome_unknown` for an answer that leaves a run possibly
- started, a server fault on the run request included.
- A failure the client met on its own side takes the step the human CLI tailors for it in place of its code's
- (`pipelex.hosted.error_rendering.tailored_next_step`).
- - An answer in a shape that predates the standard's, which the standard's client reads by its status alone, reads
- as the core code its status and the hosted plane's own code name, with the next step the human CLI gives
- (`pipelex.hosted.error_rendering.hosted_refusal_problem`): a refused or missing credential, a refused operation, a
- route, run or method this origin does not serve, a rate limit with its delay; one listing validation items is
- `method.invalid` with those items, as a stored report in the same shape is (:func:`_former_refusal_problem`);
- and any other such answer keeps the client's reading with the reason the answer gave.
- - A run that started and failed is `run.failed`, naming the run and its status, and nests the run's own problem as
- `run_error`, read off the report the hosted API stored for it, whatever its shape.
- - A failure pipelex detects itself is its `HostedRunError`'s problem, naming the run the hosted API acknowledged
- when there is one, and a method the hosted API found does not load lists the hosted API's items as `errors`.
-
- Args:
- error: The failure.
- credential_sent: Whether the run's requests carried a key, which tells a refused key from a missing one.
-
- Returns:
- The problem, in the caller's view.
- """
- if isinstance(error, HostedMethodInvalidError):
- problem = error.to_problem(view=ProblemView.CALLER)
- items = hosted_method_problem_items(validation_errors=error.validation_errors)
- return problem.with_members(errors=[item.as_wire() for item in items]) if items else problem
- if isinstance(error, HostedRunPollingError | HostedRunInterruptedError):
- return error.to_problem(view=ProblemView.CALLER, pipeline_run_id=error.pipeline_run_id)
- if isinstance(error, HostedRunError):
- return error.to_problem(view=ProblemView.CALLER)
- request_id: str | None = None
- if isinstance(error, ApiResponseError):
- refusal = _former_refusal_problem(error=error) or hosted_refusal_problem(error=error, credential_sent=credential_sent)
- if refusal is not None:
- return refusal
- request_id = error.request_id
- problem = received_problem(problem=error.problem, request_id=request_id)
- if isinstance(error, RunFailedError):
- # The run's own step rides in its nested problem.
- run_error = _stored_run_problem(report=error.error)
- return problem.with_members(run_error=run_error.to_wire()) if run_error is not None else problem
- tailored = None if isinstance(error, ApiResponseError) else tailored_next_step(error=error)
- if tailored is not None:
- problem = problem.model_copy(update={"next_step": NextStep(kind=problem.next_step.kind, detail=tailored)})
- if isinstance(error, MethodFileTransferError):
- problem = _transfer_verdict_problem(problem=problem, error=error)
- return problem
-
-
-def _transfer_verdict_problem(*, problem: PipelexProblem, error: MethodFileTransferError) -> PipelexProblem:
- """The problem of a file of the method's tree that could not be moved, its retry verdict and its step's kind the SDK's verdict.
-
- pipelex-sdk states the problem of an answer storage gave from its status alone, which the standard reads by its own
- table, so a status the SDK calls retryable, a `429` for one, can come as a code no retry gets past. Whether the
- same transfer can succeed later is the SDK's verdict (`error.retryable`), the one the human CLI tells
- (`describe_hosted_error`), so the problem carries it: a retry for every code but a refusal, which is reported.
- """
- kind = StepKind.RETRY if error.retryable else StepKind.REPORT
- return problem.model_copy(
- update={
- "retry": RetryVerdict.YES if error.retryable else RetryVerdict.NO,
- "next_step": NextStep(kind=kind, detail=problem.next_step.detail),
- }
- )
-
-
def agent_error_hosted(*, error: PipelineRequestError | HostedRunError, credential_sent: bool, exit_code: int = 1) -> NoReturn:
- """Report a run on a runner that failed as its problem (:func:`hosted_failure_problem`), and exit with `exit_code`.
+ """Report a run on a runner that failed as its problem, and exit with `exit_code`.
- The problem is printed as it came, in the active error format, with no member of the envelope this CLI wrote before
- it reported problems. pipelex's own errors add their sentence as `message`, and so does every error of pipelex-sdk's
- own, which says what its code's parameters cannot: the stored reason of a run that failed, how long the client waited
- for one that did not finish, that a completed run delivered no main output. An answer's refusal and a runner that
- cannot be reached add none, their problem saying it all, where their sentence would quote a raw body or a transport's
- class. The usage statistics record what the problem says, except for a refusal a server answered, which they record
- by the code and domain its body sent alone, and not at all when it sent none, never by the client's reading of its status.
+ The problem, the sentence beside it and the advice the Markdown prints as its tip are the ones the human CLI prints
+ (`pipelex.hosted.error_rendering.describe_hosted_error`), printed as they came, in the active error format, with no
+ member of the envelope this CLI wrote before it reported problems. The usage statistics record what the problem
+ says, except for a refusal a server answered, which they record by the code and domain its body sent alone, and not
+ at all when it sent none, never by the client's reading of its status.
"""
- problem = hosted_failure_problem(error=error, credential_sent=credential_sent)
- message: str | None
- if isinstance(error, PipelexError):
- message = error.message
- elif isinstance(error, PipelexRequestError) and not isinstance(error, ApiResponseError | ApiUnreachableError):
- message = str(error)
- else:
- message = None
+ view = describe_hosted_error(error=error, credential_sent=credential_sent)
noted_error = sent_usage_stats_error(error=error) if isinstance(error, ApiResponseError) else usage_stats_error(error=error)
- agent_error_problem(problem=problem, cause=error, noted_error=noted_error, message=message, exit_code=exit_code)
+ agent_error_problem(problem=view.problem, cause=error, noted_error=noted_error, message=view.message, exit_code=exit_code)
def build_hosted_run_output(*, outcome: HostedRunOutcome, with_memory: bool) -> dict[str, Any]:
diff --git a/pipelex/cli/commands/run/_run_hosted.py b/pipelex/cli/commands/run/_run_hosted.py
index 31a956c8f..15fb46c9e 100644
--- a/pipelex/cli/commands/run/_run_hosted.py
+++ b/pipelex/cli/commands/run/_run_hosted.py
@@ -14,13 +14,12 @@ from typing import TYPE_CHECKING, Any, cast
import typer
from mthds.protocol.exceptions import PipelineRequestError
-from pipelex_sdk.errors import ApiResponseError
from rich.markup import escape
from pipelex.base_exceptions import PipelexError
from pipelex.cli.commands.run._run_core import load_run_inputs
from pipelex.cli.commands.run._run_output_folder import make_run_output_folder
-from pipelex.cli.error_handlers import handle_validate_bundle_error, print_traceback_if_requested
+from pipelex.cli.error_handlers import handle_validate_bundle_error, print_problem_items, print_problem_rows, print_traceback_if_requested
from pipelex.hosted.client_factory import make_hosted_client
from pipelex.hosted.error_rendering import describe_hosted_error
from pipelex.hosted.exceptions import HostedRunError, HostedRunInterruptedError
@@ -108,29 +107,39 @@ def refuse_local_only_flags(
raise _fail(message=msg)
-def _print_hosted_failure(*, error: PipelineRequestError | HostedRunError, heading: str = _FAILURE_HEADING) -> None:
- """Print a hosted run's failure as `pipelex.hosted.error_rendering` reads it, the view the agent CLI's envelope carries.
+def _print_hosted_failure(*, error: PipelineRequestError | HostedRunError, credential_sent: bool, heading: str = _FAILURE_HEADING) -> None:
+ """Print a hosted run's failure as its problem, the one the agent CLI reports (`pipelex.hosted.error_rendering`).
- Its validation items name the file each fault is in when the hosted API was told it, and the run id is printed
- once the hosted API acknowledged the run, so a run that failed, outlived the wait, was lost on the way or was left
- running by an interruption can be looked up.
+ The heading, the error's own sentence when it says what the problem does not, then the problem's rows: its title,
+ its detail, its next step, its code with its domain and its retry verdict, where it happened, the request and the
+ run, so a run that failed, outlived the wait, was lost on the way or was left running by an interruption can be
+ looked up. Its faults follow, one per line with its code, its sentence and where, each naming its file when the
+ hosted API was told it, then the failed run's own problem when the run started and failed, and the advice
+ pipelex's own error gives as a tip.
+
+ Args:
+ error: The failure.
+ credential_sent: Whether the run's requests carried a key, which tells a refused key from a missing one.
+ heading: The headline, which names what failed.
"""
- view = describe_hosted_error(error=error)
+ view = describe_hosted_error(error=error, credential_sent=credential_sent)
# On stderr, as every failure's report: stdout is the run's output.
console = get_error_console()
console.print(f"\n[bold red]{escape(heading)}[/bold red]\n")
- console.print(f" {escape(view.message)}\n")
- if view.validation_errors:
- for item in view.validation_errors:
- location = item.source or item.pipe_code or item.concept_code or item.domain_code
- prefix = f"{location}: " if location else ""
- console.print(f" - {escape(prefix + item.message)}")
- console.print("")
- console.print(f" [bold]Next step:[/bold] {escape(view.next_step)}\n")
- if view.pipeline_run_id is not None:
- console.print(f" Run id: {escape(view.pipeline_run_id)}\n")
- if isinstance(error, ApiResponseError) and error.request_id:
- console.print(f" Request id: {escape(error.request_id)}\n")
+ # The sentence and the advice are plain text, so they are escaped before Rich reads markup in them.
+ printed_message = escape(view.message) if view.message else None
+ printed_tip = escape(view.advice) if view.advice else None
+ if printed_message is not None:
+ console.print(f" {printed_message}\n")
+ print_problem_rows(console=console, problem=view.problem, error_message=printed_message, tip=printed_tip)
+ print_problem_items(console=console, problem=view.problem)
+ run_error = view.problem.run_error
+ if run_error is not None:
+ console.print("[bold]The run's own problem[/bold]\n")
+ print_problem_rows(console=console, problem=run_error, error_message=printed_message, tip=None)
+ print_problem_items(console=console, problem=run_error)
+ if printed_tip is not None:
+ console.print(f"[bold green]💡 Tip:[/bold green] {printed_tip}\n")
async def _start_and_wait(*, client: PipelexAPIClient, request: HostedRunRequest, on_started: RunStartedCallback) -> HostedRunOutcome:
@@ -233,6 +242,8 @@ def execute_hosted_run(
console = get_console()
console.print(f"Running on the hosted Pipelex API at [bold]{escape(client.base_url)}[/bold]")
+ # Whether the run's requests carry a key, which tells a refused key from a missing one; never the key itself.
+ credential_sent = bool(client.api_key)
started_run_ids: list[str] = []
def _announce_start(*, pipeline_run_id: str) -> None:
@@ -244,11 +255,11 @@ def execute_hosted_run(
except (KeyboardInterrupt, asyncio.CancelledError) as exc:
# Ctrl-C stops the wait, not the run: name the run that keeps going, then exit as an interrupted command does.
interrupted = HostedRunInterruptedError(pipeline_run_id=started_run_ids[-1] if started_run_ids else None)
- _print_hosted_failure(error=interrupted, heading="Interrupted")
+ _print_hosted_failure(error=interrupted, credential_sent=credential_sent, heading="Interrupted")
raise typer.Exit(_INTERRUPTED_EXIT_CODE) from exc
except (PipelineRequestError, HostedRunError) as exc:
print_traceback_if_requested(console=console)
- _print_hosted_failure(error=exc)
+ _print_hosted_failure(error=exc, credential_sent=credential_sent)
raise typer.Exit(1) from exc
except Exception as exc:
# CLI command root: any unexpected failure is reported to the user and exits non-zero via typer.Exit.
diff --git a/pipelex/cli/error_handlers.py b/pipelex/cli/error_handlers.py
index 6f208c35d..649461025 100644
--- a/pipelex/cli/error_handlers.py
+++ b/pipelex/cli/error_handlers.py
@@ -145,6 +145,25 @@ def print_problem_rows(*, console: Console, problem: PipelexProblem, error_messa
console.print()
+def print_problem_items(*, console: Console, problem: PipelexProblem) -> None:
+ """Print a problem's faults, its ``errors``, one per line with its code, its sentence and where, then a blank line.
+
+ Nothing is printed for a problem that lists none.
+
+ Args:
+ console: The console to print to.
+ problem: The problem whose faults to print.
+ """
+ if not problem.errors:
+ return
+ console.print("[bold cyan]Errors:[/bold cyan]")
+ for item in problem.errors:
+ where = format_problem_location(location=item.location)
+ located = f" ({where})" if where else ""
+ console.print(f" - [yellow]{escape(item.code)}[/yellow]: {escape(item.detail + located)}")
+ console.print()
+
+
def print_failure_problem(*, console: Console, title: str, error: BaseException) -> PipelexProblem:
"""Print a command's own report of a failure it caught at its root, and return the failure's problem.
diff --git a/pipelex/errors/unsupported_reasons.py b/pipelex/errors/unsupported_reasons.py
index 913a39852..a1ee428a2 100644
--- a/pipelex/errors/unsupported_reasons.py
+++ b/pipelex/errors/unsupported_reasons.py
@@ -12,3 +12,8 @@ REMOTE_TABLE_UNSUPPORTED_REASON = "remote_table_url"
#: A method given as the MTHDS protocol's `files` map, a tree path to file entry, to the local runtime or the runner,
#: which take a method as its bundles' contents (`mthds_contents`) or as their library directories' method trees.
METHOD_FILES_UNSUPPORTED_REASON = "method_files_on_local_runtime"
+
+#: A local file named in a hosted run's inputs, for a method that calls another by its address: the file can be
+#: uploaded only once the method's signature is read, which the hosted API cannot do without the package the method
+#: calls, so the file has to be given as a URL the hosted API fetches instead.
+LOCAL_FILE_WITH_ADDRESS_DEPENDENCY_UNSUPPORTED_REASON = "local_file_with_address_dependency"
diff --git a/pipelex/hosted/error_rendering.py b/pipelex/hosted/error_rendering.py
index f255a2723..9f84e6149 100644
--- a/pipelex/hosted/error_rendering.py
+++ b/pipelex/hosted/error_rendering.py
@@ -1,47 +1,53 @@
-"""What went wrong on a hosted run, and what to do next, read off the error pipelex-sdk or pipelex raised.
-
-Every error of a hosted run that is not pipelex's own arrives as one of the SDK's classes, all of which derive from
-the protocol's `PipelineRequestError`; pipelex's own derive from `HostedRunError`. An `ApiResponseError` carries the
-hosted API's problem document: its reason (the problem's `detail`) and, when the server advised one, its next step
-(`user_action.detail`). Answers the hosted plane authors in front of the runner (a refused key, an unknown route, a
-rate limit, an unavailable runner) advise none, so their next step follows their status here. The human CLI prints
-this view of an error, its run id and its validation items included; the agent CLI reports the problem the error
-carries instead (`pipelex/cli/agent_cli/commands/run/_run_hosted.py`), with the next step this module tailors for a
-failure of the client's own (`tailored_next_step`), and for an answer in a shape that predates the standard's problem
-document, which the standard's client reads by its status alone, the problem `hosted_refusal_problem` reads from it:
-the core code its status and the plane's own code name, or the client's reading with the answer's own reason, with
-the next step this module gives the human CLI, so both CLIs tell the same thing.
+"""What went wrong on a hosted run, and what to do next: the problem both CLIs report, read off the error pipelex-sdk or pipelex raised.
+
+Every error of a hosted run that is not pipelex's own arrives as one of pipelex-sdk's classes, all of which derive from
+the protocol's `PipelineRequestError` and carry the failure as the standard's problem document (`exc.problem`): the
+runner's own when it answered one, and otherwise the code the client states. pipelex's own derive from `HostedRunError`
+and give theirs (:meth:`PipelexError.to_problem`). The problem is reported as it came, in the caller's view, since the
+runner is someone else's runtime (:func:`received_problem`), with two readings of this client's own
+(:func:`hosted_failure_problem`):
+
+- an answer that is no problem document, the bare answer of the hosted edge, a gateway or a proxy, which pipelex-sdk
+ reads by its status alone, is read here too: a refused credential is a missing one when the request carried no key,
+ and a refused credential or a route the server does not serve takes the next step that names this client's settings.
+ This reading stays written by hand until the registry records it and every client generates it;
+- a failure the client met on its own side, such as a runner that cannot be reached, a run past the wait or a file that
+ could not be uploaded, takes the next step this client tailors for it, naming its settings and the run.
+
+Both CLIs report the same problem (:func:`describe_hosted_error`): the agent CLI prints it as JSON or Markdown
+(`pipelex/cli/agent_cli/commands/run/_run_hosted.py`), the human CLI as the rows of its failure panels
+(`pipelex/cli/commands/run/_run_hosted.py`), each with the error's own sentence and pipelex's own advice beside it.
"""
-from typing import Any, NamedTuple
+from collections.abc import Mapping
+from typing import Any, NamedTuple, cast
from mthds.protocol.exceptions import PipelineRequestError
-from mthds.protocol.problem.answers import parse_retry_after, read_problem_document
-from mthds.protocol.problem.models import NextStep, Problem
-from mthds.protocol.problem.registry import STATUS_READINGS, CoreCode, StepKind
+from mthds.protocol.problem.answers import read_problem_document
+from mthds.protocol.problem.models import NextStep, Problem, ProblemItem, ProblemLocation, SuggestedFix
+from mthds.protocol.problem.registry import CoreCode, RetryVerdict
from pipelex_sdk.errors import (
ApiResponseError,
ApiUnreachableError,
InputPreparationError,
InvalidLocalSourceError,
- MethodErrorCode,
- MethodFileTransferCode,
MethodFileTransferError,
+ MethodFileTransferReason,
MissingMainStuffError,
+ PipelexRequestError,
PipelineExecuteTimeoutError,
RejectedAssetError,
- RunFailedError,
RunLifecycleUnavailableError,
RunTimeoutError,
UnsupportedUploadCapabilityError,
UploadAuthenticationError,
UploadTransportError,
+ UploadTransportReason,
)
-from pipelex_sdk.validation_models import ValidationErrorItem
+from pydantic import BaseModel, ValidationError
-from pipelex.base_exceptions import ErrorDomain
-from pipelex.errors.error_codes import error_code_spec
-from pipelex.errors.problem import PipelexProblem, ProblemView, make_problem
+from pipelex.base_exceptions import PipelexError
+from pipelex.errors.problem import PipelexProblem, ProblemView, caller_view_of, make_problem
from pipelex.hosted.client_factory import HOSTED_API_DEFAULT_BASE_URL, PIPELEX_API_KEY_ENV_KEY, PIPELEX_BASE_URL_ENV_KEY
from pipelex.hosted.exceptions import HostedMethodInvalidError, HostedRunError, HostedRunInterruptedError, HostedRunPollingError
@@ -59,47 +65,21 @@ HOSTED_BASE_URL_NEXT_STEP = (
f"Check the hosted API origin: --base-url, else {PIPELEX_BASE_URL_ENV_KEY}, else https://api.pipelex.com; "
"it is scheme://host[:port], with no path such as /v1"
)
-_RATE_LIMITED_NEXT_STEP = "Too many requests: wait retry_after seconds when the error gives it, otherwise a few seconds, then run again"
-# A 503 does not say whether the run happened: the hosted plane can answer it before forwarding the request and also
-# after the run completed, when it failed to record the result. So its next step warns that running again can repeat
-# a paid run.
-_UNAVAILABLE_NEXT_STEP = (
- "The hosted API or the runner behind it was unavailable. It may have failed before the run or after it, so running "
- "again can repeat a paid run: wait retry_after seconds when the error gives it, then run again only if a repeated run is acceptable"
-)
-#: The next step of a request refused because it carried no key, which the hosted plane answers with a 401 or a 403.
+#: The next step of a request refused because it carried no key, which the hosted edge answers with a bare 401 or 403.
HOSTED_MISSING_KEY_NEXT_STEP = f"The request carried no Pipelex API key. {HOSTED_API_KEY_NEXT_STEP}"
-#: The next step of a 403 the platform answers itself, for a key it authenticated and an operation the key may not do.
-HOSTED_FORBIDDEN_NEXT_STEP = (
- "The hosted API accepted the key and refused what this request does: the message says what it may not do. Ask the "
- "organization's owner for that access, or use a key of an account that has it"
-)
-
-#: The next step of a refusal whose answer advised none, by its HTTP status.
+#: The next step of an answer that is no problem document, by its HTTP status, for the statuses this client reads.
HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS: dict[int, str] = {
401: f"The hosted API refused the credentials. {HOSTED_API_KEY_NEXT_STEP}",
403: (
- f"The hosted API refused the request: check that {PIPELEX_API_KEY_ENV_KEY} is a valid key for the API at "
+ f"The hosted API refused the request's key: check that {PIPELEX_API_KEY_ENV_KEY} is a valid key for the API at "
f"{PIPELEX_BASE_URL_ENV_KEY} (or --base-url), and run {PIPELEX_LOGIN_COMMAND} to replace it when it is not; "
- "when it is, the message says what this request may not do"
+ "a valid key may also be refused a route it may not call"
),
- 404: f"The hosted API has no such method or route: check the method's address or catalog id. {HOSTED_BASE_URL_NEXT_STEP}",
- 429: _RATE_LIMITED_NEXT_STEP,
- 503: _UNAVAILABLE_NEXT_STEP,
+ 404: f"The server at the base URL serves no such route. {HOSTED_BASE_URL_NEXT_STEP}",
}
-#: The next step of a 4xx refusal that advised none and whose status has no next step of its own.
-HOSTED_REFUSAL_CALLER_NEXT_STEP = (
- "The hosted API refused the request: change what the message names (the method, the inputs or the configuration), then run again"
-)
-#: The next step of a server-side failure that advised none.
-HOSTED_SERVER_FAULT_NEXT_STEP = (
- "The hosted API failed on its side: report it with the request_id, or with the http_status when the error carries no request_id"
-)
#: The next step of a request that never reached the hosted API.
HOSTED_UNREACHABLE_NEXT_STEP = f"Check the network connection. {HOSTED_BASE_URL_NEXT_STEP}"
-#: The next step of a failure no arm of `describe_hosted_error` tailors a step for.
-HOSTED_RUN_REQUEST_NEXT_STEP = "Check the run request: the method, the pipe and the inputs"
#: The next steps of a file of the method's tree that could not be moved to or from the hosted API's storage, by why it
#: failed. pipelex-sdk moves a tree's files before the request that needs them, so nothing was started.
HOSTED_FILE_UNREACHABLE_NEXT_STEP = (
@@ -108,395 +88,352 @@ HOSTED_FILE_UNREACHABLE_NEXT_STEP = (
HOSTED_FILE_STORAGE_ERROR_NEXT_STEP = (
"The hosted API's storage failed, timed out or throttled a file of the method, so nothing was started: wait a few seconds, then run again"
)
-HOSTED_FILE_MISMATCH_NEXT_STEP = "A file of the method came back from the hosted API's storage as other bytes than the ones it names: run again"
+HOSTED_FILE_MISMATCH_NEXT_STEP = (
+ "A file of the method came back from the hosted API's storage as other bytes than the ones it names: report it with the SHA-256 the message names"
+)
HOSTED_FILE_REFUSED_NEXT_STEP = (
"The hosted API's storage refused a file of the method, so nothing was started, and running again meets the same refusal: "
"report it with the SHA-256 the message names"
)
-
-#: The member of the hosted plane's own refusal that states, in seconds, how long to wait before asking again; its
-#: `Retry-After` header states it too, and wins.
-_SENT_RETRY_AFTER_MEMBER = "retry_after_seconds"
-#: The codes the platform answers a `403` with when it authenticated the key and refuses the operation: `forbidden`, and
-#: `role_not_permitted` for a role that may not do it. pipelex-sdk names no constant for them. Any other code on a `403`
-#: is no refusal of an operation this client can tell, so it reads as the credential's.
-_PLANE_AUTHORIZATION_CODES: frozenset[str] = frozenset({"forbidden", "role_not_permitted"})
-
-#: The step kind each advice of an answer or a report in the former shape names (its `user_action.kind`), in the
-#: standard's closed list of kinds; an advice of another kind, `unknown` included, takes the kind its reader gives.
-FORMER_ADVICE_KINDS: dict[str, StepKind] = {
- "wait_and_retry": StepKind.WAIT,
- "check_billing": StepKind.CHECK_ACCOUNT,
- "check_credentials": StepKind.CHECK_CREDENTIALS,
- "change_input": StepKind.CHANGE_INPUT,
- "change_model": StepKind.CHANGE_MODEL,
- "contact_support": StepKind.REPORT,
+#: The parts of a problem, each read against the model that declares its members, so that a member neither the standard
+#: nor Pipelex declares is left out at every level. A problem's `params` and a fix's `ops` are the code's and the
+#: operation's own and are kept whole; the nested `run_error` and Pipelex's other members are read apart.
+PROBLEM_PARTS: dict[type[BaseModel], dict[str, type[BaseModel]]] = {
+ PipelexProblem: {"next_step": NextStep, "location": ProblemLocation, "errors": ProblemItem},
+ ProblemItem: {"location": ProblemLocation, "suggested_fix": SuggestedFix},
}
+#: Pipelex's members beside the standard's, each of which a problem a runner sent may carry in a shape this version does
+#: not read: it is read apart and left out alone when it does not read, never losing the problem around it.
+_PIPELEX_PROBLEM_MEMBERS: tuple[str, ...] = ("request_id", "run_error", "diagnostics")
+
+
+def _declared_members(*, members: Mapping[str, Any], shape: type[BaseModel]) -> dict[str, Any]:
+ """The members of ``members`` that ``shape`` declares, each part it nests read the same way (:data:`PROBLEM_PARTS`)."""
+ declared: dict[str, Any] = {}
+ parts = PROBLEM_PARTS.get(shape, {})
+ for name in shape.model_fields:
+ if name not in members:
+ continue
+ value = members[name]
+ part_shape = parts.get(name)
+ if part_shape is not None and isinstance(value, Mapping):
+ declared[name] = _declared_members(members=cast("Mapping[str, Any]", value), shape=part_shape)
+ elif part_shape is not None and isinstance(value, list):
+ declared[name] = [
+ _declared_members(members=cast("Mapping[str, Any]", item), shape=part_shape) if isinstance(item, Mapping) else item
+ for item in cast("list[Any]", value)
+ ]
+ else:
+ declared[name] = value
+ return declared
+
+
+def _holds_diagnostics(*, members: Mapping[str, Any]) -> bool:
+ """Whether a document, or the run's problem it nests, carries diagnostics, whatever their shape: only an operator reads them."""
+ if "diagnostics" in members:
+ return True
+ run_error = members.get("run_error")
+ return isinstance(run_error, Mapping) and _holds_diagnostics(members=cast("Mapping[str, Any]", run_error))
+
+
+def _readable_problem(*, members: Mapping[str, Any]) -> PipelexProblem | None:
+ """The problem a document's declared members make, each of Pipelex's members kept only when it reads.
+
+ The standard's members are read first, by their declared members alone; then ``request_id`` is added when it is a
+ text, and ``run_error`` when it reads the same way, so a nested problem whose own members do not all read is kept
+ without them. ``diagnostics`` is never kept: the problem is reported to a caller, who reads none.
+ Returns:
+ The problem, or ``None`` when the standard's members do not make one.
+ """
+ declared = _declared_members(members=members, shape=PipelexProblem)
+ extensions = {name: declared.pop(name) for name in _PIPELEX_PROBLEM_MEMBERS if name in declared}
+ try:
+ readable = PipelexProblem.model_validate(declared)
+ except ValidationError:
+ return None
+ run_error = extensions.get("run_error")
+ if isinstance(run_error, Mapping):
+ nested = _readable_problem(members=cast("Mapping[str, Any]", run_error))
+ if nested is not None:
+ readable = readable.model_copy(update={"run_error": nested})
+ request_id = extensions.get("request_id")
+ if isinstance(request_id, str) and request_id:
+ readable = readable.model_copy(update={"request_id": request_id})
+ return readable
+
+
+def received_problem(*, problem: Problem, request_id: str | None = None) -> PipelexProblem:
+ """A problem a runner answered or a client decided, as both CLIs report it: as it came, in the caller's view.
+
+ A runner answers its caller in the caller's view already, so the problem is kept as it came, the runner's own next
+ step included, by the members the standard and Pipelex declare alone (:func:`_readable_problem`): a member no reader
+ declares, such as the `error_type`, `error_domain` and `retryable` a runner may still write, is left out at every
+ level, and one of Pipelex's members that does not read is left out alone. An answer that carries diagnostics, which
+ a runner answers only to its operator, is projected onto the caller's view (:func:`caller_view_of`), decided from
+ the document as it came, before any member is left out, since this machine is not the runner's operator; so is the
+ failed run's own problem an answer nests (`run_error`), which is the run's stored record, in its operator's view,
+ whatever view the answer around it is in.
+
+ The reading never fails: a problem the standard's client validated always makes one, and the last resort for one
+ that would not is `runtime.unexpected`, so the command always prints a problem.
-class _RefusalReading(NamedTuple):
- """The core code a refusal of the hosted plane in its own shape reads as, and the step for it when the plane advised none.
+ Args:
+ problem: The problem as the standard's client reads it.
+ request_id: The request the answer belongs to, when the client read it off the answer and the problem names none.
- `next_step` is `None` when the code's own step, from the registry, fits the refusal better than its status's.
+ Returns:
+ The problem, in the caller's view.
"""
+ members = problem.as_wire()
+ received = _readable_problem(members=members)
+ if received is None:
+ return make_problem(code=CoreCode.RUNTIME_UNEXPECTED, view=ProblemView.CALLER, request_id=request_id)
+ if request_id and received.request_id is None:
+ received = received.model_copy(update={"request_id": request_id})
+ if _holds_diagnostics(members=members):
+ return caller_view_of(problem=received)
+ if received.run_error is not None:
+ # A runner's caller-view answer may still nest the run's record as it was stored, in its operator's view, with an
+ # operator-only next step and nothing that tells its view, so the record is projected whatever the answer's view.
+ return received.model_copy(update={"run_error": caller_view_of(problem=received.run_error)})
+ return received
+
+
+class _BareAnswerReading(NamedTuple):
+ """The code an answer that is no problem document reads as here, and the next step that names this client's settings."""
code: CoreCode
- next_step: str | None
+ next_step: str
-def _hosted_refusal_reading(*, status: int, plane_code: str | None, credential_sent: bool) -> _RefusalReading | None:
- """The core code a refusal of the hosted plane in its own shape reads as, by its status and its own code.
+def _bare_answer_reading(*, status: int, credential_sent: bool) -> _BareAnswerReading | None:
+ """The reading of an answer that is no problem document by its status, for the statuses this client reads itself.
- A refused credential is the hosted plane's `401` and the bare `403` its edge's authorizer answers, without a reason,
- for an unknown key among others; it is `auth.missing_credential` when the request carried no key. A `403` the
- platform answers with one of its authorization codes (:data:`_PLANE_AUTHORIZATION_CODES`) refuses an operation to a
- key it authenticated, and a `403` with any other code, such as one for a key that is invalid or expired, refuses the
- credential. A `404` is the run or the method the platform's code names (`run_not_found`,
- `method_version_not_found`), and otherwise a route or a method this origin does not serve, which the platform's
- `not_found` does not tell apart. A `429` is a rate limit.
+ pipelex-sdk reads the hosted edge's bare `401` as `auth.missing_credential`, since the edge answers it to a request
+ that carries no key, and its bare `403` as `auth.invalid_credential`: this client knows whether the request carried
+ a key, so either is `auth.missing_credential` when none was sent and `auth.invalid_credential` when one was. A bare
+ `404` is `request.not_found`: the server at the base URL serves no such route.
Returns:
- The reading, or ``None`` for a status none names.
+ The reading, or ``None`` for a status whose reading by pipelex-sdk stands, with its code's own next step.
"""
- by_status = HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS
match status:
case 401 | 403 if not credential_sent:
- return _RefusalReading(code=CoreCode.AUTH_MISSING_CREDENTIAL, next_step=HOSTED_MISSING_KEY_NEXT_STEP)
- case 401:
- return _RefusalReading(code=CoreCode.AUTH_INVALID_CREDENTIAL, next_step=by_status[401])
- case 403 if plane_code in _PLANE_AUTHORIZATION_CODES:
- return _RefusalReading(code=CoreCode.AUTH_FORBIDDEN, next_step=HOSTED_FORBIDDEN_NEXT_STEP)
- case 403:
- return _RefusalReading(code=CoreCode.AUTH_INVALID_CREDENTIAL, next_step=by_status[403])
+ return _BareAnswerReading(code=CoreCode.AUTH_MISSING_CREDENTIAL, next_step=HOSTED_MISSING_KEY_NEXT_STEP)
+ case 401 | 403:
+ return _BareAnswerReading(code=CoreCode.AUTH_INVALID_CREDENTIAL, next_step=HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[status])
case 404:
- match plane_code:
- # The platform's code for a run it holds none of, which pipelex-sdk names no constant for.
- case "run_not_found":
- return _RefusalReading(code=CoreCode.RUN_NOT_FOUND, next_step=None)
- case MethodErrorCode.METHOD_VERSION_NOT_FOUND:
- return _RefusalReading(code=CoreCode.METHOD_NOT_FOUND, next_step=by_status[404])
- case _:
- return _RefusalReading(code=CoreCode.REQUEST_NOT_FOUND, next_step=by_status[404])
- case 429:
- return _RefusalReading(code=CoreCode.ACCOUNT_RATE_LIMITED, next_step=by_status[429])
+ return _BareAnswerReading(code=CoreCode.REQUEST_NOT_FOUND, next_step=HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[404])
case _:
return None
-def _sent_retry_after(*, error: ApiResponseError) -> float | None:
- """How long the hosted plane said to wait, in seconds: its `Retry-After` header, else its body's own member.
-
- Whether the delay is one a problem can carry, and whether its code invites a retry at all, is :func:`make_problem`'s.
- """
- from_header = parse_retry_after((error.headers or {}).get("retry-after"))
- if from_header is not None:
- return from_header
- sent = (error.problem_document or {}).get(_SENT_RETRY_AFTER_MEMBER)
- if isinstance(sent, int | float) and not isinstance(sent, bool):
- return sent
- return None
-
-
-def answered_in_former_shape(*, error: ApiResponseError) -> bool:
- """Whether a refusal is an answer in a shape that predates the standard's problem document, read by its status alone.
-
- An answer that is a problem document of the standard speaks for itself, and one that may have started a run keeps the
- client's reading as `client.outcome_unknown`, so neither is.
- """
- if error.run_may_have_started:
- return False
- return read_problem_document(error.response_body, status=error.status, headers=error.headers or {}) is None
-
-
-def _client_reading(*, error: ApiResponseError) -> PipelexProblem:
- """The client's reading of a refusal, by the members the standard declares alone.
-
- A member beside them, such as a `run_error` or `diagnostics` of Pipelex's in a shape no reader takes, is left out, so
- the reading never fails: the members of a problem the client validated always make one.
- """
- standard = {name: value for name, value in error.problem.as_wire().items() if name in Problem.model_fields}
- return PipelexProblem.model_validate(standard)
-
-
-def hosted_refusal_problem(*, error: ApiResponseError, credential_sent: bool) -> PipelexProblem | None:
- """An answer in a shape that predates the standard's problem document, as the problem the agent CLI reports for it.
-
- The hosted plane answers its own refusals in that shape (a closed `code` such as `unauthorized` or `rate_limited`,
- beside `error_domain` and `retryable`), and so does a runner for a refusal it authors itself, such as the `422` an
- older runner answers for a reserved input key. The standard's client reads such an answer by its status alone,
- `client.response_unreadable` for most, losing its reason and what to do.
-
- - A refusal whose status and plane code name a core code (:func:`_hosted_refusal_reading`) reads as that code, in
- the caller's view (:func:`make_problem`), the plane's own `detail` kept, its request id, the delay its
- `Retry-After` header or its body states, and the step it advised, else the step the human CLI gives its status.
- - Any other answer that gives its reason keeps the client's reading, its code and its status, by the standard's
- members alone (:func:`_client_reading`), with that reason as its `detail` and the step the human CLI gives it
- (:func:`hosted_refusal_next_step`), so the reader is told what the body said rather than to report a body it
- never sees. The step's kind is the one the answer's advice names (:data:`FORMER_ADVICE_KINDS`), else
- `change_input` for a `4xx`, a refusal of the caller's request, and the client's reading's for any other status.
-
- The agent CLI reads an answer that lists validation items before this one is asked, as a method that does not
- validate (`pipelex.cli.agent_cli.commands.run._run_hosted`), since only it codes the items.
-
- Args:
- error: The refusal, as the client raised it.
- credential_sent: Whether the request carried a key, which tells a refused key from a missing one.
-
- Returns:
- The problem, or ``None`` when the answer is a problem document of the standard, which speaks for itself, when it
- may have started a run, whose reading as `client.outcome_unknown` stands, when its status is one the standard
- reads as a code, or when it names no core code here and gives no reason.
- """
- if not answered_in_former_shape(error=error):
- return None
- reading = _hosted_refusal_reading(status=error.status, plane_code=error.code, credential_sent=credential_sent)
- if reading is not None:
- return _coded_refusal_problem(error=error, reading=reading)
- if error.status in STATUS_READINGS or not error.server_message:
- return None
- reason_kept = _client_reading(error=error)
- # A refusal of the caller's request asks for a change to it; any other answer is the runtime's to explain. Advice
- # the answer gave is the step's detail, so the step takes the kind that advice names.
- status_kind = StepKind.CHANGE_INPUT if 400 <= error.status < 500 else reason_kept.next_step.kind
- advice = error.user_action
- kind = FORMER_ADVICE_KINDS.get(advice.kind, status_kind) if advice is not None else status_kind
- updates: dict[str, Any] = {
- "status": error.status,
- "detail": error.server_message,
- "next_step": NextStep(kind=kind, detail=hosted_refusal_next_step(error=error)),
- }
- if error.request_id:
- updates["request_id"] = error.request_id
- return reason_kept.model_copy(update=updates)
-
-
-def _coded_refusal_problem(*, error: ApiResponseError, reading: _RefusalReading) -> PipelexProblem:
- """A refusal of the hosted plane as the core code it reads as, with what the plane said of it (:func:`hosted_refusal_problem`)."""
- problem = make_problem(code=reading.code, view=ProblemView.CALLER, retry_after=_sent_retry_after(error=error), request_id=error.request_id)
- if error.user_action is not None:
- step_detail = error.user_action.detail
- else:
- step_detail = reading.next_step or problem.next_step.detail
- return problem.model_copy(
- update={
- "status": error.status,
- "detail": error.server_message or problem.detail,
- "next_step": NextStep(kind=problem.next_step.kind, detail=step_detail),
- }
- )
-
-
-def tailored_next_step(*, error: PipelineRequestError) -> str | None:
- """The next step the human CLI tailors for a failure the client met, ``None`` when it gives the generic one.
-
- The agent CLI reports the problem the client decided for such a failure, whose step its code gives, and takes this
- one in its place where there is one, so both CLIs tell the same thing (:func:`describe_hosted_error`).
- """
- next_step = describe_hosted_error(error=error).next_step
- return None if next_step == HOSTED_RUN_REQUEST_NEXT_STEP else next_step
-
-
-class SentVerdict(NamedTuple):
- """The `error_domain` and `retryable` a hosted API's problem document carried, each `None` when it sent none."""
-
- error_domain: str | None
- retryable: bool | None
-
+def _answered_problem(*, error: ApiResponseError, credential_sent: bool) -> PipelexProblem:
+ """The problem of an answer the hosted API, or a server in front of it, gave: the body's own, or this client's reading.
-def sent_verdict(*, error: ApiResponseError) -> SentVerdict:
- """The verdict the hosted API sent with a refusal, read off the problem document it answered.
-
- pipelex-sdk gives every `ApiResponseError` a decided `error_domain` and `retryable`, filling a member the server
- did not send from its own table by status, which reads every unlabelled 5xx, a 503 included, as retryable. A 503
- does not say whether the run happened (see `_UNAVAILABLE_NEXT_STEP`), and who has to act is only the runner's to
- say, so both CLIs report what the server sent and nothing the SDK inferred. `problem_document` keeps the server's
- members as it sent them; `problem` is the standard's reading of the answer, which may be inferred from the status.
- """
- problem_document = error.problem_document or {}
- sent_domain = problem_document.get("error_domain")
- sent_retryable = problem_document.get("retryable")
- return SentVerdict(
- error_domain=sent_domain if isinstance(sent_domain, str) and sent_domain else None,
- retryable=sent_retryable if isinstance(sent_retryable, bool) else None,
- )
-
-
-class HostedErrorView(NamedTuple):
- """A hosted run's failure, as both CLIs tell it: the class to branch on, what happened, and what to do next.
-
- `error_domain` says who acts (`input`: the caller's request; `config`: the key, the base URL or the network;
- `runtime`: the run itself), as the hosted API said it when it did; `retryable` is the hosted API's own verdict,
- `None` when it gave none. `pipeline_run_id` names the run once the hosted API acknowledged it, so a run that failed,
- outlived the wait, was lost on the way or was left running by an interruption can be looked up.
- `validation_errors` are the hosted API's items locating the faults of a method it refused, each naming its file
- when the file was sent under a label.
+ A body that is a problem document is the runner's own problem, reported as it came (:func:`received_problem`),
+ with the request id the answer names. Any other body is the bare answer of the hosted edge, a gateway or a proxy,
+ which pipelex-sdk reads by its status alone: an answer that may have started a run keeps its reading as
+ `client.outcome_unknown`, and a status this client reads itself (:func:`_bare_answer_reading`) reads as that code,
+ with the next step that names this client's settings; any other keeps pipelex-sdk's reading.
"""
-
- error_type: str
- message: str
- next_step: str
- error_domain: str | None = None
- retryable: bool | None = None
- pipeline_run_id: str | None = None
- validation_errors: tuple[ValidationErrorItem, ...] = ()
-
-
-def hosted_refusal_next_step(*, error: ApiResponseError) -> str:
- """The next step of a refusal: the one the server advised, else the one its status calls for."""
- if error.user_action is not None:
- return error.user_action.detail
- by_status = HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS.get(error.status)
- if by_status is not None:
- return by_status
- if 400 <= error.status < 500:
- return HOSTED_REFUSAL_CALLER_NEXT_STEP
- return HOSTED_SERVER_FAULT_NEXT_STEP
-
-
-def hosted_refusal_message(*, error: ApiResponseError) -> str:
- """`API POST /v1/start failed (422): <reason>`, the error's own message without the next step it appends."""
- message = str(error)
- if error.user_action is not None:
- message = message.removesuffix(f"\nNext step: {error.user_action.detail}")
- return message
+ received = received_problem(problem=error.problem, request_id=error.request_id)
+ if read_problem_document(error.response_body, status=error.status, headers=error.headers or {}) is not None:
+ return received
+ match received.effective_retry:
+ case RetryVerdict.OUTCOME_UNKNOWN:
+ return received
+ case RetryVerdict.YES | RetryVerdict.NO:
+ pass
+ reading = _bare_answer_reading(status=error.status, credential_sent=credential_sent)
+ if reading is None:
+ return received
+ problem = make_problem(code=reading.code, view=ProblemView.CALLER, request_id=error.request_id)
+ return problem.model_copy(update={"status": error.status, "next_step": NextStep(kind=problem.next_step.kind, detail=reading.next_step)})
+
+
+def _upload_transport_next_step(*, reason: UploadTransportReason | None) -> str | None:
+ """The next step of an upload of an input's file that met a transport failure, ``None`` where its code's own fits."""
+ match reason:
+ case UploadTransportReason.TIMEOUT | UploadTransportReason.UNREACHABLE:
+ return HOSTED_UNREACHABLE_NEXT_STEP
+ case (
+ UploadTransportReason.SERVER_ERROR
+ | UploadTransportReason.STORAGE_TIMEOUT
+ | UploadTransportReason.CONFLICT
+ | UploadTransportReason.REDIRECTED
+ | UploadTransportReason.INVALID_GRANT_URL
+ | UploadTransportReason.UNEXPECTED
+ | None
+ ):
+ return None
-def _method_file_transfer_next_step(*, error: MethodFileTransferError) -> str:
- """The next step of a file of the method's tree that could not be moved, by why it failed (`error.code`).
+def _method_file_transfer_next_step(*, reason: MethodFileTransferReason) -> str:
+ """The next step of a file of the method's tree that could not be moved, by why it failed.
- Running again is the step for every code pipelex-sdk calls retryable, and a refusal is reported, since storage gives
- the same answer to the same upload; whether a retry can succeed is the SDK's own verdict, `error.retryable`.
+ Running again is the step for a reason pipelex-sdk reads as `runtime.unavailable`, which a later attempt can pass,
+ and the others are reported, since storage gives the same answer to the same upload.
"""
- match error.code:
- case MethodFileTransferCode.UNREACHABLE:
+ match reason:
+ case MethodFileTransferReason.UNREACHABLE:
return HOSTED_FILE_UNREACHABLE_NEXT_STEP
- case MethodFileTransferCode.STORAGE_ERROR:
+ case MethodFileTransferReason.STORAGE_ERROR:
return HOSTED_FILE_STORAGE_ERROR_NEXT_STEP
- case MethodFileTransferCode.MISMATCH:
+ case MethodFileTransferReason.MISMATCH:
return HOSTED_FILE_MISMATCH_NEXT_STEP
- case MethodFileTransferCode.REFUSED:
+ case MethodFileTransferReason.REFUSED:
return HOSTED_FILE_REFUSED_NEXT_STEP
-def describe_hosted_error(*, error: PipelineRequestError | HostedRunError) -> HostedErrorView:
- """Read a hosted run's failure off the error pipelex-sdk or pipelex raised.
-
- Args:
- error: The SDK's error, or one pipelex raised during the run. Its class decides the next step; an
- `ApiResponseError` names the runner's own class when the problem document carries one, and a failed run
- names its stored report's.
+def tailored_next_step(*, error: PipelineRequestError) -> str | None:
+ """The next step this client tailors for a failure it met on its own side, ``None`` where its code's own step fits.
- Returns:
- The class to report, the message, the next step, and the run and the validation items when there are any.
+ The step names this client's settings and the run it means, which the code's own step, written for every client,
+ cannot. An answer the hosted API gave is read apart (:func:`_answered_problem`), and a run that started and failed
+ keeps its code's step, which points at the run's own problem.
"""
- error_type = type(error).__name__
- message = str(error)
- next_step: str
- error_domain: str | None = None
- retryable: bool | None = None
- pipeline_run_id: str | None = None
- validation_errors: tuple[ValidationErrorItem, ...] = ()
match error:
- case HostedRunError():
- message = error.message
- next_step = error.user_action.detail if error.user_action is not None else HOSTED_RUN_REQUEST_NEXT_STEP
- # Who acts and whether a retry can succeed are the error's code's.
- hosted_code_spec = error_code_spec(error.resolve_error_code())
- error_domain = ErrorDomain.from_problem_domain(hosted_code_spec.domain)
- retryable = hosted_code_spec.invites_retry
- if isinstance(error, (HostedRunPollingError, HostedRunInterruptedError)):
- pipeline_run_id = error.pipeline_run_id
- if isinstance(error, HostedMethodInvalidError):
- validation_errors = tuple(error.validation_errors)
- case ApiResponseError():
- error_type = error.error_type or error_type
- message = hosted_refusal_message(error=error)
- next_step = hosted_refusal_next_step(error=error)
- error_domain, retryable = sent_verdict(error=error)
- validation_errors = tuple(error.validation_errors or ())
- case RunFailedError():
- report = error.error
- pipeline_run_id = error.run_id
- error_domain = ErrorDomain.RUNTIME
- if report is not None:
- error_type = report.error_type or error_type
- error_domain = report.error_domain or error_domain
- retryable = report.retryable
- validation_errors = tuple(report.validation_errors or ())
- if report is not None and report.user_action is not None and report.user_action.detail:
- next_step = report.user_action.detail
- else:
- next_step = f"The run {error.run_id} ended {error.status}: change what the message names, then run again"
case RunTimeoutError():
- pipeline_run_id = error.run_id
- error_domain = ErrorDomain.RUNTIME
- next_step = (
+ return (
f"The run {error.run_id} keeps running on the hosted API: find it on app.pipelex.com, or read its result "
"later with pipelex-sdk's PipelexAPIClient.wait_for_result"
)
case MissingMainStuffError():
- pipeline_run_id = error.run_id
- error_domain = ErrorDomain.RUNTIME
- next_step = (
+ return (
f"The run {error.run_id} completed, but the hosted API delivered no main output: look the run up by its id on "
"app.pipelex.com, and report it with the run id"
)
case PipelineExecuteTimeoutError():
# A hosted run calls the blocking route only on a server that keeps no runs (its version handshake says so,
# or its start refused for a missing run store), so running again takes the same route and repeats a paid run.
- error_domain = ErrorDomain.RUNTIME
- retryable = False
- next_step = (
+ return (
"The server at the base URL keeps no runs to poll, so the run went through the blocking route and the connection "
"was cut before the result came back. The run may still be going there, and running the command again runs the "
"method again on the same route: raise the timeout of the proxy in front of that server, or point --base-url or "
f"{PIPELEX_BASE_URL_ENV_KEY} at a server that keeps runs, such as {HOSTED_API_DEFAULT_BASE_URL}"
)
case ApiUnreachableError():
- error_domain = ErrorDomain.CONFIG
- next_step = HOSTED_UNREACHABLE_NEXT_STEP
+ # A request that may have started a run keeps its code's step, which reads the run rather than sends it again.
+ match error.problem.effective_retry:
+ case RetryVerdict.OUTCOME_UNKNOWN:
+ return None
+ case RetryVerdict.YES | RetryVerdict.NO:
+ return HOSTED_UNREACHABLE_NEXT_STEP
case RunLifecycleUnavailableError():
- error_domain = ErrorDomain.CONFIG
- next_step = f"The server at the base URL is a bare runner without run polling. {HOSTED_BASE_URL_NEXT_STEP}"
+ return f"The server at the base URL is a bare runner without run polling. {HOSTED_BASE_URL_NEXT_STEP}"
case UploadAuthenticationError():
- error_domain = ErrorDomain.CONFIG
- next_step = HOSTED_API_KEY_NEXT_STEP
+ return HOSTED_API_KEY_NEXT_STEP
case InvalidLocalSourceError():
- error_domain = ErrorDomain.INPUT
- next_step = "Check the file path in the inputs: a relative path in an inputs file resolves against that file's directory"
+ return "Check the file path in the inputs: a relative path in an inputs file resolves against that file's directory"
case RejectedAssetError():
- error_domain = ErrorDomain.INPUT
- next_step = "The hosted API refused the file: send a smaller one, or one of a type the input accepts"
+ return "The hosted API refused the file: send a smaller one, or one of a type the input accepts"
case UnsupportedUploadCapabilityError():
- error_domain = ErrorDomain.CONFIG
- next_step = f"The server at the base URL takes no uploads: pass the file as an http(s) URL. {HOSTED_BASE_URL_NEXT_STEP}"
+ return f"The server at the base URL takes no uploads: pass the file as an http(s) URL. {HOSTED_BASE_URL_NEXT_STEP}"
case UploadTransportError():
- # The SDK raises it for an upload that never reached the hosted API, chained from `ApiUnreachableError`,
- # and for one the hosted API failed on its side, a 5xx.
- if isinstance(error.__cause__, ApiUnreachableError):
- error_domain = ErrorDomain.CONFIG
- next_step = HOSTED_UNREACHABLE_NEXT_STEP
- else:
- error_domain = ErrorDomain.RUNTIME
- next_step = HOSTED_SERVER_FAULT_NEXT_STEP
+ return _upload_transport_next_step(reason=error.reason)
case InputPreparationError():
- error_domain = ErrorDomain.INPUT
- next_step = "Check the inputs against the pipe's signature (pipelex-agent inputs prints a template), then run again"
+ return "Check the inputs against the pipe's signature (pipelex-agent inputs prints a template), then run again"
case MethodFileTransferError():
- # A file of the method's tree, sent by hash, that could not be uploaded before pipe-io or the run: who acts and
- # whether a retry can succeed are the SDK's verdict.
- error_domain = error.error_domain
- retryable = error.retryable
- next_step = _method_file_transfer_next_step(error=error)
+ # A file of the method's tree, sent by hash, that could not be uploaded before pipe-io or the run.
+ return _method_file_transfer_next_step(reason=error.reason)
case _:
- next_step = HOSTED_RUN_REQUEST_NEXT_STEP
- return HostedErrorView(
- error_type=error_type,
- message=message,
- next_step=next_step,
- error_domain=error_domain,
- retryable=retryable,
- pipeline_run_id=pipeline_run_id,
- validation_errors=validation_errors,
- )
+ return None
+
+
+def _method_invalid_problem(*, error: HostedMethodInvalidError) -> PipelexProblem:
+ """The problem of a method pipe-io's verdict found does not load: `method.invalid`, listing the verdict's items as they came.
+
+ The runner answered its verdict to its caller already, so its items are reported as a runner's own problem is
+ (:func:`received_problem`): by the members the standard declares alone, since pipelex-sdk keeps those it does not
+ declare as it received them, and never projected onto a view again. A projection would read an item under a code
+ this client's registry does not hold, as a runner newer than the client answers, as one whose parameters it cannot
+ tell apart, and replace its sentence and its parameters with the generic sentence, losing the runner's explanation.
+ """
+ head = error.to_problem(view=ProblemView.CALLER)
+ verdict_items = [ProblemItem.model_validate(_declared_members(members=item.as_wire(), shape=ProblemItem)) for item in error.errors]
+ return head.model_copy(update={"errors": verdict_items or None})
+
+
+def hosted_failure_problem(*, error: PipelineRequestError | HostedRunError, credential_sent: bool) -> PipelexProblem:
+ """The problem of a run on a runner that failed, in the caller's view: the runner's, the client's, or pipelex's own.
+
+ - An answer the hosted API, or a server in front of it, gave is the runner's own problem document when its body is
+ one, and otherwise this client's reading of the bare answer (:func:`_answered_problem`).
+ - A run that started and failed is `run.failed`, naming the run and its status, and nests the run's own problem as
+ `run_error`, projected onto the caller's view (:func:`received_problem`).
+ - Every other failure the client met carries the problem it decided, such as `client.unreachable` naming the base
+ URL, with the next step this client tailors for it (:func:`tailored_next_step`) in place of its code's.
+ - A failure pipelex detects itself is its `HostedRunError`'s problem, naming the run the hosted API acknowledged
+ when there is one, and a method the hosted API found does not load lists the verdict's items as its `errors`,
+ as they came, by their declared members alone (:func:`_method_invalid_problem`).
+
+ Args:
+ error: The failure.
+ credential_sent: Whether the run's requests carried a key, which tells a refused key from a missing one.
+
+ Returns:
+ The problem, in the caller's view.
+ """
+ if isinstance(error, HostedRunPollingError | HostedRunInterruptedError):
+ return error.to_problem(view=ProblemView.CALLER, pipeline_run_id=error.pipeline_run_id)
+ if isinstance(error, HostedMethodInvalidError):
+ return _method_invalid_problem(error=error)
+ if isinstance(error, HostedRunError):
+ return error.to_problem(view=ProblemView.CALLER)
+ if isinstance(error, ApiResponseError):
+ return _answered_problem(error=error, credential_sent=credential_sent)
+ problem = received_problem(problem=error.problem)
+ tailored = tailored_next_step(error=error)
+ if tailored is None:
+ return problem
+ return problem.model_copy(update={"next_step": NextStep(kind=problem.next_step.kind, detail=tailored)})
+
+
+class HostedErrorView(NamedTuple):
+ """A hosted run's failure, as both CLIs tell it: its problem, the error's own sentence, and pipelex's own advice.
+
+ `problem` is in the caller's view (:func:`hosted_failure_problem`): its title and its detail, its next step, its
+ code with its domain and its retry verdict, the request and the run it names, the faults it lists as its `errors`,
+ and, for a run that started and failed, the run's own problem it nests as `run_error`. `message` is the error's own
+ sentence when it says what the problem does not, `None` when the problem says it all. `advice` is what pipelex's own
+ error advises, which a CLI prints as its tip and no problem carries.
+ """
+
+ problem: PipelexProblem
+ message: str | None
+ advice: str | None
+
+
+def describe_hosted_error(*, error: PipelineRequestError | HostedRunError, credential_sent: bool) -> HostedErrorView:
+ """Read a hosted run's failure off the error pipelex-sdk or pipelex raised, as both CLIs report it.
+
+ pipelex's own errors give their sentence and their advice. Every error of pipelex-sdk's own gives its sentence,
+ which says what its code's parameters cannot: the reason a run that failed stored, how long the client waited for
+ one that did not finish, that a completed run delivered no main output. An answer's refusal and a runner that
+ cannot be reached give none, their problem saying it all, where their sentence would quote a raw body or a
+ transport's class, and so does an error of the MTHDS client's.
+
+ Args:
+ error: The SDK's error, or one pipelex raised during the run.
+ credential_sent: Whether the run's requests carried a key, which tells a refused key from a missing one.
+
+ Returns:
+ The problem, the error's own sentence and pipelex's own advice.
+ """
+ problem = hosted_failure_problem(error=error, credential_sent=credential_sent)
+ message: str | None
+ advice: str | None
+ if isinstance(error, PipelexError):
+ message = error.message
+ advised_action = error.advised_action()
+ advice = advised_action.detail if advised_action is not None else None
+ elif isinstance(error, PipelexRequestError) and not isinstance(error, ApiResponseError | ApiUnreachableError):
+ message = str(error)
+ advice = None
+ else:
+ message = None
+ advice = None
+ return HostedErrorView(problem=problem, message=message, advice=advice)
diff --git a/pipelex/hosted/exceptions.py b/pipelex/hosted/exceptions.py
index f9165144f..a4bf3efb8 100644
--- a/pipelex/hosted/exceptions.py
+++ b/pipelex/hosted/exceptions.py
@@ -1,12 +1,13 @@
from typing import Any, ClassVar
+from mthds.protocol.problem.models import ProblemItem
from mthds.protocol.problem.registry import CoreCode
-from pipelex_sdk.validation_models import ValidationErrorItem
from typing_extensions import override
from pipelex.base_exceptions import PipelexError
from pipelex.cogt.inference.error_classification import UserAction, UserActionKind
from pipelex.errors.error_code_declaration import ABSTRACT_ERROR, ErrorCodeDeclaration, ErrorCodeSet
+from pipelex.errors.unsupported_reasons import LOCAL_FILE_WITH_ADDRESS_DEPENDENCY_UNSUPPORTED_REASON
class HostedRunError(PipelexError):
@@ -49,16 +50,21 @@ class HostedRunSourceError(HostedRunError):
class HostedMethodInvalidError(HostedRunError):
"""The hosted API read the method's signature before the run and found that the method does not load.
- Raised from `POST /v1/pipe-io`'s invalid verdict, before any run starts. Its `validation_errors` are the hosted
- API's items, each naming the file it found the fault in by its tree path in the tree the run sends.
+ Raised from `POST /v1/pipe-io`'s invalid verdict, before any run starts. Its `errors` are the verdict's problem
+ items, each locating a fault, its file by its tree path in the tree the run sends, and its problem lists them as its
+ own `errors`.
"""
error_code = CoreCode.METHOD_INVALID
- user_action = UserAction(kind=UserActionKind.CHANGE_INPUT, detail="Fix the method as each validation error says, then run it again")
+ user_action = UserAction(kind=UserActionKind.CHANGE_INPUT, detail="Fix the method as each of its errors says, then run it again")
- def __init__(self, message: str, *, validation_errors: list[ValidationErrorItem]):
+ def __init__(self, message: str, *, errors: list[ProblemItem]):
super().__init__(message)
- self.validation_errors = validation_errors
+ self.errors = errors
+
+ @override
+ def problem_items(self) -> list[ProblemItem] | None:
+ return list(self.errors) or None
class HostedRunPollingError(HostedRunError):
@@ -92,9 +98,10 @@ class HostedRunOutcomeUnknownError(HostedRunError):
The hosted API may have created the run before the connection failed, with no way to tell from here: its id never
arrived. Running the command again could start a second paid run, so the next step is the run history first. The
- cause is pipelex-sdk's `ApiUnreachableError` for the start or the execute request, which the SDK reads as one that
- may have started the run (`run_may_have_started`); its own cause is the transport failure, such as a read, a write,
- a protocol failure or a body that could not be decoded, which does not prove the request never left this machine.
+ cause is pipelex-sdk's `ApiUnreachableError` for the start or the execute request, whose problem the SDK states as
+ `client.outcome_unknown`, a request that may have started the run; its own cause is the transport failure, such as a
+ read, a write, a protocol failure or a body that could not be decoded, which does not prove the request never left
+ this machine.
"""
error_code = CoreCode.CLIENT_OUTCOME_UNKNOWN
@@ -157,3 +164,8 @@ class HostedLocalFileUploadUnavailableError(HostedRunError):
kind=UserActionKind.CHANGE_INPUT,
detail="Pass each local file as an https URL the hosted API can fetch, instead of a path on this machine, then run again",
)
+
+ @override
+ def problem_params(self) -> dict[str, Any]:
+ # The form refused is a local file in the inputs, for a method whose dependency is named by its address.
+ return {"field": "inputs", "reason": LOCAL_FILE_WITH_ADDRESS_DEPENDENCY_UNSUPPORTED_REASON}
diff --git a/pipelex/hosted/hosted_inputs.py b/pipelex/hosted/hosted_inputs.py
index dd66e3f6e..ab013b5dd 100644
--- a/pipelex/hosted/hosted_inputs.py
+++ b/pipelex/hosted/hosted_inputs.py
@@ -40,15 +40,10 @@ from mthds.protocol.problem.registry import CoreCode, MethodDependencyMissingKin
from pipelex_sdk.client import PipelexAPIClient
from pipelex_sdk.crate_models import CrateInvalidReport, PipeIORequest
from pipelex_sdk.upload import UploadRecord
-from pipelex_sdk.validation_models import ValidationErrorItem
-from pydantic import ValidationError
-from pipelex.core.pipes.exceptions import pipe_validation_error_code
-from pipelex.core.qualified_ref import QualifiedRef
from pipelex.hosted.exceptions import HostedLocalFileUploadUnavailableError, HostedMethodInvalidError
from pipelex.tools.uri.resolved_uri import ResolvedLocalPath
from pipelex.tools.uri.uri_resolver import resolve_uri
-from pipelex.validation_error_types import PipeValidationErrorType
#: An `http(s)://` URL, which the hosted API fetches itself. Matched as the SDK matches it, whatever the case of the
#: scheme.
@@ -272,25 +267,12 @@ def _unshipped_dependency_refusal(*, report: CrateInvalidReport) -> HostedLocalF
def _missing_package(*, report: CrateInvalidReport) -> str | None:
"""The address of the first method package pipe-io's invalid verdict names as missing, else `None`.
- A runner speaking the standard answers the verdict's items as `errors`, read from the members the SDK's model does
- not name, and a `method.dependency_missing` item of the `kind` `package` and the `reason` `not_found` names the
- package in `params.name`; a package found in a cycle or in no matching version is the method's own fault. A runner
- answering the shape that predates the standard sends `validation_errors` alone, whose items carry no code: each is
- read by the code the runner gives the same item in its problem's `errors`, its type's (`pipe_validation_error_code`),
- and the package it names, the alias of the reference it could not resolve. An item this client cannot read is
- skipped, so it never takes the verdict's place, and when no item of `errors` names a package, `validation_errors`
- is read too.
+ The verdict's items are its `errors`, and a `method.dependency_missing` item of the `kind` `package` and the
+ `reason` `not_found` names the package in `params.name`; a package found in a cycle or in no matching version is the
+ method's own fault. The SDK reads each item member by member, skipping one it cannot read, so an item never takes
+ the verdict's place.
"""
- raw_errors = (report.model_extra or {}).get("errors")
- if isinstance(raw_errors, list):
- for raw_item in cast("list[Any]", raw_errors):
- try:
- item = ProblemItem.model_validate(raw_item)
- except ValidationError:
- continue
- if (package := _missing_package_of_problem_item(item=item)) is not None:
- return package
- return next((package for item in report.validation_errors if (package := _missing_package_of_validation_item(item=item)) is not None), None)
+ return next((package for item in report.errors if (package := _missing_package_of_problem_item(item=item)) is not None), None)
def _missing_package_of_problem_item(*, item: ProblemItem) -> str | None:
@@ -308,19 +290,6 @@ def _missing_package_of_problem_item(*, item: ProblemItem) -> str | None:
return name
-def _missing_package_of_validation_item(*, item: ValidationErrorItem) -> str | None:
- """The address of the method package a validation item the runner codes `method.dependency_missing` names, else `None`."""
- if item.error_type is None or not item.missing_pipe_code:
- return None
- try:
- error_type = PipeValidationErrorType(item.error_type)
- except ValueError:
- return None
- if pipe_validation_error_code(error_type=error_type) != CoreCode.METHOD_DEPENDENCY_MISSING:
- return None
- return QualifiedRef.package_named_by(raw=item.missing_pipe_code)
-
-
async def prepare_hosted_inputs(
*,
client: PipelexAPIClient,
@@ -343,7 +312,7 @@ async def prepare_hosted_inputs(
Raises:
HostedLocalFileUploadUnavailableError: If pipe-io's verdict refuses the method because it calls another method
by its address, which nothing shipped: the run route would fetch it, so the file has to reach it as a URL.
- HostedMethodInvalidError: If the method does not load, with the hosted API's validation items.
+ HostedMethodInvalidError: If the method does not load, with the verdict's problem items.
ApiResponseError: If the hosted API refuses the pipe-io request (an unknown method, a key it refuses).
InputPreparationError: If an upload fails, or a local file cannot be read.
MethodFileTransferError: If a file of the method's tree the hosted API lacks could not be uploaded.
@@ -358,7 +327,7 @@ async def prepare_hosted_inputs(
if (unshipped_dependency_refusal := _unshipped_dependency_refusal(report=report)) is not None:
raise unshipped_dependency_refusal
msg = f"The hosted API cannot load the method: {report.message}"
- raise HostedMethodInvalidError(msg, validation_errors=report.validation_errors)
+ raise HostedMethodInvalidError(msg, errors=report.errors)
selected_pipe_ref = report.pipe_ref
descriptor = report.input_form.get(selected_pipe_ref) if selected_pipe_ref is not None else None
if descriptor is None:
diff --git a/pipelex/hosted/hosted_run.py b/pipelex/hosted/hosted_run.py
index f0b554670..f0d6b9e93 100644
--- a/pipelex/hosted/hosted_run.py
+++ b/pipelex/hosted/hosted_run.py
@@ -21,6 +21,7 @@ from typing import Any, Protocol, Self
import httpx
from mthds.protocol.exceptions import PipelineRequestError
+from mthds.protocol.problem.registry import RetryVerdict
from pipelex_sdk.client import PipelexAPIClient
from pipelex_sdk.errors import ApiUnreachableError, MissingMainStuffError, RunFailedError, RunLifecycleUnavailableError, RunTimeoutError
from pipelex_sdk.execute_result import results_from_execute
@@ -134,18 +135,22 @@ async def _start_or_execute(*, client: PipelexAPIClient, request: HostedRunReque
A start the server refuses for a missing run store created no run, so running the blocking route next cannot run
the method twice.
- The SDK raises `ApiUnreachableError` for every transport failure, chained from httpx's error, and decides whether
- a run may have started (`run_may_have_started`): only on the start or the execute request itself, and only when the
- failure does not prove the request never left this machine. A failure it reads as starting nothing stays the SDK's
- error: the version handshake, the blob requests of a tree sent by hash, or a connection that was never made. Any
- other one, a connection lost or a read timed out once the run request may have left, is a
- `HostedRunOutcomeUnknownError`: the hosted API may have created the run, and its id never arrived.
+ The SDK raises `ApiUnreachableError` for every transport failure, chained from httpx's error, and states whether
+ a run may have started as its problem's retry verdict, `outcome_unknown` (`client.outcome_unknown`): only on the
+ start or the execute request itself, and only when the failure does not prove the request never left this machine.
+ A failure it reads as starting nothing stays the SDK's error: the version handshake, the blob requests of a tree
+ sent by hash, or a connection that was never made. Any other one, a connection lost or a read timed out once the run
+ request may have left, is a `HostedRunOutcomeUnknownError`: the hosted API may have created the run, and its id
+ never arrived.
"""
try:
return await _start_or_execute_unmapped(client=client, request=request, inputs=inputs)
except ApiUnreachableError as exc:
- if not exc.run_may_have_started:
- raise
+ match exc.problem.effective_retry:
+ case RetryVerdict.OUTCOME_UNKNOWN:
+ pass
+ case RetryVerdict.YES | RetryVerdict.NO:
+ raise
transport_error = exc.__cause__
failure = f"{type(transport_error).__name__}: {transport_error}" if transport_error is not None else str(exc)
msg = f"The connection to the hosted API at {client.base_url} failed on the run request, which the hosted API may have received ({failure})"
@@ -190,7 +195,7 @@ async def run_hosted(*, client: PipelexAPIClient, request: HostedRunRequest, on_
address, which the signature read cannot load.
HostedMethodInvalidError: If the hosted API reads the method's signature and the method does not load.
ApiResponseError: If the hosted API refuses the request: a key it does not accept, a method it cannot load
- (its `validation_errors` locate the fault), an input it rejects.
+ (its problem's `errors` locate the faults), an input it rejects.
RunFailedError: If the run started and ended in a status other than completed.
RunTimeoutError: If the run outlived the wait; it keeps running, and its id resumes it.
MissingMainStuffError: If the run completed and delivered no main output.
diff --git a/pyproject.toml b/pyproject.toml
index 29da916ce..f34989f77 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -44,7 +44,7 @@ dependencies = [
# The client for the hosted Pipelex API, behind hosted runs (pipelex/hosted/). Pinned exactly, like
# mthds: each pipelex-sdk release pins mthds exactly too, so the release chosen here must pin the
# same mthds as this file, and the two pins move together (the bump-mthds skill says so).
- "pipelex-sdk==0.48.0",
+ "pipelex-sdk==0.53.0",
"polyfactory>=2.21.0",
"portkey-ai>=2.1.0",
"posthog>=6.7.0",
diff --git a/tests/unit/pipelex/cli/agent_cli/test_data.py b/tests/unit/pipelex/cli/agent_cli/test_data.py
index 248f11495..d6c4e0faf 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_data.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_data.py
@@ -186,120 +186,6 @@ class UndeclaredMembers:
}
-class HostedPlaneRefusals:
- """Refusals the hosted plane answers in its own shape, which predates the standard's problem document."""
-
- UNAUTHORIZED: ClassVar[str] = json.dumps(
- {
- "type": "https://pipelex.com/errors/unauthorized",
- "title": "Unauthorized",
- "status": 401,
- "code": "unauthorized",
- "detail": "The API key is not valid.",
- "instance": "urn:pipelex:request:01M55PLEGACY401000000000000",
- "request_id": "01M55PLEGACY401000000000000",
- "error_domain": "config",
- "retryable": False,
- }
- )
- FORBIDDEN: ClassVar[str] = json.dumps(
- {
- "type": "https://pipelex.com/errors/role_not_permitted",
- "title": "Forbidden",
- "status": 403,
- "code": "role_not_permitted",
- "detail": "Your role in this organization does not allow running methods.",
- "request_id": "01M55PLEGACY403000000000000",
- "error_domain": "input",
- "retryable": False,
- }
- )
- # The platform's generic refusal of an operation to a key it authenticated, which is no matter of role.
- FORBIDDEN_OPERATION: ClassVar[str] = json.dumps(
- {
- "type": "https://pipelex.com/errors/forbidden",
- "title": "Forbidden",
- "status": 403,
- "code": "forbidden",
- "detail": "This route is served to a web session only.",
- "error_domain": "config",
- "retryable": False,
- }
- )
- # A 403 whose code is no refusal of an operation but of the credential, as a key that expired.
- FORBIDDEN_EXPIRED_KEY: ClassVar[str] = json.dumps(
- {
- "type": "https://pipelex.com/errors/api_key_expired",
- "title": "Forbidden",
- "status": 403,
- "code": "api_key_expired",
- "detail": "The API key has expired.",
- "error_domain": "config",
- "retryable": False,
- }
- )
- NOT_FOUND: ClassVar[str] = json.dumps(
- {
- "type": "https://pipelex.com/errors/not_found",
- "title": "Not found",
- "status": 404,
- "code": "not_found",
- "detail": "No route serves POST /v1/execute.",
- "error_domain": "config",
- "retryable": False,
- }
- )
- RATE_LIMITED: ClassVar[str] = json.dumps(
- {
- "type": "https://pipelex.com/errors/rate_limited",
- "title": "Too many requests",
- "status": 429,
- "code": "rate_limited",
- "detail": "Too many runs started in the last minute.",
- "request_id": "01M55PLEGACY429000000000000",
- "error_domain": "runtime",
- "retryable": True,
- }
- )
- # A run the platform knows no run by, which names the run it means by its own code.
- RUN_NOT_FOUND: ClassVar[str] = json.dumps(
- {
- "type": "https://pipelex.com/errors/run_not_found",
- "title": "Not found",
- "status": 404,
- "code": "run_not_found",
- "detail": "No run run_9 is visible to this key.",
- "error_domain": "input",
- "retryable": False,
- }
- )
- # A method version the method never published, which names the method by its own code.
- METHOD_VERSION_NOT_FOUND: ClassVar[str] = json.dumps(
- {
- "type": "https://pipelex.com/errors/method_version_not_found",
- "title": "Not found",
- "status": 404,
- "code": "method_version_not_found",
- "detail": "The method mt_7 has no published version 3.",
- "error_domain": "input",
- "retryable": False,
- }
- )
- # A rate limit whose delay rides the body alone, with no `Retry-After` header.
- RATE_LIMITED_BODY_DELAY: ClassVar[str] = json.dumps(
- {
- "type": "https://pipelex.com/errors/rate_limited",
- "title": "Too many requests",
- "status": 429,
- "code": "rate_limited",
- "detail": "Too many runs started in the last minute.",
- "retry_after_seconds": 12,
- "error_domain": "runtime",
- "retryable": True,
- }
- )
-
-
class GatewayAnswers:
"""Answers that are no problem document, which a gateway or a hosted plane in front of the runner may give."""
@@ -309,45 +195,10 @@ class GatewayAnswers:
NOT_FOUND: ClassVar[str] = '{"detail":"Not Found"}'
# A gateway's refusal of a request its authorizer did not let through.
FORBIDDEN: ClassVar[str] = '{"message":"Forbidden"}'
-
-
-class RunnerOwnRefusals:
- """Refusals a runner authors itself rather than raising a Pipelex error for, in the shape that predates the standard's."""
-
- # The runner's 422 for a run request carrying a reserved object key, as `raise_validation_error` answers it: a
- # reason, but no code, domain, retry verdict or next step the standard's client reads.
- RESERVED_OBJECT_KEY: ClassVar[str] = json.dumps(
- {
- "type": "https://docs.pipelex.com/latest/errors/reserved-object-key/",
- "title": "Reserved object key",
- "status": 422,
- "detail": (
- "Request body contains the reserved object key '__class__'. A run request is plain JSON: no object in it may "
- "carry a '__class__' or '__module__' key, or a key starting with '__kajson'."
- ),
- "instance": "urn:pipelex:request:01M55PRESERVED00000000000",
- "request_id": "01M55PRESERVED00000000000",
- "error_type": "ReservedObjectKey",
- "error_domain": "input",
- "retryable": False,
- }
- )
- # The reason and the advice of a refusal whose advice names a kind of its own.
- NO_CREDIT_REASON: ClassVar[str] = "The account has no inference credit left."
- NO_CREDIT_ADVICE: ClassVar[str] = "Add credit to the account on app.pipelex.com, then run again"
- # A 402 advising the caller to check its billing: a reason and an advice of the kind `check_billing`, but no code,
- # domain, retry verdict or next step the standard's client reads.
- NO_CREDIT: ClassVar[str] = json.dumps(
- {
- "type": "https://docs.pipelex.com/latest/errors/payment-required/",
- "title": "Payment required",
- "status": 402,
- "detail": NO_CREDIT_REASON,
- "error_domain": "config",
- "retryable": False,
- "user_action": {"kind": "check_billing", "detail": NO_CREDIT_ADVICE},
- }
- )
+ # A gateway's refusal of a request that carried no credential it reads.
+ UNAUTHORIZED: ClassVar[str] = '{"message":"Unauthorized"}'
+ # A gateway's throttle.
+ TOO_MANY_REQUESTS: ClassVar[str] = '{"message":"Too Many Requests"}'
class RetiredEnvelope:
@@ -372,44 +223,8 @@ class RetiredEnvelope:
class StoredRunReports:
- """Reports the hosted API may store for a failed run, as `RunFailedError.error` hands them back."""
-
- # The report in the shape the hosted plane wrote before it stored problem documents.
- FORMER_SHAPE: ClassVar[dict[str, Any]] = {
- "error_type": "LLMCompletionError",
- "message": "The provider refused the prompt",
- "error_domain": "runtime",
- "error_category": "transient",
- "retryable": True,
- "model": "claude-5.5-sonnet",
- "user_action": {"kind": "wait_and_retry", "detail": "Run it again in a minute"},
- }
- # A report in the former shape for a run whose method did not validate, with the items and the advice it gives.
- FORMER_SHAPE_WITH_ITEMS: ClassVar[dict[str, Any]] = {
- "error_type": "ValidateBundleError",
- "message": "The method does not validate: pipe 'draft' names an unknown model",
- "title": "Validate bundle error",
- "type_uri": "https://docs.pipelex.com/latest/errors/validate-bundle-error/",
- "error_domain": "input",
- "error_category": "configuration",
- "retryable": False,
- "caller_facing_message": True,
- "user_action": {"kind": "change_model", "detail": "Name a model the catalog knows, such as gpt-5.5, then run again"},
- "validation_errors": [
- {
- "category": "pipe_validation",
- "message": "Pipe 'draft' (PipeLLM), field 'model': Model handle 'gpt-5.1' was not found in the model deck",
- "error_type": "unknown_model",
- "pipe_code": "draft",
- "field_name": "model",
- "model_reference": "gpt-5.1",
- "model_type": "llm",
- "suggestions": ["gpt-5.5"],
- "source": "main.mthds",
- "pipe_type": "PipeLLM",
- }
- ],
- }
+ """The run's own problem the hosted API may store for a failed run, which `run.failed` nests as its `run_error`."""
+
# The run's own problem, as a runner that speaks the problem document stores it, in the operator's view.
PROBLEM: ClassVar[dict[str, Any]] = {
"type": "https://mthds.ai/errors/pipe.output_multiplicity",
@@ -437,102 +252,67 @@ class StoredRunReports:
"provider_metadata": {"region": "eu"},
"validation_errors": [{"category": "pipe_validation", "message": "multiplicity"}],
}
+ # A run refused at load, its stored problem listing the method's faults as its items, in the operator's view.
+ PROBLEM_WITH_ITEMS: ClassVar[dict[str, Any]] = {
+ "type": "https://mthds.ai/errors/method.invalid",
+ "title": "The method does not validate",
+ "detail": "The method does not validate.",
+ "code": "method.invalid",
+ "domain": "method",
+ "retry": "no",
+ "next_step": {"kind": "change_method", "detail": "Fix each fault the problem's errors list, then validate the method again."},
+ "errors": [
+ {
+ "code": "model.unknown",
+ "detail": "The method names the llm model 'claude-5.5-sonnet', which no catalog knows.",
+ "params": {"model": "claude-5.5-sonnet", "model_type": "llm"},
+ "location": {"pipe": "draft", "field": "model", "file": "main.mthds"},
+ }
+ ],
+ "diagnostics": {"error_class": "ValidateBundleError", "message": "the bundle does not load"},
+ }
-class HostedMethodItems:
- """The items of `POST /v1/pipe-io`'s verdict that a method does not load, and the problem items the agent CLI reports."""
+class PipeIoItems:
+ """The items of a pipe-io verdict for a method that does not load, as sent and as both CLIs report them.
+
+ pipelex-sdk reads each item member by member: a declared member that does not read is left out of its item alone,
+ so the item keeps its code, its locators and its other facts, and a member the standard does not declare is kept
+ as received, which the CLIs leave out, reporting each item by its declared members.
+ """
SENT: ClassVar[list[dict[str, Any]]] = [
- # An item no stage classified: its message is the finding of `method.schema_violation`.
- {"category": "blueprint_validation", "message": "unknown concept Foo", "source": "lib/b.mthds", "pipe_code": "step2"},
- # An item of a type this version reads, with the locators the model check gives it.
- {
- "category": "pipe_validation",
- "message": "Pipe 'draft' (PipeLLM), field 'model': Model handle 'gpt-5.1' was not found in the model deck",
- "error_type": "unknown_model",
- "pipe_code": "draft",
- "field_name": "model",
- "model_reference": "gpt-5.1",
- "model_type": "llm",
- "suggestions": ["gpt-5.5"],
- "source": "main.mthds",
- },
- # An item of a newer runner, whose type this version does not read.
- {"category": "pipe_validation", "message": "A kind of fault from a newer runner", "error_type": "some_future_fault", "pipe_code": "step3"},
- ]
- # An item of a type this version reads, carrying a field neither this version nor the SDK declares.
- SENT_WITH_AN_UNKNOWN_FIELD: ClassVar[dict[str, Any]] = {**SENT[1], "pipe_type": "PipeLLM"}
- # A missing dependency of a newer runner, whose fix carries a member the SDK reads and this version does not.
- SENT_WITH_AN_UNREADABLE_FIX: ClassVar[dict[str, Any]] = {
- "category": "pipe_validation",
- "message": "In-memory resolve cannot load address-based dependency 'github.com/mthds/scoring-lib/scoring'.",
- "error_type": "unresolved_package_dependency",
- "pipe_code": "score_invoice",
- "source": "bundle.mthds",
- "field_path": "pipe.score_invoice.steps[0].pipe",
- "missing_pipe_code": "github.com/mthds/scoring-lib/scoring->scoring.score",
- "suggested_fix": {
- "fix_code": "ship-dependency",
- "description": "Ship the dependency with the method",
- "safety": "unsafe",
- "ops": [{"kind": "set_key", "table_path": ["pipe", "score_invoice"], "key": "note", "value": "shipped"}],
- "preview": "A member a newer runner adds to its fixes",
- },
- }
- # Its problem item: the missing dependency its type and its locators give, without the fix this version cannot read.
- UNREADABLE_FIX_PROBLEM_ITEM: ClassVar[dict[str, Any]] = {
- "code": "method.dependency_missing",
- "detail": "The method depends on the package 'github.com/mthds/scoring-lib/scoring', which is not available here (reason: not_found).",
- "params": {"kind": "package", "name": "github.com/mthds/scoring-lib/scoring", "reason": "not_found"},
- "location": {"pipe": "score_invoice", "field": "pipe.score_invoice.steps[0].pipe", "file": "bundle.mthds"},
- }
- PROBLEM_ITEMS: ClassVar[list[dict[str, Any]]] = [
- {
- "code": "method.schema_violation",
- "detail": "The declaration at 'pipe.step2' breaks a rule of the language (unknown concept Foo).",
- "params": {"field_path": "pipe.step2", "finding": "unknown concept Foo"},
- "location": {"pipe": "step2", "file": "lib/b.mthds"},
- },
{
"code": "model.unknown",
"detail": "The method names the llm model 'gpt-5.1', which no catalog knows.",
- "params": {"model": "gpt-5.1", "model_type": "llm", "suggestions": ["gpt-5.5"]},
+ "params": {"model": "gpt-5.1", "model_type": "llm"},
"location": {"pipe": "draft", "field": "model", "file": "main.mthds"},
"suggestions": ["gpt-5.5"],
},
{
- "code": "method.schema_violation",
- "detail": "The declaration at 'pipe.step3' breaks a rule of the language (A kind of fault from a newer runner).",
- "params": {"field_path": "pipe.step3", "finding": "A kind of fault from a newer runner"},
- "location": {"pipe": "step3"},
+ "code": "method.concept_unresolved",
+ "detail": "Pipe 'summarize' names the concept 'Summary', which no domain defines.",
+ "location": {"pipe": "summarize", "field": "output", "file": "lib/summarize.mthds"},
+ "suggested_fix": "define the concept",
+ "rank": 2,
},
]
-
-
-class RunnerOwnMethodRefusals:
- """A runner's refusal of a run request whose method does not validate, in the shape that predates the standard's."""
-
- # The reason and the advice the refusal gives.
- REASON: ClassVar[str] = "The method does not validate: pipe 'draft' names an unknown model"
- ADVICE: ClassVar[str] = "Name a model the catalog knows, such as gpt-5.5, then run again"
- # The 422 a runner answers `POST /v1/start` and `POST /v1/execute` with for a method that does not load, as
- # `ValidateBundleError` answers it in the former shape: its reason, its advice and the validation items locating the
- # faults, but no code, domain, retry verdict or next step the standard's client reads.
- INVALID_METHOD: ClassVar[str] = json.dumps(
+ REPORTED: ClassVar[list[dict[str, Any]]] = [
+ SENT[0],
{
- "type": "https://docs.pipelex.com/latest/errors/validate-bundle-error/",
- "title": "Validate bundle error",
- "status": 422,
- "detail": REASON,
- "instance": "urn:pipelex:request:01M55PINVALIDMETHOD000000",
- "request_id": "01M55PINVALIDMETHOD000000",
- "error_type": "ValidateBundleError",
- "error_domain": "input",
- "retryable": False,
- "user_action": {"kind": "change_model", "detail": ADVICE},
- "validation_errors": HostedMethodItems.SENT[:2],
- }
- )
+ "code": "method.concept_unresolved",
+ "detail": "Pipe 'summarize' names the concept 'Summary', which no domain defines.",
+ "location": {"pipe": "summarize", "field": "output", "file": "lib/summarize.mthds"},
+ },
+ ]
+ # An item under a code this client's registry does not hold, as a hosted API newer than the client may answer: the
+ # runner's own sentence and parameters are all the client has to tell the fault by.
+ NEWER_CODE: ClassVar[dict[str, Any]] = {
+ "code": "method.construct_unsupported_here",
+ "detail": "Pipe 'summarize' uses the construct 'streamed_output', which this method's runtime introduced.",
+ "params": {"construct": "streamed_output"},
+ "location": {"pipe": "summarize", "file": "main.mthds"},
+ }
class RefusedBundles:
diff --git a/tests/unit/pipelex/cli/agent_cli/test_run_hosted_envelope.py b/tests/unit/pipelex/cli/agent_cli/test_run_hosted_envelope.py
index b3f3873ae..0a0e912ea 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_run_hosted_envelope.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_run_hosted_envelope.py
@@ -12,40 +12,45 @@ from typing import TYPE_CHECKING, Any
import pytest
import typer
-from mthds.protocol.problem.client_problems import make_client_problem
from mthds.protocol.problem.models import Problem
from mthds.protocol.problem.registry import CoreCode
-from pipelex_sdk.error_models import RunErrorReport
from pipelex_sdk.errors import (
- ApiResponseError,
InvalidLocalSourceError,
- MethodFileTransferCode,
MethodFileTransferError,
MethodFileTransferOperation,
+ MethodFileTransferReason,
MissingMainStuffError,
PipelexRequestError,
PipelineExecuteTimeoutError,
RunFailedError,
RunTimeoutError,
UnsupportedUploadCapabilityError,
+ run_failed_problem,
)
+from pipelex_sdk.problem_items import read_problem_items
from pipelex_sdk.runs import RunResults, RunStatus
from pipelex_sdk.upload import UploadRecord
-from pipelex_sdk.validation_models import ValidationErrorItem
from pydantic import ValidationError
from pipelex.base_exceptions import PipelexConfigError
from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat
from pipelex.cli.agent_cli.commands.run.bundle_cmd import run_bundle_cmd
from pipelex.cli.agent_cli.commands.run.method_cmd import run_method_cmd
-from pipelex.errors.problem import ProblemView, make_problem
+from pipelex.errors.problem import UNKNOWN_CODE_ITEM_DETAIL, ProblemView, make_problem
from pipelex.hosted.client_factory import PIPELEX_API_KEY_ENV_KEY, PIPELEX_BASE_URL_ENV_KEY
-from pipelex.hosted.error_rendering import HOSTED_REFUSAL_CALLER_NEXT_STEP, describe_hosted_error
+from pipelex.hosted.error_rendering import (
+ HOSTED_FILE_MISMATCH_NEXT_STEP,
+ HOSTED_FILE_REFUSED_NEXT_STEP,
+ HOSTED_FILE_STORAGE_ERROR_NEXT_STEP,
+ HOSTED_FILE_UNREACHABLE_NEXT_STEP,
+ describe_hosted_error,
+ tailored_next_step,
+)
from pipelex.hosted.exceptions import HostedMethodInvalidError, HostedRunPollingError
from pipelex.hosted.hosted_run import HostedRunOutcome, HostedRunRequest
from pipelex.hosted.run_config import RunExecution
from pipelex.system.environment import PIPELEXPATH_ENV_KEY
-from tests.unit.pipelex.cli.agent_cli.test_data import HostedMethodItems, RetiredEnvelope, StoredRunReports
+from tests.unit.pipelex.cli.agent_cli.test_data import PipeIoItems, RetiredEnvelope, StoredRunReports
if TYPE_CHECKING:
from pathlib import Path
@@ -57,8 +62,6 @@ AGENT_RUN_HOSTED_MODULE = "pipelex.cli.agent_cli.commands.run._run_hosted"
EXECUTION_MODULE = "pipelex.hosted.execution"
METHOD_REF = "github.com/Pipelex/methods/[email protected]"
STATS: dict[str, Any] = {"words": 4, "sentences": 2}
-#: The reason a runner gave for refusing a run, in a body that predates the standard's problem document.
-CONFLICT_REASON = "The run conflicts with another"
HOSTED_RESULTS: dict[str, Any] = {
"pipeline_run_id": "run_7",
"main_stuff": STATS,
@@ -126,13 +129,14 @@ class TestRunHostedEnvelope:
def test_a_failed_run_is_run_failed_naming_the_run(
self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], error_format: CliOutputFormat
) -> None:
- """A run that started and failed is the client's `run.failed`, naming the run and its status, with its stored reason;
- a report in the former shape names no code, so the run's own problem is `runtime.unexpected` carrying its reason,
- its advice and its retry verdict, as the human CLI tells them.
+ """A run that started and failed is the client's `run.failed`, naming the run and its status, with the client's
+ sentence as its `message`; a run that stored no problem of its own nests none.
"""
- report = RunErrorReport.model_validate(StoredRunReports.FORMER_SHAPE)
failed = RunFailedError(
- "Run finished with status FAILED: The provider refused the prompt", run_id="run_9", status=RunStatus.FAILED, error=report
+ "Run finished with status FAILED: The provider refused the prompt",
+ run_id="run_9",
+ status=RunStatus.FAILED,
+ problem=run_failed_problem(run_id="run_9", status=RunStatus.FAILED),
)
mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=failed))
@@ -144,72 +148,53 @@ class TestRunHostedEnvelope:
match error_format:
case CliOutputFormat.JSON:
problem = json.loads(printed)
- assert problem == {
- **failed.problem.as_wire(),
- "message": "Run finished with status FAILED: The provider refused the prompt",
- "run_error": {
- "type": "https://mthds.ai/errors/runtime.unexpected",
- "title": "An unexpected error occurred",
- "detail": "The provider refused the prompt",
- "code": "runtime.unexpected",
- "domain": "runtime",
- "retry": "yes",
- "next_step": {"kind": "wait", "detail": "Run it again in a minute"},
- },
- }
+ assert problem == {**failed.problem.as_wire(), "message": "Run finished with status FAILED: The provider refused the prompt"}
assert problem["code"] == "run.failed"
assert problem["params"] == {"pipeline_run_id": "run_9", "run_status": "FAILED"}
assert problem["pipeline_run_id"] == "run_9"
for retired in RetiredEnvelope.MEMBERS:
assert retired not in problem
- assert retired not in problem["run_error"]
case CliOutputFormat.MARKDOWN:
assert printed.startswith(f"## {failed.problem.title}\n")
assert "Run finished with status FAILED: The provider refused the prompt" in printed
assert "- Run: `run_9`" in printed
- assert "**Next step** (`wait`): Run it again in a minute" in printed
- assert "LLMCompletionError" not in printed
- assert "claude-5.5-sonnet" not in printed
+ assert f"**Next step** (`read_run`): {failed.problem.next_step.detail}" in printed
+ assert "### The run's own problem" not in printed
@pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])
- def test_a_failed_run_s_former_report_gives_its_items_and_its_advice(
+ def test_a_failed_run_s_own_problem_gives_its_items(
self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], error_format: CliOutputFormat
) -> None:
- """A report in the former shape listing validation items is the run's `method.invalid`, its items coded as a local
- verdict codes them and its advice as the next step, so the agent CLI tells what the human CLI tells of the same run.
+ """A run's own problem listing the method's faults rides as `run_error` with its items, in the caller's view, so
+ the agent CLI tells what the human CLI tells of the same run.
"""
- report = RunErrorReport.model_validate(StoredRunReports.FORMER_SHAPE_WITH_ITEMS)
- failed = RunFailedError(f"Run finished with status FAILED: {report.message}", run_id="run_9", status=RunStatus.FAILED, error=report)
+ stored = Problem.model_validate(StoredRunReports.PROBLEM_WITH_ITEMS)
+ failed = RunFailedError(
+ "Run finished with status FAILED",
+ run_id="run_9",
+ status=RunStatus.FAILED,
+ problem=run_failed_problem(run_id="run_9", status=RunStatus.FAILED, run_error=stored),
+ )
mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=failed))
with pytest.raises(typer.Exit):
run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=error_format)
printed = capsys.readouterr().err
- human_view = describe_hosted_error(error=failed)
- advice = StoredRunReports.FORMER_SHAPE_WITH_ITEMS["user_action"]["detail"]
- assert human_view.next_step == advice
+ human_view = describe_hosted_error(error=failed, credential_sent=True)
+ assert human_view.problem.run_error is not None
+ assert [item.as_wire() for item in human_view.problem.run_error.errors or []] == StoredRunReports.PROBLEM_WITH_ITEMS["errors"]
+ item = StoredRunReports.PROBLEM_WITH_ITEMS["errors"][0]
match error_format:
case CliOutputFormat.JSON:
problem = json.loads(printed)
assert problem["code"] == "run.failed"
- assert problem["run_error"] == {
- "type": "https://mthds.ai/errors/method.invalid",
- "title": "The method does not validate",
- "detail": StoredRunReports.FORMER_SHAPE_WITH_ITEMS["message"],
- "code": "method.invalid",
- "domain": "method",
- "retry": "no",
- "next_step": {"kind": "change_model", "detail": advice},
- "errors": [HostedMethodItems.PROBLEM_ITEMS[1]],
- }
+ assert problem["run_error"] == {name: value for name, value in StoredRunReports.PROBLEM_WITH_ITEMS.items() if name != "diagnostics"}
for retired in RetiredEnvelope.MEMBERS:
assert retired not in problem["run_error"]
case CliOutputFormat.MARKDOWN:
- assert f"**Next step** (`change_model`): {advice}" in printed
- assert (
- f"- `model.unknown`: {HostedMethodItems.PROBLEM_ITEMS[1]['detail']} (pipe 'draft', field 'model', file 'main.mthds')" in printed
- )
+ assert "### The run's own problem" in printed
+ assert f"- `model.unknown`: {item['detail']} (pipe 'draft', field 'model', file 'main.mthds')" in printed
assert "ValidateBundleError" not in printed
@pytest.mark.parametrize(
@@ -220,11 +205,15 @@ class TestRunHostedEnvelope:
def test_a_failed_run_nests_the_run_s_own_problem_in_the_caller_s_view(
self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], stored_report: dict[str, Any]
) -> None:
- """A stored report that is a problem document rides as `run_error` by its declared members alone, without the
- diagnostics only its operator reads, and a member it holds in a shape this version does not read drops only itself.
+ """A run's own problem rides as `run_error` by its declared members alone, without the diagnostics only its
+ operator reads, and a member it holds in a shape this version does not read drops only itself.
"""
- report = RunErrorReport.model_validate(stored_report)
- failed = RunFailedError("Run finished with status FAILED", run_id="run_9", status=RunStatus.FAILED, error=report)
+ failed = RunFailedError(
+ "Run finished with status FAILED",
+ run_id="run_9",
+ status=RunStatus.FAILED,
+ problem=run_failed_problem(run_id="run_9", status=RunStatus.FAILED, run_error=Problem.model_validate(stored_report)),
+ )
mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=failed))
with pytest.raises(typer.Exit):
@@ -236,8 +225,12 @@ class TestRunHostedEnvelope:
assert problem["run_error"] == stored
def test_a_failed_run_s_own_problem_in_markdown(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:
- report = RunErrorReport.model_validate(StoredRunReports.PROBLEM)
- failed = RunFailedError("Run finished with status FAILED", run_id="run_9", status=RunStatus.FAILED, error=report)
+ failed = RunFailedError(
+ "Run finished with status FAILED",
+ run_id="run_9",
+ status=RunStatus.FAILED,
+ problem=run_failed_problem(run_id="run_9", status=RunStatus.FAILED, run_error=Problem.model_validate(StoredRunReports.PROBLEM)),
+ )
mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=failed))
with pytest.raises(typer.Exit):
@@ -324,7 +317,7 @@ class TestRunHostedEnvelope:
[
(
RunTimeoutError("Run 'run_7' did not finish within 1200s", run_id="run_7", timeout_seconds=1200.0),
- "run.not_finished",
+ "client.follow_failed",
"Run 'run_7' did not finish within 1200s",
),
(
@@ -385,165 +378,114 @@ class TestRunHostedEnvelope:
run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)
problem = json.loads(capsys.readouterr().err)
+ human_view = describe_hosted_error(error=error, credential_sent=True)
assert problem["code"] == error.problem.code
- assert problem["next_step"] == {"kind": error.problem.next_step.kind, "detail": describe_hosted_error(error=error).next_step}
+ assert problem["next_step"] == {"kind": error.problem.next_step.kind, "detail": tailored_next_step(error=error)}
+ assert human_view.problem.next_step.as_wire() == problem["next_step"]
@pytest.mark.parametrize(
- ("error", "retry", "kind"),
+ ("reason", "status", "code", "retry", "kind", "next_step"),
[
- (
- MethodFileTransferError(
- "Uploading the file with SHA-256 abc to storage.test failed: no answer came back, so the run was not started.",
- operation=MethodFileTransferOperation.UPLOAD,
- code=MethodFileTransferCode.UNREACHABLE,
- sha256="abc",
- problem=make_client_problem(CoreCode.CLIENT_UNREACHABLE, params={"base_url": "https://storage.test"}),
- ),
- "yes",
- "retry",
- ),
- (
- MethodFileTransferError(
- "Uploading the file with SHA-256 abc to storage.test failed (429 Too Many Requests), so the run was not started.",
- operation=MethodFileTransferOperation.UPLOAD,
- code=MethodFileTransferCode.STORAGE_ERROR,
- sha256="abc",
- status=429,
- ),
- "yes",
- "retry",
- ),
- (
- MethodFileTransferError(
- "Uploading the file with SHA-256 abc to storage.test failed (403 Forbidden), so the run was not started.",
- operation=MethodFileTransferOperation.UPLOAD,
- code=MethodFileTransferCode.REFUSED,
- sha256="abc",
- status=403,
- ),
- "no",
- "report",
- ),
+ (MethodFileTransferReason.UNREACHABLE, None, "runtime.unavailable", "yes", "retry", HOSTED_FILE_UNREACHABLE_NEXT_STEP),
+ (MethodFileTransferReason.STORAGE_ERROR, 429, "runtime.unavailable", "yes", "retry", HOSTED_FILE_STORAGE_ERROR_NEXT_STEP),
+ (MethodFileTransferReason.REFUSED, 403, "client.response_unreadable", "no", "report", HOSTED_FILE_REFUSED_NEXT_STEP),
+ (MethodFileTransferReason.MISMATCH, None, "client.response_unreadable", "no", "report", HOSTED_FILE_MISMATCH_NEXT_STEP),
],
- ids=["unreachable", "throttled", "refused"],
+ ids=["unreachable", "throttled", "refused", "mismatch"],
)
def test_a_file_of_the_tree_that_could_not_be_uploaded_carries_the_sdk_s_verdict(
- self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], error: MethodFileTransferError, retry: str, kind: str
+ self,
+ mocker: MockerFixture,
+ capsys: pytest.CaptureFixture[str],
+ reason: MethodFileTransferReason,
+ status: int | None,
+ code: str,
+ retry: str,
+ kind: str,
+ next_step: str,
) -> None:
- """The SDK's problem for storage's answer is read from its status alone, which the standard may read as no retry
- helping, a 429 for one; the problem carries the SDK's verdict instead, and the step the human CLI prints.
+ """pipelex-sdk reads why the transfer failed as its verdict, a storage error a later attempt can pass and a
+ refusal or a mismatch one it cannot; the problem carries that verdict, with the step the human CLI prints.
"""
+ error = MethodFileTransferError(
+ "Uploading the file with SHA-256 abc to storage.test failed, so the run was not started.",
+ operation=MethodFileTransferOperation.UPLOAD,
+ reason=reason,
+ sha256="abc",
+ status=status,
+ )
mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=error))
with pytest.raises(typer.Exit):
run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)
problem = json.loads(capsys.readouterr().err)
- assert problem["code"] == error.problem.code
+ assert problem["code"] == code
assert problem["retry"] == retry
- assert problem["next_step"] == {"kind": kind, "detail": describe_hosted_error(error=error).next_step}
+ assert problem["next_step"] == {"kind": kind, "detail": next_step}
assert problem["message"] == str(error)
for retired in RetiredEnvelope.MEMBERS:
assert retired not in problem
@pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])
- @pytest.mark.parametrize(
- "malformed",
- [{"run_error": "not a problem"}, {"run_error": {"title": 7}}, {"diagnostics": "unreadable"}],
- ids=["run_error_text", "run_error_unreadable", "diagnostics_unreadable"],
- )
- def test_a_former_shape_refusal_whose_client_reading_holds_a_member_that_does_not_read_still_prints(
- self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], malformed: dict[str, Any], error_format: CliOutputFormat
+ def test_a_method_that_does_not_load_lists_the_hosted_api_s_items(
+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], error_format: CliOutputFormat
) -> None:
- """A refusal in the former shape keeps the client's reading with the answer's reason, read by the standard's
- members alone, so a member of Pipelex's beside them in a shape no reader takes never stops the problem printing.
+ """Each item of pipe-io's verdict is a problem item as pipelex-sdk read it, by its declared members alone: an
+ item whose declared member does not read keeps its code and its facts, and a member no reader declares is left out.
"""
- body = json.dumps({"message": CONFLICT_REASON})
- message = f"API POST /v1/start failed (409): {CONFLICT_REASON}"
- plain = ApiResponseError(message, api_url="https://hosted.test", status=409, status_text="Conflict", response_body=body)
- refusal = ApiResponseError(
- message,
- api_url="https://hosted.test",
- status=409,
- status_text="Conflict",
- response_body=body,
- server_message=CONFLICT_REASON,
- problem=Problem.model_validate({**plain.problem.as_wire(), **malformed}),
+ refused = HostedMethodInvalidError(
+ "The hosted API cannot load the method: Bundle does not load",
+ errors=read_problem_items(PipeIoItems.SENT),
)
- mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=refusal))
+ mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=refused))
- with pytest.raises(typer.Exit) as exc_info:
+ with pytest.raises(typer.Exit):
run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=error_format)
- assert exc_info.value.exit_code == 1
printed = capsys.readouterr().err
match error_format:
case CliOutputFormat.JSON:
- assert json.loads(printed) == {
- "type": "https://mthds.ai/errors/client.response_unreadable",
- "title": "The runtime's answer could not be read",
- "status": 409,
- "detail": CONFLICT_REASON,
- "code": "client.response_unreadable",
- "domain": "runtime",
- "retry": "no",
- "next_step": {"kind": "change_input", "detail": HOSTED_REFUSAL_CALLER_NEXT_STEP},
- "params": {"status": 409},
- }
+ problem = json.loads(printed)
+ assert problem["code"] == "method.invalid"
+ assert problem["errors"] == PipeIoItems.REPORTED
+ assert problem["message"] == "The hosted API cannot load the method: Bundle does not load"
+ for retired in RetiredEnvelope.MEMBERS:
+ assert retired not in problem
case CliOutputFormat.MARKDOWN:
- assert printed.startswith(f"## The runtime's answer could not be read\n\n{CONFLICT_REASON}\n")
- assert f"**Next step** (`change_input`): {HOSTED_REFUSAL_CALLER_NEXT_STEP}" in printed
- assert "### The run's own problem" not in printed
-
- def test_a_sent_item_with_a_field_this_version_does_not_read_keeps_its_code(
- self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]
- ) -> None:
- """An item of a type this version reads is coded by its type even when it carries a field no model here declares."""
- refused = HostedMethodInvalidError(
- "The hosted API cannot load the method: Bundle does not load",
- validation_errors=[ValidationErrorItem.model_validate(HostedMethodItems.SENT_WITH_AN_UNKNOWN_FIELD)],
- )
- mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=refused))
-
- with pytest.raises(typer.Exit):
- run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)
-
- assert json.loads(capsys.readouterr().err)["errors"] == [HostedMethodItems.PROBLEM_ITEMS[1]]
+ assert printed.startswith("## The method does not validate\n")
+ assert "The hosted API cannot load the method: Bundle does not load" in printed
+ assert f"- `model.unknown`: {PipeIoItems.REPORTED[0]['detail']} (pipe 'draft', field 'model', file 'main.mthds')" in printed
+ assert (
+ f"- `method.concept_unresolved`: {PipeIoItems.REPORTED[1]['detail']} (pipe 'summarize', field 'output', "
+ "file 'lib/summarize.mthds')"
+ ) in printed
- def test_a_sent_item_with_a_member_this_version_does_not_read_keeps_its_code_and_its_facts(
- self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]
+ @pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])
+ def test_an_item_of_a_code_newer_than_this_client_keeps_the_runner_s_sentence_and_parameters(
+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], error_format: CliOutputFormat
) -> None:
- """A declared member this version cannot read, such as a newer runner's fix, is left out alone: the item keeps its
- type, its locators and the dependency they name, never degrading to `method.schema_violation`.
+ """The runner answered its verdict to its caller already, so an item under a code this client's registry does
+ not hold is reported as it came, its sentence and its parameters kept, never replaced by the generic sentence.
"""
refused = HostedMethodInvalidError(
"The hosted API cannot load the method: Bundle does not load",
- validation_errors=[ValidationErrorItem.model_validate(HostedMethodItems.SENT_WITH_AN_UNREADABLE_FIX)],
+ errors=read_problem_items([PipeIoItems.NEWER_CODE]),
)
mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=refused))
with pytest.raises(typer.Exit):
- run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)
-
- assert json.loads(capsys.readouterr().err)["errors"] == [HostedMethodItems.UNREADABLE_FIX_PROBLEM_ITEM]
-
- def test_a_method_that_does_not_load_lists_the_hosted_api_s_items(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:
- """Each item of pipe-io's verdict is a problem item coded as a local verdict codes it, located in the file it was sent as."""
- refused = HostedMethodInvalidError(
- "The hosted API cannot load the method: Bundle does not load",
- validation_errors=[ValidationErrorItem.model_validate(item) for item in HostedMethodItems.SENT],
- )
- mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=refused))
-
- with pytest.raises(typer.Exit):
- run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)
+ run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=error_format)
- problem = json.loads(capsys.readouterr().err)
- assert problem["code"] == "method.invalid"
- assert problem["errors"] == HostedMethodItems.PROBLEM_ITEMS
- assert problem["message"] == "The hosted API cannot load the method: Bundle does not load"
- for retired in RetiredEnvelope.MEMBERS:
- assert retired not in problem
+ printed = capsys.readouterr().err
+ assert UNKNOWN_CODE_ITEM_DETAIL not in printed
+ match error_format:
+ case CliOutputFormat.JSON:
+ problem = json.loads(printed)
+ assert problem["code"] == "method.invalid"
+ assert problem["errors"] == [PipeIoItems.NEWER_CODE]
+ case CliOutputFormat.MARKDOWN:
+ assert (f"- `method.construct_unsupported_here`: {PipeIoItems.NEWER_CODE['detail']} (pipe 'summarize', file 'main.mthds')") in printed
def test_a_configuration_that_cannot_be_read_gives_the_boot_s_problem(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:
"""Reading `[run] execution` meets the configuration a local boot meets, and reports the problem a local boot reports."""
diff --git a/tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py b/tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py
index 717dab464..3866a1189 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py
@@ -1,8 +1,8 @@
"""Unit tests: `pipelex-agent run … --runner hosted` reports a refused, failed or unreachable run as the problem it got.
-The answers are a runner's own problem documents, replayed through the real pipelex-sdk `PipelexAPIClient` over a mocked
-HTTP transport that answers the version handshake as the hosted API does and refuses the run, or refuses every
-connection, so no test reaches the network.
+The answers are a runner's own problem documents and the bare answers of the edge in front of it, replayed through the
+real pipelex-sdk `PipelexAPIClient` over a mocked HTTP transport that answers the version handshake as the hosted API
+does and refuses the run, or refuses every connection, so no test reaches the network.
"""
from __future__ import annotations
@@ -21,27 +21,17 @@ from pipelex.cli.agent_cli.commands.run.bundle_cmd import run_bundle_cmd
from pipelex.cli.agent_cli.commands.run.method_cmd import run_method_cmd
from pipelex.cli.agent_cli.commands.run.pipe_cmd import run_pipe_cmd
from pipelex.hosted.client_factory import PIPELEX_API_KEY_ENV_KEY, PIPELEX_BASE_URL_ENV_KEY
-from pipelex.hosted.error_rendering import (
- HOSTED_FORBIDDEN_NEXT_STEP,
- HOSTED_MISSING_KEY_NEXT_STEP,
- HOSTED_REFUSAL_CALLER_NEXT_STEP,
- HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS,
- HOSTED_UNREACHABLE_NEXT_STEP,
-)
+from pipelex.hosted.error_rendering import HOSTED_MISSING_KEY_NEXT_STEP, HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS, HOSTED_UNREACHABLE_NEXT_STEP
from pipelex.hosted.run_config import RunExecution
from pipelex.system.usage_stats.usage_stats_contract import UsageStatsError, UsageStatsErrorDomain
from tests.unit.pipelex.cli.agent_cli.test_data import (
GatewayAnswers,
- HostedMethodItems,
- HostedPlaneRefusals,
OperatorViewAnswers,
RetiredEnvelope,
- RunnerOwnMethodRefusals,
- RunnerOwnRefusals,
RunnerProblems,
UndeclaredMembers,
)
-from tests.unit.pipelex.hosted.test_data import HostedVersions
+from tests.unit.pipelex.hosted.test_data import HostedRefusals, HostedVersions
if TYPE_CHECKING:
from pathlib import Path
@@ -65,7 +55,7 @@ UNREACHABLE_PROBLEM: dict[str, Any] = {
"next_step": {"kind": "retry", "detail": HOSTED_UNREACHABLE_NEXT_STEP},
"params": {"base_url": HOSTED_URL},
}
-#: A runner's own problem for a fault it met while running, which an answer on the run request cannot be trusted for.
+#: A runner's own problem for a fault it met while running, whose `retry` says no run is worth sending again.
RUNNER_FAULT: str = json.dumps(
{
"type": "https://mthds.ai/errors/runtime.unexpected",
@@ -243,10 +233,10 @@ class TestRunHostedRefusal:
@pytest.mark.usefixtures("tty_stdin")
@pytest.mark.parametrize(
("status", "body"),
- [(502, GatewayAnswers.HTML_PAGE), (500, RUNNER_FAULT)],
- ids=["gateway_page", "runner_problem"],
+ [(502, GatewayAnswers.HTML_PAGE), (500, "")],
+ ids=["gateway_page", "empty_body"],
)
- def test_a_server_fault_on_the_run_request_leaves_the_outcome_unknown(
+ def test_a_bare_server_fault_on_the_run_request_leaves_the_outcome_unknown(
self,
mocker: MockerFixture,
monkeypatch: pytest.MonkeyPatch,
@@ -255,7 +245,7 @@ class TestRunHostedRefusal:
status: int,
body: str,
) -> None:
- """A 5xx on the run request may follow a run that started, so it is the client's `client.outcome_unknown`, whatever its body."""
+ """A bare 5xx on the run request may follow a run that started, so it is the client's `client.outcome_unknown`."""
_install_hosted_api(mocker, monkeypatch, status=status, body=body)
with pytest.raises(typer.Exit) as exc_info:
@@ -269,6 +259,18 @@ class TestRunHostedRefusal:
assert problem["next_step"]["kind"] == "read_run"
_assert_no_retired_member(problem=problem)
+ @pytest.mark.usefixtures("tty_stdin")
+ def test_a_runner_s_own_fault_on_the_run_request_is_reported_as_it_came(
+ self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path
+ ) -> None:
+ """A 5xx whose body is the runner's problem document says itself whether a run may exist, by its own `retry`."""
+ _install_hosted_api(mocker, monkeypatch, status=500, body=RUNNER_FAULT)
+
+ with pytest.raises(typer.Exit):
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)
+
+ assert json.loads(capsys.readouterr().err) == json.loads(RUNNER_FAULT)
+
@pytest.mark.usefixtures("tty_stdin")
def test_a_server_fault_in_markdown(
self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path
@@ -407,90 +409,38 @@ class TestRunHostedRefusal:
assert _routes(seen=seen) == [START_ROUTE, ("POST", "/v1/execute")]
problem = json.loads(capsys.readouterr().err)
assert problem["code"] == "request.not_found"
- assert problem["detail"] == "Not Found"
+ assert problem["status"] == 404
+ assert problem["detail"] == "This runner serves no such route."
assert problem["next_step"] == {"kind": "upgrade", "detail": HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[404]}
_assert_no_retired_member(problem=problem)
- @pytest.mark.builds_problems_without_required_params(
- reason="the hosted plane's former-shape refusal names none of its code's parameters; the agent reads its status and own code alone"
- )
@pytest.mark.usefixtures("tty_stdin")
@pytest.mark.parametrize(
- ("status", "body", "headers", "expected"),
+ ("status", "body", "expected"),
[
(
401,
- HostedPlaneRefusals.UNAUTHORIZED,
- {},
+ GatewayAnswers.UNAUTHORIZED,
{
"type": "https://mthds.ai/errors/auth.invalid_credential",
"title": "The credential was refused",
"status": 401,
- "detail": "The API key is not valid.",
+ "detail": "The runtime refused the request's credential.",
"code": "auth.invalid_credential",
"domain": "account",
"retry": "no",
"next_step": {"kind": "check_credentials", "detail": HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[401]},
- "request_id": "01M55PLEGACY401000000000000",
- },
- ),
- (
- 403,
- HostedPlaneRefusals.FORBIDDEN,
- {},
- {
- "type": "https://mthds.ai/errors/auth.forbidden",
- "title": "The credential does not permit this",
- "status": 403,
- "detail": "Your role in this organization does not allow running methods.",
- "code": "auth.forbidden",
- "params": {},
- "domain": "account",
- "retry": "no",
- "next_step": {"kind": "request_access", "detail": HOSTED_FORBIDDEN_NEXT_STEP},
- "request_id": "01M55PLEGACY403000000000000",
- },
- ),
- (
- 403,
- HostedPlaneRefusals.FORBIDDEN_OPERATION,
- {},
- {
- "type": "https://mthds.ai/errors/auth.forbidden",
- "title": "The credential does not permit this",
- "status": 403,
- "detail": "This route is served to a web session only.",
- "code": "auth.forbidden",
- "params": {},
- "domain": "account",
- "retry": "no",
- "next_step": {"kind": "request_access", "detail": HOSTED_FORBIDDEN_NEXT_STEP},
- },
- ),
- (
- 403,
- HostedPlaneRefusals.FORBIDDEN_EXPIRED_KEY,
- {},
- {
- "type": "https://mthds.ai/errors/auth.invalid_credential",
- "title": "The credential was refused",
- "status": 403,
- "detail": "The API key has expired.",
- "code": "auth.invalid_credential",
- "domain": "account",
- "retry": "no",
- "next_step": {"kind": "check_credentials", "detail": HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[403]},
+ "request_id": HEADER_REQUEST_ID,
},
),
(
403,
GatewayAnswers.FORBIDDEN,
- {"x-request-id": HEADER_REQUEST_ID},
{
"type": "https://mthds.ai/errors/auth.invalid_credential",
"title": "The credential was refused",
"status": 403,
- "detail": "Forbidden",
+ "detail": "The runtime refused the request's credential.",
"code": "auth.invalid_credential",
"domain": "account",
"retry": "no",
@@ -498,87 +448,10 @@ class TestRunHostedRefusal:
"request_id": HEADER_REQUEST_ID,
},
),
- (
- 404,
- HostedPlaneRefusals.RUN_NOT_FOUND,
- {},
- {
- "type": "https://mthds.ai/errors/run.not_found",
- "title": "No such run",
- "status": 404,
- "detail": "No run run_9 is visible to this key.",
- "code": "run.not_found",
- "params": {},
- "domain": "input",
- "retry": "no",
- "next_step": {"kind": "change_input", "detail": "Check the run id, then read the run again."},
- },
- ),
- (
- 404,
- HostedPlaneRefusals.METHOD_VERSION_NOT_FOUND,
- {},
- {
- "type": "https://mthds.ai/errors/method.not_found",
- "title": "No method at this address",
- "status": 404,
- "detail": "The method mt_7 has no published version 3.",
- "code": "method.not_found",
- "params": {},
- "domain": "input",
- "retry": "no",
- "next_step": {"kind": "change_input", "detail": HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[404]},
- },
- ),
- (
- 429,
- HostedPlaneRefusals.RATE_LIMITED,
- {"retry-after": "30"},
- {
- "type": "https://mthds.ai/errors/account.rate_limited",
- "title": "The account is over its request rate",
- "status": 429,
- "detail": "Too many runs started in the last minute.",
- "code": "account.rate_limited",
- "params": {},
- "domain": "account",
- "retry": "yes",
- "retry_after": 30,
- "next_step": {"kind": "wait", "detail": HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[429]},
- "request_id": "01M55PLEGACY429000000000000",
- },
- ),
- (
- 429,
- HostedPlaneRefusals.RATE_LIMITED_BODY_DELAY,
- {},
- {
- "type": "https://mthds.ai/errors/account.rate_limited",
- "title": "The account is over its request rate",
- "status": 429,
- "detail": "Too many runs started in the last minute.",
- "code": "account.rate_limited",
- "params": {},
- "domain": "account",
- "retry": "yes",
- "retry_after": 12,
- "next_step": {"kind": "wait", "detail": HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[429]},
- },
- ),
- ],
- ids=[
- "unauthorized",
- "forbidden",
- "forbidden_operation",
- "forbidden_expired_key",
- "gateway_forbidden",
- "run_not_found",
- "method_version_not_found",
- "rate_limited",
- "rate_limited_body_delay",
],
+ ids=["unauthorized", "forbidden"],
)
- def test_a_refusal_of_the_hosted_plane_reads_as_its_core_code_with_the_hosted_guidance(
+ def test_a_bare_refusal_of_the_edge_reads_as_a_refused_credential_with_the_hosted_guidance(
self,
mocker: MockerFixture,
monkeypatch: pytest.MonkeyPatch,
@@ -586,15 +459,12 @@ class TestRunHostedRefusal:
bundle_file: Path,
status: int,
body: str,
- headers: dict[str, str],
expected: dict[str, Any],
) -> None:
- """The hosted plane answers in its pre-standard shape: its refusal reads as the core code its status and its own
- code name, the plane's own detail kept, the next step the human CLI gives, and a rate limit's delay from its header
- or its body. A 403 the platform answers with an authorization code refuses a key it authenticated; one with any
- other code, and the edge's bare 403, may refuse the key itself.
+ """An answer of the edge that is no problem document reads by its status: a request that carried a key had it
+ refused, with the next step that names this client's key and origin settings and the request id of the edge's header.
"""
- _install_hosted_api(mocker, monkeypatch, status=status, body=body, headers=headers)
+ _install_hosted_api(mocker, monkeypatch, status=status, body=body, headers={"x-request-id": HEADER_REQUEST_ID})
with pytest.raises(typer.Exit) as exc_info:
run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)
@@ -605,101 +475,83 @@ class TestRunHostedRefusal:
_assert_no_retired_member(problem=problem)
@pytest.mark.usefixtures("tty_stdin")
- @pytest.mark.parametrize(
- ("status", "body", "detail"),
- [(401, HostedPlaneRefusals.UNAUTHORIZED, "The API key is not valid."), (403, GatewayAnswers.FORBIDDEN, "Forbidden")],
- ids=["unauthorized", "gateway_forbidden"],
- )
- def test_a_refused_request_that_carried_no_key_is_a_missing_credential(
- self,
- mocker: MockerFixture,
- monkeypatch: pytest.MonkeyPatch,
- capsys: pytest.CaptureFixture[str],
- bundle_file: Path,
- status: int,
- body: str,
- detail: str,
+ def test_a_bare_throttle_of_the_edge_keeps_the_client_s_reading_and_its_delay(
+ self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path
) -> None:
- """With no key sent, a refused credential is a missing one, and its next step says how to get a key, never that one was refused."""
- _install_hosted_api(mocker, monkeypatch, status=status, body=body)
- monkeypatch.setenv(PIPELEX_API_KEY_ENV_KEY, "")
+ """The edge's bare 429 names no rate window, so it is pipelex-sdk's `runtime.unavailable`, with the delay its header gives."""
+ _install_hosted_api(mocker, monkeypatch, status=429, body=GatewayAnswers.TOO_MANY_REQUESTS, headers={"retry-after": "30"})
with pytest.raises(typer.Exit):
- run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.MARKDOWN, runner=RunExecution.HOSTED)
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)
- markdown = capsys.readouterr().err
- assert markdown.startswith(f"## No credential was sent\n\n{detail}\n")
- assert f"**Next step** (`check_credentials`): {HOSTED_MISSING_KEY_NEXT_STEP}" in markdown
- assert "refused the credentials" not in markdown
- assert "- Code: `auth.missing_credential` (domain account, retry no)" in markdown
- _assert_no_retired_markdown(markdown=markdown)
+ problem = json.loads(capsys.readouterr().err)
+ assert problem["code"] == "runtime.unavailable"
+ assert problem["retry"] == "yes"
+ assert problem["retry_after"] == 30
+ assert problem["next_step"]["kind"] == "retry"
+ _assert_no_retired_member(problem=problem)
@pytest.mark.usefixtures("tty_stdin")
- @pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])
- def test_a_runner_s_own_refusal_in_the_former_shape_keeps_its_reason(
+ @pytest.mark.parametrize("credential_sent", [True, False])
+ @pytest.mark.parametrize(
+ ("status", "body", "headers"),
+ [(401, HostedRefusals.INVALID_KEY, {}), (429, HostedRefusals.RATE_LIMITED, {"retry-after": "30"})],
+ ids=["invalid_key", "rate_limited"],
+ )
+ def test_a_refusal_of_the_hosted_plane_is_its_own_problem_document_whatever_the_key(
self,
mocker: MockerFixture,
monkeypatch: pytest.MonkeyPatch,
capsys: pytest.CaptureFixture[str],
bundle_file: Path,
- error_format: CliOutputFormat,
+ status: int,
+ body: str,
+ headers: dict[str, str],
+ credential_sent: bool,
) -> None:
- """A runner's own 422, which no standard client reads, keeps the client's `client.response_unreadable` but tells
- its reason and the step the human CLI gives it, never to report a body this CLI does not print.
+ """The hosted plane answers its refusals as problem documents, which are never read by their status: the code,
+ the domain, the retry verdict and the next step are its own, the delay of its `Retry-After` header filled in.
"""
- _install_hosted_api(mocker, monkeypatch, status=422, body=RunnerOwnRefusals.RESERVED_OBJECT_KEY)
+ _install_hosted_api(mocker, monkeypatch, status=status, body=body, headers=headers)
+ if not credential_sent:
+ monkeypatch.setenv(PIPELEX_API_KEY_ENV_KEY, "")
- with pytest.raises(typer.Exit) as exc_info:
- run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=error_format, runner=RunExecution.HOSTED)
+ with pytest.raises(typer.Exit):
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)
- assert exc_info.value.exit_code == 1
- printed = capsys.readouterr().err
- reason = json.loads(RunnerOwnRefusals.RESERVED_OBJECT_KEY)["detail"]
- match error_format:
- case CliOutputFormat.JSON:
- problem = json.loads(printed)
- assert problem == {
- "type": "https://mthds.ai/errors/client.response_unreadable",
- "title": "The runtime's answer could not be read",
- "status": 422,
- "detail": reason,
- "code": "client.response_unreadable",
- "domain": "runtime",
- "retry": "no",
- "next_step": {"kind": "change_input", "detail": HOSTED_REFUSAL_CALLER_NEXT_STEP},
- "params": {"status": 422},
- "request_id": "01M55PRESERVED00000000000",
- }
- _assert_no_retired_member(problem=problem)
- case CliOutputFormat.MARKDOWN:
- assert printed.startswith(f"## The runtime's answer could not be read\n\n{reason}\n")
- assert f"**Next step** (`change_input`): {HOSTED_REFUSAL_CALLER_NEXT_STEP}" in printed
- assert "with the status and the body" not in printed
- _assert_no_retired_markdown(markdown=printed)
+ problem = json.loads(capsys.readouterr().err)
+ sent = json.loads(body)
+ expected = {**sent, "retry_after": 30} if "retry-after" in headers else sent
+ assert problem == expected
@pytest.mark.usefixtures("tty_stdin")
- def test_a_refusal_in_the_former_shape_takes_the_step_kind_its_advice_names(
+ @pytest.mark.parametrize(
+ ("status", "body"),
+ [(401, GatewayAnswers.UNAUTHORIZED), (403, GatewayAnswers.FORBIDDEN)],
+ ids=["unauthorized", "forbidden"],
+ )
+ def test_a_refused_request_that_carried_no_key_is_a_missing_credential(
self,
mocker: MockerFixture,
monkeypatch: pytest.MonkeyPatch,
capsys: pytest.CaptureFixture[str],
bundle_file: Path,
+ status: int,
+ body: str,
) -> None:
- """A 4xx in the former shape that advises a step of its own kind, here checking the billing, reports that kind
- beside the advice it gave, never `change_input`, so the step's kind and its detail agree.
- """
- _install_hosted_api(mocker, monkeypatch, status=402, body=RunnerOwnRefusals.NO_CREDIT)
+ """With no key sent, a refused credential is a missing one, and its next step says how to get a key, never that one was refused."""
+ _install_hosted_api(mocker, monkeypatch, status=status, body=body)
+ monkeypatch.setenv(PIPELEX_API_KEY_ENV_KEY, "")
- with pytest.raises(typer.Exit) as exc_info:
- run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)
+ with pytest.raises(typer.Exit):
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.MARKDOWN, runner=RunExecution.HOSTED)
- assert exc_info.value.exit_code == 1
- problem = json.loads(capsys.readouterr().err)
- assert problem["code"] == "client.response_unreadable"
- assert problem["status"] == 402
- assert problem["detail"] == RunnerOwnRefusals.NO_CREDIT_REASON
- assert problem["next_step"] == {"kind": "check_account", "detail": RunnerOwnRefusals.NO_CREDIT_ADVICE}
- _assert_no_retired_member(problem=problem)
+ markdown = capsys.readouterr().err
+ assert markdown.startswith("## No credential was sent\n\nThis route needs a credential, and the request carried none.\n")
+ assert f"**Next step** (`check_credentials`): {HOSTED_MISSING_KEY_NEXT_STEP}" in markdown
+ assert "refused the credentials" not in markdown
+ assert "- Code: `auth.missing_credential` (domain account, retry no)" in markdown
+ _assert_no_retired_markdown(markdown=markdown)
@pytest.mark.usefixtures("tty_stdin")
@pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])
@@ -708,7 +560,7 @@ class TestRunHostedRefusal:
[(HostedVersions.HOSTED, START_ROUTE), (HostedVersions.BARE_RUNNER, ("POST", "/v1/execute"))],
ids=["start", "execute"],
)
- def test_a_runner_s_own_refusal_of_a_method_in_the_former_shape_lists_its_items(
+ def test_a_runner_s_refusal_of_a_method_lists_its_items_on_either_route(
self,
mocker: MockerFixture,
monkeypatch: pytest.MonkeyPatch,
@@ -718,11 +570,10 @@ class TestRunHostedRefusal:
route: tuple[str, str],
error_format: CliOutputFormat,
) -> None:
- """A runner's own 422 in the former shape that lists validation items is `method.invalid`, its items coded as a
- local verdict codes them, with its reason as the detail and its advice as the next step, as a stored report in the
- same shape reads, so the agent CLI lists what the human CLI lists.
+ """A runner's 422 for a method that does not load is its `method.invalid` problem with its items, on the start of
+ the hosted API and on the blocking execute of a bare runner alike.
"""
- seen = _install_hosted_api(mocker, monkeypatch, status=422, body=RunnerOwnMethodRefusals.INVALID_METHOD, version=version)
+ seen = _install_hosted_api(mocker, monkeypatch, status=422, body=HostedRefusals.INVALID_METHOD, version=version)
with pytest.raises(typer.Exit) as exc_info:
run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=error_format, runner=RunExecution.HOSTED)
@@ -733,27 +584,14 @@ class TestRunHostedRefusal:
match error_format:
case CliOutputFormat.JSON:
problem = json.loads(printed)
- assert problem == {
- "type": "https://mthds.ai/errors/method.invalid",
- "title": "The method does not validate",
- "status": 422,
- "detail": RunnerOwnMethodRefusals.REASON,
- "code": "method.invalid",
- "domain": "method",
- "retry": "no",
- "next_step": {"kind": "change_model", "detail": RunnerOwnMethodRefusals.ADVICE},
- "errors": HostedMethodItems.PROBLEM_ITEMS[:2],
- "request_id": "01M55PINVALIDMETHOD000000",
- }
+ assert problem == json.loads(HostedRefusals.INVALID_METHOD)
_assert_no_retired_member(problem=problem)
case CliOutputFormat.MARKDOWN:
- assert printed.startswith(f"## The method does not validate\n\n{RunnerOwnMethodRefusals.REASON}\n")
- assert f"**Next step** (`change_model`): {RunnerOwnMethodRefusals.ADVICE}" in printed
+ assert printed.startswith("## The method does not validate\n\nThe method does not validate.\n")
+ assert f"**Next step** (`change_method`): {HostedRefusals.INVALID_METHOD_NEXT_STEP}" in printed
assert "### Errors" in printed
- assert (
- f"- `model.unknown`: {HostedMethodItems.PROBLEM_ITEMS[1]['detail']} (pipe 'draft', field 'model', file 'main.mthds')" in printed
- )
- assert "client.response_unreadable" not in printed
+ item = HostedRefusals.INVALID_METHOD_ITEMS[0]
+ assert f"- `model.unknown`: {item['detail']} (pipe 'draft_pitch', field 'model', file 'bundle.mthds')" in printed
_assert_no_retired_markdown(markdown=printed)
@pytest.mark.usefixtures("tty_stdin")
diff --git a/tests/unit/pipelex/cli/commands/run/test_run_hosted_cli.py b/tests/unit/pipelex/cli/commands/run/test_run_hosted_cli.py
index 147a47f9d..b1570c7f6 100644
--- a/tests/unit/pipelex/cli/commands/run/test_run_hosted_cli.py
+++ b/tests/unit/pipelex/cli/commands/run/test_run_hosted_cli.py
@@ -9,14 +9,15 @@ from __future__ import annotations
import asyncio
import io
import json
+import re
from typing import TYPE_CHECKING, Any
import pytest
import typer
-from pipelex_sdk.error_models import RunErrorReport
-from pipelex_sdk.errors import ApiUnreachableError, MissingMainStuffError, RunFailedError, RunTimeoutError
+from mthds.protocol.problem.models import Problem, ProblemItem
+from pipelex_sdk.errors import ApiResponseError, ApiUnreachableError, MissingMainStuffError, RunFailedError, RunTimeoutError, run_failed_problem
+from pipelex_sdk.problem_items import read_problem_items
from pipelex_sdk.runs import RunResults, RunStatus
-from pipelex_sdk.validation_models import ValidationErrorItem
from pydantic import ValidationError
from rich.console import Console
from typer.testing import CliRunner
@@ -25,11 +26,15 @@ from pipelex.cli._cli import app as pipelex_app
from pipelex.cli.commands.run.bundle_cmd import run_bundle_cmd
from pipelex.cli.commands.run.method_cmd import run_method_cmd
from pipelex.cli.commands.run.pipe_cmd import run_pipe_cmd
+from pipelex.errors.problem import UNKNOWN_CODE_ITEM_DETAIL
from pipelex.hosted.client_factory import PIPELEX_API_KEY_ENV_KEY, PIPELEX_BASE_URL_ENV_KEY
+from pipelex.hosted.error_rendering import HOSTED_MISSING_KEY_NEXT_STEP, describe_hosted_error
from pipelex.hosted.exceptions import HostedMethodInvalidError, HostedRunPollingError
from pipelex.hosted.hosted_run import HostedRunOutcome, HostedRunRequest
from pipelex.hosted.run_config import RunExecution
from pipelex.system.environment import PIPELEXPATH_ENV_KEY
+from tests.unit.pipelex.cli.agent_cli.test_data import PipeIoItems
+from tests.unit.pipelex.hosted.test_data import HostedRefusals
if TYPE_CHECKING:
from pathlib import Path
@@ -44,8 +49,9 @@ PIPE_CMD_MODULE = "pipelex.cli.commands.run.pipe_cmd"
EXECUTION_MODULE = "pipelex.hosted.execution"
ROOT_CLI_MODULE = "pipelex.cli._cli"
TEXT_STATS_REF = "github.com/Pipelex/methods/[email protected]"
-LABELLED_ITEM = ValidationErrorItem.model_validate(
- {"category": "blueprint_validation", "message": "unknown concept Foo", "source": "lib/b.mthds", "pipe_code": "step2"}
+#: The line the failure report gives the item of `HostedRefusals.INVALID_METHOD`: its code, its sentence and where.
+INVALID_METHOD_ITEM_LINE = (
+ "- model.unknown: The method names the llm model 'gpt-5.1', which no catalog knows. (pipe 'draft_pitch', field 'model', file 'bundle.mthds')"
)
BUNDLE = """domain = "probe"
@@ -81,6 +87,24 @@ def _results_body_drift() -> ValidationError:
raise AssertionError(msg)
+def _refused_start(*, status: int, body: str, headers: dict[str, str] | None = None) -> ApiResponseError:
+ """The error pipelex-sdk raises when the hosted API answers `POST /v1/start` with this status, body and headers."""
+ return ApiResponseError(
+ f"API POST /v1/start failed ({status})",
+ api_url="https://api.pipelex.com",
+ status=status,
+ status_text="Refused",
+ response_body=body,
+ headers={"content-type": "application/json", **(headers or {})},
+ may_start_run=True,
+ )
+
+
+def _row(*, label: str, value: str) -> str:
+ """The pattern of a row of the failure report: its label, padded to the rows' common width, then its value."""
+ return rf"{re.escape(label)}:\s+{re.escape(value)}"
+
+
def _hosted_request(*, run_hosted: AsyncMock) -> HostedRunRequest:
assert run_hosted.await_args is not None
request = run_hosted.await_args.kwargs["request"]
@@ -246,7 +270,7 @@ class TestRunHostedCli:
run_bundle_cmd(path=str(bundle_dir), hosted=True)
assert exc_info.value.exit_code == 1
- print_failure.assert_called_once_with(error=unreachable)
+ print_failure.assert_called_once_with(error=unreachable, credential_sent=True)
def test_a_bundle_file_without_a_library_sends_pipelexpath(
self, monkeypatch: pytest.MonkeyPatch, run_hosted: AsyncMock, bundle_dir: Path, tmp_path: Path
@@ -315,37 +339,74 @@ class TestRunHostedCli:
@pytest.mark.parametrize(
("error", "expected_lines"),
[
+ (
+ _refused_start(status=422, body=HostedRefusals.INVALID_METHOD),
+ [
+ _row(label="Problem", value="The method does not validate"),
+ _row(label="Next step", value=HostedRefusals.INVALID_METHOD_NEXT_STEP),
+ _row(label="Code", value="method.invalid (domain method, retry no)"),
+ _row(label="Request id", value="01M55PINVALIDMETHOD000000"),
+ re.escape(INVALID_METHOD_ITEM_LINE),
+ ],
+ ),
+ (
+ _refused_start(status=429, body=HostedRefusals.RATE_LIMITED, headers={"retry-after": "30"}),
+ [
+ _row(label="Detail", value="Too many runs started in the last minute."),
+ _row(label="Code", value="account.rate_limited (domain account, retry yes, after 30 seconds)"),
+ ],
+ ),
+ (
+ _refused_start(status=401, body=HostedRefusals.BARE_UNAUTHORIZED),
+ [_row(label="Code", value="auth.invalid_credential (domain account, retry no)"), re.escape(PIPELEX_API_KEY_ENV_KEY)],
+ ),
(
RunFailedError(
- "Run finished with status FAILED: bundle invalid",
+ "Run finished with status FAILED: The method does not validate.",
run_id="run_9",
status=RunStatus.FAILED,
- error=RunErrorReport.model_validate(
- {
- "error_type": "ValidateBundleError",
- "message": "bundle invalid",
- "validation_errors": [LABELLED_ITEM.model_dump(mode="json")],
- }
+ problem=run_failed_problem(
+ run_id="run_9", status=RunStatus.FAILED, run_error=Problem.model_validate_json(HostedRefusals.INVALID_METHOD)
),
),
- ["lib/b.mthds: unknown concept Foo", "Run id: run_9"],
+ [
+ _row(label="Code", value="run.failed (domain runtime, retry no)"),
+ _row(label="Run", value="run_9"),
+ re.escape("The run's own problem"),
+ _row(label="Code", value="method.invalid (domain method, retry no)"),
+ re.escape(INVALID_METHOD_ITEM_LINE),
+ ],
),
(
- HostedMethodInvalidError("The hosted API cannot load the method: Bundle does not load", validation_errors=[LABELLED_ITEM]),
- ["lib/b.mthds: unknown concept Foo"],
+ HostedMethodInvalidError(
+ "The hosted API cannot load the method: Bundle does not load",
+ errors=[ProblemItem.model_validate(item) for item in HostedRefusals.INVALID_METHOD_ITEMS],
+ ),
+ [
+ re.escape("The hosted API cannot load the method: Bundle does not load"),
+ _row(label="Code", value="method.invalid (domain method, retry no)"),
+ re.escape(INVALID_METHOD_ITEM_LINE),
+ re.escape("Tip: Fix the method as each of its errors says, then run it again"),
+ ],
),
(
HostedRunPollingError("The run run_7 started on the hosted API, but following it failed", pipeline_run_id="run_7"),
- ["Run id: run_7", "may still be running"],
+ [_row(label="Run", value="run_7"), re.escape("may still be running")],
),
- (RunTimeoutError("Run 'run_7' did not finish within 1200s", run_id="run_7", timeout_seconds=1200.0), ["Run id: run_7"]),
- (MissingMainStuffError("Completed run 'run_7' returned no main stuff", run_id="run_7"), ["Run id: run_7"]),
+ (
+ RunTimeoutError("Run 'run_7' did not finish within 1200s", run_id="run_7", timeout_seconds=1200.0),
+ [_row(label="Run", value="run_7"), _row(label="Code", value="client.follow_failed (domain runtime, retry outcome_unknown)")],
+ ),
+ (MissingMainStuffError("Completed run 'run_7' returned no main stuff", run_id="run_7"), [_row(label="Run", value="run_7")]),
],
+ ids=["method_invalid", "rate_limited", "bare_unauthorized", "run_failed", "pipe_io_invalid", "polling", "timeout", "no_main_stuff"],
)
- def test_a_hosted_failure_prints_its_items_and_its_run(
+ def test_a_hosted_failure_prints_its_problem_its_items_and_its_run(
self, mocker: MockerFixture, bundle_dir: Path, error: Exception, expected_lines: list[str]
) -> None:
- """The failure's report goes to stderr, the run's output stream holding none of it."""
+ """The report is the problem the agent CLI reports, its code with its domain and retry verdict, its next step, its
+ request, its run and its items, and the failed run's own problem; it goes to stderr, the run's output stream holding none of it.
+ """
output = io.StringIO()
failure_output = io.StringIO()
mocker.patch(f"{RUN_HOSTED_MODULE}.get_console", return_value=Console(file=output, width=250))
@@ -357,8 +418,48 @@ class TestRunHostedCli:
printed = failure_output.getvalue()
for expected_line in expected_lines:
- assert expected_line in printed
- assert expected_line not in output.getvalue()
+ assert re.search(expected_line, printed), expected_line
+ assert not re.search(expected_line, output.getvalue())
+
+ def test_an_item_of_a_code_newer_than_this_client_keeps_the_runner_s_sentence(self, mocker: MockerFixture, bundle_dir: Path) -> None:
+ """An item of pipe-io's verdict under a code this client's registry does not hold is printed as the runner wrote
+ it, never as the generic sentence, and the problem both CLIs share keeps its parameters.
+ """
+ refused = HostedMethodInvalidError(
+ "The hosted API cannot load the method: Bundle does not load", errors=read_problem_items([PipeIoItems.NEWER_CODE])
+ )
+ failure_output = io.StringIO()
+ mocker.patch(f"{RUN_HOSTED_MODULE}.get_console", return_value=Console(file=io.StringIO(), width=250))
+ mocker.patch(f"{RUN_HOSTED_MODULE}.get_error_console", return_value=Console(file=failure_output, width=1000))
+ mocker.patch(f"{RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=refused))
+
+ with pytest.raises(typer.Exit):
+ run_bundle_cmd(path=str(bundle_dir), hosted=True)
+
+ printed = failure_output.getvalue()
+ assert f"- method.construct_unsupported_here: {PipeIoItems.NEWER_CODE['detail']} (pipe 'summarize', file 'main.mthds')" in printed
+ assert UNKNOWN_CODE_ITEM_DETAIL not in printed
+ shared = describe_hosted_error(error=refused, credential_sent=True).problem
+ assert [item.as_wire() for item in shared.errors or []] == [PipeIoItems.NEWER_CODE]
+
+ def test_a_refused_request_that_carried_no_key_is_a_missing_credential(
+ self, mocker: MockerFixture, bundle_dir: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """With no key sent, the edge's bare refusal is a missing credential, and the next step says how to get a key."""
+ monkeypatch.setenv(PIPELEX_API_KEY_ENV_KEY, "")
+ failure_output = io.StringIO()
+ mocker.patch(f"{RUN_HOSTED_MODULE}.get_console", return_value=Console(file=io.StringIO(), width=250))
+ # Wide enough for the next step's whole line.
+ mocker.patch(f"{RUN_HOSTED_MODULE}.get_error_console", return_value=Console(file=failure_output, width=1000))
+ refusal = _refused_start(status=403, body=HostedRefusals.BARE_FORBIDDEN)
+ mocker.patch(f"{RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=refusal))
+
+ with pytest.raises(typer.Exit):
+ run_bundle_cmd(path=str(bundle_dir), hosted=True)
+
+ printed = failure_output.getvalue()
+ assert re.search(_row(label="Code", value="auth.missing_credential (domain account, retry no)"), printed)
+ assert re.search(_row(label="Next step", value=HOSTED_MISSING_KEY_NEXT_STEP), printed)
def test_an_acknowledged_start_is_announced_with_its_run_id(self, mocker: MockerFixture, bundle_dir: Path, tmp_path: Path) -> None:
output = io.StringIO()
@@ -397,7 +498,7 @@ class TestRunHostedCli:
assert exc_info.value.exit_code == 130
assert "Run run_77 started on the hosted API" in output.getvalue()
printed = failure_output.getvalue()
- assert "Run id: run_77" in printed
+ assert re.search(_row(label="Run", value="run_77"), printed)
assert "keeps going on the hosted API" in printed
assert "Traceback" not in printed
@@ -413,7 +514,7 @@ class TestRunHostedCli:
assert exc_info.value.exit_code == 130
printed = failure_output.getvalue()
assert "run history" in printed
- assert "Run id:" not in printed
+ assert not re.search(r"Run:\s", printed)
def test_a_hosted_run_prints_no_deck_notice_and_a_local_run_does(self, mocker: MockerFixture, run_hosted: AsyncMock, tmp_path: Path) -> None:
"""The deck notice is about this machine's inference, which a hosted run never boots."""
diff --git a/tests/unit/pipelex/cli/test_agent_output_drift.py b/tests/unit/pipelex/cli/test_agent_output_drift.py
index 688013631..f18f9edf8 100644
--- a/tests/unit/pipelex/cli/test_agent_output_drift.py
+++ b/tests/unit/pipelex/cli/test_agent_output_drift.py
@@ -2,25 +2,20 @@ import ast
from pathlib import Path
from typing import Any, cast
-import pytest
from mthds.protocol.exceptions import PipelineRequestError
-from pipelex_sdk.error_models import RunErrorReport
-from pipelex_sdk.errors import ApiResponseError, RunFailedError
+from mthds.protocol.problem.models import Problem
+from pipelex_sdk.errors import ApiResponseError, RunFailedError, run_failed_problem
+from pipelex_sdk.problem_items import read_problem_items
from pipelex_sdk.runs import RunStatus
from pydantic import BaseModel
import pipelex.cli.agent_cli
from pipelex.cli.agent_cli.commands.agent_output import problem_payload
-from pipelex.cli.agent_cli.commands.run._run_hosted import PROBLEM_PARTS as READ_PROBLEM_PARTS
-from pipelex.cli.agent_cli.commands.run._run_hosted import hosted_failure_problem
from pipelex.errors.problem import PipelexProblem
-from tests.unit.pipelex.cli.agent_cli.test_data import (
- HostedPlaneRefusals,
- OperatorViewAnswers,
- RunnerOwnRefusals,
- StoredRunReports,
- UndeclaredMembers,
-)
+from pipelex.hosted.error_rendering import PROBLEM_PARTS as READ_PROBLEM_PARTS
+from pipelex.hosted.error_rendering import hosted_failure_problem
+from pipelex.hosted.exceptions import HostedMethodInvalidError, HostedRunError
+from tests.unit.pipelex.cli.agent_cli.test_data import GatewayAnswers, OperatorViewAnswers, PipeIoItems, StoredRunReports, UndeclaredMembers
# The functions that report a problem and take the command's own members as keyword arguments.
_PROBLEM_REPORTERS: frozenset[str] = frozenset({"agent_error", "agent_argument_error", "agent_file_error"})
@@ -100,26 +95,22 @@ def _refusal(*, status: int, body: str) -> ApiResponseError:
)
-def _reported_failures() -> list[PipelineRequestError]:
+def _reported_failures() -> list[PipelineRequestError | HostedRunError]:
"""Failures of a run on a runner whose answers carry members no reader declares, at every level."""
return [
_refusal(status=422, body=UndeclaredMembers.SENT),
- _refusal(status=401, body=HostedPlaneRefusals.UNAUTHORIZED),
- _refusal(status=429, body=HostedPlaneRefusals.RATE_LIMITED_BODY_DELAY),
+ _refusal(status=401, body=GatewayAnswers.UNAUTHORIZED),
+ _refusal(status=429, body=GatewayAnswers.TOO_MANY_REQUESTS),
_refusal(status=409, body=OperatorViewAnswers.UNREADABLE_REQUEST_ID),
- _refusal(status=422, body=RunnerOwnRefusals.RESERVED_OBJECT_KEY),
RunFailedError(
"Run finished with status FAILED",
run_id="run_9",
status=RunStatus.FAILED,
- error=RunErrorReport.model_validate(StoredRunReports.PROBLEM_WITH_REPORT_MEMBERS),
- ),
- RunFailedError(
- "Run finished with status FAILED",
- run_id="run_9",
- status=RunStatus.FAILED,
- error=RunErrorReport.model_validate(StoredRunReports.FORMER_SHAPE_WITH_ITEMS),
+ problem=run_failed_problem(
+ run_id="run_9", status=RunStatus.FAILED, run_error=Problem.model_validate(StoredRunReports.PROBLEM_WITH_REPORT_MEMBERS)
+ ),
),
+ HostedMethodInvalidError("The hosted API cannot load the method", errors=read_problem_items(PipeIoItems.SENT)),
]
@@ -176,9 +167,6 @@ class TestAgentOutputDrift:
offenders.append(f"{source_file.relative_to(package_dir)}:{getattr(node, 'lineno', 0)} writes '{member}'")
assert not offenders, f"These lines write a member of the envelope the problem replaced: {offenders}"
- @pytest.mark.builds_problems_without_required_params(
- reason="the hosted plane's former-shape refusal names none of its code's parameters; the agent reads its status and own code alone"
- )
def test_no_reported_problem_carries_a_member_its_reader_does_not_declare(self) -> None:
"""The document a run on a runner reports holds only the members the standard and Pipelex declare, at every level.
diff --git a/tests/unit/pipelex/hosted/test_data.py b/tests/unit/pipelex/hosted/test_data.py
index 51d7c0cce..590f7aba7 100644
--- a/tests/unit/pipelex/hosted/test_data.py
+++ b/tests/unit/pipelex/hosted/test_data.py
@@ -1,6 +1,7 @@
"""Shared data for the unit tests of `pipelex/hosted/`: a captured pipe-io descriptor and the problem documents of hosted refusals."""
-from typing import ClassVar
+import json
+from typing import Any, ClassVar
class HostedDescriptors:
@@ -34,28 +35,69 @@ class HostedDescriptors:
class HostedRefusals:
- """Problem documents the hosted plane answers a refused request with, as they come off the wire."""
-
- # The platform's own refusal of a key, authored in front of the runner: no `user_action`.
- UNAUTHORIZED: ClassVar[str] = (
- '{"type":"https://docs.pipelex.com/latest/errors/unauthorized/","title":"Unauthorized","status":401,'
- '"detail":"Invalid or expired API key.","instance":"/v1/start","code":"unauthorized"}'
+ """Answers the hosted API, or the edge in front of it, refuses a request with, as they come off the wire."""
+
+ # The runner's refusal of a method at load, a problem document in the caller's view listing its faults.
+ INVALID_METHOD_ITEMS: ClassVar[list[dict[str, Any]]] = [
+ {
+ "code": "model.unknown",
+ "detail": "The method names the llm model 'gpt-5.1', which no catalog knows.",
+ "params": {"model": "gpt-5.1", "model_type": "llm"},
+ "location": {"pipe": "draft_pitch", "field": "model", "file": "bundle.mthds"},
+ "suggestions": ["gpt-5.5"],
+ }
+ ]
+ INVALID_METHOD_NEXT_STEP: ClassVar[str] = "Fix each fault the problem's errors list, then validate the method again."
+ INVALID_METHOD: ClassVar[str] = json.dumps(
+ {
+ "type": "https://mthds.ai/errors/method.invalid",
+ "title": "The method does not validate",
+ "status": 422,
+ "detail": "The method does not validate.",
+ "code": "method.invalid",
+ "domain": "method",
+ "retry": "no",
+ "next_step": {"kind": "change_method", "detail": INVALID_METHOD_NEXT_STEP},
+ "errors": INVALID_METHOD_ITEMS,
+ "request_id": "01M55PINVALIDMETHOD000000",
+ }
)
- UNAUTHORIZED_DETAIL: ClassVar[str] = "Invalid or expired API key."
-
- # The runner's refusal of a bundle at load, with its own next step.
- INVALID_BUNDLE: ClassVar[str] = (
- '{"type":"https://docs.pipelex.com/latest/errors/validate-bundle-error/","title":"Validate bundle","status":422,'
- "\"detail\":\"Pipe 'draft_pitch' (PipeLLM), field 'model': Model handle 'gpt-5.1' was not found in the model deck\","
- '"instance":"/v1/start","request_id":"req_a3dd6900-7909-48d3-b551-0140e73ac7fc","error_domain":"input",'
- '"retryable":false,"error_type":"ValidateBundleError",'
- '"user_action":{"kind":"change_input","detail":"Edit the bundle as each validation error says"}}'
+ # The hosted plane's refusal of a key it does not know, a problem document with its own reason and next step.
+ INVALID_KEY_DETAIL: ClassVar[str] = "The API key is not valid."
+ INVALID_KEY_NEXT_STEP: ClassVar[str] = "Create a new API key on app.pipelex.com, then send the request again."
+ INVALID_KEY: ClassVar[str] = json.dumps(
+ {
+ "type": "https://mthds.ai/errors/auth.invalid_credential",
+ "title": "The credential was refused",
+ "status": 401,
+ "detail": INVALID_KEY_DETAIL,
+ "code": "auth.invalid_credential",
+ "domain": "account",
+ "retry": "no",
+ "next_step": {"kind": "check_credentials", "detail": INVALID_KEY_NEXT_STEP},
+ "request_id": "01M55PINVALIDKEY000000000",
+ }
)
- INVALID_BUNDLE_DETAIL: ClassVar[str] = "Pipe 'draft_pitch' (PipeLLM), field 'model': Model handle 'gpt-5.1' was not found in the model deck"
- INVALID_BUNDLE_NEXT_STEP: ClassVar[str] = "Edit the bundle as each validation error says"
-
- # A server fault with nothing to advise.
- SERVER_FAULT: ClassVar[str] = '{"title":"Internal Server Error","status":500,"detail":"Unexpected failure.","request_id":"req_42"}'
+ # The hosted plane's rate limit, a problem document whose delay rides its `Retry-After` header.
+ RATE_LIMITED: ClassVar[str] = json.dumps(
+ {
+ "type": "https://mthds.ai/errors/account.rate_limited",
+ "title": "The account is over its request rate",
+ "status": 429,
+ "detail": "Too many runs started in the last minute.",
+ "code": "account.rate_limited",
+ "domain": "account",
+ "retry": "yes",
+ "next_step": {"kind": "wait", "detail": "Wait for the rate window to pass, then send the request again."},
+ }
+ )
+ # The hosted edge's bare refusals, which are no problem document: of a request its authorizer did not let through,
+ # of a route no server behind it serves, and a gateway's error page.
+ BARE_UNAUTHORIZED: ClassVar[str] = '{"message":"Unauthorized"}'
+ BARE_FORBIDDEN: ClassVar[str] = '{"message":"Forbidden"}'
+ BARE_NOT_FOUND: ClassVar[str] = '{"detail":"Not Found"}'
+ BARE_BAD_REQUEST: ClassVar[str] = '{"message":"Bad Request"}'
+ GATEWAY_PAGE: ClassVar[str] = "<html><head><title>502 Bad Gateway</title></head><body><h1>502 Bad Gateway</h1></body></html>"
class HostedVersions:
@@ -78,47 +120,42 @@ class HostedPipeIoVerdicts:
"""`POST /v1/pipe-io` invalid verdicts, as the runner's crate core builds them in the caller's view."""
# A method calling a package by its address that the request did not ship: pipe-io loads only the packages shipped
- # with the method, and `/v1/start` fetches the dependency and runs. Built from the item
- # `resolve_crate_from_method_dir`'s refusal carries on 2026-10-18, in the shape that predates the standard, which a
- # runner answering `validation_errors` alone sends.
+ # with the method, and `/v1/start` fetches the dependency and runs. Its item is coded `method.dependency_missing`.
UNSHIPPED_ADDRESS_DEPENDENCY: ClassVar[str] = (
- '{"is_valid": false, "validation_errors": [{"category": "pipe_validation", "error_type": "unresolved_package_dependency", '
- '"pipe_code": "score_invoice", "domain_code": "invoicing", "source": "bundle.mthds", '
- '"field_path": "pipe.score_invoice.steps[0].pipe", "missing_pipe_code": "github.com/mthds/scoring-lib/scoring->scoring.score", '
- '"message": "In-memory resolve cannot load address-based dependency '
- "'github.com/mthds/scoring-lib/scoring' from the host filesystem; provide the dependency contents in the request or "
- 'use directory-based resolution."}], "message": "The method does not validate."}'
- )
- # The same verdict from a runner speaking the standard, whose items are its problem's `errors`. The empty
- # `validation_errors` is there only because the SDK model this package pins requires that member.
- UNSHIPPED_ADDRESS_DEPENDENCY_PROBLEM_ITEMS: ClassVar[str] = (
- '{"is_valid": false, "validation_errors": [], "errors": [{"code": "method.dependency_missing", "detail": "The method '
+ '{"is_valid": false, "errors": [{"code": "method.dependency_missing", "detail": "The method '
"depends on the package 'github.com/mthds/scoring-lib/scoring', which is not available here (reason: not_found).\", "
'"params": {"kind": "package", "name": "github.com/mthds/scoring-lib/scoring", "reason": "not_found"}, '
'"location": {"pipe": "score_invoice", "field": "pipe.score_invoice.steps[0].pipe", "file": "bundle.mthds"}}], '
'"message": "The method does not validate."}'
)
- # The same verdict from a runner answering both members, whose `errors` item this client cannot read (it gives no
- # `detail`): its `validation_errors` still name the package.
- UNSHIPPED_ADDRESS_DEPENDENCY_UNREADABLE_PROBLEM_ITEMS: ClassVar[str] = (
- '{"is_valid": false, "validation_errors": [{"category": "pipe_validation", "error_type": "unresolved_package_dependency", '
- '"pipe_code": "score_invoice", "source": "bundle.mthds", "missing_pipe_code": "github.com/mthds/scoring-lib/scoring->scoring.score", '
- '"message": "In-memory resolve cannot load address-based dependency \'github.com/mthds/scoring-lib/scoring\'."}], '
- '"errors": [{"code": "method.dependency_missing", "params": {"kind": "package", "name": "github.com/mthds/scoring-lib/scoring", '
- '"reason": "not_found"}}], "message": "The method does not validate."}'
+ # The same verdict with an item before it that this client cannot read, since it gives no `detail`: the SDK skips it,
+ # and the item after it still names the package.
+ UNSHIPPED_ADDRESS_DEPENDENCY_AFTER_AN_UNREADABLE_ITEM: ClassVar[str] = (
+ '{"is_valid": false, "errors": [{"code": "method.dependency_missing", "params": {"kind": "package", '
+ '"name": "github.com/mthds/other-lib/other", "reason": "not_found"}}, {"code": "method.dependency_missing", "detail": "The method '
+ "depends on the package 'github.com/mthds/scoring-lib/scoring', which is not available here (reason: not_found).\", "
+ '"params": {"kind": "package", "name": "github.com/mthds/scoring-lib/scoring", "reason": "not_found"}}], '
+ '"message": "The method does not validate."}'
)
# A package the method calls that was found in a cycle: the method's own fault, which no fetch cures.
- DEPENDENCY_CYCLE_PROBLEM_ITEMS: ClassVar[str] = (
- '{"is_valid": false, "validation_errors": [], "errors": [{"code": "method.dependency_missing", "detail": "The method '
+ DEPENDENCY_CYCLE: ClassVar[str] = (
+ '{"is_valid": false, "errors": [{"code": "method.dependency_missing", "detail": "The method '
"depends on the package 'github.com/mthds/scoring-lib/scoring', which is not available here (reason: cycle).\", "
'"params": {"kind": "package", "name": "github.com/mthds/scoring-lib/scoring", "reason": "cycle"}, '
'"location": {"pipe": "score_invoice", "file": "bundle.mthds"}}], "message": "The method does not validate."}'
)
- # An item quoting the words of that refusal that no stage coded as a missing dependency: the method's own fault.
+ # An item quoting the words of that refusal under another code: the method's own fault.
ADDRESS_DEPENDENCY_WORDS_ONLY: ClassVar[str] = (
- '{"is_valid": false, "validation_errors": [{"category": "blueprint_validation", "source": "bundle.mthds", '
- '"message": "In-memory resolve cannot load address-based dependency \'github.com/mthds/scoring-lib/scoring\'."}], '
- '"message": "The method does not validate."}'
+ '{"is_valid": false, "errors": [{"code": "method.schema_violation", "detail": "The declaration at \'pipe.score_invoice\' '
+ "breaks a rule of the language (In-memory resolve cannot load address-based dependency 'github.com/mthds/scoring-lib/scoring').\", "
+ '"params": {"field_path": "pipe.score_invoice", "finding": "In-memory resolve cannot load address-based dependency '
+ '\'github.com/mthds/scoring-lib/scoring\'"}, "location": {"file": "bundle.mthds"}}], "message": "The method does not validate."}'
+ )
+ # A method whose model no catalog knows, with the item locating the fault by its file.
+ UNKNOWN_MODEL: ClassVar[str] = (
+ '{"is_valid": false, "errors": [{"code": "model.unknown", "detail": "The method names the llm model \'gpt-5.1\', which '
+ 'no catalog knows.", "params": {"model": "gpt-5.1", "model_type": "llm"}, "location": {"pipe": "step2", "field": "model", '
+ '"file": "lib/b.mthds"}, "suggestions": ["gpt-5.5"]}], "message": "Bundle does not load"}'
)
diff --git a/tests/unit/pipelex/hosted/test_hosted_error_rendering.py b/tests/unit/pipelex/hosted/test_hosted_error_rendering.py
index 1ba34eede..0177701cb 100644
--- a/tests/unit/pipelex/hosted/test_hosted_error_rendering.py
+++ b/tests/unit/pipelex/hosted/test_hosted_error_rendering.py
@@ -1,40 +1,42 @@
from __future__ import annotations
import asyncio
+import json
+from typing import Any
import httpx
import pytest
+from mthds.protocol.problem.models import Problem, ProblemItem
from pipelex_sdk.client import PipelexAPIClient
-from pipelex_sdk.error_models import RunErrorReport
from pipelex_sdk.errors import (
ApiResponseError,
ApiUnreachableError,
InvalidLocalSourceError,
- MethodFileTransferCode,
MethodFileTransferError,
MethodFileTransferOperation,
+ MethodFileTransferReason,
MissingMainStuffError,
PipelineExecuteTimeoutError,
RunFailedError,
RunTimeoutError,
UploadAuthenticationError,
UploadTransportError,
+ UploadTransportReason,
+ run_failed_problem,
)
from pipelex_sdk.runs import RunStatus
-from pipelex_sdk.validation_models import ValidationErrorItem
+from pipelex.errors.unsupported_reasons import LOCAL_FILE_WITH_ADDRESS_DEPENDENCY_UNSUPPORTED_REASON
from pipelex.hosted.client_factory import PIPELEX_API_KEY_ENV_KEY, PIPELEX_BASE_URL_ENV_KEY
from pipelex.hosted.error_rendering import (
HOSTED_FILE_MISMATCH_NEXT_STEP,
HOSTED_FILE_REFUSED_NEXT_STEP,
HOSTED_FILE_STORAGE_ERROR_NEXT_STEP,
HOSTED_FILE_UNREACHABLE_NEXT_STEP,
- HOSTED_REFUSAL_CALLER_NEXT_STEP,
+ HOSTED_MISSING_KEY_NEXT_STEP,
HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS,
- HOSTED_RUN_REQUEST_NEXT_STEP,
- HOSTED_SERVER_FAULT_NEXT_STEP,
+ HOSTED_UNREACHABLE_NEXT_STEP,
describe_hosted_error,
- hosted_refusal_next_step,
tailored_next_step,
)
from pipelex.hosted.exceptions import (
@@ -44,294 +46,384 @@ from pipelex.hosted.exceptions import (
HostedRunOutcomeUnknownError,
HostedRunPollingError,
)
+from tests.unit.pipelex.cli.agent_cli.test_data import StoredRunReports
from tests.unit.pipelex.hosted.test_data import HostedRefusals
API_URL = "https://api.test"
-LABELLED_ITEM = ValidationErrorItem.model_validate(
- {"category": "blueprint_validation", "message": "unknown concept Foo", "source": "lib/b.mthds", "pipe_code": "step2"}
-)
+#: The request id the hosted edge names in its `X-Request-ID` header.
+HEADER_REQUEST_ID = "01M55PHEADER000000000000000"
+
+def _refusal(*, status: int, body: str, route: str = "start", headers: dict[str, str] | None = None) -> ApiResponseError:
+ """The error the real client raises when the hosted API answers `route` with this status, body and headers.
-def _refusal(*, status: int, body: str) -> ApiResponseError:
- """The error the real client raises when the hosted API answers `POST /v1/start` with this status and body."""
+ `start` sends `POST /v1/start`, which creates a run; `version` sends `GET /v1/version`, which creates none.
+ """
def _handler(request: httpx.Request) -> httpx.Response:
- return httpx.Response(status, content=body.encode("utf-8"), headers={"content-type": "application/problem+json"}, request=request)
+ return httpx.Response(status, content=body.encode("utf-8"), headers={"content-type": "application/json", **(headers or {})}, request=request)
- async def _start() -> None:
+ async def _call() -> None:
client = PipelexAPIClient(api_key="plx_sk_test_not_a_secret", base_url=API_URL)
client.client = httpx.AsyncClient(transport=httpx.MockTransport(_handler))
try:
- await client.start(pipe_code="entry", contents={"probe.mthds": 'domain = "probe"\n'})
+ match route:
+ case "start":
+ await client.start(pipe_code="entry", contents={"probe.mthds": 'domain = "probe"\n'})
+ case _:
+ await client.version()
finally:
await client.close()
with pytest.raises(ApiResponseError) as exc_info:
- asyncio.run(_start())
+ asyncio.run(_call())
return exc_info.value
+def _sent(body: str) -> dict[str, Any]:
+ sent: dict[str, Any] = json.loads(body)
+ return sent
+
+
class TestHostedErrorRendering:
- def test_a_refusal_with_a_next_step_keeps_the_runner_reason_and_its_advice(self) -> None:
- error = _refusal(status=422, body=HostedRefusals.INVALID_BUNDLE)
+ def test_a_problem_document_is_reported_as_it_came_with_its_items(self) -> None:
+ """The runner's own problem gives the code, the domain, the retry verdict, the next step, the request and the items."""
+ error = _refusal(status=422, body=HostedRefusals.INVALID_METHOD)
+
+ view = describe_hosted_error(error=error, credential_sent=True)
+
+ problem = view.problem
+ assert problem.code == "method.invalid"
+ assert problem.effective_domain == "method"
+ assert problem.effective_retry == "no"
+ assert problem.next_step.kind == "change_method"
+ assert problem.next_step.detail == HostedRefusals.INVALID_METHOD_NEXT_STEP
+ assert problem.request_id == "01M55PINVALIDMETHOD000000"
+ assert problem.errors == [ProblemItem.model_validate(item) for item in HostedRefusals.INVALID_METHOD_ITEMS]
+ assert problem.to_wire() == _sent(HostedRefusals.INVALID_METHOD)
+ # The problem says it all, where the error's sentence would quote the body.
+ assert view.message is None
+ assert view.advice is None
+
+ @pytest.mark.parametrize(
+ ("status", "body", "headers", "retry_after"),
+ [
+ (401, HostedRefusals.INVALID_KEY, {}, None),
+ (429, HostedRefusals.RATE_LIMITED, {"retry-after": "30"}, 30),
+ ],
+ ids=["invalid_key", "rate_limited"],
+ )
+ def test_a_refusal_of_the_hosted_plane_keeps_its_own_reason_and_step(
+ self, status: int, body: str, headers: dict[str, str], retry_after: int | None
+ ) -> None:
+ """A problem document is never read by its status, whether a key was sent or not: its code and its step are its own."""
+ error = _refusal(status=status, body=body, headers=headers)
- view = describe_hosted_error(error=error)
+ for credential_sent in (True, False):
+ problem = describe_hosted_error(error=error, credential_sent=credential_sent).problem
- assert view.error_type == "ValidateBundleError"
- assert view.message == f"API POST /v1/start failed (422): {HostedRefusals.INVALID_BUNDLE_DETAIL}"
- assert view.next_step == HostedRefusals.INVALID_BUNDLE_NEXT_STEP
- assert hosted_refusal_next_step(error=error) == HostedRefusals.INVALID_BUNDLE_NEXT_STEP
+ sent = _sent(body)
+ assert problem.code == sent["code"]
+ assert problem.detail == sent["detail"]
+ assert problem.next_step.detail == sent["next_step"]["detail"]
+ assert problem.effective_retry == sent["retry"]
+ assert problem.retry_after == retry_after
- def test_a_refused_key_points_at_the_pipelex_api_key(self) -> None:
- """The platform's own 401 advises nothing; the next step names the variable that holds the key."""
- error = _refusal(status=401, body=HostedRefusals.UNAUTHORIZED)
+ @pytest.mark.parametrize(
+ ("status", "body", "route", "credential_sent", "code", "next_step"),
+ [
+ (401, HostedRefusals.BARE_UNAUTHORIZED, "start", True, "auth.invalid_credential", HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[401]),
+ (401, HostedRefusals.BARE_UNAUTHORIZED, "start", False, "auth.missing_credential", HOSTED_MISSING_KEY_NEXT_STEP),
+ (403, HostedRefusals.BARE_FORBIDDEN, "start", True, "auth.invalid_credential", HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[403]),
+ (403, HostedRefusals.BARE_FORBIDDEN, "start", False, "auth.missing_credential", HOSTED_MISSING_KEY_NEXT_STEP),
+ # A start a server answers with a bare 404 is a bare runner's, which pipelex-sdk raises as its own error.
+ (404, HostedRefusals.BARE_NOT_FOUND, "version", True, "request.not_found", HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[404]),
+ ],
+ ids=["unauthorized_with_key", "unauthorized_without_key", "forbidden_with_key", "forbidden_without_key", "not_found"],
+ )
+ def test_a_bare_answer_of_the_edge_reads_by_its_status_and_the_key_sent(
+ self, status: int, body: str, route: str, credential_sent: bool, code: str, next_step: str
+ ) -> None:
+ """An answer that is no problem document reads by its status, a refused credential as a missing one when no key was
+ sent, with the next step that names this client's settings and the request id the edge's header gives.
+ """
+ error = _refusal(status=status, body=body, route=route, headers={"x-request-id": HEADER_REQUEST_ID})
- view = describe_hosted_error(error=error)
+ view = describe_hosted_error(error=error, credential_sent=credential_sent)
- assert view.error_type == "ApiResponseError"
- assert view.message == f"API POST /v1/start failed (401): {HostedRefusals.UNAUTHORIZED_DETAIL}"
- assert view.next_step == HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[401]
- assert PIPELEX_API_KEY_ENV_KEY in view.next_step
+ problem = view.problem
+ assert problem.code == code
+ assert problem.status == status
+ assert problem.next_step.detail == next_step
+ assert problem.request_id == HEADER_REQUEST_ID
+ assert view.message is None
@pytest.mark.parametrize(("status", "named"), [(401, PIPELEX_API_KEY_ENV_KEY), (403, PIPELEX_API_KEY_ENV_KEY), (404, PIPELEX_BASE_URL_ENV_KEY)])
- def test_the_status_hints_name_the_hosted_settings(self, status: int, named: str) -> None:
+ def test_the_status_steps_name_the_hosted_settings(self, status: int, named: str) -> None:
assert named in HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[status]
assert "MTHDS_" not in HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[status]
- @pytest.mark.parametrize(
- ("status", "expected_next_step"),
- [(400, HOSTED_REFUSAL_CALLER_NEXT_STEP), (500, HOSTED_SERVER_FAULT_NEXT_STEP)],
- )
- def test_an_unadvised_refusal_without_a_hint_of_its_own_falls_back_by_status_class(self, status: int, expected_next_step: str) -> None:
- error = _refusal(status=status, body=HostedRefusals.SERVER_FAULT)
- assert hosted_refusal_next_step(error=error) == expected_next_step
+ @pytest.mark.parametrize("status", [502, 503, 500])
+ def test_a_bare_server_fault_on_the_run_request_leaves_the_outcome_unknown(self, status: int) -> None:
+ """A 5xx on the run request may follow a run that started, so it keeps the client's reading, and its step reads the run."""
+ error = _refusal(status=status, body=HostedRefusals.GATEWAY_PAGE)
+
+ problem = describe_hosted_error(error=error, credential_sent=True).problem
+
+ assert problem.code == "client.outcome_unknown"
+ assert problem.effective_retry == "outcome_unknown"
+ assert problem.next_step.kind == "read_run"
@pytest.mark.parametrize(
- ("status", "body", "expected_domain", "expected_retryable"),
+ ("status", "body", "code", "retry"),
[
- (422, HostedRefusals.INVALID_BUNDLE, "input", False),
- (401, HostedRefusals.UNAUTHORIZED, None, None),
- (500, HostedRefusals.SERVER_FAULT, None, None),
- (503, HostedRefusals.SERVER_FAULT, None, None),
+ (400, HostedRefusals.BARE_BAD_REQUEST, "client.response_unreadable", "no"),
+ (503, HostedRefusals.GATEWAY_PAGE, "runtime.unavailable", "yes"),
+ (429, HostedRefusals.BARE_BAD_REQUEST, "runtime.unavailable", "yes"),
],
+ ids=["bad_request", "unavailable", "throttled"],
)
- def test_a_refusal_carries_only_the_verdict_the_hosted_api_sent(
- self, status: int, body: str, expected_domain: str | None, expected_retryable: bool | None
- ) -> None:
- """pipelex-sdk fills an unsent member from its own table, which reads a 503 as retryable; the view reports what the server said."""
- error = _refusal(status=status, body=body)
+ def test_any_other_bare_answer_keeps_the_client_s_reading_and_its_code_s_step(self, status: int, body: str, code: str, retry: str) -> None:
+ """A status this client does not read itself keeps pipelex-sdk's reading, whose code gives the next step."""
+ error = _refusal(status=status, body=body, route="version")
- view = describe_hosted_error(error=error)
+ problem = describe_hosted_error(error=error, credential_sent=True).problem
- assert view.error_domain == expected_domain
- assert view.retryable == expected_retryable
+ assert problem.code == code
+ assert problem.effective_retry == retry
+ assert problem.next_step.detail == error.problem.next_step.detail
def test_an_unreachable_api_names_the_base_url_settings(self) -> None:
- error = ApiUnreachableError("Could not reach Pipelex API at https://api.test (ConnectError)", api_url=API_URL, code="ConnectError")
-
- view = describe_hosted_error(error=error)
-
- assert view.error_type == "ApiUnreachableError"
- assert view.message == "Could not reach Pipelex API at https://api.test (ConnectError)"
- assert "--base-url" in view.next_step
- assert PIPELEX_BASE_URL_ENV_KEY in view.next_step
-
- def test_a_failed_run_reports_the_runner_class_and_its_advice(self) -> None:
- report = RunErrorReport.model_validate(
- {
- "error_type": "LLMCompletionError",
- "message": "The provider refused the prompt",
- "error_domain": "runtime",
- "user_action": {"kind": "wait_and_retry", "detail": "Run it again in a minute"},
- }
- )
+ error = ApiUnreachableError("Could not reach Pipelex API at https://api.test (ConnectError)", api_url=API_URL, network_code="ConnectError")
+
+ view = describe_hosted_error(error=error, credential_sent=True)
+
+ assert view.problem.code == "client.unreachable"
+ assert view.problem.effective_retry == "yes"
+ assert view.problem.next_step.kind == "retry"
+ assert view.problem.next_step.detail == HOSTED_UNREACHABLE_NEXT_STEP
+ assert "--base-url" in view.problem.next_step.detail
+ assert PIPELEX_BASE_URL_ENV_KEY in view.problem.next_step.detail
+ assert view.message is None
+
+ def test_a_run_request_that_may_have_left_keeps_its_code_s_step(self) -> None:
+ """A request that may have created a run is never told to check the network and run again."""
+ error = ApiUnreachableError("Lost the connection", api_url=API_URL, network_code="ReadError", may_start_run=True)
+
+ problem = describe_hosted_error(error=error, credential_sent=True).problem
+
+ assert problem.code == "client.outcome_unknown"
+ assert problem.next_step.detail != HOSTED_UNREACHABLE_NEXT_STEP
+ assert tailored_next_step(error=error) is None
+
+ @pytest.mark.parametrize(
+ ("run_error", "expected_code"),
+ [
+ (StoredRunReports.PROBLEM, "pipe.output_multiplicity"),
+ (StoredRunReports.PROBLEM_WITH_REPORT_MEMBERS, "pipe.output_multiplicity"),
+ ],
+ ids=["problem", "problem_with_report_members"],
+ )
+ def test_a_failed_run_nests_its_own_problem_in_the_caller_s_view(self, run_error: dict[str, Any], expected_code: str) -> None:
+ """The run's stored record is its operator's: it is projected onto the caller's view, its diagnostics and the members
+ no reader declares left out, and the run's code, domain and retry verdict kept.
+ """
error = RunFailedError(
- "Run finished with status FAILED: The provider refused the prompt", run_id="run_9", status=RunStatus.FAILED, error=report
+ "Run finished with status FAILED: the branches do not combine",
+ run_id="run_9",
+ status=RunStatus.FAILED,
+ problem=run_failed_problem(run_id="run_9", status=RunStatus.FAILED, run_error=Problem.model_validate(run_error)),
)
- view = describe_hosted_error(error=error)
+ view = describe_hosted_error(error=error, credential_sent=True)
+
+ problem = view.problem
+ assert problem.code == "run.failed"
+ assert problem.pipeline_run_id == "run_9"
+ assert problem.effective_retry == "no"
+ assert problem.run_error is not None
+ assert problem.run_error.code == expected_code
+ assert problem.run_error.effective_domain == "method"
+ assert problem.run_error.diagnostics is None
+ assert "error_type" not in problem.run_error.to_wire()
+ assert view.message == "Run finished with status FAILED: the branches do not combine"
+
+ def test_a_failed_run_without_a_stored_problem_still_names_the_run(self) -> None:
+ error = RunFailedError("Run finished with status CANCELLED", run_id="run_9", status=RunStatus.CANCELLED)
- assert view.error_type == "LLMCompletionError"
- assert view.message == "Run finished with status FAILED: The provider refused the prompt"
- assert view.next_step == "Run it again in a minute"
+ problem = describe_hosted_error(error=error, credential_sent=True).problem
- def test_a_failed_run_without_a_report_still_names_the_run(self) -> None:
- error = RunFailedError("Run finished with status CANCELLED", run_id="run_9", status=RunStatus.CANCELLED, error=None)
+ assert problem.code == "run.failed"
+ assert problem.pipeline_run_id == "run_9"
+ assert problem.run_error is None
+ assert tailored_next_step(error=error) is None
- view = describe_hosted_error(error=error)
+ @pytest.mark.parametrize(
+ "error",
+ [
+ RunTimeoutError("Run 'run_7' did not finish within 1200s", run_id="run_7", timeout_seconds=1200.0),
+ MissingMainStuffError("Completed run 'run_7' returned no main stuff", run_id="run_7"),
+ HostedRunPollingError("The run run_7 started on the hosted API, but following it failed", pipeline_run_id="run_7"),
+ ],
+ )
+ def test_an_error_after_the_start_names_the_run(self, error: Exception) -> None:
+ assert isinstance(error, (RunTimeoutError, MissingMainStuffError, HostedRunPollingError))
+ view = describe_hosted_error(error=error, credential_sent=True)
- assert view.error_type == "RunFailedError"
- assert "run_9" in view.next_step
+ assert view.problem.pipeline_run_id == "run_7"
+ assert "run_7" in view.problem.next_step.detail
+ assert view.message is not None
+ assert "run_7" in view.message
- def test_a_run_past_the_wait_keeps_going_and_says_where(self) -> None:
- error = RunTimeoutError("Run 'run_7' did not finish within 1200s", run_id="run_7", timeout_seconds=1200.0)
+ def test_a_lost_run_is_not_reported_as_a_network_failure(self) -> None:
+ error = HostedRunPollingError("The run run_7 started on the hosted API, but following it failed", pipeline_run_id="run_7")
- view = describe_hosted_error(error=error)
+ view = describe_hosted_error(error=error, credential_sent=True)
- assert view.error_type == "RunTimeoutError"
- assert "run_7" in view.next_step
+ assert view.problem.code == "client.follow_failed"
+ assert view.problem.effective_domain == "runtime"
+ assert view.problem.effective_retry == "outcome_unknown"
+ assert view.advice is not None
+ assert "may still be running" in view.advice
def test_an_unreadable_local_file_names_the_path_to_check(self) -> None:
error = InvalidLocalSourceError('Local file cannot be read: "inputs/missing.pdf" (FileNotFoundError).', source="inputs/missing.pdf")
- view = describe_hosted_error(error=error)
+ view = describe_hosted_error(error=error, credential_sent=True)
- assert view.error_type == "InvalidLocalSourceError"
- assert view.error_domain == "input"
+ assert view.problem.effective_domain == "input"
+ assert view.message is not None
assert "inputs/missing.pdf" in view.message
- assert "inputs" in view.next_step
+ assert "inputs" in view.problem.next_step.detail
def test_a_refused_upload_points_at_the_key(self) -> None:
error = UploadAuthenticationError('Upload of "invoice.pdf" was not authorized (401). Check the configured Pipelex API key.', status=401)
- view = describe_hosted_error(error=error)
+ problem = describe_hosted_error(error=error, credential_sent=True).problem
- assert PIPELEX_API_KEY_ENV_KEY in view.next_step
+ assert problem.effective_domain == "account"
+ assert PIPELEX_API_KEY_ENV_KEY in problem.next_step.detail
def test_an_upload_that_could_not_reach_the_api_points_at_the_network_and_the_origin(self) -> None:
- unreachable = ApiUnreachableError("Could not reach Pipelex API at https://api.test (ConnectError)", api_url=API_URL, code="ConnectError")
- error = UploadTransportError('Upload of "a.pdf" could not reach the Pipelex API (ConnectError).')
- error.__cause__ = unreachable
+ unreachable = ApiUnreachableError(
+ "Could not reach Pipelex API at https://api.test (ConnectError)", api_url=API_URL, network_code="ConnectError"
+ )
+ error = UploadTransportError(
+ 'Upload of "a.pdf" could not reach the Pipelex API (ConnectError).', reason=UploadTransportReason.UNREACHABLE, cause=unreachable
+ )
+
+ problem = describe_hosted_error(error=error, credential_sent=True).problem
+
+ assert problem.code == "client.unreachable"
+ assert PIPELEX_BASE_URL_ENV_KEY in problem.next_step.detail
+ assert "network" in problem.next_step.detail
- view = describe_hosted_error(error=error)
+ def test_an_upload_the_server_failed_keeps_its_code_s_step(self) -> None:
+ error = UploadTransportError('Upload of "a.pdf" failed (502): Bad Gateway.', status=502, reason=UploadTransportReason.SERVER_ERROR)
- assert view.error_type == "UploadTransportError"
- assert view.error_domain == "config"
- assert PIPELEX_BASE_URL_ENV_KEY in view.next_step
- assert "network" in view.next_step
+ problem = describe_hosted_error(error=error, credential_sent=True).problem
+
+ assert problem.code == "runtime.unavailable"
+ assert problem.effective_retry == "yes"
+ assert problem.next_step.detail == error.problem.next_step.detail
@pytest.mark.parametrize(
- ("code", "status", "retryable", "next_step"),
+ ("reason", "status", "code", "retry", "next_step"),
[
- (MethodFileTransferCode.UNREACHABLE, None, True, HOSTED_FILE_UNREACHABLE_NEXT_STEP),
- (MethodFileTransferCode.STORAGE_ERROR, 503, True, HOSTED_FILE_STORAGE_ERROR_NEXT_STEP),
- (MethodFileTransferCode.STORAGE_ERROR, 429, True, HOSTED_FILE_STORAGE_ERROR_NEXT_STEP),
- (MethodFileTransferCode.MISMATCH, None, True, HOSTED_FILE_MISMATCH_NEXT_STEP),
- (MethodFileTransferCode.REFUSED, 403, False, HOSTED_FILE_REFUSED_NEXT_STEP),
+ (MethodFileTransferReason.UNREACHABLE, None, "runtime.unavailable", "yes", HOSTED_FILE_UNREACHABLE_NEXT_STEP),
+ (MethodFileTransferReason.STORAGE_ERROR, 503, "runtime.unavailable", "yes", HOSTED_FILE_STORAGE_ERROR_NEXT_STEP),
+ (MethodFileTransferReason.STORAGE_ERROR, 429, "runtime.unavailable", "yes", HOSTED_FILE_STORAGE_ERROR_NEXT_STEP),
+ (MethodFileTransferReason.MISMATCH, None, "client.response_unreadable", "no", HOSTED_FILE_MISMATCH_NEXT_STEP),
+ (MethodFileTransferReason.REFUSED, 403, "client.response_unreadable", "no", HOSTED_FILE_REFUSED_NEXT_STEP),
],
ids=["unreachable", "storage_failed", "storage_throttled", "mismatch", "refused"],
)
def test_a_file_of_the_tree_that_could_not_be_moved_carries_the_sdk_s_verdict(
- self, code: MethodFileTransferCode, status: int | None, retryable: bool, next_step: str
+ self, reason: MethodFileTransferReason, status: int | None, code: str, retry: str, next_step: str
) -> None:
"""A tree sent by hash uploads what the hosted API lacks before the request: nothing started, and whether running
- again helps is the SDK's verdict, every code but a refusal, which is reported.
+ again helps is the SDK's problem, every reason but a refusal and a mismatch, which are reported.
"""
error = MethodFileTransferError(
"Uploading the file with SHA-256 abc to storage.test failed, so the run was not started.",
operation=MethodFileTransferOperation.UPLOAD,
- code=code,
+ reason=reason,
sha256="abc",
status=status,
)
- view = describe_hosted_error(error=error)
+ view = describe_hosted_error(error=error, credential_sent=True)
- assert view.error_type == "MethodFileTransferError"
assert view.message == "Uploading the file with SHA-256 abc to storage.test failed, so the run was not started."
- assert view.error_domain == "runtime"
- assert view.retryable is retryable
- assert view.retryable is error.retryable
- assert view.next_step == next_step
- assert view.next_step != HOSTED_RUN_REQUEST_NEXT_STEP
+ assert view.problem.code == code
+ assert view.problem.effective_retry == retry
+ assert view.problem.next_step.detail == next_step
assert tailored_next_step(error=error) == next_step
- def test_an_upload_the_server_failed_is_a_server_fault(self) -> None:
- error = UploadTransportError('Upload of "a.pdf" failed (502): Bad Gateway.')
-
- view = describe_hosted_error(error=error)
+ def test_a_method_that_does_not_load_lists_the_verdict_s_items(self) -> None:
+ items = [ProblemItem.model_validate(item) for item in HostedRefusals.INVALID_METHOD_ITEMS]
+ error = HostedMethodInvalidError("The hosted API cannot load the method: Bundle does not load", errors=items)
- assert view.next_step == HOSTED_SERVER_FAULT_NEXT_STEP
- assert view.error_domain == "runtime"
+ view = describe_hosted_error(error=error, credential_sent=True)
- def test_a_failed_run_carries_its_id_and_its_validation_items(self) -> None:
- report = RunErrorReport.model_validate(
- {"error_type": "ValidateBundleError", "message": "bundle invalid", "validation_errors": [LABELLED_ITEM.model_dump(mode="json")]}
- )
- error = RunFailedError("Run finished with status FAILED: bundle invalid", run_id="run_9", status=RunStatus.FAILED, error=report)
-
- view = describe_hosted_error(error=error)
-
- assert view.pipeline_run_id == "run_9"
- assert view.validation_errors == (LABELLED_ITEM,)
-
- @pytest.mark.parametrize(
- "error",
- [
- RunTimeoutError("Run 'run_7' did not finish within 1200s", run_id="run_7", timeout_seconds=1200.0),
- MissingMainStuffError("Completed run 'run_7' returned no main stuff", run_id="run_7"),
- HostedRunPollingError("The run run_7 started on the hosted API, but following it failed", pipeline_run_id="run_7"),
- ],
- )
- def test_an_error_after_the_start_names_the_run(self, error: Exception) -> None:
- assert isinstance(error, (RunTimeoutError, MissingMainStuffError, HostedRunPollingError))
- view = describe_hosted_error(error=error)
-
- assert view.pipeline_run_id == "run_7"
- assert "run_7" in view.next_step
-
- def test_a_lost_run_is_not_reported_as_a_network_failure(self) -> None:
- error = HostedRunPollingError("The run run_7 started on the hosted API, but following it failed", pipeline_run_id="run_7")
-
- view = describe_hosted_error(error=error)
-
- assert view.error_type == "HostedRunPollingError"
- assert view.error_domain == "runtime"
- assert "may still be running" in view.next_step
-
- def test_a_method_that_does_not_load_carries_its_labelled_items(self) -> None:
- error = HostedMethodInvalidError("The hosted API cannot load the method: Bundle does not load", validation_errors=[LABELLED_ITEM])
-
- view = describe_hosted_error(error=error)
-
- assert view.error_type == "HostedMethodInvalidError"
- assert view.error_domain == "input"
- assert view.validation_errors == (LABELLED_ITEM,)
- assert view.pipeline_run_id is None
+ assert view.problem.code == "method.invalid"
+ assert view.problem.effective_domain == "method"
+ assert view.problem.errors == items
+ assert view.problem.pipeline_run_id is None
+ assert view.message == "The hosted API cannot load the method: Bundle does not load"
+ assert view.advice == "Fix the method as each of its errors says, then run it again"
def test_an_interrupted_wait_names_the_run_that_keeps_going(self) -> None:
- view = describe_hosted_error(error=HostedRunInterruptedError(pipeline_run_id="run_7"))
+ view = describe_hosted_error(error=HostedRunInterruptedError(pipeline_run_id="run_7"), credential_sent=True)
- assert view.error_type == "HostedRunInterruptedError"
- assert view.pipeline_run_id == "run_7"
- assert "run_7" in view.message
+ assert view.problem.code == "client.follow_failed"
+ assert view.problem.pipeline_run_id == "run_7"
+ assert view.message is not None
assert "keeps going" in view.message
- assert "run_7" in view.next_step
+ assert view.advice is not None
+ assert "run_7" in view.advice
def test_an_interruption_before_the_acknowledgement_points_at_the_run_history(self) -> None:
- view = describe_hosted_error(error=HostedRunInterruptedError(pipeline_run_id=None))
+ view = describe_hosted_error(error=HostedRunInterruptedError(pipeline_run_id=None), credential_sent=True)
- assert view.pipeline_run_id is None
- assert "run history" in view.next_step
+ assert view.problem.code == "client.outcome_unknown"
+ assert view.problem.pipeline_run_id is None
+ assert view.advice is not None
+ assert "run history" in view.advice
def test_a_start_lost_after_it_was_sent_points_at_the_run_history(self) -> None:
error = HostedRunOutcomeUnknownError("The connection to the hosted API failed after the run request was sent (ReadError: reset)")
- view = describe_hosted_error(error=error)
+ view = describe_hosted_error(error=error, credential_sent=True)
- assert view.error_type == "HostedRunOutcomeUnknownError"
- assert view.error_domain == "runtime"
- assert view.pipeline_run_id is None
- assert "run history" in view.next_step
- assert "network" not in view.next_step
+ assert view.problem.code == "client.outcome_unknown"
+ assert view.problem.effective_retry == "outcome_unknown"
+ assert view.problem.pipeline_run_id is None
+ assert view.advice is not None
+ assert "run history" in view.advice
+ assert "network" not in view.problem.next_step.detail
def test_a_local_file_for_a_method_with_an_address_dependency_points_at_a_url(self) -> None:
error = HostedLocalFileUploadUnavailableError(
"Local file upload is not available yet for methods with address-based dependencies, and the inputs name a local file"
)
- view = describe_hosted_error(error=error)
+ view = describe_hosted_error(error=error, credential_sent=True)
- assert view.error_domain == "input"
- assert "https URL" in view.next_step
+ assert view.problem.code == "request.unsupported"
+ assert view.problem.as_wire()["params"] == {"field": "inputs", "reason": LOCAL_FILE_WITH_ADDRESS_DEPENDENCY_UNSUPPORTED_REASON}
+ assert view.problem.effective_domain == "input"
+ assert view.advice is not None
+ assert "https URL" in view.advice
def test_a_blocking_route_timeout_warns_that_the_run_may_still_be_going(self) -> None:
"""Only a server that keeps no runs is called on the blocking route, so running again takes the same route and repeats a paid run."""
error = PipelineExecuteTimeoutError("POST /v1/execute was cut off after 31s", elapsed_seconds=31.0)
- view = describe_hosted_error(error=error)
+ problem = describe_hosted_error(error=error, credential_sent=True).problem
- assert "run it again" not in view.next_step
- assert "may still be going" in view.next_step
- assert PIPELEX_BASE_URL_ENV_KEY in view.next_step
- assert view.retryable is False
+ assert problem.code == "client.outcome_unknown"
+ assert problem.effective_retry == "outcome_unknown"
+ assert "run it again" not in problem.next_step.detail
+ assert "may still be going" in problem.next_step.detail
+ assert PIPELEX_BASE_URL_ENV_KEY in problem.next_step.detail
diff --git a/tests/unit/pipelex/hosted/test_hosted_run.py b/tests/unit/pipelex/hosted/test_hosted_run.py
index f7783a93f..20551b909 100644
--- a/tests/unit/pipelex/hosted/test_hosted_run.py
+++ b/tests/unit/pipelex/hosted/test_hosted_run.py
@@ -7,14 +7,15 @@ import httpx
import pytest
from mthds.protocol.input_form import PipeInputFormDescriptor
from mthds.protocol.models import VersionInfo
+from mthds.protocol.problem.registry import RetryVerdict
from pipelex_sdk.client import PipelexAPIClient
from pipelex_sdk.crate_models import CrateInvalidReport, PipeIORequest, PipeIOValidReport
from pipelex_sdk.errors import (
ApiResponseError,
ApiUnreachableError,
- MethodFileTransferCode,
MethodFileTransferError,
MethodFileTransferOperation,
+ MethodFileTransferReason,
MissingMainStuffError,
RunFailedError,
RunLifecycleUnavailableError,
@@ -22,9 +23,9 @@ from pipelex_sdk.errors import (
)
from pipelex_sdk.runs import PipelexRunResultStart, RunResults, RunStatus
from pipelex_sdk.upload import UploadRecord
-from pipelex_sdk.validation_models import ValidationErrorItem
from pydantic import ValidationError
+from pipelex.errors.problem import ProblemView
from pipelex.hosted.exceptions import (
HostedLocalFileUploadUnavailableError,
HostedMethodInvalidError,
@@ -72,7 +73,7 @@ def _invalid_report(*, verdict_json: str) -> CrateInvalidReport:
def _pipe_io_refusal(*, problem_json: str) -> ApiResponseError:
- """The error the client raises when `POST /v1/pipe-io` answers this problem document."""
+ """The error the client raises when `POST /v1/pipe-io` answers this problem document, which it reads as the problem."""
problem: dict[str, Any] = json.loads(problem_json)
return ApiResponseError(
f"API POST /v1/pipe-io failed (422): {problem['detail']}",
@@ -80,9 +81,7 @@ def _pipe_io_refusal(*, problem_json: str) -> ApiResponseError:
status=422,
status_text="Unprocessable Entity",
response_body=problem_json,
- server_message=problem["detail"],
- code=problem["code"],
- problem_document=problem,
+ headers={"content-type": "application/problem+json"},
)
@@ -216,7 +215,7 @@ class TestHostedRun:
@pytest.mark.asyncio
async def test_an_address_dependency_runs_with_inputs_naming_no_local_file(self, mocker: MockerFixture) -> None:
"""pipe-io loads no package nothing shipped; with no file to upload it is not asked, and the run route fetches the dependency."""
- client = _mocked_client(mocker, pipe_io_report=_invalid_report(verdict_json=HostedPipeIoVerdicts.UNSHIPPED_ADDRESS_DEPENDENCY_PROBLEM_ITEMS))
+ client = _mocked_client(mocker, pipe_io_report=_invalid_report(verdict_json=HostedPipeIoVerdicts.UNSHIPPED_ADDRESS_DEPENDENCY))
request = HostedRunRequest(contents=BUNDLE_CONTENTS, inputs={"item": "a widget"})
outcome = await run_hosted(client=client, request=request)
@@ -286,10 +285,9 @@ class TestHostedRun:
"verdict_json",
[
HostedPipeIoVerdicts.UNSHIPPED_ADDRESS_DEPENDENCY,
- HostedPipeIoVerdicts.UNSHIPPED_ADDRESS_DEPENDENCY_PROBLEM_ITEMS,
- HostedPipeIoVerdicts.UNSHIPPED_ADDRESS_DEPENDENCY_UNREADABLE_PROBLEM_ITEMS,
+ HostedPipeIoVerdicts.UNSHIPPED_ADDRESS_DEPENDENCY_AFTER_AN_UNREADABLE_ITEM,
],
- ids=["validation_errors", "problem_items", "unreadable_problem_items"],
+ ids=["problem_items", "after_an_unreadable_item"],
)
async def test_a_local_file_for_a_method_whose_address_dependency_was_not_shipped_is_refused_naming_it(
self, mocker: MockerFixture, tmp_path: Path, verdict_json: str
@@ -297,8 +295,8 @@ class TestHostedRun:
"""pipe-io loads only the packages shipped with the method, and answers a call into another one with its verdict.
The run route fetches that dependency, so the method is not at fault: the error names the dependency, read from
- the `method.dependency_missing` item's parameters in either shape of the verdict, from `validation_errors` when no
- item of `errors` reads, and the URL to use, never the verdict's advice to fix the method.
+ the parameters of the verdict's `method.dependency_missing` item, an item before it that does not read skipped,
+ and the URL to use, never the verdict's advice to fix the method.
"""
(tmp_path / "invoice.pdf").write_bytes(b"%PDF")
client = _mocked_client(mocker, pipe_io_report=_invalid_report(verdict_json=verdict_json))
@@ -319,7 +317,7 @@ class TestHostedRun:
@pytest.mark.asyncio
@pytest.mark.parametrize(
"verdict_json",
- [HostedPipeIoVerdicts.ADDRESS_DEPENDENCY_WORDS_ONLY, HostedPipeIoVerdicts.DEPENDENCY_CYCLE_PROBLEM_ITEMS],
+ [HostedPipeIoVerdicts.ADDRESS_DEPENDENCY_WORDS_ONLY, HostedPipeIoVerdicts.DEPENDENCY_CYCLE],
ids=["words_only", "dependency_cycle"],
)
async def test_a_verdict_naming_no_unshipped_dependency_is_the_method_s_fault(
@@ -354,20 +352,23 @@ class TestHostedRun:
client.start.assert_not_awaited()
@pytest.mark.asyncio
- async def test_a_method_that_does_not_load_is_refused_before_the_run_with_its_labelled_items(self, mocker: MockerFixture, tmp_path: Path) -> None:
- """pipe-io's verdict names each faulty file by its tree path, before any run starts."""
+ async def test_a_method_that_does_not_load_is_refused_before_the_run_with_its_items(self, mocker: MockerFixture, tmp_path: Path) -> None:
+ """pipe-io's verdict lists its faults as problem items, each naming its file by its tree path, before any run starts."""
(tmp_path / "invoice.pdf").write_bytes(b"%PDF")
- item = ValidationErrorItem.model_validate(
- {"category": "blueprint_validation", "message": "unknown concept Foo", "source": "lib/b.mthds", "pipe_code": "step2"}
- )
- invalid = CrateInvalidReport(is_valid=False, validation_errors=[item], message="Bundle does not load")
+ invalid = _invalid_report(verdict_json=HostedPipeIoVerdicts.UNKNOWN_MODEL)
client = _mocked_client(mocker, pipe_io_report=invalid)
request = HostedRunRequest(contents=BUNDLE_CONTENTS, inputs={"document": "invoice.pdf"}, inputs_base_dir=tmp_path)
with pytest.raises(HostedMethodInvalidError) as exc_info:
await run_hosted(client=client, request=request)
- assert exc_info.value.validation_errors == [item]
+ assert exc_info.value.errors == invalid.errors
+ assert [item.code for item in exc_info.value.errors] == ["model.unknown"]
+ assert exc_info.value.errors[0].location is not None
+ assert exc_info.value.errors[0].location.file == "lib/b.mthds"
+ problem = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert problem.code == "method.invalid"
+ assert problem.errors == invalid.errors
assert "Bundle does not load" in exc_info.value.message
client.upload_file.assert_not_awaited()
client.start.assert_not_awaited()
@@ -377,7 +378,7 @@ class TestHostedRun:
"follow_error",
[
ApiUnreachableError(
- "Could not reach Pipelex API at https://hosted.test (ConnectError)", api_url="https://hosted.test", code="ConnectError"
+ "Could not reach Pipelex API at https://hosted.test (ConnectError)", api_url="https://hosted.test", network_code="ConnectError"
),
httpx.RemoteProtocolError("server disconnected"),
json.JSONDecodeError("Expecting value", "<html>Bad gateway</html>", 0),
@@ -508,7 +509,8 @@ class TestHostedRun:
) -> None:
"""No byte of the start left this machine, as the SDK reads the failure, so no run exists: checking the network is the right advice."""
sdk_error = await _sdk_transport_failure(transport_error=transport_error)
- assert sdk_error.run_may_have_started is False
+ # `client.unreachable` or `client.timeout`, both of which a retry may pass: no run may exist.
+ assert sdk_error.problem.effective_retry == RetryVerdict.YES
client = _mocked_client(mocker)
client.start.side_effect = sdk_error
@@ -517,7 +519,7 @@ class TestHostedRun:
assert exc_info.value is sdk_error
assert exc_info.value.api_url == "https://hosted.test"
- assert exc_info.value.code == expected_code
+ assert exc_info.value.network_code == expected_code
assert str(exc_info.value).startswith("Could not reach Pipelex API at https://hosted.test")
@pytest.mark.asyncio
@@ -543,7 +545,8 @@ class TestHostedRun:
request never left.
"""
sdk_error = await _sdk_transport_failure(transport_error=transport_error)
- assert sdk_error.run_may_have_started is True
+ assert sdk_error.problem.code == "client.outcome_unknown"
+ assert sdk_error.problem.effective_retry == RetryVerdict.OUTCOME_UNKNOWN
bare_version = '{"protocol_version":"0.1.0","implementation":"pipelex-api","implementation_version":"0.76.0"}'
client = _mocked_client(mocker, version=bare_version) if bare_runner else _mocked_client(mocker)
client.start.side_effect = sdk_error
@@ -565,7 +568,7 @@ class TestHostedRun:
transfer_error = MethodFileTransferError(
"Uploading the file with SHA-256 abc to storage failed (503 Service Unavailable), so the run was not started.",
operation=MethodFileTransferOperation.UPLOAD,
- code=MethodFileTransferCode.STORAGE_ERROR,
+ reason=MethodFileTransferReason.STORAGE_ERROR,
sha256="abc",
status=503,
)
@@ -593,7 +596,7 @@ class TestHostedRun:
assert requested == ["GET /v1/version", "POST /v1/start"]
cause = exc_info.value.__cause__
assert isinstance(cause, ApiUnreachableError)
- assert cause.run_may_have_started is True
+ assert cause.problem.code == "client.outcome_unknown"
assert f"ReadError: {CONNECTION_RESET}" in exc_info.value.message
@pytest.mark.asyncio
@@ -612,7 +615,7 @@ class TestHostedRun:
assert "POST /v1/blobs/missing" in requested
assert "POST /v1/start" not in requested
- assert exc_info.value.run_may_have_started is False
+ assert exc_info.value.problem.code == "client.unreachable"
assert isinstance(exc_info.value.__cause__, httpx.ReadError)
@pytest.mark.parametrize(
diff --git a/uv.lock b/uv.lock
index 4a67d97fb..65eb05bfb 100644
--- a/uv.lock
+++ b/uv.lock
@@ -3747,7 +3747,7 @@ requires-dist = [
{ name = "opentelemetry-semantic-conventions", specifier = ">=0.59b0" },
{ name = "packaging", specifier = ">=24.0" },
{ name = "pillow", specifier = ">=12.1.1" },
- { name = "pipelex-sdk", specifier = "==0.48.0" },
+ { name = "pipelex-sdk", specifier = "==0.53.0" },
{ name = "pipelex-tools", marker = "extra == 'dev'", specifier = ">=0.7.2" },
{ name = "pipelex-tools-py", specifier = ">=0.1.3" },
{ name = "polyfactory", specifier = ">=2.21.0" },
@@ -3859,7 +3859,7 @@ provides-extras = ["dev"]
[[package]]
name = "pipelex-sdk"
-version = "0.48.0"
+version = "0.53.0"
source = { registry = "https://pypi.org/simple" }
dependencies = [
{ name = "httpx" },
@@ -3867,9 +3867,9 @@ dependencies = [
{ name = "pydantic" },
{ name = "typing-extensions" },
]
-sdist = { url = "https://files.pythonhosted.org/packages/7d/2e/decbb96df27e6aab6442f19737d986e8416ff0b5b84ff75246afc10e49e8/pipelex_sdk-0.48.0.tar.gz", hash = "sha256:e9cc8921174e67e9f1f70eb3f8ec6bd005b3ffed550b61eed864f2493597c859", size = 695789, upload-time = "2026-10-20T09:19:03.443Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/cd/21/83417e62e4a5387561382f922db0e48df2679cefe7135b88b4f728bcd73a/pipelex_sdk-0.53.0.tar.gz", hash = "sha256:2324a6f478965123e2c2920d4eef97bef2f1990534a6e5224524d083020ec8e3", size = 751851, upload-time = "2026-10-25T09:39:52.315Z" }
wheels = [
- { url = "https://files.pythonhosted.org/packages/7f/20/8e5f44348090854b5e207188b3be3480eb4af0e2f89b30c4a6630dad81df/pipelex_sdk-0.48.0-py3-none-any.whl", hash = "sha256:e992714e25f6a5fa91465d0788b51bc4341149deeb95c2963146350939295dcf", size = 273538, upload-time = "2026-10-20T09:19:01.523Z" },
+ { url = "https://files.pythonhosted.org/packages/ec/19/7b1c826c04304b6855e56428f52fbe3f780fdfa0e03c1cdff823cb0c5981/pipelex_sdk-0.53.0-py3-none-any.whl", hash = "sha256:3758edc0b631bc9d995d8cf1f225633069a2046e8ef969bd4bb91d68c6013662", size = 288276, upload-time = "2026-10-25T09:39:50.431Z" },
]
[[package]]