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/Agent-reads-runner-problem · L-261017-c5e0cc (#1457)

Louis Choquel9beb852ded59
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index c8507d873..3a0324fd1 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:e9cbbf01620b3bae6f72a1088181ca0ffed8b850692d4afdcc6ebf378ee9853a"
-reviewed_by = "Louis Choquel"
-reviewed_at = "2026-10-18T17:28:48Z"
-rationale = "real-catch: the review-pass fixes list a lone bundle file's tree before run bundle reads it, report an OSError naming no file as runtime.unexpected rather than client.file_unreadable, give init's missing configuration files pipelex.config.file_missing and tip a preset failure with the boot's recovery path; docs/tools/cli/agent-cli.md and pipelex/cli/agent_cli/CLAUDE.md now say so."
+digest = "sha256:f12599081f3831f2ebae7ad28de4e2436c382329d3854286f89152335a63b0b5"
+reviewed_by = "Claude Opus 5.5"
+reviewed_at = "2026-10-18T18:18:07Z"
+rationale = "clean-pass: the merge of the base's review fixes (init's pipelex.config.file_missing, an OSError naming no file as runtime.unexpected, a lone bundle file's tree listed before it is read) into this branch's hosted-run problem reporting; each side had already brought docs/tools/cli/agent-cli.md and pipelex/cli/agent_cli/CLAUDE.md in line with its own changes, and the merged docs carry both."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -11,7 +11,7 @@ rationale = "real-catch: the review-pass fixes list a lone bundle file's tree be
"pipelex/cli/agent_cli/_agent_cli.py" = "blob:3d46a1eb5afc34834de17c46ed8b468c67cc4624"
"pipelex/cli/agent_cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:422ae48a8d4eb9b2e33dc2e6a8ca608d205e5f59"
-"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:f082a1e4ca73ae30f54db44d4a8e1ba532be2f6f"
+"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:03307ca018ed9f93f3c4aeeb164eb12032306dc8"
"pipelex/cli/agent_cli/commands/bundle_path_resolver.py" = "blob:beff9f679a2aeb29ba7213312026d80dacf4264b"
"pipelex/cli/agent_cli/commands/check_model_cmd.py" = "blob:fb66f68166671db207efbb8e974bc4e7c24915a5"
"pipelex/cli/agent_cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
@@ -38,7 +38,7 @@ rationale = "real-catch: the review-pass fixes list a lone bundle file's tree be
"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:d71aee873856cfa72eb0ff18eb82c79e348f124a"
-"pipelex/cli/agent_cli/commands/run/_run_hosted.py" = "blob:e1b309868a9bf92e5fdae06d646d995a3758a9c0"
+"pipelex/cli/agent_cli/commands/run/_run_hosted.py" = "blob:cd2b8dda59e076f1023d3b20d7c239b3674c3f2e"
"pipelex/cli/agent_cli/commands/run/app.py" = "blob:7546d9b31ea2dc22b1ddae538edfbc8e7f7d08df"
"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:e8976dd91908262d8d7d5bf2d2e4e11c978a3f3b"
"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:0df77aa1e35c22ceffdcefd7f4c12f28fda366c7"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d54307ccf..963d0691d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,7 +36,7 @@
- **A truncated completion says which limit cut it**: `LLMCompletionTruncatedError` carries `model.output_truncated` when the method's `max_tokens` cut the answer and `model.context_exceeded` when the context window did, both the method's to change.
- **`ModelDeckPresetValidationError` is spelt right (Breaking)**: the error a model deck preset that fails validation raises was `ModelDeckPresetValidatonError`, and its reports carried that `error_type`; a consumer that branched on the old name branches on the new one, or on its code, `pipelex.config.invalid`.
- **Usage statistics carry the error's code (Breaking)**: a failed `command_completed` or `run_completed` carries the code of its error in `error_code` and that code's domain in `error_domain`, now one of `input`, `method`, `account`, `operator` and `runtime` where it read `input`, `config`, `runtime` or `other`, and a `model_used` counts its failed calls by the domain of their code, in `failures_input`, `failures_method`, `failures_account`, `failures_operator` and `failures_runtime`, where it counted them by the runtime's inference category, which no event carries any more. A failed hosted run's `command_completed` carries the code and the domain the hosted API sent, and none when it sent none, and every surface reads a refusal a server answered by that rule, a run's `run_completed` reading the catch-all where nothing was sent rather than the code the client infers from the status. Every event's `schema` is 2, so a receiver tells these events from an earlier release's.
-- **`pipelex-agent` reports a failure as its problem (Breaking)**: the agent CLI's error stream is the failure's problem in the operator's view, Markdown by default and JSON with `--error-format json`: its `code`, `domain`, `retry` verdict and `next_step`, its `params`, `location` and `errors`, its `request_id` and `pipeline_run_id`, and `diagnostics` with the error's class, the model and the provider of a failed call and a pending configuration migration, which rides `diagnostics.migration` where it rode `migration`, beside the command's own `message` and members. The envelope's `error`, `error_type`, `error_domain`, `error_code`, `error_category`, `retryable`, `hint`, `validation_errors`, `error_source`, and a failed run's `pipe_code`, `pipe_stack`, `cause_type` and `cause_message`, are gone, and so are `AGENT_ERROR_HINTS`, `AGENT_ERROR_DOMAINS`, `AGENT_INIT_FAILURE_HINT`, `run_failure_fields()` and `extract_validation_errors()`: an agent branches on `code`, an invalid verdict's items are the problem's `errors`, a failed run is located by `location.pipe` and `location.path`, and the advice an error's chain gives is a Markdown tip, a boot that fails with no advice of its own tipping the recovery path through `doctor`, `migrate` and `init`. A refusal the CLI makes itself carries its own code, `client.argument_invalid` for an argument, `client.file_unreadable` for a file it cannot read, the bundle file of every bundle command included, `client.tool_missing` when `plxt` is not installed, and `pipelex.config.file_missing` when `init` finds a configuration file it should have written missing, and an exception that is no Pipelex error reads `runtime.unexpected`, an error of the system that names no file, such as a refused connection or a timeout, included. A bundle file that is not UTF-8 text does not parse, so `run bundle` and `fix bundle` report it as `validate bundle` does, the invalid verdict with a `method.syntax` item, where `run bundle` read it as a file it could not read; `fix bundle` codes the errors left as `validate bundle` codes them, where an item no stage classified read `method.schema_violation`, and a fix it cannot write is `client.write_failed`. A hosted run's failure keeps the envelope it had, for now; what the CLI refuses before sending it is a problem.
+- **`pipelex-agent` reports a failure as its problem (Breaking)**: the agent CLI's error stream is the failure's problem in the operator's view, Markdown by default and JSON with `--error-format json`: its `code`, `domain`, `retry` verdict and `next_step`, its `params`, `location` and `errors`, its `request_id` and `pipeline_run_id`, and `diagnostics` with the error's class, the model and the provider of a failed call and a pending configuration migration, which rides `diagnostics.migration` where it rode `migration`, beside the command's own `message` and members. The envelope's `error`, `error_type`, `error_domain`, `error_code`, `error_category`, `retryable`, `hint`, `validation_errors`, `error_source`, and a failed run's `pipe_code`, `pipe_stack`, `cause_type` and `cause_message`, are gone, and so are `AGENT_ERROR_HINTS`, `AGENT_ERROR_DOMAINS`, `AGENT_INIT_FAILURE_HINT`, `run_failure_fields()` and `extract_validation_errors()`: an agent branches on `code`, an invalid verdict's items are the problem's `errors`, a failed run is located by `location.pipe` and `location.path`, and the advice an error's chain gives is a Markdown tip, a boot that fails with no advice of its own tipping the recovery path through `doctor`, `migrate` and `init`. A refusal the CLI makes itself carries its own code, `client.argument_invalid` for an argument, `client.file_unreadable` for a file it cannot read, the bundle file of every bundle command included, `client.tool_missing` when `plxt` is not installed, and `pipelex.config.file_missing` when `init` finds a configuration file it should have written missing, and an exception that is no Pipelex error reads `runtime.unexpected`, an error of the system that names no file, such as a refused connection or a timeout, included. A bundle file that is not UTF-8 text does not parse, so `run bundle` and `fix bundle` report it as `validate bundle` does, the invalid verdict with a `method.syntax` item, where `run bundle` read it as a file it could not read; `fix bundle` codes the errors left as `validate bundle` codes them, where an item no stage classified read `method.schema_violation`, and a fix it cannot write is `client.write_failed`. The Markdown lists the problem's items one per line, each with its code, sentence, location, suggestions and suggested fix, an invalid verdict's included, where it rendered a verdict's items as `validate`'s category-grouped prose. A run on a runner (`--runner hosted`) that fails reports the problem the runner answered or the client decided, as it came, by the members the standard and Pipelex declare alone, in the caller's view: the runner's problem document with its `errors`, `client.unreachable` naming the base URL for a runner that cannot be reached, `client.outcome_unknown` for a server fault on the run request, and `run.failed` naming the run for a run that started and failed, the client's own sentence as `message`, nesting the run's own problem as `run_error` in the caller's view, read off its stored report whatever its shape; an answer in the 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` when no key was sent, `auth.forbidden` for an operation the platform refuses a key it accepted, under one of its authorization codes, `request.not_found`, `run.not_found` or `method.not_found`, or `account.rate_limited` with its `retry_after`, a runner's refusal of a method that does not validate lists its validation items under `method.invalid`, and any other such answer keeps the client's `client.response_unreadable` with the reason it gave; each takes the next step `pipelex run --hosted` gives, of the kind the answer's advice names when it gave one, and so does a failure the client meets on its own side; what the CLI refuses before sending it is a problem in the operator's view, and so is a failure of its own, under its own code.
- **The `pipelex` error panels print the problem**: a panel names the problem's title, its detail, its next step, its code with its domain and retry verdict, its location and its request id beside the fields it printed, and a run that fails, or any failure a command root catches, prints its problem the same way on stderr, where it printed one line with the message. Every panel, an invalid bundle's, an unavailable model's or a telemetry file's included, and the stack trace `--traceback` adds to it, now goes to stderr, where the panels and their stack traces went to stdout, so a command's piped output holds only what it produced.
- **A configuration refusal names its setting and its file**: `pipelex.config.invalid` raised for a configuration that does not validate, a telemetry configuration, a tracing sink or what a former release left in the inference configuration names the setting, its file and the configuration it belongs to in the operator's next step, a file the refusal can single out, a former release's or one that does not parse (`pipelex.config.syntax`, where `pipelex show config` named `pipelex.toml` whichever layer failed), named relative to the working directory or as `~/…` under the home directory, never with the home directory's account, and its advice, the tip a CLI prints, follows the pending migration, `pipelex migrate` when it would rewrite the files and a correction by hand when it would not, and else the refusal's code: `pipelex init` for a missing file, setting the variable for one that is not set, and `pipelex doctor` for a configuration that does not validate or parse. The refusal of what a former release left carries in `diagnostics.migration` what `pipelex migrate` would do about it, from the cleanup's dry run, so a JSON reader, who gets no tip, reads the remedy too.
- **A pipe's failure line carries its code, not its text**: `The execution of a pipe failed` carries the problem's `error.code` beside `error.type` and no longer `error.message`, so a log query selects failed pipes by code, and the line holds neither the caller's own text, a function's message or a template's source, nor a refused host.
@@ -50,7 +50,7 @@
- **A host library that refuses to load is the deployment's fault**: a method of a server's own library directories that refuses to load beside a caller's bundles raises `HostLibraryLoadRefusalError`, carrying `pipelex.config.invalid`, which an API answers with a 500 whose message reaches the operator's diagnostics alone, where it answered the caller a 422 verdict carrying the host library's text; the same refusal in the caller's own content, or in library directories the caller owns, stays the caller's 422 verdict.
- **A template error found only at render is a located refusal**: a template naming a filter or a test that does not exist, which Jinja2 only finds when the branch renders, fails the run at the pipe with `Jinja2TemplateInvalidError`, naming the unknown filter or test and none of the template, coded `method.template_invalid`, a 422, when the template is the method's, in a `PipeCondition` expression, a `PipeLLM` prompt or system prompt and a `PipeDocGen` template, and `runtime.unexpected` when it is one of Pipelex's own, such as the deployment's structure prompt rendered in a `PipeLLM` step, where it failed as an unclassified 500. A filter refusing its argument, which may be a value of the run's data, is `pipe.template_render_failed` rather than the template's fault.
- **A failure's message is bounded**: the error's message a problem carries in `diagnostics.message`, a provider's answer and every text parameter are cut at 2,000 characters, ending in ` […]`, so an oversized exception cannot swell a response, a stored run or a log line.
-- **A dry run failing on a fault of the runtime's is no verdict**: validating a method whose dry run fails only on faults that are not the method's, such as a storage outage or an unexpected error, answers the first of those faults' codes, every failure listed in `errors`, where it answered `method.invalid` and blamed the method; a verdict needs one failure in the method's domain, and the first fault is chosen with a `no` retry verdict before a retryable one, then the operator's before the account's, the input's and the runtime's, the answer's sentence rendered from the failure whose code it takes. A mock value a routed pipe cannot build, a pydantic or polyfactory refusal, stays the method's `method.mock_unsatisfiable`. A refusal met while loading that is not the method's keeps its own class and code in the same way, so `pipelex run bundle` and `pipelex-agent run bundle` on a folder whose bundles declare no single `main_pipe` print the run's refusal, `request.pipe_unspecified` or `request.pipe_ambiguous`, where they printed an invalid verdict. `POST /v1/pipe-io` answers a method calling another one by its address with the `422` problem `request.unsupported`, whose `params.reason` is `address_based_dependency`, where it answered an invalid verdict, and a hosted run whose inputs name a local file reads that refusal from the code and the reason, its message no longer naming the dependency.
+- **A dry run failing on a fault of the runtime's is no verdict**: validating a method whose dry run fails only on faults that are not the method's, such as a storage outage or an unexpected error, answers the first of those faults' codes, every failure listed in `errors`, where it answered `method.invalid` and blamed the method; a verdict needs one failure in the method's domain, and the first fault is chosen with a `no` retry verdict before a retryable one, then the operator's before the account's, the input's and the runtime's, the answer's sentence rendered from the failure whose code it takes. A mock value a routed pipe cannot build, a pydantic or polyfactory refusal, stays the method's `method.mock_unsatisfiable`. A refusal met while loading that is not the method's keeps its own class and code in the same way, so `pipelex run bundle` and `pipelex-agent run bundle` on a folder whose bundles declare no single `main_pipe` print the run's refusal, `request.pipe_unspecified` or `request.pipe_ambiguous`, where they printed an invalid verdict. A hosted run whose inputs name a local file tells `POST /v1/pipe-io`'s verdict on a method calling a package by its address that the request did not ship apart from a fault of the method by the verdict's `method.dependency_missing` item of the kind `package`, naming the package its `params.name` gives, where it matched the words of the item's message.
- **A provider's 408 is retried**: a provider answering HTTP 408, that it gave up waiting, is a transient failure carrying `provider.timeout`, so the call is repeated within the run, a billed image call included, where it was read as the caller's input and the run failed on its first attempt.
- **A `PipeFunc` returning a list of anything but stuff contents fails its output**: a function returning a list that holds a value other than a stuff content, such as a dict or a number, fails the step with `FuncOutputTypeError` (`pipe.output_invalid`), where a dict became an empty content and any other value failed as though the function had raised.
- **A CLI command's unexpected failure logs no run data**: the root of `pipelex run` and of `pipelex graph render` logs an unexpected failure with the code of its problem, its class, the classes along its cause chain and the frames it went through, each by its module, line and function with no source line or local (`error.frames`), where it attached the exception, whose traceback printed the text of every chained exception, a foreign `ValidationError` quoting the values it refused or a method function's exception included; the traceback rides the record only under `--traceback`, and the terminal prints the failure's message capped.
diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.md
index 3bf5e8c11..e8a450edc 100644
--- a/docs/tools/cli/agent-cli.md
+++ b/docs/tools/cli/agent-cli.md
@@ -59,7 +59,7 @@ With `--runner hosted` (or `--hosted`, or `[run] execution = "hosted"`), the run
The success envelope has the shape of a local run's. Compact, it is the main output's content. With `--with-memory`, `main_stuff.json` is that content (the hosted API renders no Markdown, so the markdown output shows the JSON), `working_memory` is the whole working memory, `pipeline_run_id` names the run on the hosted API, and `uploads` lists the files uploaded for it. A hosted run writes nothing to disk.
-A run refuses an invalid bundle while loading it, before any pipe runs, with exit code `1` and the problem `method.invalid`, whose `errors` hold the items `validate` gives for that bundle, each with its code, its location (its pipe, its field) and its suggested fix when it has one. A refusal found while loading a library directory you pass with `-L` (or the method's folder, for `run bundle <dir>`) is reported the same way, its items naming their file in `location.file`; a bundle file run on its own is loaded from its text, so the items of a refusal found while loading it name no file, while a bundle that does not parse when `run bundle` looks for its `main_pipe` (no `--pipe`) names its file. In markdown, the items render as the same grouped prose `validate` prints. The items come from the verdict on the error's own chain of Pipelex errors: a failure of another kind raised while handling an earlier verdict, such as an unexpected error, lists none of that verdict's items.
+A run refuses an invalid bundle while loading it, before any pipe runs, with exit code `1` and the problem `method.invalid`, whose `errors` hold the items `validate` gives for that bundle, each with its code, its location (its pipe, its field) and its suggested fix when it has one. A refusal found while loading a library directory you pass with `-L` (or the method's folder, for `run bundle <dir>`) is reported the same way, its items naming their file in `location.file`; a bundle file run on its own is loaded from its text, so the items of a refusal found while loading it name no file, while a bundle that does not parse when `run bundle` looks for its `main_pipe` (no `--pipe`) names its file. In markdown, the items are listed one per line under `### Errors`, as the JSON lists them. The items come from the verdict on the error's own chain of Pipelex errors: a failure of another kind raised while handling an earlier verdict, such as an unexpected error, lists none of that verdict's items.
!!! note "Stdin inputs stay JSON"
The agent CLI can also read inputs from stdin (a flat dict or a `working_memory` envelope). Stdin inputs are **JSON-only** — the extension-based TOML discrimination applies to `--inputs` file paths only. Like the main CLI, `run bundle <dir>` auto-detects `inputs.json` / `inputs.toml` when `--inputs` is omitted, erroring if both exist, and refuses one that is not a regular file, such as a symbolic link, which it never follows, with the problem `request.invalid` naming the field `inputs`; a file named with `--inputs` is read as given, a link followed. In a `working_memory` envelope each stuff must name its concept as the ref string; anything else there — the full concept object an older runtime dumped, for instance — is refused with the problem `client.argument_invalid`, its `params.argument` being `stdin` and its `params.reason` naming the member that does not hold the shape the contract asks for, as distinct from the reason `not valid JSON`, which means the JSON itself did not parse.
@@ -97,7 +97,7 @@ For `bundle`, additional options are available:
On a successful run, the envelope also carries `pending_signatures` — the library-wide list of pipes still declared as `PipeSignature` (unimplemented forward declarations), each namespaced by `pipe_ref` (`domain.code`). In JSON it is a `pending_signatures` array, in markdown a "Pending signatures" section. A top-down build reads it to see exactly which headers remain to implement. The envelope also carries a derived `is_runnable` boolean (`true` ⇔ `pending_signatures` is empty), and the markdown states the runnability verdict in plain English — runnable when complete, NOT yet runnable above the "Pending signatures" section otherwise. `validate bundle`, `validate method`, and `validate pipe --all` carry them and gate on them: without `--allow-signatures`, the command exits non-zero when `is_runnable` is false. Bare `validate pipe <code>` omits them, and a `--pipe` slice surfaces them for information without gating.
!!! note "Every refusal of the bundle is an invalid verdict"
- A refusal of your input raised while the bundle is loaded or validated is answered with the invalid verdict — the problem `method.invalid` with `is_valid: false`, its faults in `errors` — and exit code `1`, never a no-verdict failure and exit code `2`, which is kept for failures of the tool or its environment. Each item carries its own `code`, the sentence that code renders as its `detail`, its `params`, its `location` (its `pipe`, its `field`, its `file`, and for a TOML syntax error its 1-based `line` and `column`) and, when there is one, its `suggested_fix`. A pipe whose dry run fails gives one item per failing pipe, coded by its failure and located at the innermost pipe that failed and is not allowed to fail (its file whenever the pipe is in your files; a validator of submitted content beside a host's library directories names only that content's files), with the sentence the failure's code renders for a caller, never the failure's own text, on `validate bundle`, `validate pipe <code>` and `validate pipe --all` alike; a controller that failed because a pipe it runs failed is reported once, at that pipe. Every error found while parsing is its own item, so a misspelled field is reported beside the categorized errors as an item of its own, located at its pipe and its file. An undeclared concept gives a `method.concept_unresolved` item whose `params.concept` names it. A pipe naming a model the model deck does not define gives one `model.unknown` item located at the pipe's `model` field, its `params` naming the reference as written and its `suggestions` the deck's close matches, plus a `rename-model` `suggested_fix` when there is exactly one suggestion. That fix's `safety` is `unsafe`, because a close name can still be a different model: `fix bundle` never applies it, and the Markdown labels it `💡 Suggested fix (unsafe, confirm before applying):` where a safe fix reads `💡 Suggested fix:`. Any other refusal of your input with no code of its own gives one item with the refusal's code, located on its pipe when it was raised while that pipe was built. A pipe factory's refusal, such as a `PipeExtract` whose input is neither an image nor a document, is one of these items, located on its pipe. In Markdown the items read as the same grouped prose `validate` prints. See [Error Model](../../under-the-hood/error-model.md).
+ A refusal of your input raised while the bundle is loaded or validated is answered with the invalid verdict — the problem `method.invalid` with `is_valid: false`, its faults in `errors` — and exit code `1`, never a no-verdict failure and exit code `2`, which is kept for failures of the tool or its environment. Each item carries its own `code`, the sentence that code renders as its `detail`, its `params`, its `location` (its `pipe`, its `field`, its `file`, and for a TOML syntax error its 1-based `line` and `column`) and, when there is one, its `suggested_fix`. A pipe whose dry run fails gives one item per failing pipe, coded by its failure and located at the innermost pipe that failed and is not allowed to fail (its file whenever the pipe is in your files; a validator of submitted content beside a host's library directories names only that content's files), with the sentence the failure's code renders for a caller, never the failure's own text, on `validate bundle`, `validate pipe <code>` and `validate pipe --all` alike; a controller that failed because a pipe it runs failed is reported once, at that pipe. Every error found while parsing is its own item, so a misspelled field is reported beside the categorized errors as an item of its own, located at its pipe and its file. An undeclared concept gives a `method.concept_unresolved` item whose `params.concept` names it. A pipe naming a model the model deck does not define gives one `model.unknown` item located at the pipe's `model` field, its `params` naming the reference as written and its `suggestions` the deck's close matches, plus a `rename-model` `suggested_fix` when there is exactly one suggestion. That fix's `safety` is `unsafe`, because a close name can still be a different model: `fix bundle` never applies it, and the Markdown labels it `unsafe, confirm before applying` beside its fix code, where a safe fix is labelled `safe`. Any other refusal of your input with no code of its own gives one item with the refusal's code, located on its pipe when it was raised while that pipe was built. A pipe factory's refusal, such as a `PipeExtract` whose input is neither an image nor a document, is one of these items, located on its pipe. In Markdown the items are listed one per line under `### Errors`, each with its code, its sentence, its location, its suggestions and its suggested fix. See [Error Model](../../under-the-hood/error-model.md).
!!! note "Advisory warnings on validate"
Whole-bundle and whole-library validate surfaces (`validate bundle`, `validate method`, `validate pipe --all`) also carry a `warnings` array — advisory findings on a VALID bundle that never flip the verdict or the exit code. Each entry has the **same shape as a validation error item** (`category`, `error_type`, `pipe_code`, `domain_code`, `variable_names`, `message`) — this is a different shape from the `init`/`doctor` setup `warnings` (`{type, message}`) documented under Output Contract below. Four families ride the array, always in this order: the useless-`!` lint (`optional_force_redundant`), a `!` (force) input whose slot is guaranteed present in every analyzed flow, so the assertion can never fire; the vacuous-presence lint (`input_presence_vacuous`), an entry-pipe input that must be supplied but whose concept declares no required field, so the empty object satisfies it and a caller cannot tell what to fill in (see [Understanding Optionality](../../building-methods/pipes/understanding-optionality.md)); the [intent-hint](../../building-methods/concepts/intent-hints.md) lints (`hint_unknown_key`, `hint_unknown_intent`, `hint_inapplicable_intent`); and the warnings of a [`PipeDocGen`](../../building-methods/pipes/pipe-operators/PipeDocGen.md#office-template-files) step's template check (`template_check_warning`), found by the engine in the step's office template file during the dry run, as a `dry_run` item that also carries `template_file` (the file as the step names it) and `template_location` (the place in it, in the engine's words, absent when the engine names none). Every whole-bundle validate channel — this CLI, the bare CLI and the protocol validation report — assembles them from one composition point, so which advisories you see does not depend on which command you typed. Hint findings are bounded per site: a site naming many undefined keys reports the first few and then how many more there were, and a long authored key or value is elided in the message. In markdown, warnings render as a "Warnings" section. The array is empty when there is nothing to report. `validate pipe <code>` carries the template-check warnings alone: one pipe has no flow context to lint in, but what its dry run found is about that pipe. `validate bundle`/`validate method` with `--pipe` keep it, and it stays bundle-wide there — the slice narrows the dry run, not the validation.
@@ -200,7 +200,7 @@ Commands use different stdout formats depending on their purpose:
JSON commands return the result object directly. They are not wrapped in a `status` or `data` envelope.
-**Error** — written to stderr, one problem per failure. In JSON it is the problem document, the error document of the MTHDS standard that the hosted API answers too, in the operator's view, since whoever runs this CLI runs the runtime:
+**Error** — written to stderr, one problem per failure. In JSON it is the problem document, the error document of the MTHDS standard that the hosted API answers too, in the operator's view, since whoever runs this CLI runs the runtime, except for a run on a runner, whose failure is the runner's or the client's problem in the caller's view (see below):
```json
{
@@ -224,15 +224,22 @@ For the structured commands, exactly one problem is written to stderr per failur
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`.
-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 (an invalid verdict's items as the same grouped prose `validate` prints), a `### Diagnostics` section and the command's own members under `### Details`. No stack frame is printed in either format.
+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.
**A failed run** (`run pipe`, `run bundle`, `run method`) reports the problem of the root fault, the innermost Pipelex error behind the failure, located at the pipe that failed: `location.pipe` names it and `location.path` its path from the entry pipe. The `message` is that root fault's message prefixed with the failing pipe and its path (`Pipe 'summarize' failed (two_steps → summarize): …`), and the code, the domain, the retry verdict and the next step are the root fault's, so branch on `code` to tell, say, a model that is not available from a failure to combine a parallel's results. A failed inference call carries its model and its provider in `diagnostics.model` and `diagnostics.provider`.
-**A hosted run** (`--runner hosted`) keeps, for now, the envelope this CLI wrote before it reported problems: a refusal the hosted API answers, a run that started and failed, and a run that failed on the way are written as `{"error": true, "error_type": …, "message": …, "error_domain": …, "error_code": …, "hint": …, "retryable": …}` with `validation_errors`, `pipeline_run_id`, `http_status` and `request_id` when they apply, and an interrupted hosted run (Ctrl-C) exits with `130` and the envelope `HostedRunInterruptedError`. 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. The hosted failures read as follows.
+**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 failures of the run itself read as follows.
-**A run the hosted API refuses** (`--runner hosted`, when the hosted API answers with a non-2xx status) reports what its problem document says in that envelope, rendered in Markdown as `# Error: <error_type>` with the hint as a `💡` callout. `error_type` is the runner's error class: `ValidateBundleError` for a bundle refused before any pipe ran, as a local run reports it, or the root fault of a run that failed, such as `ModelNotFoundError` or `StuffFactoryError`, which a local run reports as `cause_type` under the `error_type` `PipelineExecutionError`. There is no `cause_type` on this path, so a consumer of a refused hosted run branches on `error_type`, which is `ApiResponseError` when the answer names no class, as a gateway's error page does not. The `message` quotes the request, the status and the runner's reason (`API POST /v1/start failed (422): Pipe 'condense_article' failed (digest_article → condense_article): …`), so on a failed run it names the failing pipe and its path. The `hint` is the runner's next step; `error_domain`, `error_category` and `retryable` are the runner's own; `validation_errors` holds the runner's items, rendered in markdown as the same grouped prose `validate` prints; `pipe_code` and `pipe_stack` appear when the problem document carries them; `error_code` is the problem's `code`, the registry code a local failure carries in the same member, or the code the hosted plane gives a refusal it authors itself in front of the runner; `retry_after_seconds` is the delay of a `Retry-After` header; and `http_status` and `request_id` are what to quote when the fault is the runner's. When the answer advised no next step, the `hint` follows its status, never the local advice kept for the runner's class: a 401 or a 403 points at `PIPELEX_API_KEY` and `pipelex login`; a 404 points at the method's address or id and at the origin (`--base-url`, else `PIPELEX_BASE_URL`, else `https://api.pipelex.com`, with no path such as `/v1`); a 429 says to wait and run again and marks the error `retryable` unless the answer said otherwise; a 503 says to wait too but warns that running again can repeat a paid run, because the service in front of the runner can answer it after the run completed, so it is `retryable` only when the answer says so; any other 4xx says to change what the message names; and any other status says to report the `request_id`, or the `http_status` when there is none.
+- **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 after the run request left, when a run may exist with no id returned, is `client.outcome_unknown`.
+- **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.
+- **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`.
-**A hosted run that started and failed** reports the error the hosted API stored for it: `error_type` is the runner's class, `message` says the run's final status and reason, `hint` is the runner's next step, `error_domain`, `error_category`, `retryable`, `model`, `provider` and `validation_errors` are the stored error's when it carries them, and `pipeline_run_id` and `run_status` name the run. `retryable` is the runner's verdict whenever it gave one, `false` included, never the local default for its class. **A hosted run that failed on the way** carries its own class as `error_type`, with a next step for each: `ApiUnreachableError` (the network or the origin, `"error_domain": "config"`, only for a failure before the run request left this machine), `HostedRunOutcomeUnknownError` (the connection failed after the run request was sent, so a run may exist with no id returned: check the run history before running again), `RunTimeoutError` (the run keeps going on the hosted API past the wait), `PipelineExecuteTimeoutError` (a server that keeps no runs cut the blocking route before the result came back; the run may still be going, so it is `"retryable": false` and its hint points at the proxy's timeout or a base URL that keeps runs), `MissingMainStuffError` (the run completed and delivered no main output), `HostedRunPollingError` (the run started, then reading its result failed; it may still be running and is paid for, so look it up rather than run again), `HostedMethodInvalidError` (the method does not load, refused before any run starts when the inputs name a local file, its `validation_errors` naming each faulty file in `source`), `HostedLocalFileUploadUnavailableError` (the inputs name a local file and the method calls another one by its address: give the file as an `https://` URL), `InvalidLocalSourceError` (a local file in the inputs cannot be read), `UploadTransportError` (`config` when the upload never reached the hosted API, `runtime` when the hosted API failed it), `UploadAuthenticationError`, `RejectedAssetError` and the other upload failures, and `HostedBaseUrlError` 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`. **An interrupted hosted run** (Ctrl-C) exits with `130` and the envelope `HostedRunInterruptedError`, whose `pipeline_run_id` names the run the hosted API had acknowledged: the run keeps going and is paid for. Interrupted before the acknowledgement, the envelope has no `pipeline_run_id` and its hint says to check the run history before running again. Any other failure of the hosted run still leaves as this envelope, with the exception's class as `error_type` and the next step of its code as `hint`, `runtime.unexpected`'s for an exception that is no Pipelex error.
+None of the members of the envelope this CLI wrote before it reported problems is left on this path, at any level of the problem: no `error`, `error_type`, `error_source`, `hint`, `error_domain`, `retryable`, `error_code` or `http_status`.
**A pending configuration migration** — a configuration error (`pipelex.config.invalid`, `"domain": "operator"`) carries `diagnostics.migration` when, and only when, a scan of this machine's configuration directories found something. Its presence says the migration history has something to report about these files; **`would_write` says whether a command repairs them.** The object holds `remedy` (the command that fixes what can be fixed), `would_write` (whether running it would rewrite any of these files), `needs_attention` (whether something there is a person's decision rather than the tool's), and `plans` — one per file, in the same shape [`pipelex-agent migrate`](migrate.md) emits under its own `plans` key. On `would_write: true` the loop is `pipelex-agent migrate --dry-run --format json`, show the user what would change, then `--yes`. On `would_write: false` there is nothing to run: the plans carry a path no ledger entry explains, or an entry blocked before anything applied, and the command would visit the files, write nothing and leave the same error standing — so read the plans and correct what they name. Never answer either one by re-initializing a configuration file — that discards every setting the migration would have kept. In Markdown it is a `### Configuration migration` section under the diagnostics.
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index 54e2b4fbe..0d1e7835d 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -211,7 +211,7 @@ Besides `category` and `message`, each item carries whatever identity fields its
**Host-wiring guards are programmer errors, not content verdicts.** `validate_bundle`'s "provide exactly one of `mthds_contents` / `mthds_file_path`" guard and `resolve_crate_from_contents`'s `mthds_sources`-length-mismatch guard raise `PipelexUnexpectedError` (`runtime.unexpected`, 500), not `ValidateBundleError` — a caller wiring bug must not be reported as if the submitted bundle were invalid. The empty-`mthds_contents` guard stays the caller's, `request.invalid` (it can legitimately reflect an end user submitting no bundles).
-`ValidationErrorItem` and the builder are the single source of truth across surfaces: `build_validation_error_items()` (`pipelex/pipeline/validation_errors.py`) is reached through `ValidateBundleError.validation_error_items()`, which `ValidateBundleError.problem_items()` (the `errors` of every problem of an invalid bundle, which the agent CLI prints), the validators' invalid arm, the agent CLI's Markdown (which renders the items as prose) and `pipelex fix` all call, so the structured shapes cannot drift. `pipelex-agent validate pipe` and `validate --all` dry-run through the same cascade, so a failing dry run there is the same invalid verdict with the same items as on `validate bundle`. The item lives in `pipelex/base_exceptions.py`, not next to the source error-data models, because the root exceptions module must not import the `pipelex.core` error modules, which import back into it.
+`ValidationErrorItem` and the builder are the single source of truth across surfaces: `build_validation_error_items()` (`pipelex/pipeline/validation_errors.py`) is reached through `ValidateBundleError.validation_error_items()`, which `ValidateBundleError.problem_items()` (the `errors` of every problem of an invalid bundle, which the agent CLI prints), the validators' invalid arm, the human CLI's prose and `pipelex fix` all call, so the structured shapes cannot drift. `pipelex-agent validate pipe` and `validate --all` dry-run through the same cascade, so a failing dry run there is the same invalid verdict with the same items as on `validate bundle`. The item lives in `pipelex/base_exceptions.py`, not next to the source error-data models, because the root exceptions module must not import the `pipelex.core` error modules, which import back into it.
#### The `error_type` registry — the closed vocabulary of faults
@@ -241,7 +241,7 @@ When a validation error has a deterministic remedy, its `ValidationErrorItem` ca
- `fix_code` — the kebab-case rule id (e.g. `match-sequence-output`). The planner's `KNOWN_FIX_CODES` set is the validation set for user-facing rule filters (`--select` / `--ignore`); an unknown code is rejected loudly, never lenient-ignored, because a typo'd filter selects *behavior*.
- `description` — human-readable statement of the change.
-- `safety` — `safe` fixes may be auto-applied; `unsafe` ones need a person's or an agent's confirmation, and `pipelex fix bundle` never applies them. Every prose rendering labels an unsafe fix `💡 Suggested fix (unsafe, confirm before applying):` where a safe one reads `💡 Suggested fix:`, through the one `suggested_fix_label` in `pipelex/pipeline/validation_render.py`.
+- `safety` — `safe` fixes may be auto-applied; `unsafe` ones need a person's or an agent's confirmation, and `pipelex fix bundle` never applies them. Every prose rendering labels an unsafe fix `💡 Suggested fix (unsafe, confirm before applying):` where a safe one reads `💡 Suggested fix:`, through the one `suggested_fix_label` in `pipelex/pipeline/validation_render.py`, and the agent CLI's Markdown, which lists the problem's items, labels an unsafe one `unsafe, confirm before applying` beside its fix code.
- `source` — the file the ops target, when known (multi-file libraries). An applier must only apply ops to the file they target.
- `ops[]` — the fix itself, as **semantic TOML patch ops** addressed by table path (`FixOpKind`: `set_key`, `ensure_table`, `delete_key`, `delete_table`, `rename_table_key`, `move_key`, `remap_value`; each op's `table_path` follows the same conventions as the items' `field_path`). The ops are the machine contract; any rendered diff or `💡 Suggested fix:` line is presentation.
@@ -492,7 +492,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 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 hosted run keeps for now the envelope the CLI wrote before (`error`, `error_type`, `error_domain`, `error_code`, `hint`, `retryable`), its refusals before anything is sent excepted.
+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.
| Command | Error output |
|---------|--------------|
diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.md
index 2d623acfc..1240b147d 100644
--- a/pipelex/cli/agent_cli/CLAUDE.md
+++ b/pipelex/cli/agent_cli/CLAUDE.md
@@ -22,7 +22,7 @@ Markdown structure per command:
- `fix`: `# Fix applied - bundle is valid` after one or more fixes, `# Bundle already valid` when the loop had nothing to apply, or `# Bundle valid but not runnable` when pending `PipeSignature` placeholders remain. The JSON success envelope carries `is_valid`, `bundle_path`, `iterations`, `fixes_applied`, `files_written`, `remaining_errors`, and, on successful validation, `pending_signatures` plus `is_runnable`. Whole-bundle fix runs are strict by default: they emit the success envelope but exit 1 on `not is_runnable` unless `--allow-signatures` is passed. A still-invalid verdict exits 1 with the problem `method.invalid` on stderr (`agent_error_fix_bundle`), its `errors` the faults left, beside the result's fields (`is_valid`, `bundle_path`, `iterations`, `fixes_applied`, `files_written`, any `bail_reason`); its Markdown ends with the fix progress (`format_fix_progress_markdown`). `fix function-names <method folder>` is the migration of a method's flat PipeFunc `function_name`s into import paths from the method tree's root (`pipelex/migration/function_names.py`): `# Function names of the method at <folder>` then the rewrites, the `@pipe_func(...)` registration names dropped, the names left unresolved with their reason and candidates, and the markers whose argument it kept (one registering a name a step still holds unresolved, or one whose name is not a string literal); the JSON envelope carries `directory`, `is_dry_run`, `is_complete`, `changed_files`, `rewrites`, `marker_removals`, `unresolved` and `unresolved_markers`. It exits 1 after the envelope when a name or a marker is left unresolved, and 2 via `FunctionNamesMigrationError` when the folder is not a method tree.
- `migrate`: `# Configuration migration`, the mode (applied / dry run) and verdict, the directories walked, a files-walked/changed/written count and, when a former release left something, its file count, then one `## <path>` section per file the former-release cleanup touches, listing its changes and its backup, a `## Pipelex still cannot start` section when the cleanup's check, run on every run, found something, and one per file that is not clean listing the entries applied, the entries blocked with their reason and guidance, and any unexplained paths. Paths, operation kinds, ledger-supplied values and the names of retired backends and profiles only — no value read from the user's file is ever rendered, in either format.
- `init`: `# Pipelex initialized` with target directory and execution, then enabled backends and routing profile for a local setup, or whether a Pipelex API key is set for a hosted one.
-- error path: the problem (`render_problem_markdown`): `## <title>`, the detail, the command's own message when it says more, the `**Next step**` line naming its kind, the advice the cause's chain gives (`PipelexError.advised_action()`) as a `💡` tip when it says more than the next step, the code with its domain and retry verdict, the request id, the run and the location, then the faults (an invalid verdict's items as the same grouped prose `validate` prints, any other problem's items under `### Errors`), `### Diagnostics` (the error class, the model and provider, a pending migration as `### Configuration migration`) and the command's own members under `### Details`. No stack frame, in either format. A hosted run's failure keeps the legacy `# Error: <error_type>` rendering (below).
+- error path: the problem (`render_problem_markdown`): `## <title>`, the detail, the command's own message when it says more, the `**Next step**` line naming its kind, the advice the cause's chain gives (`PipelexError.advised_action()`) as a `💡` tip when it says more than the next step, the code with its domain and retry verdict, the request id, the run and the location, then the faults under `### Errors`, one item per line with its code, its sentence and its location, then its suggestions and its suggested fix (an unsafe one says it needs confirming), the same items the JSON's `errors` lists whether a local verdict or a runner gave them, the failed run's own problem under `### The run's own problem` when a read of its results nests one (`run_error`), `### Diagnostics` (the error class, the model and provider, a pending migration as `### Configuration migration`) and the command's own members under `### Details`. No stack frame, in either format. A run on a runner renders the same way (below).
## Companion: Agent Skills
@@ -39,7 +39,7 @@ When changing CLI command signatures, output schemas, or error types, check whet
```
_agent_cli.py # Typer app setup, version callback, PipelexAgentCLI(TyperGroup) — command registration, ordering
commands/
- agent_output.py # agent_success(), agent_error() and the refusals, the problem's Markdown, the hosted legacy envelope
+ agent_output.py # agent_success(), agent_error() and the refusals, agent_error_problem() for a problem built elsewhere, the problem's Markdown
agent_cli_factory.py # make_pipelex_for_agent_cli() — init, a failure reported as its problem
run/ # run — execute pipeline (pipe|bundle|method subcommands)
app.py # run_app Typer, subcommand registration
@@ -47,7 +47,7 @@ commands/
bundle_cmd.py # run bundle — execute from bundle file/directory
method_cmd.py # run method — execute method (installed name, address/URL, or path)
_run_core.py # Shared async run logic (local runner)
- _run_hosted.py # Hosted runs: --runner/--hosted/--base-url resolution, the run through pipelex.hosted, its envelopes
+ _run_hosted.py # Hosted runs: --runner/--hosted/--base-url resolution, the run through pipelex.hosted, its envelope, its failure's problem
_output_helpers.py # Output formatting helpers
stdin_resolver.py # Stdin input resolution
validate/ # validate — verify pipes/bundles/methods
@@ -105,10 +105,10 @@ commands/
- **Async core**: Run and validate are async — commands use `asyncio.run()`.
- **File convention**: Generated outputs go to `mthds-wip/` with incremental naming (`pipeline_01/`, `pipeline_02/`). A `run` writes into a new numbered folder, `results/<pipe_code>_output_<NN>/`, made by `make_run_output_folder` (`pipelex/cli/commands/run/_run_output_folder.py`) beside the bundle it ran, else under `mthds-wip/`; the folder holds a `.gitignore` of `*`, so a run's outputs never join the method tree and two runs read the same tree, with the same `method_tree_digest`. `run_pipeline_core`'s `output_dir_override` replaces the directory the folder is made under: `run method` on a fetched target (a method address or GitHub URL) passes `results/` under the caller's CWD, since the fetched clone is an ephemeral temp dir deleted at process exit, and `run bundle <folder> --pipe` passes the folder's `results/`, having no entry bundle to write beside.
- **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, and its problem (`method.invalid`) carries the verdict's items as `errors`, and the Markdown renders the same errors: as `validate`'s prose when they are, item for item, the items of the first verdict on the cause's chain of Pipelex errors (`_problem_validation_items`, over `iter_pipelex_cause_chain`), else 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, so a tree past its limits, a symbolic link or a special file such as a FIFO is a `ValidateBundleError` too, refused unread, 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.
+- **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, 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, so a tree past its limits, a symbolic link or a special file such as a FIFO is a `ValidateBundleError` too, refused unread, 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.
-- **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; what the hosted run itself fails with keeps the legacy envelope below. 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; 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), 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 after the run request was sent 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 a `HostedRunInterruptedError` envelope carrying `pipeline_run_id`, 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 leaves through the command-boundary catch-all as the envelope. 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`.
-- **Hosted refusals** keep, for now, the envelope this CLI wrote before it reported problems (`error: true`, `error_type`, `error_domain`, `error_code`, `hint`, `retryable`, …), through `agent_error_hosted_envelope()` and `agent_error_api_response()` in `agent_output.py`. The first gives a `hint` from the error's advice, else its code's next step (`runtime.unexpected`'s for a foreign exception), which the fields read off the answer override, and notes the error's problem for the usage statistics (`usage_stats_error`, which reads a `PipelineRequestError`'s carried problem too, but a refusal a server answered only by the code and domain its body sent, else the catch-all); the second notes only the code and domain the hosted API sent (`sent_usage_stats_error`, the same rule, in `pipelex/system/usage_stats/usage_stats_runs.py`), as its envelope prints them, and nothing when it sent none. `agent_error_hosted()` routes pipelex-sdk's `ApiResponseError` (every `PipelexAPIClient` route raises it on a non-2xx answer) to `agent_error_api_response()`. `api_response_error_payload()` builds the envelope from the problem document alone: `error_type` is the runner's class (`ValidateBundleError` at load, as a local run reports it, or the root fault of a failed run, which a local run reports as `cause_type` under `PipelineExecutionError`; this path has no `cause_type`), `message` is the error's own `API POST /v1/start failed (<status>): <reason>` without the next step it appends, `hint` is `user_action.detail`, and `error_domain` / `error_category` / `retryable` / `validation_errors` / `pipe_code` / `pipe_stack` / `request_id` are the runner's, plus `error_code` (the problem's `code`, the member a local envelope fills from its cause's registry code), `retry_after_seconds` (the `Retry-After` header) and `http_status`. It deliberately bypasses `agent_error()`'s lookups: the dict hints keyed on a class name local commands (`doctor`, `check-model`) that cannot fix a remote refusal, and the domain is only the runner's to say, so one with no `error_domain` carries none. Both `error_domain` and `retryable` come from `pipelex.hosted.error_rendering.sent_verdict()`, the members the problem document carried, never from the verdict pipelex-sdk decides for every `ApiResponseError`, which fills an unsent member from its own status table and reads every 5xx, a 503 included, as retryable. A refusal with no `user_action` — the hosted plane's own answers in front of the runner: the gateway's 403 for a bad key, the rate limiter's 429, the unreachable runner's 503 — gets its status's next step from `pipelex.hosted.error_rendering` (`HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS`, the table the human CLI reads too; 401 and 403 point at `PIPELEX_API_KEY` and `pipelex login`, 404 at the method and the origin), else `HOSTED_REFUSAL_CALLER_NEXT_STEP` for any other 4xx and `HOSTED_SERVER_FAULT_NEXT_STEP` for the rest. Only a 429 that did not say otherwise is inferred `retryable`: the platform can answer a 503 after the run completed, when it failed to record the result, so its hint warns that a retry can repeat a paid run. Every other failure, the SDK's and pipelex's own `HostedRunError` subclasses alike, goes through `agent_error_hosted_envelope()` with what `describe_hosted_error()` reads off it, the view the human CLI prints too: the class, message, next step, domain and `retryable`, the `pipeline_run_id` of any failure met once the run was acknowledged (`RunFailedError`, `RunTimeoutError`, `MissingMainStuffError`, `HostedRunPollingError`, `HostedRunInterruptedError`), a `retryable` passed whenever the hosted API gave a verdict, `false` included, and the `validation_errors` of a failed run or of a `HostedMethodInvalidError` (pipe-io's verdict on a method that does not load, whose items name the faulty file in `source`); a `RunFailedError` adds `run_status` and its report's category, model and provider. The markdown renderer keeps a runner item this pipelex's `ValidationErrorItem` cannot type (a newer `error_type`, an unknown field) as JSON under Details instead of failing.
+- **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; what the run itself fails with is the problem the runner or the client produced, in the caller's view (below). 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; 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), 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 after the run request was sent 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. 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.
- **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(...))`), and the hosted envelopes note what they print, never the error itself. `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`.
+- **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/agent_output.py b/pipelex/cli/agent_cli/commands/agent_output.py
index f082a1e4c..03307ca01 100644
--- a/pipelex/cli/agent_cli/commands/agent_output.py
+++ b/pipelex/cli/agent_cli/commands/agent_output.py
@@ -19,26 +19,23 @@ members as ``message``, and a command's own facts (``is_valid``, ``bundle_path``
further members. The JSON form is the problem as it is written on the wire; the Markdown form renders it for an agent
to read.
-A hosted run's failure keeps the envelope it had before the problem, built from the hosted plane's answer
-(:func:`agent_error_hosted_envelope`, :func:`agent_error_api_response`), until the hosted plane answers problems.
+A run on a runner (``--runner hosted``) reports the problem the runner or the client produced, in the caller's view,
+through :func:`agent_error_problem`: the problem was built elsewhere, so this module prints it as it came.
"""
import os
import sys
-import traceback
from collections.abc import Callable, Mapping
from contextvars import ContextVar
from enum import StrEnum
from pathlib import Path
-from typing import Any, NoReturn, cast
+from typing import Any, NoReturn
import typer
-from mthds.protocol.problem.models import ProblemItem, ProblemLocation
+from mthds.protocol.problem.models import FixSafety, ProblemItem, ProblemLocation
from mthds.protocol.problem.registry import CoreCode
-from pipelex_sdk.errors import ApiResponseError
-from pydantic import ValidationError
-from pipelex.base_exceptions import ErrorDomain, PipelexError, ValidationErrorItem, iter_cause_chain, iter_pipelex_cause_chain
+from pipelex.base_exceptions import PipelexError, ValidationErrorItem
from pipelex.errors.error_codes import ErrorCode
from pipelex.errors.failure_problem import failure_diagnostics, failure_problem, format_problem_location, format_problem_verdict
from pipelex.errors.problem import (
@@ -48,14 +45,14 @@ from pipelex.errors.problem import (
ProblemView,
make_problem,
)
-from pipelex.hosted.error_rendering import hosted_refusal_message, hosted_refusal_next_step, sent_verdict
from pipelex.pipeline.exceptions import ValidateBundleError
from pipelex.pipeline.fixes.fix_loop import FixBundleResult
from pipelex.pipeline.fixes.fix_render import format_fix_progress_markdown
from pipelex.pipeline.validation_errors import problem_item_of
-from pipelex.pipeline.validation_render import build_fix_command, count_applicable_fixes, format_validation_error_items_markdown
+from pipelex.pipeline.validation_render import build_fix_command, count_applicable_fixes
from pipelex.system.usage_stats.usage_stats_client import note_command_error
-from pipelex.system.usage_stats.usage_stats_runs import sent_usage_stats_error, usage_stats_error, usage_stats_error_of_problem
+from pipelex.system.usage_stats.usage_stats_contract import UsageStatsError
+from pipelex.system.usage_stats.usage_stats_runs import usage_stats_error_of_problem
from pipelex.tools.misc.json_utils import clean_json_dumps
@@ -150,27 +147,6 @@ def _advice_of(*, error: BaseException | None) -> str | None:
return advice.detail if advice is not None else None
-def _problem_validation_items(*, error: BaseException | None, problem: PipelexProblem) -> list[ValidationErrorItem]:
- """The items of the invalid verdict the problem's errors are, to render as ``validate``'s prose; empty otherwise.
-
- The Markdown and the JSON report the one problem. The first invalid verdict along ``error``'s cause chain renders
- its items in place of the problem's errors only when it gave every one of them, item for item, so the prose lists
- the faults the JSON's ``errors`` list. Any other problem, one whose errors a wrapper added to or another error gave,
- renders its errors as they are. The walk stops at the first exception that is not a Pipelex error, as every walk
- reading a failure's chain does.
- """
- if error is None or not problem.errors:
- return []
- for node in iter_pipelex_cause_chain(error):
- if isinstance(node, ValidateBundleError):
- verdict_items = node.problem_items() or []
- verdict_faults = [(item.code, item.detail) for item in verdict_items]
- if verdict_faults != [(item.code, item.detail) for item in problem.errors]:
- return []
- return node.validation_error_items()
- return []
-
-
def problem_payload(*, problem: PipelexProblem, message: str | None, extras: Mapping[str, Any]) -> dict[str, Any]:
"""The JSON form of a reported problem: its members as written on the wire, then the command's own.
@@ -195,15 +171,63 @@ _MARKDOWN_SILENT_EXTRAS: frozenset[str] = frozenset({"is_valid"})
def _problem_item_lines(*, item: ProblemItem) -> list[str]:
- """One item of a problem as a Markdown list entry, with its suggested fix under it."""
+ """One item of a problem as a Markdown list entry: its code, its sentence and where, then its suggestions and its fix.
+
+ An unsafe fix, or one of a safety this reader does not know, says it needs confirming before it is applied.
+ """
where = format_problem_location(location=item.location)
lines = [f"- `{item.code}`: {item.detail}{f' ({where})' if where else ''}"]
+ if item.suggestions:
+ lines.append(f" - Suggestions: {', '.join(f'`{suggestion}`' for suggestion in item.suggestions)}")
fix = item.suggested_fix
if fix is not None:
- lines.append(f" - Suggested fix ({fix.safety}, {fix.fix_code}): {fix.description}")
+ safety: str
+ match fix.effective_safety:
+ case FixSafety.SAFE:
+ safety = "safe"
+ case FixSafety.UNSAFE:
+ safety = "unsafe, confirm before applying"
+ lines.append(f" - Suggested fix (`{fix.fix_code}`, {safety}): {fix.description}")
+ return lines
+
+
+def _errors_lines(*, problem: PipelexProblem, heading: str) -> list[str]:
+ """A problem's faults, one item per line under ``heading``; nothing when it lists none."""
+ if not problem.errors:
+ return []
+ lines = ["", heading, ""]
+ for item in problem.errors:
+ lines += _problem_item_lines(item=item)
return lines
+def _problem_head_lines(*, problem: PipelexProblem, depth: int, message: str | None = None, tip: str | None = None) -> list[str]:
+ """A problem under a heading of ``depth``: its title, its detail, the next step, its facts and its faults.
+
+ The command's own sentence and the tip are added when they say more than the detail and the next step. Its faults
+ are listed one heading level down. The reported problem and the run's own problem it nests both render through
+ here, at their own depths.
+ """
+ heading = "#" * depth
+ lines: list[str] = [f"{heading} {problem.title}", "", problem.detail]
+ if message and message != problem.detail:
+ lines += ["", message]
+ lines += ["", f"**Next step** (`{problem.next_step.kind}`): {problem.next_step.detail}"]
+ if tip and tip != problem.next_step.detail:
+ lines += ["", f"💡 {tip}"]
+ lines.append("")
+ lines += _fact_lines(problem=problem)
+ lines += _errors_lines(problem=problem, heading=f"{heading}# Errors")
+ return lines
+
+
+def _run_error_lines(*, run_error: PipelexProblem | None) -> list[str]:
+ """The failed run's own problem, nested in the problem of a read of its results: what made the run fail, and where."""
+ if run_error is None:
+ return []
+ return ["", "### The run's own problem", "", *_problem_head_lines(problem=run_error, depth=4)]
+
+
def _fact_lines(*, problem: PipelexProblem) -> list[str]:
"""The facts a rendering states after the problem's sentences: its code and verdict, the request, the run, the place."""
lines = [f"- Code: `{problem.code}` ({format_problem_verdict(problem=problem)})"]
@@ -270,42 +294,28 @@ def render_problem_markdown(
problem: PipelexProblem,
message: str | None = None,
extras: Mapping[str, Any] | None = None,
- validation_items: list[ValidationErrorItem] | None = None,
tip: str | None = None,
) -> str:
"""A reported problem as Markdown, for an agent: the error stream of ``pipelex-agent`` by default.
The title, the detail, the command's own sentence when it says more, the next step and the tip a local CLI prints
when the error advises one, then the code with its domain and retry verdict, the request, the run and the location.
- The faults follow: the validation items of an invalid verdict as the grouped prose ``validate`` prints, so an agent
- reads a refused run's items the way it reads an invalid verdict's, and any other problem's items one per line. Then
- the diagnostics and the command's own members.
+ The faults follow, the problem's ``errors`` one per line with their code, sentence, location, suggestions and
+ suggested fix, the same items the JSON lists, whether a local verdict or a runner gave them. Then the failed run's
+ own problem when a read of its results nests one, the diagnostics and the command's own members.
Args:
- problem: The problem, in the operator's view.
+ problem: The problem, in the view its reader is given.
message: The command's own sentence.
extras: The command's own members.
- validation_items: The items of the invalid verdict the problem's errors are, rendered in their place as prose.
tip: The advice nearest the error along its cause chain (:meth:`PipelexError.advised_action`), which a local CLI
prints and no problem carries.
Returns:
The Markdown, with no trailing newline.
"""
- lines: list[str] = [f"## {problem.title}", "", problem.detail]
- if message and message != problem.detail:
- lines += ["", message]
- lines += ["", f"**Next step** (`{problem.next_step.kind}`): {problem.next_step.detail}"]
- if tip and tip != problem.next_step.detail:
- lines += ["", f"💡 {tip}"]
- lines.append("")
- lines += _fact_lines(problem=problem)
- if validation_items:
- lines += ["", format_validation_error_items_markdown(validation_items)]
- elif problem.errors:
- lines += ["", "### Errors", ""]
- for item in problem.errors:
- lines += _problem_item_lines(item=item)
+ lines = _problem_head_lines(problem=problem, depth=2, message=message, tip=tip)
+ lines += _run_error_lines(run_error=problem.run_error)
lines += _diagnostics_lines(diagnostics=problem.diagnostics)
lines += _extras_lines(extras=extras or {})
return "\n".join(lines)
@@ -316,34 +326,46 @@ def render_problem_markdown(
# -------------------------------------------------------------------------------------------------
-def _emit_problem(
+def _print_problem(
*,
problem: PipelexProblem,
message: str | None,
extras: Mapping[str, Any],
- validation_items: list[ValidationErrorItem],
markdown_footer: str | None = None,
markdown_extras: Mapping[str, Any] | None = None,
tip: str | None = None,
) -> None:
- """Print the problem on stderr in the active error format, and note its code for the command's usage statistics.
+ """Print the problem on stderr in the active error format.
The Markdown lists ``markdown_extras`` under its Details when they are given, in place of ``extras``, for a command
whose own members the footer already says in prose, and prints ``tip``, which the JSON problem never carries.
"""
- # The command's usage statistics carry the same classification, never the error itself.
- note_command_error(error=usage_stats_error_of_problem(problem=problem))
match get_agent_cli_error_format():
case CliOutputFormat.JSON:
print(clean_json_dumps(problem_payload(problem=problem, message=message, extras=extras), indent=2), file=sys.stderr)
case CliOutputFormat.MARKDOWN:
shown_extras = extras if markdown_extras is None else markdown_extras
- markdown = render_problem_markdown(problem=problem, message=message, extras=shown_extras, validation_items=validation_items, tip=tip)
+ markdown = render_problem_markdown(problem=problem, message=message, extras=shown_extras, tip=tip)
if markdown_footer:
markdown = f"{markdown}\n\n{markdown_footer}"
print(markdown, file=sys.stderr)
+def _emit_problem(
+ *,
+ problem: PipelexProblem,
+ message: str | None,
+ extras: Mapping[str, Any],
+ markdown_footer: str | None = None,
+ markdown_extras: Mapping[str, Any] | None = None,
+ tip: str | None = None,
+) -> None:
+ """Print the problem on stderr in the active error format, and note its code for the command's usage statistics."""
+ # The command's usage statistics carry the same classification, never the error itself.
+ note_command_error(error=usage_stats_error_of_problem(problem=problem))
+ _print_problem(problem=problem, message=message, extras=extras, markdown_footer=markdown_footer, markdown_extras=markdown_extras, tip=tip)
+
+
def agent_error(
message: str,
*,
@@ -377,13 +399,35 @@ def agent_error(
**extra: The command's own members, beside the problem's; none replaces a member of the problem.
"""
problem = agent_problem(cause=cause, code=code, params=params, location=location)
- _emit_problem(
- problem=problem,
- message=message,
- extras=extra,
- validation_items=_problem_validation_items(error=cause, problem=problem),
- tip=_advice_of(error=cause) or fallback_tip,
- )
+ _emit_problem(problem=problem, message=message, extras=extra, tip=_advice_of(error=cause) or fallback_tip)
+ raise typer.Exit(exit_code) from cause
+
+
+def agent_error_problem(
+ *,
+ problem: PipelexProblem,
+ cause: BaseException,
+ noted_error: UsageStatsError | None,
+ message: str | None = None,
+ exit_code: int = 1,
+) -> NoReturn:
+ """Report a problem built elsewhere as it came, on stderr in the active error format, and exit with ``exit_code``.
+
+ The failure of a run on a runner is the problem the runner answered or the client decided, in the caller's view, so
+ this CLI neither rebuilds nor reclassifies it. The usage statistics note ``noted_error``, which the caller decides:
+ a refusal a server answered is noted by what its body sent alone, and not at all when it sent no code. The Markdown
+ prints the advice ``cause`` gives, when it is a Pipelex error that gives one, as its tip.
+
+ Args:
+ problem: The problem to report.
+ cause: The error the problem belongs to; chained with ``raise ... from``.
+ noted_error: What the command's usage statistics record, ``None`` to record nothing.
+ message: The command's own sentence, when it says what the problem does not.
+ exit_code: Process exit code.
+ """
+ if noted_error is not None:
+ note_command_error(error=noted_error)
+ _print_problem(problem=problem, message=message, extras={}, tip=_advice_of(error=cause))
raise typer.Exit(exit_code) from cause
@@ -518,8 +562,8 @@ def agent_error_validate_bundle(
The verdict's problem (``method.invalid``, its faults in ``errors``) carries ``is_valid: false`` and the
``bundle_path`` beside its members, which a software consumer (a hook pins ``--error-format json``) branches on.
- Its Markdown renders the faults as the grouped prose ``validate`` prints, with each suggested fix, and ends with a
- fix-aware footer naming the exact ``pipelex-agent fix bundle`` command when items carry a fix.
+ Its Markdown lists the same items, each with its code, sentence, location, suggestions and suggested fix, and ends
+ with a fix-aware footer naming the exact ``pipelex-agent fix bundle`` command when items carry a fix.
Args:
exc: The bundle-validation failure to report.
@@ -533,7 +577,6 @@ def agent_error_validate_bundle(
problem=exc.to_problem(view=ProblemView.OPERATOR),
message=exc.message,
extras={"is_valid": False, "bundle_path": str(bundle_path)},
- validation_items=items,
# The fix-aware footer stands in for the verdict's class-level advice, which would only repeat it less precisely.
markdown_footer=_validate_fix_footer(items=items, bundle_path=bundle_path, library_dirs=library_dirs, allow_signatures=allow_signatures),
)
@@ -546,7 +589,7 @@ def agent_error_fix_bundle(*, result: FixBundleResult, bundle_path: str, message
The problem is the method's that does not validate, ``method.invalid``, its faults the remaining errors. Beside its
members ride ``bundle_path`` and the fix result's own fields (``is_valid``, ``iterations``, ``fixes_applied``,
``files_written``, ``bail_reason`` and the rest), the remaining errors being the problem's ``errors``. Its Markdown
- renders the remaining errors as prose, then what the loop applied, why it stopped and what to do next.
+ lists the remaining errors as the problem's items, then what the loop applied, why it stopped and what to do next.
Args:
result: The fix loop's result, whose verdict is invalid.
@@ -567,238 +610,7 @@ def agent_error_fix_bundle(*, result: FixBundleResult, bundle_path: str, message
problem=problem,
message=message,
extras=extras,
- validation_items=result.remaining_errors,
markdown_footer=format_fix_progress_markdown(result, bundle_path=bundle_path),
markdown_extras={"bundle_path": bundle_path},
)
raise typer.Exit(1)
-
-
-# -------------------------------------------------------------------------------------------------
-# A hosted run's failure: the envelope it had before the problem
-# -------------------------------------------------------------------------------------------------
-
-# Statuses that say the request was refused before anything ran, so the same request can succeed later
-# (RFC 6585): the envelope marks them retryable unless the answer said otherwise. A 503 is not one of
-# them: the hosted plane can answer it after the run completed (see its next step in pipelex.hosted.error_rendering).
-_API_RETRYABLE_STATUSES: frozenset[int] = frozenset({429})
-
-
-def _build_error_source(exc: BaseException) -> list[str]:
- """Build a compact source trace from an exception's cause chain.
-
- Each entry shows where the exception was raised:
- ``"ExceptionType @ module:line (in function)"``.
-
- Args:
- exc: The exception (walks ``__cause__`` chain).
-
- Returns:
- List of source location strings, outermost first.
- """
- sources: list[str] = []
- for current in iter_cause_chain(exc):
- if current.__traceback__ is None:
- sources.append(f"{type(current).__name__} (no traceback)")
- continue
- tbe = traceback.extract_tb(current.__traceback__)
- if tbe:
- frame = tbe[-1] # default fallback
- for candidate in reversed(tbe):
- if "/pipelex/" in candidate.filename and "/.venv/" not in candidate.filename:
- frame = candidate
- break
- location = f"{type(current).__name__} @ {frame.filename}:{frame.lineno} (in {frame.name})"
- sources.append(location)
- else:
- sources.append(f"{type(current).__name__} (no traceback)")
- return sources
-
-
-# Payload keys that the markdown renderer treats specially (heading / body /
-# tip) or omits entirely rather than listing under the "Details" section.
-# ``error_source`` is dropped from markdown — it's internal stack frames that
-# don't help an LLM fix a `.mthds` file. The field stays in the JSON envelope
-# for programmatic consumers.
-_MARKDOWN_RESERVED_KEYS: frozenset[str] = frozenset({"error", "error_type", "message", "hint", "error_source", "validation_errors"})
-
-
-def _typed_validation_items(*, validation_errors: Any) -> list[ValidationErrorItem] | None:
- """The payload's ``validation_errors`` as typed items, or ``None`` when there are none to render as prose.
-
- ``None`` also when an item does not fit this pipelex's ``ValidationErrorItem``: an API runner's
- items come off the wire, and one from a newer runner can carry an ``error_type`` or a field this
- version does not know. The caller then keeps the items as JSON under Details rather than losing them.
- """
- if not isinstance(validation_errors, list) or not validation_errors:
- return None
- try:
- return [ValidationErrorItem.model_validate(item) for item in cast("list[dict[str, Any]]", validation_errors)]
- except ValidationError:
- return None
-
-
-def _render_error_markdown(payload: dict[str, Any]) -> str:
- """Render a hosted run's error envelope as agent-readable markdown.
-
- ``validation_errors`` render as the same grouped prose ``validate`` prints, rather than as a JSON
- dump under Details, so an agent reads a refused run's items the way it reads an invalid verdict's.
- Items this version cannot type stay under Details as JSON.
- """
- lines: list[str] = [f"# Error: {payload['error_type']}", "", str(payload["message"])]
-
- hint = payload.get("hint")
- if hint:
- lines += ["", f"> 💡 **Hint:** {hint}"]
-
- reserved_keys = _MARKDOWN_RESERVED_KEYS
- validation_errors = payload.get("validation_errors")
- items = _typed_validation_items(validation_errors=validation_errors)
- if items:
- lines += ["", format_validation_error_items_markdown(items)]
- elif validation_errors:
- reserved_keys = _MARKDOWN_RESERVED_KEYS - {"validation_errors"}
-
- detail_keys = [key for key in payload if key not in reserved_keys]
- if detail_keys:
- lines += ["", "## Details", ""]
- for key in detail_keys:
- value = payload[key]
- if isinstance(value, (str, int, float, bool)):
- lines.append(f"- **{key}:** {value}")
- else:
- lines += [f"- **{key}:**", "", "```json", clean_json_dumps(value, indent=2), "```", ""]
-
- return "\n".join(lines)
-
-
-def _print_hosted_envelope(*, payload: dict[str, Any]) -> None:
- """Print a hosted run's error envelope on stderr in the active error format."""
- match get_agent_cli_error_format():
- case CliOutputFormat.JSON:
- print(clean_json_dumps(payload, indent=2), file=sys.stderr)
- case CliOutputFormat.MARKDOWN:
- print(_render_error_markdown(payload), file=sys.stderr)
-
-
-def agent_error_hosted_envelope(message: str, *, error_type: str, cause: BaseException, exit_code: int = 1, **extra: Any) -> NoReturn:
- """Report a hosted run's failure in the envelope a hosted run had before the problem, and exit with ``exit_code``.
-
- ``error: true``, ``error_type`` and ``message``, then the ``hint``: the advice nearest the error along its chain, else
- its code's next step, ``runtime.unexpected``'s for an error that is no Pipelex error. For a Pipelex error, the
- ``error_code``, ``error_domain`` and ``retryable`` (only when true) its code decides; then the client-side
- ``error_source``, and the fields read off the hosted plane's answer in ``extra``, which win.
-
- Args:
- message: The failure's sentence.
- error_type: The class the hosted answer names, else the error's own.
- cause: The error the hosted run raised.
- exit_code: Process exit code.
- **extra: The fields read off the hosted plane's answer.
- """
- problem = agent_problem(cause=cause)
- payload: dict[str, Any] = {
- "error": True,
- "error_type": error_type,
- "message": message,
- "hint": _advice_of(error=cause) or problem.next_step.detail,
- }
- if isinstance(cause, PipelexError):
- if problem.is_retryable:
- payload["retryable"] = True
- payload["error_domain"] = ErrorDomain.from_problem_domain(problem.effective_domain)
- payload["error_code"] = problem.code
- payload["error_source"] = _build_error_source(cause)
- payload.update(extra)
- note_command_error(error=usage_stats_error(error=cause))
- _print_hosted_envelope(payload=payload)
- raise typer.Exit(exit_code) from cause
-
-
-def _non_empty_string(*, value: Any) -> str | None:
- """A problem member that is a non-empty string, else ``None``."""
- return value if isinstance(value, str) and value else None
-
-
-def _string_list(*, value: Any) -> list[str] | None:
- """A problem member that is a non-empty list of strings, else ``None``."""
- if not isinstance(value, list) or not value:
- return None
- entries = cast("list[Any]", value)
- if not all(isinstance(entry, str) for entry in entries):
- return None
- return cast("list[str]", entries)
-
-
-def api_response_error_payload(*, error: ApiResponseError) -> dict[str, Any]:
- """The error envelope of a request the hosted API answered non-2xx, read off the problem document it sent.
-
- - ``error_type`` is the runner's error class when the problem names one: ``ValidateBundleError`` for a bundle
- refused at load, and the root fault (``ModelNotFoundError``, ``StuffFactoryError``) for a run that failed.
- ``ApiResponseError`` when the answer names no class, as a gateway's error page does not.
- - ``message`` is ``API POST /v1/start failed (422): <reason>``, the error's own message without the next step
- it appends, which ``hint`` carries. On a failed run the runner's reason is located at the failing pipe and its
- path, ``Pipe 'condense_article' failed (digest_article → condense_article): …``.
- - ``hint`` is the runner's next step, ``user_action.detail``. An answer that advised none, such as the ones the
- hosted plane authors in front of the runner (a refused key, a rate limit, a runner it cannot reach), gets the
- next step of its status from ``pipelex.hosted.error_rendering``, the table the human CLI reads too, else one by
- status class (a 4xx asks for a change to the request, anything else for a report).
- - ``retryable`` (only when true, as on every envelope), ``error_domain`` and ``error_category`` are the answer's,
- with no local fallback, since only the runner knows whether the caller or its operator has to act; the verdict
- pipelex-sdk decides for every refusal is not read, since it fills an unsent member from its own table. The one
- exception is ``retryable`` on a 429 that did not say, a refusal sent before anything ran. A 503 is never
- inferred retryable: a hosted plane can answer it after the run completed.
- - ``validation_errors`` are the runner's items, each whole, as it sent them.
- - ``pipe_code`` and ``pipe_stack`` when the problem carries them as members.
- - ``error_code`` is the problem's ``code`` member, the stable code a hosted plane gives its own refusals
- (``rate_limited``, ``unauthorized``), and ``retry_after_seconds`` the ``Retry-After`` header's delay.
- - ``http_status`` and ``request_id`` are what to quote when the fault is the runner's.
- - ``error_source`` is the client-side trace, as on every JSON envelope.
- """
- problem: dict[str, Any] = error.problem_document or {}
- payload: dict[str, Any] = {
- "error": True,
- "error_type": error.error_type or type(error).__name__,
- "message": hosted_refusal_message(error=error),
- "hint": hosted_refusal_next_step(error=error),
- }
- sent = sent_verdict(error=error)
- if sent.retryable or (sent.retryable is None and error.status in _API_RETRYABLE_STATUSES):
- payload["retryable"] = True
- if sent.error_domain:
- payload["error_domain"] = sent.error_domain
- if error_category := _non_empty_string(value=problem.get("error_category")):
- payload["error_category"] = error_category
- if error.validation_errors:
- payload["validation_errors"] = [item.model_dump(mode="json") for item in error.validation_errors]
- if pipe_code := _non_empty_string(value=problem.get("pipe_code")):
- payload["pipe_code"] = pipe_code
- if pipe_stack := _string_list(value=problem.get("pipe_stack")):
- payload["pipe_stack"] = pipe_stack
- if error_code := _non_empty_string(value=problem.get("code")):
- payload["error_code"] = error_code
- retry_after = error.headers.get("retry-after", "").strip()
- if retry_after.isdigit():
- payload["retry_after_seconds"] = int(retry_after)
- payload["http_status"] = error.status
- if error.request_id:
- payload["request_id"] = error.request_id
- payload["error_source"] = _build_error_source(error)
- return payload
-
-
-def agent_error_api_response(*, error: ApiResponseError) -> NoReturn:
- """Emit the envelope of a request the hosted API refused to stderr, format-aware, and exit 1.
-
- The sibling of :func:`agent_error_hosted_envelope` for the one error a hosted refusal arrives as, its envelope
- read off the hosted API's answer (see :func:`api_response_error_payload`).
-
- Args:
- error: The refusal pipelex-sdk's ``PipelexAPIClient`` raised.
- """
- payload = api_response_error_payload(error=error)
- # The statistics say what the envelope says: what the hosted API sent, never what the SDK inferred from the status.
- if (sent_error := sent_usage_stats_error(error=error)) is not None:
- note_command_error(error=sent_error)
- _print_hosted_envelope(payload=payload)
- raise typer.Exit(1) from error
diff --git a/pipelex/cli/agent_cli/commands/run/_run_hosted.py b/pipelex/cli/agent_cli/commands/run/_run_hosted.py
index e1b309868..cd2b8dda5 100644
--- a/pipelex/cli/agent_cli/commands/run/_run_hosted.py
+++ b/pipelex/cli/agent_cli/commands/run/_run_hosted.py
@@ -1,42 +1,61 @@
-"""`pipelex-agent run … --runner hosted`: run on the hosted Pipelex API and answer in the run envelope.
+"""`pipelex-agent run … --runner hosted`: run on a runner, the hosted Pipelex API or another, and answer in the run envelope.
The run commands share this module for every step that differs from a local run: where the run executes (the
-flags, then `[run] execution`), the flags a hosted run refuses, the run itself through `pipelex.hosted`, and the
-envelope its result or its failure is reported in. Nothing here boots the local runtime.
+flags, then `[run] execution`), the flags a hosted run refuses, the run itself through `pipelex.hosted`, the envelope
+its result is reported in, and the problem its failure is reported as. Nothing here boots the local runtime.
-A refusal decided here, before anything is sent, is a problem like any local failure. A failure of the hosted run
-itself keeps the envelope it had before the problem, read off the hosted plane's answer, until the hosted plane
-answers problems.
+A refusal decided here, before anything is sent, is a problem like any local failure, in the operator's view. 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`.
"""
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 pipelex_sdk.errors import ApiResponseError, RunFailedError
+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, PipelexRequestError, RunFailedError
+from pydantic import BaseModel, ValidationError
-from pipelex.base_exceptions import PipelexError
+from pipelex.base_exceptions import PipelexError, ValidationErrorCategory, ValidationErrorItem
from pipelex.cli.agent_cli.commands.agent_output import (
CliOutputFormat,
agent_argument_error,
agent_error,
- agent_error_api_response,
- agent_error_hosted_envelope,
+ agent_error_problem,
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.hosted.client_factory import make_hosted_client
-from pipelex.hosted.error_rendering import describe_hosted_error
-from pipelex.hosted.exceptions import HostedRunError, HostedRunInterruptedError
+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.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 `\[`.
@@ -91,36 +110,312 @@ def refuse_local_only_flags(*, dry_run: bool, mock_inputs: bool) -> None:
)
-def agent_error_hosted(*, error: PipelineRequestError | HostedRunError, exit_code: int = 1) -> NoReturn:
- """Report a hosted run's failure in the envelope a hosted run had before the problem, and exit with `exit_code`.
+#: 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.
- A refusal the hosted API answered carries its problem document and goes through `agent_error_api_response`, whose
- envelope matches a local failure's. Every other failure is reported as `pipelex.hosted.error_rendering` reads it,
- the view the human CLI prints: its class, its reason, its next step and its domain, the run's `pipeline_run_id`
- once the hosted API acknowledged the run (a run that failed, outlived the wait, was lost on the way or was left
- running by an interruption), and the `validation_errors` of a method that does not load. A run that started and
- failed adds its stored report's status, category, model and provider. When the hosted API gave a `retryable`
- verdict, the envelope carries it, `false` included, so the local table keyed on the runner's class never overrides it.
+ 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):
- agent_error_api_response(error=error)
- view = describe_hosted_error(error=error)
- extra: dict[str, Any] = {"hint": view.next_step}
- if view.error_domain is not None:
- extra["error_domain"] = str(view.error_domain)
- if view.retryable is not None:
- extra["retryable"] = view.retryable
- if view.pipeline_run_id is not None:
- extra["pipeline_run_id"] = view.pipeline_run_id
- if view.validation_errors:
- extra["validation_errors"] = [item.model_dump(mode="json", exclude_none=True) for item in view.validation_errors]
+ 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):
- extra["run_status"] = str(error.status)
- report = error.error
- if report is not None:
- reported = {"error_category": report.error_category, "model": report.model, "provider": report.provider}
- extra.update({field_name: value for field_name, value in reported.items() if value})
- agent_error_hosted_envelope(view.message, error_type=view.error_type, cause=error, exit_code=exit_code, **extra)
+ # 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)})
+ return problem
+
+
+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`.
+
+ 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.
+ """
+ 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
+ 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)
def build_hosted_run_output(*, outcome: HostedRunOutcome, with_memory: bool) -> dict[str, Any]:
@@ -152,15 +447,17 @@ async def _start_and_wait(*, client: PipelexAPIClient, request: HostedRunRequest
def run_hosted_for_agent(*, request: HostedRunRequest, base_url: str | None, with_memory: bool, output_format: CliOutputFormat) -> None:
- """Run on the hosted API and print the run envelope, or the error envelope and exit 1.
+ """Run on the hosted API and print the run envelope, or the failure's problem and exit 1.
- Interrupted by Ctrl-C, the error envelope is a `HostedRunInterruptedError` naming the run the hosted API had
+ Interrupted by Ctrl-C, the problem is the `HostedRunInterruptedError`'s, naming the run the hosted API had
acknowledged, which keeps going, and the exit status is 130.
"""
try:
client = make_hosted_client(base_url=base_url)
except PipelexError as exc:
agent_error(exc.message, cause=exc)
+ # 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 _record_start(*, pipeline_run_id: str) -> None:
@@ -169,14 +466,15 @@ def run_hosted_for_agent(*, request: HostedRunRequest, base_url: str | None, wit
try:
outcome = asyncio.run(_start_and_wait(client=client, request=request, on_started=_record_start))
except (KeyboardInterrupt, asyncio.CancelledError):
- # Ctrl-C stops the wait, not the run: the envelope names the run that keeps going.
+ # Ctrl-C stops the wait, not the run: the problem names the run that keeps going.
interrupted = HostedRunInterruptedError(pipeline_run_id=started_run_ids[-1] if started_run_ids else None)
- agent_error_hosted(error=interrupted, exit_code=_INTERRUPTED_EXIT_CODE)
+ agent_error_hosted(error=interrupted, credential_sent=credential_sent, exit_code=_INTERRUPTED_EXIT_CODE)
except (PipelineRequestError, HostedRunError) as exc:
- agent_error_hosted(error=exc)
+ agent_error_hosted(error=exc, credential_sent=credential_sent)
except Exception as exc: # ruff: ignore[blind-except]
- # Agent CLI command boundary: a failure no arm above names, such as a results body that drifted, is still the
- # hosted run's, so it leaves in the hosted run's envelope too.
- agent_error_hosted_envelope(str(exc), error_type=type(exc).__name__, cause=exc)
+ # Agent CLI command boundary: a failure no arm above names is this process's own, so it is reported as a local
+ # run's 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`.
+ agent_error(str(exc), cause=exc)
result = build_hosted_run_output(outcome=outcome, with_memory=with_memory)
agent_success_formatted(result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format)
diff --git a/pipelex/core/qualified_ref.py b/pipelex/core/qualified_ref.py
index 603587485..0e07b0dec 100644
--- a/pipelex/core/qualified_ref.py
+++ b/pipelex/core/qualified_ref.py
@@ -215,3 +215,12 @@ class QualifiedRef(BaseModel):
raise QualifiedRefError(msg)
parts = raw.split("->", maxsplit=1)
return CrossPackageRef(alias=parts[0], remainder=parts[1])
+
+ @staticmethod
+ def package_named_by(*, raw: str) -> str:
+ """The package a reference into another package names: the alias of a cross-package reference, else the reference itself.
+
+ A verdict's item for a package dependency nothing resolved names the pipe it called (`alias->domain.pipe_code`)
+ or the package alone, and either way the package is the `name` its `method.dependency_missing` code declares.
+ """
+ return QualifiedRef.split_cross_package_ref(raw).alias if QualifiedRef.has_cross_package_prefix(raw) else raw
diff --git a/pipelex/hosted/error_rendering.py b/pipelex/hosted/error_rendering.py
index b6a2f3394..1bfdb7b68 100644
--- a/pipelex/hosted/error_rendering.py
+++ b/pipelex/hosted/error_rendering.py
@@ -4,19 +4,27 @@ Every error of a hosted run that is not pipelex's own arrives as one of the SDK'
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. Both CLIs read the
-same view of an error, its run id and its validation items included, so a person and an agent are told the same
-thing.
+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.
"""
-from typing import NamedTuple
+from typing import Any, NamedTuple
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 pipelex_sdk.errors import (
ApiResponseError,
ApiUnreachableError,
InputPreparationError,
InvalidLocalSourceError,
+ MethodErrorCode,
MissingMainStuffError,
PipelineExecuteTimeoutError,
RejectedAssetError,
@@ -31,6 +39,7 @@ from pipelex_sdk.validation_models import ValidationErrorItem
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.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
@@ -48,13 +57,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 carries it, otherwise a few seconds, then run again"
+_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 carries it, then run again only if a repeated run is acceptable"
+ "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.
+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.
@@ -79,6 +96,190 @@ HOSTED_SERVER_FAULT_NEXT_STEP = (
)
#: 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 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,
+}
+
+
+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.
+
+ `next_step` is `None` when the code's own step, from the registry, fits the refusal better than its status's.
+ """
+
+ code: CoreCode
+ next_step: str | None
+
+
+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.
+
+ 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.
+
+ Returns:
+ The reading, or ``None`` for a status none names.
+ """
+ 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])
+ 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])
+ 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):
@@ -167,7 +368,7 @@ def describe_hosted_error(*, error: PipelineRequestError | HostedRunError) -> Ho
match error:
case HostedRunError():
message = error.message
- next_step = error.user_action.detail if error.user_action is not None else "Check the run request: the method, the pipe and the inputs"
+ 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)
@@ -251,7 +452,7 @@ def describe_hosted_error(*, error: PipelineRequestError | HostedRunError) -> Ho
error_domain = ErrorDomain.INPUT
next_step = "Check the inputs against the pipe's signature (pipelex-agent inputs prints a template), then run again"
case _:
- next_step = "Check the run request: the method, the pipe and the inputs"
+ next_step = HOSTED_RUN_REQUEST_NEXT_STEP
return HostedErrorView(
error_type=error_type,
message=message,
diff --git a/pipelex/hosted/hosted_inputs.py b/pipelex/hosted/hosted_inputs.py
index f3a598ab1..8e2cd5e55 100644
--- a/pipelex/hosted/hosted_inputs.py
+++ b/pipelex/hosted/hosted_inputs.py
@@ -33,17 +33,22 @@ from mthds.protocol.input_form import (
TextItem,
UnknownItem,
)
-from mthds.protocol.problem.registry import CoreCode
+from mthds.protocol.problem.models import ProblemItem
+from mthds.protocol.problem.registry import CoreCode, MethodDependencyMissingKind, MethodDependencyMissingReason
from pipelex_sdk.client import PipelexAPIClient
from pipelex_sdk.crate_models import CrateInvalidReport, MthdsFileItem, PipeIORequest
from pipelex_sdk.errors import ApiResponseError
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.errors.unsupported_reasons import ADDRESS_DEPENDENCY_UNSUPPORTED_REASON
from pipelex.hosted.exceptions import HostedLocalFileUploadUnavailableError, HostedMethodInvalidError
-from pipelex.methods.address_dependencies import ADDRESS_DEPENDENCY_REFUSAL_MARKER
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.
@@ -57,10 +62,6 @@ _FILE_URI_PREFIX = "file://"
#: the reason `ADDRESS_DEPENDENCY_UNSUPPORTED_REASON` (`resolve_crate_from_contents` in `pipelex/pipeline/resolve_bundle.py`).
#: The run route fetches such a dependency.
_ADDRESS_DEPENDENCY_REFUSAL_CODES: frozenset[str] = frozenset({CoreCode.REQUEST_UNSUPPORTED})
-#: The dependency's address, as the refusal of `POST /v1/pipe-io` quotes it when the method calls a package by its
-#: address that the request did not ship (`ADDRESS_DEPENDENCY_REFUSAL_MARKER`). The run route fetches such a dependency;
-#: pipe-io never fetches.
-_REFUSED_DEPENDENCY_PATTERN = re.compile(re.escape(ADDRESS_DEPENDENCY_REFUSAL_MARKER) + r" '([^']+)'")
class AnchoredInputs(NamedTuple):
@@ -279,21 +280,73 @@ def _unshipped_dependency_refusal(*, report: CrateInvalidReport) -> HostedLocalF
"""The error to raise when pipe-io's invalid verdict refuses the method for calling a package by its address, else `None`.
pipe-io resolves the method's tree with only the packages the request ships, and answers a call into a package
- nothing shipped with its invalid verdict, whose item quotes the dependency's address after
- `ADDRESS_DEPENDENCY_REFUSAL_MARKER`. The run route fetches such a dependency, so the method is not at fault. The
- refusal's own advice, to send the dependency's contents, is meant for the API's callers, so the error names the
- dependency and leaves the advice out.
+ nothing shipped with its invalid verdict, whose item is coded `method.dependency_missing` with the `kind` `package`,
+ the `reason` `not_found` and the package's address as its `name`. The run route fetches such a dependency, so the method is not at fault. The
+ error names the dependency from the item's code and parameters, never from its message, and leaves out the
+ verdict's advice, to send the dependency's contents, which is meant for the API's callers.
"""
- messages = [report.message, *(item.message for item in report.validation_errors)]
- refusal = next((message for message in messages if ADDRESS_DEPENDENCY_REFUSAL_MARKER in message), None)
- if refusal is None:
+ package = _missing_package(report=report)
+ if package is None:
return None
- msg = "Local file upload is not available yet for methods with address-based dependencies, and the inputs name a local file"
- if dependency := _REFUSED_DEPENDENCY_PATTERN.search(refusal):
- msg += f": this method depends on {dependency.group(1)}"
+ msg = (
+ "Local file upload is not available yet for methods with address-based dependencies, and the inputs name a local file: "
+ f"this method depends on {package}"
+ )
return HostedLocalFileUploadUnavailableError(msg)
+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.
+ """
+ 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)
+
+
+def _missing_package_of_problem_item(*, item: ProblemItem) -> str | None:
+ """The address of the method package a `method.dependency_missing` problem item names as not found, else `None`."""
+ if item.code != CoreCode.METHOD_DEPENDENCY_MISSING or item.params is None:
+ return None
+ params = item.params.as_wire()
+ name = params.get("name")
+ if (
+ params.get("kind") != MethodDependencyMissingKind.PACKAGE
+ or params.get("reason") != MethodDependencyMissingReason.NOT_FOUND
+ or not isinstance(name, str)
+ ):
+ return 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,
diff --git a/pipelex/libraries/method_trees.py b/pipelex/libraries/method_trees.py
index 50c065659..34080bc15 100644
--- a/pipelex/libraries/method_trees.py
+++ b/pipelex/libraries/method_trees.py
@@ -104,7 +104,7 @@ def list_local_method_tree(*, handed_over: Path, limits: TreeLimits | None = Non
except MethodTreeRefusedError as exc:
if _is_empty_tree(refusal_error=exc):
raise EmptyMethodTreeError(exc.message) from exc
- raise MethodTreeLoadError(exc.message) from exc
+ raise _tree_refusal_error(refusal_error=exc, message=exc.message) from exc
except TreeSourceError as exc:
raise MethodTreeLoadError(exc.message) from exc
@@ -130,7 +130,7 @@ def list_local_method_tree_at_root(*, root: Path, limits: TreeLimits | None = No
except MethodTreeRefusedError as exc:
if _is_empty_tree(refusal_error=exc):
raise EmptyMethodTreeError(exc.message) from exc
- raise MethodTreeLoadError(exc.message) from exc
+ raise _tree_refusal_error(refusal_error=exc, message=exc.message) from exc
except TreeSourceError as exc:
raise MethodTreeLoadError(exc.message) from exc
@@ -157,6 +157,20 @@ def method_tree_root(*, handed_over: Path) -> Path:
raise MethodTreeLoadError(exc.message) from exc
+def _tree_refusal_error(*, refusal_error: MethodTreeRefusedError, message: str, path_prefix: str = "") -> MethodTreeLoadError:
+ """The `MethodTreeLoadError` of a tree the standard refused, giving `method.package_invalid` the facts it declares.
+
+ Its `reason` is the standard's refusal code, such as `symbolic_link`, and its `path` the first tree path the refusal
+ names, behind `path_prefix` (a dependency package's address, as the caller names that package's files), so a caller
+ reads which rule the tree breaks and where without the message, which is the operator's.
+ """
+ error = MethodTreeLoadError(message)
+ refusal = refusal_error.refusal
+ if refusal.names:
+ return error.with_params(reason=refusal.code, path=f"{path_prefix}{refusal.names[0]}")
+ return error.with_params(reason=refusal.code)
+
+
def _with_root_named(*, message: str, root: Path, label: str) -> str:
"""`message` with every spelling of `root` it holds replaced by `label`, the longest spelling first."""
spellings = {str(root), str(root.absolute())}
@@ -184,7 +198,10 @@ def list_package_method_tree(*, root: Path, package_address: str, limits: TreeLi
return written
try:
return list_method_tree_at_root(root, limits=limits or local_tree_limits())
- except (MethodTreeRefusedError, TreeLimitError, TreeSourceError) as exc:
+ except MethodTreeRefusedError as exc:
+ msg = _with_root_named(message=exc.message, root=root, label=package_address)
+ raise _tree_refusal_error(refusal_error=exc, message=msg, path_prefix=f"{package_address}/") from exc
+ except (TreeLimitError, TreeSourceError) as exc:
msg = _with_root_named(message=exc.message, root=root, label=package_address)
raise MethodTreeLoadError(msg) from exc
diff --git a/pipelex/methods/address_dependencies.py b/pipelex/methods/address_dependencies.py
index e0d63ff33..10afbc956 100644
--- a/pipelex/methods/address_dependencies.py
+++ b/pipelex/methods/address_dependencies.py
@@ -5,13 +5,14 @@ A bundle calls a pipe of another method package by the package's address, such a
packages shipped with the method first (its `methods_dirs`), and, when it may, among the methods installed on this host,
fetching one over the network on a miss. A host resolving a caller's method statically, such as the API server's crate
routes, reads nothing of its own and fetches nothing: a package the caller did not ship is refused, with the refusal
-`unshipped_address_dependency_message` words, which a client tells apart by `ADDRESS_DEPENDENCY_REFUSAL_MARKER`.
+`unshipped_address_dependency_message` words for the operator, and as a `method.dependency_missing` item of the kind
+`package` naming its address, by which a client tells that refusal apart (`pipelex.hosted.hosted_inputs`).
"""
from enum import StrEnum
-#: The words every refusal of an address-based dependency nothing shipped carries, which a client matches to tell that
-#: refusal apart from the method being invalid (`pipelex.hosted.hosted_inputs`).
+#: The words every refusal of an address-based dependency nothing shipped carries in its message, the operator's. No
+#: client matches them: it reads the refusal's code and parameters.
ADDRESS_DEPENDENCY_REFUSAL_MARKER = "address-based dependency"
diff --git a/pipelex/pipeline/validate_bundle_translation.py b/pipelex/pipeline/validate_bundle_translation.py
index 058df655d..ace15cb86 100644
--- a/pipelex/pipeline/validate_bundle_translation.py
+++ b/pipelex/pipeline/validate_bundle_translation.py
@@ -15,6 +15,7 @@ from contextlib import contextmanager
from pathlib import Path
from typing import NamedTuple, cast
+from mthds.protocol.problem.registry import CoreCode
from pydantic import ValidationError
from pipelex.base_exceptions import ErrorDomain, PipelexError, SecurityError
@@ -32,6 +33,7 @@ from pipelex.core.pipes.exceptions import (
)
from pipelex.core.validation import report_validation_error
from pipelex.errors.error_codes import code_is_method_domain
+from pipelex.errors.problem import ProblemView
from pipelex.errors.security_event import is_security_refusal
from pipelex.interpreter_hub import get_library_manager
from pipelex.libraries.exceptions import LibraryError, LibraryLoadingError, MethodTreeLoadError
@@ -168,6 +170,11 @@ def translate_to_validate_bundle_error() -> Generator[None, None, None]:
else:
blueprint_validation_errors = None
pipe_concept_validation_errors = None
+ if not blueprint_validation_errors and not pipe_concept_validation_errors:
+ # A tree the package rules refuse, such as one holding a symbolic link, gives its one item the file at fault.
+ refused_path = _refused_tree_path(refusal=library_error)
+ if refused_path is not None:
+ blueprint_validation_errors = [PipelexBundleBlueprintValidationErrorData(message=library_error.message, source=refused_path)]
raise ValidateBundleError(
message=library_error.message,
pipelex_bundle_blueprint_validation_errors=blueprint_validation_errors,
@@ -303,6 +310,19 @@ def _make_refusal_verdict(*, refusal: PipelexError) -> ValidateBundleError | Non
)
+def _refused_tree_path(*, refusal: PipelexError) -> str | None:
+ """The tree path a refusal of the method's package names as its `path`, which locates the verdict's item, else ``None``.
+
+ Read from the parameters a caller may read, as the item's sentence is, so the item names the file the package rule
+ refuses (a symbolic link of the tree, say) in its `location.file`, where a caller reads it without the message.
+ """
+ if refusal.resolve_error_code() != CoreCode.METHOD_PACKAGE_INVALID:
+ return None
+ params = refusal.to_problem(view=ProblemView.CALLER).params
+ path = params.as_wire().get("path") if params is not None else None
+ return path if isinstance(path, str) else None
+
+
@contextmanager
def withholding_host_library_files(
*, library_dirs: Sequence[Path], caller_sources: Collection[str] = (), caller_contents: Collection[str] = ()
diff --git a/pipelex/pipeline/validation_errors.py b/pipelex/pipeline/validation_errors.py
index 4d02c7073..0c9ccf6a2 100644
--- a/pipelex/pipeline/validation_errors.py
+++ b/pipelex/pipeline/validation_errors.py
@@ -242,8 +242,7 @@ def _dependency_facts(*, item: ValidationErrorItem) -> dict[str, Any]:
"""The package an unresolved package reference names, the prefix of its ``->`` reference, as a missing dependency."""
if item.error_type not in _PACKAGE_DEPENDENCY_TYPES or not item.missing_pipe_code:
return {}
- reference = item.missing_pipe_code
- package = QualifiedRef.split_cross_package_ref(reference).alias if QualifiedRef.has_cross_package_prefix(reference) else reference
+ package = QualifiedRef.package_named_by(raw=item.missing_pipe_code)
return {
"kind": MethodDependencyMissingKind.PACKAGE,
"name": package,
diff --git a/pipelex/pipeline/validation_render.py b/pipelex/pipeline/validation_render.py
index e17c11474..c59350c0b 100644
--- a/pipelex/pipeline/validation_render.py
+++ b/pipelex/pipeline/validation_render.py
@@ -16,10 +16,10 @@ and the API-runner cannot drift in format/structure.
``format_validation_error_items_markdown`` is the markdown sibling of the human
``display_validation_error_items`` (``cli/error_handlers.py``): it renders typed
:class:`ValidationErrorItem`s as category-grouped prose with per-item ``💡
-Suggested fix`` lines. It backs the agent ``validate`` failure surface and the
-agent ``fix`` still-invalid surface (and, in a later phase, the API
-``rendered_markdown``) so the prose an agent reads mirrors the human panel and
-cannot drift. ``build_fix_command`` is the shared builder for the copy-pasteable
+Suggested fix`` lines. It backs the API runner's ``rendered_markdown`` of an
+invalid verdict, so that prose mirrors the human panel and cannot drift; the agent
+CLI's failure surfaces list the problem's items instead, as their JSON does.
+``build_fix_command`` is the shared builder for the copy-pasteable
``<executable> fix bundle <path>`` footer, used by both the human and agent
``validate`` surfaces so the ``-L`` / ``--allow-signatures`` echo cannot drift.
"""
@@ -130,10 +130,9 @@ def render_invalid_validation_markdown(report: dict[str, Any]) -> str:
Reconstructs the typed :class:`ValidationErrorItem`s from the report's serialized
``validation_errors`` and delegates to the shared
- :func:`format_validation_error_items_markdown` — the *same* prose renderer that backs the
- agent ``validate`` failure surface and the human panel. So the markdown an agent reads
- through the hosted ``/validate`` (the opt-in ``rendered_markdown``) is byte-identical in
- structure to the local CLI prose: category-grouped items with humanized titles, identity
+ :func:`format_validation_error_items_markdown` — the *same* prose renderer that mirrors the
+ human panel. So the markdown an agent reads through the hosted ``/validate`` (the opt-in
+ ``rendered_markdown``) is the human CLI's prose in structure: category-grouped items with humanized titles, identity
fields, the message, and per-item ``💡 Suggested fix`` lines (which the old dict-based
renderer dropped). A ``# Validation failed`` heading frames it.
diff --git a/subject_grants.toml b/subject_grants.toml
index d623d2d5b..816e0784b 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -24,14 +24,6 @@ rationale = "Verb-object: iterates the exception's cause chain; single operand."
param = "exc"
rationale = "Verb-object: iterates the Pipelex part of the exception's cause chain; single operand, as iter_cause_chain."
-["pipelex/cli/agent_cli/commands/agent_output.py::_build_error_source"]
-param = "exc"
-rationale = "Derives from the exc; single operand."
-
-["pipelex/cli/agent_cli/commands/agent_output.py::_render_error_markdown"]
-param = "payload"
-rationale = "Renders the payload; single operand."
-
["pipelex/cli/agent_cli/commands/agent_output.py::agent_argument_error"]
param = "message"
rationale = "Refuses an argument with the command's message; single operand, as agent_error."
@@ -40,10 +32,6 @@ rationale = "Refuses an argument with the command's message; single operand, as
param = "message"
rationale = "Emits an agent error for the message; single operand."
-["pipelex/cli/agent_cli/commands/agent_output.py::agent_error_hosted_envelope"]
-param = "message"
-rationale = "Emits a hosted run's legacy error envelope for the message; single operand, as agent_error."
-
["pipelex/cli/agent_cli/commands/agent_output.py::agent_error_validate_bundle"]
param = "exc"
rationale = "Error handler: the exc is the single operand handled."
diff --git a/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.py b/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.py
index 75b4455e6..f99da5fc7 100644
--- a/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.py
+++ b/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.py
@@ -154,7 +154,7 @@ class TestRunBundleVerdictCli:
assert item["location"]["field"] == "output"
assert item["location"]["file"] == str(bundle_path)
- def test_agent_run_bundle_markdown_renders_the_items_as_prose(
+ def test_agent_run_bundle_markdown_renders_the_problem_items(
self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], tmp_path: Path
) -> None:
mocker.patch("pipelex.cli.agent_cli.commands.run.bundle_cmd.make_pipelex_for_agent_cli")
@@ -167,6 +167,9 @@ class TestRunBundleVerdictCli:
assert exc_info.value.exit_code == 1
markdown = capsys.readouterr().err
assert markdown.startswith("## The method does not validate")
- assert "## Pipe validation errors" in markdown
- assert "Concept 'TideNotise' in pipe.write_tide_notice.output is not declared" in markdown
+ assert (
+ "### Errors\n\n- `method.concept_unresolved`: The method names the concept 'TideNotise', which no library declares. "
+ f"(pipe 'write_tide_notice', field 'output', file '{bundle_path}')"
+ ) in markdown
+ assert "## Pipe validation errors" not in markdown
assert '"validation_errors"' not in markdown
diff --git a/tests/integration/pipelex/pipeline/test_resolve_crate_from_method_dir.py b/tests/integration/pipelex/pipeline/test_resolve_crate_from_method_dir.py
index e1112cb4e..e7955db56 100644
--- a/tests/integration/pipelex/pipeline/test_resolve_crate_from_method_dir.py
+++ b/tests/integration/pipelex/pipeline/test_resolve_crate_from_method_dir.py
@@ -129,10 +129,17 @@ class TestResolveCrateFromMethodDir:
discovery.assert_not_called()
# The unresolved dependency `/v1/validate` reports, located on the pipe calling it, in the words of the contents
- # core's refusal, whose marker a hosted run tells it apart by.
+ # core's refusal.
validation_errors = exc_info.value.validation_error_items()
assert len(validation_errors) == 1, validation_errors
item = validation_errors[0]
assert item.error_type == PipeValidationErrorType.UNRESOLVED_PACKAGE_DEPENDENCY
assert item.source == "host.mthds"
assert f"{ADDRESS_DEPENDENCY_REFUSAL_MARKER} 'github.com/org/pkg'" in item.message
+ # A hosted run tells it apart by the problem item's code and parameters, the package it names included.
+ problem_errors = exc_info.value.to_problem(view=ProblemView.CALLER).errors
+ assert problem_errors is not None
+ (problem_item,) = problem_errors
+ assert problem_item.code == "method.dependency_missing"
+ assert problem_item.params is not None
+ assert problem_item.params.as_wire() == {"kind": "package", "name": "github.com/org/pkg", "reason": "not_found"}
diff --git a/tests/unit/pipelex/cli/agent_cli/test_agent_error_format.py b/tests/unit/pipelex/cli/agent_cli/test_agent_error_format.py
index 1de22ef5e..5ecb8cccd 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_agent_error_format.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_agent_error_format.py
@@ -1,12 +1,13 @@
from __future__ import annotations
import json
+from typing import TYPE_CHECKING
import pytest
import typer
from mthds.protocol.problem.registry import CoreCode
-from pipelex.base_exceptions import PipelexError
+from pipelex.base_exceptions import PipelexError, ValidationErrorCategory, ValidationErrorItem
from pipelex.cli.agent_cli.commands.agent_output import (
CliOutputFormat,
agent_error,
@@ -16,7 +17,10 @@ from pipelex.cogt.model_backends.model_type import ModelType
from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError
from pipelex.errors.problem import make_problem_item
from pipelex.pipeline.exceptions import ValidateBundleError
-from pipelex.pipeline.validation_render import format_validation_error_items_markdown
+from pipelex.validation_error_types import PipeValidationErrorType
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
class TestAgentErrorFormat:
@@ -89,14 +93,49 @@ class TestAgentErrorFormat:
assert f"- `method.pipe_unresolved`: {missing_pipe}" in printed
assert "- `method.schema_violation`: " in printed
- def test_markdown_renders_a_verdict_s_own_errors_as_validate_s_prose(self, capsys: pytest.CaptureFixture[str]) -> None:
- """When the problem's errors are exactly the verdict's, the Markdown renders them as the prose `validate` prints."""
- set_agent_cli_error_format(CliOutputFormat.MARKDOWN)
- verdict = ValidateBundleError(message="the verdict's own fault")
+ @pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])
+ def test_an_invalid_verdict_lists_its_problem_items_in_both_formats(
+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], error_format: CliOutputFormat
+ ) -> None:
+ """An invalid bundle's Markdown lists the problem's items, code, detail, location and suggestions, as its JSON does."""
+ set_agent_cli_error_format(error_format)
+ item = ValidationErrorItem(
+ category=ValidationErrorCategory.PIPE_VALIDATION,
+ error_type=PipeValidationErrorType.UNKNOWN_MODEL,
+ message="Pipe 'draft_pitch' (PipeLLM), field 'model': Model handle 'gpt-5.1' was not found in the model deck",
+ pipe_code="draft_pitch",
+ domain_code="sales_copy",
+ field_name="model",
+ model_reference="gpt-5.1",
+ model_type="llm",
+ suggestions=["gpt-5.5", "gpt-5.4"],
+ source="pitch.mthds",
+ )
+ verdict = ValidateBundleError(message="the bundle does not validate")
+ mocker.patch.object(verdict, "validation_error_items", return_value=[item])
with pytest.raises(typer.Exit):
agent_error("the bundle does not validate", cause=verdict)
printed = capsys.readouterr().err
- assert "### Errors" not in printed
- assert format_validation_error_items_markdown(verdict.validation_error_items()) in printed
+ match error_format:
+ case CliOutputFormat.JSON:
+ problem = json.loads(printed)
+ assert problem["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", "suggestions": ["gpt-5.5", "gpt-5.4"]},
+ "location": {"pipe": "draft_pitch", "field": "model", "file": "pitch.mthds"},
+ "suggestions": ["gpt-5.5", "gpt-5.4"],
+ }
+ ]
+ case CliOutputFormat.MARKDOWN:
+ assert (
+ "### Errors\n\n"
+ "- `model.unknown`: The method names the llm model 'gpt-5.1', which no catalog knows. "
+ "(pipe 'draft_pitch', field 'model', file 'pitch.mthds')\n"
+ " - Suggestions: `gpt-5.5`, `gpt-5.4`"
+ ) in printed
+ for retired_prose in ("## Pipe validation errors", "Domain:", "Declared concepts", "Source:"):
+ assert retired_prose not in printed
diff --git a/tests/unit/pipelex/cli/agent_cli/test_data.py b/tests/unit/pipelex/cli/agent_cli/test_data.py
index 1231c2d49..eed362904 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_data.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_data.py
@@ -1,136 +1,535 @@
-"""Problem documents an API runner answers a refused run with, for the agent CLI's refusal tests."""
+"""Answers a runner gives a refused run, for the agent CLI's tests of a run on a runner."""
-from typing import ClassVar, NamedTuple
+import json
+from typing import Any, ClassVar
-class RefusedRunBodies:
- """Problem documents a runner answers when it refuses a request, as they came off the wire.
+class RunnerProblems:
+ """Problem documents a runner answers when it refuses a run, as they came off the wire.
- The first three are the dev plane's `POST /v1/execute` refusals of the execution-errors acceptance
- methods, captured on 2026-09-27 through `MthdsAPIClient` against `https://api-dev.pipelex.com`
- (pipelex-api v0.29.0 on pipelex 0.67.0) and copied byte for byte from mthds-python's
- `tests/unit/test_data.py`: a bundle the runner refused at load with an itemized diagnostic, a run
- that failed at a pipe's combine step, and a run that failed on a model the deck does not serve.
- The rest are other shapes a runner, or a gateway in front of it, may answer.
+ The first three are the answers of pipelex's runner to `POST /v1/execute` in the error contract's acceptance on
+ 2026-10-17, as both standard clients received them: a run missing a required input, a pipe whose output has another
+ multiplicity than the one declared, and a method naming a model the runner serves no backend for, refused before
+ any pipe ran with the fault as its one item. The last is a problem whose items carry suggestions and a suggested fix.
"""
+ INPUT_MISSING: ClassVar[str] = (
+ '{"type": "https://mthds.ai/errors/input.missing", "title": "A required input is missing", "status": 422, '
+ '"detail": "The request does not give the input \'topic\', which the method requires.", "code": "input.missing", '
+ '"domain": "input", "retry": "no", "next_step": {"kind": "change_input", "detail": "Add the input \'topic\' to the '
+ 'request, then send it again."}, "params": {"input": "topic"}, "location": {"pipe": "write_slogan", "path": '
+ '["write_slogan"]}, "request_id": "01M55P3J09ADGMD2MW5FSN6S1P"}'
+ )
+ OUTPUT_MULTIPLICITY: ClassVar[str] = (
+ '{"type": "https://mthds.ai/errors/pipe.output_multiplicity", "title": "A pipe\'s output does not have the declared '
+ 'multiplicity", "status": 422, "detail": "Pipe \'review_topic\' produced an output of the multiplicity \'list\', but '
+ 'its output \'ideas\' is declared \'single\'.", "code": "pipe.output_multiplicity", "domain": "method", "retry": "no", '
+ '"next_step": {"kind": "change_method", "detail": "Declare the output \'ideas\' as \'list\', or make pipe '
+ '\'review_topic\' produce \'single\'."}, "params": {"output": "ideas", "declared": "single", "produced": "list", '
+ '"pipe": "review_topic"}, "location": {"pipe": "review_topic", "path": ["review_topic"]}, '
+ '"request_id": "01M55P71KM9SGEV908K0PNXJ44"}'
+ )
UNKNOWN_MODEL_AT_LOAD: 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\\n\\n"
- 'Did you mean: gpt-5.5, gpt-5.4, gpt-5.6-sol, gpt-5.4-pro, gpt-5.6-luna","instance":"/v1/execute",'
- '"request_id":"req_a3dd6900-7909-48d3-b551-0140e73ac7fc","error_category":"configuration","error_domain":"input",'
- '"retryable":false,"error_type":"ValidateBundleError","validation_errors":[{"category":"pipe_validation",'
- "\"message\":\"Pipe 'draft_pitch' (PipeLLM), field 'model': Model handle 'gpt-5.1' was not found in the model deck\\n\\n"
- 'Did you mean: gpt-5.5, gpt-5.4, gpt-5.6-sol, gpt-5.4-pro, gpt-5.6-luna","error_type":"unknown_model",'
- '"pipe_code":"draft_pitch","domain_code":"sales_copy","field_path":"pipe.draft_pitch.model","field_name":"model",'
- '"model_reference":"gpt-5.1","model_type":"llm","suggestions":["gpt-5.5","gpt-5.4","gpt-5.6-sol","gpt-5.4-pro","gpt-5.6-luna"]}],'
- '"user_action":{"kind":"change_input","detail":"Edit the bundle as each validation error says: apply its suggested fix '
- 'where it has one, after confirming an unsafe one"}}'
- )
- UNKNOWN_MODEL_DETAIL: ClassVar[str] = (
- "Pipe 'draft_pitch' (PipeLLM), field 'model': Model handle 'gpt-5.1' was not found in the model deck\n\n"
- "Did you mean: gpt-5.5, gpt-5.4, gpt-5.6-sol, gpt-5.4-pro, gpt-5.6-luna"
- )
- UNKNOWN_MODEL_NEXT_STEP: ClassVar[str] = (
- "Edit the bundle as each validation error says: apply its suggested fix where it has one, after confirming an unsafe one"
- )
-
- COMBINE_FAILURE_AT_RUN: ClassVar[str] = (
- '{"type":"https://docs.pipelex.com/latest/errors/stuff-factory-error/","title":"Stuff factory","status":422,'
- "\"detail\":\"Pipe 'analyze_topics' failed (review_topics → analyze_topics): PipeParallel 'analyze_topics' cannot "
- "combine its branch results into its output 'TopicReview'. Branch 'draft_ideas' gives result 'ideas' as a list, "
- "'Idea[]', but field 'ideas' of 'TopicReview' holds a single item. Declare the field as a list in the structure of "
- "'TopicReview', with type 'list', item_type 'concept' and item_concept_ref 'Idea', or make branch 'draft_ideas' output "
- 'a single \'Idea\'.","instance":"/v1/execute","request_id":"req_d4212542-63a6-4ddb-87c9-4b968785c8c5",'
- '"error_domain":"input","error_type":"StuffFactoryError","user_action":{"kind":"change_input","detail":"Branch '
- "'draft_ideas' gives result 'ideas' as a list, 'Idea[]', but field 'ideas' of 'TopicReview' holds a single item. "
- "Declare the field as a list in the structure of 'TopicReview', with type 'list', item_type 'concept' and "
- "item_concept_ref 'Idea', or make branch 'draft_ideas' output a single 'Idea'.\"}}"
- )
- COMBINE_FAILURE_NEXT_STEP: ClassVar[str] = (
- "Branch 'draft_ideas' gives result 'ideas' as a list, 'Idea[]', but field 'ideas' of 'TopicReview' holds a single item. "
- "Declare the field as a list in the structure of 'TopicReview', with type 'list', item_type 'concept' and "
- "item_concept_ref 'Idea', or make branch 'draft_ideas' output a single 'Idea'."
- )
-
- UNSERVED_MODEL_AT_RUN: ClassVar[str] = (
- '{"type":"https://docs.pipelex.com/latest/errors/model-not-found-error/","title":"Model not found","status":422,'
- "\"detail\":\"Pipe 'condense_article' failed (digest_article → condense_article): Model handle 'gpt-5.1' was not "
- 'found in the model deck.","instance":"/v1/execute","request_id":"req_b7d2c66f-b2d5-4dc7-bd4f-6cf98abfbdc0",'
- '"error_category":"configuration","error_domain":"input","retryable":false,"error_type":"ModelNotFoundError",'
- '"user_action":{"kind":"change_model","detail":"Change the model \'gpt-5.1\' to an LLM the model deck serves."}}'
- )
- UNSERVED_MODEL_DETAIL: ClassVar[str] = (
- "Pipe 'condense_article' failed (digest_article → condense_article): Model handle 'gpt-5.1' was not found in the model deck."
- )
- UNSERVED_MODEL_NEXT_STEP: ClassVar[str] = "Change the model 'gpt-5.1' to an LLM the model deck serves."
-
- # The hosted plane's own refusals, authored in front of the runner with no `user_action`, `error_domain` or
- # `retryable`: the platform's rate limiter (sent with a `Retry-After` header), the API gateway's refusal of a
- # key (a bare `message`, no problem members at all), and the platform failing to reach the runner.
- PLATFORM_RATE_LIMITED: ClassVar[str] = (
- '{"type":"https://pipelex.com/errors/rate_limited","title":"Too Many Requests","status":429,"code":"rate_limited",'
- '"detail":"Rate limit of 600 requests/minute exceeded for this organization. Retry in 12s.",'
- '"instance":"urn:request:req_rate","request_id":"req_rate","errors":[]}'
- )
- GATEWAY_FORBIDDEN: ClassVar[str] = '{"message":"Forbidden"}'
- PLATFORM_RUNNER_UNREACHABLE: ClassVar[str] = (
- '{"type":"https://pipelex.com/errors/service_unavailable","title":"Service Unavailable","status":503,'
- '"code":"service_unavailable","detail":"The runner is unreachable (/execute). Retry shortly.","request_id":"req_down","errors":[]}'
- )
- # Not a problem document: a gateway's error page in front of the runner.
- GATEWAY_HTML: ClassVar[str] = "<html><head><title>502 Bad Gateway</title></head><body><h1>502 Bad Gateway</h1></body></html>"
- # A refusal carrying the failing pipe and its path as members, and an item of a kind this pipelex does not know.
- LOCATED_WITH_UNKNOWN_ITEM: ClassVar[str] = (
- '{"type":"https://docs.pipelex.com/latest/errors/stuff-factory-error/","title":"Stuff factory","status":422,'
- '"detail":"Pipe \'analyze_topics\' failed (review_topics → analyze_topics): the branches do not combine.",'
- '"request_id":"req_future","error_domain":"input","retryable":true,"error_type":"StuffFactoryError",'
- '"pipe_code":"analyze_topics","pipe_stack":["review_topics","analyze_topics"],'
- '"validation_errors":[{"category":"pipe_validation","message":"A kind of fault from a newer runner",'
- '"error_type":"some_future_fault","pipe_code":"analyze_topics"}]}'
- )
-
-
-class RefusalCase(NamedTuple):
- """One of the dev plane's refused runs, and what the agent must read in its envelope."""
-
- topic: str
- body: str
- error_type: str
- reason: str
- next_step: str
- failing_pipe: str
-
-
-class RefusalCases:
- """The dev plane's three refused runs of the execution-errors acceptance, as the agent CLI must report them."""
-
- DEV_PLANE: ClassVar[list[RefusalCase]] = [
- RefusalCase(
- topic="unknown_model_at_load",
- body=RefusedRunBodies.UNKNOWN_MODEL_AT_LOAD,
- error_type="ValidateBundleError",
- reason=RefusedRunBodies.UNKNOWN_MODEL_DETAIL,
- next_step=RefusedRunBodies.UNKNOWN_MODEL_NEXT_STEP,
- failing_pipe="draft_pitch",
+ '{"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": "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-4.5-haiku\', which no catalog knows.", "params": {"model": "claude-4.5-haiku", "model_type": "llm"}, '
+ '"location": {"pipe": "write_slogan", "field": "model"}}], "request_id": "01M55P9XMCX78NQJ1R8QBV9B4F"}'
+ )
+ ITEMS_WITH_SUGGESTIONS: ClassVar[str] = (
+ '{"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": "Fix each fault the problem\'s errors list, then validate the '
+ 'method again."}, "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", "suggestions": ["gpt-5.5", '
+ '"gpt-5.4"]}, "location": {"pipe": "draft_pitch", "field": "model"}, "suggestions": ["gpt-5.5", "gpt-5.4"], '
+ '"suggested_fix": {"fix_code": "rename-model", "description": "Replace model \'gpt-5.1\' of pipe \'draft_pitch\' '
+ 'with \'gpt-5.5\'", "safety": "unsafe", "ops": [{"kind": "set_key", "table_path": ["pipe", "draft_pitch"], '
+ '"key": "model", "value": "gpt-5.5"}]}}], "request_id": "01M55PSUGGESTIONS00000000000"}'
+ )
+
+
+#: A run stopped by an operator, as a runner answers it to its operator: the operator's next step, which reads the run's
+#: record, and the diagnostics only an operator reads. The caller of such a runner reports it instead.
+_OPERATOR_VIEW_OF_A_STOPPED_RUN: dict[str, Any] = {
+ "type": "https://mthds.ai/errors/run.terminated",
+ "title": "The run was stopped by an operator or an erasure",
+ "status": 409,
+ "detail": "The run was stopped before it ended (ended by: operator).",
+ "code": "run.terminated",
+ "domain": "operator",
+ "retry": "no",
+ "next_step": {"kind": "read_run", "detail": "Read the run's record to see when and why it was stopped."},
+ "params": {"ended_by": "operator"},
+}
+_OPERATOR_DIAGNOSTICS: dict[str, Any] = {"error_class": "RunTerminatedError", "message": "terminated from the console"}
+
+
+class OperatorViewAnswers:
+ """A runner's answers in its operator's view, each with one of Pipelex's members in a shape this version does not read."""
+
+ # The diagnostics read, the request id does not.
+ UNREADABLE_REQUEST_ID: ClassVar[str] = json.dumps({**_OPERATOR_VIEW_OF_A_STOPPED_RUN, "request_id": 12345, "diagnostics": _OPERATOR_DIAGNOSTICS})
+ # The request id reads, the diagnostics do not.
+ UNREADABLE_DIAGNOSTICS: ClassVar[str] = json.dumps(
+ {**_OPERATOR_VIEW_OF_A_STOPPED_RUN, "request_id": "01M55PREQUEST0000000000000", "diagnostics": 7}
+ )
+ # The problem the caller reads for either: the caller's next step, and no diagnostics.
+ CALLER_VIEW: ClassVar[dict[str, Any]] = {
+ **_OPERATOR_VIEW_OF_A_STOPPED_RUN,
+ "next_step": {"kind": "report", "detail": "Report this to whoever runs the runtime if the run was still wanted."},
+ }
+ # A read of a failed run's results in the caller's view, nesting the run's stored record in its operator's view with
+ # no diagnostics to tell it by: the nested problem is the run's record, so it reads in the caller's view all the same.
+ NESTING_THE_OPERATOR_S_RECORD: ClassVar[str] = json.dumps(
+ {
+ "type": "https://mthds.ai/errors/run.failed",
+ "title": "The run did not succeed",
+ "status": 409,
+ "detail": "The run 'run_9' ended as 'TERMINATED', without success.",
+ "code": "run.failed",
+ "domain": "runtime",
+ "retry": "no",
+ "next_step": {"kind": "read_run", "detail": "Read the run's own problem in run_error to see why it did not succeed."},
+ "params": {"pipeline_run_id": "run_9", "run_status": "TERMINATED"},
+ "pipeline_run_id": "run_9",
+ "run_error": _OPERATOR_VIEW_OF_A_STOPPED_RUN,
+ }
+ )
+ # Pipelex's members in shapes no version reads, the nested run's problem included: none of them may stop the report.
+ HOSTILE: ClassVar[tuple[str, ...]] = (
+ json.dumps({**_OPERATOR_VIEW_OF_A_STOPPED_RUN, "run_error": "not a problem"}),
+ json.dumps({**_OPERATOR_VIEW_OF_A_STOPPED_RUN, "run_error": {"code": 5, "diagnostics": []}}),
+ json.dumps({**_OPERATOR_VIEW_OF_A_STOPPED_RUN, "request_id": ["x"], "diagnostics": "x", "run_error": []}),
+ json.dumps(
+ {
+ **_OPERATOR_VIEW_OF_A_STOPPED_RUN,
+ "request_id": {"id": 1},
+ "run_error": {**_OPERATOR_VIEW_OF_A_STOPPED_RUN, "request_id": 9, "diagnostics": "x", "run_error": {"title": 3}},
+ }
),
- RefusalCase(
- topic="combine_failure_at_run",
- body=RefusedRunBodies.COMBINE_FAILURE_AT_RUN,
- error_type="StuffFactoryError",
- reason=(
- "Pipe 'analyze_topics' failed (review_topics → analyze_topics): PipeParallel 'analyze_topics' cannot combine its branch "
- f"results into its output 'TopicReview'. {RefusedRunBodies.COMBINE_FAILURE_NEXT_STEP}"
+ )
+
+
+#: A refused run whose problem carries, at every level, members neither the standard nor Pipelex declares: those the
+#: runner's API-authored errors write (`error_type`, `error_domain`, `retryable`), RFC 9457's `instance`, and others.
+_PROBLEM_WITH_UNDECLARED_MEMBERS: dict[str, Any] = {
+ "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": "Fix each fault the problem's errors list, then validate the method again.", "hint": "x"},
+ "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": "draft_pitch", "field": "model", "source": "main.mthds"},
+ "suggestions": ["gpt-5.5"],
+ "suggested_fix": {
+ "fix_code": "rename-model",
+ "description": "Replace model 'gpt-5.1' of pipe 'draft_pitch' with 'gpt-5.5'",
+ "safety": "unsafe",
+ "ops": [{"kind": "set_key", "table_path": ["pipe", "draft_pitch"], "key": "model", "value": "gpt-5.5"}],
+ "error_code": "unknown_model",
+ },
+ "error_type": "unknown_model",
+ "error_category": "pipe_validation",
+ }
+ ],
+ "location": {"pipe": "draft_pitch", "pipe_stack": ["draft_pitch"]},
+ "request_id": "01M55PUNDECLARED0000000000",
+ "instance": "urn:pipelex:request:01M55PUNDECLARED0000000000",
+ "error_type": "PipeValidationError",
+ "error_domain": "input",
+ "retryable": False,
+ "hint": "Fix the method",
+ "http_status": 422,
+ "validation_errors": [{"category": "pipe_validation", "message": "unknown model"}],
+}
+
+
+class UndeclaredMembers:
+ """A runner's problem carrying members no reader declares, and what the agent CLI reports of it: its declared members alone."""
+
+ SENT: ClassVar[str] = json.dumps(_PROBLEM_WITH_UNDECLARED_MEMBERS)
+ REPORTED: ClassVar[dict[str, Any]] = {
+ "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": "Fix each fault the problem's errors list, then validate the method again."},
+ "location": {"pipe": "draft_pitch"},
+ "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": "draft_pitch", "field": "model"},
+ "suggestions": ["gpt-5.5"],
+ "suggested_fix": {
+ "fix_code": "rename-model",
+ "description": "Replace model 'gpt-5.1' of pipe 'draft_pitch' with 'gpt-5.5'",
+ "safety": "unsafe",
+ "ops": [{"kind": "set_key", "table_path": ["pipe", "draft_pitch"], "key": "model", "value": "gpt-5.5"}],
+ },
+ }
+ ],
+ "request_id": "01M55PUNDECLARED0000000000",
+ }
+
+
+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."""
+
+ # A gateway's error page in front of the runner.
+ HTML_PAGE: ClassVar[str] = "<html><head><title>502 Bad Gateway</title></head><body><h1>502 Bad Gateway</h1></body></html>"
+ # A server that does not serve the route at all, as a framework answers it.
+ 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'."
),
- next_step=RefusedRunBodies.COMBINE_FAILURE_NEXT_STEP,
- failing_pipe="analyze_topics",
- ),
- RefusalCase(
- topic="unserved_model_at_run",
- body=RefusedRunBodies.UNSERVED_MODEL_AT_RUN,
- error_type="ModelNotFoundError",
- reason=RefusedRunBodies.UNSERVED_MODEL_DETAIL,
- next_step=RefusedRunBodies.UNSERVED_MODEL_NEXT_STEP,
- failing_pipe="condense_article",
- ),
+ "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},
+ }
+ )
+
+
+class RetiredEnvelope:
+ """The members of the error envelope this CLI wrote before it reported problems, none of which a problem carries."""
+
+ MEMBERS: ClassVar[tuple[str, ...]] = (
+ "error",
+ "error_type",
+ "error_source",
+ "error_domain",
+ "error_category",
+ "error_code",
+ "hint",
+ "retryable",
+ "http_status",
+ "validation_errors",
+ "pipe_code",
+ "pipe_stack",
+ "retry_after_seconds",
+ "run_status",
+ )
+
+
+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, 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",
+ "title": "A pipe's output does not have the declared multiplicity",
+ "detail": "Pipe 'review_topic' produced an output of the multiplicity 'list', but its output 'ideas' is declared 'single'.",
+ "code": "pipe.output_multiplicity",
+ "domain": "method",
+ "retry": "no",
+ "next_step": {"kind": "change_method", "detail": "Declare the output 'ideas' as 'list', or make pipe 'review_topic' produce 'single'."},
+ "params": {"output": "ideas", "declared": "single", "produced": "list", "pipe": "review_topic"},
+ "location": {"pipe": "review_topic", "path": ["review_topic"]},
+ "diagnostics": {"error_class": "PipeOutputMultiplicityError", "message": "the branches do not combine"},
+ }
+ # The same problem with the members the hosted plane's stored report carries beside it, which no reader of the
+ # problem declares, its own diagnostics in a shape this version does not read.
+ PROBLEM_WITH_REPORT_MEMBERS: ClassVar[dict[str, Any]] = {
+ **PROBLEM,
+ "diagnostics": "unreadable",
+ "message": "the branches do not combine",
+ "error_type": "PipeOutputMultiplicityError",
+ "error_domain": "input",
+ "error_category": "validation",
+ "retryable": False,
+ "caller_facing_message": "The pipe's output has another multiplicity",
+ "provider_metadata": {"region": "eu"},
+ "validation_errors": [{"category": "pipe_validation", "message": "multiplicity"}],
+ }
+
+
+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."""
+
+ 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"]},
+ "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"},
+ },
]
+
+
+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(
+ {
+ "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],
+ }
+ )
diff --git a/tests/unit/pipelex/cli/agent_cli/test_fix_format.py b/tests/unit/pipelex/cli/agent_cli/test_fix_format.py
index f8102a365..6284a1e63 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_fix_format.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_fix_format.py
@@ -228,7 +228,9 @@ class TestFixFormat:
assert captured.out == ""
assert captured.err.startswith("## The method does not validate")
assert "Fix loop stopped after 1 iteration(s)" in captured.err
- assert "## Pipe validation errors" in captured.err
+ assert "### Errors\n\n- `" in captured.err
+ assert f"file '{bundle_path}')" in captured.err
+ assert "## Pipe validation errors" not in captured.err
assert "### Applied Fixes" in captured.err
assert "**Stopped:** no safe fixes remain" in captured.err
assert f"- **bundle_path:** {bundle_path.resolve()}" in captured.err
diff --git a/tests/unit/pipelex/cli/agent_cli/test_folder_entry_commands.py b/tests/unit/pipelex/cli/agent_cli/test_folder_entry_commands.py
index a5e1df6fe..75417ddb7 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_folder_entry_commands.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_folder_entry_commands.py
@@ -210,9 +210,13 @@ class TestAgentFolderEntryCommands:
assert problem["iterations"] == 0
assert problem["fixes_applied"] == []
assert problem["files_written"] == []
- assert [item["code"] for item in problem["errors"]] == ["method.package_invalid"]
+ (item,) = problem["errors"]
+ # The item names the rule the tree breaks and the file at fault, the symbolic link, without quoting the refusal.
+ assert item["code"] == "method.package_invalid"
+ assert item["params"] == {"reason": "symbolic_link", "path": "linked.mthds"}
+ assert item["location"]["file"] == "linked.mthds"
- # The Markdown renders the remaining errors as prose, the refusal naming the file the tree refused.
+ # The Markdown lists the same item, naming the file the tree refused.
with pytest.raises(typer.Exit):
fix_bundle_cmd(path=str(tmp_path), error_format=CliOutputFormat.MARKDOWN)
assert "linked.mthds" in capsys.readouterr().err
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 5a9b53021..9123f5a8d 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
@@ -1,4 +1,4 @@
-"""Unit tests: `pipelex-agent run … --runner hosted` answers in the run envelope a local run answers in.
+"""Unit tests: `pipelex-agent run … --runner hosted` answers in the run envelope a local run answers in, and fails with a problem.
`run_hosted` is mocked at the agent CLI seam, so no request leaves.
"""
@@ -12,9 +12,19 @@ from typing import TYPE_CHECKING, Any
import pytest
import typer
+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 MissingMainStuffError, RunFailedError, RunTimeoutError
+from pipelex_sdk.errors import (
+ ApiResponseError,
+ InvalidLocalSourceError,
+ MissingMainStuffError,
+ PipelexRequestError,
+ PipelineExecuteTimeoutError,
+ RunFailedError,
+ RunTimeoutError,
+ UnsupportedUploadCapabilityError,
+)
from pipelex_sdk.runs import RunResults, RunStatus
from pipelex_sdk.upload import UploadRecord
from pipelex_sdk.validation_models import ValidationErrorItem
@@ -26,10 +36,12 @@ 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.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.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
if TYPE_CHECKING:
from pathlib import Path
@@ -41,6 +53,8 @@ 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,
@@ -104,82 +118,168 @@ class TestRunHostedEnvelope:
run_hosted.assert_awaited_once()
assert json.loads(capsys.readouterr().out) == STATS
- def test_a_failed_run_reports_its_stored_error(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:
- """A run that started and failed names the runner's class, its next step, its domain and the run."""
- report = RunErrorReport.model_validate(
- {
- "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"},
- }
- )
+ @pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])
+ 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.
+ """
+ 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
)
mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=failed))
with pytest.raises(typer.Exit) as exc_info:
- 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)
assert exc_info.value.exit_code == 1
- envelope = json.loads(capsys.readouterr().err)
- assert envelope["error_type"] == "LLMCompletionError"
- assert envelope["message"] == "Run finished with status FAILED: The provider refused the prompt"
- assert envelope["hint"] == "Run it again in a minute"
- assert envelope["error_domain"] == "runtime"
- assert envelope["error_category"] == "transient"
- assert envelope["retryable"] is True
- assert envelope["model"] == "claude-5.5-sonnet"
- assert envelope["pipeline_run_id"] == "run_9"
- assert envelope["run_status"] == "FAILED"
-
- def test_an_unexpected_failure_is_an_envelope(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:
- """A failure no hosted arm names, such as a results body that drifted, still leaves as the JSON envelope."""
- with pytest.raises(ValidationError) as drift:
- RunResults.model_validate({"main_stuff": 1})
- mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=drift.value))
+ printed = capsys.readouterr().err
+ 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["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
+
+ @pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])
+ def test_a_failed_run_s_former_report_gives_its_items_and_its_advice(
+ 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.
+ """
+ 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)
+ mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=failed))
- 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)
+
+ 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
+ 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]],
+ }
+ 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 "ValidateBundleError" not in printed
+
+ @pytest.mark.parametrize(
+ "stored_report",
+ [StoredRunReports.PROBLEM, StoredRunReports.PROBLEM_WITH_REPORT_MEMBERS],
+ ids=["problem", "problem_with_report_members"],
+ )
+ 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.
+ """
+ report = RunErrorReport.model_validate(stored_report)
+ failed = RunFailedError("Run finished with status FAILED", run_id="run_9", status=RunStatus.FAILED, error=report)
+ 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=CliOutputFormat.JSON)
- assert exc_info.value.exit_code == 1
- envelope = json.loads(capsys.readouterr().err)
- assert envelope["error"] is True
- assert envelope["error_type"] == "ValidationError"
- # The catch-all's code, `runtime.unexpected`, gives the next step an agent reads as the hint.
- assert envelope["hint"] == make_problem(code=CoreCode.RUNTIME_UNEXPECTED, view=ProblemView.OPERATOR).next_step.detail
+ problem = json.loads(capsys.readouterr().err)
+ assert problem["code"] == "run.failed"
+ stored = {name: value for name, value in StoredRunReports.PROBLEM.items() if name != "diagnostics"}
+ assert problem["run_error"] == stored
- def test_a_hosted_verdict_that_the_failure_is_not_retryable_wins_over_the_local_table(
- self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]
- ) -> None:
- """The local table calls this class retryable; the hosted runner said it is not, and only it knows."""
- report = RunErrorReport.model_validate(
- {
- "error_type": "PipeOperatorModelAvailabilityError",
- "message": "no model available for the pipe",
- "error_domain": "config",
- "retryable": False,
- }
- )
- failed = RunFailedError(
- "Run finished with status FAILED: no model available for the pipe", run_id="run_f3", status=RunStatus.FAILED, error=report
- )
+ 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)
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=CliOutputFormat.MARKDOWN)
+
+ markdown = capsys.readouterr().err
+ assert (
+ "### The run's own problem\n\n#### A pipe's output does not have the declared multiplicity\n\nPipe 'review_topic' produced "
+ "an output of the multiplicity 'list', but its output 'ideas' is declared 'single'.\n"
+ ) in markdown
+ assert "- Code: `pipe.output_multiplicity` (domain method, retry no)" in markdown
+ assert "PipeOutputMultiplicityError" not in markdown
+
+ def test_a_pipelex_error_no_hosted_arm_names_reports_its_own_code(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:
+ """A Pipelex error of this process's that is no hosted run's leaves as a local failure does, under its own code in the operator's view."""
+ config_error = PipelexConfigError("pipelex.toml is invalid")
+ mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=config_error))
+
+ with pytest.raises(typer.Exit) as exc_info:
+ run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)
+
+ assert exc_info.value.exit_code == 1
+ problem = json.loads(capsys.readouterr().err)
+ assert problem["code"] == "pipelex.config.invalid"
+ assert problem["next_step"] == config_error.to_problem(view=ProblemView.OPERATOR).next_step.as_wire()
+ assert problem["diagnostics"]["error_class"] == "PipelexConfigError"
+
+ def test_an_unexpected_failure_is_this_process_s_own_problem(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:
+ """A failure no hosted arm names, such as a results body that drifted, is `runtime.unexpected`, as a local run reports it."""
+ with pytest.raises(ValidationError) as drift:
+ RunResults.model_validate({"main_stuff": 1})
+ mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=drift.value))
+
+ with pytest.raises(typer.Exit) as exc_info:
run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)
- envelope = json.loads(capsys.readouterr().err)
- assert envelope["error_type"] == "PipeOperatorModelAvailabilityError"
- assert envelope["retryable"] is False
- assert envelope["error_domain"] == "config"
+ assert exc_info.value.exit_code == 1
+ problem = json.loads(capsys.readouterr().err)
+ assert problem["code"] == "runtime.unexpected"
+ assert problem["next_step"] == make_problem(code=CoreCode.RUNTIME_UNEXPECTED, view=ProblemView.OPERATOR).next_step.as_wire()
+ assert problem["diagnostics"]["error_class"] == "ValidationError"
+ for retired in RetiredEnvelope.MEMBERS:
+ assert retired not in problem
@pytest.mark.parametrize("interruption", [KeyboardInterrupt(), asyncio.CancelledError()])
- def test_an_interrupted_run_is_an_envelope_naming_the_run_and_exits_130(
+ def test_an_interrupted_run_names_the_run_and_exits_130(
self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], interruption: BaseException
) -> None:
def _started_then_interrupted(**kwargs: Any) -> HostedRunOutcome:
@@ -194,46 +294,194 @@ class TestRunHostedEnvelope:
assert exc_info.value.exit_code == 130
captured = capsys.readouterr()
assert captured.out == ""
- envelope = json.loads(captured.err)
- assert envelope["error_type"] == "HostedRunInterruptedError"
- assert envelope["pipeline_run_id"] == "run_77"
- assert "keeps going on the hosted API" in envelope["message"]
- assert "run_77" in envelope["hint"]
+ problem = json.loads(captured.err)
+ assert problem["code"] == "client.follow_failed"
+ assert problem["pipeline_run_id"] == "run_77"
+ assert problem["params"] == {"pipeline_run_id": "run_77"}
+ assert problem["next_step"] == {"kind": "read_run", "detail": "Read the run 'run_77' by its id rather than start it again."}
+ assert "keeps going on the hosted API" in problem["message"]
+ assert "diagnostics" not in problem
+
+ def test_a_run_interrupted_before_its_acknowledgement_leaves_the_outcome_unknown(
+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]
+ ) -> None:
+ mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=KeyboardInterrupt()))
+
+ with pytest.raises(typer.Exit) as exc_info:
+ run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)
+
+ assert exc_info.value.exit_code == 130
+ problem = json.loads(capsys.readouterr().err)
+ assert problem["code"] == "client.outcome_unknown"
+ assert "pipeline_run_id" not in problem
+
+ @pytest.mark.parametrize(
+ ("error", "code", "message"),
+ [
+ (
+ RunTimeoutError("Run 'run_7' did not finish within 1200s", run_id="run_7", timeout_seconds=1200.0),
+ "run.not_finished",
+ "Run 'run_7' did not finish within 1200s",
+ ),
+ (
+ MissingMainStuffError("Completed run 'run_7' returned no main stuff", run_id="run_7"),
+ "client.response_unreadable",
+ "Completed run 'run_7' returned no main stuff",
+ ),
+ (
+ HostedRunPollingError("The run run_7 started on the hosted API, but following it failed", pipeline_run_id="run_7"),
+ "client.follow_failed",
+ "The run run_7 started on the hosted API, but following it failed",
+ ),
+ ],
+ ids=["timed_out", "no_main_output", "follow_failed"],
+ )
+ @pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])
+ def test_an_error_after_the_start_carries_the_run_id_and_what_the_client_said(
+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], error: Exception, code: str, message: str, error_format: CliOutputFormat
+ ) -> None:
+ """The client's sentence says what the code cannot (how long it waited, that a completed run delivered nothing): it is the `message`."""
+ 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=error_format)
+
+ printed = capsys.readouterr().err
+ match error_format:
+ case CliOutputFormat.JSON:
+ problem = json.loads(printed)
+ assert problem["code"] == code
+ assert problem["pipeline_run_id"] == "run_7"
+ assert problem["message"] == message
+ for retired in RetiredEnvelope.MEMBERS:
+ assert retired not in problem
+ case CliOutputFormat.MARKDOWN:
+ assert message in printed
+ assert f"- Code: `{code}`" in printed
@pytest.mark.parametrize(
"error",
[
+ PipelineExecuteTimeoutError("The blocking execute was cut off after 30s", elapsed_seconds=30.0),
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"),
+ UnsupportedUploadCapabilityError("The deployment takes no uploads", filename="a.pdf"),
+ InvalidLocalSourceError("Cannot read ./missing.pdf", source="./missing.pdf"),
],
+ ids=["blocking_execute_cut_off", "timed_out", "no_uploads", "unreadable_local_file"],
)
- def test_an_error_after_the_start_carries_the_run_id(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], error: Exception) -> None:
+ def test_a_client_side_failure_gives_the_next_step_the_human_cli_gives(
+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], error: PipelexRequestError
+ ) -> None:
+ """A failure the client meets on its side takes the step tailored for it, the one `pipelex run --hosted` prints,
+ with the kind its code gives, so both CLIs tell the same thing.
+ """
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)
- envelope = json.loads(capsys.readouterr().err)
- assert envelope["error_type"] == type(error).__name__
- assert envelope["pipeline_run_id"] == "run_7"
- assert "run_7" in envelope["hint"]
+ problem = json.loads(capsys.readouterr().err)
+ assert problem["code"] == error.problem.code
+ assert problem["next_step"] == {"kind": error.problem.next_step.kind, "detail": describe_hosted_error(error=error).next_step}
+
+ @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
+ ) -> 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.
+ """
+ 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}),
+ )
+ mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=refusal))
- def test_a_method_that_does_not_load_lists_its_labelled_items(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:
- item = ValidationErrorItem.model_validate(
- {"category": "blueprint_validation", "message": "unknown concept Foo", "source": "lib/b.mthds", "pipe_code": "step2"}
+ with pytest.raises(typer.Exit) as exc_info:
+ 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},
+ }
+ 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]]
+
+ 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]
+ ) -> 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`.
+ """
+ refused = HostedMethodInvalidError(
+ "The hosted API cannot load the method: Bundle does not load",
+ validation_errors=[ValidationErrorItem.model_validate(HostedMethodItems.SENT_WITH_AN_UNREADABLE_FIX)],
)
- refused = HostedMethodInvalidError("The hosted API cannot load the method: Bundle does not load", validation_errors=[item])
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)
- envelope = json.loads(capsys.readouterr().err)
- assert envelope["error_type"] == "HostedMethodInvalidError"
- assert envelope["error_domain"] == "input"
- assert envelope["validation_errors"][0]["source"] == "lib/b.mthds"
- assert envelope["validation_errors"][0]["message"] == "unknown concept Foo"
+ 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)
+
+ 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
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 8e508abe3..d3a85685b 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,41 +1,46 @@
-"""Unit tests: `pipelex-agent run … --runner hosted` renders the hosted API's refusal the way it renders a local failure.
+"""Unit tests: `pipelex-agent run … --runner hosted` reports a refused, failed or unreachable run as the problem it got.
-The answers are the dev plane'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, so no test
-reaches the network.
+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.
"""
from __future__ import annotations
-import asyncio
import io
import json
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
import httpx
import pytest
import typer
from pipelex_sdk.client import PipelexAPIClient
-from pipelex_sdk.errors import ApiResponseError
-from pipelex.cli.agent_cli.commands.agent_output import (
- CliOutputFormat,
- agent_error_api_response,
- api_response_error_payload,
- set_agent_cli_error_format,
-)
+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.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_SERVER_FAULT_NEXT_STEP,
+ 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 RefusalCase, RefusalCases, RefusedRunBodies
+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
if TYPE_CHECKING:
@@ -46,55 +51,107 @@ if TYPE_CHECKING:
HOSTED_URL = "https://hosted.test"
RUN_PIPE_MODULE = "pipelex.cli.agent_cli.commands.run.pipe_cmd"
START_ROUTE = ("POST", "/v1/start")
+#: The request id a hosted API names in its `X-Request-ID` header.
+HEADER_REQUEST_ID = "01M55PHEADER000000000000000"
+#: The problem pipelex-sdk decides for a runner that cannot be reached at `HOSTED_URL`, the base client's own, with the
+#: next step the human CLI gives it.
+UNREACHABLE_PROBLEM: dict[str, Any] = {
+ "type": "https://mthds.ai/errors/client.unreachable",
+ "title": "The runtime could not be reached",
+ "detail": f"The client could not connect to the runtime at {HOSTED_URL}.",
+ "code": "client.unreachable",
+ "domain": "runtime",
+ "retry": "yes",
+ "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.
+RUNNER_FAULT: str = json.dumps(
+ {
+ "type": "https://mthds.ai/errors/runtime.unexpected",
+ "title": "The runtime met an unexpected error",
+ "status": 500,
+ "detail": "The runtime met an unexpected error.",
+ "code": "runtime.unexpected",
+ "domain": "runtime",
+ "retry": "no",
+ "next_step": {"kind": "report", "detail": "Report this to whoever runs the runtime."},
+ }
+)
-def _answering(*, status: int, body: str, seen: list[httpx.Request], headers: dict[str, str] | None = None) -> httpx.MockTransport:
- """A hosted API that answers its version, then refuses every other request with ``status``, ``body`` and ``headers``."""
+def _answering(
+ *, status: int, body: str, seen: list[httpx.Request], headers: dict[str, str] | None = None, version: str = HostedVersions.HOSTED
+) -> httpx.MockTransport:
+ """A runner that answers its ``version``, then refuses every other request with ``status``, ``body`` and ``headers``."""
def _handler(request: httpx.Request) -> httpx.Response:
seen.append(request)
if request.method == "GET" and request.url.path == "/v1/version":
- return httpx.Response(200, content=HostedVersions.HOSTED.encode("utf-8"), headers={"content-type": "application/json"})
- return httpx.Response(status, content=body.encode("utf-8"), headers={"content-type": "application/problem+json", **(headers or {})})
+ return httpx.Response(200, content=version.encode("utf-8"), headers={"content-type": "application/json"})
+ answer_headers = {"content-type": "application/problem+json", **(headers or {})}
+ return httpx.Response(status, content=body.encode("utf-8"), headers=answer_headers)
return httpx.MockTransport(_handler)
-def _install_hosted_api(mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, *, status: int, body: str) -> list[httpx.Request]:
- """Point every `PipelexAPIClient` at a mocked hosted API refusing with ``status`` / ``body``; return the requests it receives."""
+def _refusing_connections(request: httpx.Request) -> httpx.Response:
+ """A host where nothing listens: every connection is refused."""
+ msg = "connection refused"
+ raise httpx.ConnectError(msg, request=request)
+
+
+def _install_transport(mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, *, transport: httpx.MockTransport) -> None:
+ """Point every `PipelexAPIClient` at ``transport``, with a key and `HOSTED_URL` as the origin."""
monkeypatch.setenv(PIPELEX_API_KEY_ENV_KEY, "plx_sk_test_not_a_secret")
monkeypatch.setenv(PIPELEX_BASE_URL_ENV_KEY, HOSTED_URL)
- seen: list[httpx.Request] = []
- transport = _answering(status=status, body=body, seen=seen)
def _start_client(self: PipelexAPIClient) -> PipelexAPIClient:
self.client = httpx.AsyncClient(transport=transport)
return self
mocker.patch.object(PipelexAPIClient, "start_client", _start_client)
- return seen
-def _refusal(*, status: int, body: str, headers: dict[str, str] | None = None) -> ApiResponseError:
- """The typed error the real client raises when the hosted API answers `POST /v1/start` this way."""
+def _install_hosted_api(
+ mocker: MockerFixture,
+ monkeypatch: pytest.MonkeyPatch,
+ *,
+ status: int,
+ body: str,
+ headers: dict[str, str] | None = None,
+ version: str = HostedVersions.HOSTED,
+) -> list[httpx.Request]:
+ """Point every `PipelexAPIClient` at a mocked runner refusing with ``status`` / ``body``; return the requests it receives.
+
+ The runner answers its version as the hosted API does unless ``version`` says otherwise.
+ """
+ seen: list[httpx.Request] = []
+ _install_transport(mocker, monkeypatch, transport=_answering(status=status, body=body, seen=seen, headers=headers, version=version))
+ return seen
- async def _start() -> None:
- client = PipelexAPIClient(api_key="plx_sk_test_not_a_secret", base_url=HOSTED_URL)
- client.client = httpx.AsyncClient(transport=_answering(status=status, body=body, seen=[], headers=headers))
- try:
- await client.start(pipe_code="entry", mthds_contents=["# bundle"])
- finally:
- await client.close()
- with pytest.raises(ApiResponseError) as exc_info:
- asyncio.run(_start())
- return exc_info.value
+def _install_unreachable_api(mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch) -> None:
+ """Point every `PipelexAPIClient` at `HOSTED_URL`, where nothing listens."""
+ _install_transport(mocker, monkeypatch, transport=httpx.MockTransport(_refusing_connections))
def _routes(*, seen: list[httpx.Request]) -> list[tuple[str, str]]:
return [(request.method, request.url.path) for request in seen if request.url.path != "/v1/version"]
+def _assert_no_retired_member(*, problem: dict[str, Any]) -> None:
+ """No member of the envelope this CLI wrote before it reported problems is left in a reported problem."""
+ for retired in RetiredEnvelope.MEMBERS:
+ assert retired not in problem, retired
+
+
+def _assert_no_retired_markdown(*, markdown: str) -> None:
+ """The Markdown is the problem's: no heading, callout or member of the retired envelope, and no class name."""
+ for retired in ("# Error:", "**Hint:**", "error_type", "error_source", "error_domain", "ApiResponseError", "ApiUnreachableError"):
+ assert retired not in markdown, retired
+
+
class TestRunHostedRefusal:
@pytest.fixture
def tty_stdin(self, monkeypatch: pytest.MonkeyPatch) -> None:
@@ -111,17 +168,21 @@ class TestRunHostedRefusal:
return path
@pytest.mark.usefixtures("tty_stdin")
- @pytest.mark.parametrize("case", RefusalCases.DEV_PLANE, ids=[case.topic for case in RefusalCases.DEV_PLANE])
- def test_run_bundle_json_carries_the_reason_the_pipe_and_the_next_step(
- self,
- mocker: MockerFixture,
- monkeypatch: pytest.MonkeyPatch,
- capsys: pytest.CaptureFixture[str],
- bundle_file: Path,
- case: RefusalCase,
+ @pytest.mark.parametrize(
+ "body",
+ [
+ RunnerProblems.INPUT_MISSING,
+ RunnerProblems.OUTPUT_MULTIPLICITY,
+ RunnerProblems.UNKNOWN_MODEL_AT_LOAD,
+ RunnerProblems.ITEMS_WITH_SUGGESTIONS,
+ ],
+ ids=["input_missing", "output_multiplicity", "unknown_model_at_load", "items_with_suggestions"],
+ )
+ def test_json_is_the_runner_s_problem_as_it_came(
+ self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path, body: str
) -> None:
- """The JSON envelope of each dev-plane refusal names its class, its located reason, its next step and its domain."""
- seen = _install_hosted_api(mocker, monkeypatch, status=422, body=case.body)
+ """A refused run reaches the error stream as the problem the runner answered, member for member, its items included."""
+ seen = _install_hosted_api(mocker, monkeypatch, status=422, body=body)
with pytest.raises(typer.Exit) as exc_info:
run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)
@@ -133,84 +194,130 @@ class TestRunHostedRefusal:
assert start_body["mthds_contents"] == ["# bundle\n"]
captured = capsys.readouterr()
assert not captured.out
- envelope = json.loads(captured.err)
- assert envelope["error"] is True
- assert envelope["error_type"] == case.error_type
- assert envelope["message"] == f"API POST /v1/start failed (422): {case.reason}"
- assert envelope["hint"] == case.next_step
- assert envelope["error_domain"] == "input"
- assert envelope["http_status"] == 422
- assert envelope["request_id"].startswith("req_")
- assert "retryable" not in envelope
- assert case.failing_pipe in envelope["message"]
+ problem = json.loads(captured.err)
+ assert problem == json.loads(body)
+ _assert_no_retired_member(problem=problem)
@pytest.mark.usefixtures("tty_stdin")
- def test_run_bundle_json_carries_the_runner_items(
+ def test_markdown_reads_the_runner_s_problem(
self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path
) -> None:
- """A refusal at load hands the agent the runner's located items, each with what the runner sent."""
- _install_hosted_api(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNKNOWN_MODEL_AT_LOAD)
+ """The default Markdown renders the runner's problem as a local failure's: title, detail, next step, code, request, location."""
+ _install_hosted_api(mocker, monkeypatch, status=422, body=RunnerProblems.INPUT_MISSING)
+
+ with pytest.raises(typer.Exit) as exc_info:
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", runner=RunExecution.HOSTED)
+
+ assert exc_info.value.exit_code == 1
+ captured = capsys.readouterr()
+ assert not captured.out
+ markdown = captured.err
+ assert markdown.startswith("## A required input is missing\n\nThe request does not give the input 'topic', which the method requires.\n")
+ assert "**Next step** (`change_input`): Add the input 'topic' to the request, then send it again." in markdown
+ assert "- Code: `input.missing` (domain input, retry no)" in markdown
+ assert "- Request id: `01M55P3J09ADGMD2MW5FSN6S1P`" in markdown
+ assert "- Location: pipe 'write_slogan', path write_slogan" in markdown
+ _assert_no_retired_markdown(markdown=markdown)
+
+ @pytest.mark.usefixtures("tty_stdin")
+ def test_markdown_lists_the_runner_s_items_with_their_suggestions_and_fix(
+ self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path
+ ) -> None:
+ """The runner's items read one per line, with code, sentence, location, suggestions and fix, never as `validate`'s former prose."""
+ _install_hosted_api(mocker, monkeypatch, status=422, body=RunnerProblems.ITEMS_WITH_SUGGESTIONS)
with pytest.raises(typer.Exit):
- run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, hosted=True)
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.MARKDOWN, runner=RunExecution.HOSTED)
- envelope = json.loads(capsys.readouterr().err)
- assert envelope["error_category"] == "configuration"
- sent_items = json.loads(RefusedRunBodies.UNKNOWN_MODEL_AT_LOAD)["validation_errors"]
- assert len(envelope["validation_errors"]) == len(sent_items)
- for reported, sent in zip(envelope["validation_errors"], sent_items, strict=True):
- assert reported.items() >= sent.items()
+ markdown = capsys.readouterr().err
+ assert (
+ "### Errors\n\n"
+ "- `model.unknown`: The method names the llm model 'gpt-5.1', which no catalog knows. (pipe 'draft_pitch', field 'model')\n"
+ " - Suggestions: `gpt-5.5`, `gpt-5.4`\n"
+ " - Suggested fix (`rename-model`, unsafe, confirm before applying): Replace model 'gpt-5.1' of pipe 'draft_pitch' with 'gpt-5.5'"
+ ) in markdown
+ assert "## Pipe validation errors" not in markdown
+ _assert_no_retired_markdown(markdown=markdown)
@pytest.mark.usefixtures("tty_stdin")
- @pytest.mark.parametrize("case", RefusalCases.DEV_PLANE, ids=[case.topic for case in RefusalCases.DEV_PLANE])
- def test_run_bundle_markdown_names_the_reason_the_pipe_and_the_next_step(
+ @pytest.mark.parametrize(
+ ("status", "body"),
+ [(502, GatewayAnswers.HTML_PAGE), (500, RUNNER_FAULT)],
+ ids=["gateway_page", "runner_problem"],
+ )
+ def test_a_server_fault_on_the_run_request_leaves_the_outcome_unknown(
self,
mocker: MockerFixture,
monkeypatch: pytest.MonkeyPatch,
capsys: pytest.CaptureFixture[str],
bundle_file: Path,
- case: RefusalCase,
+ status: int,
+ body: str,
) -> None:
- """The markdown of each dev-plane refusal reads like a local failure: heading, reason, hint, details."""
- _install_hosted_api(mocker, monkeypatch, status=422, body=case.body)
+ """A 5xx on the run request may follow a run that started, so it is the client's `client.outcome_unknown`, whatever its body."""
+ _install_hosted_api(mocker, monkeypatch, status=status, body=body)
with pytest.raises(typer.Exit) as exc_info:
- 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)
assert exc_info.value.exit_code == 1
- captured = capsys.readouterr()
- assert not captured.out
- markdown = captured.err
- assert markdown.startswith(f"# Error: {case.error_type}\n\nAPI POST /v1/start failed (422): {case.reason}\n")
- assert f"> 💡 **Hint:** {case.next_step}" in markdown
- assert "Next step:" not in markdown
- assert "- **error_domain:** input" in markdown
- assert "- **http_status:** 422" in markdown
- assert case.failing_pipe in markdown
- assert "error_source" not in markdown
+ problem = json.loads(capsys.readouterr().err)
+ assert problem["code"] == "client.outcome_unknown"
+ assert problem["domain"] == "runtime"
+ assert problem["retry"] == "outcome_unknown"
+ assert problem["next_step"]["kind"] == "read_run"
+ _assert_no_retired_member(problem=problem)
@pytest.mark.usefixtures("tty_stdin")
- def test_run_bundle_markdown_renders_the_runner_items_as_validate_does(
+ def test_a_server_fault_in_markdown(
self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path
) -> None:
- """The runner's items render as the grouped prose `validate` prints, not as a JSON dump."""
- _install_hosted_api(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNKNOWN_MODEL_AT_LOAD)
+ _install_hosted_api(mocker, monkeypatch, status=502, body=GatewayAnswers.HTML_PAGE)
+
+ with pytest.raises(typer.Exit):
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", runner=RunExecution.HOSTED)
+
+ markdown = capsys.readouterr().err
+ assert markdown.startswith("## The call may have created a run\n")
+ assert "- Code: `client.outcome_unknown` (domain runtime, retry outcome_unknown)" in markdown
+ assert "502 Bad Gateway" not in markdown
+ _assert_no_retired_markdown(markdown=markdown)
+
+ @pytest.mark.usefixtures("tty_stdin")
+ def test_an_unreachable_runner_is_the_client_s_client_unreachable(
+ self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path
+ ) -> None:
+ """A runner nothing answers for is the base client's `client.unreachable`, naming the base URL, with no class name."""
+ _install_unreachable_api(mocker, monkeypatch)
+
+ with pytest.raises(typer.Exit) as exc_info:
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)
+
+ assert exc_info.value.exit_code == 1
+ assert json.loads(capsys.readouterr().err) == UNREACHABLE_PROBLEM
+
+ @pytest.mark.usefixtures("tty_stdin")
+ def test_an_unreachable_runner_in_markdown(
+ self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path
+ ) -> None:
+ _install_unreachable_api(mocker, monkeypatch)
with pytest.raises(typer.Exit):
run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.MARKDOWN, runner=RunExecution.HOSTED)
markdown = capsys.readouterr().err
- assert "## Pipe validation errors" in markdown
- assert "Pipe: `draft_pitch`" in markdown
- assert "Field: `model`" in markdown
- assert "validation_errors" not in markdown
+ assert markdown.startswith(f"## The runtime could not be reached\n\nThe client could not connect to the runtime at {HOSTED_URL}.\n")
+ assert f"**Next step** (`retry`): {HOSTED_UNREACHABLE_NEXT_STEP}" in markdown
+ assert "- Code: `client.unreachable` (domain runtime, retry yes)" in markdown
+ assert "ConnectError" not in markdown
+ _assert_no_retired_markdown(markdown=markdown)
@pytest.mark.usefixtures("tty_stdin")
- def test_run_bundle_error_format_json_overrides_markdown_format(
+ def test_error_format_json_overrides_markdown_format(
self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path
) -> None:
- """`--error-format json` gives the JSON envelope even when the success format is markdown."""
- _install_hosted_api(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNSERVED_MODEL_AT_RUN)
+ """`--error-format json` gives the JSON problem even when the success format is markdown."""
+ _install_hosted_api(mocker, monkeypatch, status=422, body=RunnerProblems.UNKNOWN_MODEL_AT_LOAD)
with pytest.raises(typer.Exit):
run_bundle_cmd(
@@ -221,19 +328,19 @@ class TestRunHostedRefusal:
runner=RunExecution.HOSTED,
)
- assert json.loads(capsys.readouterr().err)["error_type"] == "ModelNotFoundError"
+ assert json.loads(capsys.readouterr().err) == json.loads(RunnerProblems.UNKNOWN_MODEL_AT_LOAD)
@pytest.mark.usefixtures("tty_stdin")
def test_run_pipe_sends_its_library_and_reports_the_refusal(
self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path
) -> None:
- """`run pipe` sends the library a local run would load, and answers a refusal with the same envelope."""
- seen = _install_hosted_api(mocker, monkeypatch, status=422, body=RefusedRunBodies.COMBINE_FAILURE_AT_RUN)
+ """`run pipe` sends the library a local run would load, and reports a refusal as the runner's problem."""
+ seen = _install_hosted_api(mocker, monkeypatch, status=422, body=RunnerProblems.OUTPUT_MULTIPLICITY)
mocker.patch(f"{RUN_PIPE_MODULE}.resolve_pipe_from_exports", return_value=[])
with pytest.raises(typer.Exit) as exc_info:
run_pipe_cmd(
- pipe_code="review_topics",
+ pipe_code="review_topic",
library_dir=[str(bundle_file.parent)],
output_format=CliOutputFormat.JSON,
runner=RunExecution.HOSTED,
@@ -241,16 +348,14 @@ class TestRunHostedRefusal:
assert exc_info.value.exit_code == 1
assert json.loads(seen[-1].content)["mthds_contents"] == ["# bundle\n"]
- envelope = json.loads(capsys.readouterr().err)
- assert envelope["error_type"] == "StuffFactoryError"
- assert envelope["hint"] == RefusedRunBodies.COMBINE_FAILURE_NEXT_STEP
+ assert json.loads(capsys.readouterr().err) == json.loads(RunnerProblems.OUTPUT_MULTIPLICITY)
@pytest.mark.usefixtures("tty_stdin")
def test_run_method_by_address_is_resolved_by_the_hosted_api(
self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
- """A published address goes as `method_ref`, unfetched, and the refusal reads like a local failure."""
- seen = _install_hosted_api(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNSERVED_MODEL_AT_RUN)
+ """A published address goes as `method_ref`, unfetched, and the refusal reads as the runner's problem."""
+ seen = _install_hosted_api(mocker, monkeypatch, status=422, body=RunnerProblems.UNKNOWN_MODEL_AT_LOAD)
with pytest.raises(typer.Exit) as exc_info:
run_method_cmd(name="github.com/Pipelex/methods/[email protected]", output_format=CliOutputFormat.MARKDOWN, runner=RunExecution.HOSTED)
@@ -260,15 +365,18 @@ class TestRunHostedRefusal:
assert start_body["method_ref"] == "github.com/Pipelex/methods/[email protected]"
assert "mthds_contents" not in start_body
markdown = capsys.readouterr().err
- assert markdown.startswith("# Error: ModelNotFoundError\n")
- assert f"> 💡 **Hint:** {RefusedRunBodies.UNSERVED_MODEL_NEXT_STEP}" in markdown
+ assert markdown.startswith("## The method does not validate\n")
+ assert (
+ "- `model.unknown`: The method names the llm model 'claude-4.5-haiku', which no catalog knows. (pipe 'write_slogan', field 'model')"
+ in (markdown)
+ )
@pytest.mark.usefixtures("tty_stdin")
def test_base_url_flag_wins_over_the_environment(
self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path
) -> None:
"""`--base-url` names the origin every request of the run goes to, over `PIPELEX_BASE_URL`."""
- seen = _install_hosted_api(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNSERVED_MODEL_AT_RUN)
+ seen = _install_hosted_api(mocker, monkeypatch, status=422, body=RunnerProblems.INPUT_MISSING)
with pytest.raises(typer.Exit):
run_bundle_cmd(
@@ -284,47 +392,468 @@ class TestRunHostedRefusal:
assert {(request.url.host, request.url.port) for request in seen} == {("self-hosted.test", 8081)}
@pytest.mark.usefixtures("tty_stdin")
- def test_an_unreachable_api_names_the_base_url_settings(
+ def test_a_server_without_the_run_routes_serves_no_such_route(
self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path
) -> None:
- """A hosted API that cannot be reached is a configuration matter: the hint names where the origin comes from."""
- monkeypatch.setenv(PIPELEX_BASE_URL_ENV_KEY, HOSTED_URL)
+ """A server with neither `/v1/start` nor `/v1/execute` answers a bare 404: `request.not_found`, telling to check the origin."""
+ seen = _install_hosted_api(mocker, monkeypatch, status=404, body=GatewayAnswers.NOT_FOUND)
+
+ with pytest.raises(typer.Exit):
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)
+
+ # The SDK falls back to a blocking execute when the run routes are absent, as a bare runner serves.
+ 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["next_step"] == {"kind": "upgrade", "detail": HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[404]}
+ _assert_no_retired_member(problem=problem)
+
+ @pytest.mark.usefixtures("tty_stdin")
+ @pytest.mark.parametrize(
+ ("status", "body", "headers", "expected"),
+ [
+ (
+ 401,
+ HostedPlaneRefusals.UNAUTHORIZED,
+ {},
+ {
+ "type": "https://mthds.ai/errors/auth.invalid_credential",
+ "title": "The credential was refused",
+ "status": 401,
+ "detail": "The API key is not valid.",
+ "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",
+ "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",
+ "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]},
+ },
+ ),
+ (
+ 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",
+ "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,
+ },
+ ),
+ (
+ 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",
+ "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",
+ "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",
+ "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",
+ "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",
+ ],
+ )
+ def test_a_refusal_of_the_hosted_plane_reads_as_its_core_code_with_the_hosted_guidance(
+ self,
+ mocker: MockerFixture,
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture[str],
+ 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.
+ """
+ _install_hosted_api(mocker, monkeypatch, status=status, body=body, headers=headers)
- def _refuse_connection(request: httpx.Request) -> httpx.Response:
- msg = "connection refused"
- raise httpx.ConnectError(msg, request=request)
+ with pytest.raises(typer.Exit) as exc_info:
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)
- def _start_client(self: PipelexAPIClient) -> PipelexAPIClient:
- self.client = httpx.AsyncClient(transport=httpx.MockTransport(_refuse_connection))
- return self
+ assert exc_info.value.exit_code == 1
+ problem = json.loads(capsys.readouterr().err)
+ assert problem == expected
+ _assert_no_retired_member(problem=problem)
- mocker.patch.object(PipelexAPIClient, "start_client", _start_client)
+ @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,
+ ) -> 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, "")
with pytest.raises(typer.Exit):
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.MARKDOWN, 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)
+
+ @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(
+ self,
+ mocker: MockerFixture,
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture[str],
+ bundle_file: Path,
+ error_format: CliOutputFormat,
+ ) -> 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.
+ """
+ _install_hosted_api(mocker, monkeypatch, status=422, body=RunnerOwnRefusals.RESERVED_OBJECT_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)
+
+ 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)
+
+ @pytest.mark.usefixtures("tty_stdin")
+ def test_a_refusal_in_the_former_shape_takes_the_step_kind_its_advice_names(
+ self,
+ mocker: MockerFixture,
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture[str],
+ bundle_file: Path,
+ ) -> 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 pytest.raises(typer.Exit) as exc_info:
run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)
- envelope = json.loads(capsys.readouterr().err)
- assert envelope["error_type"] == "ApiUnreachableError"
- assert envelope["error_domain"] == "config"
- assert PIPELEX_BASE_URL_ENV_KEY in envelope["hint"]
+ 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)
+
+ @pytest.mark.usefixtures("tty_stdin")
+ @pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])
+ @pytest.mark.parametrize(
+ ("version", "route"),
+ [(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(
+ self,
+ mocker: MockerFixture,
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture[str],
+ bundle_file: Path,
+ version: str,
+ 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.
+ """
+ seen = _install_hosted_api(mocker, monkeypatch, status=422, body=RunnerOwnMethodRefusals.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)
+
+ assert exc_info.value.exit_code == 1
+ assert _routes(seen=seen) == [route]
+ printed = capsys.readouterr().err
+ 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_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 "### 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
+ _assert_no_retired_markdown(markdown=printed)
@pytest.mark.usefixtures("tty_stdin")
- def test_a_server_without_the_run_routes_points_at_the_base_url(
+ def test_a_runner_s_problem_is_reported_by_its_declared_members_alone(
self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path
) -> None:
- """A server with neither `/v1/start` nor `/v1/execute` is not the hosted API: the hint names where the origin comes from."""
- seen = _install_hosted_api(mocker, monkeypatch, status=404, body='{"detail":"Not Found"}')
+ """Members neither the standard nor Pipelex declares, at any level, are left out: the retired envelope does not come back."""
+ _install_hosted_api(mocker, monkeypatch, status=422, body=UndeclaredMembers.SENT)
with pytest.raises(typer.Exit):
run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)
- # The SDK falls back to a blocking execute when the run routes are absent, as a bare runner serves.
- assert _routes(seen=seen) == [START_ROUTE, ("POST", "/v1/execute")]
- envelope = json.loads(capsys.readouterr().err)
- assert envelope["error_type"] == "ApiResponseError"
- assert envelope["http_status"] == 404
- assert envelope["hint"] == HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[404]
- assert "--base-url" in envelope["hint"]
+ problem = json.loads(capsys.readouterr().err)
+ assert problem == UndeclaredMembers.REPORTED
+ _assert_no_retired_member(problem=problem)
+
+ @pytest.mark.usefixtures("tty_stdin")
+ @pytest.mark.parametrize(
+ ("body", "request_id"),
+ [
+ (OperatorViewAnswers.UNREADABLE_REQUEST_ID, HEADER_REQUEST_ID),
+ (OperatorViewAnswers.UNREADABLE_DIAGNOSTICS, "01M55PREQUEST0000000000000"),
+ ],
+ ids=["unreadable_request_id", "unreadable_diagnostics"],
+ )
+ def test_an_answer_in_the_operator_s_view_reads_in_the_caller_s_whatever_member_does_not_read(
+ self,
+ mocker: MockerFixture,
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture[str],
+ bundle_file: Path,
+ body: str,
+ request_id: str,
+ ) -> None:
+ """An answer holding diagnostics is projected onto the caller's view, its next step re-aimed, even when one of
+ Pipelex's members does not read; only that member is left out, and the request id survives.
+ """
+ _install_hosted_api(mocker, monkeypatch, status=409, body=body, headers={"x-request-id": HEADER_REQUEST_ID})
+
+ 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) == {**OperatorViewAnswers.CALLER_VIEW, "request_id": request_id}
+
+ @pytest.mark.usefixtures("tty_stdin")
+ @pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])
+ def test_a_nested_run_s_record_reads_in_the_caller_s_view_in_an_answer_in_the_caller_s(
+ self,
+ mocker: MockerFixture,
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture[str],
+ bundle_file: Path,
+ error_format: CliOutputFormat,
+ ) -> None:
+ """A run's stored record nested in an answer is its operator's, so its operator-only next step is re-aimed at the
+ caller even when no diagnostics tell its view; the answer around it keeps the runner's own step.
+ """
+ _install_hosted_api(mocker, monkeypatch, status=409, body=OperatorViewAnswers.NESTING_THE_OPERATOR_S_RECORD)
+
+ with pytest.raises(typer.Exit):
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=error_format, runner=RunExecution.HOSTED)
+
+ printed = capsys.readouterr().err
+ sent = json.loads(OperatorViewAnswers.NESTING_THE_OPERATOR_S_RECORD)
+ match error_format:
+ case CliOutputFormat.JSON:
+ assert json.loads(printed) == {**sent, "run_error": OperatorViewAnswers.CALLER_VIEW}
+ case CliOutputFormat.MARKDOWN:
+ assert f"**Next step** (`report`): {OperatorViewAnswers.CALLER_VIEW['next_step']['detail']}" in printed
+ assert sent["run_error"]["next_step"]["detail"] not in printed
+ assert f"**Next step** (`read_run`): {sent['next_step']['detail']}" in printed
+
+ @pytest.mark.usefixtures("tty_stdin")
+ @pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])
+ @pytest.mark.parametrize(
+ ("body", "keeps_run_error"),
+ list(zip(OperatorViewAnswers.HOSTILE, (False, False, False, True), strict=True)),
+ ids=["run_error_text", "run_error_unreadable", "every_member_unreadable", "nested_members_unreadable"],
+ )
+ def test_no_member_a_runner_answers_stops_the_report(
+ self,
+ mocker: MockerFixture,
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture[str],
+ bundle_file: Path,
+ body: str,
+ keeps_run_error: bool,
+ error_format: CliOutputFormat,
+ ) -> None:
+ """Pipelex's members in any shape, the nested run's problem included, leave the command reporting the runner's problem:
+ each member that does not read is left out alone, so a nested problem whose own members do not read is kept without them.
+ """
+ _install_hosted_api(mocker, monkeypatch, status=409, body=body)
+
+ with pytest.raises(typer.Exit) as exc_info:
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=error_format, runner=RunExecution.HOSTED)
+
+ assert exc_info.value.exit_code == 1
+ printed = capsys.readouterr().err
+ match error_format:
+ case CliOutputFormat.JSON:
+ problem = json.loads(printed)
+ assert problem["code"] == "run.terminated"
+ assert "diagnostics" not in problem
+ assert "request_id" not in problem
+ if keeps_run_error:
+ assert problem["run_error"] == OperatorViewAnswers.CALLER_VIEW
+ else:
+ assert "run_error" not in problem
+ case CliOutputFormat.MARKDOWN:
+ assert printed.startswith("## The run was stopped by an operator or an erasure\n")
@pytest.mark.parametrize(
("flags", "named"),
@@ -356,125 +885,49 @@ class TestRunHostedRefusal:
assert seen == []
assert named in json.loads(capsys.readouterr().err)["message"]
- def test_payload_of_an_answer_that_is_no_problem_document(self) -> None:
- """A gateway's page gives the client's own class, the server-fault hint, the status, and no runner classification."""
- payload = api_response_error_payload(error=_refusal(status=502, body=RefusedRunBodies.GATEWAY_HTML))
-
- assert payload["error_type"] == "ApiResponseError"
- assert payload["message"] == f"API POST /v1/start failed (502): {RefusedRunBodies.GATEWAY_HTML}"
- assert payload["hint"] == HOSTED_SERVER_FAULT_NEXT_STEP
- assert payload["http_status"] == 502
- for absent in ("error_domain", "error_category", "retryable", "request_id", "validation_errors", "pipe_code", "pipe_stack"):
- assert absent not in payload
-
- def test_payload_never_borrows_a_local_hint_or_domain_for_the_runner_class(self) -> None:
- """A runner class with a local hint and retryable flag lends neither to a remote refusal that sent none."""
- body = json.dumps({"detail": "The model is not available", "error_type": "PipeOperatorModelAvailabilityError"})
-
- payload = api_response_error_payload(error=_refusal(status=500, body=body))
-
- assert payload["error_type"] == "PipeOperatorModelAvailabilityError"
- assert payload["hint"] == HOSTED_SERVER_FAULT_NEXT_STEP
- assert "retryable" not in payload
- assert "error_domain" not in payload
-
- def test_payload_carries_the_pipe_members_and_retryable(self) -> None:
- """`pipe_code`, `pipe_stack` and a true `retryable` ride the envelope when the problem carries them."""
- payload = api_response_error_payload(error=_refusal(status=422, body=RefusedRunBodies.LOCATED_WITH_UNKNOWN_ITEM))
-
- assert payload["pipe_code"] == "analyze_topics"
- assert payload["pipe_stack"] == ["review_topics", "analyze_topics"]
- assert payload["retryable"] is True
- assert payload["hint"] == HOSTED_REFUSAL_CALLER_NEXT_STEP
-
- def test_markdown_keeps_an_item_this_version_cannot_type(self, capsys: pytest.CaptureFixture[str]) -> None:
- """An item from a newer runner stays readable as JSON under Details rather than failing the rendering."""
- set_agent_cli_error_format(CliOutputFormat.MARKDOWN)
-
- with pytest.raises(typer.Exit):
- agent_error_api_response(error=_refusal(status=422, body=RefusedRunBodies.LOCATED_WITH_UNKNOWN_ITEM))
-
- markdown = capsys.readouterr().err
- assert markdown.startswith("# Error: StuffFactoryError\n")
- assert "- **validation_errors:**" in markdown
- assert '"error_type": "some_future_fault"' in markdown
- assert "- **pipe_code:** analyze_topics" in markdown
- assert '"review_topics",' in markdown
-
- def test_payload_of_the_platform_rate_limit(self) -> None:
- """A rate limit the runner did not advise on reads as retryable, with its delay, its code and a wait-and-retry hint."""
- payload = api_response_error_payload(error=_refusal(status=429, body=RefusedRunBodies.PLATFORM_RATE_LIMITED, headers={"Retry-After": "12"}))
-
- assert payload["error_type"] == "ApiResponseError"
- assert payload["hint"] == HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[429]
- assert payload["retryable"] is True
- assert payload["retry_after_seconds"] == 12
- assert payload["error_code"] == "rate_limited"
- assert payload["request_id"] == "req_rate"
- assert "error_domain" not in payload
-
- def test_payload_of_the_gateway_refusing_a_key(self) -> None:
- """The gateway's bare 403 points at the key, not at a request_id it never sent."""
- payload = api_response_error_payload(error=_refusal(status=403, body=RefusedRunBodies.GATEWAY_FORBIDDEN))
-
- assert payload["message"] == "API POST /v1/start failed (403): Forbidden"
- assert payload["hint"] == HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[403]
- assert PIPELEX_API_KEY_ENV_KEY in payload["hint"]
- for absent in ("retryable", "request_id", "error_code", "retry_after_seconds"):
- assert absent not in payload
-
- def test_payload_of_an_unavailable_service_is_never_inferred_retryable(self) -> None:
- """A 503 can follow a run that completed, so only the answer itself can make it retryable."""
- silent = api_response_error_payload(
- error=_refusal(status=503, body=RefusedRunBodies.PLATFORM_RUNNER_UNREACHABLE, headers={"Retry-After": "10"})
- )
- body_saying_yes = json.dumps({**json.loads(RefusedRunBodies.PLATFORM_RUNNER_UNREACHABLE), "retryable": True})
- saying_yes = api_response_error_payload(error=_refusal(status=503, body=body_saying_yes))
-
- assert "retryable" not in silent
- assert silent["retry_after_seconds"] == 10
- assert silent["error_code"] == "service_unavailable"
- assert silent["hint"] == HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[503]
- assert "repeat a paid run" in silent["hint"]
- assert saying_yes["retryable"] is True
-
- def test_payload_of_a_refusal_the_caller_must_act_on(self) -> None:
- """A 404 points at the method and the base URL settings, and any other 4xx without a next step asks for a change, not a report."""
- not_found = api_response_error_payload(error=_refusal(status=404, body='{"detail":"No method at that address","code":"method_not_found"}'))
- unprocessable = api_response_error_payload(error=_refusal(status=422, body='{"detail":"Local file paths cannot be used"}'))
-
- assert not_found["message"] == "API POST /v1/start failed (404): No method at that address"
- assert not_found["hint"] == HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[404]
- assert PIPELEX_BASE_URL_ENV_KEY in not_found["hint"]
- assert unprocessable["hint"] == HOSTED_REFUSAL_CALLER_NEXT_STEP
- for payload in (not_found, unprocessable):
- assert "retryable" not in payload
-
+ @pytest.mark.usefixtures("tty_stdin")
@pytest.mark.parametrize(
("status", "body", "expected"),
[
- # A gateway's page: pipelex-sdk reads a problem from the status, which the envelope never prints.
- (502, RefusedRunBodies.GATEWAY_HTML, None),
- # The platform's own code, outside the standard's pattern, and no domain sent.
- (429, RefusedRunBodies.PLATFORM_RATE_LIMITED, None),
- # A problem document naming its code and its domain.
- (
- 422,
- json.dumps({"detail": "The input 'topic' is invalid", "code": "input.invalid", "domain": "input", "error_domain": "input"}),
- ("input.invalid", UsageStatsErrorDomain.INPUT),
- ),
+ # A runner's problem document, naming its code and its domain.
+ (422, RunnerProblems.INPUT_MISSING, UsageStatsError(code="input.missing", domain=UsageStatsErrorDomain.INPUT)),
+ # A gateway's page: pipelex-sdk reads a problem from the status, which the hosted API never sent.
+ (502, GatewayAnswers.HTML_PAGE, None),
],
+ ids=["runner_problem", "gateway_page"],
)
def test_the_statistics_record_what_the_hosted_api_sent(
- self, mocker: MockerFixture, status: int, body: str, expected: tuple[str, UsageStatsErrorDomain] | None
+ self,
+ mocker: MockerFixture,
+ monkeypatch: pytest.MonkeyPatch,
+ capsys: pytest.CaptureFixture[str],
+ bundle_file: Path,
+ status: int,
+ body: str,
+ expected: UsageStatsError | None,
) -> None:
- """The command's statistics say what the envelope says: the code and domain the hosted API sent, never the SDK's inference."""
+ """The command's statistics record the code and domain the hosted API sent, never the client's reading of a status."""
+ _install_hosted_api(mocker, monkeypatch, status=status, body=body)
noted = mocker.patch("pipelex.cli.agent_cli.commands.agent_output.note_command_error")
with pytest.raises(typer.Exit):
- agent_error_api_response(error=_refusal(status=status, body=body))
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)
+ capsys.readouterr()
if expected is None:
noted.assert_not_called()
else:
- noted.assert_called_once_with(error=UsageStatsError(code=expected[0], domain=expected[1]))
+ noted.assert_called_once_with(error=expected)
+
+ @pytest.mark.usefixtures("tty_stdin")
+ def test_the_statistics_record_an_unreachable_runner_as_the_client_decided(
+ self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path
+ ) -> None:
+ _install_unreachable_api(mocker, monkeypatch)
+ noted = mocker.patch("pipelex.cli.agent_cli.commands.agent_output.note_command_error")
+
+ with pytest.raises(typer.Exit):
+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)
+
+ capsys.readouterr()
+ noted.assert_called_once_with(error=UsageStatsError(code="client.unreachable", domain=UsageStatsErrorDomain.RUNTIME))
diff --git a/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py b/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py
index 3f9480050..9c83368ca 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_validate_bundle_error_format.py
@@ -80,8 +80,10 @@ class TestValidateBundleErrorFormat:
assert captured.out == ""
return captured.err
- def test_markdown_renders_prose_and_fix_aware_footer(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], tmp_path: Path) -> None:
- """Markdown renders the problem's heading and facts, prose items with the 💡 fix line, the bundle, and a fix-aware footer."""
+ def test_markdown_renders_the_items_and_a_fix_aware_footer(
+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], tmp_path: Path
+ ) -> None:
+ """Markdown renders the problem's heading and facts, its items with their fix, the bundle, and a fix-aware footer."""
bundle_path = tmp_path / "bundle.mthds"
markdown = self._report_markdown(
mocker=mocker, capsys=capsys, items=[_fixable_item(source=bundle_path)], bundle_path=bundle_path, library_dirs=[tmp_path / "libs"]
@@ -89,8 +91,12 @@ class TestValidateBundleErrorFormat:
assert markdown.startswith("## The method does not validate")
assert "- Code: `method.invalid` (domain method, retry no)" in markdown
- assert "1. **Inadequate Output Multiplicity**" in markdown
- assert " - 💡 Suggested fix: Set output of pipe 'brainstorm' to 'StoryIdea[]' to match its last step" in markdown
+ assert "### Errors\n\n- `method.output_multiplicity_mismatch`: " in markdown
+ assert f"(pipe 'brainstorm', file '{bundle_path}')\n" in markdown
+ assert (
+ " - Suggested fix (`match-sequence-output`, safe): Set output of pipe 'brainstorm' to 'StoryIdea[]' to match its last step"
+ ) in markdown
+ assert "## Pipe validation errors" not in markdown
assert f"- **bundle_path:** {bundle_path}" in markdown
assert "is_valid" not in markdown
assert f"💡 1 of these errors can be fixed automatically — run: `pipelex-agent fix bundle {bundle_path} -L {tmp_path / 'libs'}`" in markdown
@@ -108,11 +114,14 @@ class TestValidateBundleErrorFormat:
library_dirs=None,
)
- assert " - 💡 Suggested fix: Set output of pipe 'brainstorm' to 'StoryIdea[]' to match its last step" in markdown
assert (
- " - 💡 Suggested fix (unsafe, confirm before applying): Replace model '@best-sonet' of pipe 'write_tide_note' with '@best-gpt'"
+ " - Suggested fix (`match-sequence-output`, safe): Set output of pipe 'brainstorm' to 'StoryIdea[]' to match its last step"
+ ) in markdown
+ assert (
+ " - Suggested fix (`rename-model`, unsafe, confirm before applying): "
+ "Replace model '@best-sonet' of pipe 'write_tide_note' with '@best-gpt'"
) in markdown
- assert "💡 Suggested fix: Replace model" not in markdown
+ assert "(`rename-model`, safe)" not in markdown
assert "💡 1 of these errors can be fixed automatically" in markdown
def test_markdown_no_fix_footer_when_nothing_fixable(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], tmp_path: Path) -> None:
diff --git a/tests/unit/pipelex/cli/test_agent_output.py b/tests/unit/pipelex/cli/test_agent_output.py
index f763b6b94..1001a209c 100644
--- a/tests/unit/pipelex/cli/test_agent_output.py
+++ b/tests/unit/pipelex/cli/test_agent_output.py
@@ -14,7 +14,6 @@ from pipelex.base_exceptions import PipelexConfigError, PipelexError
from pipelex.cli.agent_cli._agent_cli import app
from pipelex.cli.agent_cli.commands.agent_output import (
CliOutputFormat,
- _build_error_source, # pyright: ignore[reportPrivateUsage]
agent_argument_error,
agent_error,
agent_file_error,
@@ -297,6 +296,52 @@ class TestAgentOutput:
assert "- **bundle_path:** /w/b.mthds" in rendered
assert "is_valid" not in rendered
+ def test_render_problem_markdown_nests_the_run_s_own_problem(self) -> None:
+ """A read of a failed run's results renders the run's own problem under it as the problem itself renders, one heading
+ level down: its title, sentence, step, code, location and items.
+ """
+ item = make_problem_item(code=CoreCode.METHOD_CONCEPT_UNRESOLVED, params={"concept": "Missing"}, location=make_location(pipe="summarize"))
+ run_error = make_problem(code=CoreCode.METHOD_INVALID, view=ProblemView.CALLER, location=make_location(pipe="summarize"), errors=[item])
+ read = make_problem(
+ code=CoreCode.RUN_FAILED, view=ProblemView.CALLER, params={"pipeline_run_id": "run-9", "run_status": "FAILED"}, pipeline_run_id="run-9"
+ ).with_members(run_error=run_error.to_wire())
+
+ rendered = render_problem_markdown(problem=read)
+
+ assert "- Code: `run.failed` (domain runtime, retry no)" in rendered
+ assert (
+ f"### The run's own problem\n\n#### {run_error.title}\n\n{run_error.detail}\n\n"
+ f"**Next step** (`{run_error.next_step.kind}`): {run_error.next_step.detail}\n\n"
+ "- Code: `method.invalid` (domain method, retry no)\n- Location: pipe 'summarize'\n\n"
+ f"##### Errors\n\n- `method.concept_unresolved`: {item.detail} (pipe 'summarize')"
+ ) in rendered
+
+ @pytest.mark.parametrize(
+ ("safety", "label"),
+ [("safe", "safe"), ("unsafe", "unsafe, confirm before applying"), ("reviewed", "unsafe, confirm before applying")],
+ ids=["safe", "unsafe", "unknown"],
+ )
+ def test_render_problem_markdown_labels_a_fix_by_its_safety(self, safety: str, label: str) -> None:
+ """A safety this reader does not know reads as unsafe (`SuggestedFix.effective_safety`), so it says it needs confirming."""
+ problem = make_problem(code=CoreCode.METHOD_INVALID, view=ProblemView.CALLER).with_members(
+ errors=[
+ {
+ "code": "model.unknown",
+ "detail": "The method names the llm model 'gpt-5.1', which no catalog knows.",
+ "suggested_fix": {
+ "fix_code": "rename-model",
+ "description": "Replace model 'gpt-5.1' with 'gpt-5.5'",
+ "safety": safety,
+ "ops": [{"kind": "set_key", "table_path": ["pipe", "draft"], "key": "model", "value": "gpt-5.5"}],
+ },
+ }
+ ]
+ )
+
+ rendered = render_problem_markdown(problem=problem)
+
+ assert f" - Suggested fix (`rename-model`, {label}): Replace model 'gpt-5.1' with 'gpt-5.5'" in rendered
+
def test_render_problem_markdown_names_the_model_and_the_provider(self) -> None:
cause = InferenceBackendCredentialsError(
credentials_error_type=InferenceBackendCredentialsErrorType.VAR_NOT_FOUND,
@@ -429,40 +474,3 @@ class TestAgentOutput:
parsed = json.loads(capsys.readouterr().out)
assert parsed["working_memory"]["report_data"]["report_date"] == "2026-03-01"
assert parsed["working_memory"]["report_data"]["items"][0]["timestamp"] == "2026-03-01T09:00:00"
-
- # -------------------------------------------------------------------------
- # _build_error_source, which a hosted run's envelope still carries
- # -------------------------------------------------------------------------
-
- def test_build_error_source_with_none_traceback(self) -> None:
- exc = RuntimeError("constructed, not raised")
- assert exc.__traceback__ is None
-
- sources = _build_error_source(exc)
- assert len(sources) == 1
- assert "RuntimeError" in sources[0]
- assert "no traceback" in sources[0]
-
- def test_build_error_source_with_chained_none_tracebacks(self) -> None:
- cause = ValueError("root cause")
- outer = RuntimeError("wrapper")
- outer.__cause__ = cause
-
- sources = _build_error_source(outer)
- assert len(sources) == 2
- assert "RuntimeError" in sources[0]
- assert "no traceback" in sources[0]
- assert "ValueError" in sources[1]
- assert "no traceback" in sources[1]
-
- def test_build_error_source_with_real_traceback(self) -> None:
- try:
- msg = "actually raised"
- raise RuntimeError(msg)
- except RuntimeError as exc:
- sources = _build_error_source(exc)
-
- assert len(sources) == 1
- assert "RuntimeError" in sources[0]
- assert "no traceback" not in sources[0]
- assert "test_agent_output.py" in sources[0]
diff --git a/tests/unit/pipelex/cli/test_agent_output_drift.py b/tests/unit/pipelex/cli/test_agent_output_drift.py
index 01631a18e..2b590aa7d 100644
--- a/tests/unit/pipelex/cli/test_agent_output_drift.py
+++ b/tests/unit/pipelex/cli/test_agent_output_drift.py
@@ -1,7 +1,25 @@
import ast
from pathlib import Path
+from typing import Any, cast
+
+from mthds.protocol.exceptions import PipelineRequestError
+from pipelex_sdk.error_models import RunErrorReport
+from pipelex_sdk.errors import ApiResponseError, RunFailedError
+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,
+)
# 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"})
@@ -12,11 +30,98 @@ _RETIRED_ENVELOPE_MEMBERS: frozenset[str] = frozenset(
{"error", "error_type", "error_domain", "error_code", "error_category", "retryable", "hint", "validation_errors", "error_source"}
)
+# The members only the retired envelope wrote, beside those above: the hosted run's own, read off the hosted plane's answer.
+_RETIRED_HOSTED_MEMBERS: frozenset[str] = frozenset({"http_status", "retry_after_seconds", "run_status"})
+
# The parameters of ``client.argument_invalid``, which ``agent_argument_error`` takes.
_ARGUMENT_REFUSAL_PARAMS: frozenset[str] = frozenset({"argument", "reason"})
+def _written_member(*, node: ast.AST) -> str | None:
+ """The string a dictionary display or a subscript assignment writes as a key, ``None`` for any other node."""
+ match node:
+ case ast.Dict(keys=keys):
+ for key in keys:
+ if isinstance(key, ast.Constant) and isinstance(key.value, str) and key.value in _RETIRED_ENVELOPE_MEMBERS | _RETIRED_HOSTED_MEMBERS:
+ return key.value
+ return None
+ case ast.Assign(targets=targets):
+ for target in targets:
+ if isinstance(target, ast.Subscript) and isinstance(target.slice, ast.Constant):
+ written = target.slice.value
+ if isinstance(written, str) and written in _RETIRED_ENVELOPE_MEMBERS | _RETIRED_HOSTED_MEMBERS:
+ return written
+ return None
+ case _:
+ return None
+
+
+# The parts of a reported problem, each read against the model that declares its members: the parts the reader of a
+# runner's answer walks, and the nested run's problem, which it reads as a problem of its own. A problem's `params` and
+# a fix's `ops` are the code's and the operation's own, so they are not walked.
+_PROBLEM_PARTS: dict[type[BaseModel], dict[str, type[BaseModel]]] = {
+ **READ_PROBLEM_PARTS,
+ PipelexProblem: {**READ_PROBLEM_PARTS[PipelexProblem], "run_error": PipelexProblem},
+}
+
+# The command's own sentence, which rides beside the problem's members.
+_COMMAND_MEMBERS: frozenset[str] = frozenset({"message"})
+
+
+def _undeclared_members(*, document: dict[str, Any], shape: type[BaseModel], path: str) -> list[str]:
+ """The members of ``document`` and of the parts it nests that their model does not declare, by their path."""
+ allowed: set[str] = set(shape.model_fields)
+ if path == "problem":
+ allowed |= _COMMAND_MEMBERS
+ offenders = [f"{path}.{name}" for name in document if name not in allowed]
+ for name, part_shape in _PROBLEM_PARTS.get(shape, {}).items():
+ part = document.get(name)
+ if isinstance(part, dict):
+ offenders += _undeclared_members(document=cast("dict[str, Any]", part), shape=part_shape, path=f"{path}.{name}")
+ elif isinstance(part, list):
+ for index_item, item in enumerate(cast("list[Any]", part)):
+ if isinstance(item, dict):
+ offenders += _undeclared_members(document=cast("dict[str, Any]", item), shape=part_shape, path=f"{path}.{name}[{index_item}]")
+ return offenders
+
+
+def _refusal(*, status: int, body: str) -> ApiResponseError:
+ """A refusal of the run request as the client raises it, the answer read the way the client reads it."""
+ return ApiResponseError(
+ f"API POST /v1/start failed ({status})",
+ api_url="https://hosted.test",
+ status=status,
+ status_text="Refused",
+ response_body=body,
+ headers={},
+ may_start_run=True,
+ )
+
+
+def _reported_failures() -> list[PipelineRequestError]:
+ """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=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),
+ ),
+ ]
+
+
def _reporter_name(*, call: ast.Call) -> str | None:
match call.func:
case ast.Name(id=name):
@@ -53,3 +158,34 @@ class TestAgentOutputDrift:
"These calls pass a member of the envelope the problem replaced; name a code (code=, params=) or let the "
f"cause's own problem speak: {offenders}"
)
+
+ def test_no_agent_cli_module_writes_a_member_of_the_retired_envelope(self) -> None:
+ """No agent CLI module builds a payload with a member of the envelope the problem replaced, a hosted run's included.
+
+ A run on a runner used to leave in that envelope, built by hand as a dictionary; its failure is now the problem the
+ runner or the client produced, so no key of that envelope is written anywhere in the agent CLI.
+ """
+ package_dir = Path(pipelex.cli.agent_cli.__file__).parent
+ offenders: list[str] = []
+ for source_file in sorted(package_dir.rglob("*.py")):
+ tree = ast.parse(source_file.read_text(encoding="utf-8"))
+ for node in ast.walk(tree):
+ member = _written_member(node=node)
+ if member is not None:
+ 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}"
+
+ 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.
+
+ A runner's answer may carry members beside its problem, those the envelope this CLI wrote before it reported
+ problems used to read (`error_type`, `error_domain`, `retryable`) among them, and a reader that copied them
+ through would bring that envelope back. This guards the emitted document itself, whatever builds it.
+ """
+ offenders: list[str] = []
+ for failure in _reported_failures():
+ document = problem_payload(problem=hosted_failure_problem(error=failure, credential_sent=True), message=None, extras={})
+ offenders += [
+ f"{type(failure).__name__}: {member}" for member in _undeclared_members(document=document, shape=PipelexProblem, path="problem")
+ ]
+ assert not offenders, f"These reported members are declared by no reader of the problem: {offenders}"
diff --git a/tests/unit/pipelex/hosted/test_data.py b/tests/unit/pipelex/hosted/test_data.py
index 14140ae48..fdb5e3b0f 100644
--- a/tests/unit/pipelex/hosted/test_data.py
+++ b/tests/unit/pipelex/hosted/test_data.py
@@ -65,6 +65,8 @@ class HostedVersions:
'{"protocol_version":"0.1.0","implementation":"pipelex-hosted","implementation_version":"0.30.0","runtime_version":null,'
'"extensions":["runs","method_id","method_ref"]}'
)
+ #: A bare runner's, which keeps no runs, so a run on it takes the blocking `POST /v1/execute`.
+ BARE_RUNNER: ClassVar[str] = '{"protocol_version":"0.1.0","implementation":"pipelex-api","implementation_version":"0.76.0"}'
class HostedPipeIoVerdicts:
@@ -72,13 +74,47 @@ class HostedPipeIoVerdicts:
# 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.
+ # `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.
UNSHIPPED_ADDRESS_DEPENDENCY: ClassVar[str] = (
'{"is_valid": false, "validation_errors": [{"category": "pipe_validation", "error_type": "unresolved_package_dependency", '
- '"source": "bundle.mthds", "message": "In-memory resolve cannot load address-based 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 '
+ "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."}'
+ )
+ # 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 '
+ "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.
+ 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."}'
+ )
class HostedPipeIoRefusals:
diff --git a/tests/unit/pipelex/hosted/test_hosted_run.py b/tests/unit/pipelex/hosted/test_hosted_run.py
index 70aecc52d..572770675 100644
--- a/tests/unit/pipelex/hosted/test_hosted_run.py
+++ b/tests/unit/pipelex/hosted/test_hosted_run.py
@@ -270,16 +270,26 @@ class TestHostedRun:
client.start.assert_not_awaited()
@pytest.mark.asyncio
+ @pytest.mark.parametrize(
+ "verdict_json",
+ [
+ HostedPipeIoVerdicts.UNSHIPPED_ADDRESS_DEPENDENCY,
+ HostedPipeIoVerdicts.UNSHIPPED_ADDRESS_DEPENDENCY_PROBLEM_ITEMS,
+ HostedPipeIoVerdicts.UNSHIPPED_ADDRESS_DEPENDENCY_UNREADABLE_PROBLEM_ITEMS,
+ ],
+ ids=["validation_errors", "problem_items", "unreadable_problem_items"],
+ )
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
+ self, mocker: MockerFixture, tmp_path: Path, verdict_json: str
) -> None:
"""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 and the URL
- to use, never the verdict's advice to fix the method.
+ 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.
"""
(tmp_path / "invoice.pdf").write_bytes(b"%PDF")
- client = _mocked_client(mocker, pipe_io_report=_invalid_report(verdict_json=HostedPipeIoVerdicts.UNSHIPPED_ADDRESS_DEPENDENCY))
+ client = _mocked_client(mocker, pipe_io_report=_invalid_report(verdict_json=verdict_json))
request = HostedRunRequest(mthds_files=[BUNDLE_FILE], inputs={"document": "invoice.pdf"}, inputs_base_dir=tmp_path)
with pytest.raises(HostedLocalFileUploadUnavailableError) as exc_info:
@@ -294,6 +304,28 @@ class TestHostedRun:
client.upload_file.assert_not_awaited()
client.start.assert_not_awaited()
+ @pytest.mark.asyncio
+ @pytest.mark.parametrize(
+ "verdict_json",
+ [HostedPipeIoVerdicts.ADDRESS_DEPENDENCY_WORDS_ONLY, HostedPipeIoVerdicts.DEPENDENCY_CYCLE_PROBLEM_ITEMS],
+ ids=["words_only", "dependency_cycle"],
+ )
+ async def test_a_verdict_naming_no_unshipped_dependency_is_the_method_s_fault(
+ self, mocker: MockerFixture, tmp_path: Path, verdict_json: str
+ ) -> None:
+ """The refusal is read from an item's code and parameters, never its words: an item only quoting them is the
+ method's, and so is a `method.dependency_missing` item whose reason is not `not_found`, such as a cycle.
+ """
+ (tmp_path / "invoice.pdf").write_bytes(b"%PDF")
+ client = _mocked_client(mocker, pipe_io_report=_invalid_report(verdict_json=verdict_json))
+ request = HostedRunRequest(mthds_files=[BUNDLE_FILE], inputs={"document": "invoice.pdf"}, inputs_base_dir=tmp_path)
+
+ with pytest.raises(HostedMethodInvalidError):
+ await run_hosted(client=client, request=request)
+
+ client.upload_file.assert_not_awaited()
+ client.start.assert_not_awaited()
+
@pytest.mark.asyncio
async def test_another_unsupported_request_form_from_pipe_io_is_the_hosted_api_s_refusal(self, mocker: MockerFixture, tmp_path: Path) -> None:
"""The same code for another reason is no address-based dependency, so the hosted API's refusal propagates as it is."""
diff --git a/tests/unit/pipelex/libraries/test_method_trees.py b/tests/unit/pipelex/libraries/test_method_trees.py
index bd1722c84..c3d2991d1 100644
--- a/tests/unit/pipelex/libraries/test_method_trees.py
+++ b/tests/unit/pipelex/libraries/test_method_trees.py
@@ -13,6 +13,7 @@ from pipelex.libraries.method_trees import (
bundle_files_under,
list_library_bundle_files,
list_library_dir_trees,
+ list_local_method_tree,
list_package_method_tree,
reporting_host_library_tree_faults,
submitted_tree_files,
@@ -188,6 +189,32 @@ class TestMethodTrees:
assert str(tmp_path.resolve()) not in message
assert LIMITS_ADVICE not in message
+ def test_a_refused_tree_names_the_rule_and_the_path_a_caller_reads(self, tmp_path: Path) -> None:
+ """`method.package_invalid` declares the rule broken and the tree path at fault, which reach a caller without the message."""
+ _touch(directory=tmp_path, tree_path="method/main.mthds")
+ (tmp_path / "method" / "link.mthds").symlink_to(tmp_path / "method" / "main.mthds")
+
+ with pytest.raises(MethodTreeLoadError) as exc_info:
+ list_local_method_tree(handed_over=tmp_path / "method")
+
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert caller.code == "method.package_invalid"
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"reason": "symbolic_link", "path": "link.mthds"}
+
+ def test_a_refused_dependency_package_names_its_path_under_its_address(self, tmp_path: Path) -> None:
+ package_root = tmp_path / "installed" / "invoicing"
+ _touch(directory=package_root, tree_path="METHODS.toml", content=_MANIFEST)
+ _touch(directory=package_root, tree_path="invoice.mthds")
+ (package_root / "link.mthds").symlink_to(package_root / "invoice.mthds")
+
+ with pytest.raises(MethodTreeLoadError) as exc_info:
+ list_package_method_tree(root=package_root, package_address="github.com/pipelex-tests/invoicing")
+
+ caller = exc_info.value.to_problem(view=ProblemView.CALLER)
+ assert caller.params is not None
+ assert caller.params.as_wire() == {"reason": "symbolic_link", "path": "github.com/pipelex-tests/invoicing/link.mthds"}
+
def test_a_host_library_tree_that_cannot_be_listed_is_the_host_s_fault(self, tmp_path: Path) -> None:
"""Beside a caller's bundles, a tree of the host's own directories is no input of theirs, and its message never reaches them."""
_touch(directory=tmp_path, tree_path="lib/a.mthds")