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-api-run-prints · L-260927-8d8ad2 (#1280)
Louis Choquelbc15b3ad11de
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex 83bb9f7b7..f2cfcc0f5 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,8 +1,8 @@contract = "cli-docs"-digest = "sha256:904da72bdd9e3c4c1be10d5a10d7dbdeb3027b8b7a8fba9d40f6bdc1649f4d23"+digest = "sha256:765de3b76ea67aa0b78b067280e6ed1beadf1219fe064414061b6734ca8c7564"reviewed_by = "Louis Choquel"-reviewed_at = "2026-09-26T23:58:30Z"-rationale = "The sprint's pipelex stacks each acked cli-docs for their own changes (the unsafe-fix label and validate hint, dry-run items and parse items, the run-path verdict and factory refusals, root-fault run errors, and the model panel of pipelex run giving a caller-fault model error's change_model next step before its local-deck remedy); their docs/tools/cli and agent_cli/CLAUDE.md edits were merged side by side in the integration's conflict resolutions. docs/tools/cli/ does not describe the model panel's tip, which docs/errors/model-not-found-error.md documents, and the merge introduced no new CLI surface. No further doc change needed."+reviewed_at = "2026-09-27T14:03:58Z"+rationale = "Round 2 review fixes: the API refusal paragraph and the agent CLI guide now say error_type is the local cause_type on a failed run, a 404 points at MTHDS_BASE_URL, another 4xx asks for a change, and only a 429 is inferred retryable"[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"@@ -12,7 +12,7 @@ rationale = "The sprint's pipelex stacks each acked cli-docs for their own chang"pipelex/cli/agent_cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/accept_gateway_terms_cmd.py" = "blob:cb8338c09a7b5dee6088551c156d69dab613213a""pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:49b8bab889d8673e7d4f1d683efe0928e43914b9"-"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:fd1f2d70111fa8f09cc2536e5ac8be70f87f243f"+"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:30ecf4a3b1cb778864ed821a7b9918f62407a7f4""pipelex/cli/agent_cli/commands/bundle_path_resolver.py" = "blob:30339c5d91048f4e67312d5691ed9a65d57472e0""pipelex/cli/agent_cli/commands/check_model_cmd.py" = "blob:91589e517509248a4639a37e82f46a69538f8071""pipelex/cli/agent_cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"@@ -40,11 +40,11 @@ rationale = "The sprint's pipelex stacks each acked cli-docs for their own chang"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:32f973c5c754b23016f3e708ab3235856e8bc5f4"-"pipelex/cli/agent_cli/commands/run/_run_core_api.py" = "blob:78a27e0ba91e6bbf99c11caedb29ad4cf20ac78b"+"pipelex/cli/agent_cli/commands/run/_run_core_api.py" = "blob:ac949cc4c93ca8e0f18b93a68f59584a7cf1a75e""pipelex/cli/agent_cli/commands/run/app.py" = "blob:64b2ecc02007cda11b526d8d3fc139593875dd9d"-"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:75ba7ca72660b3a2712c749d16880e64f27f21ce"-"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:88b358831184dd9c0ba6f9cb2b62e29aa1b10f83"-"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:65d8aa4bcf87abbb36207afaa047164cc53a4e4e"+"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:950fbfb28a1ecd73283f52853da944358662d088"+"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:75a67ad84ea53e793d2aec415b045e84abd7464c"+"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:0985c360de8fddc3f282b41a530792e3cf1fd254""pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:c7c7d7495508f1c4e5a46eba336a4ab1694ebcf7""pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:96d0f9f178739dd5a2e659cb392760b8a2bbcb32"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7f9aa7ae3..cec91c7b4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,15 @@# Changelog+## [Unreleased]++### Changed++- **`pipelex-agent --runner api run` reports the runner's refusal, not its status line**: when the API runner answers `run pipe`, `run bundle` or `run method` with a non-2xx status, the error envelope, in markdown and in JSON, now carries what its problem document says: the runner's error class as `error_type` (`ValidateBundleError`, `ModelNotFoundError`, `StuffFactoryError`), a `message` quoting its reason, which names the failing pipe and its path on a failed run, its next step as `hint`, its `error_domain`, `error_category` and `retryable`, its `validation_errors` rendered as `validate` renders them, `pipe_code` and `pipe_stack` when it carries them, its `code` as `error_code`, the `Retry-After` delay as `retry_after_seconds`, and `http_status` and `request_id`, where the envelope used to read only `HTTPStatusError` and `Client error '422 Unprocessable Entity'`. An answer that advises no next step gets one from its status: a 401 or 403 points at the API key, a 404 at `MTHDS_BASE_URL`, a 429 says to wait and retry and is `retryable`, a 503 warns that a retry can repeat a paid run, any other 4xx says to change the request, and any other status says to report the `request_id`. It requires mthds 0.17.0, whose client raises the typed `ApiResponseError`.++### Fixed++- **The API runner's credentials hint names the variables it reads**: a `ClientAuthenticationError` now says to set `MTHDS_API_KEY` and `MTHDS_BASE_URL` or to run `mthds config set`, where it pointed at `pipelex-agent doctor` and `PIPELEX_API_KEY`, which the API runner does not read.+## [v0.67.0] - 2026-09-27### Addeddiff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.mdindex 50d9ec810..b7276b29e 100644--- a/docs/tools/cli/agent-cli.md+++ b/docs/tools/cli/agent-cli.md@@ -198,6 +198,8 @@ For the structured commands, exactly one such object is written to stderr per fa**A failed run** (`run pipe`, `run bundle`, `run method`) reports `"error_type": "PipelineExecutionError"` and adds four fields: `pipe_code` and `pipe_stack` name the pipe that failed and its path from the entry pipe, and `cause_type` and `cause_message` give the class and own message of the root fault, the innermost Pipelex error behind the failure. The `message` is that root fault's message prefixed with the failing pipe and its path (`Pipe 'summarize' failed (two_steps → summarize): …`), and the classification fields are the root fault's, so branch on `cause_type` to tell, say, a model that is not available from a failure to combine a parallel's results.+**A run the API runner refuses** (`--runner api`, when the runner answers `/v1/execute` with a non-2xx status) reports what the runner's problem document says, in the same envelope and the same markdown. `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 API 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/execute 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 whole, 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 stable code a hosted plane gives the refusals it authors itself (`rate_limited`, `unauthorized`); `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 the API key; a 404 points at `MTHDS_BASE_URL`, which must be the runner's origin 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. The API runner takes its key and its origin from `MTHDS_API_KEY` and `MTHDS_BASE_URL` (or `mthds config set api-key` and `base-url`), and a missing one is a `ClientAuthenticationError`.+**`migration`** — a configuration error (`"error_domain": "config"`) carries an extra `migration` object 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.`TelemetryConfigValidationError` carries it too, on the same terms: absent means the `telemetry.toml` is wrong and the fields the message names are what to correct, present with `would_write: true` means it is old, and present with `would_write: false` means it is both reported on and unrepairable by the command.diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.mdindex a73800e60..aa7b2851e 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 via `FixBundleError` on stderr with the same structured result fields plus any `bail_reason`.- `migrate`: `# Configuration migration`, the mode (applied / dry run) and verdict, the directories walked, a files-walked/changed/written count, then one `## <path>` section 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 and ledger-supplied values only — no value read from the user's file is ever rendered, in either format.- `init`: `# Pipelex initialized` with target directory, enabled backends, and routing profile.-- error path: `# Error: <error_type>`, the message, the hint as a `> 💡` callout, the `validation_errors` items (when the cause's report carries any) as the same grouped prose `validate` prints, and a `## Details` section. `error_source` (internal stack frames) is omitted from markdown — it remains in the JSON envelope (`--error-format json`) for programmatic consumers.+- error path: `# Error: <error_type>`, the message, the hint as a `> 💡` callout, the `validation_errors` items (when the cause's report, or an API runner's refusal, carries any) as the same grouped prose `validate` prints, and a `## Details` section. `error_source` (internal stack frames) is omitted from markdown — it remains in the JSON envelope (`--error-format json`) for programmatic consumers.## Companion: Agent Skills@@ -109,5 +109,6 @@ commands/- **File convention**: Generated outputs go to `mthds-wip/` with incremental naming (`pipeline_01/`, `pipeline_02/`). Exception: `run method` on a fetched target (a method address or GitHub URL) anchors its run outputs in `results/` under the caller's CWD via `run_pipeline_core`'s `output_dir_override` — the fetched clone is an ephemeral temp dir deleted at process exit, so bundle-adjacent outputs would be lost.- **Validate refusals are verdicts**: the `validate` commands run their library load inside `translate_to_validate_bundle_error` (`pipelex/pipeline/validate_bundle_translation.py`), so every input-domained refusal raised while loading a bundle, the unknown model (`PipeOperatorModelChoiceError`, an `unknown_model` item) included, reaches the command as a `ValidateBundleError` and leaves with the invalid-verdict envelope and exit 1. 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 `_assemble_error_payload` copies the report's `validation_errors` into the envelope for any cause that carries them. `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. 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.+- **API runner refusals**: the `--runner api` branches of `run pipe` / `run bundle` / `run method` catch mthds-python's `ApiResponseError` (every `MthdsAPIClient` route raises it on a non-2xx answer; it subclasses `PipelineRequestError`, so its arm comes first) and hand it 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/execute 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`), `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. 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 hint from `API_REFUSAL_HINTS_BY_STATUS` (the 404's points at a `MTHDS_BASE_URL` ending in `/v1`), else `API_REFUSAL_CALLER_HINT` for any other 4xx and the static `ApiResponseError` hint 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. 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.- **Method-reference failures**: the `run`/`validate`/`inputs` method commands call `resolve_method_target(..., raise_ref_errors=True)` and shape the typed `MethodRefError` subclasses into `agent_error(...)` themselves (validate uses `exit_code=2`, its no-verdict convention) — the human CLI's red-text rendering stays in `resolve_method_target`'s default arm.- **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.pyindex fd1f2d701..30ecf4a3b 100644--- a/pipelex/cli/agent_cli/commands/agent_output.py+++ b/pipelex/cli/agent_cli/commands/agent_output.py@@ -27,6 +27,8 @@ from pathlib import Pathfrom typing import Any, NoReturn, castimport typer+from mthds.runners.api.exceptions import ApiResponseError+from pydantic import ValidationErrorfrom pipelex.base_exceptions import PipelexError, ValidationErrorItem, iter_cause_chainfrom pipelex.pipe_run.located_failure import find_root_fault@@ -111,6 +113,42 @@ _UNKNOWN_MODEL_HINT = ("to validate or 'pipelex-agent models -t <type>' to list available models.")+_API_CREDENTIALS_HINT = (+ "Set MTHDS_API_KEY and MTHDS_BASE_URL (the runner's origin), or run 'mthds config set api-key <key>' and 'mthds config set base-url <url>'"+)+_API_RATE_LIMITED_HINT = "Too many requests: wait retry_after_seconds when the error carries it, otherwise a few seconds, then run again"+# A 503 does not say whether the run happened: a hosted plane can answer it before forwarding the+# request and also after the run completed, when it failed to record the result. So it is never+# marked retryable, and its hint warns that running again can repeat a paid run.+_API_UNAVAILABLE_HINT = (+ "The runner or the service in front of 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"+)+# The next step of a 4xx refusal that advised none and whose status has no hint of its own.+API_REFUSAL_CALLER_HINT = (+ "The runner refused the request: change what the message names (the method, the inputs or the configuration), then run again"+)++# The next step of a refusal whose answer advised none, by its HTTP status. These are the answers a+# hosted plane authors itself, in front of the runner, and they carry no `user_action`: the gateway's+# refusal of a key, an unknown route, the platform's rate limiter, a service it cannot reach.+API_REFUSAL_HINTS_BY_STATUS: dict[int, str] = {+ 401: f"The runner refused the credentials. {_API_CREDENTIALS_HINT}",+ 403: (+ "The runner refused the request: check that MTHDS_API_KEY is a valid key for the runner at MTHDS_BASE_URL; "+ "when it is, the message says what this request may not do"+ ),+ 404: "The runner has no such route: check that MTHDS_BASE_URL is the runner's origin, with no path such as /v1",+ 429: _API_RATE_LIMITED_HINT,+ 503: _API_UNAVAILABLE_HINT,+}++# 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, see _API_UNAVAILABLE_HINT.+_API_RETRYABLE_STATUSES: frozenset[int] = frozenset({429})+AGENT_ERROR_HINTS: dict[str, str] = {# Model/routing errors"ModelChoiceNotFoundError": _UNKNOWN_MODEL_HINT,@@ -164,8 +202,15 @@ AGENT_ERROR_HINTS: dict[str, str] = {"otherwise update the deck or check the model name."),# API runner errors- "ClientAuthenticationError": "Run 'pipelex-agent doctor' to check credentials, or set the PIPELEX_API_KEY environment variable",+ "ClientAuthenticationError": _API_CREDENTIALS_HINT,"PipelineRequestError": "Check that pipe_code or mthds_contents is provided",+ # The next step of a runner's server-side failure that advised none, when its status has none of its+ # own in API_REFUSAL_HINTS_BY_STATUS (a 4xx gets API_REFUSAL_CALLER_HINT instead). It stands in for+ # the hint keyed on the runner's own class, which names a local command (doctor, check-model) that+ # cannot fix what a remote runner refused.+ "ApiResponseError": (+ "The API runner failed on its side: report it with the request_id, or with the http_status when the error carries no request_id"+ ),# Graph errors"GraphSpecParseError": "Validate graphspec.json structure; ensure it matches the expected GraphSpec schema",# Input/type errors@@ -338,11 +383,27 @@ def _assemble_error_payload(message: str, *, error_type: str, cause: BaseExcepti_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 an assembled error payload as agent-readable markdown.``validation_errors`` render as the same grouped prose ``validate`` prints, rather than as a JSONdump 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"])]@@ -350,12 +411,15 @@ def _render_error_markdown(payload: dict[str, Any]) -> str:if hint:lines += ["", f"> 💡 **Hint:** {hint}"]+ reserved_keys = _MARKDOWN_RESERVED_KEYSvalidation_errors = payload.get("validation_errors")- if isinstance(validation_errors, list) and validation_errors:- items = [ValidationErrorItem.model_validate(item) for item in cast("list[dict[str, Any]]", 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 _MARKDOWN_RESERVED_KEYS]+ detail_keys = [key for key in payload if key not in reserved_keys]if detail_keys:lines += ["", "## Details", ""]for key in detail_keys:@@ -499,6 +563,111 @@ def run_failure_fields(*, error: PipelineExecutionError) -> dict[str, Any]:return fields+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 API runner answered non-2xx, read off the problem document it sent.++ It has the shape of a local failure's envelope, so an agent reads a hosted refusal the way it reads a local one:++ - ``error_type`` is the runner's error class when the problem names one: ``ValidateBundleError`` for a bundle+ refused at load, as a local run reports it, and the root fault (``ModelNotFoundError``, ``StuffFactoryError``)+ for a run that failed, which a local run reports as ``cause_type`` under ``PipelineExecutionError``. There is+ no ``cause_type`` or ``cause_message`` on this path. ``ApiResponseError`` when the answer names no class, as a+ gateway's error page does not.+ - ``message`` is ``API POST /v1/execute 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 a+ hosted plane authors in front of the runner (a refused key, a rate limit, a runner it cannot reach), gets the+ hint of its status from ``API_REFUSAL_HINTS_BY_STATUS``, else a hint by status class (a 4xx asks for a change to+ the request, anything else for a report); never the hint keyed on the runner's class, which names a local+ command that cannot fix a remote refusal.+ - ``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 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 or {}+ message = str(error)+ hint: str+ if error.user_action is None:+ hint = API_REFUSAL_HINTS_BY_STATUS.get(error.status) or (+ API_REFUSAL_CALLER_HINT if 400 <= error.status < 500 else AGENT_ERROR_HINTS["ApiResponseError"]+ )+ else:+ hint = error.user_action.detail+ message = message.removesuffix(f"\nNext step: {hint}")++ payload: dict[str, Any] = {+ "error": True,+ "error_type": error.error_type or type(error).__name__,+ "message": message,+ "hint": hint,+ }+ if error.retryable or (error.retryable is None and error.status in _API_RETRYABLE_STATUSES):+ payload["retryable"] = True+ if error.error_domain:+ payload["error_domain"] = error.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 API runner refused to stderr, format-aware, and exit 1.++ The sibling of :func:`agent_error` for the one error an API runner's refusal arrives as. It builds its own+ payload rather than going through :func:`agent_error`'s lookups, whose fallbacks keyed on ``error_type`` are+ local advice (see :func:`api_response_error_payload`), and renders it with the same JSON dump and the same+ markdown renderer, so a hosted refusal reads like a local failure.++ Args:+ error: The refusal the ``MthdsAPIClient`` raised.+ """+ payload = api_response_error_payload(error=error)+ 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)+ raise typer.Exit(1) from error++def extract_validation_errors(exc: ValidateBundleError) -> list[dict[str, Any]]:"""Project a ``ValidateBundleError`` into the CLI ``validation_errors`` JSON array.diff --git a/pipelex/cli/agent_cli/commands/run/_run_core_api.py b/pipelex/cli/agent_cli/commands/run/_run_core_api.pyindex 78a27e0ba..ac949cc4c 100644--- a/pipelex/cli/agent_cli/commands/run/_run_core_api.py+++ b/pipelex/cli/agent_cli/commands/run/_run_core_api.py@@ -35,7 +35,9 @@ async def run_pipeline_core_api(Dictionary with execution results suitable for JSON serialization.Raises:- ClientAuthenticationError: If API credentials are invalid or missing.+ ClientAuthenticationError: If the API key or the runner's base URL is missing.+ ApiResponseError: If the runner answers non-2xx, a refused bundle or a failed run among them,+ with the members of its problem document typed.PipelineRequestError: If the pipeline request is malformed."""async with MthdsAPIClient() as runner:diff --git a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py b/pipelex/cli/agent_cli/commands/run/bundle_cmd.pyindex 75ba7ca72..950fbfb28 100644--- a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/bundle_cmd.py@@ -8,6 +8,8 @@ from pathlib import Pathfrom typing import Annotated, Anyimport typer+from mthds.protocol.exceptions import PipelineRequestError+from mthds.runners.api.exceptions import ApiResponseError, ClientAuthenticationErrorfrom mthds.runners.types import RunnerTypefrom pipelex.builder.conventions import DEFAULT_BUNDLE_FILE_NAME@@ -15,6 +17,7 @@ from pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agfrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,agent_error,+ agent_error_api_response,agent_success_formatted,run_failure_fields,set_agent_cli_error_format,@@ -177,9 +180,6 @@ def run_bundle_cmd(if mock_inputs:agent_error("--mock-inputs is not supported with --runner api", error_type="ArgumentError")- from mthds.protocol.exceptions import PipelineRequestError # ruff: ignore[import-outside-top-level]- from mthds.runners.api.exceptions import ClientAuthenticationError # ruff: ignore[import-outside-top-level]-try:result = asyncio.run(run_pipeline_core_api(@@ -196,6 +196,10 @@ def run_bundle_cmd(except ClientAuthenticationError as exc:agent_error(str(exc), error_type="ClientAuthenticationError", cause=exc)+ except ApiResponseError as exc:+ # The runner answered non-2xx: its problem document says why, where, and what to do next.+ agent_error_api_response(error=exc)+except PipelineRequestError as exc:agent_error(str(exc), error_type="PipelineRequestError", cause=exc)diff --git a/pipelex/cli/agent_cli/commands/run/method_cmd.py b/pipelex/cli/agent_cli/commands/run/method_cmd.pyindex 88b358831..75a67ad84 100644--- a/pipelex/cli/agent_cli/commands/run/method_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/method_cmd.py@@ -8,12 +8,15 @@ from pathlib import Pathfrom typing import Annotated, Anyimport typer+from mthds.protocol.exceptions import PipelineRequestError+from mthds.runners.api.exceptions import ApiResponseError, ClientAuthenticationErrorfrom mthds.runners.types import RunnerTypefrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_clifrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,agent_error,+ agent_error_api_response,agent_success_formatted,run_failure_fields,set_agent_cli_error_format,@@ -148,9 +151,6 @@ def run_method_cmd(if mock_inputs:agent_error("--mock-inputs is not supported with --runner api", error_type="ArgumentError")- from mthds.protocol.exceptions import PipelineRequestError # ruff: ignore[import-outside-top-level]- from mthds.runners.api.exceptions import ClientAuthenticationError # ruff: ignore[import-outside-top-level]-try:result = asyncio.run(run_pipeline_core_api(@@ -167,6 +167,10 @@ def run_method_cmd(except ClientAuthenticationError as exc:agent_error(str(exc), error_type="ClientAuthenticationError", cause=exc)+ except ApiResponseError as exc:+ # The runner answered non-2xx: its problem document says why, where, and what to do next.+ agent_error_api_response(error=exc)+except PipelineRequestError as exc:agent_error(str(exc), error_type="PipelineRequestError", cause=exc)diff --git a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py b/pipelex/cli/agent_cli/commands/run/pipe_cmd.pyindex 65d8aa4bc..0985c360d 100644--- a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/pipe_cmd.py@@ -8,12 +8,15 @@ from pathlib import Pathfrom typing import Annotated, Anyimport typer+from mthds.protocol.exceptions import PipelineRequestError+from mthds.runners.api.exceptions import ApiResponseError, ClientAuthenticationErrorfrom mthds.runners.types import RunnerTypefrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_clifrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,agent_error,+ agent_error_api_response,agent_success_formatted,run_failure_fields,set_agent_cli_error_format,@@ -128,9 +131,6 @@ def run_pipe_cmd(if mock_inputs:agent_error("--mock-inputs is not supported with --runner api", error_type="ArgumentError")- from mthds.protocol.exceptions import PipelineRequestError # ruff: ignore[import-outside-top-level]- from mthds.runners.api.exceptions import ClientAuthenticationError # ruff: ignore[import-outside-top-level]-try:result = asyncio.run(run_pipeline_core_api(@@ -146,6 +146,10 @@ def run_pipe_cmd(except ClientAuthenticationError as exc:agent_error(str(exc), error_type="ClientAuthenticationError", cause=exc)+ except ApiResponseError as exc:+ # The runner answered non-2xx: its problem document says why, where, and what to do next.+ agent_error_api_response(error=exc)+except PipelineRequestError as exc:agent_error(str(exc), error_type="PipelineRequestError", cause=exc)diff --git a/pyproject.toml b/pyproject.tomlindex db5afeb70..92b26731e 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -31,7 +31,7 @@ dependencies = ["json2html>=1.3.0","kajson==0.7.1","markdown>=3.6",- "mthds==0.16.0",+ "mthds==0.17.0","networkx>=3.4.2","openai>=2.0.0","opentelemetry-api>=1.38.0",diff --git a/tests/unit/pipelex/cli/agent_cli/test_data.py b/tests/unit/pipelex/cli/agent_cli/test_data.pynew file mode 100644index 000000000..1231c2d49--- /dev/null+++ b/tests/unit/pipelex/cli/agent_cli/test_data.py@@ -0,0 +1,136 @@+"""Problem documents an API runner answers a refused run with, for the agent CLI's refusal tests."""++from typing import ClassVar, NamedTuple+++class RefusedRunBodies:+ """Problem documents a runner answers when it refuses a request, 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.+ """++ 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",+ ),+ 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}"+ ),+ 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",+ ),+ ]diff --git a/tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py b/tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.pynew file mode 100644index 000000000..36a4ccbd0--- /dev/null+++ b/tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py@@ -0,0 +1,340 @@+"""Unit tests: `pipelex-agent --runner api run` renders a runner's refusal the way it renders a local failure.++The runner's answers are the dev plane's own problem documents, replayed through the real `MthdsAPIClient`+over a mocked HTTP transport, so no test reaches the network.+"""++from __future__ import annotations++import asyncio+import io+import json+from typing import TYPE_CHECKING, Any++import httpx+import pytest+import typer+from mthds.runners.api.client import MthdsAPIClient+from mthds.runners.api.exceptions import ApiResponseError+from mthds.runners.types import RunnerType++from pipelex.cli.agent_cli.commands.agent_output import (+ AGENT_ERROR_HINTS,+ API_REFUSAL_CALLER_HINT,+ API_REFUSAL_HINTS_BY_STATUS,+ CliOutputFormat,+ agent_error_api_response,+ api_response_error_payload,+ set_agent_cli_error_format,+)+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 tests.unit.pipelex.cli.agent_cli.test_data import RefusalCase, RefusalCases, RefusedRunBodies++if TYPE_CHECKING:+ from pathlib import Path++ from pytest_mock import MockerFixture++RUNNER_URL = "https://runner.test"+RUN_PIPE_MODULE = "pipelex.cli.agent_cli.commands.run.pipe_cmd"+RUN_METHOD_MODULE = "pipelex.cli.agent_cli.commands.run.method_cmd"+++def _answering(*, status: int, body: str, seen: list[httpx.Request], headers: dict[str, str] | None = None) -> httpx.MockTransport:+ """A transport answering every request with ``status``, ``body`` and ``headers``, recording the requests it saw."""++ def _handler(request: httpx.Request) -> httpx.Response:+ seen.append(request)+ return httpx.Response(status, content=body.encode("utf-8"), headers={"content-type": "application/problem+json", **(headers or {})})++ return httpx.MockTransport(_handler)+++def _install_runner(mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, *, status: int, body: str) -> list[httpx.Request]:+ """Point every `MthdsAPIClient` at a mocked runner answering ``status`` / ``body``; return the requests it receives."""+ monkeypatch.setenv("MTHDS_API_KEY", "test-key-not-a-secret")+ monkeypatch.setenv("MTHDS_BASE_URL", RUNNER_URL)+ seen: list[httpx.Request] = []+ transport = _answering(status=status, body=body, seen=seen)++ def _start_client(self: MthdsAPIClient) -> MthdsAPIClient:+ self.client = httpx.AsyncClient(transport=transport)+ return self++ mocker.patch.object(MthdsAPIClient, "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 for this answer."""++ async def _execute() -> None:+ client = MthdsAPIClient(api_key="test-key-not-a-secret", base_url=RUNNER_URL)+ client.client = httpx.AsyncClient(transport=_answering(status=status, body=body, seen=[], headers=headers))+ try:+ await client.execute(pipe_code="entry", mthds_contents=["# bundle"])+ finally:+ await client.close()++ with pytest.raises(ApiResponseError) as exc_info:+ asyncio.run(_execute())+ return exc_info.value+++def _api_ctx(mocker: MockerFixture) -> Any:+ ctx = mocker.MagicMock()+ ctx.obj = {"runner": RunnerType.API}+ return ctx+++class TestRunApiRefusal:+ @pytest.fixture+ def tty_stdin(self, monkeypatch: pytest.MonkeyPatch) -> None:+ """Make stdin look like a TTY so parse_cli_inputs skips the stdin fallback."""+ mock_stdin = io.StringIO("")+ mock_stdin.isatty = lambda: True # type: ignore[assignment]+ monkeypatch.setattr("sys.stdin", mock_stdin)++ @pytest.fixture+ def bundle_file(self, tmp_path: Path) -> Path:+ """A bundle file the command reads and sends as is (never parsed: --pipe is passed)."""+ path = tmp_path / "bundle.mthds"+ path.write_text("# bundle\n", encoding="utf-8")+ 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,+ ) -> None:+ """The JSON envelope of each dev-plane refusal names its class, its located reason, its next step and its domain."""+ seen = _install_runner(mocker, monkeypatch, status=422, body=case.body)++ with pytest.raises(typer.Exit) as exc_info:+ run_bundle_cmd(ctx=_api_ctx(mocker), path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON)++ assert exc_info.value.exit_code == 1+ assert [(request.method, request.url.path) for request in seen] == [("POST", "/v1/execute")]+ 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/execute 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"]++ @pytest.mark.usefixtures("tty_stdin")+ def test_run_bundle_json_carries_the_runner_items_whole(+ 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 exactly as the runner sent them."""+ _install_runner(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNKNOWN_MODEL_AT_LOAD)++ with pytest.raises(typer.Exit):+ run_bundle_cmd(ctx=_api_ctx(mocker), path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON)++ envelope = json.loads(capsys.readouterr().err)+ assert envelope["error_category"] == "configuration"+ assert envelope["validation_errors"] == json.loads(RefusedRunBodies.UNKNOWN_MODEL_AT_LOAD)["validation_errors"]++ @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(+ self,+ mocker: MockerFixture,+ monkeypatch: pytest.MonkeyPatch,+ capsys: pytest.CaptureFixture[str],+ bundle_file: Path,+ case: RefusalCase,+ ) -> None:+ """The markdown of each dev-plane refusal reads like a local failure: heading, reason, hint, details."""+ _install_runner(mocker, monkeypatch, status=422, body=case.body)++ with pytest.raises(typer.Exit) as exc_info:+ run_bundle_cmd(ctx=_api_ctx(mocker), path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.MARKDOWN)++ 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/execute 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++ @pytest.mark.usefixtures("tty_stdin")+ def test_run_bundle_markdown_renders_the_runner_items_as_validate_does(+ 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_runner(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNKNOWN_MODEL_AT_LOAD)++ with pytest.raises(typer.Exit):+ run_bundle_cmd(ctx=_api_ctx(mocker), path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.MARKDOWN)++ 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++ @pytest.mark.usefixtures("tty_stdin")+ def test_run_bundle_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_runner(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNSERVED_MODEL_AT_RUN)++ with pytest.raises(typer.Exit):+ run_bundle_cmd(+ ctx=_api_ctx(mocker),+ path=str(bundle_file),+ pipe="entry",+ output_format=CliOutputFormat.MARKDOWN,+ error_format=CliOutputFormat.JSON,+ )++ assert json.loads(capsys.readouterr().err)["error_type"] == "ModelNotFoundError"++ @pytest.mark.usefixtures("tty_stdin")+ def test_run_pipe_reports_the_refusal(self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]) -> None:+ """`run pipe` on the API runner answers a refusal with the same envelope."""+ _install_runner(mocker, monkeypatch, status=422, body=RefusedRunBodies.COMBINE_FAILURE_AT_RUN)+ mocker.patch(f"{RUN_PIPE_MODULE}.resolve_pipe_from_exports", return_value=[])++ with pytest.raises(typer.Exit) as exc_info:+ run_pipe_cmd(ctx=_api_ctx(mocker), pipe_code="review_topics", output_format=CliOutputFormat.JSON)++ assert exc_info.value.exit_code == 1+ envelope = json.loads(capsys.readouterr().err)+ assert envelope["error_type"] == "StuffFactoryError"+ assert envelope["hint"] == RefusedRunBodies.COMBINE_FAILURE_NEXT_STEP++ @pytest.mark.usefixtures("tty_stdin")+ def test_run_method_reports_the_refusal(+ self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path+ ) -> None:+ """`run method` on the API runner answers a refusal with the same markdown."""+ _install_runner(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNSERVED_MODEL_AT_RUN)+ method_mock = mocker.MagicMock()+ method_mock.mthds_files = [bundle_file]+ method_mock.path = bundle_file.parent+ method_mock.provenance = None+ mocker.patch(f"{RUN_METHOD_MODULE}.resolve_method_target", return_value=("digest_article", [str(bundle_file.parent)], method_mock))++ with pytest.raises(typer.Exit) as exc_info:+ run_method_cmd(ctx=_api_ctx(mocker), name="news-digest", output_format=CliOutputFormat.MARKDOWN)++ assert exc_info.value.exit_code == 1+ markdown = capsys.readouterr().err+ assert markdown.startswith("# Error: ModelNotFoundError\n")+ assert f"> 💡 **Hint:** {RefusedRunBodies.UNSERVED_MODEL_NEXT_STEP}" in markdown++ def test_payload_of_an_answer_that_is_no_problem_document(self) -> None:+ """A gateway's page gives the client's own class, the static 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/execute failed (502): {RefusedRunBodies.GATEWAY_HTML}"+ assert payload["hint"] == AGENT_ERROR_HINTS["ApiResponseError"]+ 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"] == AGENT_ERROR_HINTS["ApiResponseError"]+ 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"] == API_REFUSAL_CALLER_HINT++ 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"] == API_REFUSAL_HINTS_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/execute failed (403): Forbidden"+ assert payload["hint"] == API_REFUSAL_HINTS_BY_STATUS[403]+ assert "MTHDS_API_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"] == API_REFUSAL_HINTS_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 MTHDS_BASE_URL, 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":"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/execute failed (404): Not Found"+ assert not_found["hint"] == API_REFUSAL_HINTS_BY_STATUS[404]+ assert "MTHDS_BASE_URL" in not_found["hint"]+ assert unprocessable["hint"] == API_REFUSAL_CALLER_HINT+ for payload in (not_found, unprocessable):+ assert "retryable" not in payloaddiff --git a/tests/unit/pipelex/cli/test_agent_output_drift.py b/tests/unit/pipelex/cli/test_agent_output_drift.pyindex 978f034d9..a60a834c7 100644--- a/tests/unit/pipelex/cli/test_agent_output_drift.py+++ b/tests/unit/pipelex/cli/test_agent_output_drift.py@@ -42,6 +42,7 @@ _NON_PIPELEX_ERROR_KEYS: frozenset[str] = frozenset("PipeValidationError", # subclass of ValueError, not of PipelexError"ClientAuthenticationError", # mthds API client package"PipelineRequestError", # mthds API client package+ "ApiResponseError", # mthds API client package"ArgumentError", # synthetic error_type label"BinaryNotFoundError", # synthetic error_type label"FixBundleError", # synthetic error_type labeldiff --git a/uv.lock b/uv.lockindex 35f88c2fb..36de631a5 100644--- a/uv.lock+++ b/uv.lock@@ -2692,7 +2692,7 @@ wheels = [[[package]]name = "mthds"-version = "0.16.0"+version = "0.17.0"source = { registry = "https://pypi.org/simple" }dependencies = [{ name = "httpx" },@@ -2701,9 +2701,9 @@ dependencies = [{ name = "tomlkit" },{ name = "typing-extensions" },]-sdist = { url = "https://files.pythonhosted.org/packages/25/03/4aca733536f741f741d0cba3ae3d23dfd56f691c53a0d7e3e7baea371585/mthds-0.16.0.tar.gz", hash = "sha256:cc8f54bc76c9ed13273e7cd2e1c66767e5478fc3640a26481bf099451d56aa29", size = 259394, upload-time = "2026-09-23T12:13:31.752Z" }+sdist = { url = "https://files.pythonhosted.org/packages/3a/51/e68684d8bea26098f6a03339f97084038dba54b778ad7d55a07b73763e38/mthds-0.17.0.tar.gz", hash = "sha256:7515dea7a014ed55416e428c29172a7482d674a12bad73d1222bc5090d4c669c", size = 276301, upload-time = "2026-09-27T13:08:43.234Z" }wheels = [- { url = "https://files.pythonhosted.org/packages/d0/00/a80f90f0ed7ddff9886f925fbb8dd0061ec0b0e1af49901971664f1a3e12/mthds-0.16.0-py3-none-any.whl", hash = "sha256:67468669451278e8c17409c5fed60eafab8453fd5cd92f333d788b21f7500ebe", size = 103813, upload-time = "2026-09-23T12:13:30.288Z" },+ { url = "https://files.pythonhosted.org/packages/4e/e2/dc57d0a6370546c2ef1563eacfdb5037c6f5d569c23f407d73acb0473c2e/mthds-0.17.0-py3-none-any.whl", hash = "sha256:cfd4530eb7760490489680edbbbaba448150086ac4b122ee272a64f271785ec4", size = 110748, upload-time = "2026-09-27T13:08:41.722Z" },][[package]]@@ -3618,7 +3618,7 @@ requires-dist = [{ name = "mkdocs-meta-manager", marker = "extra == 'docs'", specifier = ">=1.1.0" },{ name = "mkdocs-redirects", marker = "extra == 'docs'", specifier = "==1.2.2" },{ name = "moto", extras = ["dynamodb", "s3"], marker = "extra == 'dev'", specifier = ">=5.0.0" },- { name = "mthds", specifier = "==0.16.0" },+ { name = "mthds", specifier = "==0.17.0" },{ name = "mypy", marker = "extra == 'dev'", specifier = "==1.19.1" },{ name = "networkx", specifier = ">=3.4.2" },{ name = "openai", specifier = ">=2.0.0" },