maf-sandbox-codeact 0.1.0__tar.gz

maf_sandbox_codeact-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOKOLAI BV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maf_sandbox_codeact-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: maf-sandbox-codeact
+Version: 0.1.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
+Author-email: SOKOLAI BV <info@sokolai.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python :: 3
+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.5.0,<0.6
+Requires-Dist: agent-framework-core>=1.13.0,<2
+Requires-Python: >=3.12, <3.15
+Project-URL: Homepage, https://www.sokol.ai
+Project-URL: Source, https://github.com/sokolaidev/maf-extensions
+Project-URL: Issues, https://github.com/sokolaidev/maf-extensions/issues
+Description-Content-Type: text/markdown
+
+# maf-sandbox-codeact
+
+> **Experimental.** This package is early-stage (pre-1.0, `Development Status :: 4 - Beta`) — its API may change or be removed in a future release without notice. Importing it emits a one-time `MafSandboxCodeactExperimentalWarning`; suppress it with `warnings.filterwarnings("ignore", category=maf_sandbox_codeact.MafSandboxCodeactExperimentalWarning)` once you've read the notice.
+
+This package is not affiliated with, endorsed by, or a product of Microsoft — it is a third-party reference implementation of [microsoft/agent-framework#7568](https://github.com/microsoft/agent-framework/issues/7568) for [Microsoft Agent Framework](https://aka.ms/AgentFramework).
+
+CodeAct as a Microsoft Agent Framework tool: the agent gets one tool, `execute_code`; the model writes a short Python program; the program runs inside a sandbox and the tool returns what it printed. Computing an answer beats reasoning about what the computation would produce — and the code that does it runs somewhere the host is not.
+
+```
+app  ->  maf_sandbox  ->  a backend (maf-sandbox-acas, maf-sandbox-wslc, ...)  ->  this workload
+```
+
+This package is a sandbox **kind** in the sense of [`maf-sandbox`](https://github.com/sokolaidev/maf-extensions/tree/main/packages/maf-sandbox)'s protocol. It contains no Azure import, no backend import and no sandbox lifecycle code; it asks a `SandboxRouter` for a sandbox and gets back `write_file` and `exec`, so the same tool runs unchanged against ACA Sandboxes, a WSL container or an in-process fake. Tests enforce both boundaries.
+
+## Quickstart
+
+```bash
+pip install maf-sandbox-codeact
+```
+
+```python
+from maf_sandbox_codeact import make_codeact_tools
+
+tools = make_codeact_tools(router, "data-analyst", context,
+                           image="mcr.microsoft.com/devcontainers/python:3.13-bookworm")
+```
+
+Pass `router=None` — or a router with no backend — and you get `[]` back: an unconfigured host attaches no tool rather than one that fails when called. A backend that cannot `exec`, or cannot take files in, is refused right there with `SandboxCapabilityNotSupported`, before the model is shown a capability it does not have.
+
+`router` and `context` are the host's, and this snippet shows neither being built. [`samples/03_acas_codeact`](https://github.com/sokolaidev/maf-extensions/tree/main/samples/03_acas_codeact) and [`samples/04_wslc_codeact`](https://github.com/sokolaidev/maf-extensions/tree/main/samples/04_wslc_codeact) are the whole wiring as runnable programs — the same agent on a microVM-isolated Azure backend and on a container on your own machine.
+
+## What the model gets
+
+One tool, `execute_code(code)`. The program is written to `/work/program.py` and run as the argv `["python3", "/work/program.py"]`, and the result is its stdout, its stderr when it wrote any, and its exit code when that was not zero. Nothing else comes back: there is no REPL echo, and no file is read out of the sandbox, so a program that computes without printing returns a sentence saying so.
+
+## Threat model
+
+**The source is never a command line.** Model-written code reaches the interpreter as file *content* and the command is a fixed two-element argv — a sequence, not a shell string — so there is no command line for the source to be part of, nothing to quote, and nothing to escape. That is the security-relevant decision in this package and it is pinned by a test.
+
+**Egress is closed.** `SandboxSpec.egress_allow` is empty, stated as a property of the workload rather than of configuration: the program computes, it does not fetch. A backend that cannot confine egress at all is refused at attach.
+
+**Nothing is dispatchable from inside.** There is no host-tool registry in this version, and that emptiness is the security story rather than a missing feature: with no network and no host functions reachable, nothing external can enter the sandbox and nothing leaves it but what the program printed. Adding that surface is what changes the calculus, so it is deliberately not here yet — see below.
+
+**The tool declares no `source_integrity`.** The library's default is `"trusted"`, which is right for a workload whose result is a compiler's own diagnostics and wrong for this one: what comes back is whatever a model-written `print(...)` chose to emit. Undeclared, MAF's information-flow tracker applies its untrusted default and the result taints the conversation — the fail-safe direction, and the honest one.
+
+**Isolation is the host's call.** This kind does not raise `SandboxSpec.min_isolation`, so the router's floor governs — `MICROVM` unless the host opted down. A kind that ran code influenced by untrusted external content would pin the floor itself; this one has no such input.
+
+## What this version is not
+
+`FILES_OUT` (reading artefacts back out of the sandbox), a workspace-files parameter, host-tool dispatch, and the `RUN_CODE` road served by an embedded-interpreter backend are all absent on purpose. The design that governs them — capabilities declared by backends and required by specs, and what `HOST_TOOLS` would have to carry before it ships — is [`docs/design/two-axis-sandbox-policy.md`](https://github.com/sokolaidev/maf-extensions/blob/main/docs/design/two-axis-sandbox-policy.md).
+
+---
+
+Maintained by [SOKOLAI BV](https://www.sokol.ai).

maf_sandbox_codeact-0.1.0/README.md

@@ -0,0 +1,54 @@
+# maf-sandbox-codeact
+
+> **Experimental.** This package is early-stage (pre-1.0, `Development Status :: 4 - Beta`) — its API may change or be removed in a future release without notice. Importing it emits a one-time `MafSandboxCodeactExperimentalWarning`; suppress it with `warnings.filterwarnings("ignore", category=maf_sandbox_codeact.MafSandboxCodeactExperimentalWarning)` once you've read the notice.
+
+This package is not affiliated with, endorsed by, or a product of Microsoft — it is a third-party reference implementation of [microsoft/agent-framework#7568](https://github.com/microsoft/agent-framework/issues/7568) for [Microsoft Agent Framework](https://aka.ms/AgentFramework).
+
+CodeAct as a Microsoft Agent Framework tool: the agent gets one tool, `execute_code`; the model writes a short Python program; the program runs inside a sandbox and the tool returns what it printed. Computing an answer beats reasoning about what the computation would produce — and the code that does it runs somewhere the host is not.
+
+```
+app  ->  maf_sandbox  ->  a backend (maf-sandbox-acas, maf-sandbox-wslc, ...)  ->  this workload
+```
+
+This package is a sandbox **kind** in the sense of [`maf-sandbox`](https://github.com/sokolaidev/maf-extensions/tree/main/packages/maf-sandbox)'s protocol. It contains no Azure import, no backend import and no sandbox lifecycle code; it asks a `SandboxRouter` for a sandbox and gets back `write_file` and `exec`, so the same tool runs unchanged against ACA Sandboxes, a WSL container or an in-process fake. Tests enforce both boundaries.
+
+## Quickstart
+
+```bash
+pip install maf-sandbox-codeact
+```
+
+```python
+from maf_sandbox_codeact import make_codeact_tools
+
+tools = make_codeact_tools(router, "data-analyst", context,
+                           image="mcr.microsoft.com/devcontainers/python:3.13-bookworm")
+```
+
+Pass `router=None` — or a router with no backend — and you get `[]` back: an unconfigured host attaches no tool rather than one that fails when called. A backend that cannot `exec`, or cannot take files in, is refused right there with `SandboxCapabilityNotSupported`, before the model is shown a capability it does not have.
+
+`router` and `context` are the host's, and this snippet shows neither being built. [`samples/03_acas_codeact`](https://github.com/sokolaidev/maf-extensions/tree/main/samples/03_acas_codeact) and [`samples/04_wslc_codeact`](https://github.com/sokolaidev/maf-extensions/tree/main/samples/04_wslc_codeact) are the whole wiring as runnable programs — the same agent on a microVM-isolated Azure backend and on a container on your own machine.
+
+## What the model gets
+
+One tool, `execute_code(code)`. The program is written to `/work/program.py` and run as the argv `["python3", "/work/program.py"]`, and the result is its stdout, its stderr when it wrote any, and its exit code when that was not zero. Nothing else comes back: there is no REPL echo, and no file is read out of the sandbox, so a program that computes without printing returns a sentence saying so.
+
+## Threat model
+
+**The source is never a command line.** Model-written code reaches the interpreter as file *content* and the command is a fixed two-element argv — a sequence, not a shell string — so there is no command line for the source to be part of, nothing to quote, and nothing to escape. That is the security-relevant decision in this package and it is pinned by a test.
+
+**Egress is closed.** `SandboxSpec.egress_allow` is empty, stated as a property of the workload rather than of configuration: the program computes, it does not fetch. A backend that cannot confine egress at all is refused at attach.
+
+**Nothing is dispatchable from inside.** There is no host-tool registry in this version, and that emptiness is the security story rather than a missing feature: with no network and no host functions reachable, nothing external can enter the sandbox and nothing leaves it but what the program printed. Adding that surface is what changes the calculus, so it is deliberately not here yet — see below.
+
+**The tool declares no `source_integrity`.** The library's default is `"trusted"`, which is right for a workload whose result is a compiler's own diagnostics and wrong for this one: what comes back is whatever a model-written `print(...)` chose to emit. Undeclared, MAF's information-flow tracker applies its untrusted default and the result taints the conversation — the fail-safe direction, and the honest one.
+
+**Isolation is the host's call.** This kind does not raise `SandboxSpec.min_isolation`, so the router's floor governs — `MICROVM` unless the host opted down. A kind that ran code influenced by untrusted external content would pin the floor itself; this one has no such input.
+
+## What this version is not
+
+`FILES_OUT` (reading artefacts back out of the sandbox), a workspace-files parameter, host-tool dispatch, and the `RUN_CODE` road served by an embedded-interpreter backend are all absent on purpose. The design that governs them — capabilities declared by backends and required by specs, and what `HOST_TOOLS` would have to carry before it ships — is [`docs/design/two-axis-sandbox-policy.md`](https://github.com/sokolaidev/maf-extensions/blob/main/docs/design/two-axis-sandbox-policy.md).
+
+---
+
+Maintained by [SOKOLAI BV](https://www.sokol.ai).

maf_sandbox_codeact-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "maf-sandbox-codeact"
+version = "0.1.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"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "codeact",
+    "code-execution",
+    "sandbox",
+    "agent-framework",
+    "microsoft-agent-framework",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Interpreters",
+]
+dependencies = [
+    "maf-sandbox>=0.5.0,<0.6",
+    "agent-framework-core>=1.13.0,<2",
+]
+
+[[project.authors]]
+name = "SOKOLAI BV"
+email = "info@sokolai.com"
+
+[project.urls]
+Homepage = "https://www.sokol.ai"
+Source = "https://github.com/sokolaidev/maf-extensions"
+Issues = "https://github.com/sokolaidev/maf-extensions/issues"
+
+[tool.uv.sources.maf-sandbox]
+workspace = true
+
+[tool.uv.build-backend]
+module-name = "maf_sandbox_codeact"
+module-root = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = [
+    "I",
+    "UP",
+    "D100",
+    "D101",
+    "D103",
+    "D104",
+]
+ignore = ["UP037"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "D101",
+    "D103",
+]
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.11.24,<0.12.0"]
+build-backend = "uv_build"

maf_sandbox_codeact-0.1.0/pyproject.toml.orig

@@ -0,0 +1,84 @@
+[project]
+name = "maf-sandbox-codeact"
+version = "0.1.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"
+authors = [{ name = "SOKOLAI BV", email = "info@sokolai.com" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "codeact",
+    "code-execution",
+    "sandbox",
+    "agent-framework",
+    "microsoft-agent-framework",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Interpreters",
+]
+dependencies = [
+    # The sandbox protocol this workload is written against — its ONLY infrastructure
+    # dependency. No Azure import, no backend import; a test enforces both.
+    # Upper-bounded too: maf-sandbox has not yet reached a stable API, so every release
+    # before 1.0.0 may include breaking changes (see its CHANGELOG). Moving either end of
+    # this range has an order to it — see RELEASING.md. The floor is where `Capability` and
+    # `SandboxSpec.requires` actually arrive — the 0.5.0 release the isolation-floor branch
+    # creates — not 0.4.0, which predates them; a floor below 0.5.0 would let a published
+    # wheel resolve a maf-sandbox base missing the imports this kind's spec needs. This
+    # package's own clean-environment wheel check cannot go green until maf-sandbox 0.5.0 is
+    # published; that ordering is deliberate (RELEASING.md release order), not a bug to work
+    # around here.
+    "maf-sandbox>=0.5.0,<0.6",
+    # The `@tool` decorator. MAF is a genuine dependency of the tool itself, not of the host
+    # application.
+    "agent-framework-core>=1.13.0,<2",
+]
+
+[project.urls]
+Homepage = "https://www.sokol.ai"
+Source = "https://github.com/sokolaidev/maf-extensions"
+Issues = "https://github.com/sokolaidev/maf-extensions/issues"
+
+# agent-framework-core resolves from PyPI at the released range declared above — no git
+# source in this repository, deliberately: the tests run against the same artifact every
+# consumer of the published wheel gets.
+[tool.uv.sources]
+maf-sandbox = { workspace = true }
+
+[tool.uv.build-backend]
+module-name = "maf_sandbox_codeact"
+module-root = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = ["I", "UP", "D100", "D101", "D103", "D104"]
+ignore = ["UP037"]
+
+[tool.ruff.lint.per-file-ignores]
+# ruff resolves [tool.ruff] per file by the NEAREST ancestor pyproject.toml that has one, so
+# this package carries its own copy rather than inheriting one from the workspace root.
+"tests/**" = ["D101", "D103"]
+
+# Self-contained type checking, scoped to this package — strict. `tests/` stays out (fakes,
+# not signal for a strict checker).
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.11.24,<0.12.0"]
+build-backend = "uv_build"

maf_sandbox_codeact-0.1.0/src/maf_sandbox_codeact/__init__.py

@@ -0,0 +1,50 @@
+"""The CodeAct sandbox: ``execute_code`` as a MAF tool.
+
+A sibling of the Bicep kind rather than a variant of it: both are written against
+:mod:`maf_sandbox`'s protocol alone, and neither knows which backend answers.  Where that one
+runs a fixed compiler over files an agent authored, this one runs a program the model just
+wrote, and returns what it printed.
+
+Nothing in this subpackage imports Azure, a backend, or a host application: it asks a
+:class:`~maf_sandbox.SandboxRouter` for a sandbox and gets back ``write_file`` and ``exec``.
+"""
+
+from __future__ import annotations
+
+from ._tool import (
+    CODEACT_KIND,
+    EXECUTE_CODE_TOOL_NAME,
+    codeact_sandbox_spec,
+    make_codeact_tools,
+)
+
+__all__ = [
+    "CODEACT_KIND",
+    "EXECUTE_CODE_TOOL_NAME",
+    "MafSandboxCodeactExperimentalWarning",
+    "codeact_sandbox_spec",
+    "make_codeact_tools",
+]
+
+# Experimental package (Beta): importing it emits a UserWarning rather than a FutureWarning,
+# so a host running under `python -W error` can still import it.
+import warnings as _warnings
+
+
+class MafSandboxCodeactExperimentalWarning(UserWarning):
+    """Warning category for maf-sandbox-codeact's experimental-package notice."""
+
+
+def _warn_experimental() -> None:
+    message = (
+        "maf_sandbox_codeact is experimental and may change or be removed in future versions "
+        "without notice."
+    )
+    try:
+        _warnings.warn(message, category=MafSandboxCodeactExperimentalWarning, stacklevel=2)
+    except MafSandboxCodeactExperimentalWarning:
+        # Deliberate: under `-W error` an informational notice must not fail the import.
+        pass
+
+
+_warn_experimental()

maf_sandbox_codeact-0.1.0/src/maf_sandbox_codeact/_tool.py

@@ -0,0 +1,211 @@
+"""``execute_code``: the CodeAct sandbox workload.
+
+The agent gets one tool, the model writes a short Python program, and the program runs inside
+a sandbox — computing an answer instead of reasoning about what the computation would produce.
+
+**This module contains no Azure import, no backend import and no sandbox lifecycle code.**  It
+talks to a :class:`~maf_sandbox.SandboxRouter` and gets back ``write_file`` and ``exec``, so
+the same tool runs unchanged against ACA Sandboxes, a WSL container or an in-process fake.
+
+This version is the ``EXEC`` road and it is stdout-only.  Nothing is read back out of the
+sandbox, no workspace file is shared into it, and no host function is dispatchable from
+inside: with the spec's egress closed as well, nothing external can enter and nothing leaves
+but what the program printed.  That empty dispatch surface is what makes running model-written
+code defensible here, so it is a property of this version rather than a gap in it.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from maf_sandbox import (
+    Capability,
+    ExecResult,
+    SandboxRouter,
+    SandboxSpec,
+    WorkspaceContext,
+    error_detail,
+)
+from maf_sandbox.maf import SandboxToolSession, sandbox_tool_declarations, sandboxed_tool
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "CODEACT_KIND",
+    "EXECUTE_CODE_TOOL_NAME",
+    "codeact_sandbox_spec",
+    "make_codeact_tools",
+]
+
+EXECUTE_CODE_TOOL_NAME = "execute_code"
+
+#: The sandbox kind this workload asks for.
+CODEACT_KIND = "codeact"
+
+#: Where the program is written and run — a dedicated root rather than the image's own tree.
+_WORK_DIR = "/work"
+
+#: One fixed name, rewritten on every call, since the sandbox is reused across calls.
+_PROGRAM_FILENAME = "program.py"
+
+_INTERPRETER = "python3"
+
+#: Writing an expression and expecting a REPL to echo it is the commonest way a first CodeAct
+#: call comes back empty, so the answer says what to do instead.
+_NO_OUTPUT = (
+    "The program ran and printed nothing. Only what you print comes back — end the program "
+    "with print(...) of what you need to see."
+)
+
+
+def codeact_sandbox_spec(image: str | None = None, image_id: str | None = None) -> SandboxSpec:
+    """The sandbox a CodeAct program needs, in backend-neutral terms.
+
+    ``egress_allow=()`` and no ``min_isolation`` are both deliberate: the program computes
+    rather than fetches, and this kind runs only what the model wrote, so the host's floor
+    governs.
+    """
+    return SandboxSpec(
+        kind=CODEACT_KIND,
+        image=image,
+        image_id=image_id,
+        egress_allow=(),
+        work_dir=_WORK_DIR,
+        requires=frozenset({Capability.EXEC, Capability.FILES_IN}),
+    )
+
+
+def make_codeact_tools(
+    router: SandboxRouter | None,
+    agent_dir: str,
+    context: WorkspaceContext,
+    *,
+    image: str | None = None,
+    image_id: str | None = None,
+    exec_timeout_seconds: int = 120,
+) -> list[Any]:
+    """Return the ``[execute_code]`` tool list, or ``[]`` when no sandbox is available.
+
+    Args:
+        router: The sandbox router, or ``None`` when sandboxing is not configured.
+        agent_dir: The agent's directory name. Baked into the sandbox key at factory time
+            rather than taken from the model at call time.
+        context: How to read the caller's scope and thread.
+        image: OCI reference of a sandbox image with a Python interpreter on its path.
+        image_id: A backend-native disk-image id, skipping resolution.
+        exec_timeout_seconds: Per-program bound. A sandbox that stops answering must not hold
+            the caller's turn open.
+    """
+    spec = codeact_sandbox_spec(image, image_id)
+    return sandboxed_tool(
+        lambda session: _execute_code_tool(session, exec_timeout_seconds),
+        router=router,
+        context=context,
+        agent_dir=agent_dir,
+        spec=spec,
+        name=EXECUTE_CODE_TOOL_NAME,
+        approval_mode="never_require",
+        # No `source_integrity`: undeclared defaults to untrusted, the fail-safe direction.
+        declarations=sandbox_tool_declarations(spec, source_integrity=None),
+        logger=logger,
+    )
+
+
+def _execute_code_tool(
+    session: SandboxToolSession,
+    timeout: int,
+) -> "Callable[..., Awaitable[str]]":
+    """Build the ``execute_code`` body for one attached tool.
+
+    Defined at module level rather than nested inside :func:`make_codeact_tools`, and that is
+    not a style choice: the function below's **docstring is the tool's description** — MAF
+    passes ``__doc__`` through verbatim, indentation and all — so nesting this one level
+    deeper would re-indent every line of what the model reads at call time.
+    """
+
+    async def execute_code(code: str) -> str:
+        """Run a short Python program inside a sandbox and return what it printed.
+
+        Use this to compute rather than to reason: parse, transform, count, check, simulate —
+        anything where running the code beats predicting what it would do.  The program runs
+        as ``python3 program.py`` in a sandbox with **no network access**, so it can compute
+        but cannot fetch.
+
+        **Only what you print comes back.**  There is no REPL echo and the value of the last
+        expression is not returned, so end the program with ``print(...)`` of everything you
+        need to see.  Nothing is read back out of the sandbox either — a file your program
+        writes may still be there on a later call in the same conversation, but the printed
+        output is the whole result.
+
+        Write a complete, self-contained program every time.  Each call replaces the previous
+        one, and nothing carries over except what the program itself wrote to disk.
+
+        Args:
+            code: The Python source to run.  The standard library, plus whatever the sandbox
+                image ships.
+
+        Returns:
+            The program's stdout, its stderr when it wrote any, and its exit code when that
+            was not zero.  If the sandbox is unavailable the tool returns an error message
+            instead, so the run degrades rather than blocking.
+        """
+        # Scope and thread come from the host's request context, never from model input.
+        key = session.key()
+        if isinstance(key, str):
+            return key
+
+        sandbox = await session.acquire(key)
+        if isinstance(sandbox, str):
+            return sandbox
+
+        program_path = f"{session.spec.work_dir}/{_PROGRAM_FILENAME}"
+        try:
+            await sandbox.write_file(program_path, code)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "execute_code: could not write the program into the sandbox: %s",
+                error_detail(exc),
+            )
+            return "Error: could not write the program into the sandbox"
+
+        try:
+            # An argv sequence, never a command line: the model's source never reaches a shell.
+            result = await sandbox.exec(
+                [_INTERPRETER, program_path],
+                working_directory=session.spec.work_dir,
+                timeout=timeout,
+            )
+        except TimeoutError:
+            logger.warning("execute_code: the program timed out after %ss", timeout)
+            return f"Error: the program timed out after {timeout}s"
+        except Exception as exc:  # noqa: BLE001
+            # Provider/transport detail can carry account ids — must not reach the transcript.
+            logger.warning("execute_code: exec failed: %s", error_detail(exc))
+            return "Error: could not run the program in the sandbox"
+
+        logger.info("execute_code: ran exit_code=%d", result.exit_code)
+        return _format_result(result)
+
+    return execute_code
+
+
+def _format_result(result: ExecResult) -> str:
+    """Render one run for a model that has to fix its own program.
+
+    Empty sections are omitted rather than shown blank, and the trailing newline ``print``
+    leaves is dropped, so a one-line program's answer is one line.
+    """
+    stdout = (result.stdout or "").rstrip("\n")
+    stderr = (result.stderr or "").rstrip("\n")
+    sections: list[str] = []
+    if stdout:
+        sections.append(f"stdout:\n{stdout}")
+    if stderr:
+        sections.append(f"stderr:\n{stderr}")
+    if result.exit_code:
+        sections.append(f"exit code: {result.exit_code}")
+    return "\n\n".join(sections) if sections else _NO_OUTPUT