Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
feature/Pipelex-runs-hosted-via · L-261004-b638d8 (#1366)
Louis Choquele58ed63b51c7
diff --git a/.badges/tests.json b/.badges/tests.jsonindex 1afc05895..f2e0817cb 100644--- a/.badges/tests.json+++ b/.badges/tests.json@@ -1,7 +1,7 @@{"schemaVersion": 1,"label": "tests",- "message": "15623",+ "message": "15816","color": "blue","cacheSeconds": 300}diff --git a/.claude/skills/bump-mthds/SKILL.md b/.claude/skills/bump-mthds/SKILL.mdindex 3a2d67066..582f43dbb 100644--- a/.claude/skills/bump-mthds/SKILL.md+++ b/.claude/skills/bump-mthds/SKILL.md@@ -2,7 +2,8 @@name: bump-mthdsdescription: >Move this repo's exact `mthds` dependency pin to the latest release on PyPI- (or a version you name), re-lock, adapt the engine source to whatever the new+ (or a version you name), with the exact `pipelex-sdk` pin that must name the+ same `mthds`, re-lock, adapt the engine source to whatever the newrelease broke, run the checks, and write the CHANGELOG entry — stopping beforethe commit. Use whenever the user says "bump mthds", "update mthds", "upgrademthds", "move to mthds 0.10.0", "get us on the latest mthds", "is our mthds@@ -11,7 +12,7 @@ description: >version mismatch — a pyright `reportAttributeAccessIssue` on something under`mthds.protocol`, an ImportError for a name that used to be there, a pydantic`Extra inputs are not permitted` from a protocol model, or a `uv lock` saying- mthds is unsatisfiable. This is the **`mthds` PyPI package** (the MTHDS+ mthds is unsatisfiable, or asks to bump pipelex-sdk. This is the **`mthds` PyPI package** (the MTHDSstandard's Python client, from the sibling `mthds-python` repo) — not theMTHDS standard's spec pages, and not releasing pipelex itself, which is the`release` skill.@@ -31,7 +32,14 @@ dependency: an upstream rename is not an internal detail this repo absorbs, itis a **breaking change to pipelex's own API**, and it has to reach the changelogas one.-The job is to land the new pin in a state a human can read and commit: pin+**`mthds` never moves alone: `pipelex-sdk` moves with it.** pipelex requires+`pipelex-sdk` (the hosted-API client `pipelex run --hosted` runs through), pinned+exactly, and `pipelex-sdk` pins `mthds` exactly too. The two pins therefore have+to name the same `mthds`, or the resolve is unsatisfiable: a bump of `mthds` is+also a bump of `pipelex-sdk` to the release that pins the new `mthds`. When no+such `pipelex-sdk` release is on PyPI yet, the bump waits for it.++The job is to land the new pins in a state a human can read and commit: pinsmoved, lock regenerated, source adapted, checks green, changelog written, ledgersquared. **Stop before committing** — the user stages and commits.@@ -39,9 +47,9 @@ squared. **Stop before committing** — the user stages and commits.| File | Why it moves ||---|---|-| `pyproject.toml` | The pin itself, one line in `[project].dependencies` — `mthds==X.Y.Z` |+| `pyproject.toml` | The pins, two lines in `[project].dependencies` — `mthds==X.Y.Z` and `pipelex-sdk==A.B.C`, the `pipelex-sdk` release whose own pin is `mthds==X.Y.Z` || `uv.lock` | Regenerated by `make li` |-| `pipelex/**` | Wherever the new release renamed, split, or tightened something this engine imports |+| `pipelex/**` | Wherever the new release renamed, split, or tightened something this engine imports — `pipelex/hosted/` included, which builds on `pipelex-sdk`'s client, errors and models || `tests/**` | Same, plus any test asserting on a shape that moved || `CHANGELOG.md` | An entry under `## [Unreleased]` — always at least the pin line || `.badges/tests.json`, `.test_durations` | Only if the adaptation added, removed or renamed tests |@@ -91,11 +99,11 @@ in the upstream notes against this table before repeating it in ours.### 1. Orient-Read the pin **from `pyproject.toml`**, not from the virtualenv:+Read the pins **from `pyproject.toml`**, not from the virtualenv:```bash-grep -n '"mthds' pyproject.toml-.venv/bin/python -c "import importlib.metadata as m; print(m.version('mthds'))"+grep -n '"mthds\|"pipelex-sdk' pyproject.toml+.venv/bin/python -c "import importlib.metadata as m; print(m.version('mthds'), m.version('pipelex-sdk'))"```Under an exact pin these two should agree, in both directions — unlike a floor,@@ -138,6 +146,19 @@ curl -s https://pypi.org/pypi/mthds/json \`info.version` is the latest non-prerelease, which is what "latest" means for apin other people inherit exactly.+Then find the `pipelex-sdk` release that pins that `mthds`. Its PyPI metadata+lists its requirements, so read the `mthds` one off the latest release:++```bash+curl -s https://pypi.org/pypi/pipelex-sdk/json \+ | python3 -c "import json,sys; info=json.load(sys.stdin)['info']; print(info['version'], [req for req in info['requires_dist'] if req.startswith('mthds')])"+```++If the latest `pipelex-sdk` pins the target `mthds`, that is its target. If it+pins an older one, `pipelex-sdk` has not moved yet: stop and report it, since a+pin naming an `mthds` no `pipelex-sdk` release accepts makes `uv lock` fail —+the cascade at step 10 is the way to get it moved, not a source override here.+**Ask PyPI, never the sibling checkout.** `mthds-python/pyproject.toml` is aworking tree and is frequently *ahead* of what has been published — a versionsitting there under `## [Unreleased]` is not installable, and a pin naming it@@ -176,16 +197,16 @@ imports, parse-time tightening (mthds models are `extra="forbid"`, so a shapethis engine constructs can start failing at construction), and any move of`MTHDS_STANDARD_VERSION`.-### 4. Move the pin+### 4. Move the pins-One line in `pyproject.toml`. Make it a substring edit — replace `==0.11.1` with-`==0.11.2` on that line, **keeping the `==`**, and leave every other character-alone. Use your editor+Two lines in `pyproject.toml`, the `mthds` pin and the `pipelex-sdk` one. Make+each a substring edit — replace `==0.11.1` with `==0.11.2` on that line,+**keeping the `==`**, and leave every other character alone. Use your editorrather than a shell one-liner: `sed -i` takes a separate empty argument on macOSand an attached suffix on GNU/Linux, so no single invocation is portable, andthe `release` skill edits this same file the same way.-Confirm with `grep -n '"mthds' pyproject.toml` before moving on.+Confirm with `grep -n '"mthds\|"pipelex-sdk' pyproject.toml` before moving on.### 5. Re-lock and install@@ -205,7 +226,7 @@ plain `uv lock` re-resolve mthds.Check the lock actually moved — a pin edit that didn't take is silent:```bash-grep -A1 '^name = "mthds"' uv.lock+grep -A1 '^name = "mthds"\|^name = "pipelex-sdk"' uv.lock```If `uv lock` reports the requirement is unsatisfiable, the version is almost@@ -214,8 +235,8 @@ published, stop and tell the user rather than inventing a git or path source:adding one is a deliberate decision with a real cost (in uv, a *source* outranksa version specifier, so the pin you wrote becomes decorative), not a workaroundto apply quietly. An exact pin can also be reported unsatisfiable because-another member of the resolve wants a different mthds — widening this pin is not-the fix, moving the other requirement is.+another member of the resolve wants a different mthds — `pipelex-sdk` first of+all — and widening this pin is not the fix, moving the other requirement is.### 6. Check whether `MTHDS_STANDARD_VERSION` moved@@ -309,9 +330,9 @@ Every bump gets at least the pin line. Follow the house form, which names therelease *by what it carries*:```markdown-- **`mthds` version**: The pin moves to `mthds==0.11.2`, <the release that- carries / the release fixing …>. Everyone downstream inherits that exact- version.+- **`mthds` and `pipelex-sdk` versions**: The pins move to `mthds==0.11.2`, <the+ release that carries / the release fixing …>, and `pipelex-sdk==0.32.0`, the+ release built on it. Everyone downstream inherits those exact versions.```Anything that reached pipelex's own surface gets its own entry under@@ -329,12 +350,14 @@ ones harder to spot.- **Close what you actually landed**, with evidence — the file and line youchanged, and the check that went green. `Closes <id>` goes in the PR body whenthe user opens one.-- **File the cascade, and note that the exact pin makes it sharper.**- The Python SDK in `pipelex-sdk/python/` pins `mthds` exactly too, and- `pipelex-server` pins `pipelex` exactly at several sites — so any bump here,- breaking or not, puts a consumer that installs both this package and the- `pipelex-sdk` distribution into an unsatisfiable resolve until `pipelex-sdk`- moves to the same version. Check where it stands+- **File the cascade, and note that the exact pins make it sharper.**+ pipelex itself requires `pipelex-sdk`, whose Python package in+ `pipelex-sdk/python/` pins `mthds` exactly, so this bump cannot land before a+ `pipelex-sdk` release pins the same `mthds` (step 2 checks PyPI for it). When+ none exists, the bump stops there, and the item to file is the `pipelex-sdk`+ bump, against `pipelex-sdk/python`, naming the `mthds` version this repo+ wants. `pipelex-server` pins `pipelex` exactly at several sites, so once this+ bump ships it has to follow too. Check where `pipelex-sdk` stands(`grep mthds ../pipelex-sdk/python/pyproject.toml`) and say so in your report.Neither repo is yours to edit from here: file it against the member thatholds the pin (`ledger new --owner pipelex-sdk/python …`, and@@ -350,7 +373,7 @@ ones harder to spot.Show the user:-- The pin move, old → new, and whether `uv.lock` actually followed.+- The pin moves, old → new for `mthds` and for `pipelex-sdk`, and whether `uv.lock` actually followed.- Whether `MTHDS_STANDARD_VERSION` moved, and what that changes for users.- Every file you changed, separated from what was already dirty when you started.- The check results, honestly — if `agent-test` failed, say so with the output@@ -368,6 +391,9 @@ and PRs target `dev`.## Traps worth remembering+- **The `mthds` and `pipelex-sdk` pins move together.** `pipelex-sdk` pins+ `mthds` exactly, so a `mthds` pin with no matching `pipelex-sdk` release is+ unsatisfiable, and `uv lock` says so about `mthds`, not about the SDK.- **Nothing in this repo enforces the `==`.** No check fails if the pin isrelaxed to `>=`; `pyproject.toml` is the only place the policy is written, andthe changelog is where it was announced. A widened pin ships silently.diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex a1524744d..4a4ce2cbd 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,17 +1,17 @@contract = "cli-docs"-digest = "sha256:67e74186129a0a063c16a4f36f412f61ede2624ab6201e489af587f58beed0de"+digest = "sha256:35f1ecf9aa9cfa54726f3badc961f2efe548559cb1b2c8966f1bf22a25f4e0de"reviewed_by = "Claude (Opus 5.5)"-reviewed_at = "2026-10-08T07:21:15Z"-rationale = "clean-pass: merged tree of origin/dev into this branch. Dev's check-model change keeps the review recorded on dev, whose doc edits in docs/tools/cli/agent-cli.md and pipelex/cli/agent_cli/CLAUDE.md came through the merge unchanged. This branch's only trigger change is init_config delegating its copy walk to the shared copy_kit_templates, with the same skip lists, overwrite on reset and the same dry-run count, so pipelex init config behaves as before. Re-read docs/tools/cli/init.md (full reset, every target replacing its file, the .gitignore rule) and the init rows of pipelex/cli/agent_cli/CLAUDE.md; none describes anything this changes."+reviewed_at = "2026-10-08T12:45:01Z"+rationale = "clean-pass: merged tree of origin/dev into this branch. The open trigger changes are all this branch's hosted run surface, the run commands of both CLIs, _run_hosted.py, _hosted_sources.py and the removed _run_core_api.py, already answered on the branch in docs/tools/cli/run.md, run-by-address.md, agent-cli.md and pipelex/cli/agent_cli/CLAUDE.md. Dev touched no file under docs/tools/cli and no run command; its one CLI trigger, init_config delegating to copy_kit_templates, keeps the review dev recorded, and docs/tools/cli/init.md still describes it. The merged docs name --hosted, --local, --base-url and --runner local or hosted, and nothing under docs/tools/cli still names the removed --runner api path except the warning that says it is gone."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"-"pipelex/cli/_cli.py" = "blob:b976c272f1b0358788c0a7add965e09950ce06e2"+"pipelex/cli/_cli.py" = "blob:1ef9cd89b6044b9b510fad81661872a43d9cc21e""pipelex/cli/agent_cli/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"-"pipelex/cli/agent_cli/_agent_cli.py" = "blob:9241b520ba209867c37330551101bdd5d262ac88"+"pipelex/cli/agent_cli/_agent_cli.py" = "blob:d3aa51f4472da74c48de39d5b15ee3f6a2fe16a8""pipelex/cli/agent_cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"-"pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:57b6a4d76b918626218633873273adbddfaac97d"-"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:506eabec37ab3b06644b6ae4c321a91780241161"+"pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:f96268c610cdd3b7328919768d1aef1b8ba4e084"+"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:a3651bb1023350e358d7865c3e9d401b3408b5c7""pipelex/cli/agent_cli/commands/bundle_path_resolver.py" = "blob:a1904517c731afb72af7d49adf6d217dc50b2660""pipelex/cli/agent_cli/commands/check_model_cmd.py" = "blob:3a9c93daecadf266b3eba466904b3d005d448d40""pipelex/cli/agent_cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"@@ -37,11 +37,11 @@ rationale = "clean-pass: merged tree of origin/dev into this branch. Dev's check"pipelex/cli/agent_cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/run/_output_helpers.py" = "blob:40ed1700e0d5e86d7696eadd7f9887baeb8059f6""pipelex/cli/agent_cli/commands/run/_run_core.py" = "blob:32f973c5c754b23016f3e708ab3235856e8bc5f4"-"pipelex/cli/agent_cli/commands/run/_run_core_api.py" = "blob:ac949cc4c93ca8e0f18b93a68f59584a7cf1a75e"+"pipelex/cli/agent_cli/commands/run/_run_hosted.py" = "blob:8178b10eff95faf8bfac8d4c12895a47dbda9b90""pipelex/cli/agent_cli/commands/run/app.py" = "blob:64b2ecc02007cda11b526d8d3fc139593875dd9d"-"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:583624d5ec02cd7d87e7f9fbd41bedb82681afcd"-"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:ab844621c41f49f9d7aa6860b852586dce6eb784"-"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:54e09713855c1b0639883da7096ed58ebe7dbfe8"+"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:cf85194e29f44b0691eb81b216d2e506fcdd75f2"+"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:7c5f73a28e50f30196088af2435cbc2f635a65e5"+"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:08b676ee02526fd7d5ab85c6d5af70c8507ad9f3""pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:c7c7d7495508f1c4e5a46eba336a4ab1694ebcf7""pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:2a04aeff94db4afc56ac0c033a9d4add54d85c88"@@ -98,15 +98,17 @@ rationale = "clean-pass: merged tree of origin/dev into this branch. Dev's check"pipelex/cli/commands/plugins_cmd.py" = "blob:9657b713c3650ff4a929e92ae68af453d896393e""pipelex/cli/commands/resolve_cmd.py" = "blob:88237df0f048bbf5a02e585baef932bfc355e1ee""pipelex/cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"+"pipelex/cli/commands/run/_hosted_sources.py" = "blob:e7ce03fcff7d474f013d6de0882b9c468274a461""pipelex/cli/commands/run/_inputs_file_loader.py" = "blob:957e6eb00531d168b3b1e179a517717d069cb7fc""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:3d09a8142b4f5a22db7239b8eab6d199ea999eff"+"pipelex/cli/commands/run/_run_core.py" = "blob:a41aafa3ee899c51e4b3b3919d164c8aaebe2095"+"pipelex/cli/commands/run/_run_hosted.py" = "blob:dd5801877a636f71187e9b23c2fab18d4d25ba32""pipelex/cli/commands/run/app.py" = "blob:a7090b0ff6bf2f1d47827fa27d2a138096a2e148"-"pipelex/cli/commands/run/bundle_cmd.py" = "blob:13d68d533986c3938b1b2ee808819d8daf6f91db"+"pipelex/cli/commands/run/bundle_cmd.py" = "blob:18659c5024e19d94bfb3116596c0b1db34970ea2""pipelex/cli/commands/run/exceptions.py" = "blob:e9552226e597922b6ac0757f7b52eb880a2e1472"-"pipelex/cli/commands/run/method_cmd.py" = "blob:9f5c7b6ad8f7fc7d086a9e6253049c6e2ec3e7d8"-"pipelex/cli/commands/run/pipe_cmd.py" = "blob:f92fcb94e3ad55cf5aeec366a59fa7a74bcc9667"+"pipelex/cli/commands/run/method_cmd.py" = "blob:a3858adc9d74b6de5d119d8082e00995d24a95a1"+"pipelex/cli/commands/run/pipe_cmd.py" = "blob:4da3fce1bc0782b56ab75274738611ca65c655f7""pipelex/cli/commands/show_cmd.py" = "blob:4c87c70058ea3b15827d03a370f3345569a2b705""pipelex/cli/commands/update_cmd.py" = "blob:b2db6170ddd9c67f17d88096ba1f1796a897557d""pipelex/cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"diff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.tomlindex c27cf5d6e..8fe38f8ba 100644--- a/.drift/acks/config-docs.toml+++ b/.drift/acks/config-docs.toml@@ -1,8 +1,8 @@contract = "config-docs"-digest = "sha256:86496f1545d0c4bcce6d54f10321cfa29d7c32964eb197d5e06a34a7bcfaf435"-reviewed_by = "Louis Choquel"-reviewed_at = "2026-10-07T14:54:43Z"-rationale = "clean-pass: config_loader.py only gains a comment saying the backends.toml write cannot follow a link, because the return above it made sure nothing stands at that path; the fill still never writes through a link. Re-read the PIPELEX_HOME section of docs/configuration/index.md, which describes only the boot fill and stays accurate; the link-following that pipelex init keeps lives in pipelex/kit/template_copy.py and is described in docs/under-the-hood/init-cli-flows.md. No config model, default, validator or load order moved."+digest = "sha256:46c31fd39394e47c2ae4442305c8ba645a976ff45dc44286f8f3416f73a3bf11"+reviewed_by = "Claude (Opus 5.5)"+reviewed_at = "2026-10-08T12:44:52Z"+rationale = "clean-pass: merged tree of origin/dev into this branch. The open trigger changes are this branch's own, the run section in pipelex/pipelex.toml and RunConfig in configs.py, already answered on the branch by run-config.md and the five-section list in docs/configuration/index.md; dev changed only the home fill in config_loader.py. The auto-merged index.md reads as one: dev's rewritten PIPELEX_HOME section and this branch's section list touch different paragraphs. A hosted run that reads the run setting goes through load_config and so now fills a home's missing kit files like any boot; run-config.md and run.md say a hosted run boots nothing locally and needs no inference configuration, which stays true, and no doc claims it leaves the home untouched. The run path is additive, so no migration ledger entry, and neither side touched the ledgers."[trigger_files]"pipelex/cogt/config_cogt.py" = "blob:02f71cb4a6b01aebda59c2e31f262ef9c865e17b"@@ -10,14 +10,14 @@ rationale = "clean-pass: config_loader.py only gains a comment saying the backen"pipelex/graph/graph_config.py" = "blob:dc0939a6d2730c0a10b88aa1a6e0b2dd583462a6""pipelex/language/mthds_config.py" = "blob:353009ad8c59dc5266bdd9dfa42b1ad18b67dca7""pipelex/methods/methods_config.py" = "blob:76ca9a0e64f8c10ef6a355aafd0d79d36b09f06a"-"pipelex/pipelex.toml" = "blob:cb3431d9d8a3265121d730eaef34cfbe5e8c4cbf"+"pipelex/pipelex.toml" = "blob:753da7e4cefacf1cc809ba9993c003b43e7e450e""pipelex/system/configuration/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc""pipelex/system/configuration/config_check.py" = "blob:2d5de29aba3d2ce205d3d82b4623f37b53108332""pipelex/system/configuration/config_loader.py" = "blob:7563f68051a568ba90d3209c1966d678078c6de2""pipelex/system/configuration/config_model.py" = "blob:83b29dc6e93393c9b98c4353636caf0135c80339""pipelex/system/configuration/config_root.py" = "blob:c7d43851270912d17413cfc6a511247d3c7cc160""pipelex/system/configuration/config_surface.py" = "blob:dc6c877564254aa97ce0b20fd29118def31c957c"-"pipelex/system/configuration/configs.py" = "blob:3cb65cf9c3d34aef0baf92b62d8bd63e5c69d4eb"+"pipelex/system/configuration/configs.py" = "blob:1754391061f3be47e28088a4f8ea85e60b1cdd2b""pipelex/system/configuration/pipe_func_config.py" = "blob:dc8890e914fbcdb611147e42eaa0cd87b32288a5""pipelex/system/telemetry/telemetry_config.py" = "blob:068a785d97a2d52ee43e82e723cd944b8b6601bc""pipelex/tools/aws/aws_config.py" = "blob:c1aeafeae08d3921464db33795f11a29ff3892ba"diff --git a/.drift/acks/hub-layering-convention.toml b/.drift/acks/hub-layering-convention.tomlindex a75cf6999..b2da02b18 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:0d04191133ff7766daf3182784f868d2da5a724f655b9d23428a3634ec97e8d3"-reviewed_by = "Claude (Opus 5.5)"-reviewed_at = "2026-10-04T20:43:02Z"-rationale = "real-catch: the guard now declares pipelex.fix_ops and pipelex.migration; hub-layering.md's declared-package list, the paragraph that called declaring migration an overreach, and a new known inversion now say so. Re-deriving the 'every top-level package accounted for' claim from ls pipelex/ found pipelex.methods unaccounted for; measured it (structures_check imports pipelex.codegen, loading interpreter modules without reaching the hub) and added it to both the doc and the guard's note."+digest = "sha256:81bac50d761cef4a2fae569e987ff576588869e0d05eb25e8037cb83959c0680"+reviewed_by = "Louis Choquel"+reviewed_at = "2026-10-07T13:45:51Z"+rationale = "real-catch: the guard now declares pipelex.hosted in KERNEL_LAYER_PACKAGES. hub-layering.md's declared-package list names it, and the paragraph accounting for every top-level package says why it is declared in its first commit: a hosted run boots nothing and reads config, builds the pipelex-sdk client and maps the run without loading an interpreter module, while what needs a bundle parsed stays in pipelex.cli. The kernel-layer import-closure test gained its three entry points and measures it clean."[trigger_files]-"pipelex/cli/dev_cli/commands/hub_layering_guard.py" = "blob:fe10deb00e0d30f300352a0696258ab108668e3c"+"pipelex/cli/dev_cli/commands/hub_layering_guard.py" = "blob:fda2237457fe0b6830ff2ae8f720698735bec4c3""pipelex/interpreter_hub.py" = "blob:327e75d0fbb5bdf46f6cbf06024f83840f0106d0""pipelex/runtime_hub.py" = "blob:05f84b9604b9f904e7df96d222b8856123ce9e91"diff --git a/.env.example b/.env.exampleindex 3973dd0a7..9fc01baea 100644--- a/.env.example+++ b/.env.example@@ -1,3 +1,10 @@+# The hosted Pipelex API: `pipelex run --hosted` (or `[run] execution = "hosted"`) runs on it with this key alone,+# no provider key needed. Create one on app.pipelex.com.+PIPELEX_API_KEY=+# Override the hosted API's origin (scheme://host[:port]), for a staging plane or a self-hosted Pipelex API server;+# unset means https://api.pipelex.com, and --base-url on the command overrides it in turn.+# PIPELEX_BASE_URL=https://api.pipelex.com+# OpenAI: to use models like GPT-4o and GPT-5OPENAI_API_KEY=diff --git a/.pipelex/pipelex.toml b/.pipelex/pipelex.tomlindex 5524343c1..60ff964f1 100644--- a/.pipelex/pipelex.toml+++ b/.pipelex/pipelex.toml@@ -10,7 +10,8 @@# - All values below are set to their defaults - modify them as needed# - The values here will override the defaults from the Pipelex package#-# The three top-level sections mirror the layers of the runtime:+# The [run] section says where your runs execute. The three other top-level sections mirror the+# layers of the runtime:# - [runtime] process-scoped infrastructure: storage, secrets, logging, tracing, plugins# - [inference] the model-calling seam: model deck, LLM, image generation, extraction# - [interpreter] library-scoped method machinery: parsing, pipe runs, pipeline execution@@ -32,6 +33,16 @@#####################################################################################################+####################################################################################################+# Run Config+####################################################################################################++[run]+# Where `pipelex run` and `pipelex-agent run` execute a method when the command passes neither+# --hosted nor --local: "local" runs on this machine, on the backends in .pipelex/inference/ (your own+# provider keys); "hosted" runs on the hosted Pipelex API, with the key in PIPELEX_API_KEY.+execution = "local"+##################################################################################################### Storage Config####################################################################################################diff --git a/.test_durations b/.test_durationsindex 490cc6692..f6f35723a 100644--- a/.test_durations+++ b/.test_durations@@ -2000,25 +2000,25 @@"tests/unit/pipelex/cli/agent_cli/test_inputs_template_format_toml.py::TestAgentInputsTemplateFormatToml::test_no_inputs_in_json_mode_keeps_envelope": 0.0026,"tests/unit/pipelex/cli/agent_cli/test_inputs_template_format_toml.py::TestAgentInputsTemplateFormatToml::test_no_inputs_in_toml_mode_prints_comment": 0.004,"tests/unit/pipelex/cli/agent_cli/test_inputs_template_format_toml.py::TestAgentInputsTemplateFormatToml::test_toml_format_prints_raw_toml": 0.9327,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_markdown_keeps_an_item_this_version_cannot_type": 0.0062,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_payload_carries_the_pipe_members_and_retryable": 0.306,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_payload_never_borrows_a_local_hint_or_domain_for_the_runner_class": 0.2826,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_payload_of_a_refusal_the_caller_must_act_on": 0.0045,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_payload_of_an_answer_that_is_no_problem_document": 0.2866,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_payload_of_an_unavailable_service_is_never_inferred_retryable": 0.271,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_payload_of_the_gateway_refusing_a_key": 0.0031,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_payload_of_the_platform_rate_limit": 0.3184,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_run_bundle_error_format_json_overrides_markdown_format": 0.2837,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_run_bundle_json_carries_the_reason_the_pipe_and_the_next_step[combine_failure_at_run]": 0.3109,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_run_bundle_json_carries_the_reason_the_pipe_and_the_next_step[unknown_model_at_load]": 0.2895,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_run_bundle_json_carries_the_reason_the_pipe_and_the_next_step[unserved_model_at_run]": 0.2686,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_run_bundle_json_carries_the_runner_items_whole": 0.2866,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_run_bundle_markdown_names_the_reason_the_pipe_and_the_next_step[combine_failure_at_run]": 0.2843,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_run_bundle_markdown_names_the_reason_the_pipe_and_the_next_step[unknown_model_at_load]": 0.2754,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_run_bundle_markdown_names_the_reason_the_pipe_and_the_next_step[unserved_model_at_run]": 0.3032,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_run_bundle_markdown_renders_the_runner_items_as_validate_does": 0.2663,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_run_method_reports_the_refusal": 0.2715,- "tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py::TestRunApiRefusal::test_run_pipe_reports_the_refusal": 0.2889,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_markdown_keeps_an_item_this_version_cannot_type": 0.0062,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_payload_carries_the_pipe_members_and_retryable": 0.306,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_payload_never_borrows_a_local_hint_or_domain_for_the_runner_class": 0.2826,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_payload_of_a_refusal_the_caller_must_act_on": 0.0045,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_payload_of_an_answer_that_is_no_problem_document": 0.2866,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_payload_of_an_unavailable_service_is_never_inferred_retryable": 0.271,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_payload_of_the_gateway_refusing_a_key": 0.0031,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_payload_of_the_platform_rate_limit": 0.3184,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_run_bundle_error_format_json_overrides_markdown_format": 0.2837,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_run_bundle_json_carries_the_reason_the_pipe_and_the_next_step[combine_failure_at_run]": 0.3109,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_run_bundle_json_carries_the_reason_the_pipe_and_the_next_step[unknown_model_at_load]": 0.2895,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_run_bundle_json_carries_the_reason_the_pipe_and_the_next_step[unserved_model_at_run]": 0.2686,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_run_bundle_json_carries_the_runner_items": 0.2866,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_run_bundle_markdown_names_the_reason_the_pipe_and_the_next_step[combine_failure_at_run]": 0.2843,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_run_bundle_markdown_names_the_reason_the_pipe_and_the_next_step[unknown_model_at_load]": 0.2754,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_run_bundle_markdown_names_the_reason_the_pipe_and_the_next_step[unserved_model_at_run]": 0.3032,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_run_bundle_markdown_renders_the_runner_items_as_validate_does": 0.2663,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_run_method_by_address_is_resolved_by_the_hosted_api": 0.2715,+ "tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py::TestRunHostedRefusal::test_run_pipe_sends_its_library_and_reports_the_refusal": 0.2889,"tests/unit/pipelex/cli/agent_cli/test_run_bundle_auto_inputs.py::TestAgentRunBundleAutoInputs::test_auto_detects_inputs_toml": 0.9468,"tests/unit/pipelex/cli/agent_cli/test_run_bundle_auto_inputs.py::TestAgentRunBundleAutoInputs::test_both_inputs_files_error_envelope": 0.0057,"tests/unit/pipelex/cli/agent_cli/test_run_bundle_auto_inputs.py::TestAgentRunBundleAutoInputs::test_explicit_inputs_bypasses_ambiguity": 0.0914,@@ -2405,7 +2405,6 @@"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_string_literal_import_module_form_is_caught": 0.0005,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_tests_may_reference_the_interpreter_hub": 0.0004,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_the_boot_split_left_the_kernel_half_declared": 0.0007,- "tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_the_boot_split_left_the_runtime_half_declared": 0.0004,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_the_boot_tolerance_replay_stays_declared": 0.1557,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_the_measured_clean_packages_stay_declared": 0.0007,"tests/unit/pipelex/cli/dev/test_hub_layering_guard.py::TestHubLayeringGuard::test_the_pipelex_kernel_stays_declared": 0.0016,diff --git a/CHANGELOG.md b/CHANGELOG.mdindex dfa7244a4..cd358c6cc 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,10 @@## [Unreleased]+### Added++- **Runs on the hosted Pipelex API, `--runner api` removed (Breaking)**: `pipelex run method|pipe|bundle` and `pipelex-agent run` take `--hosted` / `--local` and `--base-url <scheme://host[:port]>` (over `PIPELEX_BASE_URL`, over `https://api.pipelex.com`), and the new `[run] execution = "local" | "hosted"` setting (default `local`) chooses when no flag does; a hosted run boots nothing locally, needs only `PIPELEX_API_KEY`, sends what a local run would load (`PIPELEXPATH` included) or a published address or a catalog id (`mt_…`) for the hosted API to resolve, uploads the local files named at document and image inputs (reading the method's signature only when the inputs name an existing local file), saves its outputs where a local run does, prints the run id as soon as the run is acknowledged and names it in any failure met after that, Ctrl-C included, and reports a connection lost after the run request was sent as a run that may exist rather than as a network failure. The agent CLI's global `--runner pipelex|api` and its mthds `MthdsAPIClient` path are removed: `pipelex-agent run … --runner local|hosted` replaces it, on pipelex-sdk's `PipelexAPIClient`, which `pipelex` now requires (pinned exactly, like `mthds`) and which Python callers use directly to run on the hosted API.+### Fixed- **A home configuration directory holding only some files gets the kit's missing ones**: every boot now copies into `~/.pipelex/`, or the directory `PIPELEX_HOME` names, each kit file it lacks, never overwriting one it holds or writing through a symbolic link, so a kit file deleted from it comes back. A directory holding anything at all, such as the `pipelex_service.toml` an earlier release wrote, used to be left as it was, and every boot then failed with "Config files are missing for the inference backend library". The inference files are copied as one unit, only when the directory has no `inference/backends.toml`, each file and kit manifest is written whole or not at all, so a fill cut short is completed by the next boot, and a directory Pipelex cannot write to is read as it is.diff --git a/README.md b/README.mdindex 6f2665e28..e2a2c3e5f 100644--- a/README.md+++ b/README.md@@ -190,8 +190,8 @@ The same `.mthds` file runs from multiple execution targets:| Target | How ||--------|-----|-| **CLI** | `pipelex run bundle method.mthds --inputs inputs.json` |-| **Python** | `PipelexMTHDSProtocol().execute(...)` |+| **CLI** | `pipelex run bundle method.mthds --inputs inputs.json`, on your machine, or with `--hosted` on the hosted API |+| **Python** | `PipelexMTHDSProtocol().execute(...)` in your process, or [`pipelex-sdk`](https://pypi.org/project/pipelex-sdk/)'s `PipelexAPIClient` against the hosted API || **TypeScript / Node** | [`@pipelex/sdk`](https://www.npmjs.com/package/@pipelex/sdk) against the hosted API, or [`mthds`](https://www.npmjs.com/package/mthds) against any MTHDS API || **REST API** | Self-host the [`pipelex/pipelex-api`](https://hub.docker.com/r/pipelex/pipelex-api) image, built from this repository's [`api/`](https://github.com/Pipelex/pipelex/tree/main/api) directory; the hosted API is the one in the Quick start above || **MCP** | The [Pipelex MCP](https://github.com/Pipelex/pipelex-mcp): your chatbot runs the methods saved in your account |diff --git a/docs/building-methods/pipes/executing-pipelines.md b/docs/building-methods/pipes/executing-pipelines.mdindex 0725db411..adf13fc13 100644--- a/docs/building-methods/pipes/executing-pipelines.md+++ b/docs/building-methods/pipes/executing-pipelines.md@@ -1,5 +1,5 @@----description: "Run Pipelex pipelines from the CLI, Python API, or Pipelex Client. Execute .mthds bundles and retrieve structured outputs programmatically."+description: "Run Pipelex pipelines from the CLI or the Python API, locally or on the hosted Pipelex API. Execute .mthds bundles and retrieve structured outputs programmatically."---# Executing Pipelines@@ -216,7 +216,9 @@ pipe_output = response.pipe_output## Using the Pipelex API-The [Pipelex API server](../../api-server/index.md) runs pipelines over HTTP on infrastructure you host yourself: it is published as the `pipelex/pipelex-api` Docker image, and [Pipe Run](../../api-server/pipe-run.md) documents its `/v1/execute` and `/v1/start` routes.+Everything above runs in your own process, with your own inference backends. To run on the hosted Pipelex API instead, with only a Pipelex API key, use pipelex-sdk's `PipelexAPIClient`, which is installed with `pipelex`: see [Running on the Hosted API from Python](running-on-the-hosted-api.md). From the CLI, the same runs take `--hosted`, see [Running on the Hosted API](../../tools/cli/run.md#running-on-the-hosted-api).++The [Pipelex API server](../../api-server/index.md) runs pipelines over HTTP on infrastructure you host yourself: it is published as the `pipelex/pipelex-api` Docker image, and [Pipe Run](../../api-server/pipe-run.md) documents its `/v1/execute` and `/v1/start` routes. The same client reaches it when its base URL points there.---diff --git a/docs/building-methods/pipes/running-on-the-hosted-api.md b/docs/building-methods/pipes/running-on-the-hosted-api.mdnew file mode 100644index 000000000..bb448b123--- /dev/null+++ b/docs/building-methods/pipes/running-on-the-hosted-api.md@@ -0,0 +1,90 @@+---+description: "Run methods on the hosted Pipelex API from Python with pipelex-sdk's PipelexAPIClient, the hosted half of the Pipelex Python API."+---++# Running on the Hosted API from Python++The Pipelex Python API has two halves. `PipelexMTHDSProtocol`, shown in [Executing Pipelines](executing-pipelines.md), runs a method in your own process, with your own inference backends and provider keys. **`PipelexAPIClient`**, from the `pipelex-sdk` package, runs it on the hosted Pipelex API, with only a Pipelex API key. `pipelex-sdk` is a dependency of `pipelex`, so it is installed with it, and it is the client `pipelex run --hosted` uses under the hood.++Use the client directly: it has no Pipelex wrapper, and it needs no `Pipelex.make()`, since nothing runs locally.++## The Key and the Origin++The client reads its key from `PIPELEX_API_KEY` and its origin from `PIPELEX_BASE_URL`, falling back to `https://api.pipelex.com`. Both can also be passed to the constructor, as `api_key=` and `base_url=`. The client reads the process environment only. To use a key saved in `~/.pipelex/.env`, as `pipelex run --hosted` does, import `pipelex.system.environment` before creating the client: importing it loads `~/.pipelex/.env` (or the one in `PIPELEX_HOME`), then a `.env` in the working directory.++## Running a Method++The client runs the same three sources the CLI does: a published method by its address (`method_ref`), a method stored on the hosted platform by its catalog id (`method_id`), or your own bundle by its contents (`mthds_contents`). `start_and_wait` starts the run and polls it until it ends, so a long run is not cut short by a synchronous request's timeout.++```python+import asyncio++from pipelex_sdk.client import PipelexAPIClient+++async def main() -> None:+ async with PipelexAPIClient() as client:+ results = await client.start_and_wait(+ method_ref="github.com/Pipelex/methods/[email protected]",+ inputs={"text": "Hello world. Second sentence."},+ )+ print(results.pipeline_run_id)+ print(results.main_stuff["text"])+++asyncio.run(main())+```++`results.main_stuff` is the main output's content, as JSON. `results.working_memory` holds every stuff of the run, each naming its concept by ref, and `results.graph_spec` the run's execution graph.++To run your own bundle, send its contents and name the pipe, or leave `pipe_code` out to run the bundle's `main_pipe`:++```python+from pathlib import Path++results = await client.start_and_wait(+ pipe_code="summarize",+ mthds_contents=[Path("my_bundle.mthds").read_text(encoding="utf-8")],+ inputs={"text": "…"},+)+```++## Inputs That Name Local Files++The hosted API cannot read your machine's files, so a document or an image given as a local path is uploaded first. `prepare_inputs` reads the pipe's signature from the hosted API, uploads each local file found at a document or image input, and returns the inputs with each one replaced by its storage URI. It takes the method the same way the run does, and the pipe as its qualified ref, `domain.pipe_code`:++```python+prepared = await client.prepare_inputs(+ method_ref="github.com/Pipelex/methods/[email protected]",+ pipe_ref="documents.extract_document_text",+ inputs={"document": "invoices/march.pdf"},+)+results = await client.start_and_wait(+ method_ref="github.com/Pipelex/methods/[email protected]",+ pipe_code="extract_document_text",+ inputs=prepared.inputs,+)+```++A relative path is read from the working directory, and a `file://` URI is not decoded, so pass the path itself. `http(s)://` URLs are passed through for the hosted API to fetch. Call `prepare_inputs` only when the inputs name a local file: other inputs can go to the run as they are.++Two cases where `pipelex run --hosted` goes further than `prepare_inputs`:++- `prepare_inputs` refuses an explicit `None` at a document or image input. Leave an optional file out of the inputs rather than setting it to `None`. The CLI uploads the files itself and keeps the `null` for the run.+- `prepare_inputs` reads the signature through a route that cannot load a method calling another method by its address (`github.com/…`), so it refuses such a method, which `start_and_wait` runs. Give its files as `https://` URLs and start the run without preparing the inputs.++## Errors++A failure is one of the SDK's typed errors, from `pipelex_sdk.errors`, all subclasses of the protocol's `PipelineRequestError`, with one exception: `start` and `execute`, which the client inherits from the MTHDS protocol client, let httpx's transport errors through. A `ConnectError` or a `ConnectTimeout` means the request never left your machine. A `ReadError`, a `RemoteProtocolError` or a `ReadTimeout` can come after the hosted API received it, so a run may exist with no id returned: check the run history on app.pipelex.com before starting it again.++- `ApiResponseError` is a refusal the hosted API answered: `status`, the reason in `server_message`, the next step in `user_action.detail` when the server advised one, and `validation_errors` locating the faults of a bundle it refused to load.+- `RunFailedError` is a run that started and failed; `error` holds its stored report, with the runner's `error_type`, `message`, `error_domain` and `user_action`.+- `RunTimeoutError` is a run that outlived the wait; it keeps running, and `run_id` reads its result later with `wait_for_result`.+- `ApiUnreachableError` is a hosted API that could not be reached at all, on the routes the SDK owns: the signature read, the uploads, and the polling of a started run.+- `InputPreparationError` and its subclasses are a local file that could not be read or uploaded.++## Related Documentation++- [Running on the Hosted API](../../tools/cli/run.md#running-on-the-hosted-api) — The same runs from `pipelex run --hosted`+- [Run Configuration](../../configuration/config-practical/run-config.md) — Making hosted runs the CLI's default+- [Executing Pipelines](executing-pipelines.md) — The local half of the Python APIdiff --git a/docs/configuration/config-practical/run-config.md b/docs/configuration/config-practical/run-config.mdnew file mode 100644index 000000000..f12f7f908--- /dev/null+++ b/docs/configuration/config-practical/run-config.md@@ -0,0 +1,49 @@+---+description: "Choose where pipelex run executes a method by default: on this machine with your own inference, or on the hosted Pipelex API."+---++# Run Configuration++The `[run]` section says where `pipelex run` and `pipelex-agent run` execute a method when the command does not say.++## Configuration Options++```python+class RunExecution(StrEnum):+ LOCAL = "local"+ HOSTED = "hosted"+++class RunConfig(ConfigModel):+ execution: RunExecution+```++### Fields++- `execution`: where a run executes when the command passes neither `--hosted` nor `--local` (nor `--runner` on the agent CLI).+ - `"local"` (the default) runs on this machine, with the inference backends configured in `.pipelex/inference/` and your own provider keys.+ - `"hosted"` runs on the hosted Pipelex API, with the Pipelex API key in `PIPELEX_API_KEY`, at the origin in `PIPELEX_BASE_URL` (`https://api.pipelex.com` when unset). Nothing is booted locally, so no provider key or inference configuration is needed on this machine.++A flag on the command always wins: with `execution = "hosted"`, `pipelex run … --local` still runs on this machine, and with `"local"`, `--hosted` sends that one run to the hosted API.++## Example Configuration++```toml+[run]+execution = "hosted"+```++Put it in your project's `.pipelex/pipelex.toml` to make hosted runs the default for one project, or in `~/.pipelex/pipelex.toml` for every project on the machine; the project's file wins over the global one.++## The Key and the Origin++A hosted run reads its key and its origin from the environment, never from this file:++- `PIPELEX_API_KEY` holds the Pipelex API key (`plx_sk_…`). Export it in your shell, or save it in `~/.pipelex/.env`, which Pipelex loads at startup.+- `PIPELEX_BASE_URL` overrides the origin, for a staging plane or a self-hosted Pipelex API server. `--base-url` on the command overrides it in turn. Either must be `scheme://host[:port]`, with no path such as `/v1`.++## Related Documentation++- [Running on the Hosted API](../../tools/cli/run.md#running-on-the-hosted-api) — What a hosted run sends, uploads, saves and refuses+- [Running on the Hosted API from Python](../../building-methods/pipes/running-on-the-hosted-api.md) — The pipelex-sdk client, the hosted half of the Python API+- [Agent CLI](../../tools/cli/agent-cli.md) — `pipelex-agent run --runner local|hosted`diff --git a/docs/configuration/index.md b/docs/configuration/index.mdindex fea3fe1bf..72dd275a2 100644--- a/docs/configuration/index.md+++ b/docs/configuration/index.md@@ -66,12 +66,13 @@ In addition to the base `pipelex.toml`, Pipelex applies override files from **in## Configuration Structure-The configuration is organized into four main sections, which mirror the layers of the runtime:+The configuration is organized into five main sections. The first three mirror the layers of the runtime:1. `[runtime]` - process-scoped infrastructure: storage, secrets, logging, cloud credentials, outbound network posture, reporting, tracing, observation, and the plugin denylist2. `[inference]` - the model-calling seam: the model deck, LLM, image generation, extraction, the default templating style, and dry-run mocks3. `[interpreter]` - library-scoped method machinery: MTHDS parsing, pipe runs, pipe functions, pipeline execution, source scanning, and the builder-4. `[kit]` - settings for the `pipelex-dev` kit tooling+4. `[run]` - where `pipelex run` and `pipelex-agent run` execute a method by default: on this machine or on the hosted Pipelex API, see [Run Configuration](config-practical/run-config.md)+5. `[kit]` - settings for the `pipelex-dev` kit toolingEach section contains multiple subsections for specific features and functionalities. A setting's address tells you which layer owns it: `[runtime.*]` applies to any process, whatever it loads; `[interpreter.*]` only means something once a method is loaded.diff --git a/docs/contribute/hub-layering.md b/docs/contribute/hub-layering.mdindex 17a43a38a..56e9adc90 100644--- a/docs/contribute/hub-layering.md+++ b/docs/contribute/hub-layering.md@@ -243,9 +243,9 @@ make check-hub-layering # alias: make chlAn AST guard (`pipelex-dev check-hub-layering`, core in `pipelex/cli/dev_cli/commands/hub_layering_guard.py`) that runs in `make agent-check`, in the `make check` aggregate, and in CI. It checks three rules over `pipelex/` and `tests/`:-1. **The layer rule.** A module in the declared kernel layer — `pipelex.cogt`, `pipelex.core`, `pipelex.errors`, `pipelex.fix_ops`, `pipelex.graph`, `pipelex.kernel`, `pipelex.migration`, `pipelex.observer`, `pipelex.plugins`, `pipelex.providers`, `pipelex.reporting`, `pipelex.system`, `pipelex.test_extras`, `pipelex.tools`, `pipelex.tracing`, plus the `pipelex.runtime_hub` and `pipelex.runtime_boot` modules themselves — may not import `pipelex.interpreter_hub`. The declaration is compliant with an empty exception list, so the guard hard-blocks on **any** violation. Entries are matched exact-or-dotted-prefix, which is why a bare *module* is a legal entry beside the packages: without `pipelex.runtime_hub` spelled out, the module at the centre of the rule would be exempt from it, and without `pipelex.runtime_boot` the kernel layer's own composition root would be — see [Where the boot splits](#where-the-boot-splits). `pipelex.core` was six entries until its interpreter tenants moved out — see [Where core splits](#where-core-splits) for what that enumeration was working around.+1. **The layer rule.** A module in the declared kernel layer — `pipelex.cogt`, `pipelex.core`, `pipelex.errors`, `pipelex.fix_ops`, `pipelex.graph`, `pipelex.hosted`, `pipelex.kernel`, `pipelex.migration`, `pipelex.observer`, `pipelex.plugins`, `pipelex.providers`, `pipelex.reporting`, `pipelex.system`, `pipelex.test_extras`, `pipelex.tools`, `pipelex.tracing`, plus the `pipelex.runtime_hub` and `pipelex.runtime_boot` modules themselves — may not import `pipelex.interpreter_hub`. The declaration is compliant with an empty exception list, so the guard hard-blocks on **any** violation. Entries are matched exact-or-dotted-prefix, which is why a bare *module* is a legal entry beside the packages: without `pipelex.runtime_hub` spelled out, the module at the centre of the rule would be exempt from it, and without `pipelex.runtime_boot` the kernel layer's own composition root would be — see [Where the boot splits](#where-the-boot-splits). `pipelex.core` was six entries until its interpreter tenants moved out — see [Where core splits](#where-core-splits) for what that enumeration was working around.- `graph`, `tracing`, `observer` and `errors` joined the list late, and the delay cost something — see [Known inversions](#known-inversions). They are the run-graph data model with its tracer and renderers, the trace-event assembler feeding it, the run-observation hooks, and the error taxonomy: machinery present at execution time whatever is loaded, which is the kernel layer's own definition. `pipelex.test_extras` is on the list for the same reason: it ships, `runtime_boot.py` imports it at boot, and it measures clean. `pipelex.kernel` is the same rule applied *ahead* of a breach instead of behind one: it was declared in the commit that created the package, because it holds the operator-execution semantics the interpreter's operator classes call into, and a single `interpreter_hub` reach anywhere in it would put the interpreter back into every programmatic caller — the property the package exists to provide. `pipelex.kit` is data files with no module to police; `pipelex.language`, `pipelex.runtime_bridge` and `pipelex.cli` all measure dirty and are interpreter-side by construction. `pipelex.methods` measures dirty as well, without reaching `interpreter_hub`: its structures check reads the stamp the code generator writes, and `pipelex.codegen` is an interpreter package. `pipelex.migration` and `pipelex.fix_ops` are declared because a kernel-layer boot *runs* them: a configuration file that fails validation is replayed through the migration engine in memory before the boot gives up, so the engine is part of every kernel-layer boot that meets a stale file. `fix_ops` holds the applier and the file transaction the engine shares with the `.mthds` fix loop, one applier and one set of transaction primitives for both; it sits below the interpreter layer so that sharing them costs the kernel nothing — see [Known inversions](#known-inversions) for what it cost while they lived under `pipelex.pipeline`. `system/configuration/config_surface.py` still defers the engine import into the boot-tolerance retry, but only so that a healthy boot never loads it, not to keep the layering. That is every top-level package accounted for — which is the point, because the rule of thumb is that a measured-clean package should be *declared*, not left undeclared: **an undeclared package is not neutral, it is unpoliced.**+ `graph`, `tracing`, `observer` and `errors` joined the list late, and the delay cost something — see [Known inversions](#known-inversions). They are the run-graph data model with its tracer and renderers, the trace-event assembler feeding it, the run-observation hooks, and the error taxonomy: machinery present at execution time whatever is loaded, which is the kernel layer's own definition. `pipelex.test_extras` is on the list for the same reason: it ships, `runtime_boot.py` imports it at boot, and it measures clean. `pipelex.kernel` is the same rule applied *ahead* of a breach instead of behind one: it was declared in the commit that created the package, because it holds the operator-execution semantics the interpreter's operator classes call into, and a single `interpreter_hub` reach anywhere in it would put the interpreter back into every programmatic caller — the property the package exists to provide. `pipelex.hosted` was declared in its first commit for the same reason: a hosted run boots nothing and must work on a machine with no inference configured, so it reads the configuration files, builds pipelex-sdk's client and maps a run onto it without loading a single interpreter module; what needs a bundle parsed stays in `pipelex.cli`. `pipelex.kit` is data files with no module to police; `pipelex.language`, `pipelex.runtime_bridge` and `pipelex.cli` all measure dirty and are interpreter-side by construction. `pipelex.methods` measures dirty as well, without reaching `interpreter_hub`: its structures check reads the stamp the code generator writes, and `pipelex.codegen` is an interpreter package. `pipelex.migration` and `pipelex.fix_ops` are declared because a kernel-layer boot *runs* them: a configuration file that fails validation is replayed through the migration engine in memory before the boot gives up, so the engine is part of every kernel-layer boot that meets a stale file. `fix_ops` holds the applier and the file transaction the engine shares with the `.mthds` fix loop, one applier and one set of transaction primitives for both; it sits below the interpreter layer so that sharing them costs the kernel nothing — see [Known inversions](#known-inversions) for what it cost while they lived under `pipelex.pipeline`. `system/configuration/config_surface.py` still defers the engine import into the boot-tolerance retry, but only so that a healthy boot never loads it, not to keep the layering. That is every top-level package accounted for — which is the point, because the rule of thumb is that a measured-clean package should be *declared*, not left undeclared: **an undeclared package is not neutral, it is unpoliced.**2. **The dead-module rule.** *No* scanned module may reference `pipelex.hub`. It was deleted rather than aliased so a stale import fails loudly; this closes the one hole in that guarantee.3. **The transitive rule.** No kernel-layer module may *reach* `pipelex.interpreter_hub` either, through any chain of module-level imports. Rules 1 and 2 are per-file and see one hop; this one resolves the whole module-level import graph of `pipelex/` and does reachability over it, reporting the shortest chain and the line of its first hop. It exists because the one-hop rules missed a live breach for a whole release: four modules of the declared kernel-layer `pipelex.plugins` package reached the interpreter hub through `runtime_bridge`, `pipeline` and `pipe_operators`, and both gates stayed green (see [Known inversions](#known-inversions)). A *direct* import is left to rule 1, which names the more specific remedy, rather than reported twice.diff --git a/docs/errors/hosted-base-url-error.md b/docs/errors/hosted-base-url-error.mdnew file mode 100644index 000000000..369e55bce--- /dev/null+++ b/docs/errors/hosted-base-url-error.md@@ -0,0 +1,22 @@+---+title: "Hosted base url"+description: "Reference for the `HostedBaseUrlError` Pipelex error class."+---++<!-- pipelex:generated -->++# Hosted base url++The base URL of the hosted API is not an origin: it carries a path, a query, credentials, or a scheme other than http or https.++| Field | Value |+|---|---|+| `error_type` | `HostedBaseUrlError` |+| `title` | Hosted base url |+| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-base-url-error/` |+| `error_domain` | `input` |+| Defined in | `pipelex.hosted.exceptions` |+| Parent class | [`HostedRunError`](hosted-run-error.md) |+| `user_action` | `change_input` — Give the hosted API's origin as scheme://host[:port], such as https://api.pipelex.com, in --base-url or PIPELEX_BASE_URL |++[Back to Error Reference](index.md)diff --git a/docs/errors/hosted-local-file-upload-unavailable-error.md b/docs/errors/hosted-local-file-upload-unavailable-error.mdnew file mode 100644index 000000000..356c780ab--- /dev/null+++ b/docs/errors/hosted-local-file-upload-unavailable-error.md@@ -0,0 +1,22 @@+---+title: "Hosted local file upload unavailable"+description: "Reference for the `HostedLocalFileUploadUnavailableError` Pipelex error class."+---++<!-- pipelex:generated -->++# Hosted local file upload unavailable++A hosted run's inputs name a local file, and its method calls another method by its address.++| Field | Value |+|---|---|+| `error_type` | `HostedLocalFileUploadUnavailableError` |+| `title` | Hosted local file upload unavailable |+| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-local-file-upload-unavailable-error/` |+| `error_domain` | `input` |+| Defined in | `pipelex.hosted.exceptions` |+| Parent class | [`HostedRunError`](hosted-run-error.md) |+| `user_action` | `change_input` — Pass each local file as an https URL the hosted API can fetch, instead of a path on this machine, then run again |++[Back to Error Reference](index.md)diff --git a/docs/errors/hosted-method-invalid-error.md b/docs/errors/hosted-method-invalid-error.mdnew file mode 100644index 000000000..7beef1fd0--- /dev/null+++ b/docs/errors/hosted-method-invalid-error.md@@ -0,0 +1,22 @@+---+title: "Hosted method invalid"+description: "Reference for the `HostedMethodInvalidError` Pipelex error class."+---++<!-- pipelex:generated -->++# Hosted method invalid++The hosted API read the method's signature before the run and found that the method does not load.++| Field | Value |+|---|---|+| `error_type` | `HostedMethodInvalidError` |+| `title` | Hosted method invalid |+| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-method-invalid-error/` |+| `error_domain` | `input` |+| Defined in | `pipelex.hosted.exceptions` |+| Parent class | [`HostedRunError`](hosted-run-error.md) |+| `user_action` | `change_input` — Fix the method as each validation error says, then run it again |++[Back to Error Reference](index.md)diff --git a/docs/errors/hosted-run-error.md b/docs/errors/hosted-run-error.mdnew file mode 100644index 000000000..bca5a8736--- /dev/null+++ b/docs/errors/hosted-run-error.md@@ -0,0 +1,21 @@+---+title: "Hosted run error"+description: "Reference for the `HostedRunError` Pipelex error class."+---++<!-- pipelex:generated -->++# Hosted run error++Base class for errors pipelex raises itself while running a method on the hosted Pipelex API.++| Field | Value |+|---|---|+| `error_type` | `HostedRunError` |+| `title` | Hosted run error |+| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-run-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.hosted.exceptions` |+| Parent class | [`PipelexError`](pipelex-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/hosted-run-interrupted-error.md b/docs/errors/hosted-run-interrupted-error.mdnew file mode 100644index 000000000..3dad19829--- /dev/null+++ b/docs/errors/hosted-run-interrupted-error.md@@ -0,0 +1,21 @@+---+title: "Hosted run interrupted"+description: "Reference for the `HostedRunInterruptedError` Pipelex error class."+---++<!-- pipelex:generated -->++# Hosted run interrupted++The hosted run was interrupted on this machine, by Ctrl-C or a cancellation, while it was being started or followed.++| Field | Value |+|---|---|+| `error_type` | `HostedRunInterruptedError` |+| `title` | Hosted run interrupted |+| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-run-interrupted-error/` |+| `error_domain` | `runtime` |+| Defined in | `pipelex.hosted.exceptions` |+| Parent class | [`HostedRunError`](hosted-run-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/hosted-run-outcome-unknown-error.md b/docs/errors/hosted-run-outcome-unknown-error.mdnew file mode 100644index 000000000..156b25737--- /dev/null+++ b/docs/errors/hosted-run-outcome-unknown-error.md@@ -0,0 +1,22 @@+---+title: "Hosted run outcome unknown"+description: "Reference for the `HostedRunOutcomeUnknownError` Pipelex error class."+---++<!-- pipelex:generated -->++# Hosted run outcome unknown++The request that runs the method was sent, and the connection failed before its answer came back.++| Field | Value |+|---|---|+| `error_type` | `HostedRunOutcomeUnknownError` |+| `title` | Hosted run outcome unknown |+| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-run-outcome-unknown-error/` |+| `error_domain` | `runtime` |+| Defined in | `pipelex.hosted.exceptions` |+| Parent class | [`HostedRunError`](hosted-run-error.md) |+| `user_action` | `unknown` — A run may have started on the hosted API before the connection failed: check the run history on app.pipelex.com before running again, since running again starts a new, paid run |++[Back to Error Reference](index.md)diff --git a/docs/errors/hosted-run-polling-error.md b/docs/errors/hosted-run-polling-error.mdnew file mode 100644index 000000000..b06a56e4d--- /dev/null+++ b/docs/errors/hosted-run-polling-error.md@@ -0,0 +1,21 @@+---+title: "Hosted run polling"+description: "Reference for the `HostedRunPollingError` Pipelex error class."+---++<!-- pipelex:generated -->++# Hosted run polling++A run started on the hosted API, but following it to its result failed: the network, the hosted API, or its answer.++| Field | Value |+|---|---|+| `error_type` | `HostedRunPollingError` |+| `title` | Hosted run polling |+| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-run-polling-error/` |+| `error_domain` | `runtime` |+| Defined in | `pipelex.hosted.exceptions` |+| Parent class | [`HostedRunError`](hosted-run-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/hosted-run-source-error.md b/docs/errors/hosted-run-source-error.mdnew file mode 100644index 000000000..9f41374ef--- /dev/null+++ b/docs/errors/hosted-run-source-error.md@@ -0,0 +1,21 @@+---+title: "Hosted run source"+description: "Reference for the `HostedRunSourceError` Pipelex error class."+---++<!-- pipelex:generated -->++# Hosted run source++A hosted run cannot be given the method to run: no bundle file, no `.mthds` file in the library directories, or no source at all.++| Field | Value |+|---|---|+| `error_type` | `HostedRunSourceError` |+| `title` | Hosted run source |+| `type_uri` | `https://docs.pipelex.com/latest/errors/hosted-run-source-error/` |+| `error_domain` | `input` |+| Defined in | `pipelex.hosted.exceptions` |+| Parent class | [`HostedRunError`](hosted-run-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/index.md b/docs/errors/index.mdindex cf99d4329..2d9efe185 100644--- a/docs/errors/index.md+++ b/docs/errors/index.md@@ -18,7 +18,7 @@ the error came from:- [Authoring & language](authoring-and-language.md) — MTHDS parsing, Core language, Pipe operators, Pipe controllers, Pipe signatures, Libraries.- [Execution & runtime](execution-and-runtime.md) — Pipe execution, Pipeline execution, Runtime bridge, Graph, Tracing.- [Inference & providers](inference-and-providers.md) — Inference (Cogt), Provider adapters, Plugin system.-- [Platform & tooling](platform-and-tooling.md) — Base & root errors, Tools, Kit, System & configuration, CLI, Codegen, Fix ops, Methods, Migration.+- [Platform & tooling](platform-and-tooling.md) — Base & root errors, Tools, Kit, System & configuration, CLI, Codegen, Fix ops, Hosted, Methods, Migration.See [Error Model](../under-the-hood/error-model.md) for the underlying contractand classification rules.diff --git a/docs/errors/platform-and-tooling.md b/docs/errors/platform-and-tooling.mdindex a7ce3f0c3..b1d35e67c 100644--- a/docs/errors/platform-and-tooling.md+++ b/docs/errors/platform-and-tooling.md@@ -103,6 +103,17 @@ own page. Classes are grouped by subsystem.- [`FixTransactionError`](fix-transaction-error.md) — Fix transaction- [`FixWriteConflictError`](fix-write-conflict-error.md) — Fix write conflict+## Hosted++- [`HostedBaseUrlError`](hosted-base-url-error.md) — Hosted base url+- [`HostedLocalFileUploadUnavailableError`](hosted-local-file-upload-unavailable-error.md) — Hosted local file upload unavailable+- [`HostedMethodInvalidError`](hosted-method-invalid-error.md) — Hosted method invalid+- [`HostedRunError`](hosted-run-error.md) — Hosted run error+- [`HostedRunInterruptedError`](hosted-run-interrupted-error.md) — Hosted run interrupted+- [`HostedRunOutcomeUnknownError`](hosted-run-outcome-unknown-error.md) — Hosted run outcome unknown+- [`HostedRunPollingError`](hosted-run-polling-error.md) — Hosted run polling+- [`HostedRunSourceError`](hosted-run-source-error.md) — Hosted run source+## Methods- [`MethodDependencyFetchError`](method-dependency-fetch-error.md) — Method dependency fetchdiff --git a/docs/get-started/run-it-yourself.md b/docs/get-started/run-it-yourself.mdindex acef451de..e307b70f6 100644--- a/docs/get-started/run-it-yourself.md+++ b/docs/get-started/run-it-yourself.md@@ -39,6 +39,7 @@ uv tool install "pipelex[cli,anthropic,google,google-genai,mistralai,bedrock,fal- **Bring Your Own Keys** — Use existing API keys from OpenAI, Anthropic, Google, Mistral, etc. See [Configure AI Providers](./configure-ai-providers.md).- **Local AI** — Ollama, vLLM, LM Studio, or llama.cpp — no API keys required. See [Configure AI Providers](./configure-ai-providers.md).+- **The hosted API** — Set `PIPELEX_API_KEY` and add `--hosted` to a run, or set `[run] execution = "hosted"`, to run on the hosted Pipelex API with no provider key on this machine. See [Running on the Hosted API](../tools/cli/run.md#running-on-the-hosted-api).## Run a methoddiff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.mdindex 7d35d92c3..346f5d182 100644--- a/docs/tools/cli/agent-cli.md+++ b/docs/tools/cli/agent-cli.md@@ -14,11 +14,13 @@ It ships in the same `cli` extra as the main CLI, `uv tool install "pipelex[cli]| Option | Description ||--------|-------------|-| `--runner` | Select the runner backend to use (`pipelex` or `api`) || `--version` | Print the version handshake — the runtime version, the MTHDS Protocol version and the MTHDS standard version — and exit. Same three lines as `pipelex --version`; see the [CLI reference](index.md#the-version-handshake) |There is no `--log-level` flag: `pipelex-agent` is machine-consumed, so logging is cut off process-wide by design.+!!! warning "`--runner api` is gone"+ The global `--runner pipelex|api` option and its MTHDS API runner path are removed. Where a run executes is now a `run` subcommand option, `--runner local|hosted`, and the hosted value runs on the hosted Pipelex API through pipelex-sdk, with the key in `PIPELEX_API_KEY` rather than `MTHDS_API_KEY`. A self-hosted runner is reached with `--runner hosted --base-url <origin>`. To target an arbitrary MTHDS runner, use the vendor-neutral `mthds-agent` CLI.+## Commands OverviewThe agent CLI mirrors the main CLI's subcommand structure for `run`, `validate`, and `inputs`, each with `pipe`, `bundle`, and `method` subcommands. It also provides `fix bundle` for deterministic in-place repairs.@@ -43,9 +45,18 @@ pipelex-agent run method <NAME> [OPTIONS]- `--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)+- `--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.+#### Running on the hosted API++With `--runner hosted` (or `--hosted`, or `[run] execution = "hosted"`), the run executes on the hosted Pipelex API and nothing local is booted: no provider key or inference configuration is needed on this machine, only a Pipelex API key in `PIPELEX_API_KEY` (in the shell, or in `~/.pipelex/.env`). What the run sends is what a local run would load. `run bundle` sends the bundle, then every `.mthds` file of its library directories. `run pipe` sends its library directories' files (the installed method exporting the pipe and `-L`, else `PIPELEXPATH`) and is refused when it has none. `run method` sends an installed or local method's files, but a published address (`github.com/owner/repo[/name][@tag]`) goes as a `method_ref` and a stored method's catalog id (`mt_…`) as a `method_id`, both resolved by the hosted API, so nothing is fetched or read locally and `-L` is refused with them. A local file named at a document or image input is uploaded first (a relative path in an inputs file resolves against that file's directory, and a `file://` URI is read as its path), and the run's inputs carry its storage URI; an explicit `null`, such as an optional image left out, reaches the run as `null`. The method's signature is read only when some value of the inputs names an existing file on this machine, so inputs naming none go straight to the run, a method calling another one by its address included. Such a method cannot have a local file uploaded yet: give the file as an `https://` URL. `run bundle` on a bundle file with no `-L` sends `PIPELEXPATH`'s files too, as a local run loads them, and `run method` takes a method installed under a name spelled like a catalog id (`mt_reports`) as that method. `--dry-run` and `--mock-inputs` are refused on a hosted run.++The success envelope has the shape of a local run's. Compact, it is the main output's content. With `--with-memory`, `main_stuff.json` is that content (the hosted API renders no Markdown, so the markdown output shows the JSON), `working_memory` is the whole working memory, `pipeline_run_id` names the run on the hosted API, and `uploads` lists the files uploaded for it. A hosted run writes nothing to disk.+A run refuses an invalid bundle while loading it, before any pipe runs, with exit code `1` and 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 bundle's own directory) 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.!!! note "Stdin inputs stay JSON"@@ -192,7 +203,9 @@ For the structured commands, exactly one such object is written to stderr per fa**A failed run** (`run pipe`, `run bundle`, `run method`) reports `"error_type": "PipelineExecutionError"` and adds four fields: `pipe_code` and `pipe_stack` name the pipe that failed and its path from the entry pipe, and `cause_type` and `cause_message` give the class and own message of the root fault, the innermost Pipelex error behind the failure. The `message` is that root fault's message prefixed with the failing pipe and its path (`Pipe 'summarize' failed (two_steps → summarize): …`), and the classification fields are the root fault's, so branch on `cause_type` to tell, say, a model that is not available from a failure to combine a parallel's results.-**A run the API runner refuses** (`--runner api`, when the runner answers `/v1/execute` with a non-2xx status) reports what the runner's problem document says, in the same envelope and the same markdown. `error_type` is the runner's error class: `ValidateBundleError` for a bundle refused before any pipe ran, as a local run reports it, or the root fault of a run that failed, such as `ModelNotFoundError` or `StuffFactoryError`, which a local run reports as `cause_type` under the `error_type` `PipelineExecutionError`. There is no `cause_type` on this path, so a consumer of a refused API run branches on `error_type`, which is `ApiResponseError` when the answer names no class, as a gateway's error page does not. The `message` quotes the request, the status and the runner's reason (`API POST /v1/execute failed (422): Pipe 'condense_article' failed (digest_article → condense_article): …`), so on a failed run it names the failing pipe and its path. The `hint` is the runner's next step; `error_domain`, `error_category` and `retryable` are the runner's own; `validation_errors` holds the runner's items whole, rendered in markdown as the same grouped prose `validate` prints; `pipe_code` and `pipe_stack` appear when the problem document carries them; `error_code` is the problem's `code`, the stable code a hosted plane gives the refusals it authors itself (`rate_limited`, `unauthorized`); `retry_after_seconds` is the delay of a `Retry-After` header; and `http_status` and `request_id` are what to quote when the fault is the runner's. When the answer advised no next step, the `hint` follows its status, never the local advice kept for the runner's class: a 401 or a 403 points at the API key; a 404 points at `MTHDS_BASE_URL`, which must be the runner's origin with no path such as `/v1`; a 429 says to wait and run again and marks the error `retryable` unless the answer said otherwise; a 503 says to wait too but warns that running again can repeat a paid run, because the service in front of the runner can answer it after the run completed, so it is `retryable` only when the answer says so; any other 4xx says to change what the message names; and any other status says to report the `request_id`, or the `http_status` when there is none. The API runner takes its key and its origin from `MTHDS_API_KEY` and `MTHDS_BASE_URL` (or `mthds config set api-key` and `base-url`), and a missing one is a `ClientAuthenticationError`.+**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 stable code the hosted plane gives the refusals it authors itself (`rate_limited`, `unauthorized`); `retry_after_seconds` is the delay of a `Retry-After` header; and `http_status` and `request_id` are what to quote when the fault is the runner's. When the answer advised no next step, the `hint` follows its status, never the local advice kept for the runner's class: a 401 or a 403 points at `PIPELEX_API_KEY`; 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 hosted run that started and failed** reports its stored error report: `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 report'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`.**`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.diff --git a/docs/tools/cli/index.md b/docs/tools/cli/index.mdindex 01b7aae45..e18059085 100644--- a/docs/tools/cli/index.md+++ b/docs/tools/cli/index.md@@ -29,7 +29,7 @@ The Pipelex CLI is organized into several command groups:| [**validate**](validate.md) | Validate configuration and pipelines || [**fix**](fix.md) | Apply deterministic safe fixes to a bundle and re-validate || [**show**](show.md) | Inspect configuration, pipes, and AI models |-| [**run**](run.md) | Execute pipelines |+| [**run**](run.md) | Execute pipelines, on this machine or on the hosted Pipelex API || [**run method by address**](run-by-address.md) | Fetch and run a method straight from a public GitHub repository || [**build**](build/index.md) | Generate concept structures and example inputs and outputs for a pipe |diff --git a/docs/tools/cli/run-by-address.md b/docs/tools/cli/run-by-address.mdindex fb6a33c32..0837f9600 100644--- a/docs/tools/cli/run-by-address.md+++ b/docs/tools/cli/run-by-address.md@@ -48,6 +48,14 @@ The pipe to run defaults to the manifest's `main_pipe`; `--pipe <code>` overrideThe fetched clone is temporary: it lives in a system temp directory and is deleted when the CLI process exits. Default outputs therefore anchor in **your current working directory** — `pipelex run method <ref>` writes into `./results/`, and the `pipelex build` method commands write their generated files there too, so nothing you produced disappears with the clone. An explicit `--output-dir` / `--output` is honored verbatim. For an installed method or a local path, defaults stay inside the method's own directory, as before.+## Running by address on the hosted API++With `--hosted` (or `[run] execution = "hosted"`), `pipelex run method <ref>` fetches nothing: the address goes to the hosted Pipelex API as a method reference, and the hosted runner locates and fetches the package itself, under the same grammar and the same manifest-identity rule. The entry pipe is still the manifest's `main_pipe` unless `--pipe` names another, outputs still land in `./results/` under your working directory, and a relative `--inputs` path resolves against the working directory, since there is no local clone to anchor it to. `-L` is refused, because the hosted API loads no local library alongside an address. See [Running on the Hosted API](run.md#running-on-the-hosted-api).++```bash+pipelex run method github.com/Pipelex/methods/[email protected] --hosted --inputs '{"text": "Hello world."}'+```+## Python in fetched methods: the hosted ruleWhat decides whether Python in a method is acceptable is **where it would execute**:diff --git a/docs/tools/cli/run.md b/docs/tools/cli/run.mdindex fc7acee6a..60e7e8b4a 100644--- a/docs/tools/cli/run.md+++ b/docs/tools/cli/run.md@@ -40,6 +40,8 @@ Runs a pipe by code from your project's pipe library.- `--dry-run` - Dry-run the pipeline without calling AI providers; no inference credentials are needed- `--mock-inputs` - Use mock inputs for the pipeline (requires `--dry-run`)- `--library-dir`, `-L` - Directory to search for pipe definitions. Can be specified multiple times.+- `--hosted` / `--local` - Run on the hosted Pipelex API or on this machine. Defaults to `[run] execution` (see [Running on the Hosted API](#running-on-the-hosted-api)), else local+- `--base-url` - The origin a hosted run calls, `scheme://host[:port]`. Overrides `PIPELEX_BASE_URL`, which overrides `https://api.pipelex.com`**Examples:**@@ -64,6 +66,9 @@ pipelex run pipe my_pipe --dry-run# Run with custom library directoriespipelex run pipe my_pipe -L ./pipelines -L ./shared_pipes++# Run on the hosted Pipelex API, sending the library+pipelex run pipe my_pipe -L ./pipelines --hosted --inputs data.json```## Run Bundle@@ -93,6 +98,8 @@ Runs a pipeline from a bundle file (`.mthds`) or a pipeline directory. When a di- `--dry-run` - Dry-run the pipeline without calling AI providers; no inference credentials are needed- `--mock-inputs` - Use mock inputs for the pipeline (requires `--dry-run`)- `--library-dir`, `-L` - Directory to search for additional pipe definitions. Can be specified multiple times.+- `--hosted` / `--local` - Run on the hosted Pipelex API or on this machine. Defaults to `[run] execution` (see [Running on the Hosted API](#running-on-the-hosted-api)), else local+- `--base-url` - The origin a hosted run calls, `scheme://host[:port]`. Overrides `PIPELEX_BASE_URL`, which overrides `https://api.pipelex.com`**Examples:**@@ -111,6 +118,9 @@ pipelex run bundle my_bundle.mthds --inputs invoice_data.json# Run with execution graphpipelex run bundle my_bundle.mthds --graph++# Run on the hosted Pipelex API+pipelex run bundle my_bundle.mthds --hosted```## Run Method@@ -123,7 +133,7 @@ Runs a pipeline from an installed method package.**Arguments:**-- `NAME` - The name of the installed method to run, a method address (`github.com/owner/repo[/name][@tag]`), or a GitHub URL — see [Run a Method by Address](run-by-address.md)+- `NAME` - The name of the installed method to run, a method address (`github.com/owner/repo[/name][@tag]`), or a GitHub URL — see [Run a Method by Address](run-by-address.md). On a hosted run, also a stored method's catalog id (`mt_…`)**Options:**@@ -140,6 +150,8 @@ Runs a pipeline from an installed method package.- `--dry-run` - Dry-run the pipeline without calling AI providers; no inference credentials are needed- `--mock-inputs` - Use mock inputs for the pipeline (requires `--dry-run`)- `--library-dir`, `-L` - Directory to search for additional pipe definitions. Can be specified multiple times.+- `--hosted` / `--local` - Run on the hosted Pipelex API or on this machine. Defaults to `[run] execution` (see [Running on the Hosted API](#running-on-the-hosted-api)), else local+- `--base-url` - The origin a hosted run calls, `scheme://host[:port]`. Overrides `PIPELEX_BASE_URL`, which overrides `https://api.pipelex.com`**Examples:**@@ -155,8 +167,44 @@ pipelex run method invoice_extractor --inputs invoice_data.json# Run a method fetched by address from a public GitHub repository, pinned at a tagpipelex run method github.com/Pipelex/methods/[email protected] --pipe extract_document_text++# Run a published method on the hosted Pipelex API, which resolves the address itself+pipelex run method github.com/Pipelex/methods/[email protected] --hosted --inputs '{"text": "Hello world."}'++# Run a method stored on the hosted platform, by its catalog id+pipelex run method mt_abc123 --hosted --inputs data.json```+## Running on the Hosted API++A run executes on this machine by default, with the inference backends configured in `.pipelex/inference/` and your own provider keys. It can execute on the hosted Pipelex API instead, which needs only a Pipelex API key: no provider key and no inference configuration on this machine, since a hosted run boots nothing locally.++Where a run executes is decided in this order:++1. `--hosted` or `--local` on the command.+2. `[run] execution` in `.pipelex/pipelex.toml` (`"local"` or `"hosted"`; the project's file over the one in `~/.pipelex/`), see [Run Configuration](../../configuration/config-practical/run-config.md).+3. Local.++The key is read from `PIPELEX_API_KEY`, exported in your shell or saved in `~/.pipelex/.env` (or a `.env` in the working directory), which Pipelex loads at startup. The run goes to `--base-url` when given, else to `PIPELEX_BASE_URL`, else to `https://api.pipelex.com`. Either value must be an origin, `scheme://host[:port]` with `http` or `https` and no path such as `/v1`; anything else is refused before a request is sent, naming the setting it came from. A self-hosted Pipelex API server is reached the same way, by pointing the base URL at it.++**What a hosted run sends** is what a local run would load:++- `run bundle` sends the bundle, then every `.mthds` file of its library directories (the bundle's own directory for `run bundle <dir>`, then `-L`; for a bundle file with no `-L`, `PIPELEXPATH`), each once. Without `--pipe`, the bundle's `main_pipe` is read from the bundle here, as a local run reads it.+- `run pipe` sends every `.mthds` file of its library directories: the installed method exporting the pipe and `-L`, else `PIPELEXPATH`. With none of them, the run is refused and asks for `-L`.+- `run method` sends an installed or local method's files. A published address goes as a reference and a catalog id (`mt_…`) as an id, both resolved by the hosted API: nothing is fetched or read locally, `-L` is refused with them, and a relative `--inputs` path resolves against the working directory rather than the method's. A method installed under a name spelled like a catalog id, such as `mt_reports`, is that installed method, not an id.++**Local files in the inputs** are uploaded before the run. A path at a document or image input (compact, as `"invoice.pdf"`, or as the `url` of a document or image object, in a list or nested in a structure) is uploaded, and the run receives its storage URI instead. A relative path written in an inputs file resolves against that file's directory, as on a local run, and a `file://` URI is read as the path it names. A text that reads like a file name at any other input is left as text, `http(s)://` URLs, whatever the case of the scheme, are passed through for the hosted API to fetch, and an explicit `null`, such as an optional image left out, reaches the run as `null`.++The method's signature, which says where a file sits, is read from the hosted API only when some value of the inputs, at any depth, names an existing file on this machine (from the inputs file's directory or the working directory). Inputs naming none go straight to the run. When the signature is read, a method that does not load is refused there, before any run starts, with validation errors that name the file each fault is in. A method that calls another method by its address (`github.com/…`) cannot have its signature read yet, so a local file cannot be uploaded for it: the run is refused before it starts, and the file has to be given as an `https://` URL instead. The same method runs with inputs that name no local file.++**What it saves** goes where a local run saves its outputs, in `<output-dir>/<pipe>_output_NN/`: `main_stuff.json` (and `main_stuff.md` when the main output is text), `working_memory.json`, and `graphspec.json` when the hosted API returned the run's graph, which [`pipelex graph render`](../../features/execution-graph.md) turns into a viewer. The run id is printed as soon as the hosted API acknowledges the run, as `Run <id> started on the hosted API`, and again with the recap.++**When you interrupt it** with Ctrl-C, the command stops waiting, but a run the hosted API acknowledged keeps going and is paid for: the command prints its run id, so you can look it up on app.pipelex.com, and exits with `130`. Interrupted before the acknowledgement, it says that a run may have started if the request had reached the hosted API, and to check the run history before running again.++**What it refuses**: `--dry-run`, `--mock-inputs`, `--mock-usage`, `--orchestrator`, `--save-csv`, `--costs` / `--no-costs` and `--graph-full-data` / `--graph-no-data` steer this machine's runtime, which a hosted run never boots, so each is refused with a message pointing at `--local`. `--base-url` on a run that executes locally is refused too.++**When it fails**, the message gives the hosted API's reason and a next step: the one the server advised when it gave one, else one that follows the status (a refused key points at `PIPELEX_API_KEY`, an unknown method or route at the method's address and the base URL, a rate limit says to wait). A bundle the hosted API refuses lists its validation errors, and so does a run that started and failed on them. Once the hosted API has acknowledged the run, the failure also prints the run id: a run that failed, one that outlived the wait, one that completed without a main output, and one whose result could not be read, because the network or the hosted API failed while the run was being followed. That last one may still be running and is paid for, so look it up by its id on app.pipelex.com rather than running the command again. A connection lost after the request that runs the method was sent is not reported as a network failure either: the hosted API may have created the run before the connection failed, and its id never arrived, so check the run history before running again. Only a failure before the request left this machine, a connection that could not be made, points at the network and the base URL. A server that keeps no runs to poll, such as a self-hosted runner, is run on the blocking route, and when the connection is cut before its result comes back, the run may still be going there: running the command again runs the method again, so raise the timeout of the proxy in front of that server, or point the base URL at a server that keeps runs. The exit code is `1`.+## Input File FormatsAn inputs file is a dictionary whose keys are input variable names, and each value is interpreted **against the pipe's declared signature** — so you provide the values directly (a string, a number, an object) and Pipelex types them as the declared concept. See [Providing Inputs](../../building-methods/pipes/provide-inputs.md) for the full model, including the explicit `{concept, content}` escape hatch. Pipelex accepts **both JSON and TOML**, discriminated by the file extension:diff --git a/docs/tools/cli/update.md b/docs/tools/cli/update.mdindex 3ca664078..15b1a7b83 100644--- a/docs/tools/cli/update.md+++ b/docs/tools/cli/update.md@@ -15,7 +15,7 @@ When a new `pipelex` release ships changes to the model deck — new models, new## When to run it-Pipelex prints a one-line yellow advisory on most CLI invocations when it detects that the installed deck is older than the running package, or when no deck manifest is present yet (it is suppressed for `init`, `doctor`, `update`, `migrate`, and `which`):+Pipelex prints a one-line yellow advisory on most CLI invocations when it detects that the installed deck is older than the running package, or when no deck manifest is present yet. It is suppressed for `init`, `doctor`, `update`, `migrate`, and `which`, and `pipelex run` prints it only for a run that executes on this machine, since a run on the hosted API reads no local deck:```text⚠ Pipelex model deck may be out of date — run pipelex update to refreshdiff --git a/mkdocs.yml b/mkdocs.ymlindex a5babdf47..962e45149 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -263,6 +263,7 @@ plugins:- building-methods/libraries.md: "Libraries"- building-methods/packages.md: "Packages"- building-methods/pipes/executing-pipelines.md: "Executing Pipelines"+ - building-methods/pipes/running-on-the-hosted-api.md: "Running on the Hosted API from Python"- building-methods/pipes/run-modes-and-backends.md: "Run Modes & Backends"- building-methods/pipes/provide-inputs.md: "Providing Inputs to Pipelines"- building-methods/pipes/working-memory.md: "Working Memory"@@ -309,6 +310,7 @@ plugins:- configuration/config-practical/methods-config.md: "Methods Configuration"- configuration/config-practical/pipe-run-config.md: "Pipe Run Configuration"- configuration/config-practical/reporting-config.md: "Reporting Configuration"+ - configuration/config-practical/run-config.md: "Run Configuration"- configuration/config-practical/telemetry-config.md: "Telemetry Configuration"- configuration/config-technical/aws-config.md: "AWS Configuration"- configuration/config-technical/inference-config.md: "Inference Configuration"@@ -492,6 +494,7 @@ nav:- Libraries: building-methods/libraries.md- Packages: building-methods/packages.md- Executing Pipelines: building-methods/pipes/executing-pipelines.md+ - Running on the Hosted API: building-methods/pipes/running-on-the-hosted-api.md- Run Modes & Backends: building-methods/pipes/run-modes-and-backends.md- Providing Inputs to Pipelines: building-methods/pipes/provide-inputs.md- Working Memory: building-methods/pipes/working-memory.md@@ -565,6 +568,7 @@ nav:- Methods: configuration/config-practical/methods-config.md- Pipe Run: configuration/config-practical/pipe-run-config.md- Reporting: configuration/config-practical/reporting-config.md+ - Run: configuration/config-practical/run-config.md- Telemetry: configuration/config-practical/telemetry-config.md- Technical Configuration:- AWS: configuration/config-technical/aws-config.mddiff --git a/pipelex/cli/_cli.py b/pipelex/cli/_cli.pyindex b976c272f..1ef9cd89b 100644--- a/pipelex/cli/_cli.py+++ b/pipelex/cli/_cli.py@@ -157,8 +157,10 @@ def app_callback(# Check system readiness (dependencies and venv for dev installs)check_readiness()- # Warn if the model deck has fallen behind the installed pipelex version- warn_if_deck_stale()+ # Warn if the model deck has fallen behind the installed pipelex version. `run` warns from its local branch+ # instead, once it knows the run executes here: a hosted run reads no deck.+ if ctx.invoked_subcommand != "run":+ warn_if_deck_stale()@app.command(name="init", help="Initialize Pipelex configuration, backends, credentials, routing, and telemetry")diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.mdindex d46b8f1dc..2ceb8768f 100644--- a/pipelex/cli/agent_cli/CLAUDE.md+++ b/pipelex/cli/agent_cli/CLAUDE.md@@ -9,7 +9,7 @@ Two 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`.-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`, runner validation in the app callback, 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 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.`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.@@ -17,12 +17,12 @@ Only the error format is backed by a module-level `ContextVar` in `agent_output.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 the API-runner path (which does not assemble 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.+- `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.- `validate`: `# Validation passed`, the bundle path when relevant, and a list of validated pipes with their status. 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, 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 none; `validate bundle` / `validate method` with `--pipe` DO carry them, 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`.- `migrate`: `# Configuration migration`, the mode (applied / dry run) and verdict, the directories walked, a files-walked/changed/written count, then one `## <path>` section per file that is not clean listing the entries applied, the entries blocked with their reason and guidance, and any unexplained paths. Paths, operation kinds and ledger-supplied values only — no value read from the user's file is ever rendered, in either format.- `init`: `# Pipelex initialized` with target directory, enabled backends, and routing profile.-- error path: `# Error: <error_type>`, the message, the hint as a `> 💡` callout, the `validation_errors` items (when the cause's report, or an API runner's refusal, carries any) as the same grouped prose `validate` prints, and a `## Details` section. `error_source` (internal stack frames) is omitted from markdown — it remains in the JSON envelope (`--error-format json`) for programmatic consumers.+- 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.## Companion: Agent Skills@@ -47,7 +47,7 @@ commands/bundle_cmd.py # run bundle — execute from bundle file/directorymethod_cmd.py # run method — execute method (installed name, address/URL, or path)_run_core.py # Shared async run logic (local runner)- _run_core_api.py # Shared async run logic (API runner)+ _run_hosted.py # Hosted runs: --runner/--hosted/--base-url resolution, the run through pipelex.hosted, its envelopes_output_helpers.py # Output formatting helpersstdin_resolver.py # Stdin input resolutionvalidate/ # validate — verify pipes/bundles/methods@@ -105,6 +105,7 @@ commands/- **File convention**: Generated outputs go to `mthds-wip/` with incremental naming (`pipeline_01/`, `pipeline_02/`). Exception: `run method` on a fetched target (a method address or GitHub URL) anchors its run outputs in `results/` under the caller's CWD via `run_pipeline_core`'s `output_dir_override` — the fetched clone is an ephemeral temp dir deleted at process exit, so bundle-adjacent outputs would be lost.- **Validate refusals are verdicts**: the `validate` commands run their library load inside `translate_to_validate_bundle_error` (`pipelex/pipeline/validate_bundle_translation.py`), so every input-domained refusal raised while loading a bundle, the unknown model (`PipeOperatorModelChoiceError`, an `unknown_model` item) included, reaches the command as a `ValidateBundleError` and leaves with the invalid-verdict envelope and exit 1. No `validate` command keeps an arm of its own for a model-choice error; exit 2 stays for a failure of the tool or its environment (config, runtime, security).- **Run refusals are verdicts too**: a run loads its bundle inside the same translation (`acquire_library`), so an invalid bundle leaves `run pipe` / `run bundle` / `run method` as a `ValidateBundleError` with exit 1, through the generic `agent_error` arm, and `_assemble_error_payload` copies the report's `validation_errors` into the envelope for any cause that carries them. `run_pipeline_core` sets `library_dirs_are_callers=True`, so a refusal in a `-L` directory (or the bundle's own directory) is the same verdict; `run bundle`'s own parse of a bundle without `--pipe` goes through the translation too. So no `run` command keeps an arm of its own for a model-choice error either: an unknown model reaches it as the verdict's `unknown_model` item.-- **API runner refusals**: the `--runner api` branches of `run pipe` / `run bundle` / `run method` catch mthds-python's `ApiResponseError` (every `MthdsAPIClient` route raises it on a non-2xx answer; it subclasses `PipelineRequestError`, so its arm comes first) and hand it to `agent_error_api_response()`. `api_response_error_payload()` builds the envelope from the problem document alone: `error_type` is the runner's class (`ValidateBundleError` at load, as a local run reports it, or the root fault of a failed run, which a local run reports as `cause_type` under `PipelineExecutionError`; this path has no `cause_type`), `message` is the error's own `API POST /v1/execute failed (<status>): <reason>` without the next step it appends, `hint` is `user_action.detail`, and `error_domain` / `error_category` / `retryable` / `validation_errors` / `pipe_code` / `pipe_stack` / `request_id` are the runner's, plus `error_code` (the problem's `code`), `retry_after_seconds` (the `Retry-After` header) and `http_status`. It deliberately bypasses `agent_error()`'s lookups: the dict hints keyed on a class name local commands (`doctor`, `check-model`) that cannot fix a remote refusal, and the domain is only the runner's to say, so one with no `error_domain` carries none. A refusal with no `user_action` — the hosted plane's own answers in front of the runner: the gateway's 403 for a bad key, the rate limiter's 429, the unreachable runner's 503 — gets its status's hint from `API_REFUSAL_HINTS_BY_STATUS` (the 404's points at a `MTHDS_BASE_URL` ending in `/v1`), else `API_REFUSAL_CALLER_HINT` for any other 4xx and the static `ApiResponseError` hint for the rest. Only a 429 that did not say otherwise is inferred `retryable`: the platform can answer a 503 after the run completed, when it failed to record the result, so its hint warns that a retry can repeat a paid run. The markdown renderer keeps a runner item this pipelex's `ValidationErrorItem` cannot type (a newer `error_type`, an unknown field) as JSON under Details instead of failing.+- **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. 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`), `retry_after_seconds` (the `Retry-After` header) and `http_status`. It deliberately bypasses `agent_error()`'s lookups: the dict hints keyed on a class name local commands (`doctor`, `check-model`) that cannot fix a remote refusal, and the domain is only the runner's to say, so one with no `error_domain` carries none. A refusal with no `user_action` — the hosted plane's own answers in front of the runner: the gateway's 403 for a bad key, the rate limiter's 429, the unreachable runner's 503 — gets its status's 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`, 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, so `RETRYABLE_ERROR_TYPES` keyed on the runner's class never overrides it, 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.- **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 9241b520b..d3aa51f44 100644--- a/pipelex/cli/agent_cli/_agent_cli.py+++ b/pipelex/cli/agent_cli/_agent_cli.py@@ -4,12 +4,11 @@ from typing import Annotatedimport typerfrom click import Command, Context-from mthds.runners.types import RunnerTypefrom 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, agent_error, set_agent_cli_error_format+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_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@@ -80,7 +79,6 @@ def version_callback(value: bool) -> None: # kw-only: ignore — click invokes@app.callback(invoke_without_command=True)def app_callback(- ctx: typer.Context,version: Annotated[ # ruff: ignore[unused-function-argument]bool,typer.Option(@@ -91,10 +89,6 @@ def app_callback(is_eager=True,),] = False,- runner: Annotated[- str,- typer.Option("--runner", help="Runner to use: 'pipelex' (local) or 'api' (remote MTHDS API)."),- ] = "pipelex",) -> None:"""Agent CLI callback - no logo, minimal output.@@ -109,7 +103,7 @@ def app_callback(touches no log path. For verbose debugging, use the human ``pipelex`` CLI instead."""# Process-global logging cutoff, armed BEFORE any command body runs and BEFORE any- # error-format / runner-validation code below can route through ``log.*``. This is the+ # error-format code below can route through ``log.*``. This is the# primary armor for the stdout/stderr discipline; the per-call invocations inside# ``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.@@ -119,16 +113,6 @@ def app_callback(# --format / --error-format commands override this afterwards; JSON-only commands keep the JSON default.set_agent_cli_error_format(CliOutputFormat.JSON)- ctx.ensure_object(dict)- try:- ctx.obj["runner"] = RunnerType(runner)- except ValueError:- valid_values = ", ".join(runner_type.value for runner_type in RunnerType)- agent_error(- f"Invalid runner '{runner}'. Valid values: {valid_values}",- error_type="ArgumentError",- )-app.command(name="init", help="Initialize Pipelex configuration (non-interactive)")(agent_init_cmd)app.add_typer(run_app, name="run", help="Execute a pipeline and output JSON results")diff --git a/pipelex/cli/agent_cli/commands/agent_cli_factory.py b/pipelex/cli/agent_cli/commands/agent_cli_factory.pyindex 57b6a4d76..f96268c61 100644--- a/pipelex/cli/agent_cli/commands/agent_cli_factory.py+++ b/pipelex/cli/agent_cli/commands/agent_cli_factory.py@@ -127,6 +127,10 @@ 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.+AGENT_INIT_FAILURE_HINT = "Initialization failed. Run 'pipelex-agent doctor' to diagnose, or 'pipelex init config' to reset configuration"++def apply_agent_cli_output_discipline() -> None:"""Reaffirm the agent CLI output contract on the Rich/hub channels post-init.@@ -218,7 +222,7 @@ def make_pipelex_for_agent_cli(*, library_dirs: list[str] | list[Path] | None =f"Pipelex initialization failed: {exc}",error_type=type(exc).__name__,cause=exc,- hint="Initialization failed. Run 'pipelex-agent doctor' to diagnose, or 'pipelex init config' to reset configuration",+ hint=AGENT_INIT_FAILURE_HINT,)# 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 506eabec3..a3651bb10 100644--- a/pipelex/cli/agent_cli/commands/agent_output.py+++ b/pipelex/cli/agent_cli/commands/agent_output.py@@ -26,10 +26,11 @@ from pathlib import Pathfrom typing import Any, NoReturn, castimport typer-from mthds.runners.api.exceptions import ApiResponseError+from pipelex_sdk.errors import ApiResponseErrorfrom pydantic import ValidationErrorfrom pipelex.base_exceptions import PipelexError, ValidationErrorItem, iter_cause_chain+from pipelex.hosted.error_rendering import hosted_refusal_message, hosted_refusal_next_stepfrom pipelex.pipe_run.located_failure import find_root_faultfrom pipelex.pipeline.exceptions import PipelineExecutionError, ValidateBundleErrorfrom pipelex.pipeline.validation_render import build_fix_command, count_applicable_fixes, format_validation_error_items_markdown@@ -86,40 +87,9 @@ _UNKNOWN_MODEL_HINT = ("to validate or 'pipelex-agent models -t <type>' to list available models.")-_API_CREDENTIALS_HINT = (- "Set MTHDS_API_KEY and MTHDS_BASE_URL (the runner's origin), or run 'mthds config set api-key <key>' and 'mthds config set base-url <url>'"-)-_API_RATE_LIMITED_HINT = "Too many requests: wait retry_after_seconds when the error carries it, otherwise a few seconds, then run again"-# A 503 does not say whether the run happened: a hosted plane can answer it before forwarding the-# request and also after the run completed, when it failed to record the result. So it is never-# marked retryable, and its hint warns that running again can repeat a paid run.-_API_UNAVAILABLE_HINT = (- "The runner or the service in front of it was unavailable. It may have failed before the run or after it, "- "so running again can repeat a paid run: wait retry_after_seconds when the error carries it, then run again "- "only if a repeated run is acceptable"-)-# The next step of a 4xx refusal that advised none and whose status has no hint of its own.-API_REFUSAL_CALLER_HINT = (- "The runner refused the request: change what the message names (the method, the inputs or the configuration), then run again"-)--# The next step of a refusal whose answer advised none, by its HTTP status. These are the answers a-# hosted plane authors itself, in front of the runner, and they carry no `user_action`: the gateway's-# refusal of a key, an unknown route, the platform's rate limiter, a service it cannot reach.-API_REFUSAL_HINTS_BY_STATUS: dict[int, str] = {- 401: f"The runner refused the credentials. {_API_CREDENTIALS_HINT}",- 403: (- "The runner refused the request: check that MTHDS_API_KEY is a valid key for the runner at MTHDS_BASE_URL; "- "when it is, the message says what this request may not do"- ),- 404: "The runner has no such route: check that MTHDS_BASE_URL is the runner's origin, with no path such as /v1",- 429: _API_RATE_LIMITED_HINT,- 503: _API_UNAVAILABLE_HINT,-}-# Statuses that say the request was refused before anything ran, so the same request can succeed later# (RFC 6585): the envelope marks them retryable unless the answer said otherwise. A 503 is not one of-# them, see _API_UNAVAILABLE_HINT.+# 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] = {@@ -161,16 +131,6 @@ AGENT_ERROR_HINTS: dict[str, str] = {"Without a 'migration' field, correct the telemetry.toml settings named in the message."),"BinaryNotFoundError": "Install pipelex-tools: uv tool install pipelex-tools",- # API runner errors- "ClientAuthenticationError": _API_CREDENTIALS_HINT,- "PipelineRequestError": "Check that pipe_code or mthds_contents is provided",- # The next step of a runner's server-side failure that advised none, when its status has none of its- # own in API_REFUSAL_HINTS_BY_STATUS (a 4xx gets API_REFUSAL_CALLER_HINT instead). It stands in for- # the hint keyed on the runner's own class, which names a local command (doctor, check-model) that- # cannot fix what a remote runner refused.- "ApiResponseError": (- "The API runner failed on its side: report it with the request_id, or with the http_status when the error carries no request_id"- ),# Graph errors"GraphSpecParseError": "Validate graphspec.json structure; ensure it matches the expected GraphSpec schema",# Input/type errors@@ -211,14 +171,12 @@ AGENT_ERROR_DOMAINS: dict[str, str] = {"ValidationError": "input","ValueError": "input","BundleError": "input",- "PipelineRequestError": "input","GraphSpecParseError": "input","UnknownCommandError": "input","CodegenDriftError": "input","CodegenLockNotFoundError": "input","CodegenLockError": "input",# config = environment/config changes needed- "ClientAuthenticationError": "config","PipeOperatorModelAvailabilityError": "config","BinaryNotFoundError": "config","InitConfigError": "config",@@ -527,7 +485,7 @@ 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 API runner answered non-2xx, read off the problem document it sent.+ """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:@@ -536,14 +494,14 @@ def api_response_error_payload(*, error: ApiResponseError) -> dict[str, Any]:for a run that failed, which a local run reports as ``cause_type`` under ``PipelineExecutionError``. There isno ``cause_type`` or ``cause_message`` on this path. ``ApiResponseError`` when the answer names no class, as agateway's error page does not.- - ``message`` is ``API POST /v1/execute failed (422): <reason>``, the error's own message without the next step+ - ``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 a+ - ``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 the- hint of its status from ``API_REFUSAL_HINTS_BY_STATUS``, else a hint by status class (a 4xx asks for a change to- the request, anything else for a report); never the hint keyed on the runner's class, which names a local- command that cannot fix a remote refusal.+ next step of its status from ``pipelex.hosted.error_rendering``, the table the human CLI reads too, else one by+ status class (a 4xx asks for a change to the request, anything else for a report); never the hint keyed on the+ runner's class, which names a local command that cannot fix a remote refusal.- ``retryable`` (only when true, as on every envelope), ``error_domain`` and ``error_category`` are the answer's,with no local fallback, since only the runner knows whether the caller or its operator has to act. The oneexception is ``retryable`` on a 429 that did not say, a refusal sent before anything ran. A 503 is never@@ -556,21 +514,11 @@ def api_response_error_payload(*, error: ApiResponseError) -> dict[str, Any]:- ``error_source`` is the client-side trace, as on every JSON envelope."""problem: dict[str, Any] = error.problem or {}- message = str(error)- hint: str- if error.user_action is None:- hint = API_REFUSAL_HINTS_BY_STATUS.get(error.status) or (- API_REFUSAL_CALLER_HINT if 400 <= error.status < 500 else AGENT_ERROR_HINTS["ApiResponseError"]- )- else:- hint = error.user_action.detail- message = message.removesuffix(f"\nNext step: {hint}")-payload: dict[str, Any] = {"error": True,"error_type": error.error_type or type(error).__name__,- "message": message,- "hint": hint,+ "message": hosted_refusal_message(error=error),+ "hint": hosted_refusal_next_step(error=error),}if error.retryable or (error.retryable is None and error.status in _API_RETRYABLE_STATUSES):payload["retryable"] = True@@ -597,15 +545,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 API runner refused to stderr, format-aware, and exit 1.+ """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 an API runner's refusal arrives as. It builds its own+ The sibling of :func:`agent_error` for the one error a hosted refusal arrives as. It builds its ownpayload rather than going through :func:`agent_error`'s lookups, whose fallbacks keyed on ``error_type`` arelocal advice (see :func:`api_response_error_payload`), and renders it with the same JSON dump and the samemarkdown renderer, so a hosted refusal reads like a local failure.Args:- error: The refusal the ``MthdsAPIClient`` raised.+ error: The refusal pipelex-sdk's ``PipelexAPIClient`` raised."""payload = api_response_error_payload(error=error)match get_agent_cli_error_format():diff --git a/pipelex/cli/agent_cli/commands/run/_run_core_api.py b/pipelex/cli/agent_cli/commands/run/_run_core_api.pydeleted file mode 100644index ac949cc4c..000000000--- a/pipelex/cli/agent_cli/commands/run/_run_core_api.py+++ /dev/null@@ -1,88 +0,0 @@-"""Core logic for running a pipeline via the remote MTHDS API in the agent CLI."""--# pyright: reportUnknownMemberType=false-# pyright: reportUnknownVariableType=false-# pyright: reportUnknownArgumentType=false--from __future__ import annotations--from typing import Any, cast--from mthds.runners.api.client import MthdsAPIClient-from mthds.runners.api.models import MAIN_STUFF_NAME--from pipelex.cli.agent_cli.commands.run._output_helpers import build_run_output-from pipelex.pipeline.exceptions import PipeExecutionError---async def run_pipeline_core_api(- pipe_code: str,- *,- mthds_contents: list[str] | None = None,- inputs: dict[str, Any] | None = None,- with_memory: bool = False,-) -> dict[str, Any]:- """Core logic for running a pipeline via the MTHDS API and returning JSON-serializable output.-- Args:- pipe_code: The pipe code to run.- mthds_contents: List of MTHDS content strings (optional).- inputs: Input dictionary for the pipeline.- with_memory: Whether to include full working memory in output (True) or- return compact concept JSON only (False, default).-- Returns:- Dictionary with execution results suitable for JSON serialization.-- Raises:- ClientAuthenticationError: If the API key or the runner's base URL is missing.- ApiResponseError: If the runner answers non-2xx, a refused bundle or a failed run among them,- with the members of its problem document typed.- PipelineRequestError: If the pipeline request is malformed.- """- async with MthdsAPIClient() as runner:- response = await runner.execute(- pipe_code=pipe_code,- mthds_contents=mthds_contents,- inputs=inputs,- )-- pipe_output = response.pipe_output-- # `main_stuff_name` and `state` are pipelex extension fields on the protocol's- # extension-open RunResult — they ride model_extra, never named by the SDK.- extensions: dict[str, Any] = response.model_extra or {}-- # Extract the main stuff content from the working memory. A completed run always resolves its- # declared output: a value or a recorded absence — but the mthds SDK wire models do not carry- # the absences ledger yet (root + aliases only, extra=forbid), so the resolved-as-absent arm on- # this API path is gated on the cross-repo mthds protocol bump. Until then a response with no- # main stuff under the announced key is reported as a runner contract violation.- raw_main_stuff_name = extensions.get("main_stuff_name")- main_stuff_name = raw_main_stuff_name if isinstance(raw_main_stuff_name, str) else MAIN_STUFF_NAME- main_stuff = pipe_output.working_memory.root.get(main_stuff_name)- if main_stuff is None:- msg = (- f"Completed run '{response.pipeline_run_id}' response has no main stuff under key '{main_stuff_name}' — "- "a completed run always resolves its declared output."- )- raise PipeExecutionError(msg)-- main_stuff_json: dict[str, Any] = {- "json": main_stuff.content,- "markdown": "",- "html": "",- }- content: Any = main_stuff.content- compact_result: dict[str, Any] = cast("dict[str, Any]", content) if isinstance(content, dict) else {"result": content}-- return build_run_output(- with_memory=with_memory,- main_stuff_json=main_stuff_json,- working_memory_dump=pipe_output.working_memory.model_dump(),- compact_result=compact_result,- extra_metadata={- "pipeline_run_id": response.pipeline_run_id,- "pipeline_state": extensions.get("state"),- },- )diff --git a/pipelex/cli/agent_cli/commands/run/_run_hosted.py b/pipelex/cli/agent_cli/commands/run/_run_hosted.pynew file mode 100644index 000000000..8178b10ef--- /dev/null+++ b/pipelex/cli/agent_cli/commands/run/_run_hosted.py@@ -0,0 +1,171 @@+"""`pipelex-agent run … --runner hosted`: run on the hosted Pipelex API and answer in the run envelope.++The run commands share this module for every step that differs from a local run: where the run executes (the+flags, then `[run] execution`), the flags a hosted run refuses, the run itself through `pipelex.hosted`, and the+envelope its result or its failure is reported in. Nothing here boots the local runtime.+"""++from __future__ import annotations++import asyncio+import functools+from typing import TYPE_CHECKING, Any, NoReturn, cast++from mthds.protocol.exceptions import PipelineRequestError+from 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.cli.agent_cli.commands.agent_output import (+ CliOutputFormat,+ agent_error,+ agent_error_api_response,+ agent_success_formatted,+)+from pipelex.cli.agent_cli.commands.run._output_helpers import build_run_output, format_run_markdown+from pipelex.hosted.client_factory import make_hosted_client+from pipelex.hosted.error_rendering import describe_hosted_error+from pipelex.hosted.exceptions import HostedRunError, HostedRunInterruptedError+from pipelex.hosted.execution import resolve_run_execution+from pipelex.hosted.hosted_run import HostedRunOutcome, HostedRunRequest, RunStartedCallback, run_hosted+from pipelex.hosted.run_config import RunExecution++if TYPE_CHECKING:+ from pipelex_sdk.client import PipelexAPIClient++#: The `--runner` help, shared by the run commands.+RUNNER_OPTION_HELP = "Where the run executes: 'local' (this machine) or 'hosted' (the hosted Pipelex API). Default: [run] execution, else local."+#: The `--hosted/--local` help, shared by the run commands.+HOSTED_OPTION_HELP = "Run on the hosted Pipelex API (key in PIPELEX_API_KEY) or on this machine; the same choice as --runner."+#: The `--base-url` help, shared by the run commands.+BASE_URL_OPTION_HELP = (+ "Origin of the hosted API a hosted run calls, scheme://host[:port]. Overrides PIPELEX_BASE_URL; default https://api.pipelex.com."+)+#: The exit status of a command interrupted by Ctrl-C, the shell's 128 + SIGINT, which Typer gives one too.+_INTERRUPTED_EXIT_CODE = 130+++def resolve_agent_run_execution(*, runner: RunExecution | None, hosted: bool | None, base_url: str | None) -> RunExecution:+ """Where this `pipelex-agent run` executes: `--runner` or `--hosted`/`--local`, else `[run] execution`, else local.++ `--runner` and the flag pair name the same choice, so they must agree when both are given. `--base-url` names the+ hosted API a hosted run calls, so it is refused on a run that executes locally rather than ignored.+ """+ from_flag = RunExecution.from_hosted_flag(hosted=hosted)+ requested = runner or from_flag+ if 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")+ 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)+ if base_url is not None and not execution.is_hosted:+ agent_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",+ )+ return execution+++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(+ 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",+ )+++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`.++ A refusal the hosted API answered carries its problem document and goes through `agent_error_api_response`, whose+ envelope matches a local failure's. Every other failure is reported as `pipelex.hosted.error_rendering` reads it,+ the view the human CLI prints: its class, its reason, its next step and its domain, the run's `pipeline_run_id`+ once the hosted API acknowledged the run (a run that failed, outlived the wait, was lost on the way or was left+ running by an interruption), and the `validation_errors` of a method that does not load. A run that started and+ failed adds its stored report's status, category, model and provider. When the hosted API gave a `retryable`+ verdict, the envelope carries it, `false` included, so the local table keyed on the runner's class never overrides it.+ """+ if isinstance(error, ApiResponseError):+ agent_error_api_response(error=error)+ view = describe_hosted_error(error=error)+ extra: dict[str, Any] = {"hint": view.next_step}+ if view.error_domain is not None:+ extra["error_domain"] = str(view.error_domain)+ if view.retryable is not None:+ extra["retryable"] = view.retryable+ if view.pipeline_run_id is not None:+ extra["pipeline_run_id"] = view.pipeline_run_id+ if view.validation_errors:+ extra["validation_errors"] = [item.model_dump(mode="json", exclude_none=True) for item in view.validation_errors]+ if isinstance(error, RunFailedError):+ extra["run_status"] = str(error.status)+ report = error.error+ if report is not None:+ reported = {"error_category": report.error_category, "model": report.model, "provider": report.provider}+ extra.update({field_name: value for field_name, value in reported.items() if value})+ agent_error(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]:+ """The run envelope of a hosted run, in the shape a local run's has.++ Compact, it is the main output's content. With memory, `main_stuff.json` is that content (the hosted API renders+ no Markdown or HTML, so the Markdown output falls back to it), `working_memory` is the whole working memory, and+ `pipeline_run_id` names the run on the hosted API. Nothing is written to disk.+ """+ results = outcome.results+ content: Any = results.main_stuff+ compact_result: dict[str, Any] = cast("dict[str, Any]", content) if isinstance(content, dict) else {"result": content}+ working_memory_dump: dict[str, Any] = results.working_memory.model_dump(mode="json") if results.working_memory is not None else {}+ extra_metadata: dict[str, Any] = {"pipeline_run_id": results.pipeline_run_id}+ if outcome.uploads:+ extra_metadata["uploads"] = [upload.model_dump(mode="json") for upload in outcome.uploads]+ return build_run_output(+ with_memory=with_memory,+ main_stuff_json={"json": content, "markdown": "", "html": ""},+ working_memory_dump=working_memory_dump,+ compact_result=compact_result,+ extra_metadata=extra_metadata,+ )+++async def _start_and_wait(*, client: PipelexAPIClient, request: HostedRunRequest, on_started: RunStartedCallback) -> HostedRunOutcome:+ async with client:+ return await run_hosted(client=client, request=request, on_started=on_started)+++def run_hosted_for_agent(*, request: HostedRunRequest, base_url: str | None, with_memory: bool, output_format: CliOutputFormat) -> None:+ """Run on the hosted API and print the run envelope, or the error envelope and exit 1.++ Interrupted by Ctrl-C, the error envelope is a `HostedRunInterruptedError` naming the run the hosted API had+ acknowledged, which keeps going, and the exit status is 130.+ """+ try:+ client = make_hosted_client(base_url=base_url)+ except PipelexError as exc:+ agent_error(exc.message, error_type=type(exc).__name__, cause=exc)+ started_run_ids: list[str] = []++ def _record_start(*, pipeline_run_id: str) -> None:+ started_run_ids.append(pipeline_run_id)++ try:+ outcome = asyncio.run(_start_and_wait(client=client, request=request, on_started=_record_start))+ except (KeyboardInterrupt, asyncio.CancelledError):+ # Ctrl-C stops the wait, not the run: the envelope names the run that keeps going.+ interrupted = HostedRunInterruptedError(pipeline_run_id=started_run_ids[-1] if started_run_ids else None)+ agent_error_hosted(error=interrupted, exit_code=_INTERRUPTED_EXIT_CODE)+ except (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)+ 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 583624d5e..cf85194e2 100644--- a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/bundle_cmd.py@@ -8,23 +8,30 @@ from pathlib import Pathfrom typing import Annotated, Anyimport typer-from mthds.protocol.exceptions import PipelineRequestError-from mthds.runners.api.exceptions import ApiResponseError, ClientAuthenticationError-from mthds.runners.types import RunnerTypefrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_clifrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,agent_error,- agent_error_api_response,agent_success_formatted,run_failure_fields,set_agent_cli_error_format,)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-from pipelex.cli.agent_cli.commands.run._run_core_api import run_pipeline_core_api+from pipelex.cli.agent_cli.commands.run._run_hosted import (+ BASE_URL_OPTION_HELP,+ HOSTED_OPTION_HELP,+ RUNNER_OPTION_HELP,+ refuse_local_only_flags,+ resolve_agent_run_execution,+ run_hosted_for_agent,+)from pipelex.cli.agent_cli.commands.run.stdin_resolver import parse_cli_inputs+from pipelex.cli.commands.run._hosted_sources import collect_mthds_files, hosted_library_dirs+from pipelex.hosted.exceptions import HostedRunSourceError+from pipelex.hosted.hosted_run import HostedRunRequest+from 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 MTHDS_EXTENSION, is_pipelex_filefrom pipelex.mthds_parsing.parser import MthdsParserfrom pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError@@ -35,7 +42,6 @@ from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bdef run_bundle_cmd(- ctx: typer.Context,path: Annotated[str,typer.Argument(help="Path to a .mthds bundle file or a pipeline directory"),@@ -80,6 +86,18 @@ def run_bundle_cmd(CliOutputFormat | None,typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),] = None,+ runner: Annotated[+ RunExecution | None,+ typer.Option("--runner", help=RUNNER_OPTION_HELP),+ ] = None,+ hosted: Annotated[+ bool | None,+ typer.Option("--hosted/--local", help=HOSTED_OPTION_HELP),+ ] = None,+ base_url: Annotated[+ str | None,+ typer.Option("--base-url", help=BASE_URL_OPTION_HELP),+ ] = None,) -> None:"""Execute a pipeline from a bundle file (.mthds) or pipeline directory.@@ -92,6 +110,7 @@ def run_bundle_cmd(pipelex-agent run bundle my_bundle.mthds --pipe my_pipepipelex-agent run bundle pipeline_01/ --dry-run --mock-inputspipelex-agent run bundle pipeline_01/ --format json+ pipelex-agent run bundle pipeline_01/ --runner hosted"""set_agent_cli_error_format(error_format or output_format)@@ -170,83 +189,62 @@ def run_bundle_cmd(parsed_inputs = parse_cli_inputs(inputs_arg=inputs, stdin_fallback=True, auto_inputs_dir=auto_inputs_dir)pipeline_inputs: dict[str, Any] | None = parsed_inputs.pipeline_inputs- runner_type: RunnerType = ctx.obj["runner"]-- match runner_type:- case RunnerType.API:- # Validate unsupported flags for API runner- if dry_run:- agent_error("--dry-run is not supported with --runner api", error_type="ArgumentError")- if mock_inputs:- agent_error("--mock-inputs is not supported with --runner api", error_type="ArgumentError")-- try:- result = asyncio.run(- run_pipeline_core_api(- pipe_code=pipe_code, # type: ignore[arg-type]- mthds_contents=[mthds_content] if mthds_content else None,- inputs=pipeline_inputs,- with_memory=with_memory,- )- )- agent_success_formatted(- result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format- )-- except ClientAuthenticationError as exc:- agent_error(str(exc), error_type="ClientAuthenticationError", cause=exc)-- except ApiResponseError as exc:- # The runner answered non-2xx: its problem document says why, where, and what to do next.- agent_error_api_response(error=exc)-- except PipelineRequestError as exc:- agent_error(str(exc), error_type="PipelineRequestError", cause=exc)-- 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)-- case RunnerType.PIPELEX:- make_pipelex_for_agent_cli(needs_inference=not dry_run)-- try:- result = asyncio.run(- run_pipeline_core(- pipe_code=pipe_code, # type: ignore[arg-type]- mthds_contents=[mthds_content] if mthds_content else None,- bundle_uris=[bundle_path] if bundle_path else None,- inputs=pipeline_inputs,- dry_run=dry_run,- mock_inputs=mock_inputs,- library_dirs=library_dir,- graph=graph,- costs=costs,- with_memory=with_memory,- inputs_base_dir=parsed_inputs.inputs_base_dir,- )- )- agent_success_formatted(- result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format- )+ execution = resolve_agent_run_execution(runner=runner, hosted=hosted, base_url=base_url)+ if execution.is_hosted:+ refuse_local_only_flags(dry_run=dry_run, mock_inputs=mock_inputs)+ # The bundle goes first, then the rest of the library a local run would load with it: -L, else PIPELEXPATH.+ try:+ bundle_files = collect_mthds_files(primary=Path(bundle_path), library_dirs=hosted_library_dirs(library_dirs=library_dir))+ except HostedRunSourceError as exc:+ agent_error(exc.message, error_type=type(exc).__name__, cause=exc)+ request = HostedRunRequest(+ mthds_files=bundle_files,+ pipe_code=pipe_code,+ inputs=pipeline_inputs,+ inputs_base_dir=parsed_inputs.inputs_base_dir,+ )+ run_hosted_for_agent(request=request, base_url=base_url, with_memory=with_memory, output_format=output_format)+ return++ make_pipelex_for_agent_cli(needs_inference=not dry_run)++ try:+ result = asyncio.run(+ run_pipeline_core(+ pipe_code=pipe_code, # type: ignore[arg-type]+ mthds_contents=[mthds_content] if mthds_content else None,+ bundle_uris=[bundle_path] if bundle_path else None,+ inputs=pipeline_inputs,+ dry_run=dry_run,+ mock_inputs=mock_inputs,+ library_dirs=library_dir,+ graph=graph,+ costs=costs,+ with_memory=with_memory,+ inputs_base_dir=parsed_inputs.inputs_base_dir,+ )+ )+ agent_success_formatted(+ result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format+ )- except PipelineExecutionError as exc:- agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **run_failure_fields(error=exc))-- except PipeOperatorModelAvailabilityError as exc:- availability_extra: dict[str, Any] = {- "pipe_code": exc.pipe_code,- "model_handle": exc.model_handle,- }- if exc.fallback_list:- availability_extra["fallback_list"] = exc.fallback_list- if exc.pipe_stack:- availability_extra["pipe_stack"] = exc.pipe_stack- agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", 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)-- finally:- Pipelex.teardown_if_needed()+ except PipelineExecutionError as exc:+ agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **run_failure_fields(error=exc))++ except PipeOperatorModelAvailabilityError as exc:+ availability_extra: dict[str, Any] = {+ "pipe_code": exc.pipe_code,+ "model_handle": exc.model_handle,+ }+ if exc.fallback_list:+ availability_extra["fallback_list"] = exc.fallback_list+ if exc.pipe_stack:+ availability_extra["pipe_stack"] = exc.pipe_stack+ agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", 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)++ 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 ab844621c..7c5f73a28 100644--- a/pipelex/cli/agent_cli/commands/run/method_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/method_cmd.py@@ -8,25 +8,32 @@ from pathlib import Pathfrom typing import Annotated, Anyimport typer-from mthds.protocol.exceptions import PipelineRequestError-from mthds.runners.api.exceptions import ApiResponseError, ClientAuthenticationError-from mthds.runners.types import RunnerTypefrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_clifrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,agent_error,- agent_error_api_response,agent_success_formatted,run_failure_fields,set_agent_cli_error_format,)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-from pipelex.cli.agent_cli.commands.run._run_core_api import run_pipeline_core_api+from pipelex.cli.agent_cli.commands.run._run_hosted import (+ BASE_URL_OPTION_HELP,+ HOSTED_OPTION_HELP,+ RUNNER_OPTION_HELP,+ refuse_local_only_flags,+ resolve_agent_run_execution,+ run_hosted_for_agent,+)from pipelex.cli.agent_cli.commands.run.stdin_resolver import parse_cli_inputs+from pipelex.cli.commands.run._hosted_sources import resolve_hosted_method_targetfrom pipelex.cli.commands.run._inputs_file_loader import resolve_inputs_arg_against_dirfrom pipelex.cli.method_resolver import method_output_base_dir, resolve_method_target+from pipelex.hosted.exceptions import HostedRunSourceError+from pipelex.hosted.hosted_run import HostedRunRequest+from pipelex.hosted.run_config import RunExecution # ruff: ignore[typing-only-first-party-import] - typer reads the --runner annotation at runtimefrom pipelex.methods.exceptions import MethodRefErrorfrom pipelex.mthds_parsing.helpers import MTHDS_EXTENSIONfrom pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityError@@ -35,7 +42,6 @@ from pipelex.pipeline.exceptions import PipelineExecutionErrordef run_method_cmd(- ctx: typer.Context,name: Annotated[str,typer.Argument(help="Installed method name, method address (github.com/owner/repo\\[/name]\\[@tag]), or GitHub URL"),@@ -80,6 +86,18 @@ def run_method_cmd(CliOutputFormat | None,typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),] = None,+ runner: Annotated[+ RunExecution | None,+ typer.Option("--runner", help=RUNNER_OPTION_HELP),+ ] = None,+ hosted: Annotated[+ bool | None,+ typer.Option("--hosted/--local", help=HOSTED_OPTION_HELP),+ ] = None,+ base_url: Annotated[+ str | None,+ typer.Option("--base-url", help=BASE_URL_OPTION_HELP),+ ] = None,) -> None:"""Execute a pipeline for an installed method and output the results.@@ -87,10 +105,15 @@ def run_method_cmd((or --pipe override), and runs the pipeline. Default output is markdown;use --format json for structured JSON.+ With --runner hosted (or [run] execution = "hosted"), the run executes on the hosted+ Pipelex API: an address or a catalog id (mt_...) is resolved there, an installed or+ local method's files are sent, and local files named in the inputs are uploaded.+Examples:pipelex-agent run method my-methodpipelex-agent run method my-method --pipe custom_pipepipelex-agent run method my-method --dry-run --mock-inputs+ pipelex-agent run method github.com/Pipelex/methods/[email protected] --runner hosted --inputs '{"text": "Hello"}'"""set_agent_cli_error_format(error_format or output_format)@@ -98,6 +121,30 @@ def run_method_cmd(if mock_inputs and not dry_run:agent_error("--mock-inputs requires --dry-run", error_type="ArgumentError")+ execution = resolve_agent_run_execution(runner=runner, hosted=hosted, base_url=base_url)+ if execution.is_hosted:+ refuse_local_only_flags(dry_run=dry_run, mock_inputs=mock_inputs)+ # A published address and a stored method are resolved by the hosted API, so nothing is fetched here; an+ # installed or local method is resolved as on a local run, and its files are sent.+ 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)+ hosted_inputs = parse_cli_inputs(+ inputs_arg=resolve_inputs_arg_against_dir(inputs, base_dir=target.inputs_anchor_dir),+ stdin_fallback=True,+ )+ request = HostedRunRequest(+ mthds_files=target.mthds_files,+ method_ref=target.method_ref,+ method_id=target.method_id,+ pipe_code=target.pipe_code,+ inputs=hosted_inputs.pipeline_inputs,+ inputs_base_dir=hosted_inputs.inputs_base_dir,+ )+ run_hosted_for_agent(request=request, base_url=base_url, with_memory=with_memory, output_format=output_format)+ return+try:pipe_code, method_library_dirs, method = resolve_method_target(method_name=name,@@ -141,84 +188,46 @@ def run_method_cmd(parsed_inputs = parse_cli_inputs(inputs_arg=effective_inputs, stdin_fallback=True)pipeline_inputs: dict[str, Any] | None = parsed_inputs.pipeline_inputs- runner_type: RunnerType = ctx.obj["runner"]-- match runner_type:- case RunnerType.API:- # Validate unsupported flags for API runner- if dry_run:- agent_error("--dry-run is not supported with --runner api", error_type="ArgumentError")- if mock_inputs:- agent_error("--mock-inputs is not supported with --runner api", error_type="ArgumentError")-- try:- result = asyncio.run(- run_pipeline_core_api(- pipe_code=pipe_code,- mthds_contents=[mthds_content] if mthds_content else None,- inputs=pipeline_inputs,- with_memory=with_memory,- )- )- agent_success_formatted(- result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format- )-- except ClientAuthenticationError as exc:- agent_error(str(exc), error_type="ClientAuthenticationError", cause=exc)-- except ApiResponseError as exc:- # The runner answered non-2xx: its problem document says why, where, and what to do next.- agent_error_api_response(error=exc)-- except PipelineRequestError as exc:- agent_error(str(exc), error_type="PipelineRequestError", cause=exc)-- 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)-- case RunnerType.PIPELEX:- make_pipelex_for_agent_cli(needs_inference=not dry_run)-- try:- result = asyncio.run(- run_pipeline_core(- pipe_code=pipe_code,- mthds_contents=[mthds_content] if mthds_content else None,- bundle_uris=[bundle_path] if bundle_path else None,- inputs=pipeline_inputs,- dry_run=dry_run,- mock_inputs=mock_inputs,- library_dirs=all_library_dirs,- graph=graph,- costs=costs,- with_memory=with_memory,- inputs_base_dir=parsed_inputs.inputs_base_dir,- output_dir_override=output_dir_override,- )- )- agent_success_formatted(- result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format- )-- except PipelineExecutionError as exc:- agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **run_failure_fields(error=exc))-- except PipeOperatorModelAvailabilityError as exc:- availability_extra: dict[str, Any] = {- "pipe_code": exc.pipe_code,- "model_handle": exc.model_handle,- }- if exc.fallback_list:- availability_extra["fallback_list"] = exc.fallback_list- if exc.pipe_stack:- availability_extra["pipe_stack"] = exc.pipe_stack- agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", 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)-- finally:- Pipelex.teardown_if_needed()+ make_pipelex_for_agent_cli(needs_inference=not dry_run)++ try:+ result = asyncio.run(+ run_pipeline_core(+ pipe_code=pipe_code,+ mthds_contents=[mthds_content] if mthds_content else None,+ bundle_uris=[bundle_path] if bundle_path else None,+ inputs=pipeline_inputs,+ dry_run=dry_run,+ mock_inputs=mock_inputs,+ library_dirs=all_library_dirs,+ graph=graph,+ costs=costs,+ with_memory=with_memory,+ inputs_base_dir=parsed_inputs.inputs_base_dir,+ output_dir_override=output_dir_override,+ )+ )+ agent_success_formatted(+ result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format+ )++ except PipelineExecutionError as exc:+ agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **run_failure_fields(error=exc))++ except PipeOperatorModelAvailabilityError as exc:+ availability_extra: dict[str, Any] = {+ "pipe_code": exc.pipe_code,+ "model_handle": exc.model_handle,+ }+ if exc.fallback_list:+ availability_extra["fallback_list"] = exc.fallback_list+ if exc.pipe_stack:+ availability_extra["pipe_stack"] = exc.pipe_stack+ agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", 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)++ 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 54e097138..08b676ee0 100644--- a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/pipe_cmd.py@@ -8,24 +8,31 @@ from pathlib import Pathfrom typing import Annotated, Anyimport typer-from mthds.protocol.exceptions import PipelineRequestError-from mthds.runners.api.exceptions import ApiResponseError, ClientAuthenticationError-from mthds.runners.types import RunnerTypefrom pipelex.cli.agent_cli.commands.agent_cli_factory import make_pipelex_for_agent_clifrom pipelex.cli.agent_cli.commands.agent_output import (CliOutputFormat,agent_error,- agent_error_api_response,agent_success_formatted,run_failure_fields,set_agent_cli_error_format,)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-from pipelex.cli.agent_cli.commands.run._run_core_api import run_pipeline_core_api+from pipelex.cli.agent_cli.commands.run._run_hosted import (+ BASE_URL_OPTION_HELP,+ HOSTED_OPTION_HELP,+ RUNNER_OPTION_HELP,+ refuse_local_only_flags,+ resolve_agent_run_execution,+ run_hosted_for_agent,+)from pipelex.cli.agent_cli.commands.run.stdin_resolver import parse_cli_inputs+from pipelex.cli.commands.run._hosted_sources import hosted_pipe_library_filesfrom pipelex.cli.method_resolver import resolve_pipe_from_exports+from pipelex.hosted.exceptions import HostedRunSourceError+from pipelex.hosted.hosted_run import HostedRunRequest+from 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 MTHDS_EXTENSION, is_pipelex_filefrom pipelex.pipe_operators.exceptions import PipeOperatorModelAvailabilityErrorfrom pipelex.pipelex import Pipelex@@ -33,7 +40,6 @@ from pipelex.pipeline.exceptions import PipelineExecutionErrordef run_pipe_cmd(- ctx: typer.Context,pipe_code: Annotated[str,typer.Argument(help="Pipe code to run"),@@ -74,6 +80,18 @@ def run_pipe_cmd(CliOutputFormat | None,typer.Option("--error-format", help="Error output format (defaults to --format value): markdown or json"),] = None,+ runner: Annotated[+ RunExecution | None,+ typer.Option("--runner", help=RUNNER_OPTION_HELP),+ ] = None,+ hosted: Annotated[+ bool | None,+ typer.Option("--hosted/--local", help=HOSTED_OPTION_HELP),+ ] = None,+ base_url: Annotated[+ str | None,+ typer.Option("--base-url", help=BASE_URL_OPTION_HELP),+ ] = None,) -> None:"""Execute a pipeline by pipe code and output the results.@@ -86,6 +104,7 @@ def run_pipe_cmd(pipelex-agent run pipe my_pipe --inputs data.jsonpipelex-agent run pipe my_pipe --dry-run --mock-inputspipelex-agent run pipe my_pipe --format json+ pipelex-agent run pipe my_pipe -L my_library/ --runner hosted --inputs data.json"""set_agent_cli_error_format(error_format or output_format)@@ -121,80 +140,60 @@ def run_pipe_cmd(parsed_inputs = parse_cli_inputs(inputs_arg=inputs, stdin_fallback=True)pipeline_inputs: dict[str, Any] | None = parsed_inputs.pipeline_inputs- runner_type: RunnerType = ctx.obj["runner"]-- match runner_type:- case RunnerType.API:- # Validate unsupported flags for API runner- if dry_run:- agent_error("--dry-run is not supported with --runner api", error_type="ArgumentError")- if mock_inputs:- agent_error("--mock-inputs is not supported with --runner api", error_type="ArgumentError")-- try:- result = asyncio.run(- run_pipeline_core_api(- pipe_code=pipe_code,- inputs=pipeline_inputs,- with_memory=with_memory,- )- )- agent_success_formatted(- result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format- )-- except ClientAuthenticationError as exc:- agent_error(str(exc), error_type="ClientAuthenticationError", cause=exc)-- except ApiResponseError as exc:- # The runner answered non-2xx: its problem document says why, where, and what to do next.- agent_error_api_response(error=exc)-- except PipelineRequestError as exc:- agent_error(str(exc), error_type="PipelineRequestError", cause=exc)-- 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)-- case RunnerType.PIPELEX:- make_pipelex_for_agent_cli(needs_inference=not dry_run)-- try:- result = asyncio.run(- run_pipeline_core(- pipe_code=pipe_code,- inputs=pipeline_inputs,- dry_run=dry_run,- mock_inputs=mock_inputs,- library_dirs=library_dir,- graph=graph,- costs=costs,- with_memory=with_memory,- inputs_base_dir=parsed_inputs.inputs_base_dir,- )- )- agent_success_formatted(- result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format- )-- except PipelineExecutionError as exc:- agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **run_failure_fields(error=exc))-- except PipeOperatorModelAvailabilityError as exc:- availability_extra: dict[str, Any] = {- "pipe_code": exc.pipe_code,- "model_handle": exc.model_handle,- }- if exc.fallback_list:- availability_extra["fallback_list"] = exc.fallback_list- if exc.pipe_stack:- availability_extra["pipe_stack"] = exc.pipe_stack- agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", 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)-- finally:- Pipelex.teardown_if_needed()+ execution = resolve_agent_run_execution(runner=runner, hosted=hosted, base_url=base_url)+ if execution.is_hosted:+ refuse_local_only_flags(dry_run=dry_run, mock_inputs=mock_inputs)+ # The hosted API holds no library of yours: the one a local run would load is sent along.+ 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)+ request = HostedRunRequest(+ mthds_files=library_files,+ pipe_code=pipe_code,+ inputs=pipeline_inputs,+ inputs_base_dir=parsed_inputs.inputs_base_dir,+ )+ run_hosted_for_agent(request=request, base_url=base_url, with_memory=with_memory, output_format=output_format)+ return++ make_pipelex_for_agent_cli(needs_inference=not dry_run)++ try:+ result = asyncio.run(+ run_pipeline_core(+ pipe_code=pipe_code,+ inputs=pipeline_inputs,+ dry_run=dry_run,+ mock_inputs=mock_inputs,+ library_dirs=library_dir,+ graph=graph,+ costs=costs,+ with_memory=with_memory,+ inputs_base_dir=parsed_inputs.inputs_base_dir,+ )+ )+ agent_success_formatted(+ result, markdown_renderer=functools.partial(format_run_markdown, with_memory=with_memory), output_format=output_format+ )++ except PipelineExecutionError as exc:+ agent_error(exc.message, error_type="PipelineExecutionError", cause=exc, **run_failure_fields(error=exc))++ except PipeOperatorModelAvailabilityError as exc:+ availability_extra: dict[str, Any] = {+ "pipe_code": exc.pipe_code,+ "model_handle": exc.model_handle,+ }+ if exc.fallback_list:+ availability_extra["fallback_list"] = exc.fallback_list+ if exc.pipe_stack:+ availability_extra["pipe_stack"] = exc.pipe_stack+ agent_error(exc.message, error_type="PipeOperatorModelAvailabilityError", 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)++ finally:+ Pipelex.teardown_if_needed()diff --git a/pipelex/cli/commands/run/_hosted_sources.py b/pipelex/cli/commands/run/_hosted_sources.pynew file mode 100644index 000000000..e7ce03fcf--- /dev/null+++ b/pipelex/cli/commands/run/_hosted_sources.py@@ -0,0 +1,203 @@+"""The method a hosted run names, read from the same places a local run loads it from.++Both CLIs resolve a hosted run's source here, so `pipelex run --hosted` and `pipelex-agent run --runner hosted`+send the same thing for the same arguments:++- `run bundle` sends the bundle file, then every `.mthds` file in the library directories a local run would load+ (the bundle's own directory when the target is one, then `-L`; with neither, `PIPELEXPATH`), each file once.+- `run pipe` sends every `.mthds` file in its library directories: the installed method exporting the pipe and+ `-L`, else `PIPELEXPATH`. With none of them there is nothing to send, and the run is refused.+- `run method` names a published address as `method_ref` and a stored method's catalog id (`mt_…`) as `method_id`,+ both resolved by the hosted API, so nothing is fetched or read here. An installed method's name or a local+ method directory is resolved as a local run resolves it, and its files are sent; an installed method wins over a+ catalog id spelled the same, since `mt_reports` is a valid method name too.+"""++from __future__ import annotations++import re+from pathlib import Path+from typing import TYPE_CHECKING++from pipelex_sdk.crate_models import MthdsFileItem+from pydantic import BaseModel, ConfigDict++from pipelex.cli.installed_methods import DuplicateMethodNameError, MethodNotFoundError, find_method_by_name+from pipelex.cli.method_resolver import method_output_base_dir, resolve_method_target+from pipelex.hosted.exceptions import HostedRunSourceError+from pipelex.hosted.execution import get_or_load_pipelex_config+from pipelex.methods.method_ref import looks_like_method_ref, parse_method_ref+from pipelex.mthds_parsing.helpers import MTHDS_EXTENSION, is_pipelex_file+from pipelex.system.environment import PIPELEXPATH_ENV_KEY, get_pipelexpath_dirs+from pipelex.tools.misc.file_utils import find_files_in_dir++if TYPE_CHECKING:+ from collections.abc import Sequence++#: A stored method's catalog id on the hosted platform, as `pipelex-server` mints it.+METHOD_ID_PATTERN = re.compile(r"^mt_[A-Za-z0-9_-]{1,64}$")+++def looks_like_method_id(target: str) -> bool:+ """Whether a `run method` target is spelled as a stored method's catalog id (`mt_…`).++ The spelling alone does not decide it: a method may be installed under such a name, and then that method is the+ target. `resolve_hosted_method_target` checks.+ """+ return METHOD_ID_PATTERN.fullmatch(target) is not None+++def _names_an_installed_method(*, name: str, library_dirs: list[str] | None) -> bool:+ """Whether an installed method, or one in the library directories, bears this name; several count, and are refused later."""+ try:+ find_method_by_name(name, library_dirs=library_dirs)+ except MethodNotFoundError:+ return False+ except DuplicateMethodNameError:+ return True+ return True+++def hosted_library_dirs(*, library_dirs: Sequence[str] | None) -> Sequence[str | Path] | None:+ """The library directories a local run would load: `-L` when given, which replaces `PIPELEXPATH`, else `PIPELEXPATH`.++ `None` when neither names any.+ """+ if library_dirs is not None:+ return library_dirs+ return get_pipelexpath_dirs()+++def collect_mthds_files(*, primary: Path | None, library_dirs: Sequence[str | Path] | None) -> list[MthdsFileItem]:+ """Read the `.mthds` files a local run would load: `primary` first, then each library directory's, each file once.++ A library directory is scanned recursively, skipping the configured `[interpreter.scan] excluded_dirs`, as a+ local load scans it; a library entry naming a `.mthds` file is taken as it is; a missing one is skipped, as a+ local load skips it. Each file carries its path as its label: the hosted API names it in the validation errors+ of the method's signature, read before the run, while the run route takes the bare contents.++ Raises:+ HostedRunSourceError: If a file cannot be read.+ """+ excluded_dirs = list(get_or_load_pipelex_config().interpreter.scan.excluded_dirs)+ ordered: list[Path] = []+ if primary is not None:+ ordered.append(primary)+ for library_dir in library_dirs or []:+ library_path = Path(library_dir)+ if library_path.is_file() and is_pipelex_file(library_path):+ ordered.append(library_path)+ elif library_path.is_dir():+ found = find_files_in_dir(dir_path=library_path, pattern=f"*{MTHDS_EXTENSION}", excluded_dirs=excluded_dirs)+ ordered.extend(path for path in found if is_pipelex_file(path))++ seen: set[Path] = set()+ files: list[MthdsFileItem] = []+ for path in ordered:+ resolved = path.resolve()+ if resolved in seen:+ continue+ seen.add(resolved)+ try:+ content = path.read_text(encoding="utf-8")+ except (OSError, UnicodeDecodeError) as exc:+ msg = f"Could not read the method file '{path}' to send it to the hosted API: {exc}"+ raise HostedRunSourceError(msg) from exc+ files.append(MthdsFileItem(content=content, source=str(path)))+ return files+++def hosted_pipe_library_files(*, library_dirs: Sequence[str] | None) -> list[MthdsFileItem]:+ """The library a hosted `run pipe` sends: its library directories', else `PIPELEXPATH`'s.++ Raises:+ HostedRunSourceError: If no directory names a library, or the ones named hold no `.mthds` file.+ """+ effective_dirs = hosted_library_dirs(library_dirs=library_dirs or None)+ if not effective_dirs:+ msg = (+ f"A hosted pipe run sends the library that defines the pipe, and none is named: pass -L <dir> (repeatable), "+ f"set {PIPELEXPATH_ENV_KEY}, or run the bundle with 'run bundle <path>'."+ )+ raise HostedRunSourceError(msg)+ files = collect_mthds_files(primary=None, library_dirs=effective_dirs)+ if not files:+ named = ", ".join(str(one_dir) for one_dir in effective_dirs)+ msg = f"No .mthds file found to send to the hosted API in {named}."+ raise HostedRunSourceError(msg)+ return files+++class HostedMethodTarget(BaseModel):+ """What a hosted `run method` sends, and where its outputs and inputs are anchored.++ Exactly one of `mthds_files`, `method_ref` and `method_id` is set, as `HostedRunRequest` takes them.+ """++ model_config = ConfigDict(frozen=True)++ mthds_files: list[MthdsFileItem] | None = None+ method_ref: str | None = None+ method_id: str | None = None+ #: The pipe to run: `--pipe`, or a local method's `main_pipe`; `None` lets the hosted API run the entry pipe.+ pipe_code: str | None = None+ #: A short name for the run's outputs: the pipe, else the method.+ label: str+ #: The directory default outputs go under: a local method's own, else the working directory.+ output_base_dir: Path+ #: The directory a relative `--inputs` file path resolves against: a local method's own, else the working one.+ inputs_anchor_dir: Path+++def resolve_hosted_method_target(*, name: str, pipe_override: str | None, library_dirs: list[str] | None) -> HostedMethodTarget:+ """Resolve a hosted `run method` target.++ Args:+ name: A catalog id (`mt_…`), a method address or GitHub URL, an installed method's name, or a local method+ directory. A name spelled as a catalog id that an installed method bears is that method.+ pipe_override: `--pipe`.+ library_dirs: `-L`, sent along with a local method's files. A method the hosted API resolves loads no local+ library, so `-L` is refused with one.++ Raises:+ HostedRunSourceError: If `-L` is given with a method the hosted API resolves, or a local file cannot be read.+ MethodRefParseError: If an address does not parse.+ typer.Exit: If an installed method's name does not resolve, as on a local run.+ """+ cwd = Path.cwd()+ remote_ref: str | None = None+ remote_id: str | None = None+ if looks_like_method_id(name) and not _names_an_installed_method(name=name, library_dirs=library_dirs):+ remote_id = name+ elif looks_like_method_ref(name):+ remote_ref = parse_method_ref(name).ref_str+ if remote_ref is not None or remote_id is not None:+ if library_dirs:+ msg = (+ f"-L does not apply to '{name}': the hosted API resolves this method and loads no local library. "+ "Install it and run it by name, or run its bundle with 'run bundle <path> -L <dir>'."+ )+ raise HostedRunSourceError(msg)+ label = pipe_override or (parse_method_ref(remote_ref).address.rsplit("/", 1)[-1] if remote_ref else name)+ return HostedMethodTarget(+ method_ref=remote_ref,+ method_id=remote_id,+ pipe_code=pipe_override,+ label=label,+ output_base_dir=cwd,+ inputs_anchor_dir=cwd,+ )++ pipe_code, method_library_dirs, method = resolve_method_target(method_name=name, pipe_override=pipe_override, library_dirs=library_dirs)+ all_library_dirs = [*method_library_dirs, *(library_dirs or [])]+ mthds_files = collect_mthds_files(primary=None, library_dirs=all_library_dirs)+ if not mthds_files:+ msg = f"Method '{name}' at '{method.path}' holds no .mthds file to send to the hosted API."+ raise HostedRunSourceError(msg)+ return HostedMethodTarget(+ mthds_files=mthds_files,+ pipe_code=pipe_code,+ label=pipe_code,+ output_base_dir=method_output_base_dir(method=method),+ inputs_anchor_dir=Path(method_library_dirs[0]),+ )diff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.pyindex 3d09a8142..a41aafa3e 100644--- a/pipelex/cli/commands/run/_run_core.py+++ b/pipelex/cli/commands/run/_run_core.py@@ -3,7 +3,7 @@ from __future__ import annotationsimport asyncioimport jsonfrom pathlib import Path-from typing import TYPE_CHECKING, cast+from typing import TYPE_CHECKING, Any, NamedTuple, castimport typerfrom posthog import tag@@ -15,6 +15,7 @@ from pipelex.cli.cli_factory import make_pipelex_for_clifrom pipelex.cli.commands.run._inputs_file_loader import load_inputs_dict_from_pathfrom pipelex.cli.commands.run._inputs_path_resolver import resolve_inputs_pathsfrom pipelex.cli.commands.run._main_stuff_file import save_main_stuff_file+from pipelex.cli.deck_notice import warn_if_deck_stalefrom pipelex.cli.error_handlers import (ErrorContext,handle_dedicated_failure_panel,@@ -82,6 +83,65 @@ def validate_run_flag_combination(*, dry_run: bool, mock_usage: bool, mock_inputraise typer.Exit(1)+class LoadedRunInputs(NamedTuple):+ """A run's inputs as `--inputs` gave them, and the directory their relative file paths resolve against."""++ pipeline_inputs: dict[str, Any] | None+ #: The inputs file's directory, `None` for inline JSON, which has no file to anchor to.+ inputs_base_dir: Path | None+++def load_run_inputs(*, inputs: str | None) -> LoadedRunInputs:+ """Load `--inputs`: inline JSON (a `{` prefix) or a JSON or TOML file, its relative `url` paths resolved against its directory.++ Shared by local and hosted runs, so both read the same inputs the same way.++ Raises:+ typer.Exit: If the inputs cannot be read or parsed, after printing why.+ """+ pipeline_inputs: dict[str, Any] | None = None+ # Directory bare relative file paths resolve against (Smart Inputs D3). Set only when inputs are+ # file-loaded (its parent); None for inline JSON — an inline caller has no file to anchor to.+ inputs_base_dir: Path | None = None+ if inputs:+ if inputs.startswith("{"):+ try:+ pipeline_inputs = json.loads(inputs)+ except json.JSONDecodeError as json_decode_exc:+ print_traceback_if_requested(console=get_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+ else:+ try:+ # 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).+ inputs_path = Path(inputs).expanduser()+ pipeline_inputs = load_inputs_dict_from_path(inputs_path)+ # Resolve relative url paths against the inputs file's parent directory. The same+ # directory is threaded to the runner as inputs_base_dir so the shaper can resolve+ # bare relative file-ish / CSV strings (whose declared concept the CLI cannot see).+ inputs_base_dir = inputs_path.parent.resolve()+ pipeline_inputs = resolve_inputs_paths(pipeline_inputs, base_dir=inputs_base_dir)+ typer.echo(f"Loaded inputs from: {inputs}")+ except FileNotFoundError as file_not_found_exc:+ print_traceback_if_requested(console=get_console())+ typer.secho(f"Failed to load input file '{inputs}': file not found", fg=typer.colors.RED, err=True)+ raise typer.Exit(1) from file_not_found_exc+ except json.JSONDecodeError as json_decode_exc:+ print_traceback_if_requested(console=get_console())+ typer.secho(f"Failed to parse input file '{inputs}': invalid JSON: {json_decode_exc}", fg=typer.colors.RED, err=True)+ raise typer.Exit(1) from json_decode_exc+ except JsonTypeError as json_type_error_exc:+ print_traceback_if_requested(console=get_console())+ typer.secho(f"Failed to parse input file '{inputs}': must be a valid JSON dictionary", fg=typer.colors.RED, err=True)+ raise typer.Exit(1) from json_type_error_exc+ except TomlError as toml_error_exc:+ print_traceback_if_requested(console=get_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_exc+ return LoadedRunInputs(pipeline_inputs=pipeline_inputs, inputs_base_dir=inputs_base_dir)++def _resolve_row_model_for_empty_result(*,concept: Concept,@@ -181,47 +241,7 @@ async def _execute_run(typer.secho("Failed to run: no pipe code specified", fg=typer.colors.RED, err=True)raise typer.Exit(1)- # Load inputs if provided- pipeline_inputs = None- # Directory bare relative file paths resolve against (Smart Inputs D3). Set only when inputs are- # file-loaded (its parent); None for inline JSON — an inline caller has no file to anchor to.- inputs_base_dir: Path | None = None- if inputs:- if inputs.startswith("{"):- try:- pipeline_inputs = json.loads(inputs)- except json.JSONDecodeError as json_decode_exc:- print_traceback_if_requested(console=get_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- else:- try:- # 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).- inputs_path = Path(inputs).expanduser()- pipeline_inputs = load_inputs_dict_from_path(inputs_path)- # Resolve relative url paths against the inputs file's parent directory. The same- # directory is threaded to the runner as inputs_base_dir so the shaper can resolve- # bare relative file-ish / CSV strings (whose declared concept the CLI cannot see).- inputs_base_dir = inputs_path.parent.resolve()- pipeline_inputs = resolve_inputs_paths(pipeline_inputs, base_dir=inputs_base_dir)- typer.echo(f"Loaded inputs from: {inputs}")- except FileNotFoundError as file_not_found_exc:- print_traceback_if_requested(console=get_console())- typer.secho(f"Failed to load input file '{inputs}': file not found", fg=typer.colors.RED, err=True)- raise typer.Exit(1) from file_not_found_exc- except json.JSONDecodeError as json_decode_exc:- print_traceback_if_requested(console=get_console())- typer.secho(f"Failed to parse input file '{inputs}': invalid JSON: {json_decode_exc}", fg=typer.colors.RED, err=True)- raise typer.Exit(1) from json_decode_exc- except JsonTypeError as json_type_error_exc:- print_traceback_if_requested(console=get_console())- typer.secho(f"Failed to parse input file '{inputs}': must be a valid JSON dictionary", fg=typer.colors.RED, err=True)- raise typer.Exit(1) from json_type_error_exc- except TomlError as toml_error_exc:- print_traceback_if_requested(console=get_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_exc+ pipeline_inputs, inputs_base_dir = load_run_inputs(inputs=inputs)# Determine pipe run modepipe_run_mode = PipeRunMode.DRY if dry_run else None@@ -492,8 +512,10 @@ def execute_run() -> None:"""Synchronous entry point that wraps the async execution with Pipelex setup/teardown.- Shared between the ``method`` and ``pipe`` subcommands.+ Shared between the ``method``, ``pipe`` and ``bundle`` subcommands, for a run that executes on this machine. It+ prints the deck staleness notice, which the root callback leaves to it: only a local run reads the deck."""+ warn_if_deck_stale()# A dry run makes no inference call, so it must not demand credentials: `needs_inference=False`# forces every run to DRY and resolves no backend's credentials, yet keeps every enabled backend# with its models, so a dry run resolves model handles exactly as a live run would, whichever keysdiff --git a/pipelex/cli/commands/run/_run_hosted.py b/pipelex/cli/commands/run/_run_hosted.pynew file mode 100644index 000000000..dd5801877--- /dev/null+++ b/pipelex/cli/commands/run/_run_hosted.py@@ -0,0 +1,300 @@+"""`pipelex run … --hosted`: run a method on the hosted Pipelex API, without booting the local runtime.++A hosted run needs no provider key and no inference configuration on this machine: it reads the `[run]` setting and+the scan settings from the configuration files, sends the method and its inputs through pipelex-sdk, and writes what+the hosted API returns where a local run writes its own outputs.+"""++from __future__ import annotations++import asyncio+import json+from pathlib import Path+from typing import TYPE_CHECKING, Any, cast++import typer+from mthds.protocol.exceptions import PipelineRequestError+from pipelex_sdk.errors import ApiResponseError+from rich.markup import escape++from pipelex.base_exceptions import PipelexError+from pipelex.cli.commands.run._run_core import load_run_inputs+from pipelex.cli.error_handlers import handle_validate_bundle_error, print_traceback_if_requested+from pipelex.hosted.client_factory import make_hosted_client+from pipelex.hosted.error_rendering import describe_hosted_error+from pipelex.hosted.exceptions import HostedRunError, HostedRunInterruptedError+from pipelex.hosted.execution import resolve_run_execution+from pipelex.hosted.hosted_run import HostedRunOutcome, HostedRunRequest, RunStartedCallback, run_hosted+from pipelex.hosted.run_config import RunExecution+from pipelex.mthds_parsing.parser import MthdsParser+from pipelex.pipeline.exceptions import ValidateBundleError+from pipelex.pipeline.validate_bundle_translation import translate_to_validate_bundle_error+from pipelex.runtime_hub import get_console+from pipelex.tools.misc.file_utils import get_incremental_directory_path+from pipelex.tools.misc.json_utils import save_as_json_to_path+from pipelex.tools.misc.pretty import pretty_print, pretty_print_md++if TYPE_CHECKING:+ from pipelex_sdk.client import PipelexAPIClient+ from pipelex_sdk.crate_models import MthdsFileItem++_NATIVE_TEXT_CONCEPT_REF = "native.Text"+_MAIN_STUFF_NAME = "main_stuff"+_WORKING_MEMORY_FILENAME = "working_memory.json"+_GRAPHSPEC_FILENAME = "graphspec.json"+_FAILURE_HEADING = "Failed to run on the hosted API"+#: The exit status of a command interrupted by Ctrl-C, the shell's 128 + SIGINT, which Typer gives one too.+_INTERRUPTED_EXIT_CODE = 130+++def _fail(*, message: str) -> typer.Exit:+ """Print a refusal and hand back the exit to raise."""+ typer.secho(f"Failed to run: {message}", fg=typer.colors.RED, err=True)+ return typer.Exit(1)+++def resolve_cli_run_execution(*, hosted: bool | None, base_url: str | None) -> RunExecution:+ """Where this `pipelex run` executes: `--hosted`/`--local`, else `[run] execution`, else local.++ `--base-url` names the hosted API to call, so it is refused on a run that executes locally rather than ignored.++ Raises:+ typer.Exit: If the configuration cannot be read, or `--base-url` is given to a local run.+ """+ try:+ execution = resolve_run_execution(requested=RunExecution.from_hosted_flag(hosted=hosted))+ except PipelexError as exc:+ print_traceback_if_requested(console=get_console())+ raise _fail(message=exc.message) from exc+ if 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."+ raise _fail(message=msg)+ return execution+++def refuse_local_only_flags(+ *,+ dry_run: bool,+ mock_usage: bool,+ mock_inputs: bool,+ orchestrator: str | None,+ save_csv: str | None,+ costs: bool | None,+ graph_full_data: bool | None,+) -> None:+ """Refuse the flags that steer this machine's runtime, which a hosted run never boots.++ Raises:+ typer.Exit: If any of them is given, naming each and `--local`.+ """+ named: list[str] = []+ if dry_run:+ named.append("--dry-run")+ if mock_usage:+ named.append("--mock-usage")+ if mock_inputs:+ named.append("--mock-inputs")+ if orchestrator is not None:+ named.append("--orchestrator")+ if save_csv is not None:+ named.append("--save-csv")+ if costs is not None:+ named.append("--costs/--no-costs")+ if graph_full_data is not None:+ named.append("--graph-full-data/--graph-no-data")+ if named:+ msg = f"{', '.join(named)} only apply to a run on this machine, and this run executes on the hosted API. Pass --local to run it here."+ raise _fail(message=msg)+++def _print_hosted_failure(*, error: PipelineRequestError | HostedRunError, heading: str = _FAILURE_HEADING) -> None:+ """Print a hosted run's failure as `pipelex.hosted.error_rendering` reads it, the view the agent CLI's envelope carries.++ Its validation items name the file each fault is in when the hosted API was told it, and the run id is printed+ once the hosted API acknowledged the run, so a run that failed, outlived the wait, was lost on the way or was left+ running by an interruption can be looked up.+ """+ view = describe_hosted_error(error=error)+ console = get_console()+ console.print(f"\n[bold red]{escape(heading)}[/bold red]\n")+ console.print(f" {escape(view.message)}\n")+ if view.validation_errors:+ for item in view.validation_errors:+ location = item.source or item.pipe_code or item.concept_code or item.domain_code+ prefix = f"{location}: " if location else ""+ console.print(f" - {escape(prefix + item.message)}")+ console.print("")+ console.print(f" [bold]Next step:[/bold] {escape(view.next_step)}\n")+ if view.pipeline_run_id is not None:+ console.print(f" Run id: {escape(view.pipeline_run_id)}\n")+ if isinstance(error, ApiResponseError) and error.request_id:+ console.print(f" Request id: {escape(error.request_id)}\n")+++async def _start_and_wait(*, client: PipelexAPIClient, request: HostedRunRequest, on_started: RunStartedCallback) -> HostedRunOutcome:+ async with client:+ return await run_hosted(client=client, request=request, on_started=on_started)+++def _main_stuff_concept_ref(*, outcome: HostedRunOutcome) -> str | None:+ """The concept of the main output, read from the working memory, where a step that named its output keeps it+ under that name and points the `main_stuff` alias at it.+ """+ working_memory = outcome.results.working_memory+ if working_memory is None:+ return None+ main_stuff_name = working_memory.aliases.get(_MAIN_STUFF_NAME, _MAIN_STUFF_NAME)+ main_stuff = working_memory.root.get(main_stuff_name)+ return main_stuff.concept if main_stuff is not None else None+++def _main_text(*, outcome: HostedRunOutcome) -> str | None:+ """The main output's text when it is native Text, which reads best rendered as Markdown."""+ main_stuff = outcome.results.main_stuff+ if _main_stuff_concept_ref(outcome=outcome) != _NATIVE_TEXT_CONCEPT_REF or not isinstance(main_stuff, dict):+ return None+ text = cast("dict[str, Any]", main_stuff).get("text")+ return text if isinstance(text, str) else None+++def bundle_main_pipe_code(*, bundle_path: str, library_dirs: list[str] | None) -> str:+ """The `main_pipe` a bundle declares, read by parsing it here, as a local run reads it when `--pipe` is not given.++ Raises:+ typer.Exit: If the bundle cannot be read, does not parse, or declares no `main_pipe`.+ """+ try:+ mthds_content = Path(bundle_path).read_text(encoding="utf-8")+ with translate_to_validate_bundle_error():+ bundle_blueprint = MthdsParser.make_pipelex_bundle_blueprint(mthds_content=mthds_content, mthds_source=bundle_path)+ except (OSError, UnicodeDecodeError) as exc:+ raise _fail(message=f"could not read the bundle '{bundle_path}': {exc}") from exc+ except ValidateBundleError as exc:+ library_dir_paths = [Path(one_dir) for one_dir in library_dirs] if library_dirs else None+ handle_validate_bundle_error(exc, bundle_path=Path(bundle_path), library_dirs=library_dir_paths)+ if not bundle_blueprint.main_pipe:+ msg = f"the bundle '{bundle_path}' declares no main_pipe. Name the pipe to run with --pipe, or declare a main_pipe in the bundle."+ raise _fail(message=msg)+ return bundle_blueprint.main_pipe+++def execute_hosted_run(+ *,+ mthds_files: list[MthdsFileItem] | None = None,+ method_ref: str | None = None,+ method_id: str | None = None,+ pipe_code: str | None,+ inputs: str | None,+ dynamic_output_concept_ref: str | None,+ base_url: str | None,+ output_label: str,+ output_dir: str,+ save_working_memory: bool,+ working_memory_path: str | None,+ save_main_stuff: bool,+ no_pretty_print: bool,+ graph: bool | None,+) -> None:+ """Run on the hosted API, print the main output, and save the outputs as a local run saves them.++ The method is named by exactly one of `mthds_files`, `method_ref` and `method_id`. `inputs` is `--inputs` as the+ command resolved it: inline JSON or a JSON or TOML file, read as a local run reads it, and a local file it names+ at a document or image input is uploaded first.++ The outputs go to `<output_dir>/<output_label>_output_NN/`: `main_stuff.json` (and `main_stuff.md` for a text+ output), `working_memory.json`, and `graphspec.json` when the hosted API returned the run's graph, which+ `pipelex graph render` turns into a viewer.++ The run's id is printed as soon as the hosted API acknowledges the start. Interrupted by Ctrl-C, the command names+ the run, which keeps going on the hosted API, and exits 130.++ Raises:+ typer.Exit: If the base URL is not an origin, the inputs cannot be read, or the hosted run fails or is+ interrupted, after printing why and what next.+ """+ try:+ client = make_hosted_client(base_url=base_url)+ except PipelexError as exc:+ raise _fail(message=exc.message) from exc++ loaded_inputs = load_run_inputs(inputs=inputs)+ request = HostedRunRequest(+ mthds_files=mthds_files,+ method_ref=method_ref,+ method_id=method_id,+ pipe_code=pipe_code,+ inputs=loaded_inputs.pipeline_inputs,+ inputs_base_dir=loaded_inputs.inputs_base_dir,+ dynamic_output_concept_ref=dynamic_output_concept_ref,+ )++ console = get_console()+ console.print(f"Running on the hosted Pipelex API at [bold]{escape(client.base_url)}[/bold]")+ started_run_ids: list[str] = []++ def _announce_start(*, pipeline_run_id: str) -> None:+ started_run_ids.append(pipeline_run_id)+ console.print(f"Run {escape(pipeline_run_id)} started on the hosted API")++ try:+ outcome = asyncio.run(_start_and_wait(client=client, request=request, on_started=_announce_start))+ except (KeyboardInterrupt, asyncio.CancelledError) as exc:+ # Ctrl-C stops the wait, not the run: name the run that keeps going, then exit as an interrupted command does.+ interrupted = HostedRunInterruptedError(pipeline_run_id=started_run_ids[-1] if started_run_ids else None)+ _print_hosted_failure(error=interrupted, heading="Interrupted")+ raise typer.Exit(_INTERRUPTED_EXIT_CODE) from exc+ except (PipelineRequestError, HostedRunError) as exc:+ print_traceback_if_requested(console=console)+ _print_hosted_failure(error=exc)+ raise typer.Exit(1) from exc+ except Exception as exc:+ # CLI command root: any unexpected failure is reported to the user and exits non-zero via typer.Exit.+ print_traceback_if_requested(console=console)+ console.print(f"\n[bold red]{_FAILURE_HEADING}[/bold red]\n")+ console.print(f" {escape(f'{type(exc).__name__}: {exc}')}\n")+ raise typer.Exit(1) from exc++ results = outcome.results+ main_text = _main_text(outcome=outcome)+ if not no_pretty_print:+ title = f"Final output of {output_label}"+ if main_text is not None:+ pretty_print_md(main_text, title=title)+ else:+ pretty_print(json.dumps(results.main_stuff, indent=2, ensure_ascii=False), title=title)++ output_path: Path | None = None+ saved: list[str] = []+ if save_main_stuff or save_working_memory or (graph is not False and results.graph_spec is not None):+ output_path = get_incremental_directory_path(base_path=Path(output_dir), base_name=f"{output_label}_output")+ output_path.mkdir(parents=True, exist_ok=True)++ if output_path is not None and save_main_stuff:+ save_as_json_to_path(object_to_save=results.main_stuff, path=output_path / "main_stuff.json")+ saved.append("main_stuff.json")+ if main_text is not None:+ (output_path / "main_stuff.md").write_text(main_text, encoding="utf-8")+ saved.append("main_stuff.md")++ working_memory_output_path: Path | None = None+ if output_path is not None and save_working_memory and results.working_memory is not None:+ working_memory_output_path = Path(working_memory_path) if working_memory_path else output_path / _WORKING_MEMORY_FILENAME+ save_as_json_to_path(object_to_save=results.working_memory.model_dump(mode="json"), path=working_memory_output_path)+ saved.append(_WORKING_MEMORY_FILENAME if working_memory_output_path.parent == output_path else str(working_memory_output_path))++ graphspec_path: Path | None = None+ if output_path is not None and graph is not False and results.graph_spec is not None:+ graphspec_path = output_path / _GRAPHSPEC_FILENAME+ save_as_json_to_path(object_to_save=results.graph_spec, path=graphspec_path)+ saved.append(_GRAPHSPEC_FILENAME)++ console.print("\n[green]✓[/green] [bold]Hosted run completed successfully[/bold]")+ console.print(f" Run id: {escape(results.pipeline_run_id)}")+ if outcome.uploads:+ console.print(f" Uploaded {len(outcome.uploads)} local file(s) for the run")+ if output_path is not None and saved:+ console.print(f" Output saved to [bold magenta]{escape(str(output_path))}[/bold magenta]:")+ for saved_name in saved:+ console.print(f" [green]✓[/green] {escape(saved_name)}")+ if graphspec_path is not None:+ console.print(f" View the run's graph with: pipelex graph render {escape(str(graphspec_path))}")diff --git a/pipelex/cli/commands/run/bundle_cmd.py b/pipelex/cli/commands/run/bundle_cmd.pyindex 13d68d533..18659c502 100644--- a/pipelex/cli/commands/run/bundle_cmd.py+++ b/pipelex/cli/commands/run/bundle_cmd.py@@ -5,9 +5,12 @@ from typing import Annotatedimport typer+from pipelex.cli.commands.run._hosted_sources import collect_mthds_files, hosted_library_dirsfrom pipelex.cli.commands.run._inputs_file_loader import find_default_inputs_filefrom pipelex.cli.commands.run._run_core import COMMAND, execute_run, validate_run_flag_combination+from pipelex.cli.commands.run._run_hosted import bundle_main_pipe_code, execute_hosted_run, refuse_local_only_flags, resolve_cli_run_executionfrom pipelex.cli.commands.run.exceptions import AmbiguousInputsFilesError+from pipelex.hosted.exceptions import HostedRunSourceErrorfrom pipelex.mthds_parsing.helpers import MTHDS_EXTENSION, is_pipelex_filefrom pipelex.pipeline.default_file_names import DEFAULT_BUNDLE_FILE_NAME@@ -105,6 +108,20 @@ def run_bundle_cmd(help="Write the main stuff to this literal CSV path (not under --output-dir; absolute/~/relative ok). Requires a flat list output.",),] = None,+ hosted: Annotated[+ bool | None,+ typer.Option(+ "--hosted/--local",+ help="Run on the hosted Pipelex API (key in PIPELEX_API_KEY) or on this machine. Default: [run] execution, else local.",+ ),+ ] = None,+ base_url: Annotated[+ str | None,+ typer.Option(+ "--base-url",+ help="Origin of the hosted API a hosted run calls, scheme://host[:port]. Overrides PIPELEX_BASE_URL; default https://api.pipelex.com.",+ ),+ ] = None,) -> None:"""Run a pipeline from a bundle file (.mthds) or pipeline directory.@@ -114,6 +131,7 @@ def run_bundle_cmd(pipelex run bundle my_bundle.mthdspipelex run bundle my_bundle.mthds --pipe my_pipe --inputs data.jsonpipelex run bundle pipeline_01/ --dry-run+ pipelex run bundle pipeline_01/ --hosted"""validate_run_flag_combination(dry_run=dry_run, mock_usage=mock_usage, mock_inputs=mock_inputs)@@ -179,6 +197,40 @@ def run_bundle_cmd()raise typer.Exit(1)+ execution = resolve_cli_run_execution(hosted=hosted, base_url=base_url)+ if execution.is_hosted:+ refuse_local_only_flags(+ dry_run=dry_run,+ mock_usage=mock_usage,+ mock_inputs=mock_inputs,+ orchestrator=orchestrator,+ save_csv=save_csv,+ costs=costs,+ graph_full_data=graph_full_data,+ )+ hosted_pipe_code = pipe_code or bundle_main_pipe_code(bundle_path=bundle_path, library_dirs=library_dir)+ # The bundle goes first, then the rest of the library a local run would load with it: -L, else PIPELEXPATH.+ try:+ bundle_files = collect_mthds_files(primary=Path(bundle_path), library_dirs=hosted_library_dirs(library_dirs=library_dir))+ except HostedRunSourceError as exc:+ typer.secho(f"Failed to run: {exc.message}", fg=typer.colors.RED, err=True)+ raise typer.Exit(1) from exc+ execute_hosted_run(+ mthds_files=bundle_files,+ pipe_code=hosted_pipe_code,+ inputs=inputs,+ dynamic_output_concept_ref=dynamic_output_concept_ref,+ base_url=base_url,+ output_label=hosted_pipe_code,+ output_dir=output_dir,+ save_working_memory=save_working_memory,+ working_memory_path=working_memory_path,+ save_main_stuff=save_main_stuff,+ no_pretty_print=no_pretty_print,+ graph=graph,+ )+ return+execute_run(pipe_code=pipe_code,bundle_path=bundle_path,diff --git a/pipelex/cli/commands/run/method_cmd.py b/pipelex/cli/commands/run/method_cmd.pyindex 9f5c7b6ad..a3858adc9 100644--- a/pipelex/cli/commands/run/method_cmd.py+++ b/pipelex/cli/commands/run/method_cmd.py@@ -5,9 +5,13 @@ from typing import Annotatedimport typer+from pipelex.cli.commands.run._hosted_sources import resolve_hosted_method_targetfrom pipelex.cli.commands.run._inputs_file_loader import resolve_inputs_arg_against_dirfrom pipelex.cli.commands.run._run_core import COMMAND, execute_run, validate_run_flag_combination+from pipelex.cli.commands.run._run_hosted import execute_hosted_run, refuse_local_only_flags, resolve_cli_run_executionfrom pipelex.cli.method_resolver import method_output_base_dir, resolve_method_target+from pipelex.hosted.exceptions import HostedRunSourceError+from pipelex.methods.exceptions import MethodRefErrordef run_method_cmd(@@ -103,22 +107,78 @@ def run_method_cmd(help="Write the main stuff to this literal CSV path (not under --output-dir; absolute/~/relative ok). Requires a flat list output.",),] = None,+ hosted: Annotated[+ bool | None,+ typer.Option(+ "--hosted/--local",+ help="Run on the hosted Pipelex API (key in PIPELEX_API_KEY) or on this machine. Default: [run] execution, else local.",+ ),+ ] = None,+ base_url: Annotated[+ str | None,+ typer.Option(+ "--base-url",+ help="Origin of the hosted API a hosted run calls, scheme://host[:port]. Overrides PIPELEX_BASE_URL; default https://api.pipelex.com.",+ ),+ ] = None,) -> None:- """Run a method by name, address, or URL.+ """Run a method by name, address, URL, or (hosted only) catalog id.Resolves the method from ~/.mthds/methods/ or .mthds/methods/ (or fetches itby address / GitHub URL, optionally pinned at a git tag), determines the pipeto execute (using --pipe or the method's main_pipe), and runs it.+ With --hosted (or [run] execution = "hosted"), the run executes on the hosted+ Pipelex API: an address or a catalog id (mt_...) is resolved there, an installed+ or local method's files are sent, and local files named in the inputs are uploaded.+Examples:pipelex run method my-methodpipelex run method my-method --pipe custom_pipepipelex run method my-method --inputs data.jsonpipelex run method my-method --dry-runpipelex run method github.com/Pipelex/methods/[email protected] --pipe extract_document_text+ pipelex run method github.com/Pipelex/methods/[email protected] --hosted --inputs '{"text": "Hello"}'+ pipelex run method mt_abc123 --hosted --inputs data.json"""validate_run_flag_combination(dry_run=dry_run, mock_usage=mock_usage, mock_inputs=mock_inputs)+ execution = resolve_cli_run_execution(hosted=hosted, base_url=base_url)+ if execution.is_hosted:+ refuse_local_only_flags(+ dry_run=dry_run,+ mock_usage=mock_usage,+ mock_inputs=mock_inputs,+ orchestrator=orchestrator,+ save_csv=save_csv,+ costs=costs,+ graph_full_data=graph_full_data,+ )+ # A published address and a stored method are resolved by the hosted API, so nothing is fetched here; an+ # installed or local method is resolved as below, and its files are sent.+ try:+ target = resolve_hosted_method_target(name=name, pipe_override=pipe, library_dirs=library_dir)+ except (HostedRunSourceError, MethodRefError) as exc:+ typer.secho(f"Failed to run: {exc.message}", fg=typer.colors.RED, err=True)+ raise typer.Exit(1) from exc+ execute_hosted_run(+ mthds_files=target.mthds_files,+ method_ref=target.method_ref,+ method_id=target.method_id,+ pipe_code=target.pipe_code,+ inputs=resolve_inputs_arg_against_dir(inputs, base_dir=target.inputs_anchor_dir),+ dynamic_output_concept_ref=dynamic_output_concept_ref,+ base_url=base_url,+ output_label=target.label,+ output_dir=output_dir or str(target.output_base_dir / "results"),+ save_working_memory=save_working_memory,+ working_memory_path=working_memory_path,+ save_main_stuff=save_main_stuff,+ no_pretty_print=no_pretty_print,+ graph=graph,+ )+ return+# Resolve method name to pipe_code and library dirspipe_code, method_library_dirs, method = resolve_method_target(method_name=name,diff --git a/pipelex/cli/commands/run/pipe_cmd.py b/pipelex/cli/commands/run/pipe_cmd.pyindex f92fcb94e..4da3fce1b 100644--- a/pipelex/cli/commands/run/pipe_cmd.py+++ b/pipelex/cli/commands/run/pipe_cmd.py@@ -5,8 +5,11 @@ from typing import Annotatedimport typer+from pipelex.cli.commands.run._hosted_sources import hosted_pipe_library_filesfrom pipelex.cli.commands.run._run_core import COMMAND, execute_run, validate_run_flag_combination+from pipelex.cli.commands.run._run_hosted import execute_hosted_run, refuse_local_only_flags, resolve_cli_run_executionfrom pipelex.cli.method_resolver import resolve_pipe_from_exports+from pipelex.hosted.exceptions import HostedRunSourceErrorfrom pipelex.mthds_parsing.helpers import MTHDS_EXTENSION, is_pipelex_file@@ -99,6 +102,20 @@ def run_pipe_cmd(help="Write the main stuff to this literal CSV path (not under --output-dir; absolute/~/relative ok). Requires a flat list output.",),] = None,+ hosted: Annotated[+ bool | None,+ typer.Option(+ "--hosted/--local",+ help="Run on the hosted Pipelex API (key in PIPELEX_API_KEY) or on this machine. Default: [run] execution, else local.",+ ),+ ] = None,+ base_url: Annotated[+ str | None,+ typer.Option(+ "--base-url",+ help="Origin of the hosted API a hosted run calls, scheme://host[:port]. Overrides PIPELEX_BASE_URL; default https://api.pipelex.com.",+ ),+ ] = None,) -> None:"""Run a pipe by code.@@ -107,6 +124,7 @@ def run_pipe_cmd(pipelex run pipe my_pipe --inputs data.jsonpipelex run pipe my_pipe --dry-runpipelex run pipe my_pipe --dry-run --mock-inputs+ pipelex run pipe my_pipe -L my_library/ --hosted --inputs data.json"""# Helpful error if the user passes a path instead of a pipe codetarget_path = Path(pipe_code)@@ -137,6 +155,39 @@ def run_pipe_cmd(else:library_dir = [*extra_dirs, *library_dir]+ execution = resolve_cli_run_execution(hosted=hosted, base_url=base_url)+ if execution.is_hosted:+ refuse_local_only_flags(+ dry_run=dry_run,+ mock_usage=mock_usage,+ mock_inputs=mock_inputs,+ orchestrator=orchestrator,+ save_csv=save_csv,+ costs=costs,+ graph_full_data=graph_full_data,+ )+ # The hosted API holds no library of yours: the one a local run would load is sent along.+ try:+ library_files = hosted_pipe_library_files(library_dirs=library_dir)+ except HostedRunSourceError as exc:+ typer.secho(f"Failed to run: {exc.message}", fg=typer.colors.RED, err=True)+ raise typer.Exit(1) from exc+ execute_hosted_run(+ mthds_files=library_files,+ pipe_code=pipe_code,+ inputs=inputs,+ dynamic_output_concept_ref=dynamic_output_concept_ref,+ base_url=base_url,+ output_label=pipe_code,+ output_dir=output_dir,+ save_working_memory=save_working_memory,+ working_memory_path=working_memory_path,+ save_main_stuff=save_main_stuff,+ no_pretty_print=no_pretty_print,+ graph=graph,+ )+ return+execute_run(pipe_code=pipe_code,bundle_path=None,diff --git a/pipelex/cli/dev_cli/commands/hub_layering_guard.py b/pipelex/cli/dev_cli/commands/hub_layering_guard.pyindex fe10deb00..fda223745 100644--- a/pipelex/cli/dev_cli/commands/hub_layering_guard.py+++ b/pipelex/cli/dev_cli/commands/hub_layering_guard.py@@ -153,6 +153,11 @@ SCAN_ROOTS: tuple[Path, ...] = (SOURCE_ROOT, TESTS_ROOT)#: interpreter modules into a kernel-only process and no static gate could see it, because the#: engine never reached `interpreter_hub`. Declaring both is what keeps the next such import loud.#:+#: `pipelex.hosted` is declared from its first commit for the same reason as `pipelex.kernel`: a hosted run+#: boots nothing, and it has to work on a machine with no inference configured, so its whole value is that it+#: loads no interpreter module. It reads the configuration files, builds pipelex-sdk's client and maps a run onto+#: it; the CLI parts that need a bundle parsed stay in `pipelex.cli`.+#:#: `pipelex.kit` is data files with no module to police; `pipelex.language`, `pipelex.runtime_bridge`#: and `pipelex.cli` all measure dirty and are interpreter-side by construction. `pipelex.methods`#: measures dirty as well, without reaching `interpreter_hub`: its structures check reads the stamp@@ -166,6 +171,7 @@ KERNEL_LAYER_PACKAGES: tuple[str, ...] = ("pipelex.errors","pipelex.fix_ops","pipelex.graph",+ "pipelex.hosted","pipelex.kernel","pipelex.migration","pipelex.observer",diff --git a/pipelex/hosted/__init__.py b/pipelex/hosted/__init__.pynew file mode 100644index 000000000..e69de29bbdiff --git a/pipelex/hosted/client_factory.py b/pipelex/hosted/client_factory.pynew file mode 100644index 000000000..72a1d895e--- /dev/null+++ b/pipelex/hosted/client_factory.py@@ -0,0 +1,84 @@+"""The one place pipelex builds a client for the hosted Pipelex API.++The client is pipelex-sdk's `PipelexAPIClient`, which resolves its own key and base URL: the key from+`PIPELEX_API_KEY`, the base URL from the argument, then `PIPELEX_BASE_URL`, then `https://api.pipelex.com`. The+runtime loads `~/.pipelex/.env` and then `./.env` into the environment when `pipelex.system.environment` is first+imported, which this module does, so a key saved there reaches the client with nothing exported.+"""++from urllib.parse import urlsplit, urlunsplit++from mthds.protocol.exceptions import PipelineRequestError+from pipelex_sdk.client import DEFAULT_API_BASE_URL, PipelexAPIClient+from pipelex_sdk.user_agent import AppInfo++from pipelex.hosted.exceptions import HostedBaseUrlError+from pipelex.system.environment import get_optional_env+from pipelex.tools.misc.package_utils import get_package_version++#: The variable holding the Pipelex API key (`plx_sk_…`), read by the SDK.+PIPELEX_API_KEY_ENV_KEY = "PIPELEX_API_KEY"+#: The variable overriding the hosted API's origin, read by the SDK when no `--base-url` is given.+PIPELEX_BASE_URL_ENV_KEY = "PIPELEX_BASE_URL"+#: The origin a hosted run goes to when neither `--base-url` nor `PIPELEX_BASE_URL` names another.+HOSTED_API_DEFAULT_BASE_URL = DEFAULT_API_BASE_URL+#: The name this runtime gives itself in the `User-Agent` of every hosted request.+_APP_NAME = "pipelex"+++def redact_url_for_display(*, url: str) -> str:+ """A URL as a message may show it: its scheme, host, port and path, never its credentials, query or fragment.++ Userinfo becomes `***@`, and a query or a fragment becomes `?…` or `#…`, so the reader still sees what made the URL+ unfit without the secrets it may carry, a password or a token in a query. A value that does not parse as a URL+ is not shown at all.+ """+ try:+ parts = urlsplit(url)+ port = parts.port+ except ValueError:+ return "<a value that does not parse as a URL>"+ if not parts.netloc and "@" in url:+ # Without `//`, urlsplit reads userinfo as a scheme plus a path (`user:secret@host` is scheme `user`), so the+ # credentials would pass through whole: show only what follows the last `@`, its query and fragment dropped.+ after_userinfo = url.rsplit("@", 1)[1]+ return "***@" + after_userinfo.split("?", 1)[0].split("#", 1)[0]+ host = parts.hostname or ""+ netloc = f"[{host}]" if ":" in host else host+ if port is not None:+ netloc = f"{netloc}:{port}"+ if parts.username is not None or parts.password is not None:+ netloc = f"***@{netloc}"+ shown = urlunsplit((parts.scheme, netloc, parts.path, "", ""))+ if parts.query:+ shown += "?…"+ if parts.fragment:+ shown += "#…"+ return shown+++def make_hosted_client(*, base_url: str | None = None) -> PipelexAPIClient:+ """Build a hosted API client, the key and the base URL left to the SDK's own resolution.++ Args:+ base_url: The origin to call, `scheme://host[:port]`, as `--base-url` gives it. `None` lets the SDK read+ `PIPELEX_BASE_URL`, then fall back to the hosted API.++ Returns:+ A client not yet started: use it as an async context manager.++ Raises:+ HostedBaseUrlError: If the base URL is not host-only, naming the setting it came from.+ """+ try:+ return PipelexAPIClient(base_url=base_url, app_info=AppInfo(name=_APP_NAME, version=get_package_version()))+ except PipelineRequestError:+ # The SDK's constructor raises this for one reason only: a base URL that is not an origin.+ source = "--base-url" if base_url is not None else PIPELEX_BASE_URL_ENV_KEY+ given = base_url if base_url is not None else get_optional_env(PIPELEX_BASE_URL_ENV_KEY) or ""+ msg = (+ f"The hosted API base URL from {source} is not an origin: {redact_url_for_display(url=given)!r}. "+ "Give scheme://host[:port], with http or https and no path, query or credentials, such as https://api.pipelex.com."+ )+ # Not chained: the SDK's message quotes the rejected value whole, credentials included, and a traceback prints it.+ raise HostedBaseUrlError(msg) from Nonediff --git a/pipelex/hosted/error_rendering.py b/pipelex/hosted/error_rendering.pynew file mode 100644index 000000000..4c6f47b44--- /dev/null+++ b/pipelex/hosted/error_rendering.py@@ -0,0 +1,229 @@+"""What went wrong on a hosted run, and what to do next, read off the error pipelex-sdk or pipelex raised.++Every error of a hosted run that is not pipelex's own arrives as one of the SDK's classes, all of which derive from+the protocol's `PipelineRequestError`; pipelex's own derive from `HostedRunError`. An `ApiResponseError` carries the+hosted API's problem document: its reason (the problem's `detail`) and, when the server advised one, its next step+(`user_action.detail`). Answers the hosted plane authors in front of the runner (a refused key, an unknown route, a+rate limit, an unavailable runner) advise none, so their next step follows their status here. Both CLIs read the+same view of an error, its run id and its validation items included, so a person and an agent are told the same+thing.+"""++from typing import NamedTuple++from mthds.protocol.exceptions import PipelineRequestError+from pipelex_sdk.errors import (+ ApiResponseError,+ ApiUnreachableError,+ InputPreparationError,+ InvalidLocalSourceError,+ MissingMainStuffError,+ PipelineExecuteTimeoutError,+ RejectedAssetError,+ RunFailedError,+ RunLifecycleUnavailableError,+ RunTimeoutError,+ UnsupportedUploadCapabilityError,+ UploadAuthenticationError,+ UploadTransportError,+)+from pipelex_sdk.validation_models import ValidationErrorItem++from pipelex.base_exceptions import ErrorDomain+from pipelex.hosted.client_factory import HOSTED_API_DEFAULT_BASE_URL, PIPELEX_API_KEY_ENV_KEY, PIPELEX_BASE_URL_ENV_KEY+from pipelex.hosted.exceptions import HostedMethodInvalidError, HostedRunError, HostedRunInterruptedError, HostedRunPollingError++#: Where a hosted run takes its key from, and where a person gets one.+HOSTED_API_KEY_NEXT_STEP = (+ f"Set {PIPELEX_API_KEY_ENV_KEY} to a Pipelex API key (plx_sk_…) in your shell or in ~/.pipelex/.env; create one on app.pipelex.com"+)+#: Where a hosted run takes its origin from.+HOSTED_BASE_URL_NEXT_STEP = (+ f"Check the hosted API origin: --base-url, else {PIPELEX_BASE_URL_ENV_KEY}, else https://api.pipelex.com; "+ "it is scheme://host[:port], with no path such as /v1"+)+_RATE_LIMITED_NEXT_STEP = "Too many requests: wait retry_after_seconds when the error carries it, otherwise a few seconds, then run again"+# A 503 does not say whether the run happened: the hosted plane can answer it before forwarding the request and also+# after the run completed, when it failed to record the result. So its next step warns that running again can repeat+# a paid run.+_UNAVAILABLE_NEXT_STEP = (+ "The hosted API or the runner behind it was unavailable. It may have failed before the run or after it, so running "+ "again can repeat a paid run: wait retry_after_seconds when the error carries it, then run again only if a repeated run is acceptable"+)++#: The next step of a refusal whose answer advised none, by its HTTP status.+HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS: dict[int, str] = {+ 401: f"The hosted API refused the credentials. {HOSTED_API_KEY_NEXT_STEP}",+ 403: (+ f"The hosted API refused the request: check that {PIPELEX_API_KEY_ENV_KEY} is a valid key for the API at "+ f"{PIPELEX_BASE_URL_ENV_KEY} (or --base-url); when it is, the message says what this request may not do"+ ),+ 404: f"The hosted API has no such method or route: check the method's address or catalog id. {HOSTED_BASE_URL_NEXT_STEP}",+ 429: _RATE_LIMITED_NEXT_STEP,+ 503: _UNAVAILABLE_NEXT_STEP,+}+#: The next step of a 4xx refusal that advised none and whose status has no next step of its own.+HOSTED_REFUSAL_CALLER_NEXT_STEP = (+ "The hosted API refused the request: change what the message names (the method, the inputs or the configuration), then run again"+)+#: The next step of a server-side failure that advised none.+HOSTED_SERVER_FAULT_NEXT_STEP = (+ "The hosted API failed on its side: report it with the request_id, or with the http_status when the error carries no request_id"+)+#: The next step of a request that never reached the hosted API.+HOSTED_UNREACHABLE_NEXT_STEP = f"Check the network connection. {HOSTED_BASE_URL_NEXT_STEP}"+++class HostedErrorView(NamedTuple):+ """A hosted run's failure, as both CLIs tell it: the class to branch on, what happened, and what to do next.++ `error_domain` says who acts (`input`: the caller's request; `config`: the key, the base URL or the network;+ `runtime`: the run itself), as the hosted API said it when it did; `retryable` is the hosted API's own verdict,+ `None` when it gave none. `pipeline_run_id` names the run once the hosted API acknowledged it, so a run that failed,+ outlived the wait, was lost on the way or was left running by an interruption can be looked up.+ `validation_errors` are the hosted API's items locating the faults of a method it refused, each naming its file+ when the file was sent under a label.+ """++ error_type: str+ message: str+ next_step: str+ error_domain: str | None = None+ retryable: bool | None = None+ pipeline_run_id: str | None = None+ validation_errors: tuple[ValidationErrorItem, ...] = ()+++def hosted_refusal_next_step(*, error: ApiResponseError) -> str:+ """The next step of a refusal: the one the server advised, else the one its status calls for."""+ if error.user_action is not None:+ return error.user_action.detail+ by_status = HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS.get(error.status)+ if by_status is not None:+ return by_status+ if 400 <= error.status < 500:+ return HOSTED_REFUSAL_CALLER_NEXT_STEP+ return HOSTED_SERVER_FAULT_NEXT_STEP+++def hosted_refusal_message(*, error: ApiResponseError) -> str:+ """`API POST /v1/start failed (422): <reason>`, the error's own message without the next step it appends."""+ message = str(error)+ if error.user_action is not None:+ message = message.removesuffix(f"\nNext step: {error.user_action.detail}")+ return message+++def describe_hosted_error(*, error: PipelineRequestError | HostedRunError) -> HostedErrorView:+ """Read a hosted run's failure off the error pipelex-sdk or pipelex raised.++ Args:+ error: The SDK's error, or one pipelex raised during the run. Its class decides the next step; an+ `ApiResponseError` names the runner's own class when the problem document carries one, and a failed run+ names its stored report's.++ Returns:+ The class to report, the message, the next step, and the run and the validation items when there are any.+ """+ error_type = type(error).__name__+ message = str(error)+ next_step: str+ error_domain: str | None = None+ retryable: bool | None = None+ pipeline_run_id: str | None = None+ validation_errors: tuple[ValidationErrorItem, ...] = ()+ match error:+ case HostedRunError():+ message = error.message+ next_step = error.user_action.detail if error.user_action is not None else "Check the run request: the method, the pipe and the inputs"+ error_domain = error.error_domain+ if isinstance(error, (HostedRunPollingError, HostedRunInterruptedError)):+ pipeline_run_id = error.pipeline_run_id+ if isinstance(error, HostedMethodInvalidError):+ validation_errors = tuple(error.validation_errors)+ case ApiResponseError():+ error_type = error.error_type or error_type+ message = hosted_refusal_message(error=error)+ next_step = hosted_refusal_next_step(error=error)+ error_domain = error.error_domain+ retryable = error.retryable+ validation_errors = tuple(error.validation_errors or ())+ case RunFailedError():+ report = error.error+ pipeline_run_id = error.run_id+ error_domain = ErrorDomain.RUNTIME+ if report is not None:+ error_type = report.error_type or error_type+ error_domain = report.error_domain or error_domain+ retryable = report.retryable+ validation_errors = tuple(report.validation_errors or ())+ if report is not None and report.user_action is not None and report.user_action.detail:+ next_step = report.user_action.detail+ else:+ next_step = f"The run {error.run_id} ended {error.status}: change what the message names, then run again"+ case RunTimeoutError():+ pipeline_run_id = error.run_id+ error_domain = ErrorDomain.RUNTIME+ next_step = (+ f"The run {error.run_id} keeps running on the hosted API: find it on app.pipelex.com, or read its result "+ "later with pipelex-sdk's PipelexAPIClient.wait_for_result"+ )+ case MissingMainStuffError():+ pipeline_run_id = error.run_id+ error_domain = ErrorDomain.RUNTIME+ next_step = (+ f"The run {error.run_id} completed, but the hosted API delivered no main output: look the run up by its id on "+ "app.pipelex.com, and report it with the run id"+ )+ case PipelineExecuteTimeoutError():+ # A hosted run calls the blocking route only on a server that keeps no runs (its version handshake says so,+ # or its start refused for a missing run store), so running again takes the same route and repeats a paid run.+ error_domain = ErrorDomain.RUNTIME+ retryable = False+ next_step = (+ "The server at the base URL keeps no runs to poll, so the run went through the blocking route and the connection "+ "was cut before the result came back. The run may still be going there, and running the command again runs the "+ "method again on the same route: raise the timeout of the proxy in front of that server, or point --base-url or "+ f"{PIPELEX_BASE_URL_ENV_KEY} at a server that keeps runs, such as {HOSTED_API_DEFAULT_BASE_URL}"+ )+ case ApiUnreachableError():+ error_domain = ErrorDomain.CONFIG+ next_step = HOSTED_UNREACHABLE_NEXT_STEP+ case RunLifecycleUnavailableError():+ error_domain = ErrorDomain.CONFIG+ next_step = f"The server at the base URL is a bare runner without run polling. {HOSTED_BASE_URL_NEXT_STEP}"+ case UploadAuthenticationError():+ error_domain = ErrorDomain.CONFIG+ next_step = HOSTED_API_KEY_NEXT_STEP+ case InvalidLocalSourceError():+ error_domain = ErrorDomain.INPUT+ next_step = "Check the file path in the inputs: a relative path in an inputs file resolves against that file's directory"+ case RejectedAssetError():+ error_domain = ErrorDomain.INPUT+ next_step = "The hosted API refused the file: send a smaller one, or one of a type the input accepts"+ case UnsupportedUploadCapabilityError():+ error_domain = ErrorDomain.CONFIG+ next_step = f"The server at the base URL takes no uploads: pass the file as an http(s) URL. {HOSTED_BASE_URL_NEXT_STEP}"+ case UploadTransportError():+ # The SDK raises it for an upload that never reached the hosted API, chained from `ApiUnreachableError`,+ # and for one the hosted API failed on its side, a 5xx.+ if isinstance(error.__cause__, ApiUnreachableError):+ error_domain = ErrorDomain.CONFIG+ next_step = HOSTED_UNREACHABLE_NEXT_STEP+ else:+ error_domain = ErrorDomain.RUNTIME+ next_step = HOSTED_SERVER_FAULT_NEXT_STEP+ case InputPreparationError():+ error_domain = ErrorDomain.INPUT+ next_step = "Check the inputs against the pipe's signature (pipelex-agent inputs prints a template), then run again"+ case _:+ next_step = "Check the run request: the method, the pipe and the inputs"+ return HostedErrorView(+ error_type=error_type,+ message=message,+ next_step=next_step,+ error_domain=error_domain,+ retryable=retryable,+ pipeline_run_id=pipeline_run_id,+ validation_errors=validation_errors,+ )diff --git a/pipelex/hosted/exceptions.py b/pipelex/hosted/exceptions.pynew file mode 100644index 000000000..5fbcc12d0--- /dev/null+++ b/pipelex/hosted/exceptions.py@@ -0,0 +1,142 @@+from typing import ClassVar++from pipelex_sdk.validation_models import ValidationErrorItem++from pipelex.base_exceptions import ErrorDomain, PipelexError+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind+++class HostedRunError(PipelexError):+ """Base class for errors pipelex raises itself while running a method on the hosted Pipelex API.++ An error the hosted API answers, or one the pipelex-sdk client raises on the way, keeps the SDK's own class+ (`ApiResponseError`, `ApiUnreachableError`, `RunFailedError`, …); these are the ones pipelex detects itself: before+ it sends anything, from the verdict of the method's signature, from a connection lost after the run request was+ sent, while following a run it started, or when the run is interrupted on this machine.+ """++ _declared_title = "Hosted run error"+++class HostedBaseUrlError(HostedRunError):+ """The base URL of the hosted API is not an origin: it carries a path, a query, credentials, or a scheme other than http or https.++ The message names where the value came from, `--base-url` or `PIPELEX_BASE_URL`, and what an origin looks like.+ """++ error_domain = ErrorDomain.INPUT+ user_action = UserAction(+ kind=UserActionKind.CHANGE_INPUT,+ detail="Give the hosted API's origin as scheme://host[:port], such as https://api.pipelex.com, in --base-url or PIPELEX_BASE_URL",+ )+ _authors_caller_facing_message: ClassVar[bool] = True+++class HostedRunSourceError(HostedRunError):+ """A hosted run cannot be given the method to run: no bundle file, no `.mthds` file in the library directories, or no source at all."""++ error_domain = ErrorDomain.INPUT+ _authors_caller_facing_message: ClassVar[bool] = True+++class HostedMethodInvalidError(HostedRunError):+ """The hosted API read the method's signature before the run and found that the method does not load.++ Raised from `POST /v1/pipe-io`'s invalid verdict, before any run starts. Its `validation_errors` are the hosted+ API's items, each naming the file it found the fault in by the label the file was sent under, which the run route+ could not do: it takes the method's files as bare contents.+ """++ error_domain = ErrorDomain.INPUT+ user_action = UserAction(kind=UserActionKind.CHANGE_INPUT, detail="Fix the method as each validation error says, then run it again")+ _authors_caller_facing_message: ClassVar[bool] = True++ def __init__(self, message: str, *, validation_errors: list[ValidationErrorItem]):+ super().__init__(message)+ self.validation_errors = validation_errors+++class HostedRunPollingError(HostedRunError):+ """A run started on the hosted API, but following it to its result failed: the network, the hosted API, or its answer.++ The run was acknowledged, so it may still be running, and it is paid for: `pipeline_run_id` locates it, and running+ the command again would start another one. The cause is the failure met while following it.+ """++ error_domain = ErrorDomain.RUNTIME++ def __init__(self, message: str, *, pipeline_run_id: str):+ super().__init__(message)+ self.pipeline_run_id = pipeline_run_id+ self.user_action = UserAction(+ kind=UserActionKind.UNKNOWN,+ detail=(+ f"The run {pipeline_run_id} may still be running on the hosted API, and running the command again starts a new, paid "+ f"run: look the run up by its id on app.pipelex.com, or read its result with pipelex-sdk's "+ f"PipelexAPIClient.wait_for_result('{pipeline_run_id}')"+ ),+ )+++class HostedRunOutcomeUnknownError(HostedRunError):+ """The request that runs the method was sent, and the connection failed before its answer came back.++ The hosted API may have created the run before the connection failed, with no way to tell from here: its id never+ arrived. Running the command again could start a second paid run, so the next step is the run history first. The+ cause is the transport failure, a read, a write or a protocol failure met after the request left this machine.+ """++ error_domain = ErrorDomain.RUNTIME+ user_action = UserAction(+ kind=UserActionKind.UNKNOWN,+ detail=(+ "A run may have started on the hosted API before the connection failed: check the run history on app.pipelex.com "+ "before running again, since running again starts a new, paid run"+ ),+ )+++class HostedRunInterruptedError(HostedRunError):+ """The hosted run was interrupted on this machine, by Ctrl-C or a cancellation, while it was being started or followed.++ Interrupting stops the wait, not the run: a run the hosted API acknowledged keeps going and is paid for, and+ `pipeline_run_id` finds it again. Interrupted before the acknowledgement, `pipeline_run_id` is `None`, and the+ start request may still have reached the hosted API.+ """++ error_domain = ErrorDomain.RUNTIME+ _authors_caller_facing_message: ClassVar[bool] = True++ def __init__(self, *, pipeline_run_id: str | None):+ if pipeline_run_id is None:+ message = "Interrupted before the hosted API acknowledged a run"+ detail = (+ "If the start request had reached the hosted API, a run may have started: check the run history on app.pipelex.com "+ "before running again"+ )+ else:+ message = f"Interrupted while following the run {pipeline_run_id}, which keeps going on the hosted API"+ detail = (+ f"The run {pipeline_run_id} keeps going on the hosted API and is paid for: look it up by its id on app.pipelex.com, "+ f"or read its result with pipelex-sdk's PipelexAPIClient.wait_for_result('{pipeline_run_id}'); running the command "+ "again starts a new run"+ )+ super().__init__(message)+ self.pipeline_run_id = pipeline_run_id+ self.user_action = UserAction(kind=UserActionKind.UNKNOWN, detail=detail)+++class HostedLocalFileUploadUnavailableError(HostedRunError):+ """A hosted run's inputs name a local file, and its method calls another method by its address.++ Uploading a local file is guided by the pipe's signature, which `POST /v1/pipe-io` reads, and the crate core behind+ that route loads no address-based dependency, while the run route fetches it. The method is not at fault: the same+ run goes through when the file is given as an https URL, which needs no upload.+ """++ error_domain = ErrorDomain.INPUT+ user_action = UserAction(+ kind=UserActionKind.CHANGE_INPUT,+ detail="Pass each local file as an https URL the hosted API can fetch, instead of a path on this machine, then run again",+ )+ _authors_caller_facing_message: ClassVar[bool] = Truediff --git a/pipelex/hosted/execution.py b/pipelex/hosted/execution.pynew file mode 100644index 000000000..ccbb7bf0f--- /dev/null+++ b/pipelex/hosted/execution.py@@ -0,0 +1,50 @@+"""Where a run executes: the `--hosted`/`--local` flag, then the `[run] execution` setting.++Both CLIs call `resolve_run_execution` before they boot anything, because the answer decides what to boot: a+local run boots the runtime with its inference, a hosted run boots nothing and talks to the hosted API.+"""++from pipelex.core.validation import raise_config_setup_error+from pipelex.hosted.run_config import RunExecution+from pipelex.runtime_hub import get_optional_config+from pipelex.system.configuration.config_loader import CONFIG_REFUSED, config_manager+from pipelex.system.configuration.config_surface import PIPELEX_CONFIG_SURFACE_ID+from pipelex.system.configuration.configs import PipelexConfig+++def get_or_load_pipelex_config() -> PipelexConfig:+ """The booted configuration when a boot holds one, else the same layers read and validated without booting.++ A hosted run never boots the runtime, so it reads its settings the way a boot would: the package defaults, the+ home configuration directory, then the project's `.pipelex/`, project over home.++ Raises:+ PipelexConfigError: If the configuration files do not validate, with what a `pipelex migrate` would find.+ """+ booted = get_optional_config()+ if isinstance(booted, PipelexConfig):+ return booted+ try:+ return config_manager.load_config_validated(config_cls=PipelexConfig)+ except CONFIG_REFUSED as config_error:+ raise_config_setup_error(config_error=config_error, surface_id=PIPELEX_CONFIG_SURFACE_ID)+++def configured_run_execution() -> RunExecution:+ """The `[run] execution` setting: the project's `.pipelex/pipelex.toml` over the home one over the packaged `local`."""+ return get_or_load_pipelex_config().run.execution+++def resolve_run_execution(*, requested: RunExecution | None) -> RunExecution:+ """Where this run executes: the execution the command requested, else the configured default.++ Args:+ requested: The execution the command's flags name (`--hosted`, `--local`, or `--runner` on the agent CLI),+ or `None` when they name none.++ Returns:+ The execution to use. A requested one never reads the configuration.+ """+ if requested is not None:+ return requested+ return configured_run_execution()diff --git a/pipelex/hosted/hosted_inputs.py b/pipelex/hosted/hosted_inputs.pynew file mode 100644index 000000000..7d2a73e20--- /dev/null+++ b/pipelex/hosted/hosted_inputs.py@@ -0,0 +1,318 @@+"""Inputs of a hosted run: find the local files they name, anchor them, and upload them before the run.++A hosted run cannot read this machine's files, so a document or an image given as a local path must be uploaded+first, and the run given the storage URI instead. Where a file sits is the pipe's signature to say, so the input-form+descriptor `POST /v1/pipe-io` answers guides a walk over the inputs: each local path at a document or image position is+anchored as a local run reads it (a relative path in an inputs file against that file's directory, a `file://` URI as+the path it names, `~` expanded), uploaded once with the SDK's `upload_file`, and rewritten to canonical content+carrying the storage URI. Every other value, an explicit `null` included, reaches the run as the caller wrote it.++The signature is read only when it can matter: when some string of the inputs, at any depth, names an existing file on+this machine. Any other inputs go straight to the run, which keeps pipe-io out of a run that uploads nothing; pipe-io+cannot load a method calling another one by its address, which the run route fetches and runs.+"""++import contextlib+import os+import re+from pathlib import Path+from typing import Any, NamedTuple, Protocol, cast++from mthds.protocol.input_form import (+ BooleanItem,+ DateItem,+ DocumentItem,+ EnumItem,+ ImageItem,+ InputFormItem,+ ListItem,+ NumberItem,+ ObjectItem,+ PipeInputFormDescriptor,+ ProseItem,+ TextItem,+ UnknownItem,+)+from pipelex_sdk.client import PipelexAPIClient+from pipelex_sdk.crate_models import CrateInvalidReport, MthdsFileItem, PipeIORequest+from pipelex_sdk.upload import UploadRecord++from pipelex.hosted.exceptions import HostedLocalFileUploadUnavailableError, HostedMethodInvalidError+from pipelex.tools.uri.resolved_uri import ResolvedLocalPath+from pipelex.tools.uri.uri_resolver import resolve_uri++#: An `http(s)://` URL, which the hosted API fetches itself. Matched as the SDK matches it, whatever the case of the+#: scheme.+_HTTP_URL_PATTERN = re.compile(r"^https?://", re.IGNORECASE)+#: The other source forms that are not files on this machine, matched as the SDK matches them, case included: a storage+#: URI, and a data URL, which carries its bytes and reaches the run as it is.+_NOT_LOCAL_PREFIXES: tuple[str, ...] = ("pipelex-storage://", "data:")+#: A `file://` URI, which a local run reads as the local path it names.+_FILE_URI_PREFIX = "file://"+#: What the crate core behind `POST /v1/pipe-io` says when it refuses a method calling another one by its address+#: (`pipelex/pipeline/resolve_bundle.py`). The run route fetches such a dependency; pipe-io cannot load it.+ADDRESS_DEPENDENCY_REFUSAL_MARKER = "address-based dependency"+#: The dependency's address, as that refusal quotes it.+_REFUSED_DEPENDENCY_PATTERN = re.compile(re.escape(ADDRESS_DEPENDENCY_REFUSAL_MARKER) + r" '([^']+)'")+++class AnchoredInputs(NamedTuple):+ """Inputs with every local file at a file position anchored, and the local files found, in walk order."""++ inputs: dict[str, Any]+ local_sources: list[str]+++class PreparedHostedInputs(NamedTuple):+ """What a hosted run sends as inputs, the files uploaded for it, and the qualified pipe its signature was read from."""++ inputs: dict[str, Any] | None+ uploads: list[UploadRecord]+ #: The qualified ref of the pipe whose signature was read, `None` when the inputs named no local file to read it for.+ pipe_ref: str | None+++class _FilePositionVisitor(Protocol):+ """What the descriptor walk does with a value the signature declares a document or an image."""++ def __call__(self, *, value: Any) -> Any: ...+++def _local_path_reference(*, source: str, base_dir: Path | None) -> str | None:+ """The local path a source names, anchored to `base_dir` when relative; `None` for a form that is not a local file.++ A `file://` URI is decoded to its path, as a local run decodes it, and `~` is expanded, leaving a `~user` whose+ home is unknown as it is rather than failing.+ """+ if source.startswith(_NOT_LOCAL_PREFIXES) or _HTTP_URL_PATTERN.match(source):+ return None+ if source.startswith(_FILE_URI_PREFIX):+ resolved = resolve_uri(source)+ if isinstance(resolved, ResolvedLocalPath):+ source = resolved.path+ path = Path(source)+ with contextlib.suppress(RuntimeError):+ # A `~user` whose home is unknown stays as written: any text of the inputs is asked about, not only paths.+ path = path.expanduser()+ if base_dir is not None and not path.is_absolute():+ path = base_dir / path+ return str(path)+++def _names_an_existing_local_file(*, source: str, base_dir: Path | None) -> bool:+ """Whether a string names a file on this machine, from `base_dir` or from the working directory.++ `os.path.isfile` answers `False` for a value no path can be (one too long, one carrying a NUL byte), so any text+ is safe to ask about. `Path.is_file` raises on a name too long before Python 3.13, so it is not used here.+ """+ candidates = {_local_path_reference(source=source, base_dir=base_dir), _local_path_reference(source=source, base_dir=None)}+ return any(candidate is not None and os.path.isfile(candidate) for candidate in candidates) # ruff: ignore[os-path-isfile]+++def _value_names_a_local_file(*, value: Any, base_dir: Path | None) -> bool:+ if isinstance(value, str):+ return _names_an_existing_local_file(source=value, base_dir=base_dir)+ if isinstance(value, dict):+ return any(_value_names_a_local_file(value=member, base_dir=base_dir) for member in cast("dict[str, Any]", value).values())+ if isinstance(value, list):+ return any(_value_names_a_local_file(value=element, base_dir=base_dir) for element in cast("list[Any]", value))+ return False+++def inputs_name_a_local_file(*, inputs: dict[str, Any], base_dir: Path | None) -> bool:+ """Whether some string of the inputs, at any depth, names an existing file on this machine.++ The test decides whether a hosted run reads its pipe's signature before it starts, so it reads no signature: it+ looks at every string, whatever its position, and counts one that is not an `http(s)://` URL, a+ `pipelex-storage://` URI or a `data:` URL and names a file under `base_dir` (the inputs file's directory) or the+ working directory. A `file://` URI counts by the path it names.+ """+ return _value_names_a_local_file(value=inputs, base_dir=base_dir)+++def _anchor_source(*, source: str, base_dir: Path | None, local_sources: list[str]) -> str:+ """A source at a file position, a local path anchored to `base_dir` and recorded, any other form unchanged."""+ anchored = _local_path_reference(source=source, base_dir=base_dir)+ if anchored is None:+ return source+ local_sources.append(anchored)+ return anchored+++def _anchor_file_position(*, value: Any, base_dir: Path | None, local_sources: list[str]) -> Any:+ """A value the signature declares a document or an image: a path string, or content whose `url` is one."""+ if isinstance(value, str):+ return _anchor_source(source=value, base_dir=base_dir, local_sources=local_sources)+ if isinstance(value, dict):+ content = cast("dict[str, Any]", value)+ url = content.get("url")+ if isinstance(url, str):+ return {**content, "url": _anchor_source(source=url, base_dir=base_dir, local_sources=local_sources)}+ return content+ # `None` (an optional file left out) and any other shape are left for the run to read: preparation never+ # second-guesses the signature.+ return value+++def _walk_node(*, node: InputFormItem, value: Any, at_file_position: _FilePositionVisitor) -> Any:+ """Walk one value against its descriptor node, the way the SDK's preparation walks it.++ The match is over the item classes, which the per-kind named fields derive from, so one set of patterns covers a+ named position and a list's nameless item alike. An `unknown` node is a dynamic input whose signature declares no+ file, and it is not entered, as the SDK does not enter it.+ """+ match node:+ case DocumentItem() | ImageItem():+ return at_file_position(value=value)+ case ObjectItem():+ if not isinstance(value, dict):+ return value+ caller_dict = cast("dict[str, Any]", value)+ walked: dict[str, Any] = dict(caller_dict)+ for field in node.fields:+ if field.name in caller_dict:+ walked[field.name] = _walk_node(node=field, value=caller_dict[field.name], at_file_position=at_file_position)+ return walked+ case ListItem():+ if not isinstance(value, list):+ return value+ elements = cast("list[Any]", value)+ return [_walk_node(node=node.item, value=element, at_file_position=at_file_position) for element in elements]+ case TextItem() | ProseItem() | DateItem() | NumberItem() | BooleanItem() | EnumItem() | UnknownItem():+ return value+++def _is_explicit_envelope(*, value: Any) -> bool:+ """The explicit `{concept, content}` input envelope: exactly those two keys, as the runtime's input shaper reads it."""+ return isinstance(value, dict) and set(cast("dict[str, Any]", value)) == {"concept", "content"}+++def _walk_inputs(*, inputs: dict[str, Any], descriptor: PipeInputFormDescriptor, at_file_position: _FilePositionVisitor) -> dict[str, Any]:+ """Walk each declared input against its descriptor field, an explicit envelope through its content; a copy."""+ declared = {field.name: field for field in descriptor.fields}+ walked: dict[str, Any] = dict(inputs)+ for name, caller_value in inputs.items():+ field = declared.get(name)+ if field is None:+ continue+ if _is_explicit_envelope(value=caller_value):+ envelope = cast("dict[str, Any]", caller_value)+ walked[name] = {**envelope, "content": _walk_node(node=field, value=envelope["content"], at_file_position=at_file_position)}+ else:+ walked[name] = _walk_node(node=field, value=caller_value, at_file_position=at_file_position)+ return walked+++def anchor_local_file_sources(*, inputs: dict[str, Any], descriptor: PipeInputFormDescriptor, base_dir: Path | None) -> AnchoredInputs:+ """Anchor the local files named at the file positions `descriptor` declares, and list them.++ Args:+ inputs: The caller's inputs, compact or in an explicit `{concept, content}` envelope per input. Not mutated.+ descriptor: The input form of the pipe that runs.+ base_dir: The directory a relative path resolves against: the inputs file's, or `None` for inline inputs,+ whose relative paths stay relative to the working directory as on a local run.++ Returns:+ A copy of the inputs with each local path at a file position anchored: a relative one joined to `base_dir`, a+ `file://` URI decoded to its path, `~` expanded. And every local file found, anchored, in walk order. A+ `pipelex-storage://` URI, an `http(s)://` URL (whatever the case of its scheme), a `data:` URL and a `null`+ are not local files. A value at a position the signature does not declare a file is never touched, whatever+ it looks like.+ """+ local_sources: list[str] = []++ def _anchor(*, value: Any) -> Any:+ return _anchor_file_position(value=value, base_dir=base_dir, local_sources=local_sources)++ anchored = _walk_inputs(inputs=inputs, descriptor=descriptor, at_file_position=_anchor)+ return AnchoredInputs(inputs=anchored, local_sources=local_sources)+++def _with_storage_uris(*, anchored: AnchoredInputs, descriptor: PipeInputFormDescriptor, uri_by_source: dict[str, str]) -> dict[str, Any]:+ """The anchored inputs with each uploaded file rewritten to canonical content carrying its storage URI, as the SDK writes it."""++ def _rewrite(*, value: Any) -> Any:+ if isinstance(value, str):+ uri = uri_by_source.get(value)+ return value if uri is None else {"url": uri}+ if isinstance(value, dict):+ content = cast("dict[str, Any]", value)+ url = content.get("url")+ if isinstance(url, str) and url in uri_by_source:+ return {**content, "url": uri_by_source[url]}+ return content+ return value++ return _walk_inputs(inputs=anchored.inputs, descriptor=descriptor, at_file_position=_rewrite)+++def _address_dependency_refusal(*, report: CrateInvalidReport) -> HostedLocalFileUploadUnavailableError | None:+ """The error to raise when pipe-io refused the method for calling another one by its address, else `None`.++ The run route fetches such a dependency, so the method is not at fault. The refusal's own advice, to send the+ dependency's contents, is meant for the API's callers, so the error names the dependency and leaves the advice out.+ """+ messages = [report.message, *(item.message for item in report.validation_errors)]+ refusal = next((message for message in messages if ADDRESS_DEPENDENCY_REFUSAL_MARKER in message), None)+ if refusal is None:+ return None+ msg = "Local file upload is not available yet for methods with address-based dependencies, and the inputs name a local file"+ if dependency := _REFUSED_DEPENDENCY_PATTERN.search(refusal):+ msg += f": this method depends on {dependency.group(1)}"+ return HostedLocalFileUploadUnavailableError(msg)+++async def prepare_hosted_inputs(+ *,+ client: PipelexAPIClient,+ mthds_files: list[MthdsFileItem] | None,+ method_ref: str | None,+ method_id: str | None,+ pipe_code: str | None,+ inputs: dict[str, Any] | None,+ inputs_base_dir: Path | None,+) -> PreparedHostedInputs:+ """Upload the local files a hosted run's inputs name, and hand back the inputs to send.++ Inputs naming no existing file on this machine go as they are, with no request. Otherwise one `POST /v1/pipe-io`+ reads the signature of the pipe that runs, `pipe_code` or the method's entry pipe; each local file at a file+ position is uploaded once with `upload_file` and rewritten to its `pipelex-storage://` URI, and every other value+ is sent as written. A method whose signature does not resolve is refused here, before any run starts: pipe-io's+ verdict names each faulty file by the label it was sent under, which the run route, taking the files as bare+ contents, cannot do.++ Raises:+ HostedLocalFileUploadUnavailableError: If pipe-io cannot load the method because it calls another method by+ its address: the run route would, so the file has to reach it as a URL.+ HostedMethodInvalidError: If the method does not load, with the hosted API's labelled validation items.+ ApiResponseError: If the hosted API refuses the pipe-io request (an unknown method, a key it refuses).+ InputPreparationError: If an upload fails, or a local file cannot be read.+ """+ if not inputs or not inputs_name_a_local_file(inputs=inputs, base_dir=inputs_base_dir):+ return PreparedHostedInputs(inputs=inputs, uploads=[], pipe_ref=None)++ report = await client.pipe_io(PipeIORequest(files=mthds_files, method_ref=method_ref, method_id=method_id, pipe_ref=pipe_code))+ if isinstance(report, CrateInvalidReport):+ if (address_dependency_refusal := _address_dependency_refusal(report=report)) is not None:+ raise address_dependency_refusal+ msg = f"The hosted API cannot load the method: {report.message}"+ raise HostedMethodInvalidError(msg, validation_errors=report.validation_errors)+ selected_pipe_ref = report.pipe_ref+ descriptor = report.input_form.get(selected_pipe_ref) if selected_pipe_ref is not None else None+ if descriptor is None:+ return PreparedHostedInputs(inputs=inputs, uploads=[], pipe_ref=selected_pipe_ref)++ anchored = anchor_local_file_sources(inputs=inputs, descriptor=descriptor, base_dir=inputs_base_dir)+ if not anchored.local_sources:+ return PreparedHostedInputs(inputs=inputs, uploads=[], pipe_ref=selected_pipe_ref)++ uploads: list[UploadRecord] = []+ uri_by_source: dict[str, str] = {}+ for local_source in anchored.local_sources:+ if local_source in uri_by_source:+ continue+ record = await client.upload_file(local_source)+ uploads.append(record)+ uri_by_source[local_source] = record.uri+ prepared_inputs = _with_storage_uris(anchored=anchored, descriptor=descriptor, uri_by_source=uri_by_source)+ return PreparedHostedInputs(inputs=prepared_inputs, uploads=uploads, pipe_ref=selected_pipe_ref)diff --git a/pipelex/hosted/hosted_run.py b/pipelex/hosted/hosted_run.pynew file mode 100644index 000000000..3d560e0c7--- /dev/null+++ b/pipelex/hosted/hosted_run.py@@ -0,0 +1,232 @@+"""A run on the hosted Pipelex API, mapped onto pipelex-sdk's `PipelexAPIClient`.++The request names the method one of three ways, as the hosted API takes them: a local bundle sent as its+`.mthds` contents, a published method's address (`method_ref`, resolved by the hosted runner), or a stored method's+catalog id (`method_id`, resolved by the platform). Local files named in the inputs are uploaded first+(`pipelex.hosted.hosted_inputs`), then the run is started and followed to its end, which outlives the hosted+gateway's 30-second ceiling on a synchronous request.++The lifecycle is the one the SDK's `start_and_wait` drives, taken step by step so that the run's id is in hand once+the hosted API acknowledges the start: the caller is told it at once, and a failure while following the run names the+run, which may still be going and is paid for, instead of reading as a network failure before any run. A connection+lost after the request that runs the method was sent is not read as a network failure either, since the hosted API may+have created the run before it.+"""++from pathlib import Path+from typing import Any, Protocol, Self++import httpx+from mthds.protocol.exceptions import PipelineRequestError+from pipelex_sdk.client import PipelexAPIClient+from pipelex_sdk.crate_models import MthdsFileItem+from pipelex_sdk.errors import ApiUnreachableError, MissingMainStuffError, RunFailedError, RunLifecycleUnavailableError, RunTimeoutError+from pipelex_sdk.execute_result import results_from_execute+from pipelex_sdk.runs import RunResults+from pipelex_sdk.upload import UploadRecord+from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator++from pipelex.hosted.exceptions import HostedRunOutcomeUnknownError, HostedRunPollingError+from pipelex.hosted.hosted_inputs import prepare_hosted_inputs++#: The `implementation` a bare runner names in its `GET /v1/version` handshake: an open-source pipelex-api, which+#: keeps no runs to poll. The same value pipelex-sdk's `start_and_wait` tests to choose the blocking route.+BARE_RUNNER_IMPLEMENTATION = "pipelex-api"+#: The transport failures httpx raises before a request leaves this machine: no connection was made, so no run exists.+#: Every other one (a read, a write, a protocol failure) may come after the hosted API received the request.+_PRE_SEND_TRANSPORT_ERRORS: tuple[type[httpx.TransportError], ...] = (+ httpx.ConnectError,+ httpx.ConnectTimeout,+ httpx.PoolTimeout,+ httpx.UnsupportedProtocol,+ httpx.ProxyError,+)+++class RunStartedCallback(Protocol):+ """Told the id of the run the hosted API acknowledged, before the run is followed to its result."""++ def __call__(self, *, pipeline_run_id: str) -> None: ...+++class HostedRunRequest(BaseModel):+ """One run to execute on the hosted API: its source, its pipe and its inputs.++ Exactly one source: `mthds_files` (a local bundle and the rest of its library), `method_ref` (an address such as+ `github.com/Pipelex/methods/[email protected]`) or `method_id` (a catalog id such as `mt_abc123`). Each file of+ `mthds_files` carries a label, its path: the signature read before the run sends it, so the hosted API names the+ file in the validation errors of a method that does not load, while the run itself takes the bare contents.+ """++ model_config = ConfigDict(frozen=True, extra="forbid")++ mthds_files: list[MthdsFileItem] | None = None+ method_ref: str | None = None+ method_id: str | None = None+ #: The pipe to run; `None` runs the method's entry pipe (a package manifest's or the bundle's `main_pipe`).+ pipe_code: str | None = None+ inputs: dict[str, Any] | None = None+ #: The directory a relative file path in the inputs resolves against: the inputs file's, `None` for inline inputs.+ inputs_base_dir: Path | None = None+ dynamic_output_concept_ref: str | None = None++ @model_validator(mode="after")+ def _exactly_one_source(self) -> Self:+ named = [name for name, value in (("mthds_files", self.mthds_files), ("method_ref", self.method_ref), ("method_id", self.method_id)) if value]+ if len(named) != 1:+ msg = f"A hosted run names exactly one source among mthds_files, method_ref and method_id, got {named or 'none'}"+ raise ValueError(msg)+ return self++ @property+ def mthds_contents(self) -> list[str] | None:+ if not self.mthds_files:+ return None+ return [mthds_file.content for mthds_file in self.mthds_files]+++class HostedRunOutcome(BaseModel):+ """A completed hosted run: its results, the files uploaded for it, and the qualified pipe its inputs were read for."""++ model_config = ConfigDict(frozen=True)++ results: RunResults+ uploads: list[UploadRecord] = Field(default_factory=list[UploadRecord])+ #: The qualified ref (`domain.pipe_code`) of the pipe that ran, when the inputs' preparation read it; `None` otherwise.+ pipe_ref: str | None = None+++async def _serves_run_lifecycle(*, client: PipelexAPIClient) -> bool:+ """Whether the server keeps runs to poll, decided as the SDK's `start_and_wait` decides it.++ The `GET /v1/version` handshake of a bare runner names it; any other answer, and a handshake that fails, is read+ as the hosted API, whose start then surfaces the real error.+ """+ try:+ version_info = await client.version()+ except (PipelineRequestError, httpx.HTTPError, ValidationError):+ return True+ implementation = (version_info.model_extra or {}).get("implementation")+ return not (isinstance(implementation, str) and implementation == BARE_RUNNER_IMPLEMENTATION)+++async def _execute_blocking(*, client: PipelexAPIClient, request: HostedRunRequest, inputs: dict[str, Any] | None) -> RunResults:+ """The blocking `POST /v1/execute` of a server with no run store, lifted onto the results a started run returns."""+ result = await client.execute(+ pipe_code=request.pipe_code,+ mthds_contents=request.mthds_contents,+ inputs=inputs,+ dynamic_output_concept_ref=request.dynamic_output_concept_ref,+ method_ref=request.method_ref,+ method_id=request.method_id,+ )+ return results_from_execute(result)+++async def _start_or_execute_unmapped(*, client: PipelexAPIClient, request: HostedRunRequest, inputs: dict[str, Any] | None) -> str | RunResults:+ if not await _serves_run_lifecycle(client=client):+ return await _execute_blocking(client=client, request=request, inputs=inputs)+ try:+ started = await client.start(+ pipe_code=request.pipe_code,+ mthds_contents=request.mthds_contents,+ inputs=inputs,+ dynamic_output_concept_ref=request.dynamic_output_concept_ref,+ method_ref=request.method_ref,+ method_id=request.method_id,+ )+ except RunLifecycleUnavailableError:+ return await _execute_blocking(client=client, request=request, inputs=inputs)+ return started.pipeline_run_id+++async def _start_or_execute(*, client: PipelexAPIClient, request: HostedRunRequest, inputs: dict[str, Any] | None) -> str | RunResults:+ """Start the run and hand back its id; on a server that keeps no runs, run it on the blocking route and hand back its results.++ A start the server refuses for a missing run store created no run, so running the blocking route next cannot run+ the method twice.++ The SDK maps a transport failure to `ApiUnreachableError` on the routes it owns, but `start` and `execute`, which+ it inherits from mthds, let httpx's error through, and only some of them mean the hosted API was not reached. A+ failure before the request left this machine is mapped as the SDK maps it. Any later one, a connection lost after+ the request was sent, is a `HostedRunOutcomeUnknownError`: the hosted API may have created the run, and its id+ never arrived.+ """+ try:+ return await _start_or_execute_unmapped(client=client, request=request, inputs=inputs)+ except _PRE_SEND_TRANSPORT_ERRORS as exc:+ if isinstance(exc, httpx.TimeoutException):+ msg = f"Could not reach Pipelex API at {client.base_url} (timeout)"+ raise ApiUnreachableError(msg, api_url=client.base_url, code="ABORT_TIMEOUT") from exc+ code = type(exc).__name__+ msg = f"Could not reach Pipelex API at {client.base_url} ({code})"+ raise ApiUnreachableError(msg, api_url=client.base_url, code=code) from exc+ except httpx.TransportError as exc:+ msg = f"The connection to the hosted API at {client.base_url} failed after the run request was sent ({type(exc).__name__}: {exc})"+ raise HostedRunOutcomeUnknownError(msg) from exc+++async def _follow(*, client: PipelexAPIClient, run_id: str) -> RunResults:+ """Poll a started run to its result.++ A failure that names the run already (a run that failed, one past the wait, one that delivered no main output) is+ raised as it is. Any other one met after the start was acknowledged, the network, the hosted API or an answer that+ does not parse, is raised as a `HostedRunPollingError` naming the run, which may still be going.+ """+ try:+ return await client.wait_for_result(run_id)+ except (RunFailedError, RunTimeoutError, MissingMainStuffError):+ raise+ except (PipelineRequestError, httpx.HTTPError, ValueError) as exc:+ # `ValueError` covers an answer that is not what the results route promises: a body that is not JSON+ # (`json.JSONDecodeError`) or one that drifted from the SDK's model (pydantic's `ValidationError`).+ msg = f"The run {run_id} started on the hosted API, but following it to its result failed: {exc}"+ raise HostedRunPollingError(msg, pipeline_run_id=run_id) from exc+++async def run_hosted(*, client: PipelexAPIClient, request: HostedRunRequest, on_started: RunStartedCallback | None = None) -> HostedRunOutcome:+ """Run a method on the hosted API and wait for its result.++ Args:+ client: A started client, from `pipelex.hosted.client_factory.make_hosted_client`.+ request: The run.+ on_started: Told the run's id as soon as the hosted API acknowledges the start, before the run is followed, so+ a caller interrupted while waiting can still name the run. Not called on a server with no run store, whose+ blocking route answers with the results directly.++ Returns:+ The outcome, its `results` read the same way whatever the source: `results.main_stuff` is the main output's+ content, `results.working_memory` the whole working memory, `results.pipeline_run_id` the run's id.++ Raises:+ HostedLocalFileUploadUnavailableError: If the inputs name a local file and the method calls another one by its+ address, which the signature read cannot load.+ HostedMethodInvalidError: If the hosted API reads the method's signature and the method does not load.+ ApiResponseError: If the hosted API refuses the request: a key it does not accept, a method it cannot load+ (its `validation_errors` locate the fault), an input it rejects.+ RunFailedError: If the run started and ended in a status other than completed.+ RunTimeoutError: If the run outlived the wait; it keeps running, and its id resumes it.+ MissingMainStuffError: If the run completed and delivered no main output.+ HostedRunPollingError: If following a started run failed any other way; it names the run.+ HostedRunOutcomeUnknownError: If the connection failed after the run request was sent, so a run may exist.+ ApiUnreachableError: If the hosted API cannot be reached before the run request is sent.+ InputPreparationError: If a local file cannot be read or uploaded.+ """+ prepared = await prepare_hosted_inputs(+ client=client,+ mthds_files=request.mthds_files,+ method_ref=request.method_ref,+ method_id=request.method_id,+ pipe_code=request.pipe_code,+ inputs=request.inputs,+ inputs_base_dir=request.inputs_base_dir,+ )+ run_id_or_results = await _start_or_execute(client=client, request=request, inputs=prepared.inputs)++ if isinstance(run_id_or_results, RunResults):+ results = run_id_or_results+ else:+ if on_started is not None:+ on_started(pipeline_run_id=run_id_or_results)+ results = await _follow(client=client, run_id=run_id_or_results)+ return HostedRunOutcome(results=results, uploads=prepared.uploads, pipe_ref=prepared.pipe_ref)diff --git a/pipelex/hosted/run_config.py b/pipelex/hosted/run_config.pynew file mode 100644index 000000000..3a80ac2f3--- /dev/null+++ b/pipelex/hosted/run_config.py@@ -0,0 +1,42 @@+"""Where a run executes, and the `[run]` configuration section that sets the default."""++from enum import StrEnum++from pydantic import Field++from pipelex.system.configuration.config_model import ConfigModel+++class RunExecution(StrEnum):+ """Where a method runs: on this machine with your own inference, or on the hosted Pipelex API."""++ LOCAL = "local"+ HOSTED = "hosted"++ @property+ def is_hosted(self) -> bool:+ match self:+ case RunExecution.LOCAL:+ return False+ case RunExecution.HOSTED:+ return True++ @classmethod+ def from_hosted_flag(cls, *, hosted: bool | None) -> "RunExecution | None":+ """The execution a `--hosted/--local` flag pair requests: `None` when neither was given."""+ if hosted is None:+ return None+ if hosted:+ return RunExecution.HOSTED+ return RunExecution.LOCAL+++class RunConfig(ConfigModel):+ """The run commands' defaults.++ ``execution`` is where a run executes when the command names neither ``--hosted`` nor ``--local``:+ ``local`` runs on this machine with the backends in ``.pipelex/inference/``, ``hosted`` runs on the+ hosted Pipelex API with the key in ``PIPELEX_API_KEY``.+ """++ execution: RunExecution = Field(strict=False)diff --git a/pipelex/kit/configs/pipelex.toml b/pipelex/kit/configs/pipelex.tomlindex 5524343c1..60ff964f1 100644--- a/pipelex/kit/configs/pipelex.toml+++ b/pipelex/kit/configs/pipelex.toml@@ -10,7 +10,8 @@# - All values below are set to their defaults - modify them as needed# - The values here will override the defaults from the Pipelex package#-# The three top-level sections mirror the layers of the runtime:+# The [run] section says where your runs execute. The three other top-level sections mirror the+# layers of the runtime:# - [runtime] process-scoped infrastructure: storage, secrets, logging, tracing, plugins# - [inference] the model-calling seam: model deck, LLM, image generation, extraction# - [interpreter] library-scoped method machinery: parsing, pipe runs, pipeline execution@@ -32,6 +33,16 @@#####################################################################################################+####################################################################################################+# Run Config+####################################################################################################++[run]+# Where `pipelex run` and `pipelex-agent run` execute a method when the command passes neither+# --hosted nor --local: "local" runs on this machine, on the backends in .pipelex/inference/ (your own+# provider keys); "hosted" runs on the hosted Pipelex API, with the key in PIPELEX_API_KEY.+execution = "local"+##################################################################################################### Storage Config####################################################################################################diff --git a/pipelex/migration/goldens/pipelex-config/[email protected] b/pipelex/migration/goldens/pipelex-config/[email protected]index cb3431d9d..753da7e4c 100644--- a/pipelex/migration/goldens/pipelex-config/[email protected]+++ b/pipelex/migration/goldens/pipelex-config/[email protected]@@ -474,6 +474,17 @@ default_output_dir = "."default_bundle_file_name = "bundle"default_directory_base_name = "pipeline"+####################################################################################################+# Run — where `pipelex run` and `pipelex-agent run` execute a method+####################################################################################################++[run]+# Where a run executes when the command passes neither --hosted nor --local:+# - "local" runs on this machine, on the backends configured in .pipelex/inference/ (your own provider keys)+# - "hosted" runs on the hosted Pipelex API, with the key in PIPELEX_API_KEY (the environment or ~/.pipelex/.env),+# at the origin in PIPELEX_BASE_URL (https://api.pipelex.com when unset)+execution = "local"+##################################################################################################### Kit Config####################################################################################################diff --git a/pipelex/migration/goldens/pipelex-config/[email protected] b/pipelex/migration/goldens/pipelex-config/[email protected]index fb7c00c17..01897aad6 100644--- a/pipelex/migration/goldens/pipelex-config/[email protected]+++ b/pipelex/migration/goldens/pipelex-config/[email protected]@@ -956,6 +956,21 @@],"open_node": false},+ "run": {+ "value_type": "table",+ "required": true,+ "open_node": false+ },+ "run.execution": {+ "value_type": "enum",+ "required": true,+ "enum_members": [+ "hosted",+ "local"+ ],+ "default": "local",+ "open_node": false+ },"runtime": {"value_type": "table","required": true,diff --git a/pipelex/pipelex.toml b/pipelex/pipelex.tomlindex cb3431d9d..753da7e4c 100644--- a/pipelex/pipelex.toml+++ b/pipelex/pipelex.toml@@ -474,6 +474,17 @@ default_output_dir = "."default_bundle_file_name = "bundle"default_directory_base_name = "pipeline"+####################################################################################################+# Run — where `pipelex run` and `pipelex-agent run` execute a method+####################################################################################################++[run]+# Where a run executes when the command passes neither --hosted nor --local:+# - "local" runs on this machine, on the backends configured in .pipelex/inference/ (your own provider keys)+# - "hosted" runs on the hosted Pipelex API, with the key in PIPELEX_API_KEY (the environment or ~/.pipelex/.env),+# at the origin in PIPELEX_BASE_URL (https://api.pipelex.com when unset)+execution = "local"+##################################################################################################### Kit Config####################################################################################################diff --git a/pipelex/system/configuration/configs.py b/pipelex/system/configuration/configs.pyindex 3cb65cf9c..175439106 100644--- a/pipelex/system/configuration/configs.py+++ b/pipelex/system/configuration/configs.py@@ -5,6 +5,7 @@ from pydantic import Field, field_validator, model_validatorfrom pipelex.cogt.config_cogt import InferenceConfigfrom pipelex.graph.graph_config import GraphConfig+from pipelex.hosted.run_config import RunConfigfrom pipelex.language.mthds_config import MthdsConfigfrom pipelex.methods.methods_config import MethodsConfigfrom pipelex.system.configuration.config_model import ConfigModel@@ -214,4 +215,5 @@ class PipelexConfig(ConfigRoot):runtime: RuntimeConfiginference: InferenceConfiginterpreter: InterpreterConfig+ run: RunConfigkit: KitConfigdiff --git a/pyproject.toml b/pyproject.tomlindex 15427d552..e329b8d1a 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -40,6 +40,10 @@ dependencies = ["opentelemetry-sdk>=1.39.0", # 1.39+ exports InMemoryLogRecordExporter, which the otlp sink's tests use"pillow>=12.1.1","pipelex-tools-py>=0.1.3",+ # The client for the hosted Pipelex API, behind hosted runs (pipelex/hosted/). Pinned exactly, like+ # mthds: each pipelex-sdk release pins mthds exactly too, so the release chosen here must pin the+ # same mthds as this file, and the two pins move together (the bump-mthds skill says so).+ "pipelex-sdk==0.31.0","polyfactory>=2.21.0","portkey-ai>=2.1.0","posthog>=6.7.0",@@ -48,7 +52,7 @@ dependencies = ["pydantic>=2.10.6,<3.0.0","python-dotenv>=1.2.2","PyYAML>=6.0.2",- "reportlab>=4.0,<5", # the built-in PDF engine of PipeDocGen, and synthetic PDFs in tests+ "reportlab>=4.0,<5", # the built-in PDF engine of PipeDocGen, and synthetic PDFs in tests"requests>=2.33.0","semantic-version>=2.10.0","shortuuid>=1.0.13",diff --git a/subject_grants.toml b/subject_grants.tomlindex 0d604e9d5..497316312 100644--- a/subject_grants.toml+++ b/subject_grants.toml@@ -160,10 +160,6 @@ rationale = "Renders the result; single operand."param = "pipe_code"rationale = "Runs the pipe identified by pipe_code; single operand."-["pipelex/cli/agent_cli/commands/run/_run_core_api.py::run_pipeline_core_api"]-param = "pipe_code"-rationale = "Runs the pipe identified by pipe_code via the API; single operand."-["pipelex/cli/agent_cli/commands/run/stdin_resolver.py::_extract_stuff_entry"]param = "stuff_data"rationale = "Extracts from the stuff_data; single operand."@@ -296,6 +292,10 @@ rationale = "Derives from the remaining_backends; single operand."param = "backend_keys"rationale = "Derives from the backend_keys; single operand."+["pipelex/cli/commands/run/_hosted_sources.py::looks_like_method_id"]+param = "target"+rationale = "Tests the target string; single operand, as looks_like_method_ref does."+["pipelex/cli/commands/run/_inputs_file_loader.py::_convert_temporal_inputs"]param = "inputs_dict"rationale = "Single-operand conversion of the inputs dict."diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txtindex fd320523d..248e01489 100644--- a/tests/data/errors/error_identity.txt+++ b/tests/data/errors/error_identity.txt@@ -110,6 +110,14 @@ GoogleImgGenWorkerError | Google img gen worker | https://docs.pipelex.com/latesGoogleLLMWorkerError | Google LLM worker | https://docs.pipelex.com/latest/errors/google-llm-worker-error/GraphSpecError | Graph spec | https://docs.pipelex.com/latest/errors/graph-spec-error/GraphSpecValidationError | Graph spec validation | https://docs.pipelex.com/latest/errors/graph-spec-validation-error/+HostedBaseUrlError | Hosted base url | https://docs.pipelex.com/latest/errors/hosted-base-url-error/+HostedLocalFileUploadUnavailableError | Hosted local file upload unavailable | https://docs.pipelex.com/latest/errors/hosted-local-file-upload-unavailable-error/+HostedMethodInvalidError | Hosted method invalid | https://docs.pipelex.com/latest/errors/hosted-method-invalid-error/+HostedRunError | Hosted run error | https://docs.pipelex.com/latest/errors/hosted-run-error/+HostedRunInterruptedError | Hosted run interrupted | https://docs.pipelex.com/latest/errors/hosted-run-interrupted-error/+HostedRunOutcomeUnknownError | Hosted run outcome unknown | https://docs.pipelex.com/latest/errors/hosted-run-outcome-unknown-error/+HostedRunPollingError | Hosted run polling | https://docs.pipelex.com/latest/errors/hosted-run-polling-error/+HostedRunSourceError | Hosted run source | https://docs.pipelex.com/latest/errors/hosted-run-source-error/HubSlotAlreadyClaimedError | Hub slot already claimed | https://docs.pipelex.com/latest/errors/hub-slot-already-claimed-error/ImageContentError | Image content | https://docs.pipelex.com/latest/errors/image-content-error/ImgGenGeneratedTypeError | Img gen generated type | https://docs.pipelex.com/latest/errors/img-gen-generated-type-error/diff --git a/tests/e2e/pipelex/cli/test_hosted_run_cli.py b/tests/e2e/pipelex/cli/test_hosted_run_cli.pynew file mode 100644index 000000000..bbc05fc34--- /dev/null+++ b/tests/e2e/pipelex/cli/test_hosted_run_cli.py@@ -0,0 +1,255 @@+"""E2E: both CLIs run a published method on the hosted Pipelex API, by flag and by configured default.++Every case spawns the real `pipelex` or `pipelex-agent` binary against a live hosted API, so a run spends+hosted credits. That is why the `pipelex_api` marker keeps the module out of `make agent-test` and of the+default pytest selection, and why it is skipped when `PIPELEX_API_KEY` is unset. To run it against the dev+plane, export the key and the origin, then select the marker:++ export PIPELEX_API_KEY=<a dev-plane key>+ export PIPELEX_BASE_URL=https://api-dev.pipelex.com+ .venv/bin/pytest -m pipelex_api tests/e2e/pipelex/cli/test_hosted_run_cli.py++Without `PIPELEX_BASE_URL` the runs go to `https://api.pipelex.com`. The methods are the public+`github.com/Pipelex/methods` packages at a pinned tag, which the hosted API fetches itself.++Each test runs in its own `HOME` and `PIPELEX_HOME` (the hermetic-home fixture copies the kit's configuration+there), so nothing is read from or written to the developer's `~/.pipelex`. The subprocess environment is+built from nothing: it carries the Pipelex API key and base URL and no provider key, which is the point of a+hosted run.+"""++from __future__ import annotations++import json+import os+import shutil+import subprocess # ruff: ignore[suspicious-subprocess-import] — invokes the real pipelex binaries for E2E coverage+from pathlib import Path++import pytest++from pipelex.hosted.client_factory import HOSTED_API_DEFAULT_BASE_URL, PIPELEX_API_KEY_ENV_KEY, PIPELEX_BASE_URL_ENV_KEY++REPO_ROOT = Path(__file__).resolve().parents[4]+PIPELEX_BIN = REPO_ROOT / ".venv" / "bin" / "pipelex"+PIPELEX_AGENT_BIN = REPO_ROOT / ".venv" / "bin" / "pipelex-agent"+SAMPLE_PDF = REPO_ROOT / "tests" / "data" / "documents" / "John-Doe-CV.pdf"++TEXT_STATS_REF = "github.com/Pipelex/methods/[email protected]"+DOCUMENTS_REF = "github.com/Pipelex/methods/[email protected]"+TEXT_INPUTS = '{"text": "Hello world. A second sentence follows."}'+#: An origin nothing listens on: a run that reached it would fail, so a run that succeeds went elsewhere.+UNREACHABLE_BASE_URL = "http://127.0.0.1:9"+#: Hosted runs poll until the run ends; an extraction takes a while on a cold plane.+RUN_TIMEOUT_SECONDS = 600.0++LOCAL_BUNDLE = """domain = "hosted_e2e"+main_pipe = "shout"++[pipe.shout]+type = "PipeLLM"+description = "Repeat a text in capitals"+inputs = { text = "Text" }+output = "Text"+prompt = "Repeat $text in capitals."+"""++pytestmark = [+ pytest.mark.pipelex_api,+ pytest.mark.skipif(not os.environ.get(PIPELEX_API_KEY_ENV_KEY), reason=f"{PIPELEX_API_KEY_ENV_KEY} is not set"),+]+++def _expected_base_url() -> str:+ return os.environ.get(PIPELEX_BASE_URL_ENV_KEY) or HOSTED_API_DEFAULT_BASE_URL+++def _hosted_env(*, home: Path, base_url: str | None) -> dict[str, str]:+ """A subprocess environment holding the Pipelex API key and no provider key."""+ env = {+ "HOME": str(home),+ "PIPELEX_HOME": str(home / ".pipelex"),+ "PATH": "/usr/bin:/bin:/usr/local/bin",+ # Wide enough that Rich never wraps the lines the tests read.+ "COLUMNS": "250",+ PIPELEX_API_KEY_ENV_KEY: os.environ[PIPELEX_API_KEY_ENV_KEY],+ }+ if base_url is not None:+ env[PIPELEX_BASE_URL_ENV_KEY] = base_url+ return env+++def _run(*, binary: Path, args: list[str], env: dict[str, str], cwd: Path) -> subprocess.CompletedProcess[str]:+ return subprocess.run( # ruff: ignore[subprocess-without-shell-equals-true]+ [str(binary), *args],+ env=env,+ cwd=str(cwd),+ stdin=subprocess.DEVNULL,+ capture_output=True,+ text=True,+ check=False,+ timeout=RUN_TIMEOUT_SECONDS,+ )+++def _set_run_execution(*, home: Path, execution: str) -> None:+ """Set `[run] execution` in the hermetic home's `pipelex.toml`, which the kit ships as `"local"`."""+ config_path = home / ".pipelex" / "pipelex.toml"+ original = config_path.read_text(encoding="utf-8")+ assert '\nexecution = "local"\n' in original, 'the kit\'s pipelex.toml no longer sets [run] execution = "local"'+ config_path.write_text(original.replace('\nexecution = "local"\n', f'\nexecution = "{execution}"\n'), encoding="utf-8")+++def _single_output_dir(*, output_root: Path) -> Path:+ found = sorted(output_root.glob("*_output_*"))+ assert len(found) == 1, f"expected one run directory under {output_root}, found {found}"+ return found[0]+++def _console(result: subprocess.CompletedProcess[str]) -> str:+ """What the human CLI printed: its final output goes to stdout, its banner, progress and recap to stderr."""+ return result.stdout + result.stderr+++def _report(result: subprocess.CompletedProcess[str]) -> str:+ return f"exit {result.returncode}\n--- stdout ---\n{result.stdout}\n--- stderr ---\n{result.stderr}"+++class TestHostedRunCli:+ def test_run_method_hosted_flag(self, hermetic_home: Path) -> None:+ """`pipelex run method <address> --hosted` runs on the hosted API and saves its outputs locally."""+ output_root = hermetic_home / "out"++ result = _run(+ binary=PIPELEX_BIN,+ args=["run", "method", TEXT_STATS_REF, "--hosted", "--inputs", TEXT_INPUTS, "-o", str(output_root)],+ env=_hosted_env(home=hermetic_home, base_url=os.environ.get(PIPELEX_BASE_URL_ENV_KEY)),+ cwd=hermetic_home,+ )++ assert result.returncode == 0, _report(result)+ assert f"Running on the hosted Pipelex API at {_expected_base_url()}" in _console(result)+ assert "Hosted run completed successfully" in _console(result)+ assert "Run id: run_" in _console(result)+ run_dir = _single_output_dir(output_root=output_root)+ assert run_dir.name == "text_stats_output_01"+ main_stuff = json.loads((run_dir / "main_stuff.json").read_text(encoding="utf-8"))+ assert "Sentences" in main_stuff["text"]+ assert (run_dir / "main_stuff.md").is_file()+ assert (run_dir / "working_memory.json").is_file()+ assert (run_dir / "graphspec.json").is_file()++ def test_configured_hosted_default_runs_without_a_flag(self, hermetic_home: Path) -> None:+ """`[run] execution = "hosted"` sends a run with no flag to the hosted API."""+ _set_run_execution(home=hermetic_home, execution="hosted")+ output_root = hermetic_home / "out"++ result = _run(+ binary=PIPELEX_BIN,+ args=["run", "method", TEXT_STATS_REF, "--inputs", TEXT_INPUTS, "-o", str(output_root)],+ env=_hosted_env(home=hermetic_home, base_url=os.environ.get(PIPELEX_BASE_URL_ENV_KEY)),+ cwd=hermetic_home,+ )++ assert result.returncode == 0, _report(result)+ assert f"Running on the hosted Pipelex API at {_expected_base_url()}" in _console(result)+ assert (_single_output_dir(output_root=output_root) / "main_stuff.json").is_file()++ def test_agent_run_method_runner_hosted(self, hermetic_home: Path) -> None:+ """`pipelex-agent run method <address> --runner hosted` answers the main output as JSON on stdout."""+ result = _run(+ binary=PIPELEX_AGENT_BIN,+ args=["run", "method", TEXT_STATS_REF, "--runner", "hosted", "--inputs", TEXT_INPUTS, "--format", "json"],+ env=_hosted_env(home=hermetic_home, base_url=os.environ.get(PIPELEX_BASE_URL_ENV_KEY)),+ cwd=hermetic_home,+ )++ assert result.returncode == 0, _report(result)+ main_stuff = json.loads(result.stdout)+ assert "Sentences" in main_stuff["text"]++ def test_base_url_flag_wins_over_the_environment(self, hermetic_home: Path) -> None:+ """`--base-url` wins over `PIPELEX_BASE_URL`, which here names an origin nothing listens on."""+ output_root = hermetic_home / "out"++ result = _run(+ binary=PIPELEX_BIN,+ args=[+ "run",+ "method",+ TEXT_STATS_REF,+ "--hosted",+ "--base-url",+ _expected_base_url(),+ "--inputs",+ TEXT_INPUTS,+ "-o",+ str(output_root),+ ],+ env=_hosted_env(home=hermetic_home, base_url=UNREACHABLE_BASE_URL),+ cwd=hermetic_home,+ )++ assert result.returncode == 0, _report(result)+ assert f"Running on the hosted Pipelex API at {_expected_base_url()}" in _console(result)+ assert UNREACHABLE_BASE_URL not in _console(result)++ def test_a_local_input_file_is_uploaded(self, hermetic_home: Path) -> None:+ """A relative path at a Document input, written in an inputs file, is uploaded and run as a storage URI."""+ inputs_dir = hermetic_home / "inputs"+ inputs_dir.mkdir()+ shutil.copy2(SAMPLE_PDF, inputs_dir / "cv.pdf")+ (inputs_dir / "inputs.json").write_text('{"document": "cv.pdf"}', encoding="utf-8")+ output_root = hermetic_home / "out"++ result = _run(+ binary=PIPELEX_BIN,+ args=[+ "run",+ "method",+ DOCUMENTS_REF,+ "--pipe",+ "extract_document_text",+ "--hosted",+ "--inputs",+ "inputs/inputs.json",+ "-o",+ str(output_root),+ ],+ env=_hosted_env(home=hermetic_home, base_url=os.environ.get(PIPELEX_BASE_URL_ENV_KEY)),+ cwd=hermetic_home,+ )++ assert result.returncode == 0, _report(result)+ assert "Uploaded 1 local file(s) for the run" in _console(result)+ run_dir = _single_output_dir(output_root=output_root)+ assert "pipelex-storage://" in (run_dir / "working_memory.json").read_text(encoding="utf-8")+ main_stuff = json.loads((run_dir / "main_stuff.json").read_text(encoding="utf-8"))+ assert "JOHN DOE" in main_stuff["text"].upper()++ def test_local_flag_overrides_a_hosted_default(self, hermetic_home: Path) -> None:+ """`--local` runs on this machine even when `[run] execution` is `"hosted"`.++ A live local run needs provider keys, which this module deliberately withholds, so the observable is a+ dry run instead: it needs no key, and it is a flag a hosted run refuses. The same command without+ `--local` is refused for asking a hosted run to dry-run, which proves the hosted default is in force and+ sends nothing; with `--local` it completes, which proves the run executed here.+ """+ _set_run_execution(home=hermetic_home, execution="hosted")+ bundle_path = hermetic_home / "bundle.mthds"+ bundle_path.write_text(LOCAL_BUNDLE, encoding="utf-8")+ output_root = hermetic_home / "out"+ dry_run_args = ["run", "bundle", str(bundle_path), "--dry-run", "--mock-inputs", "--no-graph", "-o", str(output_root)]+ env = _hosted_env(home=hermetic_home, base_url=os.environ.get(PIPELEX_BASE_URL_ENV_KEY))++ refused = _run(binary=PIPELEX_BIN, args=dry_run_args, env=env, cwd=hermetic_home)++ assert refused.returncode == 1, _report(refused)+ assert "only apply to a run on this machine" in _console(refused)++ local = _run(binary=PIPELEX_BIN, args=[*dry_run_args, "--local"], env=env, cwd=hermetic_home)++ assert local.returncode == 0, _report(local)+ assert "Dry run completed successfully" in _console(local)+ assert "Running on the hosted Pipelex API" not in _console(local)+ assert (_single_output_dir(output_root=output_root) / "working_memory.json").is_file()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 21b4341d6..d9fa0812f 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@@ -19,14 +19,12 @@ from typing import TYPE_CHECKINGimport pytestimport typer-from mthds.runners.types import RunnerTypefrom pipelex.cli.agent_cli.commands.agent_output import CliOutputFormatfrom pipelex.cli.agent_cli.commands.run.pipe_cmd import run_pipe_cmdfrom pipelex.cli.agent_cli.commands.run.stdin_resolver import ParsedCliInputsfrom pipelex.cogt.content_generation.content_generator import ContentGeneratorfrom pipelex.cogt.exceptions import InferenceErrorCategory, LLMCompletionError-from pipelex.tools.log.log_levels import LogLevelif TYPE_CHECKING:from pytest_mock import MockerFixture@@ -57,12 +55,8 @@ class TestRunErrorChain:transient_error.backend_name = WORKER_PROVIDERmocker.patch.object(ContentGenerator, "make_llm_text", side_effect=transient_error)- ctx = mocker.MagicMock()- ctx.obj = {"log_level": LogLevel.WARNING, "runner": RunnerType.PIPELEX}-with pytest.raises(typer.Exit) as exit_info:run_pipe_cmd(- ctx=ctx,pipe_code="greet",graph=False,library_dir=[str(ERROR_CHAIN_LIBRARY_DIR)],diff --git a/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.py b/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.pyindex ec3e8b458..c8e460889 100644--- a/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.py+++ b/tests/integration/pipelex/cli/test_run_bundle_verdict_cli.py@@ -15,12 +15,10 @@ from __future__ import annotationsimport asyncioimport json-from types import SimpleNamespace-from typing import TYPE_CHECKING, Any, cast+from typing import TYPE_CHECKING, Anyimport pytestimport typer-from mthds.runners.types import RunnerTypefrom rich.console import Consolefrom pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_format@@ -91,10 +89,8 @@ def _run_bundle(*, bundle_path: Path, library_dir: list[str] | None) -> None:def _run_agent_bundle(*, bundle_path: Path, output_format: CliOutputFormat) -> None:- context = cast("typer.Context", SimpleNamespace(obj={"runner": RunnerType.PIPELEX}))try:agent_run_bundle_cmd(- ctx=context,path=str(bundle_path.parent),pipe=None,inputs=None,diff --git a/tests/integration/pipelex/pipeline/test_resolve_bundle.py b/tests/integration/pipelex/pipeline/test_resolve_bundle.pyindex 86660073c..ceff01687 100644--- a/tests/integration/pipelex/pipeline/test_resolve_bundle.py+++ b/tests/integration/pipelex/pipeline/test_resolve_bundle.py@@ -13,6 +13,7 @@ from mthds.package.manifest.schema import MTHDS_STANDARD_VERSIONfrom pytest_mock import MockerFixturefrom pipelex.base_exceptions import PipelexUnexpectedError+from pipelex.hosted.hosted_inputs import ADDRESS_DEPENDENCY_REFUSAL_MARKERfrom pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_managerfrom pipelex.pipeline.exceptions import ValidateBundleErrorfrom pipelex.pipeline.resolve_bundle import resolve_crate_from_contents@@ -143,7 +144,10 @@ class TestResolveCrateFromContents:side_effect=AssertionError("in-memory resolve must not discover installed methods or fetch by address"),)- with pytest.raises(ValidateBundleError, match="address-based dependency"):+ with pytest.raises(ValidateBundleError, match=ADDRESS_DEPENDENCY_REFUSAL_MARKER) as exc_info:resolve_crate_from_contents(mthds_contents=[ADDRESS_DEPENDENCY_MTHDS], mthds_sources=["host.mthds"])discovery.assert_not_called()+ # The items `/v1/pipe-io` sends in its invalid verdict carry the marker a hosted run tells this refusal apart by.+ validation_errors = exc_info.value.to_error_report().validation_errors or []+ assert any(ADDRESS_DEPENDENCY_REFUSAL_MARKER in item.message for item in validation_errors)diff --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 c1f1a1786..d538b4892 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@@ -42,7 +42,7 @@ class TestAgentMethodRefErrors:self._mock_failing_clone(mocker, tmp_path)with pytest.raises(typer.Exit) as exc_info:- run_method_cmd(ctx=mocker.MagicMock(), name=BROKEN_REF, error_format=CliOutputFormat.JSON)+ run_method_cmd(name=BROKEN_REF, error_format=CliOutputFormat.JSON)assert exc_info.value.exit_code == 1error_obj = _parse_single_json_error(capsys.readouterr().err)diff --git a/tests/unit/pipelex/cli/agent_cli/test_agent_run_method_output_location.py b/tests/unit/pipelex/cli/agent_cli/test_agent_run_method_output_location.pyindex 0314e0b4a..569a431b5 100644--- a/tests/unit/pipelex/cli/agent_cli/test_agent_run_method_output_location.py+++ b/tests/unit/pipelex/cli/agent_cli/test_agent_run_method_output_location.py@@ -7,7 +7,6 @@ from pathlib import Pathfrom typing import TYPE_CHECKING, Anyimport pytest-from mthds.runners.types import RunnerTypefrom pipelex.cli.agent_cli.commands.agent_output import CliOutputFormatfrom pipelex.cli.agent_cli.commands.run.method_cmd import run_method_cmd@@ -42,18 +41,13 @@ class TestAgentRunMethodOutputLocation:mocker.patch(f"{RUN_METHOD_MODULE}.Pipelex.teardown_if_needed")return mocker.patch(f"{RUN_METHOD_MODULE}.run_pipeline_core", new=mocker.AsyncMock(return_value={"answer": "42"}))- def _make_ctx(self, mocker: MockerFixture) -> Any:- ctx = mocker.MagicMock()- ctx.obj = {"runner": RunnerType.PIPELEX}- return ctx-@pytest.mark.usefixtures("tty_stdin")def test_fetched_method_overrides_output_dir_to_cwd(self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:"""A fetched method (provenance set) re-anchors run outputs under the caller's CWD, not the clone."""clone_dir = tmp_path / "mthds_remote_clone"run_core_mock = self._patch_method_run(mocker, method_dir=clone_dir, fetched=True)- run_method_cmd(ctx=self._make_ctx(mocker), name="github.com/test/remote-method", output_format=CliOutputFormat.JSON)+ run_method_cmd(name="github.com/test/remote-method", output_format=CliOutputFormat.JSON)capsys.readouterr()override = run_core_mock.call_args.kwargs["output_dir_override"]@@ -65,7 +59,7 @@ class TestAgentRunMethodOutputLocation:"""An installed method (no provenance) keeps the bundle-adjacent default: no override is passed."""run_core_mock = self._patch_method_run(mocker, method_dir=tmp_path, fetched=False)- run_method_cmd(ctx=self._make_ctx(mocker), name="my-method", output_format=CliOutputFormat.JSON)+ run_method_cmd(name="my-method", output_format=CliOutputFormat.JSON)capsys.readouterr()assert run_core_mock.call_args.kwargs["output_dir_override"] is Nonediff --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 93a1f595f..f426555f7 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@@ -5,7 +5,6 @@ from typing import TYPE_CHECKING, Anyimport pytestimport typer-from mthds.runners.types import RunnerTypefrom pipelex.cli.agent_cli.commands.agent_output import CliOutputFormatfrom pipelex.cli.agent_cli.commands.run.pipe_cmd import run_pipe_cmd@@ -18,22 +17,13 @@ RUN_PIPE_MODULE = "pipelex.cli.agent_cli.commands.run.pipe_cmd"class TestErrorFormatIndependent:- def _patch_success(self, mocker: MockerFixture, result: dict[str, Any]) -> Any:+ def _patch_success(self, mocker: MockerFixture, result: dict[str, Any]) -> None:"""Patch the run pipe command's dependencies for the success path."""mocker.patch(f"{RUN_PIPE_MODULE}.make_pipelex_for_agent_cli")mocker.patch(f"{RUN_PIPE_MODULE}.Pipelex.teardown_if_needed")mocker.patch(f"{RUN_PIPE_MODULE}.resolve_pipe_from_exports", return_value=[])mocker.patch(f"{RUN_PIPE_MODULE}.parse_cli_inputs", return_value=ParsedCliInputs(pipeline_inputs=None, inputs_base_dir=None))mocker.patch(f"{RUN_PIPE_MODULE}.run_pipeline_core", new=mocker.AsyncMock(return_value=result))- ctx = mocker.MagicMock()- ctx.obj = {"runner": RunnerType.PIPELEX}- return ctx-- def _ctx_for_error_path(self, mocker: MockerFixture) -> Any:- """Mock typer.Context shaped for the error path (no Pipelex init needed)."""- ctx = mocker.MagicMock()- ctx.obj = {"runner": RunnerType.PIPELEX}- return ctx@pytest.mark.parametrize(("output_format", "error_format", "expected_success_is_markdown"),@@ -57,9 +47,9 @@ class TestErrorFormatIndependent:expected_success_is_markdown: bool,) -> None:"""Success output follows --format regardless of --error-format."""- ctx = self._patch_success(mocker, {"answer": "42"})+ self._patch_success(mocker, {"answer": "42"})- run_pipe_cmd(ctx=ctx, pipe_code="my_pipe", output_format=output_format, error_format=error_format)+ run_pipe_cmd(pipe_code="my_pipe", output_format=output_format, error_format=error_format)out = capsys.readouterr().outif expected_success_is_markdown:@@ -84,18 +74,15 @@ class TestErrorFormatIndependent:)def test_error_path_follows_error_format(self,- mocker: MockerFixture,capsys: pytest.CaptureFixture[str],output_format: CliOutputFormat,error_format: CliOutputFormat | None,expected_error_is_markdown: bool,) -> None:"""Error output follows --error-format (or --format when --error-format is omitted)."""- ctx = self._ctx_for_error_path(mocker)-# Passing a pipe_code that ends in .mthds triggers the ArgumentError branch in run_pipe_cmd.with pytest.raises(typer.Exit):- run_pipe_cmd(ctx=ctx, pipe_code="my_pipe.mthds", output_format=output_format, error_format=error_format)+ run_pipe_cmd(pipe_code="my_pipe.mthds", output_format=output_format, error_format=error_format)err = capsys.readouterr().errif expected_error_is_markdown: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 6563dfab6..17246a712 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@@ -8,7 +8,6 @@ from typing import TYPE_CHECKING, Anyimport pytestimport typer-from mthds.runners.types import RunnerTypefrom pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat, set_agent_cli_error_formatfrom pipelex.cli.agent_cli.commands.run.bundle_cmd import run_bundle_cmd@@ -41,18 +40,13 @@ class TestAgentRunBundleAutoInputs:mocker.patch(f"{RUN_BUNDLE_MODULE}.Pipelex.teardown_if_needed")return mocker.patch(f"{RUN_BUNDLE_MODULE}.run_pipeline_core", new=mocker.AsyncMock(return_value=result))- def _make_ctx(self, mocker: MockerFixture) -> Any:- ctx = mocker.MagicMock()- ctx.obj = {"runner": RunnerType.PIPELEX}- return ctx-@pytest.mark.usefixtures("tty_stdin")def test_auto_detects_inputs_toml(self, mocker: MockerFixture, bundle_dir: Path, capsys: pytest.CaptureFixture[str]) -> None:"""With only inputs.toml in the directory, it is auto-detected and loaded through the TOML parser."""run_core_mock = self._patch_run(mocker, {"answer": "42"})(bundle_dir / "inputs.toml").write_text('topic = "cats"\n', encoding="utf-8")- run_bundle_cmd(ctx=self._make_ctx(mocker), path=str(bundle_dir), pipe="my_pipe", output_format=CliOutputFormat.JSON)+ run_bundle_cmd(path=str(bundle_dir), pipe="my_pipe", output_format=CliOutputFormat.JSON)capsys.readouterr()assert run_core_mock.call_args.kwargs["inputs"] == {"topic": "cats"}@@ -66,7 +60,7 @@ class TestAgentRunBundleAutoInputs:(bundle_dir / "inputs.toml").write_text('topic = "cats"\n', encoding="utf-8")with pytest.raises(typer.Exit) as exc_info:- run_bundle_cmd(ctx=self._make_ctx(mocker), path=str(bundle_dir), pipe="my_pipe", output_format=CliOutputFormat.JSON)+ run_bundle_cmd(path=str(bundle_dir), pipe="my_pipe", output_format=CliOutputFormat.JSON)assert exc_info.value.exit_code == 1envelope = json.loads(capsys.readouterr().err)@@ -87,7 +81,7 @@ class TestAgentRunBundleAutoInputs:piped_stdin.isatty = lambda: False # type: ignore[assignment]monkeypatch.setattr("sys.stdin", piped_stdin)- run_bundle_cmd(ctx=self._make_ctx(mocker), path=str(bundle_dir), pipe="my_pipe", output_format=CliOutputFormat.JSON)+ run_bundle_cmd(path=str(bundle_dir), pipe="my_pipe", output_format=CliOutputFormat.JSON)capsys.readouterr()assert run_core_mock.call_args.kwargs["inputs"] == {"topic": "fromstdin"}@@ -100,7 +94,6 @@ class TestAgentRunBundleAutoInputs:(bundle_dir / "inputs.toml").write_text('topic = "toml"\n', encoding="utf-8")run_bundle_cmd(- ctx=self._make_ctx(mocker),path=str(bundle_dir),pipe="my_pipe",inputs=str(bundle_dir / "inputs.toml"),diff --git a/tests/unit/pipelex/cli/agent_cli/test_run_format.py b/tests/unit/pipelex/cli/agent_cli/test_run_format.pyindex d8cb01474..ee0412805 100644--- a/tests/unit/pipelex/cli/agent_cli/test_run_format.py+++ b/tests/unit/pipelex/cli/agent_cli/test_run_format.py@@ -6,7 +6,6 @@ import jsonfrom typing import TYPE_CHECKING, Anyimport pytest-from mthds.runners.types import RunnerTypefrom pipelex.cli.agent_cli.commands.agent_output import CliOutputFormatfrom pipelex.cli.agent_cli.commands.run.pipe_cmd import run_pipe_cmd@@ -21,22 +20,19 @@ RUN_PIPE_MODULE = "pipelex.cli.agent_cli.commands.run.pipe_cmd"class TestRunFormat:"""run pipe emits markdown by default and JSON with --format json."""- def _patch_run(self, mocker: MockerFixture, result: dict[str, Any]) -> Any:- """Patch the run pipe command's dependencies and return a mock typer context."""+ def _patch_run(self, mocker: MockerFixture, result: dict[str, Any]) -> None:+ """Patch the run pipe command's dependencies."""mocker.patch(f"{RUN_PIPE_MODULE}.make_pipelex_for_agent_cli")mocker.patch(f"{RUN_PIPE_MODULE}.Pipelex.teardown_if_needed")mocker.patch(f"{RUN_PIPE_MODULE}.resolve_pipe_from_exports", return_value=[])mocker.patch(f"{RUN_PIPE_MODULE}.parse_cli_inputs", return_value=ParsedCliInputs(pipeline_inputs=None, inputs_base_dir=None))mocker.patch(f"{RUN_PIPE_MODULE}.run_pipeline_core", new=mocker.AsyncMock(return_value=result))- ctx = mocker.MagicMock()- ctx.obj = {"runner": RunnerType.PIPELEX}- return ctxdef test_run_pipe_markdown_is_default(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:"""Run pipe with no --format produces markdown to stdout."""- ctx = self._patch_run(mocker, {"answer": "42"})+ self._patch_run(mocker, {"answer": "42"})- run_pipe_cmd(ctx=ctx, pipe_code="my_pipe", output_format=CliOutputFormat.MARKDOWN)+ run_pipe_cmd(pipe_code="my_pipe", output_format=CliOutputFormat.MARKDOWN)out = capsys.readouterr().outassert out.startswith("# Pipeline run complete")@@ -45,9 +41,9 @@ class TestRunFormat:def test_run_pipe_json_with_format_json(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:"""Run pipe --format json produces valid JSON to stdout."""- ctx = self._patch_run(mocker, {"answer": "42"})+ self._patch_run(mocker, {"answer": "42"})- run_pipe_cmd(ctx=ctx, pipe_code="my_pipe", output_format=CliOutputFormat.JSON)+ run_pipe_cmd(pipe_code="my_pipe", output_format=CliOutputFormat.JSON)parsed = json.loads(capsys.readouterr().out)assert parsed == {"answer": "42"}diff --git a/tests/unit/pipelex/cli/agent_cli/test_run_hosted_envelope.py b/tests/unit/pipelex/cli/agent_cli/test_run_hosted_envelope.pynew file mode 100644index 000000000..db0498697--- /dev/null+++ b/tests/unit/pipelex/cli/agent_cli/test_run_hosted_envelope.py@@ -0,0 +1,262 @@+"""Unit tests: `pipelex-agent run … --runner hosted` answers in the run envelope a local run answers in.++`run_hosted` is mocked at the agent CLI seam, so no request leaves.+"""++from __future__ import annotations++import asyncio+import io+import json+from typing import TYPE_CHECKING, Any++import pytest+import typer+from pipelex_sdk.error_models import RunErrorReport+from pipelex_sdk.errors import MissingMainStuffError, RunFailedError, RunTimeoutError+from pipelex_sdk.runs import RunResults, RunStatus+from pipelex_sdk.upload import UploadRecord+from pipelex_sdk.validation_models import ValidationErrorItem+from pydantic import ValidationError++from pipelex.base_exceptions import PipelexConfigError+from pipelex.cli.agent_cli.commands.agent_cli_factory import AGENT_INIT_FAILURE_HINT+from pipelex.cli.agent_cli.commands.agent_output import CliOutputFormat+from pipelex.cli.agent_cli.commands.run.bundle_cmd import run_bundle_cmd+from pipelex.cli.agent_cli.commands.run.method_cmd import run_method_cmd+from pipelex.hosted.client_factory import PIPELEX_API_KEY_ENV_KEY, PIPELEX_BASE_URL_ENV_KEY+from pipelex.hosted.exceptions import HostedMethodInvalidError, HostedRunPollingError+from pipelex.hosted.hosted_run import HostedRunOutcome, HostedRunRequest+from pipelex.hosted.run_config import RunExecution+from pipelex.system.environment import PIPELEXPATH_ENV_KEY++if TYPE_CHECKING:+ from pathlib import Path+ from unittest.mock import AsyncMock++ from pytest_mock import MockerFixture++AGENT_RUN_HOSTED_MODULE = "pipelex.cli.agent_cli.commands.run._run_hosted"+EXECUTION_MODULE = "pipelex.hosted.execution"+METHOD_REF = "github.com/Pipelex/methods/[email protected]"+STATS: dict[str, Any] = {"words": 4, "sentences": 2}+HOSTED_RESULTS: dict[str, Any] = {+ "pipeline_run_id": "run_7",+ "main_stuff": STATS,+ "working_memory": {+ "root": {"main_stuff": {"concept": "text_stats.Stats", "content": STATS, "stuff_code": "abc", "stuff_name": "main_stuff"}},+ "aliases": {},+ },+}+++class TestRunHostedEnvelope:+ @pytest.fixture(autouse=True)+ def hosted_env(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv(PIPELEX_API_KEY_ENV_KEY, "plx_sk_test_not_a_secret")+ monkeypatch.delenv(PIPELEX_BASE_URL_ENV_KEY, raising=False)+ mock_stdin = io.StringIO("")+ mock_stdin.isatty = lambda: True # type: ignore[assignment]+ monkeypatch.setattr("sys.stdin", mock_stdin)++ @pytest.fixture+ def run_hosted(self, mocker: MockerFixture) -> AsyncMock:+ upload = UploadRecord(uri="pipelex-storage://uploads/a.pdf", filename="a.pdf", content_type="application/pdf", size=3)+ outcome = HostedRunOutcome(results=RunResults.model_validate(HOSTED_RESULTS), uploads=[upload])+ mocked: AsyncMock = mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(return_value=outcome))+ return mocked++ def test_compact_json_is_the_main_output(self, run_hosted: AsyncMock, capsys: pytest.CaptureFixture[str]) -> None:+ run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, inputs='{"text": "Hello world."}', output_format=CliOutputFormat.JSON)++ assert json.loads(capsys.readouterr().out) == STATS+ assert run_hosted.await_args is not None+ request = run_hosted.await_args.kwargs["request"]+ assert request.method_ref == METHOD_REF+ assert request.inputs == {"text": "Hello world."}++ def test_with_memory_carries_the_run_id_the_memory_and_the_uploads(self, run_hosted: AsyncMock, capsys: pytest.CaptureFixture[str]) -> None:+ run_method_cmd(name=METHOD_REF, hosted=True, with_memory=True, output_format=CliOutputFormat.JSON)++ run_hosted.assert_awaited_once()+ envelope = json.loads(capsys.readouterr().out)+ assert envelope["pipeline_run_id"] == "run_7"+ assert envelope["main_stuff"]["json"] == STATS+ assert envelope["working_memory"]["root"]["main_stuff"]["concept"] == "text_stats.Stats"+ assert envelope["uploads"][0]["uri"] == "pipelex-storage://uploads/a.pdf"++ def test_markdown_renders_the_main_output(self, run_hosted: AsyncMock, capsys: pytest.CaptureFixture[str]) -> None:+ run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.MARKDOWN)++ run_hosted.assert_awaited_once()+ markdown = capsys.readouterr().out+ assert markdown.startswith("# Pipeline run complete")+ assert '"sentences": 2' in markdown++ def test_the_configured_default_runs_hosted_without_a_flag(+ self, mocker: MockerFixture, run_hosted: AsyncMock, capsys: pytest.CaptureFixture[str]+ ) -> None:+ mocker.patch(f"{EXECUTION_MODULE}.configured_run_execution", return_value=RunExecution.HOSTED)++ run_method_cmd(name=METHOD_REF, output_format=CliOutputFormat.JSON)++ run_hosted.assert_awaited_once()+ assert json.loads(capsys.readouterr().out) == STATS++ def test_a_failed_run_reports_its_stored_error(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:+ """A run that started and failed names the runner's class, its next step, its domain and the run."""+ report = RunErrorReport.model_validate(+ {+ "error_type": "LLMCompletionError",+ "message": "The provider refused the prompt",+ "error_domain": "runtime",+ "error_category": "transient",+ "retryable": True,+ "model": "claude-5.5-sonnet",+ "user_action": {"kind": "wait_and_retry", "detail": "Run it again in a minute"},+ }+ )+ failed = RunFailedError(+ "Run finished with status FAILED: The provider refused the prompt", run_id="run_9", status=RunStatus.FAILED, error=report+ )+ mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=failed))++ with pytest.raises(typer.Exit) as exc_info:+ run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)++ assert exc_info.value.exit_code == 1+ envelope = json.loads(capsys.readouterr().err)+ assert envelope["error_type"] == "LLMCompletionError"+ assert envelope["message"] == "Run finished with status FAILED: The provider refused the prompt"+ assert envelope["hint"] == "Run it again in a minute"+ assert envelope["error_domain"] == "runtime"+ assert envelope["error_category"] == "transient"+ assert envelope["retryable"] is True+ assert envelope["model"] == "claude-5.5-sonnet"+ assert envelope["pipeline_run_id"] == "run_9"+ assert envelope["run_status"] == "FAILED"++ def test_an_unexpected_failure_is_an_envelope(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:+ """A failure no hosted arm names, such as a results body that drifted, still leaves as the JSON envelope."""+ with pytest.raises(ValidationError) as drift:+ RunResults.model_validate({"main_stuff": 1})+ mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=drift.value))++ with pytest.raises(typer.Exit) as exc_info:+ run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)++ assert exc_info.value.exit_code == 1+ envelope = json.loads(capsys.readouterr().err)+ assert envelope["error"] is True+ assert envelope["error_type"] == "ValidationError"++ def test_a_hosted_verdict_that_the_failure_is_not_retryable_wins_over_the_local_table(+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]+ ) -> None:+ """The local table calls this class retryable; the hosted runner said it is not, and only it knows."""+ report = RunErrorReport.model_validate(+ {+ "error_type": "PipeOperatorModelAvailabilityError",+ "message": "no model available for the pipe",+ "error_domain": "config",+ "retryable": False,+ }+ )+ failed = RunFailedError(+ "Run finished with status FAILED: no model available for the pipe", run_id="run_f3", status=RunStatus.FAILED, error=report+ )+ mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=failed))++ with pytest.raises(typer.Exit):+ run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)++ envelope = json.loads(capsys.readouterr().err)+ assert envelope["error_type"] == "PipeOperatorModelAvailabilityError"+ assert envelope["retryable"] is False+ assert envelope["error_domain"] == "config"++ @pytest.mark.parametrize("interruption", [KeyboardInterrupt(), asyncio.CancelledError()])+ def test_an_interrupted_run_is_an_envelope_naming_the_run_and_exits_130(+ self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], interruption: BaseException+ ) -> None:+ def _started_then_interrupted(**kwargs: Any) -> HostedRunOutcome:+ kwargs["on_started"](pipeline_run_id="run_77")+ raise interruption++ mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=_started_then_interrupted))++ with pytest.raises(typer.Exit) as exc_info:+ run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)++ assert exc_info.value.exit_code == 130+ captured = capsys.readouterr()+ assert captured.out == ""+ envelope = json.loads(captured.err)+ assert envelope["error_type"] == "HostedRunInterruptedError"+ assert envelope["pipeline_run_id"] == "run_77"+ assert "keeps going on the hosted API" in envelope["message"]+ assert "run_77" in envelope["hint"]++ @pytest.mark.parametrize(+ "error",+ [+ RunTimeoutError("Run 'run_7' did not finish within 1200s", run_id="run_7", timeout_seconds=1200.0),+ MissingMainStuffError("Completed run 'run_7' returned no main stuff", run_id="run_7"),+ HostedRunPollingError("The run run_7 started on the hosted API, but following it failed", pipeline_run_id="run_7"),+ ],+ )+ def test_an_error_after_the_start_carries_the_run_id(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str], error: Exception) -> None:+ mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=error))++ with pytest.raises(typer.Exit):+ run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)++ envelope = json.loads(capsys.readouterr().err)+ assert envelope["error_type"] == type(error).__name__+ assert envelope["pipeline_run_id"] == "run_7"+ assert "run_7" in envelope["hint"]++ def test_a_method_that_does_not_load_lists_its_labelled_items(self, mocker: MockerFixture, capsys: pytest.CaptureFixture[str]) -> None:+ item = ValidationErrorItem.model_validate(+ {"category": "blueprint_validation", "message": "unknown concept Foo", "source": "lib/b.mthds", "pipe_code": "step2"}+ )+ refused = HostedMethodInvalidError("The hosted API cannot load the method: Bundle does not load", validation_errors=[item])+ mocker.patch(f"{AGENT_RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=refused))++ with pytest.raises(typer.Exit):+ run_method_cmd(name=METHOD_REF, runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)++ envelope = json.loads(capsys.readouterr().err)+ assert envelope["error_type"] == "HostedMethodInvalidError"+ assert envelope["error_domain"] == "input"+ assert envelope["validation_errors"][0]["source"] == "lib/b.mthds"+ assert envelope["validation_errors"][0]["message"] == "unknown concept Foo"++ 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"))++ 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++ def test_a_bundle_file_without_a_library_sends_pipelexpath(+ self, monkeypatch: pytest.MonkeyPatch, run_hosted: AsyncMock, tmp_path: Path, capsys: pytest.CaptureFixture[str]+ ) -> None:+ bundle_path = tmp_path / "bundle.mthds"+ bundle_path.write_text('domain = "probe"\nmain_pipe = "entry"\n', encoding="utf-8")+ shared_dir = tmp_path / "shared"+ shared_dir.mkdir()+ (shared_dir / "shared.mthds").write_text('domain = "probe_lib"\n', encoding="utf-8")+ monkeypatch.setenv(PIPELEXPATH_ENV_KEY, str(shared_dir))++ run_bundle_cmd(path=str(bundle_path), pipe="entry", runner=RunExecution.HOSTED, output_format=CliOutputFormat.JSON)++ capsys.readouterr()+ assert run_hosted.await_args is not None+ request = run_hosted.await_args.kwargs["request"]+ assert isinstance(request, HostedRunRequest)+ assert [mthds_file.source for mthds_file in request.mthds_files or []] == [str(bundle_path), str(shared_dir / "shared.mthds")]diff --git a/tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py b/tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.pysimilarity index 50%rename from tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.pyrename to tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.pyindex 36a4ccbd0..8ee07d69b 100644--- a/tests/unit/pipelex/cli/agent_cli/test_run_api_refusal.py+++ b/tests/unit/pipelex/cli/agent_cli/test_run_hosted_refusal.py@@ -1,7 +1,8 @@-"""Unit tests: `pipelex-agent --runner api run` renders a runner's refusal the way it renders a local failure.+"""Unit tests: `pipelex-agent run … --runner hosted` renders the hosted API's refusal the way it renders a local failure.-The runner's answers are the dev plane's own problem documents, replayed through the real `MthdsAPIClient`-over a mocked HTTP transport, so no test reaches the network.+The answers are the dev plane's own problem documents, replayed through the real pipelex-sdk `PipelexAPIClient` over+a mocked HTTP transport that answers the version handshake as the hosted API does and refuses the run, so no test+reaches the network."""from __future__ import annotations@@ -9,19 +10,15 @@ from __future__ import annotationsimport asyncioimport ioimport json-from typing import TYPE_CHECKING, Any+from typing import TYPE_CHECKINGimport httpximport pytestimport typer-from mthds.runners.api.client import MthdsAPIClient-from mthds.runners.api.exceptions import ApiResponseError-from mthds.runners.types import RunnerType+from pipelex_sdk.client import PipelexAPIClient+from pipelex_sdk.errors import ApiResponseErrorfrom pipelex.cli.agent_cli.commands.agent_output import (- AGENT_ERROR_HINTS,- API_REFUSAL_CALLER_HINT,- API_REFUSAL_HINTS_BY_STATUS,CliOutputFormat,agent_error_api_response,api_response_error_payload,@@ -30,66 +27,74 @@ from pipelex.cli.agent_cli.commands.agent_output import (from pipelex.cli.agent_cli.commands.run.bundle_cmd import run_bundle_cmdfrom pipelex.cli.agent_cli.commands.run.method_cmd import run_method_cmdfrom pipelex.cli.agent_cli.commands.run.pipe_cmd import run_pipe_cmd+from pipelex.hosted.client_factory import PIPELEX_API_KEY_ENV_KEY, PIPELEX_BASE_URL_ENV_KEY+from pipelex.hosted.error_rendering import (+ HOSTED_REFUSAL_CALLER_NEXT_STEP,+ HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS,+ HOSTED_SERVER_FAULT_NEXT_STEP,+)+from pipelex.hosted.run_config import RunExecutionfrom tests.unit.pipelex.cli.agent_cli.test_data import RefusalCase, RefusalCases, RefusedRunBodies+from tests.unit.pipelex.hosted.test_data import HostedVersionsif TYPE_CHECKING:from pathlib import Pathfrom pytest_mock import MockerFixture-RUNNER_URL = "https://runner.test"+HOSTED_URL = "https://hosted.test"RUN_PIPE_MODULE = "pipelex.cli.agent_cli.commands.run.pipe_cmd"-RUN_METHOD_MODULE = "pipelex.cli.agent_cli.commands.run.method_cmd"+START_ROUTE = ("POST", "/v1/start")def _answering(*, status: int, body: str, seen: list[httpx.Request], headers: dict[str, str] | None = None) -> httpx.MockTransport:- """A transport answering every request with ``status``, ``body`` and ``headers``, recording the requests it saw."""+ """A hosted API that answers its version, then refuses every other request with ``status``, ``body`` and ``headers``."""def _handler(request: httpx.Request) -> httpx.Response:seen.append(request)+ if request.method == "GET" and request.url.path == "/v1/version":+ return httpx.Response(200, content=HostedVersions.HOSTED.encode("utf-8"), headers={"content-type": "application/json"})return httpx.Response(status, content=body.encode("utf-8"), headers={"content-type": "application/problem+json", **(headers or {})})return httpx.MockTransport(_handler)-def _install_runner(mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, *, status: int, body: str) -> list[httpx.Request]:- """Point every `MthdsAPIClient` at a mocked runner answering ``status`` / ``body``; return the requests it receives."""- monkeypatch.setenv("MTHDS_API_KEY", "test-key-not-a-secret")- monkeypatch.setenv("MTHDS_BASE_URL", RUNNER_URL)+def _install_hosted_api(mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, *, status: int, body: str) -> list[httpx.Request]:+ """Point every `PipelexAPIClient` at a mocked hosted API refusing with ``status`` / ``body``; return the requests it receives."""+ monkeypatch.setenv(PIPELEX_API_KEY_ENV_KEY, "plx_sk_test_not_a_secret")+ monkeypatch.setenv(PIPELEX_BASE_URL_ENV_KEY, HOSTED_URL)seen: list[httpx.Request] = []transport = _answering(status=status, body=body, seen=seen)- def _start_client(self: MthdsAPIClient) -> MthdsAPIClient:+ def _start_client(self: PipelexAPIClient) -> PipelexAPIClient:self.client = httpx.AsyncClient(transport=transport)return self- mocker.patch.object(MthdsAPIClient, "start_client", _start_client)+ mocker.patch.object(PipelexAPIClient, "start_client", _start_client)return seendef _refusal(*, status: int, body: str, headers: dict[str, str] | None = None) -> ApiResponseError:- """The typed error the real client raises for this answer."""+ """The typed error the real client raises when the hosted API answers `POST /v1/start` this way."""- async def _execute() -> None:- client = MthdsAPIClient(api_key="test-key-not-a-secret", base_url=RUNNER_URL)+ async def _start() -> None:+ client = PipelexAPIClient(api_key="plx_sk_test_not_a_secret", base_url=HOSTED_URL)client.client = httpx.AsyncClient(transport=_answering(status=status, body=body, seen=[], headers=headers))try:- await client.execute(pipe_code="entry", mthds_contents=["# bundle"])+ await client.start(pipe_code="entry", mthds_contents=["# bundle"])finally:await client.close()with pytest.raises(ApiResponseError) as exc_info:- asyncio.run(_execute())+ asyncio.run(_start())return exc_info.value-def _api_ctx(mocker: MockerFixture) -> Any:- ctx = mocker.MagicMock()- ctx.obj = {"runner": RunnerType.API}- return ctx+def _routes(*, seen: list[httpx.Request]) -> list[tuple[str, str]]:+ return [(request.method, request.url.path) for request in seen if request.url.path != "/v1/version"]-class TestRunApiRefusal:+class TestRunHostedRefusal:@pytest.fixturedef tty_stdin(self, monkeypatch: pytest.MonkeyPatch) -> None:"""Make stdin look like a TTY so parse_cli_inputs skips the stdin fallback."""@@ -115,19 +120,22 @@ class TestRunApiRefusal:case: RefusalCase,) -> None:"""The JSON envelope of each dev-plane refusal names its class, its located reason, its next step and its domain."""- seen = _install_runner(mocker, monkeypatch, status=422, body=case.body)+ seen = _install_hosted_api(mocker, monkeypatch, status=422, body=case.body)with pytest.raises(typer.Exit) as exc_info:- run_bundle_cmd(ctx=_api_ctx(mocker), path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON)+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)assert exc_info.value.exit_code == 1- assert [(request.method, request.url.path) for request in seen] == [("POST", "/v1/execute")]+ assert _routes(seen=seen) == [START_ROUTE]+ start_body = json.loads(seen[-1].content)+ assert start_body["pipe_code"] == "entry"+ assert start_body["mthds_contents"] == ["# bundle\n"]captured = capsys.readouterr()assert not captured.outenvelope = json.loads(captured.err)assert envelope["error"] is Trueassert envelope["error_type"] == case.error_type- assert envelope["message"] == f"API POST /v1/execute failed (422): {case.reason}"+ assert envelope["message"] == f"API POST /v1/start failed (422): {case.reason}"assert envelope["hint"] == case.next_stepassert envelope["error_domain"] == "input"assert envelope["http_status"] == 422@@ -136,18 +144,21 @@ class TestRunApiRefusal:assert case.failing_pipe in envelope["message"]@pytest.mark.usefixtures("tty_stdin")- def test_run_bundle_json_carries_the_runner_items_whole(+ def test_run_bundle_json_carries_the_runner_items(self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path) -> None:- """A refusal at load hands the agent the runner's located items exactly as the runner sent them."""- _install_runner(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNKNOWN_MODEL_AT_LOAD)+ """A refusal at load hands the agent the runner's located items, each with what the runner sent."""+ _install_hosted_api(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNKNOWN_MODEL_AT_LOAD)with pytest.raises(typer.Exit):- run_bundle_cmd(ctx=_api_ctx(mocker), path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON)+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, hosted=True)envelope = json.loads(capsys.readouterr().err)assert envelope["error_category"] == "configuration"- assert envelope["validation_errors"] == json.loads(RefusedRunBodies.UNKNOWN_MODEL_AT_LOAD)["validation_errors"]+ sent_items = json.loads(RefusedRunBodies.UNKNOWN_MODEL_AT_LOAD)["validation_errors"]+ assert len(envelope["validation_errors"]) == len(sent_items)+ for reported, sent in zip(envelope["validation_errors"], sent_items, strict=True):+ assert reported.items() >= sent.items()@pytest.mark.usefixtures("tty_stdin")@pytest.mark.parametrize("case", RefusalCases.DEV_PLANE, ids=[case.topic for case in RefusalCases.DEV_PLANE])@@ -160,16 +171,16 @@ class TestRunApiRefusal:case: RefusalCase,) -> None:"""The markdown of each dev-plane refusal reads like a local failure: heading, reason, hint, details."""- _install_runner(mocker, monkeypatch, status=422, body=case.body)+ _install_hosted_api(mocker, monkeypatch, status=422, body=case.body)with pytest.raises(typer.Exit) as exc_info:- run_bundle_cmd(ctx=_api_ctx(mocker), path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.MARKDOWN)+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.MARKDOWN, runner=RunExecution.HOSTED)assert exc_info.value.exit_code == 1captured = capsys.readouterr()assert not captured.outmarkdown = captured.err- assert markdown.startswith(f"# Error: {case.error_type}\n\nAPI POST /v1/execute failed (422): {case.reason}\n")+ assert markdown.startswith(f"# Error: {case.error_type}\n\nAPI POST /v1/start failed (422): {case.reason}\n")assert f"> 💡 **Hint:** {case.next_step}" in markdownassert "Next step:" not in markdownassert "- **error_domain:** input" in markdown@@ -182,10 +193,10 @@ class TestRunApiRefusal:self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path) -> None:"""The runner's items render as the grouped prose `validate` prints, not as a JSON dump."""- _install_runner(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNKNOWN_MODEL_AT_LOAD)+ _install_hosted_api(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNKNOWN_MODEL_AT_LOAD)with pytest.raises(typer.Exit):- run_bundle_cmd(ctx=_api_ctx(mocker), path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.MARKDOWN)+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.MARKDOWN, runner=RunExecution.HOSTED)markdown = capsys.readouterr().errassert "## Pipe validation errors" in markdown@@ -198,60 +209,159 @@ class TestRunApiRefusal:self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path) -> None:"""`--error-format json` gives the JSON envelope even when the success format is markdown."""- _install_runner(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNSERVED_MODEL_AT_RUN)+ _install_hosted_api(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNSERVED_MODEL_AT_RUN)with pytest.raises(typer.Exit):run_bundle_cmd(- ctx=_api_ctx(mocker),path=str(bundle_file),pipe="entry",output_format=CliOutputFormat.MARKDOWN,error_format=CliOutputFormat.JSON,+ runner=RunExecution.HOSTED,)assert json.loads(capsys.readouterr().err)["error_type"] == "ModelNotFoundError"@pytest.mark.usefixtures("tty_stdin")- def test_run_pipe_reports_the_refusal(self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]) -> None:- """`run pipe` on the API runner answers a refusal with the same envelope."""- _install_runner(mocker, monkeypatch, status=422, body=RefusedRunBodies.COMBINE_FAILURE_AT_RUN)+ def test_run_pipe_sends_its_library_and_reports_the_refusal(+ self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path+ ) -> None:+ """`run pipe` sends the library a local run would load, and answers a refusal with the same envelope."""+ seen = _install_hosted_api(mocker, monkeypatch, status=422, body=RefusedRunBodies.COMBINE_FAILURE_AT_RUN)mocker.patch(f"{RUN_PIPE_MODULE}.resolve_pipe_from_exports", return_value=[])with pytest.raises(typer.Exit) as exc_info:- run_pipe_cmd(ctx=_api_ctx(mocker), pipe_code="review_topics", output_format=CliOutputFormat.JSON)+ run_pipe_cmd(+ pipe_code="review_topics",+ library_dir=[str(bundle_file.parent)],+ output_format=CliOutputFormat.JSON,+ runner=RunExecution.HOSTED,+ )assert exc_info.value.exit_code == 1+ assert json.loads(seen[-1].content)["mthds_contents"] == ["# bundle\n"]envelope = json.loads(capsys.readouterr().err)assert envelope["error_type"] == "StuffFactoryError"assert envelope["hint"] == RefusedRunBodies.COMBINE_FAILURE_NEXT_STEP@pytest.mark.usefixtures("tty_stdin")- def test_run_method_reports_the_refusal(- self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path+ def test_run_method_by_address_is_resolved_by_the_hosted_api(+ self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]) -> None:- """`run method` on the API runner answers a refusal with the same markdown."""- _install_runner(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNSERVED_MODEL_AT_RUN)- method_mock = mocker.MagicMock()- method_mock.mthds_files = [bundle_file]- method_mock.path = bundle_file.parent- method_mock.provenance = None- mocker.patch(f"{RUN_METHOD_MODULE}.resolve_method_target", return_value=("digest_article", [str(bundle_file.parent)], method_mock))+ """A published address goes as `method_ref`, unfetched, and the refusal reads like a local failure."""+ seen = _install_hosted_api(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNSERVED_MODEL_AT_RUN)with pytest.raises(typer.Exit) as exc_info:- run_method_cmd(ctx=_api_ctx(mocker), name="news-digest", output_format=CliOutputFormat.MARKDOWN)+ run_method_cmd(name="github.com/Pipelex/methods/[email protected]", output_format=CliOutputFormat.MARKDOWN, runner=RunExecution.HOSTED)assert exc_info.value.exit_code == 1+ start_body = json.loads(seen[-1].content)+ assert start_body["method_ref"] == "github.com/Pipelex/methods/[email protected]"+ assert "mthds_contents" not in start_bodymarkdown = capsys.readouterr().errassert markdown.startswith("# Error: ModelNotFoundError\n")assert f"> 💡 **Hint:** {RefusedRunBodies.UNSERVED_MODEL_NEXT_STEP}" in markdown+ @pytest.mark.usefixtures("tty_stdin")+ def test_base_url_flag_wins_over_the_environment(+ self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path+ ) -> None:+ """`--base-url` names the origin every request of the run goes to, over `PIPELEX_BASE_URL`."""+ seen = _install_hosted_api(mocker, monkeypatch, status=422, body=RefusedRunBodies.UNSERVED_MODEL_AT_RUN)++ with pytest.raises(typer.Exit):+ run_bundle_cmd(+ path=str(bundle_file),+ pipe="entry",+ output_format=CliOutputFormat.JSON,+ runner=RunExecution.HOSTED,+ base_url="https://self-hosted.test:8081",+ )++ capsys.readouterr()+ assert seen+ assert {(request.url.host, request.url.port) for request in seen} == {("self-hosted.test", 8081)}++ @pytest.mark.usefixtures("tty_stdin")+ def test_an_unreachable_api_names_the_base_url_settings(+ self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path+ ) -> None:+ """A hosted API that cannot be reached is a configuration matter: the hint names where the origin comes from."""+ monkeypatch.setenv(PIPELEX_BASE_URL_ENV_KEY, HOSTED_URL)++ def _refuse_connection(request: httpx.Request) -> httpx.Response:+ msg = "connection refused"+ raise httpx.ConnectError(msg, request=request)++ def _start_client(self: PipelexAPIClient) -> PipelexAPIClient:+ self.client = httpx.AsyncClient(transport=httpx.MockTransport(_refuse_connection))+ return self++ mocker.patch.object(PipelexAPIClient, "start_client", _start_client)++ with pytest.raises(typer.Exit):+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)++ envelope = json.loads(capsys.readouterr().err)+ assert envelope["error_type"] == "ApiUnreachableError"+ assert envelope["error_domain"] == "config"+ assert PIPELEX_BASE_URL_ENV_KEY in envelope["hint"]++ @pytest.mark.usefixtures("tty_stdin")+ def test_a_server_without_the_run_routes_points_at_the_base_url(+ self, mocker: MockerFixture, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], bundle_file: Path+ ) -> None:+ """A server with neither `/v1/start` nor `/v1/execute` is not the hosted API: the hint names where the origin comes from."""+ seen = _install_hosted_api(mocker, monkeypatch, status=404, body='{"detail":"Not Found"}')++ with pytest.raises(typer.Exit):+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, runner=RunExecution.HOSTED)++ # The SDK falls back to a blocking execute when the run routes are absent, as a bare runner serves.+ assert _routes(seen=seen) == [START_ROUTE, ("POST", "/v1/execute")]+ envelope = json.loads(capsys.readouterr().err)+ assert envelope["error_type"] == "ApiResponseError"+ assert envelope["http_status"] == 404+ assert envelope["hint"] == HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[404]+ assert "--base-url" in envelope["hint"]++ @pytest.mark.parametrize(+ ("flags", "named"),+ [+ ({"runner": RunExecution.LOCAL, "hosted": True}, "--runner local contradicts --hosted"),+ ({"runner": RunExecution.LOCAL, "base_url": "https://api.pipelex.com"}, "--base-url"),+ ({"hosted": True, "dry_run": True}, "--dry-run"),+ ({"runner": RunExecution.HOSTED, "dry_run": True, "mock_inputs": True}, "--dry-run and --mock-inputs"),+ ({"runner": RunExecution.HOSTED, "base_url": "https://api.pipelex.com/v1"}, "scheme://host[:port]"),+ ],+ )+ @pytest.mark.usefixtures("tty_stdin")+ def test_contradicting_or_local_only_flags_are_refused_before_anything_is_sent(+ self,+ mocker: MockerFixture,+ monkeypatch: pytest.MonkeyPatch,+ capsys: pytest.CaptureFixture[str],+ bundle_file: Path,+ flags: dict[str, object],+ named: str,+ ) -> None:+ """Flags naming two places, or a local-only flag on a hosted run, are an argument error, and no request leaves."""+ seen = _install_hosted_api(mocker, monkeypatch, status=500, body="{}")++ with pytest.raises(typer.Exit) as exc_info:+ run_bundle_cmd(path=str(bundle_file), pipe="entry", output_format=CliOutputFormat.JSON, **flags) # type: ignore[arg-type]++ assert exc_info.value.exit_code == 1+ assert seen == []+ assert named in json.loads(capsys.readouterr().err)["message"]+def test_payload_of_an_answer_that_is_no_problem_document(self) -> None:- """A gateway's page gives the client's own class, the static hint, the status, and no runner classification."""+ """A gateway's page gives the client's own class, the server-fault hint, the status, and no runner classification."""payload = api_response_error_payload(error=_refusal(status=502, body=RefusedRunBodies.GATEWAY_HTML))assert payload["error_type"] == "ApiResponseError"- assert payload["message"] == f"API POST /v1/execute failed (502): {RefusedRunBodies.GATEWAY_HTML}"- assert payload["hint"] == AGENT_ERROR_HINTS["ApiResponseError"]+ assert payload["message"] == f"API POST /v1/start failed (502): {RefusedRunBodies.GATEWAY_HTML}"+ assert payload["hint"] == HOSTED_SERVER_FAULT_NEXT_STEPassert payload["http_status"] == 502for absent in ("error_domain", "error_category", "retryable", "request_id", "validation_errors", "pipe_code", "pipe_stack"):assert absent not in payload@@ -263,7 +373,7 @@ class TestRunApiRefusal:payload = api_response_error_payload(error=_refusal(status=500, body=body))assert payload["error_type"] == "PipeOperatorModelAvailabilityError"- assert payload["hint"] == AGENT_ERROR_HINTS["ApiResponseError"]+ assert payload["hint"] == HOSTED_SERVER_FAULT_NEXT_STEPassert "retryable" not in payloadassert "error_domain" not in payload@@ -274,7 +384,7 @@ class TestRunApiRefusal:assert payload["pipe_code"] == "analyze_topics"assert payload["pipe_stack"] == ["review_topics", "analyze_topics"]assert payload["retryable"] is True- assert payload["hint"] == API_REFUSAL_CALLER_HINT+ assert payload["hint"] == HOSTED_REFUSAL_CALLER_NEXT_STEPdef test_markdown_keeps_an_item_this_version_cannot_type(self, capsys: pytest.CaptureFixture[str]) -> None:"""An item from a newer runner stays readable as JSON under Details rather than failing the rendering."""@@ -295,7 +405,7 @@ class TestRunApiRefusal:payload = api_response_error_payload(error=_refusal(status=429, body=RefusedRunBodies.PLATFORM_RATE_LIMITED, headers={"Retry-After": "12"}))assert payload["error_type"] == "ApiResponseError"- assert payload["hint"] == API_REFUSAL_HINTS_BY_STATUS[429]+ assert payload["hint"] == HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[429]assert payload["retryable"] is Trueassert payload["retry_after_seconds"] == 12assert payload["error_code"] == "rate_limited"@@ -306,9 +416,9 @@ class TestRunApiRefusal:"""The gateway's bare 403 points at the key, not at a request_id it never sent."""payload = api_response_error_payload(error=_refusal(status=403, body=RefusedRunBodies.GATEWAY_FORBIDDEN))- assert payload["message"] == "API POST /v1/execute failed (403): Forbidden"- assert payload["hint"] == API_REFUSAL_HINTS_BY_STATUS[403]- assert "MTHDS_API_KEY" in payload["hint"]+ assert payload["message"] == "API POST /v1/start failed (403): Forbidden"+ assert payload["hint"] == HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[403]+ assert PIPELEX_API_KEY_ENV_KEY in payload["hint"]for absent in ("retryable", "request_id", "error_code", "retry_after_seconds"):assert absent not in payload@@ -323,18 +433,18 @@ class TestRunApiRefusal:assert "retryable" not in silentassert silent["retry_after_seconds"] == 10assert silent["error_code"] == "service_unavailable"- assert silent["hint"] == API_REFUSAL_HINTS_BY_STATUS[503]+ assert silent["hint"] == HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[503]assert "repeat a paid run" in silent["hint"]assert saying_yes["retryable"] is Truedef test_payload_of_a_refusal_the_caller_must_act_on(self) -> None:- """A 404 points at MTHDS_BASE_URL, and any other 4xx without a next step asks for a change, not a report."""- not_found = api_response_error_payload(error=_refusal(status=404, body='{"detail":"Not Found"}'))+ """A 404 points at the method and the base URL settings, and any other 4xx without a next step asks for a change, not a report."""+ not_found = api_response_error_payload(error=_refusal(status=404, body='{"detail":"No method at that address","code":"method_not_found"}'))unprocessable = api_response_error_payload(error=_refusal(status=422, body='{"detail":"Local file paths cannot be used"}'))- assert not_found["message"] == "API POST /v1/execute failed (404): Not Found"- assert not_found["hint"] == API_REFUSAL_HINTS_BY_STATUS[404]- assert "MTHDS_BASE_URL" in not_found["hint"]- assert unprocessable["hint"] == API_REFUSAL_CALLER_HINT+ assert not_found["message"] == "API POST /v1/start failed (404): No method at that address"+ assert not_found["hint"] == HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[404]+ assert PIPELEX_BASE_URL_ENV_KEY in not_found["hint"]+ assert unprocessable["hint"] == HOSTED_REFUSAL_CALLER_NEXT_STEPfor payload in (not_found, unprocessable):assert "retryable" not in payloaddiff --git a/tests/unit/pipelex/cli/agent_cli/test_run_method_inputs_resolution.py b/tests/unit/pipelex/cli/agent_cli/test_run_method_inputs_resolution.pyindex d70867bc3..3b236bc8b 100644--- a/tests/unit/pipelex/cli/agent_cli/test_run_method_inputs_resolution.py+++ b/tests/unit/pipelex/cli/agent_cli/test_run_method_inputs_resolution.py@@ -6,7 +6,6 @@ import iofrom typing import TYPE_CHECKING, Anyimport pytest-from mthds.runners.types import RunnerTypefrom pipelex.cli.agent_cli.commands.agent_output import CliOutputFormatfrom pipelex.cli.agent_cli.commands.run.method_cmd import run_method_cmd@@ -40,18 +39,13 @@ class TestAgentRunMethodInputsResolution:mocker.patch(f"{RUN_METHOD_MODULE}.Pipelex.teardown_if_needed")return mocker.patch(f"{RUN_METHOD_MODULE}.run_pipeline_core", new=mocker.AsyncMock(return_value=result))- def _make_ctx(self, mocker: MockerFixture) -> Any:- ctx = mocker.MagicMock()- ctx.obj = {"runner": RunnerType.PIPELEX}- return ctx-@pytest.mark.usefixtures("tty_stdin")def test_relative_inputs_resolved_against_method_dir(self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:"""A relative --inputs path loads from the method's directory, not the CWD (same rule as the main CLI)."""(tmp_path / "inputs.toml").write_text('topic = "cats"\n', encoding="utf-8")run_core_mock = self._patch_method_run(mocker, method_dir=tmp_path, result={"answer": "42"})- run_method_cmd(ctx=self._make_ctx(mocker), name="my-method", inputs="inputs.toml", output_format=CliOutputFormat.JSON)+ run_method_cmd(name="my-method", inputs="inputs.toml", output_format=CliOutputFormat.JSON)capsys.readouterr()assert run_core_mock.call_args.kwargs["inputs"] == {"topic": "cats"}@@ -61,7 +55,7 @@ class TestAgentRunMethodInputsResolution:"""Inline JSON --inputs is parsed as-is, never treated as a path."""run_core_mock = self._patch_method_run(mocker, method_dir=tmp_path, result={"answer": "42"})- run_method_cmd(ctx=self._make_ctx(mocker), name="my-method", inputs='{"topic": "inline"}', output_format=CliOutputFormat.JSON)+ run_method_cmd(name="my-method", inputs='{"topic": "inline"}', output_format=CliOutputFormat.JSON)capsys.readouterr()assert run_core_mock.call_args.kwargs["inputs"] == {"topic": "inline"}diff --git a/tests/unit/pipelex/cli/commands/run/test_hosted_sources.py b/tests/unit/pipelex/cli/commands/run/test_hosted_sources.pynew file mode 100644index 000000000..e17e584db--- /dev/null+++ b/tests/unit/pipelex/cli/commands/run/test_hosted_sources.py@@ -0,0 +1,158 @@+"""Unit tests for what a hosted run sends: the `.mthds` files a local run would load, or a name the hosted API resolves."""++from __future__ import annotations++from pathlib import Path+from typing import TYPE_CHECKING++import pytest++from pipelex.cli.commands.run._hosted_sources import (+ collect_mthds_files,+ hosted_library_dirs,+ hosted_pipe_library_files,+ looks_like_method_id,+ resolve_hosted_method_target,+)+from pipelex.hosted.exceptions import HostedRunSourceError+from pipelex.system.environment import PIPELEXPATH_ENV_KEY++if TYPE_CHECKING:+ from pytest_mock import MockerFixture++SOURCES_MODULE = "pipelex.cli.commands.run._hosted_sources"+++MT_REPORTS_MANIFEST = """[package]+address = "github.com/acme/reports"+version = "1.0.0"+description = "Reports"+name = "mt_reports"+main_pipe = "shout"++[exports.reports]+pipes = ["shout"]+"""+MT_REPORTS_BUNDLE = """domain = "reports"+main_pipe = "shout"++[pipe.shout]+type = "PipeLLM"+description = "Shout"+inputs = { text = "Text" }+output = "Text"+prompt = "Shout $text"+"""+++def _write(*, path: Path, content: str) -> Path:+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_text(content, encoding="utf-8")+ return path+++class TestHostedSources:+ def test_the_primary_file_goes_first_and_each_file_once(self, tmp_path: Path) -> None:+ bundle = _write(path=tmp_path / "lib" / "bundle.mthds", content="bundle")+ _write(path=tmp_path / "lib" / "a_other.mthds", content="other")+ _write(path=tmp_path / "lib" / "nested" / "deep.mthds", content="deep")+ _write(path=tmp_path / "lib" / "notes.md", content="not a bundle")+ _write(path=tmp_path / "lib" / ".venv" / "vendored.mthds", content="excluded")+ single = _write(path=tmp_path / "single.mthds", content="single")++ files = collect_mthds_files(primary=bundle, library_dirs=[str(tmp_path / "lib"), str(single), str(tmp_path / "missing")])++ assert [mthds_file.content for mthds_file in files] == ["bundle", "other", "deep", "single"]+ assert files[0].source == str(bundle)++ def test_a_pipe_run_without_a_library_is_refused(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.delenv(PIPELEXPATH_ENV_KEY, raising=False)+ with pytest.raises(HostedRunSourceError, match="-L"):+ hosted_pipe_library_files(library_dirs=None)++ def test_a_pipe_run_falls_back_to_pipelexpath(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:+ _write(path=tmp_path / "lib" / "bundle.mthds", content="bundle")+ monkeypatch.setenv(PIPELEXPATH_ENV_KEY, str(tmp_path / "lib"))++ files = hosted_pipe_library_files(library_dirs=None)++ assert [mthds_file.content for mthds_file in files] == ["bundle"]++ def test_a_library_with_no_bundle_is_refused(self, tmp_path: Path) -> None:+ with pytest.raises(HostedRunSourceError, match=r"No \.mthds file"):+ hosted_pipe_library_files(library_dirs=[str(tmp_path)])++ @pytest.mark.parametrize(+ ("target", "is_method_id"),+ [+ ("mt_abc123", True),+ ("mt_A-b_9", True),+ ("mt_", False),+ ("my-method", False),+ ("mt abc", False),+ ("github.com/Pipelex/methods/text_stats", False),+ ],+ )+ def test_a_catalog_id_is_told_from_a_method_name(self, target: str, is_method_id: bool) -> None:+ assert looks_like_method_id(target) is is_method_id++ def test_a_remote_method_with_a_local_library_is_refused(self, tmp_path: Path) -> None:+ """The hosted API resolves an address alone: it loads no library from this machine."""+ with pytest.raises(HostedRunSourceError, match="-L does not apply"):+ resolve_hosted_method_target(name="mt_abc123", pipe_override=None, library_dirs=[str(tmp_path)])++ def test_a_remote_method_is_anchored_in_the_working_directory(self) -> None:+ target = resolve_hosted_method_target(name="github.com/Pipelex/methods/[email protected]", pipe_override=None, library_dirs=None)++ assert target.method_ref == "github.com/Pipelex/methods/[email protected]"+ assert target.label == "text_stats"+ assert target.output_base_dir == Path.cwd()+ assert target.inputs_anchor_dir == Path.cwd()++ def test_a_local_method_sends_its_files_and_anchors_in_its_directory(self, mocker: MockerFixture, tmp_path: Path) -> None:+ method_dir = tmp_path / "my-method"+ _write(path=method_dir / "main.mthds", content="main")+ _write(path=tmp_path / "extra" / "extra.mthds", content="extra")+ method = mocker.MagicMock()+ method.path = method_dir+ method.provenance = None+ mocker.patch(f"{SOURCES_MODULE}.resolve_method_target", return_value=("summarize", [str(method_dir)], method))++ target = resolve_hosted_method_target(name="my-method", pipe_override=None, library_dirs=[str(tmp_path / "extra")])++ assert [mthds_file.content for mthds_file in target.mthds_files or []] == ["main", "extra"]+ assert target.pipe_code == "summarize"+ assert target.output_base_dir == method_dir+ assert target.inputs_anchor_dir == method_dir++ def test_an_installed_method_named_like_a_catalog_id_is_the_installed_method(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:+ """`mt_reports` is a valid method name: the installed method wins, as a local run would run it."""+ method_dir = tmp_path / ".mthds" / "methods" / "mt_reports"+ _write(path=method_dir / "METHODS.toml", content=MT_REPORTS_MANIFEST)+ _write(path=method_dir / "bundle.mthds", content=MT_REPORTS_BUNDLE)+ monkeypatch.chdir(tmp_path)++ target = resolve_hosted_method_target(name="mt_reports", pipe_override=None, library_dirs=None)++ assert target.method_id is None+ assert [mthds_file.content for mthds_file in target.mthds_files or []] == [MT_REPORTS_BUNDLE]+ assert target.pipe_code == "shout"++ def test_a_catalog_id_no_installed_method_bears_is_sent_as_an_id(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:+ monkeypatch.chdir(tmp_path)++ target = resolve_hosted_method_target(name="mt_reports", pipe_override=None, library_dirs=None)++ assert target.method_id == "mt_reports"+ assert target.mthds_files is None++ def test_the_library_of_a_run_is_its_library_dirs_else_pipelexpath(self, monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:+ """As a local run loads it: `-L` replaces PIPELEXPATH, and PIPELEXPATH is read only without it."""+ monkeypatch.setenv(PIPELEXPATH_ENV_KEY, str(tmp_path / "shared"))++ assert hosted_library_dirs(library_dirs=["lib"]) == ["lib"]+ assert hosted_library_dirs(library_dirs=[]) == []+ assert hosted_library_dirs(library_dirs=None) == [tmp_path / "shared"]++ monkeypatch.delenv(PIPELEXPATH_ENV_KEY)+ assert hosted_library_dirs(library_dirs=None) is Nonediff --git a/tests/unit/pipelex/cli/commands/run/test_run_hosted_cli.py b/tests/unit/pipelex/cli/commands/run/test_run_hosted_cli.pynew file mode 100644index 000000000..af2697467--- /dev/null+++ b/tests/unit/pipelex/cli/commands/run/test_run_hosted_cli.py@@ -0,0 +1,423 @@+"""Unit tests for `pipelex run method|pipe|bundle --hosted`: what each command sends, and what it saves.++`run_hosted` is mocked at the CLI seam, so no request leaves; the client is the real one, built from the flags and+the environment as a real run builds it.+"""++from __future__ import annotations++import asyncio+import io+import json+from typing import TYPE_CHECKING, Any++import pytest+import typer+from pipelex_sdk.error_models import RunErrorReport+from pipelex_sdk.errors import ApiUnreachableError, MissingMainStuffError, RunFailedError, RunTimeoutError+from pipelex_sdk.runs import RunResults, RunStatus+from pipelex_sdk.validation_models import ValidationErrorItem+from pydantic import ValidationError+from rich.console import Console+from typer.testing import CliRunner++from pipelex.cli._cli import app as pipelex_app+from pipelex.cli.commands.run.bundle_cmd import run_bundle_cmd+from pipelex.cli.commands.run.method_cmd import run_method_cmd+from pipelex.cli.commands.run.pipe_cmd import run_pipe_cmd+from pipelex.hosted.client_factory import PIPELEX_API_KEY_ENV_KEY, PIPELEX_BASE_URL_ENV_KEY+from pipelex.hosted.exceptions import HostedMethodInvalidError, HostedRunPollingError+from pipelex.hosted.hosted_run import HostedRunOutcome, HostedRunRequest+from pipelex.hosted.run_config import RunExecution+from pipelex.system.environment import PIPELEXPATH_ENV_KEY++if TYPE_CHECKING:+ from pathlib import Path+ from unittest.mock import AsyncMock++ from pytest_mock import MockerFixture++RUN_HOSTED_MODULE = "pipelex.cli.commands.run._run_hosted"+RUN_CORE_MODULE = "pipelex.cli.commands.run._run_core"+BUNDLE_CMD_MODULE = "pipelex.cli.commands.run.bundle_cmd"+PIPE_CMD_MODULE = "pipelex.cli.commands.run.pipe_cmd"+EXECUTION_MODULE = "pipelex.hosted.execution"+ROOT_CLI_MODULE = "pipelex.cli._cli"+TEXT_STATS_REF = "github.com/Pipelex/methods/[email protected]"+LABELLED_ITEM = ValidationErrorItem.model_validate(+ {"category": "blueprint_validation", "message": "unknown concept Foo", "source": "lib/b.mthds", "pipe_code": "step2"}+)++BUNDLE = """domain = "probe"+main_pipe = "summarize"++[pipe.summarize]+type = "PipeLLM"+description = "Summarize"+inputs = { text = "Text" }+output = "Text"+prompt = "Summarize $text"+"""+LIBRARY_BUNDLE = 'domain = "probe_lib"\n'+REPORT_TEXT = "# Report\n\nAll good."+HOSTED_RESULTS: dict[str, Any] = {+ "pipeline_run_id": "run_42",+ "main_stuff": {"text": REPORT_TEXT},+ "graph_spec": {"graph_id": "run_42", "nodes": [], "edges": []},+ "working_memory": {+ "root": {"main_stuff": {"concept": "native.Text", "content": {"text": REPORT_TEXT}, "stuff_code": "abc", "stuff_name": "main_stuff"}},+ "aliases": {},+ },+}+++def _results_body_drift() -> ValidationError:+ """The pydantic error a results body that drifted from the SDK's model raises when it is read."""+ try:+ RunResults.model_validate({"main_stuff": 1})+ except ValidationError as drift:+ return drift+ msg = "the drifted body validated"+ raise AssertionError(msg)+++def _hosted_request(*, run_hosted: AsyncMock) -> HostedRunRequest:+ assert run_hosted.await_args is not None+ request = run_hosted.await_args.kwargs["request"]+ assert isinstance(request, HostedRunRequest)+ return request+++class TestRunHostedCli:+ @pytest.fixture(autouse=True)+ def no_hosted_env(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.delenv(PIPELEX_BASE_URL_ENV_KEY, raising=False)+ monkeypatch.setenv(PIPELEX_API_KEY_ENV_KEY, "plx_sk_test_not_a_secret")++ @pytest.fixture+ def run_hosted(self, mocker: MockerFixture) -> AsyncMock:+ outcome = HostedRunOutcome(results=RunResults.model_validate(HOSTED_RESULTS))+ mocked: AsyncMock = mocker.patch(f"{RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(return_value=outcome))+ return mocked++ @pytest.fixture+ def bundle_dir(self, tmp_path: Path) -> Path:+ """A pipeline directory with its bundle and a second library file beside it."""+ pipeline_dir = tmp_path / "pipeline"+ pipeline_dir.mkdir()+ (pipeline_dir / "bundle.mthds").write_text(BUNDLE, encoding="utf-8")+ (pipeline_dir / "lib.mthds").write_text(LIBRARY_BUNDLE, encoding="utf-8")+ return pipeline_dir++ def test_bundle_sends_the_bundle_first_then_its_library_and_saves_the_outputs(+ self, run_hosted: AsyncMock, bundle_dir: Path, tmp_path: Path+ ) -> None:+ output_dir = tmp_path / "results"++ run_bundle_cmd(path=str(bundle_dir), hosted=True, output_dir=str(output_dir), no_pretty_print=True)++ request = _hosted_request(run_hosted=run_hosted)+ assert request.pipe_code == "summarize"+ assert [mthds_file.content for mthds_file in request.mthds_files or []] == [BUNDLE, LIBRARY_BUNDLE]+ assert request.method_ref is None+ assert request.method_id is None+ saved_dir = output_dir / "summarize_output_01"+ assert json.loads((saved_dir / "main_stuff.json").read_text(encoding="utf-8")) == {"text": REPORT_TEXT}+ assert (saved_dir / "main_stuff.md").read_text(encoding="utf-8") == REPORT_TEXT+ assert json.loads((saved_dir / "working_memory.json").read_text(encoding="utf-8"))["root"]["main_stuff"]["concept"] == "native.Text"+ assert json.loads((saved_dir / "graphspec.json").read_text(encoding="utf-8"))["graph_id"] == "run_42"++ def test_no_graph_saves_no_graphspec(self, run_hosted: AsyncMock, bundle_dir: Path, tmp_path: Path) -> None:+ run_bundle_cmd(path=str(bundle_dir), hosted=True, output_dir=str(tmp_path / "results"), graph=False, no_pretty_print=True)++ run_hosted.assert_awaited_once()+ assert not (tmp_path / "results" / "summarize_output_01" / "graphspec.json").exists()++ @pytest.mark.parametrize(+ ("name", "expected_method_ref", "expected_method_id"),+ [+ ("github.com/Pipelex/methods/[email protected]", "github.com/Pipelex/methods/[email protected]", None),+ ("https://github.com/Pipelex/methods/tree/main/text_stats", "github.com/Pipelex/methods/text_stats", None),+ ("mt_abc123", None, "mt_abc123"),+ ],+ )+ def test_method_named_remotely_is_resolved_by_the_hosted_api(+ self,+ mocker: MockerFixture,+ run_hosted: AsyncMock,+ tmp_path: Path,+ name: str,+ expected_method_ref: str | None,+ expected_method_id: str | None,+ ) -> None:+ """An address and a catalog id are sent as names: nothing is fetched or read on this machine."""+ fetch = mocker.patch("pipelex.cli.method_resolver.fetch_method_package", side_effect=AssertionError("fetched"))++ run_method_cmd(name=name, hosted=True, inputs='{"text": "Hello"}', output_dir=str(tmp_path), no_pretty_print=True)++ request = _hosted_request(run_hosted=run_hosted)+ assert request.method_ref == expected_method_ref+ assert request.method_id == expected_method_id+ assert request.mthds_files is None+ assert request.pipe_code is None+ assert request.inputs == {"text": "Hello"}+ fetch.assert_not_called()++ def test_an_inputs_file_anchors_its_relative_paths_to_its_directory(self, run_hosted: AsyncMock, tmp_path: Path) -> None:+ inputs_dir = tmp_path / "inputs"+ inputs_dir.mkdir()+ (inputs_dir / "inputs.json").write_text('{"document": "invoice.pdf"}', encoding="utf-8")++ run_method_cmd(+ name="github.com/Pipelex/methods/[email protected]",+ pipe="extract_document_text",+ hosted=True,+ inputs=str(inputs_dir / "inputs.json"),+ output_dir=str(tmp_path),+ no_pretty_print=True,+ )++ request = _hosted_request(run_hosted=run_hosted)+ assert request.pipe_code == "extract_document_text"+ assert request.inputs_base_dir == inputs_dir.resolve()++ def test_the_configured_default_runs_hosted_and_local_overrides_it(+ self, mocker: MockerFixture, run_hosted: AsyncMock, bundle_dir: Path, tmp_path: Path+ ) -> None:+ """`[run] execution = "hosted"` sends a run with no flag; `--local` keeps the run on this machine."""+ mocker.patch(f"{EXECUTION_MODULE}.configured_run_execution", return_value=RunExecution.HOSTED)+ local_run = mocker.patch(f"{BUNDLE_CMD_MODULE}.execute_run")++ run_bundle_cmd(path=str(bundle_dir), output_dir=str(tmp_path), no_pretty_print=True)+ run_hosted.assert_awaited_once()+ local_run.assert_not_called()++ run_bundle_cmd(path=str(bundle_dir), hosted=False, output_dir=str(tmp_path), no_pretty_print=True)+ local_run.assert_called_once()+ run_hosted.assert_awaited_once()++ @pytest.mark.parametrize(+ "flags",+ [+ {"hosted": True, "dry_run": True},+ {"hosted": True, "orchestrator": "temporal"},+ {"hosted": True, "save_csv": "out.csv"},+ {"hosted": True, "costs": False},+ {"hosted": True, "graph_full_data": True},+ {"hosted": False, "base_url": "https://api.pipelex.com"},+ {"hosted": True, "base_url": "https://api.pipelex.com/v1"},+ ],+ )+ def test_local_only_flags_and_a_misplaced_base_url_are_refused(+ self, mocker: MockerFixture, run_hosted: AsyncMock, bundle_dir: Path, flags: dict[str, Any]+ ) -> None:+ local_run = mocker.patch(f"{BUNDLE_CMD_MODULE}.execute_run")++ with pytest.raises(typer.Exit) as exc_info:+ run_bundle_cmd(path=str(bundle_dir), **flags)++ assert exc_info.value.exit_code == 1+ run_hosted.assert_not_awaited()+ local_run.assert_not_called()++ def test_a_pipe_run_with_no_library_is_refused(self, mocker: MockerFixture, run_hosted: AsyncMock, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.delenv("PIPELEXPATH", raising=False)+ mocker.patch(f"{PIPE_CMD_MODULE}.resolve_pipe_from_exports", return_value=None)++ with pytest.raises(typer.Exit) as exc_info:+ run_pipe_cmd(pipe_code="summarize", hosted=True)++ assert exc_info.value.exit_code == 1+ run_hosted.assert_not_awaited()++ def test_a_pipe_run_sends_its_library(self, mocker: MockerFixture, run_hosted: AsyncMock, bundle_dir: Path, tmp_path: Path) -> None:+ mocker.patch(f"{PIPE_CMD_MODULE}.resolve_pipe_from_exports", return_value=None)++ run_pipe_cmd(pipe_code="summarize", hosted=True, library_dir=[str(bundle_dir)], output_dir=str(tmp_path), no_pretty_print=True)++ request = _hosted_request(run_hosted=run_hosted)+ assert request.pipe_code == "summarize"+ assert sorted(mthds_file.content for mthds_file in request.mthds_files or []) == sorted([BUNDLE, LIBRARY_BUNDLE])++ def test_a_hosted_failure_exits_with_its_next_step(self, mocker: MockerFixture, bundle_dir: Path) -> None:+ unreachable = ApiUnreachableError("Could not reach Pipelex API at https://api.pipelex.com (ConnectError)", api_url="https://api.pipelex.com")+ mocker.patch(f"{RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=unreachable))+ print_failure = mocker.patch(f"{RUN_HOSTED_MODULE}._print_hosted_failure")++ with pytest.raises(typer.Exit) as exc_info:+ run_bundle_cmd(path=str(bundle_dir), hosted=True)++ assert exc_info.value.exit_code == 1+ print_failure.assert_called_once_with(error=unreachable)++ def test_a_bundle_file_without_a_library_sends_pipelexpath(+ self, monkeypatch: pytest.MonkeyPatch, run_hosted: AsyncMock, bundle_dir: Path, tmp_path: Path+ ) -> None:+ """A local run of a bundle file loads PIPELEXPATH when no -L is given; a hosted one sends it."""+ shared_dir = tmp_path / "shared"+ shared_dir.mkdir()+ (shared_dir / "shared.mthds").write_text(LIBRARY_BUNDLE, encoding="utf-8")+ monkeypatch.setenv(PIPELEXPATH_ENV_KEY, str(shared_dir))++ run_bundle_cmd(path=str(bundle_dir / "bundle.mthds"), hosted=True, output_dir=str(tmp_path / "results"), no_pretty_print=True)++ request = _hosted_request(run_hosted=run_hosted)+ assert [mthds_file.source for mthds_file in request.mthds_files or []] == [str(bundle_dir / "bundle.mthds"), str(shared_dir / "shared.mthds")]++ def test_a_named_text_output_is_saved_as_markdown_too(self, mocker: MockerFixture, bundle_dir: Path, tmp_path: Path) -> None:+ """The working memory names the main output through its `main_stuff` alias when a step named it."""+ named = RunResults.model_validate(+ {+ "pipeline_run_id": "run_6",+ "main_stuff": {"text": REPORT_TEXT},+ "working_memory": {+ "root": {"summary": {"concept": "native.Text", "content": {"text": REPORT_TEXT}}},+ "aliases": {"main_stuff": "summary"},+ },+ }+ )+ mocker.patch(f"{RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(return_value=HostedRunOutcome(results=named)))+ output_dir = tmp_path / "results"++ run_bundle_cmd(path=str(bundle_dir), hosted=True, output_dir=str(output_dir), no_pretty_print=True)++ assert (output_dir / "summarize_output_01" / "main_stuff.md").read_text(encoding="utf-8") == REPORT_TEXT++ def test_an_unexpected_failure_exits_with_a_failure_line(self, mocker: MockerFixture, bundle_dir: Path) -> None:+ """A failure no hosted arm names, such as a results body that drifted, is a failure line and exit 1, not a traceback."""+ output = io.StringIO()+ mocker.patch(f"{RUN_HOSTED_MODULE}.get_console", return_value=Console(file=output, width=250))+ mocker.patch(f"{RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=_results_body_drift()))++ with pytest.raises(typer.Exit) as exc_info:+ run_bundle_cmd(path=str(bundle_dir), hosted=True)++ assert exc_info.value.exit_code == 1+ printed = output.getvalue()+ assert "Failed to run on the hosted API" in printed+ assert "ValidationError" in printed+ assert "Traceback" not in printed++ @pytest.mark.parametrize(+ ("error", "expected_lines"),+ [+ (+ RunFailedError(+ "Run finished with status FAILED: bundle invalid",+ run_id="run_9",+ status=RunStatus.FAILED,+ error=RunErrorReport.model_validate(+ {+ "error_type": "ValidateBundleError",+ "message": "bundle invalid",+ "validation_errors": [LABELLED_ITEM.model_dump(mode="json")],+ }+ ),+ ),+ ["lib/b.mthds: unknown concept Foo", "Run id: run_9"],+ ),+ (+ HostedMethodInvalidError("The hosted API cannot load the method: Bundle does not load", validation_errors=[LABELLED_ITEM]),+ ["lib/b.mthds: unknown concept Foo"],+ ),+ (+ HostedRunPollingError("The run run_7 started on the hosted API, but following it failed", pipeline_run_id="run_7"),+ ["Run id: run_7", "may still be running"],+ ),+ (RunTimeoutError("Run 'run_7' did not finish within 1200s", run_id="run_7", timeout_seconds=1200.0), ["Run id: run_7"]),+ (MissingMainStuffError("Completed run 'run_7' returned no main stuff", run_id="run_7"), ["Run id: run_7"]),+ ],+ )+ def test_a_hosted_failure_prints_its_items_and_its_run(+ self, mocker: MockerFixture, bundle_dir: Path, error: Exception, expected_lines: list[str]+ ) -> None:+ output = io.StringIO()+ mocker.patch(f"{RUN_HOSTED_MODULE}.get_console", return_value=Console(file=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()+ for expected_line in expected_lines:+ assert expected_line in printed++ def test_an_acknowledged_start_is_announced_with_its_run_id(self, mocker: MockerFixture, bundle_dir: Path, tmp_path: Path) -> None:+ output = io.StringIO()+ mocker.patch(f"{RUN_HOSTED_MODULE}.get_console", return_value=Console(file=output, width=250))+ outcome = HostedRunOutcome(results=RunResults.model_validate(HOSTED_RESULTS))++ def _started(**kwargs: Any) -> HostedRunOutcome:+ kwargs["on_started"](pipeline_run_id="run_42")+ return outcome++ mocker.patch(f"{RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=_started))++ run_bundle_cmd(path=str(bundle_dir), hosted=True, output_dir=str(tmp_path / "results"), no_pretty_print=True)++ assert "Run run_42 started on the hosted API" in output.getvalue()++ @pytest.mark.parametrize("interruption", [KeyboardInterrupt(), asyncio.CancelledError()])+ def test_an_interrupted_run_names_the_run_that_keeps_going_and_exits_130(+ self, mocker: MockerFixture, bundle_dir: Path, interruption: BaseException+ ) -> None:+ """Ctrl-C stops the wait, not the run: the run id is what finds it again."""+ output = io.StringIO()+ mocker.patch(f"{RUN_HOSTED_MODULE}.get_console", return_value=Console(file=output, width=250))++ def _started_then_interrupted(**kwargs: Any) -> HostedRunOutcome:+ kwargs["on_started"](pipeline_run_id="run_77")+ raise interruption++ mocker.patch(f"{RUN_HOSTED_MODULE}.run_hosted", new=mocker.AsyncMock(side_effect=_started_then_interrupted))++ 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()+ assert "Run id: run_77" in printed+ assert "keeps going on the hosted API" in printed+ assert "Traceback" not in printed++ def 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))+ 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()+ assert "run history" in printed+ assert "Run id:" not in printed++ def test_a_hosted_run_prints_no_deck_notice_and_a_local_run_does(self, mocker: MockerFixture, run_hosted: AsyncMock, tmp_path: Path) -> None:+ """The deck notice is about this machine's inference, which a hosted run never boots."""+ mocker.patch(f"{ROOT_CLI_MODULE}.check_readiness")+ root_notice = mocker.patch(f"{ROOT_CLI_MODULE}.warn_if_deck_stale")+ run_notice = mocker.patch(f"{RUN_CORE_MODULE}.warn_if_deck_stale")+ mocker.patch(f"{RUN_CORE_MODULE}.make_pipelex_for_cli", side_effect=typer.Exit(3))++ hosted = CliRunner().invoke(+ pipelex_app,+ ["--no-logo", "run", "method", TEXT_STATS_REF, "--hosted", "--inputs", '{"text": "x"}', "-o", str(tmp_path), "--no-pretty-print"],+ )+ assert hosted.exit_code == 0, hosted.output+ run_hosted.assert_awaited_once()+ root_notice.assert_not_called()+ run_notice.assert_not_called()++ local = CliRunner().invoke(pipelex_app, ["--no-logo", "run", "pipe", "summarize", "--local", "-L", str(tmp_path)])+ assert local.exit_code == 3, local.output+ run_notice.assert_called_once()+ root_notice.assert_not_called()++ def test_every_other_command_still_prints_the_deck_notice(self, mocker: MockerFixture) -> None:+ mocker.patch(f"{ROOT_CLI_MODULE}.check_readiness")+ root_notice = mocker.patch(f"{ROOT_CLI_MODULE}.warn_if_deck_stale")++ CliRunner().invoke(pipelex_app, ["--no-logo", "validate", "--help"])++ root_notice.assert_called_once()diff --git a/tests/unit/pipelex/cli/dev/test_hub_layering_guard.py b/tests/unit/pipelex/cli/dev/test_hub_layering_guard.pyindex 01cb8b721..9583171dc 100644--- a/tests/unit/pipelex/cli/dev/test_hub_layering_guard.py+++ b/tests/unit/pipelex/cli/dev/test_hub_layering_guard.py@@ -215,6 +215,19 @@ class TestHubLayeringGuard:"layer it belongs to.")+ def test_the_hosted_run_package_stays_declared(self) -> None:+ """`pipelex.hosted` must stay declared: a hosted run boots nothing and must load no interpreter module.++ Its contract is that `pipelex run --hosted` works on a machine with no inference configured, which+ holds only while nothing in it reaches the interpreter. Deleting the entry takes it out of the layer+ rule, the transitive rule and the exceptions aggregate gate at once, with every one still passing.+ """+ assert "pipelex.hosted" in KERNEL_LAYER_PACKAGES, (+ "pipelex.hosted runs methods on the hosted API without booting, and it is no longer declared "+ "kernel-layer. Undeclared means unchecked, not flagged — restore the entry, or move whatever "+ "made it dirty to the layer it belongs to."+ )+def test_kernel_layer_may_import_runtime_hub(self) -> None:"""The permitted direction is never flagged — the kernel layer lives on `runtime_hub`."""violations = _violate(diff --git a/tests/unit/pipelex/cli/test_agent_output_drift.py b/tests/unit/pipelex/cli/test_agent_output_drift.pyindex cb4e40d6f..8f83ef8cb 100644--- a/tests/unit/pipelex/cli/test_agent_output_drift.py+++ b/tests/unit/pipelex/cli/test_agent_output_drift.py@@ -39,9 +39,6 @@ _NON_PIPELEX_ERROR_KEYS: frozenset[str] = frozenset("ValueError", # builtin"ValidationError", # pydantic"PipeValidationError", # subclass of ValueError, not of PipelexError- "ClientAuthenticationError", # mthds API client package- "PipelineRequestError", # mthds API client package- "ApiResponseError", # mthds API client package"ArgumentError", # synthetic error_type label"BinaryNotFoundError", # synthetic error_type label"FixBundleError", # synthetic error_type labeldiff --git a/tests/unit/pipelex/hosted/test_data.py b/tests/unit/pipelex/hosted/test_data.pynew file mode 100644index 000000000..14b06e503--- /dev/null+++ b/tests/unit/pipelex/hosted/test_data.py@@ -0,0 +1,81 @@+"""Shared data for the unit tests of `pipelex/hosted/`: a captured pipe-io descriptor and the problem documents of hosted refusals."""++from typing import ClassVar+++class HostedDescriptors:+ """Input-form descriptors as the dev API's `POST /v1/pipe-io` answers them.++ `MIXED_FILE_POSITIONS` was captured on 2026-10-07 from `https://api-dev.pipelex.com` for a probe bundle whose+ entry pipe takes a structure carrying an optional nested image, a document, a text and a list of images: every+ kind of position the anchoring walk has to tell apart, the optional nested file included.+ """++ MIXED_FILE_POSITIONS_PIPE_REF: ClassVar[str] = "hosted_probe.summarize_report"+ MIXED_FILE_POSITIONS: ClassVar[str] = (+ '{"fields": [{"kind": "object", "name": "report", "concept_ref": "hosted_probe.Report", '+ '"description": "A report with a cover image and attachments", "required": true, "presence": "plain", "gating": true, '+ '"fields": [{"kind": "text", "name": "title", "description": "The title", "required": true}, '+ '{"kind": "image", "name": "cover", "concept_ref": "native.Image", "description": "The cover", "required": false}]}, '+ '{"kind": "document", "name": "document", "concept_ref": "native.Document", "description": "A document", "required": true, '+ '"presence": "plain", "gating": true}, '+ '{"kind": "prose", "name": "notes", "concept_ref": "native.Text", "description": "A text", "required": true, '+ '"presence": "plain", "gating": true}, '+ '{"kind": "list", "name": "pages", "concept_ref": "native.Image", "description": "An image", "required": true, '+ '"presence": "plain", "gating": false, "item": {"kind": "image", "concept_ref": "native.Image", "description": "An image", '+ '"required": true}}]}'+ )++ TEXT_ONLY_PIPE_REF: ClassVar[str] = "text_stats.analyze_text"+ TEXT_ONLY: ClassVar[str] = (+ '{"fields": [{"kind": "prose", "name": "text", "concept_ref": "native.Text", "description": "A text", "required": true, '+ '"presence": "plain", "gating": true}]}'+ )+++class HostedRefusals:+ """Problem documents the hosted plane answers a refused request with, as they come off the wire."""++ # The platform's own refusal of a key, authored in front of the runner: no `user_action`.+ UNAUTHORIZED: ClassVar[str] = (+ '{"type":"https://docs.pipelex.com/latest/errors/unauthorized/","title":"Unauthorized","status":401,'+ '"detail":"Invalid or expired API key.","instance":"/v1/start","code":"unauthorized"}'+ )+ UNAUTHORIZED_DETAIL: ClassVar[str] = "Invalid or expired API key."++ # The runner's refusal of a bundle at load, with its own next step.+ INVALID_BUNDLE: ClassVar[str] = (+ '{"type":"https://docs.pipelex.com/latest/errors/validate-bundle-error/","title":"Validate bundle","status":422,'+ "\"detail\":\"Pipe 'draft_pitch' (PipeLLM), field 'model': Model handle 'gpt-5.1' was not found in the model deck\","+ '"instance":"/v1/start","request_id":"req_a3dd6900-7909-48d3-b551-0140e73ac7fc","error_domain":"input",'+ '"retryable":false,"error_type":"ValidateBundleError",'+ '"user_action":{"kind":"change_input","detail":"Edit the bundle as each validation error says"}}'+ )+ INVALID_BUNDLE_DETAIL: ClassVar[str] = "Pipe 'draft_pitch' (PipeLLM), field 'model': Model handle 'gpt-5.1' was not found in the model deck"+ INVALID_BUNDLE_NEXT_STEP: ClassVar[str] = "Edit the bundle as each validation error says"++ # A server fault with nothing to advise.+ SERVER_FAULT: ClassVar[str] = '{"title":"Internal Server Error","status":500,"detail":"Unexpected failure.","request_id":"req_42"}'+++class HostedVersions:+ """`GET /v1/version` answers: the hosted API's, which serves the durable run lifecycle, as the dev API gave it on 2026-10-07."""++ HOSTED: ClassVar[str] = (+ '{"protocol_version":"0.1.0","implementation":"pipelex-hosted","implementation_version":"0.30.0","runtime_version":null,'+ '"extensions":["runs","method_id","method_ref"]}'+ )+++class HostedPipeIoVerdicts:+ """`POST /v1/pipe-io` invalid verdicts, as the runner's crate core builds them."""++ # A method calling a published method by address: the crate core behind pipe-io loads no address-based dependency,+ # which `/v1/start` fetches and runs. Built from `resolve_crate_from_contents`'s refusal on 2026-10-07.+ ADDRESS_DEPENDENCY: ClassVar[str] = (+ '{"is_valid": false, "validation_errors": [{"category": "blueprint_validation", "message": "In-memory resolve cannot load '+ "address-based dependency 'github.com/mthds/scoring-lib/scoring' from the host filesystem; provide the dependency contents "+ 'in the request or use directory-based resolution."}], "message": "In-memory resolve cannot load address-based dependency '+ "'github.com/mthds/scoring-lib/scoring' from the host filesystem; provide the dependency contents in the request or use "+ 'directory-based resolution."}'+ )diff --git a/tests/unit/pipelex/hosted/test_hosted_client_factory.py b/tests/unit/pipelex/hosted/test_hosted_client_factory.pynew file mode 100644index 000000000..e813c73f0--- /dev/null+++ b/tests/unit/pipelex/hosted/test_hosted_client_factory.py@@ -0,0 +1,106 @@+from __future__ import annotations++import pytest++from pipelex.hosted.client_factory import (+ HOSTED_API_DEFAULT_BASE_URL,+ PIPELEX_API_KEY_ENV_KEY,+ PIPELEX_BASE_URL_ENV_KEY,+ make_hosted_client,+)+from pipelex.hosted.exceptions import HostedBaseUrlError+from pipelex.tools.misc.package_utils import get_package_version+++class TestHostedClientFactory:+ @pytest.fixture(autouse=True)+ def no_hosted_env(self, monkeypatch: pytest.MonkeyPatch) -> None:+ """Start every case with neither variable set, whatever the developer's shell exports."""+ monkeypatch.delenv(PIPELEX_API_KEY_ENV_KEY, raising=False)+ monkeypatch.delenv(PIPELEX_BASE_URL_ENV_KEY, raising=False)++ @pytest.mark.parametrize(+ ("base_url", "env_base_url", "expected"),+ [+ ("https://api-dev.pipelex.com", "https://elsewhere.test", "https://api-dev.pipelex.com"),+ (None, "https://api-dev.pipelex.com", "https://api-dev.pipelex.com"),+ (None, None, HOSTED_API_DEFAULT_BASE_URL),+ ("http://localhost:8081/", None, "http://localhost:8081"),+ ],+ )+ def test_the_base_url_resolves_flag_then_variable_then_default(+ self,+ monkeypatch: pytest.MonkeyPatch,+ base_url: str | None,+ env_base_url: str | None,+ expected: str,+ ) -> None:+ """`--base-url` wins over `PIPELEX_BASE_URL`, which wins over the hosted API."""+ if env_base_url is not None:+ monkeypatch.setenv(PIPELEX_BASE_URL_ENV_KEY, env_base_url)+ client = make_hosted_client(base_url=base_url)+ assert client.base_url == expected++ def test_the_default_is_the_hosted_api(self) -> None:+ assert HOSTED_API_DEFAULT_BASE_URL == "https://api.pipelex.com"++ def test_the_key_comes_from_the_environment(self, monkeypatch: pytest.MonkeyPatch) -> None:+ """The key is the SDK's to resolve: `PIPELEX_API_KEY`, which the runtime loads from `~/.pipelex/.env` at import."""+ monkeypatch.setenv(PIPELEX_API_KEY_ENV_KEY, "plx_sk_test_not_a_secret")+ assert make_hosted_client().api_key == "plx_sk_test_not_a_secret"++ def test_no_key_is_anonymous(self) -> None:+ """No key is not refused here: a self-hosted runner answers its protocol routes without one."""+ assert make_hosted_client().api_key == ""++ def test_the_user_agent_names_pipelex(self) -> None:+ """Every request says it comes from this runtime, so the hosted plane can tell its callers apart."""+ client = make_hosted_client()+ assert client.user_agent.startswith(f"pipelex/{get_package_version()} ")++ @pytest.mark.parametrize(+ ("base_url", "env_base_url", "named_source"),+ [+ ("https://api.pipelex.com/v1", None, "--base-url"),+ ("ftp://api.pipelex.com", None, "--base-url"),+ (None, "https://api.pipelex.com/v1", PIPELEX_BASE_URL_ENV_KEY),+ (None, "", PIPELEX_BASE_URL_ENV_KEY),+ ],+ )+ def test_a_base_url_that_is_not_host_only_is_refused_naming_where_it_came_from(+ self,+ monkeypatch: pytest.MonkeyPatch,+ base_url: str | None,+ env_base_url: str | None,+ named_source: str,+ ) -> None:+ """A path, a query or another scheme is refused before any request, and the message says which setting to fix."""+ if env_base_url is not None:+ monkeypatch.setenv(PIPELEX_BASE_URL_ENV_KEY, env_base_url)+ with pytest.raises(HostedBaseUrlError) as exc_info:+ make_hosted_client(base_url=base_url)+ assert named_source in exc_info.value.message+ assert "scheme://host[:port]" in exc_info.value.message++ @pytest.mark.parametrize(+ ("base_url", "env_base_url"),+ [+ ("https://alice:[email protected]", None),+ (None, "https://alice:[email protected]/v1?key=s3cret-token#s3cret-token"),+ ("alice:[email protected]", None),+ ("https:alice:[email protected]", None),+ (None, "alice:[email protected]"),+ ],+ )+ def test_a_refused_base_url_is_echoed_without_its_credentials(+ self, monkeypatch: pytest.MonkeyPatch, base_url: str | None, env_base_url: str | None+ ) -> None:+ """The message is caller-facing and ends up in logs and agent transcripts: the userinfo, query and fragment never reach it."""+ if env_base_url is not None:+ monkeypatch.setenv(PIPELEX_BASE_URL_ENV_KEY, env_base_url)+ with pytest.raises(HostedBaseUrlError) as exc_info:+ make_hosted_client(base_url=base_url)+ message = exc_info.value.message+ assert "s3cret-token" not in message+ assert "alice" not in message+ assert "api.pipelex.com" in messagediff --git a/tests/unit/pipelex/hosted/test_hosted_error_rendering.py b/tests/unit/pipelex/hosted/test_hosted_error_rendering.pynew file mode 100644index 000000000..4b7a52a8a--- /dev/null+++ b/tests/unit/pipelex/hosted/test_hosted_error_rendering.py@@ -0,0 +1,273 @@+from __future__ import annotations++import asyncio++import httpx+import pytest+from pipelex_sdk.client import PipelexAPIClient+from pipelex_sdk.error_models import RunErrorReport+from pipelex_sdk.errors import (+ ApiResponseError,+ ApiUnreachableError,+ InvalidLocalSourceError,+ MissingMainStuffError,+ PipelineExecuteTimeoutError,+ RunFailedError,+ RunTimeoutError,+ UploadAuthenticationError,+ UploadTransportError,+)+from pipelex_sdk.runs import RunStatus+from pipelex_sdk.validation_models import ValidationErrorItem++from pipelex.hosted.client_factory import PIPELEX_API_KEY_ENV_KEY, PIPELEX_BASE_URL_ENV_KEY+from pipelex.hosted.error_rendering import (+ HOSTED_REFUSAL_CALLER_NEXT_STEP,+ HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS,+ HOSTED_SERVER_FAULT_NEXT_STEP,+ describe_hosted_error,+ hosted_refusal_next_step,+)+from pipelex.hosted.exceptions import (+ HostedLocalFileUploadUnavailableError,+ HostedMethodInvalidError,+ HostedRunInterruptedError,+ HostedRunOutcomeUnknownError,+ HostedRunPollingError,+)+from tests.unit.pipelex.hosted.test_data import HostedRefusals++API_URL = "https://api.test"+LABELLED_ITEM = ValidationErrorItem.model_validate(+ {"category": "blueprint_validation", "message": "unknown concept Foo", "source": "lib/b.mthds", "pipe_code": "step2"}+)+++def _refusal(*, status: int, body: str) -> ApiResponseError:+ """The error the real client raises when the hosted API answers `POST /v1/start` with this status and body."""++ def _handler(request: httpx.Request) -> httpx.Response:+ return httpx.Response(status, content=body.encode("utf-8"), headers={"content-type": "application/problem+json"}, request=request)++ async def _start() -> None:+ client = PipelexAPIClient(api_key="plx_sk_test_not_a_secret", base_url=API_URL)+ client.client = httpx.AsyncClient(transport=httpx.MockTransport(_handler))+ try:+ await client.start(pipe_code="entry", mthds_contents=['domain = "probe"\n'])+ finally:+ await client.close()++ with pytest.raises(ApiResponseError) as exc_info:+ asyncio.run(_start())+ return exc_info.value+++class TestHostedErrorRendering:+ def test_a_refusal_with_a_next_step_keeps_the_runner_reason_and_its_advice(self) -> None:+ error = _refusal(status=422, body=HostedRefusals.INVALID_BUNDLE)++ view = describe_hosted_error(error=error)++ assert view.error_type == "ValidateBundleError"+ assert view.message == f"API POST /v1/start failed (422): {HostedRefusals.INVALID_BUNDLE_DETAIL}"+ assert view.next_step == HostedRefusals.INVALID_BUNDLE_NEXT_STEP+ assert hosted_refusal_next_step(error=error) == HostedRefusals.INVALID_BUNDLE_NEXT_STEP++ def test_a_refused_key_points_at_the_pipelex_api_key(self) -> None:+ """The platform's own 401 advises nothing; the next step names the variable that holds the key."""+ error = _refusal(status=401, body=HostedRefusals.UNAUTHORIZED)++ view = describe_hosted_error(error=error)++ assert view.error_type == "ApiResponseError"+ assert view.message == f"API POST /v1/start failed (401): {HostedRefusals.UNAUTHORIZED_DETAIL}"+ assert view.next_step == HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[401]+ assert PIPELEX_API_KEY_ENV_KEY in view.next_step++ @pytest.mark.parametrize(("status", "named"), [(401, PIPELEX_API_KEY_ENV_KEY), (403, PIPELEX_API_KEY_ENV_KEY), (404, PIPELEX_BASE_URL_ENV_KEY)])+ def test_the_status_hints_name_the_hosted_settings(self, status: int, named: str) -> None:+ assert named in HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[status]+ assert "MTHDS_" not in HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS[status]++ @pytest.mark.parametrize(+ ("status", "expected_next_step"),+ [(400, HOSTED_REFUSAL_CALLER_NEXT_STEP), (500, HOSTED_SERVER_FAULT_NEXT_STEP)],+ )+ def test_an_unadvised_refusal_without_a_hint_of_its_own_falls_back_by_status_class(self, status: int, expected_next_step: str) -> None:+ error = _refusal(status=status, body=HostedRefusals.SERVER_FAULT)+ assert hosted_refusal_next_step(error=error) == expected_next_step++ def test_an_unreachable_api_names_the_base_url_settings(self) -> None:+ error = ApiUnreachableError("Could not reach Pipelex API at https://api.test (ConnectError)", api_url=API_URL, code="ConnectError")++ view = describe_hosted_error(error=error)++ assert view.error_type == "ApiUnreachableError"+ assert view.message == "Could not reach Pipelex API at https://api.test (ConnectError)"+ assert "--base-url" in view.next_step+ assert PIPELEX_BASE_URL_ENV_KEY in view.next_step++ def test_a_failed_run_reports_the_runner_class_and_its_advice(self) -> None:+ report = RunErrorReport.model_validate(+ {+ "error_type": "LLMCompletionError",+ "message": "The provider refused the prompt",+ "error_domain": "runtime",+ "user_action": {"kind": "wait_and_retry", "detail": "Run it again in a minute"},+ }+ )+ error = RunFailedError(+ "Run finished with status FAILED: The provider refused the prompt", run_id="run_9", status=RunStatus.FAILED, error=report+ )++ view = describe_hosted_error(error=error)++ assert view.error_type == "LLMCompletionError"+ assert view.message == "Run finished with status FAILED: The provider refused the prompt"+ assert view.next_step == "Run it again in a minute"++ def test_a_failed_run_without_a_report_still_names_the_run(self) -> None:+ error = RunFailedError("Run finished with status CANCELLED", run_id="run_9", status=RunStatus.CANCELLED, error=None)++ view = describe_hosted_error(error=error)++ assert view.error_type == "RunFailedError"+ assert "run_9" in view.next_step++ def test_a_run_past_the_wait_keeps_going_and_says_where(self) -> None:+ error = RunTimeoutError("Run 'run_7' did not finish within 1200s", run_id="run_7", timeout_seconds=1200.0)++ view = describe_hosted_error(error=error)++ assert view.error_type == "RunTimeoutError"+ assert "run_7" in view.next_step++ def test_an_unreadable_local_file_names_the_path_to_check(self) -> None:+ error = InvalidLocalSourceError('Local file cannot be read: "inputs/missing.pdf" (FileNotFoundError).', source="inputs/missing.pdf")++ view = describe_hosted_error(error=error)++ assert view.error_type == "InvalidLocalSourceError"+ assert view.error_domain == "input"+ assert "inputs/missing.pdf" in view.message+ assert "inputs" in view.next_step++ def test_a_refused_upload_points_at_the_key(self) -> None:+ error = UploadAuthenticationError('Upload of "invoice.pdf" was not authorized (401). Check the configured Pipelex API key.', status=401)++ view = describe_hosted_error(error=error)++ assert PIPELEX_API_KEY_ENV_KEY in view.next_step++ def test_an_upload_that_could_not_reach_the_api_points_at_the_network_and_the_origin(self) -> None:+ unreachable = ApiUnreachableError("Could not reach Pipelex API at https://api.test (ConnectError)", api_url=API_URL, code="ConnectError")+ error = UploadTransportError('Upload of "a.pdf" could not reach the Pipelex API (ConnectError).')+ error.__cause__ = unreachable++ view = describe_hosted_error(error=error)++ assert view.error_type == "UploadTransportError"+ assert view.error_domain == "config"+ assert PIPELEX_BASE_URL_ENV_KEY in view.next_step+ assert "network" in view.next_step++ def test_an_upload_the_server_failed_is_a_server_fault(self) -> None:+ error = UploadTransportError('Upload of "a.pdf" failed (502): Bad Gateway.')++ view = describe_hosted_error(error=error)++ assert view.next_step == HOSTED_SERVER_FAULT_NEXT_STEP+ assert view.error_domain == "runtime"++ def test_a_failed_run_carries_its_id_and_its_validation_items(self) -> None:+ report = RunErrorReport.model_validate(+ {"error_type": "ValidateBundleError", "message": "bundle invalid", "validation_errors": [LABELLED_ITEM.model_dump(mode="json")]}+ )+ error = RunFailedError("Run finished with status FAILED: bundle invalid", run_id="run_9", status=RunStatus.FAILED, error=report)++ view = describe_hosted_error(error=error)++ assert view.pipeline_run_id == "run_9"+ assert view.validation_errors == (LABELLED_ITEM,)++ @pytest.mark.parametrize(+ "error",+ [+ RunTimeoutError("Run 'run_7' did not finish within 1200s", run_id="run_7", timeout_seconds=1200.0),+ MissingMainStuffError("Completed run 'run_7' returned no main stuff", run_id="run_7"),+ HostedRunPollingError("The run run_7 started on the hosted API, but following it failed", pipeline_run_id="run_7"),+ ],+ )+ def test_an_error_after_the_start_names_the_run(self, error: Exception) -> None:+ assert isinstance(error, (RunTimeoutError, MissingMainStuffError, HostedRunPollingError))+ view = describe_hosted_error(error=error)++ assert view.pipeline_run_id == "run_7"+ assert "run_7" in view.next_step++ def test_a_lost_run_is_not_reported_as_a_network_failure(self) -> None:+ error = HostedRunPollingError("The run run_7 started on the hosted API, but following it failed", pipeline_run_id="run_7")++ view = describe_hosted_error(error=error)++ assert view.error_type == "HostedRunPollingError"+ assert view.error_domain == "runtime"+ assert "may still be running" in view.next_step++ def test_a_method_that_does_not_load_carries_its_labelled_items(self) -> None:+ error = HostedMethodInvalidError("The hosted API cannot load the method: Bundle does not load", validation_errors=[LABELLED_ITEM])++ view = describe_hosted_error(error=error)++ assert view.error_type == "HostedMethodInvalidError"+ assert view.error_domain == "input"+ assert view.validation_errors == (LABELLED_ITEM,)+ assert view.pipeline_run_id is None++ def test_an_interrupted_wait_names_the_run_that_keeps_going(self) -> None:+ view = describe_hosted_error(error=HostedRunInterruptedError(pipeline_run_id="run_7"))++ assert view.error_type == "HostedRunInterruptedError"+ assert view.pipeline_run_id == "run_7"+ assert "run_7" in view.message+ assert "keeps going" in view.message+ assert "run_7" in view.next_step++ def test_an_interruption_before_the_acknowledgement_points_at_the_run_history(self) -> None:+ view = describe_hosted_error(error=HostedRunInterruptedError(pipeline_run_id=None))++ assert view.pipeline_run_id is None+ assert "run history" in view.next_step++ def test_a_start_lost_after_it_was_sent_points_at_the_run_history(self) -> None:+ error = HostedRunOutcomeUnknownError("The connection to the hosted API failed after the run request was sent (ReadError: reset)")++ view = describe_hosted_error(error=error)++ assert view.error_type == "HostedRunOutcomeUnknownError"+ assert view.error_domain == "runtime"+ assert view.pipeline_run_id is None+ assert "run history" in view.next_step+ assert "network" not in view.next_step++ def test_a_local_file_for_a_method_with_an_address_dependency_points_at_a_url(self) -> None:+ error = HostedLocalFileUploadUnavailableError(+ "Local file upload is not available yet for methods with address-based dependencies: the method depends on "+ "github.com/mthds/scoring-lib/scoring"+ )++ view = describe_hosted_error(error=error)++ assert view.error_domain == "input"+ assert "https URL" in view.next_step++ def test_a_blocking_route_timeout_warns_that_the_run_may_still_be_going(self) -> None:+ """Only a server that keeps no runs is called on the blocking route, so running again takes the same route and repeats a paid run."""+ error = PipelineExecuteTimeoutError("POST /v1/execute was cut off after 31s", elapsed_seconds=31.0)++ view = describe_hosted_error(error=error)++ assert "run it again" not in view.next_step+ assert "may still be going" in view.next_step+ assert PIPELEX_BASE_URL_ENV_KEY in view.next_step+ assert view.retryable is Falsediff --git a/tests/unit/pipelex/hosted/test_hosted_inputs.py b/tests/unit/pipelex/hosted/test_hosted_inputs.pynew file mode 100644index 000000000..4d054e125--- /dev/null+++ b/tests/unit/pipelex/hosted/test_hosted_inputs.py@@ -0,0 +1,169 @@+from __future__ import annotations++from pathlib import Path+from typing import Any++import pytest+from mthds.protocol.input_form import PipeInputFormDescriptor++from pipelex.hosted.hosted_inputs import anchor_local_file_sources, inputs_name_a_local_file+from tests.unit.pipelex.hosted.test_data import HostedDescriptors++BASE_DIR = Path("/work/inputs")+++def _descriptor() -> PipeInputFormDescriptor:+ return PipeInputFormDescriptor.model_validate_json(HostedDescriptors.MIXED_FILE_POSITIONS)+++class TestHostedInputs:+ @pytest.mark.parametrize(+ ("topic", "inputs", "expected_inputs", "expected_local_sources"),+ [+ (+ "a compact relative document",+ {"document": "invoice.pdf"},+ {"document": "/work/inputs/invoice.pdf"},+ ["/work/inputs/invoice.pdf"],+ ),+ (+ "a document content keeps its other members",+ {"document": {"url": "scans/invoice.pdf", "mime_type": "application/pdf"}},+ {"document": {"url": "/work/inputs/scans/invoice.pdf", "mime_type": "application/pdf"}},+ ["/work/inputs/scans/invoice.pdf"],+ ),+ (+ "an absolute path is local but already anchored",+ {"document": "/elsewhere/invoice.pdf"},+ {"document": "/elsewhere/invoice.pdf"},+ ["/elsewhere/invoice.pdf"],+ ),+ (+ "a reachable URL, a storage URI and a data URL are not local files",+ {+ "document": "https://example.com/invoice.pdf",+ "pages": ["pipelex-storage://uploads/a.png", {"url": "data:image/png;base64,iVBORw0KGgo="}],+ },+ {+ "document": "https://example.com/invoice.pdf",+ "pages": ["pipelex-storage://uploads/a.png", {"url": "data:image/png;base64,iVBORw0KGgo="}],+ },+ [],+ ),+ (+ "a URL scheme is told apart whatever its case, as the SDK tells it",+ {"document": "HTTPS://example.com/invoice.pdf", "pages": ["Http://example.com/page.png"]},+ {"document": "HTTPS://example.com/invoice.pdf", "pages": ["Http://example.com/page.png"]},+ [],+ ),+ (+ "a text that reads like a file name is not a file position",+ {"notes": "invoice.pdf"},+ {"notes": "invoice.pdf"},+ [],+ ),+ (+ "an optional file nested in a structure",+ {"report": {"title": "cover.png", "cover": "cover.png"}},+ {"report": {"title": "cover.png", "cover": "/work/inputs/cover.png"}},+ ["/work/inputs/cover.png"],+ ),+ (+ "each image of a list, compact or as content",+ {"pages": ["page1.png", {"url": "page2.png"}]},+ {"pages": ["/work/inputs/page1.png", {"url": "/work/inputs/page2.png"}]},+ ["/work/inputs/page1.png", "/work/inputs/page2.png"],+ ),+ (+ "an explicit envelope is walked through its content",+ {"document": {"concept": "native.Document", "content": {"url": "invoice.pdf"}}},+ {"document": {"concept": "native.Document", "content": {"url": "/work/inputs/invoice.pdf"}}},+ ["/work/inputs/invoice.pdf"],+ ),+ (+ "an input the signature does not declare passes through",+ {"extra": "invoice.pdf"},+ {"extra": "invoice.pdf"},+ [],+ ),+ (+ "a file URI is the local path it names, as a local run reads it",+ {"document": "file:///scans/invoice%20v2.pdf", "pages": [{"url": "file:///scans/page.png"}]},+ {"document": "/scans/invoice v2.pdf", "pages": [{"url": "/scans/page.png"}]},+ ["/scans/invoice v2.pdf", "/scans/page.png"],+ ),+ (+ "an explicit null at a file position is no file, and stays null",+ {"report": {"title": "Report", "cover": None}, "pages": [None]},+ {"report": {"title": "Report", "cover": None}, "pages": [None]},+ [],+ ),+ (+ "a value whose shape disagrees with its position is left for the run to refuse",+ {"document": ["invoice.pdf"], "pages": "page.png"},+ {"document": ["invoice.pdf"], "pages": "page.png"},+ [],+ ),+ ],+ )+ def test_local_files_are_found_and_anchored_where_the_signature_declares_them(+ self,+ topic: str,+ inputs: dict[str, Any],+ expected_inputs: dict[str, Any],+ expected_local_sources: list[str],+ ) -> None:+ """Only a document or image position holds a file, whatever a value looks like elsewhere."""+ anchored = anchor_local_file_sources(inputs=inputs, descriptor=_descriptor(), base_dir=BASE_DIR)+ assert anchored.inputs == expected_inputs, topic+ assert anchored.local_sources == expected_local_sources, topic++ def test_the_caller_inputs_are_not_mutated(self) -> None:+ inputs: dict[str, Any] = {"document": {"url": "invoice.pdf"}, "pages": ["page.png"]}+ anchor_local_file_sources(inputs=inputs, descriptor=_descriptor(), base_dir=BASE_DIR)+ assert inputs == {"document": {"url": "invoice.pdf"}, "pages": ["page.png"]}++ def test_without_a_base_directory_a_relative_path_stays_relative(self) -> None:+ """Inline inputs have no file to anchor to: the path is read from the working directory, as a local run reads it."""+ anchored = anchor_local_file_sources(inputs={"document": "invoice.pdf"}, descriptor=_descriptor(), base_dir=None)+ assert anchored.inputs == {"document": "invoice.pdf"}+ assert anchored.local_sources == ["invoice.pdf"]++ def test_a_home_relative_path_is_expanded(self) -> None:+ anchored = anchor_local_file_sources(inputs={"document": "~/invoice.pdf"}, descriptor=_descriptor(), base_dir=BASE_DIR)+ expected = str(Path("~/invoice.pdf").expanduser())+ assert anchored.inputs == {"document": expected}+ assert anchored.local_sources == [expected]++ def test_inputs_name_a_local_file_when_a_string_at_any_depth_is_an_existing_file(self, tmp_path: Path) -> None:+ """Whether to read the signature at all is decided before reading it: any string naming a file on this machine."""+ (tmp_path / "scans").mkdir()+ (tmp_path / "scans" / "invoice.pdf").write_bytes(b"%PDF")+ assert inputs_name_a_local_file(inputs={"document": "scans/invoice.pdf"}, base_dir=tmp_path)+ assert inputs_name_a_local_file(inputs={"report": {"pages": [{"url": "scans/invoice.pdf"}]}}, base_dir=tmp_path)+ assert inputs_name_a_local_file(inputs={"document": str(tmp_path / "scans" / "invoice.pdf")}, base_dir=None)+ assert inputs_name_a_local_file(inputs={"document": (tmp_path / "scans" / "invoice.pdf").as_uri()}, base_dir=None)++ def test_a_relative_path_also_counts_from_the_working_directory(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ (tmp_path / "invoice.pdf").write_bytes(b"%PDF")+ monkeypatch.chdir(tmp_path)+ assert inputs_name_a_local_file(inputs={"document": "invoice.pdf"}, base_dir=None)+ assert inputs_name_a_local_file(inputs={"document": "invoice.pdf"}, base_dir=tmp_path / "elsewhere")++ @pytest.mark.parametrize(+ ("topic", "inputs"),+ [+ ("no file is named", {"text": "a widget", "count": 3, "flag": True, "cover": None}),+ ("a missing file is not a local file", {"document": "missing.pdf"}),+ ("a directory is not a file", {"document": "."}),+ (+ "the remote forms are never local files",+ {"a": "https://example.com/x.pdf", "b": "HTTP://example.com/y.pdf", "c": "pipelex-storage://u/z.pdf", "d": "data:text/plain,hi"},+ ),+ ("a long text is not a path", {"text": "word " * 5000}),+ ("a text naming an unknown home is not a path", {"text": "~nobody-by-this-name/x"}),+ ],+ )+ def test_inputs_naming_no_existing_local_file(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, topic: str, inputs: dict[str, Any]) -> None:+ monkeypatch.chdir(tmp_path)+ assert not inputs_name_a_local_file(inputs=inputs, base_dir=tmp_path), topicdiff --git a/tests/unit/pipelex/hosted/test_hosted_run.py b/tests/unit/pipelex/hosted/test_hosted_run.pynew file mode 100644index 000000000..077921993--- /dev/null+++ b/tests/unit/pipelex/hosted/test_hosted_run.py@@ -0,0 +1,442 @@+from __future__ import annotations++import json+from typing import TYPE_CHECKING, Any++import httpx+import pytest+from mthds.protocol.input_form import PipeInputFormDescriptor+from mthds.protocol.models import VersionInfo+from pipelex_sdk.client import PipelexAPIClient+from pipelex_sdk.crate_models import CrateInvalidReport, MthdsFileItem, PipeIORequest, PipeIOValidReport+from pipelex_sdk.errors import (+ ApiUnreachableError,+ MissingMainStuffError,+ RunFailedError,+ RunLifecycleUnavailableError,+ RunTimeoutError,+)+from pipelex_sdk.runs import PipelexRunResultStart, RunResults, RunStatus+from pipelex_sdk.upload import UploadRecord+from pipelex_sdk.validation_models import ValidationErrorItem+from pydantic import ValidationError++from pipelex.hosted.exceptions import (+ HostedLocalFileUploadUnavailableError,+ HostedMethodInvalidError,+ HostedRunOutcomeUnknownError,+ HostedRunPollingError,+)+from pipelex.hosted.hosted_run import HostedRunRequest, run_hosted+from tests.unit.pipelex.hosted.test_data import HostedDescriptors, HostedPipeIoVerdicts, HostedVersions++if TYPE_CHECKING:+ from pathlib import Path+ from unittest.mock import MagicMock++ from pytest_mock import MockerFixture++BUNDLE_FILE = MthdsFileItem(content='domain = "probe"\n', source="probe.mthds")+DOCUMENT_METHOD_REF = "github.com/Pipelex/methods/[email protected]"+HOSTED_RUN_MODULE = "pipelex.hosted.hosted_run"+RUN_ID = "run_1"+DONE = RunResults(pipeline_run_id=RUN_ID, main_stuff={"text": "done"})+++def _valid_report(*, pipe_ref: str, descriptor_json: str) -> PipeIOValidReport:+ """A pipe-io valid arm carrying the one descriptor this module reads; the other artifacts play no part here."""+ descriptor = PipeInputFormDescriptor.model_validate_json(descriptor_json)+ return PipeIOValidReport.model_construct(+ is_valid=True,+ pipe_ref=pipe_ref,+ pipe_io_contracts={},+ input_form={pipe_ref: descriptor},+ output_form={},+ default_pipe_ref=pipe_ref,+ pending_signatures=[],+ is_runnable=True,+ )+++def _invalid_report(*, verdict_json: str) -> CrateInvalidReport:+ return CrateInvalidReport.model_validate_json(verdict_json)+++def _mocked_client(+ mocker: MockerFixture, *, pipe_io_report: PipeIOValidReport | CrateInvalidReport | None = None, version: str = HostedVersions.HOSTED+) -> MagicMock:+ """A client whose handshake names `version`, whose start is acknowledged as `RUN_ID`, and whose run completes."""+ client: MagicMock = mocker.create_autospec(PipelexAPIClient, instance=True)+ client.base_url = "https://hosted.test"+ client.version.return_value = VersionInfo.model_validate_json(version)+ client.start.return_value = PipelexRunResultStart(pipeline_run_id=RUN_ID)+ client.wait_for_result.return_value = DONE+ if pipe_io_report is not None:+ client.pipe_io.return_value = pipe_io_report+ return client+++class TestHostedRun:+ @pytest.mark.asyncio+ async def test_an_inline_bundle_without_inputs_starts_and_waits_on_its_contents(self, mocker: MockerFixture) -> None:+ """A local bundle travels as `mthds_contents`, and with no inputs nothing is asked of pipe-io."""+ client = _mocked_client(mocker)+ request = HostedRunRequest(mthds_files=[BUNDLE_FILE], pipe_code="entry", dynamic_output_concept_ref="probe.Thing")++ outcome = await run_hosted(client=client, request=request)++ client.start.assert_awaited_once_with(+ pipe_code="entry",+ mthds_contents=[BUNDLE_FILE.content],+ inputs=None,+ dynamic_output_concept_ref="probe.Thing",+ method_ref=None,+ method_id=None,+ )+ client.wait_for_result.assert_awaited_once_with(RUN_ID)+ client.pipe_io.assert_not_awaited()+ client.prepare_inputs.assert_not_awaited()+ assert outcome.results.pipeline_run_id == "run_1"+ assert outcome.results.main_stuff == {"text": "done"}+ assert outcome.uploads == []+ assert outcome.pipe_ref is None++ @pytest.mark.asyncio+ @pytest.mark.parametrize(+ ("source", "expected_method_ref", "expected_method_id"),+ [+ ({"method_ref": DOCUMENT_METHOD_REF}, DOCUMENT_METHOD_REF, None),+ ({"method_id": "mt_abc123"}, None, "mt_abc123"),+ ],+ )+ async def test_a_remote_source_is_named_not_sent(+ self,+ mocker: MockerFixture,+ source: dict[str, str],+ expected_method_ref: str | None,+ expected_method_id: str | None,+ ) -> None:+ """A published address and a stored method are resolved by the hosted API: no content leaves this machine."""+ client = _mocked_client(mocker)+ request = HostedRunRequest.model_validate(source)++ await run_hosted(client=client, request=request)++ client.start.assert_awaited_once_with(+ pipe_code=None,+ mthds_contents=None,+ inputs=None,+ dynamic_output_concept_ref=None,+ method_ref=expected_method_ref,+ method_id=expected_method_id,+ )++ @pytest.mark.asyncio+ async def test_inputs_naming_no_local_file_go_straight_to_the_run(self, mocker: MockerFixture) -> None:+ """Inputs naming no file on this machine need no preparation, so the signature is not even read."""+ client = _mocked_client(mocker)+ inputs = {"text": "report.pdf is a word here, not a file", "page": "https://example.com/page.png", "nested": {"cover": None}}+ request = HostedRunRequest(method_ref="github.com/Pipelex/methods/[email protected]", inputs=inputs)++ outcome = await run_hosted(client=client, request=request)++ client.pipe_io.assert_not_awaited()+ client.upload_file.assert_not_awaited()+ assert client.start.await_args.kwargs["inputs"] == inputs+ assert outcome.pipe_ref is None++ @pytest.mark.asyncio+ async def test_an_address_dependency_runs_with_inputs_naming_no_local_file(self, mocker: MockerFixture) -> None:+ """pipe-io loads no address-based dependency; with no file to upload it is not asked, and the run route fetches the dependency."""+ client = _mocked_client(mocker, pipe_io_report=_invalid_report(verdict_json=HostedPipeIoVerdicts.ADDRESS_DEPENDENCY))+ request = HostedRunRequest(mthds_files=[BUNDLE_FILE], inputs={"item": "a widget"})++ outcome = await run_hosted(client=client, request=request)++ client.pipe_io.assert_not_awaited()+ assert client.start.await_args.kwargs["inputs"] == {"item": "a widget"}+ assert outcome.results is DONE++ @pytest.mark.asyncio+ async def test_a_local_file_is_anchored_then_uploaded_before_the_run(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A relative file path resolves against the inputs file's directory, is uploaded, and the run gets the storage URI.++ The signature is read once: the upload is driven from that one answer, not from a second pipe-io request.+ """+ (tmp_path / "docs").mkdir()+ (tmp_path / "docs" / "invoice.pdf").write_bytes(b"%PDF")+ report = _valid_report(pipe_ref=HostedDescriptors.MIXED_FILE_POSITIONS_PIPE_REF, descriptor_json=HostedDescriptors.MIXED_FILE_POSITIONS)+ client = _mocked_client(mocker, pipe_io_report=report)+ upload = UploadRecord(uri="pipelex-storage://uploads/abc.pdf", filename="invoice.pdf", content_type="application/pdf", size=4)+ client.upload_file.return_value = upload+ request = HostedRunRequest(+ mthds_files=[BUNDLE_FILE],+ pipe_code="summarize_report",+ inputs={"document": "docs/invoice.pdf", "notes": "see attached"},+ inputs_base_dir=tmp_path,+ )++ outcome = await run_hosted(client=client, request=request)++ client.pipe_io.assert_awaited_once_with(PipeIORequest(files=[BUNDLE_FILE], pipe_ref="summarize_report"))+ client.prepare_inputs.assert_not_awaited()+ client.upload_file.assert_awaited_once_with(str(tmp_path / "docs" / "invoice.pdf"))+ assert client.start.await_args.kwargs["inputs"] == {"document": {"url": "pipelex-storage://uploads/abc.pdf"}, "notes": "see attached"}+ assert outcome.uploads == [upload]+ assert outcome.pipe_ref == HostedDescriptors.MIXED_FILE_POSITIONS_PIPE_REF++ @pytest.mark.asyncio+ async def test_a_null_optional_file_beside_a_local_file_reaches_the_run_as_null(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """A local run takes an explicit null for an optional image; the upload walk leaves it for the run to read."""+ (tmp_path / "invoice.pdf").write_bytes(b"%PDF")+ report = _valid_report(pipe_ref=HostedDescriptors.MIXED_FILE_POSITIONS_PIPE_REF, descriptor_json=HostedDescriptors.MIXED_FILE_POSITIONS)+ client = _mocked_client(mocker, pipe_io_report=report)+ client.upload_file.return_value = UploadRecord(+ uri="pipelex-storage://uploads/invoice.pdf", filename="invoice.pdf", content_type="application/pdf", size=4+ )+ inputs: dict[str, Any] = {+ "document": {"url": "invoice.pdf", "mime_type": "application/pdf"},+ "report": {"title": "Report", "cover": None},+ "pages": ["invoice.pdf", None],+ }+ request = HostedRunRequest(mthds_files=[BUNDLE_FILE], inputs=inputs, inputs_base_dir=tmp_path)++ await run_hosted(client=client, request=request)++ client.upload_file.assert_awaited_once_with(str(tmp_path / "invoice.pdf"))+ assert client.start.await_args.kwargs["inputs"] == {+ "document": {"url": "pipelex-storage://uploads/invoice.pdf", "mime_type": "application/pdf"},+ "report": {"title": "Report", "cover": None},+ "pages": [{"url": "pipelex-storage://uploads/invoice.pdf"}, None],+ }++ @pytest.mark.asyncio+ async def test_a_local_file_for_a_method_with_an_address_dependency_is_refused_with_a_url_to_use(+ self, mocker: MockerFixture, tmp_path: Path+ ) -> None:+ """Uploading needs the signature, which pipe-io cannot read through an address-based dependency: the method is not at fault."""+ (tmp_path / "invoice.pdf").write_bytes(b"%PDF")+ client = _mocked_client(mocker, pipe_io_report=_invalid_report(verdict_json=HostedPipeIoVerdicts.ADDRESS_DEPENDENCY))+ request = HostedRunRequest(mthds_files=[BUNDLE_FILE], inputs={"document": "invoice.pdf"}, inputs_base_dir=tmp_path)++ with pytest.raises(HostedLocalFileUploadUnavailableError) as exc_info:+ await run_hosted(client=client, request=request)++ error = exc_info.value+ assert "address-based dependencies" in error.message+ assert "github.com/mthds/scoring-lib/scoring" in error.message+ assert error.user_action is not None+ assert "https URL" in error.user_action.detail+ assert "Fix the method" not in error.user_action.detail+ client.upload_file.assert_not_awaited()+ client.start.assert_not_awaited()++ @pytest.mark.asyncio+ async def test_a_method_that_does_not_load_is_refused_before_the_run_with_its_labelled_items(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """pipe-io's verdict names each file by the label it was sent under; `/v1/start` takes bare contents and could not."""+ (tmp_path / "invoice.pdf").write_bytes(b"%PDF")+ item = ValidationErrorItem.model_validate(+ {"category": "blueprint_validation", "message": "unknown concept Foo", "source": "lib/b.mthds", "pipe_code": "step2"}+ )+ invalid = CrateInvalidReport(is_valid=False, validation_errors=[item], message="Bundle does not load")+ client = _mocked_client(mocker, pipe_io_report=invalid)+ request = HostedRunRequest(mthds_files=[BUNDLE_FILE], inputs={"document": "invoice.pdf"}, inputs_base_dir=tmp_path)++ with pytest.raises(HostedMethodInvalidError) as exc_info:+ await run_hosted(client=client, request=request)++ assert exc_info.value.validation_errors == [item]+ assert "Bundle does not load" in exc_info.value.message+ client.upload_file.assert_not_awaited()+ client.start.assert_not_awaited()++ @pytest.mark.asyncio+ @pytest.mark.parametrize(+ "follow_error",+ [+ ApiUnreachableError(+ "Could not reach Pipelex API at https://hosted.test (ConnectError)", api_url="https://hosted.test", code="ConnectError"+ ),+ httpx.RemoteProtocolError("server disconnected"),+ json.JSONDecodeError("Expecting value", "<html>Bad gateway</html>", 0),+ ],+ )+ async def test_a_failure_while_following_a_started_run_keeps_its_id(self, mocker: MockerFixture, follow_error: Exception) -> None:+ """A paid run that is still going is not reported as a plain network failure: the error names it."""+ client = _mocked_client(mocker)+ client.wait_for_result.side_effect = follow_error++ with pytest.raises(HostedRunPollingError) as exc_info:+ await run_hosted(client=client, request=HostedRunRequest(mthds_files=[BUNDLE_FILE]))++ error = exc_info.value+ assert error.pipeline_run_id == RUN_ID+ assert error.__cause__ is follow_error+ assert RUN_ID in error.message+ assert error.user_action is not None+ assert RUN_ID in error.user_action.detail++ @pytest.mark.asyncio+ async def test_a_results_body_that_does_not_parse_keeps_the_run_id(self, mocker: MockerFixture) -> None:+ """A drift in the results body fails after the run completed: the run id still locates it."""+ with pytest.raises(ValidationError) as drift:+ RunResults.model_validate({"main_stuff": 1})+ client = _mocked_client(mocker)+ client.wait_for_result.side_effect = drift.value++ with pytest.raises(HostedRunPollingError) as exc_info:+ await run_hosted(client=client, request=HostedRunRequest(mthds_files=[BUNDLE_FILE]))++ assert exc_info.value.pipeline_run_id == RUN_ID++ @pytest.mark.asyncio+ @pytest.mark.parametrize(+ "terminal_error",+ [+ RunFailedError("Run finished with status FAILED: boom", run_id=RUN_ID, status=RunStatus.FAILED),+ RunTimeoutError(f"Run '{RUN_ID}' did not finish within 1200s", run_id=RUN_ID, timeout_seconds=1200.0),+ MissingMainStuffError(f"Completed run '{RUN_ID}' returned no main stuff", run_id=RUN_ID),+ ],+ )+ async def test_an_error_that_names_the_run_already_is_raised_as_it_is(self, mocker: MockerFixture, terminal_error: Exception) -> None:+ client = _mocked_client(mocker)+ client.wait_for_result.side_effect = terminal_error++ with pytest.raises(type(terminal_error)) as exc_info:+ await run_hosted(client=client, request=HostedRunRequest(mthds_files=[BUNDLE_FILE]))++ assert exc_info.value is terminal_error++ @pytest.mark.asyncio+ async def test_a_bare_runner_runs_the_blocking_route(self, mocker: MockerFixture) -> None:+ """A runner whose handshake names no run store is never started: it gets the blocking execute, as the SDK does."""+ bare_version = '{"protocol_version":"0.1.0","implementation":"pipelex-api","implementation_version":"0.76.0"}'+ client = _mocked_client(mocker, version=bare_version)+ lift = mocker.patch(f"{HOSTED_RUN_MODULE}.results_from_execute", return_value=DONE)++ outcome = await run_hosted(client=client, request=HostedRunRequest(method_ref=DOCUMENT_METHOD_REF, pipe_code="extract"))++ client.start.assert_not_awaited()+ client.execute.assert_awaited_once_with(+ pipe_code="extract",+ mthds_contents=None,+ inputs=None,+ dynamic_output_concept_ref=None,+ method_ref=DOCUMENT_METHOD_REF,+ method_id=None,+ )+ lift.assert_called_once_with(client.execute.return_value)+ assert outcome.results is DONE++ @pytest.mark.asyncio+ async def test_a_server_without_the_run_store_falls_back_to_the_blocking_route(self, mocker: MockerFixture) -> None:+ """A start refused for a missing run store created no run, so the blocking execute cannot run it twice."""+ client = _mocked_client(mocker)+ client.start.side_effect = RunLifecycleUnavailableError("no run store", api_url="https://hosted.test")+ mocker.patch(f"{HOSTED_RUN_MODULE}.results_from_execute", return_value=DONE)++ outcome = await run_hosted(client=client, request=HostedRunRequest(mthds_files=[BUNDLE_FILE]))++ client.execute.assert_awaited_once()+ client.wait_for_result.assert_not_awaited()+ assert outcome.results is DONE++ @pytest.mark.asyncio+ async def test_an_acknowledged_start_is_announced_before_the_run_is_followed(self, mocker: MockerFixture) -> None:+ """The caller learns the run's id as soon as the hosted API acknowledges it, so an interrupted wait can still name it."""+ client = _mocked_client(mocker)+ announced: list[str] = []++ def _on_started(*, pipeline_run_id: str) -> None:+ announced.append(pipeline_run_id)++ def _follow(run_id: str) -> RunResults:+ assert announced == [run_id], "the start must be announced before the run is followed"+ return DONE++ client.wait_for_result.side_effect = _follow++ await run_hosted(client=client, request=HostedRunRequest(mthds_files=[BUNDLE_FILE]), on_started=_on_started)++ assert announced == [RUN_ID]++ @pytest.mark.asyncio+ async def test_a_blocking_run_announces_no_start(self, mocker: MockerFixture) -> None:+ bare_version = '{"protocol_version":"0.1.0","implementation":"pipelex-api","implementation_version":"0.76.0"}'+ client = _mocked_client(mocker, version=bare_version)+ mocker.patch(f"{HOSTED_RUN_MODULE}.results_from_execute", return_value=DONE)+ on_started = mocker.Mock()++ await run_hosted(client=client, request=HostedRunRequest(mthds_files=[BUNDLE_FILE]), on_started=on_started)++ on_started.assert_not_called()++ @pytest.mark.asyncio+ @pytest.mark.parametrize(+ ("transport_error", "expected_code"),+ [+ (httpx.ConnectError("connection refused"), "ConnectError"),+ (httpx.ConnectTimeout("connect timed out"), "ABORT_TIMEOUT"),+ (httpx.PoolTimeout("no free connection"), "ABORT_TIMEOUT"),+ (httpx.UnsupportedProtocol("unknown scheme"), "UnsupportedProtocol"),+ (httpx.ProxyError("proxy refused"), "ProxyError"),+ ],+ )+ async def test_a_transport_failure_before_the_start_is_sent_is_an_unreachable_api(+ self, mocker: MockerFixture, transport_error: httpx.TransportError, expected_code: str+ ) -> None:+ """No byte of the start left this machine, so no run exists: checking the network is the right advice."""+ client = _mocked_client(mocker)+ client.start.side_effect = transport_error++ with pytest.raises(ApiUnreachableError) as exc_info:+ await run_hosted(client=client, request=HostedRunRequest(mthds_files=[BUNDLE_FILE]))++ assert exc_info.value.api_url == "https://hosted.test"+ assert exc_info.value.code == expected_code+ assert str(exc_info.value).startswith("Could not reach Pipelex API at https://hosted.test")++ @pytest.mark.asyncio+ @pytest.mark.parametrize(+ "transport_error",+ [+ httpx.ReadError("connection reset"),+ httpx.RemoteProtocolError("Server disconnected without sending a response."),+ httpx.ReadTimeout("timed out"),+ httpx.WriteError("broken pipe"),+ httpx.WriteTimeout("write timed out"),+ ],+ )+ @pytest.mark.parametrize("bare_runner", [False, True])+ async def test_a_transport_failure_after_the_run_request_was_sent_is_an_unknown_outcome(+ self, mocker: MockerFixture, transport_error: httpx.TransportError, bare_runner: bool+ ) -> None:+ """The hosted API may have created the run before the connection failed, so "check the network" would lead to a second paid run."""+ bare_version = '{"protocol_version":"0.1.0","implementation":"pipelex-api","implementation_version":"0.76.0"}'+ client = _mocked_client(mocker, version=bare_version) if bare_runner else _mocked_client(mocker)+ client.start.side_effect = transport_error+ client.execute.side_effect = transport_error++ with pytest.raises(HostedRunOutcomeUnknownError) as exc_info:+ await run_hosted(client=client, request=HostedRunRequest(mthds_files=[BUNDLE_FILE]))++ error = exc_info.value+ assert error.__cause__ is transport_error+ assert type(transport_error).__name__ in error.message+ assert error.user_action is not None+ assert "run history" in error.user_action.detail+ assert "before running again" in error.user_action.detail++ @pytest.mark.parametrize(+ "source",+ [+ {},+ {"method_ref": DOCUMENT_METHOD_REF, "method_id": "mt_abc123"},+ {"mthds_files": [BUNDLE_FILE], "method_ref": DOCUMENT_METHOD_REF},+ {"mthds_files": []},+ ],+ )+ def test_a_request_names_exactly_one_source(self, source: dict[str, Any]) -> None:+ """A bundle, a published address or a stored method: one of the three, never none or several."""+ with pytest.raises(ValidationError, match="exactly one"):+ HostedRunRequest.model_validate(source)diff --git a/tests/unit/pipelex/hosted/test_run_execution.py b/tests/unit/pipelex/hosted/test_run_execution.pynew file mode 100644index 000000000..5403cc002--- /dev/null+++ b/tests/unit/pipelex/hosted/test_run_execution.py@@ -0,0 +1,82 @@+from __future__ import annotations++from typing import TYPE_CHECKING++import pytest++from pipelex.config import get_config+from pipelex.hosted.execution import configured_run_execution, resolve_run_execution+from pipelex.hosted.run_config import RunConfig, RunExecution+from pipelex.system.configuration.config_loader import config_manager+from pipelex.system.configuration.configs import PipelexConfig++if TYPE_CHECKING:+ from pathlib import Path++ from pytest_mock import MockerFixture++EXECUTION_MODULE = "pipelex.hosted.execution"+++class TestRunExecution:+ @pytest.mark.parametrize(+ ("requested", "configured", "expected"),+ [+ (RunExecution.HOSTED, RunExecution.LOCAL, RunExecution.HOSTED),+ (RunExecution.LOCAL, RunExecution.HOSTED, RunExecution.LOCAL),+ (None, RunExecution.HOSTED, RunExecution.HOSTED),+ (None, RunExecution.LOCAL, RunExecution.LOCAL),+ ],+ )+ def test_the_flag_wins_then_the_setting(+ self,+ mocker: MockerFixture,+ requested: RunExecution | None,+ configured: RunExecution,+ expected: RunExecution,+ ) -> None:+ """A flag on the run decides; with none, the `[run] execution` setting does."""+ mocker.patch(f"{EXECUTION_MODULE}.configured_run_execution", return_value=configured)+ assert resolve_run_execution(requested=requested) is expected++ def test_a_flag_reads_no_configuration(self, mocker: MockerFixture) -> None:+ """A run that names where it executes never loads the configuration to find out."""+ reader = mocker.patch(f"{EXECUTION_MODULE}.configured_run_execution", side_effect=AssertionError("configuration read"))+ assert resolve_run_execution(requested=RunExecution.HOSTED) is RunExecution.HOSTED+ reader.assert_not_called()++ def test_the_kit_default_is_local(self) -> None:+ """The packaged default, which the booted test configuration carries, runs locally."""+ assert get_config().run.execution is RunExecution.LOCAL+ assert configured_run_execution() is RunExecution.LOCAL++ def test_without_a_boot_the_setting_is_read_from_the_configuration_files(self, mocker: MockerFixture) -> None:+ """A hosted run does not boot, so the setting is read from the same layers a boot would merge."""+ mocker.patch(f"{EXECUTION_MODULE}.get_optional_config", return_value=None)+ hosted_config = get_config().model_copy(update={"run": RunConfig(execution=RunExecution.HOSTED)})+ load = mocker.patch.object(config_manager, "load_config_validated", return_value=hosted_config)++ assert configured_run_execution() is RunExecution.HOSTED+ load.assert_called_once_with(config_cls=PipelexConfig)++ def test_a_configuration_file_sets_the_default(self, tmp_path: Path) -> None:+ """`[run] execution = "hosted"` in a configuration directory validates into the hosted default."""+ (tmp_path / "pipelex.toml").write_text('[run]\nexecution = "hosted"\n', encoding="utf-8")+ loaded = config_manager.load_config_validated(config_cls=PipelexConfig, config_dir=tmp_path)+ assert loaded.run.execution is RunExecution.HOSTED++ @pytest.mark.parametrize(+ ("hosted", "expected"),+ [+ (True, RunExecution.HOSTED),+ (False, RunExecution.LOCAL),+ (None, None),+ ],+ )+ def test_the_hosted_flag_pair_maps_onto_the_execution(self, hosted: bool | None, expected: RunExecution | None) -> None:+ """`--hosted` and `--local` are one flag pair; leaving both out requests nothing."""+ assert RunExecution.from_hosted_flag(hosted=hosted) is expected++ @pytest.mark.parametrize(("execution", "is_hosted"), [(RunExecution.HOSTED, True), (RunExecution.LOCAL, False)])+ def test_is_hosted(self, execution: RunExecution, is_hosted: bool) -> None:+ assert execution.is_hosted is is_hosteddiff --git a/tests/unit/pipelex/test_kernel_layer_import_closure.py b/tests/unit/pipelex/test_kernel_layer_import_closure.pyindex ec6489942..c35ff4b0b 100644--- a/tests/unit/pipelex/test_kernel_layer_import_closure.py+++ b/tests/unit/pipelex/test_kernel_layer_import_closure.py@@ -94,6 +94,10 @@ KERNEL_LAYER_ENTRY_POINTS = [# The boot-tolerance replay imports the engine; `pipelex migrate` drives the runner."pipelex.migration.engine","pipelex.migration.runner",+ # A hosted run boots nothing: the run mapping and the execution resolution carry the whole package.+ "pipelex.hosted.hosted_run",+ "pipelex.hosted.execution",+ "pipelex.hosted.error_rendering",]#: The negative control, and the reason it is needed: the detector below is a `textwrap.dedent`diff --git a/uv.lock b/uv.lockindex d807c0667..e87b6c9bd 100644--- a/uv.lock+++ b/uv.lock@@ -3552,6 +3552,7 @@ dependencies = [{ name = "opentelemetry-sdk" },{ name = "opentelemetry-semantic-conventions" },{ name = "pillow" },+ { name = "pipelex-sdk" },{ name = "pipelex-tools-py" },{ name = "polyfactory" },{ name = "portkey-ai" },@@ -3716,6 +3717,7 @@ requires-dist = [{ name = "opentelemetry-sdk", specifier = ">=1.39.0" },{ name = "opentelemetry-semantic-conventions", specifier = ">=0.59b0" },{ name = "pillow", specifier = ">=12.1.1" },+ { name = "pipelex-sdk", specifier = "==0.31.0" },{ name = "pipelex-tools", marker = "extra == 'dev'", specifier = ">=0.7.2" },{ name = "pipelex-tools-py", specifier = ">=0.1.3" },{ name = "polyfactory", specifier = ">=2.21.0" },@@ -3825,6 +3827,21 @@ requires-dist = []provides-extras = ["dev"]+[[package]]+name = "pipelex-sdk"+version = "0.31.0"+source = { registry = "https://pypi.org/simple" }+dependencies = [+ { name = "httpx" },+ { name = "mthds" },+ { name = "pydantic" },+ { name = "typing-extensions" },+]+sdist = { url = "https://files.pythonhosted.org/packages/95/36/c2e3d1e4783cc8371cf0ca76357198992100f57d6ff96434dcd28bfd35e4/pipelex_sdk-0.31.0.tar.gz", hash = "sha256:caca6d52b07a4672eb0f75a97f919c864df63a88eaae4ed739c151d95edd5587", size = 368507, upload-time = "2026-10-05T00:18:32.979Z" }+wheels = [+ { url = "https://files.pythonhosted.org/packages/a3/4a/45d96ab1643d1f8c8d7a40dea0e5754fc10915ba2738a3cc4a0d826071a9/pipelex_sdk-0.31.0-py3-none-any.whl", hash = "sha256:d48f24364a9d1123466640a86ce3a7e2800f45a9fa553ae316d7f152ef1b9ad0", size = 138964, upload-time = "2026-10-05T00:18:31.291Z" },+]+[[package]]name = "pipelex-tools"version = "0.7.2"