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/Fetch-refusal-message-stale · L-260929-7bcc21 (#1301)
Louis Choquel46163b2c2bd5
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex f2cfcc0f5..c95e9c9ba 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,8 +1,8 @@contract = "cli-docs"-digest = "sha256:765de3b76ea67aa0b78b067280e6ed1beadf1219fe064414061b6734ca8c7564"+digest = "sha256:c6dad185bafd093de8ccfc4083426af035c8e8e738c7412e9ecbc387ba3e6955"reviewed_by = "Louis Choquel"-reviewed_at = "2026-09-27T14:03:58Z"-rationale = "Round 2 review fixes: the API refusal paragraph and the agent CLI guide now say error_type is the local cause_type on a failed run, a 404 points at MTHDS_BASE_URL, another 4xx asks for a change, and only a 429 is inferred retryable"+reviewed_at = "2026-09-29T11:38:40Z"+rationale = "The fetched-method structures warning now gives the shared remedy; docs/tools/cli/run-by-address.md updated to state the same route, agent CLI CLAUDE.md does not describe this warning"[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"@@ -130,6 +130,6 @@ rationale = "Round 2 review fixes: the API refusal paragraph and the agent CLI g"pipelex/cli/error_handlers.py" = "blob:4b97a9c89d9b2532f0a9d1406baad130fc4d56f7""pipelex/cli/exceptions.py" = "blob:1d51c3a53ddd3f6cf8de566fa2ade3fa75ab7a3a""pipelex/cli/installed_methods.py" = "blob:09197f47baf8d7251d28d148a0544b4a23ee7365"-"pipelex/cli/method_resolver.py" = "blob:1230dde5f89ac28bbdcbcbbd0c1d485c71803caf"+"pipelex/cli/method_resolver.py" = "blob:afaf77b2d8b6a3467d6ab1f355b1ee78a71eafa7""pipelex/cli/readiness.py" = "blob:6d185324ed0784663e1dc78d1194a28312c54798""pipelex/cli/version_report.py" = "blob:f4a2311bb629bd77196ea2f6b031c166db0d362a"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 72151a5a3..e5d9e635f 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -25,7 +25,7 @@- **Every template renders in a sandbox (Breaking)**: prompts, compose and construct templates, image and search prompts and condition expressions may read data and call methods of plain values (strings, numbers, dates, containers) only, so a template that reaches for a Python internal, calls a method of a Pipelex or pydantic object, or reads a name starting with an underscore other than an input's `_stuff_name`, `_content_class`, `_concept_code` and `_stuff_code` raises `Jinja2TemplateSecurityError` instead of rendering, and validation refuses the visible cases with the new `template_private_name` error. `_content` and the `stuff` property are no longer readable on an input, and bracket access and `get` on an input resolve only its content fields and metadata fields; a plain dict's keys stay readable with brackets, `record['_id']` included, and a `namespace()` holds data only, refusing a callable. The `jinja2` floor rises to 3.1.6, the release carrying Jinja's own sandbox fix for the `attr` filter.- **Dotted paths refuse underscore segments**: a PipeCompose construct `from` path such as `note.__class__.__init__.__globals__.sys.modules.os.environ` walked into Python internals with plain `getattr` and could copy the process environment into a method's output. A `from` path or `list_to_dict_keyed_by` name with a segment starting with an underscore is now refused at validation, and every dotted path the runtime walks, batch lists and prompt image references included, refuses one.- **A scoped run reads only under its read scope, and never the local disk**: on a run with a read scope, a `pipelex-storage://` key is read only when it lies under that scope, compared segment by segment, and a bare path or a `file://` URI is never read, whichever value carries it — an input, a `PipeCompose` construct that assembles a URL from text, a model's structured output. Every content-generation leaf checks the URLs it will read before the dry-run branch, and the input seam checks a CSV input and every file it would upload or sign; a refused read raises `UriReadRefusedError`, answered as a 422, which names where the URL sat without quoting it. A run whose read scope is `None` reads as before.-- **A sandbox-hosted load imports no method Python, and refuses structure classes (Breaking)**: on a deployment whose PipeFunc execution mode is not `direct`, loading a library directory captures every `.py` file as source for the sandbox and imports none of them, where a file declaring a `StructuredContent` subclass was imported into the loading process and its module-level code ran. A load whose Python declares such a class, however the method arrived, now raises `MethodStructuresRefusedError` naming each file and class by its relative path, the error a fetched package already got: declare the types as MTHDS concepts with inline structures, which a PipeFunc imports in the sandbox from the generated `structures` module. The module `pipelex build structures` writes is accepted while it is left as generated, by this refusal and by the fetched-package one, and is not sent to the sandbox, which generates its own from the same concepts. A `direct` load is unchanged.+- **A sandbox-hosted load imports no method Python, and refuses structure classes (Breaking)**: on a deployment whose PipeFunc execution mode is not `direct`, loading a library directory captures every `.py` file as source for the sandbox and imports none of them, where a file declaring a `StructuredContent` subclass was imported into the loading process and its module-level code ran. A load whose Python declares such a class, however the method arrived, now raises `MethodStructuresRefusedError` naming each file and class by its relative path, the error a fetched package already got: declare the types as MTHDS concepts with inline structures, which a PipeFunc imports in the sandbox from the generated `structures` module. The module `pipelex build structures` writes is accepted while it is left as generated, by this refusal and by the fetched-package one, and is not sent to the sandbox, which generates its own from the same concepts. Both refusals, and the local warnings that predict them, now give that same route. A `direct` load is unchanged.## [v0.69.0] - 2026-09-28diff --git a/docs/tools/cli/run-by-address.md b/docs/tools/cli/run-by-address.mdindex a76151538..b4151ae4e 100644--- a/docs/tools/cli/run-by-address.md+++ b/docs/tools/cli/run-by-address.md@@ -56,7 +56,7 @@ What decides whether Python in a method is acceptable is **where it would execut- `.mthds` content is data — always fine.- **PipeFunc `.py`** is supported: on hosted deployments it executes in a network-blocked sandbox, never in the runner's process.-- **Python structure classes** (`StructuredContent` subclasses) are imported into the runner's own process, so *hosted execution accepts MTHDS concepts and sandboxed PipeFuncs, not in-process Python*. A fetched method declaring structure classes runs locally, but the CLI prints a hosted-parity warning: express the types as MTHDS concepts (inline structures) to keep the method hosted-runnable.+- **Python structure classes** (`StructuredContent` subclasses) would have to be imported into the runner's own process to back a concept, so *hosted execution accepts MTHDS concepts and sandboxed PipeFuncs, not in-process Python*. A fetched method declaring structure classes runs locally, but the CLI prints a hosted-parity warning with the route: declare the types as MTHDS concepts with inline structures, and have a PipeFunc import the classes the sandbox generates from them (`from structures import <domain>__<Concept>`). The module `pipelex build structures` writes is accepted as long as it is left as generated.## Boundsdiff --git a/pipelex/cli/method_resolver.py b/pipelex/cli/method_resolver.pyindex 1230dde5f..afaf77b2d 100644--- a/pipelex/cli/method_resolver.py+++ b/pipelex/cli/method_resolver.py@@ -19,6 +19,7 @@ from pipelex.methods.exceptions import MethodRefErrorfrom pipelex.methods.fetching import fetch_method_packagefrom pipelex.methods.method_ref import looks_like_method_ref, parse_method_reffrom pipelex.methods.structures_check import (+ STRUCTURES_REFUSAL_REMEDY,STRUCTURES_REFUSAL_RULE,describe_structured_content_violations,scan_structured_content_classes,@@ -149,7 +150,7 @@ def resolve_method_from_ref(ref_str: str) -> InstalledMethod:details = describe_structured_content_violations(violations=violations)typer.secho(f"Warning: this method declares Python structure classes ({details}). It runs locally, but {STRUCTURES_REFUSAL_RULE} — "- f"hosted execution would refuse it. Express the types as MTHDS concepts to keep the method hosted-runnable.",+ f"hosted execution would refuse it. {STRUCTURES_REFUSAL_REMEDY}",fg=typer.colors.YELLOW,err=True,)diff --git a/pipelex/methods/fetch_on_miss.py b/pipelex/methods/fetch_on_miss.pyindex b6fe18162..9f9f04721 100644--- a/pipelex/methods/fetch_on_miss.py+++ b/pipelex/methods/fetch_on_miss.py@@ -26,6 +26,7 @@ from pipelex.methods.exceptions import (from pipelex.methods.fetching import fetch_method_packagefrom pipelex.methods.method_ref import MethodRef, looks_like_method_ref, parse_method_reffrom pipelex.methods.structures_check import (+ STRUCTURES_REFUSAL_REMEDY,STRUCTURES_REFUSAL_RULE,describe_structured_content_violations,scan_structured_content_classes,@@ -139,8 +140,7 @@ def resolve_address_based_method(details = describe_structured_content_violations(violations=violations)log.warning(f"Method '{fetched.full_address}' declares Python structure classes ({details}). It runs locally, but "- f"{STRUCTURES_REFUSAL_RULE} — hosted execution would refuse it. Express the types as MTHDS concepts "- f"to keep the method hosted-runnable."+ f"{STRUCTURES_REFUSAL_RULE} — hosted execution would refuse it. {STRUCTURES_REFUSAL_REMEDY}")name = fetched.manifest.name or fetched.package_dir.namediff --git a/pipelex/methods/structures_check.py b/pipelex/methods/structures_check.pyindex c0a6037c3..585132be7 100644--- a/pipelex/methods/structures_check.py+++ b/pipelex/methods/structures_check.py@@ -46,6 +46,13 @@ STRUCTURE_BASE_CLASS_NAME = "StructuredContent"STRUCTURES_REFUSAL_RULE = "hosted execution accepts MTHDS concepts and sandboxed PipeFuncs, not in-process Python"+# What every message about the rule tells the author to do, whether it refuses or only predicts a refusal.+STRUCTURES_REFUSAL_REMEDY = (+ "Declare these types as MTHDS concepts with inline structures; a PipeFunc can return them by importing the classes "+ "the sandbox generates from those concepts (`from structures import <domain>__<Concept>`). A structures module "+ "generated by `pipelex build structures` is accepted as long as it is left as generated."+)+_SKIPPED_DIR_NAMES = {".git", "__pycache__"}@@ -211,9 +218,8 @@ def ensure_no_structured_content_python(*, package_dir: Path, package_address: sreturndetails = describe_structured_content_violations(violations=violations)msg = (- f"Method package '{package_address}' declares Python structure classes ({details}), which are imported "- f"into the runner's own process. Refused: {STRUCTURES_REFUSAL_RULE}. Express the types as MTHDS concepts "- f"with inline structures instead of Python classes."+ f"Method package '{package_address}' declares Python structure classes ({details}), which would be imported "+ f"into the runner's own process. Refused: {STRUCTURES_REFUSAL_RULE}. {STRUCTURES_REFUSAL_REMEDY}")raise MethodStructuresRefusedError(msg)@@ -244,9 +250,6 @@ def ensure_no_structured_content_in_library_sources(*, sources_by_dir: Mapping[Pdetails = describe_structured_content_violations(violations=violations)msg = (f"This method declares Python structure classes ({details}), which would be imported into the runner's "- f"own process. Refused: {STRUCTURES_REFUSAL_RULE}. Declare these types as MTHDS concepts with inline "- f"structures; a PipeFunc can return them by importing the classes the sandbox generates from those "- f"concepts (`from structures import <domain>__<Concept>`). A structures module generated by "- f"`pipelex build structures` is accepted as long as it is left as generated."+ f"own process. Refused: {STRUCTURES_REFUSAL_RULE}. {STRUCTURES_REFUSAL_REMEDY}")raise MethodStructuresRefusedError(msg)diff --git a/tests/unit/pipelex/cli/test_method_resolver.py b/tests/unit/pipelex/cli/test_method_resolver.pyindex 80ba32fc7..af5eaea2a 100644--- a/tests/unit/pipelex/cli/test_method_resolver.py+++ b/tests/unit/pipelex/cli/test_method_resolver.py@@ -18,6 +18,7 @@ from pipelex.cli.method_resolver import (resolve_method_target,)from pipelex.methods.exceptions import MethodFetchError, MethodPackageNotFoundError, MethodRefParseError+from pipelex.methods.structures_check import STRUCTURES_REFUSAL_REMEDYif TYPE_CHECKING:from pytest_mock import MockerFixture@@ -168,6 +169,7 @@ class TestResolveMethodTarget:assert method.name == "remote_method"warning_calls = [call for call in secho_spy.call_args_list if "hosted execution would refuse" in str(call)]assert len(warning_calls) == 1+ assert STRUCTURES_REFUSAL_REMEDY in warning_calls[0].args[0]def test_resolve_method_target_dispatches_bare_address(self, mocker: MockerFixture, tmp_path: Path) -> None:"""A bare github.com address dispatches to the fetch arm, not the local-path arm."""diff --git a/tests/unit/pipelex/methods/test_fetch_on_miss.py b/tests/unit/pipelex/methods/test_fetch_on_miss.pyindex e3781a81a..1c71ac4b3 100644--- a/tests/unit/pipelex/methods/test_fetch_on_miss.py+++ b/tests/unit/pipelex/methods/test_fetch_on_miss.py@@ -19,6 +19,7 @@ from pipelex.methods.exceptions import (from pipelex.methods.fetch_on_miss import resolve_address_based_methodfrom pipelex.methods.fetching import FetchedMethodPackage, MethodProvenancefrom pipelex.methods.method_ref import parse_method_ref+from pipelex.methods.structures_check import STRUCTURES_REFUSAL_REMEDYif TYPE_CHECKING:from pathlib import Path@@ -40,6 +41,14 @@ main_pipe = "compute"pipes = ["compute"]"""+STRUCTURES_MODULE = """\+from pipelex.core.stuffs.structured_content import StructuredContent+++class Invoice(StructuredContent):+ total: float+"""+def _make_package_dir(base: Path) -> Path:package_dir = base / "fetched-pkg"@@ -198,6 +207,24 @@ class TestResolveAddressBasedMethod:assert exc_info.value is refusalassert fetch_mock.call_args.kwargs["refuse_structures"] is True+ @pytest.mark.usefixtures("isolated_methods_dirs")+ def test_local_fetch_of_structures_warns_with_the_remedy(self, tmp_path: Path, mocker: MockerFixture) -> None:+ """Locally a structure-declaring package still installs, and the warning predicting the hosted refusal gives its remedy."""+ mocker.patch("pipelex.methods.fetch_on_miss.is_method_fetch_on_miss_enabled", return_value=True)+ mocker.patch("pipelex.methods.fetch_on_miss.is_pipe_func_sandbox_hosted", return_value=False)+ package_dir = _make_package_dir(tmp_path)+ (package_dir / "structures.py").write_text(STRUCTURES_MODULE, encoding="utf-8")+ mocker.patch("pipelex.methods.fetch_on_miss.fetch_method_package", return_value=_make_fetched(package_dir))+ warning_spy = mocker.patch("pipelex.methods.fetch_on_miss.log.warning")++ resolved = resolve_address_based_method(full_address=FULL_ADDRESS)++ assert (resolved.path / "structures.py").is_file()+ warning_messages = [call.args[0] for call in warning_spy.call_args_list if "hosted execution would refuse" in call.args[0]]+ assert len(warning_messages) == 1+ assert "Invoice" in warning_messages[0]+ assert STRUCTURES_REFUSAL_REMEDY in warning_messages[0]+@pytest.mark.usefixtures("isolated_methods_dirs")def test_fetched_provenance_records_the_bare_address_fetch(self, tmp_path: Path, mocker: MockerFixture) -> None:"""A bare-address fetch records provenance with no tag."""diff --git a/tests/unit/pipelex/methods/test_structures_check.py b/tests/unit/pipelex/methods/test_structures_check.pyindex cf14eaa44..11d0baa98 100644--- a/tests/unit/pipelex/methods/test_structures_check.py+++ b/tests/unit/pipelex/methods/test_structures_check.py@@ -11,6 +11,7 @@ from pipelex.codegen.emitters.target import CodegenKind, CodegenTargetfrom pipelex.codegen.stamp import apply_stampfrom pipelex.methods.exceptions import MethodStructuresRefusedErrorfrom pipelex.methods.structures_check import (+ STRUCTURES_REFUSAL_REMEDY,STRUCTURES_REFUSAL_RULE,StructuredContentViolation,ensure_no_structured_content_in_library_sources,@@ -110,7 +111,7 @@ class TestStructuresCheck:ensure_no_structured_content_python(package_dir=tmp_path, package_address="github.com/acme/funcs-only")def test_refusal_names_the_rule(self, tmp_path: Path) -> None:- """The refusal error names the rule and the offending classes."""+ """The refusal error names the rule, the offending classes and the same route as the load-time refusal."""(tmp_path / "structures.py").write_text(STRUCTURES_MODULE, encoding="utf-8")with pytest.raises(MethodStructuresRefusedError) as exc_info:@@ -120,7 +121,8 @@ class TestStructuresCheck:assert STRUCTURES_REFUSAL_RULE in messageassert "github.com/acme/bad-package" in messageassert "Invoice" in message- assert "MTHDS concepts" in message+ assert "would be imported into the runner's own process" in message+ assert STRUCTURES_REFUSAL_REMEDY in messagedef test_from_import_alias_is_detected(self, tmp_path: Path) -> None:"""`from ... import StructuredContent as SC` does not bypass the refusal."""@@ -235,7 +237,7 @@ class TestStructuresCheck:message = str(exc_info.value)assert "structures/invoice.py defines Invoice, LineItem; models/receipt.py defines Invoice" in messageassert STRUCTURES_REFUSAL_RULE in message- assert "MTHDS concepts with inline structures" in message+ assert STRUCTURES_REFUSAL_REMEDY in messageassert "from structures import <domain>__<Concept>" in messageassert "funcs.py" not in messageassert str(tmp_path) not in message