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.
fix/Validate-viewer-outside-tree · L-261016-ab4f9e (#1469)
Louis Choquel8a3fdc6b7ea0
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex 90c78c2f6..c7a18bdab 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,8 +1,8 @@contract = "cli-docs"-digest = "sha256:5a0be307b82eceee7cc18c0127e0e3df9db4a382c534b61bf96b0cda39bddc8c"+digest = "sha256:15c34e11fbeda068e0b43ecdcec888acaa608831376c25b11466fb784d96fe81"reviewed_by = "Louis Choquel"-reviewed_at = "2026-10-20T05:51:05Z"-rationale = "clean-pass: since the last ack the CLI triggers only switch their off-the-loop helper from run_in_worker_thread to run_method_load, the bounded method-load pool; no flag, output, exit code or error format changes, and neither docs/tools/cli/ nor pipelex/cli/agent_cli/CLAUDE.md names the helper or describes where a command's load runs, so nothing there is stale."+reviewed_at = "2026-10-20T07:11:19Z"+rationale = "real-catch: validate bundle --graph now makes its folder under the directory bundle_run_outputs_dir settles for the target, the one run bundle writes to (beside the bundle file named or the bundle defining a folder's entry pipe, or the folder's own results/ when --pipe names the pipe), and only once the graph has rendered; docs/tools/cli/agent-cli.md (Graph Visualization) and pipelex/cli/agent_cli/CLAUDE.md (the validate output and the file convention) now say so. run bundle's own locations are unchanged, only routed through that function."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"@@ -37,17 +37,17 @@ rationale = "clean-pass: since the last ack the CLI triggers only switch their o"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_core.py" = "blob:44036b8b1e344e52880896d4c8edc2bfd35fe60d""pipelex/cli/agent_cli/commands/run/_run_hosted.py" = "blob:8d2e819c44d5669756e931b9f3fc83741d54a1df""pipelex/cli/agent_cli/commands/run/app.py" = "blob:7546d9b31ea2dc22b1ddae538edfbc8e7f7d08df"-"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:fd02137f1286cb4293cdc5dc2b03c31d5c87454b"+"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:42a795f9139eaf038af833f74f1f595e0807a737""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:f74178959782fe6e8edc2b7171b9967d82cf2076""pipelex/cli/agent_cli/commands/validate/app.py" = "blob:1982684a2aae81e0d634bb3b262457a5f187d979"-"pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:3c7045c77c15b2ab5fdb1629a4203e53231b764d"+"pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:4e785799e8a548fb973ad2b2fd184d1695a7dced""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"@@ -113,7 +113,7 @@ rationale = "clean-pass: since the last ack the CLI triggers only switch their o"pipelex/cli/commands/run/_main_stuff_file.py" = "blob:ca806e55085aa2e5748492751521296ce1f42960""pipelex/cli/commands/run/_run_core.py" = "blob:56cff4673ad0e30e87b25dada61515f3188feb0d""pipelex/cli/commands/run/_run_hosted.py" = "blob:f61b3ea7fdc6c29823ecd6cb5b469ab271814c3f"-"pipelex/cli/commands/run/_run_output_folder.py" = "blob:5834889a5e35e6457acf24761b408bc6a7bbfd6c"+"pipelex/cli/commands/run/_run_output_folder.py" = "blob:6f3b237849d9b6498a4dbf5cb81ceea948c91782""pipelex/cli/commands/run/app.py" = "blob:e312b159625e0a72bc9a18d3bfd2c73e7ac59f24""pipelex/cli/commands/run/bundle_cmd.py" = "blob:faff9a7cba8027bb7b13f7f5a3b94666f3742b80""pipelex/cli/commands/run/exceptions.py" = "blob:cebeb5950c87a1e113ed717565ae8cb783bb5001"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8bae3ab20..0ff09daad 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,7 @@### Changed+- **`pipelex-agent validate bundle --graph` writes into an output folder (Breaking)**: the flowchart it draws, `dry_run.html`, and `mermaidflow.html` with `--graph-format mermaidflow` or `both`, go into a new numbered folder, `<pipe_code>_output_<NN>/`, under the `results/` directory a `run bundle` of the same target writes to (beside the bundle file named, beside the bundle defining a folder's entry pipe, or in the folder's own `results/` when `--pipe` names the pipe), holding the `.gitignore` a run's output folder holds, instead of beside the bundle drawn, so validating a method no longer adds files to its tree or changes its digest. Read each file's path from `graph_files` in the envelope, the Markdown listing them under `## Graph files`, and the folder from `graph_output_dir`.- **The API server's examples send a method in `files`**: the server's README and the API Server pages send a method to `/v1/execute` and `/v1/validate` in `files`, a map from each file's path in the method's folder to its content, where they sent `mthds_contents`. The reference pages and the OpenAPI artifact now say that `mthds_contents`, with `bundle_b64`, `resources` and `/v1/validate`'s `mthds_sources`, is being retired and will be refused by a later release, so a client sends `files` now.- **A PipeFunc package-offer factory is never called on a thread running an event loop (Breaking)**: the factory a plugin registers with `PluginRegistrar.add_pipe_func_package_offer` may block for as long as its work takes and must not use an event loop of its caller's, and pipelex enforces it: a load that would call the factory on a thread running an event loop fails with `PipelexUnexpectedError` instead, so a host that calls a load itself from asynchronous code, such as a worker's activity, moves it off the loop with `run_method_load` (`pipelex.libraries.method_load_threads`) or with `acquire_library_async` (`pipelex.pipeline.execution_seams`), the twin of `acquire_library` that loads off the loop. The factory's signature is unchanged, and so is the plugin API version. `run_method_load` runs a blocking call in the method-load pool, a named pool of at most `METHOD_LOAD_MAX_THREADS` threads (four) apart from asyncio's default executor, in a copy of the caller's context, and when its caller is cancelled, the shutdown of `asyncio.run` included, withdraws a call no thread has taken yet or lets the cancellation through only once the running call has ended; the general mechanism is `WorkerThreads` (`pipelex.tools.misc.async_utils`).- **The refusal of a package the request did not send**: the message of the `unresolved_package_dependency` refusal a static resolution gives, such as the one behind `/v1/resolve`, `/v1/codegen` and `/v1/pipe-io`, tells its reader to send the package's files in `dependencies`, keyed by its address, beside the method's own files in `files`, where it spoke of an in-memory resolve and the host filesystem and advised directory-based resolution; it still carries the words `address-based dependency '<address>'`.diff --git a/docs/building-methods/method-trees.md b/docs/building-methods/method-trees.mdindex 508039400..0c5b1fcb7 100644--- a/docs/building-methods/method-trees.md+++ b/docs/building-methods/method-trees.md@@ -26,7 +26,7 @@ A tree holds the regular files under its root, except those its membership ruleA symbolic link anywhere in the tree refuses the whole tree: a tree holds regular files only, so replace the link with the file it names, or keep it out with a `.gitignore` pattern.-The tree's `.gitignore` files are what keeps a run's outputs out of the method: every folder `pipelex run` creates for its outputs holds a `.gitignore` ignoring everything in it, so a run started from the method's own folder leaves its tree, and its digest, as they were.+The tree's `.gitignore` files are what keeps a run's outputs out of the method: every folder `pipelex run` creates for its outputs holds a `.gitignore` ignoring everything in it, and so does the folder `pipelex-agent validate bundle --graph` writes its flowchart into, so a run or a validation started from the method's own folder leaves its tree, and its digest, as they were.## File referencesdiff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.mdindex 493b6e367..2dc5e5483 100644--- a/docs/tools/cli/agent-cli.md+++ b/docs/tools/cli/agent-cli.md@@ -85,7 +85,7 @@ pipelex-agent validate method <NAME> [OPTIONS]For `bundle`, additional options are available:- `--pipe` - Require a specific pipe in the bundle, and dry-run only that pipe; for a method's folder, the whole tree is still validated-- `--graph`, `-g` - Generate an execution graph visualization+- `--graph`, `-g` - Draw the method's flowchart from a dry run and save it in a new output folder kept out of the method's tree (see [Graph Visualization](#graph-visualization))- `--graph-format`, `-f` - Graph output format (`mermaidflow`, `reactflow`, or `both`)- `--direction` - Graph layout direction@@ -264,4 +264,6 @@ A configuration that does not validate names, in the next step's sentence, the sGraph visualization is available through the `validate bundle` subcommand with the `--graph` flag, and through `run` subcommands where it is enabled by default. Use `--no-graph` on `run` to disable it.+`validate bundle --graph` writes its flowchart, the ReactFlow viewer `dry_run.html`, and the Mermaid viewer `mermaidflow.html` with `--graph-format mermaidflow` or `both`, into a new numbered folder, `<pipe_code>_output_<NN>/`, under the `results/` directory a `run bundle` of the same target writes its outputs to: beside the bundle file named, beside the bundle defining a folder's entry pipe, or in the folder's own `results/` when `--pipe` names the pipe, whichever bundle defines it. The folder is made the way a run's is, holding a `.gitignore` ignoring everything in it, so validating a method never adds a file to its tree nor changes its digest, and each validation gets a folder of its own. The envelope names each file it wrote in `graph_files` (`reactflow_html`, `mermaidflow_html`) and the folder in `graph_output_dir`, and the Markdown lists the files under `## Graph files`: open the path the command reports rather than looking for the viewer in a fixed place.+A `run` writes its outputs into a new numbered folder, `results/<pipe_code>_output_<NN>/` beside its bundle, or under `mthds-wip/` when it ran no bundle file; a folder run that named its pipe writes under the folder's `results/`, and a fetched method under `results/` in the working directory. The folder holds a `.gitignore` ignoring everything in it, so no output ever joins the method tree and the next run reads the same tree, with the same `method_tree_digest`. With the graph on, that folder holds the ReactFlow viewer (`dry_run.html` or `live_run.html`) and the graph itself: `graphspec.json` on a dry run, `live_run_graph.json` on a live run. Beside the graph, under their canonical names whatever the graph file is called, sit the three files that describe its data: `pipe_io_contracts.json`, `input_form.json` and `output_form.json`, the same artifacts `validate` reports under those names, keyed by namespaced `pipe_ref`. A graph viewer resolves them from the graph file's directory, not from its name. With `--with-memory`, the JSON envelope's `graph_files` object names every one of these paths (`graph_html`, `graph_spec` on a live run, `pipe_io_contracts`, `input_form`, `output_form`).diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.mdindex 4cb19a993..ca36f6dab 100644--- a/pipelex/cli/agent_cli/CLAUDE.md+++ b/pipelex/cli/agent_cli/CLAUDE.md@@ -18,7 +18,7 @@ Only the error format is backed by module-level `ContextVar`s in `agent_output.pMarkdown 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. `validate bundle` and `validate method` also carry `tree_files_read` and `tree_file_readers`, the protocol report's members of the same names, splatted from `tree_files_envelope_fields` in `pipelex/pipeline/tree_files_read.py` so the envelope and the report share their shapes, and rendered as a "Files the steps read" section in markdown; `validate all` and `validate pipe`, which may span several trees, carry neither.+- `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. `validate bundle --graph` writes its viewer (`dry_run.html`, and `mermaidflow.html` per `--graph-format`) into a new run output folder, `<pipe_code>_output_<NN>/`, under the directory `bundle_run_outputs_dir` settles for the target, the one `run bundle` writes to, so the two cannot drift; it is made by `make_run_output_folder` through the `make_output_folder` callback `generate_graph_for_bundle` calls once the graph has rendered, so a failed render leaves no folder, so it holds the same `.gitignore` and never joins the method tree it validated; never write it beside the bundle, which would change the tree's digest. The envelope's `graph_files` names each file and `graph_output_dir` the folder, rendered as a `## Graph files` 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. `validate bundle` and `validate method` also carry `tree_files_read` and `tree_file_readers`, the protocol report's members of the same names, splatted from `tree_files_envelope_fields` in `pipelex/pipeline/tree_files_read.py` so the envelope and the report share their shapes, and rendered as a "Files the steps read" section in markdown; `validate all` and `validate pipe`, which may span several trees, carry neither.- `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.@@ -103,7 +103,7 @@ commands/- **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.+- **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` passes the directory `bundle_run_outputs_dir` settles for its target, `results/` beside the bundle file named or the bundle defining a folder's entry pipe, or the folder's own `results/` when `--pipe` names the pipe, which `validate bundle --graph` asks too.- **Validate refusals of the method are verdicts**: the `validate` commands run their library load inside `translate_to_validate_bundle_error` (`pipelex/pipeline/validate_bundle_translation.py`), so every refusal raised while loading a bundle whose code is in the `method` domain, the unknown model (`PipeOperatorModelChoiceError`, an `unknown_model` item) included, reaches the command as a `ValidateBundleError` and leaves with the invalid verdict's problem and exit 1. A refusal of another actor, the request's or the input's included, keeps its own class and code, and so does a dry run none of whose failures is the method's. No `validate` command keeps an arm of its own for a model-choice error; exit 2 stays for a failure of the tool or its environment (config, runtime, security).- **Run refusals are verdicts too**: a run loads its bundle inside the same translation (`acquire_library`), so an invalid bundle leaves `run pipe` / `run bundle` / `run method` as a `ValidateBundleError` with exit 1, through the generic `agent_error` arm (`run bundle`'s own reading of its bundle through `agent_error_method_refusal()`, in the caller's view on a runner), and its problem (`method.invalid`) carries the verdict's items as `errors`, and the Markdown lists the same errors one per line, so both formats list the one problem's errors and a foreign exception raised while handling an earlier verdict lists none of its items. `run_pipeline_core` sets `library_dirs_are_callers=True`, so a refusal in a `-L` directory (or the bundle's own directory) is the same verdict; `run bundle`'s own parse of a bundle without `--pipe` goes through the translation too, and so does its reading of the method tree: a folder resolves through `pipelex/cli/bundle_target_resolution.py` (`resolve_method_folder_run`, the protocol's entry rule in `pipelex/pipeline/method_entry.py`) and a lone file through `list_bundle_file_tree`, listed before the file is read, 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.diff --git a/pipelex/cli/agent_cli/commands/run/_run_core.py b/pipelex/cli/agent_cli/commands/run/_run_core.pyindex d71aee873..44036b8b1 100644--- a/pipelex/cli/agent_cli/commands/run/_run_core.py+++ b/pipelex/cli/agent_cli/commands/run/_run_core.py@@ -74,9 +74,10 @@ async def run_pipeline_core(inputs_base_dir: Directory bare relative file paths in ``inputs`` resolve against (SmartInputs D3) — the inputs file's parent when file-loaded, else ``None``.output_dir_override: Directory the run's output folder (output JSON, graph files) is created under,- overriding the default, `results/` beside the bundle. The caller passes one when the bundle lives- in a directory that will not survive the process — a fetched method's ephemeral clone — or when a- folder run named its pipe and has no entry bundle to write beside.+ overriding the default, `results/` beside the bundle. `run bundle` always passes the one+ `bundle_run_outputs_dir` settles for its target, which `validate bundle --graph` shares; `run method`+ passes one when the bundle lives in a directory that will not survive the process, a fetched method's+ ephemeral clone.method_tree: The method tree the run reads, when the command listed one: its digest is recorded as``method_tree_digest`` beside the run's other side effects, on disk and under ``with_memory``.diff --git a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py b/pipelex/cli/agent_cli/commands/run/bundle_cmd.pyindex fd02137f1..42a795f91 100644--- a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/bundle_cmd.py@@ -35,7 +35,7 @@ from pipelex.cli.agent_cli.commands.run._run_hosted import (from pipelex.cli.agent_cli.commands.run.stdin_resolver import parse_cli_inputsfrom pipelex.cli.bundle_target_resolution import list_bundle_file_tree, resolve_method_folder_runfrom pipelex.cli.commands.run._hosted_sources import collect_mthds_files, hosted_library_dirs-from pipelex.cli.commands.run._run_output_folder import RUN_RESULTS_DIR_NAME+from pipelex.cli.commands.run._run_output_folder import bundle_run_outputs_dirfrom 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 runtime@@ -148,9 +148,8 @@ def run_bundle_cmd(# The method tree the run reads, whose digest the run records: the folder's, or the bundle file's own.method_tree: MethodTree | None = None- # Where a folder run that named its pipe writes its output folders: `results/` in the folder, which has no entry- # bundle to write beside.- output_dir_override: Path | None = None+ # The bundle defining a folder's entry pipe, which the run's output folders are made beside.+ entry_bundle_file: Path | None = None# The pipe a hosted run names: `--pipe`, else the main pipe the local run starts at, qualified by its domain, so the# hosted API starts at the same pipe when two domains of the files it is sent define the same code.hosted_pipe_code: str | None = pipe@@ -170,9 +169,8 @@ def run_bundle_cmd(pipe_code = folder_run.pipe_codeif folder_run.entry is not None and folder_run.entry_bundle_file is not None:bundle_path = str(folder_run.entry_bundle_file)+ entry_bundle_file = folder_run.entry_bundle_filehosted_pipe_code = folder_run.entry.pipe_ref- else:- output_dir_override = target_path / RUN_RESULTS_DIR_NAME# Hand the directory to parse_cli_inputs as the lowest-priority inputs source: it probes# for inputs.json / inputs.toml (and applies the ambiguity rule) only after --inputs and@@ -195,6 +193,9 @@ def run_bundle_cmd(reason="not a .mthds file or a directory",)+ # Where the run's output folders go on this machine, settled by the one function `validate bundle --graph` asks too.+ output_dir_override = bundle_run_outputs_dir(target_path=target_path, pipe_override=pipe, entry_bundle_file=entry_bundle_file)+# Load MTHDS content from bundlemthds_content: str | None = Noneif bundle_path:diff --git a/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py b/pipelex/cli/agent_cli/commands/validate/bundle_cmd.pyindex 3c7045c77..4e785799e 100644--- a/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py+++ b/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py@@ -24,13 +24,14 @@ from pipelex.cli.agent_cli.commands.validate._validate_core import (validate_pipe_in_bundle_core,)from pipelex.cli.bundle_target_resolution import locate_folder_pipe+from pipelex.cli.commands.run._run_output_folder import bundle_run_outputs_dir, make_run_output_folder, run_output_labelfrom pipelex.cli.judged_target import JudgedBundleTargetfrom pipelex.graph.graph_rendering import GraphFormatfrom pipelex.libraries.pipe.exceptions import PipeNotFoundErrorfrom pipelex.mthds_parsing.exceptions import MthdsParserErrorfrom pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityErrorfrom pipelex.pipelex import Pipelex-from pipelex.pipeline.bundle_graph_rendering import generate_graph_for_bundle, generate_view_for_bundle+from pipelex.pipeline.bundle_graph_rendering import GraphOutputFolderMaker, generate_graph_for_bundle, generate_view_for_bundlefrom pipelex.pipeline.exceptions import MethodEntryError, PipelineExecutionError, ValidateBundleErrorfrom pipelex.pipeline.validation_render import format_validate_markdownfrom pipelex.tools.misc.chart_utils import FlowchartDirection@@ -39,10 +40,12 @@ _GRAPH_UNAVAILABLE_KEY = "graph_unavailable"class _GraphTarget(NamedTuple):- """The bundle file a graph is drawn from, and the pipe drawn: the one named, else the bundle's or method's entry."""+ """The bundle file a graph is drawn from, the pipe drawn (the one named, else the bundle's or method's entry), and where."""bundle_path: Pathpipe_code: str | None+ #: The directory a `run bundle` of the same target makes its output folders under, where `--graph` makes its own.+ outputs_dir: Pathdef _graph_target(*, target: JudgedBundleTarget, pipe: str | None) -> _GraphTarget | str:@@ -54,15 +57,34 @@ def _graph_target(*, target: JudgedBundleTarget, pipe: str | None) -> _GraphTargthe validation standing as it is."""if target.bundle_path is not None:- return _GraphTarget(bundle_path=target.bundle_path, pipe_code=pipe)- if target.method_tree is None:+ outputs_dir = bundle_run_outputs_dir(target_path=target.bundle_path, pipe_override=pipe, entry_bundle_file=None)+ return _GraphTarget(bundle_path=target.bundle_path, pipe_code=pipe, outputs_dir=outputs_dir)+ if target.method_tree is None or target.method_dir is None:msg = "A method's folder was resolved without its method tree."raise PipelexUnexpectedError(msg)try:entry = locate_folder_pipe(tree=target.method_tree, pipe_override=pipe)except MethodEntryError as exc:return f"No graph was drawn, since a graph is drawn from one pipe: {exc.message}"- return _GraphTarget(bundle_path=target.method_tree.file_location(entry.tree_path), pipe_code=entry.pipe_ref)+ bundle_path = target.method_tree.file_location(entry.tree_path)+ # A run of the folder writes beside the bundle defining its entry pipe, or in the folder itself when a pipe is named.+ outputs_dir = bundle_run_outputs_dir(target_path=target.method_dir, pipe_override=pipe, entry_bundle_file=bundle_path)+ return _GraphTarget(bundle_path=bundle_path, pipe_code=entry.pipe_ref, outputs_dir=outputs_dir)+++def _graph_output_folder_maker(*, outputs_dir: Path) -> GraphOutputFolderMaker:+ """Where `--graph` writes its files: a new numbered folder, `<pipe_code>_output_<NN>/`, under `outputs_dir`.++ `outputs_dir` is where a `run bundle` of the same target makes its output folders, and the folder is made the same+ way, holding a `.gitignore` that ignores everything in it, so the viewer and its graph files never join the method+ tree they were drawn from: validating a method leaves its tree, and its digest, as they were. The envelope names+ each file's path.+ """++ def make_output_folder(*, pipe_code: str) -> Path:+ return make_run_output_folder(output_dir=outputs_dir, label=run_output_label(pipe_ref=pipe_code))++ return make_output_folderdef validate_bundle_cmd(@@ -76,7 +98,12 @@ def validate_bundle_cmd(] = None,graph: Annotated[bool,- typer.Option("--graph", "-g", help="On successful bundle validation, save graph HTML files and include their paths in the JSON output"),+ typer.Option(+ "--graph",+ "-g",+ help="On successful bundle validation, save graph HTML files in a new <pipe_code>_output_<NN>/ folder under the results/ "+ "directory a run of the same target writes to, kept out of the method tree, and include their paths in the output",+ ),] = False,graph_format: Annotated[GraphFormat,@@ -176,6 +203,7 @@ def validate_bundle_cmd(generate_graph_for_bundle(bundle_path=graph_target.bundle_path,graph_format=graph_format,+ make_output_folder=_graph_output_folder_maker(outputs_dir=graph_target.outputs_dir),library_dirs=library_dir_strings,pipe_code=graph_target.pipe_code,direction=direction,diff --git a/pipelex/cli/commands/run/_run_output_folder.py b/pipelex/cli/commands/run/_run_output_folder.pyindex 5834889a5..6f3b23784 100644--- a/pipelex/cli/commands/run/_run_output_folder.py+++ b/pipelex/cli/commands/run/_run_output_folder.py@@ -1,7 +1,9 @@"""The folder a `pipelex run` writes its outputs to, kept out of every method tree, and the record of the tree it ran.A run writes its outputs to a new numbered folder, `<label>_output_<NN>`, under `--output-dir` for `pipelex run`, and-under `results/` beside the bundle it ran for `pipelex-agent run`. That folder often+under `results/` beside the bundle it ran for `pipelex-agent run`; `pipelex-agent validate bundle --graph` writes its+graph files to such a folder too, under the directory a `run bundle` of the same target writes to, which+`bundle_run_outputs_dir` settles for both commands. That folder oftenlies inside a method's folder, the working directory being the method's, so the run writes a `.gitignore` holding `*`into it: the membership rule honours the tree's `.gitignore` files as git does (`mthds/docs/spec/method-tree.md`), sonone of a run's outputs, nor the `.gitignore` itself, ever joins the tree, and a second run of the method reads the@@ -19,9 +21,9 @@ from mthds.method_tree.models import MethodTreefrom pipelex.tools.misc.file_utils import get_incremental_directory_pathRUN_OUTPUT_GITIGNORE_NAME = ".gitignore"-RUN_OUTPUT_GITIGNORE_CONTENT = "# Written by pipelex run: a run's outputs are never part of a method.\n*\n"+RUN_OUTPUT_GITIGNORE_CONTENT = "# Written by pipelex: what a run or a validation writes here is never part of a method.\n*\n"METHOD_TREE_RECORD_NAME = "method_tree.json"-#: The directory `pipelex-agent run` creates its output folders under, beside the bundle it ran.+#: The directory `pipelex-agent run` creates its output folders under, beside the bundle it ran, as `validate bundle --graph` does.RUN_RESULTS_DIR_NAME = "results"@@ -34,6 +36,21 @@ def run_output_label(*, pipe_ref: str) -> str:return pipe_ref.rsplit("->", 1)[-1].rsplit(".", 1)[-1]+def bundle_run_outputs_dir(*, target_path: Path, pipe_override: str | None, entry_bundle_file: Path | None) -> Path:+ """The directory `pipelex-agent run bundle <target_path>` makes its output folders under, on this machine.++ A bundle file's run writes under `results/` beside the file. A folder's run writes under `results/` beside the bundle+ defining the pipe it starts at, `entry_bundle_file`, when no pipe was named, and under the folder's own `results/`+ when `pipe_override` names one, whichever bundle defines it. `pipelex-agent validate bundle --graph` asks this same+ function about the same target, so a validation's flowchart lands where a run of that target writes its outputs.+ """+ if not target_path.is_dir():+ return target_path.parent / RUN_RESULTS_DIR_NAME+ if pipe_override or entry_bundle_file is None:+ return target_path / RUN_RESULTS_DIR_NAME+ return entry_bundle_file.parent / RUN_RESULTS_DIR_NAME++def make_run_output_folder(*, output_dir: Path, label: str) -> Path:"""Create the next numbered output folder for a run under `output_dir`, holding a `.gitignore` that ignores it all."""output_path = get_incremental_directory_path(output_dir, base_name=f"{label}_output")diff --git a/pipelex/graph/graph_rendering.py b/pipelex/graph/graph_rendering.pyindex 33c81864b..9ea7f7ed8 100644--- a/pipelex/graph/graph_rendering.py+++ b/pipelex/graph/graph_rendering.py@@ -22,36 +22,33 @@ class GraphFormat(StrEnum):BOTH = "both"-async def render_graph_from_spec(- graph_spec: GraphSpec,+async def render_graph_outputs(*,+ graph_spec: GraphSpec,graph_config: GraphConfig,include_mermaidflow: bool,include_reactflow: bool,- output_dir: Path,pipe_code: str = "",title: str | None = None,direction: FlowchartDirection | None = None,include_subgraphs: bool = True,-) -> dict[str, Path]:- """Render graph outputs from a graph spec and save to output_dir.+) -> GraphOutputs:+ """Render the HTML viewers of a graph spec in memory, writing nothing.- Builds a render config from the provided graph config with format selection,- generates graph outputs, and saves them to the output directory.+ A caller that saves them into a folder of its own making renders first, so a render that fails leaves no folder.Args:graph_spec: The graph spec produced by pipeline execution.graph_config: The base graph configuration.include_mermaidflow: Whether to generate Mermaid HTML output.include_reactflow: Whether to generate ReactFlow HTML output.- output_dir: Directory where graph files will be saved.pipe_code: The pipe code, used to derive the HTML page title.title: Explicit title for the graph page (takes precedence over pipe_code).direction: Flowchart direction override.include_subgraphs: Whether to include controller subgraphs in Mermaid output.Returns:- Dict mapping output format keys to saved file paths.+ The rendered outputs, the viewers selected and nothing else."""render_graph_config = graph_config.model_copy(update={@@ -71,7 +68,7 @@ async def render_graph_from_spec(})- graph_outputs: GraphOutputs = await generate_graph_outputs(+ return await generate_graph_outputs(graph_spec=graph_spec,graph_config=render_graph_config,pipe_code=pipe_code,@@ -80,4 +77,45 @@ async def render_graph_from_spec(include_subgraphs=include_subgraphs,)++async def render_graph_from_spec(+ graph_spec: GraphSpec,+ *,+ graph_config: GraphConfig,+ include_mermaidflow: bool,+ include_reactflow: bool,+ output_dir: Path,+ pipe_code: str = "",+ title: str | None = None,+ direction: FlowchartDirection | None = None,+ include_subgraphs: bool = True,+) -> dict[str, Path]:+ """Render graph outputs from a graph spec and save to output_dir.++ Renders the selected viewers with `render_graph_outputs`, then saves them to the output directory.++ Args:+ graph_spec: The graph spec produced by pipeline execution.+ graph_config: The base graph configuration.+ include_mermaidflow: Whether to generate Mermaid HTML output.+ include_reactflow: Whether to generate ReactFlow HTML output.+ output_dir: Directory where graph files will be saved.+ pipe_code: The pipe code, used to derive the HTML page title.+ title: Explicit title for the graph page (takes precedence over pipe_code).+ direction: Flowchart direction override.+ include_subgraphs: Whether to include controller subgraphs in Mermaid output.++ Returns:+ Dict mapping output format keys to saved file paths.+ """+ graph_outputs = await render_graph_outputs(+ graph_spec=graph_spec,+ graph_config=graph_config,+ include_mermaidflow=include_mermaidflow,+ include_reactflow=include_reactflow,+ pipe_code=pipe_code,+ title=title,+ direction=direction,+ include_subgraphs=include_subgraphs,+ )return save_graph_outputs_to_dir(graph_outputs=graph_outputs, output_dir=output_dir)diff --git a/pipelex/pipeline/bundle_graph_rendering.py b/pipelex/pipeline/bundle_graph_rendering.pyindex ed6630eac..44318c046 100644--- a/pipelex/pipeline/bundle_graph_rendering.py+++ b/pipelex/pipeline/bundle_graph_rendering.py@@ -7,15 +7,26 @@ see ``docs/contribute/hub-layering.md``."""from pathlib import Path-from typing import Any+from typing import Any, Protocolfrom pipelex.config import get_config-from pipelex.graph.graph_rendering import GraphFormat, render_graph_from_spec+from pipelex.graph.graph_factory import save_graph_outputs_to_dir+from pipelex.graph.graph_rendering import GraphFormat, render_graph_outputsfrom pipelex.graph.graphspec import GraphSpecfrom pipelex.pipeline.dry_run_pipeline import dry_run_pipelinefrom pipelex.tools.misc.chart_utils import FlowchartDirection+class GraphOutputFolderMaker(Protocol):+ """Makes the folder a bundle's graph files are written into, once the dry run has settled the pipe the graph draws.++ Where that folder lies is the caller's decision, never this module's: the agent CLI makes a new numbered folder+ beside the bundle, holding a `.gitignore` that keeps it out of every method tree, as a run's output folder does.+ """++ def __call__(self, *, pipe_code: str) -> Path: ...++def _sanitize_graph_name(graph_name: str) -> str:"""Sanitize graph_name to prevent path traversal.@@ -73,6 +84,7 @@ async def generate_graph_for_bundle(bundle_path: Path,*,graph_format: GraphFormat,+ make_output_folder: GraphOutputFolderMaker,library_dirs: list[str] | None = None,pipe_code: str | None = None,direction: FlowchartDirection | None = None,@@ -80,19 +92,22 @@ async def generate_graph_for_bundle() -> dict[str, Any]:"""Generate graph visualization for a bundle via dry-run pipeline execution.- Reads the bundle, parses main_pipe, performs a dry-run with graph tracing,- then renders and saves graph HTML files alongside the bundle.+ Reads the bundle, parses main_pipe, performs a dry-run with graph tracing, then renders the graph HTML files and,+ once they have rendered, saves them in the folder `make_output_folder` makes for the pipe the dry run drew. The bundle's own folder is+ usually inside a method's tree, so the files are never written there unasked: a file added to the tree would change+ the digest of the method the graph was drawn from.Args:bundle_path: Path to the .mthds bundle file.graph_format: Which graph format(s) to generate.+ make_output_folder: Makes the folder the graph files are written into, given the pipe the graph draws.library_dirs: Optional library directories for pipe resolution.pipe_code: Optional explicit pipe target for graph generation.direction: Flowchart layout direction (default: None, uses TB).graph_name: Filename for the generated HTML graph (default: "dry_run.html").Returns:- Dictionary with graph_files, graph_output_dir, and direction.+ Dictionary with graph_files (each file's path), graph_output_dir (the folder made), pipe_code, and direction.Raises:MthdsParserError: If bundle parsing fails or main_pipe is missing.@@ -119,16 +134,17 @@ async def generate_graph_for_bundle(include_mermaidflow = Trueinclude_reactflow = True- output_dir = bundle_path.parent- saved_files = await render_graph_from_spec(+ graph_outputs = await render_graph_outputs(graph_spec=graph_spec,graph_config=execution_config.graph,include_mermaidflow=include_mermaidflow,include_reactflow=include_reactflow,- output_dir=output_dir,pipe_code=resolved_pipe_code,direction=direction,)+ # The folder is made once the graph has rendered, so a render that fails leaves no empty numbered folder behind.+ output_dir = make_output_folder(pipe_code=resolved_pipe_code)+ saved_files = save_graph_outputs_to_dir(graph_outputs=graph_outputs, output_dir=output_dir)# Rename reactflow.html to the requested filenamereactflow_path = saved_files.get("reactflow_html")diff --git a/tests/integration/pipelex/cli/conftest.py b/tests/integration/pipelex/cli/conftest.pynew file mode 100644index 000000000..d7109d420--- /dev/null+++ b/tests/integration/pipelex/cli/conftest.py@@ -0,0 +1,24 @@+from __future__ import annotations++from typing import TYPE_CHECKING++import pytest++from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library++if TYPE_CHECKING:+ from collections.abc import Iterator+++def restore_current_library() -> Iterator[None]:+ """A command whose teardown is patched out leaves its library open and current: tear it down and restore the outer one."""+ outer_library_id = get_current_library_id_or_none()+ yield+ current_library_id = get_current_library_id_or_none()+ if current_library_id is not None and current_library_id != outer_library_id:+ get_library_manager().teardown(library_id=current_library_id)+ if outer_library_id is not None:+ set_current_library(library_id=outer_library_id)+ else:+ clear_current_library()diff --git a/tests/integration/pipelex/cli/test_agent_validate_graph_folder.py b/tests/integration/pipelex/cli/test_agent_validate_graph_folder.pynew file mode 100644index 000000000..de99f8962--- /dev/null+++ b/tests/integration/pipelex/cli/test_agent_validate_graph_folder.py@@ -0,0 +1,113 @@+from __future__ import annotations++import json+from pathlib import Path+from typing import TYPE_CHECKING++import pytest+from mthds.method_tree.lister import list_method_tree++from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_format+from pipelex.cli.agent_cli.commands.validate.bundle_cmd import validate_bundle_cmd++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++VALIDATE_BUNDLE_CMD_MODULE = "pipelex.cli.agent_cli.commands.validate.bundle_cmd"++_BUNDLE = """domain = "graph_folder_probe"+main_pipe = "greet"++[pipe.greet]+type = "PipeCompose"+description = "Greet the reader"+inputs = { name = "Text" }+output = "Text"+template = "Hello, $name"+"""++# A second bundle of the same method, nested in a sub-folder, defining a pipe a `--pipe` can name.+_NESTED_BUNDLE = """domain = "graph_folder_probe"++[pipe.wave]+type = "PipeCompose"+description = "Wave at the reader"+inputs = { name = "Text" }+output = "Text"+template = "Bye, $name"+"""+++def _write_method(*, tmp_path: Path) -> Path:+ """A method's folder: `bundle.mthds` declaring the main pipe, and `parts/extra.mthds` defining another pipe."""+ method_dir = (tmp_path / "method").resolve()+ (method_dir / "parts").mkdir(parents=True)+ (method_dir / "bundle.mthds").write_text(_BUNDLE, encoding="utf-8")+ (method_dir / "parts" / "extra.mthds").write_text(_NESTED_BUNDLE, encoding="utf-8")+ return method_dir++[email protected](autouse=True)+def no_boot(mocker: MockerFixture) -> None:+ """The suite's session boot owns the runtime, so the command's own boot and teardown are patched out."""+ mocker.patch(f"{VALIDATE_BUNDLE_CMD_MODULE}.make_pipelex_for_agent_cli")+ mocker.patch(f"{VALIDATE_BUNDLE_CMD_MODULE}.Pipelex.teardown_if_needed")++[email protected]("restore_current_library")+class TestAgentValidateGraphFolder:+ def test_two_validations_with_a_graph_leave_the_method_tree_unchanged(+ self,+ capsys: pytest.CaptureFixture[str],+ tmp_path: Path,+ ) -> None:+ """The real validation and dry-run graph, twice on a method's folder: each draws into its own ignored folder, whose path both formats name."""+ method_dir = _write_method(tmp_path=tmp_path)+ tree_before = list_method_tree(method_dir)++ try:+ validate_bundle_cmd(path=str(method_dir), graph=True, output_format=CliOutputFormat.JSON)+ envelope = json.loads(capsys.readouterr().out)+ validate_bundle_cmd(path=str(method_dir), graph=True, output_format=CliOutputFormat.MARKDOWN)+ markdown = capsys.readouterr().out+ finally:+ set_agent_cli_error_format(CliOutputFormat.JSON)++ first_folder = method_dir / "results" / "greet_output_01"+ first_viewer = Path(envelope["graph_files"]["reactflow_html"])+ assert first_viewer.resolve() == first_folder / "dry_run.html"+ assert first_viewer.is_file()+ assert Path(envelope["graph_output_dir"]).resolve() == first_folder+ assert (first_folder / ".gitignore").read_text(encoding="utf-8").splitlines()[-1] == "*"++ second_viewer = method_dir / "results" / "greet_output_02" / "dry_run.html"+ assert second_viewer.is_file()+ assert "## Graph files" in markdown+ assert "dry_run.html" in markdown+ assert "greet_output_02" in markdown++ assert not (method_dir / "dry_run.html").exists()+ tree_after = list_method_tree(method_dir)+ assert tree_after.tree_paths == ["bundle.mthds", "parts/extra.mthds"]+ assert tree_after.digest == tree_before.digest++ def test_a_named_pipe_of_a_nested_bundle_draws_into_the_folder_s_own_results(+ self,+ capsys: pytest.CaptureFixture[str],+ tmp_path: Path,+ ) -> None:+ """`--pipe` naming a pipe of `parts/extra.mthds` draws where `run bundle <folder> --pipe` writes: the folder's `results/`."""+ method_dir = _write_method(tmp_path=tmp_path)+ tree_before = list_method_tree(method_dir)++ try:+ validate_bundle_cmd(path=str(method_dir), pipe="graph_folder_probe.wave", graph=True, output_format=CliOutputFormat.JSON)+ envelope = json.loads(capsys.readouterr().out)+ finally:+ set_agent_cli_error_format(CliOutputFormat.JSON)++ viewer = Path(envelope["graph_files"]["reactflow_html"])+ assert viewer.resolve() == method_dir / "results" / "wave_output_01" / "dry_run.html"+ assert viewer.is_file()+ assert not (method_dir / "parts" / "results").exists()+ assert list_method_tree(method_dir).digest == tree_before.digestdiff --git a/tests/integration/pipelex/cli/test_validate_load_refusals_cli.py b/tests/integration/pipelex/cli/test_validate_load_refusals_cli.pyindex a136c36a4..235e15a0d 100644--- a/tests/integration/pipelex/cli/test_validate_load_refusals_cli.py+++ b/tests/integration/pipelex/cli/test_validate_load_refusals_cli.py@@ -29,11 +29,9 @@ from pipelex.cli.commands.validate._validate_core import (_validate_pipe_or_bundle, # pyright: ignore[reportPrivateUsage]do_validate_all_libraries_and_dry_run,)-from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_libraryfrom pipelex.test_extras.mthds_corpus.loader import get_entryif TYPE_CHECKING:- from collections.abc import Iteratorfrom pathlib import Pathfrom pytest_mock import MockerFixture@@ -65,20 +63,6 @@ def console(mocker: MockerFixture) -> Console:return recorded_console-def restore_current_library() -> Iterator[None]:- """The pipe and --all paths leave their library open and current (the command's teardown owns it)."""- outer_library_id = get_current_library_id_or_none()- yield- current_library_id = get_current_library_id_or_none()- if current_library_id is not None and current_library_id != outer_library_id:- get_library_manager().teardown(library_id=current_library_id)- if outer_library_id is not None:- set_current_library(library_id=outer_library_id)- else:- clear_current_library()--@pytest.fixturedef unknown_model_bundle(tmp_path: Path) -> Path:bundle_path = tmp_path / "bundle.mthds"diff --git a/tests/unit/pipelex/cli/commands/run/test_run_output_folder.py b/tests/unit/pipelex/cli/commands/run/test_run_output_folder.pyindex 53f9900ac..c301e0f87 100644--- a/tests/unit/pipelex/cli/commands/run/test_run_output_folder.py+++ b/tests/unit/pipelex/cli/commands/run/test_run_output_folder.py@@ -5,7 +5,13 @@ import pytestfrom mthds.method_tree.digest import tree_listingfrom mthds.method_tree.lister import list_method_tree-from pipelex.cli.commands.run._run_output_folder import METHOD_TREE_RECORD_NAME, make_run_output_folder, run_output_label, write_method_tree_record+from pipelex.cli.commands.run._run_output_folder import (+ METHOD_TREE_RECORD_NAME,+ bundle_run_outputs_dir,+ make_run_output_folder,+ run_output_label,+ write_method_tree_record,+)class TestRunOutputFolder:@@ -53,3 +59,35 @@ class TestRunOutputFolder:def test_a_run_folder_is_labelled_by_the_pipe_s_own_code(self, pipe_ref: str, expected_label: str) -> None:"""A pipe named with its domain, or through a dependency's alias, labels its folder as its bare code does, locally or hosted."""assert run_output_label(pipe_ref=pipe_ref) == expected_label++ @pytest.mark.parametrize(+ ("target", "pipe_override", "entry_bundle", "expected_outputs_dir"),+ [+ ("method/bundle.mthds", None, None, "method/results"),+ ("method/parts/extra.mthds", "wave", None, "method/parts/results"),+ ("method", None, "method/bundle.mthds", "method/results"),+ ("method", None, "method/parts/extra.mthds", "method/parts/results"),+ ("method", "graph_folder_probe.wave", "method/parts/extra.mthds", "method/results"),+ ("method", "wave", None, "method/results"),+ ],+ )+ def test_a_bundle_run_writes_beside_the_bundle_it_starts_in_else_in_the_folder_named(+ self,+ tmp_path: Path,+ target: str,+ pipe_override: str | None,+ entry_bundle: str | None,+ expected_outputs_dir: str,+ ) -> None:+ """A file writes beside itself, a folder beside its entry bundle, and a folder whose pipe is named in the folder itself."""+ (tmp_path / "method" / "parts").mkdir(parents=True)+ for bundle_name in ("method/bundle.mthds", "method/parts/extra.mthds"):+ (tmp_path / bundle_name).write_text("domain = 'run_folder_tests'\n", encoding="utf-8")++ outputs_dir = bundle_run_outputs_dir(+ target_path=tmp_path / target,+ pipe_override=pipe_override,+ entry_bundle_file=tmp_path / entry_bundle if entry_bundle else None,+ )++ assert outputs_dir == tmp_path / expected_outputs_dirdiff --git a/tests/unit/pipelex/pipeline/test_bundle_graph_rendering_generate_graph.py b/tests/unit/pipelex/pipeline/test_bundle_graph_rendering_generate_graph.pyindex d7203af54..c3d5f3c18 100644--- a/tests/unit/pipelex/pipeline/test_bundle_graph_rendering_generate_graph.py+++ b/tests/unit/pipelex/pipeline/test_bundle_graph_rendering_generate_graph.py@@ -20,6 +20,18 @@ BUNDLE_GRAPH_RENDERING_MODULE = "pipelex.pipeline.bundle_graph_rendering"BUNDLE_CONTENT = 'domain = "test_domain"\nmain_pipe = "test_pipe"\n'+class _FolderMaker:+ """Hands back one folder, whatever pipe the graph draws, and records the pipes it was asked to make a folder for."""++ def __init__(self, *, folder: Path) -> None:+ self.folder = folder+ self.pipes_drawn: list[str] = []++ def __call__(self, *, pipe_code: str) -> Path:+ self.pipes_drawn.append(pipe_code)+ return self.folder++@pytest.mark.asyncio(loop_scope="class")class TestGenerateGraphForBundle:"""Tests for generate_graph_for_bundle format dispatch, rename branch, and return shape."""@@ -32,9 +44,10 @@ class TestGenerateGraphForBundle:) -> dict[str, Any]:"""Create the bundle file and patch the bundle_graph_rendering collaborators.- The renderer is patched as a whole: since the split, `render_graph_from_spec` lives in the- kernel-layer `pipelex.graph.graph_rendering` and is this module's collaborator, not its- internals. How it maps the inclusion flags onto the graph config is its own test's business+ The renderer and the saver are patched as a whole: `render_graph_outputs` lives in the+ kernel-layer `pipelex.graph.graph_rendering` and `save_graph_outputs_to_dir` in+ `pipelex.graph.graph_factory`, both this module's collaborators, not its internals. How the+ renderer maps the inclusion flags onto the graph config is its own test's business(`tests/unit/pipelex/graph/test_graph_rendering.py`); what belongs here is the dispatch."""bundle_path = tmp_path / "bundle.mthds"@@ -52,11 +65,13 @@ class TestGenerateGraphForBundle:config_mock.interpreter.pipeline_execution.with_execution_overrides.return_value = execution_config_mockmocker.patch(f"{BUNDLE_GRAPH_RENDERING_MODULE}.get_config", return_value=config_mock)+ graph_outputs_mock = mocker.MagicMock()mock_render = mocker.patch(- f"{BUNDLE_GRAPH_RENDERING_MODULE}.render_graph_from_spec",+ f"{BUNDLE_GRAPH_RENDERING_MODULE}.render_graph_outputs",new_callable=mocker.AsyncMock,- return_value=saved_files,+ return_value=graph_outputs_mock,)+ mock_save = mocker.patch(f"{BUNDLE_GRAPH_RENDERING_MODULE}.save_graph_outputs_to_dir", return_value=saved_files)return {"bundle_path": bundle_path,@@ -65,6 +80,8 @@ class TestGenerateGraphForBundle:"config_mock": config_mock,"execution_config_mock": execution_config_mock,"mock_render": mock_render,+ "graph_outputs_mock": graph_outputs_mock,+ "mock_save": mock_save,}@pytest.mark.parametrize(@@ -89,6 +106,7 @@ class TestGenerateGraphForBundle:await generate_graph_for_bundle(bundle_path=mocks["bundle_path"],graph_format=graph_format,+ make_output_folder=_FolderMaker(folder=tmp_path),)render_kwargs = mocks["mock_render"].call_args.kwargs@@ -111,6 +129,7 @@ class TestGenerateGraphForBundle:result = await generate_graph_for_bundle(bundle_path=mocks["bundle_path"],graph_format=GraphFormat.REACTFLOW,+ make_output_folder=_FolderMaker(folder=tmp_path),graph_name="../../evil.html",)@@ -132,6 +151,7 @@ class TestGenerateGraphForBundle:result = await generate_graph_for_bundle(bundle_path=mocks["bundle_path"],graph_format=GraphFormat.MERMAIDFLOW,+ make_output_folder=_FolderMaker(folder=tmp_path),graph_name="renamed.html",)@@ -153,16 +173,18 @@ class TestGenerateGraphForBundle:direction: FlowchartDirection | None,expected_direction: str | None,) -> None:- """The result should carry the bundle parent dir, dry-run pipe_code, and stringified direction."""+ """The result should carry the folder the graph was written to, dry-run pipe_code, and stringified direction."""mocks = self._setup_mocks(mocker, tmp_path, saved_files={})+ graph_folder = tmp_path / "results" / "pipe_code_output_01"result = await generate_graph_for_bundle(bundle_path=mocks["bundle_path"],graph_format=GraphFormat.BOTH,+ make_output_folder=_FolderMaker(folder=graph_folder),direction=direction,)- assert result["graph_output_dir"] == str(tmp_path)+ assert result["graph_output_dir"] == str(graph_folder)assert result["pipe_code"] == "pipe_code"assert result["direction"] == expected_direction@@ -177,8 +199,49 @@ class TestGenerateGraphForBundle:await generate_graph_for_bundle(bundle_path=mocks["bundle_path"],graph_format=GraphFormat.REACTFLOW,+ make_output_folder=_FolderMaker(folder=tmp_path),pipe_code="other_pipe",)mocks["mock_dry_run"].assert_awaited_once()assert mocks["mock_dry_run"].call_args.kwargs["pipe_code"] == "other_pipe"++ async def test_the_graph_is_written_to_the_folder_made_for_the_pipe_drawn(+ self,+ mocker: MockerFixture,+ tmp_path: Path,+ ) -> None:+ """The folder is made once the dry run has settled the pipe, never the bundle's own folder, and the renderer writes there."""+ mocks = self._setup_mocks(mocker, tmp_path, saved_files={})+ folder_maker = _FolderMaker(folder=tmp_path / "elsewhere")++ await generate_graph_for_bundle(+ bundle_path=mocks["bundle_path"],+ graph_format=GraphFormat.REACTFLOW,+ make_output_folder=folder_maker,+ )++ assert folder_maker.pipes_drawn == ["pipe_code"]+ assert mocks["mock_save"].call_args.kwargs == {"graph_outputs": mocks["graph_outputs_mock"], "output_dir": tmp_path / "elsewhere"}++ async def test_a_render_that_fails_makes_no_folder(+ self,+ mocker: MockerFixture,+ tmp_path: Path,+ ) -> None:+ """The folder is made only once the graph has rendered, so a failed render spends no folder number and leaves nothing."""+ mocks = self._setup_mocks(mocker, tmp_path, saved_files={})+ render_error = RuntimeError("the renderer broke")+ mocks["mock_render"].side_effect = render_error+ folder_maker = _FolderMaker(folder=tmp_path / "elsewhere")++ with pytest.raises(RuntimeError) as exc_info:+ await generate_graph_for_bundle(+ bundle_path=mocks["bundle_path"],+ graph_format=GraphFormat.REACTFLOW,+ make_output_folder=folder_maker,+ )++ assert exc_info.value is render_error+ assert folder_maker.pipes_drawn == []+ mocks["mock_save"].assert_not_called()