maf-sandbox-codeact 0.21.4__tar.gz → 0.22.0__tar.gz

{maf_sandbox_codeact-0.21.4 → maf_sandbox_codeact-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maf-sandbox-codeact
-Version: 0.21.4
+Version: 0.22.0
 Summary: CodeAct as a Microsoft Agent Framework tool — the model writes a short Python program and it runs inside a sandbox — written against maf-sandbox so it runs on any sandbox backend.
 Keywords: codeact,code-execution,sandbox,agent-framework,microsoft-agent-framework
 Author: SOKOLAI BV
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Interpreters
-Requires-Dist: maf-sandbox>=0.46.0,<0.47
+Requires-Dist: maf-sandbox>=0.47.0,<0.48
 Requires-Dist: agent-framework-core>=1.19.0,<1.20
 Requires-Python: >=3.12, <3.15
 Project-URL: Homepage, https://www.sokol.ai
@@ -52,7 +52,7 @@ tools = make_codeact_tools(
 
 The host supplies the router and `CallerContext`. With no configured backend the factory returns `[]`. Unsupported requirements are refused before attachment.
 
-The default path writes `program.py` and runs it with `python3`. It requires `EXEC` and `FILES_IN`. Source text is file content, never part of the command line.
+The default path requests a backend-owned `python-portable-v1` channel, preferring exec. This profile promises Python 3.11+ with `json`, `math`, `re`, `sys` and `types`; it promises no other imports or retained state. The exec channel verifies CPython and owns `program.py`, the interpreter and any host-tool transport. Source text is file content, never part of the command line. See [channel selection and migration](https://github.com/sokolaidev/maf-extensions/blob/main/docs/sandbox/program-channels.md).
 
 Use the [Docker sample](https://github.com/sokolaidev/maf-extensions/tree/main/samples/06_docker_codeact), [ACAS sample](https://github.com/sokolaidev/maf-extensions/tree/main/samples/03_acas_codeact) or [WSLC sample](https://github.com/sokolaidev/maf-extensions/tree/main/samples/04_wslc_codeact) for complete applications.
 
@@ -64,7 +64,7 @@ All four channels below are off by default. The host enables them when building
 |---|---|
 | `file_store=store` | A `files` argument selecting caller-visible input files. |
 | `output_sink=sink`, `outputs=...` | Collection and delivery of named output files. |
-| `host_tools=registry` | Calls from guest Python to registered host functions, in exec mode. |
+| `host_tools=registry` | Calls from guest Python to registered host functions through a supporting program channel. |
 | `egress_allow=(...)` | Network requests to named destinations. |
 
 These channels operate during `execute_code`. Hiding its final report does not undo host calls, network requests or artifact delivery.
@@ -101,10 +101,12 @@ tools = make_codeact_tools(
 )
 ```
 
-`files_in` and `files_out` bound file count, individual bytes and total bytes. A missing declared output is reported. Artifacts carry no guest-selected media type; the host decides how to handle them.
+`files_in` and `files_out` bound shared-file count, individual bytes and total bytes. Shared inputs default to 8 MiB per file, 24 MiB total and 63 files, leaving room for the default 8 MiB program and its staging file within a 32 MiB/64-file backend ceiling. Explicit limits are preserved and the complete channel demand is checked without clamping; larger programs or host-tool transport traffic can require a backend with larger ceilings. On the automatic channel path, `program=ProgramRequirements(max_program_bytes=8 * 1024 * 1024, host_tool_timeout_seconds=30)` from `maf_sandbox` configures source bytes and callback time separately. A missing declared output is reported. Artifacts carry no guest-selected media type; the host decides how to handle them.
 
 Keep the output sink separate from the agent's writable input store. Otherwise guest code could overwrite files through a channel that bypasses the host's file-write approval. See the [files sample](https://github.com/sokolaidev/maf-extensions/tree/main/samples/08_docker_codeact_files).
 
+With `withhold_guest_output=True`, a sink can supply `locate=lambda name: f".tool-results/execute_code/{name}"` to report a fixed landing folder in the Saved and not-written lists. Have `deliver` write to the same location and return it in `LandedArtifact.name` or `handle`. The pure synchronous locator receives only validated declared names, normalized as the sink requests; it must never depend on guest content or delivery state. A mismatched receipt falls back to the declared name and logs a warning. The default locator preserves existing results, and `per_call` sinks retain their folder-only reporting. See the [withholding contract](https://github.com/sokolaidev/maf-extensions/blob/main/docs/sandbox/kinds/codeact.md#withholding-guest-output) for the information this mode still reveals.
+
 ## Host functions and network access
 
 Register host functions before passing the registry to the factory. Reading its combined policy seals it against later registration.
@@ -125,7 +127,7 @@ registry.register(exchange_rate)
 
 `exchange_rate` is a host-defined function. Its body runs with host authority and bypasses ordinary agent middleware. Configure declarations, permitted identities and approval policy before exposing it. Registering a user-authority function makes the enclosing tool approval-gated.
 
-A nonempty registry requires `HOST_TOOLS` and `FILES_OUT` as well as `EXEC` and `FILES_IN`. Docker and ACAS support this transport; WSLC does not. The image needs the POSIX launcher utilities, including `sh` and `nohup`.
+A nonempty registry requires `HOST_TOOLS` and an explicit supporting program channel. Docker, ACAS and Docker Sandboxes supply the exec channel, which adds `EXEC`, `FILES_IN` and `FILES_OUT` internally. WSLC supports programs without host tools. The exec image needs the POSIX launcher utilities, including `sh` and `nohup`. Hyperlight native host tools remain pending.
 
 Transport traffic counts toward backend transfer limits. Set response limits to fit your functions; broad defaults can make the tool fail attachment. Model-named files live separately from transport files. Without a registry, `program.py` is reserved.
 

{maf_sandbox_codeact-0.21.4 → maf_sandbox_codeact-0.22.0}/README.md

@@ -27,7 +27,7 @@ tools = make_codeact_tools(
 
 The host supplies the router and `CallerContext`. With no configured backend the factory returns `[]`. Unsupported requirements are refused before attachment.
 
-The default path writes `program.py` and runs it with `python3`. It requires `EXEC` and `FILES_IN`. Source text is file content, never part of the command line.
+The default path requests a backend-owned `python-portable-v1` channel, preferring exec. This profile promises Python 3.11+ with `json`, `math`, `re`, `sys` and `types`; it promises no other imports or retained state. The exec channel verifies CPython and owns `program.py`, the interpreter and any host-tool transport. Source text is file content, never part of the command line. See [channel selection and migration](https://github.com/sokolaidev/maf-extensions/blob/main/docs/sandbox/program-channels.md).
 
 Use the [Docker sample](https://github.com/sokolaidev/maf-extensions/tree/main/samples/06_docker_codeact), [ACAS sample](https://github.com/sokolaidev/maf-extensions/tree/main/samples/03_acas_codeact) or [WSLC sample](https://github.com/sokolaidev/maf-extensions/tree/main/samples/04_wslc_codeact) for complete applications.
 
@@ -39,7 +39,7 @@ All four channels below are off by default. The host enables them when building
 |---|---|
 | `file_store=store` | A `files` argument selecting caller-visible input files. |
 | `output_sink=sink`, `outputs=...` | Collection and delivery of named output files. |
-| `host_tools=registry` | Calls from guest Python to registered host functions, in exec mode. |
+| `host_tools=registry` | Calls from guest Python to registered host functions through a supporting program channel. |
 | `egress_allow=(...)` | Network requests to named destinations. |
 
 These channels operate during `execute_code`. Hiding its final report does not undo host calls, network requests or artifact delivery.
@@ -76,10 +76,12 @@ tools = make_codeact_tools(
 )
 ```
 
-`files_in` and `files_out` bound file count, individual bytes and total bytes. A missing declared output is reported. Artifacts carry no guest-selected media type; the host decides how to handle them.
+`files_in` and `files_out` bound shared-file count, individual bytes and total bytes. Shared inputs default to 8 MiB per file, 24 MiB total and 63 files, leaving room for the default 8 MiB program and its staging file within a 32 MiB/64-file backend ceiling. Explicit limits are preserved and the complete channel demand is checked without clamping; larger programs or host-tool transport traffic can require a backend with larger ceilings. On the automatic channel path, `program=ProgramRequirements(max_program_bytes=8 * 1024 * 1024, host_tool_timeout_seconds=30)` from `maf_sandbox` configures source bytes and callback time separately. A missing declared output is reported. Artifacts carry no guest-selected media type; the host decides how to handle them.
 
 Keep the output sink separate from the agent's writable input store. Otherwise guest code could overwrite files through a channel that bypasses the host's file-write approval. See the [files sample](https://github.com/sokolaidev/maf-extensions/tree/main/samples/08_docker_codeact_files).
 
+With `withhold_guest_output=True`, a sink can supply `locate=lambda name: f".tool-results/execute_code/{name}"` to report a fixed landing folder in the Saved and not-written lists. Have `deliver` write to the same location and return it in `LandedArtifact.name` or `handle`. The pure synchronous locator receives only validated declared names, normalized as the sink requests; it must never depend on guest content or delivery state. A mismatched receipt falls back to the declared name and logs a warning. The default locator preserves existing results, and `per_call` sinks retain their folder-only reporting. See the [withholding contract](https://github.com/sokolaidev/maf-extensions/blob/main/docs/sandbox/kinds/codeact.md#withholding-guest-output) for the information this mode still reveals.
+
 ## Host functions and network access
 
 Register host functions before passing the registry to the factory. Reading its combined policy seals it against later registration.
@@ -100,7 +102,7 @@ registry.register(exchange_rate)
 
 `exchange_rate` is a host-defined function. Its body runs with host authority and bypasses ordinary agent middleware. Configure declarations, permitted identities and approval policy before exposing it. Registering a user-authority function makes the enclosing tool approval-gated.
 
-A nonempty registry requires `HOST_TOOLS` and `FILES_OUT` as well as `EXEC` and `FILES_IN`. Docker and ACAS support this transport; WSLC does not. The image needs the POSIX launcher utilities, including `sh` and `nohup`.
+A nonempty registry requires `HOST_TOOLS` and an explicit supporting program channel. Docker, ACAS and Docker Sandboxes supply the exec channel, which adds `EXEC`, `FILES_IN` and `FILES_OUT` internally. WSLC supports programs without host tools. The exec image needs the POSIX launcher utilities, including `sh` and `nohup`. Hyperlight native host tools remain pending.
 
 Transport traffic counts toward backend transfer limits. Set response limits to fit your functions; broad defaults can make the tool fail attachment. Model-named files live separately from transport files. Without a registry, `program.py` is reserved.
 

{maf_sandbox_codeact-0.21.4 → maf_sandbox_codeact-0.22.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "maf-sandbox-codeact"
-version = "0.21.4"
+version = "0.22.0"
 description = "CodeAct as a Microsoft Agent Framework tool — the model writes a short Python program and it runs inside a sandbox — written against maf-sandbox so it runs on any sandbox backend."
 readme = "README.md"
 requires-python = ">=3.12,<3.15"
@@ -24,7 +24,7 @@ classifiers = [
     "Topic :: Software Development :: Interpreters",
 ]
 dependencies = [
-    "maf-sandbox>=0.46.0,<0.47",
+    "maf-sandbox>=0.47.0,<0.48",
     "agent-framework-core>=1.19.0,<1.20",
 ]
 

{maf_sandbox_codeact-0.21.4 → maf_sandbox_codeact-0.22.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "maf-sandbox-codeact"
-version = "0.21.4"
+version = "0.22.0"
 description = "CodeAct as a Microsoft Agent Framework tool — the model writes a short Python program and it runs inside a sandbox — written against maf-sandbox so it runs on any sandbox backend."
 readme = "README.md"
 requires-python = ">=3.12,<3.15"
@@ -35,7 +35,7 @@ dependencies = [
     # import, and that one fails at the call, where no import check is looking. The number
     # itself is below, and `scripts/set_dependents_range.py` moves it — so this says which
     # release the floor is for, never which release that is.
-    "maf-sandbox>=0.46.0,<0.47",
+    "maf-sandbox>=0.47.0,<0.48",
     # The `@tool` decorator. MAF is a genuine dependency of the tool itself, not of the host
     # application. Both ends of the range are measured: 1.19 made an item's embedded label
     # restrict-only, which the result wrapper now works with rather than against.

{maf_sandbox_codeact-0.21.4 → maf_sandbox_codeact-0.22.0}/src/maf_sandbox_codeact/_tool.py

@@ -35,8 +35,6 @@ from typing import TYPE_CHECKING, Any, cast
 
 from maf_sandbox import (
     DEFAULT_TRANSFER_LIMITS,
-    SHIM_MODULE,
-    WORK_DIRECTORY,
     CallerContext,
     Capability,
     Cleanup,
@@ -50,6 +48,7 @@ from maf_sandbox import (
     ListedFile,
     NameNormalization,
     OutputSink,
+    ProgramRequirements,
     SandboxArtifactNameInvalid,
     SandboxOutputError,
     SandboxProgramTimeout,
@@ -61,9 +60,6 @@ from maf_sandbox import (
     collect_outputs,
     echoed_name,
     error_detail,
-    guest_run_layout,
-    host_tool_calls_over_exec,
-    host_tool_shim,
     validate_artifact_name,
 )
 from maf_sandbox.maf import (
@@ -81,10 +77,12 @@ if TYPE_CHECKING:
 
     from agent_framework import AgentFileStore
     from maf_sandbox import (
+        Artifact,
         FileStoreProvenance,
         HostToolAggregate,
         HostToolRegistry,
         LandedArtifact,
+        ProgramRequirements,
         Sandbox,
         SandboxKey,
     )
@@ -136,10 +134,10 @@ _SMALLEST_MANIFEST = len(
 #: time and cannot un-deliver, so "could not be saved" is not the same as "nothing was saved".
 _MAY_HAVE_LANDED = "Some of them may already have been saved; do not assume none were."
 
-_INTERPRETER = "python3"
-
 #: Eight artifacts is a generous single call and a cap that actually bounds something; the
 #: byte ceilings are the shared defaults, so only the count is this workload's own opinion.
+# Shared inputs leave room for the default program within a 32 MiB / 64-file backend.
+_DEFAULT_FILES_IN = replace(DEFAULT_TRANSFER_LIMITS, max_total_bytes=24 * 1024 * 1024, max_files=63)
 _DEFAULT_FILES_OUT = replace(DEFAULT_TRANSFER_LIMITS, max_files=8)
 
 #: Writing an expression and expecting a REPL to echo it is the commonest way a first CodeAct
@@ -201,11 +199,12 @@ def codeact_sandbox_spec(
     image_id: str | None = None,
     *,
     outputs: CodeactOutputs = CodeactOutputs.NONE,
-    files_in: TransferLimits = DEFAULT_TRANSFER_LIMITS,
+    files_in: TransferLimits = _DEFAULT_FILES_IN,
     files_out: TransferLimits = _DEFAULT_FILES_OUT,
     host_tools: HostToolRegistry | None = None,
     egress_allow: Sequence[str | EgressRule] = (),
     runtime: CodeactRuntime | None = None,
+    program: ProgramRequirements = ProgramRequirements(),
     takes_files: bool = False,
     credential_retention_seconds: int | None = None,
 ) -> SandboxSpec:
@@ -269,6 +268,7 @@ def codeact_sandbox_spec(
         surface=_host_tools(host_tools),
         egress_allow=egress_allow,
         runtime=runtime,
+        program=program,
         takes_files=takes_files,
         credential_retention_seconds=credential_retention_seconds,
     )
@@ -288,10 +288,11 @@ def make_codeact_tools(
     image: str | None = None,
     image_id: str | None = None,
     exec_timeout_seconds: int = 120,
-    files_in: TransferLimits = DEFAULT_TRANSFER_LIMITS,
+    files_in: TransferLimits = _DEFAULT_FILES_IN,
     files_out: TransferLimits = _DEFAULT_FILES_OUT,
     egress_allow: Sequence[str | EgressRule] = (),
     runtime: CodeactRuntime | None = None,
+    program: ProgramRequirements = ProgramRequirements(),
     credential_retention_seconds: int | None = None,
     file_store_provenance: FileStoreProvenance | None = None,
     requires_file_integrity: SourceIntegrity | None = None,
@@ -323,7 +324,7 @@ def make_codeact_tools(
             :data:`CodeactOutputs.NONE`, and refused at attach without one.
         outputs: How a program's output files are named. See :class:`CodeactOutputs`.
         withhold_guest_output: Keep what the program printed out of the tool result, and answer
-            with whether it exited cleanly and the model's own declared names instead. No
+            with whether it exited cleanly and the declared names or their sink locations. No
             guest-authored text survives into the result — but the values that replace it were
             still chosen by a program the model wrote. The workload therefore claims
             ``SourceIntegrity.UNTRUSTED`` for its derived report in both modes. The result
@@ -358,8 +359,9 @@ def make_codeact_tools(
             ``docs/sandbox/information-flow.md``.
 
             **What withholding gets you, exactly.** The prose and the shape are this package's,
-            and the artifact names are the model's own — but what fills them is the program's
-            to choose, and it is a channel rather than a leak-free boundary. Whether the program
+            and artifact locations depend only on declared names and host configuration — but
+            what fills them is the program's to choose, and it is a channel rather than a
+            leak-free boundary. Whether the program
             exited cleanly is one bit and whether it finished in time is another; **each
             declared output is one further bit**, since the program decides whether to write it
             and the result says of every declared name whether it landed — up to
@@ -453,36 +455,8 @@ def make_codeact_tools(
                 f"a non-empty host_tools registry makes it the guest's patience as well as the "
                 f"run's bound, so it must be a finite positive number of seconds."
             )
-        # Generated here, so the module the checks below measure is the one every call writes.
-        # Its patience is the run's own bound: give up first and a program is told the host
-        # never answered while the host-tool call it asked for goes on to act.
-        host_tool_call = _HostToolCall(
-            host_tools, host_tool_shim(host_tools.names(), call_timeout=exec_timeout_seconds)
-        )
-    if configured and runtime is None and files_in.max_files < 1:
-        # `program.py` is one inbound file on every call, so a cap below one refuses all of
-        # them. Every impossible pairing below is caught here rather than per call: a tool the
-        # model can see and can never use successfully is worse than one that never attached.
-        raise ValueError(
-            f"{EXECUTE_CODE_TOOL_NAME}: files_in.max_files is {files_in.max_files}, and the "
-            f"program itself is one file written into the sandbox on every call, so no call "
-            f"could succeed."
-        )
-    if host_tool_call is not None:
-        if files_in.max_files < 2:
-            raise ValueError(
-                f"{EXECUTE_CODE_TOOL_NAME}: files_in.max_files is {files_in.max_files}, and a "
-                f"non-empty host_tools registry puts the guest's host-tool module beside the "
-                f"program on every call, so no call could succeed."
-            )
-        crossing = len(host_tool_call.shim.encode())
-        room = min(files_in.max_bytes_per_file, files_in.max_total_bytes)
-        if crossing > room:
-            raise ValueError(
-                f"{EXECUTE_CODE_TOOL_NAME}: the guest's host-tool module is {crossing} bytes and "
-                f"crosses beside the program on every call, and this host's files_in allows "
-                f"{room}, so no call could succeed."
-            )
+        host_tool_call = _HostToolCall(host_tools)
+
     if configured and outputs is CodeactOutputs.DECLARED and files_out.max_files < 1:
         raise ValueError(
             f"{EXECUTE_CODE_TOOL_NAME}: outputs={str(CodeactOutputs.DECLARED)!r} shows the "
@@ -544,6 +518,7 @@ def make_codeact_tools(
         surface=surface,
         egress_allow=egress_allow if configured else (),
         runtime=runtime if configured else None,
+        program=program if configured else ProgramRequirements(),
         takes_files=file_store is not None,
         credential_retention_seconds=credential_retention_seconds if configured else None,
     )
@@ -694,24 +669,24 @@ def _codeact_spec(
     surface: HostToolAggregate | None,
     egress_allow: Sequence[str | EgressRule] = (),
     runtime: CodeactRuntime | None = None,
+    program: ProgramRequirements = ProgramRequirements(),
     takes_files: bool = False,
     credential_retention_seconds: int | None = None,
 ) -> SandboxSpec:
     """:func:`codeact_sandbox_spec`, over a host-tool surface the caller has already derived."""
     _validate_runtime(runtime, takes_files=takes_files, outputs=outputs)
+    if runtime is None and program.profile != "python-portable-v1":
+        raise ValueError("CodeAct requires the python-portable-v1 execution profile")
     if runtime is not None and surface is not None:
         raise ValueError("CodeAct runtime host tools require a native channel; not supported")
     collects = outputs is not CodeactOutputs.NONE
-    requires = {Capability.EXEC, Capability.FILES_IN} if runtime is None else {Capability.RUN_CODE}
+    requires: set[Capability] = set() if runtime is None else {Capability.RUN_CODE}
     if takes_files:
         requires.add(Capability.FILES_IN)
     if collects:
         requires.add(Capability.FILES_OUT)
     if surface is not None:
-        # FILES_OUT for the transport rather than for this kind's outputs: a host-tool call stats
-        # and reads its request files and the exit marker back over the pull surface, so even a
-        # stdout-only program that can call a host function needs one.
-        requires |= {Capability.HOST_TOOLS, Capability.FILES_OUT}
+        requires.add(Capability.HOST_TOOLS)
     # CodeAct runs model-written code, so it accepts only two postures and never UNRESTRICTED:
     # CLOSED to compute offline, ALLOWLIST to reach the deployment's named sources. The mode is
     # derived from whether any host was named — an allowlist with hosts is ALLOWLIST, an empty
@@ -738,7 +713,10 @@ def _codeact_spec(
         max_identity_scope=IdentityScope.PER_SANDBOX if authority else None,
         max_identity_retention_seconds=credential_retention_seconds,
         work_dir=runtime.guest_work_dir if runtime is not None else None,
-        execution_contract=runtime_contract(runtime),
+        execution_contract=runtime_contract(runtime)
+        if runtime is not None
+        else f"codeact:{program.profile}",
+        program=program if runtime is None else None,
         # Model-written code can write outside the call path and leave processes running.
         confined_to_guest_call_path=False,
         # And read whatever a sibling call put in the sandbox, so calls run one at a time.
@@ -873,8 +851,7 @@ _DESCRIPTION_HOST_TOOLS = """**To call a host tool, ``import maf_host_tools`` an
         The tools you may call this way are: {names}.  A refusal raises
         ``maf_host_tools.HostToolError``, whose message says why."""
 
-_DESCRIPTION_ARG_CODE = """code: The Python source to run.  The standard library, plus
-                whatever the sandbox image ships."""
+_DESCRIPTION_ARG_CODE = """code: The Python source to run using the profile described above."""
 
 _DESCRIPTION_ARG_FILES = """files: Store-relative paths to share into the sandbox, or
                 omit for none.  Only files in your file store listing can be shared."""
@@ -935,6 +912,19 @@ _DESCRIPTION_IN_PLACE_WITHHELD = """Naming a file in both ``files`` and ``output
 
 _DESCRIPTION_RETURNS_SAVED_WITHHELD = """  A call that saved files also names each one."""
 
+_DESCRIPTION_DECLARED_WITHHELD_LOCATED = """**To produce files, name them in ``outputs`` and
+        write them into the working directory.** They are saved to host storage after the
+        program exits. The result names their host-configured landing paths when delivery
+        confirms them, otherwise their declared names. A name you declare and do not write
+        is reported at its configured landing path. A file you write without declaring is
+        not saved. **A program that fails still saves what it wrote.** Saved files have not
+        been read back; do not claim to know their contents from this result."""
+
+_DESCRIPTION_IN_PLACE_WITHHELD_LOCATED = """Naming a file in both ``files`` and ``outputs``
+        edits the supplied copy; the saved copy goes to the sink's configured location.
+        The supplied copy is already present, so it cannot be reported as not written.
+        A failed program still saves whatever it had written by then."""
+
 #: The withholding pair again, for a host whose sink lands each call under a folder of its own.
 #: Two promises above stop being true: nothing names which files landed, so nothing reports a
 #: name declared and not written either. It names the folder without promising a reader for it,
@@ -966,6 +956,7 @@ def _tool_description(
     egress_allow: Sequence[str | EgressRule] = (),
     withhold: bool,
     lands_per_call: bool = False,
+    locates_outputs: bool = False,
     runtime: CodeactRuntime | None = None,
 ) -> str:
     """The description the model reads, for the channels this host actually wired.
@@ -992,7 +983,19 @@ def _tool_description(
             "*this* call is in it.",
             "Use only the runtime facilities described below.",
         )
+    else:
+        head = head.replace("as ``python3 program.py``", "with the ``python-portable-v1`` profile")
+        head = head.replace(
+            "Each call gets a fresh working\n        directory: nothing you did not pass in to "
+            "*this* call is in it.",
+            "Do not rely on state from earlier calls.",
+        )
     body = [head.format(network=network)]
+    if runtime is None:
+        body.append(
+            "Python 3.11 or newer is available with ``json``, ``math``, ``re``, ``sys`` and "
+            "``types``. Other standard-library modules and third-party packages are not promised."
+        )
     if runtime is not None:
         if runtime.guest_work_dir is not None:
             body.append(
@@ -1027,8 +1030,18 @@ def _tool_description(
             body.append(_DESCRIPTION_DECLARED_WITHHELD_PER_CALL)
             in_place = _DESCRIPTION_IN_PLACE_WITHHELD_PER_CALL
         else:
-            body.append(_DESCRIPTION_DECLARED_WITHHELD)
-            in_place = _DESCRIPTION_IN_PLACE_WITHHELD
+            body.append(
+                _DESCRIPTION_DECLARED_WITHHELD_LOCATED
+                if locates_outputs
+                else _DESCRIPTION_DECLARED_WITHHELD
+            )
+            in_place = (
+                _DESCRIPTION_IN_PLACE_WITHHELD_LOCATED
+                if locates_outputs
+                else _DESCRIPTION_IN_PLACE_WITHHELD
+            )
+        if withhold and lands_per_call and locates_outputs:
+            in_place = _DESCRIPTION_IN_PLACE_WITHHELD_LOCATED
         if takes_files:
             body.append(in_place)
         arguments.append(_DESCRIPTION_ARG_OUTPUTS)
@@ -1083,14 +1096,9 @@ def _tool_description(
 
 @dataclass(frozen=True)
 class _HostToolCall:
-    """What one attached tool serves host-tool calls with: the registry, and the guest module.
-
-    Generated once and written into every run, which the registry's sealing is what makes
-    honest: the names it spells cannot change after the factory has read them.
-    """
+    """The sealed registry from which each program receives a fresh policy run."""
 
     registry: HostToolRegistry
-    shim: str
 
 
 def _execute_code_tool(
@@ -1167,6 +1175,9 @@ def _execute_code_tool(
         egress_allow=session.spec.egress_allow,
         withhold=withhold,
         lands_per_call=lands_per_call,
+        locates_outputs=(
+            session.output_sink is not None and session.output_sink.locate is not OutputSink.locate
+        ),
         runtime=runtime,
     )
     return body
@@ -1227,9 +1238,7 @@ async def _execute(
     # writes. One sentence for both would be false about one of them.
     reserved: dict[str, str] = {}
     if host_tool_call is None and runtime is None:
-        reserved[_PROGRAM_FILENAME] = (
-            "this tool writes a file of that name into every call's directory"
-        )
+        reserved[_PROGRAM_FILENAME] = "this name is reserved for program execution"
     if outputs is CodeactOutputs.MANIFEST:
         reserved[_MANIFEST_FILENAME] = (
             "this tool reads a file of that name from every call's directory as its manifest"
@@ -1248,12 +1257,21 @@ async def _execute(
     # from, and what is collected out — so the three cannot disagree about one call's layout.
     # It is longer when calling a host tool, which is why the name checks below take it rather than
     # `call_id`: five more bytes of the 255 a guest path gets, spent before the name is.
-    guest_prefix = f"{call_id}/{WORK_DIRECTORY}" if host_tool_call is not None else call_id
+    guest_prefix = call_id
     if runtime is not None and not runtime.use_call_directory:
         guest_prefix = ""
 
     names: list[str] = []
     if outputs is CodeactOutputs.DECLARED:
+        if runtime is None:
+            prospective = session.prospective_program_channel(key)
+            if prospective is not None:
+                guest_prefix = _channel_output_prefix(
+                    call_directory,
+                    prospective.guest_working_directory(
+                        call_directory, host_tools=host_tool_call is not None
+                    ),
+                )
         checked = _validated_output_names(
             declared,
             max_files=session.spec.files_out.max_files,
@@ -1268,35 +1286,26 @@ async def _execute(
             return _stopped("Error: the outputs argument is invalid.", detail=checked)
         names = checked
 
-    # Cap before acquiring anything, and cap *as we go*: a bound that answers only once
-    # everything is in memory has already spent what it exists to bound. Every check below
-    # therefore happens before the read it would have prevented — the count before the listing,
-    # the program's own bytes before the store is touched at all, and each file's as it arrives.
-    # The tally covers the submitted program, an exec shim where wired, and each shared file.
-    # The transport's launcher and responses have their own limits.
     limits = session.spec.files_in
     tally = _InboundTally(limits)
     shared: list[tuple[str, str, str]] = []
-    inbound = len(files) + (0 if runtime is not None else 2 if host_tool_call is not None else 1)
     program = code
     if runtime is not None:
         refusal = _InboundTally(limits).add("", code, named="the program", program=True)
         if refusal is not None:
             return _stopped("Error: the program could not be staged.", detail=refusal)
         program = runtime_program(runtime, code, call_directory)
-    over_cap = _over_file_count(
-        inbound,
-        limits,
-        calls_host_tool=host_tool_call is not None,
-        program_is_file=runtime is None,
-    ) or tally.add(
-        _PROGRAM_FILENAME,
-        program,
-        named="the program" if runtime is not None else None,
-        program=runtime is not None,
-    )
-    if over_cap is None and host_tool_call is not None:
-        over_cap = tally.add(SHIM_MODULE, host_tool_call.shim)
+        refusal = tally.add("", program, named="the program", program=True)
+        if refusal is not None:
+            return _stopped("Error: the program could not be staged.", detail=refusal)
+    else:
+        try:
+            program_bytes = len(code.encode("utf-8"))
+        except UnicodeEncodeError:
+            return _stopped("Error: the program is not valid UTF-8.")
+        if session.spec.program is None or program_bytes > session.spec.program.max_program_bytes:
+            return _stopped("Error: the program exceeds its declared byte limit.")
+    over_cap = _over_file_count(len(files), limits, calls_host_tool=False, program_is_file=False)
     if over_cap is not None:
         return _stopped("Error: the call's inputs could not be staged.", detail=over_cap)
     if store is not None:
@@ -1317,18 +1326,28 @@ async def _execute(
     if isinstance(sandbox, str):
         return _stopped("Error: the sandbox could not be acquired.", detail=sandbox)
 
-    # The session owns this path, and `sandboxed_tool` cleans the sandbox when the call returns.
-    # Built before anything is written, because it decides where everything goes. A call that
-    # calls a host tool is two directories — the model's files in `work`, the program and the shim
-    # in the transport's — and one that does not is the call directory flat, which is what a kind
-    # writing no shim has always been. The program name and the interpreter are passed rather
-    # than defaulted, so this kind's constants and the transport's cannot drift apart.
-    layout = (
-        guest_run_layout(call_directory, program=_PROGRAM_FILENAME)
-        if host_tool_call is not None
-        else None
+    channel = session.program_channel(key, sandbox) if runtime is None else None
+    shared_dir = (
+        channel.guest_working_directory(call_directory, host_tools=host_tool_call is not None)
+        if channel is not None
+        else call_directory
     )
-    shared_dir = layout.work if layout is not None else call_directory
+    if channel is not None:
+        guest_prefix = _channel_output_prefix(call_directory, shared_dir)
+    if runtime is None and outputs is CodeactOutputs.DECLARED:
+        checked = _validated_output_names(
+            declared,
+            max_files=session.spec.files_out.max_files,
+            reserved=reserved,
+            guest_prefix=guest_prefix,
+            normalization=_normalization(session),
+            named_by=_OUTPUTS_ARGUMENT,
+            argument=_OUTPUTS_ARGUMENT,
+            candidates=rewritten,
+        )
+        if isinstance(checked, str):
+            return _stopped("Error: the outputs argument is invalid.", detail=checked)
+        names = checked
 
     for name, named, content in shared:
         refusal = await _write_shared(
@@ -1339,45 +1358,20 @@ async def _execute(
                 "Error: an input file could not be written into the sandbox.", detail=refusal
             )
 
-    program_path = layout.program if layout is not None else f"{call_directory}/{_PROGRAM_FILENAME}"
     try:
-        if runtime is None:
-            await sandbox.write_file(
-                posixpath.relpath(
-                    program_path, layout.directory if layout is not None else call_directory
-                ),
-                code,
-                working_directory=layout.directory if layout is not None else call_directory,
-            )
-    except Exception as exc:  # noqa: BLE001
-        logger.warning(
-            "execute_code: could not write the program into the sandbox: %s", error_detail(exc)
-        )
-        return _stopped("Error: could not write the program into the sandbox")
-
-    try:
-        # The two are built together above and are never one without the other; both are named
-        # here so neither has to be narrowed from the other.
         if runtime is not None:
             result = await sandbox.run_code(program, timeout=timeout)
-        elif host_tool_call is not None and layout is not None:
-            await sandbox.write_file(
-                posixpath.relpath(layout.shim, layout.directory),
-                host_tool_call.shim,
-                working_directory=layout.directory,
-            )
-            # A fresh run per call: the host-tool-call cap and the ledger bound one program.
-            result = await host_tool_calls_over_exec(
+        else:
+            assert channel is not None and session.spec.program is not None
+            result = await channel.run(
                 sandbox,
-                HostToolRun(host_tool_call.registry, logger=logger, key=key),
-                layout,
+                code,
+                requirements=session.spec.program,
+                guest_call_path=call_directory,
                 timeout=timeout,
-                interpreter=_INTERPRETER,
-            )
-        else:
-            # An argv sequence, never a command line: the model's source never reaches a shell.
-            result = await sandbox.exec(
-                [_INTERPRETER, _PROGRAM_FILENAME], working_directory=call_directory, timeout=timeout
+                policy=HostToolRun(host_tool_call.registry, logger=logger, key=key)
+                if host_tool_call
+                else None,
             )
     except SandboxQueuedTimeout:
         logger.warning("execute_code: the deadline expired before the queued program started")
@@ -1740,6 +1734,13 @@ async def _write_shared(
 # --- Files out -----------------------------------------------------------------------------
 
 
+def _channel_output_prefix(guest_call_path: str, guest_working_directory: str) -> str:
+    call_id = guest_call_path.rsplit("/", 1)[-1]
+    return posixpath.normpath(
+        f"{call_id}/{posixpath.relpath(guest_working_directory, guest_call_path)}"
+    )
+
+
 def _normalization(session: SandboxToolSession) -> NameNormalization:
     """What the attached sink does to a name, which decides the spelling to judge."""
     sink = session.output_sink
@@ -1877,7 +1878,11 @@ async def _collect(
         DeclaredOutput(path=posixpath.join(guest_prefix, name), name=name, required=False)
         for name in declared
     )
+    locations: dict[str, str] = {}
+    delivered_names: list[str] | None = None
     try:
+        if withhold and not sink.per_call and sink.locate is not OutputSink.locate:
+            sink, locations, delivered_names = _located_sink(sink, declared)
         landed = await collect_outputs(
             sandbox,
             spec,
@@ -1911,9 +1916,40 @@ async def _collect(
         named_by=_MANIFEST_FILENAME if outputs is CodeactOutputs.MANIFEST else _OUTPUTS_ARGUMENT,
         argument=None if outputs is CodeactOutputs.MANIFEST else _OUTPUTS_ARGUMENT,
         candidates=candidates,
+        locations=locations,
+        delivered_names=delivered_names,
     )
 
 
+def _located_sink(
+    sink: OutputSink, declared: Sequence[str]
+) -> tuple[OutputSink, dict[str, str], list[str]]:
+    """Calculate locations before reading guest bytes, then check each delivery receipt."""
+    locations = {
+        name: sink.locate(
+            unicodedata.normalize("NFC", name)
+            if sink.normalization is NameNormalization.NFC
+            else name
+        )
+        for name in declared
+    }
+    originals = {unicodedata.normalize("NFC", name): name for name in declared}
+    delivered_names: list[str] = []
+
+    async def deliver(artifact: Artifact) -> LandedArtifact:
+        accepted = await sink.deliver(artifact)
+        name = originals[unicodedata.normalize("NFC", artifact.name)]
+        if locations[name] not in (accepted.name, accepted.handle):
+            logger.warning(
+                "execute_code: output sink locate disagrees with delivery; using declared name"
+            )
+            locations[name] = name
+        delivered_names.append(artifact.name)
+        return accepted
+
+    return replace(sink, deliver=deliver), locations, delivered_names
+
+
 async def _read_manifest(
     session: SandboxToolSession, sandbox: Sandbox, guest_prefix: str
 ) -> tuple[list[str], int] | str:
@@ -2000,6 +2036,8 @@ def _format_landed(
     named_by: str = _OUTPUTS_ARGUMENT,
     argument: str | None = None,
     candidates: frozenset[str] | None = None,
+    locations: Mapping[str, str] | None = None,
+    delivered_names: Sequence[str] | None = None,
 ) -> str:
     """What the model is told about the files: what landed, and what is absent.
 
@@ -2015,14 +2053,20 @@ def _format_landed(
     before it: without it a declared name equal to hidden content renders as a position, and a
     caller watching which way its own spelling comes back learns that the guess was right.
 
-    ``withhold`` drops ``display`` in favour of the name the model itself declared. The sink
+    ``withhold`` drops ``display`` in favour of the declared name or its checked location. The sink
     composes ``display`` from an :class:`~maf_sandbox.Artifact` whose ``content`` is the guest's
     bytes, and nothing in the protocol requires the two to be independent — so a sink that puts
     any of that content in the string would be putting guest-authored text back into a result
-    rendered to hold none. Naming the declared spelling costs the sink's own detail and needs no
-    promise from the host to stay honest.
+    rendered to hold none. Locations are calculated from validated declarations before delivery;
+    substituted declarations still render only as argument positions.
     """
-    delivered = {unicodedata.normalize("NFC", item.name) for item in landed}
+    delivered = {
+        unicodedata.normalize("NFC", name)
+        for name in (
+            delivered_names if delivered_names is not None else [item.name for item in landed]
+        )
+    }
+    locations = locations or {}
     lines: list[str] = []
     # Answered once, above the two renderings that need it: a name that landed is reported as
     # surely as one that did not, and a name the framework substituted must not be repeated
@@ -2039,10 +2083,11 @@ def _format_landed(
         if withhold:
             for position, name in enumerate(declared):
                 if unicodedata.normalize("NFC", name) in delivered:
-                    # The name itself unless the framework put it there: this is a list of
-                    # files, not a refusal, so a name of the model's own is what it wants back.
+                    # Only model-authored declarations may reveal their location.
                     lines.append(
-                        f"- {named_by}[{position}]" if position in rewritten else f"- {name}"
+                        f"- {named_by}[{position}]"
+                        if position in rewritten
+                        else f"- {locations.get(name, name)}"
                     )
         else:
             for item in landed:
@@ -2058,7 +2103,11 @@ def _format_landed(
     # spelling where it is the caller's, and the position where the framework put something
     # else there. It is the one line here that names a file which does not exist.
     missing = [
-        echoed_name(name, at=f"{named_by}[{position}]", hidden=position in rewritten)
+        echoed_name(
+            locations.get(name, name),
+            at=f"{named_by}[{position}]",
+            hidden=position in rewritten,
+        )
         for position, name in enumerate(declared)
         if unicodedata.normalize("NFC", name) not in delivered
     ]