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-renders-problem · L-261015-cf3bf1 (#1453)
Louis Choquel846664031453
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex 7882bc2e4..c8507d873 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,55 +1,55 @@contract = "cli-docs"-digest = "sha256:b626be1be5722c6a18de9dc925647ab01eff48908a67a4f568da6295a1e711aa"+digest = "sha256:e9cbbf01620b3bae6f72a1088181ca0ffed8b850692d4afdcc6ebf378ee9853a"reviewed_by = "Louis Choquel"-reviewed_at = "2026-10-18T10:52:34Z"-rationale = "clean-pass: merging code-on-every-error, which carries dev's v0.89.0, into the Problem branch combines changes each side reviewed; run bundle keeps both arms, the run's own MethodEntryError for a folder with no single main_pipe and dev's pre-boot configuration refusal, now through bundle_target_resolution.py. docs/tools/cli/run.md and agent-cli.md, and pipelex/cli/agent_cli/CLAUDE.md, which this merge updated to dev's paths and anchors, describe both."+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."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc""pipelex/cli/_cli.py" = "blob:86fa74a5c45f33915548dc5ad4ec8ddbaf2b75d6""pipelex/cli/agent_cli/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"-"pipelex/cli/agent_cli/_agent_cli.py" = "blob:ad97a597f92ece45d06e571792f77c5b4805826e"+"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:1e816dea1a7439e0bd0030754a5c519112aeead0"-"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:0e6c177a0e7b8156f6b43c57ae87b2e87cadf661"-"pipelex/cli/agent_cli/commands/bundle_path_resolver.py" = "blob:93dd3c074626be471437c3815e51b6783cb52d13"-"pipelex/cli/agent_cli/commands/check_model_cmd.py" = "blob:3a9c93daecadf266b3eba466904b3d005d448d40"+"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/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""pipelex/cli/agent_cli/commands/codegen/app.py" = "blob:56130b89fe9efec5ad3d014ed6bc16bef1bd1645"-"pipelex/cli/agent_cli/commands/codegen/check_cmd.py" = "blob:9e8beb084a9f04f39e8acca9e6ae2554d40cb667"-"pipelex/cli/agent_cli/commands/codegen/types_cmd.py" = "blob:7ada455f0bbe20dc30cff73cbc33c397bcf86f39"-"pipelex/cli/agent_cli/commands/doctor_cmd.py" = "blob:948be63cf4fab165846c83b4bd2517bd4a46be5e"+"pipelex/cli/agent_cli/commands/codegen/check_cmd.py" = "blob:6c3bf07ca0a72676f06c1649aa82142fd37e20d5"+"pipelex/cli/agent_cli/commands/codegen/types_cmd.py" = "blob:e12880cff97b7272d26ea5b20da7885667a05e56"+"pipelex/cli/agent_cli/commands/doctor_cmd.py" = "blob:2636e79518279a61b8aee679fcea7bb0c31a57f4""pipelex/cli/agent_cli/commands/fix/__init__.py" = "blob:65662c86f17f610ad55ecfc3e27a022b9aa26e8b""pipelex/cli/agent_cli/commands/fix/app.py" = "blob:fbf3b1ff8298b0cd18f0b712b7623652c5975662"-"pipelex/cli/agent_cli/commands/fix/bundle_cmd.py" = "blob:96c978985debd9deba7a25e055c541c6f85f592e"-"pipelex/cli/agent_cli/commands/fix/function_names_cmd.py" = "blob:4b06e5d112fe9b9dfd3e9a5fdda5ba1bc99cff14"+"pipelex/cli/agent_cli/commands/fix/bundle_cmd.py" = "blob:c37674a1a89e164b1fae24191466c7e93a92ce40"+"pipelex/cli/agent_cli/commands/fix/function_names_cmd.py" = "blob:3c3c839707e789949c5783b640d23aaef112981a""pipelex/cli/agent_cli/commands/fmt_cmd.py" = "blob:97d6fb6c328e0b718b1293bd6b73cba03edcb7dc"-"pipelex/cli/agent_cli/commands/init_cmd.py" = "blob:513b1160d8e3815b34b905bbabccd59d6c379842"+"pipelex/cli/agent_cli/commands/init_cmd.py" = "blob:5d634c6f27f243de904e42322bd1e43d62c81ba9""pipelex/cli/agent_cli/commands/inputs/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/inputs/_inputs_core.py" = "blob:4161029643f3a302de54fa637d2676521e10d873""pipelex/cli/agent_cli/commands/inputs/app.py" = "blob:b30915d6fce2f524af4f0b2a50a37ffd7eaffab6"-"pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py" = "blob:fedf9fb6f37b37f80dd73be5380a603e23248bfa"-"pipelex/cli/agent_cli/commands/inputs/method_cmd.py" = "blob:604e91b2e65d951fd9a6eeed924a01f04fe2096f"-"pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py" = "blob:73b79e57c9c71da282723711b5cbe9ade8838779"+"pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py" = "blob:976b909bac4d8d10b8de5efa84d03f17a5793dee"+"pipelex/cli/agent_cli/commands/inputs/method_cmd.py" = "blob:632864820c102553c972c9ce3a2a2429c6d8f7be"+"pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py" = "blob:9001d6336761236b2f6947cdb3694b4a13cd3bf2""pipelex/cli/agent_cli/commands/lint_cmd.py" = "blob:91ad9cb4d618ba4c0b7da366cde2f74f38d350df"-"pipelex/cli/agent_cli/commands/migrate_cmd.py" = "blob:dbe1f689607ccea0b1f5f1dadca20f19f65ce400"-"pipelex/cli/agent_cli/commands/models_cmd.py" = "blob:f48a921fa89d8275c585b3e15f135f5585ac01aa"-"pipelex/cli/agent_cli/commands/plxt_passthrough.py" = "blob:289adc65f49a185ca9f81bb73f87b4c68facb62b"+"pipelex/cli/agent_cli/commands/migrate_cmd.py" = "blob:3f60020ed38c289e7fae66e8e9c735030bd2521f"+"pipelex/cli/agent_cli/commands/models_cmd.py" = "blob:f6365858100ccedb5e85afe5c6c689d9018adfdb"+"pipelex/cli/agent_cli/commands/plxt_passthrough.py" = "blob:dc4916d28a5e83e18c9c59cc7e81191ea7869646""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:cea011e61feb082a7b9d82d7693b4fd3246737e5"+"pipelex/cli/agent_cli/commands/run/_run_hosted.py" = "blob:e1b309868a9bf92e5fdae06d646d995a3758a9c0""pipelex/cli/agent_cli/commands/run/app.py" = "blob:7546d9b31ea2dc22b1ddae538edfbc8e7f7d08df"-"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:81ce053d4401a782bfce0d5536d6e4d3fc748a6d"-"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:776d1cf4bfbdce645f3cbfcd28be46bfb97174b0"-"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:f6be2d8b0a5e20c087a12fdaf8c42eb2549dfb00"-"pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:847552a863af5f8e98a4ce1c473c2e828b86a5d6"+"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:e8976dd91908262d8d7d5bf2d2e4e11c978a3f3b"+"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:0df77aa1e35c22ceffdcefd7f4c12f28fda366c7"+"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:1a5a2f86ac80fb86cb53376202bad05ffd19e9f6"+"pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:db0176d7de1e074fd6eefd787c10e71b891eeb32""pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:b15fb5ee5b3d84cb229f3eb3353df8354cfd488d""pipelex/cli/agent_cli/commands/validate/app.py" = "blob:1982684a2aae81e0d634bb3b262457a5f187d979"-"pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:ee5dd482fdf03eb2530afcdebfc393fe68646893"-"pipelex/cli/agent_cli/commands/validate/method_cmd.py" = "blob:0f4cf76d99b39422610c5daf6b5a0500de234818"-"pipelex/cli/agent_cli/commands/validate/pipe_cmd.py" = "blob:c945950c88d4049b5c6400111ccb85b0cb4cc657"+"pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:3c7045c77c15b2ab5fdb1629a4203e53231b764d"+"pipelex/cli/agent_cli/commands/validate/method_cmd.py" = "blob:19cbf94ca5027983e5fd95b73bc346efaf195c37"+"pipelex/cli/agent_cli/commands/validate/pipe_cmd.py" = "blob:786e4f13878dbe04d18493c15c613fc7d0d8e473""pipelex/cli/bundle_target_resolution.py" = "blob:fd4c1da386c33f4542c11a68ad4ce5bed64bc4aa""pipelex/cli/cli_factory.py" = "blob:9768ead842eecbfc9509dc68aafca31957a27439""pipelex/cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"@@ -78,11 +78,11 @@ rationale = "clean-pass: merging code-on-every-error, which carries dev's v0.89."pipelex/cli/commands/doctor_cmd.py" = "blob:a991d210787c0df68d9cc6bac29361df89e8e9c7""pipelex/cli/commands/fix/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/commands/fix/_diff_sandbox.py" = "blob:d05eb4351f7065eaa45f63089f2daae0b02457dd"-"pipelex/cli/commands/fix/_fix_core.py" = "blob:afd6b07809e2a67105d5a2a9fea31523e2d14c9e"+"pipelex/cli/commands/fix/_fix_core.py" = "blob:3e8246119b9e89d695b3a8383094d65b89aa9ed0""pipelex/cli/commands/fix/app.py" = "blob:61ed114633c679a252fa7d9367d4cf8e800f86ee""pipelex/cli/commands/fix/bundle_cmd.py" = "blob:83bf3fda431fb5d81f1763be28835730df0a9872""pipelex/cli/commands/fix/function_names_cmd.py" = "blob:b645a3d7687f01f18474446d29e23df4f1acc751"-"pipelex/cli/commands/graph_cmd.py" = "blob:6876a99877752f23369436c4bd7e3eb8726c8401"+"pipelex/cli/commands/graph_cmd.py" = "blob:a7b1b232c890d623ecf10fed54b4109546e0f95e""pipelex/cli/commands/init/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/commands/init/backends.py" = "blob:0cc3543c78f832149ebbbf3cc8beafee619e4f63""pipelex/cli/commands/init/command.py" = "blob:4747c1b9dff00163ca5cd48595ea8545a3b02b4b"@@ -111,15 +111,15 @@ rationale = "clean-pass: merging code-on-every-error, which carries dev's v0.89."pipelex/cli/commands/run/_inputs_file_loader.py" = "blob:8039ca6b29f4f9091d0ea7406c8b8a4590848131""pipelex/cli/commands/run/_inputs_path_resolver.py" = "blob:c8ec89d98718e18af7aaaded44c9f545be60adab""pipelex/cli/commands/run/_main_stuff_file.py" = "blob:ca806e55085aa2e5748492751521296ce1f42960"-"pipelex/cli/commands/run/_run_core.py" = "blob:2bc88a004d2d55f6f85c786b133718dd168678c6"-"pipelex/cli/commands/run/_run_hosted.py" = "blob:80df4e50e7f4ece31ebf4d51e34dbddef9466cae"+"pipelex/cli/commands/run/_run_core.py" = "blob:633b707d1ae9bf6a08735f3acbd0c2a9ba415329"+"pipelex/cli/commands/run/_run_hosted.py" = "blob:f61b3ea7fdc6c29823ecd6cb5b469ab271814c3f""pipelex/cli/commands/run/_run_output_folder.py" = "blob:5834889a5e35e6457acf24761b408bc6a7bbfd6c""pipelex/cli/commands/run/app.py" = "blob:e312b159625e0a72bc9a18d3bfd2c73e7ac59f24""pipelex/cli/commands/run/bundle_cmd.py" = "blob:faff9a7cba8027bb7b13f7f5a3b94666f3742b80""pipelex/cli/commands/run/exceptions.py" = "blob:cebeb5950c87a1e113ed717565ae8cb783bb5001""pipelex/cli/commands/run/method_cmd.py" = "blob:924bca6e242d8490e32eeb9ed2329db3d1b58b8d""pipelex/cli/commands/run/pipe_cmd.py" = "blob:c967729a039518a718d7bc28d77797423ce20fc4"-"pipelex/cli/commands/show_cmd.py" = "blob:764665c787525a52d44bff1fb6e64acd008729aa"+"pipelex/cli/commands/show_cmd.py" = "blob:ed0653825fa72563e9dd20840457929ea6c71e3b""pipelex/cli/commands/update_cmd.py" = "blob:b2db6170ddd9c67f17d88096ba1f1796a897557d""pipelex/cli/commands/usage_stats_cmd.py" = "blob:b3723c64f911d1b69e1e1aa126610a132a16e3da""pipelex/cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"@@ -130,11 +130,11 @@ rationale = "clean-pass: merging code-on-every-error, which carries dev's v0.89."pipelex/cli/commands/validate/pipe_cmd.py" = "blob:ab8cca9c5c8c5d7dce005deba6d2d8b32dc2e81e""pipelex/cli/commands/which_cmd.py" = "blob:5febd14510603f09ef0fb29d5ef97c35b7a6692f""pipelex/cli/deck_notice.py" = "blob:542877125e89e35b02bc969cfee952155b0d7c2c"-"pipelex/cli/error_handlers.py" = "blob:a54aba5689ffcb6bfda2b842b2875f4121683787"+"pipelex/cli/error_handlers.py" = "blob:b0bbfbb058ef764de90c7f1ba09093a7616f43c6""pipelex/cli/exceptions.py" = "blob:5c66f20b0a06c8ae8c20b94f92e2c30b78f5b6c5""pipelex/cli/installed_methods.py" = "blob:1de9b36e7717786fe0454af69011e05ef50610ba""pipelex/cli/judged_target.py" = "blob:8d3f3b3359992feeeca2bd4acd1d404262cbaf87""pipelex/cli/method_resolver.py" = "blob:54fe2e6036b637c2e298f18bbfd10cfc616ef4a8""pipelex/cli/readiness.py" = "blob:6d185324ed0784663e1dc78d1194a28312c54798"-"pipelex/cli/usage_stats_cli.py" = "blob:d04e2191e6f6a18027558a3e063f945be7b77679"+"pipelex/cli/usage_stats_cli.py" = "blob:c4714885f6bae4ff30609c0db5463bd1b056ce61""pipelex/cli/version_report.py" = "blob:f4a2311bb629bd77196ea2f6b031c166db0d362a"diff --git a/.drift/acks/hub-layering-convention.toml b/.drift/acks/hub-layering-convention.tomlindex b540eb484..7e2e8ec64 100644--- a/.drift/acks/hub-layering-convention.toml+++ b/.drift/acks/hub-layering-convention.toml@@ -1,10 +1,10 @@contract = "hub-layering-convention"-digest = "sha256:79d4e68f7ae4755f1a027bc882f105c1985a5ecf291bd888dd3792269162951b"+digest = "sha256:dd59159853d97c98d62d3fcb2c38c8f0b4a10807033c5ac43a17a13bcaa37e85"reviewed_by = "Louis Choquel"-reviewed_at = "2026-10-16T05:26:39Z"-rationale = "real-catch: runtime_hub.py gains the method file store and the template file stage, and interpreter_hub.py drops does_pipe_run_leave_process with set_pipe_run's leaves_process; docs/contribute/hub-layering.md now lists get_method_file_store and get_template_file_stage, no longer lists does_pipe_run_leave_process, and says how the template file stage is installed by the interpreter's boot and released at teardown. No import crosses the boundary."+reviewed_at = "2026-10-17T05:54:29Z"+rationale = "real-catch: runtime_hub.py gains get_error_console, the stderr console a CLI prints a failure's report through; docs/contribute/hub-layering.md lists it beside get_console. No import crosses the boundary."[trigger_files]"pipelex/cli/dev_cli/commands/hub_layering_guard.py" = "blob:fda2237457fe0b6830ff2ae8f720698735bec4c3""pipelex/interpreter_hub.py" = "blob:e1a4b941820aeb8affbb6c70b7f81eb29e4cc191"-"pipelex/runtime_hub.py" = "blob:ca642e419aeac8eee7bd0dba2b5784feb0059e82"+"pipelex/runtime_hub.py" = "blob:48f34feea22c29a56910f4a2fbb317a1d0a1e492"diff --git a/.drift/acks/logging-docs.toml b/.drift/acks/logging-docs.tomlindex d0252ecb4..0ffa14467 100644--- a/.drift/acks/logging-docs.toml+++ b/.drift/acks/logging-docs.toml@@ -1,10 +1,10 @@contract = "logging-docs"-digest = "sha256:f07cb29a7da0c4d4f3b462d3cc7879db0de8a1991455e000de153d036e487b4f"+digest = "sha256:e9d1efdae09623788998bf78a017bf4ab34e85bf61e88c64ff02b29f6f613494"reviewed_by = "Louis Choquel"-reviewed_at = "2026-10-17T06:50:19Z"-rationale = "real-catch: the contract now triggers on pydantic_utils.py, where error_fields writes a ValidationError: its locations, reasons and the new is_authored_input option live there. logging.md now names the TypeAdapter form of validated_type and is_authored_input, the secondary-failure lines logged by class and code, and the instructor records no sink writes; log-sink-plugins.md said a redaction failure was the one case a sink misses an accepted record, and now names the instructor filter as the other."+reviewed_at = "2026-10-19T10:03:38Z"+rationale = "real-catch: the merge of dev's #1452 into this branch left error_fields.py with two ERROR_CODE_FIELD constants, #1452's for a pipe's failure line and this branch's for a CLI root's failure line and the security event; one remains. logging.md's field table row for error.code was merged in the merge commit to name all three carriers, and its Exceptions section, which #1452 rewrote for a pipe's failure and a secondary failure, still holds against error_fields.py and pydantic_utils.py; log-sink-plugins.md states nothing these modules decide."[trigger_files]"pipelex/tools/log/console_fields.py" = "blob:10c4516405dfdfe889590ef0d8e1914f56600a2f"-"pipelex/tools/log/error_fields.py" = "blob:e58e2a88ebc48c08fdfe1c7d173c9a719346cac0"+"pipelex/tools/log/error_fields.py" = "blob:76a1e4c88aa57427a11e7550c1144644494d56f3""pipelex/tools/typing/pydantic_utils.py" = "blob:6c469e95f53135d426c00e7b4cfc8711004f518b"diff --git a/AGENTS.md b/AGENTS.mdindex 6a24dd8eb..7e1037fd5 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -208,7 +208,7 @@pretty_print(output_object, title="Your first Pipelex output")```- Both handle formatting json using Rich, pretty_print makes it prettier.-- A log message is a fixed sentence with its values in `fields=`, never interpolated at INFO and above, and never holding Rich markup: `log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})`. It is one short sentence, subject first, starting with a capital and ending with no period or `...`, with no backtick and, at INFO and above, no identifier and at most 80 characters; advice rides in a `user_action` field ("Wording a message" in `docs/tools/logging.md`). A handled exception at WARNING and below rides in `fields=` as `**error_fields(exc=exc)` (`pipelex.tools.log.error_fields`), at ERROR as `include_exception=True`, never as `{exc}` in the text, at any level; an exception logged and then re-raised rides as `**error_fields(exc=exc)` at every level, its traceback being its catcher's to print, and so do a cleanup's failure while another exception propagates, whose traceback would chain the primary's text, and a swallowed pydantic `ValidationError`, whose traceback quotes the values it refused. The catcher of an unexpected failure, a CLI command's root or the API's error handler, logs it at ERROR with `include_exception=True` and prints no traceback of its own; a CLI command's root also prints the exception's type and message in its own output (`print_unexpected_failure` in `pipelex.cli.error_handlers`), so the terminal names the cause whatever the sink and the level. Field names come from the vocabulary table in `docs/tools/logging.md` ("Log-call conventions"), which review holds the calls to: `make check-log-calls` reads the messages, never the `fields=` keys.+- A log message is a fixed sentence with its values in `fields=`, never interpolated at INFO and above, and never holding Rich markup: `log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})`. It is one short sentence, subject first, starting with a capital and ending with no period or `...`, with no backtick and, at INFO and above, no identifier and at most 80 characters; advice rides in a `user_action` field ("Wording a message" in `docs/tools/logging.md`). A handled exception at WARNING and below rides in `fields=` as `**error_fields(exc=exc)` (`pipelex.tools.log.error_fields`), at ERROR as `include_exception=True`, never as `{exc}` in the text, at any level; an exception logged and then re-raised rides as `**error_fields(exc=exc)` at every level, its traceback being its catcher's to print, and so do a cleanup's failure while another exception propagates, whose traceback would chain the primary's text, and a swallowed pydantic `ValidationError`, whose traceback quotes the values it refused. The API's error handler, the catcher of an unexpected failure, logs it at ERROR with `include_exception=True` and prints no traceback of its own. A CLI command's root logs an unexpected failure at ERROR with identifiers only, `fields=failure_log_fields(error=exc, problem=problem)` (`pipelex.errors.failure_problem`: the problem's code and the chain's classes, never a chained exception's text, which can quote a run's data) and `include_exception=is_traceback_requested()`, so the traceback rides only under `--traceback`; it prints the failure's problem in its own output (`print_failure_problem` in `pipelex.cli.error_handlers`), so the terminal names the cause whatever the sink and the level. Field names come from the vocabulary table in `docs/tools/logging.md` ("Log-call conventions"), which review holds the calls to: `make check-log-calls` reads the messages, never the `fields=` keys.#### StrEnum and Self typediff --git a/CHANGELOG.md b/CHANGELOG.mdindex e8fc825ad..d54307ccf 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,7 @@- **Every error carries its registry code**: every `PipelexError` subclass declares in `error_code` the code it raises, a code of the MTHDS core registry or of the Pipelex error registry, or else an `ErrorCodeSet` its raise sites choose from with `with_error_code()`, its cause's code (`InheritsCause`, with a fallback), or `ABSTRACT_ERROR` for a base never raised itself. `resolve_error_code()` gives the code an error reports, the first one named along its cause chain, and `runtime.unexpected` when none is; `pipelex.errors.error_codes` reads any code's title, domain, retry verdict, status and steps (`error_code_spec`, `parse_error_code`).- **`PipelexError.with_items()`**: a raise site that finds several faults of one kind gives one problem item per fault, so a `PipeParallel` whose branches give several results of a multiplicity their fields do not declare names each one in its `pipe.output_multiplicity` problem's `errors`, beside the first in its sentence.- **`PluginRegistrar.declare_error_codes`**: a plugin, a closed one included, declares the public codes it raises while it registers, and a code neither the MTHDS core nor the Pipelex registry defines refuses the boot with `PluginErrorCodeNotRegisteredError` (`pipelex.plugin.broken`), naming the plugin and the code.+- **`--error-format` on `pipelex-agent` itself and on its `inputs` commands**: the error format can be given before the command, `pipelex-agent --error-format json validate bundle …`, where a command's own `--error-format` still wins and its `--format` still serves when neither is given, so a caller forwards one flag whatever the command; the `inputs` commands take `--error-format` too, falling back to the program's and then to JSON, never to their `--format`, which is the template's serialization.- **`InputFreeValueError` and the input-free rendering of a refusal**: a pydantic validator raising `InputFreeValueError` (`pipelex.tools.typing.validation_exceptions`) declares that its message names nothing of the value it refused, which keeps its sentence wherever a refusal of a run's data is written, and `format_validation_error_without_input()` and `describe_exception_without_input()` (`pipelex.tools.typing.pydantic_utils`) write a `ValidationError` as its locations and reasons, never the values it refused.- **`PipelexRequestError`**: the runtime's own refusal of a request it cannot serve is a `PipelineRequestError` of the mthds package carrying the core code `request.invalid` (or `request.unsupported`) and its problem document, so a client reads the same refusal whether the runtime or the standard's client raised it.- **The security event**: a refusal coded in the `security.` or `pipelex.security.` family fails its run under that code and logs one record on its own logger, `pipelex.errors.security_event`, at warning level, with the message `A security rule refused a request` and `event.name` set to `pipelex.security.refusal`, naming the code, its domain, the kind of target refused, the class of destination when the rule knows it (`loopback`, `private`, `link_local`, `metadata`, `scheme`, `foreign_storage_key`), the run, the request and each of the run's extras as `run.extras.<key>`, and never the URL, path, template or any input value. The process that raises a refusal logs it, once: the pipe run for a refusal raised while it executes, its delivery included, the runner for one before the run exists and for one raised in its own process that no pipe run logged, and the API server for one answered before any run, the refusals it authors itself included (a reserved object key, a callback URL the SSRF rule refuses, a resource path or a method file path leaving the method: absolute, naming a drive or a network share, or climbing with `..`, read with either separator, while a path of the wrong shape is `request.invalid` and logs none), which keep their response, while a failure rebuilt from another process's report is never logged again, since the orchestrator that rebuilds it marks it, and no event names a run id a request body chose; `pipelex.errors.security_event` gives a host `emit_security_event()`, `mark_security_event_emitted()` and `log_security_event()`, and a raise site states the class of destination with `PipelexError.with_security_target_class()`.@@ -34,8 +35,11 @@- **Inference failures carry the code their classification picks (Breaking)**: the classification of a provider's failure picks a code with its category, a `ServiceErrorCode` a plugin contributes names its `error_code`, and a category that repeats the call within the run must pick a code that invites a retry; an error built with a category alone reports the category's code (`provider.unavailable` for `TRANSIENT`, `runtime.misconfigured` for `CONFIGURATION`, `provider.quota_exhausted` for `CAPACITY`, `provider.outcome_unknown` for `AMBIGUOUS`). A provider 400 that carries no context-window or content-policy signal is `runtime.unexpected`, answered 500, where it was the caller's 422, and a local extractor's `OSError` is `runtime.unexpected`, no longer repeated within the run.- **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.+- **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.-- **`pipelex-agent` reads `retryable` from the code (Breaking)**: the agent CLI's error envelope takes `retryable` from the error's code, and its table of retryable error types is gone, as are the domain-table entries of classes that now carry a code. The envelope names that code as `error_code`, the member a hosted refusal already carried, so an agent branches on the code whichever runner failed, and its `hint`, when the error's chain advises nothing and the table names no hint for its class, is its code's next step as the operator reads it.- **`Jinja2TemplateSecurityError` is a `SecurityError` (Breaking)**: the template sandbox's refusal at render time now derives from `SecurityError`, like `UriReadRefusedError`, `SsrfBlockedError` and `UnsafeSchemaError`, instead of `ToolError`, so a host catching `SecurityError` catches it too and an `except ToolError` no longer does; it stays a type of its own, apart from `Jinja2TemplateRenderError`, and its class name, which the operator reads as `diagnostics.error_class`, and its code, `security.template_refused` on a method's template, are unchanged.- **A security refusal is never a validation verdict (Breaking)**: a refusal a raise site coded in the `security.` family is let through by the bundle-validation cascade whatever its class, as a `SecurityError` always was, so a `PipeDocGen` step whose `template_file` climbs above its method tree's root fails `validate` and a run with `security.method_path_refused` and logs its security event, where it was a `method.invalid` verdict naming the pipe.- **`mthds` 0.22.1 and `pipelex-sdk` 0.46.0 (Breaking)**: the exact pins move from `mthds==0.22.0` and `pipelex-sdk==0.45.0` to `mthds==0.22.1`, the release whose errors carry the MTHDS problem document read by its registry code, and `pipelex-sdk==0.46.0`, the release built on it; everyone downstream inherits those exact versions.@@ -49,6 +53,7 @@- **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 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.- **A prompt over the model's context window reads `model.context_exceeded`**: a provider 400, or another 4xx such as the 422 or 413 a gateway may answer, saying the inputs are over what the model can read, by OpenAI's `context_length_exceeded` code or by the wording OpenAI, Anthropic, Mistral, Bedrock and Gemini give it, in the error's message or its body, is the caller's `model.context_exceeded`, answered 422, where it read `runtime.unexpected`, or `input.too_large` on a 413. A language model's window holds the prompt and the output requested with `max_tokens` together, and a 400 the `max_tokens` sent caused reads the same, so its next step is to shorten the input or lower `max_tokens`, or choose a model with a larger context window; an image, extraction, search or judgment model's next step names what it reads instead. A 400 about a malformed request still reads `runtime.unexpected`.- **A structured output cut at `max_tokens` reads `model.output_truncated`**: the Anthropic, OpenAI Chat Completions and Mistral workers turn instructor's `IncompleteOutputException`, raised for a structured answer cut at its output limit, into `LLMCompletionTruncatedError`, naming a structured output, the stop value, the output tokens and the `max_tokens` sent, where it escaped unclassified as `runtime.unexpected`. `LLMCompletionTruncatedError` takes an `output_kind`, a text or a structured output. When the Anthropic structured-output timeout lowered the limit that cut it, the error says so and advises a lower reasoning effort or a smaller output, never a higher `max_tokens`.- **A Gemini image a safety filter blocked reads `model.content_refused`**: the Google image worker reads the answer's finish reason, or the prompt's block reason when no candidate came back, and raises `ImgGenGenerationError` with `model.content_refused`, answered 422 with a next step to revise the prompt or its images, where an `IMAGE_SAFETY` or `PROHIBITED_CONTENT` answer read as an empty one, `provider.response_invalid`. The message names the reason Gemini gave and what it says, so an image stopped for recitation or for an unsupported language reads the same code without being called a safety block. An answer the model's output token limit stopped before it held an image (`MAX_TOKENS`) raises the new `ImgGenOutputTruncatedError`, `model.output_truncated`, answered 422 with a next step to simplify the prompt or choose another image model, where it read `provider.response_invalid`.diff --git a/api/pipelex_api/routes/pipelex/validate.py b/api/pipelex_api/routes/pipelex/validate.pyindex 84cdb4e35..ec7cdcc40 100644--- a/api/pipelex_api/routes/pipelex/validate.py+++ b/api/pipelex_api/routes/pipelex/validate.py@@ -477,10 +477,10 @@ def _invalid_report_response(failure: BundleValidationFailure, *, requested_formvalidation_errors=failure.validation_errors,message=failure.problem.detail,)- # `exclude_none` drops each item's unset locators, so the wire items match the agent CLI's- # `extract_validation_errors` byte-for-byte (it dumps items the same way) — the "one error item,- # two surfaces" guarantee. The invalid arm's own fields are all non-None, so none are lost; and- # `rendered_markdown` stays absent here unless explicitly requested below.+ # `exclude_none` drops each item's unset locators, so a wire item carries only what its fault has. The+ # items are `ValidateBundleError.validation_error_items()`, the ones the agent CLI's problem turns into its+ # `errors` — the "one error item, two surfaces" guarantee. The invalid arm's own fields are all non-None,+ # so none are lost; and `rendered_markdown` stays absent here unless explicitly requested below.content = invalid_report.model_dump(mode="json", serialize_as_any=True, by_alias=True, exclude_none=True)# Opt-in presentation extra (D-D): a faithful render of the structured `validation_errors`,# attached only when `markdown` was requested. Built from the just-dumped content so the rendererdiff --git a/docs/api-server/openapi/pipelex-api.openapi.yaml b/docs/api-server/openapi/pipelex-api.openapi.yamlindex 0c4559446..777fefd66 100644--- a/docs/api-server/openapi/pipelex-api.openapi.yaml+++ b/docs/api-server/openapi/pipelex-api.openapi.yaml@@ -9397,11 +9397,11 @@ components:The error channel is built exclusively by- ``pipelex.pipeline.validation_errors.build_validation_error_items``, which both the agent+ ``pipelex.pipeline.validation_errors.build_validation_error_items``, which the agent- CLI (``extract_validation_errors``) and the API path+ CLI''s problem (``ValidateBundleError.problem_items``) and the API path- (``ValidateBundleError.validation_error_items``) call — so the CLI''s structured+ (``ValidateBundleError.validation_error_items``) both reach — so the CLI''s structuredoutput and the API''s invalid verdict can never drift. The samediff --git a/docs/contribute/hub-layering.md b/docs/contribute/hub-layering.mdindex b22eef3b7..bf252e789 100644--- a/docs/contribute/hub-layering.md+++ b/docs/contribute/hub-layering.md@@ -36,7 +36,7 @@ There is deliberately **no** `pipelex.hub`. It was deleted rather than kept as a| --- | --- || container | `RuntimeHub`, `get_runtime_hub`, `set_runtime_hub` || config | `get_required_config`, `get_optional_config` |-| console | `get_console` |+| console | `get_console`, `get_error_console` || secrets | `get_secrets_provider`, `get_secret` || system registries | `get_class_registry` || storage | `get_storage_provider` |diff --git a/docs/contribute/mthds-test-corpus.md b/docs/contribute/mthds-test-corpus.mdindex 244018a7e..f9b6c062a 100644--- a/docs/contribute/mthds-test-corpus.md+++ b/docs/contribute/mthds-test-corpus.md@@ -60,12 +60,14 @@ An entry directory is a method's folder whose bundles declare one `main_pipe` be7. **Run the gates**: `.venv/bin/pytest tests/unit/pipelex/test_extras tests/integration/pipelex/test_extras`.-An **invalid** entry additionally declares the exact wire `error_type` it must produce. Read that string off the runtime rather than inferring it from the source:+An **invalid** entry additionally declares the exact `error_type` its validation item must carry. Read that string off the runtime rather than inferring it from the source: declare any value, run the entries gate on the entry, and its failure names the `error_type` the bundle produced:```bash-.venv/bin/pipelex-agent validate bundle <path> -L <entry_dir>/ --format json --error-format json+.venv/bin/pytest tests/integration/pipelex/test_extras/test_mthds_corpus_entries.py -k <entry_name>```+The agent CLI no longer prints it: its invalid verdict is a problem, whose items carry the registry `code` of each fault rather than the validation item's `error_type`.+Two rules shape an invalid entry beyond that. Its **`covers` list is its `error.*` tag and nothing else** — it is tempting to also tag the pipe kind that carries the fault, but the exhaustivity gate reads `covers` as the claim that a tag has a focused entry, and a deliberately broken bundle must never be what satisfies that claim for a working feature. And the two ways it names its fault have to agree: `expected_error` carries the wire string, `covers` carries the normalized tag, and the exhaustivity gate requires the entry to cover the tag whose `code` is its `expected_error`, so an entry cannot advertise coverage it does not produce. The rule has a second half, gated alongside it: a **valid** entry may not carry an `error.*` tag at all, because its bundle produces no diagnostic and the claim would go unhonoured in exactly the same way.!!! warning "The `.mthds` editor hook fights invalid entries"diff --git a/docs/features/cli.md b/docs/features/cli.mdindex b21b5f447..73f65cc03 100644--- a/docs/features/cli.md+++ b/docs/features/cli.md@@ -45,19 +45,19 @@ Package manifest management is currently exposed through the lowercase `mthds` C## Agent CLI-The `pipelex-agent` CLI is a machine-first interface designed for automated environments like Claude Code skills. Output format varies by command — markdown or JSON, raw TOML, or `plxt` passthrough — with no interactive prompts or Rich formatting. Structured commands emit errors to stderr; the error format is controlled by `--error-format` and defaults to the value of `--format` (so `--format json` flips both). `fmt` and `lint` pass through native `plxt` output.+The `pipelex-agent` CLI is a machine-first interface designed for automated environments like Claude Code skills. Output format varies by command — markdown or JSON, raw TOML, or `plxt` passthrough — with no interactive prompts or Rich formatting. Structured commands report a failure on stderr as its problem, the error document the hosted API answers too, with its code, its domain, its retry verdict and its next step; the error format is the command's `--error-format`, else the program's own `--error-format`, else the value of `--format` (so `--format json` flips both). `fmt` and `lint` pass through native `plxt` output.| Command | Description ||---------|-------------|-| `init` | Non-interactive configuration setup; `"execution": "hosted"` in `--config` sets up hosted runs (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to `--format`'s value) |-| `run` | Execute a pipeline (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to `--format`'s value) |-| `validate` | Validate pipes, bundles, or methods (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to `--format`'s value) |-| `fix` | Apply deterministic safe fixes to a bundle in place and re-validate (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to `--format`'s value) |+| `init` | Non-interactive configuration setup; `"execution": "hosted"` in `--config` sets up hosted runs (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to the program's `--error-format`, then to `--format`'s value) |+| `run` | Execute a pipeline (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to the program's `--error-format`, then to `--format`'s value) |+| `validate` | Validate pipes, bundles, or methods (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to the program's `--error-format`, then to `--format`'s value) |+| `fix` | Apply deterministic safe fixes to a bundle in place and re-validate (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to the program's `--error-format`, then to `--format`'s value) || `fmt` | Format `.mthds`, `.toml`, or `.plx` files in-place || `lint` | Lint files for errors || `inputs` | Generate example input JSON for a pipe |-| `models` | List available model presets, aliases, and waterfalls (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to `--format`'s value) |-| `doctor` | Check configuration health (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to `--format`'s value) |+| `models` | List available model presets, aliases, and waterfalls (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to the program's `--error-format`, then to `--format`'s value) |+| `doctor` | Check configuration health (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to the program's `--error-format`, then to `--format`'s value) |For detailed CLI documentation, see the [CLI reference](../tools/cli/index.md).diff --git a/docs/migration-ledger.md b/docs/migration-ledger.mdindex d965f39f3..b203a3611 100644--- a/docs/migration-ledger.md+++ b/docs/migration-ledger.md@@ -505,7 +505,7 @@ Two rules govern how an entry appears, and both exist so that a report is neverThat is a mechanical rule rather than a list of credential-shaped key names, because such a list is a guess that eventually misses one. The single deliberate exception is the backup file, which contains the user's values by definition and is protected by inheriting the source file's mode rather than the process umask.-When migration is reported through a validation error, the error keeps `error_domain: "config"` and gains a structured `migration` block carrying the plan, the remedy and the diagnosis. Consumers branch on the presence of that block, never on wording: the structured fields are the contract, and Markdown, exit codes and HTTP statuses are presentation.+When migration is reported through a validation error, the error gains a structured `migration` block carrying the plan, the remedy and the diagnosis, which its problem carries as `diagnostics.migration`. Consumers branch on the presence of that block, never on wording: the structured fields are the contract, and Markdown, exit codes and HTTP statuses are presentation.## The commands@@ -542,7 +542,7 @@ load user files → deep-merge → validate (extra="forbid")→ re-merge → re-run the loader's own post-merge step → re-validateok → WARNING naming the file and, where the command reaches it, the `pipelex migrate` remedy → bootfails → unsafe entries, CONFLICT, or unexplained paths → validation error- with error_domain "config" and the `migration` block+ coded pipelex.config.invalid, with the `migration` block```The rules this encodes:@@ -580,7 +580,7 @@ A validation error cannot answer that by itself. It is raised against the mergedThe answer rides the error twice, and the two halves are not interchangeable:-- **`error_domain` stays `"config"`.** It does not become a domain of its own. `ErrorDomain` is a closed cross-repo enum and the agent-hook specification routes any domain it does not know to BLOCK, so a stale configuration reported under a new domain would stop an agent rather than tell it what to run.+- **The code stays `pipelex.config.invalid`.** A stale configuration is no code of its own: it is the same refusal, one only the operator can act on (`"domain": "operator"`), and the block rides its problem as `diagnostics.migration`, the operator's view, which is the view `pipelex` and `pipelex-agent` print, since whoever runs them runs the runtime. A caller of a hosted runtime is shown no block, having no configuration of that runtime to migrate.- **The structured `migration` block is the contract, and consumers branch on its presence.** Absent means the failure is not staleness. Present, it carries `remedy` (the command), `would_write` (whether that command would rewrite any of these files), `needs_attention` (whether anything here is a person's rather than the tool's), and `plans` — the same `MigrationPlan` shape `pipelex-agent migrate --dry-run --format json` emits under its own `plans` key, so an agent that parses one has already parsed the other. Only the files the scan found something in are listed: unlike the commands' report, which answers *what did the walk visit*, the block answers *what is wrong with this machine*.- **The message is presentation.** It carries the refusal — the pydantic analysis where the surface's own model refused, or, for the two libraries the boot reports on, the loader's own sentence, kept whole because it names *which model, which backend, which file* before quoting that analysis, and a directory holds a dozen files with the same field names — followed by a paragraph naming the files, what the command would carry forward, and what it cannot do for anyone. Nothing branches on its wording.@@ -598,9 +598,9 @@ A configuration error reaches a user through several surfaces at once — the huSo no surface holds its own answer any more:-- Every configuration surface's refusal goes through `report_validation_error`, so the `migration` block reaches the error wherever it is caught. Most surfaces do it in the loader; the inference backend definitions do it one frame out, in the boot that catches the library's own error, because that library refuses after the main configuration is already up and the boot has a message of its own to build. `TelemetryConfigError` is a `PipelexConfigError` for this reason — it carries `error_domain = CONFIG` from the class rather than from the agent CLI's lookup table, and it can carry a block.+- Every configuration surface's refusal goes through `report_validation_error`, so the `migration` block reaches the error wherever it is caught. Most surfaces do it in the loader; the inference backend definitions do it one frame out, in the boot that catches the library's own error, because that library refuses after the main configuration is already up and the boot has a message of its own to build. `TelemetryConfigError` is a `PipelexConfigError` for this reason — it carries the code `pipelex.config.invalid` from the class, and it can carry a block.- The **human handler** prints the fields the model refused and then names `pipelex migrate` when the block says it would write, the dry run when it says it would not, and an edit when there is no block at all.-- The **agent envelope** carries `migration` as a field and its hint says which of the three readings applies — no block, a block that would write, a block that would not; an agent branches on the fields, never on the sentence.+- The **agent CLI's problem** carries the block as `diagnostics.migration`, and its readings — no block, a block that would write, a block that would not — are its absence, `would_write: true` and `would_write: false`; an agent branches on those fields, never on the sentence.- The **`doctor` row** carries a *finding* — `healthy`, `not_found`, `unparseable`, `out_of_date`, `invalid` — and every caller reads that instead of the row's wording. This one is a correctness fix and not only a tidy-up: `--fix` used to decide what it could repair by searching the message for `"format has changed"`, so rewording the row would have switched the whole repair path off in silence. The finding answers for the one file the row is about: the scan behind `out_of_date` runs over the directory that file lives in — which also holds the `telemetry_*.toml` tier — and the verdict is read off that file's own plan, so a stale tier file beside a wrong base file leaves the base file `invalid`, and the fields the model refused stay on the row. **`out_of_date` means the plan would rewrite that file**, not merely that it is unclean: a file the migration would leave untouched is `invalid`, which is the finding that routes to a person and which `--fix` does not offer to run a command over, and the row keeps the dry run's pointer so the diagnosis is not lost with the finding.> **Writing a fresh file repairs exactly one finding: a missing one.** There is nothing in a file that is not there to lose. Every other unhealthy state has the user's own settings in it, so an out-of-date file is offered `pipelex migrate` and a broken one is left to a person. Regeneration is still reachable, and it is described as what it is — a way to start over that discards the file.diff --git a/docs/setup/usage-statistics.md b/docs/setup/usage-statistics.mdindex 929b875b8..8d4687ee2 100644--- a/docs/setup/usage-statistics.md+++ b/docs/setup/usage-statistics.md@@ -8,7 +8,7 @@ Pipelex collects **anonymous usage statistics**: counts of commands, runs, pipeThey are on by default, and you can turn them off at any time, for one command, one project or the whole machine, as [Turning them off](#turning-them-off) explains.-The first time a Pipelex tool runs with statistics on, it prints this notice on stderr, once per machine. A command whose stderr a program reads rather than a person, `pipelex-agent` with JSON errors (`--error-format json`, or `--format json` with no `--error-format`), neither prints nor records it, and still sends its statistics; the next command whose stderr a person reads prints it:+The first time a Pipelex tool runs with statistics on, it prints this notice on stderr, once per machine. A command whose stderr a program reads rather than a person, `pipelex-agent` with JSON errors (the command's `--error-format json`, the program's `--error-format json` given before the command, or `--format json` with no `--error-format`), neither prints nor records it, and still sends its statistics; the next command whose stderr a person reads prints it:> Pipelex collects anonymous usage statistics: counts of commands, runs, pipe types, models and tokens, and the country your IP address maps to; the address itself is never stored. It never collects your methods, prompts, inputs, outputs, file names or pipe names. To turn it off, run `pipelex usage-stats disable` or set DO_NOT_TRACK=1. Details: https://docs.pipelex.com/latest/setup/usage-statistics/@@ -24,17 +24,20 @@ Every event is a count, a yes-or-no, or a value from a closed list. No property- the tool and its version (`pipelex`, and the release), and the surface it ran from: the `pipelex` CLI, the `pipelex-agent` CLI, the API server or a Python program;- the operating system and processor family, the Python minor version, and whether the process ran in CI or in a container;- an anonymous **installation identifier**, a random UUID drawn once per machine and shared by every Pipelex tool on it, never derived from anything about the machine or you.+- the version of the event contract it follows, `schema`, which is 2 from the release whose events name a failure by its error's code and that code's domain, so that a receiver tells them from an earlier release's events.The events themselves are:| Event | Sent | What it counts || --- | --- | --- |-| `command_completed` | once per command of the `pipelex` and `pipelex-agent` CLIs | the command's path in the command tree (`run bundle`, `validate pipe`, `init` and so on, a shorthand such as `pipelex validate my_pipe` counting as the command it runs; never its arguments or option values), its outcome, its duration, who could fix a failure (`input`, `config`, `runtime` or `other`), and whether it ran on the hosted API; for `init`, also where it set runs to execute and, when it set up backends on this machine, which backend kinds it enabled |-| `run_completed` | once per run, whatever started it | the outcome, live or dry, the kind of source the method came from (a local bundle, an installed method, a published address), the duration, the bundle's size and nesting depth, which language features it used (batching, parallel branches, conditions, structured outputs, image and document inputs), how many pipes of each type ran, and its inference totals: calls, failures, tokens, images, pages and cost |-| `model_used` | once per model a run used | the backend kind (`openai`, `anthropic`, `mistral`, and so on, `custom` for a backend Pipelex does not ship), the model's name in the backend tables Pipelex ships (`other` for any other), and that run's calls, failures by category, tokens, images, pages and cost for it |+| `command_completed` | once per command of the `pipelex` and `pipelex-agent` CLIs | the command's path in the command tree (`run bundle`, `validate pipe`, `init` and so on, a shorthand such as `pipelex validate my_pipe` counting as the command it runs; never its arguments or option values), its outcome, its duration, for a failure the code of its error from the [error registry](../under-the-hood/error-model.md) (`client.argument_invalid`, `method.invalid` and so on) and that code's domain, who must act on it (`input`, `method`, `account`, `operator` or `runtime`), and whether it ran on the hosted API; for `init`, also where it set runs to execute and, when it set up backends on this machine, which backend kinds it enabled |+| `run_completed` | once per run, whatever started it | the outcome, for a failed run the code of its error and that code's domain, live or dry, the kind of source the method came from (a local bundle, an installed method, a published address), the duration, the bundle's size and nesting depth, which language features it used (batching, parallel branches, conditions, structured outputs, image and document inputs), how many pipes of each type ran, and its inference totals: calls, failures, tokens, images, pages and cost |+| `model_used` | once per model a run used | the backend kind (`openai`, `anthropic`, `mistral`, and so on, `custom` for a backend Pipelex does not ship), the model's name in the backend tables Pipelex ships (`other` for any other), and that run's calls, its failed calls by the domain of their error's code, tokens, images, pages and cost for it || `method_validated` | once per validation of a method | the verdict, the duration, the number of errors and warnings, and the bundle's size and depth || `code_generated` | once per code generation | what was generated (types, input templates or structure classes), the target language, the outcome, the duration and the bundle's size |+A refusal a server answered, the hosted API's among them, is counted by the code and the domain its answer sent, never by what Pipelex reads from its HTTP status: a command's event then carries none, and a run's, which must name one, the catch-all `runtime.unexpected`.+A run's token totals come from the run's own usage events: when you turn tracing or cost reporting off, the run reports that its usage is unknown and no `model_used` is sent. The statistics never turn tracing on.### What is never collecteddiff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.mdindex d5516c2ca..3bf5e8c11 100644--- a/docs/tools/cli/agent-cli.md+++ b/docs/tools/cli/agent-cli.md@@ -4,7 +4,7 @@ description: "Use the pipelex-agent CLI for machine-oriented output — designed# Agent CLI (`pipelex-agent`)-The `pipelex-agent` CLI is a machine-oriented companion to the main `pipelex` CLI. It is designed for programmatic consumption by AI agents, IDE extensions, and other automation tools. Output format varies by command — markdown or JSON, raw TOML, or `plxt` passthrough — with no Rich formatting or interactive prompts. Structured commands emit errors to stderr; the error format is controlled by `--error-format`, which defaults to the value of `--format` (so `--format json` flips both, as before the split). `fmt` and `lint` pass through native `plxt` output.+The `pipelex-agent` CLI is a machine-oriented companion to the main `pipelex` CLI. It is designed for programmatic consumption by AI agents, IDE extensions, and other automation tools. Output format varies by command — markdown or JSON, raw TOML, or `plxt` passthrough — with no Rich formatting or interactive prompts. Structured commands report a failure on stderr as its problem, the error document of the [MTHDS standard](https://mthds.ai) that the hosted API answers too, in Markdown or in JSON (see [Output Contract](#output-contract)). The error format is the command's `--error-format`, else the program's own `--error-format` given before the command (`pipelex-agent --error-format json validate bundle …`), else the command's `--format` (so `--format json` flips both, as before the split), else JSON. `fmt` and `lint` pass through native `plxt` output.It is consumed by the `mthds-agent` CLI (from the `mthds` npm package) which itself is used by Claude Code skills, the VS Code extension, and can be called directly from the command line.@@ -27,7 +27,7 @@ The agent CLI mirrors the main CLI's subcommand structure for `run`, `validate`,### Run-Execute a pipeline. Success output is markdown by default, or JSON with `--format json`. Errors follow `--error-format` (defaults to `--format`'s value).+Execute a pipeline. Success output is markdown by default, or JSON with `--format json`. Errors follow `--error-format` (defaults to the program's `--error-format`, then to `--format`'s value).```bashpipelex-agent run pipe <PIPE_CODE> [OPTIONS]@@ -44,14 +44,14 @@ pipelex-agent run method <NAME> [OPTIONS]- `--library-dir`, `-L` - Additional library directory- `--with-memory` - Include full working memory in output, each stuff naming its concept by ref (`"concept": "<domain>.<Code>"`); piped back into another `run` on stdin, the envelope's stuffs become that run's inputs, provided the receiving method declares the same `<domain>.<Code>` — the ref carries its domain, and a method declaring another one refuses it rather than guessing- `--format` - Success output format: `markdown` (default) or `json`-- `--error-format` - Error output format: `markdown` or `json` (defaults to `--format`'s value)+- `--error-format` - Error output format: `markdown` or `json` (defaults to the program's `--error-format`, then to `--format`'s value)- `--runner local|hosted` - Where the run executes: on this machine, or on the hosted Pipelex API. Defaults to `[run] execution` in `.pipelex/pipelex.toml` (see [Run Configuration](../../configuration/config-practical/run-config.md)), else `local`- `--hosted` / `--local` - The same choice as `--runner`, spelled as the main CLI spells it. Given together, they must agree- `--base-url <scheme://host[:port]>` - The origin a hosted run calls. Overrides `PIPELEX_BASE_URL`, which overrides `https://api.pipelex.com`; refused on a run that executes locallyFor `bundle` and `method`, use `--pipe` to target a specific pipe.-`run bundle` reads its method through its [method tree](../../building-methods/method-trees.md), as `pipelex run bundle` does. A folder is the method rooted at the nearest `METHODS.toml` at or above it, else at the folder itself, and with no `--pipe` the run starts at the manifest's `main_pipe`, or, with no manifest, at the one `main_pipe` its bundles declare; none or several is refused as a `MethodEntryError` naming each bundle by its path in the tree, with the `error_code` `request.pipe_unspecified`, naming the declared ones as its `candidates` when there are several, and no `validation_errors`, since the method may be valid and only the pipe to start at is missing: pass `--pipe`. A bundle file named alone starts at its own `main_pipe`, and with no `METHODS.toml` at or above its folder its method is that one file, so a step naming a file beside it, such as a `template_file`, is refused with the advice to run the folder or to add a `METHODS.toml`. The run's output file (`live_run.json` or `dry_run.json`, in the run's output folder) carries `method_tree_digest`, the digest of the tree the run read, and so does the output under `--with-memory`.+`run bundle` reads its method through its [method tree](../../building-methods/method-trees.md), as `pipelex run bundle` does. A folder is the method rooted at the nearest `METHODS.toml` at or above it, else at the folder itself, and with no `--pipe` the run starts at the manifest's `main_pipe`, or, with no manifest, at the one `main_pipe` its bundles declare; none or several is refused with the problem `request.pipe_unspecified`, whose message names each bundle by its path in the tree and whose `params.candidates` names the declared ones when there are several, with no `errors`, since the method may be valid and only the pipe to start at is missing: pass `--pipe`. A bundle file named alone starts at its own `main_pipe`, and with no `METHODS.toml` at or above its folder its method is that one file, so a step naming a file beside it, such as a `template_file`, is refused with the advice to run the folder or to add a `METHODS.toml`. The run's output file (`live_run.json` or `dry_run.json`, in the run's output folder) carries `method_tree_digest`, the digest of the tree the run read, and so does the output under `--with-memory`.#### Running on the hosted API@@ -59,14 +59,14 @@ With `--runner hosted` (or `--hosted`, or `[run] execution = "hosted"`), the runThe 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 an error envelope whose `error_type` is `ValidateBundleError` and whose `validation_errors` array holds the items `validate` gives for that bundle, each with 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 `source`; a bundle file run on its own is loaded from its text, so the items of a refusal found while loading it carry no `source`, 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 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.!!! 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, under `"error_type": "AutoDetectedInputsFileError"`; 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 under `"error_type": "StdinEnvelopeShapeError"`, which is the label for an envelope that parsed as JSON but does not hold the shape the contract asks for, as distinct from the `JSONDecodeError` that means the JSON itself did not parse.+ 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.### Validate-Validate pipes, bundles, or methods. Success output is markdown by default, or JSON with `--format json`. Errors follow `--error-format` (defaults to `--format`'s value).+Validate pipes, bundles, or methods. Success output is markdown by default, or JSON with `--format json`. Errors follow `--error-format` (defaults to the program's `--error-format`, then to `--format`'s value).```bashpipelex-agent validate pipe <PIPE_CODE> [OPTIONS]@@ -80,7 +80,7 @@ pipelex-agent validate method <NAME> [OPTIONS]- `--library-dir`, `-L` - Additional library directory- `--allow-signatures` - Accept [`PipeSignature`](../../building-methods/pipes/signature-pipes.md) placeholders in the dependency graph (lenient mode)- `--format` - Success output format: `markdown` (default) or `json`-- `--error-format` - Error output format: `markdown` or `json` (defaults to `--format`'s value)+- `--error-format` - Error output format: `markdown` or `json` (defaults to the program's `--error-format`, then to `--format`'s value)For `bundle`, additional options are available:@@ -89,7 +89,7 @@ For `bundle`, additional options are available:- `--graph-format`, `-f` - Graph output format (`mermaidflow`, `reactflow`, or `both`)- `--direction` - Graph layout direction-`validate bundle <folder>` reads the folder as its [method tree](../../building-methods/method-trees.md), the method rooted at the nearest `METHODS.toml` at or above it, else at the folder itself, and judges the whole tree, as the MTHDS protocol's validation judges a method: every bundle of it is loaded and every pipe of it dry-run. It needs no pipe to start at, so a folder whose bundles declare several `main_pipe`s, or none, is validated like any other, and `bundle_path` in the envelope names the folder. Only the tree's own pipes are judged: the `-L` directories, a nested package below the folder with its own `METHODS.toml`, and the packages the method depends on all load for its bundles to use, but their own pipes are not judged. A graph, which is drawn from one pipe, is drawn from the pipe named by `--pipe`, else from the pipe a run of the folder starts at, the manifest's `main_pipe` or, with no manifest, the one `main_pipe` its bundles declare; when the folder decides no such pipe, `--graph` and `--view` draw nothing and the envelope carries `graph_unavailable`, a sentence saying why, while the validation stands and exits on its own verdict. A folder holding no `.mthds` bundle produces no verdict: `error_type: EmptyMethodTreeError`, exit code `2`.+`validate bundle <folder>` reads the folder as its [method tree](../../building-methods/method-trees.md), the method rooted at the nearest `METHODS.toml` at or above it, else at the folder itself, and judges the whole tree, as the MTHDS protocol's validation judges a method: every bundle of it is loaded and every pipe of it dry-run. It needs no pipe to start at, so a folder whose bundles declare several `main_pipe`s, or none, is validated like any other, and `bundle_path` in the envelope names the folder. Only the tree's own pipes are judged: the `-L` directories, a nested package below the folder with its own `METHODS.toml`, and the packages the method depends on all load for its bundles to use, but their own pipes are not judged. A graph, which is drawn from one pipe, is drawn from the pipe named by `--pipe`, else from the pipe a run of the folder starts at, the manifest's `main_pipe` or, with no manifest, the one `main_pipe` its bundles declare; when the folder decides no such pipe, `--graph` and `--view` draw nothing and the envelope carries `graph_unavailable`, a sentence saying why, while the validation stands and exits on its own verdict. A folder holding no `.mthds` bundle produces no verdict: the problem `method.invalid`, its `diagnostics.error_class` being `EmptyMethodTreeError`, with exit code `2`.!!! note "Signature pipes"`pipelex-agent validate` is strict by default — same as `pipelex validate`. A bundle whose dependency graph reaches a `PipeSignature` is rejected unless you pass `--allow-signatures`, which dry-runs signatures as mocks.@@ -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 envelope — `is_valid: false` and a `validation_errors` array — and exit code `1`, never the no-verdict envelope and exit code `2`, which is kept for failures of the tool or its environment. A pipe whose dry run fails gives one `dry_run` item per failing pipe, with `error_type: DryRunError`, the `pipe_code`, `domain_code` and `source` of the innermost pipe that failed and is not allowed to fail (its `source` whenever the pipe is in your files; a validator of submitted content beside a host's library directories names only that content's files), and a message naming the pipe and giving 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 without an `error_type`, carrying its `pipe_code`, `source` and `field_path`. A TOML syntax error's item carries its 1-based `line` and `column`, and an `unresolved_concept` item lists the concepts the validated bundle declares in its domain in `declared_concepts`. A pipe naming a model the model deck does not define gives one `pipe_validation` item with `error_type: unknown_model`, carrying `pipe_code`, `domain_code`, `source`, `field_path` (`pipe.<code>.model`), `model_reference` (the reference as written), `model_type` and `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 without an `error_type`, 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. See [Error Model](../../under-the-hood/error-model.md#validation_errors-structured-bundle-validation-diagnostics).+ 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).!!! 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.@@ -118,9 +118,9 @@ pipelex-agent fix bundle <PATH> [OPTIONS]- `--select` - Apply only the named fix rule; repeat for multiple rules- `--ignore` - Skip the named fix rule; repeat for multiple rules (`--select` and `--ignore` are mutually exclusive)- `--format` - Success output format: `markdown` (default) or `json`-- `--error-format` - Error output format: `markdown` or `json` (defaults to `--format`'s value)+- `--error-format` - Error output format: `markdown` or `json` (defaults to the program's `--error-format`, then to `--format`'s value)-The result reports `iterations`, `fixes_applied`, `files_written`, and any `remaining_errors`. A fully valid result exits 0; a completed fix attempt that remains invalid exits 1; argument, setup, or unexpected failures exit 2, and so does a folder holding no `.mthds` bundle. A folder is fixed whole, as `validate bundle` judges it: every file of its method tree, from the tree's root down, is inside the write scope, a fix lands in the file its error names, and a folder whose bundles declare several `main_pipe`s, or none, is fixed like any other. A folder whose tree cannot be read, such as one past this machine's limits, leaves as the still-invalid verdict, `error_type: FixBundleError` with exit code `1`, its `remaining_errors` carrying the refusal. A configuration that does not validate, which these commands read before the boot for the tree's limits, is reported as the failed boot it would have been, under the configuration error's own `error_type` with the boot's hint.+The result reports `iterations`, `fixes_applied`, `files_written`, and any `remaining_errors`. A fully valid result exits 0; a completed fix attempt that remains invalid exits 1 with the problem `method.invalid` on stderr, its `errors` the faults left, each with the code `validate bundle` gives it, and beside them `is_valid`, `bundle_path`, `iterations`, `fixes_applied`, `files_written` and any `bail_reason`; argument, setup, or unexpected failures exit 2, and so does a folder holding no `.mthds` bundle. A fix the command cannot write, its round rolled back, is `client.write_failed`, whose `params.path` names the file, or the directory a copy staged beside it could not be written in, and `params.reason` the system's reason, never `client.file_unreadable`, which is a method file it cannot read. A folder is fixed whole, as `validate bundle` judges it: every file of its method tree, from the tree's root down, is inside the write scope, a fix lands in the file its error names, and a folder whose bundles declare several `main_pipe`s, or none, is fixed like any other. A folder whose tree cannot be read, such as one past this machine's limits, leaves as the still-invalid problem `method.invalid` with exit code `1`, its `errors` carrying the refusal. A configuration that does not validate, which these commands read before the boot for the tree's limits, is reported as the failed boot it would have been, under the configuration error's own code, with the boot's recovery tip in Markdown.Rewrite a method's flat `PipeFunc` function names as import paths from its folder, the migration of the retired function registry (see [PipeFunc](../../building-methods/pipes/pipe-operators/PipeFunc.md#migrating-flat-function-names)):@@ -145,8 +145,9 @@ pipelex-agent inputs method <NAME> [OPTIONS]- `--library-dir`, `-L` - Additional library directory- `--format` - Template serialization: `json` (default) or `toml`- `--explicit` - Emit the ceremonial `{concept, content}` envelope form instead of the light values+- `--error-format` - Error output format: `markdown` or `json` (defaults to the program's `--error-format`, then to `json`; never to `--format`, which here selects the template's serialization)-For `bundle` and `method`, use `--pipe` to target a specific pipe. With no `--pipe`, a method's folder generates the template of the pipe a run of the folder starts at, as `run bundle` selects it; a folder whose bundles declare no `main_pipe`, or several, is refused under `error_type: MethodEntryError` with exit code `1`, and a folder holding no bundle is refused the same way. With `--pipe`, the folder loads as the method's library and the pipe is looked up there, as `run bundle <folder> --pipe` runs it.+For `bundle` and `method`, use `--pipe` to target a specific pipe. With no `--pipe`, a method's folder generates the template of the pipe a run of the folder starts at, as `run bundle` selects it; a folder whose bundles declare no `main_pipe`, or several, is refused with the problem `request.pipe_unspecified` and exit code `1`, its `diagnostics.error_class` being `MethodEntryError`, and a folder holding no bundle with the problem `method.invalid`, exit code `1` too. With `--pipe`, the folder loads as the method's library and the pipe is looked up there, as `run bundle <folder> --pipe` runs it.The JSON success envelope names the pipe the template was generated for as `pipe_ref`, the qualified `domain.pipe_code` of the pipe that was resolved, whether you named it with a bare code, a qualified ref, or let it default to the bundle's `main_pipe`. A pipe you reached through a dependency alias keeps that alias, `alias->domain.pipe_code`, since that is the ref that selects it again:@@ -161,7 +162,7 @@ The JSON success envelope names the pipe the template was generated for as `pipeA pipe that declares no inputs is not an error: the envelope carries `"inputs": {}` and the command exits `0`; under `--format toml` it prints the comment `# Pipe 'my_domain.main_pipe' declares no inputs.`!!! note "`inputs --format` is `json|toml`, not `markdown|json`"- Unlike `run`/`validate`, the `inputs` command's `--format` selects the **template serialization**, not a presentation style. `json` (the default) emits the structured JSON success envelope; `toml` prints the raw TOML template straight to stdout (a pipe with no inputs prints a TOML comment line, which loads back as an empty dict). `inputs` has no `--error-format` — its errors stay JSON.+ Unlike `run`/`validate`, the `inputs` command's `--format` selects the **template serialization**, not a presentation style. `json` (the default) emits the structured JSON success envelope; `toml` prints the raw TOML template straight to stdout (a pipe with no inputs prints a TOML comment line, which loads back as an empty dict). Its errors follow its own `--error-format`, else the program's, else JSON, never its `--format`.!!! note "`--explicit` and concept hints"The light `--format toml` template carries the declared concept for each key as a `# concept: ...` comment; the light `--format json` template (the default) cannot (JSON has no comments), so pass `--explicit` when you want the concept written out inline. The JSON success envelope shape (`success` / `pipe_ref` / `inputs`) is unchanged — only the `inputs` payload flips between the light values and the envelope form.@@ -172,12 +173,12 @@ These commands do not have subcommands:| Command | Description ||---------|-------------|-| `init` | Initialize configuration non-interactively from `--config`: `execution` (`hosted` or `local`), `backends`, `primary_backend`; see [Non-Interactive Init](init.md#non-interactive-init-pipelex-agent-init) (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to `--format`'s value) |+| `init` | Initialize configuration non-interactively from `--config`: `execution` (`hosted` or `local`), `backends`, `primary_backend`; see [Non-Interactive Init](init.md#non-interactive-init-pipelex-agent-init) (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to the program's `--error-format`, then to `--format`'s value) || `fmt` | Format a `.mthds`/`.toml`/`.plx` file in-place (delegates to `plxt`) || `lint` | Lint a `.mthds`/`.toml`/`.plx` file for errors (delegates to `plxt`) |-| `models` | List available model presets, aliases, and waterfalls (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to `--format`'s value) |-| `check-model` | Check a model reference for a model category (`check-model <reference> --type <category>`, the category being `llm`, `extract`, `img_gen`, `search`, `judgment` or `doc_gen`) and suggest alternatives when it is not valid. It applies the rule a validation applies, as [`GET /v1/models/check`](../../api-server/models.md#check-a-model-reference) does: a sigiled reference names that kind of binding, and a bare name is valid when it is a model of the category, an alias of the category, or a waterfall of the category while model fallback is on; a `handle:` reference writes a bare name without reading a sigil, so `handle:@best-gpt` is the bare name `@best-gpt`, not the alias `best-gpt`. `--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to `--format`'s value |-| `doctor` | Check config, credentials, and model health; a hosted setup (`[run] execution = "hosted"`) is judged by its Pipelex API key, reported in `checks.pipelex_api_key`, with `execution` at the top level and the provider credentials and models rows marked `informational` (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to `--format`'s value) |+| `models` | List available model presets, aliases, and waterfalls (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to the program's `--error-format`, then to `--format`'s value) |+| `check-model` | Check a model reference for a model category (`check-model <reference> --type <category>`, the category being `llm`, `extract`, `img_gen`, `search`, `judgment` or `doc_gen`) and suggest alternatives when it is not valid. It applies the rule a validation applies, as [`GET /v1/models/check`](../../api-server/models.md#check-a-model-reference) does: a sigiled reference names that kind of binding, and a bare name is valid when it is a model of the category, an alias of the category, or a waterfall of the category while model fallback is on; a `handle:` reference writes a bare name without reading a sigil, so `handle:@best-gpt` is the bare name `@best-gpt`, not the alias `best-gpt`. `--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to the program's `--error-format`, then to `--format`'s value |+| `doctor` | Check config, credentials, and model health; a hosted setup (`[run] execution = "hosted"`) is judged by its Pipelex API key, reported in `checks.pipelex_api_key`, with `execution` at the top level and the provider credentials and models rows marked `informational` (`--format markdown\|json` success, default: markdown; `--error-format` for errors, defaults to the program's `--error-format`, then to `--format`'s value) |## Output Contract@@ -199,35 +200,47 @@ 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:+**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:```json{- "error": true,- "error_type": "specific_error_type",- "message": "Human-readable description",- "error_domain": "input",- "error_code": "method.invalid",- "hint": "Suggested fix or next step",- "retryable": false+ "type": "https://mthds.ai/errors/client.file_unreadable",+ "title": "A local file cannot be read",+ "detail": "The local file '/path/to/bundle.mthds' cannot be read (reason: not found).",+ "code": "client.file_unreadable",+ "domain": "input",+ "retry": "no",+ "next_step": {+ "kind": "change_input",+ "detail": "Check that '/path/to/bundle.mthds' exists and is readable, then try again."+ },+ "params": {"path": "/path/to/bundle.mthds", "reason": "not found"},+ "diagnostics": {"error_class": "FileNotFoundError", "message": "[Errno 2] No such file or directory: '/path/to/bundle.mthds'", "runtime_version": "0.87.0"},+ "message": "Bundle file not found: /path/to/bundle.mthds"}```-For the structured commands, exactly one such object is written to stderr per failure, so the stream parses as a single JSON document.+For the structured commands, exactly one problem is written to stderr per failure, so the stream parses as a single JSON document.-`error_code` is the registry code of the error behind the failure, as its problem carries it, the stable name of its case (the [error codes](../../errors/index.md) page lists them), and it decides `error_domain` and `retryable`: branch on it rather than on `error_type`, which names a Pipelex class and can change between releases. An envelope whose cause is not a Pipelex error, a missing file or malformed JSON read by the command itself, carries no `error_code`, and its domain and hint come from the command's own table. On a Pipelex error the `hint` is the advice nearest the failure along its cause chain, else the command's own advice for its class, else the next step its code gives whoever runs the runtime, so an envelope with an `error_code` always carries a `hint`.+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`.-**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.+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.-**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 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 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 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 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. A configuration that cannot be read while deciding where the run executes gives the hint a failed local boot gives, and any other failure still leaves as this envelope, with the exception's class as `error_type`.+**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.-**`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.+**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.-`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.+**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.-**`FormerReleaseConfigError`** — a boot on a configuration set up by a release that ran on the Pipelex Gateway, with its backend enabled or one of its routing profiles active, is refused with this error, which names what stops it with its file and carries no `migration` object: what is there is no stale shape but what that release left. The loop is the same, `pipelex-agent migrate --dry-run --format json`, whose `former_release` key lists each file the cleanup rewrites or removes and its changes, show the user, then `--yes`. On every run, `former_release.still_blocking` lists, one sentence each, whatever would still stop the boot once the cleanup is done: after `--yes`, read off the files written, and in a dry run, off the files as they would be written, so the plan already says when the cleanup alone will not be enough. When it is not empty, `needs_attention` is true and `is_clean` false, even with no file left to clean, and the machine is not fixed yet.+**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.++A telemetry configuration that does not load (`diagnostics.error_class` `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.++A configuration that does not validate names, in the next step's sentence, the setting at fault, its file and the configuration it belongs to (`params.setting`, `params.file` and `params.surface`, which only the operator's view carries): `Correct the setting 'runtime.log.level' in the file 'pipelex.toml' of the pipelex configuration, then restart the runtime.` A refusal of the merged layers names the configuration's file, `pipelex.toml` or `telemetry.toml`, since the setting can come from any of them, and a refusal that knows the one file at fault names that file: a file that does not parse, with its line and column, or a file a former release left. Such a file is named relative to the working directory when it is under it, else as `~/…` when it is under the home directory, so a step never names the home directory's account. The Markdown tip reads the migration: with `would_write: true`, the migrate loop above; with `would_write: false`, correct by hand what the plans name; with none, the code: a missing file (`pipelex.config.file_missing`) is restored or written by `pipelex-agent init`, a variable that is not set (`pipelex.config.variable_missing`) is set where the configuration reads it, and a configuration that does not validate or parse is what `pipelex-agent doctor` finds.++**A configuration a former release left** — a boot on a configuration set up by a release that ran on the Pipelex Gateway, with its backend enabled or one of its routing profiles active, is refused with `pipelex.config.invalid` (`diagnostics.error_class` `FormerReleaseConfigError`), whose message names what stops it with its file, and whose `diagnostics.migration` says what `pipelex migrate` would do about it, read off the cleanup's own dry run: `would_write` whether it would rewrite or remove a file, `needs_attention` whether something is left for a person, a file it would leave for a hand edit, a boot it would still not start or a file outside the directories it walks, and `plans` empty, since the cleanup's files are the command's `former_release` key. A JSON reader branches on it as on any pending migration. The Markdown tip gives the loop, the same one: `pipelex-agent migrate --dry-run --format json`, whose `former_release` key lists each file the cleanup rewrites or removes and its changes, show the user, then `--yes`. On every run, `former_release.still_blocking` lists, one sentence each, whatever would still stop the boot once the cleanup is done: after `--yes`, read off the files written, and in a dry run, off the files as they would be written, so the plan already says when the cleanup alone will not be enough. When it is not empty, `needs_attention` is true and `is_clean` false, even with no file left to clean, and the machine is not fixed yet.**A failure is not the only way to learn this, and for an agent it is not even the reliable one.** A configuration the migration history explains boots with a warning rather than an error — and `pipelex-agent` silences logging process-wide before anything can emit one, so no error arrives and the machine is still stale. `pipelex-agent doctor` is the channel that always answers: its `checks.pending_migrations` row carries a `finding` (`up_to_date`, `pending`, `needs_attention`, `unavailable`), the `migratable_files` a migration would rewrite, the `attention_files` it will not repair on its own, and the `former_release_files` its first step cleans up, with `former_release_blocks_boot` saying whether they stop this machine's boot, read off the files the boot merges in the current directory rather than off each directory alone. When the cleanup's own check finds that a boot would still not start once it has run, the row says so in its `message` and `recommended_actions` names `pipelex migrate --dry-run`, which says why; with nothing left to clean its `finding` is `needs_attention`, and that action is the row's only one. Branch on `finding`; `unavailable` means the check could not run and is not a claim that the machine is current. The row answers for both configuration directories even under `--global`, because it describes `pipelex migrate`, which has no such flag.@@ -235,7 +248,7 @@ For the structured commands, exactly one such object is written to stderr per fa## Usage Statistics-`pipelex-agent` sends Pipelex's [anonymous usage statistics](../../setup/usage-statistics.md) as `pipelex` does: one `command_completed` per command, plus the events of the runs, validations and code generations it performs, all off under `DO_NOT_TRACK=1`, `PIPELEX_USAGE_STATS=0` or `pipelex usage-stats disable`. When the invocation's errors are JSON, with `--error-format json` or with `--format json` and no `--error-format`, stderr is a machine contract, so the one-time notice is neither printed nor recorded there; the next command whose stderr a person reads prints it. The `plxt` that `fmt` and `lint` start reports nothing of its own. There is no `usage-stats` group on this CLI: [`pipelex usage-stats`](usage-stats.md) shows and changes the statistics for both.+`pipelex-agent` sends Pipelex's [anonymous usage statistics](../../setup/usage-statistics.md) as `pipelex` does: one `command_completed` per command, plus the events of the runs, validations and code generations it performs, all off under `DO_NOT_TRACK=1`, `PIPELEX_USAGE_STATS=0` or `pipelex usage-stats disable`. When the invocation's errors are JSON, with the command's `--error-format json`, the program's `--error-format json` given before the command, or `--format json` and no `--error-format` at all, stderr is a machine contract, so the one-time notice is neither printed nor recorded there; the next command whose stderr a person reads prints it. A command's `command_completed` names its failure's code and domain as its problem gives them, and a failed hosted run's names what the hosted API sent: the problem document's `code` and `domain` when it sent both, else nothing, never a domain the client inferred from the status. The `plxt` that `fmt` and `lint` start reports nothing of its own. There is no `usage-stats` group on this CLI: [`pipelex usage-stats`](usage-stats.md) shows and changes the statistics for both.## Graph Visualizationdiff --git a/docs/tools/cli/index.md b/docs/tools/cli/index.mdindex 184c34a3b..6085059ae 100644--- a/docs/tools/cli/index.md+++ b/docs/tools/cli/index.md@@ -40,7 +40,7 @@ The Pipelex CLI is organized into several command groups:These flags work on any `pipelex` command and are position-agnostic — place them anywhere in the invocation:-- `--traceback` - print the full Rich-rendered stack trace before the friendly one-line error. Off by default. Both `pipelex run --traceback pipe ...` and `pipelex run pipe ... --traceback` work.+- `--traceback` - print the full Rich-rendered stack trace before the error panel, both on stderr, and let the log line about an unexpected failure carry its traceback. Off by default, since a traceback prints the text of every exception along the chain, which can quote a run's data; without it the log line names the failure by its code, the classes along its chain and the frames it went through, by module, line and function. Both `pipelex run --traceback pipe ...` and `pipelex run pipe ... --traceback` work.- `--no-logo` - suppress the startup logo banner. Handy for clean logs and to save tokens in agent output.`--version` / `-V` is **not** one of these: it is an option on the root command, so it goes before any subcommand (`pipelex --version`, never `pipelex show --version`). See below.diff --git a/docs/tools/cli/run.md b/docs/tools/cli/run.mdindex f28cf54a0..9bc88e926 100644--- a/docs/tools/cli/run.md+++ b/docs/tools/cli/run.md@@ -303,7 +303,11 @@ A run whose main output resolves as a recorded absence (an optional `?` output t## An Invalid Bundle-A run loads its bundle before any pipe runs, and refuses an invalid one there, before spending anything. The refusal is reported the way [`pipelex validate`](validate.md) reports the same bundle: the grouped invalid-bundle panel, with one located item per refusal (its pipe, its field, its message and its suggested fix when it has one), and exit code `1`. 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, and the panel names the bundle instead; a bundle that does not parse when `run bundle` looks for its `main_pipe` (no `--pipe`) names its file on the item too. That holds whether the parse or the load refuses the bundle, and for a refusal found while loading a library directory you pass with `-L` (or the method's folder, for `run bundle <dir>`). When the items carry automatic fixes, the panel names the `pipelex fix bundle` command that applies them.+A run loads its bundle before any pipe runs, and refuses an invalid one there, before spending anything. The refusal is reported the way [`pipelex validate`](validate.md) reports the same bundle: the grouped invalid-bundle panel, with one located item per refusal (its pipe, its field, its message and its suggested fix when it has one), and exit code `1`. 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, and the panel names the bundle instead; a bundle that does not parse when `run bundle` looks for its `main_pipe` (no `--pipe`) names its file on the item too. That holds whether the parse or the load refuses the bundle, and for a refusal found while loading a library directory you pass with `-L` (or the method's folder, for `run bundle <dir>`). When the items carry automatic fixes, the panel names the `pipelex fix bundle` command that applies them. The panel goes to stderr, as every failure's report does.++## A Failed Run++A run that fails prints its problem: the failure's message, then the problem's title, its next step, its code with its domain and retry verdict, and its location, the pipe that failed and its path from the entry pipe, followed by the error's advice as a tip when it gives one, and exits with code `1`. A failure with a panel of its own, a model that is not available or a model choice that cannot be read, prints that panel, which carries the same rows. An unexpected failure is printed the same way, its message capped, and logged by its code, the classes along its cause chain and the frames it went through, by module, line and function; pass `--traceback` for its stack trace. The report and the stack trace go to stderr whatever `console_print_target` says, so stdout keeps only what the run produced.## Related Documentationdiff --git a/docs/tools/cli/validate.md b/docs/tools/cli/validate.mdindex 08ab1cd6c..0d3e8c5c0 100644--- a/docs/tools/cli/validate.md+++ b/docs/tools/cli/validate.md@@ -124,7 +124,7 @@ pipelex validate method invoice_extractor --pipe extract_amounts## An Invalid Bundle Is a Verdict-Every refusal of your method raised while it is loaded or validated is reported as an invalid bundle: the grouped `❌ Bundle validation failed` output naming each error's pipe, domain, field and file, with exit code `1`. Exit code `2` is kept for the cases where no verdict could be produced — bad arguments, a target that does not resolve, or a failure of Pipelex or its environment. This holds on every subcommand: `validate pipe` and `validate --all` render a pipe whose dry run fails the same way `validate bundle` does, where they used to print a traceback. A failing dry run is listed under `Dry Run Errors:` with one entry per failing pipe, naming the innermost pipe that failed and is not allowed to fail rather than every controller around it, and every error found while parsing gets its own entry, so a misspelled field is reported beside the other errors instead of after they are fixed. A few refusals raised while a pipe is built do not classify themselves as a fault of your method yet, and those still stop validation without a verdict.+Every refusal of your method raised while it is loaded or validated is reported as an invalid bundle: the grouped `❌ Bundle validation failed` output naming each error's pipe, domain, field and file, printed on stderr with any `--traceback` stack trace, with exit code `1`. Exit code `2` is kept for the cases where no verdict could be produced — bad arguments, a target that does not resolve, or a failure of Pipelex or its environment. This holds on every subcommand: `validate pipe` and `validate --all` render a pipe whose dry run fails the same way `validate bundle` does, where they used to print a traceback. A failing dry run is listed under `Dry Run Errors:` with one entry per failing pipe, naming the innermost pipe that failed and is not allowed to fail rather than every controller around it, and every error found while parsing gets its own entry, so a misspelled field is reported beside the other errors instead of after they are fixed. A few refusals raised while a pipe is built do not classify themselves as a fault of your method yet, and those still stop validation without a verdict.A pipe that names a model your model deck does not define is the most common case. It is reported as an `Unknown Model` error on that pipe, with the path of the field that names it (`pipe.<code>.model`, or `pipe.<code>.model_to_structure` for the model a `PipeLLM` structures its output with) and the deck's close matches:diff --git a/docs/tools/logging.md b/docs/tools/logging.mdindex a9379c585..b00124135 100644--- a/docs/tools/logging.md+++ b/docs/tools/logging.md@@ -566,7 +566,9 @@ What varies goes in `fields`, named by the [naming convention](#naming-conventio| `auth_refusal_reason` | string | Why the API server refused a caller's own credentials: `missing_bearer_token`, `expired_token`, `invalid_token` or `api_key_mismatch` || `claim_type` | string | The type a token's claim was decoded as, by its Python name, where the claim is refused and its value is not logged: `str`, `int`, `dict` || `error.type`, `error.message` | string | A handled exception's class name and its text, as [Exceptions](#exceptions) describes |-| `error.code` | string | The registry code of a failure's problem, which the line about a pipe's failure carries in place of its text |+| `error.code` | string | The registry code of a failure's problem, which a line about a failure that may quote a run's data gives in place of its text, the line about a pipe's failure and the root of a CLI command's among them, and the code of the refusal a [security event](#the-security-event) logs, whose domain rides beside it in `error.domain` |+| `error.chain` | list of strings | The classes along a failure's cause chain, its own first, which the root of a CLI command gives in place of the chain's texts |+| `error.frames` | list of strings | The frames a failure went through, from where the root of a CLI command caught it down to where its first exception was raised, each `module:line in function`, with no source line and no local, the innermost forty kept, which that root gives in place of the traceback || `error_domain` | string | Who fixes a failure: `input`, `config`, `runtime`, read from the domain of the failure's code || `error_category` | string | An inference failure's Pipelex classification, as its error carries it || `retryable` | boolean | Whether retrying the failed call as it was can help, as the failure's code says |@@ -581,7 +583,8 @@ What varies goes in `fields`, named by the [naming convention](#naming-conventioAn exception rides the record, never the message, at every level, DEBUG and VERBOSE included, as the [log-call guard](../contribute/log-calls.md#no-exception-in-the-text) holds every call to. Spliced into the text, `{exc}` makes the message vary, loses the exception's type and traceback, and gets only the pattern half of the [redaction](#redaction), where a field also has its control characters escaped. So:-- **At ERROR and CRITICAL**, inside the `except` block, pass `include_exception=True`: the record carries the exception, and each sink writes its type and its traceback its own way. That is for an exception the code handles where it logs it, whose traceback nobody else will see, and above all for the catcher of an unexpected failure, the root of a CLI command or the API server's error handler, which logs it there and prints no traceback of its own: the `console` sink renders it under the line, and the `json` and `otlp` sinks write it to the log store, which a traceback printed on the console alone never reaches. A CLI command's root also names the exception's type and message in its own output, which is not a log record, so the terminal says why the command failed whatever the sink and the level, under a `json` sink writing to a file as under a level above ERROR.+- **At ERROR and CRITICAL**, inside the `except` block, pass `include_exception=True`: the record carries the exception, and each sink writes its type and its traceback its own way. That is for an exception the code handles where it logs it, whose traceback nobody else will see, and for the API server's error handler, which logs it there and prints no traceback of its own: the `console` sink renders it under the line, and the `json` and `otlp` sinks write it to the log store, which a traceback printed on the console alone never reaches.+- **The root of a CLI command carries identifiers, not the exception**, unless the person running it passed `--traceback`. A traceback prints the text of every exception along the chain, and that text can quote a run's data: a foreign `ValidationError` quotes the values it refused, a method function's exception says what the function was given. So the line about an unexpected failure carries `error.code`, the code of the failure's problem, `error.type`, its class, `error.chain`, the classes along its cause chain, the failure's own first, and `error.frames`, the frames it went through down to the fault, each by its module, its line and its function, with no source line, no local and no text (`failure_log_fields`, in `pipelex.errors.failure_problem`), so a log store says where the failure happened, and `include_exception=is_traceback_requested()` puts the traceback on the record only under `--traceback`. The command's own output, which is not a log record, prints the failure's problem in the operator's view, its message capped, so the terminal says why the command failed whatever the sink and the level, under a `json` sink writing to a file as under a level above ERROR.- **An exception logged and then re-raised carries no traceback, at ERROR too**: it rides as `error_fields`, since whoever catches it owns its traceback, and a line that carried it as well would print it a second time, ahead of the catcher's own report.- **A pipe's failure carries no text at all**: `The execution of a pipe failed` names the pipe, `error.code`, the code of the problem the failure reports, and `error.type`, the exception's class, and never `error.message`. A run's failure can hold the caller's own text, a method function's message or a template's source, and a refused host, which no log line carries, while the caller's own problem holds them where the code declares a parameter for them, and the catcher's report gives the operator the rest.- **A secondary failure carries no traceback either**: a cleanup that fails while another exception propagates, a tracer that will not close, a library that will not tear down, a delivery that fails after the run did, rides as fields, at ERROR too, and a failure that follows a pipe's own, the delivery's or the graph tracer's, rides as its class and, for a Pipelex error, its code, never its text, which names the caller's webhook URL or the trace's file, as the line about the pipe's own failure does. Python chains the propagating exception onto it as its context, so its traceback would print the primary's text, a `ValidationError`'s refused input included, under a line that is not about it, while the primary's own catcher reports it. A cleanup that runs either way, a plugin's teardown callback, follows the same rule.@@ -601,7 +604,7 @@ An exception rides the record, never the message, at every level, DEBUG and VERBThe [level table](#log-levels) states what a line at each level means, and choosing the level of a call follows from it. There is no DEV level.-- **ERROR** says a run failed or data was lost, and that somebody should look; it carries an exception it handles with `include_exception=True`, and one it re-raises, a secondary failure and a swallowed `ValidationError` as `error_fields`.+- **ERROR** says a run failed or data was lost, and that somebody should look; it carries an exception it handles with `include_exception=True`, one it re-raises, a secondary failure and a swallowed `ValidationError` as `error_fields`, and a CLI command's unexpected failure as `failure_log_fields`, its traceback only under `--traceback`.- **WARNING** must be actionable: a degradation that was handled, or a misconfiguration the user can fix. A warning nobody can act on moves down to DEBUG, or up to ERROR when something was in fact lost.- **INFO** marks a lifecycle milestone, and there are few of them, because Pipelex is also a library and a library says little at INFO. The [summary events](#summary-events) are the one exception in number, an event for each inference call and each live pipe run: they are INFO because the dashboards built from them read the default production level, and a host that wants Pipelex quieter at INFO raises their loggers' level, as that section shows.- **DEBUG** answers a question you would ask on reading a log a user sent: which file was read, which fallback was taken, why a model was left out.diff --git a/docs/under-the-hood/codegen-projections.md b/docs/under-the-hood/codegen-projections.mdindex 03e75ea97..9660bee1c 100644--- a/docs/under-the-hood/codegen-projections.md+++ b/docs/under-the-hood/codegen-projections.md@@ -59,7 +59,7 @@ Two command families drive the engine:Both codegen commands load and normalize the crate through the same shared helper the resolver uses (`pipelex/cli/commands/crate_loading.py`), so they share the resolve/validate exit-code contract.-The **agent CLI mirrors** the family for machine consumers: `pipelex-agent codegen types --target <flavor>` runs the same engine and emission layer but presents through the agent CLI's two-stream envelopes (`--format markdown|json` on stdout for success, `--error-format` on stderr for errors — markdown default), and `pipelex-agent codegen check` is the same offline drift check with the verdict as a structured envelope: up-to-date is a success envelope, drift is a `CodegenDriftError` error envelope enumerating `drifts[]` by category (exit `1`), and a missing/unreadable lock is a no-verdict error (exit `2`). There is no `pipelex-agent codegen inputs` — the existing `pipelex-agent inputs` group already surfaces that projection. The legacy `build` family rides the same engine: `pipelex build inputs` renders through the same `input_renderer` engine as `codegen inputs` (they cannot diverge), and `pipelex build structures` is a thin alias of `codegen types --target python-structures` (the old always-qualified per-file generator is gone — the alias emits the single stamped `structures.py` + `codegen.lock`, bare-when-unique names).+The **agent CLI mirrors** the family for machine consumers: `pipelex-agent codegen types --target <flavor>` runs the same engine and emission layer but presents through the agent CLI's two-stream envelopes (`--format markdown|json` on stdout for success, `--error-format` on stderr for errors — markdown default), and `pipelex-agent codegen check` is the same offline drift check with the verdict as a structured envelope: up-to-date is a success envelope, drift is the problem `pipelex.codegen.drifted`, its `params.artifacts` naming the drifted files and a `drifts[]` member beside it enumerating them by category (exit `1`), and a missing or unreadable lock is a no-verdict problem, `pipelex.codegen.lock_not_found` or `pipelex.codegen.lock_invalid` (exit `2`). There is no `pipelex-agent codegen inputs` — the existing `pipelex-agent inputs` group already surfaces that projection. The legacy `build` family rides the same engine: `pipelex build inputs` renders through the same `input_renderer` engine as `codegen inputs` (they cannot diverge), and `pipelex build structures` is a thin alias of `codegen types --target python-structures` (the old always-qualified per-file generator is gone — the alias emits the single stamped `structures.py` + `codegen.lock`, bare-when-unique names).## The trust chain: stamps, lock, and the offline checkdiff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.mdindex caab6f3f0..54e2b4fbe 100644--- a/docs/under-the-hood/error-model.md+++ b/docs/under-the-hood/error-model.md@@ -139,9 +139,9 @@ Every text a raise site, a provider or a caller wrote is bounded in a problem: `### The identity, and why renaming an error class or changing its code is a wire break-`code` is the identity a problem carries, and a consumer branches on it. `title` and `type` follow from the code, so no class declares them. The class an error was raised as is no member of the caller's problem: it rides the operator view's `diagnostics.error_class`, the agent CLI's envelope as `error_type` and the API's log record as `error.type`.+`code` is the identity a problem carries, and a consumer branches on it. `title` and `type` follow from the code, so no class declares them. The class an error was raised as is no member of the caller's problem: it rides the operator view's `diagnostics.error_class`, which both CLIs print, and the log records as `error.type`.-Changing the code a class declares changes what every reader is told to do, and breaks a consumer branching on the old code *silently*: its build stays green and its branch simply stops matching, falling through to a generic error path. Renaming an error class breaks whoever reads its name the same way: an agent switching on the CLI envelope's `error_type`, or an operator's log query or alert on `error.type`.+Changing the code a class declares changes what every reader is told to do, and breaks a consumer branching on the old code *silently*: its build stays green and its branch simply stops matching, falling through to a generic error path. Renaming an error class breaks whoever reads its name the same way: an agent switching on the CLI problem's `diagnostics.error_class`, or an operator's log query or alert on `error.type`.The guard against both is a committed snapshot of every class's name and code declaration at `tests/data/errors/error_identity.txt`, regenerated with `make generate-error-identity` (alias `make gei`) and gated by `tests/unit/pipelex/errors/test_error_identity_snapshot.py`. A rename or a change of code cannot land without producing a reviewable diff on that file at the moment it is made — which is also the moment to plan the matching consumer updates. The same command rewrites the static redirects of the retired per-class error pages, described below.@@ -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()` (every problem of an invalid bundle), the validators' invalid arm, the agent CLI's `extract_validation_errors()` (the CLI JSON envelope) 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 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.#### The `error_type` registry — the closed vocabulary of faults@@ -233,7 +233,7 @@ exc.validation_error_items() # the typed items a verdict carries as validation_```!!! info "Two shapes of the same items"- A validation verdict — the `200` `is_valid: false` answer of the API's diagnostic routes, the CLIs' validation output and a validator's invalid arm — carries the `ValidationErrorItem`s whole, as `validation_errors`. A problem — the `422` answer of a run refused before any pipe ran — carries them as `errors` items, each with its code. Both are built from the same items, so they name the same faults at the same places.+ A validation verdict — the `200` `is_valid: false` answer of the API's diagnostic routes, the human CLI's validation output and a validator's invalid arm — carries the `ValidationErrorItem`s whole, as `validation_errors`. A problem — the `422` answer of a run refused before any pipe ran, and the agent CLI's invalid verdict on stderr — carries them as `errors` items, each with its code. Both are built from the same items, so they name the same faults at the same places.### `suggested_fix` — structured deterministic fixes@@ -261,7 +261,7 @@ Two `StrEnum`s sit beside the code. Neither decides anything a reader branches o### InferenceErrorCategory-Defined in `pipelex/cogt/exceptions.py`. It stays inside the runtime as the classification that **picks a provider failure's code**: the worker's classification (`pipelex/cogt/inference/error_classify.py`) reads the provider's answer, assigns a category and a code together, and the rendered error carries both. The category also still drives one decision the code cannot carry: whether the Temporal activity may repeat a provider call within the run, through `is_retryable` and `find_inference_error_category_in_chain`. A call whose outcome is unknown (`AMBIGUOUS`) must never be repeated within the run, though its code, `provider.outcome_unknown`, says a new run may succeed.+Defined in `pipelex/cogt/exceptions.py`. It stays inside the runtime as the classification that **picks a provider failure's code**: the worker's classification (`pipelex/cogt/inference/error_classify.py`) reads the provider's answer, assigns a category and a code together, and the rendered error carries both. The category also still drives one decision the code cannot carry: whether the Temporal activity may repeat a provider call within the run, through `is_retryable` and `find_inference_error_category_in_chain`. A call whose outcome is unknown (`AMBIGUOUS`) must never be repeated within the run, though its code, `provider.outcome_unknown`, says a new run may succeed. It never reaches a reader: no problem, no CLI output and no usage-statistics event carries it, and the usage statistics count a model's failed calls by the domain of their code.| Category | Meaning | Repeated within the run | Typical codes ||----------|---------|-------------------------|---------------|@@ -279,7 +279,7 @@ The category and the code are checked against each other. A classification whose### ErrorDomain-Defined in `pipelex/base_exceptions.py`. A problem carries its code's own domain, one of the five the MTHDS core declares; `ErrorDomain` is a three-valued reading of it, derived through `ErrorDomain.from_problem_domain()`, which the CLIs' error envelopes, the usage statistics and the API's log records still carry as `error_domain`:+Defined in `pipelex/base_exceptions.py`. A problem carries its code's own domain, one of those the MTHDS core declares; `ErrorDomain` is a coarser reading of it, derived through `ErrorDomain.from_problem_domain()`, which the API's log records still carry as `error_domain`. The CLIs' problems and the usage statistics carry the code's own domain instead, from the core's full list:| Code's domain | `error_domain` | Who acts ||---------------|----------------|----------|@@ -492,15 +492,15 @@ A refusal is reported once per process, however many of these boundaries it cros### CLI-The agent CLI (`pipelex-agent`) emits a structured error to **stderr**, markdown by default and JSON with `--error-format json`. When `--error-format` is omitted it **inherits the value of `--format`** (the success-output flag) — so `--format json` still flips both as it did before the split. Both exit with code 1.+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.| Command | Error output ||---------|--------------|-| `run`, `validate`, `init`, `models`, `check-model`, `doctor` | Markdown (default) or JSON via `--error-format` (or via `--format`, which `--error-format` inherits) |-| `inputs` | JSON only |-| `fmt`, `lint` | Native `plxt` output (subprocess passthrough); falls back to JSON only when the `plxt` binary itself is missing |+| `run`, `validate`, `fix`, `init`, `models`, `check-model`, `doctor`, `migrate`, `codegen` | Markdown (default) or JSON via `--error-format` (or via `--format`, which `--error-format` inherits) |+| `inputs` | Markdown or JSON via `--error-format`, JSON by default: its `--format` is the template's serialization |+| `fmt`, `lint` | Native `plxt` output (subprocess passthrough); the problem `client.tool_missing` only when the `plxt` binary itself is missing |-The human CLI (`pipelex`) renders a Rich error panel — red banner, structured fields, the `user_action` tip, doc/Discord links — through the shared `display_error_panel()` helper in `pipelex/cli/error_handlers.py`.+The human CLI (`pipelex`) renders a Rich error panel — red banner, structured fields, the error message, then the problem's rows (its title, its detail, its next step, its code with the domain and the retry verdict, its location, its request id and its run), the `user_action` tip, doc/Discord links — through the shared `display_error_panel()` helper in `pipelex/cli/error_handlers.py`. A command's root that catches any other failure prints it the same way, through `print_failure_problem()`, and logs it by identifiers only: the problem's code, the failure's class and the classes along its chain (`failure_log_fields()`, in `pipelex/errors/failure_problem.py`), never a chained exception's text, which can quote a run's data, and its traceback only under `--traceback`.#### Validate exit-code policy (0 / 1 / 2)@@ -512,9 +512,9 @@ The `validate` surface — both the bare `pipelex validate {bundle,method,pipe}`| `1` | negative verdict | a produced "no": an invalid bundle (`ValidateBundleError`), or valid-but-not-runnable **without** `--allow-signatures` (a strict signature breach) || `2` | no verdict | the CLI could not produce a verdict — bad args, an unresolvable target (no `.mthds` in a directory, a missing file, an unknown/ambiguous pipe code), or a setup/internal error during validate |-**The verdict lives in the structured `is_valid` field, not the exit code.** The exit code is a convenience signal for naive shell/CI/Makefile use (`set -e`, `cmd && next`, `if cmd; then`); machine consumers (hooks, the Codex hook, runners) MUST read `is_valid` (and `error_domain`) from the JSON for their block/warn decisions rather than branching on the exit code. Decoupling the verdict from the exit code is what keeps any future exit-code change non-breaking. The 1-vs-2 split is also additive for flat consumers: both stay non-zero, so anything that only tests zero-vs-non-zero is unaffected.+**The verdict lives in the structured `is_valid` field, not the exit code.** The exit code is a convenience signal for naive shell/CI/Makefile use (`set -e`, `cmd && next`, `if cmd; then`); machine consumers (hooks, the Codex hook, runners) MUST read `is_valid` (and the problem's `code` and `domain`) from the JSON for their block/warn decisions rather than branching on the exit code. Decoupling the verdict from the exit code is what keeps any future exit-code change non-breaking. The 1-vs-2 split is also additive for flat consumers: both stay non-zero, so anything that only tests zero-vs-non-zero is unaffected.-Implementation: the agent CLI threads `exit_code` through `agent_error(...)` (`agent_output.py`, default 1); the validate commands pass `exit_code=2` at every no-verdict site and keep the default 1 on the `ValidateBundleError` arm and the signature gate. The bare CLI sets the code directly via `typer.Exit(...)` in `cli/commands/validate/*` and via the `exit_code` parameter on `handle_model_availability_error` in `cli/error_handlers.py`. Every refusal of the bundle is a negative verdict on both CLIs: `validate bundle` and `validate method` validate through the shared cascade, and `validate pipe` and `validate --all` load their libraries through it too, so an unknown model or any other load-time refusal exits 1 with the invalid-bundle output rather than a traceback or the no-verdict exit 2. The bare `validate pipe` and `validate --all` also run their dry run through it, so a pipe whose dry run fails is rendered like any other invalid bundle; the agent CLI answers that failure with its `DryRunError` envelope, `is_valid: false` and exit 1. Shared boot handlers (`make_pipelex_for_cli`'s telemetry-config and model-deck-preset paths) stay exit 1 — they are shared across `run`/`build`/`validate` and out of the validate-policy scope.+Implementation: the agent CLI threads `exit_code` through `agent_error(...)` (`agent_output.py`, default 1); the validate commands pass `exit_code=2` at every no-verdict site and keep the default 1 on the `ValidateBundleError` arm and the signature gate. The bare CLI sets the code directly via `typer.Exit(...)` in `cli/commands/validate/*` and via the `exit_code` parameter on `handle_model_availability_error` in `cli/error_handlers.py`. Every refusal of the bundle is a negative verdict on both CLIs: `validate bundle` and `validate method` validate through the shared cascade, and `validate pipe` and `validate --all` load their libraries through it too, so an unknown model or any other load-time refusal exits 1 with the invalid-bundle output rather than a traceback or the no-verdict exit 2. The bare `validate pipe` and `validate --all` also run their dry run through it, so a pipe whose dry run fails is rendered like any other invalid bundle; the agent CLI answers that failure with the problem `method.invalid`, `is_valid: false` and exit 1. Shared boot handlers (`make_pipelex_for_cli`'s telemetry-config and model-deck-preset paths) stay exit 1 — they are shared across `run`/`build`/`validate` and out of the validate-policy scope.### APIdiff --git a/pipelex/base_exceptions.py b/pipelex/base_exceptions.pyindex 1fd5fcc3e..aaa62968e 100644--- a/pipelex/base_exceptions.py+++ b/pipelex/base_exceptions.py@@ -8,7 +8,7 @@ from opentelemetry import tracefrom pydantic import BaseModel, ConfigDict, Fieldfrom typing_extensions import override-from pipelex.cogt.inference.error_classification import UserAction+from pipelex.cogt.inference.error_classification import UserAction, UserActionKindfrom pipelex.errors.error_code_declaration import (ABSTRACT_ERROR,AbstractError,@@ -170,9 +170,9 @@ class ValidationErrorItem(BaseModel):``exclude_none`` wire projection.The error channel is built exclusively by- ``pipelex.pipeline.validation_errors.build_validation_error_items``, which both the agent- CLI (``extract_validation_errors``) and the API path- (``ValidateBundleError.validation_error_items``) call — so the CLI's structured+ ``pipelex.pipeline.validation_errors.build_validation_error_items``, which the agent+ CLI's problem (``ValidateBundleError.problem_items``) and the API path+ (``ValidateBundleError.validation_error_items``) both reach — so the CLI's structuredoutput and the API's invalid verdict can never drift. The sameitem type also carries the report's advisory ``warnings``, built by``pipelex.pipeline.advisory_warnings``: a warning is the same shape of@@ -383,11 +383,19 @@ class PipelexError(Exception):self._given_items = list(items)return self+ def own_advice(self) -> UserAction | None:+ """The advice this error gives by itself, before its causes': its ``user_action``.++ A class whose advice follows what its raise site chose, such as a configuration refusal's code, overrides it.+ """+ return self.user_action+def advised_action(self) -> UserAction | None:"""The advice nearest this error along its cause chain, which a local CLI prints as a tip; never part of a problem."""for node in iter_pipelex_cause_chain(self):- if node.user_action is not None:- return node.user_action+ advice = node.own_advice()+ if advice is not None:+ return advicereturn None@property@@ -683,17 +691,119 @@ class PipelexUnexpectedError(PipelexError):error_code: ClassVar[ErrorCodeDeclaration] = CoreCode.RUNTIME_UNEXPECTED+#: The advice a configuration that does not validate gives when no pending migration explains it.+CONFIG_DOCTOR_ADVICE = UserAction(+ kind=UserActionKind.UNKNOWN,+ detail=(+ "Run 'pipelex doctor' (from an agent, 'pipelex-agent doctor') to find what in the configuration does not "+ "validate, correct it, then run the command again."+ ),+)++#: The advice a stale configuration gives, which a migration brings up to date.+CONFIG_MIGRATE_ADVICE = UserAction(+ kind=UserActionKind.UNKNOWN,+ detail=(+ "The configuration is out of date: run 'pipelex migrate' to bring it up to date, which keeps a copy of each file it "+ "changes. From an agent, run 'pipelex-agent migrate --dry-run --format json' to see what it would change, show the "+ "user, then run 'pipelex-agent migrate --yes'. 'pipelex-agent init' (with --global for the home configuration) "+ "writes a fresh configuration instead, discarding its settings."+ ),+)++#: The advice a configuration gives when a migration has something to say but would write nothing.+CONFIG_MIGRATE_BY_HAND_ADVICE = UserAction(+ kind=UserActionKind.UNKNOWN,+ detail=(+ "A migration would rewrite nothing here: correct by hand what the migration's plans name (the problem's "+ "'diagnostics.migration', or 'pipelex-agent migrate --dry-run --format json'), then run the command again. "+ "Do not write a fresh configuration over it, which would discard settings a migration keeps."+ ),+)+++#: The advice a configuration file that is missing gives: restore it, or write the default one.+CONFIG_INIT_ADVICE = UserAction(+ kind=UserActionKind.UNKNOWN,+ detail=(+ "A configuration file is missing: restore it, or run 'pipelex init' (from an agent, 'pipelex-agent init', with "+ "--global for the home configuration) to write the default configuration, then run the command again."+ ),+)++#: The advice a variable the configuration reads and finds unset gives: set it where the configuration reads it.+CONFIG_VARIABLE_ADVICE = UserAction(+ kind=UserActionKind.UNKNOWN,+ detail=(+ "A variable the configuration reads is not set: set the one the message names, in the environment or in the "+ "secrets provider the configuration reads it from, then run the command again."+ ),+)++#: The advice of a configuration refusal no migration explains, by its code; any other code is a configuration that+#: does not validate or does not parse, which ``doctor`` finds.+_CONFIG_ADVICE_BY_CODE: dict[ErrorCode, UserAction] = {+ PipelexErrorCode.CONFIG_FILE_MISSING: CONFIG_INIT_ADVICE,+ PipelexErrorCode.CONFIG_VARIABLE_MISSING: CONFIG_VARIABLE_ADVICE,+}+++def config_refusal_advice(*, migration: MigrationErrorBlock | None, code: ErrorCode | None) -> UserAction:+ """The advice a refused configuration gives: the migration's that explains it, when one does, else its code's.++ A migration that would write: the configuration is old, and a migration brings it up to date. One that would write+ nothing: the plans are a diagnosis, to act on by hand. No migration: a missing file is restored or written by+ ``init``, a variable that is not set is set, and a configuration that does not validate or parse is what ``doctor``+ finds.+ """+ if migration is None:+ if code is None:+ return CONFIG_DOCTOR_ADVICE+ return _CONFIG_ADVICE_BY_CODE.get(code, CONFIG_DOCTOR_ADVICE)+ if migration.would_write:+ return CONFIG_MIGRATE_ADVICE+ return CONFIG_MIGRATE_BY_HAND_ADVICE++class PipelexConfigError(PipelexError):- """A configuration this process cannot use, optionally with the migration that explains it."""+ """A configuration this process cannot use, optionally with the migration that explains it.++ Its raise site names what its code's step reads, as far as it knows them: the part of the configuration at fault+ (``surface``), the file (``file``) and the setting (``setting``). Its advice, the tip a local CLI prints, is read+ off the migration and the code (:func:`config_refusal_advice`): migrate, or correct what the plans name, or else+ write a missing file with ``init``, set a missing variable, or find with ``doctor`` what does not validate.+ """error_code: ClassVar[ErrorCodeDeclaration] = ErrorCodeSet(default=PipelexErrorCode.CONFIG_INVALID,others=(PipelexErrorCode.CONFIG_SYNTAX, PipelexErrorCode.CONFIG_FILE_MISSING),)- def __init__(self, message: str, *, migration: MigrationErrorBlock | None = None):+ def __init__(+ self,+ message: str,+ *,+ migration: MigrationErrorBlock | None = None,+ surface: str | None = None,+ file: str | None = None,+ setting: str | None = None,+ ):super().__init__(message)self.migration = migration+ self.surface = surface+ self.file = file+ self.setting = setting++ @override+ def own_advice(self) -> UserAction | None:+ # Read when the advice is, so it follows the code a raise site chose after building the error.+ if self.user_action is not None:+ return self.user_action+ return config_refusal_advice(migration=self.migration, code=self.own_error_code)++ @override+ def problem_params(self) -> dict[str, Any]:+ return {name: value for name, value in {"surface": self.surface, "file": self.file, "setting": self.setting}.items() if value is not None}@overridedef problem_facts(self) -> ProblemFacts:diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.mdindex b2d8a8436..2d623acfc 100644--- a/pipelex/cli/agent_cli/CLAUDE.md+++ b/pipelex/cli/agent_cli/CLAUDE.md@@ -7,22 +7,22 @@ Machine-first CLI for running and validating Pipelex method bundles (`.mthds` fiTwo independent options control the two output streams:- `--format markdown|json` — **success/useful output**. Defaults to markdown. Accepted by `run`, `validate`, `fix`, `init`, `models`, `check-model`, `doctor`, `migrate`, `codegen types`, `codegen check`. Goes to stdout. Threaded explicitly to `agent_success_formatted()` from each command function — no hidden state.-- `--error-format markdown|json` — **error reporting** (stderr). Optional. When omitted, **inherits the value of `--format`**, so `--format json` still flips both as it did historically. Accepted by the same commands as `--format`.+- `--error-format markdown|json` — **error reporting** (stderr), the failure's problem. Optional. When omitted, the program's own `--error-format` (given before the command, on the root callback) applies, else it **inherits the value of `--format`**, so `--format json` still flips both as it did historically, else JSON. Accepted by the same commands as `--format`, by the `inputs` commands, and by the root.-Only the error format is backed by a module-level `ContextVar` in `agent_output.py` (`_agent_cli_error_format`). The reason: `agent_error()` is called from sites that don't see the Typer option — factory init failures (`agent_cli_factory.py`), the unknown-command handler in `PipelexAgentCLI.get_command`, and any future site in shared library/runtime code. The ContextVar lets all of them honor `--error-format` (or `--format`'s inherited value) for free. JSON is the default so errors raised before any command opts in stay machine-parseable.+Only the error format is backed by module-level `ContextVar`s in `agent_output.py`: `_agent_cli_error_format`, the invocation's, and `_agent_cli_root_error_format`, the root's `--error-format`, which the root callback sets through `start_agent_cli_error_format(root_error_format=…)` before any command runs. Each command settles its own with `use_agent_cli_error_format(error_format=…, output_format=…)`: its `--error-format`, else the root's, else its `--format`, else JSON. The reason for the ContextVar: `agent_error()` is called from sites that don't see the Typer option — factory init failures (`agent_cli_factory.py`), the unknown-command handler in `PipelexAgentCLI.get_command`, and any future site in shared library/runtime code. The ContextVar lets all of them honor the settled format for free. JSON is the default so errors raised before any command opts in stay machine-parseable, and `mthds-agent` can forward `--error-format` before the command whatever the command.-`fmt` and `lint` are **always JSON / raw passthrough** — they have neither `--format` nor `--error-format`. Their errors keep flowing through the ContextVar's JSON default.+`fmt` and `lint` are **raw passthrough** — they have neither `--format` nor `--error-format`. Their one error, `plxt` not installed (`client.tool_missing`), follows the root's `--error-format`, else JSON.-`inputs` is a deliberate deviation: its `--format` takes `json|toml` (an `InputsTemplateFormat`, NOT the `markdown|json` `CliOutputFormat` pair) because it selects the **template serialization**, not a presentation style. `json` (default) keeps the structured success envelope; `toml` prints the raw TOML template to stdout. A pipe with no inputs prints a TOML comment line in `toml` mode (valid TOML, loads back as an empty dict). `inputs` still has no `--error-format` — its errors keep flowing through the ContextVar's JSON default.+`inputs` is a deliberate deviation: its `--format` takes `json|toml` (an `InputsTemplateFormat`, NOT the `markdown|json` `CliOutputFormat` pair) because it selects the **template serialization**, not a presentation style. `json` (default) keeps the structured success envelope; `toml` prints the raw TOML template to stdout. A pipe with no inputs prints a TOML comment line in `toml` mode (valid TOML, loads back as an empty dict). `inputs` takes its own `--error-format` (`markdown|json`), which falls back to the root's and then to JSON, never to its `--format`.Markdown structure per command:- `run`: `# Pipeline run complete`, a `## Result` section (the rendered `main_stuff` markdown with `--with-memory`, otherwise the concept JSON in a fenced block), and output / graph file paths. With the graph on, the `graph_files` object of the `--with-memory` envelope names the viewer (`graph_html`), the graph on a live run (`graph_spec`, the graphspec renamed `live_run_graph.json`) and the graph's three companions written beside it under their canonical names (`pipe_io_contracts`, `input_form`, `output_form` — the validate artifacts describing the graph's data, keyed by `pipe_ref`); the agent CLI settles its graph inclusion (graphspec on, viewer on) before the run rather than at render time, since the companions are built inside the run's library window under that same flag; a viewer resolves them from the graph file's directory, so the rename never moves them. Cost is machine-first: on the local runner, when costs are on (`--costs`, the default) and the run did reportable work (any tokens or any cost), a best-effort `cost_report` object (`{total_cost, by_model: [...]}`, real USD) rides the JSON `--with-memory` envelope — there is **no** Rich cost table on stderr (unlike the human `pipelex run` CLI). The markdown renderer ignores the `cost_report` key, so it is JSON-only. A free/zero-price model still reports its token usage (with `total_cost` 0). The `cost_report` is **absent** when the run did no reportable work (dry runs), when `--no-costs` is passed, on a hosted run (which assembles no local usage), or if cost-summary aggregation fails (caught and skipped so it never fails an otherwise-successful run) — so consumers must treat it as optional. A local `run bundle` also carries `method_tree_digest`, the digest of the method tree it read, in its output file and its `--with-memory` envelope.- `validate`: `# Validation passed`, the bundle path when relevant (a method's folder, for a folder judged whole), and a list of validated pipes with their status. `validate bundle <folder> --graph` / `--view` on a folder that decides no pipe to start at adds `graph_unavailable`, a sentence saying why no graph was drawn, rendered as a `## Graph` section. Every entry in `validated_pipes` (markdown and JSON) identifies its pipe by the namespaced `pipe_ref` (`domain.code`) — the same unambiguous identity across `validate all`, `validate bundle`, and `validate pipe`, so the same pipe is never reported under two identifiers. `validate bundle`, `validate method`, and `validate all` carry `pending_signatures` — the library-wide list of pipes still declared as `PipeSignature` (unimplemented forward declarations), namespaced by `pipe_ref` — rendered as a "Pending signatures" section in markdown. They also carry a derived `is_runnable` boolean (`true` ⇔ `pending_signatures` is empty), and the markdown adds an explicit plain-English runnability verdict on those surfaces: a complete bundle/library states it is runnable, while one with pending signatures states it is NOT yet runnable immediately above the verbatim "Pending signatures" heading. These whole-bundle/whole-library surfaces are **strict by default**: they exit non-zero on `not is_runnable` unless `--allow-signatures` is passed (which both tolerates the placeholders for the exit code and mock-runs the signature pipes in the sweep). Single-pipe surfaces make no library-wide runnability claim and never gate the exit code on it: bare `validate pipe <code>` omits the key and emits no verdict, while `validate bundle`/`validate method` with `--pipe` still surface the library-wide `pending_signatures` for information but do not gate on it (the requested slice can be fully implemented even when unrelated placeholders remain elsewhere). The whole-bundle and whole-library surfaces also carry a `warnings` array — the advisory lints, then what the sweep's dry runs found without failing (a `PipeDocGen` template check's `template_check_warning`s), rendered as a "Warnings" section in markdown — assembled by `pipelex/pipeline/advisory_warnings.py`, the ONE composition point every advisory-bearing channel calls (this CLI, the bare CLI and the protocol report). Bare `validate pipe <code>` carries the dry-run findings alone (`pipelex/pipeline/dry_run_warnings.py`), since one pipe has no flow to lint but what its dry run found is about it; `validate bundle` / `validate method` with `--pipe` carry every family, because they validate the whole bundle and only narrow the dry run, so the array stays bundle-wide there. Add a new advisory family there, never at a call site: the sites used to assemble their own and disagreed about which families they carried.-- `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`. `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.+- `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: `# Error: <error_type>`, the message, the hint as a `> 💡` callout, the `validation_errors` items (when the cause's report, or a hosted 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.+- 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).## Companion: Agent Skills@@ -39,8 +39,8 @@ When changing CLI command signatures, output schemas, or error types, check whet```_agent_cli.py # Typer app setup, version callback, PipelexAgentCLI(TyperGroup) — command registration, orderingcommands/- agent_output.py # agent_success(), agent_error(), error hints/domains- agent_cli_factory.py # make_pipelex_for_agent_cli() — init with JSON errors+ agent_output.py # agent_success(), agent_error() and the refusals, the problem's Markdown, the hosted legacy envelope+ agent_cli_factory.py # make_pipelex_for_agent_cli() — init, a failure reported as its problemrun/ # run — execute pipeline (pipe|bundle|method subcommands)app.py # run_app Typer, subcommand registrationpipe_cmd.py # run pipe — execute by pipe code@@ -90,7 +90,7 @@ commands/| `fmt` | Formats a .mthds/.toml/.plx file in-place (delegates to plxt) || `lint` | Lints a .mthds/.toml/.plx file for errors (delegates to plxt) || `inputs` | Generates an example inputs template for a pipe/bundle/method (pipe\|bundle\|method subcommands). `--format json\|toml` (template serialization, default: json — NOT the markdown\|json pair); `toml` prints raw TOML to stdout |-| `codegen` | Agent mirror of the bare `pipelex codegen` family (types\|check subcommands). `types --target <flavor>` resolves the closure into the normalized crate and writes stamped typed artifacts + `codegen.lock` (write-if-changed); `check` is the offline drift check (pure hashing, no Pipelex boot — exit 0 current, 1 drift as a structured `CodegenDriftError` with `drifts[]`, 2 no/unreadable lock). Both: `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). |+| `codegen` | Agent mirror of the bare `pipelex codegen` family (types\|check subcommands). `types --target <flavor>` resolves the closure into the normalized crate and writes stamped typed artifacts + `codegen.lock` (write-if-changed); `check` is the offline drift check (pure hashing, no Pipelex boot — exit 0 current, 1 drift as the problem `pipelex.codegen.drifted` with `params.artifacts` and a `drifts[]` member, 2 no lock (`pipelex.codegen.lock_not_found`) or an unreadable one (`pipelex.codegen.lock_invalid`)). Both: `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). || `models` | Lists available model presets, aliases, and waterfalls. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value) || `check-model` | Validates a model reference by `ModelDeck.is_reference_defined`, the rule a validation and `GET /v1/models/check` apply, and suggests alternatives if invalid. `--type`/`-t` for model category, a `ModelCheckCategory` (the check's categories, `doc_gen` included, which the `models` listing's `ModelCategory` leaves out), `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value) || `migrate` | Migrates this machine's configuration files (the home configuration directory, `~/.pipelex/` or `PIPELEX_HOME`, and project `.pipelex/`, non-recursively) to the current schema by replaying each surface's ledger. Does **not** boot — it is the command for a configuration that cannot load. Its first step is the cleanup of what a former release that ran on the Pipelex Gateway left (the boot's `FormerReleaseConfigError` names this command): the JSON carries it under `former_release` (`is_clean`, `needs_attention`, `files`, each with `file_path`, `action` `rewrite`/`remove`, `changes`, `backup_path`, `was_applied`, `blocked_reason`, `blocked_detail`, and `still_blocking`, what would still stop the boot once the cleanup is done, read on every run: off the files a `--yes` run wrote, or as a dry run would write them) and counts it in `summary` (`former_release_files`, `former_release_files_cleaned`, `former_release_files_blocked`), `needs_attention` and `is_clean`. Writes only with `--yes`; `--dry-run` plans and is the default; the two together are refused with exit 2. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json`. The verdict is the structured `needs_attention`, not the exit code. |@@ -98,17 +98,17 @@ commands/## Key Patterns-- **Output contract**: Commands with `--format` emit success via `agent_success_formatted(result, markdown_renderer, output_format)` — JSON or a markdown renderer per the explicit `output_format` argument. `agent_error(message, error_type, cause)` dispatches JSON or markdown by reading the `_agent_cli_error_format` ContextVar, which each `--format`-aware command sets via `set_agent_cli_error_format(error_format or output_format)` at function entry. Exceptions that print directly to stdout: `fmt`/`lint` (plxt passthrough) and `inputs --format toml` (the raw TOML template). Markdown renderers: `format_run_markdown` (`run/_output_helpers.py`), `format_validate_markdown` (lifted to the non-CLI `pipelex/pipeline/validation_render.py` so `pipelex-api` can import it without CLI/Typer deps), `format_fix_markdown` (non-CLI `pipelex/pipeline/fixes/fix_render.py`), `_format_init_markdown` (`init_cmd.py`).-- **Error classification**: Each error carries a domain (`input`, `config`, `runtime`), a hint string, and a `retryable` flag. `agent_error()` reads them **code-first**: a `PipelexError` cause's registry code wins, and every `PipelexError` carries one, which decides the envelope's domain (the code's own domain read through `ErrorDomain.from_problem_domain`) and its `retryable` verdict. The code, the domain and the verdict are all read off the cause's problem in the operator's view, never off `resolve_error_code()` beside it, so a cause that reports a problem it recovered across a transport boundary gives its classification together with its step. The envelope names that code as `error_code`, the member a hosted refusal carries too; a cause that is not a `PipelexError` has no code and the envelope names none. The hint is the advice nearest the cause along its chain (`PipelexError.advised_action()`), which only a local CLI prints and no problem carries, else the `AGENT_ERROR_HINTS` entry, else the code's next step in the operator's view, since whoever runs this CLI runs the runtime; the model, the provider and a pending migration come from the cause's problem in the operator's view (`to_problem(view=ProblemView.OPERATOR)`, its `diagnostics`), and `validation_errors` from the first `ValidateBundleError` on the chain. The `AGENT_ERROR_DOMAINS` dict in `agent_output.py` is the fallback for the error types that carry no code alone (builtins, third-party classes, synthetic `error_type` labels), and no `PipelexError` subclass may sit in it, since its entry could never be read; `AGENT_ERROR_HINTS` may still name one, being read only when the cause's chain advises no action, but not one that declares a class-level `user_action`. There is no retryable lookup: only a code's verdict, or a `retryable` passed in `extra`, sets it. `tests/unit/pipelex/cli/test_agent_output_drift.py` enforces these. Because the read is code-first, the `error_type` an arm passes must name the class that actually failed — `type(exc).__name__`, not the base class the `except` caught. A hardcoded label detaches the reported class from the domain and hint riding the same envelope from the cause's code, so a consumer reading `error_type` is told one class produced a classification only another declares; the `validate pipe` / `validate bundle` not-found arms did exactly that until the entry-shaped lookups gained their own INPUT-domain classes. A synthetic label is still legitimate where there is no exception class to name, and that is what the dicts key on. The run arms are the one deliberate exception: they pass `PipelineExecutionError`, the one class a run failure arrives as, and `run_failure_fields()` adds `pipe_code` / `pipe_stack` (the failing pipe and its path) and `cause_type` / `cause_message` (the root fault's class and message, found with `find_root_fault()`, never the router wrapper right under the run error); the code and the location come from the run error's problem, which is its root fault's. When the domain a class reports is wrong, the class needs another code, never a dict entry. An HTTP surface answers the problem's own status, the one its code declares in the registry — see [Error Model](../../../docs/under-the-hood/error-model.md).-- **The `migration` field on a configuration error**: A `PipelexConfigError` carries one when a scan of this machine's configuration directories found something — and only then, so its presence is the test for whether the migration history has anything to say. Whether a command *repairs* it is the separate `would_write` field: true means the configuration is *old*, and the loop is `pipelex-agent migrate --dry-run --format json`, show the user, then `--yes`; false means the block is a diagnosis its `plans` carry and the command would rewrite nothing, so branching on presence alone sends an agent to a run with nothing to do. Its `plans` are the same shape that command emits under its own `plans` key. `error_domain` stays `config`: a domain the hook specification does not know routes to BLOCK, which would stop an agent instead of telling it what to run. See `docs/migration-ledger.md` → "Reporting a stale configuration on a validation error".-- **Init**: All commands that need Pipelex use `make_pipelex_for_agent_cli(library_dirs)`. It catches init errors and routes them through `agent_error()`.+- **Output contract**: Commands with `--format` emit success via `agent_success_formatted(result, markdown_renderer, output_format)` — JSON or a markdown renderer per the explicit `output_format` argument. A failure leaves through `agent_error(message, *, cause, code, params, location, exit_code, **extra)`, or `agent_argument_error(message, *, argument, reason, …)` (`client.argument_invalid`) and `agent_file_error(message, *, path, reason, …)` (`client.file_unreadable`, its reason `not found` or `file_read_failure_reason()`'s for any other `OSError` or a `UnicodeDecodeError`) for the refusals a command makes itself, `agent_unreadable_file_error(error=…)` refusing the file an `OSError` names, which every bundle command's boundary does for its bundle, while an `OSError` naming no file (a refused connection, a timeout) is no file's refusal and reads `runtime.unexpected` (a bundle that is not UTF-8 text is no such refusal: it does not parse, the verdict's `method.syntax` item, through `decode_mthds_text`, and a write `fix bundle` cannot make is its `FixWriteFailedError`, `client.write_failed`, never an `OSError`); each prints the problem, JSON or Markdown by reading the `_agent_cli_error_format` ContextVar, and raises `typer.Exit`. The JSON is `problem_payload()`: the problem's wire members first, then `message` and the command's own members (`**extra`), which never override a member of the problem. `agent_error_validate_bundle` and `agent_error_fix_bundle` report an invalid verdict with its items, the latter coding each remaining error by `FixBundleResult.remaining_error_codes`, the codes the loop's last verdict gave them (`ValidateBundleError.item_codes()`), so its items match `validate`'s. Exceptions that print directly to stdout: `fmt`/`lint` (plxt passthrough) and `inputs --format toml` (the raw TOML template). Markdown renderers: `format_run_markdown` (`run/_output_helpers.py`), `format_validate_markdown` (lifted to the non-CLI `pipelex/pipeline/validation_render.py` so `pipelex-api` can import it without CLI/Typer deps), `format_fix_markdown` (non-CLI `pipelex/pipeline/fixes/fix_render.py`), `_format_init_markdown` (`init_cmd.py`), and `render_problem_markdown` for every failure.+- **Error classification**: the problem is the classification. `agent_problem()` builds it in the operator's view, since whoever runs this CLI runs the runtime: a refusal the command decides names its code and parameters, with the error it caught, if any, giving the diagnostics; a `PipelexError` cause reports its own problem (`to_problem(view=ProblemView.OPERATOR)`), which walks its chain, so a wrapper reports its root fault's code, location, model and provider, and a cause carrying a recovered problem reports it; any other exception is `runtime.unexpected` (`pipelex.errors.failure_problem.failure_problem`, shared with the human CLI), its class, capped message and causes' classes in `diagnostics`. There is no lookup table: `AGENT_ERROR_DOMAINS`, `AGENT_ERROR_HINTS`, `run_failure_fields()` and `extract_validation_errors()` are gone, and `tests/unit/pipelex/cli/test_agent_output_drift.py` refuses a call site passing a member of the retired envelope (`error_type`, `error_domain`, `hint`, `retryable`, `validation_errors`, …) or `argument`/`reason` to plain `agent_error`. When the code a class reports is wrong, the class needs another code. The advice nearest the cause along its chain (`PipelexError.advised_action()`) is printed as the Markdown `💡` tip only, never in the JSON, where the code's `next_step` is the contract; a command whose own footer stands in for it (`validate`'s fix command) prints none. An HTTP surface answers the problem's own status, the one its code declares in the registry — see [Error Model](../../../docs/under-the-hood/error-model.md).+- **The `diagnostics.migration` block on a configuration error**: A `PipelexConfigError` carries one when a scan of this machine's configuration directories found something — and only then, so its presence is the test for whether the migration history has anything to say. Its problem (`pipelex.config.invalid`, domain `operator`) carries it as `diagnostics.migration`, which only the operator view holds. Whether a command *repairs* it is the separate `would_write` field: true means the configuration is *old*, and the loop is `pipelex-agent migrate --dry-run --format json`, show the user, then `--yes`; false means the block is a diagnosis its `plans` carry and the command would rewrite nothing, so branching on presence alone sends an agent to a run with nothing to do. Its `plans` are the same shape that command emits under its own `plans` key. The Markdown renders it as `### Configuration migration` under the diagnostics. A `FormerReleaseConfigError` carries one too, read off the cleanup's dry run (`former_release_pending_migration` in `pipelex/migration/former_release_cleanup.py`), with empty `plans`, since its files are `migrate`'s `former_release` key. See `docs/migration-ledger.md` → "Reporting a stale configuration on a validation error".+- **Init**: All commands that need Pipelex use `make_pipelex_for_agent_cli(library_dirs)`. It catches init errors and routes them through `agent_error()`; a failure whose chain advises nothing is reported as its own problem, its code and its class in `diagnostics.error_class`, with `AGENT_BOOT_RECOVERY_TIP` as its Markdown tip (`agent_error(..., fallback_tip=...)`), the recovery path (`doctor`, `migrate --dry-run` then `--yes`, `init`); no wrapper error stands between the agent and what failed. A configuration error advises for itself, from its migration and else its code (`config_refusal_advice` in `pipelex/base_exceptions.py`, read through `PipelexError.own_advice()`): `init` for a missing file, setting the variable for an unset one, `doctor` for the rest.- **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 envelope 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 `_assemble_error_payload` copies into the envelope the `validation_errors` of the first verdict on the cause's chain of Pipelex errors (`_chain_validation_error_items`, over `iter_pipelex_cause_chain`), so 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`, so a tree past its limits or a symbolic link in the tree is a `ValidateBundleError` too, 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. 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 `FixBundleError` envelope of a fix that could not start (`unfixable_method_result`), 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 envelope 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; a `PipelexConfigError` there carries `AGENT_INIT_FAILURE_HINT`, the hint a failed boot gives (`agent_cli_factory.py`). 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**: `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()` 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.-- **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.-- **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 (`--error-format json`, or `--format json` with no `--error-format`), so the anonymous-statistics notice is then neither printed nor recorded, though the events are still sent. `_assemble_error_payload` and `api_response_error_payload` note the envelope's `error_domain` as the command's, 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`.+- **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.+- **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.+- **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`.- **TOML handling**: Uses `tomlkit` (not `tomllib`) to preserve formatting and inline tables.diff --git a/pipelex/cli/agent_cli/_agent_cli.py b/pipelex/cli/agent_cli/_agent_cli.pyindex ad97a597f..3d46a1eb5 100644--- a/pipelex/cli/agent_cli/_agent_cli.py+++ b/pipelex/cli/agent_cli/_agent_cli.py@@ -6,11 +6,12 @@ from typing import Annotated, Anyimport typerfrom click import Command, Context+from mthds.protocol.problem.registry import CoreCodefrom typer.core import TyperGroupfrom typing_extensions import overridefrom pipelex.cli.agent_cli.commands.agent_cli_factory import silence_logging_for_agent_cli-from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_format+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, start_agent_cli_error_formatfrom pipelex.cli.agent_cli.commands.check_model_cmd import agent_check_model_cmdfrom pipelex.cli.agent_cli.commands.codegen.app import codegen_appfrom pipelex.cli.agent_cli.commands.doctor_cmd import agent_doctor_cmd@@ -82,10 +83,15 @@ class PipelexAgentCLI(TyperGroup):if cmd is None:from pipelex.cli.agent_cli.commands.agent_output import agent_error # ruff: ignore[import-outside-top-level]+ # Click resolves the command before it runs the app callback, so the program's own --error-format, already+ # parsed, is read here.+ root_error_format = ctx.params.get("error_format")+ start_agent_cli_error_format(root_error_format=CliOutputFormat(root_error_format) if root_error_format else None)valid_commands = super().list_commands(ctx)agent_error(f"Unknown command: {cmd_name}",- error_type="UnknownCommandError",+ code=CoreCode.CLIENT_ARGUMENT_INVALID,+ params={"argument": cmd_name, "reason": "not a command of pipelex-agent"},valid_commands=valid_commands,)return cmd@@ -111,7 +117,7 @@ def version_callback(value: bool) -> None: # kw-only: ignore — click invokes#: docstring, which is written for this module's maintainers.AGENT_CLI_HELP = ("The machine-oriented Pipelex CLI, for AI agents, IDE extensions and automation: no prompts and no logs, results on stdout "- "(Markdown or JSON for most commands), and errors as a structured envelope on stderr."+ "(Markdown or JSON for most commands), and errors as a problem document on stderr (Markdown or JSON with --error-format).")@@ -127,11 +133,21 @@ def app_callback(is_eager=True,),] = False,+ error_format: Annotated[+ CliOutputFormat | None,+ typer.Option(+ "--error-format",+ help=(+ "Error output format for every command: markdown or json. "+ "A command's own --error-format wins; without either, a command's --format decides."+ ),+ ),+ ] = None,) -> None:"""Agent CLI callback - no logo, minimal output.Note: there is no ``--log-level`` flag. ``pipelex-agent`` is machine-consumed:- stdout is reserved for the success envelope and stderr for the error envelope.+ stdout is reserved for the success envelope and stderr for the problem a failure reports.Free-floating logs would corrupt those channels, so Python's logging system iscut off process-wide via ``silence_logging_for_agent_cli`` as the very firstaction in this callback — covering every subcommand invocation (including ones@@ -146,10 +162,11 @@ def app_callback(# ``make_pipelex_for_agent_cli`` and ``agent_doctor_cmd`` are kept as defense-in-depth# for direct library callers that bypass this Typer entry point.silence_logging_for_agent_cli()- # Reset the error-format ContextVar at the single choke point every command passes through, so- # a markdown command cannot leak markdown into a later JSON-only command in the same process.- # --format / --error-format commands override this afterwards; JSON-only commands keep the JSON default.- set_agent_cli_error_format(CliOutputFormat.JSON)+ # Start the error-format ContextVar at the single choke point every command passes through, from the program's own+ # --error-format, so a markdown command cannot leak markdown into a later JSON-only command in the same process.+ # A command's own --error-format, then this one, then its --format settle it afterwards; commands without either+ # keep this one, else JSON.+ start_agent_cli_error_format(root_error_format=error_format)app.command(name="init", help="Initialize Pipelex configuration (non-interactive)")(agent_init_cmd)diff --git a/pipelex/cli/agent_cli/commands/agent_cli_factory.py b/pipelex/cli/agent_cli/commands/agent_cli_factory.pyindex 1e816dea1..422ae48a8 100644--- a/pipelex/cli/agent_cli/commands/agent_cli_factory.py+++ b/pipelex/cli/agent_cli/commands/agent_cli_factory.py@@ -1,4 +1,4 @@-"""Factory function for agent CLI commands -- JSON-only error output."""+"""Factory function for agent CLI commands -- a failure to boot reported as its problem."""import loggingimport sys@@ -7,18 +7,26 @@ from pathlib import Pathfrom types import MappingProxyTypefrom typing import Any, NoReturn+from pipelex.base_exceptions import PipelexErrorfrom pipelex.cli.agent_cli.commands.agent_output import agent_errorfrom pipelex.cogt.exceptions import ModelDeckPresetValidationError-from pipelex.migration.exceptions import FormerReleaseConfigErrorfrom pipelex.pipelex import Pipelexfrom pipelex.runtime_hub import RuntimeHubfrom pipelex.system.console_target import ConsoleTargetfrom pipelex.system.runtime import IntegrationMode-from pipelex.system.telemetry.exceptions import TelemetryConfigValidationErrorfrom pipelex.tools.log.log import logfrom pipelex.tools.log.log_levels import LogLevelfrom pipelex.tools.misc.pretty import PrettyPrinter, PrettyPrintMode+#: The tip of a boot that failed with no advice along its chain: the recovery path an agent can run. It is a tip, never+#: a wrapper error, so the problem, its code and its diagnostics' error class stay the failure's own.+AGENT_BOOT_RECOVERY_TIP = (+ "Run 'pipelex-agent doctor' to diagnose the installation and its configuration. An out-of-date configuration is "+ "brought up to date by 'pipelex-agent migrate --dry-run --format json', shown to the user, then "+ "'pipelex-agent migrate --yes'; 'pipelex-agent init' (--global for the home configuration) writes a fresh one "+ "instead, discarding its settings."+)+# Canonical leaf dict for "for any agent-CLI invocation, both Rich-managed channels land# on stderr AND Python's logging system is globally muted from the very first init call."# Consumed by:@@ -128,15 +136,6 @@ AGENT_CLI_CONFIG_OVERRIDES: Mapping[str, Any] = MappingProxyType()-#: The next step of a boot that failed, and of any other failure to read this machine's configuration. It names only-#: commands an agent can run: `pipelex init config` asks questions and can open a browser.-AGENT_INIT_FAILURE_HINT = (- "Initialization failed. Run 'pipelex-agent doctor' to diagnose. An out-of-date configuration is brought up to date by "- "'pipelex-agent migrate --dry-run --format json', shown to the user, then 'pipelex-agent migrate --yes'; "- "'pipelex-agent init' (--global for the home configuration) writes a fresh one instead, discarding its settings"-)--def apply_agent_cli_output_discipline() -> None:"""Reaffirm the agent CLI output contract on the Rich/hub channels post-init.@@ -164,43 +163,37 @@ def apply_agent_cli_output_discipline() -> None:def report_agent_init_failure(*, error: Exception) -> NoReturn:- """Report a failure to initialize Pipelex, or to read the configuration it boots from, as the agent error envelope.+ """Report a failure to initialize Pipelex, or to read the configuration it boots from, as its problem.The one account of a failed boot, given whether the boot raised it or a step reading this machine's configurationbefore the boot did, such as listing a method's tree under the configured limits: the same configuration fails the- same way wherever it is first read.+ same way wherever it is first read. A configuration that does not load, telemetry and a former release's leftovers+ included, reports its own code, its next step, its advice and, when the migration history explains it, the pending+ migration in its diagnostics. A failure whose chain gives no advice is tipped with the boot's recovery path, its+ problem still its own."""- if isinstance(error, TelemetryConfigValidationError):- agent_error(error.message, error_type="TelemetryConfigValidationError", cause=error)- if isinstance(error, FormerReleaseConfigError):- # Its own hint, the class's user_action, rather than the generic one, which offers a reset: the cleanup keeps- # everything but what a former release left, and an agent can run it.- agent_error(error.message, error_type="FormerReleaseConfigError", cause=error)if isinstance(error, ModelDeckPresetValidationError):agent_error(error.message,- error_type="ModelDeckPresetValidationError",cause=error,+ fallback_tip=AGENT_BOOT_RECOVERY_TIP,preset_id=error.preset_id,model_type=str(error.model_type),model_handle=error.model_handle,enabled_backends=sorted(error.enabled_backends),)- agent_error(- f"Pipelex initialization failed: {error}",- error_type=type(error).__name__,- cause=error,- hint=AGENT_INIT_FAILURE_HINT,- )+ if isinstance(error, PipelexError):+ agent_error(error.message, cause=error, fallback_tip=AGENT_BOOT_RECOVERY_TIP)+ agent_error(f"Pipelex initialization failed: {error}", cause=error, fallback_tip=AGENT_BOOT_RECOVERY_TIP)def make_pipelex_for_agent_cli(*, library_dirs: list[str] | list[Path] | None = None, needs_inference: bool = True) -> Pipelex:- """Initialize Pipelex for agent CLI commands with JSON error output.+ """Initialize Pipelex for agent CLI commands, a failure reported as its problem.This is the agent CLI counterpart of ``make_pipelex_for_cli`` in``pipelex.cli.cli_factory``. It catches the same initialization- exceptions but routes them through ``agent_error()`` so the output- is always machine-parseable JSON on stderr.+ exceptions but routes them through ``agent_error()``, so a failure is+ always the problem document on stderr, in the invocation's error format.Stdout / stderr contract: every ``pipelex-agent`` invocation reserves stdoutexclusively for the structured success envelope (JSON via ``--format json``, or@@ -229,7 +222,7 @@ def make_pipelex_for_agent_cli(*, library_dirs: list[str] | list[Path] | None =Initialized Pipelex instance.Raises:- typer.Exit: If initialization fails (after printing JSON error to stderr).+ typer.Exit: If initialization fails (after printing its problem to stderr)."""# Process-global logging cutoff, BEFORE Pipelex.make can trigger any third-party# log line (anthropic/httpx/botocore credential probes, telemetry setup, etc.).@@ -242,8 +235,8 @@ def make_pipelex_for_agent_cli(*, library_dirs: list[str] | list[Path] | None =config_overrides=dict(AGENT_CLI_CONFIG_OVERRIDES),)except Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: report_agent_init_failure() (NoReturn) converts any boot failure into the structured- # error payload, the known configuration failures with their own fields and hints.+ # Agent CLI command boundary: report_agent_init_failure() (NoReturn) converts any boot failure into its problem,+ # the model deck's preset refusal with its own fields.report_agent_init_failure(error=exc)# Silence pipelex logs and Rich pretty-printing so the agent CLI emits only thediff --git a/pipelex/cli/agent_cli/commands/agent_output.py b/pipelex/cli/agent_cli/commands/agent_output.pyindex 0e6c177a0..f082a1e4c 100644--- a/pipelex/cli/agent_cli/commands/agent_output.py+++ b/pipelex/cli/agent_cli/commands/agent_output.py@@ -5,39 +5,57 @@ Two independent format axes:- **Success output** is driven by the per-command ``--format`` Typer option, passedexplicitly to :func:`agent_success_formatted`. No hidden state — every successcall site lives inside a command function that has ``output_format`` in scope.-- **Error reporting** is driven by ``--error-format`` (or by ``--format``'s value- when ``--error-format`` is omitted). Errors must be format-aware from sites far- from any Typer command (init failures in ``agent_cli_factory.py``,- ``UnknownCommandError`` from the Typer group, validation errors in the app- callback, etc.), so the error format is carried in a module-level- ``ContextVar``. JSON is the default so any error raised before a command opts- in stays machine-parseable.--Commands that don't accept ``--format`` (``inputs``, ``fmt``, ``lint``) never-touch the ContextVar and therefore emit JSON errors via the default.+- **Error reporting** is driven by ``--error-format``, given to the command or before it to the+ program itself, else by the command's ``--format``. Errors must be format-aware from sites far+ from any Typer command (init failures in ``agent_cli_factory.py``, an unknown command from the+ Typer group, and so on), so the error format is carried in a module-level ``ContextVar``. JSON+ is the default so any error raised before a command opts in stays machine-parseable.++A failure is reported as a problem document (RFC 9457, the MTHDS core members and Pipelex's), in the operator's view,+since a local CLI is authenticated as the operator of the runtime it boots: its ``code``, ``domain``, ``retry`` and+``next_step`` are what an agent branches on, and ``diagnostics`` holds the error's class and message, the model and+provider of a failed call, and a pending configuration migration. The command's own sentence rides beside the core+members as ``message``, and a command's own facts (``is_valid``, ``bundle_path``, ``valid_commands`` and the like) as+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."""+import osimport sysimport traceback-from collections.abc import Callable+from collections.abc import Callable, Mappingfrom contextvars import ContextVarfrom enum import StrEnumfrom pathlib import Pathfrom typing import Any, NoReturn, castimport typer+from mthds.protocol.problem.models import ProblemItem, ProblemLocation+from mthds.protocol.problem.registry import CoreCodefrom pipelex_sdk.errors import ApiResponseErrorfrom pydantic import ValidationErrorfrom pipelex.base_exceptions import ErrorDomain, PipelexError, ValidationErrorItem, iter_cause_chain, iter_pipelex_cause_chain-from pipelex.cogt.exceptions import find_inference_error_category_in_chain-from pipelex.errors.problem import ProblemView+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 (+ MigrationErrorBlock,+ PipelexProblem,+ ProblemDiagnostics,+ ProblemView,+ make_problem,+)from pipelex.hosted.error_rendering import hosted_refusal_message, hosted_refusal_next_step, sent_verdict-from pipelex.pipe_run.located_failure import find_root_fault-from pipelex.pipeline.exceptions import PipelineExecutionError, ValidateBundleError+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_offrom pipelex.pipeline.validation_render import build_fix_command, count_applicable_fixes, format_validation_error_items_markdown-from pipelex.system.usage_stats.usage_stats_client import note_command_error_domain-from pipelex.system.usage_stats.usage_stats_runs import usage_stats_error_domain_of+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_problemfrom pipelex.tools.misc.json_utils import clean_json_dumps@@ -49,11 +67,15 @@ class CliOutputFormat(StrEnum):# The active **error** format for the current agent-CLI invocation. JSON is the# default so any error raised before a command opts into markdown (the app# callback, unknown-command handling, init failures inside the factory) stays-# machine-parseable. A command with a ``--format`` / ``--error-format`` option-# calls set_agent_cli_error_format() at its start, and agent_error() follows it.+# machine-parseable. The app callback starts it from the program's own+# ``--error-format``; a command with a ``--format`` / ``--error-format`` option+# settles it at its start (use_agent_cli_error_format), and agent_error() follows it.# The success path is NOT routed through this var — it threads ``output_format``# explicitly to agent_success_formatted()._agent_cli_error_format: ContextVar[CliOutputFormat] = ContextVar("agent_cli_error_format", default=CliOutputFormat.JSON)+# The ``--error-format`` given to the program itself, before the command (``pipelex-agent --error-format json validate+# bundle …``), which a command's own ``--format`` does not override.+_agent_cli_root_error_format: ContextVar[CliOutputFormat | None] = ContextVar("agent_cli_root_error_format", default=None)def set_agent_cli_error_format(error_format: CliOutputFormat) -> None:@@ -66,106 +88,501 @@ def get_agent_cli_error_format() -> CliOutputFormat:return _agent_cli_error_format.get()-# Fallback error-classification lookups, keyed by error_type name.-#-# agent_error() reads error_domain / retryable from a PipelexError cause's registry-# code first, and every PipelexError carries one, which decides its domain and its-# retry verdict, and its hint from the advice along the cause's chain. So-# AGENT_ERROR_DOMAINS is the fallback for the error types that carry no code alone:-# builtin and third-party exceptions, and synthetic error_type labels passed straight-# to agent_error(). A PipelexError subclass must NOT appear in it, since its entry-# could never be read; when the domain the code projects is not the one this CLI-# wants, the class needs another code, never an entry here. AGENT_ERROR_HINTS may-# still name a PipelexError subclass: a hint is read only when the cause's chain-# advises no action. Both are enforced by tests/unit/pipelex/cli/test_agent_output_drift.py.-# An unknown model is the author's input fault, whether it is raised bare by the deck check or located-# on its pipe: the next step is to correct the reference, not to diagnose the installation.-_UNKNOWN_MODEL_HINT = (- "Check model name for typos. Use 'pipelex-agent check-model <name> -t <type>' "- "to validate or 'pipelex-agent models -t <type>' to list available models."-)+def start_agent_cli_error_format(*, root_error_format: CliOutputFormat | None = None) -> None:+ """Start an invocation's error format: the program's own ``--error-format``, else JSON.++ Called by the app callback, the one choke point every command passes through, so a format a command chose cannot+ leak into a later command of the same process.+ """+ _agent_cli_root_error_format.set(root_error_format)+ _agent_cli_error_format.set(root_error_format or CliOutputFormat.JSON)+++def use_agent_cli_error_format(*, error_format: CliOutputFormat | None, output_format: CliOutputFormat | None = None) -> None:+ """Settle a command's error format: its own ``--error-format``, else the program's, else its ``--format``, else JSON.++ An ``--error-format`` given anywhere wins over the format the error stream inherits from ``--format``, so a caller+ that forwards ``--error-format`` before the command (as ``mthds-agent`` does) gets it whatever the command's default.+ """+ resolved = error_format or _agent_cli_root_error_format.get() or output_format or CliOutputFormat.JSON+ _agent_cli_error_format.set(resolved)+++# -------------------------------------------------------------------------------------------------+# The problem of a failure+# -------------------------------------------------------------------------------------------------+++def agent_problem(+ *,+ cause: BaseException | None = None,+ code: ErrorCode | None = None,+ params: Mapping[str, Any] | None = None,+ location: ProblemLocation | None = None,+) -> PipelexProblem:+ """The problem a command reports, in the operator's view.++ A command that refuses something itself, an argument or a file it cannot read, names the code and its parameters,+ and the error it caught, if any, gives the diagnostics. Otherwise the problem is the Pipelex error's own, which its+ code decides; and an error that is no Pipelex error is the registry's catch-all, ``runtime.unexpected``.++ Args:+ cause: The error the command caught, when it caught one.+ code: The code of a refusal the command decides itself.+ params: The parameters of that code.+ location: Where the refusal is, when the command knows.++ Returns:+ The problem, in the operator's view.+ """+ if code is not None:+ return make_problem(code=code, view=ProblemView.OPERATOR, params=params, location=location, diagnostics=failure_diagnostics(cause=cause))+ if cause is None:+ return make_problem(code=CoreCode.RUNTIME_UNEXPECTED, view=ProblemView.OPERATOR)+ return failure_problem(error=cause)+++def _advice_of(*, error: BaseException | None) -> str | None:+ """The advice nearest ``error`` along its cause chain, which a local CLI prints as a tip, ``None`` when none is given."""+ if not isinstance(error, PipelexError):+ return None+ advice = error.advised_action()+ 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.++ The command's sentence rides as ``message`` and its facts as further members; none of them replaces a member of the+ problem itself.+ """+ payload = problem.to_wire()+ own_members: dict[str, Any] = {"message": message} if message else {}+ own_members.update(extras)+ for name, value in own_members.items():+ if value is not None and name not in payload:+ payload[name] = value+ return payload+++# -------------------------------------------------------------------------------------------------+# The Markdown rendering+# -------------------------------------------------------------------------------------------------++# Members of a reported problem's own the Markdown leaves out of its Details: the verdict an agent reads off the heading.+_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."""+ where = format_problem_location(location=item.location)+ lines = [f"- `{item.code}`: {item.detail}{f' ({where})' if where else ''}"]+ fix = item.suggested_fix+ if fix is not None:+ lines.append(f" - Suggested fix ({fix.safety}, {fix.fix_code}): {fix.description}")+ return lines+++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)})"]+ if problem.request_id:+ lines.append(f"- Request id: `{problem.request_id}`")+ if problem.pipeline_run_id:+ lines.append(f"- Run: `{problem.pipeline_run_id}`")+ where = format_problem_location(location=problem.location)+ if where:+ lines.append(f"- Location: {where}")+ return lines+++def _migration_lines(*, migration: MigrationErrorBlock) -> list[str]:+ """A pending configuration migration: the command that applies it, whether it would write, and its plans."""+ lines = [+ "",+ "### Configuration migration",+ "",+ f"- Remedy: `{migration.remedy}`",+ f"- Would write: {'yes' if migration.would_write else 'no'}",+ f"- Needs attention: {'yes' if migration.needs_attention else 'no'}",+ ]+ if migration.plans:+ plans = [plan.model_dump(mode="json") for plan in migration.plans]+ lines += ["", "```json", clean_json_dumps(plans, indent=2), "```"]+ return lines+++def _diagnostics_lines(*, diagnostics: ProblemDiagnostics | None) -> list[str]:+ """What the operator's diagnostics add for an agent: the error's class, the model and provider, and a migration."""+ if diagnostics is None:+ return []+ lines = ["", "### Diagnostics", "", f"- Error class: `{diagnostics.error_class}`"]+ if diagnostics.model:+ lines.append(f"- Model: `{diagnostics.model}`")+ provider = diagnostics.provider+ if provider is not None and provider.name:+ said = [f"status {provider.status}"] if provider.status is not None else []+ if provider.code:+ said.append(f"code `{provider.code}`")+ lines.append(f"- Provider: `{provider.name}`" + (f" ({', '.join(said)})" if said else ""))+ if diagnostics.migration is not None:+ lines += _migration_lines(migration=diagnostics.migration)+ return lines+++def _extras_lines(*, extras: Mapping[str, Any]) -> list[str]:+ """The command's own members, under Details: a scalar on its line, anything else as a JSON block."""+ shown = {name: value for name, value in extras.items() if value is not None and name not in _MARKDOWN_SILENT_EXTRAS}+ if not shown:+ return []+ lines = ["", "### Details", ""]+ for name, value in shown.items():+ if isinstance(value, (str, int, float, bool)):+ lines.append(f"- **{name}:** {value}")+ else:+ lines += [f"- **{name}:**", "", "```json", clean_json_dumps(value, indent=2), "```", ""]+ return lines+++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.++ Args:+ problem: The problem, in the operator's view.+ 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 += _diagnostics_lines(diagnostics=problem.diagnostics)+ lines += _extras_lines(extras=extras or {})+ return "\n".join(lines)+++# -------------------------------------------------------------------------------------------------+# Reporting a failure+# -------------------------------------------------------------------------------------------------+++def _emit_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.++ 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)+ if markdown_footer:+ markdown = f"{markdown}\n\n{markdown_footer}"+ print(markdown, file=sys.stderr)+++def agent_error(+ message: str,+ *,+ cause: BaseException | None = None,+ code: ErrorCode | None = None,+ params: Mapping[str, Any] | None = None,+ location: ProblemLocation | None = None,+ exit_code: int = 1,+ fallback_tip: str | None = None,+ **extra: Any,+) -> NoReturn:+ """Report a failure as its problem on stderr, in the active error format, and exit with ``exit_code`` (default 1).++ Dispatches on the active error format (see :func:`use_agent_cli_error_format`): JSON by default, Markdown when the+ invocation asked for it with ``--format`` or ``--error-format``, so every call site follows it for free, including+ sites in factory or unknown-command code that never see a Typer option. The problem is+ :func:`agent_problem`'s: the code the command names for a refusal of its own, else the caught Pipelex error's own,+ else ``runtime.unexpected``.++ Args:+ message: The command's own sentence, which rides beside the problem as ``message``.+ cause: The error the command caught; chained with ``raise ... from``.+ code: The code of a refusal the command decides itself, such as ``client.argument_invalid``.+ params: The parameters of that code.+ location: Where the refusal is, when the command knows.+ exit_code: Process exit code. 1 (default) marks a produced negative+ verdict; the validate commands pass 2 for no-verdict conditions+ (bad args, unresolvable target, setup error) per the 0/1/2 policy.+ fallback_tip: The advice the Markdown prints when ``cause``'s chain gives none, such as the recovery path of a+ boot that failed; like any tip, the JSON problem never carries it.+ **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,+ )+ raise typer.Exit(exit_code) from cause+++def agent_argument_error(+ message: str, *, argument: str, reason: str, cause: BaseException | None = None, exit_code: int = 1, **extra: Any+) -> NoReturn:+ """Refuse an argument of the command, before anything ran: ``client.argument_invalid``, naming the argument and why.++ Args:+ message: The command's own sentence.+ argument: The argument refused, as the command line gave it or as its option names it.+ reason: Why it was refused, in a few words.+ cause: The error the refusal was raised from, when there is one.+ exit_code: Process exit code.+ **extra: The command's own members.+ """+ agent_error(+ message, cause=cause, code=CoreCode.CLIENT_ARGUMENT_INVALID, params={"argument": argument, "reason": reason}, exit_code=exit_code, **extra+ )+++def agent_file_error(+ message: str, *, path: str | Path, reason: str, cause: BaseException | None = None, exit_code: int = 1, **extra: Any+) -> NoReturn:+ """Refuse a local file the command cannot read: ``client.file_unreadable``, naming the file and why.++ Args:+ message: The command's own sentence.+ path: The file, as the command was given it.+ reason: Why it cannot be read, in a few words, such as ``not found``.+ cause: The error the refusal was raised from, when there is one.+ exit_code: Process exit code.+ **extra: The command's own members.+ """+ agent_error(+ message, cause=cause, code=CoreCode.CLIENT_FILE_UNREADABLE, params={"path": str(path), "reason": reason}, exit_code=exit_code, **extra+ )+++def agent_unreadable_file_error(*, error: OSError, exit_code: int = 1) -> NoReturn:+ """Refuse a local file the operating system would not let the command read: ``client.file_unreadable``.++ The file named is the one the error names, and the reason is the system's own (:func:`file_read_failure_reason`).+ An error that names no file, such as a refused connection, a timeout or a TLS failure met while the command ran,+ refuses no file: it is reported as the unexpected failure it is, ``runtime.unexpected``, as the command's boundary+ reports any other exception that is no Pipelex error.++ Args:+ error: The error the system raised.+ exit_code: Process exit code.+ """+ if error.filename is None:+ agent_error(str(error), cause=error, exit_code=exit_code)+ unreadable = os.fsdecode(error.filename) if isinstance(error.filename, (str, bytes)) else str(error.filename)+ reason = file_read_failure_reason(error=error)+ agent_file_error(f"Cannot read '{unreadable}': {reason}", path=unreadable, reason=reason, cause=error, exit_code=exit_code)+++def file_read_failure_reason(*, error: OSError | UnicodeDecodeError) -> str:+ """Why a local file could not be read, in the few words ``client.file_unreadable`` names: the system's own reason."""+ if isinstance(error, UnicodeDecodeError):+ return "not UTF-8 text"+ return error.strerror.lower() if error.strerror else "cannot be opened"+++def agent_success(result: dict[str, Any]) -> None:+ """Print a structured JSON success result to stdout.++ Args:+ result: Dictionary to serialize as JSON.+ """+ print(clean_json_dumps(result, indent=2))+++def agent_success_formatted(+ result: dict[str, Any],+ *,+ markdown_renderer: Callable[[dict[str, Any]], str],+ output_format: CliOutputFormat,+) -> None:+ """Emit a success result in the given CLI output format.++ JSON format serializes ``result`` to stdout; markdown format prints the+ output of ``markdown_renderer(result)`` to stdout.++ The format is passed explicitly (not read from a ContextVar) because every+ call site lives inside a command function that already has its ``--format``+ parameter in scope. Only the error path needs the ContextVar — see+ :func:`agent_error`.++ Args:+ result: The structured result dict (the JSON-mode payload).+ markdown_renderer: Renders ``result`` into a markdown string.+ output_format: The success output format for this command invocation.+ """+ match output_format:+ case CliOutputFormat.JSON:+ agent_success(result)+ case CliOutputFormat.MARKDOWN:+ print(markdown_renderer(result))+++def _validate_fix_footer(+ *,+ items: list[ValidationErrorItem],+ bundle_path: Path,+ library_dirs: list[Path] | None,+ allow_signatures: bool,+) -> str:+ """The footer of the ``validate`` failure Markdown: the exact fix command when items carry a fix, else a pointer to them.++ Mirrors the human ``handle_validate_bundle_error`` panel: the same predicate and the same command shape, with+ ``pipelex-agent`` as the program. Doc and Discord links are left out, being noise for an LLM fixing a ``.mthds`` file.+ """+ fixable_count = count_applicable_fixes(items, bundle_path=bundle_path, library_dirs=library_dirs)+ if fixable_count:+ fix_command = build_fix_command(+ executable="pipelex-agent", bundle_path=bundle_path, library_dirs=library_dirs, allow_signatures=allow_signatures+ )+ return f"💡 {fixable_count} of these errors can be fixed automatically — run: `{fix_command}`"+ return "💡 These errors have no automatic fix — review the messages above and edit the bundle."+++def agent_error_validate_bundle(+ exc: ValidateBundleError,+ *,+ bundle_path: Path,+ library_dirs: list[Path] | None = None,+ allow_signatures: bool = False,+) -> NoReturn:+ """Report the ``validate`` invalid verdict as its problem on stderr, format-aware, and exit 1.++ 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.++ Args:+ exc: The bundle-validation failure to report.+ bundle_path: The bundle file / pipeline directory that failed validation.+ library_dirs: The ``-L/--library-dir`` values, echoed into the markdown fix-command footer.+ allow_signatures: Whether the invocation accepted ``PipeSignature`` placeholders; echoed into+ the markdown fix-command footer so the suggested fix keeps the same leniency.+ """+ items = exc.validation_error_items()+ _emit_problem(+ 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),+ )+ raise typer.Exit(1) from exc+++def agent_error_fix_bundle(*, result: FixBundleResult, bundle_path: str, message: str) -> NoReturn:+ """Report a ``fix bundle`` that left the bundle invalid as its problem on stderr, format-aware, and exit 1.++ 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.++ Args:+ result: The fix loop's result, whose verdict is invalid.+ bundle_path: The bundle file the fix started from, resolved.+ message: The command's own sentence.+ """+ # Each remaining error keeps the code `validate` gives it, which the verdict the loop last read decided.+ items = [+ problem_item_of(item=item, code=item_code.code, params=item_code.params)+ for item, item_code in zip(result.remaining_errors, result.remaining_error_codes, strict=True)+ ]+ problem = make_problem(code=CoreCode.METHOD_INVALID, view=ProblemView.OPERATOR, errors=items or None)+ extras: dict[str, Any] = {+ "bundle_path": bundle_path,+ **result.model_dump(mode="json", exclude_none=True, exclude={"remaining_errors", "remaining_error_codes"}),+ }+ _emit_problem(+ 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})-AGENT_ERROR_HINTS: dict[str, str] = {- # Model/routing errors- "ModelChoiceNotFoundError": _UNKNOWN_MODEL_HINT,- "PipeOperatorModelChoiceError": _UNKNOWN_MODEL_HINT,- "PipeOperatorModelAvailabilityError": "Run 'pipelex-agent doctor' to check available models and verify API keys",- "ModelDeckPresetValidationError": (- "Run 'pipelex-agent doctor' to check model configuration. "- "Update the preset model, configure it in an enabled backend, or enable a supporting backend"- ),- # Validation errors- "PipeValidationError": "Check pipe inputs, outputs, and concept references for consistency",- "FixBundleError": "Inspect remaining_errors and bail_reason, adjust the bundle, then run fix or validate again",- # Execution errors- "PipeExecutionError": "A pipe input validation failed during pipeline execution. Check the error message for the failing model and field.",- # File/input errors- "FileNotFoundError": "Verify the file path exists and is accessible from the current working directory",- "ArgumentError": "Check command usage with 'pipelex-agent <command> --help'",- "JSONDecodeError": "Verify the JSON input is valid (check for trailing commas, unquoted keys, etc.)",- "StdinEnvelopeShapeError": (- "The JSON parsed — its shape is what the envelope contract refuses. In a 'working_memory' envelope each stuff "- "names its concept as the ref string '<domain>.<Code>'; replace a concept object with its ref, or re-pipe the "- "output of a current 'pipelex-agent run --with-memory'."- ),- # Interpreter errors- "MthdsParserError": "Check MTHDS file TOML syntax and ensure all referenced concepts and pipes are defined",- # Configuration/initialization errors- # Three readings, and two fields on this same payload separate them: an absent `migration`- # means the file is wrong, and a present one means the migration history has something to say- # about it — `migration.would_write` then says whether a command repairs it or whether the- # plans are a diagnosis to act on by hand. Never `pipelex init telemetry` on either of the- # last two: that writes a fresh file over settings a migration would have kept.- "TelemetryConfigValidationError": (- "If this payload carries a 'migration' field, read its 'would_write': true means the "- "configuration is out of date and 'pipelex-agent migrate --yes' repairs it — run "- "'pipelex-agent migrate --dry-run --format json' first to show the user what would change. "- "False means the migration would write nothing and its 'plans' name what to correct by hand. "- "Without a 'migration' field, correct the telemetry.toml settings named in the message."- ),- "BinaryNotFoundError": "Install pipelex-tools: uv tool install pipelex-tools",- # Input/type errors- "JsonTypeError": "Input file must be a JSON object {...}, not an array or scalar value",- "TomlError": "Fix the TOML syntax error (the message includes the line and column)",- "BundleError": "Bundle must declare a 'main_pipe' or use the --pipe flag to specify which pipe to run",- "ValidationError": "Check that spec fields match the expected schema for the given type",- "ValueError": "Check that the provided value is valid for the parameter (e.g., --type must be a valid pipe type)",- # Init errors- "InitConfigError": "Check the --config JSON and ensure backend keys match available backends in the template",- # Codegen errors- "CodegenDriftError": (- "Regenerate with 'pipelex-agent codegen types --target <flavor> -o <dir>' (a dev action). "- "Check 'drifts' in this error response for the drifting artifacts and their categories."- ),- "CodegenLockNotFoundError": "Pass the directory that holds codegen.lock, or generate first with 'pipelex-agent codegen types'",- "CodegenLockError": ("The codegen.lock file is unreadable or malformed — remove it, then regenerate with 'pipelex-agent codegen types'"),- # Unknown command- "UnknownCommandError": "Check 'valid_commands' in this error response for available commands",-}--AGENT_ERROR_DOMAINS: dict[str, str] = {- # input = agent can fix (bad .mthds, wrong args, bad JSON)- "FixBundleError": "input",- "FileNotFoundError": "input",- "JSONDecodeError": "input",- "StdinEnvelopeShapeError": "input",- "ArgumentError": "input",- "ValidationError": "input",- "ValueError": "input",- "BundleError": "input",- "UnknownCommandError": "input",- "CodegenDriftError": "input",- "CodegenLockNotFoundError": "input",- # config = environment/config changes needed- "BinaryNotFoundError": "config",- "InitConfigError": "config",-}-def _build_error_source(exc: BaseException) -> list[str]:"""Build a compact source trace from an exception's cause chain.@@ -198,98 +615,6 @@ def _build_error_source(exc: BaseException) -> list[str]:return sources-def _assemble_error_payload(message: str, *, error_type: str, cause: BaseException | None, extra: dict[str, Any]) -> dict[str, Any]:- """Build the structured error payload shared by the JSON and markdown renderers.-- Sources ``hint`` / ``retryable`` / ``error_domain`` / ``error_code`` / ``error_category`` /- ``model`` / ``provider`` from a ``PipelexError`` cause first: its code, its chain's advice and- its problem in the operator's view, falling back to the lookup dicts for error types that cannot- self-describe. ``extra`` is merged last and overrides everything.-- ``migration`` comes from the problem's diagnostics too, and it is the one field here that an agent- is meant to *act* on rather than classify by: its presence says the configuration is stale rather- than wrong, and the loop it opens is ``pipelex-agent migrate --dry-run --format json`` followed by- ``--yes``. Emitted only when the error carries one, so branching on its presence is the- whole test.-- ``validation_errors`` comes from the cause's chain as well, whenever a verdict on it carries any: a command that- refuses an invalid bundle (a run refused before any pipe ran, for one) hands the agent the same- located items ``validate`` gives, each with its pipe, its field and its fix, rather than only the- summary sentence. They are the items :func:`extract_validation_errors` projects, dumped the same way.- """- error_json: dict[str, Any] = {- "error": True,- "error_type": error_type,- "message": message,- }-- # Extract structured data from a PipelexError cause when available: its code decides the domain and the verdict- report_hint: str | None = None- report_next_step: str | None = None- report_retryable: bool | None = None- report_category: str | None = None- report_domain: str | None = None- report_code: str | None = None- report_extras: dict[str, Any] = {}-- if isinstance(cause, PipelexError):- # Every classification is read off the one problem, so a cause that reports a problem of its own, such as one- # recovered across a transport boundary, gives its code, its domain and its verdict together with its step.- problem = cause.to_problem(view=ProblemView.OPERATOR)- advised_action = cause.advised_action()- report_hint = advised_action.detail if advised_action is not None and advised_action.detail else None- # The code's next step, as the operator reads it, which whoever runs this CLI is: the hint when nothing advises.- report_next_step = problem.next_step.detail- report_retryable = problem.is_retryable- report_category = find_inference_error_category_in_chain(cause)- report_domain = ErrorDomain.from_problem_domain(problem.effective_domain)- report_code = problem.code- diagnostics = problem.diagnostics- if diagnostics is not None and diagnostics.model:- report_extras["model"] = diagnostics.model- if diagnostics is not None and diagnostics.provider is not None and diagnostics.provider.name:- report_extras["provider"] = diagnostics.provider.name- if diagnostics is not None and diagnostics.migration is not None:- report_extras["migration"] = diagnostics.migration.model_dump(mode="json")- chain_validation_errors = _chain_validation_error_items(error=cause)- if chain_validation_errors:- report_extras["validation_errors"] = [item.model_dump(mode="json", exclude_none=True) for item in chain_validation_errors]-- # hint: the chain's advice, else the lookup dict, else the code's next step- hint = report_hint or AGENT_ERROR_HINTS.get(error_type) or report_next_step- if hint:- error_json["hint"] = hint-- # retryable: the report's verdict, which its code decides (only emit when True)- if report_retryable:- error_json["retryable"] = True-- # error_domain: report-first (its code's projection), lookup dict as fallback for an error that carries no code- domain = report_domain or AGENT_ERROR_DOMAINS.get(error_type)- if domain:- error_json["error_domain"] = domain- # The command's usage statistics carry the same classification, never the error itself.- note_command_error_domain(error_domain=usage_stats_error_domain_of(domain=domain))-- # error_code: the cause's registry code, the member a hosted refusal carries as well; an uncoded cause names none- if report_code:- error_json["error_code"] = report_code-- # error_category: from report when available- if report_category:- error_json["error_category"] = report_category-- # model/provider from report- error_json.update(report_extras)-- if cause is not None:- error_json["error_source"] = _build_error_source(cause)-- # **extra overrides everything- error_json.update(extra)- return error_json--# 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@@ -314,7 +639,7 @@ def _typed_validation_items(*, validation_errors: Any) -> list[ValidationErrorItdef _render_error_markdown(payload: dict[str, Any]) -> str:- """Render an assembled error payload as agent-readable markdown.+ """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 JSONdump under Details, so an agent reads a refused run's items the way it reads an invalid verdict's.@@ -347,134 +672,47 @@ def _render_error_markdown(payload: dict[str, Any]) -> str:return "\n".join(lines)-def _agent_error_json(message: str, *, error_type: str, cause: BaseException | None, extra: dict[str, Any], exit_code: int = 1) -> NoReturn:- """Print a structured JSON error to stderr and exit with ``exit_code`` (default 1)."""- payload = _assemble_error_payload(message, error_type=error_type, cause=cause, extra=extra)- print(clean_json_dumps(payload, indent=2), file=sys.stderr)- raise typer.Exit(exit_code) from cause---def agent_error_markdown(message: str, *, error_type: str, cause: BaseException | None = None, exit_code: int = 1, **extra: Any) -> NoReturn:- """Print a markdown-rendered error to stderr and exit with ``exit_code`` (default 1).-- The markdown sibling of :func:`agent_error`'s JSON path: an error-type- heading, the message body, the hint as a tip callout, and structured fields- under a Details section. ``error_source`` (internal stack frames) is- deliberately omitted from markdown — the field remains in the JSON envelope- for programmatic consumers.-- Args:- message: Human-readable error message.- error_type: Error class name for programmatic matching.- cause: Optional exception to chain with ``raise ... from``.- exit_code: Process exit code. 1 (default) marks a produced negative- verdict; 2 marks a no-verdict condition (bad args, unresolvable- target, setup error) — the validate surface's 0/1/2 policy.- **extra: Additional fields merged into the payload.- """- payload = _assemble_error_payload(message, error_type=error_type, cause=cause, extra=extra)- print(_render_error_markdown(payload), file=sys.stderr)- raise typer.Exit(exit_code) from cause---def agent_error(message: str, *, error_type: str, cause: BaseException | None = None, exit_code: int = 1, **extra: Any) -> NoReturn:- """Emit a structured error to stderr and exit with ``exit_code`` (default 1).-- Dispatches on the active error format (see :func:`set_agent_cli_error_format`):- JSON by default, markdown when a command has opted in via ``--format`` or- ``--error-format``. All existing ``agent_error(...)`` call sites therefore- follow the active error format for free — including sites in factory /- unknown-command code that never see the Typer option.-- Args:- message: Human-readable error message.- error_type: Error class name for programmatic matching.- cause: Optional exception to chain with ``raise ... from``.- exit_code: Process exit code. 1 (default) marks a produced negative- verdict; the validate commands pass 2 for no-verdict conditions- (bad args, unresolvable target, setup error) per the 0/1/2 policy.- **extra: Additional fields merged into the payload.- Can override the auto-added ``hint`` field.- """+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:- _agent_error_json(message, error_type=error_type, cause=cause, extra=extra, exit_code=exit_code)+ print(clean_json_dumps(payload, indent=2), file=sys.stderr)case CliOutputFormat.MARKDOWN:- agent_error_markdown(message, error_type=error_type, cause=cause, exit_code=exit_code, **extra)---def agent_success(result: dict[str, Any]) -> None:- """Print a structured JSON success result to stdout.-- Args:- result: Dictionary to serialize as JSON.- """- print(clean_json_dumps(result, indent=2))+ print(_render_error_markdown(payload), file=sys.stderr)-def agent_success_formatted(- result: dict[str, Any],- *,- markdown_renderer: Callable[[dict[str, Any]], str],- output_format: CliOutputFormat,-) -> None:- """Emit a success result in the given CLI output format.-- JSON format serializes ``result`` to stdout; markdown format prints the- output of ``markdown_renderer(result)`` to stdout.+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``.- The format is passed explicitly (not read from a ContextVar) because every- call site lives inside a command function that already has its ``--format``- parameter in scope. Only the error path needs the ContextVar — see- :func:`agent_error`.+ ``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:- result: The structured result dict (the JSON-mode payload).- markdown_renderer: Renders ``result`` into a markdown string.- output_format: The success output format for this command invocation.- """- match output_format:- case CliOutputFormat.JSON:- agent_success(result)- case CliOutputFormat.MARKDOWN:- print(markdown_renderer(result))---def run_failure_fields(*, error: PipelineExecutionError) -> dict[str, Any]:- """The fields an agent reads off a failed run, beside the report-derived ones.-- ``pipe_code`` and ``pipe_stack`` name the pipe that failed and its path from the entry pipe.- ``cause_type`` and ``cause_message`` are the root fault's identity and its own message, not- those of the wrapper right under the ``PipelineExecutionError``, which is the pipe router's or- a bridge's and says nothing about what went wrong.+ 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."""- fields: dict[str, Any] = {- "pipe_code": error.pipe_code,- "pipe_stack": error.pipe_stack,+ 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,}- cause = error.__cause__- if cause is None:- return fields- root_fault = find_root_fault(error=cause)- if root_fault is None:- fields["cause_type"] = type(cause).__name__- fields["cause_message"] = str(cause)- else:- fields["cause_type"] = type(root_fault).__name__- fields["cause_message"] = root_fault.message- return fields---def _chain_validation_error_items(*, error: BaseException) -> list[ValidationErrorItem]:- """The items of the first invalid verdict along ``error``'s cause chain, ``error`` itself included; empty when none.-- The walk stops at the first exception that is not a Pipelex error, as every walk reading a failure's chain does: a- foreign exception raised from an earlier, handled verdict is a new failure, whose envelope lists none of its items.- """- for node in iter_pipelex_cause_chain(error):- if isinstance(node, ValidateBundleError):- return node.validation_error_items()- return []+ 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 causedef _non_empty_string(*, value: Any) -> str | None:@@ -495,21 +733,16 @@ def _string_list(*, value: Any) -> list[str] | None: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.- 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.+ 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 stepit appends, which ``hint`` carries. On a failed run the runner's reason is located at the failing pipe and itspath, ``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 thehosted plane authors in front of the runner (a refused key, a rate limit, a runner it cannot reach), gets thenext 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); never the hint keyed on the- runner's class, which names a local command that cannot fix a remote refusal.+ 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 verdictpipelex-sdk decides for every refusal is not read, since it fills an unsent member from its own table. The one@@ -534,7 +767,6 @@ def api_response_error_payload(*, error: ApiResponseError) -> dict[str, Any]:payload["retryable"] = Trueif sent.error_domain:payload["error_domain"] = sent.error_domain- note_command_error_domain(error_domain=usage_stats_error_domain_of(domain=sent.error_domain))if error_category := _non_empty_string(value=problem.get("error_category")):payload["error_category"] = error_categoryif error.validation_errors:@@ -558,115 +790,15 @@ def api_response_error_payload(*, error: ApiResponseError) -> dict[str, Any]: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` for the one error a hosted 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.+ 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)- 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)+ # 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---def extract_validation_errors(exc: ValidateBundleError) -> list[dict[str, Any]]:- """Project a ``ValidateBundleError`` into the CLI ``validation_errors`` JSON array.-- Thin adapter over ``ValidateBundleError.validation_error_items`` — the shared builder,- same one feeding the ``/validate`` verdict and the problem's items — so the CLI- and API structured shapes can never drift. Each typed item is dumped to a- plain dict with unset fields dropped (``exclude_none``), matching the- machine-first agent-CLI envelope; the entries carry ``category``,- ``error_type``, ``message``, and whatever identity / ``source`` fields the- underlying error populated. Each pipe whose dry run failed becomes its own- located ``dry_run`` item, and a parse-level failure that carries only a- message becomes one ``blueprint_validation`` residual. So the envelope's- ``validation_errors[]`` is non-empty on every invalid verdict (the- structured-info invariant) — never a bare message.-- Args:- exc: The ValidateBundleError to extract errors from.-- Returns:- List of dicts, each with at minimum ``category`` and ``message``.- """- return [item.model_dump(mode="json", exclude_none=True) for item in exc.validation_error_items()]---def _render_validate_bundle_markdown(- items: list[ValidationErrorItem],- *,- bundle_path: Path,- library_dirs: list[Path] | None,- allow_signatures: bool,-) -> str:- """Compose the agent ``validate`` failure markdown: heading, bundle, prose items, fix-aware footer.-- Mirrors the human ``handle_validate_bundle_error`` panel: the structured items become prose- (via the shared :func:`format_validation_error_items_markdown`) rather than a JSON dump, and- the footer either names the exact ``pipelex-agent fix bundle`` command when items carry a- suggested fix, or points at the messages above when nothing is auto-fixable. Doc/Discord- links are deliberately dropped — they are noise for an LLM fixing a ``.mthds`` file.- """- lines: list[str] = ["# Bundle validation failed", "", f"**Bundle:** `{bundle_path}`", "", format_validation_error_items_markdown(items)]-- # A hint needs an action behind it (disease E): when items carry a suggested fix, name the exact- # fix command — same predicate and command shape as the human footer — instead of the boilerplate- # class-level hint that the JSON envelope keeps.- fixable_count = count_applicable_fixes(items, bundle_path=bundle_path, library_dirs=library_dirs)- if fixable_count:- fix_command = build_fix_command(- executable="pipelex-agent", bundle_path=bundle_path, library_dirs=library_dirs, allow_signatures=allow_signatures- )- lines += ["", f"💡 {fixable_count} of these errors can be fixed automatically — run: `{fix_command}`"]- else:- lines += ["", "💡 These errors have no automatic fix — review the messages above and edit the bundle."]- return "\n".join(lines)---def agent_error_validate_bundle(- exc: ValidateBundleError,- *,- bundle_path: Path,- library_dirs: list[Path] | None = None,- allow_signatures: bool = False,-) -> NoReturn:- """Emit an agent-CLI bundle-validation failure to stderr, format-aware, and exit 1.-- The dedicated dispatcher for the ``validate`` invalid verdict (the sibling of- :func:`agent_error` for this one error type). It keeps the two streams honest to the- workspace's "format follows consumer" doctrine:-- - **markdown** renders the structured items as prose with per-item ``💡 Suggested fix`` lines- and a fix-aware footer, mirroring the human ``handle_validate_bundle_error`` panel;- - **JSON** emits the *exact same* structured envelope as before — ``is_valid`` / ``bundle_path``- / ``validation_errors`` — because software consumers (hooks pin ``--format json``) branch on- those structured fields; the machine contract must not change.-- Args:- exc: The bundle-validation failure to report.- bundle_path: The bundle file / pipeline directory that failed validation.- library_dirs: The ``-L/--library-dir`` values, echoed into the markdown fix-command footer.- allow_signatures: Whether the invocation accepted ``PipeSignature`` placeholders; echoed into- the markdown fix-command footer so the suggested fix keeps the same leniency.- """- match get_agent_cli_error_format():- case CliOutputFormat.JSON:- _agent_error_json(- exc.message,- error_type="ValidateBundleError",- cause=exc,- extra={"is_valid": False, "bundle_path": str(bundle_path), "validation_errors": extract_validation_errors(exc)},- exit_code=1,- )- case CliOutputFormat.MARKDOWN:- items = exc.validation_error_items()- markdown = _render_validate_bundle_markdown(items, bundle_path=bundle_path, library_dirs=library_dirs, allow_signatures=allow_signatures)- print(markdown, file=sys.stderr)- raise typer.Exit(1) from excdiff --git a/pipelex/cli/agent_cli/commands/bundle_path_resolver.py b/pipelex/cli/agent_cli/commands/bundle_path_resolver.pyindex 93dd3c074..beff9f679 100644--- a/pipelex/cli/agent_cli/commands/bundle_path_resolver.py+++ b/pipelex/cli/agent_cli/commands/bundle_path_resolver.py@@ -3,13 +3,13 @@``validate bundle`` and ``fix bundle`` must resolve the user's ``path`` argument identically: fix must patch exactlywhat validate judged, a bundle file or a method's whole folder. The shared core (``pipelex.cli.judged_target``, over``pipelex.cli.bundle_target_resolution``) owns the decision, the one every command taking a bundle path makes,-``run bundle`` included; this wrapper owns the agent error envelopes of a target that names nothing to judge, and of-a configuration that cannot be read before the boot.+``run bundle`` included; this wrapper owns the agent problems of a target that names nothing to judge, and of a+configuration that cannot be read before the boot."""from pipelex.base_exceptions import PipelexConfigErrorfrom pipelex.cli.agent_cli.commands.agent_cli_factory import report_agent_init_failure-from pipelex.cli.agent_cli.commands.agent_output import agent_error+from pipelex.cli.agent_cli.commands.agent_output import agent_argument_error, agent_errorfrom pipelex.cli.bundle_target_resolution import BundleTargetResolutionErrorfrom pipelex.cli.judged_target import JudgedBundleTarget, resolve_judged_targetfrom pipelex.libraries.exceptions import EmptyMethodTreeError@@ -22,9 +22,9 @@ def resolve_bundle_target(path: str, *, library_dir: list[str] | None) -> Judgeda method: it needs no pipe to start at. The folder is prepended to the library directories; a fix may write anybundle of its tree, being user-passed.- A folder holding no bundle and a path that is neither a ``.mthds`` file nor a directory produce no verdict: exit 2- via ``agent_error``. A configuration that does not validate, read for the tree's limits before the boot, is- reported as the failed boot it would have been.+ A folder holding no bundle, its problem the error's own, and a path that is neither a ``.mthds`` file nor a+ directory, ``client.argument_invalid``, produce no verdict: exit 2 via ``agent_error``. A configuration that does+ not validate, read for the tree's limits before the boot, is reported as the failed boot it would have been.Both ``path`` and each ``library_dir`` entry have ``~`` expanded before resolution, so home-relative inputs behavelike every other CLI path argument.@@ -40,15 +40,16 @@ def resolve_bundle_target(path: str, *, library_dir: list[str] | None) -> Judgedtry:result = resolve_judged_target(path=path, library_dir=library_dir)except EmptyMethodTreeError as exc:- agent_error(exc.message, error_type=type(exc).__name__, cause=exc, exit_code=2)+ agent_error(exc.message, cause=exc, exit_code=2)except PipelexConfigError as exc:report_agent_init_failure(error=exc)if isinstance(result, BundleTargetResolutionError):- agent_error(+ agent_argument_error(f"'{result.input_path}' is not a .mthds file or directory. "f"Use 'validate pipe <code>' for pipe codes, or 'validate bundle <path>' for .mthds files/directories.",- error_type="ArgumentError",+ argument=str(result.input_path),+ reason="not a .mthds file or a directory",exit_code=2,)return resultdiff --git a/pipelex/cli/agent_cli/commands/check_model_cmd.py b/pipelex/cli/agent_cli/commands/check_model_cmd.pyindex 3a9c93dae..fb66f6816 100644--- a/pipelex/cli/agent_cli/commands/check_model_cmd.py+++ b/pipelex/cli/agent_cli/commands/check_model_cmd.py@@ -5,7 +5,7 @@ from typing import Annotated, Anyimport typerfrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_cli-from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, agent_error, agent_success, set_agent_cli_error_format+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, agent_argument_error, agent_error, agent_success, use_agent_cli_error_formatfrom pipelex.cogt.models.exceptions import ModelReferenceParseErrorfrom pipelex.cogt.models.model_reference import ModelReferencefrom pipelex.cogt.models.model_reference_check import ModelCheckCategory@@ -62,7 +62,7 @@ def agent_check_model_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,) -> None:"""Check if a model reference is valid and suggest alternatives if not.@@ -71,7 +71,7 @@ def agent_check_model_cmd(model deck by the rule a validation applies, and on failure provides fuzzysuggestions and wrong-sigil hints."""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)try:make_pipelex_for_agent_cli(needs_inference=False)@@ -109,9 +109,9 @@ def agent_check_model_cmd(# `agent_error` has already reported is caught again below and reported twice.raiseexcept ModelReferenceParseError as exc:- agent_error(f"Invalid model reference: {exc}", error_type="ArgumentError", cause=exc)+ agent_argument_error(f"Invalid model reference: {exc}", argument=name, reason="not a model reference", cause=exc)except Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(f"Failed to check model: {exc}", error_type=type(exc).__name__, cause=exc)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(f"Failed to check model: {exc}", cause=exc)finally:Pipelex.teardown_if_needed()diff --git a/pipelex/cli/agent_cli/commands/codegen/check_cmd.py b/pipelex/cli/agent_cli/commands/codegen/check_cmd.pyindex 9e8beb084..6c3bf07ca 100644--- a/pipelex/cli/agent_cli/commands/codegen/check_cmd.py+++ b/pipelex/cli/agent_cli/commands/codegen/check_cmd.py@@ -18,11 +18,12 @@ from pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,agent_error,agent_success_formatted,- set_agent_cli_error_format,+ use_agent_cli_error_format,)from pipelex.codegen.check import run_codegen_checkfrom pipelex.codegen.exceptions import CodegenLockErrorfrom pipelex.codegen.lock import CODEGEN_LOCK_FILENAME+from pipelex.errors.registry.pipelex_codes import PipelexErrorCodedef agent_codegen_check_cmd(@@ -36,7 +37,7 @@ def agent_codegen_check_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,) -> None:"""Verify generated artifacts are current, offline — no engine, no network, no API key.@@ -45,7 +46,7 @@ def agent_codegen_check_cmd(pipelex-agent codegen check ./generated/pipelex-agent codegen check ./generated/ --format json"""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)root_path = Path(root).expanduser()try:@@ -54,7 +55,8 @@ def agent_codegen_check_cmd(if not report.lock_found:agent_error(f"No {CODEGEN_LOCK_FILENAME} found in '{root_path}' — nothing to check.",- error_type="CodegenLockNotFoundError",+ code=PipelexErrorCode.CODEGEN_LOCK_NOT_FOUND,+ params={"path": str(root_path)},exit_code=2,root=str(root_path),)@@ -64,7 +66,8 @@ def agent_codegen_check_cmd(drifts = [drift.model_dump(mode="json") for drift in report.drifts]agent_error(f"Generated artifacts in '{root_path}' have drifted.",- error_type="CodegenDriftError",+ code=PipelexErrorCode.CODEGEN_DRIFTED,+ params={"artifacts": [drift.path for drift in report.drifts]},exit_code=1,root=str(root_path),is_current=False,@@ -83,11 +86,11 @@ def agent_codegen_check_cmd(except CodegenLockError as exc:# No verdict: the lock exists but cannot be read, so nothing can be checked.- agent_error(exc.message, error_type=type(exc).__name__, cause=exc, exit_code=2, root=str(root_path))+ agent_error(exc.message, cause=exc, exit_code=2, root=str(root_path))except Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(str(exc), cause=exc)def _format_codegen_check_markdown(result: dict[str, Any]) -> str:diff --git a/pipelex/cli/agent_cli/commands/codegen/types_cmd.py b/pipelex/cli/agent_cli/commands/codegen/types_cmd.pyindex 7ada455f0..e12880cff 100644--- a/pipelex/cli/agent_cli/commands/codegen/types_cmd.py+++ b/pipelex/cli/agent_cli/commands/codegen/types_cmd.py@@ -18,8 +18,9 @@ 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_file_error,agent_success_formatted,- set_agent_cli_error_format,+ use_agent_cli_error_format,)from pipelex.cli.commands.crate_loading import load_normalized_cratefrom pipelex.cli.exceptions import BundleClosureEmptyError@@ -60,7 +61,7 @@ def agent_codegen_types_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,) -> None:"""Project the crate's concept set into typed artifacts for the chosen target.@@ -73,7 +74,7 @@ def agent_codegen_types_cmd(pipelex-agent codegen types ./my_pipes/ --target ts-zod -o ./generated/pipelex-agent codegen types --target python-structures -L ./shared_pipes/ --format json"""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)output_root = Path(output_dir).expanduser()make_pipelex_for_agent_cli(needs_inference=False)@@ -86,13 +87,14 @@ def agent_codegen_types_cmd(crate = load_normalized_crate(library_dirs=combined_dirs or None)except (LibraryLoadingError, PipeLibraryError) as exc:# Negative verdict: the library is structurally invalid, so no crate can be produced.- agent_error(f"Cannot resolve — the library is invalid: {exc}", error_type=type(exc).__name__, cause=exc, exit_code=1)+ agent_error(f"Cannot resolve — the library is invalid: {exc}", cause=exc, exit_code=1)except FileNotFoundError as exc:# No verdict: the closure could not even be assembled.- agent_error(f"Cannot resolve — {exc}", error_type="FileNotFoundError", cause=exc, exit_code=2)+ missing_path = str(exc.filename) if exc.filename else ", ".join(str(combined_dir) for combined_dir in combined_dirs)+ agent_file_error(f"Cannot resolve — {exc}", path=missing_path, reason="not found", cause=exc, exit_code=2)except BundleClosureEmptyError as exc:# No verdict: the closure holds no bundle to read.- agent_error(f"Cannot resolve — {exc}", error_type=type(exc).__name__, cause=exc, exit_code=2)+ agent_error(f"Cannot resolve — {exc}", cause=exc, exit_code=2)generation_report.describe(crate=crate)emitted = emit_types(crate, target=target)@@ -122,8 +124,8 @@ def agent_codegen_types_cmd(raiseexcept Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(str(exc), cause=exc)finally:Pipelex.teardown_if_needed()diff --git a/pipelex/cli/agent_cli/commands/doctor_cmd.py b/pipelex/cli/agent_cli/commands/doctor_cmd.pyindex 948be63cf..2636e7951 100644--- a/pipelex/cli/agent_cli/commands/doctor_cmd.py+++ b/pipelex/cli/agent_cli/commands/doctor_cmd.py@@ -10,7 +10,7 @@ from pipelex.cli.agent_cli.commands.agent_cli_factory import (apply_agent_cli_output_discipline,silence_logging_for_agent_cli,)-from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, agent_error, agent_success, set_agent_cli_error_format+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, agent_error, agent_success, use_agent_cli_error_formatfrom pipelex.cli.commands.doctor_cmd import (LOCAL_RUNS_ONLY_NOTE,BackendFileReport,@@ -245,7 +245,7 @@ def agent_doctor_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,) -> None:"""Check Pipelex configuration health and output a diagnostic report.@@ -272,7 +272,7 @@ def agent_doctor_cmd(def _do_agent_doctor_cmd(*, global_: bool, output_format: CliOutputFormat, error_format: CliOutputFormat | None) -> None:"""The report itself; ``agent_doctor_cmd`` is the entry point that releases what this configured."""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)# Process-global logging cutoff, BEFORE setup_doctor_runtime / check_* can trigger# any third-party log line.silence_logging_for_agent_cli()@@ -347,9 +347,9 @@ def _do_agent_doctor_cmd(*, global_: bool, output_format: CliOutputFormat, errorbackend_file_reports = {}except Exception as exc: # ruff: ignore[blind-except]# Agent CLI command boundary: agent_error() (NoReturn) converts any genuinely- # unexpected failure into the structured error payload. PipelexConfigError is+ # unexpected failure into its problem. PipelexConfigError is# handled by the inner arm above and never reaches here.- agent_error(f"Health check failed unexpectedly: {exc}", error_type=type(exc).__name__, cause=exc)+ agent_error(f"Health check failed unexpectedly: {exc}", cause=exc)# Pin stdout discipline regardless of bootstrap path (broken-config branch never# installed a hub or configured log — the helper guards both internally).diff --git a/pipelex/cli/agent_cli/commands/fix/bundle_cmd.py b/pipelex/cli/agent_cli/commands/fix/bundle_cmd.pyindex 96c978985..c37674a1a 100644--- a/pipelex/cli/agent_cli/commands/fix/bundle_cmd.py+++ b/pipelex/cli/agent_cli/commands/fix/bundle_cmd.py@@ -1,7 +1,6 @@"""Agent CLI fix bundle command."""import asyncio-import sysfrom pathlib import Pathfrom typing import Annotated, Any, NoReturn@@ -10,10 +9,13 @@ import typerfrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_clifrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,+ agent_argument_error,agent_error,+ agent_error_fix_bundle,+ agent_file_error,agent_success_formatted,- get_agent_cli_error_format,- set_agent_cli_error_format,+ agent_unreadable_file_error,+ use_agent_cli_error_format,)from pipelex.cli.agent_cli.commands.bundle_path_resolver import resolve_bundle_targetfrom pipelex.cli.judged_target import fix_judged_target@@ -22,7 +24,7 @@ from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityErrorfrom pipelex.pipelex import Pipelexfrom pipelex.pipeline.exceptions import ValidateBundleErrorfrom pipelex.pipeline.fixes.fix_loop import FixBundleResult, unfixable_method_result-from pipelex.pipeline.fixes.fix_render import format_fix_markdown, format_fix_still_invalid_markdown+from pipelex.pipeline.fixes.fix_render import format_fix_markdownfrom pipelex.pipeline.fixes.planner import KNOWN_FIX_CODES@@ -34,9 +36,10 @@ def _normalize_rule_codes(codes: list[str] | None) -> tuple[str, ...] | None:def _reject_invalid_rule_filters(*, select_codes: tuple[str, ...] | None, ignore_codes: tuple[str, ...] | None) -> None:if select_codes is not None and ignore_codes is not None:- agent_error(+ agent_argument_error("--select and --ignore are mutually exclusive",- error_type="ArgumentError",+ argument="--ignore",+ reason="contradicts --select",exit_code=2,known_fix_codes=sorted(KNOWN_FIX_CODES),)@@ -50,9 +53,10 @@ def _reject_invalid_rule_filters(*, select_codes: tuple[str, ...] | None, ignoreif unknown_codes:known_codes = ", ".join(sorted(KNOWN_FIX_CODES))unknown = ", ".join(unknown_codes)- agent_error(+ agent_argument_error(f"Unknown fix rule code(s): {unknown}. Known codes: {known_codes}",- error_type="ArgumentError",+ argument=unknown,+ reason="unknown fix rule code",exit_code=2,unknown_fix_codes=unknown_codes,known_fix_codes=sorted(KNOWN_FIX_CODES),@@ -62,7 +66,8 @@ def _reject_invalid_rule_filters(*, select_codes: tuple[str, ...] | None, ignoredef _result_payload(result: FixBundleResult, *, bundle_path: str) -> dict[str, Any]:return {"bundle_path": str(Path(bundle_path).resolve()),- **result.model_dump(mode="json", exclude_none=True),+ # The remaining errors' codes are the problem's items' when the fix fails, never a member of the result.+ **result.model_dump(mode="json", exclude_none=True, exclude={"remaining_error_codes"}),}@@ -77,19 +82,11 @@ def _failure_message(result: FixBundleResult) -> str:def _emit_still_invalid(*, result: FixBundleResult, bundle_path: str) -> NoReturn:- """Emit the still-invalid verdict, format-aware, and exit 1.+ """Report the still-invalid verdict, format-aware, and exit 1.- JSON keeps the exact FixBundleError envelope (the result fields + bail_reason via the payload); markdown renders the- remaining errors as prose with their 💡 lines (mirroring the human still-invalid panel) instead of a raw JSON dump- of the details.+ The problem is the method's that does not validate, its faults the remaining errors."""- payload = _result_payload(result, bundle_path=bundle_path)- match get_agent_cli_error_format():- case CliOutputFormat.JSON:- agent_error(_failure_message(result), error_type="FixBundleError", exit_code=1, **payload)- case CliOutputFormat.MARKDOWN:- print(format_fix_still_invalid_markdown(result, bundle_path=str(payload["bundle_path"])), file=sys.stderr)- raise typer.Exit(1)+ agent_error_fix_bundle(result=result, bundle_path=str(Path(bundle_path).resolve()), message=_failure_message(result))def fix_bundle_cmd(@@ -126,14 +123,14 @@ def fix_bundle_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,) -> None:"""Fix a bundle file (.mthds) or a method's folder in place.A folder is judged whole, every bundle of its method tree, as `validate bundle` judges it."""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)select_codes = _normalize_rule_codes(select_codes_raw)ignore_codes = _normalize_rule_codes(ignore_codes_raw)@@ -166,15 +163,21 @@ def fix_bundle_cmd(if not allow_signatures and result.is_runnable is False:raise typer.Exit(1)return++ # Still-invalid verdict: the problem of the method that does not validate, its faults the remaining errors._emit_still_invalid(result=result, bundle_path=bundle_path)except FileNotFoundError as exc:- agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc, exit_code=2)+ agent_file_error(f"Bundle file not found: {bundle_path}", path=bundle_path, reason="not found", cause=exc, exit_code=2)++ except OSError as exc:+ # A method file the loop could not read; a write it could not make is a `FixWriteFailedError`, never an OSError.+ # An error naming no file, a connection or a timeout, is the unexpected failure the boundary reports.+ agent_unreadable_file_error(error=exc, exit_code=2)except PipeOperatorModelChoiceError as exc:agent_error(exc.message,- error_type="PipeOperatorModelChoiceError",cause=exc,exit_code=2,pipe_code=exc.pipe_code,@@ -191,14 +194,14 @@ def fix_bundle_cmd(availability_extra["fallback_list"] = exc.fallback_listif exc.pipe_stack:availability_extra["pipe_stack"] = exc.pipe_stack- agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, exit_code=2, **availability_extra)+ agent_error(exc.message, cause=exc, exit_code=2, **availability_extra)except typer.Exit:raiseexcept Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc, exit_code=2)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(str(exc), cause=exc, exit_code=2)finally:Pipelex.teardown_if_needed()diff --git a/pipelex/cli/agent_cli/commands/fix/function_names_cmd.py b/pipelex/cli/agent_cli/commands/fix/function_names_cmd.pyindex 4b06e5d11..3c3c83970 100644--- a/pipelex/cli/agent_cli/commands/fix/function_names_cmd.py+++ b/pipelex/cli/agent_cli/commands/fix/function_names_cmd.py@@ -5,7 +5,7 @@ from typing import Annotated, Anyimport typer-from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, agent_error, agent_success_formatted, set_agent_cli_error_format+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, agent_error, agent_success_formatted, use_agent_cli_error_formatfrom pipelex.migration.exceptions import FunctionNamesMigrationErrorfrom pipelex.migration.function_names import FunctionNamesMigration, migrate_function_names_in_directoryfrom pipelex.migration.function_names_render import format_function_names_markdown@@ -37,16 +37,16 @@ def fix_function_names_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,) -> None:"""Rewrite every flat PipeFunc function_name of a method as its import path; branch on `is_complete`."""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)directory = Path(path)try:migration = migrate_function_names_in_directory(directory=directory, is_dry_run=dry_run)except FunctionNamesMigrationError as exc:- agent_error(exc.message, error_type=type(exc).__name__, cause=exc, exit_code=2)+ agent_error(exc.message, cause=exc, exit_code=2)agent_success_formatted(_payload(migration=migration, directory=directory, is_dry_run=dry_run),markdown_renderer=lambda _payload_dict: format_function_names_markdown(migration=migration, directory=path, is_dry_run=dry_run),diff --git a/pipelex/cli/agent_cli/commands/init_cmd.py b/pipelex/cli/agent_cli/commands/init_cmd.pyindex 513b1160d..5d634c6f2 100644--- a/pipelex/cli/agent_cli/commands/init_cmd.py+++ b/pipelex/cli/agent_cli/commands/init_cmd.py@@ -10,9 +10,12 @@ from tomlkit import tablefrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,+ agent_argument_error,agent_error,+ agent_file_error,agent_success_formatted,- set_agent_cli_error_format,+ file_read_failure_reason,+ use_agent_cli_error_format,)from pipelex.cli.commands.init.backends import get_selected_backend_keys, update_backends_in_tomlfrom pipelex.cli.commands.init.config_files import init_config@@ -21,11 +24,13 @@ from pipelex.cli.commands.init.setup_path import describe_project_execution_shadfrom pipelex.cli.commands.init.ui.backends_ui import get_backend_options_from_tomlfrom pipelex.cli.commands.login.api_key_store import find_pipelex_api_keyfrom pipelex.cogt.models.deck_manifest import stamp_kit_manifests+from pipelex.errors.registry.pipelex_codes import PipelexErrorCodefrom pipelex.hosted.client_factory import PIPELEX_API_KEY_ENV_KEYfrom pipelex.hosted.run_config import RunExecutionfrom pipelex.kit.paths import get_kit_configs_dirfrom pipelex.system.configuration.config_loader import config_managerfrom pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAME, TELEMETRY_PROJECT_TEMPLATE_FILE_NAME+from pipelex.tools.misc.file_utils import path_labelfrom pipelex.tools.misc.toml_utils import load_toml_with_tomlkit, save_toml_to_path@@ -46,18 +51,23 @@ def _parse_config_arg(config_arg: str | None) -> dict[str, Any]:result: dict[str, Any] = json.loads(config_arg)return resultexcept json.JSONDecodeError as exc:- agent_error(f"Failed to parse inline JSON config: {exc}", error_type="JSONDecodeError", cause=exc)+ agent_argument_error(f"Failed to parse inline JSON config: {exc}", argument="--config", reason="not valid JSON", cause=exc)else:try:with open(config_arg, encoding="utf-8") as file:loaded: Any = json.load(file)if not isinstance(loaded, dict):- agent_error(f"Config file must contain a JSON object, got {type(loaded).__name__}", error_type="JSONDecodeError")+ agent_argument_error(+ f"Config file must contain a JSON object, got {type(loaded).__name__}", argument="--config", reason="not a JSON object"+ )return cast("dict[str, Any]", loaded)except FileNotFoundError as exc:- agent_error(f"Config file not found: {config_arg}", error_type="FileNotFoundError", cause=exc)+ agent_file_error(f"Config file not found: {config_arg}", path=config_arg, reason="not found", cause=exc)except json.JSONDecodeError as exc:- agent_error(f"Failed to parse config file JSON: {exc}", error_type="JSONDecodeError", cause=exc)+ agent_argument_error(f"Failed to parse config file JSON: {exc}", argument="--config", reason="the file is not valid JSON", cause=exc)+ except (OSError, UnicodeDecodeError) as exc:+ reason = file_read_failure_reason(error=exc)+ agent_file_error(f"Config file cannot be read: {config_arg}: {reason}", path=config_arg, reason=reason, cause=exc)return {}@@ -110,17 +120,19 @@ def _resolve_execution(*, config: dict[str, Any]) -> RunExecution:try:execution = RunExecution(requested)except ValueError:- agent_error(+ agent_argument_error(f"Unknown execution: {requested!r}. Available: {', '.join(RunExecution)}",- error_type="ArgumentError",+ argument="execution",+ reason="unknown execution",)if execution.is_hosted:local_only_keys = [key for key in _LOCAL_ONLY_CONFIG_KEYS if key in config]if local_only_keys:- agent_error(+ agent_argument_error(f"{', '.join(local_only_keys)} configure the backends of runs on this machine, which a hosted setup does not: "'drop them, or set "execution": "local"',- error_type="ArgumentError",+ argument=", ".join(local_only_keys),+ reason="configures runs on this machine, which a hosted setup has none of",)return execution@@ -139,10 +151,11 @@ def _resolve_target_dir(*, global_: bool) -> Path:# Default: project-level .pipelex/ at detected project rootproject_root = config_manager.project_rootif project_root is None:- agent_error(+ agent_argument_error("No project root found (no .git, pyproject.toml, etc. in parent directories). ""Use --global/-g to target the home configuration directory (~/.pipelex/, or PIPELEX_HOME).",- error_type="ArgumentError",+ argument="--global",+ reason="omitted outside a project",)return project_root / ".pipelex"@@ -227,7 +240,11 @@ def _configure_backends(List of enabled backend keys."""if not backends_toml_path.exists():- agent_error("backends.toml not found after config initialization", error_type="InitConfigError")+ agent_error(+ "backends.toml not found after config initialization",+ code=PipelexErrorCode.CONFIG_FILE_MISSING,+ params={"surface": "inference", "file": path_label(path=backends_toml_path)},+ )requested_backends: list[str] | None = config.get("backends")@@ -241,9 +258,10 @@ def _configure_backends(for backend_key in requested_backends:if backend_key not in available_keys:- agent_error(+ agent_argument_error(f"Unknown backend: {backend_key}. Available: {', '.join(available_keys)}",- error_type="ArgumentError",+ argument="backends",+ reason="unknown backend",)# Build selected indices from requested backend keys@@ -272,7 +290,11 @@ def _configure_routing(selected_backend_keys: list[str], *, config: dict[str, Anrouting_profiles_toml_path = target_dir / "inference" / "routing_profiles.toml"if not routing_profiles_toml_path.exists():- agent_error("routing_profiles.toml not found after config initialization", error_type="InitConfigError")+ agent_error(+ "routing_profiles.toml not found after config initialization",+ code=PipelexErrorCode.CONFIG_FILE_MISSING,+ params={"surface": "inference", "file": path_label(path=routing_profiles_toml_path)},+ )toml_doc = load_toml_with_tomlkit(routing_profiles_toml_path)@@ -305,15 +327,17 @@ def _configure_routing(selected_backend_keys: list[str], *, config: dict[str, Anprimary_backend: str | None = config.get("primary_backend")if primary_backend is None:- agent_error(+ agent_argument_error(f"primary_backend is required when multiple backends are selected ({', '.join(selected_backend_keys)})",- error_type="ArgumentError",+ argument="primary_backend",+ reason="required when several backends are selected",)if primary_backend not in selected_backend_keys:- agent_error(+ agent_argument_error(f"primary_backend '{primary_backend}' is not in the selected backends: {', '.join(selected_backend_keys)}",- error_type="ArgumentError",+ argument="primary_backend",+ reason="not among the selected backends",)# Build custom_routing profile@@ -378,7 +402,7 @@ def agent_init_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,) -> None:"""Initialize Pipelex configuration (non-interactive).@@ -412,7 +436,7 @@ def agent_init_cmd(off; project init drops in a commented-out template that inherits the user's globaltelemetry settings via layered loading. Edit `telemetry.toml` to enable destinations."""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)try:# Parse config@@ -476,5 +500,5 @@ def agent_init_cmd(except typer.Exit:raiseexcept Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(f"Initialization failed: {exc}", error_type=type(exc).__name__, cause=exc)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(f"Initialization failed: {exc}", cause=exc)diff --git a/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py b/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.pyindex fedf9fb6f..976b909ba 100644--- a/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py+++ b/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py@@ -9,7 +9,14 @@ import typerfrom pipelex.base_exceptions import PipelexConfigErrorfrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_cli, report_agent_init_failure-from pipelex.cli.agent_cli.commands.agent_output import agent_error, extract_validation_errors+from pipelex.cli.agent_cli.commands.agent_output import (+ CliOutputFormat,+ agent_argument_error,+ agent_error,+ agent_file_error,+ agent_unreadable_file_error,+ use_agent_cli_error_format,+)from pipelex.cli.agent_cli.commands.inputs._inputs_core import emit_inputs_result, inputs_corefrom pipelex.cli.bundle_target_resolution import BundleTargetResolutionError, FolderReading, resolve_bundle_target_corefrom pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError@@ -40,11 +47,15 @@ def inputs_bundle_cmd(bool,typer.Option("--explicit", help="Emit the ceremonial {concept, content} envelope form instead of the light values"),] = False,+ error_format: Annotated[+ CliOutputFormat | None,+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to json)"),+ ] = None,) -> None:"""Generate an example inputs template from a bundle file (.mthds) or pipeline directory.Outputs the JSON envelope (or raw TOML with --format toml) to stdout on- success, JSON to stderr on error with exit code 1.+ success, and the problem to stderr on error with exit code 1, as JSON unless --error-format says markdown.Examples:pipelex-agent inputs bundle my_bundle.mthds@@ -54,22 +65,26 @@ def inputs_bundle_cmd(pipelex-agent inputs bundle pipeline_01/ --format tomlpipelex-agent inputs bundle pipeline_01/ --explicit"""+ use_agent_cli_error_format(error_format=error_format)# A folder is read as its method tree: the pipe is the one named, else the one the method starts at, as `run bundle`# reads it. A folder whose pipe was named loads as the method's library, with no entry bundle, as `run bundle` runs it.try:target = resolve_bundle_target_core(path, library_dir=library_dir, reading=FolderReading.ENTRY_PIPE, pipe_override=pipe)except MethodEntryError as exc:- agent_error(exc.message, error_type=type(exc).__name__, cause=exc)+ # No pipe to start at is the run's refusal and no verdict: its problem carries its own code.+ agent_error(exc.message, cause=exc)except ValidateBundleError as exc:- agent_error(exc.message, error_type="ValidateBundleError", cause=exc, validation_errors=extract_validation_errors(exc))+ # A tree refused or past this machine's limits is the invalid verdict, its items the problem's errors.+ agent_error(exc.message, cause=exc)except PipelexConfigError as exc:# Listing the tree reads its limits from the configuration, before the boot would.report_agent_init_failure(error=exc)if isinstance(target, BundleTargetResolutionError):- agent_error(+ agent_argument_error(f"'{path}' is not a .mthds file or directory. "f"Use 'inputs pipe <code>' for pipe codes, or 'inputs bundle <path>' for .mthds files/directories.",- error_type="ArgumentError",+ argument=path,+ reason="not a .mthds file or a directory",)bundle_path = target.bundle_pathlibrary_dirs = target.library_dirs@@ -80,16 +95,20 @@ def inputs_bundle_cmd(emit_inputs_result(result, template_format=template_format, explicit=explicit)except FileNotFoundError as exc:- agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc)+ agent_file_error(f"Bundle file not found: {bundle_path}", path=str(bundle_path), reason="not found", cause=exc)++ except OSError as exc:+ # A method file this machine would not let the command read: the file, never a fault of the method. An error+ # naming no file, a connection or a timeout, is the unexpected failure the boundary reports.+ agent_unreadable_file_error(error=exc)except ValidateBundleError as exc:- # A failing dry run rides validation_errors as one located dry_run item per failing pipe.- agent_error(exc.message, error_type="ValidateBundleError", cause=exc, validation_errors=extract_validation_errors(exc))+ # A failing dry run is the problem's errors, one located item per failing pipe.+ agent_error(exc.message, cause=exc)except PipeOperatorModelChoiceError as exc:agent_error(exc.message,- error_type="PipeOperatorModelChoiceError",cause=exc,pipe_code=exc.pipe_code,model_type=str(exc.model_type),@@ -105,14 +124,14 @@ def inputs_bundle_cmd(availability_extra["fallback_list"] = exc.fallback_listif exc.pipe_stack:availability_extra["pipe_stack"] = exc.pipe_stack- agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)+ agent_error(exc.message, cause=exc, **availability_extra)except typer.Exit:raiseexcept Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(str(exc), cause=exc)finally:Pipelex.teardown_if_needed()diff --git a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py b/pipelex/cli/agent_cli/commands/inputs/method_cmd.pyindex 604e91b2e..632864820 100644--- a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py+++ b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py@@ -9,7 +9,7 @@ from typing import Annotated, Anyimport typerfrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_cli-from pipelex.cli.agent_cli.commands.agent_output import agent_error, extract_validation_errors+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, agent_error, agent_file_error, use_agent_cli_error_formatfrom pipelex.cli.agent_cli.commands.inputs._inputs_core import emit_inputs_result, inputs_corefrom pipelex.cli.method_resolver import resolve_method_targetfrom pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError@@ -41,12 +41,16 @@ def inputs_method_cmd(bool,typer.Option("--explicit", help="Emit the ceremonial {concept, content} envelope form instead of the light values"),] = False,+ error_format: Annotated[+ CliOutputFormat | None,+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to json)"),+ ] = None,) -> None:"""Generate an example inputs template for an installed method.Resolves the method by name, finds its .mthds bundle, and generates inputs.Outputs the JSON envelope (or raw TOML with --format toml) to stdout on- success, JSON to stderr on error with exit code 1.+ success, and the problem to stderr on error with exit code 1, as JSON unless --error-format says markdown.Examples:pipelex-agent inputs method my-method@@ -54,6 +58,7 @@ def inputs_method_cmd(pipelex-agent inputs method my-method --format tomlpipelex-agent inputs method my-method --explicit"""+ use_agent_cli_error_format(error_format=error_format)try:pipe_code, method_library_dirs, method = resolve_method_target(method_name=name,@@ -62,9 +67,9 @@ def inputs_method_cmd(raise_ref_errors=True,)except MethodRefError as exc:- # Method-reference failure (parse, fetch, location, bounds, refusal): report it through- # the structured error envelope instead of the human CLI's plain red text.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc)+ # Method-reference failure (parse, fetch, location, bounds, refusal): report it as its problem+ # instead of the human CLI's plain red text.+ agent_error(str(exc), cause=exc)bundle_path: Path | None = Noneif method.mthds_files:@@ -82,16 +87,15 @@ def inputs_method_cmd(emit_inputs_result(result, template_format=template_format, explicit=explicit)except FileNotFoundError as exc:- agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc)+ agent_file_error(f"Bundle file not found: {bundle_path}", path=str(bundle_path), reason="not found", cause=exc)except ValidateBundleError as exc:- # A failing dry run rides validation_errors as one located dry_run item per failing pipe.- agent_error(exc.message, error_type="ValidateBundleError", cause=exc, validation_errors=extract_validation_errors(exc))+ # A failing dry run is the problem's errors, one located item per failing pipe.+ agent_error(exc.message, cause=exc)except PipeOperatorModelChoiceError as exc:agent_error(exc.message,- error_type="PipeOperatorModelChoiceError",cause=exc,pipe_code=exc.pipe_code,model_type=str(exc.model_type),@@ -107,11 +111,11 @@ def inputs_method_cmd(availability_extra["fallback_list"] = exc.fallback_listif exc.pipe_stack:availability_extra["pipe_stack"] = exc.pipe_stack- agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)+ agent_error(exc.message, cause=exc, **availability_extra)except Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(str(exc), cause=exc)finally:Pipelex.teardown_if_needed()diff --git a/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py b/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.pyindex 73b79e57c..9001d6336 100644--- a/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py+++ b/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py@@ -9,7 +9,13 @@ from typing import Annotated, Anyimport typerfrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_cli-from pipelex.cli.agent_cli.commands.agent_output import agent_error, extract_validation_errors+from pipelex.cli.agent_cli.commands.agent_output import (+ CliOutputFormat,+ agent_argument_error,+ agent_error,+ agent_file_error,+ use_agent_cli_error_format,+)from pipelex.cli.agent_cli.commands.inputs._inputs_core import emit_inputs_result, inputs_corefrom pipelex.cli.exceptions import ExportedPipeAmbiguousErrorfrom pipelex.cli.method_resolver import resolve_pipe_from_exports@@ -38,11 +44,15 @@ def inputs_pipe_cmd(bool,typer.Option("--explicit", help="Emit the ceremonial {concept, content} envelope form instead of the light values"),] = False,+ error_format: Annotated[+ CliOutputFormat | None,+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to json)"),+ ] = None,) -> None:"""Generate an example inputs template for a pipe by code.Outputs the JSON envelope (or raw TOML with --format toml) to stdout on- success, JSON to stderr on error with exit code 1.+ success, and the problem to stderr on error with exit code 1, as JSON unless --error-format says markdown.Examples:pipelex-agent inputs pipe my_pipe@@ -50,24 +60,22 @@ def inputs_pipe_cmd(pipelex-agent inputs pipe my_pipe --format tomlpipelex-agent inputs pipe my_pipe --explicit"""+ use_agent_cli_error_format(error_format=error_format)# Helpful error if the user passes a path instead of a pipe codetarget_path = Path(pipe_code)if target_path.is_dir() or is_pipelex_file(target_path) or pipe_code.endswith(MTHDS_EXTENSION):- agent_error(+ agent_argument_error(f"'{pipe_code}' looks like a file path or directory. "f"Use 'inputs bundle {pipe_code}' for bundles/directories, or 'inputs pipe <code>' for pipe codes.",- error_type="ArgumentError",+ argument=pipe_code,+ reason="a path where a pipe code is expected",)# Check installed methods' exports for additional library dirstry:export_dirs = resolve_pipe_from_exports(pipe_code)except ExportedPipeAmbiguousError as exc:- agent_error(- f"Ambiguous pipe code '{pipe_code}': {exc}",- error_type="ArgumentError",- cause=exc,- )+ agent_error(f"Ambiguous pipe code '{pipe_code}': {exc}", cause=exc)if export_dirs:if library_dir is None:library_dir = export_dirs@@ -82,16 +90,15 @@ def inputs_pipe_cmd(emit_inputs_result(result, template_format=template_format, explicit=explicit)except FileNotFoundError as exc:- agent_error(f"File not found: {exc}", error_type="FileNotFoundError", cause=exc)+ agent_file_error(f"File not found: {exc}", path=str(exc.filename or exc), reason="not found", cause=exc)except ValidateBundleError as exc:- # A failing dry run rides validation_errors as one located dry_run item per failing pipe.- agent_error(exc.message, error_type="ValidateBundleError", cause=exc, validation_errors=extract_validation_errors(exc))+ # A failing dry run is the problem's errors, one located item per failing pipe.+ agent_error(exc.message, cause=exc)except PipeOperatorModelChoiceError as exc:agent_error(exc.message,- error_type="PipeOperatorModelChoiceError",cause=exc,pipe_code=exc.pipe_code,model_type=str(exc.model_type),@@ -107,14 +114,14 @@ def inputs_pipe_cmd(availability_extra["fallback_list"] = exc.fallback_listif exc.pipe_stack:availability_extra["pipe_stack"] = exc.pipe_stack- agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)+ agent_error(exc.message, cause=exc, **availability_extra)except typer.Exit:raiseexcept Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(str(exc), cause=exc)finally:Pipelex.teardown_if_needed()diff --git a/pipelex/cli/agent_cli/commands/migrate_cmd.py b/pipelex/cli/agent_cli/commands/migrate_cmd.pyindex dbe1f6896..3f60020ed 100644--- a/pipelex/cli/agent_cli/commands/migrate_cmd.py+++ b/pipelex/cli/agent_cli/commands/migrate_cmd.py@@ -35,9 +35,9 @@ import typerfrom pipelex.cli.agent_cli.commands.agent_cli_factory import silence_logging_for_agent_clifrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,- agent_error,+ agent_argument_error,agent_success_formatted,- set_agent_cli_error_format,+ use_agent_cli_error_format,)from pipelex.cli.commands.migrate_cmd import describe_opfrom pipelex.migration.former_release_cleanup import FormerReleaseCleanup, FormerReleaseFileCleanup, clean_former_release@@ -60,7 +60,7 @@ def agent_migrate_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,) -> None:"""Migrate this machine's Pipelex configuration files to the current schema.@@ -69,12 +69,13 @@ def agent_migrate_cmd(surface's ledger over every file it claims, and — with ``--yes`` — rewrites what changed,backing up each original beside itself."""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)silence_logging_for_agent_cli()if dry_run and yes:- agent_error(+ agent_argument_error("--dry-run and --yes contradict each other: one refuses to write, the other authorizes it",- error_type="ArgumentError",+ argument="--yes",+ reason="contradicts --dry-run",exit_code=2,)diff --git a/pipelex/cli/agent_cli/commands/models_cmd.py b/pipelex/cli/agent_cli/commands/models_cmd.pyindex f48a921fa..f63658581 100644--- a/pipelex/cli/agent_cli/commands/models_cmd.py+++ b/pipelex/cli/agent_cli/commands/models_cmd.py@@ -5,7 +5,7 @@ from typing import Annotatedimport typerfrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_cli-from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, agent_error, agent_success, set_agent_cli_error_format+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, agent_error, agent_success, use_agent_cli_error_formatfrom pipelex.cogt.models.model_listing import ModelCategory, format_models_markdown, list_modelsfrom pipelex.pipelex import Pipelex@@ -25,7 +25,7 @@ def agent_models_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,) -> None:"""List available model presets, aliases, and waterfalls.@@ -33,7 +33,7 @@ def agent_models_cmd(Outputs model configuration that an agent needs to reference when building pipelines.Default output is markdown; use --format json for structured JSON."""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)try:make_pipelex_for_agent_cli(needs_inference=False)@@ -51,7 +51,7 @@ def agent_models_cmd(# JSON documents and a machine consumer parsing it got "Extra data".raiseexcept Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(f"Failed to list models: {exc}", error_type=type(exc).__name__, cause=exc)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(f"Failed to list models: {exc}", cause=exc)finally:Pipelex.teardown_if_needed()diff --git a/pipelex/cli/agent_cli/commands/plxt_passthrough.py b/pipelex/cli/agent_cli/commands/plxt_passthrough.pyindex 289adc65f..dc4916d28 100644--- a/pipelex/cli/agent_cli/commands/plxt_passthrough.py+++ b/pipelex/cli/agent_cli/commands/plxt_passthrough.py@@ -5,6 +5,7 @@ import shutilimport subprocess # ruff: ignore[suspicious-subprocess-import]import typer+from mthds.protocol.problem.registry import CoreCodefrom pipelex.cli.agent_cli.commands.agent_output import agent_errorfrom pipelex.system.usage_stats.usage_stats_contract import UsageStatsEnvVar@@ -23,8 +24,9 @@ def run_plxt(subcommand: str, *, file_path: str) -> None:plxt_path = shutil.which("plxt")if plxt_path is None:agent_error(- message="plxt binary not found. Install via: uv tool install pipelex-tools",- error_type="BinaryNotFoundError",+ "plxt binary not found. Install via: uv tool install pipelex-tools",+ code=CoreCode.CLIENT_TOOL_MISSING,+ params={"tool": "plxt"},)# The command's usage statistics are pipelex-agent's own, so the plxt it delegates to reports none of its own.diff --git a/pipelex/cli/agent_cli/commands/run/_run_hosted.py b/pipelex/cli/agent_cli/commands/run/_run_hosted.pyindex cea011e61..e1b309868 100644--- a/pipelex/cli/agent_cli/commands/run/_run_hosted.py+++ b/pipelex/cli/agent_cli/commands/run/_run_hosted.py@@ -3,6 +3,10 @@The run commands share this module for every step that differs from a local run: where the run executes (theflags, then `[run] execution`), the flags a hosted run refuses, the run itself through `pipelex.hosted`, and theenvelope its result or its failure is reported in. 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."""from __future__ import annotations@@ -14,12 +18,13 @@ from typing import TYPE_CHECKING, Any, NoReturn, castfrom mthds.protocol.exceptions import PipelineRequestErrorfrom pipelex_sdk.errors import ApiResponseError, RunFailedError-from pipelex.base_exceptions import PipelexConfigError, PipelexError-from pipelex.cli.agent_cli.commands.agent_cli_factory import AGENT_INIT_FAILURE_HINT+from pipelex.base_exceptions import PipelexErrorfrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,+ agent_argument_error,agent_error,agent_error_api_response,+ agent_error_hosted_envelope,agent_success_formatted,)from pipelex.cli.agent_cli.commands.run._output_helpers import build_run_output, format_run_markdown@@ -55,18 +60,21 @@ def resolve_agent_run_execution(*, runner: RunExecution | None, hosted: bool | Nfrom_flag = RunExecution.from_hosted_flag(hosted=hosted)requested = runner or from_flagif runner is not None and from_flag is not None and runner is not from_flag:- agent_error(f"--runner {runner} contradicts --{from_flag}: name one place for the run to execute", error_type="ArgumentError")+ agent_argument_error(+ f"--runner {runner} contradicts --{from_flag}: name one place for the run to execute",+ argument="--runner",+ reason=f"contradicts --{from_flag}",+ )try:execution = resolve_run_execution(requested=requested)- except PipelexConfigError as exc:- # The same configuration a local boot reads, so the same next step a failed boot gives.- agent_error(exc.message, error_type=type(exc).__name__, cause=exc, hint=AGENT_INIT_FAILURE_HINT)except PipelexError as exc:- agent_error(exc.message, error_type=type(exc).__name__, cause=exc)+ # A configuration error is the same one a local boot reads, so its problem gives the same next step.+ agent_error(exc.message, cause=exc)if base_url is not None and not execution.is_hosted:- agent_error(+ agent_argument_error("--base-url names the hosted API a hosted run calls, and this run executes locally. Add --runner hosted, or drop --base-url.",- error_type="ArgumentError",+ argument="--base-url",+ reason="only applies to a hosted run",)return execution@@ -75,15 +83,16 @@ def refuse_local_only_flags(*, dry_run: bool, mock_inputs: bool) -> None:"""Refuse the flags that steer this machine's runtime, which a hosted run never boots."""named = [flag for flag, given in (("--dry-run", dry_run), ("--mock-inputs", mock_inputs)) if given]if named:- agent_error(+ agent_argument_error(f"{' and '.join(named)} only apply to a run on this machine, and this run executes on the hosted API. ""Pass --runner local to run it here.",- error_type="ArgumentError",+ argument=" and ".join(named),+ reason="only applies to a run on this machine",)def agent_error_hosted(*, error: PipelineRequestError | HostedRunError, exit_code: int = 1) -> NoReturn:- """Report a hosted run's failure in the agent error envelope, and exit with `exit_code`.+ """Report a hosted run's failure in the envelope a hosted run had before the problem, and exit with `exit_code`.A refusal the hosted API answered carries its problem document and goes through `agent_error_api_response`, whoseenvelope matches a local failure's. Every other failure is reported as `pipelex.hosted.error_rendering` reads it,@@ -111,7 +120,7 @@ def agent_error_hosted(*, error: PipelineRequestError | HostedRunError, exit_codif 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(view.message, error_type=view.error_type, cause=error, exit_code=exit_code, **extra)+ agent_error_hosted_envelope(view.message, error_type=view.error_type, cause=error, exit_code=exit_code, **extra)def build_hosted_run_output(*, outcome: HostedRunOutcome, with_memory: bool) -> dict[str, Any]:@@ -151,7 +160,7 @@ def run_hosted_for_agent(*, request: HostedRunRequest, base_url: str | None, wittry:client = make_hosted_client(base_url=base_url)except PipelexError as exc:- agent_error(exc.message, error_type=type(exc).__name__, cause=exc)+ agent_error(exc.message, cause=exc)started_run_ids: list[str] = []def _record_start(*, pipeline_run_id: str) -> None:@@ -166,7 +175,8 @@ def run_hosted_for_agent(*, request: HostedRunRequest, base_url: str | None, witexcept (PipelineRequestError, HostedRunError) as exc:agent_error_hosted(error=exc)except Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc)+ # 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)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/cli/agent_cli/commands/run/bundle_cmd.py b/pipelex/cli/agent_cli/commands/run/bundle_cmd.pyindex 81ce053d4..e8976dd91 100644--- a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/bundle_cmd.py@@ -4,19 +4,23 @@ from __future__ import annotationsimport asyncioimport functools+import osfrom pathlib import Pathfrom typing import TYPE_CHECKING, Annotated, Anyimport typer+from mthds.protocol.problem.registry import CoreCode-from pipelex.base_exceptions import PipelexConfigError+from pipelex.base_exceptions import PipelexConfigError, iter_cause_chainfrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_cli, report_agent_init_failurefrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,+ agent_argument_error,agent_error,+ agent_file_error,agent_success_formatted,- run_failure_fields,- set_agent_cli_error_format,+ agent_unreadable_file_error,+ use_agent_cli_error_format,)from pipelex.cli.agent_cli.commands.run._output_helpers import format_run_markdownfrom pipelex.cli.agent_cli.commands.run._run_core import run_pipeline_core@@ -36,7 +40,7 @@ from pipelex.hosted.exceptions import HostedRunSourceErrorfrom pipelex.hosted.hosted_run import HostedRunRequestfrom pipelex.hosted.run_config import RunExecution # ruff: ignore[typing-only-first-party-import] - typer reads the --runner annotation at runtimefrom pipelex.mthds_parsing.helpers import is_pipelex_file-from pipelex.mthds_parsing.parser import MthdsParser+from pipelex.mthds_parsing.parser import MthdsParser, decode_mthds_textfrom pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityErrorfrom pipelex.pipelex import Pipelexfrom pipelex.pipeline.exceptions import MethodEntryError, PipelineExecutionError, ValidateBundleError@@ -46,6 +50,14 @@ if TYPE_CHECKING:from mthds.method_tree.models import MethodTree+def _file_error_in_chain(*, error: ValidateBundleError) -> OSError | None:+ """The error the system raised about a file while the tree was listed, when that is why it could not be; else None."""+ for node in iter_cause_chain(error):+ if isinstance(node, OSError) and node.filename is not None:+ return node+ return None++def run_bundle_cmd(path: Annotated[str,@@ -89,7 +101,7 @@ def run_bundle_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,runner: Annotated[RunExecution | None,@@ -117,11 +129,11 @@ def run_bundle_cmd(pipelex-agent run bundle pipeline_01/ --format jsonpipelex-agent run bundle pipeline_01/ --runner hosted"""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)# Validate --mock-inputs requires --dry-runif mock_inputs and not dry_run:- agent_error("--mock-inputs requires --dry-run", error_type="ArgumentError")+ agent_argument_error("--mock-inputs requires --dry-run", argument="--mock-inputs", reason="requires --dry-run")pipe_code: str | None = pipebundle_path: str | None = None@@ -141,10 +153,10 @@ def run_bundle_cmd(try:folder_run = resolve_method_folder_run(directory=target_path, pipe_override=pipe)except ValidateBundleError as exc:- agent_error(exc.message, error_type="ValidateBundleError", cause=exc)+ agent_error(exc.message, cause=exc)except MethodEntryError as exc:- # No pipe to start at is the run's refusal and no verdict: its envelope carries its own code.- agent_error(exc.message, error_type="MethodEntryError", cause=exc)+ # No pipe to start at is the run's refusal and no verdict: its problem carries its own code.+ agent_error(exc.message, cause=exc)except PipelexConfigError as exc:# Listing the tree reads its limits from the configuration, before the boot would.report_agent_init_failure(error=exc)@@ -170,23 +182,45 @@ def run_bundle_cmd(elif is_pipelex_file(target_path):bundle_path = path- try:- method_tree = list_bundle_file_tree(bundle_file=target_path)- except ValidateBundleError as exc:- agent_error(exc.message, error_type="ValidateBundleError", cause=exc)- except PipelexConfigError as exc:- report_agent_init_failure(error=exc)else:- agent_error(+ agent_argument_error(f"'{path}' is not a .mthds file or directory. Use 'run pipe <code>' for pipe codes, or 'run bundle <path>' for .mthds files/directories.",- error_type="ArgumentError",+ argument=path,+ reason="not a .mthds file or a directory",)# Load MTHDS content from bundlemthds_content: str | None = Noneif bundle_path:+ if method_tree is None:+ # The bundle file named alone: its own tree, which a folder run has already listed. The tree is listed+ # before the file is read, since the listing refuses a symbolic link, a special file such as a FIFO and a+ # file past this machine's limits without reading it.+ try:+ method_tree = list_bundle_file_tree(bundle_file=target_path)+ except ValidateBundleError as exc:+ # A file this machine would not let the listing read is the file the command was handed+ # (`client.file_unreadable`), never a fault of the method.+ read_error = _file_error_in_chain(error=exc)+ if isinstance(read_error, FileNotFoundError):+ missing = os.fsdecode(read_error.filename) if isinstance(read_error.filename, (str, bytes)) else str(read_error.filename)+ agent_file_error(f"Bundle file not found: {missing}", path=missing, reason="not found", cause=read_error)+ if read_error is not None:+ agent_unreadable_file_error(error=read_error)+ agent_error(exc.message, cause=exc)+ except PipelexConfigError as exc:+ # Listing the tree reads its limits from the configuration, before the boot would.+ report_agent_init_failure(error=exc)+ try:+ mthds_bytes = Path(bundle_path).read_bytes()+ except FileNotFoundError as exc:+ agent_file_error(f"Bundle file not found: {bundle_path}", path=bundle_path, reason="not found", cause=exc)+ except OSError as exc:+ agent_unreadable_file_error(error=exc)try:- mthds_content = Path(bundle_path).read_text(encoding="utf-8")+ # A file that is not UTF-8 text does not parse: the invalid verdict `validate` gives it, `method.syntax`.+ with translate_to_validate_bundle_error():+ mthds_content = decode_mthds_text(content=mthds_bytes, source=bundle_path)if not pipe_code:# A bundle file named alone starts at its own main_pipe.# A bundle that does not parse is the invalid verdict, with the items `validate` gives,@@ -197,16 +231,13 @@ def run_bundle_cmd(if not main_pipe_code:agent_error(f"Bundle '{bundle_path}' does not declare a main_pipe. Specify a pipe code with --pipe.",- error_type="BundleError",+ code=CoreCode.REQUEST_PIPE_UNSPECIFIED,+ params={"candidates": sorted(bundle_blueprint.pipe or {})},)pipe_code = main_pipe_codehosted_pipe_code = main_pipe_code- except FileNotFoundError as exc:- agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc)- except (OSError, UnicodeDecodeError) as exc:- agent_error(f"Failed to read bundle file '{bundle_path}': {exc}", error_type=type(exc).__name__, cause=exc)except ValidateBundleError as exc:- agent_error(f"Failed to parse bundle '{bundle_path}': {exc.message}", error_type="ValidateBundleError", cause=exc)+ agent_error(f"Failed to parse bundle '{bundle_path}': {exc.message}", cause=exc)# Load inputs: --inputs flag takes priority, then stdin fallback, then auto-detectedparsed_inputs = parse_cli_inputs(inputs_arg=inputs, stdin_fallback=True, auto_inputs_dir=auto_inputs_dir)@@ -221,7 +252,7 @@ def run_bundle_cmd(primary=Path(bundle_path) if bundle_path else None, library_dirs=hosted_library_dirs(library_dirs=library_dir))except HostedRunSourceError as exc:- agent_error(exc.message, error_type=type(exc).__name__, cause=exc)+ agent_error(exc.message, cause=exc)request = HostedRunRequest(mthds_files=bundle_files,pipe_code=hosted_pipe_code,@@ -256,7 +287,7 @@ def run_bundle_cmd()except PipelineExecutionError as exc:- agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **run_failure_fields(error=exc))+ agent_error(exc.message, cause=exc)except PipeOperatorModelAvailabilityError as exc:availability_extra: dict[str, Any] = {@@ -267,11 +298,11 @@ def run_bundle_cmd(availability_extra["fallback_list"] = exc.fallback_listif exc.pipe_stack:availability_extra["pipe_stack"] = exc.pipe_stack- agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)+ agent_error(exc.message, cause=exc, **availability_extra)except Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(str(exc), cause=exc)finally:Pipelex.teardown_if_needed()diff --git a/pipelex/cli/agent_cli/commands/run/method_cmd.py b/pipelex/cli/agent_cli/commands/run/method_cmd.pyindex 776d1cf4b..0df77aa1e 100644--- a/pipelex/cli/agent_cli/commands/run/method_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/method_cmd.py@@ -12,10 +12,10 @@ import typerfrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_clifrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,+ agent_argument_error,agent_error,agent_success_formatted,- run_failure_fields,- set_agent_cli_error_format,+ use_agent_cli_error_format,)from pipelex.cli.agent_cli.commands.run._output_helpers import format_run_markdownfrom pipelex.cli.agent_cli.commands.run._run_core import run_pipeline_core@@ -90,7 +90,7 @@ def run_method_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,runner: Annotated[RunExecution | None,@@ -121,11 +121,11 @@ def run_method_cmd(pipelex-agent run method my-method --dry-run --mock-inputspipelex-agent run method github.com/Pipelex/methods/[email protected] --runner hosted --inputs '{"text": "Hello"}'"""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)# Validate --mock-inputs requires --dry-runif mock_inputs and not dry_run:- agent_error("--mock-inputs requires --dry-run", error_type="ArgumentError")+ agent_argument_error("--mock-inputs requires --dry-run", argument="--mock-inputs", reason="requires --dry-run")execution = resolve_agent_run_execution(runner=runner, hosted=hosted, base_url=base_url)if execution.is_hosted:@@ -135,7 +135,7 @@ def run_method_cmd(try:target = resolve_hosted_method_target(name=name, pipe_override=pipe, library_dirs=library_dir)except (HostedRunSourceError, MethodRefError) as exc:- agent_error(exc.message, error_type=type(exc).__name__, cause=exc)+ agent_error(exc.message, cause=exc)hosted_inputs = parse_cli_inputs(inputs_arg=resolve_inputs_arg_against_dir(inputs, base_dir=target.inputs_anchor_dir),stdin_fallback=True,@@ -161,7 +161,7 @@ def run_method_cmd(except MethodRefError as exc:# Method-reference failure (parse, fetch, location, bounds, refusal): report it through# the structured error envelope instead of the human CLI's plain red text.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc)+ agent_error(str(exc), cause=exc)# A fetched method's package directory is an ephemeral clone deleted at process exit —# anchor run output folders (output JSON, graph files) in a durable location instead.@@ -218,7 +218,7 @@ def run_method_cmd()except PipelineExecutionError as exc:- agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **run_failure_fields(error=exc))+ agent_error(exc.message, cause=exc)except PipeOperatorModelAvailabilityError as exc:availability_extra: dict[str, Any] = {@@ -229,11 +229,11 @@ def run_method_cmd(availability_extra["fallback_list"] = exc.fallback_listif exc.pipe_stack:availability_extra["pipe_stack"] = exc.pipe_stack- agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)+ agent_error(exc.message, cause=exc, **availability_extra)except Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(str(exc), cause=exc)finally:Pipelex.teardown_if_needed()diff --git a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py b/pipelex/cli/agent_cli/commands/run/pipe_cmd.pyindex f6be2d8b0..1a5a2f86a 100644--- a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/pipe_cmd.py@@ -12,10 +12,10 @@ import typerfrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_clifrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,+ agent_argument_error,agent_error,agent_success_formatted,- run_failure_fields,- set_agent_cli_error_format,+ use_agent_cli_error_format,)from pipelex.cli.agent_cli.commands.run._output_helpers import format_run_markdownfrom pipelex.cli.agent_cli.commands.run._run_core import run_pipeline_core@@ -79,7 +79,7 @@ def run_pipe_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,runner: Annotated[RunExecution | None,@@ -107,20 +107,21 @@ def run_pipe_cmd(pipelex-agent run pipe my_pipe --format jsonpipelex-agent run pipe my_pipe -L my_library/ --runner hosted --inputs data.json"""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)# Helpful error if the user passes a path instead of a pipe codetarget_path = Path(pipe_code)if target_path.is_dir() or is_pipelex_file(target_path) or pipe_code.endswith(MTHDS_EXTENSION):- agent_error(+ agent_argument_error(f"'{pipe_code}' looks like a file path or directory. "f"Use 'run bundle {pipe_code}' for bundles/directories, or 'run pipe <code>' for pipe codes.",- error_type="ArgumentError",+ argument=pipe_code,+ reason="a path where a pipe code is expected",)# Validate --mock-inputs requires --dry-runif mock_inputs and not dry_run:- agent_error("--mock-inputs requires --dry-run", error_type="ArgumentError")+ agent_argument_error("--mock-inputs requires --dry-run", argument="--mock-inputs", reason="requires --dry-run")# Check installed methods' exports for additional library dirstry:@@ -128,7 +129,6 @@ def run_pipe_cmd(except ExportedPipeAmbiguousError as exc:agent_error(f"Ambiguous pipe code '{pipe_code}': {exc}",- error_type="ArgumentError",cause=exc,)if export_dirs:@@ -148,7 +148,7 @@ def run_pipe_cmd(try:library_files = hosted_pipe_library_files(library_dirs=library_dir)except HostedRunSourceError as exc:- agent_error(exc.message, error_type=type(exc).__name__, cause=exc)+ agent_error(exc.message, cause=exc)request = HostedRunRequest(mthds_files=library_files,pipe_code=pipe_code,@@ -179,7 +179,7 @@ def run_pipe_cmd()except PipelineExecutionError as exc:- agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **run_failure_fields(error=exc))+ agent_error(exc.message, cause=exc)except PipeOperatorModelAvailabilityError as exc:availability_extra: dict[str, Any] = {@@ -190,11 +190,11 @@ def run_pipe_cmd(availability_extra["fallback_list"] = exc.fallback_listif exc.pipe_stack:availability_extra["pipe_stack"] = exc.pipe_stack- agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra)+ agent_error(exc.message, cause=exc, **availability_extra)except Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(str(exc), cause=exc)finally:Pipelex.teardown_if_needed()diff --git a/pipelex/cli/agent_cli/commands/run/stdin_resolver.py b/pipelex/cli/agent_cli/commands/run/stdin_resolver.pyindex 847552a86..db0176d7d 100644--- a/pipelex/cli/agent_cli/commands/run/stdin_resolver.py+++ b/pipelex/cli/agent_cli/commands/run/stdin_resolver.py@@ -9,7 +9,7 @@ from typing import Any, NamedTuple, castfrom mthds.protocol.problem.registry import CoreCode-from pipelex.cli.agent_cli.commands.agent_output import agent_error+from pipelex.cli.agent_cli.commands.agent_output import agent_argument_error, agent_error, agent_file_error, file_read_failure_reasonfrom pipelex.cli.commands.run._inputs_file_loader import load_inputs_dict_from_bytes, load_inputs_dict_from_path, read_default_inputs_filefrom pipelex.cli.commands.run._inputs_path_resolver import resolve_inputs_pathsfrom pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError, AutoDetectedInputsFileError@@ -55,13 +55,15 @@ def _extract_stuff_entry(stuff_data: dict[str, Any], *, stuff_name: str) -> dictif concept_data is None or content_data is None:return Noneif not isinstance(concept_data, str):- # Not a JSONDecodeError: the envelope parsed. What failed is its *shape* — the concept- # field holds something the CLI I/O contract does not put there — and the label is a- # machine contract, so it must not send a consumer hunting for trailing commas.- agent_error(+ # Not a parse failure: the envelope parsed. What failed is its *shape* — the concept field holds+ # something the CLI I/O contract does not put there — and the reason says so, so it does not send+ # a consumer hunting for trailing commas.+ agent_argument_error(f"stdin envelope has invalid 'working_memory.root.{stuff_name}.concept': "- f"expected the concept ref string '<domain>.<Code>', got {type(concept_data).__name__}",- error_type="StdinEnvelopeShapeError",+ f"expected the concept ref string '<domain>.<Code>', got {type(concept_data).__name__}. "+ "Replace the concept object with its ref, or re-pipe the output of a current 'pipelex-agent run --with-memory'.",+ argument="stdin",+ reason=f"working_memory.root.{stuff_name}.concept is not a concept ref string",)return {"concept": concept_data,@@ -93,12 +95,16 @@ def resolve_stdin_inputs(stdin_data: dict[str, Any]) -> dict[str, Any]:working_memory_raw: Any = stdin_data[WORKING_MEMORY_KEY]if not isinstance(working_memory_raw, dict):- agent_error("stdin envelope has invalid 'working_memory': expected a dict", error_type="JSONDecodeError")+ agent_argument_error(+ "stdin envelope has invalid 'working_memory': expected a dict", argument="stdin", reason="working_memory is not an object"+ )working_memory = cast("dict[str, Any]", working_memory_raw)root_raw: Any = working_memory.get("root", {})if not isinstance(root_raw, dict):- agent_error("stdin envelope has invalid 'working_memory.root': expected a dict", error_type="JSONDecodeError")+ agent_argument_error(+ "stdin envelope has invalid 'working_memory.root': expected a dict", argument="stdin", reason="working_memory.root is not an object"+ )root = cast("dict[str, Any]", root_raw)aliases_raw: Any = working_memory.get("aliases", {})@@ -176,7 +182,7 @@ def parse_cli_inputs(try:detected_inputs = read_default_inputs_file(directory=auto_inputs_dir)except (AmbiguousInputsFilesError, AutoDetectedInputsFileError) as inputs_file_exc:- agent_error(inputs_file_exc.message, error_type=type(inputs_file_exc).__name__, cause=inputs_file_exc)+ agent_error(inputs_file_exc.message, cause=inputs_file_exc)if detected_inputs is not None:# Parsed from the bytes the probe read without following a link, never by opening the path again.return _parse_inputs_file(inputs_path=detected_inputs.path, label=str(detected_inputs.path), data=detected_inputs.data)@@ -198,7 +204,7 @@ def _parse_inputs_arg(inputs_arg: str) -> ParsedCliInputs:try:result: dict[str, Any] = json.loads(inputs_arg)except json.JSONDecodeError as exc:- agent_error(f"Failed to parse inline JSON inputs: {exc}", error_type="JSONDecodeError", cause=exc)+ agent_argument_error(f"Failed to parse inline JSON inputs: {exc}", argument="--inputs", reason="not valid JSON", cause=exc)return ParsedCliInputs(pipeline_inputs=result, inputs_base_dir=None)# expanduser so a quoted / `=`-form `~/inputs.json` resolves to the home dir, not a# literal `~` component (unquoted `~` is shell-expanded, but the quoted/`=` forms are not).@@ -225,14 +231,20 @@ def _parse_inputs_file(*, inputs_path: Path, label: str, data: bytes | None) ->base_dir = inputs_path.parent.resolve()return ParsedCliInputs(pipeline_inputs=resolve_inputs_paths(loaded, base_dir=base_dir), inputs_base_dir=base_dir)except FileNotFoundError as exc:- agent_error(f"Input file not found: {label}", error_type="FileNotFoundError", cause=exc)+ agent_file_error(f"Input file not found: {label}", path=label, reason="not found", cause=exc)except json.JSONDecodeError as exc:- agent_error(f"Input file contains invalid JSON: {label}: {exc}", error_type="JSONDecodeError", cause=exc)+ # A subclass of ValueError, never of the read failures below.+ agent_argument_error(f"Input file contains invalid JSON: {label}: {exc}", argument="--inputs", reason="the file is not valid JSON", cause=exc)+ except (OSError, UnicodeDecodeError) as exc:+ reason = file_read_failure_reason(error=exc)+ agent_file_error(f"Input file cannot be read: {label}: {reason}", path=label, reason=reason, cause=exc)except JsonTypeError as exc:- agent_error(f"Input file must be a valid JSON dictionary: {label}", error_type="JsonTypeError", cause=exc)+ agent_argument_error(+ f"Input file must be a valid JSON dictionary: {label}", argument="--inputs", reason="the file does not hold a JSON object", cause=exc+ )except TomlError as exc:# The inputs file is the caller's request, not the runtime's configuration.- agent_error(exc.message, error_type="TomlError", cause=exc.with_error_code(CoreCode.REQUEST_MALFORMED))+ agent_error(exc.message, cause=exc.with_error_code(CoreCode.REQUEST_MALFORMED))def _read_stdin_inputs() -> dict[str, Any] | None:@@ -252,10 +264,10 @@ def _read_stdin_inputs() -> dict[str, Any] | None:try:parsed: Any = json.loads(stdin_raw)except json.JSONDecodeError as exc:- agent_error(f"Failed to parse stdin JSON: {exc}", error_type="JSONDecodeError", cause=exc)+ agent_argument_error(f"Failed to parse stdin JSON: {exc}", argument="stdin", reason="not valid JSON", cause=exc)if not isinstance(parsed, dict):- agent_error("stdin JSON must be a dictionary, got " + type(parsed).__name__, error_type="JSONDecodeError")+ agent_argument_error("stdin JSON must be a dictionary, got " + type(parsed).__name__, argument="stdin", reason="not a JSON object")parsed_dict = cast("dict[str, Any]", parsed)return resolve_stdin_inputs(parsed_dict)diff --git a/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py b/pipelex/cli/agent_cli/commands/validate/bundle_cmd.pyindex ee5dd482f..3c7045c77 100644--- a/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py+++ b/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py@@ -12,9 +12,10 @@ from pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,agent_error,agent_error_validate_bundle,+ agent_file_error,agent_success_formatted,- run_failure_fields,- set_agent_cli_error_format,+ agent_unreadable_file_error,+ use_agent_cli_error_format,)from pipelex.cli.agent_cli.commands.bundle_path_resolver import resolve_bundle_targetfrom pipelex.cli.agent_cli.commands.validate._validate_core import (@@ -106,7 +107,7 @@ def validate_bundle_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,) -> None:"""Validate a bundle file (.mthds) or a method's folder and output the results.@@ -126,7 +127,7 @@ def validate_bundle_cmd(pipelex-agent validate bundle my_method/ --graphpipelex-agent validate bundle draft_pipeline.mthds --allow-signatures"""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)# A folder is judged whole, as the MTHDS protocol's validation judges a method: every bundle of its tree.try:@@ -184,18 +185,16 @@ def validate_bundle_cmd(except PipelineExecutionError as exc:agent_error(f"Graph generation failed: {exc.message}",- error_type="PipelineExecutionError",cause=exc,exit_code=2,- **run_failure_fields(error=exc),)except MthdsParserError as exc:- agent_error(f"Graph generation failed: {exc}", error_type=type(exc).__name__, cause=exc, exit_code=2)+ agent_error(f"Graph generation failed: {exc}", cause=exc, exit_code=2)except typer.Exit:raiseexcept Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(f"Graph generation failed: {exc}", error_type=type(exc).__name__, cause=exc, exit_code=2)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(f"Graph generation failed: {exc}", cause=exc, exit_code=2)# Generate view (GraphSpec JSON) if requested and validation succeededif view and isinstance(graph_target, _GraphTarget):@@ -212,18 +211,16 @@ def validate_bundle_cmd(except PipelineExecutionError as exc:agent_error(f"View generation failed: {exc.message}",- error_type="PipelineExecutionError",cause=exc,exit_code=2,- **run_failure_fields(error=exc),)except MthdsParserError as exc:- agent_error(f"View generation failed: {exc}", error_type=type(exc).__name__, cause=exc, exit_code=2)+ agent_error(f"View generation failed: {exc}", cause=exc, exit_code=2)except typer.Exit:raiseexcept Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(f"View generation failed: {exc}", error_type=type(exc).__name__, cause=exc, exit_code=2)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(f"View generation failed: {exc}", cause=exc, exit_code=2)agent_success_formatted(result, markdown_renderer=format_validate_markdown, output_format=output_format)@@ -242,16 +239,21 @@ def validate_bundle_cmd(except PipeNotFoundError as exc:# The real class, not the caught base — see the same arm in `validate pipe`.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc, exit_code=2)+ agent_error(str(exc), cause=exc, exit_code=2)except FileNotFoundError as exc:- agent_error(f"Bundle file not found: {judged_path}", error_type="FileNotFoundError", cause=exc, exit_code=2)+ agent_file_error(f"Bundle file not found: {judged_path}", path=str(judged_path), reason="not found", cause=exc, exit_code=2)++ except OSError as exc:+ # A method file this machine would not let the command read: the file, never a fault of the method. An error+ # naming no file, a connection or a timeout, is the unexpected failure the boundary reports.+ agent_unreadable_file_error(error=exc, exit_code=2)except ValidateBundleError as exc:- # Invalid verdict: emit the format-aware failure surface. JSON keeps the exact structured- # envelope (is_valid:false discriminant + validation_errors[], the shared builder's output,- # non-empty on every invalid verdict); markdown renders those items as prose with a fix-aware- # footer. Signatures never reach here (they are a runnability fact, gated above).+ # Invalid verdict: the problem of the method that does not validate, format-aware. Its errors are+ # the shared builder's items, non-empty on every invalid verdict, beside the is_valid:false+ # discriminant; markdown renders those items as prose with a fix-aware footer. Signatures never+ # reach here (they are a runnability fact, gated above).agent_error_validate_bundle(exc, bundle_path=judged_path, library_dirs=library_dirs, allow_signatures=allow_signatures)except PipeOperatorModelAvailabilityError as exc:@@ -263,14 +265,14 @@ def validate_bundle_cmd(availability_extra["fallback_list"] = exc.fallback_listif exc.pipe_stack:availability_extra["pipe_stack"] = exc.pipe_stack- agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, exit_code=2, **availability_extra)+ agent_error(exc.message, cause=exc, exit_code=2, **availability_extra)except typer.Exit:raiseexcept Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc, exit_code=2)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(str(exc), cause=exc, exit_code=2)finally:Pipelex.teardown_if_needed()diff --git a/pipelex/cli/agent_cli/commands/validate/method_cmd.py b/pipelex/cli/agent_cli/commands/validate/method_cmd.pyindex 0f4cf76d9..19cbf94ca 100644--- a/pipelex/cli/agent_cli/commands/validate/method_cmd.py+++ b/pipelex/cli/agent_cli/commands/validate/method_cmd.py@@ -7,14 +7,16 @@ from pathlib import Pathfrom typing import Annotated, Anyimport typer+from mthds.protocol.problem.registry import CoreCodefrom 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_validate_bundle,+ agent_file_error,agent_success_formatted,- set_agent_cli_error_format,+ use_agent_cli_error_format,)from pipelex.cli.agent_cli.commands.validate._validate_core import (validate_bundle_core,@@ -54,7 +56,7 @@ def validate_method_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,) -> None:"""Validate an installed method and output the results.@@ -68,7 +70,7 @@ def validate_method_cmd(pipelex-agent validate method my-method --pipe custom_pipepipelex-agent validate method my-method --allow-signatures"""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)try:pipe_code, method_library_dirs, method = resolve_method_target(@@ -79,11 +81,11 @@ def validate_method_cmd()except MethodRefError as exc:# Method-reference failure (parse, fetch, location, bounds, refusal): no verdict could be- # produced, so exit 2 with the structured error envelope (not the human CLI's red text).- agent_error(str(exc), error_type=type(exc).__name__, cause=exc, exit_code=2)+ # produced, so exit 2 with its problem (not the human CLI's red text).+ agent_error(str(exc), cause=exc, exit_code=2)if not method.mthds_files:- agent_error(f"Method '{name}' has no .mthds bundle files.", error_type="MethodError", exit_code=2)+ agent_error(f"Method '{name}' has no .mthds bundle files.", code=CoreCode.METHOD_NOT_FOUND, params={"method_ref": name}, exit_code=2)bundle_path = method.mthds_files[0]@@ -121,11 +123,11 @@ def validate_method_cmd(raise typer.Exit(1)except FileNotFoundError as exc:- agent_error(f"Bundle file not found: {bundle_path}", error_type="FileNotFoundError", cause=exc, exit_code=2)+ agent_file_error(f"Bundle file not found: {bundle_path}", path=bundle_path, reason="not found", cause=exc, exit_code=2)except ValidateBundleError as exc:- # Invalid verdict (see bundle_cmd): format-aware failure surface. JSON keeps the exact- # structured envelope; markdown renders the items as prose with a fix-aware footer.+ # Invalid verdict (see bundle_cmd): the method's problem, format-aware; markdown renders the+ # items as prose with a fix-aware footer.agent_error_validate_bundle(exc, bundle_path=bundle_path, library_dirs=library_dirs_paths, allow_signatures=allow_signatures)except PipeOperatorModelAvailabilityError as exc:@@ -137,7 +139,7 @@ def validate_method_cmd(availability_extra["fallback_list"] = exc.fallback_listif exc.pipe_stack:availability_extra["pipe_stack"] = exc.pipe_stack- agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, exit_code=2, **availability_extra)+ agent_error(exc.message, cause=exc, exit_code=2, **availability_extra)except typer.Exit:# The runnability gate raises typer.Exit(1) after emitting the success envelope; let it@@ -145,8 +147,8 @@ def validate_method_cmd(raiseexcept Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc, exit_code=2)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(str(exc), cause=exc, exit_code=2)finally:Pipelex.teardown_if_needed()diff --git a/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py b/pipelex/cli/agent_cli/commands/validate/pipe_cmd.pyindex c945950c8..786e4f138 100644--- a/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py+++ b/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py@@ -9,10 +9,10 @@ import typerfrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_clifrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,+ agent_argument_error,agent_error,agent_success_formatted,- extract_validation_errors,- set_agent_cli_error_format,+ use_agent_cli_error_format,)from pipelex.cli.agent_cli.commands.validate._validate_core import (validate_all_core,@@ -54,7 +54,7 @@ def validate_pipe_cmd(] = CliOutputFormat.MARKDOWN,error_format: Annotated[CliOutputFormat | None,- typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),+ typer.Option("--error-format", help="Error output format: markdown or json (defaults to the program's --error-format, then to --format)"),] = None,) -> None:"""Validate a pipe by code, or all pipes, and output the results.@@ -68,14 +68,14 @@ def validate_pipe_cmd(pipelex-agent validate pipe --all -L ./my_pipespipelex-agent validate pipe my_draft_pipe --allow-signatures"""- set_agent_cli_error_format(error_format or output_format)+ use_agent_cli_error_format(error_format=error_format, output_format=output_format)library_dirs = [Path(lib_dir) for lib_dir in library_dir] if library_dir else None# Handle --all flagif validate_all:if pipe_code:- agent_error("--all cannot be used with a pipe code", error_type="ArgumentError", exit_code=2)+ agent_argument_error("--all cannot be used with a pipe code", argument="--all", reason="contradicts the pipe code given", exit_code=2)make_pipelex_for_agent_cli(library_dirs=library_dirs, needs_inference=False)@@ -92,21 +92,18 @@ def validate_pipe_cmd(raise typer.Exit(1)except ValidateBundleError as exc:- # Invalid verdict: structured failure envelope. validation_errors[] is the shared builder's- # output (a failing dry run rides one located dry_run item per failing pipe). Signatures are a- # runnability fact (pending_signatures + the gate above), not an error, so they never reach this arm.+ # Invalid verdict: the problem of the method that does not validate, its errors one located item per+ # fault (a failing dry run gives one per failing pipe). Signatures are a runnability fact+ # (pending_signatures + the gate above), not an error, so they never reach this arm.agent_error(exc.message,- error_type="ValidateBundleError",cause=exc,is_valid=False,- validation_errors=extract_validation_errors(exc),)except PipeOperatorModelAvailabilityError as exc:agent_error(str(exc),- error_type="PipeOperatorModelAvailabilityError",cause=exc,pipe_code=exc.pipe_code,model_handle=exc.model_handle,@@ -119,27 +116,29 @@ def validate_pipe_cmd(raiseexcept Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc, exit_code=2)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(str(exc), cause=exc, exit_code=2)finally:Pipelex.teardown_if_needed()returnif not pipe_code:- agent_error(+ agent_argument_error("No pipe code specified. Use --all to validate all pipes, or use 'validate bundle <path>' for bundle files.",- error_type="ArgumentError",+ argument="pipe_code",+ reason="missing without --all",exit_code=2,)# Helpful error if the user passes a path instead of a pipe codetarget_path = Path(pipe_code)if target_path.is_dir() or is_pipelex_file(target_path) or pipe_code.endswith(MTHDS_EXTENSION):- agent_error(+ agent_argument_error(f"'{pipe_code}' looks like a file path or directory. "f"Use 'validate bundle {pipe_code}' for bundles/directories, or 'validate pipe <code>' for pipe codes.",- error_type="ArgumentError",+ argument=pipe_code,+ reason="a path where a pipe code is expected",exit_code=2,)@@ -149,7 +148,6 @@ def validate_pipe_cmd(except ExportedPipeAmbiguousError as exc:agent_error(f"Ambiguous pipe code '{pipe_code}': {exc}",- error_type="ArgumentError",cause=exc,exit_code=2,)@@ -173,17 +171,15 @@ def validate_pipe_cmd(# The label is the real class, not the caught base: the entry-shaped lookup raises# EntryPipeNotFoundError, whose INPUT domain and hint already ride this envelope from the# report. Hardcoding the base name would attribute them to a class that declares neither.- agent_error(error_message, error_type=type(exc).__name__, cause=exc, exit_code=2)+ agent_error(error_message, cause=exc, exit_code=2)except ValidateBundleError as exc:# Invalid verdict (see the --all arm): structured failure envelope; validation_errors[] is the# shared builder's output (a failing dry run rides one located dry_run item per failing pipe).agent_error(exc.message,- error_type="ValidateBundleError",cause=exc,is_valid=False,- validation_errors=extract_validation_errors(exc),)except PipeOperatorModelAvailabilityError as exc:@@ -195,14 +191,14 @@ def validate_pipe_cmd(availability_extra["fallback_list"] = exc.fallback_listif exc.pipe_stack:availability_extra["pipe_stack"] = exc.pipe_stack- agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", cause=exc, **availability_extra, exit_code=2)+ agent_error(exc.message, cause=exc, **availability_extra, exit_code=2)except typer.Exit:raiseexcept Exception as exc: # ruff: ignore[blind-except]- # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into the structured error payload.- agent_error(str(exc), error_type=type(exc).__name__, cause=exc, exit_code=2)+ # Agent CLI command boundary: agent_error() (NoReturn) converts any unexpected failure into its problem.+ agent_error(str(exc), cause=exc, exit_code=2)finally:Pipelex.teardown_if_needed()diff --git a/pipelex/cli/commands/fix/_fix_core.py b/pipelex/cli/commands/fix/_fix_core.pyindex afd6b0780..3e8246119 100644--- a/pipelex/cli/commands/fix/_fix_core.py+++ b/pipelex/cli/commands/fix/_fix_core.py@@ -26,7 +26,7 @@ from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityErrorfrom pipelex.pipelex import Pipelexfrom pipelex.pipeline.fixes.fix_loop import unfixable_method_resultfrom pipelex.pipeline.validate_bundle import dirs_beside_method-from pipelex.runtime_hub import get_console, get_telemetry_manager+from pipelex.runtime_hub import get_console, get_error_console, get_telemetry_managerfrom pipelex.system.runtime import IntegrationModefrom pipelex.system.telemetry.events import EventPropertyfrom pipelex.tools.misc.package_utils import get_package_version@@ -273,7 +273,7 @@ def render_refused_method(*, error: ValidateBundleError, method_dir: Path, allowThe verdict is the fix loop's still-invalid one, with nothing applied and the refusal as its remaining errors, sothe output names the folder and reads as a fix that could not be made, as `validate` names it in its invalid one."""- print_traceback_if_requested(console=get_console())+ print_traceback_if_requested(console=get_error_console())_render_fix_result(console=get_console(),result=unfixable_method_result(error=error),@@ -336,7 +336,7 @@ def execute_fix()_render_fix_result(console=get_console(), result=result, bundle_path=judged_path, allow_signatures=allow_signatures)except FileNotFoundError as exc:- print_traceback_if_requested(console=get_console())+ print_traceback_if_requested(console=get_error_console())typer.secho(f"Failed to fix: bundle file not found: '{judged_path}'", fg=typer.colors.RED, err=True)raise typer.Exit(2) from excexcept PipeOperatorModelChoiceError as exc:@@ -347,7 +347,7 @@ def execute_fix(raiseexcept Exception as exc:# Human CLI command boundary: an unexpected failure produced no verdict — exit 2.- print_traceback_if_requested(console=get_console())+ print_traceback_if_requested(console=get_error_console())typer.secho(f"Failed to fix: {exc}", fg=typer.colors.RED, err=True)raise typer.Exit(2) from excfinally:diff --git a/pipelex/cli/commands/graph_cmd.py b/pipelex/cli/commands/graph_cmd.pyindex 6876a9987..a7b1b232c 100644--- a/pipelex/cli/commands/graph_cmd.py+++ b/pipelex/cli/commands/graph_cmd.py@@ -20,13 +20,14 @@ from rich.markup import escapefrom pipelex import logfrom pipelex.cli.cli_factory import make_pipelex_for_cli-from pipelex.cli.error_handlers import ErrorContext, print_unexpected_failure+from pipelex.cli.error_handlers import ErrorContext, is_traceback_requested, print_failure_problemfrom pipelex.config import get_config+from pipelex.errors.failure_problem import failure_log_fieldsfrom pipelex.graph.exceptions import GraphSpecValidationErrorfrom pipelex.graph.graph_rendering import render_graph_from_specfrom pipelex.graph.graphspec import GraphSpecfrom pipelex.pipelex import Pipelex-from pipelex.runtime_hub import get_console, get_telemetry_manager+from pipelex.runtime_hub import get_error_console, get_telemetry_managerfrom pipelex.system.runtime import IntegrationModefrom pipelex.system.telemetry.events import EventName, EventPropertyfrom pipelex.system.telemetry.otel_constants import OTelLogAttr@@ -203,19 +204,24 @@ def graph_render_cmd(log.error("The graph spec was refused and no graph was rendered", fields={OTelLogAttr.FILE_PATH: str(input_file), **error_fields(exc=spec_error)})- console = get_console()- console.print(f"\n[bold red]Failed to render graph[/bold red]\n\n{escape(str(spec_error))}\n")+ get_error_console().print(f"\n[bold red]Failed to render graph[/bold red]\n\n{escape(str(spec_error))}\n")raise typer.Exit(1) from spec_errorexcept Exception as exc:# CLI command root: any unexpected failure is reported to the user and exits non-zero via typer.Exit.- # An unexpected failure is a bug, and this is the catcher that owns its traceback, so the traceback rides the- # log record: the `console` sink renders it under the line, and the `json` and `otlp` sinks write it to the- # log store, which a traceback printed on the console alone never reached. The CLI's own output names the- # exception's type and message, so the terminal says why the render failed whatever the sink and the level.- # The console renders no locals unless the configuration asks it to, since they would print the loaded graph.- print_unexpected_failure(console=get_console(), title="Failed to render graph", exc=exc)- log.error("The graph could not be rendered", fields={OTelLogAttr.FILE_PATH: str(input_file)}, include_exception=True)+ # The CLI's own output is the failure's problem, the exception's type and its message capped, so the terminal+ # says why the render failed whatever the sink and the level. The log line carries identifiers only, the+ # problem's code and the classes along the chain, since an exception's text can quote the graph, which holds+ # a run's traced content. The traceback, which prints every chained exception's text, rides the record only+ # under `--traceback`: the `console` sink renders it under the line, and the `json` and `otlp` sinks write it+ # to the log store. The console renders no locals unless the configuration asks it to, since they would print+ # the loaded graph.+ problem = print_failure_problem(console=get_error_console(), title="Failed to render graph", error=exc)+ log.error(+ "The graph could not be rendered",+ fields={OTelLogAttr.FILE_PATH: str(input_file), **failure_log_fields(error=exc, problem=problem)},+ include_exception=is_traceback_requested(),+ )raise typer.Exit(1) from excfinally:diff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.pyindex 2bc88a004..633b707d1 100644--- a/pipelex/cli/commands/run/_run_core.py+++ b/pipelex/cli/commands/run/_run_core.py@@ -23,8 +23,9 @@ from pipelex.cli.error_handlers import (handle_model_availability_error,handle_model_choice_error,handle_validate_bundle_error,+ is_traceback_requested,+ print_failure_problem,print_traceback_if_requested,- print_unexpected_failure,)from pipelex.config import get_configfrom pipelex.core.concepts.exceptions import ConceptValueError@@ -33,6 +34,7 @@ from pipelex.core.memory.absence_render import build_absence_json, build_absencefrom pipelex.core.pipes.exceptions import PipeOperatorModelChoiceErrorfrom pipelex.core.stuffs.list_content import ListContentfrom pipelex.core.stuffs.stuff_viewer import render_stuff_viewer+from pipelex.errors.failure_problem import failure_log_fieldsfrom pipelex.graph.graph_factory import generate_graph_outputs, save_graph_outputs_to_dirfrom pipelex.interpreter_hub import clear_current_library, get_concept_library, get_library_managerfrom pipelex.mthds_parsing.parser import MthdsParser@@ -43,7 +45,7 @@ from pipelex.pipeline.execution_seams import acquire_libraryfrom pipelex.pipeline.runner import PipelexMTHDSProtocolfrom pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_errorfrom pipelex.reporting.cost_report_renderer import render_cost_report_for_output-from pipelex.runtime_hub import get_console, get_telemetry_manager+from pipelex.runtime_hub import get_console, get_error_console, get_telemetry_managerfrom pipelex.system.pipe_run_mode import PipeRunModefrom pipelex.system.runtime import IntegrationModefrom pipelex.system.telemetry.events import EventProperty@@ -114,7 +116,7 @@ def load_run_inputs(*, inputs: str | DetectedInputsFile | None) -> LoadedRunInputry:inline_inputs: dict[str, Any] = json.loads(inputs)except json.JSONDecodeError as json_decode_exc:- print_traceback_if_requested(console=get_console())+ print_traceback_if_requested(console=get_error_console())typer.secho(f"Failed to parse inline JSON inputs: {json_decode_exc}", fg=typer.colors.RED, err=True)raise typer.Exit(1) from json_decode_exc# Inline JSON has no file to anchor relative paths to.@@ -141,19 +143,19 @@ def _load_run_inputs_file(*, inputs_path: Path, label: str, data: bytes | None)pipeline_inputs = resolve_inputs_paths(pipeline_inputs, base_dir=inputs_base_dir)typer.echo(f"Loaded inputs from: {label}")except FileNotFoundError as file_not_found_exc:- print_traceback_if_requested(console=get_console())+ print_traceback_if_requested(console=get_error_console())typer.secho(f"Failed to load input file '{label}': file not found", fg=typer.colors.RED, err=True)raise typer.Exit(1) from file_not_found_excexcept json.JSONDecodeError as json_decode_exc:- print_traceback_if_requested(console=get_console())+ print_traceback_if_requested(console=get_error_console())typer.secho(f"Failed to parse input file '{label}': invalid JSON: {json_decode_exc}", fg=typer.colors.RED, err=True)raise typer.Exit(1) from json_decode_excexcept JsonTypeError as json_type_error_exc:- print_traceback_if_requested(console=get_console())+ print_traceback_if_requested(console=get_error_console())typer.secho(f"Failed to parse input file '{label}': must be a valid JSON dictionary", fg=typer.colors.RED, err=True)raise typer.Exit(1) from json_type_error_excexcept TomlError as toml_error_exc:- print_traceback_if_requested(console=get_console())+ print_traceback_if_requested(console=get_error_console())typer.secho(f"Failed to parse input file: {toml_error_exc.message}", fg=typer.colors.RED, err=True)raise typer.Exit(1) from toml_error_excreturn LoadedRunInputs(pipeline_inputs=pipeline_inputs, inputs_base_dir=inputs_base_dir)@@ -251,7 +253,7 @@ async def _execute_run(raise typer.Exit(1)pipe_code = main_pipe_codeexcept FileNotFoundError as exc:- print_traceback_if_requested(console=get_console())+ print_traceback_if_requested(console=get_error_console())typer.secho(f"Failed to load bundle '{bundle_path}': {exc}", fg=typer.colors.RED, err=True)raise typer.Exit(1) from excexcept ValidateBundleError as exc:@@ -300,14 +302,17 @@ async def _execute_run(# A failure whose cause has a dedicated panel (a model that is not available, a model choice# that cannot be read) renders it: the panel names the pipe that failed, the model and the stack.handle_dedicated_failure_panel(error=exc, context=ErrorContext.PIPE_RUN)- print_traceback_if_requested(console=get_console())- # The message names the pipe that failed and its path; the pipeline named first is the entry pipe.+ print_traceback_if_requested(console=get_error_console())+ # The message names the pipe that failed and its path; the pipeline named first is the entry pipe. The problem+ # is the root fault's, located at the failing pipe, with its code and next step.entry_pipe_code = exc.pipe_stack[0] if exc.pipe_stack else exc.pipe_code- typer.secho(f"Failed to execute pipeline '{entry_pipe_code}': {exc.message}", fg=typer.colors.RED, err=True)+ print_failure_problem(console=get_error_console(), title=f"Failed to execute pipeline '{entry_pipe_code}'", error=exc)raise typer.Exit(1) from excexcept PipelexError as exc:- print_traceback_if_requested(console=get_console())- typer.secho(f"Failed to execute pipeline '{pipe_code or bundle_path}': {exc}", fg=typer.colors.RED, err=True)+ # The report goes to stderr, as every failure's does: stdout is the run's output.+ error_console = get_error_console()+ print_traceback_if_requested(console=error_console)+ print_failure_problem(console=error_console, title=f"Failed to execute pipeline '{pipe_code or bundle_path}'", error=exc)raise typer.Exit(1) from exc# Pretty print the resolved main result unless disabled or in dry run mode. A completed run@@ -590,22 +595,27 @@ def execute_run(raiseexcept PipelexError as exc:- console = get_console()- print_traceback_if_requested(console=console)- console.print("\n[bold red]Failed to execute pipeline[/bold red]\n")- # The message is plain text, a model's description such as `SDK[openai]` or a type such as `list[int]` included- console.print(f" {escape(exc.message)}\n")+ error_console = get_error_console()+ print_traceback_if_requested(console=error_console)+ print_failure_problem(console=error_console, title="Failed to execute pipeline", error=exc)raise typer.Exit(1) from excexcept Exception as exc:# CLI command root: any unexpected failure is reported to the user and exits non-zero via typer.Exit.- # This is the catcher every re-raised failure hands its traceback to, so the traceback rides the log record,- # where the `console` sink renders it under the line and the `json` and `otlp` sinks write it to the log- # store; printing it on the console as well would show it twice. The CLI's own output names the exception's- # type and message, so the terminal says why the run failed whatever the sink and the level. The console- # renders no locals unless the configuration asks it to, since they hold the run's working memory.- print_unexpected_failure(console=get_console(), title="Failed to execute pipeline", exc=exc)- log.error("The pipeline could not be executed", include_exception=True)+ # The CLI's own output is the failure's problem, the exception's type and its message capped, so the terminal+ # says why the run failed whatever the sink and the level. The log line carries identifiers only, the problem's+ # code and the classes along the chain: an exception's text, and every chained one's, can quote the run's data,+ # a foreign `ValidationError` the values it refused or a method function's exception what it was given. The+ # traceback, which prints every one of those texts, rides the record only under `--traceback`, where the+ # `console` sink renders it under the line and the `json` and `otlp` sinks write it to the log store; printing+ # it on the console as well would show it twice. The console renders no locals unless the configuration asks+ # it to, since they hold the run's working memory.+ problem = print_failure_problem(console=get_error_console(), title="Failed to execute pipeline", error=exc)+ log.error(+ "The pipeline could not be executed",+ fields=failure_log_fields(error=exc, problem=problem),+ include_exception=is_traceback_requested(),+ )raise typer.Exit(1) from excfinally:diff --git a/pipelex/cli/commands/run/_run_hosted.py b/pipelex/cli/commands/run/_run_hosted.pyindex 80df4e50e..f61b3ea7f 100644--- a/pipelex/cli/commands/run/_run_hosted.py+++ b/pipelex/cli/commands/run/_run_hosted.py@@ -30,7 +30,7 @@ from pipelex.hosted.run_config import RunExecutionfrom pipelex.mthds_parsing.parser import MthdsParserfrom pipelex.pipeline.exceptions import ValidateBundleErrorfrom pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error-from pipelex.runtime_hub import get_console+from pipelex.runtime_hub import get_console, get_error_consolefrom pipelex.tools.misc.json_utils import save_as_json_to_pathfrom pipelex.tools.misc.pretty import pretty_print, pretty_print_md@@ -66,7 +66,7 @@ def resolve_cli_run_execution(*, hosted: bool | None, base_url: str | None) -> Rtry:execution = resolve_run_execution(requested=RunExecution.from_hosted_flag(hosted=hosted))except PipelexError as exc:- print_traceback_if_requested(console=get_console())+ print_traceback_if_requested(console=get_error_console())raise _fail(message=exc.message) from excif base_url is not None and not execution.is_hosted:msg = "--base-url names the hosted API a hosted run calls, and this run executes locally. Add --hosted, or drop --base-url."@@ -117,7 +117,8 @@ def _print_hosted_failure(*, error: PipelineRequestError | HostedRunError, headirunning by an interruption can be looked up."""view = describe_hosted_error(error=error)- console = get_console()+ # On stderr, as every failure's report: stdout is the run's output.+ console = get_error_console()console.print(f"\n[bold red]{escape(heading)}[/bold red]\n")console.print(f" {escape(view.message)}\n")if view.validation_errors:diff --git a/pipelex/cli/commands/show_cmd.py b/pipelex/cli/commands/show_cmd.pyindex 764665c78..ed0653825 100644--- a/pipelex/cli/commands/show_cmd.py+++ b/pipelex/cli/commands/show_cmd.py@@ -29,6 +29,7 @@ from pipelex.system.configuration.config_loader import config_managerfrom pipelex.system.runtime import IntegrationModefrom pipelex.system.telemetry.events import EventName, EventPropertyfrom pipelex.tools.misc.exceptions import TomlError+from pipelex.tools.misc.file_utils import path_labelfrom pipelex.tools.misc.package_utils import get_package_versionif TYPE_CHECKING:@@ -46,11 +47,19 @@ def do_show_config() -> None:final_config = config_manager.load_config()pretty_print(final_config, title="Pipelex configuration")except TomlError as exc:+ # The configuration is layered, the packaged file then the home and the project ones, so the refusal names the+ # layer that does not parse, which the line and column belong to; a document read from no file names none.msg = f"Error loading configuration: {exc}"- raise PipelexConfigError(msg).with_error_code(PipelexErrorCode.CONFIG_SYNTAX) from exc+ failed_file = path_label(path=exc.path) if exc.path is not None else None+ raise (+ PipelexConfigError(msg, surface="pipelex", file=failed_file)+ .with_error_code(PipelexErrorCode.CONFIG_SYNTAX)+ .with_params(line=exc.lineno, column=exc.colno)+ ) from excexcept OSError as exc:msg = f"Error loading configuration: {exc}"- raise PipelexConfigError(msg).with_error_code(PipelexErrorCode.CONFIG_FILE_MISSING) from exc+ failed_file = path_label(path=Path(str(exc.filename))) if exc.filename is not None else None+ raise PipelexConfigError(msg, surface="pipelex", file=failed_file).with_error_code(PipelexErrorCode.CONFIG_FILE_MISSING) from excdef do_list_pipes() -> None:diff --git a/pipelex/cli/error_handlers.py b/pipelex/cli/error_handlers.pyindex a54aba568..b0bbfbb05 100644--- a/pipelex/cli/error_handlers.py+++ b/pipelex/cli/error_handlers.py@@ -12,11 +12,13 @@ from rich.traceback import Tracebackfrom pipelex.base_exceptions import ErrorDomain, PipelexConfigError, PipelexError, ValidationErrorCategory, ValidationErrorItem, iter_cause_chainfrom pipelex.cogt.exceptions import ModelDeckPresetValidationErrorfrom pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError+from pipelex.errors.failure_problem import failure_problem, format_problem_location, format_problem_verdict+from pipelex.errors.problem import PipelexProblem, ProblemView, cap_problem_textfrom pipelex.migration.exceptions import FormerReleaseConfigErrorfrom pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityErrorfrom pipelex.pipeline.exceptions import ValidateBundleErrorfrom pipelex.pipeline.validation_render import build_fix_command, count_applicable_fixes, suggested_fix_label, validation_item_title-from pipelex.runtime_hub import get_console+from pipelex.runtime_hub import get_error_consolefrom pipelex.system.telemetry.exceptions import TelemetryConfigValidationErrorfrom pipelex.urls import URLs@@ -84,30 +86,121 @@ def print_traceback_if_requested(*, console: Console) -> None:console.print(Traceback())-def print_unexpected_failure(*, console: Console, title: str, exc: BaseException) -> None:- """Print a command's own report of an unexpected failure: the title, then the exception's type and message.+def problem_panel_fields(+ *, problem: PipelexProblem, error_message: str | None, tip: str | None, with_next_step: bool = True+) -> list[tuple[str, str]]:+ """The rows a panel prints for its problem, their values escaped for Rich.- The catcher logs the failure at ERROR with its traceback, which the `console` sink renders under the line and a- structured sink writes to its log store. This report is the CLI's output, not a log record, so the terminal names- the cause whatever the sink and the level: under the `json` sink writing to a file, or a level above ERROR, it is- the only place the person running the command reads it. It prints no traceback, which the `console` sink already- shows under the log line.+ The problem's title, its detail when neither the title nor the error message already says it, its next step when the tip does+ not, its code with the domain and the retry verdict, then where it happened, the request and the run when known.++ Args:+ problem: The problem the panel reports, in the operator's view.+ error_message: The error message the panel prints, as printed (escaped), or ``None`` when it prints none.+ tip: The tip the panel prints, as printed (escaped or markup), or ``None`` when it prints none.+ with_next_step: Whether to print the code's next step, which a panel whose own remedy names the command that+ applies leaves out.++ Returns:+ ``(label, value)`` pairs, the values already escaped."""- exception_text = str(exc)- cause = f"{type(exc).__name__}: {exception_text}" if exception_text else type(exc).__name__+ rows: list[tuple[str, str]] = [("Problem", escape(problem.title))]+ detail = escape(problem.detail)+ if detail and detail not in {error_message, escape(problem.title)}:+ rows.append(("Detail", detail))+ next_step = escape(problem.next_step.detail)+ if with_next_step and next_step and next_step != tip:+ rows.append(("Next step", next_step))+ rows.append(("Code", f"[yellow]{escape(problem.code)}[/yellow] [dim]({escape(format_problem_verdict(problem=problem))})[/dim]"))+ where = format_problem_location(location=problem.location)+ if where:+ rows.append(("Location", escape(where)))+ if problem.request_id:+ rows.append(("Request id", escape(problem.request_id)))+ if problem.pipeline_run_id:+ rows.append(("Run", escape(problem.pipeline_run_id)))+ return rows+++def _print_panel_rows(*, console: Console, rows: list[tuple[str, str]]) -> None:+ """Print ``(label, value)`` rows with their labels padded to a common width, so the values line up."""+ label_width = max((len(label) for label, _ in rows), default=0)+ for label, value in rows:+ padded_label = f"{label}:".ljust(label_width + 1)+ console.print(f"[bold cyan]{padded_label}[/bold cyan] {value}")+++def print_problem_rows(*, console: Console, problem: PipelexProblem, error_message: str | None, tip: str | None, with_next_step: bool = True) -> None:+ """Print a panel's problem rows (:func:`problem_panel_fields`), followed by a blank line.++ Args:+ console: The console to print to.+ problem: The problem the panel reports, in the operator's view.+ error_message: The error message the panel prints, as printed (escaped), or ``None``.+ tip: The tip the panel prints, as printed (escaped or markup), or ``None``.+ with_next_step: Whether to print the code's next step.+ """+ rows = problem_panel_fields(problem=problem, error_message=error_message, tip=tip, with_next_step=with_next_step)+ _print_panel_rows(console=console, rows=rows)+ console.print()+++def print_failure_problem(*, console: Console, title: str, error: BaseException) -> PipelexProblem:+ """Print a command's own report of a failure it caught at its root, and return the failure's problem.++ The title, then the error's message: a Pipelex error's own, or, for an exception that is no Pipelex error, its type+ and its message capped as the operator view caps it. Then the problem's rows and the advice the error's chain gives+ as a tip. This report is the CLI's output, not a log record, so the terminal names the cause whatever the sink and+ the level: under the `json` sink writing to a file, or a level above ERROR, it is the only place the person running+ the command reads it. The log line the caller writes carries the problem's code and the chain's classes, never a+ message (:func:`pipelex.errors.failure_problem.failure_log_fields`), and a traceback only under ``--traceback``.++ Args:+ console: The console to print to.+ title: The headline, which names what failed.+ error: What the command caught.++ Returns:+ The failure's problem, in the operator's view, for the caller's log line.+ """+ problem = failure_problem(error=error)+ message: str+ advice: str | None+ if isinstance(error, PipelexError):+ message = error.message+ advice = _advice_detail(error=error)+ else:+ exception_text = cap_problem_text(text=str(error))+ message = f"{type(error).__name__}: {exception_text}" if exception_text else type(error).__name__+ advice = None+ # The message and the advice are plain text, a type such as `list[int]` or a model's description such as+ # `SDK[openai]` included, so they are escaped before Rich reads markup in them.+ printed_message = escape(message)+ printed_tip = escape(advice) if advice is not None else Noneconsole.print(f"\n[bold red]{escape(title)}[/bold red]\n")- # The cause is plain text, a type such as `list[int]` included, so it is escaped before Rich reads markup in it.- console.print(f" {escape(cause)}\n")+ console.print(f" {printed_message}\n")+ print_problem_rows(console=console, problem=problem, error_message=printed_message, tip=printed_tip)+ if printed_tip is not None:+ console.print(f"[bold green]💡 Tip:[/bold green] {printed_tip}\n")+ return problemdef display_error_panel(- *, console: Console, title: str, fields: list[tuple[str, str]], error_message: str | None, tip: str, links: list[tuple[str, str]]+ *,+ console: Console,+ title: str,+ fields: list[tuple[str, str]],+ error_message: str | None,+ problem: PipelexProblem | None,+ tip: str,+ links: list[tuple[str, str]],) -> None:"""Print the canonical CLI error panel.Layout: a red ❌ banner, an aligned block of structured fields, the error- message, a 💡 tip, and dimmed help links. Field labels are right-padded to- a common width so the values line up.+ message, the problem's rows (title, detail, next step, code, location,+ request id), a 💡 tip, and dimmed help links. Field labels are right-padded+ to a common width so the values line up.Exception-specific logic (which fields to include, what tip to derive)stays in each ``handle_*`` function; this helper owns only the panel shape.@@ -116,17 +209,21 @@ def display_error_panel(console: Rich console to print to.title: Headline text after the ❌ (already markup-safe).fields: ``(label, value)`` pairs; values must already be escaped.- error_message: The error message body, or None to omit it.- tip: The 💡 tip text (may span multiple lines / carry markup).+ error_message: The error message body (already markup-safe), or None to omit it.+ problem: The problem the panel reports, in the operator's view, or None to print no problem rows.+ tip: The 💡 tip text, printed as given: already markup-safe, its plain text escaped by the caller (it may+ span several lines and carry markup the caller meant).links: ``(label, url)`` pairs printed dimmed at the bottom."""console.print(f"\n[bold red]❌ {title}[/bold red]\n")- label_width = max((len(label) for label, _ in fields), default=0)- for label, value in fields:- padded_label = f"{label}:".ljust(label_width + 1)- console.print(f"[bold cyan]{padded_label}[/bold cyan] {value}")+ _print_panel_rows(console=console, rows=fields)if error_message is not None:console.print(f"\n[bold red]Error:[/bold red] {error_message}\n")+ elif fields:+ console.print()+ if problem is not None:+ print_problem_rows(console=console, problem=problem, error_message=error_message, tip=tip)+ # The tip is printed as given: its caller escaped the plain text in it and kept the markup it meant.console.print(f"[bold green]💡 Tip:[/bold green] {tip}")for link_label, link_url in links:console.print(f"[dim]{link_label}: {link_url}[/dim]")@@ -143,7 +240,7 @@ def handle_model_choice_error(exc: PipeOperatorModelChoiceError, *, context: Errthis handler: an unknown model is an invalid verdict there, rendered by:func:`handle_validate_bundle_error`."""- console = get_console()+ console = get_error_console()print_traceback_if_requested(console=console)tip = _advice_detail(error=exc) or (f"Check your model configuration in .pipelex/inference/ or specify a different model in the '{exc.pipe_code}' pipe."@@ -157,6 +254,7 @@ def handle_model_choice_error(exc: PipeOperatorModelChoiceError, *, context: Err("Model Choice", f"[yellow]'{escape(str(exc.model_choice))}'[/yellow]"),],error_message=escape(exc.message),+ problem=exc.to_problem(view=ProblemView.OPERATOR),tip=escape(tip),links=[("Learn more about the inference backend system", URLs.backend_provider_docs),@@ -176,7 +274,7 @@ def handle_model_availability_error(exc: PipeOperatorModelAvailabilityError, *,but no enabled backend serves is a setup fault of this machine, so no verdict, unlikean unknown model, which is an invalid verdict there. Other contexts keep the default 1."""- console = get_console()+ console = get_error_console()print_traceback_if_requested(console=console)fields: list[tuple[str, str]] = [("Pipe", f"[yellow]'{escape(exc.pipe_code)}'[/yellow] [dim]({escape(exc.pipe_type)})[/dim]"),@@ -214,6 +312,7 @@ def handle_model_availability_error(exc: PipeOperatorModelAvailabilityError, *,title=f"{context} failed because a model wasn't available",fields=fields,error_message=escape(str(exc)),+ problem=exc.to_problem(view=ProblemView.OPERATOR),tip=escape(tip),links=[("Learn more about the inference backend system", URLs.backend_provider_docs),@@ -245,7 +344,7 @@ def handle_model_deck_preset_error(exc: ModelDeckPresetValidationError, *, conteexc: The model deck preset validation error exceptioncontext: Context for the error message"""- console = get_console()+ console = get_error_console()print_traceback_if_requested(console=console)model_handle = exc.model_handle or ""fields: list[tuple[str, str]] = [@@ -283,6 +382,7 @@ def handle_model_deck_preset_error(exc: ModelDeckPresetValidationError, *, contetitle=f"{context} failed due to model deck preset validation error",fields=fields,error_message=escape(exc.message),+ problem=exc.to_problem(view=ProblemView.OPERATOR),tip=tip,links=[("Learn more about the inference backend system", URLs.backend_provider_docs),@@ -386,7 +486,7 @@ def handle_validate_bundle_error(the actionable fix command preserves the same leniency."""items = exc.validation_error_items()- console = get_console()+ console = get_error_console()print_traceback_if_requested(console=console)console.print("\n[bold red]❌ Bundle validation failed[/bold red]\n")@@ -398,7 +498,9 @@ def handle_validate_bundle_error(# A hint needs an action behind it: when fixes exist, the actionable footer replaces the# generic tip (two stacked 💡 tips would be noise).fixable_count = count_applicable_fixes(items, bundle_path=bundle_path, library_dirs=library_dirs) if bundle_path is not None else 0+ problem = exc.to_problem(view=ProblemView.OPERATOR)if fixable_count and bundle_path is not None:+ print_problem_rows(console=console, problem=problem, error_message=None, tip=None)# Shared builder so the human and agent fix-command footers echo -L / --allow-signatures identically.fix_command = build_fix_command(executable="pipelex", bundle_path=bundle_path, library_dirs=library_dirs, allow_signatures=allow_signatures)console.print(@@ -409,7 +511,10 @@ def handle_validate_bundle_error("Review the error messages above and check your pipeline configuration. ""Make sure all required fields are present and correctly formatted.")- console.print(f"[bold green]💡 Tip:[/bold green] {escape(tip)}")+ # The advice is plain text, a model's description such as `SDK[openai]` included, escaped once for Rich.+ printed_tip = escape(tip)+ print_problem_rows(console=console, problem=problem, error_message=None, tip=printed_tip)+ console.print(f"[bold green]💡 Tip:[/bold green] {printed_tip}")console.print(f"[dim]Learn more: {URLs.documentation}[/dim]")console.print(f"[dim]Join our Discord for help: {URLs.discord}[/dim]\n")raise typer.Exit(1) from exc@@ -428,7 +533,7 @@ def handle_pre_boot_config_error(*, exc: PipelexConfigError, command: str, exit_command: The human command name, as the command's other failures name it (e.g. ``"validate"``).exit_code: The exit code the command gives a failed boot."""- print_traceback_if_requested(console=get_console())+ print_traceback_if_requested(console=get_error_console())typer.secho(f"Failed to {command}: {exc.message}", fg=typer.colors.RED, err=True)raise typer.Exit(exit_code) from exc@@ -449,12 +554,14 @@ def handle_telemetry_config_validation_error(exc: TelemetryConfigValidationErrorArgs:exc: The telemetry config validation error exception"""- console = get_console()+ console = get_error_console()print_traceback_if_requested(console=console)console.print("\n[bold red]❌ Telemetry configuration could not be loaded[/bold red]\n")console.print(escape(exc.message))console.print()+ # The remedy below names the command that applies, which the code's generic next step does not.+ print_problem_rows(console=console, problem=exc.to_problem(view=ProblemView.OPERATOR), error_message=None, tip=None, with_next_step=False)if exc.migration is not None and exc.migration.would_write:console.print(f"[bold green]💡 To fix:[/bold green] Run [cyan]{exc.migration.remedy}[/cyan] to bring your configuration up to date\n")@@ -483,10 +590,12 @@ def handle_former_release_config_error(*, exc: FormerReleaseConfigError) -> NoReArgs:exc: The former release configuration error."""- console = get_console()+ console = get_error_console()print_traceback_if_requested(console=console)console.print("\n[bold red]❌ Configuration left by a former release[/bold red]\n")console.print(escape(exc.message))console.print()+ # The message names the remedies, which the code's generic next step does not.+ print_problem_rows(console=console, problem=exc.to_problem(view=ProblemView.OPERATOR), error_message=None, tip=None, with_next_step=False)console.print(f"[dim]Join our Discord for help: {URLs.discord}[/dim]\n")raise typer.Exit(1) from excdiff --git a/pipelex/cli/usage_stats_cli.py b/pipelex/cli/usage_stats_cli.pyindex d04e2191e..c4714885f 100644--- a/pipelex/cli/usage_stats_cli.py+++ b/pipelex/cli/usage_stats_cli.py@@ -11,7 +11,7 @@ commands never send, queue or print the notice.import timefrom collections.abc import Callable, Sequence-from typing import Any, NamedTuple, Protocol, TypeVar, runtime_checkable+from typing import Any, NamedTuple, Protocol, TypeVar, cast, runtime_checkableimport click@@ -28,7 +28,7 @@ from pipelex.system.usage_stats.usage_stats_contract import (UsageStatsSurface,)from pipelex.system.usage_stats.usage_stats_events import CommandCompletedProperties, UsageStatsEvent, bounded_duration_ms-from pipelex.system.usage_stats.usage_stats_runs import usage_stats_error_domain+from pipelex.system.usage_stats.usage_stats_runs import usage_stats_errorfrom pipelex.tools.log.error_fields import error_fields#: The statistics command group, `pipelex usage-stats`.@@ -39,6 +39,8 @@ INTERRUPTED_EXIT_CODE = 130_FORMAT_OPTION = "--format"_ERROR_FORMAT_OPTION = "--error-format"_JSON = "json"+#: The formats a `pipelex-agent` error stream is written in, which a command's `--format` must offer for its errors to follow it.+_ERROR_FORMATS = frozenset({"json", "markdown"})ResultT = TypeVar("ResultT")@@ -98,23 +100,35 @@ def _default_of(*, command: click.Command, option: str) -> str | None:return str(param.default)-def _errors_are_json(*, command: click.Command, args: Sequence[str]) -> bool:- """Whether a `pipelex-agent` command's errors are JSON: `--error-format`, else `--format`, else its defaults.+def _format_feeds_errors(*, param: click.Parameter | None) -> bool:+ """Whether a command's `--format` decides its errors when nothing else does: a presentation format, markdown or json.- A command with neither option is one of the JSON-only commands, whose errors are always the JSON envelope.+ `inputs`' `--format` chooses a template's serialization, json or toml, and its errors never follow it."""- has_error_format = _find_param(command=command, token=_ERROR_FORMAT_OPTION) is not None- has_format = _find_param(command=command, token=_FORMAT_OPTION) is not None- if not has_error_format and not has_format:- return True- chosen = _option_value(args=args, option=_ERROR_FORMAT_OPTION) if has_error_format else None- if chosen is None and has_format:- chosen = _option_value(args=args, option=_FORMAT_OPTION)- if chosen is None and has_error_format:- chosen = _default_of(command=command, option=_ERROR_FORMAT_OPTION)- if chosen is None and has_format:- chosen = _default_of(command=command, option=_FORMAT_OPTION)- return chosen is not None and chosen.strip().lower() == _JSON+ if param is None:+ return False+ param_type: click.ParamType = param.type+ if not isinstance(param_type, click.Choice):+ return False+ choices = cast("click.Choice[Any]", param_type).choices+ return frozenset(str(choice) for choice in choices) == _ERROR_FORMATS+++def _errors_are_json(*, command: click.Command, args: Sequence[str], root_error_format: str | None) -> bool:+ """Whether a `pipelex-agent` command's errors are JSON, with the precedence the command itself settles them by.++ The command's own `--error-format`, else the program's (`root_error_format`, given before the command), else the+ command's `--format` when it is a presentation format, given or by default, else JSON: the order+ `pipelex.cli.agent_cli.commands.agent_output.use_agent_cli_error_format` applies, so the notice is kept off a+ stream that will carry a JSON problem, wherever the flag that made it JSON was written.+ """+ chosen: str | None = None+ if _find_param(command=command, token=_ERROR_FORMAT_OPTION) is not None:+ chosen = _option_value(args=args, option=_ERROR_FORMAT_OPTION) or _default_of(command=command, option=_ERROR_FORMAT_OPTION)+ chosen = chosen or root_error_format+ if chosen is None and _format_feeds_errors(param=_find_param(command=command, token=_FORMAT_OPTION)):+ chosen = _option_value(args=args, option=_FORMAT_OPTION) or _default_of(command=command, option=_FORMAT_OPTION)+ return chosen is None or chosen.strip().lower() == _JSONdef _allowed_commands(*, surface: UsageStatsSurface) -> frozenset[str]:@@ -140,12 +154,15 @@ def resolve_invocation(*, root: click.Group, args: Sequence[str], surface: UsageThe command is its path of names in the tree, aliases and a group's default routing resolved, `other` when the schemadoes not list it (or no command has that name), and `None` when nothing is counted: help, the version, no command at- all, or the statistics group.+ all, or the statistics group. The only values read are the formats the errors will be written in, the program's+ `--error-format` and the command's own options, so a notice is never printed ahead of a JSON problem."""not_counted = CliInvocation(command=None, is_statistics_group=False, is_machine_read=False)help_names = {"--help"}current: click.Command = rootpath: list[str] = []+ # The program's own `--error-format`, given before the command, which the command's errors follow unless it has its own.+ root_error_format: str | None = Noneindex_arg = 0while isinstance(current, click.Group):if isinstance(current, RoutesToDefaultCommand):@@ -168,13 +185,17 @@ def resolve_invocation(*, root: click.Group, args: Sequence[str], surface: Usage# `--version` and `-V`: they print and exit before any command runs.return not_countedconsumed = 2 if param is not None and "=" not in token and _takes_value(param=param) else 1+ if param is not None and _ERROR_FORMAT_OPTION in param.opts:+ root_error_format = _option_value(args=args[index_arg : index_arg + consumed], option=_ERROR_FORMAT_OPTION)index_arg += consumedcontinueif not path and token == STATISTICS_GROUP_NAME:return CliInvocation(command=None, is_statistics_group=True, is_machine_read=False)subcommand = current.commands.get(token)if subcommand is None:- return CliInvocation(command=OTHER_COMMAND, is_statistics_group=False, is_machine_read=_is_machine_read_surface(surface=surface))+ # An unknown command is refused in the program's error format, JSON unless `--error-format` said otherwise.+ is_unknown_machine_read = _is_machine_read_surface(surface=surface) and (root_error_format or _JSON).strip().lower() == _JSON+ return CliInvocation(command=OTHER_COMMAND, is_statistics_group=False, is_machine_read=is_unknown_machine_read)path.append(token)current = subcommandindex_arg += 1@@ -185,7 +206,9 @@ def resolve_invocation(*, root: click.Group, args: Sequence[str], surface: Usagereturn not_countedcommand_path = " ".join(path)command = command_path if command_path in _allowed_commands(surface=surface) else OTHER_COMMAND- is_machine_read = _is_machine_read_surface(surface=surface) and _errors_are_json(command=current, args=leaf_args)+ is_machine_read = _is_machine_read_surface(surface=surface) and _errors_are_json(+ command=current, args=leaf_args, root_error_format=root_error_format+ )return CliInvocation(command=command, is_statistics_group=False, is_machine_read=is_machine_read)@@ -280,9 +303,9 @@ def _end_command(runs whatever the one before it did."""try:- error_domain = None+ command_error = Noneif outcome.is_failed:- error_domain = usage_stats_error_domain(error=failure) if failure is not None else client.command_error_domain+ command_error = usage_stats_error(error=failure) if failure is not None else client.command_errorinit_properties: dict[str, Any] = {}if client.command_init_choices is not None and command == INIT_COMMAND:init_properties = client.command_init_choices.as_properties()@@ -292,7 +315,8 @@ def _end_command(properties=CommandCompletedProperties(command=command,outcome=outcome,- error_domain=error_domain,+ error_code=command_error.code if command_error is not None else None,+ error_domain=command_error.domain if command_error is not None else None,duration_ms=bounded_duration_ms(seconds=duration_seconds),hosted=True if client.is_command_hosted else None,**init_properties,diff --git a/pipelex/cogt/inference/inference_call_summary.py b/pipelex/cogt/inference/inference_call_summary.pyindex 3948977cb..240f6a44f 100644--- a/pipelex/cogt/inference/inference_call_summary.py+++ b/pipelex/cogt/inference/inference_call_summary.py@@ -38,11 +38,10 @@ from typing import TYPE_CHECKING, Anyfrom typing_extensions import overridefrom pipelex import log-from pipelex.cogt.exceptions import find_inference_error_category_in_chainfrom pipelex.cogt.usage.token_category import TokenCategoryfrom pipelex.cogt.usage.usage_cost import compute_tokens_usage_costfrom pipelex.system.telemetry.otel_constants import GenAISpanAttr-from pipelex.system.usage_stats.usage_stats_runs import current_run_tally+from pipelex.system.usage_stats.usage_stats_runs import current_run_tally, usage_stats_failure_domainfrom pipelex.tools.log.console_layouts import LogLayoutfrom pipelex.tools.log.summary_event import SummaryEventfrom pipelex.tools.log.summary_fields import COST_USD_FIELD@@ -137,7 +136,7 @@ class InferenceCallSummary(SummaryEvent):self._note_in_run_tally(error=error)def _note_in_run_tally(self, *, error: BaseException | None) -> None:- """Note how the call ended in its run's tally: its model and backend, and, for a failure, the runtime's category.+ """Note how the call ended in its run's tally: its model and backend, and, for a failure, the domain of its error's code.A call stopped from outside is a call, not a failure. A call whose handle resolved to no model counts in the run'stotals only, since no backend served it.@@ -146,15 +145,10 @@ class InferenceCallSummary(SummaryEvent):if run_tally is None:returninference_model = self._read_inference_model()- failed = isinstance(error, Exception)- failure_category: str | None = None- if isinstance(error, Exception):- failure_category = find_inference_error_category_in_chain(error)run_tally.note_call(model_handle=inference_model.name if inference_model is not None else self._model_handle,backend_name=inference_model.backend_name if inference_model is not None else None,- failed=failed,- failure_category=failure_category,+ failure_domain=usage_stats_failure_domain(error=error) if isinstance(error, Exception) else None,images_generated=self._images_generated,pages_extracted=self._pages_extracted,)diff --git a/pipelex/cogt/models/model_manager.py b/pipelex/cogt/models/model_manager.pyindex eb6fcd231..03fba13eb 100644--- a/pipelex/cogt/models/model_manager.py+++ b/pipelex/cogt/models/model_manager.py@@ -28,9 +28,10 @@ from pipelex.cogt.models.model_manager_abstract import ModelManagerAbstractfrom pipelex.config import get_configfrom pipelex.migration.exceptions import FormerReleaseConfigErrorfrom pipelex.migration.former_release import describe_former_release_boot_refusal, former_release_boot_blockers+from pipelex.migration.former_release_cleanup import former_release_pending_migrationfrom pipelex.plugins.plugin_model_declarations import PluginModelDeclarationsfrom pipelex.system.configuration.config_loader import config_manager-from pipelex.tools.misc.file_utils import find_files_in_dir+from pipelex.tools.misc.file_utils import find_files_in_dir, path_labelfrom pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstract@@ -94,7 +95,13 @@ class ModelManager(ModelManagerAbstract):routing_profile_library_paths=resolved_routing_profile_library_paths,):msg = describe_former_release_boot_refusal(blockers=blockers)- raise FormerReleaseConfigError(msg)+ # The step names the first of them, the backend library's before the routing profiles'.+ first_blocker = blockers[0]+ # What `pipelex migrate` would do about them rides the problem as its pending migration, for a JSON reader.+ migration = former_release_pending_migration(config_dirs=config_manager.existing_config_dirs)+ raise FormerReleaseConfigError(msg, migration=migration).with_params(+ surface="inference", file=path_label(path=first_blocker.file_path), setting=first_blocker.setting+ )self.inference_backend_library.load(secrets_provider=secrets_provider,backends_library_paths=resolved_backends_library_paths,diff --git a/pipelex/core/validation.py b/pipelex/core/validation.pyindex e639d962d..1853e7625 100644--- a/pipelex/core/validation.py+++ b/pipelex/core/validation.py@@ -24,7 +24,9 @@ from pydantic import BaseModel, ConfigDict, ValidationErrorfrom pipelex.base_exceptions import MigrationErrorBlock, PipelexConfigErrorfrom pipelex.migration.exceptions import MigrationErrorfrom pipelex.migration.plan import MigrationPlan-from pipelex.system.configuration.config_loader import pydantic_error_behind+from pipelex.system.configuration.config_loader import CONFIG_NAME, pydantic_error_behind+from pipelex.system.configuration.config_surface import PIPELEX_CONFIG_SURFACE_ID, TELEMETRY_CONFIG_SURFACE_ID+from pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAMEfrom pipelex.tools.typing.pydantic_utils import analyze_pydantic_validation_errorMIGRATE_COMMAND = "pipelex migrate"@@ -46,6 +48,29 @@ class ValidationErrorReport(BaseModel):"""What a `pipelex migrate` would find for the surface that refused, when a scan foundanything at all. `None` means the failure is not staleness — or that no surface was named."""+ setting: str | None = None+ """The setting the first refusal names, as a dotted path of keys, which the refusal's problem gives its step;+ `None` when the refusal names none, or carries no pydantic error. A path of names, never a value."""+++#: The part of the configuration and the file a surface's refusal names, by the surface's id.+_SURFACE_PARTS: dict[str, tuple[str, str]] = {+ PIPELEX_CONFIG_SURFACE_ID: ("pipelex", CONFIG_NAME),+ TELEMETRY_CONFIG_SURFACE_ID: ("telemetry", TELEMETRY_CONFIG_FILE_NAME),+}+++def refused_setting(*, validation_error: ValidationError) -> str | None:+ """The setting the first refusal of `validation_error` names, as a dotted path of keys; `None` when none names one.++ Only the location is read, never the input, so no value from the user's file reaches it.+ """+ for error in validation_error.errors(include_url=False, include_input=False, include_context=False):+ location = [str(part) for part in error["loc"]]+ if location:+ return ".".join(location)+ return None+def report_validation_error(*,@@ -71,7 +96,8 @@ def report_validation_error(The translated message and, when a scan found something, the structured migration block."""message = analyze_pydantic_validation_error(validation_error).error_msg- return _report_after_the_scan(message=message, surface_id=surface_id, config_dirs=config_dirs)+ report = _report_after_the_scan(message=message, surface_id=surface_id, config_dirs=config_dirs)+ return report.model_copy(update={"setting": refused_setting(validation_error=validation_error)})def report_config_refusal(@@ -115,8 +141,9 @@ def report_config_refusal(Returns:The body and, when a scan found something, the structured migration block."""- message = analyze_pydantic_validation_error(refusal).error_msg if isinstance(refusal, ValidationError) else str(refusal)- return _report_after_the_scan(message=message, surface_id=surface_id, config_dirs=config_dirs)+ if isinstance(refusal, ValidationError):+ return report_validation_error(validation_error=refusal, surface_id=surface_id, config_dirs=config_dirs)+ return _report_after_the_scan(message=str(refusal), surface_id=surface_id, config_dirs=config_dirs)def _report_after_the_scan(*, message: str, surface_id: str | None, config_dirs: list[Path] | None) -> ValidationErrorReport:@@ -154,7 +181,8 @@ def raise_config_setup_error(*, config_error: Exception, surface_id: str, configraise config_errorreport = report_validation_error(validation_error=validation_error, surface_id=surface_id, config_dirs=config_dirs)msg = f"Could not setup config because of: {report.message}"- raise PipelexConfigError(msg, migration=report.migration) from config_error+ surface, file = _SURFACE_PARTS.get(surface_id, (surface_id, None))+ raise PipelexConfigError(msg, migration=report.migration, surface=surface, file=file, setting=report.setting) from config_errordef _pending_migration(*, surface_id: str, config_dirs: list[Path] | None) -> MigrationErrorBlock | None:diff --git a/pipelex/errors/failure_problem.py b/pipelex/errors/failure_problem.pynew file mode 100644index 000000000..7b5cd5275--- /dev/null+++ b/pipelex/errors/failure_problem.py@@ -0,0 +1,166 @@+"""The problem of a failure a local command caught, whatever raised it, and the identifiers its log line carries.++A local CLI reports what a command raised in the operator's view, the view of whoever runs the runtime: a Pipelex+error's own problem, which its code decides, or, for an exception that is no Pipelex error, the registry's catch-all+``runtime.unexpected``, with the exception's class, its message capped and its causes' classes in the diagnostics. Both+CLIs read it from here, ``pipelex-agent`` to print it on its error stream and ``pipelex`` to print its panel, so the two+report one failure the same way.++The log line a command root writes about a failure carries identifiers only: the problem's code, the exception's class,+the classes along its cause chain and the frames the failure began in, each by its module, its line and its function,+so a log store says where an unexpected failure happened. An exception's text, and the text of every exception chained to it, can quote a+run's data — a foreign ``ValidationError`` quotes the values it refused, a method function's exception says what the+function was given — and a log record reaches stores and readers a run's data must not. The capped message belongs to+the operator view the terminal prints, and the traceback, which prints every chained exception's text, rides the record+only when the person running the command asked for it. A frame is named without its source line and without its+locals, which can hold a run's data as well as the text can.+"""++from pathlib import Path+from types import TracebackType+from typing import Any++from mthds.protocol.problem.models import ProblemLocation+from mthds.protocol.problem.registry import CoreCode++from pipelex.base_exceptions import PipelexError, iter_cause_chain+from pipelex.errors.problem import (+ DiagnosticCause,+ PipelexProblem,+ ProblemDiagnostics,+ ProblemView,+ cap_problem_text,+ make_problem,+ runtime_version,+)+from pipelex.tools.log.error_fields import ERROR_CODE_FIELD, ERROR_TYPE_FIELD++#: The classes along the failure's cause chain, the failure's own first, which a line gives in place of their texts.+ERROR_CHAIN_FIELD = "error.chain"++#: The frames the failure went through, from the command's root down to where its first exception was raised, each+#: ``module:line in function``, which a line gives in place of the traceback.+ERROR_FRAMES_FIELD = "error.frames"++#: The most frames ``error.frames`` holds: the innermost, where the failure began, when there are more, as a runaway+#: recursion gives.+MAX_LOGGED_FRAMES = 40+++def foreign_failure_diagnostics(*, error: BaseException) -> ProblemDiagnostics:+ """The operator's diagnostics of an error that is no Pipelex error: its class, its message capped and its causes."""+ causes = [DiagnosticCause(error_class=type(node).__name__) for node in iter_cause_chain(error) if node is not error]+ return ProblemDiagnostics(+ error_class=type(error).__name__,+ message=cap_problem_text(text=str(error) or repr(error)),+ causes=causes or None,+ runtime_version=runtime_version(),+ )+++def failure_diagnostics(*, cause: BaseException | None) -> ProblemDiagnostics | None:+ """The operator's diagnostics of the error a refusal was raised from, ``None`` when it was raised from none."""+ if cause is None:+ return None+ if isinstance(cause, PipelexError):+ return cause.to_problem(view=ProblemView.OPERATOR).diagnostics+ return foreign_failure_diagnostics(error=cause)+++def failure_problem(*, error: BaseException) -> PipelexProblem:+ """The problem of a failure a local command caught, in the operator's view.++ Args:+ error: What the command caught.++ Returns:+ The Pipelex error's own problem, else ``runtime.unexpected`` with the foreign error's diagnostics.+ """+ if isinstance(error, PipelexError):+ return error.to_problem(view=ProblemView.OPERATOR)+ return make_problem(code=CoreCode.RUNTIME_UNEXPECTED, view=ProblemView.OPERATOR, diagnostics=foreign_failure_diagnostics(error=error))+++def _frame_labels(*, traceback: TracebackType | None) -> list[str]:+ """Each frame of a traceback as ``module:line in function``, outermost first: no source line, no local, no text.++ The module is the one the frame's code ran in, so a path naming the machine's directories never reaches the line;+ a frame of code no module holds is named by its file's name.+ """+ labels: list[str] = []+ node = traceback+ while node is not None:+ frame = node.tb_frame+ code = frame.f_code+ module = frame.f_globals.get("__name__")+ where = module if isinstance(module, str) else Path(code.co_filename).name+ labels.append(f"{where}:{node.tb_lineno} in {code.co_name}")+ node = node.tb_next+ return labels+++def failure_frames(*, error: BaseException) -> list[str]:+ """The frames a failure went through, from where it was caught down to where its first exception was raised.++ Each exception's traceback runs from where it was caught to where it was raised, and the cause of one was caught+ where that one was raised, so the chain's tracebacks, the failure's own first, read one after the other as the path+ down to the fault. The innermost :data:`MAX_LOGGED_FRAMES` are kept.+ """+ labels: list[str] = []+ for node in iter_cause_chain(error):+ labels += _frame_labels(traceback=node.__traceback__)+ return labels[-MAX_LOGGED_FRAMES:]+++def failure_log_fields(*, error: BaseException, problem: PipelexProblem) -> dict[str, Any]:+ """The fields a command root's log line about a failure carries: identifiers, never an exception's text.++ Args:+ error: What the command caught.+ problem: The failure's problem, whose code the line names.++ Returns:+ ``error.code``, the problem's code, ``error.type``, the failure's class, ``error.chain``, the classes along its+ cause chain, its own first, and ``error.frames``, the frames it went through down to the fault+ (:func:`failure_frames`).+ """+ return {+ ERROR_CODE_FIELD: problem.code,+ ERROR_TYPE_FIELD: type(error).__name__,+ ERROR_CHAIN_FIELD: [type(node).__name__ for node in iter_cause_chain(error)],+ ERROR_FRAMES_FIELD: failure_frames(error=error),+ }+++def format_problem_location(*, location: ProblemLocation | None) -> str:+ """Where a fault happened, in words: ``pipe 'summarize', path main > summarize, file 'contracts.mthds', line 12``."""+ if location is None:+ return ""+ parts: list[str] = []+ if location.pipe is not None:+ parts.append(f"pipe '{location.pipe}'")+ if location.path:+ parts.append(f"path {' > '.join(location.path)}")+ if location.input is not None:+ parts.append(f"input '{location.input}'")+ if location.field is not None:+ parts.append(f"field '{location.field}'")+ if location.item is not None:+ parts.append(f"item {location.item}")+ if location.attempt is not None:+ parts.append(f"attempt {location.attempt}")+ if location.file is not None:+ parts.append(f"file '{location.file}'")+ if location.line is not None:+ parts.append(f"line {location.line}")+ if location.column is not None:+ parts.append(f"column {location.column}")+ return ", ".join(parts)+++def format_problem_verdict(*, problem: PipelexProblem) -> str:+ """The problem's verdict in words: ``domain runtime, retry yes, after 30 seconds``."""+ verdict = [f"domain {problem.effective_domain}", f"retry {problem.effective_retry}"]+ if problem.retry_after is not None:+ verdict.append(f"after {problem.retry_after:g} seconds")+ return ", ".join(verdict)diff --git a/pipelex/errors/security_event.py b/pipelex/errors/security_event.pyindex 68df09bc0..ee8cc1daf 100644--- a/pipelex/errors/security_event.py+++ b/pipelex/errors/security_event.py@@ -40,7 +40,7 @@ from pipelex.errors.error_code_declaration import InheritsCausefrom pipelex.errors.error_codes import ErrorCode, error_code_specfrom pipelex.errors.registry.pipelex_codes import PipelexErrorCodefrom pipelex.errors.security_target import SecurityTargetClass, SecurityTargetKind-from pipelex.tools.log.error_fields import ERROR_TYPE_FIELD+from pipelex.tools.log.error_fields import ERROR_CODE_FIELD, ERROR_TYPE_FIELDfrom pipelex.tools.log.log import logfrom pipelex.tools.log.log_context import PIPELINE_RUN_ID_FIELD, REQUEST_ID_FIELD@@ -58,9 +58,6 @@ SECURITY_EVENT_NAME = "pipelex.security.refusal"#: The field naming the kind of record, the OpenTelemetry semantic-convention key for a log event's name.EVENT_NAME_FIELD = "event.name"-#: The field carrying the refusal's registry code.-ERROR_CODE_FIELD = "error.code"-#: The field carrying the code's domain, who caused the refusal.ERROR_DOMAIN_FIELD = "error.domain"diff --git a/pipelex/fix_ops/exceptions.py b/pipelex/fix_ops/exceptions.pyindex 0bbc7dd09..8ef047a25 100644--- a/pipelex/fix_ops/exceptions.py+++ b/pipelex/fix_ops/exceptions.py@@ -1,4 +1,8 @@+from pathlib import Path+from typing import Any+from mthds.protocol.problem.registry import CoreCode+from typing_extensions import overridefrom pipelex.base_exceptions import PipelexError, PipelexUnexpectedError@@ -13,3 +17,22 @@ class FixTransactionError(PipelexUnexpectedError):"""A multi-file commit failed and could not be fully rolled back."""error_code = CoreCode.RUNTIME_UNEXPECTED+++class FixWriteFailedError(PipelexError):+ """A fix could not write a file it fixed: the file or its directory refused the write, and the round was rolled back.++ It is ``client.write_failed``, naming the file, or the directory a copy staged beside it could not be written in, and+ the system's reason, so a write failure is never read as a method file that cannot be read.+ """++ error_code = CoreCode.CLIENT_WRITE_FAILED++ def __init__(self, message: str, *, path: Path, reason: str):+ super().__init__(message)+ self.path = path+ self.reason = reason++ @override+ def problem_params(self) -> dict[str, Any]:+ return {"path": str(self.path), "reason": self.reason}diff --git a/pipelex/kit/agent_rules/python_standards.md b/pipelex/kit/agent_rules/python_standards.mdindex 21d82a7a0..cbf1315cc 100644--- a/pipelex/kit/agent_rules/python_standards.md+++ b/pipelex/kit/agent_rules/python_standards.md@@ -75,7 +75,7 @@pretty_print(output_object, title="Your first Pipelex output")```- Both handle formatting json using Rich, pretty_print makes it prettier.-- A log message is a fixed sentence with its values in `fields=`, never interpolated at INFO and above, and never holding Rich markup: `log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})`. It is one short sentence, subject first, starting with a capital and ending with no period or `...`, with no backtick and, at INFO and above, no identifier and at most 80 characters; advice rides in a `user_action` field ("Wording a message" in `docs/tools/logging.md`). A handled exception at WARNING and below rides in `fields=` as `**error_fields(exc=exc)` (`pipelex.tools.log.error_fields`), at ERROR as `include_exception=True`, never as `{exc}` in the text, at any level; an exception logged and then re-raised rides as `**error_fields(exc=exc)` at every level, its traceback being its catcher's to print, and so do a cleanup's failure while another exception propagates, whose traceback would chain the primary's text, and a swallowed pydantic `ValidationError`, whose traceback quotes the values it refused. The catcher of an unexpected failure, a CLI command's root or the API's error handler, logs it at ERROR with `include_exception=True` and prints no traceback of its own; a CLI command's root also prints the exception's type and message in its own output (`print_unexpected_failure` in `pipelex.cli.error_handlers`), so the terminal names the cause whatever the sink and the level. Field names come from the vocabulary table in `docs/tools/logging.md` ("Log-call conventions"), which review holds the calls to: `make check-log-calls` reads the messages, never the `fields=` keys.+- A log message is a fixed sentence with its values in `fields=`, never interpolated at INFO and above, and never holding Rich markup: `log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias})`. It is one short sentence, subject first, starting with a capital and ending with no period or `...`, with no backtick and, at INFO and above, no identifier and at most 80 characters; advice rides in a `user_action` field ("Wording a message" in `docs/tools/logging.md`). A handled exception at WARNING and below rides in `fields=` as `**error_fields(exc=exc)` (`pipelex.tools.log.error_fields`), at ERROR as `include_exception=True`, never as `{exc}` in the text, at any level; an exception logged and then re-raised rides as `**error_fields(exc=exc)` at every level, its traceback being its catcher's to print, and so do a cleanup's failure while another exception propagates, whose traceback would chain the primary's text, and a swallowed pydantic `ValidationError`, whose traceback quotes the values it refused. The API's error handler, the catcher of an unexpected failure, logs it at ERROR with `include_exception=True` and prints no traceback of its own. A CLI command's root logs an unexpected failure at ERROR with identifiers only, `fields=failure_log_fields(error=exc, problem=problem)` (`pipelex.errors.failure_problem`: the problem's code and the chain's classes, never a chained exception's text, which can quote a run's data) and `include_exception=is_traceback_requested()`, so the traceback rides only under `--traceback`; it prints the failure's problem in its own output (`print_failure_problem` in `pipelex.cli.error_handlers`), so the terminal names the cause whatever the sink and the level. Field names come from the vocabulary table in `docs/tools/logging.md` ("Log-call conventions"), which review holds the calls to: `make check-log-calls` reads the messages, never the `fields=` keys.### StrEnum and Self typediff --git a/pipelex/migration/exceptions.py b/pipelex/migration/exceptions.pyindex 86488cdb3..b7c68bb5f 100644--- a/pipelex/migration/exceptions.py+++ b/pipelex/migration/exceptions.py@@ -1,10 +1,12 @@from typing import ClassVarfrom mthds.protocol.problem.registry import CoreCode+from typing_extensions import override-from pipelex.base_exceptions import PipelexError, PipelexSetupError+from pipelex.base_exceptions import PipelexError, PipelexSetupError, ProblemFactsfrom pipelex.cogt.inference.error_classification import UserAction, UserActionKindfrom pipelex.errors.error_code_declaration import ABSTRACT_ERROR, ErrorCodeDeclaration, InheritsCause+from pipelex.errors.problem import MigrationErrorBlockfrom pipelex.errors.registry.pipelex_codes import PipelexErrorCode@@ -82,3 +84,13 @@ class FormerReleaseConfigError(PipelexSetupError):"(its 'former_release' key), show the user, then run 'pipelex-agent migrate --yes'."),)++ def __init__(self, message: str, *, migration: MigrationErrorBlock | None = None):+ super().__init__(message)+ # What `pipelex migrate` would do about it, from the cleanup's dry run, so a JSON reader of the problem, which+ # carries no tip, branches on `diagnostics.migration` as it does for a stale configuration.+ self.migration = migration++ @override+ def problem_facts(self) -> ProblemFacts:+ return ProblemFacts(migration=self.migration)diff --git a/pipelex/migration/former_release.py b/pipelex/migration/former_release.pyindex 4ddefc5ba..074a0308c 100644--- a/pipelex/migration/former_release.py+++ b/pipelex/migration/former_release.py@@ -199,6 +199,29 @@ class FormerReleaseFinding(BaseModel):whole for every boot reading the file, the `active` is left as it is, and so it is when moving it would changethe profile another boot starts on."""+ @property+ def setting(self) -> str | None:+ """The key the finding is at in its file, as a dotted path; `None` for a finding that is a whole file."""+ match self.kind:+ case FormerReleaseFindingKind.RETIRED_BACKEND_TABLE:+ return self.subject+ case FormerReleaseFindingKind.MODEL_SPECS_SECTION_KEY:+ return f"{self.subject}.{MODEL_SPECS_SECTION_KEY}"+ case (+ FormerReleaseFindingKind.RETIRED_BACKEND_FILE+ | FormerReleaseFindingKind.GATEWAY_MODELS_REFERENCE+ | FormerReleaseFindingKind.SERVICE_FILE+ ):+ return None+ case FormerReleaseFindingKind.RETIRED_ROUTING_PROFILE:+ return f"{ROUTING_PROFILES_KEY}.{self.subject}"+ case FormerReleaseFindingKind.RETIRED_PROFILE_DEFAULT:+ return f"{ROUTING_PROFILES_KEY}.{self.subject}.{_DEFAULT_KEY}"+ case FormerReleaseFindingKind.ROUTE_TO_RETIRED_BACKEND:+ return f"{ROUTING_PROFILES_KEY}.{self.subject}.{self.route_table or _ROUTES_KEY}"+ case FormerReleaseFindingKind.ACTIVE_ROUTING_PROFILE | FormerReleaseFindingKind.PROJECT_ACTIVE_ROUTING_PROFILE:+ return ACTIVE_KEY+@propertydef description(self) -> str:"""The finding as one sentence, for a report a person reads."""diff --git a/pipelex/migration/former_release_cleanup.py b/pipelex/migration/former_release_cleanup.pyindex d1624d0cf..16ca835dc 100644--- a/pipelex/migration/former_release_cleanup.py+++ b/pipelex/migration/former_release_cleanup.py@@ -53,9 +53,11 @@ from tomlkit.items import Comment, Item, Null, Table, Whitespacefrom pipelex.base_exceptions import PipelexUnexpectedErrorfrom pipelex.cogt.model_routing.routing_profile_factory import RoutingProfileLibraryBlueprintfrom pipelex.core.validation import MIGRATE_COMMAND+from pipelex.errors.problem import MigrationErrorBlockfrom pipelex.fix_ops.applier import apply_fix_ops, delete_literallyfrom pipelex.fix_ops.file_transaction import FileSnapshot, read_file_snapshotfrom pipelex.migration.engine import apply_ops_over_text+from pipelex.migration.exceptions import MigrationErrorfrom pipelex.migration.former_release import (ACTIVE_KEY,MODEL_SPECS_SECTION_KEY,@@ -225,6 +227,37 @@ def clean_former_release(*, config_dirs: Sequence[Path], dry_run: bool, moment:return FormerReleaseCleanup(dry_run=False, files=files, still_blocking=what_stops_the_boot(config_dirs=directories))+def former_release_pending_migration(*, config_dirs: Sequence[Path]) -> MigrationErrorBlock | None:+ """What `pipelex migrate` would do about what a former release left, as the pending migration a boot refusal carries.++ The cleanup's own dry run over the directories the command walks, so the refusal says what the command would do,+ as its `diagnostics.migration`: whether it would rewrite or remove a file (`would_write`), and whether something is+ a person's to resolve (`needs_attention`), a file it would leave for a hand edit or a boot it would still not start.+ A refusal whose blockers the walk does not reach, which the dry run finds nothing in, needs attention too: the+ command cannot repair them. The plans are empty: the cleanup's files are the command's `former_release` key.++ Runs on the failure path only. **A failure inside the dry run never becomes the failure the user sees**, which+ names what to run: it gives no block, and the catch stays narrow, so a bug in the cleanup surfaces as itself.++ Args:+ config_dirs: The directories `pipelex migrate` walks, as `ConfigLoader.existing_config_dirs` lists them.++ Returns:+ The block, or `None` when the dry run could not be made.+ """+ try:+ cleanup = clean_former_release(config_dirs=config_dirs, dry_run=True)+ except (MigrationError, OSError):+ return None+ would_write = any(not file.is_blocked for file in cleanup.files)+ return MigrationErrorBlock(+ remedy=MIGRATE_COMMAND,+ would_write=would_write,+ needs_attention=cleanup.needs_attention or not would_write,+ plans=[],+ )++def what_stops_the_boot(*, config_dirs: Sequence[Path], contents: Mapping[Path, str | None] | None = None) -> list[str]:"""What stops a boot of this machine, read off the files each boot merges: the home's alone, and the project's.diff --git a/pipelex/mthds_parsing/parser.py b/pipelex/mthds_parsing/parser.pyindex 1537d9863..f8d080e34 100644--- a/pipelex/mthds_parsing/parser.py+++ b/pipelex/mthds_parsing/parser.py@@ -25,6 +25,32 @@ def _decode_error_position(exc: UnicodeDecodeError) -> tuple[int, int]:return before.count("\n") + 1, len(before) - line_start + 1+def undecodable_mthds_error(*, error: UnicodeDecodeError, source: str | None) -> MthdsParserError:+ """The refusal of an MTHDS file that is not UTF-8 text: ``method.syntax``, located at its first byte that does not decode.++ TOML is UTF-8 text, so such a file does not parse: it is the method's syntax fault, which every command reports as+ ``validate`` does, and never a file this machine cannot read.+ """+ line, column = _decode_error_position(error)+ msg = f"The MTHDS file is not UTF-8 text: the byte at line {line}, column {column} does not decode."+ return MthdsParserError(+ msg,+ validation_errors=[PipelexBundleBlueprintValidationErrorData(source=source, message=msg, line=line, column=column)],+ ).with_error_code(CoreCode.METHOD_SYNTAX)+++def decode_mthds_text(*, content: bytes, source: str | None) -> str:+ """The text of an MTHDS file read as bytes, decoded as the parser decodes a file it reads itself.++ Raises:+ MthdsParserError: The bytes are not UTF-8 text (:func:`undecodable_mthds_error`).+ """+ try:+ return content.decode("utf-8")+ except UnicodeDecodeError as exc:+ raise undecodable_mthds_error(error=exc, source=source) from exc++class MthdsParser(BaseModel):"""MTHDS -> PipelexBundleBlueprint"""@@ -99,12 +125,7 @@ class MthdsParser(BaseModel):except UnicodeDecodeError as exc:# tomli reads a file as bytes and decodes them as UTF-8, so a file of a tree that is not text fails here.source = mthds_source if mthds_source is not None else str(bundle_path)- line, column = _decode_error_position(exc)- msg = f"The MTHDS file is not UTF-8 text: the byte at line {line}, column {column} does not decode."- raise MthdsParserError(- msg,- validation_errors=[PipelexBundleBlueprintValidationErrorData(source=source, message=msg, line=line, column=column)],- ).with_error_code(CoreCode.METHOD_SYNTAX) from exc+ raise undecodable_mthds_error(error=exc, source=source) from excif not blueprint_dict:msg = "Could not make 'PipelexBundleBlueprint': no blueprint found in the MTHDS file"diff --git a/pipelex/pipeline/exceptions.py b/pipelex/pipeline/exceptions.pyindex bd0f0c31b..04ef048ff 100644--- a/pipelex/pipeline/exceptions.py+++ b/pipelex/pipeline/exceptions.py@@ -20,7 +20,7 @@ from pipelex.errors.problem import PipelexProblem, ProblemViewfrom pipelex.errors.registry.pipelex_codes import PipelexErrorCodefrom pipelex.pipe_run.exceptions import find_failure_locationfrom pipelex.pipe_run.located_failure import failure_location_of, locate_failure_message, located_problem, located_root_fault-from pipelex.pipeline.validation_errors import build_validation_error_items, problem_item_of, validation_item_code+from pipelex.pipeline.validation_errors import ValidationItemCode, build_validation_error_items, problem_item_of, validation_item_codefrom pipelex.system.pipe_run_mode import PipeRunMode@@ -416,12 +416,27 @@ class ValidateBundleError(PipelexError):@overridedef problem_items(self) -> list[ProblemItem] | None:- """One problem item per validation item, each with its own code: a dry run's the failure's, any other its type's.+ """One problem item per validation item, each with its own code (:meth:`item_codes`).++ On a withheld verdict (:meth:`withholding_files`), every item is withheld whole, its sentence, its parameters and+ its locators, whichever channel each came from.+ """+ items = [problem_item_of(item=item, code=item_code.code, params=item_code.params) for item, item_code in self._coded_items()]+ if self._file_withholding is not None:+ file_withholding = self._file_withholding+ items = [file_withholding.withheld_item(item=item) for item in items]+ return items or None++ def item_codes(self) -> list[ValidationItemCode]:+ """The code of each of :meth:`validation_error_items`, in its order (:meth:`problem_items`'s codes)."""+ return [item_code for _, item_code in self._coded_items()]++ def _coded_items(self) -> list[tuple[ValidationErrorItem, ValidationItemCode]]:+ """Each of :meth:`validation_error_items` with its code: a dry run's the failure's, any other its type's.An item no stage classified takes the code of the refusal this verdict was built from when that refusal isthe method's, and ``method.schema_violation`` otherwise, or when that code is ``method.invalid``: the verdict's- own umbrella, whose sentence says nothing of the item. On a withheld verdict (:meth:`withholding_files`), every- item is withheld whole, its sentence, its parameters and its locators, whichever channel each came from.+ own umbrella, whose sentence says nothing of the item."""residual_code: ErrorCode = CoreCode.METHOD_SCHEMA_VIOLATION# The parameters the refusal's code renders from, as a caller reads them, which an item taking its code keeps.@@ -434,7 +449,7 @@ class ValidateBundleError(PipelexError):cause_params = cause.to_problem(view=ProblemView.CALLER).paramsresidual_params = cause_params.as_wire() if cause_params is not None else Nonedry_run_failures = iter(self.dry_run_failures)- items: list[ProblemItem] = []+ coded_items: list[tuple[ValidationErrorItem, ValidationItemCode]] = []for item in self.validation_error_items():item_code: ErrorCodeitem_params: dict[str, Any] | None = None@@ -447,11 +462,8 @@ class ValidateBundleError(PipelexError):item_params = residual_paramselse:item_code = validation_item_code(item=item, residual_code=residual_code)- items.append(problem_item_of(item=item, code=item_code, params=item_params))- if self._file_withholding is not None:- file_withholding = self._file_withholding- items = [file_withholding.withheld_item(item=item) for item in items]- return items or None+ coded_items.append((item, ValidationItemCode(code=item_code, params=item_params)))+ return coded_itemsclass HostLibraryLoadRefusalError(PipelexError):diff --git a/pipelex/pipeline/fixes/fix_loop.py b/pipelex/pipeline/fixes/fix_loop.pyindex 8383c7f69..81d26f931 100644--- a/pipelex/pipeline/fixes/fix_loop.py+++ b/pipelex/pipeline/fixes/fix_loop.py@@ -30,15 +30,15 @@ not only the folder named, and so are the ``library_dirs`` passed beside it.import osfrom collections.abc import Awaitable, Callable, Iterable, Sequencefrom pathlib import Path-from typing import Any, NamedTuple, cast+from typing import Any, NamedTuple, Self, castimport tomlkit-from pydantic import BaseModel, ConfigDict, Field+from pydantic import BaseModel, ConfigDict, Field, model_validatorfrom pipelex.base_exceptions import ValidationErrorItemfrom pipelex.config import get_configfrom pipelex.fix_ops.applier import apply_fix_ops, serialize_and_format-from pipelex.fix_ops.exceptions import FixWriteConflictError+from pipelex.fix_ops.exceptions import FixWriteConflictError, FixWriteFailedErrorfrom pipelex.fix_ops.file_transaction import (FileSnapshot,PendingFileUpdate,@@ -54,9 +54,11 @@ from pipelex.pipeline.exceptions import ValidateBundleErrorfrom pipelex.pipeline.fixes.applicability import is_safe_fix_for_load_scope, is_target_in_write_scopefrom pipelex.pipeline.validate_bundle import ValidateBundleResult, dirs_beside_method, validate_bundlefrom pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error+from pipelex.pipeline.validation_errors import ValidationItemCodefrom pipelex.suggested_fix import DeleteKeyOp, DeleteTableOp, EnsureTableOp, FixOp, MoveKeyOp, RemapValueOp, RenameTableKeyOp, SetKeyOp, SuggestedFixfrom pipelex.tools.misc.exceptions import TomlErrorfrom pipelex.tools.misc.toml_utils import load_toml_from_path+from pipelex.tools.typing.pydantic_utils import empty_list_factory_of_MAIN_PIPE_KEY = "main_pipe"@@ -86,6 +88,9 @@ class FixBundleResult(BaseModel):"""Distinct files written, in first-write order across iterations (resolved paths)."""remaining_errors: list[ValidationErrorItem]"""The last failed validation's structured errors; empty when ``is_valid``."""+ remaining_error_codes: list[ValidationItemCode] = Field(default_factory=empty_list_factory_of(ValidationItemCode))+ """The code each of ``remaining_errors`` takes, in its order, as ``validate`` codes the same errors: a surface that+ reports them as a problem's items reads its codes here, never re-derived without the verdict that decided them."""pending_signatures: list[str] | None = None"""Qualified refs still declared as ``PipeSignature`` after a successful validation."""is_runnable: bool | None = None@@ -94,6 +99,15 @@ class FixBundleResult(BaseModel):"""Why the loop stopped early (no-progress repeat, out-of-scope targets, cross-filecollision, max_iterations), if it did."""+ @model_validator(mode="after")+ def _each_remaining_error_has_its_code(self) -> Self:+ if len(self.remaining_error_codes) != len(self.remaining_errors):+ msg = (+ f"{len(self.remaining_errors)} remaining error(s) but {len(self.remaining_error_codes)} code(s): each remaining error takes one code"+ )+ raise ValueError(msg)+ return self+def _fix_fingerprint(fix: SuggestedFix) -> str:"""Stable identity of a fix attempt: ``fix_code`` + ``source`` + every op serialized whole.@@ -124,6 +138,7 @@ def unfixable_method_result(*, error: ValidateBundleError) -> FixBundleResult:fixes_applied=[],files_written=[],remaining_errors=_validation_error_items(error),+ remaining_error_codes=error.item_codes(),)@@ -141,6 +156,18 @@ def _pending_signatures_from_validation_result(validation_result: Any) -> list[sreturn validated_pending_signatures+def _write_failure_path(*, error: OSError, targets: Sequence[Path]) -> Path:+ """What a failed commit could not write: the target the error names, else the directory of the file it names.++ A target is replaced from a copy staged beside it, so an error naming a file that is no target names that copy, and+ its directory is what refused the write. An error naming no file names the round's first target.+ """+ if error.filename is None:+ return targets[0]+ named = Path(os.fsdecode(error.filename))+ return named if named in targets else named.parent++def _absolute_source_path(path: Path) -> Path:"""Normalize a source pathname without following symlinks."""return Path(os.path.abspath(path))@@ -528,6 +555,7 @@ async def _fix_to_fixed_point(written_paths: set[Path] = set()apply_rounds = 0last_error_items: list[ValidationErrorItem] = []+ last_error_codes: list[ValidationItemCode] = []for _ in range(max_iterations):# The snapshot lists the method's trees: one that cannot be listed is the invalid verdict, with nothing to fix.@@ -541,6 +569,7 @@ async def _fix_to_fixed_point(fixes_applied=fixes_applied,files_written=files_written,remaining_errors=_validation_error_items(exc),+ remaining_error_codes=exc.item_codes(),)try:validation_result = await validate()@@ -556,6 +585,7 @@ async def _fix_to_fixed_point()except ValidateBundleError as exc:last_error_items = _validation_error_items(exc)+ last_error_codes = exc.item_codes()safe_fixes = _safe_fixes(last_error_items, is_single_file=is_single_file, select_codes=select_codes, ignore_codes=ignore_codes)if not safe_fixes:@@ -565,6 +595,7 @@ async def _fix_to_fixed_point(fixes_applied=fixes_applied,files_written=files_written,remaining_errors=last_error_items,+ remaining_error_codes=last_error_codes,)bound_fixes = _bind_fixes_to_snapshots(@@ -584,6 +615,7 @@ async def _fix_to_fixed_point(fixes_applied=fixes_applied,files_written=files_written,remaining_errors=last_error_items,+ remaining_error_codes=last_error_codes,bail_reason=bail_reason,)@@ -602,6 +634,7 @@ async def _fix_to_fixed_point(fixes_applied=fixes_applied,files_written=files_written,remaining_errors=last_error_items,+ remaining_error_codes=last_error_codes,bail_reason=bail_reason,)@@ -621,6 +654,7 @@ async def _fix_to_fixed_point(fixes_applied=fixes_applied,files_written=files_written,remaining_errors=last_error_items,+ remaining_error_codes=last_error_codes,bail_reason=bail_reason,)@@ -644,7 +678,14 @@ async def _fix_to_fixed_point(pending_updates.append(PendingFileUpdate(snapshot=snapshot, new_content=serialize_and_format(toml_doc)))round_written_paths.append(target_path)- commit_file_updates(pending_updates)+ try:+ commit_file_updates(pending_updates)+ except OSError as exc:+ # The round is rolled back; what failed is a write, never a read of the method.+ failed_path = _write_failure_path(error=exc, targets=[update.snapshot.path for update in pending_updates])+ reason = exc.strerror.lower() if exc.strerror else "cannot be written"+ msg = f"The fix could not write '{failed_path}': {reason}"+ raise FixWriteFailedError(msg, path=failed_path, reason=reason) from excseen_fingerprints.update(_fix_fingerprint(fix.fix) for fix in new_fixes)fixes_applied.extend(round_fixes_applied)for target_path in round_written_paths:@@ -673,5 +714,6 @@ async def _fix_to_fixed_point(fixes_applied=fixes_applied,files_written=files_written,remaining_errors=_validation_error_items(exc),+ remaining_error_codes=exc.item_codes(),bail_reason=f"max_iterations ({max_iterations}) reached without convergence",)diff --git a/pipelex/pipeline/fixes/fix_render.py b/pipelex/pipeline/fixes/fix_render.pyindex 8e71267e6..2000c07d7 100644--- a/pipelex/pipeline/fixes/fix_render.py+++ b/pipelex/pipeline/fixes/fix_render.py@@ -5,8 +5,6 @@ from __future__ import annotationsfrom pathlib import Pathfrom typing import TYPE_CHECKING, Any, cast-from pipelex.pipeline.validation_render import format_validation_error_items_markdown-if TYPE_CHECKING:from pipelex.pipeline.fixes.fix_loop import FixBundleResult@@ -75,50 +73,42 @@ def format_fix_markdown(result: dict[str, Any]) -> str:return "\n".join(lines)-def format_fix_still_invalid_markdown(result: FixBundleResult, *, bundle_path: str) -> str:- """Render a still-invalid ``fix bundle`` result as agent-readable markdown (stderr, exit 1).+def format_fix_progress_markdown(result: FixBundleResult, *, bundle_path: str) -> str:+ """What a still-invalid ``fix bundle`` did before it stopped, as the markdown that follows its problem (stderr, exit 1).- The markdown sibling of the human ``_render_fix_result`` still-invalid arm- (``cli/commands/fix/_fix_core.py``): a heading, the bundle, the partial progress that WAS- applied, the bail reason, then the remaining errors rendered as prose items (with their ``💡- Suggested fix`` lines, via the shared :func:`format_validation_error_items_markdown`) rather- than a raw JSON dump, and a context-aware tip. This is the step-5-deferred "richer- still-invalid markdown for the agent command".+ The agent command reports a still-invalid result as the problem of the method that does not validate, whose faults+ are the remaining errors, rendered as prose items with their ``💡 Suggested fix`` lines. This is what follows them,+ the markdown sibling of the human ``_render_fix_result`` still-invalid arm (``cli/commands/fix/_fix_core.py``): the+ partial progress that WAS applied, the reason the loop stopped, and a context-aware tip."""- lines: list[str] = ["# Fix incomplete - bundle still invalid", "", f"**Bundle:** `{bundle_path}`"]+ lines: list[str] = []- # Partial progress is normal: name what WAS applied before the remaining errors.+ # Partial progress is normal: name what WAS applied before the loop stopped.if result.fixes_applied:entry_resolved = Path(bundle_path).resolve()- lines += ["", "## Applied Fixes", ""]+ lines += ["### Applied Fixes", ""]for fix in result.fixes_applied:suffix = f" (`{fix.source}`)" if fix.source is not None and Path(fix.source).resolve() != entry_resolved else ""lines.append(f"- `{fix.fix_code}` - {fix.description}{suffix}")if result.files_written:- lines += ["", "## Files Written", ""]+ lines += ["", "### Files Written", ""]for file_path in result.files_written:lines.append(f"- `{file_path}`")- lines += ["", f"- **Iterations:** {result.iterations}"]+ lines += ["", f"- **Iterations:** {result.iterations}", ""]if result.bail_reason:- lines += ["", f"**Stopped:** {result.bail_reason}"]-- if result.remaining_errors:- lines += ["", format_validation_error_items_markdown(result.remaining_errors)]+ lines += [f"**Stopped:** {result.bail_reason}", ""]# A remaining error can still carry a safe 💡 suggested-fix line — dropped by --select/--ignore, left# outside the write scope, or unconverged when the loop bailed. Claiming "no safe fix" there would- # contradict the line just printed, so only say it when nothing fixable remains (mirrors the human tip).+ # contradict the line printed above, so only say it when nothing fixable remains (mirrors the human tip).if any(item.suggested_fix is not None and item.suggested_fix.safety.is_safe for item in result.remaining_errors):- lines += [- "",- (- "💡 Some remaining errors above still show a suggested fix that was not applied — they were skipped by "- "--select/--ignore, fell outside the write scope, or the loop stopped early (see the reason above). "- "Adjust those flags (or pass -L) and re-run, or fix the rest manually."- ),- ]+ lines.append(+ "💡 Some remaining errors above still show a suggested fix that was not applied — they were skipped by "+ "--select/--ignore, fell outside the write scope, or the loop stopped early (see the reason above). "+ "Adjust those flags (or pass -L) and re-run, or fix the rest manually."+ )else:- lines += ["", "💡 The remaining errors have no deterministic safe fix — they need a manual edit."]+ lines.append("💡 The remaining errors have no deterministic safe fix — they need a manual edit.")return "\n".join(lines)diff --git a/pipelex/pipeline/usage_stats_reporting.py b/pipelex/pipeline/usage_stats_reporting.pyindex 94cd45176..b3cc6353a 100644--- a/pipelex/pipeline/usage_stats_reporting.py+++ b/pipelex/pipeline/usage_stats_reporting.py@@ -37,13 +37,14 @@ from pipelex.pipe_controllers.parallel.pipe_parallel import PipeParallelfrom pipelex.pipe_controllers.sequence.pipe_sequence import PipeSequencefrom pipelex.pipe_machinery.pipe_abstract import PipeAbstractfrom pipelex.pipeline.exceptions import ValidateBundleError-from pipelex.system.usage_stats.usage_stats_client import note_command_error_domain, record_usage_stats_event, usage_stats_are_enabled+from pipelex.system.usage_stats.usage_stats_client import note_command_error, record_usage_stats_event, usage_stats_are_enabledfrom pipelex.system.usage_stats.usage_stats_contract import (MODEL_HANDLE_PATTERN,OTHER_MODEL,UsageStatsCodegenArtifact,UsageStatsCodegenOutcome,UsageStatsCodegenTarget,+ UsageStatsErrorDomain,UsageStatsEventName,UsageStatsOutcome,UsageStatsProvider,@@ -70,10 +71,9 @@ from pipelex.system.usage_stats.usage_stats_events import (bounded_duration_ms,)from pipelex.system.usage_stats.usage_stats_runs import (- FAILURE_CATEGORIES,RunInferenceTally,current_method_source,- usage_stats_error_domain,+ usage_stats_error,)from pipelex.tools.log.error_fields import error_fieldsfrom pipelex.tracing.trace_events import PipeStartEvent, TraceEvent, UsageReportEvent@@ -265,7 +265,7 @@ class _ModelUsageRow:self.tallied_calls = 0self.usage_reports = 0self.failures = 0- self.failures_by_category: dict[str, int] = dict.fromkeys(FAILURE_CATEGORIES, 0)+ self.failures_by_domain: dict[UsageStatsErrorDomain, int] = dict.fromkeys(UsageStatsErrorDomain, 0)self.input_tokens = 0self.output_tokens = 0self.cached_tokens = 0@@ -299,8 +299,8 @@ def _model_usage_rows(*, tally: RunInferenceTally | None, events: Sequence[Tracerow = row_for(model_handle=tallied_handle, backend_name=tallied_backend)row.tallied_calls += model_tally.callsrow.failures += model_tally.failures- for category, count in model_tally.failures_by_category.items():- row.failures_by_category[category] += count+ for domain, count in model_tally.failures_by_domain.items():+ row.failures_by_domain[domain] += countrow.images_generated += model_tally.images_generatedrow.pages_extracted += model_tally.pages_extracted@@ -365,9 +365,11 @@ def build_run_usage_events(*, facts: RunUsageFacts) -> list[UsageStatsEvent]:shape = bundle_shape_of(pipes=facts.own_pipes, concepts=facts.own_concepts, main_pipe=facts.main_pipe)features = bundle_features_of(pipes=facts.own_pipes)is_usage_known = facts.events is not None+ run_error = usage_stats_error(error=facts.error) if facts.outcome.is_failed else Nonerun_properties = RunCompletedProperties(outcome=facts.outcome,- error_domain=usage_stats_error_domain(error=facts.error) if facts.outcome.is_failed else None,+ error_code=run_error.code if run_error is not None else None,+ error_domain=run_error.domain if run_error is not None else None,dry_run=facts.is_dry_run,method_source=current_method_source(),duration_ms=bounded_duration_ms(seconds=facts.duration_seconds),@@ -418,12 +420,11 @@ def build_run_usage_events(*, facts: RunUsageFacts) -> list[UsageStatsEvent]:model=model,calls=bounded(value=row.calls, maximum=MAX_CALLS),failures=bounded(value=row.failures, maximum=MAX_CALLS),- failures_transient=bounded(value=row.failures_by_category["transient"], maximum=MAX_CALLS),- failures_configuration=bounded(value=row.failures_by_category["configuration"], maximum=MAX_CALLS),- failures_content=bounded(value=row.failures_by_category["content"], maximum=MAX_CALLS),- failures_capacity=bounded(value=row.failures_by_category["capacity"], maximum=MAX_CALLS),- failures_ambiguous=bounded(value=row.failures_by_category["ambiguous"], maximum=MAX_CALLS),- failures_unknown=bounded(value=row.failures_by_category["unknown"], maximum=MAX_CALLS),+ failures_input=bounded(value=row.failures_by_domain[UsageStatsErrorDomain.INPUT], maximum=MAX_CALLS),+ failures_method=bounded(value=row.failures_by_domain[UsageStatsErrorDomain.METHOD], maximum=MAX_CALLS),+ failures_account=bounded(value=row.failures_by_domain[UsageStatsErrorDomain.ACCOUNT], maximum=MAX_CALLS),+ failures_operator=bounded(value=row.failures_by_domain[UsageStatsErrorDomain.OPERATOR], maximum=MAX_CALLS),+ failures_runtime=bounded(value=row.failures_by_domain[UsageStatsErrorDomain.RUNTIME], maximum=MAX_CALLS),input_tokens=bounded(value=row.input_tokens, maximum=MAX_TOKENS),output_tokens=bounded(value=row.output_tokens, maximum=MAX_TOKENS),cached_tokens=bounded(value=row.cached_tokens, maximum=MAX_TOKENS),@@ -437,10 +438,10 @@ def build_run_usage_events(*, facts: RunUsageFacts) -> list[UsageStatsEvent]:def report_run_usage(*, facts: RunUsageFacts) -> None:- """Record a run's `run_completed` and `model_used` events, and its error domain for the command that ran it."""+ """Record a run's `run_completed` and `model_used` events, and its error's code and domain for the command that ran it."""usage_events = build_run_usage_events(facts=facts)if facts.outcome.is_failed:- note_command_error_domain(error_domain=usage_stats_error_domain(error=facts.error))+ note_command_error(error=usage_stats_error(error=facts.error))for usage_event in usage_events:record_usage_stats_event(event=usage_event)diff --git a/pipelex/pipeline/validation_errors.py b/pipelex/pipeline/validation_errors.pyindex 50242bc89..4d02c7073 100644--- a/pipelex/pipeline/validation_errors.py+++ b/pipelex/pipeline/validation_errors.py@@ -3,11 +3,11 @@``build_validation_error_items`` is the single source of truth behind everystructured-error surface:-- the agent CLI's ``validation_errors`` JSON array (via- ``pipelex.cli.agent_cli.commands.agent_output.extract_validation_errors``),-- the ``/validate`` route's invalid verdict, and+- the ``/validate`` route's invalid verdict,- the problem's ``errors`` (via ``ValidateBundleError.problem_items``, which- turns each item into a problem item with :func:`problem_item_of`).+ turns each item into a problem item with :func:`problem_item_of`), which the+ agent CLI prints, and+- the agent CLI's Markdown, which renders the items themselves as prose.All of them reach it through ``ValidateBundleError.validation_error_items``, so the CLIand API structured shapes cannot drift. It takes the error-data lists directly@@ -25,6 +25,7 @@ from mthds.protocol.problem.registry import (MethodDependencyMissingReason,MethodIdentifierInvalidIdentifierKind,)+from pydantic import BaseModel, ConfigDictfrom pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItemfrom pipelex.core.exceptions import (@@ -174,6 +175,19 @@ def build_validation_error_items(return items+class ValidationItemCode(BaseModel):+ """The code a validation item takes in its verdict's problem, with the parameters known beside the item that it renders from.++ A verdict decides it (``ValidateBundleError.item_codes``) from more than the item holds, the refusal it was built from and+ its dry-run failures, so a surface that reports the items after the verdict is gone, ``fix bundle``'s, keeps it beside them.+ """++ model_config = ConfigDict(frozen=True, extra="forbid")++ code: ErrorCode+ params: dict[str, Any] | None = None++def validation_item_code(*, item: ValidationErrorItem, residual_code: ErrorCode) -> ErrorCode:"""The code of a validation item that is not a dry run's: its ``error_type``'s, or ``residual_code`` for an item with none.diff --git a/pipelex/runtime_hub.py b/pipelex/runtime_hub.pyindex ca642e419..48f34feea 100644--- a/pipelex/runtime_hub.py+++ b/pipelex/runtime_hub.py@@ -786,3 +786,15 @@ def get_console() -> "Console":return runtime_hub.get_console()else:return _make_console(stderr=True)+++def get_error_console() -> "Console":+ """The Rich console the CLI prints a failure's report through: always stderr, whatever boot's print target.++ ``get_console()`` prints to stdout by default, the stream a person pipes a command's data from, so a failure printed+ there would be read as the command's output; its report, and the traceback ``--traceback`` asks for, go to stderr.++ Raises:+ MissingDependencyError: If Rich is not installed.+ """+ return _make_console(stderr=True)diff --git a/pipelex/system/telemetry/telemetry_loader.py b/pipelex/system/telemetry/telemetry_loader.pyindex f01861d65..14572f0a8 100644--- a/pipelex/system/telemetry/telemetry_loader.py+++ b/pipelex/system/telemetry/telemetry_loader.py@@ -39,6 +39,9 @@ from pipelex.tools.secrets.exceptions import UnknownVarPrefixErrorfrom pipelex.tools.secrets.secrets_provider_abstract import SecretsProviderAbstractfrom pipelex.tools.secrets.secrets_utils import substitute_vars+#: The part of the configuration a telemetry refusal names, as `pipelex.config.invalid`'s step reads it.+TELEMETRY_SURFACE = "telemetry"+def load_telemetry_config(*, secrets_provider: SecretsProviderAbstract) -> TelemetryConfig:"""Load telemetry configuration from a TOML file with variable substitution.@@ -89,7 +92,7 @@ def load_telemetry_config(*, secrets_provider: SecretsProviderAbstract) -> Telemexcept UnknownVarPrefixError as exc:paths_str = "\n".join(str(path) for path in telemetry_config_paths)msg = f"Variable substitution failed in telemetry configuration based on '{paths_str}': {exc}"- raise TelemetryConfigValidationError(msg) from exc+ raise TelemetryConfigValidationError(msg, surface=TELEMETRY_SURFACE, file=TELEMETRY_CONFIG_FILE_NAME) from exctry:telemetry_config = TelemetryConfig.model_validate(telemetry_config_toml)@@ -112,7 +115,9 @@ def load_telemetry_config(*, secrets_provider: SecretsProviderAbstract) -> Telemreport = report_validation_error(validation_error=exc, surface_id=TELEMETRY_CONFIG_SURFACE_ID)paths_str = "\n".join(str(path) for path in telemetry_config_paths)msg = f"Invalid telemetry configuration in '{paths_str}':\n{report.message}"- raise TelemetryConfigValidationError(msg, migration=report.migration) from exc+ raise TelemetryConfigValidationError(+ msg, migration=report.migration, surface=TELEMETRY_SURFACE, file=TELEMETRY_CONFIG_FILE_NAME, setting=report.setting+ ) from excreturn telemetry_configdiff --git a/pipelex/system/usage_stats/usage_stats_client.py b/pipelex/system/usage_stats/usage_stats_client.pyindex 2704b802c..1d6579822 100644--- a/pipelex/system/usage_stats/usage_stats_client.py+++ b/pipelex/system/usage_stats/usage_stats_client.py@@ -32,7 +32,7 @@ from pipelex.system.runtime import IntegrationModefrom pipelex.system.usage_stats.usage_stats_contract import (NOTICE_VERSION,TOOL_NAME,- UsageStatsErrorDomain,+ UsageStatsError,UsageStatsHost,UsageStatsIntegration,UsageStatsOffBy,@@ -228,8 +228,8 @@ class UsageStatsClient:self._common: CommonProperties | None = Noneself._held: list[dict[str, Any]] = []self._background: _BackgroundSender | None = None- #: Who can fix the failure the command reported, when something said so; read for its `command_completed`.- self.command_error_domain: UsageStatsErrorDomain | None = None+ #: The code and the domain of the failure the command reported, when something said so; read for its `command_completed`.+ self.command_error: UsageStatsError | None = None#: Whether the command sent its work to the hosted API, which holds the rest of what it did.self.is_command_hosted = False#: What an `init` command set, for its `command_completed`.@@ -241,9 +241,9 @@ class UsageStatsClient:def is_enabled(self) -> bool:return not self.settings.off_by- def note_command_error_domain(self, *, error_domain: UsageStatsErrorDomain) -> None:- """Record who can fix the failure the command is reporting, as its error output classifies it; the last one wins."""- self.command_error_domain = error_domain+ def note_command_error(self, *, error: UsageStatsError) -> None:+ """Record the code and the domain of the failure the command is reporting, as its error output gives them; the last one wins."""+ self.command_error = errordef note_command_hosted(self) -> None:"""Record that the command sent its work to the hosted API, for its `command_completed`."""@@ -614,11 +614,11 @@ def record_usage_stats_event(*, event: UsageStatsEvent) -> None:client.record(event=event)-def note_command_error_domain(*, error_domain: UsageStatsErrorDomain) -> None:- """Record, for the running command's `command_completed`, who can fix the failure it is reporting."""+def note_command_error(*, error: UsageStatsError) -> None:+ """Record, for the running command's `command_completed`, the code and the domain of the failure it is reporting."""client = _PROCESS.clientif client is not None:- client.note_command_error_domain(error_domain=error_domain)+ client.note_command_error(error=error)def note_command_hosted() -> None:diff --git a/pipelex/system/usage_stats/usage_stats_contract.py b/pipelex/system/usage_stats/usage_stats_contract.pyindex f71df4db4..8e478938a 100644--- a/pipelex/system/usage_stats/usage_stats_contract.py+++ b/pipelex/system/usage_stats/usage_stats_contract.py@@ -11,9 +11,13 @@ are in `usage_stats_core`, which the sender runs alone; the tests check them aga"""from enum import StrEnum-from typing import Final+from typing import Final, NamedTuple-SCHEMA_VERSION = 1+#: The version of the contract the events follow, which every event carries as `schema`. 2 since the events name a+#: failure by its error's code and that code's domain, where version 1 read the runtime's own error domains and counted+#: a model's failed calls by its inference category: the change removed and renamed what version 1 declared, which only a+#: new version may do, so a receiver tells the two shapes apart by this number.+SCHEMA_VERSION = 2#: The reporting tool's name, the `tool` property and the name of its spool directory.TOOL_NAME: Final = "pipelex"@@ -163,12 +167,20 @@ class UsageStatsOutcome(StrEnum):class UsageStatsErrorDomain(StrEnum):- """Who can fix a failure: the runtime's own error domains, `other` when it cannot say."""+ """Who must act on a failure: the domain of its error's code, from the problem registry's closed list."""INPUT = "input"- CONFIG = "config"+ METHOD = "method"+ ACCOUNT = "account"+ OPERATOR = "operator"RUNTIME = "runtime"- OTHER = "other"+++class UsageStatsError(NamedTuple):+ """What the usage statistics say of a failure: the code of its error, and that code's domain, who must act on it."""++ code: str+ domain: UsageStatsErrorDomainclass UsageStatsMethodSource(StrEnum):@@ -397,3 +409,7 @@ OTHER_COMMAND = "other"#: The patterns of the contract the emitter's own values must match, in Python's `re.fullmatch`.RELEASE_VERSION_PATTERN = r"^[0-9]{1,4}\.[0-9]{1,4}\.[0-9]{1,4}([.-]?(a|b|rc|alpha|beta|dev|post|insider)[.]?[0-9]{0,4})?$"MODEL_HANDLE_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,95}$"+#: A registry error code, the standard's code pattern: a family and a name, or a runtime's own code under its prefix.+ERROR_CODE_PATTERN = r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){1,2}$"+#: The longest error code the events carry.+ERROR_CODE_MAX_LENGTH = 96diff --git a/pipelex/system/usage_stats/usage_stats_events.py b/pipelex/system/usage_stats/usage_stats_events.pyindex 089e01618..b84bb2e30 100644--- a/pipelex/system/usage_stats/usage_stats_events.py+++ b/pipelex/system/usage_stats/usage_stats_events.py@@ -119,6 +119,7 @@ class CommandCompletedProperties(UsageStatsProperties):command: stroutcome: UsageStatsOutcome+ error_code: str | None = Noneerror_domain: UsageStatsErrorDomain | None = Noneduration_ms: inthosted: bool | None = None@@ -168,6 +169,7 @@ class BundleFeatures(UsageStatsProperties):class RunCompletedProperties(UsageStatsProperties):outcome: UsageStatsOutcome+ error_code: str | None = Noneerror_domain: UsageStatsErrorDomain | None = Nonedry_run: boolmethod_source: UsageStatsMethodSource@@ -212,12 +214,11 @@ class ModelUsedProperties(UsageStatsProperties):model: strcalls: intfailures: int- failures_transient: int- failures_configuration: int- failures_content: int- failures_capacity: int- failures_ambiguous: int- failures_unknown: int+ failures_input: int+ failures_method: int+ failures_account: int+ failures_operator: int+ failures_runtime: intinput_tokens: intoutput_tokens: intcached_tokens: intdiff --git a/pipelex/system/usage_stats/usage_stats_runs.py b/pipelex/system/usage_stats/usage_stats_runs.pyindex 720c26c23..41429fa8a 100644--- a/pipelex/system/usage_stats/usage_stats_runs.py+++ b/pipelex/system/usage_stats/usage_stats_runs.py@@ -1,6 +1,6 @@"""What a run's inference calls did, tallied as they end, for the run's `run_completed` and `model_used` events.-The run's events carry its pipes and its token usage, but not what a call that failed was refused for, which backend+The run's events carry its pipes and its token usage, but not who must act on a call that failed, which backendserved a model, or how many images and pages a call produced. The inference call's own summary event knows all of itwhen the call ends, so it notes it here, in the tally of the run the call belongs to: a context variable `PipeRun`sets for the duration of a run, which the run's tasks inherit. With no run tallying (statistics off, or a call made@@ -10,19 +10,31 @@ The tally is in-process: a run whose calls execute in other processes, a Temporaall. The hosted plane sets `DO_NOT_TRACK=1`, so no such run reports."""+import reimport threadingfrom collections.abc import Generatorfrom contextlib import contextmanagerfrom contextvars import ContextVar+from typing import Any, cast-from pipelex.base_exceptions import ErrorDomain, PipelexError+from mthds.protocol.exceptions import PipelineRequestError+from mthds.protocol.problem.answers import decode_json+from mthds.protocol.problem.models import Problem+from mthds.protocol.problem.registry import CoreCode, ProblemDomain+from mthds.runners.api.exceptions import ApiResponseError++from pipelex.base_exceptions import PipelexErrorfrom pipelex.errors.problem import ProblemView-from pipelex.system.usage_stats.usage_stats_contract import UsageStatsErrorDomain, UsageStatsMethodSource+from pipelex.system.usage_stats.usage_stats_contract import (+ ERROR_CODE_MAX_LENGTH,+ ERROR_CODE_PATTERN,+ UsageStatsError,+ UsageStatsErrorDomain,+ UsageStatsMethodSource,+)-#: The failure categories a `model_used` event counts, the runtime's own `InferenceErrorCategory` values.-FAILURE_CATEGORIES: tuple[str, ...] = ("transient", "configuration", "content", "capacity", "ambiguous", "unknown")-#: The category a failure is counted under when the runtime could not classify it.-UNCLASSIFIED_FAILURE_CATEGORY = "unknown"+#: A failure that is no Pipelex error, which every surface reads as the registry's catch-all.+UNEXPECTED_USAGE_STATS_ERROR = UsageStatsError(code=CoreCode.RUNTIME_UNEXPECTED, domain=UsageStatsErrorDomain.RUNTIME)class ModelCallTally:@@ -32,7 +44,7 @@ class ModelCallTally:self.backend_name = backend_nameself.calls = 0self.failures = 0- self.failures_by_category: dict[str, int] = dict.fromkeys(FAILURE_CATEGORIES, 0)+ self.failures_by_domain: dict[UsageStatsErrorDomain, int] = dict.fromkeys(UsageStatsErrorDomain, 0)self.images_generated = 0self.pages_extracted = 0@@ -56,14 +68,13 @@ class RunInferenceTally:*,model_handle: str,backend_name: str | None,- failed: bool,- failure_category: str | None,+ failure_domain: UsageStatsErrorDomain | None,images_generated: int,pages_extracted: int,) -> None:with self._lock:self.calls += 1- if failed:+ if failure_domain is not None:self.failures += 1if backend_name is None:return@@ -74,10 +85,9 @@ class RunInferenceTally:model_tally.calls += 1model_tally.images_generated += images_generatedmodel_tally.pages_extracted += pages_extracted- if failed:+ if failure_domain is not None:model_tally.failures += 1- category = failure_category if failure_category in model_tally.failures_by_category else UNCLASSIFIED_FAILURE_CATEGORY- model_tally.failures_by_category[category] += 1+ model_tally.failures_by_domain[failure_domain] += 1_RUN_TALLY: ContextVar[RunInferenceTally | None] = ContextVar("pipelex_usage_stats_run_tally", default=None)@@ -104,31 +114,91 @@ def tallying_inference_calls(*, tally: RunInferenceTally | None) -> Generator[No_RUN_TALLY.reset(token)-def usage_stats_error_domain(*, error: BaseException | None) -> UsageStatsErrorDomain:- """Who can fix a failure, by the domain of the runtime's own code: `input`, `config`, `runtime`, or `other` when it cannot say.+def sent_usage_stats_error(*, error: ApiResponseError) -> UsageStatsError | None:+ """What the usage statistics say of a refusal a server answered: the code and the domain its body sent, nothing inferred.- The domain is the failure's problem's, which a cause reporting a problem of its own, such as one recovered across a- transport boundary, decides, as every other surface reads it.+ The one rule for an answered refusal, every surface's: who has to act is only the server's to say, so the domain is+ the problem document's own `domain` member, read off the body the server sent, and never the one the client reads+ from the status when the body names none, as pipelex-sdk does for a gateway's error page. `None` when the answer+ sent no reportable code with a domain."""- if not isinstance(error, PipelexError):- return UsageStatsErrorDomain.OTHER- return usage_stats_error_domain_of(domain=ErrorDomain.from_problem_domain(error.to_problem(view=ProblemView.CALLER).effective_domain))---def usage_stats_error_domain_of(*, domain: ErrorDomain | str | None) -> UsageStatsErrorDomain:- """The statistics' error domain of a runtime domain, given as the enum or as its value; `other` for none or another."""- if domain is None:- return UsageStatsErrorDomain.OTHER+ decoded = decode_json(error.response_body)+ sent: object = decoded.value if decoded.is_json else None+ document = cast("dict[str, Any]", sent) if isinstance(sent, dict) else {}+ sent_code = document.get("code")+ sent_domain = document.get("domain")+ if not isinstance(sent_code, str) or not isinstance(sent_domain, str) or not is_reportable_error_code(code=sent_code):+ return Nonetry:- runtime_domain = ErrorDomain(domain)+ problem_domain = ProblemDomain(sent_domain)except ValueError:- return UsageStatsErrorDomain.OTHER- match runtime_domain:- case ErrorDomain.INPUT:+ return None+ return UsageStatsError(code=sent_code, domain=usage_stats_error_domain_of(domain=problem_domain))+++def usage_stats_error(*, error: BaseException | None) -> UsageStatsError:+ """The code of a failure and its domain, as its problem gives them; `runtime.unexpected` for an error that carries none.++ A Pipelex error's code is its problem's, which a cause reporting a problem of its own, such as one recovered across+ a transport boundary, decides, as every other surface reads it. A refusal a server answered is read by what its body+ sent alone (:func:`sent_usage_stats_error`), and as the catch-all when it sent nothing, never by the problem the+ client inferred from the status. Any other request error of the MTHDS client carries the problem the client itself+ decided, an unreachable runtime or a timeout, which is read as it is. Any other error, and a failure with no error+ to read, is the catch-all, since every failure has a code.+ """+ if isinstance(error, PipelexError):+ return usage_stats_error_of_problem(problem=error.to_problem(view=ProblemView.CALLER))+ if isinstance(error, ApiResponseError):+ return sent_usage_stats_error(error=error) or UNEXPECTED_USAGE_STATS_ERROR+ if isinstance(error, PipelineRequestError):+ return usage_stats_error_of_problem(problem=error.problem)+ return UNEXPECTED_USAGE_STATS_ERROR+++def usage_stats_failure_domain(*, error: BaseException) -> UsageStatsErrorDomain:+ """Who must act on a failure, read off its code alone, without building its problem.++ The cheap reading a hot path takes, such as a failed inference call's: the code the error resolves to, and the+ domain the registry gives it, the same domain :func:`usage_stats_error` reads off the problem.+ """+ if isinstance(error, PipelexError):+ recovered = error.recovered_problem()+ domain = recovered.effective_domain if recovered is not None else error.resolve_domain()+ return usage_stats_error_domain_of(domain=domain)+ if isinstance(error, ApiResponseError):+ return (sent_usage_stats_error(error=error) or UNEXPECTED_USAGE_STATS_ERROR).domain+ if isinstance(error, PipelineRequestError):+ return usage_stats_error_domain_of(domain=error.problem.effective_domain)+ return UNEXPECTED_USAGE_STATS_ERROR.domain+++def is_reportable_error_code(*, code: str) -> bool:+ """Whether a code fits the contract's pattern and length, as every registry's does."""+ return len(code) <= ERROR_CODE_MAX_LENGTH and re.fullmatch(ERROR_CODE_PATTERN, code) is not None+++def usage_stats_error_of_problem(*, problem: Problem) -> UsageStatsError:+ """The code and the domain of a problem a surface reports.++ A code the contract's pattern refuses, which no registry gives, reads as the catch-all rather than losing the event.+ """+ if not is_reportable_error_code(code=problem.code):+ return UNEXPECTED_USAGE_STATS_ERROR+ return UsageStatsError(code=problem.code, domain=usage_stats_error_domain_of(domain=problem.effective_domain))+++def usage_stats_error_domain_of(*, domain: ProblemDomain) -> UsageStatsErrorDomain:+ """The statistics' error domain of a problem's domain: the same closed list, under the contract's own enum."""+ match domain:+ case ProblemDomain.INPUT:return UsageStatsErrorDomain.INPUT- case ErrorDomain.CONFIG:- return UsageStatsErrorDomain.CONFIG- case ErrorDomain.RUNTIME:+ case ProblemDomain.METHOD:+ return UsageStatsErrorDomain.METHOD+ case ProblemDomain.ACCOUNT:+ return UsageStatsErrorDomain.ACCOUNT+ case ProblemDomain.OPERATOR:+ return UsageStatsErrorDomain.OPERATOR+ case ProblemDomain.RUNTIME:return UsageStatsErrorDomain.RUNTIMEdiff --git a/pipelex/tools/log/error_fields.py b/pipelex/tools/log/error_fields.pyindex e58e2a88e..76a1e4c88 100644--- a/pipelex/tools/log/error_fields.py+++ b/pipelex/tools/log/error_fields.py@@ -32,12 +32,13 @@ from pipelex.tools.typing.pydantic_utils import ValidatedType, describe_exceptio#: The class of the handled exception, by its name.ERROR_TYPE_FIELD = "error.type"+#: The registry code of the failure or the refusal a record is about, which a line about a run's failure gives in place+#: of its text.+ERROR_CODE_FIELD = "error.code"+#: The handled exception's text.ERROR_MESSAGE_FIELD = "error.message"-#: The registry code a failure's problem carries, which a line about a run's failure gives in place of its text.-ERROR_CODE_FIELD = "error.code"-def error_fields(*, exc: BaseException, text: str | None = None, validated_type: ValidatedType | None = None, is_authored_input: bool = Falsediff --git a/pipelex/tools/misc/exceptions.py b/pipelex/tools/misc/exceptions.pyindex 87cc40196..2dc9e7f60 100644--- a/pipelex/tools/misc/exceptions.py+++ b/pipelex/tools/misc/exceptions.py@@ -1,3 +1,4 @@+from pathlib import Pathfrom typing import Any, ClassVar, Selfimport tomli@@ -57,12 +58,14 @@ class TomlError(ToolError):error_code = ErrorCodeSet(default=PipelexErrorCode.CONFIG_SYNTAX, others=(CoreCode.REQUEST_MALFORMED, CoreCode.METHOD_SYNTAX))- def __init__(self, message: str, doc: str, pos: int, lineno: int, colno: int):+ def __init__(self, message: str, doc: str, pos: int, lineno: int, colno: int, *, path: Path | None = None):super().__init__(message)self.doc = docself.pos = posself.lineno = linenoself.colno = colno+ # The file the document was read from, when it was read from one: a refusal names that file, never a guess.+ self.path = path@overridedef problem_params(self) -> dict[str, Any]:diff --git a/pipelex/tools/misc/file_utils.py b/pipelex/tools/misc/file_utils.pyindex 10a5099e5..757efd534 100644--- a/pipelex/tools/misc/file_utils.py+++ b/pipelex/tools/misc/file_utils.py@@ -476,6 +476,42 @@ def ensure_directory_for_file_path(file_path: Path) -> None:ensure_directory_exists(file_path.parent)+def path_label(*, path: Path) -> str:+ """The path as a refusal names it to its reader, without the home directory.++ A problem's parameters are read by an agent, printed and logged, and a home directory names the account it belongs+ to, so a path under the working directory is written relative to it, as a project's files are, and a path under the+ home directory as ``~/…``. When the working directory holds the home directory, the home directory itself or one+ above it, a file under the home directory is written ``~/…`` all the same, so the home configuration never reads+ as a project's. A path under neither is written whole: it names no account.++ Args:+ path: The file or directory, absolute or relative to the working directory.++ Returns:+ The label, with forward slashes in a relative or ``~/`` label.+ """+ try:+ working_dir: Path | None = Path.cwd()+ except FileNotFoundError:+ # The working directory was removed while the process ran: only the home directory can shorten the path.+ working_dir = None+ try:+ home_dir: Path | None = Path.home()+ except RuntimeError:+ home_dir = None+ joined = path if path.is_absolute() or working_dir is None else working_dir / path+ # Collapsed lexically before it is compared, so a `..` cannot climb out of the working directory or the home+ # directory while still reading as under it, nor walk back into the home directory past its name.+ absolute = Path(os.path.normpath(joined))+ if working_dir is not None and absolute.is_relative_to(working_dir):+ if home_dir is None or not home_dir.is_relative_to(working_dir):+ return absolute.relative_to(working_dir).as_posix()+ if home_dir is not None and absolute.is_relative_to(home_dir):+ return f"~/{absolute.relative_to(home_dir).as_posix()}"+ return str(path)++def path_exists(path_str: str | Path) -> bool:"""Checks if a file or directory exists at the specified path.diff --git a/pipelex/tools/misc/toml_utils.py b/pipelex/tools/misc/toml_utils.pyindex 930cebe0a..8bf18aa56 100644--- a/pipelex/tools/misc/toml_utils.py+++ b/pipelex/tools/misc/toml_utils.py@@ -1,10 +1,10 @@from __future__ import annotations+from pathlib import Pathfrom typing import TYPE_CHECKING, Anyif TYPE_CHECKING:from collections.abc import Sequence- from pathlib import Pathimport tomliimport tomlkit@@ -58,7 +58,7 @@ def load_toml_from_bytes(*, data: bytes, source: str | Path) -> dict[str, Any]:return tomli.loads(data.decode())except tomli.TOMLDecodeError as exc:msg = f"TOML parsing error in file '{source}': {exc.msg}"- raise TomlError(message=msg, doc=exc.doc, pos=exc.pos, lineno=exc.lineno, colno=exc.colno) from exc+ raise TomlError(message=msg, doc=exc.doc, pos=exc.pos, lineno=exc.lineno, colno=exc.colno, path=Path(source)) from excdef load_toml_from_path_if_exists(path: str | Path) -> dict[str, Any] | None:diff --git a/pipelex/tracing/event_log_factory.py b/pipelex/tracing/event_log_factory.pyindex 1f0913250..c4d2d5980 100644--- a/pipelex/tracing/event_log_factory.py+++ b/pipelex/tracing/event_log_factory.py@@ -1,6 +1,7 @@"""Factory for creating event log backends from configuration."""from pipelex.base_exceptions import PipelexConfigError+from pipelex.system.configuration.config_loader import CONFIG_NAMEfrom pipelex.system.configuration.configs import TracingBackend, TracingConfigfrom pipelex.tracing.dynamodb_event_log import DynamoDBEventLogfrom pipelex.tracing.event_log_protocol import EventLogProtocol@@ -18,12 +19,12 @@ def make_event_log(tracing_config: TracingConfig, *, writer_id: str = "primary")case TracingBackend.NDJSON:if tracing_config.ndjson is None:msg = "ndjson config is required when backend is 'ndjson'"- raise PipelexConfigError(msg)+ raise PipelexConfigError(msg, surface="pipelex", file=CONFIG_NAME, setting="runtime.tracing.ndjson")return NdjsonEventLog(traces_dir=tracing_config.ndjson.traces_dir, writer_id=writer_id)case TracingBackend.DYNAMODB:if tracing_config.dynamodb is None:msg = "dynamodb config is required when backend is 'dynamodb'"- raise PipelexConfigError(msg)+ raise PipelexConfigError(msg, surface="pipelex", file=CONFIG_NAME, setting="runtime.tracing.dynamodb")return DynamoDBEventLog(table_name=tracing_config.dynamodb.table_name,region=tracing_config.dynamodb.region,diff --git a/subject_grants.toml b/subject_grants.tomlindex cdbc37dbc..d623d2d5b 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::_agent_error_json"]-param = "message"-rationale = "Builds the error JSON around the message; single operand."--["pipelex/cli/agent_cli/commands/agent_output.py::_assemble_error_payload"]-param = "message"-rationale = "Assembles the error payload around the message; single operand."-["pipelex/cli/agent_cli/commands/agent_output.py::_build_error_source"]param = "exc"rationale = "Derives from the exc; single operand."@@ -40,22 +32,26 @@ rationale = "Derives from the exc; single operand."param = "payload"rationale = "Renders the payload; single operand."-["pipelex/cli/agent_cli/commands/agent_output.py::_render_validate_bundle_markdown"]-param = "items"-rationale = "Verb-object: renders the validation error items; the rest is context."+["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."["pipelex/cli/agent_cli/commands/agent_output.py::agent_error"]param = "message"rationale = "Emits an agent error for the message; single operand."-["pipelex/cli/agent_cli/commands/agent_output.py::agent_error_markdown"]+["pipelex/cli/agent_cli/commands/agent_output.py::agent_error_hosted_envelope"]param = "message"-rationale = "Renders the message; single operand."+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."+["pipelex/cli/agent_cli/commands/agent_output.py::agent_file_error"]+param = "message"+rationale = "Refuses a local file with the command's message; single operand, as agent_error."+["pipelex/cli/agent_cli/commands/agent_output.py::agent_success"]param = "result"rationale = "Emits the success result payload; single operand."@@ -64,10 +60,6 @@ rationale = "Emits the success result payload; single operand."param = "result"rationale = "Emits the formatted success result; single operand."-["pipelex/cli/agent_cli/commands/agent_output.py::extract_validation_errors"]-param = "exc"-rationale = "Extracts from the exc; single operand."-["pipelex/cli/agent_cli/commands/agent_output.py::set_agent_cli_error_format"]param = "error_format"rationale = "Setter: installs the agent-CLI error format; single operand."@@ -4488,9 +4480,9 @@ rationale = "Verb-object: formats the fix payload; bundle_path is context."param = "result"rationale = "Positional-Callable protocol shape: markdown renderer over the result dict."-["pipelex/pipeline/fixes/fix_render.py::format_fix_still_invalid_markdown"]+["pipelex/pipeline/fixes/fix_render.py::format_fix_progress_markdown"]param = "result"-rationale = "Verb-object: formats the fix result; bundle_path is context."+rationale = "Verb-object: formats the fix result's progress; bundle_path is context."["pipelex/pipeline/fixes/planner.py::_plan_match_sequence_output"]param = "error_data"diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txtindex f0931ce9e..735b6e066 100644--- a/tests/data/errors/error_identity.txt+++ b/tests/data/errors/error_identity.txt@@ -113,6 +113,7 @@ FatalError | abstractFileTypeError | one of input.file_type_unsupported, provider.response_invalidFixTransactionError | runtime.unexpectedFixWriteConflictError | method.changed_concurrently+FixWriteFailedError | client.write_failedFormerReleaseConfigError | pipelex.config.invalidFuncOutputTypeError | pipe.output_invalidFunctionNamesMigrationError | inherits cause, else runtime.unexpected; or chosen: request.invaliddiff --git a/tests/data/usage_stats/usage-statistics.json b/tests/data/usage_stats/usage-statistics.jsonindex 95a929cb5..ed6ef11e6 100644--- a/tests/data/usage_stats/usage-statistics.json+++ b/tests/data/usage_stats/usage-statistics.json@@ -1,7 +1,7 @@{"description": "The usage-statistics contract in machine-readable form: the source of truth for specs/usage-statistics.md's generated tables, the PostHog gate generated from it, and every emitter's typed events. Emitters vendor it byte-identical; conformance/scripts/check-usage-statistics-schema.py gates the copies.","spec": "conformance/specs/usage-statistics.md",- "schema_version": 1,+ "schema_version": 2,"destination": {"project": "Open-source usage","region": "eu",@@ -36,6 +36,11 @@"max_length": 96,"description": "A model's name as a shipped backend table names it, or `other`."},+ "error_code": {+ "regex": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*){1,2}$",+ "max_length": 96,+ "description": "A problem registry's error code, the MTHDS standard's code pattern: a family and a name, such as `input.invalid`, or a runtime's own code under its prefix, such as `pipelex.config.invalid`."+ },"installation_id": {"regex": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","max_length": 36,@@ -92,7 +97,7 @@"type": "integer","required": true,"min": 1,- "max": 1,+ "max": 2,"description": "The version of this event schema the event follows."},"tool": {@@ -240,16 +245,27 @@],"description": "How the run ended."},+ "error_code": {+ "type": "pattern",+ "required": true,+ "pattern": "error_code",+ "description": "For a failed run, the code of its error, from the problem registry: `runtime.unexpected` for an error the runtime gives no other code.",+ "when": {+ "property": "outcome",+ "equals": "failed"+ }+ },"error_domain": {"type": "enum","required": true,"values": ["input",- "config",- "runtime",- "other"+ "method",+ "account",+ "operator",+ "runtime"],- "description": "For a failed run, who can fix the error, `other` when the runtime cannot say.",+ "description": "For a failed run, who must act on the error: the domain of its code.","when": {"property": "outcome","equals": "failed"@@ -653,47 +669,40 @@"max": 10000000,"description": "The run's failed calls to this model."},- "failures_transient": {- "type": "integer",- "required": true,- "min": 0,- "max": 10000000,- "description": "The failed calls the runtime classified as `transient`."- },- "failures_configuration": {+ "failures_input": {"type": "integer","required": true,"min": 0,"max": 10000000,- "description": "The failed calls the runtime classified as `configuration`."+ "description": "The failed calls whose error's code has the domain `input`."},- "failures_content": {+ "failures_method": {"type": "integer","required": true,"min": 0,"max": 10000000,- "description": "The failed calls the runtime classified as `content`."+ "description": "The failed calls whose error's code has the domain `method`."},- "failures_capacity": {+ "failures_account": {"type": "integer","required": true,"min": 0,"max": 10000000,- "description": "The failed calls the runtime classified as `capacity`."+ "description": "The failed calls whose error's code has the domain `account`."},- "failures_ambiguous": {+ "failures_operator": {"type": "integer","required": true,"min": 0,"max": 10000000,- "description": "The failed calls the runtime classified as `ambiguous`."+ "description": "The failed calls whose error's code has the domain `operator`."},- "failures_unknown": {+ "failures_runtime": {"type": "integer","required": true,"min": 0,"max": 10000000,- "description": "The failed calls the runtime classified as `unknown`."+ "description": "The failed calls whose error's code has the domain `runtime`."},"input_tokens": {"type": "integer",@@ -894,16 +903,27 @@],"description": "How the command ended; `cancelled` for an interrupt."},+ "error_code": {+ "type": "pattern",+ "required": false,+ "pattern": "error_code",+ "description": "For a failed command, the code of its error, from the problem registry, when the tool can say.",+ "when": {+ "property": "outcome",+ "equals": "failed"+ }+ },"error_domain": {"type": "enum","required": false,"values": ["input",- "config",- "runtime",- "other"+ "method",+ "account",+ "operator",+ "runtime"],- "description": "For a failed command, who can fix the error, when the tool can say.",+ "description": "For a failed command, who must act on the error, the domain of its code, when the tool can say.","when": {"property": "outcome","equals": "failed"@@ -1414,7 +1434,7 @@"type": "integer","required": true,"min": 1,- "max": 1,+ "max": 2,"description": "The version of this event schema the event follows."},"deletion_key": {diff --git a/tests/e2e/agent_cli/test_fix_bundle.py b/tests/e2e/agent_cli/test_fix_bundle.pyindex 8fc55f220..af16c114c 100644--- a/tests/e2e/agent_cli/test_fix_bundle.py+++ b/tests/e2e/agent_cli/test_fix_bundle.py@@ -92,6 +92,6 @@ class TestFixBundleE2E:assert result.returncode == 1, f"unfixable bundle must exit 1.\nstdout={result.stdout!r}\nstderr={result.stderr!r}"assert result.stdout == ""payload = json.loads(result.stderr)- assert payload["error_type"] == "FixBundleError"+ assert payload["code"] == "method.invalid"assert payload["is_valid"] is False- assert payload["remaining_errors"]+ assert payload["errors"]diff --git a/tests/e2e/pipelex/cli/test_former_release_commands.py b/tests/e2e/pipelex/cli/test_former_release_commands.pyindex fa42ce3cc..9ad670f7a 100644--- a/tests/e2e/pipelex/cli/test_former_release_commands.py+++ b/tests/e2e/pipelex/cli/test_former_release_commands.py@@ -88,9 +88,15 @@ class TestAFormerReleaseMachine:assert "FormerReleaseConfigError" in output, outputassert "pipelex migrate" in outputassert "pipelex init" in output- envelope = json.loads(booted.stderr)- assert envelope["error_type"] == "FormerReleaseConfigError"- assert "pipelex-agent migrate --dry-run --format json" in envelope["hint"], "an agent is handed the loop it can run"+ problem = json.loads(booted.stderr)+ assert problem["code"] == "pipelex.config.invalid"+ assert problem["diagnostics"]["error_class"] == "FormerReleaseConfigError"++ # The error's advice is a tip the Markdown prints, the stream an agent reads by default.+ booted_markdown = _run(args=[str(PIPELEX_AGENT_BIN), "models", "--format", "markdown"], env=offline_subprocess_env, cwd=project_dir)+ assert booted_markdown.returncode != 0+ assert "💡 " in booted_markdown.stderr+ assert "pipelex-agent migrate --dry-run --format json" in booted_markdown.stderr, "an agent is handed the loop it can run"def test_pipelex_migrate_cleans_both_directories_and_the_machine_boots(self, hermetic_home: Path, offline_subprocess_env: dict[str, str]) -> None:project_dir, home_config_dir, project_config_dir = _plant_a_former_release_machine(hermetic_home=hermetic_home)diff --git a/tests/e2e/pipelex/cli/test_migrate_commands.py b/tests/e2e/pipelex/cli/test_migrate_commands.pyindex ab2a198b6..32a2532a7 100644--- a/tests/e2e/pipelex/cli/test_migrate_commands.py+++ b/tests/e2e/pipelex/cli/test_migrate_commands.py@@ -522,7 +522,9 @@ class TestTheAgentMigrateLoop:)assert refused.returncode == 2- assert json.loads(refused.stderr)["error_type"] == "ArgumentError"+ problem: dict[str, Any] = json.loads(refused.stderr)+ assert problem["code"] == "client.argument_invalid"+ assert problem["params"] == {"argument": "--yes", "reason": "contradicts --dry-run"}class TestAPreReshapeMachine:@@ -727,12 +729,13 @@ class TestAPreReshapeMachine:boot = _boot(env=offline_subprocess_env, cwd=hermetic_home)assert boot.returncode != 0, "a file the ledger cannot fully explain still fails the boot"- assert boot.stderr.count('"error": true') == 1, boot.stderr- envelope: dict[str, Any] = json.loads(boot.stderr)- assert envelope["error_type"] == "PipelexConfigError"- assert envelope["error_domain"] == "config"+ # One problem: a second JSON document on the stream would make json.loads refuse it ("Extra data").+ problem: dict[str, Any] = json.loads(boot.stderr)+ assert problem["code"] == "pipelex.config.invalid"+ assert problem["domain"] == "operator"+ assert problem["diagnostics"]["error_class"] == "PipelexConfigError"- block: dict[str, Any] = envelope["migration"]+ block: dict[str, Any] = problem["diagnostics"]["migration"]assert block["remedy"] == "pipelex migrate"assert block["needs_attention"] is Truefirst_step_title = next(step["title"] for plan in block["plans"] for step in plan["steps"])@@ -1007,7 +1010,7 @@ class TestABootFailureCarriesThePendingMigration:config_file.write_text(planted + config_file.read_text(encoding="utf-8"), encoding="utf-8")return config_file- def test_the_agent_boot_error_carries_the_config_domain_and_the_block(+ def test_the_agent_boot_error_carries_the_operator_domain_and_the_block(self,hermetic_home: Path,offline_subprocess_env: dict[str, str],@@ -1017,16 +1020,19 @@ class TestABootFailureCarriesThePendingMigration:boot = _boot(env=offline_subprocess_env, cwd=hermetic_home)assert boot.returncode != 0, "the scenario is worthless if this machine boots"- # One envelope, and it has to be said out loud: `agent_error` leaves through `typer.Exit`,+ # One problem, and it has to be said out loud: `agent_error` leaves through `typer.Exit`,# which is a `RuntimeError` rather than a `SystemExit`, so a command boundary re-raising# only `SystemExit` caught it again and printed a second document after the first. Two- # JSON documents on one stream is not JSON, and the block below would be unreadable.- assert boot.stderr.count('"error": true') == 1, boot.stderr- envelope: dict[str, Any] = json.loads(boot.stderr)- assert envelope["error_type"] == "PipelexConfigError"- assert envelope["error_domain"] == "config", "a new domain would route the agent hooks to BLOCK"+ # JSON documents on one stream is not JSON: json.loads refuses them ("Extra data").+ problem: dict[str, Any] = json.loads(boot.stderr)+ assert problem["code"] == "pipelex.config.invalid"+ assert problem["domain"] == "operator", "the operator's configuration, which only the operator can fix"+ assert problem["next_step"]["kind"] == "fix_configuration"+ assert problem["next_step"]["detail"] == (+ "Correct the setting 'posthog_project_key' in the file 'pipelex.toml' of the pipelex configuration, then restart the runtime."+ )- block: dict[str, Any] = envelope["migration"]+ block: dict[str, Any] = problem["diagnostics"]["migration"]assert block["remedy"] == "pipelex migrate"assert block["needs_attention"] is True, "a key no entry explains is a person's to resolve"unexplained = [found for plan in block["plans"] for found in plan["unexplained"]]@@ -1103,7 +1109,7 @@ class TestAStaleTelemetryFileIsMigratedNotReset:assert any("pipelex migrate" in action for action in actions)assert not any("init telemetry" in action for action in actions), "this file is old, not broken"- def test_a_telemetry_boot_failure_carries_the_block_in_one_envelope(+ def test_a_telemetry_boot_failure_carries_the_block_in_one_problem(self,hermetic_home: Path,offline_subprocess_env: dict[str, str],@@ -1121,12 +1127,12 @@ class TestAStaleTelemetryFileIsMigratedNotReset:boot = _boot(env=offline_subprocess_env, cwd=hermetic_home)assert boot.returncode != 0, "a file the ledger cannot fully explain still fails the boot"- assert boot.stderr.count('"error": true') == 1, boot.stderr- envelope: dict[str, Any] = json.loads(boot.stderr)- assert envelope["error_type"] == "TelemetryConfigValidationError"- assert envelope["error_domain"] == "config", "it comes from the class now, not the lookup table"- assert envelope["migration"]["remedy"] == "pipelex migrate"- assert "init telemetry" not in envelope["hint"]+ problem: dict[str, Any] = json.loads(boot.stderr)+ assert problem["code"] == "pipelex.config.invalid"+ assert problem["domain"] == "operator"+ assert problem["diagnostics"]["error_class"] == "TelemetryConfigValidationError"+ assert problem["diagnostics"]["migration"]["remedy"] == "pipelex migrate"+ assert "init telemetry" not in problem["next_step"]["detail"]def test_the_human_doctor_says_migrate_and_never_offers_to_start_the_file_over(self,diff --git a/tests/helpers/fix_results.py b/tests/helpers/fix_results.pynew file mode 100644index 000000000..6a7cd3341--- /dev/null+++ b/tests/helpers/fix_results.py@@ -0,0 +1,20 @@+from typing import Any++from mthds.protocol.problem.registry import CoreCode++from pipelex.pipeline.fixes.fix_loop import FixBundleResult+from pipelex.pipeline.validation_errors import ValidationItemCode, validation_item_code+++def fix_result(**fields: Any) -> FixBundleResult:+ """A fix result as a test states it, each remaining error coded by its type when the test gives no codes.++ The fix loop takes each remaining error's code from the verdict it read; a test that only renders the errors has no+ verdict, so its errors take the code their type gives them, ``method.schema_violation`` for an item with none.+ """+ if "remaining_error_codes" not in fields:+ remaining_errors = fields.get("remaining_errors", [])+ fields["remaining_error_codes"] = [+ ValidationItemCode(code=validation_item_code(item=item, residual_code=CoreCode.METHOD_SCHEMA_VIOLATION)) for item in remaining_errors+ ]+ return FixBundleResult(**fields)diff --git a/tests/integration/pipelex/cli/agent_cli/conftest.py b/tests/integration/pipelex/cli/agent_cli/conftest.pyindex f7f343640..0c393a932 100644--- a/tests/integration/pipelex/cli/agent_cli/conftest.py+++ b/tests/integration/pipelex/cli/agent_cli/conftest.py@@ -6,7 +6,7 @@ from typing import TYPE_CHECKINGimport pytest-from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_format+from pipelex.cli.agent_cli.commands.agent_output import start_agent_cli_error_formatif TYPE_CHECKING:from collections.abc import Iterator@@ -14,7 +14,7 @@ if TYPE_CHECKING:@pytest.fixture(autouse=True)def reset_agent_cli_error_format() -> Iterator[None]:- """Keep the module-level error-format ContextVar from leaking between tests."""- set_agent_cli_error_format(CliOutputFormat.JSON)+ """Keep the error-format ContextVars, the program's and the active one, from leaking between tests."""+ start_agent_cli_error_format()yield- set_agent_cli_error_format(CliOutputFormat.JSON)+ start_agent_cli_error_format()diff --git a/tests/integration/pipelex/cli/agent_cli/test_run_error_chain.py b/tests/integration/pipelex/cli/agent_cli/test_run_error_chain.pyindex fd9ef9eb8..010664020 100644--- a/tests/integration/pipelex/cli/agent_cli/test_run_error_chain.py+++ b/tests/integration/pipelex/cli/agent_cli/test_run_error_chain.py@@ -2,13 +2,13 @@Proves that a deterministic worker failure propagates through the wholepipeline — worker error -> pipe operator -> router -> runner ->-PipelineExecutionError -> agent_error() -> stderr — and surfaces correct-structured output in both JSON and markdown.+PipelineExecutionError -> agent_error() -> stderr — and surfaces as the+worker's problem, located at the failing pipe, in both JSON and markdown.The LLM worker is mocked to raise a transient LLMCompletionError; everywrapping layer below the CLI runs for real, so this catches wiring-regressions no per-worker test can (a wrapper dropping error_category, a-field agent_error() forgets to forward, a degraded error_source chain).+regressions no per-worker test can (a wrapper hiding the worker's code,+a lost location, a lost model or provider, a degraded cause chain)."""from __future__ import annotations@@ -76,71 +76,47 @@ class TestRunErrorChain:mocker: MockerFixture,capsys: pytest.CaptureFixture[str],) -> None:- """The JSON error payload carries the worker's category, retryability, model, and source chain."""+ """The JSON problem is the worker's: its code and retry verdict, located at the pipe, with the model, provider and chain."""self._invoke_failing_run(mocker, CliOutputFormat.JSON)captured = capsys.readouterr()assert captured.out == ""payload = json.loads(captured.err)- assert payload["error"] is True- assert payload["error_type"] == "PipelineExecutionError"- assert payload["message"]- # error_category / retryable / model / provider originate on the worker's- # LLMCompletionError and must survive every wrapping layer.- assert payload["error_category"] == "transient"- assert payload["retryable"] is True- assert payload["hint"] == WORKER_ADVICE- assert payload["error_domain"] == "runtime"- assert payload["model"] == WORKER_MODEL- assert payload["provider"] == WORKER_PROVIDER- assert payload["pipe_code"] == "greet"- assert payload["pipe_stack"] == ["greet"]- # The cause fields name the root fault, not the router wrapper right under the run error.- assert payload["cause_type"] == "LLMCompletionError"- assert payload["cause_message"] == WORKER_ERROR_MESSAGE+ # The code, the domain and the verdict originate on the worker's LLMCompletionError and survive every wrapping layer.+ assert payload["code"] == "provider.unavailable"+ assert payload["domain"] == "runtime"+ assert payload["retry"] == "yes"+ assert payload["location"] == {"pipe": "greet", "path": ["greet"]}assert payload["message"] == f"Pipe 'greet' failed: {WORKER_ERROR_MESSAGE}"-- # error_source is the cause chain, outermost first: runner -> router -> pipe operator -> worker.- error_source: list[str] = payload["error_source"]- assert isinstance(error_source, list)- joined_source = "\n".join(error_source)- runner_frame = joined_source.index("PipelineExecutionError")- router_frame = joined_source.index("PipeRouterError")- operator_frame = joined_source.index("PipeRunError")- worker_frame = joined_source.index("LLMCompletionError")- assert runner_frame < router_frame < operator_frame < worker_frame+ diagnostics = payload["diagnostics"]+ assert diagnostics["error_class"] == "LLMCompletionError"+ assert diagnostics["model"] == WORKER_MODEL+ assert diagnostics["provider"]["name"] == WORKER_PROVIDER+ for retired in ("error", "error_type", "error_category", "retryable", "hint", "error_source", "cause_type", "pipe_stack"):+ assert retired not in payloaddef test_run_error_chain_markdown(self,mocker: MockerFixture,capsys: pytest.CaptureFixture[str],) -> None:- """The markdown error output carries the error type, message, hint, and structured details — but no source frames.-- ``error_source`` (the internal Python stack chain — ``PipeRouterError``,- ``LLMCompletionError``, etc.) is deliberately stripped from markdown. It's- noise for an LLM trying to fix a `.mthds` file. The JSON test above is what- pins the wrapping-chain contract.- """+ """The markdown problem names the fault, the next step, the worker's advice, the place, the model and provider — no source frames."""self._invoke_failing_run(mocker, CliOutputFormat.MARKDOWN)captured = capsys.readouterr()assert captured.out == ""markdown = captured.err- assert markdown.startswith("# Error: PipelineExecutionError")+ assert markdown.startswith("## ")assert WORKER_ERROR_MESSAGE in markdown- assert "💡" in markdown # hint callout- assert WORKER_ADVICE in markdown- assert "error_category" in markdown- assert "transient" in markdown- # The whole stack-trace section is gone. The stack-frame format from- # _build_error_source is "<ExceptionType> @ <file>:<line> (in <func>)" —- # check the section header and the frame format are both absent.- # Note: structured cause fields like ``cause_type`` may legitimately- # surface exception names under ``## Details``; that's not a stack frame.- assert "## Error source" not in markdown+ assert "**Next step** (`retry`)" in markdown+ assert f"💡 {WORKER_ADVICE}" in markdown+ assert "- Code: `provider.unavailable` (domain runtime, retry yes)" in markdown+ assert "- Location: pipe 'greet', path greet" in markdown+ assert f"- Model: `{WORKER_MODEL}`" in markdown+ assert f"- Provider: `{WORKER_PROVIDER}`" in markdown+ # No stack frame reaches the agent: the frame format "<ExceptionType> @ <file>:<line> (in <func>)" is absent.assert " @ pipelex/" not in markdownassert "(in " not in markdownwith pytest.raises(json.JSONDecodeError):diff --git a/tests/integration/pipelex/cli/test_agent_bundle_file_reads.py b/tests/integration/pipelex/cli/test_agent_bundle_file_reads.pynew file mode 100644index 000000000..48c6ba50a--- /dev/null+++ b/tests/integration/pipelex/cli/test_agent_bundle_file_reads.py@@ -0,0 +1,213 @@+from __future__ import annotations++import json+import os+import sys+from pathlib import Path+from typing import TYPE_CHECKING, Any++import pytest+import typer+from mthds.method_tree.models import TreeLimits++from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_format+from pipelex.cli.agent_cli.commands.fix.bundle_cmd import fix_bundle_cmd+from pipelex.cli.agent_cli.commands.inputs.bundle_cmd import inputs_bundle_cmd+from pipelex.cli.agent_cli.commands.run.bundle_cmd import run_bundle_cmd+from pipelex.cli.agent_cli.commands.validate.bundle_cmd import validate_bundle_cmd++if TYPE_CHECKING:+ from collections.abc import Callable, Iterator++ from pytest_mock import MockerFixture++_BUNDLE = """domain = "greetings"+main_pipe = "say_hello"++[pipe.say_hello]+type = "PipeLLM"+description = "Say hello"+output = "Text"+prompt = "Say hello"+"""+++def _validate(path: str) -> None:+ validate_bundle_cmd(path=path, output_format=CliOutputFormat.JSON, error_format=CliOutputFormat.JSON)+++def _inputs(path: str) -> None:+ inputs_bundle_cmd(path=path, error_format=CliOutputFormat.JSON)+++def _fix(path: str) -> None:+ fix_bundle_cmd(path=path, output_format=CliOutputFormat.JSON, error_format=CliOutputFormat.JSON)+++def _run(path: str) -> None:+ run_bundle_cmd(path=path, output_format=CliOutputFormat.JSON, error_format=CliOutputFormat.JSON)+++_COMMANDS: list[tuple[str, Callable[[str], None]]] = [+ ("validate", _validate),+ ("inputs", _inputs),+ ("fix", _fix),+ ("run", _run),+]++[email protected](autouse=True)+def no_boot(mocker: MockerFixture) -> Iterator[None]:+ """The suite's session boot owns the runtime, and no run reaches its pipeline."""+ for module in ("validate", "inputs", "fix", "run"):+ mocker.patch(f"pipelex.cli.agent_cli.commands.{module}.bundle_cmd.make_pipelex_for_agent_cli")+ mocker.patch(f"pipelex.cli.agent_cli.commands.{module}.bundle_cmd.Pipelex.teardown_if_needed")+ mocker.patch("pipelex.cli.agent_cli.commands.run.bundle_cmd.run_pipeline_core", new=mocker.AsyncMock(return_value={}))+ yield+ set_agent_cli_error_format(CliOutputFormat.JSON)+++def _problem_of(*, command: Callable[[str], None], path: Path, capsys: pytest.CaptureFixture[str]) -> dict[str, Any]:+ with pytest.raises(typer.Exit):+ command(str(path))+ problem: dict[str, Any] = json.loads(capsys.readouterr().err)+ return problem+++class TestAgentBundleFileReads:+ @pytest.mark.skipif(sys.platform == "win32" or os.geteuid() == 0, reason="needs a file permissions can keep this user from reading")+ @pytest.mark.parametrize(("name", "command"), _COMMANDS)+ def test_a_bundle_this_machine_cannot_read_is_the_file_s_refusal(+ self, tmp_path: Path, capsys: pytest.CaptureFixture[str], name: str, command: Callable[[str], None]+ ) -> None:+ """Every bundle command refuses a bundle file the system will not let it read as `client.file_unreadable`, naming it."""+ bundle_file = tmp_path / f"{name}.mthds"+ bundle_file.write_text(_BUNDLE, encoding="utf-8")+ bundle_file.chmod(0)+ try:+ problem = _problem_of(command=command, path=bundle_file, capsys=capsys)+ finally:+ bundle_file.chmod(0o600)++ assert problem["code"] == "client.file_unreadable"+ assert problem["params"]["reason"] == "permission denied"+ assert problem["params"]["path"].endswith(f"{name}.mthds")++ @pytest.mark.parametrize(("name", "command"), _COMMANDS)+ @pytest.mark.parametrize(+ ("content", "line", "column"),+ [+ # Not UTF-8 text: located at the first byte that does not decode.+ (b'domain = "caf\xe9"\n', 1, 14),+ # UTF-8 text that is not TOML.+ (b'domain = "greetings"\nmain_pipe =\n', 2, 12),+ ],+ )+ def test_a_bundle_that_does_not_parse_is_the_method_s_syntax_fault(+ self,+ tmp_path: Path,+ capsys: pytest.CaptureFixture[str],+ name: str,+ command: Callable[[str], None],+ content: bytes,+ line: int,+ column: int,+ ) -> None:+ """Every bundle command refuses a bundle file that does not parse as `validate` does: the invalid verdict, its item `method.syntax`."""+ bundle_file = tmp_path / f"{name}.mthds"+ bundle_file.write_bytes(content)++ problem = _problem_of(command=command, path=bundle_file, capsys=capsys)++ assert problem["code"] == "method.invalid"+ (item,) = problem["errors"]+ assert item["code"] == "method.syntax"+ assert item["location"]["line"] == line+ assert item["location"]["column"] == column+++def bundle_never_read(mocker: MockerFixture) -> None:+ """Fail the test as soon as a command reads a `.mthds` file whole: its tree's listing must refuse the file first."""+ real_read_bytes = Path.read_bytes++ def guarded_read_bytes(self: Path) -> bytes:+ if self.suffix == ".mthds":+ msg = f"The bundle file '{self}' was read whole before its tree was listed."+ raise AssertionError(msg)+ return real_read_bytes(self)++ mocker.patch.object(Path, "read_bytes", autospec=True, side_effect=guarded_read_bytes)++[email protected]("bundle_never_read")+class TestAgentRunBundleListsTheTreeFirst:+ def test_a_bundle_file_past_this_machine_s_limits_is_refused_unread(+ self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]+ ) -> None:+ """`run bundle` lists a bundle file's tree before reading it, so a file past the limits is refused, never read whole."""+ mocker.patch("pipelex.libraries.method_trees.local_tree_limits", return_value=TreeLimits(max_file_bytes=16))+ bundle_file = tmp_path / "run.mthds"+ bundle_file.write_text(_BUNDLE, encoding="utf-8")++ problem = _problem_of(command=_run, path=bundle_file, capsys=capsys)++ assert problem["code"] == "method.invalid"+ assert "interpreter.method_tree_limits" in problem["message"]++ @pytest.mark.skipif(sys.platform == "win32", reason="needs a FIFO")+ def test_a_fifo_named_as_the_bundle_file_is_refused_unread(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ """`run bundle` refuses a FIFO named as its bundle file from its tree's listing, rather than blocking on reading it."""+ fifo = tmp_path / "run.mthds"+ os.mkfifo(fifo)++ problem = _problem_of(command=_run, path=fifo, capsys=capsys)++ assert problem["code"] == "method.invalid"+ assert "neither a regular file nor a directory" in problem["message"]++ def test_a_bundle_file_that_does_not_exist_is_the_file_s_refusal(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ """A bundle file the listing finds missing is the file the command was handed, `client.file_unreadable`, not found."""+ missing = tmp_path / "run.mthds"++ problem = _problem_of(command=_run, path=missing, capsys=capsys)++ assert problem["code"] == "client.file_unreadable"+ assert problem["params"]["reason"] == "not found"+ assert problem["params"]["path"] == str(missing)+++class TestAgentBundleSystemErrorsNamingNoFile:+ @pytest.mark.parametrize(+ ("command", "core_target"),+ [+ (_validate, "pipelex.cli.agent_cli.commands.validate.bundle_cmd.validate_bundle_core"),+ (_inputs, "pipelex.cli.agent_cli.commands.inputs.bundle_cmd.inputs_core"),+ (_fix, "pipelex.cli.agent_cli.commands.fix.bundle_cmd.fix_judged_target"),+ ],+ )+ @pytest.mark.parametrize(+ "system_error",+ [+ ConnectionRefusedError(61, "Connection refused"),+ TimeoutError("timed out"),+ ],+ )+ def test_a_system_error_naming_no_file_is_no_refusal_of_the_bundle(+ self,+ mocker: MockerFixture,+ tmp_path: Path,+ capsys: pytest.CaptureFixture[str],+ command: Callable[[str], None],+ core_target: str,+ system_error: OSError,+ ) -> None:+ """An `OSError` naming no file, met while the command ran, is the unexpected failure it is, never `client.file_unreadable`."""+ mocker.patch(core_target, new=mocker.AsyncMock(side_effect=system_error))+ bundle_file = tmp_path / "bundle.mthds"+ bundle_file.write_text(_BUNDLE, encoding="utf-8")++ problem = _problem_of(command=command, path=bundle_file, capsys=capsys)++ assert problem["code"] == "runtime.unexpected"+ assert problem["diagnostics"]["error_class"] == type(system_error).__name__diff --git a/tests/integration/pipelex/cli/test_agent_fix_bundle.py b/tests/integration/pipelex/cli/test_agent_fix_bundle.pyindex cdd72cfd0..4415c82ce 100644--- a/tests/integration/pipelex/cli/test_agent_fix_bundle.py+++ b/tests/integration/pipelex/cli/test_agent_fix_bundle.py@@ -3,13 +3,15 @@from __future__ import annotationsimport json+import os+import sysfrom typing import TYPE_CHECKING, castimport pytestimport tomlkitimport typer-from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_formatfrom pipelex.cli.agent_cli.commands.fix.bundle_cmd import fix_bundle_cmdif TYPE_CHECKING:@@ -117,10 +119,10 @@ class TestAgentFixBundle:assert exc_info.value.exit_code == 1payload = json.loads(capsys.readouterr().err)- assert payload["error_type"] == "FixBundleError"+ assert payload["code"] == "method.invalid"assert payload["is_valid"] is Falseassert payload["fixes_applied"] == []- assert payload["remaining_errors"]+ assert payload["errors"]def test_signature_only_bundle_exits_one_after_success_payload(self,@@ -147,6 +149,7 @@ class TestAgentFixBundle:assert payload["pending_signatures"] == ["agent_fix_signature.summarize_doc"]assert payload["fixes_applied"] == []assert payload["remaining_errors"] == []+ assert "remaining_error_codes" not in payloaddef test_select_filter_is_honored_end_to_end(self,@@ -172,3 +175,32 @@ class TestAgentFixBundle:assert payload["is_valid"] is Falseassert payload["fixes_applied"] == []assert _pipes(bundle_path)["list_ideas"]["output"] == "Idea"++ @pytest.mark.skipif(sys.platform == "win32" or os.geteuid() == 0, reason="needs a directory permissions can keep this user from writing in")+ def test_a_fix_it_cannot_write_is_a_write_failure_never_an_unreadable_file(+ self,+ tmp_path: Path,+ mocker: MockerFixture,+ capsys: pytest.CaptureFixture[str],+ load_empty_library: Callable[[], str],+ ) -> None:+ """A fix whose directory refuses its write is `client.write_failed` naming the directory, and the bundle is left as it was."""+ load_empty_library()+ _patch_setup(mocker)+ bundle_dir = tmp_path / "read_only"+ bundle_dir.mkdir()+ bundle_path = bundle_dir / "bundle.mthds"+ bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")+ bundle_dir.chmod(0o500)+ try:+ with pytest.raises(typer.Exit) as exc_info:+ fix_bundle_cmd(path=str(bundle_path), output_format=CliOutputFormat.JSON, error_format=CliOutputFormat.JSON)+ finally:+ bundle_dir.chmod(0o700)+ set_agent_cli_error_format(CliOutputFormat.JSON)++ assert exc_info.value.exit_code == 2+ payload = json.loads(capsys.readouterr().err)+ assert payload["code"] == "client.write_failed"+ assert payload["params"] == {"path": str(bundle_dir.resolve()), "reason": "permission denied"}+ assert bundle_path.read_text(encoding="utf-8") == _FIXABLE_SEQUENCE_MTHDSdiff --git a/tests/integration/pipelex/cli/test_agent_validate_pipe_dry_run_items.py b/tests/integration/pipelex/cli/test_agent_validate_pipe_dry_run_items.pyindex ea6577020..e64972a99 100644--- a/tests/integration/pipelex/cli/test_agent_validate_pipe_dry_run_items.py+++ b/tests/integration/pipelex/cli/test_agent_validate_pipe_dry_run_items.py@@ -58,11 +58,9 @@ class TestAgentValidatePipeDryRunItems:assert exc_info.value.exit_code == 1envelope: dict[str, Any] = json.loads(capsys.readouterr().err)assert envelope["is_valid"] is False- assert envelope["error_type"] == "ValidateBundleError"- (item,) = envelope["validation_errors"]- assert item["category"] == "dry_run"- assert item["error_type"] == "DryRunError"- assert item["pipe_code"] == "analyze_topic"- assert item["domain_code"] == ValidationDetailBundles.DOMAIN- assert item["source"] == str(library_dir / "bundle.mthds")- assert not any(marker in item["message"] for marker in ValidationDetailBundles.RECORD_REPR_MARKERS)+ assert envelope["code"] == "method.invalid"+ (item,) = envelope["errors"]+ assert item["location"]["pipe"] == "analyze_topic"+ assert item["location"]["file"] == str(library_dir / "bundle.mthds")+ assert not any(marker in item["detail"] for marker in ValidationDetailBundles.RECORD_REPR_MARKERS)+ assert not any(marker in envelope["message"] for marker in ValidationDetailBundles.RECORD_REPR_MARKERS)diff --git a/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.py b/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.pyindex c8e460889..75b4455e6 100644--- a/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.py+++ b/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.py@@ -7,7 +7,7 @@ verdict. These tests drive the real run cores on a bundle whose pipe names a misitem, and exits 1 — whether the bundle is run from its directory (loaded as a library directory) or asa file, and whether the parse or the load refuses it. It used to print one line, ``Failed to executepipeline '<pipe>': Could not load blueprints from [...] because of: …``.-- ``pipelex-agent run bundle`` copies the verdict's ``validation_errors`` into its error envelope, and its+- ``pipelex-agent run bundle`` reports the verdict's problem, its items the problem's ``errors``, and itsmarkdown error renders them as the same grouped prose ``validate`` prints."""@@ -56,7 +56,7 @@ main_pipe = "write_tide_notice"def console(mocker: MockerFixture) -> Console:"""A recording console patched into the error handlers, so the panel can be read back."""recorded_console = Console(width=200, record=True, color_system=None)- mocker.patch("pipelex.cli.error_handlers.get_console", return_value=recorded_console)+ mocker.patch("pipelex.cli.error_handlers.get_error_console", return_value=recorded_console)return recorded_console@@ -134,7 +134,7 @@ class TestRunBundleVerdictCli:assert "Bundle validation failed" in outputassert "TOML syntax error at line 2" in output- def test_agent_run_bundle_carries_the_validation_errors(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], tmp_path: Path) -> None:+ def test_agent_run_bundle_carries_the_verdict_s_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")mocker.patch("pipelex.cli.agent_cli.commands.run.bundle_cmd.Pipelex.teardown_if_needed")bundle_path = _write_bundle(directory=tmp_path, content=_MISSPELLED_CONCEPT_BUNDLE)@@ -143,16 +143,16 @@ class TestRunBundleVerdictCli:_run_agent_bundle(bundle_path=bundle_path, output_format=CliOutputFormat.JSON)assert exc_info.value.exit_code == 1- envelope: dict[str, Any] = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "ValidateBundleError"- assert envelope["error_domain"] == "input"- concept_items = [item for item in envelope["validation_errors"] if item.get("error_type") == "unresolved_concept"]- assert concept_items, f"expected an unresolved_concept item, got {envelope['validation_errors']!r}"+ problem: dict[str, Any] = json.loads(capsys.readouterr().err)+ assert problem["code"] == "method.invalid"+ assert problem["domain"] == "method"+ concept_items = [item for item in problem["errors"] if item["code"] == "method.concept_unresolved"]+ assert concept_items, f"expected a method.concept_unresolved item, got {problem['errors']!r}"(item,) = concept_items- assert item["pipe_code"] == "write_tide_notice"- assert item["concept_code"] == "TideNotise"- assert item["field_path"] == "pipe.write_tide_notice.output"- assert item["source"] == str(bundle_path)+ assert item["params"]["concept"] == "TideNotise"+ assert item["location"]["pipe"] == "write_tide_notice"+ assert item["location"]["field"] == "output"+ assert item["location"]["file"] == str(bundle_path)def test_agent_run_bundle_markdown_renders_the_items_as_prose(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], tmp_path: Path@@ -166,7 +166,7 @@ class TestRunBundleVerdictCli:assert exc_info.value.exit_code == 1markdown = capsys.readouterr().err- assert markdown.startswith("# Error: ValidateBundleError")+ assert markdown.startswith("## The method does not validate")assert "## Pipe validation errors" in markdownassert "Concept 'TideNotise' in pipe.write_tide_notice.output is not declared" in markdownassert '"validation_errors"' not in markdowndiff --git a/tests/integration/pipelex/cli/test_run_located_failure_panel.py b/tests/integration/pipelex/cli/test_run_located_failure_panel.pyindex bef36affb..588e13e1d 100644--- a/tests/integration/pipelex/cli/test_run_located_failure_panel.py+++ b/tests/integration/pipelex/cli/test_run_located_failure_panel.py@@ -25,7 +25,7 @@ class TestRunLocatedFailurePanel:) -> None:"""`pipelex run` on the model example renders the model panel naming the failing step, its next step, and the local-deck tip there only."""console = Console(width=400, record=True, color_system=None)- mocker.patch("pipelex.cli.error_handlers.get_console", return_value=console)+ mocker.patch("pipelex.cli.error_handlers.get_error_console", return_value=console)mocker.patch("pipelex.cli.commands.run._run_core.get_console", return_value=console)bundle_path = tmp_path / "located_failure_model.mthds"bundle_path.write_text(LocatedRunFailureTestData.MODEL_MTHDS, encoding="utf-8")diff --git a/tests/integration/pipelex/cli/test_run_truncated_completion.py b/tests/integration/pipelex/cli/test_run_truncated_completion.pyindex 6ed560315..36bf4b503 100644--- a/tests/integration/pipelex/cli/test_run_truncated_completion.py+++ b/tests/integration/pipelex/cli/test_run_truncated_completion.py@@ -72,12 +72,19 @@ class TestRunTruncatedCompletion:mocker: MockerFixture,tmp_path: Path,capsys: pytest.CaptureFixture[str],+ monkeypatch: pytest.MonkeyPatch,) -> None:- """`pipelex run` on a step whose completion stops at its limit exits non-zero, naming the pipe and the truncation, and prints no output."""+ """`pipelex run` on a step whose completion stops at its limit exits non-zero, naming the pipe and its truncation on stderr.++ Nothing of the failure is printed on stdout.+ """mocker.patch("pipelex.cogt.content_generation.llm_generate.get_llm_worker", return_value=_truncating_worker())+ # The output console, stdout, is recorded to show the failure never reaches it; the report goes to stderr,+ # wide enough that no sentence of it wraps.console = Console(width=400, record=True, color_system=None)- mocker.patch("pipelex.cli.error_handlers.get_console", return_value=console)+ mocker.patch("pipelex.cli.error_handlers.get_error_console", return_value=console)mocker.patch("pipelex.cli.commands.run._run_core.get_console", return_value=console)+ monkeypatch.setenv("COLUMNS", "400")bundle_path = tmp_path / "truncated_completion.mthds"bundle_path.write_text(TruncatedCompletionRunTestData.MTHDS, encoding="utf-8")@@ -100,14 +107,20 @@ class TestRunTruncatedCompletion:)assert exit_info.value.exit_code == 1- stderr = capsys.readouterr().err+ captured = capsys.readouterr()+ printed = captured.errpipe_code = TruncatedCompletionRunTestData.PIPE_CODEmodel_handle = TruncatedCompletionRunTestData.MODEL_HANDLE- assert f"Failed to execute pipeline '{pipe_code}': Pipe '{pipe_code}' failed: " in stderr+ assert f"Failed to execute pipeline '{pipe_code}'" in printed+ assert f"Pipe '{pipe_code}' failed: " in printedassert (f"The model '{model_handle}' was cut off before it finished the text of pipe '{pipe_code}' ""(stop reason 'length', 64 output tokens used, no max_tokens sent), so the text is incomplete. ""Set the pipe's max_tokens up to the model's limit, lower its reasoning effort, or shorten its input."- ) in stderr- assert TruncatedCompletionRunTestData.PARTIAL_TEXT not in stderr- assert TruncatedCompletionRunTestData.PARTIAL_TEXT not in console.export_text()+ ) in printed+ # The panel names the problem's code and where it happened.+ assert "Code: model.output_truncated (domain method, retry no)" in printed+ assert f"Location: pipe '{pipe_code}', path {pipe_code}" in printed+ assert TruncatedCompletionRunTestData.PARTIAL_TEXT not in printed+ assert TruncatedCompletionRunTestData.PARTIAL_TEXT not in captured.out+ assert "Failed to execute pipeline" not in console.export_text()diff --git a/tests/integration/pipelex/cli/test_validate_load_refusals_cli.py b/tests/integration/pipelex/cli/test_validate_load_refusals_cli.pyindex a5dda246a..a136c36a4 100644--- a/tests/integration/pipelex/cli/test_validate_load_refusals_cli.py+++ b/tests/integration/pipelex/cli/test_validate_load_refusals_cli.py@@ -61,7 +61,7 @@ _DRY_RUN_FAILURE_PIPE = "route_parcel"def console(mocker: MockerFixture) -> Console:"""A recording console patched into the error handlers, so the panel can be read back."""recorded_console = Console(width=200, record=True, color_system=None)- mocker.patch("pipelex.cli.error_handlers.get_console", return_value=recorded_console)+ mocker.patch("pipelex.cli.error_handlers.get_error_console", return_value=recorded_console)return recorded_console@@ -100,7 +100,7 @@ class TestValidateLoadRefusalsCli:assert "Path: pipe.write_tide_note.model" in outputassert "Traceback" not in output- def test_agent_validate_bundle_emits_the_invalid_verdict_envelope(+ def test_agent_validate_bundle_emits_the_invalid_verdict_s_problem(self,mocker: MockerFixture,capsys: pytest.CaptureFixture[str],@@ -119,19 +119,14 @@ class TestValidateLoadRefusalsCli:set_agent_cli_error_format(CliOutputFormat.JSON)assert exc_info.value.exit_code == 1- envelope = json.loads(capsys.readouterr().err)- assert envelope["is_valid"] is False- assert envelope["error_type"] == "ValidateBundleError"- assert envelope["error_domain"] == "input"- (item,) = envelope["validation_errors"]- assert item["category"] == "pipe_validation"- assert item["error_type"] == "unknown_model"- assert item["pipe_code"] == "write_tide_note"- assert item["domain_code"] == "tide_tables"- assert item["source"] == str(unknown_model_bundle)- assert item["field_path"] == "pipe.write_tide_note.model"- assert item["model_reference"] == "gpt-5.6-lunna"- assert item["model_type"] == "llm"+ problem = json.loads(capsys.readouterr().err)+ assert problem["is_valid"] is False+ assert problem["code"] == "method.invalid"+ assert problem["domain"] == "method"+ (item,) = problem["errors"]+ assert item["code"] == "model.unknown"+ assert item["location"] == {"pipe": "write_tide_note", "field": "model", "file": str(unknown_model_bundle)}+ assert "gpt-5.6-lunna" in json.dumps(item["params"])assert item["suggestions"]@pytest.mark.usefixtures("restore_current_library")diff --git a/tests/integration/pipelex/cli/test_validate_parallel_multiplicity_next_step.py b/tests/integration/pipelex/cli/test_validate_parallel_multiplicity_next_step.pyindex 683873807..72ee7a674 100644--- a/tests/integration/pipelex/cli/test_validate_parallel_multiplicity_next_step.py+++ b/tests/integration/pipelex/cli/test_validate_parallel_multiplicity_next_step.py@@ -177,7 +177,7 @@ def _write_bundle(*, directory: Path, content: str) -> Path:def console(mocker: MockerFixture) -> Console:"""A recording console patched into the error handlers, so the panel can be read back."""recorded_console = Console(width=400, record=True, color_system=None)- mocker.patch("pipelex.cli.error_handlers.get_console", return_value=recorded_console)+ mocker.patch("pipelex.cli.error_handlers.get_error_console", return_value=recorded_console)return recorded_console@@ -266,15 +266,14 @@ class TestValidateParallelMultiplicityNextStep:set_agent_cli_error_format(CliOutputFormat.JSON)assert exc_info.value.exit_code == 1- envelope = json.loads(capsys.readouterr().err)- assert envelope["is_valid"] is False- assert envelope["error_domain"] == "input"- assert envelope["error_code"] == CoreCode.METHOD_INVALID- assert envelope["hint"].startswith(_TOP_LEVEL_NEXT_STEP)- (item,) = envelope["validation_errors"]- assert item["category"] == "dry_run"- assert item["pipe_code"] == "analyze_topics"- assert item["message"] == f"Pipe 'analyze_topics' failed its dry run: {_LIST_INTO_SINGLE_SENTENCE}"+ problem = json.loads(capsys.readouterr().err)+ assert problem["is_valid"] is False+ assert problem["domain"] == "method"+ assert problem["code"] == CoreCode.METHOD_INVALID+ assert problem["next_step"]["kind"] == "change_method"+ (item,) = problem["errors"]+ assert item["location"]["pipe"] == "analyze_topics"+ assert item["detail"] == _LIST_INTO_SINGLE_SENTENCEdef test_the_verdict_problem_carries_both_next_steps(self, tmp_path: Path) -> None:"""The problem every surface draws from: the item names the fault, the top level points at the items."""diff --git a/tests/integration/pipelex/cli/test_validate_suggested_fix_integration.py b/tests/integration/pipelex/cli/test_validate_suggested_fix_integration.pyindex bb15bffbe..9ed58d8ca 100644--- a/tests/integration/pipelex/cli/test_validate_suggested_fix_integration.py+++ b/tests/integration/pipelex/cli/test_validate_suggested_fix_integration.py@@ -61,7 +61,7 @@ class TestValidateSuggestedFixIntegration:mocker.patch(f"{VALIDATE_CORE_MODULE}.get_telemetry_manager", return_value=mocker.MagicMock())mocker.patch(f"{VALIDATE_CORE_MODULE}.tag")recorded_console = Console(width=500, record=True, color_system=None)- mocker.patch("pipelex.cli.error_handlers.get_console", return_value=recorded_console)+ mocker.patch("pipelex.cli.error_handlers.get_error_console", return_value=recorded_console)bundle_path = tmp_path / "bundle.mthds"bundle_path.write_text(_FIXABLE_SEQUENCE_MTHDS, encoding="utf-8")diff --git a/tests/integration/pipelex/pipes/operator/pipe_doc_gen/test_pipe_doc_gen_run_bundle_trees.py b/tests/integration/pipelex/pipes/operator/pipe_doc_gen/test_pipe_doc_gen_run_bundle_trees.pyindex 23effb06d..7be8f4f1c 100644--- a/tests/integration/pipelex/pipes/operator/pipe_doc_gen/test_pipe_doc_gen_run_bundle_trees.py+++ b/tests/integration/pipelex/pipes/operator/pipe_doc_gen/test_pipe_doc_gen_run_bundle_trees.py@@ -22,7 +22,7 @@ _STEP_FIELDS = 'format = "docx"\ntemplate_file = "letter.docx"'def _run_agent_bundle(*, path: Path, pipe: str | None = None) -> dict[str, Any]:- """Run `run bundle` on `path` as a dry run with JSON errors, and return the error envelope it exits with."""+ """Run `run bundle` on `path` as a dry run with JSON errors, which exits with the problem on stderr."""try:agent_run_bundle_cmd(path=str(path),@@ -59,13 +59,12 @@ class TestPipeDocGenRunBundleTrees:_run_agent_bundle(path=bundle_path)assert exc_info.value.exit_code == 1- envelope: dict[str, Any] = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "ValidateBundleError"- assert envelope["error_code"] == CoreCode.METHOD_INVALID- assert envelope["error_domain"] == "input"+ problem: dict[str, Any] = json.loads(capsys.readouterr().err)+ assert problem["code"] == CoreCode.METHOD_INVALID+ assert problem["domain"] == "method"# The item reads the sentence of the refusal's code, which names the file the step could not read.- (item,) = envelope["validation_errors"]- assert "'letter.docx'" in item["message"]+ (item,) = problem["errors"]+ assert "'letter.docx'" in item["detail"]def test_a_folder_whose_bundles_declare_several_main_pipes_is_refused_naming_them(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]@@ -78,9 +77,9 @@ class TestPipeDocGenRunBundleTrees:with pytest.raises(typer.Exit):_run_agent_bundle(path=tmp_path)- envelope: dict[str, Any] = json.loads(capsys.readouterr().err)- assert envelope["error_domain"] == "input"- rendered = json.dumps(envelope)+ problem: dict[str, Any] = json.loads(capsys.readouterr().err)+ assert problem["domain"] == "input"+ rendered = json.dumps(problem)assert "several of its bundles declare a main_pipe" in renderedassert "'invoice.mthds' declares 'print_invoice'" in renderedassert "'other/invoice.mthds' declares 'print_invoice'" in rendereddiff --git a/tests/unit/pipelex/cli/agent_cli/commands/test_agent_init_execution.py b/tests/unit/pipelex/cli/agent_cli/commands/test_agent_init_execution.pyindex 8c2dcad71..ff0694f8c 100644--- a/tests/unit/pipelex/cli/agent_cli/commands/test_agent_init_execution.py+++ b/tests/unit/pipelex/cli/agent_cli/commands/test_agent_init_execution.py@@ -91,16 +91,31 @@ class TestAgentInitExecution:exit_code, payload = _init(config={"execution": "elsewhere"})assert exit_code != 0- assert payload["error_type"] == "ArgumentError"+ assert payload["code"] == "client.argument_invalid"+ assert payload["params"] == {"argument": "execution", "reason": "unknown execution"}assert "elsewhere" in payload["message"]assert not target_dir.exists()+ def test_a_config_file_that_cannot_be_read_is_a_file_refusal(self, target_dir: Path, tmp_path: Path) -> None:+ """A --config path naming a directory is `client.file_unreadable` with the system's reason, never the catch-all."""+ config_dir = tmp_path / "config.json"+ config_dir.mkdir()++ result = CliRunner().invoke(_app, ["--format", "json", "--config", str(config_dir)])++ assert result.exit_code != 0+ payload = json.loads(result.stderr)+ assert payload["code"] == "client.file_unreadable"+ assert payload["params"] == {"path": str(config_dir), "reason": "is a directory"}+ assert not target_dir.exists()+@pytest.mark.parametrize("config", [{"execution": "hosted", "backends": ["openai"]}, {"execution": "hosted", "primary_backend": "openai"}])def test_hosted_refuses_the_backend_keys(self, target_dir: Path, config: dict[str, Any]) -> None:exit_code, payload = _init(config=config)assert exit_code != 0- assert payload["error_type"] == "ArgumentError"+ assert payload["code"] == "client.argument_invalid"+ assert payload["params"]["argument"] in {"backends", "primary_backend"}assert not target_dir.exists()def test_a_global_init_names_a_project_that_overrides_it(self, target_dir: Path, mocker: MockerFixture, tmp_path: Path) -> None:diff --git a/tests/unit/pipelex/cli/agent_cli/commands/test_agent_init_routing.py b/tests/unit/pipelex/cli/agent_cli/commands/test_agent_init_routing.pyindex e588d1128..2e1f5b3be 100644--- a/tests/unit/pipelex/cli/agent_cli/commands/test_agent_init_routing.py+++ b/tests/unit/pipelex/cli/agent_cli/commands/test_agent_init_routing.py@@ -4,13 +4,18 @@ The template enables many backends and routes among them with its own profile, smust keep that profile rather than demand a primary backend nobody was asked for."""+import jsonimport shutilfrom pathlib import Pathimport pytestimport typer-from pipelex.cli.agent_cli.commands.init_cmd import _configure_routing # pyright: ignore[reportPrivateUsage]+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_format+from pipelex.cli.agent_cli.commands.init_cmd import (+ _configure_backends, # pyright: ignore[reportPrivateUsage]+ _configure_routing, # pyright: ignore[reportPrivateUsage]+)from pipelex.kit.paths import get_kit_configs_dirfrom pipelex.tools.misc.toml_utils import load_toml_from_path@@ -48,3 +53,30 @@ class TestAgentInitRouting:def test_several_backends_named_without_a_primary_is_refused(self, target_dir: Path) -> None:with pytest.raises(typer.Exit):_configure_routing(TEMPLATE_BACKENDS, config={"backends": TEMPLATE_BACKENDS}, target_dir=target_dir)+++class TestAgentInitMissingFiles:+ """A configuration file `init` should have written but finds missing is `pipelex.config.file_missing`, never a bug."""++ def test_a_missing_routing_profiles_file_is_a_missing_configuration_file(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ set_agent_cli_error_format(CliOutputFormat.JSON)++ with pytest.raises(typer.Exit):+ _configure_routing(TEMPLATE_BACKENDS, config={}, target_dir=tmp_path)++ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "pipelex.config.file_missing"+ assert problem["next_step"]["kind"] == "fix_configuration"+ assert "routing_profiles.toml' of the inference configuration" in problem["next_step"]["detail"]++ def test_a_missing_backends_file_is_a_missing_configuration_file(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ set_agent_cli_error_format(CliOutputFormat.JSON)+ template_backends_path = Path(str(get_kit_configs_dir())) / "inference" / "backends.toml"++ with pytest.raises(typer.Exit):+ _configure_backends(config={}, backends_toml_path=tmp_path / "backends.toml", template_backends_path=template_backends_path)++ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "pipelex.config.file_missing"+ assert problem["next_step"]["kind"] == "fix_configuration"+ assert "backends.toml' of the inference configuration" in problem["next_step"]["detail"]diff --git a/tests/unit/pipelex/cli/agent_cli/commands/test_bundle_path_resolver.py b/tests/unit/pipelex/cli/agent_cli/commands/test_bundle_path_resolver.pyindex a48d71d7f..b809a847e 100644--- a/tests/unit/pipelex/cli/agent_cli/commands/test_bundle_path_resolver.py+++ b/tests/unit/pipelex/cli/agent_cli/commands/test_bundle_path_resolver.py@@ -71,10 +71,10 @@ class TestResolveBundleTarget:resolve_bundle_target(str(tmp_path), library_dir=None)assert exc_info.value.exit_code == 2- envelope = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "EmptyMethodTreeError"- assert envelope["error_domain"] == "input"- assert envelope["message"] == f"The folder '{tmp_path}' holds no .mthds bundle."+ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "method.invalid"+ assert problem["diagnostics"]["error_class"] == "EmptyMethodTreeError"+ assert problem["message"] == f"The folder '{tmp_path}' holds no .mthds bundle."def test_a_folder_whose_tree_is_refused_raises_the_verdict_for_the_command(self, tmp_path: Path) -> None:"""A symbolic link in the tree is the invalid verdict, which each command renders as its surface does."""@@ -91,6 +91,7 @@ class TestResolveBundleTarget:resolve_bundle_target(str(tmp_path / "nope.txt"), library_dir=None)assert exc_info.value.exit_code == 2- envelope = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "ArgumentError"- assert "is not a .mthds file or directory" in envelope["message"]+ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "client.argument_invalid"+ assert problem["params"] == {"argument": str(tmp_path / "nope.txt"), "reason": "not a .mthds file or a directory"}+ assert "is not a .mthds file or directory" in problem["message"]diff --git a/tests/unit/pipelex/cli/agent_cli/commands/test_plxt_passthrough.py b/tests/unit/pipelex/cli/agent_cli/commands/test_plxt_passthrough.pyindex 298ad6947..54851b0bc 100644--- a/tests/unit/pipelex/cli/agent_cli/commands/test_plxt_passthrough.py+++ b/tests/unit/pipelex/cli/agent_cli/commands/test_plxt_passthrough.py@@ -21,12 +21,12 @@ if TYPE_CHECKING:class TestPlxtPassthrough:"""Tests for run_plxt(), fmt_cmd(), and lint_cmd() delegation to the plxt binary."""- def test_run_plxt_raises_binary_not_found_error_when_plxt_missing(+ def test_run_plxt_reports_the_missing_tool_when_plxt_missing(self,mocker: MockerFixture,capsys: pytest.CaptureFixture[str],) -> None:- """run_plxt exits with code 1 and BinaryNotFoundError when plxt is not on PATH."""+ """run_plxt exits with code 1 and the client.tool_missing problem naming plxt when plxt is not on PATH."""mocker.patch("shutil.which", return_value=None)with pytest.raises(typer.Exit) as exc_info:@@ -34,7 +34,8 @@ class TestPlxtPassthrough:assert exc_info.value.exit_code == 1parsed = json.loads(capsys.readouterr().err)- assert parsed["error_type"] == "BinaryNotFoundError"+ assert parsed["code"] == "client.tool_missing"+ assert parsed["params"] == {"tool": "plxt"}def test_error_message_references_uv_tool_install(self,diff --git a/tests/unit/pipelex/cli/agent_cli/conftest.py b/tests/unit/pipelex/cli/agent_cli/conftest.pyindex 6c1733511..a02b36ed4 100644--- a/tests/unit/pipelex/cli/agent_cli/conftest.py+++ b/tests/unit/pipelex/cli/agent_cli/conftest.py@@ -6,7 +6,7 @@ from typing import TYPE_CHECKINGimport pytest-from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_format+from pipelex.cli.agent_cli.commands.agent_output import start_agent_cli_error_formatif TYPE_CHECKING:from collections.abc import Iterator@@ -14,7 +14,7 @@ if TYPE_CHECKING:@pytest.fixture(autouse=True)def reset_agent_cli_error_format() -> Iterator[None]:- """Keep the module-level error-format ContextVar from leaking between tests."""- set_agent_cli_error_format(CliOutputFormat.JSON)+ """Keep the error-format ContextVars, the program's and the active one, from leaking between tests."""+ start_agent_cli_error_format()yield- set_agent_cli_error_format(CliOutputFormat.JSON)+ start_agent_cli_error_format()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.pyindex 7989f51d6..1de22ef5e 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,64 +1,102 @@-"""Unit tests for format-aware agent CLI error output."""-from __future__ import annotationsimport jsonimport pytestimport typer+from mthds.protocol.problem.registry import CoreCode+from pipelex.base_exceptions import PipelexErrorfrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,agent_error,- agent_error_markdown,set_agent_cli_error_format,)+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_markdownclass TestAgentErrorFormat:- """Tests for agent_error dispatch and agent_error_markdown rendering."""-def test_agent_error_defaults_to_json(self, capsys: pytest.CaptureFixture[str]) -> None:- """With no format opted in, agent_error keeps emitting JSON to stderr."""+ """With no format opted in, agent_error emits the problem as JSON on stderr."""with pytest.raises(typer.Exit):- agent_error("something went wrong", error_type="FooError")+ agent_error("something went wrong")parsed = json.loads(capsys.readouterr().err)- assert parsed["error"] is True- assert parsed["error_type"] == "FooError"+ assert parsed["code"] == "runtime.unexpected"+ assert parsed["message"] == "something went wrong"def test_agent_error_emits_markdown_when_format_is_markdown(self, capsys: pytest.CaptureFixture[str]) -> None:- """When markdown is the active error format, agent_error renders markdown to stderr."""+ """When markdown is the active error format, agent_error renders the problem as Markdown on stderr."""set_agent_cli_error_format(CliOutputFormat.MARKDOWN)with pytest.raises(typer.Exit) as exc_info:- agent_error("something went wrong", error_type="FooError")+ agent_error("something went wrong")assert exc_info.value.exit_code == 1captured = capsys.readouterr()assert captured.out == ""- assert captured.err.startswith("# Error: FooError")+ assert captured.err.startswith("## ")assert "something went wrong" in captured.err+ assert "- Code: `runtime.unexpected` (domain runtime, retry no)" in captured.errwith pytest.raises(json.JSONDecodeError):json.loads(captured.err)- def test_agent_error_markdown_renders_hint_and_details_but_omits_source(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error_markdown renders the heading, hint callout, and details — but not the source block.-- ``error_source`` (internal stack frames) is deliberately omitted from markdown — it's- noise for an LLM trying to fix a `.mthds` file. The field still appears in the JSON- envelope for programmatic consumers; that's covered by the integration test.- """- cause = ValueError("bad value")+ def test_markdown_renders_the_next_step_and_the_command_s_facts_but_no_source(self, capsys: pytest.CaptureFixture[str]) -> None:+ """The Markdown carries the next step, the code and the command's facts, never internal stack frames."""+ cause = PipeOperatorModelChoiceError(+ "model issue",+ pipe_type="PipeLLM",+ pipe_code="my_pipe",+ domain_code="my_domain",+ field_name="model",+ model_type=ModelType.LLM,+ model_choice="gpt-nope",+ )+ set_agent_cli_error_format(CliOutputFormat.MARKDOWN)with pytest.raises(typer.Exit):- agent_error_markdown(- "model issue",- error_type="PipeOperatorModelChoiceError",- cause=cause,- pipe_code="my_pipe",- )+ agent_error("model issue", cause=cause, pipe_code="my_pipe")err = capsys.readouterr().err- assert "# Error: PipeOperatorModelChoiceError" in err- assert "model issue" in err- assert "💡" in err # hint callout for a known error type- assert "**pipe_code:** my_pipe" in err- assert "## Error source" not in err+ problem_code = cause.resolve_error_code()+ assert f"- Code: `{problem_code}`" in err+ assert "**Next step** (`" in err+ assert "- **pipe_code:** my_pipe" in errassert "error_source" not in err+ assert "Traceback" not in err++ @pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])+ def test_both_formats_list_the_one_problem_s_errors(self, capsys: pytest.CaptureFixture[str], error_format: CliOutputFormat) -> None:+ """A wrapper adding a fault of its own above a verdict: both formats list the verdict's item and the wrapper's."""+ set_agent_cli_error_format(error_format)+ verdict = ValidateBundleError(message="the verdict's own fault")+ wrapper = PipelexError("several faults")+ wrapper.with_items(items=[make_problem_item(code=CoreCode.METHOD_PIPE_UNRESOLVED, params={"pipe": "summarize", "missing": "condense"})])+ wrapper.__cause__ = verdict++ with pytest.raises(typer.Exit):+ agent_error("the run was refused", cause=wrapper)++ printed = capsys.readouterr().err+ missing_pipe = "Pipe 'summarize' names the pipe 'condense', which does not exist."+ match error_format:+ case CliOutputFormat.JSON:+ problem = json.loads(printed)+ assert [item["code"] for item in problem["errors"]] == ["method.schema_violation", "method.pipe_unresolved"]+ assert problem["errors"][1]["detail"] == missing_pipe+ case CliOutputFormat.MARKDOWN:+ assert "### Errors" in printed+ 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")++ 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 printeddiff --git a/tests/unit/pipelex/cli/agent_cli/test_agent_method_ref_errors.py b/tests/unit/pipelex/cli/agent_cli/test_agent_method_ref_errors.pyindex d538b4892..72af21c36 100644--- a/tests/unit/pipelex/cli/agent_cli/test_agent_method_ref_errors.py+++ b/tests/unit/pipelex/cli/agent_cli/test_agent_method_ref_errors.py@@ -31,14 +31,14 @@ def _parse_single_json_error(stderr_text: str) -> dict[str, Any]:class TestAgentMethodRefErrors:- """A fetch failure surfaces as the structured JSON envelope, never unstructured Typer text."""+ """A fetch failure surfaces as its problem, never unstructured Typer text."""def _mock_failing_clone(self, mocker: MockerFixture, tmp_path: Path) -> None:mocker.patch("pipelex.methods.fetching.clone_default_branch", side_effect=VCSFetchError("connection refused"))mocker.patch("pipelex.cli.method_resolver.tempfile.mkdtemp", return_value=str(tmp_path / "dest"))- def test_run_method_fetch_failure_emits_json_envelope(self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:- """`run method <ref>` with a failing fetch exits 1 with a MethodFetchError JSON envelope on stderr."""+ def test_run_method_fetch_failure_reports_its_problem(self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ """`run method <ref>` with a failing fetch exits 1 with the fetch failure's problem as JSON on stderr."""self._mock_failing_clone(mocker, tmp_path)with pytest.raises(typer.Exit) as exc_info:@@ -46,14 +46,14 @@ class TestAgentMethodRefErrors:assert exc_info.value.exit_code == 1error_obj = _parse_single_json_error(capsys.readouterr().err)- assert error_obj["error"] is True- assert error_obj["error_type"] == "MethodFetchError"+ assert error_obj["code"] == "method.fetch_failed"+ assert error_obj["diagnostics"]["error_class"] == "MethodFetchError"assert "connection refused" in error_obj["message"]- def test_validate_method_fetch_failure_emits_json_envelope(+ def test_validate_method_fetch_failure_reports_its_problem(self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:- """`validate method <ref>` with a failing fetch is a no-verdict condition: exit 2, structured envelope."""+ """`validate method <ref>` with a failing fetch is a no-verdict condition: exit 2, its problem."""self._mock_failing_clone(mocker, tmp_path)with pytest.raises(typer.Exit) as exc_info:@@ -61,12 +61,12 @@ class TestAgentMethodRefErrors:assert exc_info.value.exit_code == 2error_obj = _parse_single_json_error(capsys.readouterr().err)- assert error_obj["error"] is True- assert error_obj["error_type"] == "MethodFetchError"+ assert error_obj["code"] == "method.fetch_failed"+ assert error_obj["diagnostics"]["error_class"] == "MethodFetchError"assert "connection refused" in error_obj["message"]- def test_inputs_method_fetch_failure_emits_json_envelope(self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:- """`inputs method <ref>` with a failing fetch exits 1 with the structured envelope (JSON is its error default)."""+ def test_inputs_method_fetch_failure_reports_its_problem(self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ """`inputs method <ref>` with a failing fetch exits 1 with its problem (JSON is its error default)."""set_agent_cli_error_format(CliOutputFormat.JSON)self._mock_failing_clone(mocker, tmp_path)@@ -75,6 +75,6 @@ class TestAgentMethodRefErrors:assert exc_info.value.exit_code == 1error_obj = _parse_single_json_error(capsys.readouterr().err)- assert error_obj["error"] is True- assert error_obj["error_type"] == "MethodFetchError"+ assert error_obj["code"] == "method.fetch_failed"+ assert error_obj["diagnostics"]["error_class"] == "MethodFetchError"assert "connection refused" in error_obj["message"]diff --git a/tests/unit/pipelex/cli/agent_cli/test_error_format_independent.py b/tests/unit/pipelex/cli/agent_cli/test_error_format_independent.pyindex f426555f7..c665bd706 100644--- a/tests/unit/pipelex/cli/agent_cli/test_error_format_independent.py+++ b/tests/unit/pipelex/cli/agent_cli/test_error_format_independent.py@@ -80,16 +80,15 @@ class TestErrorFormatIndependent:expected_error_is_markdown: bool,) -> None:"""Error output follows --error-format (or --format when --error-format is omitted)."""- # Passing a pipe_code that ends in .mthds triggers the ArgumentError branch in run_pipe_cmd.+ # Passing a pipe_code that ends in .mthds triggers the argument refusal in run_pipe_cmd.with pytest.raises(typer.Exit):run_pipe_cmd(pipe_code="my_pipe.mthds", output_format=output_format, error_format=error_format)err = capsys.readouterr().errif expected_error_is_markdown:- assert err.startswith("# Error: ArgumentError")+ assert err.startswith("## An argument was refused before sending")with pytest.raises(json.JSONDecodeError):json.loads(err)else:parsed = json.loads(err)- assert parsed["error"] is True- assert parsed["error_type"] == "ArgumentError"+ assert parsed["code"] == "client.argument_invalid"diff --git a/tests/unit/pipelex/cli/agent_cli/test_fix_format.py b/tests/unit/pipelex/cli/agent_cli/test_fix_format.pyindex bdba700e7..f8102a365 100644--- a/tests/unit/pipelex/cli/agent_cli/test_fix_format.py+++ b/tests/unit/pipelex/cli/agent_cli/test_fix_format.py@@ -7,13 +7,16 @@ from typing import TYPE_CHECKINGimport pytestimport typer+from mthds.protocol.problem.registry import CoreCodefrom pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItemfrom pipelex.cli.agent_cli.commands.agent_output import CliOutputFormatfrom pipelex.cli.agent_cli.commands.fix.bundle_cmd import fix_bundle_cmdfrom pipelex.pipeline.fixes.fix_loop import FixBundleResult-from pipelex.suggested_fix import FixSafety, SuggestedFix+from pipelex.pipeline.validation_errors import ValidationItemCode+from pipelex.suggested_fix import FixSafety, SetKeyOp, SuggestedFixfrom pipelex.validation_error_types import PipeValidationErrorType+from tests.helpers.fix_results import fix_resultif TYPE_CHECKING:from pathlib import Path@@ -30,7 +33,7 @@ def _applied_fix(source: str) -> SuggestedFix:description="Set output of pipe 'list_ideas' to 'Idea[]'",safety=FixSafety.SAFE,source=source,- ops=[],+ ops=[SetKeyOp(table_path=["pipe", "list_ideas"], key="output", value="Idea[]")],)@@ -153,7 +156,7 @@ class TestFixFormat:def test_still_invalid_emits_json_error(self, tmp_path: Path, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:bundle_path = tmp_path / "bundle.mthds"bundle_path.write_text('domain = "fix_format"\n', encoding="utf-8")- result = FixBundleResult(+ result = fix_result(is_valid=False,iterations=1,fixes_applied=[_applied_fix(str(bundle_path))],@@ -168,17 +171,46 @@ class TestFixFormat:assert exc_info.value.exit_code == 1parsed = json.loads(capsys.readouterr().err)- assert parsed["error"] is True- assert parsed["error_type"] == "FixBundleError"+ assert parsed["code"] == "method.invalid"assert parsed["is_valid"] is Falseassert parsed["bail_reason"] == "no safe fixes remain"- assert parsed["remaining_errors"][0]["source"] == str(bundle_path)+ assert parsed["bundle_path"] == str(bundle_path.resolve())+ assert [fix["fix_code"] for fix in parsed["fixes_applied"]] == ["match-sequence-output"]+ # The remaining errors are the problem's own faults, located in their file.+ assert "remaining_errors" not in parsed+ assert [item["location"]["file"] for item in parsed["errors"]] == [str(bundle_path)]+ assert "error_type" not in parsed++ def test_still_invalid_items_keep_the_codes_the_verdict_gave_them(+ self, tmp_path: Path, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]+ ) -> None:+ """A remaining error no stage classified takes the code the loop's last verdict gave it, as `validate` reports it."""+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text('domain = "fix_format"\n', encoding="utf-8")+ unparsed = ValidationErrorItem(category=ValidationErrorCategory.BLUEPRINT_VALIDATION, message="Expected a value", source=str(bundle_path))+ result = fix_result(+ is_valid=False,+ iterations=0,+ fixes_applied=[],+ remaining_errors=[unparsed],+ remaining_error_codes=[ValidationItemCode(code=CoreCode.METHOD_SYNTAX, params={"finding": "Expected a value"})],+ )+ _patch_command(mocker, result=result)++ with pytest.raises(typer.Exit):+ fix_bundle_cmd(path=str(bundle_path), output_format=CliOutputFormat.JSON)++ parsed = json.loads(capsys.readouterr().err)+ (item,) = parsed["errors"]+ assert item["code"] == "method.syntax"+ assert item["params"] == {"finding": "Expected a value"}+ assert "remaining_error_codes" not in parseddef test_still_invalid_markdown_renders_prose(self, tmp_path: Path, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:"""Default (markdown) still-invalid renders the remaining errors as prose on stderr, not a JSON dump."""bundle_path = tmp_path / "bundle.mthds"bundle_path.write_text('domain = "fix_format"\n', encoding="utf-8")- result = FixBundleResult(+ result = fix_result(is_valid=False,iterations=1,fixes_applied=[_applied_fix(str(bundle_path))],@@ -194,10 +226,13 @@ class TestFixFormat:assert exc_info.value.exit_code == 1captured = capsys.readouterr()assert captured.out == ""- assert captured.err.startswith("# Fix incomplete - bundle still invalid")- assert "## Applied Fixes" in captured.err- assert "**Stopped:** no safe fixes remain" in captured.err+ assert captured.err.startswith("## The method does not validate")+ assert "Fix loop stopped after 1 iteration(s)" in captured.errassert "## Pipe validation errors" 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+ assert "fixes_applied" not in captured.errwith pytest.raises(json.JSONDecodeError):json.loads(captured.err)@@ -212,7 +247,8 @@ class TestFixFormat:assert exc_info.value.exit_code == 2parsed = json.loads(capsys.readouterr().err)- assert parsed["error_type"] == "ArgumentError"+ assert parsed["code"] == "client.argument_invalid"+ assert parsed["params"] == {"argument": "--ignore", "reason": "contradicts --select"}assert "mutually exclusive" in parsed["message"]def test_unknown_fix_code_is_rejected(self, capsys: pytest.CaptureFixture[str]) -> None:@@ -221,6 +257,7 @@ class TestFixFormat:assert exc_info.value.exit_code == 2parsed = json.loads(capsys.readouterr().err)- assert parsed["error_type"] == "ArgumentError"+ assert parsed["code"] == "client.argument_invalid"+ assert parsed["params"] == {"argument": "typo-rule", "reason": "unknown fix rule code"}assert parsed["unknown_fix_codes"] == ["typo-rule"]assert "match-sequence-output" in parsed["known_fix_codes"]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.pyindex 85cc82fb2..a5e1df6fe 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@@ -9,7 +9,6 @@ import pytestimport typerfrom pipelex.base_exceptions import PipelexConfigError-from pipelex.cli.agent_cli.commands.agent_cli_factory import AGENT_INIT_FAILURE_HINTfrom pipelex.cli.agent_cli.commands.agent_output import CliOutputFormatfrom pipelex.cli.agent_cli.commands.fix.bundle_cmd import fix_bundle_cmdfrom pipelex.cli.agent_cli.commands.inputs.bundle_cmd import inputs_bundle_cmd@@ -193,10 +192,10 @@ class TestAgentFolderEntryCommands:assert mock_fix.call_args.kwargs["method_dir"] == tmp_pathassert mock_fix.call_args.kwargs["library_dirs"] == [tmp_path]- def test_fix_reports_a_folder_whose_tree_is_refused_in_the_fix_envelope(+ def test_fix_reports_a_folder_whose_tree_is_refused_as_the_still_invalid_problem(self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:- """The documented FixBundleError envelope, as a fix that could not be made, never a bare refusal."""+ """The still-invalid problem of a fix that could not be made, `method.invalid` with the fix result beside it, never a bare refusal."""mock_fix = _patch_fix(mocker)_write_folder_with_a_refused_tree(directory=tmp_path)@@ -204,22 +203,26 @@ class TestAgentFolderEntryCommands:fix_bundle_cmd(path=str(tmp_path), error_format=CliOutputFormat.JSON)assert exc_info.value.exit_code == 1- envelope = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "FixBundleError"- assert envelope["is_valid"] is False- assert envelope["bundle_path"] == str(tmp_path.resolve())- assert envelope["iterations"] == 0- assert envelope["fixes_applied"] == []- assert envelope["files_written"] == []- assert envelope["remaining_errors"]- assert any("linked.mthds" in item["message"] for item in envelope["remaining_errors"])+ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "method.invalid"+ assert problem["is_valid"] is False+ assert problem["bundle_path"] == str(tmp_path.resolve())+ assert problem["iterations"] == 0+ assert problem["fixes_applied"] == []+ assert problem["files_written"] == []+ assert [item["code"] for item in problem["errors"]] == ["method.package_invalid"]++ # The Markdown renders the remaining errors as prose, the refusal 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().errmock_fix.assert_not_called()@pytest.mark.parametrize("command", ["validate", "fix", "inputs", "run"])- def test_a_configuration_that_does_not_validate_before_the_boot_is_the_failed_boot_envelope(+ def test_a_configuration_that_does_not_validate_before_the_boot_is_the_failed_boot_problem(self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str], command: str) -> None:- """Listing the tree reads its limits from the configuration: a refusal there is the envelope a failed boot gives."""+ """Listing the tree reads its limits from the configuration: a refusal there is the problem a failed boot gives."""mocker.patch("pipelex.libraries.method_trees.local_tree_limits", side_effect=PipelexConfigError("the configuration is out of date"))write_method_folder(directory=tmp_path, shape=MethodFolderShape.ONE_DECLARED_MAIN_PIPE)@@ -227,10 +230,10 @@ class TestAgentFolderEntryCommands:_invoke_pre_boot_command(command=command, path=tmp_path)assert exc_info.value.exit_code == 1- envelope = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "PipelexConfigError"- assert envelope["message"] == "Pipelex initialization failed: the configuration is out of date"- assert envelope["hint"] == AGENT_INIT_FAILURE_HINT+ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "pipelex.config.invalid"+ assert problem["diagnostics"]["error_class"] == "PipelexConfigError"+ assert problem["message"] == "the configuration is out of date"@pytest.mark.parametrize("command", ["validate", "fix"])def test_validate_and_fix_refuse_a_folder_holding_no_bundle_with_no_verdict(@@ -243,9 +246,10 @@ class TestAgentFolderEntryCommands:_invoke_validate_or_fix_for_json(command=command, path=tmp_path)assert exc_info.value.exit_code == 2- envelope = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "EmptyMethodTreeError"- assert envelope["message"] == f"The folder '{tmp_path}' holds no .mthds bundle."+ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "method.invalid"+ assert problem["diagnostics"]["error_class"] == "EmptyMethodTreeError"+ assert problem["message"] == f"The folder '{tmp_path}' holds no .mthds bundle."mocks.folder.assert_not_called()mock_fix.assert_not_called()@@ -285,7 +289,8 @@ class TestAgentFolderEntryCommands:inputs_bundle_cmd(path=str(tmp_path))assert exc_info.value.exit_code == 1- envelope = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "MethodEntryError"- assert envelope["message"] == _run_refusal(directory=tmp_path)+ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "request.pipe_unspecified"+ assert problem["diagnostics"]["error_class"] == "MethodEntryError"+ assert problem["message"] == _run_refusal(directory=tmp_path)mock_inputs.assert_not_called()diff --git a/tests/unit/pipelex/cli/agent_cli/test_inputs_format_unaffected.py b/tests/unit/pipelex/cli/agent_cli/test_inputs_format_unaffected.pyindex 2e68790d4..b5958b072 100644--- a/tests/unit/pipelex/cli/agent_cli/test_inputs_format_unaffected.py+++ b/tests/unit/pipelex/cli/agent_cli/test_inputs_format_unaffected.py@@ -1,9 +1,12 @@-"""Regression test: the `inputs` commands' --format is the template serialization (json|toml), not the markdown|json pair."""-from __future__ import annotationsimport inspect+import json++import pytest+import typer+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, start_agent_cli_error_formatfrom pipelex.cli.agent_cli.commands.inputs.bundle_cmd import inputs_bundle_cmdfrom pipelex.cli.agent_cli.commands.inputs.method_cmd import inputs_method_cmdfrom pipelex.cli.agent_cli.commands.inputs.pipe_cmd import inputs_pipe_cmd@@ -11,19 +14,46 @@ from pipelex.pipe_machinery.rendering.input_renderer import InputsTemplateFormatclass TestInputsFormatUnaffected:- """The `inputs` commands never gain the markdown|json presentation pair.-- Their `--format` is an InputsTemplateFormat (json|toml) selecting the template- serialization — a deliberate deviation documented in the agent CLI CLAUDE.md.- Errors stay on the ContextVar's JSON default: no --error-format.- """+ def test_inputs_commands_have_template_format_and_their_own_error_format(self) -> None:+ """Each inputs subcommand's --format is the template's (json|toml), never the markdown|json pair, and it takes --error-format.- def test_inputs_commands_have_template_format_not_presentation_format(self) -> None:- """Each inputs subcommand declares template_format (InputsTemplateFormat) and no output_format/error_format."""+ Its errors fall back on JSON, the template's default, unless --error-format, its own or the program's, says markdown.+ """for command in (inputs_pipe_cmd, inputs_bundle_cmd, inputs_method_cmd):parameters = inspect.signature(command).parametersassert "output_format" not in parameters, f"{command.__name__} unexpectedly gained an output_format parameter"- assert "error_format" not in parameters, f"{command.__name__} unexpectedly gained an error_format parameter"template_format_param = parameters.get("template_format")assert template_format_param is not None, f"{command.__name__} lost its template_format parameter"assert template_format_param.default == InputsTemplateFormat.JSON, f"{command.__name__} must default to the JSON envelope"+ error_format_param = parameters.get("error_format")+ assert error_format_param is not None, f"{command.__name__} lost its error_format parameter"+ assert error_format_param.default is None, f"{command.__name__} must inherit the program's error format"++ @pytest.mark.parametrize(+ ("root_error_format", "command_error_format", "is_markdown"),+ [+ (None, None, False),+ (CliOutputFormat.MARKDOWN, None, True),+ (None, CliOutputFormat.MARKDOWN, True),+ (CliOutputFormat.MARKDOWN, CliOutputFormat.JSON, False),+ ],+ )+ def test_an_inputs_refusal_follows_the_error_format(+ self,+ capsys: pytest.CaptureFixture[str],+ root_error_format: CliOutputFormat | None,+ command_error_format: CliOutputFormat | None,+ is_markdown: bool,+ ) -> None:+ start_agent_cli_error_format(root_error_format=root_error_format)+ with pytest.raises(typer.Exit) as exc_info:+ inputs_pipe_cmd(pipe_code="my_pipe.mthds", error_format=command_error_format)+ assert exc_info.value.exit_code == 1++ err = capsys.readouterr().err+ if is_markdown:+ assert err.startswith("## An argument was refused before sending")+ else:+ parsed = json.loads(err)+ assert parsed["code"] == "client.argument_invalid"+ assert parsed["params"] == {"argument": "my_pipe.mthds", "reason": "a path where a pipe code is expected"}diff --git a/tests/unit/pipelex/cli/agent_cli/test_run_bundle_auto_inputs.py b/tests/unit/pipelex/cli/agent_cli/test_run_bundle_auto_inputs.pyindex c5825586b..eb9e666de 100644--- a/tests/unit/pipelex/cli/agent_cli/test_run_bundle_auto_inputs.py+++ b/tests/unit/pipelex/cli/agent_cli/test_run_bundle_auto_inputs.py@@ -57,7 +57,7 @@ class TestAgentRunBundleAutoInputs:@pytest.mark.usefixtures("tty_stdin")def test_both_inputs_files_error_envelope(self, mocker: MockerFixture, bundle_dir: Path, capsys: pytest.CaptureFixture[str]) -> None:- """With both default inputs files present, the command emits the ambiguity envelope and exits."""+ """With both default inputs files present, the command reports the ambiguity's problem and exits."""set_agent_cli_error_format(CliOutputFormat.JSON)run_core_mock = self._patch_run(mocker, {"answer": "42"})(bundle_dir / "inputs.json").write_text('{"topic": "cats"}', encoding="utf-8")@@ -67,10 +67,11 @@ class TestAgentRunBundleAutoInputs:run_bundle_cmd(path=str(bundle_dir), pipe="my_pipe", output_format=CliOutputFormat.JSON)assert exc_info.value.exit_code == 1- envelope = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "AmbiguousInputsFilesError"- assert envelope["error_domain"] == "input"- assert "--inputs" in envelope["hint"]+ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "request.invalid"+ assert problem["domain"] == "input"+ assert problem["diagnostics"]["error_class"] == "AmbiguousInputsFilesError"+ assert "Pass --inputs explicitly" in problem["message"]run_core_mock.assert_not_called()def test_piped_stdin_preempts_ambiguous_auto_detect(@@ -107,10 +108,27 @@ class TestAgentRunBundleAutoInputs:capsys.readouterr()assert run_core_mock.call_args.kwargs["inputs"] == {"topic": "toml"}+ @pytest.mark.usefixtures("tty_stdin")+ def test_a_bundle_that_is_not_text_does_not_parse(self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ """A bundle file that is not UTF-8 text is the invalid verdict `validate` gives it, its item `method.syntax`, never a file refusal."""+ set_agent_cli_error_format(CliOutputFormat.JSON)+ self._patch_run(mocker, {"answer": "42"})+ bundle_file = tmp_path / "bundle.mthds"+ bundle_file.write_bytes(b"\xff\xfe domain = 'x'\n")++ with pytest.raises(typer.Exit):+ run_bundle_cmd(path=str(bundle_file), output_format=CliOutputFormat.JSON)++ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "method.invalid"+ (item,) = problem["errors"]+ assert item["code"] == "method.syntax"+ assert item["location"] == {"file": str(bundle_file), "line": 1, "column": 1}+@_NO_SYMLINKS_ON_WINDOWS@pytest.mark.usefixtures("tty_stdin")def test_an_auto_detected_link_is_refused(self, mocker: MockerFixture, bundle_dir: Path, capsys: pytest.CaptureFixture[str]) -> None:- """A link named inputs.json is never followed: the command emits the refusal envelope pointing to --inputs and runs nothing."""+ """A link named inputs.json is never followed: the command emits the refusal problem pointing to --inputs and runs nothing."""set_agent_cli_error_format(CliOutputFormat.JSON)run_core_mock = self._patch_run(mocker, {"answer": "42"})outside = bundle_dir.parent / f"{bundle_dir.name}-outside.json"@@ -124,12 +142,13 @@ class TestAgentRunBundleAutoInputs:run_bundle_cmd(path=str(bundle_dir), pipe="my_pipe", output_format=CliOutputFormat.JSON)assert exc_info.value.exit_code == 1- envelope = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "AutoDetectedInputsFileError"- assert envelope["error_domain"] == "input"- assert "symbolic link" in envelope["message"]- assert "--inputs" in envelope["hint"]- assert "outside-sentinel" not in json.dumps(envelope)+ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "request.invalid"+ assert problem["domain"] == "input"+ assert problem["diagnostics"]["error_class"] == "AutoDetectedInputsFileError"+ assert "symbolic link" in problem["message"]+ assert "--inputs <path>" in problem["message"]+ assert "outside-sentinel" not in json.dumps(problem)run_core_mock.assert_not_called()@_NO_SYMLINKS_ON_WINDOWSdiff --git a/tests/unit/pipelex/cli/agent_cli/test_run_hosted_envelope.py b/tests/unit/pipelex/cli/agent_cli/test_run_hosted_envelope.pyindex a721371e8..5a9b53021 100644--- a/tests/unit/pipelex/cli/agent_cli/test_run_hosted_envelope.py+++ b/tests/unit/pipelex/cli/agent_cli/test_run_hosted_envelope.py@@ -12,6 +12,7 @@ from typing import TYPE_CHECKING, Anyimport pytestimport typer+from mthds.protocol.problem.registry import CoreCodefrom pipelex_sdk.error_models import RunErrorReportfrom pipelex_sdk.errors import MissingMainStuffError, RunFailedError, RunTimeoutErrorfrom pipelex_sdk.runs import RunResults, RunStatus@@ -20,10 +21,10 @@ from pipelex_sdk.validation_models import ValidationErrorItemfrom pydantic import ValidationErrorfrom pipelex.base_exceptions import PipelexConfigError-from pipelex.cli.agent_cli.commands.agent_cli_factory import AGENT_INIT_FAILURE_HINTfrom pipelex.cli.agent_cli.commands.agent_output import CliOutputFormatfrom pipelex.cli.agent_cli.commands.run.bundle_cmd import run_bundle_cmdfrom pipelex.cli.agent_cli.commands.run.method_cmd import run_method_cmd+from pipelex.errors.problem import ProblemView, make_problemfrom pipelex.hosted.client_factory import PIPELEX_API_KEY_ENV_KEY, PIPELEX_BASE_URL_ENV_KEYfrom pipelex.hosted.exceptions import HostedMethodInvalidError, HostedRunPollingErrorfrom pipelex.hosted.hosted_run import HostedRunOutcome, HostedRunRequest@@ -149,6 +150,8 @@ class TestRunHostedEnvelope:envelope = json.loads(capsys.readouterr().err)assert envelope["error"] is Trueassert 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.detaildef test_a_hosted_verdict_that_the_failure_is_not_retryable_wins_over_the_local_table(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]@@ -232,16 +235,20 @@ class TestRunHostedEnvelope:assert envelope["validation_errors"][0]["source"] == "lib/b.mthds"assert envelope["validation_errors"][0]["message"] == "unknown concept Foo"- def test_a_configuration_that_cannot_be_read_gives_the_boot_hint(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:- """Reading `[run] execution` meets the configuration a local boot meets, and says what a local boot says."""- mocker.patch(f"{EXECUTION_MODULE}.configured_run_execution", side_effect=PipelexConfigError("pipelex.toml is invalid"))+ 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."""+ config_error = PipelexConfigError("pipelex.toml is invalid")+ mocker.patch(f"{EXECUTION_MODULE}.configured_run_execution", side_effect=config_error)with pytest.raises(typer.Exit):run_method_cmd(name=METHOD_REF, output_format=CliOutputFormat.JSON)- envelope = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "PipelexConfigError"- assert envelope["hint"] == AGENT_INIT_FAILURE_HINT+ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "pipelex.config.invalid"+ assert problem["domain"] == "operator"+ assert problem["next_step"] == config_error.to_problem(view=ProblemView.OPERATOR).next_step.model_dump(mode="json", exclude_none=True)+ assert problem["diagnostics"]["error_class"] == "PipelexConfigError"+ assert "error_type" not in problemdef test_a_bundle_file_without_a_library_sends_pipelexpath(self, monkeypatch: pytest.MonkeyPatch, run_hosted: AsyncMock, tmp_path: Path, capsys: pytest.CaptureFixture[str]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.pyindex 8ee07d69b..8e508abe3 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@@ -34,6 +34,7 @@ from pipelex.hosted.error_rendering import (HOSTED_SERVER_FAULT_NEXT_STEP,)from pipelex.hosted.run_config import RunExecution+from pipelex.system.usage_stats.usage_stats_contract import UsageStatsError, UsageStatsErrorDomainfrom tests.unit.pipelex.cli.agent_cli.test_data import RefusalCase, RefusalCases, RefusedRunBodiesfrom tests.unit.pipelex.hosted.test_data import HostedVersions@@ -448,3 +449,32 @@ class TestRunHostedRefusal:assert unprocessable["hint"] == HOSTED_REFUSAL_CALLER_NEXT_STEPfor payload in (not_found, unprocessable):assert "retryable" not in payload++ @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),+ ),+ ],+ )+ def test_the_statistics_record_what_the_hosted_api_sent(+ self, mocker: MockerFixture, status: int, body: str, expected: tuple[str, UsageStatsErrorDomain] | None+ ) -> None:+ """The command's statistics say what the envelope says: the code and domain the hosted API sent, never the SDK's inference."""+ 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))++ if expected is None:+ noted.assert_not_called()+ else:+ noted.assert_called_once_with(error=UsageStatsError(code=expected[0], domain=expected[1]))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.pyindex 74a477e4b..3f9480050 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@@ -1,9 +1,3 @@-"""Unit tests for the agent-CLI bundle-validation failure surface (``agent_error_validate_bundle``).--Markdown renders the structured items as prose with a fix-aware footer; JSON keeps the exact-structured envelope (``is_valid`` / ``bundle_path`` / ``validation_errors`` + the unchanged hint).-"""-from __future__ import annotationsimport json@@ -15,18 +9,18 @@ import typerfrom pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItemfrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,- _render_validate_bundle_markdown, # pyright: ignore[reportPrivateUsage]agent_error_validate_bundle,set_agent_cli_error_format,)from pipelex.pipeline.exceptions import ValidateBundleError-from pipelex.suggested_fix import FixSafety, SuggestedFix+from pipelex.suggested_fix import FixSafety, SetKeyOp, SuggestedFixfrom pipelex.validation_error_types import PipeValidationErrorTypeif TYPE_CHECKING:- from collections.abc import Iteratorfrom pathlib import Path+ from pytest_mock import MockerFixture+def _fixable_item(*, source: Path) -> ValidationErrorItem:return ValidationErrorItem(@@ -41,7 +35,7 @@ def _fixable_item(*, source: Path) -> ValidationErrorItem:description="Set output of pipe 'brainstorm' to 'StoryIdea[]' to match its last step",safety=FixSafety.SAFE,source=str(source),- ops=[],+ ops=[SetKeyOp(table_path=["pipe", "brainstorm"], key="output", value="StoryIdea[]")],),)@@ -60,45 +54,58 @@ def _unsafe_fixable_item(*, source: Path) -> ValidationErrorItem:description="Replace model '@best-sonet' of pipe 'write_tide_note' with '@best-gpt', its one close match in the model deck",safety=FixSafety.UNSAFE,source=str(source),- ops=[],+ ops=[SetKeyOp(table_path=["pipe", "write_tide_note"], key="model", value="@best-gpt")],),)class TestValidateBundleErrorFormat:- @pytest.fixture(autouse=True)- def _reset_error_format(self) -> Iterator[None]:- # The error format is a process-global ContextVar; reset it after each test so a markdown- # test can't leak into a later JSON-default test (mirrors the app callback's per-invocation reset).- yield- set_agent_cli_error_format(CliOutputFormat.JSON)+ def _report_markdown(+ self,+ *,+ mocker: MockerFixture,+ capsys: pytest.CaptureFixture[str],+ items: list[ValidationErrorItem],+ bundle_path: Path,+ library_dirs: list[Path] | None,+ ) -> str:+ """The Markdown ``agent_error_validate_bundle`` prints for a verdict whose items are ``items``."""+ set_agent_cli_error_format(CliOutputFormat.MARKDOWN)+ exc = ValidateBundleError(message="the bundle does not validate")+ mocker.patch.object(exc, "validation_error_items", return_value=items)+ with pytest.raises(typer.Exit) as exc_info:+ agent_error_validate_bundle(exc, bundle_path=bundle_path, library_dirs=library_dirs)+ assert exc_info.value.exit_code == 1+ captured = capsys.readouterr()+ assert captured.out == ""+ return captured.err- def test_markdown_renders_prose_and_fix_aware_footer(self, tmp_path: Path) -> None:- """Markdown renders a heading, the bundle, prose items with the 💡 fix line, and a fix-aware footer."""+ 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."""bundle_path = tmp_path / "bundle.mthds"- markdown = _render_validate_bundle_markdown(- [_fixable_item(source=bundle_path)],- bundle_path=bundle_path,- library_dirs=[tmp_path / "libs"],- allow_signatures=False,+ markdown = self._report_markdown(+ mocker=mocker, capsys=capsys, items=[_fixable_item(source=bundle_path)], bundle_path=bundle_path, library_dirs=[tmp_path / "libs"])- assert markdown.startswith("# Bundle validation failed")- assert f"**Bundle:** `{bundle_path}`" in markdown+ assert markdown.startswith("## The method does not validate")+ assert "- Code: `method.invalid` (domain method, retry no)" in markdownassert "1. **Inadequate Output Multiplicity**" in markdownassert " - 💡 Suggested fix: Set output of pipe 'brainstorm' to 'StoryIdea[]' to match its last step" in markdown- # Disease E: the boilerplate hint is replaced by a fix-aware footer naming the exact command with -L echoed.- assert "Check the validation_errors array" not in markdown+ assert f"- **bundle_path:** {bundle_path}" in markdown+ assert "is_valid" not in markdownassert f"💡 1 of these errors can be fixed automatically — run: `pipelex-agent fix bundle {bundle_path} -L {tmp_path / 'libs'}`" in markdown+ with pytest.raises(json.JSONDecodeError):+ json.loads(markdown)- def test_markdown_says_an_unsafe_fix_needs_confirmation(self, tmp_path: Path) -> None:+ def test_markdown_says_an_unsafe_fix_needs_confirmation(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], tmp_path: Path) -> None:"""A safe fix keeps the plain 💡 line; an unsafe one says it is unsafe, and the footer counts only the safe one."""bundle_path = tmp_path / "bundle.mthds"- markdown = _render_validate_bundle_markdown(- [_fixable_item(source=bundle_path), _unsafe_fixable_item(source=bundle_path)],+ markdown = self._report_markdown(+ mocker=mocker,+ capsys=capsys,+ items=[_fixable_item(source=bundle_path), _unsafe_fixable_item(source=bundle_path)],bundle_path=bundle_path,library_dirs=None,- allow_signatures=False,)assert " - 💡 Suggested fix: Set output of pipe 'brainstorm' to 'StoryIdea[]' to match its last step" in markdown@@ -108,32 +115,17 @@ class TestValidateBundleErrorFormat:assert "💡 Suggested fix: Replace model" not in markdownassert "💡 1 of these errors can be fixed automatically" in markdown- def test_markdown_no_fix_footer_when_nothing_fixable(self, tmp_path: Path) -> None:+ def test_markdown_no_fix_footer_when_nothing_fixable(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], tmp_path: Path) -> None:"""With no suggested fix, the footer points at the messages instead of naming a fix command."""item = ValidationErrorItem(category=ValidationErrorCategory.BLUEPRINT_VALIDATION, message="something is wrong")- markdown = _render_validate_bundle_markdown([item], bundle_path=tmp_path / "b.mthds", library_dirs=None, allow_signatures=False)+ markdown = self._report_markdown(mocker=mocker, capsys=capsys, items=[item], bundle_path=tmp_path / "b.mthds", library_dirs=None)assert "no automatic fix" in markdownassert "pipelex-agent fix bundle" not in markdown- def test_markdown_dispatch_emits_prose_to_stderr(self, capsys: pytest.CaptureFixture[str], tmp_path: Path) -> None:- """In markdown mode the dispatcher prints prose (not JSON) to stderr and exits 1."""- set_agent_cli_error_format(CliOutputFormat.MARKDOWN)- exc = ValidateBundleError(message="Could not load blueprints because of: bad stuff")-- with pytest.raises(typer.Exit) as exc_info:- agent_error_validate_bundle(exc, bundle_path=tmp_path / "b.mthds")-- assert exc_info.value.exit_code == 1- captured = capsys.readouterr()- assert captured.out == ""- assert captured.err.startswith("# Bundle validation failed")- with pytest.raises(json.JSONDecodeError):- json.loads(captured.err)-- def test_json_dispatch_emits_unchanged_structured_envelope(self, capsys: pytest.CaptureFixture[str], tmp_path: Path) -> None:- """In JSON mode the dispatcher emits the byte-stable structured envelope hooks branch on."""+ def test_json_is_the_method_s_problem_with_the_verdict_beside_it(self, capsys: pytest.CaptureFixture[str], tmp_path: Path) -> None:+ """In JSON the verdict is the problem a hook branches on: its code and errors, with is_valid and the bundle beside them."""set_agent_cli_error_format(CliOutputFormat.JSON)bundle_path = tmp_path / "b.mthds"exc = ValidateBundleError(message="no details")@@ -143,13 +135,12 @@ class TestValidateBundleErrorFormat:assert exc_info.value.exit_code == 1parsed = json.loads(capsys.readouterr().err)- assert parsed["error"] is True- assert parsed["error_type"] == "ValidateBundleError"+ assert parsed["code"] == "method.invalid"+ assert parsed["domain"] == "method"+ assert parsed["next_step"]["kind"] == "change_method"assert parsed["is_valid"] is Falseassert parsed["bundle_path"] == str(bundle_path)- # The message-only residual makes the structured-info invariant total; the hint is the class-level next step.- assert parsed["validation_errors"] == [{"category": "blueprint_validation", "message": "no details"}]- assert (- parsed["hint"]- == "Edit the bundle as each validation error says: apply its suggested fix where it has one, after confirming an unsafe one"- )+ # The message-only residual makes the structured-info invariant total: one item, never an empty list.+ assert [(item["code"], item["params"]["finding"]) for item in parsed["errors"]] == [("method.schema_violation", "no details")]+ for retired in ("error", "error_type", "hint", "validation_errors"):+ assert retired not in parseddiff --git a/tests/unit/pipelex/cli/commands/fix/test_fix_bundle_human_format.py b/tests/unit/pipelex/cli/commands/fix/test_fix_bundle_human_format.pyindex 9eb2d1c4b..0c0f695ee 100644--- a/tests/unit/pipelex/cli/commands/fix/test_fix_bundle_human_format.py+++ b/tests/unit/pipelex/cli/commands/fix/test_fix_bundle_human_format.py@@ -20,6 +20,7 @@ from pipelex.cli.commands.fix.bundle_cmd import fix_bundle_cmdfrom pipelex.pipeline.fixes.fix_loop import FixBundleResultfrom pipelex.suggested_fix import FixSafety, SuggestedFixfrom pipelex.validation_error_types import PipeValidationErrorType+from tests.helpers.fix_results import fix_resultif TYPE_CHECKING:from pathlib import Path@@ -194,7 +195,7 @@ class TestFixBundleHumanFormat:console: Console,) -> None:bundle_path = self._bundle_file(tmp_path)- result = FixBundleResult(+ result = fix_result(is_valid=False,iterations=2,fixes_applied=[_applied_fix(str(bundle_path))],@@ -227,7 +228,7 @@ class TestFixBundleHumanFormat:) -> None:"""A remaining error still showing a 💡 suggested fix (skipped/out-of-scope) must not be told it has 'no deterministic safe fix'."""bundle_path = self._bundle_file(tmp_path)- result = FixBundleResult(+ result = fix_result(is_valid=False,iterations=0,fixes_applied=[],@@ -304,7 +305,7 @@ class TestFixBundleHumanFormat:source=str(sandbox_path),field_path="pipe → output",)- result = FixBundleResult(+ result = fix_result(is_valid=False,iterations=0,fixes_applied=[],diff --git a/tests/unit/pipelex/cli/commands/run/test_run_hosted_cli.py b/tests/unit/pipelex/cli/commands/run/test_run_hosted_cli.pyindex 876317eb9..1fca53697 100644--- a/tests/unit/pipelex/cli/commands/run/test_run_hosted_cli.py+++ b/tests/unit/pipelex/cli/commands/run/test_run_hosted_cli.py@@ -347,16 +347,20 @@ class TestRunHostedCli:def test_a_hosted_failure_prints_its_items_and_its_run(self, mocker: MockerFixture, bundle_dir: Path, error: Exception, expected_lines: list[str]) -> None:+ """The failure's report goes to stderr, the run's output stream holding none of it."""output = io.StringIO()+ failure_output = io.StringIO()mocker.patch(f"{RUN_HOSTED_MODULE}.get_console", return_value=Console(file=output, width=250))+ mocker.patch(f"{RUN_HOSTED_MODULE}.get_error_console", return_value=Console(file=failure_output, width=250))mocker.patch(f"{RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=error))with pytest.raises(typer.Exit):run_bundle_cmd(path=str(bundle_dir), hosted=True)- printed = output.getvalue()+ printed = failure_output.getvalue()for expected_line in expected_lines:assert expected_line in printed+ assert expected_line not in output.getvalue()def test_an_acknowledged_start_is_announced_with_its_run_id(self, mocker: MockerFixture, bundle_dir: Path, tmp_path: Path) -> None:output = io.StringIO()@@ -379,7 +383,9 @@ class TestRunHostedCli:) -> None:"""Ctrl-C stops the wait, not the run: the run id is what finds it again."""output = io.StringIO()+ failure_output = io.StringIO()mocker.patch(f"{RUN_HOSTED_MODULE}.get_console", return_value=Console(file=output, width=250))+ mocker.patch(f"{RUN_HOSTED_MODULE}.get_error_console", return_value=Console(file=failure_output, width=250))def _started_then_interrupted(**kwargs: Any) -> HostedRunOutcome:kwargs["on_started"](pipeline_run_id="run_77")@@ -391,21 +397,23 @@ class TestRunHostedCli:run_bundle_cmd(path=str(bundle_dir), hosted=True)assert exc_info.value.exit_code == 130- printed = output.getvalue()+ assert "Run run_77 started on the hosted API" in output.getvalue()+ printed = failure_output.getvalue()assert "Run id: run_77" in printedassert "keeps going on the hosted API" in printedassert "Traceback" not in printeddef test_an_interruption_before_the_acknowledgement_points_at_the_run_history(self, mocker: MockerFixture, bundle_dir: Path) -> None:- output = io.StringIO()- mocker.patch(f"{RUN_HOSTED_MODULE}.get_console", return_value=Console(file=output, width=250))+ failure_output = io.StringIO()+ mocker.patch(f"{RUN_HOSTED_MODULE}.get_console", return_value=Console(file=io.StringIO(), width=250))+ mocker.patch(f"{RUN_HOSTED_MODULE}.get_error_console", return_value=Console(file=failure_output, width=250))mocker.patch(f"{RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=KeyboardInterrupt()))with pytest.raises(typer.Exit) as exc_info:run_bundle_cmd(path=str(bundle_dir), hosted=True)assert exc_info.value.exit_code == 130- printed = output.getvalue()+ printed = failure_output.getvalue()assert "run history" in printedassert "Run id:" not in printeddiff --git a/tests/unit/pipelex/cli/commands/test_folder_entry_commands.py b/tests/unit/pipelex/cli/commands/test_folder_entry_commands.pyindex d8725de97..2771b6c9e 100644--- a/tests/unit/pipelex/cli/commands/test_folder_entry_commands.py+++ b/tests/unit/pipelex/cli/commands/test_folder_entry_commands.py@@ -122,7 +122,7 @@ class TestHumanFolderEntryCommands:def test_validate_names_the_folder_whose_tree_is_refused_in_its_invalid_verdict(self, mocker: MockerFixture, tmp_path: Path) -> None:recorded_console = Console(width=500, record=True, color_system=None)- mocker.patch("pipelex.cli.error_handlers.get_console", return_value=recorded_console)+ mocker.patch("pipelex.cli.error_handlers.get_error_console", return_value=recorded_console)mock_execute = mocker.patch("pipelex.cli.commands.validate.bundle_cmd.execute_validate")_write_folder_with_a_refused_tree(directory=tmp_path)@@ -140,7 +140,7 @@ class TestHumanFolderEntryCommands:def test_fix_reports_a_folder_whose_tree_is_refused_as_a_fix_that_fails(self, mocker: MockerFixture, tmp_path: Path, diff: bool) -> None:recorded_console = Console(width=500, record=True, color_system=None)mocker.patch("pipelex.cli.commands.fix._fix_core.get_console", return_value=recorded_console)- mocker.patch("pipelex.cli.error_handlers.get_console", return_value=recorded_console)+ mocker.patch("pipelex.cli.error_handlers.get_error_console", return_value=recorded_console)mock_execute = mocker.patch("pipelex.cli.commands.fix.bundle_cmd.execute_fix")_write_folder_with_a_refused_tree(directory=tmp_path)diff --git a/tests/unit/pipelex/cli/conftest.py b/tests/unit/pipelex/cli/conftest.pyindex 3b4cb078d..9b70b4224 100644--- a/tests/unit/pipelex/cli/conftest.py+++ b/tests/unit/pipelex/cli/conftest.py@@ -2,11 +2,12 @@from __future__ import annotations+import loggingfrom typing import TYPE_CHECKINGimport pytest-from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_format+from pipelex.cli.agent_cli.commands.agent_output import start_agent_cli_error_formatfrom pipelex.cli.error_handlers import set_traceback_requestedif TYPE_CHECKING:@@ -28,13 +29,27 @@ def reset_traceback_requested() -> Iterator[None]:@pytest.fixture(autouse=True)def reset_agent_cli_error_format() -> Iterator[None]:- """Keep the module-level error-format ContextVar from leaking between cli/ tests.+ """Keep the error-format ContextVars, the program's and the active one, from leaking between cli/ tests.The deeper ``agent_cli/`` conftest has the same fixture, but tests directly under``cli/`` (e.g. ``test_agent_output.py``, which sets the ContextVar to MARKDOWN)are not covered by it — without this, a leaked MARKDOWN format would make asibling test's JSON-format assertion order-dependent."""- set_agent_cli_error_format(CliOutputFormat.JSON)+ start_agent_cli_error_format()yield- set_agent_cli_error_format(CliOutputFormat.JSON)+ start_agent_cli_error_format()++[email protected](autouse=True)+def restore_logging_cutoff() -> Iterator[None]:+ """Keep the agent CLI's process-global ``logging.disable`` cutoff from leaking out of cli/ tests.++ A test that runs ``pipelex-agent`` in-process, through its app callback, ``make_pipelex_for_agent_cli`` or the+ doctor, arms ``silence_logging_for_agent_cli``, which raises ``logging.root.manager.disable`` to ``sys.maxsize``+ for the whole process. A real agent CLI process exits right after, but a test session goes on, so without this+ restore every log-capture test that runs later, in any directory, would see no record at all.+ """+ original_disable = logging.root.manager.disable+ yield+ logging.disable(original_disable)diff --git a/tests/unit/pipelex/cli/test_agent_cli_factory.py b/tests/unit/pipelex/cli/test_agent_cli_factory.pyindex 2a91579ab..8d304e420 100644--- a/tests/unit/pipelex/cli/test_agent_cli_factory.py+++ b/tests/unit/pipelex/cli/test_agent_cli_factory.py@@ -12,10 +12,14 @@ import typerif TYPE_CHECKING:from pytest_mock import MockerFixture+from pipelex.base_exceptions import MigrationErrorBlock, PipelexConfigError, PipelexSetupErrorfrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_cli+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, start_agent_cli_error_formatfrom pipelex.cogt.exceptions import ModelDeckPresetValidationErrorfrom pipelex.cogt.model_backends.model_type import ModelType-from pipelex.system.telemetry.exceptions import TelemetryConfigValidationError+from pipelex.core.validation import MIGRATE_COMMAND+from pipelex.errors.registry.pipelex_codes import PipelexErrorCode+from pipelex.system.telemetry.exceptions import TelemetryApiKeyMissingError, TelemetryConfigValidationErrorfrom pipelex.tools.misc.pretty import PrettyPrinter@@ -46,7 +50,7 @@ class TestMakePipelexForAgentCli:assert result is mock_pipelex@pytest.mark.parametrize(- ("exc_class", "exc_args", "expected_error_type"),+ ("exc_class", "exc_args", "expected_error_class"),[(TelemetryConfigValidationError, ("telemetry config bad",), "TelemetryConfigValidationError"),],@@ -57,9 +61,9 @@ class TestMakePipelexForAgentCli:capsys: pytest.CaptureFixture[str],exc_class: type[Exception],exc_args: tuple[str, ...],- expected_error_type: str,+ expected_error_class: str,) -> None:- """Each initialization exception should produce JSON stderr with the correct error_type."""+ """Each initialization exception is reported as its problem on stderr, its class in the operator's diagnostics."""mocker.patch("pipelex.cli.agent_cli.commands.agent_cli_factory.Pipelex.make",side_effect=exc_class(*exc_args),@@ -70,9 +74,11 @@ class TestMakePipelexForAgentCli:assert exc_info.value.exit_code == 1parsed = json.loads(capsys.readouterr().err)- assert parsed["error"] is True- assert parsed["error_type"] == expected_error_type- assert "message" in parsed+ assert parsed["code"] == "pipelex.config.invalid"+ assert parsed["domain"] == "operator"+ assert parsed["diagnostics"]["error_class"] == expected_error_class+ assert parsed["message"] == "telemetry config bad"+ assert "hint" not in parseddef test_model_deck_preset_error_includes_structured_fields(self,@@ -96,7 +102,138 @@ class TestMakePipelexForAgentCli:make_pipelex_for_agent_cli()parsed = json.loads(capsys.readouterr().err)- assert parsed["error_type"] == "ModelDeckPresetValidationError"+ assert parsed["diagnostics"]["error_class"] == "ModelDeckPresetValidationError"assert parsed["preset_id"] == "my_preset"assert parsed["model_handle"] == "claude-3-opus"assert sorted(parsed["enabled_backends"]) == ["anthropic", "openai"]++ @pytest.mark.parametrize(+ ("failure", "expected_code"),+ [+ (RuntimeError("the disk is full"), "runtime.unexpected"),+ (PipelexSetupError("Pipelex is already initialized"), "runtime.misconfigured"),+ (+ ModelDeckPresetValidationError(+ message="preset validation failed",+ preset_id="my_preset",+ model_type=ModelType.LLM,+ model_handle="claude-3-opus",+ enabled_backends={"openai"},+ ),+ "pipelex.config.invalid",+ ),+ ],+ )+ def test_a_boot_failure_with_no_advice_tips_the_recovery_path(+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], failure: Exception, expected_code: str+ ) -> None:+ """A boot failure whose chain advises nothing is tipped with the recovery path an agent can run, and keeps its code."""+ mocker.patch("pipelex.cli.agent_cli.commands.agent_cli_factory.Pipelex.make", side_effect=failure)+ start_agent_cli_error_format(root_error_format=CliOutputFormat.MARKDOWN)++ with pytest.raises(typer.Exit):+ make_pipelex_for_agent_cli()++ markdown = capsys.readouterr().err+ assert f"- Code: `{expected_code}`" in markdown+ assert "💡 Run 'pipelex-agent doctor' to diagnose the installation and its configuration." in markdown+ assert "'pipelex-agent migrate --dry-run --format json', shown to the user, then 'pipelex-agent migrate --yes'" in markdown+ assert "'pipelex-agent init' (--global for the home configuration)" in markdown++ @pytest.mark.parametrize(+ ("failure", "expected_code", "expected_message"),+ [+ (RuntimeError("the disk is full"), "runtime.unexpected", "Pipelex initialization failed: the disk is full"),+ (PipelexSetupError("Pipelex is already initialized"), "runtime.misconfigured", "Pipelex is already initialized"),+ ],+ )+ def test_a_boot_failure_keeps_its_code_and_class(+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], failure: Exception, expected_code: str, expected_message: str+ ) -> None:+ """Under the boot's tip the problem is the failure's own: its code, and its class as the diagnostics' error class."""+ mocker.patch("pipelex.cli.agent_cli.commands.agent_cli_factory.Pipelex.make", side_effect=failure)++ with pytest.raises(typer.Exit):+ make_pipelex_for_agent_cli()++ stderr = capsys.readouterr().err+ parsed = json.loads(stderr)+ assert parsed["code"] == expected_code+ assert parsed["message"] == expected_message+ assert parsed["diagnostics"]["error_class"] == type(failure).__name__+ assert "AgentBootError" not in stderr++ start_agent_cli_error_format(root_error_format=CliOutputFormat.MARKDOWN)+ with pytest.raises(typer.Exit):+ make_pipelex_for_agent_cli()++ assert f"- Error class: `{type(failure).__name__}`" in capsys.readouterr().err++ @pytest.mark.parametrize(+ ("migration", "expected_tip"),+ [+ (None, "💡 Run 'pipelex doctor' (from an agent, 'pipelex-agent doctor') to find what in the configuration does not validate"),+ (+ MigrationErrorBlock(remedy=MIGRATE_COMMAND, would_write=True, needs_attention=False, plans=[]),+ "then run 'pipelex-agent migrate --yes'",+ ),+ (+ MigrationErrorBlock(remedy=MIGRATE_COMMAND, would_write=False, needs_attention=True, plans=[]),+ "💡 A migration would rewrite nothing here: correct by hand what the migration's plans name",+ ),+ ],+ )+ def test_a_configuration_that_does_not_load_tips_its_own_advice(+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], migration: MigrationErrorBlock | None, expected_tip: str+ ) -> None:+ """A configuration error advises by its migration: doctor, migrate, or correct by hand; its step names the setting."""+ refusal = PipelexConfigError(+ "Could not setup config because of: bad", migration=migration, surface="pipelex", file="pipelex.toml", setting="runtime.log.level"+ )+ mocker.patch("pipelex.cli.agent_cli.commands.agent_cli_factory.Pipelex.make", side_effect=refusal)+ start_agent_cli_error_format(root_error_format=CliOutputFormat.MARKDOWN)++ with pytest.raises(typer.Exit):+ make_pipelex_for_agent_cli()++ markdown = capsys.readouterr().err+ assert expected_tip in markdown+ assert "Run 'pipelex-agent doctor' to diagnose the installation" not in markdown+ assert (+ "Correct the setting 'runtime.log.level' in the file 'pipelex.toml' of the pipelex configuration, then restart the runtime." in markdown+ )++ @pytest.mark.parametrize(+ ("refusal", "expected_tip"),+ [+ (+ PipelexConfigError("Error loading configuration: no such file", surface="pipelex", file="pipelex.toml").with_error_code(+ PipelexErrorCode.CONFIG_FILE_MISSING+ ),+ "💡 A configuration file is missing: restore it, or run 'pipelex init' (from an agent, 'pipelex-agent init', with --global",+ ),+ (+ TelemetryApiKeyMissingError("Custom PostHog is enabled in the telemetry configuration, but its API key is not set"),+ "💡 A variable the configuration reads is not set: set the one the message names",+ ),+ (+ PipelexConfigError("Error loading configuration: bad TOML", surface="pipelex", file="pipelex.toml")+ .with_error_code(PipelexErrorCode.CONFIG_SYNTAX)+ .with_params(line=1, column=9),+ "💡 Run 'pipelex doctor' (from an agent, 'pipelex-agent doctor') to find what in the configuration does not validate",+ ),+ ],+ )+ def test_a_configuration_refusal_s_tip_follows_its_code(+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], refusal: PipelexConfigError, expected_tip: str+ ) -> None:+ """A missing file is written by init, a missing variable is set, and only a file that does not validate or parse sends to doctor."""+ mocker.patch("pipelex.cli.agent_cli.commands.agent_cli_factory.Pipelex.make", side_effect=refusal)+ start_agent_cli_error_format(root_error_format=CliOutputFormat.MARKDOWN)++ with pytest.raises(typer.Exit):+ make_pipelex_for_agent_cli()++ markdown = capsys.readouterr().err+ assert expected_tip in markdown+ assert markdown.count("💡") == 1diff --git a/tests/unit/pipelex/cli/test_agent_codegen_check_cmd.py b/tests/unit/pipelex/cli/test_agent_codegen_check_cmd.pyindex 380a3112b..17f92ab3c 100644--- a/tests/unit/pipelex/cli/test_agent_codegen_check_cmd.py+++ b/tests/unit/pipelex/cli/test_agent_codegen_check_cmd.py@@ -55,7 +55,7 @@ class TestAgentCodegenCheckCmd:capsys.readouterr()def test_drift_is_structured_negative_verdict_exit_1(self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:- """Drift is a produced negative verdict: exit 1 with the drifting artifacts enumerated in the envelope."""+ """Drift is a produced negative verdict: exit 1, its problem naming the drifting artifacts, which ride beside it in full."""report = CodegenCheckReport(lock_found=True,drifts=[CodegenDrift(path="models.py", category=DriftCategory.HAND_EDITED, detail="Body was edited below the stamp.")],@@ -67,7 +67,8 @@ class TestAgentCodegenCheckCmd:assert exc_info.value.exit_code == 1error = json.loads(capsys.readouterr().err)- assert error["error_type"] == "CodegenDriftError"+ assert error["code"] == "pipelex.codegen.drifted"+ assert error["params"] == {"artifacts": ["models.py"]}assert error["is_current"] is Falseassert error["drifts"] == [{"path": "models.py", "category": "hand-edited", "detail": "Body was edited below the stamp."}]@@ -79,7 +80,8 @@ class TestAgentCodegenCheckCmd:assert exc_info.value.exit_code == 2error = json.loads(capsys.readouterr().err)- assert error["error_type"] == "CodegenLockNotFoundError"+ assert error["code"] == "pipelex.codegen.lock_not_found"+ assert error["params"] == {"path": str(tmp_path)}def test_unreadable_lock_is_no_verdict_exit_2(self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:mocker.patch(f"{CMD_MODULE}.run_codegen_check", side_effect=CodegenLockError("codegen.lock is not valid TOML"))@@ -89,6 +91,20 @@ class TestAgentCodegenCheckCmd:assert exc_info.value.exit_code == 2error = json.loads(capsys.readouterr().err)- assert error["error_type"] == "CodegenLockError"+ assert error["code"] == "pipelex.codegen.lock_invalid"+ assert error["diagnostics"]["error_class"] == "CodegenLockError"assert "not valid TOML" in error["message"]- assert "remove it, then regenerate" in error["hint"]++ def test_unreadable_lock_markdown_follows_the_success_format(+ self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]+ ) -> None:+ """With no --error-format, the error stream follows --format: Markdown here, naming the code and the lock's fault."""+ mocker.patch(f"{CMD_MODULE}.run_codegen_check", side_effect=CodegenLockError("codegen.lock is not valid TOML"))++ with pytest.raises(typer.Exit):+ agent_codegen_check_cmd(root=str(tmp_path), output_format=CliOutputFormat.MARKDOWN, error_format=None)++ err = capsys.readouterr().err+ assert err.startswith("## ")+ assert "- Code: `pipelex.codegen.lock_invalid`" in err+ assert "codegen.lock is not valid TOML" in errdiff --git a/tests/unit/pipelex/cli/test_agent_codegen_types_cmd.py b/tests/unit/pipelex/cli/test_agent_codegen_types_cmd.pyindex 41694bffa..27a266556 100644--- a/tests/unit/pipelex/cli/test_agent_codegen_types_cmd.py+++ b/tests/unit/pipelex/cli/test_agent_codegen_types_cmd.py@@ -100,15 +100,14 @@ class TestAgentCodegenTypesCmd:assert exc_info.value.exit_code == 1error = json.loads(capsys.readouterr().err)- assert error["error"] is True- assert error["error_type"] == "LibraryLoadingError"+ assert error["diagnostics"]["error_class"] == "LibraryLoadingError"assert "duplicate pipe" in error["message"]@pytest.mark.parametrize(- ("raised", "expected_error_type"),+ ("raised", "expected_code"),[- (FileNotFoundError("the library directory does not exist."), "FileNotFoundError"),- (BundleClosureEmptyError("no .mthds bundles found in the closure."), "BundleClosureEmptyError"),+ (FileNotFoundError("the library directory does not exist."), "client.file_unreadable"),+ (BundleClosureEmptyError("no .mthds bundles found in the closure."), "method.not_found"),],)def test_unassembled_closure_is_no_verdict_exit_2(@@ -117,7 +116,7 @@ class TestAgentCodegenTypesCmd:tmp_path: Path,capsys: pytest.CaptureFixture[str],raised: Exception,- expected_error_type: str,+ expected_code: str,) -> None:self._neutralize_boot(mocker)mocker.patch(f"{CMD_MODULE}.load_normalized_crate", side_effect=raised)@@ -134,7 +133,7 @@ class TestAgentCodegenTypesCmd:assert exc_info.value.exit_code == 2error = json.loads(capsys.readouterr().err)- assert error["error_type"] == expected_error_type+ assert error["code"] == expected_codedef test_boot_loads_model_specs_for_offline_validation(self, mocker: MockerFixture, tmp_path: Path) -> None:"""Like the bare CLI, the agent mirror boots offline but WITH model specs: library validationdiff --git a/tests/unit/pipelex/cli/test_agent_doctor_cmd.py b/tests/unit/pipelex/cli/test_agent_doctor_cmd.pyindex c4cef0dbe..241c163c8 100644--- a/tests/unit/pipelex/cli/test_agent_doctor_cmd.py+++ b/tests/unit/pipelex/cli/test_agent_doctor_cmd.py@@ -504,7 +504,7 @@ class TestAgentDoctorCmd:assert any("ANTHROPIC_API_KEY" in action for action in parsed["recommended_actions"])def test_unexpected_error_produces_json_error(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:- """If a health check raises an unexpected exception, agent_error JSON should be produced."""+ """If a health check raises an unexpected exception, its problem is printed as JSON."""mocker.patch("pipelex.cli.agent_cli.commands.doctor_cmd.check_config_files",side_effect=RuntimeError("unexpected kaboom"),@@ -515,7 +515,8 @@ class TestAgentDoctorCmd:assert exc_info.value.exit_code == 1parsed = json.loads(capsys.readouterr().err)- assert parsed["error"] is True+ assert parsed["code"] == "runtime.unexpected"+ assert parsed["diagnostics"]["error_class"] == "RuntimeError"assert "unexpected kaboom" in parsed["message"]def test_broken_config_skips_bootstrap_and_preserves_partial_report(diff --git a/tests/unit/pipelex/cli/test_agent_output.py b/tests/unit/pipelex/cli/test_agent_output.pyindex 0159bc631..f763b6b94 100644--- a/tests/unit/pipelex/cli/test_agent_output.py+++ b/tests/unit/pipelex/cli/test_agent_output.py@@ -1,11 +1,9 @@-"""Unit tests for the agent CLI output helpers."""-from __future__ import annotationsimport datetimeimport jsonimport logging-from typing import TYPE_CHECKING+from typing import TYPE_CHECKING, Anyimport pytestimport typer@@ -15,31 +13,25 @@ from typer.testing import CliRunnerfrom pipelex.base_exceptions import PipelexConfigError, PipelexErrorfrom pipelex.cli.agent_cli._agent_cli import appfrom pipelex.cli.agent_cli.commands.agent_output import (- AGENT_ERROR_DOMAINS,- AGENT_ERROR_HINTS,CliOutputFormat,_build_error_source, # pyright: ignore[reportPrivateUsage]+ agent_argument_error,agent_error,+ agent_file_error,agent_success,- extract_validation_errors,- run_failure_fields,+ get_agent_cli_error_format,+ problem_payload,+ render_problem_markdown,set_agent_cli_error_format,+ start_agent_cli_error_format,+ use_agent_cli_error_format,)-from pipelex.cogt.exceptions import (- CogtError,- InferenceBackendCredentialsError,- InferenceBackendCredentialsErrorType,- InferenceErrorCategory,- ModelChoiceNotFoundError,-)-from pipelex.cogt.inference.error_classification import UserAction, UserActionKind-from pipelex.cogt.model_backends.model_type import ModelType-from pipelex.errors.problem import ProblemView-from pipelex.pipe_run.exceptions import PipeRouterError+from pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError+from pipelex.cogt.exceptions import InferenceBackendCredentialsError, InferenceBackendCredentialsErrorType+from pipelex.errors.problem import MigrationErrorBlock, ProblemView, make_location, make_problem, make_problem_itemfrom pipelex.pipe_run.located_failure import make_unexpected_failure-from pipelex.pipeline.exceptions import PipelineExecutionError, ValidateBundleError-from pipelex.runtime_bridge.exceptions import MissingOrchestratorError-from pipelex.system.pipe_run_mode import PipeRunMode+from pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.system.usage_stats.usage_stats_contract import UsageStatsError, UsageStatsErrorDomainfrom pipelex.tools.misc.exceptions import RemoteFileFetchErrorfrom tests.helpers.recovered_problem import make_recovered_url_refusal@@ -49,9 +41,11 @@ if TYPE_CHECKING:from pytest_mock import MockerFixture-class TestAgentOutput:- """Tests for agent_error, agent_success, and extract_validation_errors."""+def _url_refusal() -> RemoteFileFetchError:+ return RemoteFileFetchError("Could not fetch 'https://example.com/a.pdf': the request timed out").with_error_code(CoreCode.INPUT_URL_UNREACHABLE)++class TestAgentOutput:@pytest.fixture(autouse=True)def _restore_logging_cutoff(self) -> Iterator[None]:"""Restore the process-global ``logging.disable`` threshold after a test that runs the app.@@ -63,55 +57,331 @@ class TestAgentOutput:yieldlogging.disable(original_disable)- def test_agent_error_outputs_json_to_stderr(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error should print valid JSON to stderr and exit with code 1."""+ # -------------------------------------------------------------------------+ # The JSON problem+ # -------------------------------------------------------------------------++ def test_agent_error_prints_the_problem_as_json_on_stderr(self, capsys: pytest.CaptureFixture[str]) -> None:+ """A failure with no cause and no code is the registry's catch-all, the command's sentence riding as message."""with pytest.raises(typer.Exit) as exc_info:- agent_error("something went wrong", error_type="TestError")+ agent_error("something went wrong")assert exc_info.value.exit_code == 1captured = capsys.readouterr()assert captured.out == ""parsed = json.loads(captured.err)- assert parsed["error"] is True- assert parsed["error_type"] == "TestError"+ assert parsed["type"] == "https://mthds.ai/errors/runtime.unexpected"+ assert parsed["code"] == CoreCode.RUNTIME_UNEXPECTED+ assert parsed["domain"] == "runtime"assert parsed["message"] == "something went wrong"+ for retired in ("error", "error_type", "error_domain", "error_code", "hint", "retryable", "error_source", "validation_errors"):+ assert retired not in parsed- def test_agent_error_includes_hint_for_known_type(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error should auto-add a hint for known error types."""- with pytest.raises(typer.Exit):- agent_error("model issue", error_type="PipeOperatorModelChoiceError")+ def test_agent_error_names_the_code_of_a_refusal_the_command_decides(self, capsys: pytest.CaptureFixture[str]) -> None:+ with pytest.raises(typer.Exit) as exc_info:+ agent_argument_error("--yes contradicts --dry-run", argument="--yes", reason="contradicts --dry-run", exit_code=2)+ assert exc_info.value.exit_code == 2parsed = json.loads(capsys.readouterr().err)- assert "hint" in parsed- assert parsed["hint"] == AGENT_ERROR_HINTS["PipeOperatorModelChoiceError"]-- def test_agent_error_no_hint_for_unknown_type(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error should not include hint for unregistered error types."""+ assert parsed["code"] == CoreCode.CLIENT_ARGUMENT_INVALID+ assert parsed["domain"] == "input"+ assert parsed["retry"] == "no"+ assert parsed["params"] == {"argument": "--yes", "reason": "contradicts --dry-run"}+ assert parsed["detail"] == "The argument '--yes' was refused before any request left (reason: contradicts --dry-run)."+ assert parsed["next_step"] == {"kind": "change_input", "detail": "Correct the argument '--yes', then try again."}+ assert parsed["message"] == "--yes contradicts --dry-run"+ assert "diagnostics" not in parsed++ def test_agent_file_error_names_the_file_and_the_caught_error(self, capsys: pytest.CaptureFixture[str]) -> None:with pytest.raises(typer.Exit):- agent_error("oops", error_type="CompletelyUnknownError")+ agent_file_error("Input file not found: inputs.json", path="inputs.json", reason="not found", cause=FileNotFoundError("inputs.json"))parsed = json.loads(capsys.readouterr().err)- assert "hint" not in parsed+ assert parsed["code"] == CoreCode.CLIENT_FILE_UNREADABLE+ assert parsed["params"] == {"path": "inputs.json", "reason": "not found"}+ assert parsed["diagnostics"]["error_class"] == "FileNotFoundError"- def test_agent_error_includes_extra_fields(self, capsys: pytest.CaptureFixture[str]) -> None:- """Extra kwargs should appear as top-level fields in the JSON output."""+ def test_agent_error_carries_the_command_s_own_members_beside_the_problem(self, capsys: pytest.CaptureFixture[str]) -> None:+ """The command's facts ride as further members, a datetime serialized, and none replaces a member of the problem."""with pytest.raises(typer.Exit):- agent_error("fail", error_type="SomeError", pipe_code="my_pipe", custom_data=[1, 2])+ agent_error(+ "fail",+ pipe_code="my_pipe",+ custom_data=[1, 2],+ failed_at=datetime.datetime(2026, 2, 9, 14, 0, 0),+ code_hint="mine",+ detail="not the problem's",+ )parsed = json.loads(capsys.readouterr().err)assert parsed["pipe_code"] == "my_pipe"assert parsed["custom_data"] == [1, 2]+ assert parsed["failed_at"] == "2026-02-09T14:00:00"+ assert parsed["code_hint"] == "mine"+ assert parsed["detail"] != "not the problem's"++ def test_problem_payload_never_lets_a_member_of_the_command_replace_the_problem_s(self) -> None:+ problem = make_problem(code=CoreCode.RUNTIME_UNEXPECTED, view=ProblemView.OPERATOR)+ payload = problem_payload(problem=problem, message="the command's sentence", extras={"code": "not.mine", "is_valid": False, "empty": None})+ assert payload["code"] == CoreCode.RUNTIME_UNEXPECTED+ assert payload["message"] == "the command's sentence"+ assert payload["is_valid"] is False+ assert "empty" not in payload++ def test_agent_error_reports_a_pipelex_cause_by_its_own_problem_in_the_operator_view(self, capsys: pytest.CaptureFixture[str]) -> None:+ cause = _url_refusal()+ with pytest.raises(typer.Exit):+ agent_error("fetch timed out", cause=cause)++ parsed = json.loads(capsys.readouterr().err)+ expected = cause.to_problem(view=ProblemView.OPERATOR).to_wire()+ for member in ("type", "title", "detail", "code", "domain", "retry", "next_step"):+ assert parsed[member] == expected[member]+ assert parsed["retry"] == "yes"+ assert parsed["diagnostics"]["error_class"] == "RemoteFileFetchError"- def test_agent_error_extra_can_override_hint(self, capsys: pytest.CaptureFixture[str]) -> None:- """An explicit hint kwarg should override the auto-looked-up hint."""+ def test_agent_error_classifies_a_recovered_problem_by_its_own_code(self, capsys: pytest.CaptureFixture[str]) -> None:+ """A cause reporting a problem it recovered gives its code, domain and verdict together with its step, never its class's."""+ cause = make_recovered_url_refusal()+ problem = cause.to_problem(view=ProblemView.OPERATOR)with pytest.raises(typer.Exit):- agent_error("fail", error_type="ValidateBundleError", hint="custom hint")+ agent_error("the run failed on the worker", cause=cause)parsed = json.loads(capsys.readouterr().err)- assert parsed["hint"] == "custom hint"+ assert parsed["code"] == CoreCode.INPUT_URL_UNREACHABLE+ assert parsed["domain"] == "input"+ assert parsed["retry"] == "yes"+ assert parsed["next_step"]["detail"] == problem.next_step.detail++ def test_agent_error_lists_no_item_of_a_verdict_behind_a_foreign_exception(self, capsys: pytest.CaptureFixture[str]) -> None:+ """A foreign exception raised from a handled verdict is a new failure: its problem lists none of the verdict's items."""+ stale_verdict = ValidateBundleError(message="validation failed", pipelex_bundle_blueprint_validation_errors=[])+ foreign_fault = RuntimeError("the cache could not be written")+ foreign_fault.__cause__ = stale_verdict+ stand_in = make_unexpected_failure(error=foreign_fault)++ with pytest.raises(typer.Exit):+ agent_error("unexpected failure", cause=stand_in)++ parsed = json.loads(capsys.readouterr().err)+ assert parsed["code"] == CoreCode.RUNTIME_UNEXPECTED+ assert "errors" not in parsed++ def test_agent_error_lists_the_items_of_a_verdict_under_pipelex_wrappers(self, capsys: pytest.CaptureFixture[str]) -> None:+ verdict = ValidateBundleError(message="Pipe 'post_notice' could not be loaded")+ wrapper = PipelexError("the run was refused")+ wrapper.__cause__ = verdict++ with pytest.raises(typer.Exit):+ agent_error("the run was refused", cause=wrapper)++ parsed = json.loads(capsys.readouterr().err)+ assert parsed["code"] == CoreCode.METHOD_INVALID+ assert [item["params"]["finding"] for item in parsed["errors"]] == ["Pipe 'post_notice' could not be loaded"]++ def test_agent_error_reports_a_foreign_cause_as_unexpected_with_its_class(self, capsys: pytest.CaptureFixture[str]) -> None:+ cause = RuntimeError("constructed, not raised")+ with pytest.raises(typer.Exit) as exc_info:+ agent_error("something broke", cause=cause)+ assert exc_info.value.exit_code == 1++ parsed = json.loads(capsys.readouterr().err)+ assert parsed["code"] == CoreCode.RUNTIME_UNEXPECTED+ assert parsed["diagnostics"]["error_class"] == "RuntimeError"+ assert parsed["diagnostics"]["message"] == "constructed, not raised"++ def test_agent_error_names_the_provider_of_a_failed_backend(self, capsys: pytest.CaptureFixture[str]) -> None:+ cause = InferenceBackendCredentialsError(+ credentials_error_type=InferenceBackendCredentialsErrorType.VAR_NOT_FOUND,+ backend_name="openai",+ message="OPENAI_API_KEY not set",+ key_name="OPENAI_API_KEY",+ )+ with pytest.raises(typer.Exit):+ agent_error("OPENAI_API_KEY not set", cause=cause)++ parsed = json.loads(capsys.readouterr().err)+ assert parsed["code"] == "pipelex.config.credential_missing"+ assert parsed["domain"] == "operator"+ assert parsed["diagnostics"]["provider"] == {"name": "openai"}++ @pytest.mark.parametrize("error_format", [CliOutputFormat.JSON, CliOutputFormat.MARKDOWN])+ def test_a_pending_configuration_migration_rides_the_diagnostics(self, capsys: pytest.CaptureFixture[str], error_format: CliOutputFormat) -> None:+ migration = MigrationErrorBlock(remedy="pipelex-agent migrate --yes", would_write=True, needs_attention=False, plans=[])+ set_agent_cli_error_format(error_format)+ with pytest.raises(typer.Exit):+ agent_error("Pipelex initialization failed", cause=PipelexConfigError("bad config", migration=migration))++ err = capsys.readouterr().err+ match error_format:+ case CliOutputFormat.JSON:+ parsed = json.loads(err)+ assert parsed["code"] == "pipelex.config.invalid"+ assert parsed["diagnostics"]["migration"] == {+ "remedy": "pipelex-agent migrate --yes",+ "would_write": True,+ "needs_attention": False,+ "plans": [],+ }+ case CliOutputFormat.MARKDOWN:+ assert "### Configuration migration" in err+ assert "- Remedy: `pipelex-agent migrate --yes`" in err+ assert "- Would write: yes" in err+ assert "- Needs attention: no" in err++ def test_agent_error_notes_the_problem_s_code_for_the_usage_statistics(self, mocker: MockerFixture) -> None:+ noted = mocker.patch("pipelex.cli.agent_cli.commands.agent_output.note_command_error")+ with pytest.raises(typer.Exit):+ agent_argument_error("bad", argument="--yes", reason="contradicts --dry-run")+ noted.assert_called_once_with(error=UsageStatsError(code="client.argument_invalid", domain=UsageStatsErrorDomain.INPUT))++ # -------------------------------------------------------------------------+ # The Markdown problem+ # -------------------------------------------------------------------------++ def test_agent_error_renders_markdown_when_markdown_is_the_error_format(self, capsys: pytest.CaptureFixture[str]) -> None:+ set_agent_cli_error_format(CliOutputFormat.MARKDOWN)+ with pytest.raises(typer.Exit) as exc_info:+ agent_argument_error("--yes contradicts --dry-run", argument="--yes", reason="contradicts --dry-run", pipe_code="my_pipe")+ assert exc_info.value.exit_code == 1++ captured = capsys.readouterr()+ assert captured.out == ""+ err = captured.err+ assert err.startswith("## An argument was refused before sending\n\nThe argument '--yes' was refused before any request left")+ assert "\n--yes contradicts --dry-run\n" in err+ assert "**Next step** (`change_input`): Correct the argument '--yes', then try again." in err+ assert "- Code: `client.argument_invalid` (domain input, retry no)" in err+ assert "### Details" in err+ assert "- **pipe_code:** my_pipe" in err+ with pytest.raises(json.JSONDecodeError):+ json.loads(err)++ def test_markdown_prints_the_advice_of_the_error_as_a_tip_the_json_never_carries(self, capsys: pytest.CaptureFixture[str]) -> None:+ cause = AmbiguousInputsFilesError("Directory 'd' holds both 'inputs.json' and 'inputs.toml'")+ advice = cause.advised_action()+ assert advice is not None++ set_agent_cli_error_format(CliOutputFormat.MARKDOWN)+ with pytest.raises(typer.Exit):+ agent_error(cause.message, cause=cause)+ assert f"\n💡 {advice.detail}\n" in capsys.readouterr().err++ set_agent_cli_error_format(CliOutputFormat.JSON)+ with pytest.raises(typer.Exit):+ agent_error(cause.message, cause=cause)+ assert advice.detail not in capsys.readouterr().err++ def test_render_problem_markdown_states_the_facts_the_faults_and_the_diagnostics(self) -> None:+ location = make_location(pipe="summarize", path=["main", "summarize"], file="contracts.mthds", line=12)+ item = make_problem_item(code=CoreCode.METHOD_CONCEPT_UNRESOLVED, params={"concept": "Missing"}, location=make_location(pipe="summarize"))+ problem = make_problem(+ code=CoreCode.METHOD_INVALID,+ view=ProblemView.OPERATOR,+ location=location,+ errors=[item],+ request_id="req-123",+ pipeline_run_id="run-456",+ )++ rendered = render_problem_markdown(problem=problem, message=problem.detail, extras={"is_valid": False, "bundle_path": "/w/b.mthds"})++ assert rendered.startswith(f"## {problem.title}\n\n{problem.detail}\n\n**Next step**")+ assert f"\n{problem.detail}\n\n{problem.detail}" not in rendered+ assert "- Code: `method.invalid` (domain method, retry no)" in rendered+ assert "- Request id: `req-123`" in rendered+ assert "- Run: `run-456`" in rendered+ assert "- Location: pipe 'summarize', path main > summarize, file 'contracts.mthds', line 12" in rendered+ assert "### Errors" in rendered+ assert f"- `method.concept_unresolved`: {item.detail} (pipe 'summarize')" in rendered+ assert "- **bundle_path:** /w/b.mthds" in rendered+ assert "is_valid" not in rendered++ def test_render_problem_markdown_names_the_model_and_the_provider(self) -> None:+ cause = InferenceBackendCredentialsError(+ credentials_error_type=InferenceBackendCredentialsErrorType.VAR_NOT_FOUND,+ backend_name="openai",+ message="OPENAI_API_KEY not set",+ key_name="OPENAI_API_KEY",+ )+ rendered = render_problem_markdown(problem=cause.to_problem(view=ProblemView.OPERATOR))+ assert "### Diagnostics" in rendered+ assert "- Error class: `InferenceBackendCredentialsError`" in rendered+ assert "- Provider: `openai`" in rendered++ # -------------------------------------------------------------------------+ # The error format: the command's, the program's, the command's --format+ # -------------------------------------------------------------------------++ @pytest.mark.parametrize(+ ("command_error_format", "root_error_format", "output_format", "expected"),+ [+ (None, None, None, CliOutputFormat.JSON),+ (None, None, CliOutputFormat.MARKDOWN, CliOutputFormat.MARKDOWN),+ (None, CliOutputFormat.JSON, CliOutputFormat.MARKDOWN, CliOutputFormat.JSON),+ (None, CliOutputFormat.MARKDOWN, CliOutputFormat.JSON, CliOutputFormat.MARKDOWN),+ (CliOutputFormat.JSON, CliOutputFormat.MARKDOWN, CliOutputFormat.MARKDOWN, CliOutputFormat.JSON),+ (CliOutputFormat.MARKDOWN, None, None, CliOutputFormat.MARKDOWN),+ ],+ )+ def test_the_error_format_is_the_command_s_then_the_program_s_then_the_format(+ self,+ command_error_format: CliOutputFormat | None,+ root_error_format: CliOutputFormat | None,+ output_format: CliOutputFormat | None,+ expected: CliOutputFormat,+ ) -> None:+ start_agent_cli_error_format(root_error_format=root_error_format)+ use_agent_cli_error_format(error_format=command_error_format, output_format=output_format)+ assert get_agent_cli_error_format() == expected++ def test_app_callback_resets_error_format_to_json(self, mocker: MockerFixture) -> None:+ """The error format is reset per invocation: a markdown command leaving it set must not leak into a later one."""+ set_agent_cli_error_format(CliOutputFormat.MARKDOWN)+ mocker.patch("pipelex.cli.agent_cli.commands.plxt_passthrough.shutil.which", return_value=None)++ # `fmt` has no --format / --error-format option; with no plxt binary on the path it errors via agent_error().+ result = CliRunner().invoke(app, ["fmt", "bundle.mthds"])++ assert result.exit_code == 1+ parsed = json.loads(result.stderr)+ assert parsed["code"] == CoreCode.CLIENT_TOOL_MISSING+ assert parsed["params"] == {"tool": "plxt"}++ def test_the_program_s_error_format_reaches_a_command_with_no_option_of_its_own(self, mocker: MockerFixture) -> None:+ mocker.patch("pipelex.cli.agent_cli.commands.plxt_passthrough.shutil.which", return_value=None)++ result = CliRunner().invoke(app, ["--error-format", "markdown", "fmt", "bundle.mthds"])++ assert result.exit_code == 1+ assert result.stderr.startswith("## A local tool the client needs is missing")+ assert "- Code: `client.tool_missing`" in result.stderr++ @pytest.mark.parametrize(+ ("args", "is_markdown"),+ [+ (["no-such-command"], False),+ (["--error-format", "markdown", "no-such-command"], True),+ ],+ )+ def test_an_unknown_command_is_an_argument_refusal_in_the_program_s_error_format(self, args: list[str], is_markdown: bool) -> None:+ result = CliRunner().invoke(app, args)++ assert result.exit_code == 1+ if is_markdown:+ assert result.stderr.startswith("## An argument was refused before sending")+ assert "Unknown command: no-such-command" in result.stderr+ else:+ parsed: dict[str, Any] = json.loads(result.stderr)+ assert parsed["code"] == CoreCode.CLIENT_ARGUMENT_INVALID+ assert parsed["params"] == {"argument": "no-such-command", "reason": "not a command of pipelex-agent"}+ assert "validate" in parsed["valid_commands"]++ # -------------------------------------------------------------------------+ # Success output+ # -------------------------------------------------------------------------def test_agent_success_outputs_json_to_stdout(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_success should print valid JSON to stdout."""agent_success({"success": True, "value": 42})captured = capsys.readouterr()@@ -120,17 +390,6 @@ class TestAgentOutput:assert parsed["success"] is Trueassert parsed["value"] == 42- # NOTE: the per-category projection of ``extract_validation_errors`` is now pinned- # thoroughly (including CLI↔API shape parity) by the shared-builder suite in- # tests/unit/pipelex/pipeline/test_validation_errors.py — the former- # ``test_extract_validation_errors_all_categories`` here duplicated it with weaker- # asserts and a stale "4 categories" docstring, so it was removed.-- # -------------------------------------------------------------------------- # Datetime serialization tests (regression for "Object of type datetime is- # not JSON serializable" bug in dry-run output)- # --------------------------------------------------------------------------@pytest.mark.parametrize(("label", "value", "expected_iso"),[@@ -154,7 +413,6 @@ class TestAgentOutput:assert parsed["field"] == expected_iso, f"Expected ISO format for {label}"def test_agent_success_handles_nested_datetime(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_success must handle datetime objects nested in dicts and lists."""result = {"success": True,"working_memory": {@@ -172,55 +430,11 @@ class TestAgentOutput: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"- def test_agent_error_handles_datetime_in_extras(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error must serialize datetime values passed via **extra kwargs."""- with pytest.raises(typer.Exit):- agent_error(- "pipeline failed",- error_type="PipelineExecutionError",- failed_at=datetime.datetime(2026, 2, 9, 14, 0, 0),- )-- parsed = json.loads(capsys.readouterr().err)- assert parsed["error"] is True- assert parsed["failed_at"] == "2026-02-09T14:00:00"-- def test_run_failure_fields_name_the_location_and_the_root_fault(self) -> None:- """A failed run's fields carry the failing pipe, its path, and the root fault's identity and own message."""- root_fault = CogtError(message="rate limited", error_category=InferenceErrorCategory.TRANSIENT)- located = PipeRouterError.make_located(- failure=root_fault, run_mode=PipeRunMode.LIVE, pipe_code="summarize", output_name=None, pipe_stack=["two_steps", "summarize"]- )- located.__cause__ = root_fault- run_failure = PipelineExecutionError.make_for_run_failure(- failure=located, run_mode=PipeRunMode.LIVE, entry_pipe_code="two_steps", output_name=None- )- run_failure.__cause__ = located-- assert run_failure_fields(error=run_failure) == {- "pipe_code": "summarize",- "pipe_stack": ["two_steps", "summarize"],- "cause_type": "CogtError",- "cause_message": "rate limited",- }-- def test_extract_validation_errors_message_only(self) -> None:- """A message-only error yields one ``blueprint_validation`` residual — the structured-info invariant is total.-- A parse-level failure (TOML syntax, an empty blueprint, a bundle elaborator) carries no- categorized data, but the builder's last-resort ``fallback_message`` residual still emits- one item so the CLI's ``validation_errors[]`` is never empty on an invalid verdict.- """- exc = ValidateBundleError(message="no details")- result = extract_validation_errors(exc)- assert result == [{"category": "blueprint_validation", "message": "no details"}]-# -------------------------------------------------------------------------- # _build_error_source tests+ # _build_error_source, which a hosted run's envelope still carries# -------------------------------------------------------------------------def test_build_error_source_with_none_traceback(self) -> None:- """_build_error_source should handle exceptions with no traceback (constructed but never raised)."""exc = RuntimeError("constructed, not raised")assert exc.__traceback__ is None@@ -230,12 +444,9 @@ class TestAgentOutput:assert "no traceback" in sources[0]def test_build_error_source_with_chained_none_tracebacks(self) -> None:- """_build_error_source should handle a cause chain where all exceptions lack tracebacks."""cause = ValueError("root cause")outer = RuntimeError("wrapper")outer.__cause__ = cause- assert cause.__traceback__ is None- assert outer.__traceback__ is Nonesources = _build_error_source(outer)assert len(sources) == 2@@ -245,7 +456,6 @@ class TestAgentOutput:assert "no traceback" in sources[1]def test_build_error_source_with_real_traceback(self) -> None:- """_build_error_source should extract location info from a raised exception."""try:msg = "actually raised"raise RuntimeError(msg)@@ -256,265 +466,3 @@ class TestAgentOutput:assert "RuntimeError" in sources[0]assert "no traceback" not in sources[0]assert "test_agent_output.py" in sources[0]-- def test_agent_error_with_no_traceback_cause(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error should emit valid JSON even when cause has no traceback."""- cause = RuntimeError("constructed, not raised")- assert cause.__traceback__ is None-- with pytest.raises(typer.Exit) as exc_info:- agent_error("something broke", error_type="RuntimeError", cause=cause)- assert exc_info.value.exit_code == 1-- parsed = json.loads(capsys.readouterr().err)- assert parsed["error"] is True- assert "error_source" in parsed- assert len(parsed["error_source"]) == 1- assert "no traceback" in parsed["error_source"][0]-- # -------------------------------------------------------------------------- # to_problem() integration tests- # --------------------------------------------------------------------------- def test_agent_error_uses_report_hint_from_cogt_error(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error should use the next step from to_problem() as the hint field."""- cause = CogtError(- "inference failed",- user_action=UserAction(kind=UserActionKind.CHECK_CREDENTIALS, detail="Check your API key and try again"),- )- with pytest.raises(typer.Exit):- agent_error("inference failed", error_type="CogtError", cause=cause)-- parsed = json.loads(capsys.readouterr().err)- assert parsed["hint"] == "Check your API key and try again"-- def test_agent_error_uses_report_retryable_from_the_code(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error sets retryable=True when the cause's code says a retry can succeed."""- cause = RemoteFileFetchError("Could not fetch 'https://example.com/a.pdf': the request timed out").with_error_code(- CoreCode.INPUT_URL_UNREACHABLE- )- with pytest.raises(typer.Exit):- agent_error("fetch timed out", error_type="RemoteFileFetchError", cause=cause)-- parsed = json.loads(capsys.readouterr().err)- assert parsed["retryable"] is True- assert parsed["error_domain"] == "input"-- def test_agent_error_carries_the_cause_registry_code(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error names the cause's registry code as error_code, the member a hosted refusal carries too."""- cause = RemoteFileFetchError("Could not fetch 'https://example.com/a.pdf': the request timed out").with_error_code(- CoreCode.INPUT_URL_UNREACHABLE- )- with pytest.raises(typer.Exit):- agent_error("fetch timed out", error_type="RemoteFileFetchError", cause=cause)-- parsed = json.loads(capsys.readouterr().err)- assert parsed["error_code"] == CoreCode.INPUT_URL_UNREACHABLE-- def test_agent_error_classifies_a_recovered_problem_by_its_own_code(self, capsys: pytest.CaptureFixture[str]) -> None:- """A cause reporting a problem it recovered gives its code, domain and verdict together with its step, never its class's."""- cause = make_recovered_url_refusal()- problem = cause.to_problem(view=ProblemView.OPERATOR)- with pytest.raises(typer.Exit):- agent_error("the run failed on the worker", error_type="RecoveredProblemError", cause=cause)-- parsed = json.loads(capsys.readouterr().err)- assert parsed["error_code"] == CoreCode.INPUT_URL_UNREACHABLE- assert parsed["error_domain"] == "input"- assert parsed["retryable"] is True- assert parsed["hint"] == problem.next_step.detail-- def test_agent_error_lists_no_item_of_a_verdict_behind_a_foreign_exception(self, capsys: pytest.CaptureFixture[str]) -> None:- """A foreign exception raised from a handled verdict is a new failure: its envelope lists none of the verdict's items."""- stale_verdict = ValidateBundleError(message="validation failed", pipelex_bundle_blueprint_validation_errors=[])- foreign_fault = RuntimeError("the cache could not be written")- foreign_fault.__cause__ = stale_verdict- stand_in = make_unexpected_failure(error=foreign_fault)-- with pytest.raises(typer.Exit):- agent_error("unexpected failure", error_type="PipelexUnexpectedError", cause=stand_in)-- parsed = json.loads(capsys.readouterr().err)- assert parsed["error_code"] == CoreCode.RUNTIME_UNEXPECTED- assert "validation_errors" not in parsed-- def test_agent_error_lists_the_items_of_a_verdict_under_pipelex_wrappers(self, capsys: pytest.CaptureFixture[str]) -> None:- verdict = ValidateBundleError(message="Pipe 'post_notice' could not be loaded")- wrapper = PipelexError("the run was refused")- wrapper.__cause__ = verdict-- with pytest.raises(typer.Exit):- agent_error("the run was refused", error_type="PipelexError", cause=wrapper)-- parsed = json.loads(capsys.readouterr().err)- assert [item["message"] for item in parsed["validation_errors"]] == ["Pipe 'post_notice' could not be loaded"]-- def test_agent_error_has_no_error_code_without_a_coded_cause(self, capsys: pytest.CaptureFixture[str]) -> None:- """A builtin cause carries no registry code, so the envelope names none rather than inventing one."""- with pytest.raises(typer.Exit):- agent_error("file not found", error_type="FileNotFoundError", cause=FileNotFoundError("missing.mthds"))-- parsed = json.loads(capsys.readouterr().err)- assert "error_code" not in parsed-- def test_agent_error_uses_report_error_category(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error should include error_category from to_problem()."""- cause = CogtError("bad config", error_category=InferenceErrorCategory.CONFIGURATION)- with pytest.raises(typer.Exit):- agent_error("bad config", error_type="CogtError", cause=cause)-- parsed = json.loads(capsys.readouterr().err)- assert parsed["error_category"] == "configuration"-- def test_agent_error_falls_back_to_lookup_for_non_pipelex_error(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error should use lookup dicts when cause is not a PipelexError."""- cause = FileNotFoundError("missing.mthds")- with pytest.raises(typer.Exit):- agent_error("file not found", error_type="FileNotFoundError", cause=cause)-- parsed = json.loads(capsys.readouterr().err)- assert parsed["hint"] == AGENT_ERROR_HINTS["FileNotFoundError"]- assert "error_category" not in parsed-- def test_agent_error_falls_back_to_lookup_when_report_fields_none(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error should fall back to lookup when PipelexError has no category/user_action."""- cause = PipelexError("something failed")- with pytest.raises(typer.Exit):- agent_error("something failed", error_type="PipeExecutionError", cause=cause)-- parsed = json.loads(capsys.readouterr().err)- # hint should come from AGENT_ERROR_HINTS since PipelexError has no user_action- assert parsed["hint"] == AGENT_ERROR_HINTS["PipeExecutionError"]-- def test_agent_error_falls_back_to_the_code_s_next_step(self, capsys: pytest.CaptureFixture[str]) -> None:- """With no advice on the chain and no table entry, the hint is the code's next step as the operator reads it."""- cause = MissingOrchestratorError(mode="temporal")- with pytest.raises(typer.Exit):- agent_error(cause.message, error_type="MissingOrchestratorError", cause=cause)-- parsed = json.loads(capsys.readouterr().err)- assert parsed["hint"] == (- "Install a plugin that provides 'temporal' for the setting 'orchestration_mode', or choose a value an installed plugin provides."- )-- def test_agent_error_report_hint_overrides_lookup(self, capsys: pytest.CaptureFixture[str]) -> None:- """When cause has user_action, it should override the lookup dict hint."""- # Use an error_type that exists in AGENT_ERROR_HINTS- cause = CogtError(- "model not found",- user_action=UserAction(kind=UserActionKind.CHANGE_MODEL, detail="Use pipelex-agent models to list available models"),- )- with pytest.raises(typer.Exit):- agent_error("model not found", error_type="ModelChoiceNotFoundError", cause=cause)-- parsed = json.loads(capsys.readouterr().err)- assert parsed["hint"] == "Use pipelex-agent models to list available models"- assert parsed["hint"] != AGENT_ERROR_HINTS["ModelChoiceNotFoundError"]-- def test_agent_error_extra_still_overrides_report(self, capsys: pytest.CaptureFixture[str]) -> None:- """Explicit **extra kwargs should override report-derived fields."""- cause = CogtError(- "failed",- user_action=UserAction(kind=UserActionKind.UNKNOWN, detail="from report"),- )- with pytest.raises(typer.Exit):- agent_error("failed", error_type="CogtError", cause=cause, hint="custom override")-- parsed = json.loads(capsys.readouterr().err)- assert parsed["hint"] == "custom override"-- def test_agent_error_includes_model_and_provider_from_report(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error should include model and provider from to_problem()."""- cause = InferenceBackendCredentialsError(- credentials_error_type=InferenceBackendCredentialsErrorType.VAR_NOT_FOUND,- backend_name="openai",- message="OPENAI_API_KEY not set",- key_name="OPENAI_API_KEY",- )- with pytest.raises(typer.Exit):- agent_error("OPENAI_API_KEY not set", error_type="InferenceBackendCredentialsError", cause=cause)-- parsed = json.loads(capsys.readouterr().err)- assert parsed["provider"] == "openai"-- def test_agent_error_non_retryable_not_in_output(self, capsys: pytest.CaptureFixture[str]) -> None:- """Non-retryable errors should not include retryable field in JSON output."""- cause = CogtError("bad config", error_category=InferenceErrorCategory.CONFIGURATION)- with pytest.raises(typer.Exit):- agent_error("bad config", error_type="CogtError", cause=cause)-- parsed = json.loads(capsys.readouterr().err)- assert "retryable" not in parsed-- def test_agent_error_domain_lookup_serves_an_uncoded_cause(self, capsys: pytest.CaptureFixture[str]) -> None:- """An error that carries no registry code takes its domain from the lookup, and no category.-- Every ``PipelexError`` carries a code, whose domain the report always holds, so the lookup is read only- for a builtin or third-party cause, or for a synthetic label with no cause at all.- """- error_type = "FileNotFoundError"- assert error_type in AGENT_ERROR_DOMAINS, "precondition: error_type must be in AGENT_ERROR_DOMAINS"-- cause = FileNotFoundError("inputs.json")- with pytest.raises(typer.Exit):- agent_error("Input file not found", error_type=error_type, cause=cause)-- parsed = json.loads(capsys.readouterr().err)- assert parsed["error_domain"] == AGENT_ERROR_DOMAINS[error_type]- assert "error_category" not in parsed- assert "retryable" not in parsed-- def test_agent_error_report_domain_beats_the_lookup(self, capsys: pytest.CaptureFixture[str]) -> None:- """A categorized CogtError cause supplies the domain itself, so the lookup is not consulted.-- `ModelChoiceNotFoundError` used to be an `AGENT_ERROR_DOMAINS` entry reading `input`. It now- declares that domain on the class, which is what the report carries — same answer for this- CLI, from the single source of truth the drift test enforces.- """- cause = ModelChoiceNotFoundError(- message="model not found",- model_type=ModelType.LLM,- model_choice="gpt-nope",- )- with pytest.raises(typer.Exit):- agent_error("model not found", error_type="ModelChoiceNotFoundError", cause=cause)-- parsed = json.loads(capsys.readouterr().err)- assert "ModelChoiceNotFoundError" not in AGENT_ERROR_DOMAINS, "the class is the single source of truth now"- assert parsed["error_domain"] == "input"- assert parsed["error_category"] == "configuration"-- def test_agent_error_uses_report_error_domain(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error should include error_domain from to_problem() for a PipelexError cause."""- cause = PipelexConfigError("bad config")- with pytest.raises(typer.Exit):- agent_error("bad config", error_type="PipelexConfigError", cause=cause)-- parsed = json.loads(capsys.readouterr().err)- assert parsed["error_domain"] == "config"-- def test_agent_error_error_domain_falls_back_to_dict_for_builtin(self, capsys: pytest.CaptureFixture[str]) -> None:- """agent_error should read error_domain from the lookup dict for a non-PipelexError cause."""- cause = FileNotFoundError("missing.mthds")- with pytest.raises(typer.Exit):- agent_error("file not found", error_type="FileNotFoundError", cause=cause)-- parsed = json.loads(capsys.readouterr().err)- assert parsed["error_domain"] == "input"-- def test_app_callback_resets_error_format_to_json(self, mocker: MockerFixture) -> None:- """The error-format ContextVar must be reset per invocation: a markdown command leaving- it set must not leak markdown into a later JSON-only command in the same process.- """- # Simulate a prior markdown command having left the ContextVar set.- set_agent_cli_error_format(CliOutputFormat.MARKDOWN)- mocker.patch("pipelex.cli.agent_cli.commands.plxt_passthrough.shutil.which", return_value=None)-- # `fmt` is a JSON-only command with no --format / --error-format option; with no plxt binary on the- # path it errors via agent_error(). Its error must be JSON, proving the callback reset the format.- result = CliRunner().invoke(app, ["fmt", "bundle.mthds"])-- assert result.exit_code == 1- parsed = json.loads(result.stderr)- assert parsed["error"] is True- assert parsed["error_type"] == "BinaryNotFoundError"diff --git a/tests/unit/pipelex/cli/test_agent_output_drift.py b/tests/unit/pipelex/cli/test_agent_output_drift.pyindex 5c904c84f..01631a18e 100644--- a/tests/unit/pipelex/cli/test_agent_output_drift.py+++ b/tests/unit/pipelex/cli/test_agent_output_drift.py@@ -1,74 +1,55 @@-"""Drift-detection tests for the agent CLI error lookup dicts.+import ast+from pathlib import Path-AGENT_ERROR_HINTS / AGENT_ERROR_DOMAINS are string-keyed by exception class name (or-synthetic error_type label). These tests catch:-- stale keys left behind when an exception class is renamed or deleted;-- a PipelexError subclass in AGENT_ERROR_DOMAINS, whose entry can never be read: every- PipelexError carries a registry code, and the report's domain is that code's.-"""+import pipelex.cli.agent_cli-from pipelex.base_exceptions import PipelexError-from pipelex.cli.agent_cli.commands.agent_output import AGENT_ERROR_DOMAINS, AGENT_ERROR_HINTS-from pipelex.errors.error_class_discovery import iter_pipelex_error_subclasses+# 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"})-# Lookup-dict keys that are intentionally NOT PipelexError subclasses and-# therefore carry no registry code:-# - builtin / third-party exception classes-# - synthetic error_type labels passed straight to agent_error(...)-_NON_PIPELEX_ERROR_KEYS: frozenset[str] = frozenset(- {- "FileNotFoundError", # builtin- "JSONDecodeError", # json builtin- "ValueError", # builtin- "ValidationError", # pydantic- "ArgumentError", # synthetic error_type label- "BinaryNotFoundError", # synthetic error_type label- "FixBundleError", # synthetic error_type label- "BundleError", # synthetic error_type label- "CodegenDriftError", # synthetic error_type label (a drift verdict, not an exception)- "CodegenLockNotFoundError", # synthetic error_type label- "InitConfigError", # synthetic error_type label- "StdinEnvelopeShapeError", # synthetic error_type label- "UnknownCommandError", # synthetic error_type label- }+# The members of the retired envelope, which a problem carries under its own names (code, domain, retry, next_step,+# errors, diagnostics) or not at all.+_RETIRED_ENVELOPE_MEMBERS: frozenset[str] = frozenset(+ {"error", "error_type", "error_domain", "error_code", "error_category", "retryable", "hint", "validation_errors", "error_source"})-def _pipelex_error_names() -> set[str]:- """The name of every PipelexError subclass, every error module force-loaded."""- return {cls.__name__ for cls in iter_pipelex_error_subclasses() if cls is not PipelexError}+# The parameters of ``client.argument_invalid``, which ``agent_argument_error`` takes.+_ARGUMENT_REFUSAL_PARAMS: frozenset[str] = frozenset({"argument", "reason"})-class TestAgentOutputDrift:- """Guards the agent CLI lookup dicts against class renames and unreadable entries."""-- def test_every_dict_key_is_a_known_error_type(self) -> None:- """Every lookup-dict key resolves to a PipelexError subclass or a documented non-PipelexError type."""- known_pipelex_names = _pipelex_error_names()- for key in set(AGENT_ERROR_HINTS) | set(AGENT_ERROR_DOMAINS):- assert key in known_pipelex_names or key in _NON_PIPELEX_ERROR_KEYS, (- f"Lookup-dict key {key!r} is neither a known PipelexError subclass nor a documented "- f"non-PipelexError type — likely a stale entry after a rename or delete."- )+def _reporter_name(*, call: ast.Call) -> str | None:+ match call.func:+ case ast.Name(id=name):+ return name+ case ast.Attribute(attr=name):+ return name+ case _:+ return None- def test_no_documented_non_pipelex_key_is_a_pipelex_error(self) -> None:- """A key documented as carrying no code must not name a PipelexError subclass, which carries one."""- joined = sorted(_NON_PIPELEX_ERROR_KEYS & _pipelex_error_names())- assert not joined, f"These keys now name PipelexError subclasses; drop them from _NON_PIPELEX_ERROR_KEYS: {joined}"- def test_no_pipelex_error_has_a_domain_entry(self) -> None:- """A PipelexError subclass's domain is its code's, so an AGENT_ERROR_DOMAINS entry for it is never read."""- offenders = sorted(set(AGENT_ERROR_DOMAINS) & _pipelex_error_names())+class TestAgentOutputDrift:+ def test_no_call_site_passes_a_member_of_the_retired_envelope(self) -> None:+ """No agent CLI call site passes a member of the envelope the problem replaced.++ ``agent_error`` takes a command's own members as ``**extra``, so a leftover ``error_type=`` or ``hint=`` would+ not fail: it would ride beside the problem under a name consumers used to read as the envelope's.+ """+ 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):+ if not isinstance(node, ast.Call) or _reporter_name(call=node) not in _PROBLEM_REPORTERS:+ continue+ reporter = _reporter_name(call=node)+ for keyword in node.keywords:+ if keyword.arg in _RETIRED_ENVELOPE_MEMBERS:+ offenders.append(f"{source_file.relative_to(package_dir)}:{node.lineno} passes {keyword.arg}=")+ elif reporter == "agent_error" and keyword.arg in _ARGUMENT_REFUSAL_PARAMS:+ # The parameters of client.argument_invalid, passed to agent_error, ride as members of the+ # command's own beside a problem with no code of theirs: the call meant agent_argument_error.+ offenders.append(f"{source_file.relative_to(package_dir)}:{node.lineno} passes {keyword.arg}= to agent_error")assert not offenders, (- f"These AGENT_ERROR_DOMAINS keys name PipelexError subclasses, whose report carries the domain of their code: "- f"{offenders}. Remove the entries; if the domain is wrong, the class needs another code."+ "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_class_level_user_action_not_duplicated_in_dict(self) -> None:- """A subclass that declares class-level user_action must not also sit in AGENT_ERROR_HINTS."""- for cls in iter_pipelex_error_subclasses():- if cls.user_action is not None:- assert cls.__name__ not in AGENT_ERROR_HINTS, (- f"{cls.__name__} carries a class-level user_action; its AGENT_ERROR_HINTS entry "- f"is redundant — remove it so the class is the single source of truth."- )diff --git a/tests/unit/pipelex/cli/test_agent_validate_cmd.py b/tests/unit/pipelex/cli/test_agent_validate_cmd.pyindex 4d07224cf..6026b2d0d 100644--- a/tests/unit/pipelex/cli/test_agent_validate_cmd.py+++ b/tests/unit/pipelex/cli/test_agent_validate_cmd.py@@ -98,8 +98,7 @@ class TestValidateBundleCmd:assert len(json_objects) == 1, f"Expected exactly 1 JSON error on stderr, got {len(json_objects)}. stderr was:\n{stderr_text}"error_obj = json_objects[0]- assert error_obj["error"] is True- assert error_obj["error_type"] == "PipelineExecutionError"+ assert "code" in error_objassert "graph" in error_obj["message"].lower()def test_view_generation_uses_pipe_override(diff --git a/tests/unit/pipelex/cli/test_error_handlers.py b/tests/unit/pipelex/cli/test_error_handlers.pyindex 077a0132d..a53d50b83 100644--- a/tests/unit/pipelex/cli/test_error_handlers.py+++ b/tests/unit/pipelex/cli/test_error_handlers.py@@ -30,7 +30,7 @@ class TestErrorHandlers:def test_handle_model_choice_error_exits_and_reads_the_advice(self, mocker: MockerFixture) -> None:"""handle_model_choice_error should read the advice for its tip and exit with code 1."""- mocker.patch("pipelex.cli.error_handlers.get_console")+ mocker.patch("pipelex.cli.error_handlers.get_error_console")exc = PipeOperatorModelChoiceError(message="model 'gpt-5' not found",pipe_type="llm_text",@@ -50,7 +50,7 @@ class TestErrorHandlers:def test_handle_model_availability_error_exits_and_reads_the_advice(self, mocker: MockerFixture) -> None:"""handle_model_availability_error should read the advice for its tip and exit with code 1."""- mocker.patch("pipelex.cli.error_handlers.get_console")+ mocker.patch("pipelex.cli.error_handlers.get_error_console")exc = PipeOperatorModelAvailabilityError(message="model not available",run_mode=PipeRunMode.LIVE,@@ -70,7 +70,7 @@ class TestErrorHandlers:def test_handle_model_deck_preset_error_exits_and_reads_the_advice(self, mocker: MockerFixture) -> None:"""handle_model_deck_preset_error should read the advice for its tip and exit with code 1."""- mocker.patch("pipelex.cli.error_handlers.get_console")+ mocker.patch("pipelex.cli.error_handlers.get_error_console")exc = ModelDeckPresetValidationError(message="preset references unavailable model",model_type=ModelType.LLM,@@ -87,13 +87,20 @@ class TestErrorHandlers:spy.assert_called_once()def test_handle_validate_bundle_error_exits_and_reads_its_items(self, mocker: MockerFixture) -> None:- """handle_validate_bundle_error should read the verdict's items and exit with code 1."""- mocker.patch("pipelex.cli.error_handlers.get_console")+ """handle_validate_bundle_error should read the verdict's items and exit with code 1.++ The items are read exactly twice: once for the panel's own sections, and once by the problem the panel prints+ rows from, since ``to_problem`` builds its ``errors`` through ``problem_items``. Both reads are the same builder+ over the same error data, so the sections and the problem cannot disagree.+ """+ mocker.patch("pipelex.cli.error_handlers.get_error_console")exc = ValidateBundleError(message="validation failed")spy = mocker.spy(exc, "validation_error_items")+ problem_items_spy = mocker.spy(exc, "problem_items")with pytest.raises(typer.Exit) as exc_info:handle_validate_bundle_error(exc)assert exc_info.value.exit_code == 1- spy.assert_called_once()+ assert spy.call_count == 2+ problem_items_spy.assert_called_once()diff --git a/tests/unit/pipelex/cli/test_error_handlers_more.py b/tests/unit/pipelex/cli/test_error_handlers_more.pyindex a36912f25..b71c4c7a8 100644--- a/tests/unit/pipelex/cli/test_error_handlers_more.py+++ b/tests/unit/pipelex/cli/test_error_handlers_more.py@@ -29,6 +29,7 @@ from pipelex.cogt.inference.error_classification import UserAction, UserActionKifrom pipelex.cogt.model_backends.model_type import ModelTypefrom pipelex.core.exceptions import DryRunFailureErrorData, PipelexBundleBlueprintValidationErrorData, PipesAndConceptValidationErrorDatafrom pipelex.core.validation import MIGRATE_COMMAND+from pipelex.errors.problem import ProblemView, make_location, make_problemfrom pipelex.migration.exceptions import FormerReleaseConfigErrorfrom pipelex.pipeline.exceptions import ValidateBundleErrorfrom pipelex.system.telemetry.exceptions import TelemetryConfigValidationError@@ -43,7 +44,7 @@ class TestErrorHandlersExtended:def console(self, mocker: MockerFixture) -> Console:"""Recorded console patched into the error handlers module."""recorded_console = Console(width=120, record=True, color_system=None)- mocker.patch("pipelex.cli.error_handlers.get_console", return_value=recorded_console)+ mocker.patch("pipelex.cli.error_handlers.get_error_console", return_value=recorded_console)return recorded_consoledef test_display_error_panel_full_layout(self) -> None:@@ -54,6 +55,7 @@ class TestErrorHandlersExtended:title="Something failed",fields=[("Pipe", "'my_pipe'"), ("Model Choice", "'gpt-5'")],error_message="model not found",+ problem=None,tip="try another model",links=[("Docs", "https://docs.example.com")],)@@ -65,6 +67,35 @@ class TestErrorHandlersExtended:assert "💡 Tip: try another model" in outputassert "Docs: https://docs.example.com" in output+ def test_display_error_panel_prints_the_problem_s_rows(self) -> None:+ """The problem's title, next step, code with its verdict, location, request id and run follow the error message."""+ console = Console(width=200, record=True, color_system=None)+ problem = make_problem(+ code=CoreCode.RUNTIME_UNEXPECTED,+ view=ProblemView.OPERATOR,+ location=make_location(pipe="summarize", path=["main", "summarize"]),+ request_id="req-123",+ pipeline_run_id="run-456",+ )+ display_error_panel(+ console=console,+ title="Something failed",+ fields=[("Pipe", "'summarize'")],+ error_message="the step broke",+ problem=problem,+ tip="try again",+ links=[],+ )+ output = console.export_text()+ assert f"Problem: {problem.title}" in output+ assert f"Detail: {problem.detail}" in output+ assert f"Next step: {problem.next_step.detail}" in output+ assert "Code: runtime.unexpected (domain runtime, retry no)" in output+ assert "Location: pipe 'summarize', path main > summarize" in output+ assert "Request id: req-123" in output+ assert "Run: run-456" in output+ assert output.index("Error: the step broke") < output.index("Problem:") < output.index("💡 Tip: try again")+def test_display_error_panel_omits_error_block_when_none(self) -> None:"""A None error_message omits the Error block entirely."""console = Console(width=120, record=True, color_system=None)@@ -73,6 +104,7 @@ class TestErrorHandlersExtended:title="Soft failure",fields=[],error_message=None,+ problem=None,tip="a tip",links=[],)@@ -88,6 +120,7 @@ class TestErrorHandlersExtended:title="Failure",fields=[],error_message=None,+ problem=None,tip="first line\nsecond line",links=[],)@@ -119,20 +152,36 @@ class TestErrorHandlersExtended:assert "anthropic, openai" in outputassert "Possible solutions:" in outputassert "Configure model 'gpt-5' in one of your enabled backends" in output+ # The tip's markup is the handler's own and is rendered, never printed as text.+ assert "[bold]" not in output+ assert "[yellow]" not in outputdef test_handle_model_deck_preset_error_uses_user_action_detail(self, console: Console) -> None:- """When the error carries user-action advice, it becomes the tip verbatim."""+ """When the error carries user-action advice, it becomes the tip verbatim, brackets included and escaped once."""exc = self._make_deck_preset_error(enabled_backends=None)- exc.user_action = UserAction(kind=UserActionKind.CHANGE_MODEL, detail="switch to gpt-4o in the preset")+ exc.user_action = UserAction(kind=UserActionKind.CHANGE_MODEL, detail="switch to 'gpt-4o → SDK[openai]' in the preset")with pytest.raises(typer.Exit):handle_model_deck_preset_error(exc, context=ErrorContext.VALIDATION)output = console.export_text()- assert "switch to gpt-4o in the preset" in output+ assert "💡 Tip: switch to 'gpt-4o → SDK[openai]' in the preset" in output+ assert "\\[" not in outputassert "Possible solutions:" not in outputassert "Enabled Backends:" not in output+ def test_handle_validate_bundle_error_prints_a_bracketed_tip_as_written(self, console: Console) -> None:+ """The verdict's advice is plain text: `SDK[openai]` prints as written, neither swallowed as a style tag nor escaped twice."""+ exc = ValidateBundleError(message="validation failed")+ exc.user_action = UserAction(kind=UserActionKind.CHANGE_MODEL, detail="use 'gpt-4o → SDK[openai]' in the pipe")++ with pytest.raises(typer.Exit):+ handle_validate_bundle_error(exc)++ output = console.export_text()+ assert "💡 Tip: use 'gpt-4o → SDK[openai]' in the pipe" in output+ assert "\\[" not in output+def test_handle_validate_bundle_error_renders_all_sections(self, console: Console) -> None:"""Blueprint, pipe, and dry-run sections all render with their details."""blueprint_error = PipelexBundleBlueprintValidationErrorData(diff --git a/tests/unit/pipelex/cli/test_error_handlers_snapshot.py b/tests/unit/pipelex/cli/test_error_handlers_snapshot.pyindex cdc239b32..402922af4 100644--- a/tests/unit/pipelex/cli/test_error_handlers_snapshot.py+++ b/tests/unit/pipelex/cli/test_error_handlers_snapshot.py@@ -1,8 +1,9 @@"""Snapshot tests for the Rich CLI error panels.Pin the exact plain-text layout produced by the shared ``display_error_panel``-helper, guarding the Phase 7 panel refactor against rendering drift. These are-not load-bearing for production correctness — they protect the refactor.+helper, the problem's rows (title, detail, next step, code, location) included,+guarding the panel against rendering drift. These are not load-bearing for+production correctness — they protect the layout."""from __future__ import annotations@@ -32,6 +33,13 @@ EXPECTED_MODEL_CHOICE_PANEL = ("\n""Error: model 'gpt-5' not found\n""\n"+ "Problem: The method names a model that does not exist\n"+ "Detail: The method names the llm model 'gpt-5', which no catalog knows.\n"+ "Next step: Name a model that exists in place of 'gpt-5', then run the method \n"+ "again.\n"+ "Code: model.unknown (domain method, retry no)\n"+ "Location: pipe 'my_pipe', field 'model'\n"+ "\n""💡 Tip: Check your model configuration in .pipelex/inference/ or specify a \n""different model in the 'my_pipe' pipe.\n""Learn more about the inference backend system: \n"@@ -51,6 +59,10 @@ EXPECTED_MODEL_AVAILABILITY_PANEL = ("\n""Error: model not available\n""\n"+ "Problem: This deployment serves no backend for the model\n"+ "Next step: Correct the runtime's configuration, then restart it.\n"+ "Code: model.unavailable (domain operator, retry no)\n"+ "\n""💡 Tip: Your local model deck may be out of date: new aliases and presets are \n""added to Pipelex over time, and existing '.pipelex/inference/deck/*.toml' files \n""are not refreshed automatically. To pick up the latest definitions, delete your \n"@@ -75,7 +87,7 @@ class TestErrorHandlersSnapshot:def _render(self, mocker: MockerFixture, render: Callable[[], None]) -> str:"""Render a handler to plain text via a fixed-width, color-free Rich console."""console = Console(width=80, record=True, color_system=None)- mocker.patch("pipelex.cli.error_handlers.get_console", return_value=console)+ mocker.patch("pipelex.cli.error_handlers.get_error_console", return_value=console)with pytest.raises(typer.Exit) as exit_info:render()assert exit_info.value.exit_code == 1diff --git a/tests/unit/pipelex/cli/test_failure_panels_on_stderr.py b/tests/unit/pipelex/cli/test_failure_panels_on_stderr.pynew file mode 100644index 000000000..67509a0ba--- /dev/null+++ b/tests/unit/pipelex/cli/test_failure_panels_on_stderr.py@@ -0,0 +1,133 @@+from __future__ import annotations++from typing import TYPE_CHECKING, Callable++import click+import pytest+import typer++from pipelex.cli.error_handlers import (+ ErrorContext,+ handle_former_release_config_error,+ handle_model_availability_error,+ handle_model_choice_error,+ handle_model_deck_preset_error,+ handle_telemetry_config_validation_error,+ handle_validate_bundle_error,+)+from pipelex.cogt.exceptions import ModelDeckPresetValidationError+from pipelex.cogt.model_backends.model_type import ModelType+from pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError+from pipelex.migration.exceptions import FormerReleaseConfigError+from pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError+from pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.system.pipe_run_mode import PipeRunMode+from pipelex.system.telemetry.exceptions import TelemetryConfigValidationError++if TYPE_CHECKING:+ from pytest_mock import MockerFixture+++def _model_choice() -> None:+ exc = PipeOperatorModelChoiceError(+ message="model 'gpt-5' not found",+ pipe_type="llm_text",+ pipe_code="my_pipe",+ domain_code="my_domain",+ field_name="model",+ model_type=ModelType.LLM,+ model_choice="gpt-5",+ )+ try:+ raise exc+ except PipeOperatorModelChoiceError:+ handle_model_choice_error(exc, context=ErrorContext.PIPE_RUN)+++def _model_availability() -> None:+ exc = PipeOperatorModelAvailabilityError(+ message="model not available",+ run_mode=PipeRunMode.LIVE,+ pipe_type="llm_text",+ pipe_code="my_pipe",+ pipe_stack=["my_pipe"],+ model_handle="gpt-4o",+ fallback_list=["gpt-4o-mini"],+ )+ try:+ raise exc+ except PipeOperatorModelAvailabilityError:+ handle_model_availability_error(exc, context=ErrorContext.PIPE_RUN)+++def _deck_preset() -> None:+ exc = ModelDeckPresetValidationError(+ message="preset references unavailable model",+ model_type=ModelType.LLM,+ preset_id="default",+ model_handle="gpt-5",+ enabled_backends={"openai"},+ )+ try:+ raise exc+ except ModelDeckPresetValidationError:+ handle_model_deck_preset_error(exc, context=ErrorContext.VALIDATION)+++def _validate_bundle() -> None:+ exc = ValidateBundleError(message="validation failed")+ try:+ raise exc+ except ValidateBundleError:+ handle_validate_bundle_error(exc)+++def _telemetry() -> None:+ exc = TelemetryConfigValidationError("'custom_posthog.mode': invalid enum value")+ try:+ raise exc+ except TelemetryConfigValidationError:+ handle_telemetry_config_validation_error(exc)+++def _former_release() -> None:+ exc = FormerReleaseConfigError("This configuration was set up by a former Pipelex release.")+ try:+ raise exc+ except FormerReleaseConfigError:+ handle_former_release_config_error(exc=exc)+++class TestFailurePanelsOnStderr:+ @pytest.mark.parametrize(+ ("render", "heading"),+ [+ (_model_choice, "Pipe run failed because of a model choice could not be interpreted correctly"),+ (_model_availability, "Pipe run failed because a model wasn't available"),+ (_deck_preset, "failed due to model deck preset validation error"),+ (_validate_bundle, "Bundle validation failed"),+ (_telemetry, "Telemetry configuration could not be loaded"),+ (_former_release, "Configuration left by a former release"),+ ],+ )+ @pytest.mark.parametrize("traceback_requested", [False, True])+ def test_a_dedicated_panel_and_its_traceback_go_to_stderr(+ self,+ mocker: MockerFixture,+ capsys: pytest.CaptureFixture[str],+ render: Callable[[], None],+ heading: str,+ traceback_requested: bool,+ ) -> None:+ """A failure's panel is the failure's report, so stdout keeps only what the command produced, under --traceback too."""+ mocker.patch("pipelex.cli.error_handlers.is_traceback_requested", return_value=traceback_requested)+ ctx = click.Context(click.Command("test"), obj={"traceback": traceback_requested})++ with ctx, pytest.raises(typer.Exit) as exit_info:+ render()++ assert exit_info.value.exit_code == 1+ captured = capsys.readouterr()+ assert captured.out == ""+ assert heading in captured.err+ assert ("Traceback" in captured.err) is traceback_requesteddiff --git a/tests/unit/pipelex/cli/test_graph_render_cmd.py b/tests/unit/pipelex/cli/test_graph_render_cmd.pyindex ca3f83725..e5d051798 100644--- a/tests/unit/pipelex/cli/test_graph_render_cmd.py+++ b/tests/unit/pipelex/cli/test_graph_render_cmd.py@@ -44,7 +44,7 @@ class TestGraphRenderFailure:telemetry_manager = mocker.patch(f"{GRAPH_CMD}.get_telemetry_manager").return_valuetelemetry_manager.telemetry_context.return_value = contextlib.nullcontext()printed = io.StringIO()- mocker.patch(f"{GRAPH_CMD}.get_console", return_value=Console(file=printed, width=1000))+ mocker.patch(f"{GRAPH_CMD}.get_error_console", return_value=Console(file=printed, width=1000))log_spy = mocker.patch(f"{GRAPH_CMD}.log")spec_dir = tmp_path / bracketed_dir@@ -68,9 +68,11 @@ class TestGraphRenderFailure:assert str(spec_file) in fields["error.message"]assert "\\[" not in fields["error.message"]- def test_an_unexpected_error_logs_its_traceback_once(self, mocker: MockerFixture, tmp_path: Path) -> None:- """The log line is a fixed message with the file, and carries the exception for every sink to write its traceback,- the console under the line; the console prints no traceback of its own, which would show it twice.+ def test_an_unexpected_error_logs_its_identifiers_and_no_traceback(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """The log line is a fixed message with the file, the problem's code and the chain's classes, and no exception.++ The exception's text can quote the graph, a run's traced content, so it reaches the terminal alone; the+ traceback rides the record only under ``--traceback``."""mocker.patch(f"{GRAPH_CMD}.make_pipelex_for_cli")mocker.patch(f"{GRAPH_CMD}.Pipelex.teardown_if_needed")@@ -78,7 +80,7 @@ class TestGraphRenderFailure:telemetry_manager = mocker.patch(f"{GRAPH_CMD}.get_telemetry_manager").return_valuetelemetry_manager.telemetry_context.return_value = contextlib.nullcontext()printed = io.StringIO()- mocker.patch(f"{GRAPH_CMD}.get_console", return_value=Console(file=printed, width=1000))+ mocker.patch(f"{GRAPH_CMD}.get_error_console", return_value=Console(file=printed, width=1000))mocker.patch(f"{GRAPH_CMD}._do_graph_render", side_effect=RuntimeError("the renderer broke"))log_spy = mocker.patch(f"{GRAPH_CMD}.log")@@ -92,7 +94,20 @@ class TestGraphRenderFailure:assert "Failed to render graph" in printed.getvalue()assert "RuntimeError: the renderer broke" in printed.getvalue()assert "Traceback" not in printed.getvalue()- log_spy.error.assert_called_once_with("The graph could not be rendered", fields={"file.path": str(spec_file)}, include_exception=True)+ log_spy.error.assert_called_once()+ (message,), log_kwargs = log_spy.error.call_args+ assert message == "The graph could not be rendered"+ assert log_kwargs["include_exception"] is False+ fields = dict(log_kwargs["fields"])+ frames = fields.pop("error.frames")+ assert fields == {+ "file.path": str(spec_file),+ "error.code": "runtime.unexpected",+ "error.type": "RuntimeError",+ "error.chain": ["RuntimeError"],+ }+ # The failing frame is named, by module, line and function, so the log says where the failure happened.+ assert any(frame.startswith(f"{GRAPH_CMD}:") for frame in frames)@pytest.mark.parametrize("sink_kind", ["console", "json"])def test_an_unexpected_error_names_its_cause_on_the_terminal_whatever_the_sink(@@ -100,7 +115,7 @@ class TestGraphRenderFailure:) -> None:"""Under a sink that does not write to the terminal, the CLI's own output was "Failed to render graph" and nothing else.- The CLI names the exception's type and message itself, and the traceback is printed once, by the log line.+ The CLI names the exception's type and message itself, and the log line names the failure by its code alone."""caplog.set_level(logging.INFO, logger=GRAPH_CMD)mocker.patch(f"{GRAPH_CMD}.make_pipelex_for_cli")@@ -109,7 +124,7 @@ class TestGraphRenderFailure:telemetry_manager = mocker.patch(f"{GRAPH_CMD}.get_telemetry_manager").return_valuetelemetry_manager.telemetry_context.return_value = contextlib.nullcontext()printed = io.StringIO()- mocker.patch(f"{GRAPH_CMD}.get_console", return_value=Console(file=printed, width=1000))+ mocker.patch(f"{GRAPH_CMD}.get_error_console", return_value=Console(file=printed, width=1000))mocker.patch(f"{GRAPH_CMD}._do_graph_render", side_effect=RuntimeError("the renderer broke"))sink_buffer = io.StringIO()sink: LogSink = console_sink_on_buffer(buffer=sink_buffer) if sink_kind == "console" else JsonLogSink(stream=sink_buffer)@@ -126,11 +141,15 @@ class TestGraphRenderFailure:assert "RuntimeError: the renderer broke" in terminalassert "Traceback" not in terminallogged = sink_buffer.getvalue()+ assert "the renderer broke" not in logged+ assert "Traceback" not in loggedif sink_kind == "console":assert "The graph could not be rendered" in logged- assert logged.count("Traceback") == 1+ assert "runtime.unexpected" in loggedelse:(record,) = [json.loads(line) for line in logged.splitlines() if line and json.loads(line)[LOGGER_KEY] == GRAPH_CMD]assert record[MESSAGE_KEY] == "The graph could not be rendered"- assert record[EXCEPTION_KEY].startswith("Traceback")- assert record[EXCEPTION_KEY].rstrip().endswith("RuntimeError: the renderer broke")+ assert EXCEPTION_KEY not in record+ assert record["error.code"] == "runtime.unexpected"+ assert record["error.chain"] == ["RuntimeError"]+ assert any(frame.startswith(f"{GRAPH_CMD}:") for frame in record["error.frames"])diff --git a/tests/unit/pipelex/cli/test_run_core_wrapper.py b/tests/unit/pipelex/cli/test_run_core_wrapper.pyindex c209ec4ac..73b23b055 100644--- a/tests/unit/pipelex/cli/test_run_core_wrapper.py+++ b/tests/unit/pipelex/cli/test_run_core_wrapper.py@@ -16,7 +16,7 @@ from rich.console import Consolefrom pipelex.base_exceptions import PipelexError, PipelexSetupErrorfrom pipelex.cli.commands.run._run_core import execute_run-from pipelex.cli.error_handlers import ErrorContext+from pipelex.cli.error_handlers import ErrorContext, set_traceback_requestedfrom pipelex.cogt.model_backends.backend_credentials import BackendCredentialsErrorMsgFactoryfrom pipelex.cogt.model_backends.model_type import ModelTypefrom pipelex.core.pipes.exceptions import PipeOperatorModelChoiceError@@ -33,6 +33,9 @@ if TYPE_CHECKING:RUN_CORE_MODULE = "pipelex.cli.commands.run._run_core"+# A value a run carries, which a chained exception may quote and no log record may hold.+_PLANTED_RUN_DATA = "patient-4417-diagnosis"+def _call_execute_run(**overrides: Any) -> None:kwargs: dict[str, Any] = {@@ -67,9 +70,13 @@ class TestExecuteRunWrapper:"teardown": mocker.patch("pipelex.cli.commands.run._run_core.Pipelex.teardown_if_needed"),"core": mocker.patch("pipelex.cli.commands.run._run_core._execute_run", new=mocker.AsyncMock(return_value=None)),}+ # A failure's report goes to the error console, stderr; the output console, stdout, is the run's output.recorded_console = Console(width=200, record=True, color_system=None)- mocker.patch("pipelex.cli.commands.run._run_core.get_console", return_value=recorded_console)+ mocker.patch("pipelex.cli.commands.run._run_core.get_error_console", return_value=recorded_console)mocks["console"] = recorded_console+ output_console = Console(width=200, record=True, color_system=None)+ mocker.patch("pipelex.cli.commands.run._run_core.get_console", return_value=output_console)+ mocks["output_console"] = output_consolereturn mocksdef test_happy_path_setup_and_teardown(self, wrapper_mocks: dict[str, Any]) -> None:@@ -164,6 +171,7 @@ class TestExecuteRunWrapper:output = wrapper_mocks["console"].export_text()assert "Failed to execute pipeline" in outputassert message in output+ assert wrapper_mocks["output_console"].export_text() == ""def test_a_missing_credential_message_prints_the_backend_table_as_written(self, wrapper_mocks: dict[str, Any]) -> None:r"""The message names the table as `[openai]`; it used to carry a Rich escape, which the escape here printed as `\[openai]`."""@@ -183,12 +191,8 @@ class TestExecuteRunWrapper:assert "Add 'enabled = false' under '[openai]' in '.pipelex/inference/backends.toml'" in outputassert "\\[" not in output- def test_unexpected_error_logs_its_traceback_and_exits(self, wrapper_mocks: dict[str, Any], mocker: MockerFixture) -> None:- """An unexpected exception is logged at ERROR with its traceback, which the console does not print a second time, and exits 1.-- The traceback used to be printed on the console alone, so under the `json` or `otlp` sink an unexpected- failure's stack never reached the log store.- """+ def test_unexpected_error_logs_identifiers_and_exits(self, wrapper_mocks: dict[str, Any], mocker: MockerFixture) -> None:+ """An unexpected exception prints its problem, is logged at ERROR by its code and classes, with no traceback, and exits 1."""log_mock = mocker.patch("pipelex.cli.commands.run._run_core.log")wrapper_mocks["core"].side_effect = RuntimeError("totally unexpected")@@ -199,21 +203,36 @@ class TestExecuteRunWrapper:output = wrapper_mocks["console"].export_text()assert "Failed to execute pipeline" in outputassert "RuntimeError: totally unexpected" in output+ assert "Code: runtime.unexpected (domain runtime, retry no)" in outputassert "Traceback" not in output- log_mock.error.assert_called_once_with("The pipeline could not be executed", include_exception=True)+ log_mock.error.assert_called_once()+ (message,), log_kwargs = log_mock.error.call_args+ assert message == "The pipeline could not be executed"+ assert log_kwargs["include_exception"] is False+ fields = dict(log_kwargs["fields"])+ frames = fields.pop("error.frames")+ assert fields == {"error.code": "runtime.unexpected", "error.type": "RuntimeError", "error.chain": ["RuntimeError"]}+ # The failing frame is named, by module, line and function, so the log says where the failure happened.+ assert any(frame.startswith(f"{RUN_CORE_MODULE}:") for frame in frames)@pytest.mark.parametrize("sink_kind", ["console", "json"])- def test_unexpected_error_names_its_cause_on_the_terminal_whatever_the_sink(+ def test_no_exception_text_of_the_chain_reaches_the_log_record(self, wrapper_mocks: dict[str, Any], mocker: MockerFixture, caplog: pytest.LogCaptureFixture, sink_kind: str) -> None:- """Under a sink that does not write to the terminal, the CLI's own output was "Failed to execute pipeline" and nothing else.+ """A chained exception's text can quote the run's data: the record names the chain's classes, never their texts.- The CLI names the exception's type and message itself, and the traceback is printed once, by the log line.+ The terminal is the operator's view and names the failure's type and capped message, so the person running+ the command still reads why it failed whatever the sink."""caplog.set_level(logging.INFO, logger=RUN_CORE_MODULE)sink_buffer = io.StringIO()sink: LogSink = console_sink_on_buffer(buffer=sink_buffer) if sink_kind == "console" else JsonLogSink(stream=sink_buffer)- wrapper_mocks["core"].side_effect = RuntimeError("totally unexpected")+ try:+ raise KeyError(_PLANTED_RUN_DATA)+ except KeyError as cause:+ failure = ValueError(f"the function refused {_PLANTED_RUN_DATA}")+ failure.__cause__ = cause+ wrapper_mocks["core"].side_effect = failurewith installed_log(sink=sink) as fresh:mocker.patch(f"{RUN_CORE_MODULE}.log", new=fresh)@@ -222,29 +241,34 @@ class TestExecuteRunWrapper:terminal = wrapper_mocks["console"].export_text()assert "Failed to execute pipeline" in terminal- assert "RuntimeError: totally unexpected" in terminal- assert "Traceback" not in terminal+ assert f"ValueError: the function refused {_PLANTED_RUN_DATA}" in terminallogged = sink_buffer.getvalue()+ assert _PLANTED_RUN_DATA not in logged+ assert "Traceback" not in loggedif sink_kind == "console":assert "The pipeline could not be executed" in logged- assert logged.count("Traceback") == 1+ assert "runtime.unexpected" in loggedelse:(record,) = [json.loads(line) for line in logged.splitlines() if line and json.loads(line)[LOGGER_KEY] == RUN_CORE_MODULE]assert record[MESSAGE_KEY] == "The pipeline could not be executed"- assert record[EXCEPTION_KEY].startswith("Traceback")- assert record[EXCEPTION_KEY].rstrip().endswith("RuntimeError: totally unexpected")-- def test_unexpected_error_reaches_a_structured_sink_with_its_traceback(- self, wrapper_mocks: dict[str, Any], caplog: pytest.LogCaptureFixture- ) -> None:- """The record carries the exception itself, so a structured sink writes the stack the console used to keep to itself."""+ assert EXCEPTION_KEY not in record+ assert record["error.code"] == "runtime.unexpected"+ assert record["error.type"] == "ValueError"+ assert record["error.chain"] == ["ValueError", "KeyError"]+ assert record["error.frames"][0].startswith(f"{RUN_CORE_MODULE}:")++ def test_the_traceback_flag_puts_the_exception_on_the_record(self, wrapper_mocks: dict[str, Any], caplog: pytest.LogCaptureFixture) -> None:+ """Under ``--traceback`` the person running the command asked for every chained text: the record carries the exception."""wrapper_mocks["core"].side_effect = RuntimeError("totally unexpected")- with caplog.at_level(logging.ERROR, logger="pipelex.cli.commands.run._run_core"), pytest.raises(typer.Exit):- _call_execute_run()+ set_traceback_requested(value=True)+ try:+ with caplog.at_level(logging.ERROR, logger=RUN_CORE_MODULE), pytest.raises(typer.Exit):+ _call_execute_run()+ finally:+ set_traceback_requested(value=False)(record,) = [record for record in caplog.records if record.getMessage() == "The pipeline could not be executed"]assert record.levelno == logging.ERRORassert record.exc_info is not Noneassert isinstance(record.exc_info[1], RuntimeError)- assert str(record.exc_info[1]) == "totally unexpected"diff --git a/tests/unit/pipelex/cli/test_show_cmd.py b/tests/unit/pipelex/cli/test_show_cmd.pyindex c8a69881b..47e6836d6 100644--- a/tests/unit/pipelex/cli/test_show_cmd.py+++ b/tests/unit/pipelex/cli/test_show_cmd.py@@ -6,6 +6,7 @@ Covers the do_* functions directly with mocked hub getters — the Typer wrapperfrom __future__ import annotations+from pathlib import Pathfrom types import SimpleNamespacefrom typing import TYPE_CHECKING, Any@@ -16,12 +17,13 @@ from pipelex.base_exceptions import PipelexConfigErrorfrom pipelex.cli.commands.show_cmd import do_list_pipes, do_show_backends, do_show_config, do_show_pipefrom pipelex.cli.exceptions import PipelexCLIErrorfrom pipelex.cogt.model_backends.credential_resolution import CredentialResolution+from pipelex.errors.problem import ProblemViewfrom pipelex.errors.registry.pipelex_codes import PipelexErrorCode+from pipelex.system.configuration.config_loader import CONFIG_NAME+from pipelex.system.environment import CONFIG_DIR_NAMEfrom pipelex.tools.misc.exceptions import TomlErrorif TYPE_CHECKING:- from pathlib import Path-from pytest_mock import MockerFixture@@ -111,6 +113,50 @@ class TestShowCmd:do_show_config()assert exc_info.value.resolve_error_code() == expected_code+ @pytest.mark.usefixtures("no_pipelex_home")+ @pytest.mark.parametrize(+ ("broken_layer", "expected_file"),+ [+ ("project", ".pipelex/pipelex.toml"),+ ("home", "~/.pipelex/pipelex.toml"),+ ],+ )+ def test_do_show_config_names_the_layer_that_does_not_parse(+ self, mocker: MockerFixture, tmp_path: Path, broken_layer: str, expected_file: str+ ) -> None:+ """A syntax error names the layer at fault, where its line and column are, without the home directory."""+ home_dir = tmp_path / "home"+ project_dir = home_dir / "project"+ (project_dir / ".git").mkdir(parents=True)+ broken_dir = (project_dir if broken_layer == "project" else home_dir) / CONFIG_DIR_NAME+ broken_dir.mkdir(parents=True, exist_ok=True)+ (broken_dir / CONFIG_NAME).write_text("[pipelex\n", encoding="utf-8")+ mocker.patch.object(Path, "home", return_value=home_dir)+ mocker.patch.object(Path, "cwd", return_value=project_dir)++ with pytest.raises(PipelexConfigError) as exc_info:+ do_show_config()++ assert exc_info.value.resolve_error_code() == PipelexErrorCode.CONFIG_SYNTAX+ assert exc_info.value.file == expected_file+ step = exc_info.value.to_problem(view=ProblemView.OPERATOR).next_step.detail+ assert step.startswith(f"Fix the TOML of the file '{expected_file}' of the pipelex configuration at line 1, column ")+ assert str(tmp_path) not in step++ @pytest.mark.usefixtures("no_pipelex_home")+ def test_do_show_config_names_the_file_it_cannot_read(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A file the load cannot open is named as the OS named it, without the home directory, never as the base file's name."""+ home_dir = tmp_path / "home"+ unreadable = home_dir / CONFIG_DIR_NAME / "pipelex_override.toml"+ mocker.patch.object(Path, "home", return_value=home_dir)+ mocked_manager = mocker.patch("pipelex.cli.commands.show_cmd.config_manager")+ mocked_manager.load_config.side_effect = PermissionError(13, "Permission denied", str(unreadable))++ with pytest.raises(PipelexConfigError) as exc_info:+ do_show_config()++ assert exc_info.value.file == "~/.pipelex/pipelex_override.toml"+def test_do_list_pipes_tracks_pipe_count(self, mocker: MockerFixture, telemetry: Any) -> None:"""Listing pipes delegates to the library and reports the count to telemetry."""pipe_library = mocker.Mock()diff --git a/tests/unit/pipelex/cli/test_stdin_resolver.py b/tests/unit/pipelex/cli/test_stdin_resolver.pyindex da5ef04f5..7e34ba412 100644--- a/tests/unit/pipelex/cli/test_stdin_resolver.py+++ b/tests/unit/pipelex/cli/test_stdin_resolver.py@@ -178,7 +178,7 @@ class TestStdinResolver:def test_concept_object_form_is_refused(self, capsys: pytest.CaptureFixture[str]) -> None:"""The full-object concept a stale runtime dumped is refused, never reduced to a bare code.- The label is a shape error, not a decode error: the envelope parsed, so a consumer must not+ The reason is the shape, not a decode error: the envelope parsed, so a consumer must notbe told to go hunting for trailing commas in JSON that was valid."""set_agent_cli_error_format(CliOutputFormat.JSON)@@ -196,10 +196,13 @@ class TestStdinResolver:with pytest.raises(typer.Exit) as exc_info:resolve_stdin_inputs(data)assert exc_info.value.exit_code == 1- envelope = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "StdinEnvelopeShapeError"- assert "working_memory.root.item.concept" in envelope["message"]- assert "trailing commas" not in envelope["hint"]+ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "client.argument_invalid"+ assert problem["params"] == {"argument": "stdin", "reason": "working_memory.root.item.concept is not a concept ref string"}+ assert "working_memory.root.item.concept" in problem["message"]+ # The way out the refusal names: the concept's ref, or a fresh envelope from a current run.+ assert "Replace the concept object with its ref, or re-pipe the output of a current 'pipelex-agent run --with-memory'." in problem["message"]+ assert "valid JSON" not in problem["detail"]def test_stuff_missing_concept_skipped(self) -> None:"""Stuff entries missing concept or content are silently skipped."""@@ -380,8 +383,8 @@ class TestStdinResolver:assert result.pipeline_inputs == {"contract_text": {"concept": "Text", "content": "First line.\nSecond line.\n"}}- def test_inputs_toml_syntax_error_envelope(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:- """Invalid TOML in a .toml inputs file emits a TomlError envelope with input domain."""+ def test_inputs_toml_syntax_error_problem(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ """Invalid TOML in a .toml inputs file is the request's problem, request.malformed, in the input domain."""set_agent_cli_error_format(CliOutputFormat.JSON)toml_file = tmp_path / "inputs.toml"toml_file.write_text("topic = \n", encoding="utf-8")@@ -390,10 +393,10 @@ class TestStdinResolver:parse_cli_inputs(inputs_arg=str(toml_file))assert exc_info.value.exit_code == 1- envelope = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "TomlError"- assert envelope["error_domain"] == "input"- assert "hint" in envelope+ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "request.malformed"+ assert problem["domain"] == "input"+ assert problem["diagnostics"]["error_class"] == "TomlError"def test_inputs_toml_time_only_becomes_time_content(self, tmp_path: Path) -> None:"""A bare TOML time-of-day input maps to a native Time content (no rejection since native.Time exists)."""@@ -405,8 +408,8 @@ class TestStdinResolver:assert parsed.pipeline_inputs is not Noneassert parsed.pipeline_inputs["opening"] == TimeContent(time=datetime.time(9, 0))- def test_inputs_json_syntax_error_envelope(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:- """Invalid JSON in a .json inputs file emits a JSONDecodeError envelope (not a raw traceback)."""+ def test_inputs_json_syntax_error_problem(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ """Invalid JSON in a .json inputs file is an argument refusal naming --inputs (not a raw traceback)."""set_agent_cli_error_format(CliOutputFormat.JSON)json_file = tmp_path / "inputs.json"json_file.write_text("{not valid json", encoding="utf-8")@@ -415,8 +418,48 @@ class TestStdinResolver:parse_cli_inputs(inputs_arg=str(json_file))assert exc_info.value.exit_code == 1- envelope = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "JSONDecodeError"+ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "client.argument_invalid"+ assert problem["params"] == {"argument": "--inputs", "reason": "the file is not valid JSON"}+ assert problem["diagnostics"]["error_class"] == "JSONDecodeError"++ def test_an_inputs_file_holding_no_object_names_the_argument(self, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:+ """A JSON inputs file holding an array is the caller's argument to correct, never the runtime's catch-all."""+ set_agent_cli_error_format(CliOutputFormat.JSON)+ json_file = tmp_path / "inputs.json"+ json_file.write_text("[1, 2]", encoding="utf-8")++ with pytest.raises(typer.Exit):+ parse_cli_inputs(inputs_arg=str(json_file))++ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "client.argument_invalid"+ assert problem["params"] == {"argument": "--inputs", "reason": "the file does not hold a JSON object"}++ @pytest.mark.parametrize(+ ("body", "reason"),+ [+ (None, "is a directory"),+ (b"\xff\xfe{}", "not UTF-8 text"),+ ],+ )+ def test_an_inputs_file_that_cannot_be_read_is_a_file_refusal(+ self, tmp_path: Path, capsys: pytest.CaptureFixture[str], body: bytes | None, reason: str+ ) -> None:+ """A path that is a directory, or a file that is not text, is `client.file_unreadable` with the system's reason."""+ set_agent_cli_error_format(CliOutputFormat.JSON)+ inputs_path = tmp_path / "inputs.json"+ if body is None:+ inputs_path.mkdir()+ else:+ inputs_path.write_bytes(body)++ with pytest.raises(typer.Exit):+ parse_cli_inputs(inputs_arg=str(inputs_path))++ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "client.file_unreadable"+ assert problem["params"] == {"path": str(inputs_path), "reason": reason}# -------------------------------------------------------------------------# auto_inputs_dir precedence tests@@ -491,7 +534,7 @@ class TestStdinResolver:def test_ambiguous_auto_dir_raises_when_no_stdin(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Any, capsys: pytest.CaptureFixture[str]) -> None:- """With no stdin and both default files present, auto-detect is the active source and emits the ambiguity envelope."""+ """With no stdin and both default files present, auto-detect is the active source and reports the ambiguity's problem."""set_agent_cli_error_format(CliOutputFormat.JSON)(tmp_path / "inputs.json").write_text('{"from_auto": true}')(tmp_path / "inputs.toml").write_text("from_auto = true\n")@@ -504,7 +547,8 @@ class TestStdinResolver:parse_cli_inputs(inputs_arg=None, auto_inputs_dir=tmp_path)assert exc_info.value.exit_code == 1- envelope = json.loads(capsys.readouterr().err)- assert envelope["error_type"] == "AmbiguousInputsFilesError"- assert envelope["error_domain"] == "input"- assert "--inputs" in envelope["hint"]+ problem = json.loads(capsys.readouterr().err)+ assert problem["code"] == "request.invalid"+ assert problem["domain"] == "input"+ assert problem["diagnostics"]["error_class"] == "AmbiguousInputsFilesError"+ assert "--inputs" in problem["message"]diff --git a/tests/unit/pipelex/cli/test_traceback_flag_error_handlers.py b/tests/unit/pipelex/cli/test_traceback_flag_error_handlers.pyindex eff75946b..44a2d6311 100644--- a/tests/unit/pipelex/cli/test_traceback_flag_error_handlers.py+++ b/tests/unit/pipelex/cli/test_traceback_flag_error_handlers.py@@ -37,7 +37,7 @@ class TestTracebackFlagInErrorHandlers:def test_handler_prints_traceback_when_flag_active(self, mocker: MockerFixture) -> None:"""handle_model_deck_preset_error prints traceback when --traceback is set."""mock_console = mocker.MagicMock()- mocker.patch("pipelex.cli.error_handlers.get_console", return_value=mock_console)+ mocker.patch("pipelex.cli.error_handlers.get_error_console", return_value=mock_console)exc = _deck_preset_error()ctx = click.Context(click.Command("test"), obj={"traceback": True})@@ -55,7 +55,7 @@ class TestTracebackFlagInErrorHandlers:def test_handler_does_not_print_traceback_when_flag_absent(self, mocker: MockerFixture) -> None:"""handle_model_deck_preset_error does NOT print traceback without --traceback."""mock_console = mocker.MagicMock()- mocker.patch("pipelex.cli.error_handlers.get_console", return_value=mock_console)+ mocker.patch("pipelex.cli.error_handlers.get_error_console", return_value=mock_console)exc = _deck_preset_error()ctx = click.Context(click.Command("test"), obj={"traceback": False})diff --git a/tests/unit/pipelex/cli/test_traceback_flag_run_core.py b/tests/unit/pipelex/cli/test_traceback_flag_run_core.pyindex e8fa4c149..e1e538093 100644--- a/tests/unit/pipelex/cli/test_traceback_flag_run_core.py+++ b/tests/unit/pipelex/cli/test_traceback_flag_run_core.py@@ -51,7 +51,7 @@ class TestTracebackFlagInExecuteRunInnerExcepts:pipe_stack=["test-pipe"],)- mocker.patch("pipelex.cli.commands.run._run_core.get_console", return_value=mock_console)+ mocker.patch("pipelex.cli.commands.run._run_core.get_error_console", return_value=mock_console)mock_runner_cls = mocker.patch("pipelex.cli.commands.run._run_core.PipelexMTHDSProtocol")mock_runner = mocker.MagicMock()@@ -96,7 +96,7 @@ class TestTracebackFlagInExecuteRunInnerExcepts:def test_bundle_file_not_found_prints_traceback(self, mocker: MockerFixture) -> None:"""FileNotFoundError for bundle in _execute_run prints traceback when --traceback is active."""mock_console = mocker.MagicMock()- mocker.patch("pipelex.cli.commands.run._run_core.get_console", return_value=mock_console)+ mocker.patch("pipelex.cli.commands.run._run_core.get_error_console", return_value=mock_console)ctx = click.Context(click.Command("run"), obj={"traceback": True})with ctx, pytest.raises(typer.Exit):@@ -125,7 +125,7 @@ class TestTracebackFlagInExecuteRunInnerExcepts:def test_json_decode_error_prints_traceback(self, mocker: MockerFixture) -> None:"""json.JSONDecodeError for inline inputs prints traceback when --traceback is active."""mock_console = mocker.MagicMock()- mocker.patch("pipelex.cli.commands.run._run_core.get_console", return_value=mock_console)+ mocker.patch("pipelex.cli.commands.run._run_core.get_error_console", return_value=mock_console)ctx = click.Context(click.Command("run"), obj={"traceback": True})with ctx, pytest.raises(typer.Exit):@@ -154,7 +154,7 @@ class TestTracebackFlagInExecuteRunInnerExcepts:def test_no_traceback_when_flag_absent(self, mocker: MockerFixture) -> None:"""FileNotFoundError for bundle does NOT print traceback when --traceback is False."""mock_console = mocker.MagicMock()- mocker.patch("pipelex.cli.commands.run._run_core.get_console", return_value=mock_console)+ mocker.patch("pipelex.cli.commands.run._run_core.get_error_console", return_value=mock_console)ctx = click.Context(click.Command("run"), obj={"traceback": False})with ctx, pytest.raises(typer.Exit):diff --git a/tests/unit/pipelex/cli/test_usage_stats_cli.py b/tests/unit/pipelex/cli/test_usage_stats_cli.pyindex 272393ff1..da02a33df 100644--- a/tests/unit/pipelex/cli/test_usage_stats_cli.py+++ b/tests/unit/pipelex/cli/test_usage_stats_cli.py@@ -18,13 +18,14 @@ from pipelex.system.usage_stats.usage_stats_client import (UsageStatsClient,configure_usage_stats_for_cli,configure_usage_stats_for_runtime,- note_command_error_domain,+ note_command_error,note_command_hosted,show_usage_stats_notice,)from pipelex.system.usage_stats.usage_stats_contract import (NOTICE_VERSION,UsageStatsEnvVar,+ UsageStatsError,UsageStatsErrorDomain,UsageStatsProvider,UsageStatsSurface,@@ -59,7 +60,7 @@ def _succeed() -> None:def _fail_with_input_error() -> None:- note_command_error_domain(error_domain=UsageStatsErrorDomain.INPUT)+ note_command_error(error=UsageStatsError(code="client.argument_invalid", domain=UsageStatsErrorDomain.INPUT))raise SystemExit(1)@@ -144,7 +145,29 @@ class TestUsageStatsCli:False,),(UsageStatsSurface.PIPELEX_AGENT, ["inputs", "pipe", "my_pipe"], "inputs pipe", True),+ # `inputs`' `--format` is a template's serialization, which its errors never follow.+ (UsageStatsSurface.PIPELEX_AGENT, ["inputs", "pipe", "my_pipe", "--format", "toml"], "inputs pipe", True),(UsageStatsSurface.PIPELEX_AGENT, ["models"], "models", False),+ # The program's `--error-format`, given before the command, wins over the command's `--format`...+ (UsageStatsSurface.PIPELEX_AGENT, ["--error-format", "json", "validate", "bundle", "x.mthds"], "validate bundle", True),+ (UsageStatsSurface.PIPELEX_AGENT, ["--error-format=json", "validate", "bundle", "x.mthds"], "validate bundle", True),+ (UsageStatsSurface.PIPELEX_AGENT, ["--error-format", "json", "models"], "models", True),+ (+ UsageStatsSurface.PIPELEX_AGENT,+ ["--error-format", "markdown", "validate", "bundle", "x.mthds", "--format", "json"],+ "validate bundle",+ False,+ ),+ (UsageStatsSurface.PIPELEX_AGENT, ["--error-format", "markdown", "inputs", "pipe", "my_pipe"], "inputs pipe", False),+ # ...and the command's own `--error-format` wins over the program's.+ (+ UsageStatsSurface.PIPELEX_AGENT,+ ["--error-format", "json", "validate", "bundle", "x.mthds", "--error-format", "markdown"],+ "validate bundle",+ False,+ ),+ (UsageStatsSurface.PIPELEX_AGENT, ["no-such-command"], "other", True),+ (UsageStatsSurface.PIPELEX_AGENT, ["--error-format", "markdown", "no-such-command"], "other", False),],)def test_invocation_is_resolved_without_reading_arguments(@@ -192,12 +215,35 @@ class TestUsageStatsCli:assert events[0]["properties"]["surface"] == "pipelex-agent"assert events[0]["properties"]["outcome"] == "failed"assert events[0]["properties"]["error_domain"] == "input"+ assert events[0]["properties"]["error_code"] == "client.argument_invalid"++ def test_the_program_s_error_format_keeps_the_notice_off_a_json_problem(+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]+ ) -> None:+ """`pipelex-agent --error-format json validate bundle …` writes one JSON problem on stderr, and no notice ahead of it.++ The command's own default is Markdown, so reading the command's options alone took the stream for one a person+ reads, printed the notice first, and left stderr no longer parseable as the JSON its caller asked for.+ """+ # Refused before any boot: the session's own Pipelex stays out of it.+ not_a_bundle = tmp_path / "notes.txt"+ with usage_stats_switched_on(monkeypatch=monkeypatch, home=tmp_path / "home", cwd=make_project_dir(parent=tmp_path), is_debug=False) as state:+ with pytest.raises(SystemExit) as exit_info:+ _root_of(UsageStatsSurface.PIPELEX_AGENT).main(+ args=["--error-format", "json", "validate", "bundle", str(not_a_bundle)], prog_name="pipelex-agent"+ )+ captured = capsys.readouterr()+ assert exit_info.value.code != 0+ assert captured.out == ""+ problem: dict[str, Any] = json.loads(captured.err)+ assert problem["code"] == "client.argument_invalid"+ assert not state.notice_marker(version=NOTICE_VERSION).exists()@pytest.mark.parametrize(("invoke", "expected"),[(_succeed, {"outcome": "succeeded"}),- (_fail_with_input_error, {"outcome": "failed", "error_domain": "input"}),+ (_fail_with_input_error, {"outcome": "failed", "error_code": "client.argument_invalid", "error_domain": "input"}),(_interrupted, {"outcome": "cancelled"}),(_cancelled_exit, {"outcome": "cancelled"}),(_hosted_run, {"outcome": "succeeded", "hosted": True}),@@ -223,6 +269,7 @@ class TestUsageStatsCli:for name, value in expected.items():assert properties[name] == valueassert ("error_domain" in properties) is ("error_domain" in expected)+ assert ("error_code" in properties) is ("error_code" in expected)assert ("hosted" in properties) is ("hosted" in expected)@pytest.mark.parametrize(diff --git a/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py b/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.pyindex b166a8b17..3db70db2d 100644--- a/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py+++ b/tests/unit/pipelex/cli/test_validate_suggested_fix_rendering.py@@ -70,7 +70,7 @@ class TestValidateSuggestedFixRendering:def console(self, mocker: MockerFixture) -> Console:"""Recorded console patched into the error handlers module."""recorded_console = Console(width=200, record=True, color_system=None)- mocker.patch("pipelex.cli.error_handlers.get_console", return_value=recorded_console)+ mocker.patch("pipelex.cli.error_handlers.get_error_console", return_value=recorded_console)return recorded_consoledef test_fixable_error_renders_suggested_fix_line_and_actionable_footer(self, console: Console) -> None:diff --git a/tests/unit/pipelex/cogt/models/test_model_manager_former_release.py b/tests/unit/pipelex/cogt/models/test_model_manager_former_release.pyindex ef56b342b..91cc7da76 100644--- a/tests/unit/pipelex/cogt/models/test_model_manager_former_release.py+++ b/tests/unit/pipelex/cogt/models/test_model_manager_former_release.py@@ -12,6 +12,7 @@ files laid over it, copied from that release's wheel.from __future__ import annotations+import loggingimport shutilfrom pathlib import Pathfrom typing import TYPE_CHECKING@@ -20,12 +21,19 @@ import pytestfrom pipelex.base_exceptions import PipelexSetupErrorfrom pipelex.cogt.models.model_manager import ModelManager+from pipelex.core.validation import MIGRATE_COMMAND+from pipelex.errors.problem import ProblemViewfrom pipelex.kit.paths import get_kit_configs_dirfrom pipelex.migration.exceptions import FormerReleaseConfigErrorfrom pipelex.migration.former_release import kit_default_routing_profile_namefrom pipelex.migration.former_release_cleanup import clean_former_releasefrom pipelex.plugins.plugin_model_declarations import PluginModelDeclarations-from pipelex.system.configuration.config_loader import BACKENDS_FILE_NAME, INFERENCE_DIR_NAME, ROUTING_PROFILES_OVERRIDE_FILE_NAME+from pipelex.system.configuration.config_loader import (+ BACKENDS_FILE_NAME,+ INFERENCE_DIR_NAME,+ ROUTING_PROFILES_OVERRIDE_FILE_NAME,+ config_manager,+)from pipelex.system.environment import CONFIG_DIR_NAMEfrom pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider@@ -93,6 +101,48 @@ class TestAFormerReleaseHomeAtBoot:message = str(refused.value)assert "'all_pipelex_gateway'" in messageassert "enables the 'pipelex_gateway' backend" not in message+ # The step names the first blocker: the routing profile file making the Gateway's profile active.+ step = refused.value.to_problem(view=ProblemView.OPERATOR).next_step.detail+ assert step.startswith("Correct the setting 'active' in the file '")+ assert step.endswith("' of the inference configuration, then restart the runtime.")++ def test_the_refusal_s_step_names_the_first_blocker(self, home_config_dir: Path, caplog: pytest.LogCaptureFixture) -> None:+ """The code's step renders from the first blocker, the enabled Gateway table, and never falls back on the generic sentence."""+ with pytest.raises(FormerReleaseConfigError) as refused:+ _setup(needs_inference=False)++ with caplog.at_level(logging.WARNING, logger="pipelex.errors.problem"):+ problem = refused.value.to_problem(view=ProblemView.OPERATOR)+ # The file is named under the home directory as `~/…`: a step an agent reads, prints and logs names no account.+ backends_label = f"~/{CONFIG_DIR_NAME}/{INFERENCE_DIR_NAME}/{BACKENDS_FILE_NAME}"+ assert problem.next_step.detail == (+ f"Correct the setting 'pipelex_gateway' in the file '{backends_label}' of the inference configuration, then restart the runtime."+ )+ assert str(home_config_dir) not in problem.next_step.detail+ assert not [record for record in caplog.records if record.name == "pipelex.errors.problem"]++ def test_the_refusal_carries_what_pipelex_migrate_would_do(self, home_config_dir: Path) -> None:+ """A JSON reader, who gets no tip, reads the remedy off `diagnostics.migration`: the cleanup would write, and needs nobody."""+ assert home_config_dir.is_dir()+ with pytest.raises(FormerReleaseConfigError) as refused:+ _setup(needs_inference=False)++ wire = refused.value.to_problem(view=ProblemView.OPERATOR).to_wire()+ assert wire["diagnostics"]["error_class"] == "FormerReleaseConfigError"+ assert wire["diagnostics"]["migration"] == {"remedy": MIGRATE_COMMAND, "would_write": True, "needs_attention": False, "plans": []}+ assert "diagnostics" not in refused.value.to_problem(view=ProblemView.CALLER).to_wire()++ def test_a_refusal_the_walk_cannot_reach_needs_attention(self, home_config_dir: Path, mocker: MockerFixture) -> None:+ """When `pipelex migrate` walks no directory holding the blockers, the block says the command repairs nothing."""+ assert home_config_dir.is_dir()+ mocker.patch.object(type(config_manager), "existing_config_dirs", new_callable=mocker.PropertyMock, return_value=[])++ with pytest.raises(FormerReleaseConfigError) as refused:+ _setup(needs_inference=False)++ migration = refused.value.to_problem(view=ProblemView.OPERATOR).to_wire()["diagnostics"]["migration"]+ assert migration["would_write"] is False+ assert migration["needs_attention"] is Truedef test_a_home_whose_overrides_moved_it_off_the_gateway_boots(self, home_config_dir: Path) -> None:"""Only what stops the boot is refused: what is inert is left for `pipelex migrate` and the doctor to report."""diff --git a/tests/unit/pipelex/core/test_validation_report.py b/tests/unit/pipelex/core/test_validation_report.pyindex 11c488521..27e207876 100644--- a/tests/unit/pipelex/core/test_validation_report.py+++ b/tests/unit/pipelex/core/test_validation_report.py@@ -21,6 +21,7 @@ Three properties are what the tests below exist to hold:from __future__ import annotationsimport json+import loggingfrom pathlib import Pathfrom typing import TYPE_CHECKING@@ -312,6 +313,35 @@ class TestTheErrorCarriesBothTheDomainAndTheBlock:assert diagnostics is not Noneassert diagnostics.migration is None+ @pytest.mark.usefixtures("machine")+ @pytest.mark.parametrize(+ ("surface_id", "expected_step"),+ [+ (+ PIPELEX_CONFIG_SURFACE_ID,+ "Correct the setting 'required_field' in the file 'pipelex.toml' of the pipelex configuration, then restart the runtime.",+ ),+ (+ TELEMETRY_CONFIG_SURFACE_ID,+ "Correct the setting 'required_field' in the file 'telemetry.toml' of the telemetry configuration, then restart the runtime.",+ ),+ ],+ )+ def test_the_operator_s_step_names_the_setting_the_file_and_the_surface(+ self, surface_id: str, expected_step: str, caplog: pytest.LogCaptureFixture+ ) -> None:+ """The code's step renders from the parameters the refusal gives, never falling back on the generic sentence."""+ refusal = ConfigValidationError("the configuration was refused")+ refusal.__cause__ = _make_validation_error()++ with pytest.raises(PipelexConfigError) as raised:+ raise_config_setup_error(config_error=refusal, surface_id=surface_id)++ with caplog.at_level(logging.WARNING, logger="pipelex.errors.problem"):+ problem = raised.value.to_problem(view=ProblemView.OPERATOR)+ assert problem.next_step.detail == expected_step+ assert not [record for record in caplog.records if record.name == "pipelex.errors.problem"]+def test_a_refusal_carrying_no_pydantic_error_is_re_raised_as_itself(self) -> None:"""There is nothing to translate, and its own message is already the whole account."""refusal = ConfigValidationError("the configuration directory is not readable")diff --git a/tests/unit/pipelex/errors/test_failure_problem.py b/tests/unit/pipelex/errors/test_failure_problem.pynew file mode 100644index 000000000..32623d291--- /dev/null+++ b/tests/unit/pipelex/errors/test_failure_problem.py@@ -0,0 +1,154 @@+from __future__ import annotations++from typing import TYPE_CHECKING++import pytest+from mthds.protocol.problem.registry import CoreCode+from pydantic import BaseModel, ValidationError++from pipelex.base_exceptions import PipelexError+from pipelex.errors.failure_problem import (+ MAX_LOGGED_FRAMES,+ failure_log_fields,+ failure_problem,+ format_problem_location,+ format_problem_verdict,+)+from pipelex.errors.problem import ProblemView, make_location+from pipelex.migration.exceptions import FormerReleaseConfigError++if TYPE_CHECKING:+ from mthds.protocol.problem.models import ProblemLocation++# A value a run carries, which an exception's text may quote and no log line may hold.+_PLANTED_RUN_DATA = "invoice-9921-iban-FR7630006000011234567890189"+++class _Invoice(BaseModel):+ amount: int+++def _chained_failure() -> ValueError:+ """A method function's exception quoting the run's data, raised from a foreign validation error that quotes it too."""+ try:+ _Invoice.model_validate({"amount": _PLANTED_RUN_DATA})+ except ValidationError as validation_error:+ failure = ValueError(f"could not total {_PLANTED_RUN_DATA}")+ failure.__cause__ = validation_error+ return failure+ msg = "the planted value validated"+ raise AssertionError(msg)+++# A marker on the source line of a raise, which a logged frame never quotes.+_SOURCE_MARKER = "SOURCE-LINE-MARKER-5512"+++def _total_of(*, value: str) -> int:+ planted_local = value+ raise KeyError(planted_local) # SOURCE-LINE-MARKER-5512+++def _raise_a_wrapped_fault(*, value: str) -> None:+ try:+ _total_of(value=value)+ except KeyError as fault:+ msg = f"the step failed on {value}"+ raise PipelexError(msg) from fault+++def _recurse(*, depth: int) -> None:+ if depth == 0:+ msg = "the bottom"+ raise KeyError(msg)+ _recurse(depth=depth - 1)+++class TestFailureProblem:+ def test_a_foreign_failure_is_runtime_unexpected_with_its_class_and_capped_message_in_the_diagnostics(self) -> None:+ """The operator view holds the message, capped: it is the terminal's to print, never a log line's."""+ failure = _chained_failure()++ problem = failure_problem(error=failure)++ assert problem.code == CoreCode.RUNTIME_UNEXPECTED+ assert problem.diagnostics is not None+ assert problem.diagnostics.error_class == "ValueError"+ assert problem.diagnostics.message == f"could not total {_PLANTED_RUN_DATA}"+ assert [cause.error_class for cause in problem.diagnostics.causes or []] == ["ValidationError"]++ def test_a_pipelex_failure_is_its_own_problem(self) -> None:+ failure = FormerReleaseConfigError("a former release left its gateway backend enabled")++ assert failure_problem(error=failure) == failure.to_problem(view=ProblemView.OPERATOR)++ def test_the_log_fields_name_the_code_and_the_chain_s_classes_and_no_text(self) -> None:+ """No chained exception's text reaches the fields, the foreign ``ValidationError``'s included."""+ failure = _chained_failure()++ fields = failure_log_fields(error=failure, problem=failure_problem(error=failure))++ frames = fields.pop("error.frames")+ assert fields == {"error.code": "runtime.unexpected", "error.type": "ValueError", "error.chain": ["ValueError", "ValidationError"]}+ assert all(isinstance(frame, str) for frame in frames)+ assert _PLANTED_RUN_DATA not in repr(fields)+ assert _PLANTED_RUN_DATA not in repr(frames)++ def test_the_log_fields_name_the_frames_down_to_the_fault_without_source_or_locals(self) -> None:+ """The frames go from where the failure was caught down to where its first exception was raised, by module, line and function."""+ with pytest.raises(PipelexError) as caught:+ _raise_a_wrapped_fault(value=_PLANTED_RUN_DATA)+ failure = caught.value++ frames = failure_log_fields(error=failure, problem=failure_problem(error=failure))["error.frames"]++ module = __name__+ assert frames[0].startswith(f"{module}:")+ assert frames[0].endswith(" in test_the_log_fields_name_the_frames_down_to_the_fault_without_source_or_locals")+ assert [frame.rsplit(" in ", 1)[1] for frame in frames[1:]] == ["_raise_a_wrapped_fault", "_raise_a_wrapped_fault", "_total_of"]+ assert all(frame.startswith(f"{module}:") for frame in frames)+ # No source line, whose comment carries a marker, and no local, which holds the run's data.+ assert _SOURCE_MARKER not in repr(frames)+ assert _PLANTED_RUN_DATA not in repr(frames)++ def test_the_frames_keep_the_innermost_of_a_deep_failure(self) -> None:+ with pytest.raises(KeyError) as caught:+ _recurse(depth=MAX_LOGGED_FRAMES * 2)+ failure = caught.value++ frames = failure_log_fields(error=failure, problem=failure_problem(error=failure))["error.frames"]++ assert len(frames) == MAX_LOGGED_FRAMES+ assert frames[-1].endswith(" in _recurse")++ def test_the_log_fields_of_a_pipelex_failure_carry_its_code(self) -> None:+ try:+ raise KeyError(_PLANTED_RUN_DATA)+ except KeyError as cause:+ failure = PipelexError(f"the step failed on {_PLANTED_RUN_DATA}")+ failure.__cause__ = cause++ problem = failure_problem(error=failure)+ fields = failure_log_fields(error=failure, problem=problem)++ assert fields["error.code"] == problem.code+ assert fields["error.chain"] == ["PipelexError", "KeyError"]+ assert _PLANTED_RUN_DATA not in repr(fields)++ @pytest.mark.parametrize(+ ("location", "expected"),+ [+ (None, ""),+ (make_location(pipe="summarize", path=["main", "summarize"]), "pipe 'summarize', path main > summarize"),+ (make_location(input_name="invoice", field="amount"), "input 'invoice', field 'amount'"),+ (make_location(item=2, attempt=3), "item 2, attempt 3"),+ (make_location(file="contracts.mthds", line=12, column=4), "file 'contracts.mthds', line 12, column 4"),+ ],+ )+ def test_a_location_reads_as_words(self, location: ProblemLocation | None, expected: str) -> None:+ assert format_problem_location(location=location) == expected++ def test_the_verdict_names_the_domain_and_the_retry(self) -> None:+ problem = failure_problem(error=RuntimeError("boom"))++ assert format_problem_verdict(problem=problem) == "domain runtime, retry no"diff --git a/tests/unit/pipelex/pipe_run/test_pipe_run_usage_stats.py b/tests/unit/pipelex/pipe_run/test_pipe_run_usage_stats.pyindex 0d8bd1ac3..d7138fcc4 100644--- a/tests/unit/pipelex/pipe_run/test_pipe_run_usage_stats.py+++ b/tests/unit/pipelex/pipe_run/test_pipe_run_usage_stats.py@@ -17,7 +17,7 @@ from pipelex.system.pipe_run_mode import PipeRunModefrom pipelex.system.runtime import IntegrationModefrom pipelex.system.trace_context import TraceContextfrom pipelex.system.usage_stats.usage_stats_client import configure_usage_stats_for_runtime-from pipelex.system.usage_stats.usage_stats_runs import current_run_tally, usage_stats_error_domain+from pipelex.system.usage_stats.usage_stats_runs import current_run_tally, usage_stats_errorfrom tests.helpers.usage_stats_process import make_project_dir, usage_stats_switched_onfrom tests.helpers.usage_stats_run_events import USAGE_STATS_RUN_ID, llm_usage_eventfrom tests.helpers.usage_stats_schema import assert_envelope_is_valid@@ -53,7 +53,7 @@ def _job(*, mocker: MockerFixture, is_traced: bool) -> Any:def _note_one_call() -> None:tally = current_run_tally()assert tally is not None- tally.note_call(model_handle=_MODEL, backend_name="anthropic", failed=False, failure_category=None, images_generated=0, pages_extracted=0)+ tally.note_call(model_handle=_MODEL, backend_name="anthropic", failure_domain=None, images_generated=0, pages_extracted=0)def _call_then_fail(pipe_job: Any) -> Any:@@ -152,7 +152,7 @@ class TestPipeRunUsageStats:assert (run["inference_calls"], run["input_tokens"], run["output_tokens"], run["models_used"]) == (1, 120, 30, 1)assert run["surface"] == "python"if outcome == "failed":- assert run["error_domain"] == usage_stats_error_domain(error=_FAILURE)+ assert (run["error_code"], run["error_domain"]) == usage_stats_error(error=_FAILURE)assert model_event["event"] == "model_used"assert (model_event["properties"]["provider"], model_event["properties"]["model"]) == ("anthropic", _MODEL)diff --git a/tests/unit/pipelex/pipeline/fixes/test_fix_render.py b/tests/unit/pipelex/pipeline/fixes/test_fix_render.pyindex cddbeae96..4b1d3e09e 100644--- a/tests/unit/pipelex/pipeline/fixes/test_fix_render.py+++ b/tests/unit/pipelex/pipeline/fixes/test_fix_render.py@@ -3,10 +3,10 @@from typing import Anyfrom pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem-from pipelex.pipeline.fixes.fix_loop import FixBundleResult-from pipelex.pipeline.fixes.fix_render import format_fix_markdown, format_fix_still_invalid_markdown+from pipelex.pipeline.fixes.fix_render import format_fix_markdown, format_fix_progress_markdownfrom pipelex.suggested_fix import FixSafety, SuggestedFixfrom pipelex.validation_error_types import PipeValidationErrorType+from tests.helpers.fix_results import fix_resultclass TestFixRender:@@ -94,11 +94,12 @@ class TestFixRender:assert "## Pending Signatures" in renderedassert "- `signature_demo.summarize_doc`" in rendered- def test_still_invalid_renders_applied_fixes_bail_and_remaining_as_prose(self) -> None:- """The still-invalid markdown names the partial progress, the bail reason, and the remaining- errors as prose items (with their 💡 lines) — not a JSON dump.+ def test_still_invalid_progress_names_the_applied_fixes_the_bail_and_the_tip(self) -> None:+ """What follows a still-invalid result's problem names the partial progress, the bail reason and a tip.++ The remaining errors are the problem's own, rendered with it, so this part does not repeat them."""- result = FixBundleResult(+ result = fix_result(is_valid=False,iterations=2,fixes_applied=[@@ -130,22 +131,19 @@ class TestFixRender:bail_reason="Cross-file collision: two files declare pipe 'b'",)- rendered = format_fix_still_invalid_markdown(result, bundle_path="/w/entry.mthds")+ rendered = format_fix_progress_markdown(result, bundle_path="/w/entry.mthds")- assert rendered.startswith("# Fix incomplete - bundle still invalid")- assert "## Applied Fixes" in rendered+ assert rendered.startswith("### Applied Fixes")assert "- `match-sequence-output` - Set output of pipe 'a' to 'X[]'" in rendered+ assert "### Files Written" in renderedassert "**Stopped:** Cross-file collision: two files declare pipe 'b'" in rendered- # Remaining errors render as prose items, with the humanized title and the 💡 suggested-fix line.- assert "1. **Unresolved Concept**" in rendered- assert " - Concept: `Missing`" in rendered- assert " - 💡 Suggested fix: Strip the same-domain prefix from pipe 'b'" in rendered+ assert "Unresolved Concept" not in rendered# A remaining fixable item flips the tip toward "not applied", not "no safe fix".assert "still show a suggested fix that was not applied" in rendereddef test_still_invalid_tip_says_manual_when_no_remaining_fix(self) -> None:"""When no remaining error carries a suggested fix, the tip points at a manual edit."""- result = FixBundleResult(+ result = fix_result(is_valid=False,iterations=1,fixes_applied=[],@@ -159,7 +157,7 @@ class TestFixRender:],)- rendered = format_fix_still_invalid_markdown(result, bundle_path="/w/entry.mthds")+ rendered = format_fix_progress_markdown(result, bundle_path="/w/entry.mthds")assert "have no deterministic safe fix" in rendered- assert "## Applied Fixes" not in rendered+ assert "### Applied Fixes" not in rendereddiff --git a/tests/unit/pipelex/pipeline/test_usage_stats_reporting.py b/tests/unit/pipelex/pipeline/test_usage_stats_reporting.pyindex 18e9968aa..3c523186f 100644--- a/tests/unit/pipelex/pipeline/test_usage_stats_reporting.py+++ b/tests/unit/pipelex/pipeline/test_usage_stats_reporting.py@@ -1,6 +1,11 @@from typing import Any, castimport pytest+from mthds.protocol.exceptions import PipelineRequestError+from mthds.protocol.problem.answers import read_answer+from mthds.protocol.problem.client_problems import make_client_problem+from mthds.protocol.problem.registry import CoreCode+from mthds.runners.api.exceptions import ApiResponseErrorfrom pytest_mock import MockerFixturefrom pipelex.base_exceptions import PipelexError@@ -23,7 +28,7 @@ from pipelex.system.usage_stats.usage_stats_contract import (UsageStatsProvider,)from pipelex.system.usage_stats.usage_stats_events import UsageStatsEvent-from pipelex.system.usage_stats.usage_stats_runs import RunInferenceTally, usage_stats_error_domain+from pipelex.system.usage_stats.usage_stats_runs import RunInferenceTally, sent_usage_stats_error, usage_stats_error, usage_stats_failure_domainfrom pipelex.tracing.trace_events import TraceEventfrom tests.helpers.recovered_problem import make_recovered_url_refusalfrom tests.helpers.usage_stats_run_events import envelope_of, llm_usage_event, pipe_start_event@@ -104,6 +109,19 @@ def _generate_raising(*, error: BaseException) -> None:raise error+def _answered_refusal(*, status: int, body: str) -> ApiResponseError:+ """A refusal a server answered with `body`, with the problem the MTHDS client reads from it, inferred from the status if the body names none."""+ reading = read_answer(status=status, body=body, headers={}, creates_run=False)+ return ApiResponseError(+ f"API POST /v1/start failed ({status})",+ problem=reading.problem,+ api_url="https://runner.test",+ status=status,+ status_text="",+ response_body=body,+ )++class TestUsageStatsReporting:def test_run_with_usage_reports_one_model_used_per_model(self, mocker: MockerFixture) -> None:"""Pipe counts and tokens come from the run's events, failures and backends from its tally, one `model_used` per model."""@@ -112,16 +130,14 @@ class TestUsageStatsReporting:tally.note_call(model_handle=_SHIPPED_ANTHROPIC_MODEL,backend_name="anthropic",- failed=False,- failure_category=None,+ failure_domain=None,images_generated=0,pages_extracted=0,)tally.note_call(model_handle=_SHIPPED_ANTHROPIC_MODEL,backend_name="anthropic",- failed=True,- failure_category="capacity",+ failure_domain=UsageStatsErrorDomain.RUNTIME,images_generated=0,pages_extracted=0,)@@ -147,13 +163,14 @@ class TestUsageStatsReporting:assert (run["input_tokens"], run["output_tokens"], run["cached_tokens"]) == (300, 60, 20)assert run["cost_usd"] > 0model = _properties(usage_event=model_event)- assert (model["provider"], model["model"], model["calls"], model["failures"], model["failures_capacity"]) == (+ assert (model["provider"], model["model"], model["calls"], model["failures"], model["failures_runtime"]) == ("anthropic",_SHIPPED_ANTHROPIC_MODEL,3,1,1,)+ assert (model["failures_input"], model["failures_method"], model["failures_account"], model["failures_operator"]) == (0, 0, 0, 0)assert (model["input_tokens"], model["output_tokens"], model["cached_tokens"]) == (300, 60, 20)assert model["cost_usd"] == run["cost_usd"]@@ -166,8 +183,7 @@ class TestUsageStatsReporting:tally.note_call(model_handle=_SHIPPED_ANTHROPIC_MODEL,backend_name=backend_name,- failed=failed,- failure_category="capacity" if failed else None,+ failure_domain=UsageStatsErrorDomain.RUNTIME if failed else None,images_generated=0,pages_extracted=0,)@@ -196,16 +212,14 @@ class TestUsageStatsReporting:tally.note_call(model_handle=_SHIPPED_ANTHROPIC_MODEL,backend_name="anthropic",- failed=False,- failure_category=None,+ failure_domain=None,images_generated=0,pages_extracted=0,)tally.note_call(model_handle="my-own-gpu-model",backend_name="my_gpu_box",- failed=False,- failure_category=None,+ failure_domain=None,images_generated=0,pages_extracted=0,)@@ -247,14 +261,70 @@ class TestUsageStatsReporting:assert run["outcome"] == outcomeassert run["input_tokens"] == 7if outcome.is_failed:- assert run["error_domain"] == usage_stats_error_domain(error=error)+ assert (run["error_code"], run["error_domain"]) == ("runtime.unexpected", "runtime")else:+ assert "error_code" not in runassert "error_domain" not in runassert "secret" not in str(envelope)- def test_a_recovered_problem_is_counted_in_its_own_domain(self) -> None:- """A failure reporting a problem recovered from a worker is counted by that problem's domain, not by its carrier's class."""- assert usage_stats_error_domain(error=make_recovered_url_refusal()) == UsageStatsErrorDomain.INPUT+ def test_a_recovered_problem_is_counted_by_its_own_code(self) -> None:+ """A failure reporting a problem recovered from a worker is counted by that problem's code and domain, not by its carrier's class."""+ assert usage_stats_error(error=make_recovered_url_refusal()) == ("input.url_unreachable", UsageStatsErrorDomain.INPUT)++ def test_a_request_error_is_counted_by_the_problem_it_carries(self) -> None:+ """An MTHDS client's request error is no Pipelex error, and carries its problem: it is counted by that, not as the catch-all."""+ unreachable = PipelineRequestError(+ "the runner could not be reached",+ problem=make_client_problem(CoreCode.CLIENT_UNREACHABLE, params={"base_url": "https://runner.test"}),+ )++ assert usage_stats_error(error=unreachable) == ("client.unreachable", UsageStatsErrorDomain.RUNTIME)++ @pytest.mark.parametrize(+ ("body", "expected", "expected_sent"),+ [+ # A gateway's page: the client infers `runtime.unavailable` from the 503, which no statistic reports.+ ("<html>502 Bad Gateway</html>", ("runtime.unexpected", UsageStatsErrorDomain.RUNTIME), None),+ # A problem document naming its code and its domain is counted by them, on every path.+ (+ '{"detail": "The input is invalid", "code": "input.invalid", "domain": "input"}',+ ("input.invalid", UsageStatsErrorDomain.INPUT),+ ("input.invalid", UsageStatsErrorDomain.INPUT),+ ),+ ],+ )+ def test_an_answered_refusal_is_counted_by_what_its_body_sent_alone(+ self, body: str, expected: tuple[str, UsageStatsErrorDomain], expected_sent: tuple[str, UsageStatsErrorDomain] | None+ ) -> None:+ """One rule for a refusal a server answered: its body's code and domain, never the problem the client inferred from the status."""+ refusal = _answered_refusal(status=503, body=body)++ assert usage_stats_error(error=refusal) == expected+ assert sent_usage_stats_error(error=refusal) == expected_sent+ assert usage_stats_failure_domain(error=refusal) == expected[1]++ @pytest.mark.parametrize(+ "error",+ [+ make_recovered_url_refusal(),+ PipelexError("a fault of ours"),+ PipelineRequestError("refused", problem=make_client_problem(CoreCode.CLIENT_NOT_CONFIGURED, params={"setting": "base_url"})),+ RuntimeError("no Pipelex error at all"),+ ],+ )+ def test_a_failed_call_s_domain_is_read_off_its_code_alone(self, mocker: MockerFixture, error: Exception) -> None:+ """The cheap reading a failed inference call takes agrees with the problem's, and builds no problem to get it."""+ expected_domain = usage_stats_error(error=error).domain+ to_problem_spy = mocker.patch.object(PipelexError, "to_problem")++ assert usage_stats_failure_domain(error=error) == expected_domain+ to_problem_spy.assert_not_called()++ def test_a_failed_run_carries_its_error_s_code_and_domain(self, mocker: MockerFixture) -> None:+ """A failed run's `run_completed` names its error's code and that code's domain, which the gate accepts."""+ run_event = build_run_usage_events(facts=_facts(mocker=mocker, outcome=UsageStatsOutcome.FAILED, error=make_recovered_url_refusal()))[0]+ run = _properties(usage_event=run_event)+ assert (run["error_code"], run["error_domain"]) == ("input.url_unreachable", "input")@pytest.mark.parametrize(("backend_name", "model_handle", "provider", "model"),diff --git a/tests/unit/pipelex/pipeline/test_validation_errors.py b/tests/unit/pipelex/pipeline/test_validation_errors.pyindex a1edbfd3a..375a98ac3 100644--- a/tests/unit/pipelex/pipeline/test_validation_errors.py+++ b/tests/unit/pipelex/pipeline/test_validation_errors.py@@ -1,11 +1,10 @@"""Unit tests for ``build_validation_error_items`` — the shared structured-error builder.-The single builder feeds both the agent CLI's ``validation_errors`` JSON array-(via ``extract_validation_errors``) and the API's invalid verdict-(``BundleValidationFailure.validation_errors``, via ``ValidateBundleError.validation_error_items``),-so the two surfaces can never drift. These tests pin the per-category field-projection — including the ``source`` / ``field_name`` / ``concept_code`` fields-that the older CLI-only extractor dropped — and the CLI↔API shape parity.+The single builder feeds the problem's ``errors`` (via ``ValidateBundleError.problem_items``), which the agent CLI+prints, and the API's invalid verdict (``BundleValidationFailure.validation_errors``, via+``ValidateBundleError.validation_error_items``), so the surfaces can never drift. These tests pin the per-category+field projection, including the ``source`` / ``field_name`` / ``concept_code`` fields, and that the problem's errors+follow the builder's items one for one."""import json@@ -13,7 +12,6 @@ import jsonfrom mthds.protocol.problem.registry import CoreCodefrom pipelex.base_exceptions import ValidationErrorCategory, ValidationErrorItem-from pipelex.cli.agent_cli.commands.agent_output import extract_validation_errorsfrom pipelex.core.exceptions import (DryRunFailureErrorData,PipeFactoryErrorData,@@ -32,8 +30,8 @@ def _build_items(exc: ValidateBundleError) -> list[ValidationErrorItem]:"""Call the builder with the error's categorized lists only — for the category-projection tests.The pipe-validation arm uses ``pipe_validation_error_data`` (pipe validation **plus**- pipe/concept instantiation errors) — the same combined accessor both real call sites- (``ValidateBundleError.validation_error_items`` and the CLI ``extract_validation_errors``) pass.+ pipe/concept instantiation errors) — the same combined accessor the real call site+ (``ValidateBundleError.validation_error_items``, which the problem's items and the API verdict both read) passes.The dry-run failures and the ``fallback_message`` residual are intentionally omitted here so thesetests pin the categorized projection in isolation; they have their own dedicated tests below."""@@ -260,11 +258,6 @@ class TestBuildValidationErrorItems:assert problem.errors is not Noneassert [item.code for item in problem.errors] == [CoreCode.METHOD_SCHEMA_VIOLATION]- def test_cli_extractor_is_total_for_message_only_error(self) -> None:- """The CLI ``extract_validation_errors`` is also total — a bare-message error yields one item, never an empty array."""- cli_dicts = extract_validation_errors(ValidateBundleError(message="empty blueprint"))- assert cli_dicts == [{"category": "blueprint_validation", "message": "empty blueprint"}]-def test_empty_collections_collapse_to_none(self) -> None:"""An empty ``declared_concepts`` / ``variable_names`` becomes ``None`` so it drops from the wire."""exc = ValidateBundleError(@@ -281,32 +274,23 @@ class TestBuildValidationErrorItems:factory_item = _build_items(exc)[0]assert factory_item.declared_concepts is None- def test_cli_extractor_matches_builder_dumped_shape(self) -> None:- """The CLI ``extract_validation_errors`` dicts equal the dumped builder items — single shape, two surfaces.-- Pins that the agent CLI and the API's invalid verdict emit the identical structured- items: the CLI adapter is exactly ``model_dump(exclude_none=True)`` over- the same builder the API verdict uses.- """- exc = _all_category_error()- cli_dicts = extract_validation_errors(exc)- builder_dicts = [item.model_dump(mode="json", exclude_none=True) for item in _build_items(exc)]- assert cli_dicts == builder_dicts-- def test_cli_extractor_equals_api_verdict_validation_errors(self) -> None:- """The CLI array and the API's invalid verdict ``validation_errors`` are identical on the wire.+ def test_the_problem_s_errors_follow_the_builder_s_items_one_for_one(self) -> None:+ """The problem the agent CLI prints lists one fault per item of the API's invalid verdict, at the same pipe.- The API's verdict is the ``BundleValidationFailure`` a validator returns, built as the direct- validator builds it. A plain ``==`` would pass merely because ``StrEnum`` subclasses ``str``; to- prove *wire-byte* parity (and catch a future python/json-divergent field that is not a StrEnum),- we also compare the encoded JSON, not just the in-memory dicts.+ The API's verdict is the ``BundleValidationFailure`` a validator returns, built as the direct validator builds+ it; its items are dumped to the wire and compared as encoded JSON, so a field that diverges between Python and+ JSON would show."""exc = _all_category_error()- cli_dicts = extract_validation_errors(exc)verdict = BundleValidationFailure(problem=exc.to_problem(view=ProblemView.OPERATOR), validation_errors=exc.validation_error_items())verdict_items = verdict.model_dump(mode="json", exclude_none=True)["validation_errors"]- assert verdict_items == cli_dicts- assert json.dumps(verdict_items, sort_keys=True) == json.dumps(cli_dicts, sort_keys=True)+ builder_dicts = [item.model_dump(mode="json", exclude_none=True) for item in _build_items(exc)]+ assert json.dumps(verdict_items, sort_keys=True) == json.dumps(builder_dicts, sort_keys=True)++ problem_items = exc.to_problem(view=ProblemView.OPERATOR).errors+ assert problem_items is not None+ assert len(problem_items) == len(builder_dicts)+ assert [item.location.pipe if item.location else None for item in problem_items] == [item.get("pipe_code") for item in builder_dicts]def test_enriched_pipe_validation_error_rides_a_suggested_fix(self) -> None:"""An enriched output-mismatch error data yields an item carrying the planner's suggested_fix."""diff --git a/tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py b/tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.pyindex d561229d1..6d59e0c08 100644--- a/tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py+++ b/tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py@@ -17,6 +17,7 @@ The stale documents here are the package's own: `telemetry-config@2` is the shipfrom __future__ import annotations+import loggingfrom pathlib import Pathfrom typing import TYPE_CHECKING@@ -102,6 +103,20 @@ class TestTheErrorSaysWhetherTheFileIsOldOrWrong:assert MIGRATE_COMMAND not in exc.messageassert "custom_posthog.mode" in exc.message+ def test_the_operator_s_step_names_the_setting_the_file_and_the_surface(self, global_dir: Path, caplog: pytest.LogCaptureFixture) -> None:+ """The code's step renders from the refused setting, never falling back on the generic sentence; the advice is doctor's."""+ exc = load_and_capture(config_dir=global_dir, body='[custom_posthog]\nmode = "no-such-mode"\n')++ with caplog.at_level(logging.WARNING, logger="pipelex.errors.problem"):+ problem = exc.to_problem(view=ProblemView.OPERATOR)+ assert problem.next_step.detail == (+ "Correct the setting 'custom_posthog.mode' in the file 'telemetry.toml' of the telemetry configuration, then restart the runtime."+ )+ assert not [record for record in caplog.records if record.name == "pipelex.errors.problem"]+ advice = exc.advised_action()+ assert advice is not None+ assert "'pipelex-agent doctor'" in advice.detail+def test_a_key_no_build_knows_is_named_even_with_nothing_to_migrate(self, global_dir: Path) -> None:"""The diagnosis speaks on its own: an unknown root key is a finding without a single step."""exc = load_and_capture(config_dir=global_dir, body=f"{UNKNOWN_KEY} = true\n")diff --git a/tests/unit/pipelex/system/usage_stats/test_usage_stats_client.py b/tests/unit/pipelex/system/usage_stats/test_usage_stats_client.pyindex e1a7321e8..c57e5183c 100644--- a/tests/unit/pipelex/system/usage_stats/test_usage_stats_client.py+++ b/tests/unit/pipelex/system/usage_stats/test_usage_stats_client.py@@ -19,6 +19,7 @@ from pipelex.system.usage_stats.usage_stats_client import (get_usage_stats_client,)from pipelex.system.usage_stats.usage_stats_contract import (+ SCHEMA_VERSION,TOOL_NAME,UsageStatsEnvVar,UsageStatsEventName,@@ -120,7 +121,7 @@ class TestUsageStatsClient:assert_envelope_is_valid(envelope)properties = envelope["properties"]assert properties["$process_person_profile"] is False- assert properties["schema"] == 1+ assert properties["schema"] == SCHEMA_VERSIONassert properties["tool"] == "pipelex"assert properties["surface"] == "pipelex"assert properties["integration"] == "cli"diff --git a/tests/unit/pipelex/system/usage_stats/test_usage_stats_contract.py b/tests/unit/pipelex/system/usage_stats/test_usage_stats_contract.pyindex f282342e7..ea7cb44ef 100644--- a/tests/unit/pipelex/system/usage_stats/test_usage_stats_contract.py+++ b/tests/unit/pipelex/system/usage_stats/test_usage_stats_contract.py@@ -10,6 +10,8 @@ from pipelex.system.usage_stats.usage_stats_contract import (CONTAINER_CGROUP_WORDS,CONTAINER_MARKER_FILES,CONTAINER_MARKER_VARIABLES,+ ERROR_CODE_MAX_LENGTH,+ ERROR_CODE_PATTERN,FALSY_VALUES,MODEL_HANDLE_PATTERN,NOTICE_DETAILS_URL,@@ -93,6 +95,23 @@ class TestUsageStatsContract:assert load_usage_stats_schema()["schema_version"] == SCHEMA_VERSIONassert load_usage_stats_schema()["person_profile_property"] == PERSON_PROFILE_PROPERTY+ def test_the_schema_property_s_maximum_is_the_schema_version(self) -> None:+ """Every `schema` property reaches the contract's version, as the spec's own load check holds, from version 1 on."""+ schema = load_usage_stats_schema()+ schema_properties = [schema["common_properties"]["schema"]]+ schema_properties += [event["properties"]["schema"] for event in schema["events"].values() if "schema" in event["properties"]]+ assert schema_properties+ for schema_property in schema_properties:+ assert schema_property["min"] == 1+ assert schema_property["max"] == SCHEMA_VERSION++ def test_the_error_contract_is_version_2(self) -> None:+ """The error's code and the registry's domains replaced what version 1 declared, which only a new version may do."""+ schema = load_usage_stats_schema()+ assert SCHEMA_VERSION == 2+ assert set(schema["events"]["run_completed"]["properties"]["error_domain"]["values"]) == {domain.value for domain in UsageStatsErrorDomain}+ assert "failures_transient" not in schema["events"]["model_used"]["properties"]+def test_notice_is_the_schemas_text_for_pipelex(self) -> None:notice = load_usage_stats_schema()["notice"]assert notice["version"] == NOTICE_VERSION@@ -160,6 +179,8 @@ class TestUsageStatsContract:assert patterns["release_version"]["regex"] == RELEASE_VERSION_PATTERNassert patterns["installation_id"]["regex"] == INSTALLATION_ID_PATTERNassert patterns["model_handle"]["regex"] == MODEL_HANDLE_PATTERN+ assert patterns["error_code"]["regex"] == ERROR_CODE_PATTERN+ assert patterns["error_code"]["max_length"] == ERROR_CODE_MAX_LENGTHdef test_enums_are_the_schemas_values(self) -> None:assert {event.value for event in UsageStatsEventName} <= set(load_usage_stats_schema()["events"])diff --git a/tests/unit/pipelex/tools/misc/test_path_label.py b/tests/unit/pipelex/tools/misc/test_path_label.pynew file mode 100644index 000000000..305ccc8c2--- /dev/null+++ b/tests/unit/pipelex/tools/misc/test_path_label.py@@ -0,0 +1,62 @@+from pathlib import Path++import pytest+from pytest_mock import MockerFixture++from pipelex.tools.misc.exceptions import TomlError+from pipelex.tools.misc.file_utils import path_label+from pipelex.tools.misc.toml_utils import load_toml_from_path+++class TestPathLabel:+ @pytest.mark.parametrize(+ ("working_dir", "target", "expected"),+ [+ # A project's file is named relative to the project the command runs in.+ ("home/project", "home/project/.pipelex/pipelex.toml", ".pipelex/pipelex.toml"),+ # The home configuration, from a project, is named under `~`.+ ("home/project", "home/.pipelex/inference/backends.toml", "~/.pipelex/inference/backends.toml"),+ # From the home directory itself, the home configuration still reads as the home's, never as a project's.+ ("home", "home/.pipelex/pipelex.toml", "~/.pipelex/pipelex.toml"),+ # From above the home directory too.+ (".", "home/.pipelex/pipelex.toml", "~/.pipelex/pipelex.toml"),+ # A relative path is read against the working directory.+ ("home/project", ".pipelex/pipelex.toml", ".pipelex/pipelex.toml"),+ # A relative path climbing out of the working directory and back into the home directory by its name.+ ("home/project/sub", "../../../home/.pipelex/pipelex.toml", "~/.pipelex/pipelex.toml"),+ # An absolute path that climbs out of the working directory.+ ("home/project", "home/project/../.pipelex/pipelex.toml", "~/.pipelex/pipelex.toml"),+ ],+ )+ def test_a_path_is_named_without_the_home_directory(+ self, mocker: MockerFixture, tmp_path: Path, working_dir: str, target: str, expected: str+ ) -> None:+ mocker.patch.object(Path, "home", return_value=tmp_path / "home")+ mocker.patch.object(Path, "cwd", return_value=tmp_path / working_dir)+ target_path = Path(target) if not target.startswith("home") else tmp_path / target++ assert path_label(path=target_path) == expected++ def test_a_path_under_neither_is_named_whole(self, mocker: MockerFixture, tmp_path: Path) -> None:+ mocker.patch.object(Path, "home", return_value=tmp_path / "home")+ mocker.patch.object(Path, "cwd", return_value=tmp_path / "home" / "project")+ elsewhere = tmp_path / "etc" / "pipelex" / "pipelex.toml"++ assert path_label(path=elsewhere) == str(elsewhere)++ def test_without_a_home_directory_a_path_outside_the_working_directory_is_named_whole(self, mocker: MockerFixture, tmp_path: Path) -> None:+ mocker.patch.object(Path, "home", side_effect=RuntimeError("Could not determine home directory."))+ mocker.patch.object(Path, "cwd", return_value=tmp_path / "project")++ assert path_label(path=tmp_path / "project" / "a.toml") == "a.toml"+ assert path_label(path=tmp_path / "other" / "a.toml") == str(tmp_path / "other" / "a.toml")++ def test_a_toml_syntax_error_carries_the_file_it_was_read_from(self, tmp_path: Path) -> None:+ broken = tmp_path / "broken.toml"+ broken.write_text("[table\n", encoding="utf-8")++ with pytest.raises(TomlError) as exc_info:+ load_toml_from_path(broken)++ assert exc_info.value.path == broken+ assert exc_info.value.lineno == 1