maf-sandbox-deepagents 0.1.0__tar.gz

maf_sandbox_deepagents-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_deepagents-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: maf-sandbox-deepagents
+Version: 0.1.0
+Summary: A maf-sandbox router as a Deep Agents sandbox backend — any backend the router admits (Docker, ACA Sandboxes) behind LangChain's BaseSandbox, with the router's isolation floor and egress policy still enforced.
+Keywords: deepagents,langchain,langgraph,sandbox,isolation,ai-agents
+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 :: Libraries :: Python Modules
+Requires-Dist: maf-sandbox>=0.38.0,<0.39
+Requires-Dist: deepagents>=0.7.13,<0.8
+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-deepagents
+
+[![PyPI](https://img.shields.io/pypi/v/maf-sandbox-deepagents)](https://pypi.org/project/maf-sandbox-deepagents/) [![Python](https://img.shields.io/pypi/pyversions/maf-sandbox-deepagents)](https://pypi.org/project/maf-sandbox-deepagents/) [![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/sokolaidev/maf-extensions/blob/main/LICENSE)
+
+> **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 `MafSandboxDeepagentsExperimentalWarning`; suppress it with `warnings.filterwarnings("ignore", category=maf_sandbox_deepagents.MafSandboxDeepagentsExperimentalWarning)` once you've read the notice.
+
+This package is not affiliated with, endorsed by, or a product of LangChain, Inc. or Microsoft — it is a third-party bridge between [Deep Agents](https://docs.langchain.com/oss/python/deepagents/sandboxes) and the `maf-sandbox` suite.
+
+```
+deepagents  ->  maf_sandbox_deepagents  ->  maf_sandbox (router)  ->  a backend  ->  the sandbox
+```
+
+A `maf-sandbox` router as a Deep Agents sandbox. Deep Agents gives an agent one `execute` tool over a sandbox object the host constructs, and derives its file tools from that; the cloud providers it ships with (LangSmith, Daytona, E2B, Modal, Runloop, Vercel) each wrap a vendor client. `MafSandbox` is that object over a `SandboxRouter` instead — so a LangChain or LangGraph agent runs its shell in a Docker container or an Azure Container Apps sandbox, and the host keeps the router's decisions: a backend below the isolation floor is refused at construction, egress is closed unless the spec names hosts, and the sandbox is keyed from the request context and purged with the conversation.
+
+It is the suite in the other direction. The packaged kinds (`bicep_validate`, `execute_code`) attach to a Microsoft Agent Framework agent as tools; this package attaches a *backend* to a Deep Agents agent and lets the agent write its own commands. What that gives up is said below.
+
+## Quickstart
+
+```python
+from deepagents import create_deep_agent
+from maf_sandbox import Isolation, SandboxKey, SandboxRouter
+from maf_sandbox_deepagents import MafSandbox, deepagents_spec
+from maf_sandbox_docker import DockerSandboxBackend, DockerSandboxConfig
+
+router = SandboxRouter([DockerSandboxBackend(DockerSandboxConfig())], min_isolation=Isolation.CONTAINER)
+spec = deepagents_spec("python:3.12-alpine")
+
+# One sandbox per agent in a conversation: scope, thread and agent directory come from the host's request context.
+sandbox = MafSandbox(router, SandboxKey(scope="tenant-a", thread_id="thread-1", agent_dir="coder"), spec)
+
+agent = create_deep_agent(model=..., backend=sandbox, system_prompt="...")
+```
+
+`deepagents_spec` builds the spec Deep Agents needs — `EXEC`, `FILES_IN` and `FILES_OUT` — with the protocol's default base, and derives egress: `egress_allow=("pypi.org",)` runs the sandbox `ALLOWLIST` with that host, and no hosts runs it `CLOSED`. There is no open posture to ask for, because the agent writes the commands, and a spec built another way that asks for `UNRESTRICTED` is refused. `MafSandbox` refuses that, a spec that lacks a required capability, a router with no backend, and a spec that leaves the base to the backend, and asks the router at construction whether the backend can serve it, so a misconfigured host fails before an agent is built.
+
+**Paths are guest paths**, as they are for every sandbox Deep Agents ships: the agent's `read_file`, `write_file` and the rest name them absolutely, and `execute` runs in the base. The adapter's own upload and download take an absolute path anywhere in the guest, or a relative one under the base. Inside `spec.work_dir` they go through the backend's file plane, which refuses a path through a link as `invalid_path`; outside it — Deep Agents keeps its offloaded history under `/conversation_history/` and its large-edit temporaries under `/tmp/` — they go through the same shell the agent already has, in base64 chunks, under the same caps, so the file plane's confinement widens nothing that `execute` had not already opened. Put `spec.work_dir` in the system prompt so the model knows where its own files are; the example does. A backend-allocated base (`work_dir=None`) is refused at construction, because nothing could then tell the model where it is.
+
+The sandbox is acquired on the first operation, a command or a file transfer, and reused warm after that. It lives until the host disposes it: `await sandbox.aclose()`, or the router's `dispose_scope(scope, thread_id)` on the host's own conversation-delete path — the backstop every sandbox in the suite answers to, and the one to wire, because LangGraph fires nothing when a thread is deleted. [`examples/docker_bicep`](https://github.com/sokolaidev/maf-extensions/tree/main/packages/maf-sandbox-deepagents/examples/docker_bicep) runs the whole thing end to end; it moves to `samples/` once this package is published, because the samples install from PyPI.
+
+## What the adapter maps
+
+| Deep Agents | `maf_sandbox` |
+|---|---|
+| `execute(command, timeout)` | `BoundedExec.exec_bounded(command, working_directory=".", timeout=..., max_output_bytes=...)` — run in the sandbox's storage base, a shell string the backend runs as `sh -c`, under one deadline that a cold acquire spends part of and cannot outlive, and under `max_output_bytes` (1 MiB by default), which the backend enforces before it buffers anything: output past it is dropped whole and the result says so with `truncated=True`; a timeout, an overflow, the caller's cancellation or any failure that kept the result from coming back also condemns the sandbox, because nothing establishes that the process stopped when the host stopped waiting: every call is admitted through the router's call lifecycle, which every call over the key shares whichever adapter made it, the delete runs when the last call in flight leaves, so a parallel tool call is never cut off underneath, that release goes to the process's own loop after an unfinished command, so the delete neither extends the caller's wait nor dies with the caller's loop, and a later call is admitted once it is done, so the next command starts cold; `stdout` and `stderr` come back as one stream with `[stderr]` on the second, the way Deep Agents' own backends render it, and that stream is held to the same budget once rendered, since the prefixes grow it |
+| `upload_files([(path, bytes)])` | `Sandbox.write_file` under the base, one call per file, and the core's `write_file_over_exec` outside it, which stages the chunks in a sibling named for the call and moves it into place once the last landed, so a reader or a second writer sees a whole file and never two interleaved, under `spec.files_in`: a batch over `max_files` is refused whole, a file over `max_bytes_per_file` or past `max_total_bytes` is refused alone; a path through a link under the base is refused as `invalid_path` and an unsearchable ancestor as `permission_denied`, what either road refuses comes back as Deep Agents' code for the core's `FileRefusal`, and a write the plane did not refuse and did not finish condemns the sandbox and fails the batch, since the plane does not promise a whole file or none; a shell write that does not finish, on a timeout, an output overflow, the caller's cancellation or any other failure, condemns the sandbox and fails the whole batch, because what it had put there goes with it |
+| `download_files([path])` | `Sandbox.stat_file` then `Sandbox.read_file` under the base, and the core's `read_file_over_exec` outside it, a probe that tells a file behind an unsearchable ancestor from an absent one and a base64 read under the cap, under `spec.files_out`: a batch over `max_files` is refused whole, and each file is read under the smaller of `max_bytes_per_file` and what `max_total_bytes` has left, refusing rather than truncating; a missing file is `file_not_found`, a directory `is_directory`, a link under the base or a parent that is a file `invalid_path`, an unreadable file `permission_denied`; a plane stat or read that times out fails that file alone and the sandbox stays, since a read changes nothing in it and the bound is the backend's own refusal of an entry it cannot serve; a shell read that does not finish, on a timeout, an overflow, the caller's cancellation or any other failure, condemns the sandbox and fails the rest of the batch |
+| `id` | An opaque hash of what names the sandbox — the key, the kind, the serving backend instance and the egress posture — because Deep Agents may render it to the model and a scope is often a tenant; two adapters over one router and key share it, since they reach one sandbox, and two backends of one name reaching two engines do not |
+| `aclose()` | `SandboxRouter.enter_call` exclusively, so every call over the key has left and a delete one of them queued has run, then `dispose_kind` for the one instance this adapter acquired, so a packaged kind serving the same conversation, or another adapter over the same key with a different backend or egress, keeps its own; before any acquire, or once a queued delete took the instance, there is nothing of this adapter's to delete |
+
+Both surfaces are served: the `a*` methods are native, and the synchronous ones, which a sync tool on a LangGraph worker thread calls, run the same coroutine on the core's `SyncRunner`, one loop on a thread of its own, shared by every adapter in the process and started by the first sync call, so a backend that caches a client per loop holds one, not one per adapter or per call; a forked child starts its own on its first sync call, since a fork carries the loop but not its thread.
+
+## What it costs, honestly
+
+**The agent writes the shell.** The packaged kinds run a fixed argv and never a shell; here the model's command string is what runs, which is Deep Agents' model and what its `BaseSandbox` documents. The container boundary and the egress policy are the controls, and nothing above them is. Do not put a credential in the image.
+
+**Cleanup is disposal.** A kind can claim confinement to its own call directory and earn warm reuse through `RECLAIM`; an arbitrary shell cannot, so the router cleans this sandbox by deleting it. It stays warm across the turns of one conversation and goes when the host disposes it.
+
+**Deep Agents' derived file tools need `python3` in the guest.** `ls`, `read_file`, `edit_file`, `glob` and `grep` are shell-and-Python snippets Deep Agents runs through `execute`, and `write_file` runs one too, a preflight that creates the parent directory, before it hands the bytes to `upload_files`. On an image without an interpreter — [`images/bicep-sandbox`](https://github.com/sokolaidev/maf-extensions/tree/main/images/bicep-sandbox) is one — only `execute`, `delete` (a `test` and an `rm -rf` through `execute`) and this package's own `upload_files` and `download_files` work. The image is the host's to choose, and the sample says so in its prompt.
+
+**No labels and no declared outputs.** MAF's information-flow declarations, the per-call guest path, declared outputs with a landing sink, and host tools called from inside the guest are the kinds' contract with the framework, and Deep Agents has no place to put them. A host that needs them attaches a kind to a MAF agent; this package is for a host that already has a Deep Agents agent.
+
+## Requirements
+
+- Python 3.12 or newer.
+- `deepagents` 0.7.x. Its backend protocol has changed between 0.x minors, so one minor is admitted at a time.
+- An image with `sh`, `mkdir`, `mv`, `rm`, `base64` and `wc` (the core's `SHELL_UTILITIES`), which the shell road runs for an upload or download outside the base (`test`, `printf` and `echo` are the shell's own in busybox, dash and bash). Docker's exec probe checks only `sh`, so an image without `base64` or `wc` constructs fine and fails on the first transfer outside the base; `python:3.12-alpine` and the bicep image have all six.
+- A `maf-sandbox` backend that implements `BoundedExec` (the adapter runs nothing through a sandbox that cannot bound its output), and declares `EXEC`, `FILES_IN` and `FILES_OUT` — [`maf-sandbox-docker`](https://github.com/sokolaidev/maf-extensions/tree/main/packages/maf-sandbox-docker) and [`maf-sandbox-acas`](https://github.com/sokolaidev/maf-extensions/tree/main/packages/maf-sandbox-acas) do; `maf-sandbox-wslc` does not declare `FILES_OUT`, so the router refuses it here.

maf_sandbox_deepagents-0.1.0/README.md

@@ -0,0 +1,67 @@
+# maf-sandbox-deepagents
+
+[![PyPI](https://img.shields.io/pypi/v/maf-sandbox-deepagents)](https://pypi.org/project/maf-sandbox-deepagents/) [![Python](https://img.shields.io/pypi/pyversions/maf-sandbox-deepagents)](https://pypi.org/project/maf-sandbox-deepagents/) [![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/sokolaidev/maf-extensions/blob/main/LICENSE)
+
+> **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 `MafSandboxDeepagentsExperimentalWarning`; suppress it with `warnings.filterwarnings("ignore", category=maf_sandbox_deepagents.MafSandboxDeepagentsExperimentalWarning)` once you've read the notice.
+
+This package is not affiliated with, endorsed by, or a product of LangChain, Inc. or Microsoft — it is a third-party bridge between [Deep Agents](https://docs.langchain.com/oss/python/deepagents/sandboxes) and the `maf-sandbox` suite.
+
+```
+deepagents  ->  maf_sandbox_deepagents  ->  maf_sandbox (router)  ->  a backend  ->  the sandbox
+```
+
+A `maf-sandbox` router as a Deep Agents sandbox. Deep Agents gives an agent one `execute` tool over a sandbox object the host constructs, and derives its file tools from that; the cloud providers it ships with (LangSmith, Daytona, E2B, Modal, Runloop, Vercel) each wrap a vendor client. `MafSandbox` is that object over a `SandboxRouter` instead — so a LangChain or LangGraph agent runs its shell in a Docker container or an Azure Container Apps sandbox, and the host keeps the router's decisions: a backend below the isolation floor is refused at construction, egress is closed unless the spec names hosts, and the sandbox is keyed from the request context and purged with the conversation.
+
+It is the suite in the other direction. The packaged kinds (`bicep_validate`, `execute_code`) attach to a Microsoft Agent Framework agent as tools; this package attaches a *backend* to a Deep Agents agent and lets the agent write its own commands. What that gives up is said below.
+
+## Quickstart
+
+```python
+from deepagents import create_deep_agent
+from maf_sandbox import Isolation, SandboxKey, SandboxRouter
+from maf_sandbox_deepagents import MafSandbox, deepagents_spec
+from maf_sandbox_docker import DockerSandboxBackend, DockerSandboxConfig
+
+router = SandboxRouter([DockerSandboxBackend(DockerSandboxConfig())], min_isolation=Isolation.CONTAINER)
+spec = deepagents_spec("python:3.12-alpine")
+
+# One sandbox per agent in a conversation: scope, thread and agent directory come from the host's request context.
+sandbox = MafSandbox(router, SandboxKey(scope="tenant-a", thread_id="thread-1", agent_dir="coder"), spec)
+
+agent = create_deep_agent(model=..., backend=sandbox, system_prompt="...")
+```
+
+`deepagents_spec` builds the spec Deep Agents needs — `EXEC`, `FILES_IN` and `FILES_OUT` — with the protocol's default base, and derives egress: `egress_allow=("pypi.org",)` runs the sandbox `ALLOWLIST` with that host, and no hosts runs it `CLOSED`. There is no open posture to ask for, because the agent writes the commands, and a spec built another way that asks for `UNRESTRICTED` is refused. `MafSandbox` refuses that, a spec that lacks a required capability, a router with no backend, and a spec that leaves the base to the backend, and asks the router at construction whether the backend can serve it, so a misconfigured host fails before an agent is built.
+
+**Paths are guest paths**, as they are for every sandbox Deep Agents ships: the agent's `read_file`, `write_file` and the rest name them absolutely, and `execute` runs in the base. The adapter's own upload and download take an absolute path anywhere in the guest, or a relative one under the base. Inside `spec.work_dir` they go through the backend's file plane, which refuses a path through a link as `invalid_path`; outside it — Deep Agents keeps its offloaded history under `/conversation_history/` and its large-edit temporaries under `/tmp/` — they go through the same shell the agent already has, in base64 chunks, under the same caps, so the file plane's confinement widens nothing that `execute` had not already opened. Put `spec.work_dir` in the system prompt so the model knows where its own files are; the example does. A backend-allocated base (`work_dir=None`) is refused at construction, because nothing could then tell the model where it is.
+
+The sandbox is acquired on the first operation, a command or a file transfer, and reused warm after that. It lives until the host disposes it: `await sandbox.aclose()`, or the router's `dispose_scope(scope, thread_id)` on the host's own conversation-delete path — the backstop every sandbox in the suite answers to, and the one to wire, because LangGraph fires nothing when a thread is deleted. [`examples/docker_bicep`](https://github.com/sokolaidev/maf-extensions/tree/main/packages/maf-sandbox-deepagents/examples/docker_bicep) runs the whole thing end to end; it moves to `samples/` once this package is published, because the samples install from PyPI.
+
+## What the adapter maps
+
+| Deep Agents | `maf_sandbox` |
+|---|---|
+| `execute(command, timeout)` | `BoundedExec.exec_bounded(command, working_directory=".", timeout=..., max_output_bytes=...)` — run in the sandbox's storage base, a shell string the backend runs as `sh -c`, under one deadline that a cold acquire spends part of and cannot outlive, and under `max_output_bytes` (1 MiB by default), which the backend enforces before it buffers anything: output past it is dropped whole and the result says so with `truncated=True`; a timeout, an overflow, the caller's cancellation or any failure that kept the result from coming back also condemns the sandbox, because nothing establishes that the process stopped when the host stopped waiting: every call is admitted through the router's call lifecycle, which every call over the key shares whichever adapter made it, the delete runs when the last call in flight leaves, so a parallel tool call is never cut off underneath, that release goes to the process's own loop after an unfinished command, so the delete neither extends the caller's wait nor dies with the caller's loop, and a later call is admitted once it is done, so the next command starts cold; `stdout` and `stderr` come back as one stream with `[stderr]` on the second, the way Deep Agents' own backends render it, and that stream is held to the same budget once rendered, since the prefixes grow it |
+| `upload_files([(path, bytes)])` | `Sandbox.write_file` under the base, one call per file, and the core's `write_file_over_exec` outside it, which stages the chunks in a sibling named for the call and moves it into place once the last landed, so a reader or a second writer sees a whole file and never two interleaved, under `spec.files_in`: a batch over `max_files` is refused whole, a file over `max_bytes_per_file` or past `max_total_bytes` is refused alone; a path through a link under the base is refused as `invalid_path` and an unsearchable ancestor as `permission_denied`, what either road refuses comes back as Deep Agents' code for the core's `FileRefusal`, and a write the plane did not refuse and did not finish condemns the sandbox and fails the batch, since the plane does not promise a whole file or none; a shell write that does not finish, on a timeout, an output overflow, the caller's cancellation or any other failure, condemns the sandbox and fails the whole batch, because what it had put there goes with it |
+| `download_files([path])` | `Sandbox.stat_file` then `Sandbox.read_file` under the base, and the core's `read_file_over_exec` outside it, a probe that tells a file behind an unsearchable ancestor from an absent one and a base64 read under the cap, under `spec.files_out`: a batch over `max_files` is refused whole, and each file is read under the smaller of `max_bytes_per_file` and what `max_total_bytes` has left, refusing rather than truncating; a missing file is `file_not_found`, a directory `is_directory`, a link under the base or a parent that is a file `invalid_path`, an unreadable file `permission_denied`; a plane stat or read that times out fails that file alone and the sandbox stays, since a read changes nothing in it and the bound is the backend's own refusal of an entry it cannot serve; a shell read that does not finish, on a timeout, an overflow, the caller's cancellation or any other failure, condemns the sandbox and fails the rest of the batch |
+| `id` | An opaque hash of what names the sandbox — the key, the kind, the serving backend instance and the egress posture — because Deep Agents may render it to the model and a scope is often a tenant; two adapters over one router and key share it, since they reach one sandbox, and two backends of one name reaching two engines do not |
+| `aclose()` | `SandboxRouter.enter_call` exclusively, so every call over the key has left and a delete one of them queued has run, then `dispose_kind` for the one instance this adapter acquired, so a packaged kind serving the same conversation, or another adapter over the same key with a different backend or egress, keeps its own; before any acquire, or once a queued delete took the instance, there is nothing of this adapter's to delete |
+
+Both surfaces are served: the `a*` methods are native, and the synchronous ones, which a sync tool on a LangGraph worker thread calls, run the same coroutine on the core's `SyncRunner`, one loop on a thread of its own, shared by every adapter in the process and started by the first sync call, so a backend that caches a client per loop holds one, not one per adapter or per call; a forked child starts its own on its first sync call, since a fork carries the loop but not its thread.
+
+## What it costs, honestly
+
+**The agent writes the shell.** The packaged kinds run a fixed argv and never a shell; here the model's command string is what runs, which is Deep Agents' model and what its `BaseSandbox` documents. The container boundary and the egress policy are the controls, and nothing above them is. Do not put a credential in the image.
+
+**Cleanup is disposal.** A kind can claim confinement to its own call directory and earn warm reuse through `RECLAIM`; an arbitrary shell cannot, so the router cleans this sandbox by deleting it. It stays warm across the turns of one conversation and goes when the host disposes it.
+
+**Deep Agents' derived file tools need `python3` in the guest.** `ls`, `read_file`, `edit_file`, `glob` and `grep` are shell-and-Python snippets Deep Agents runs through `execute`, and `write_file` runs one too, a preflight that creates the parent directory, before it hands the bytes to `upload_files`. On an image without an interpreter — [`images/bicep-sandbox`](https://github.com/sokolaidev/maf-extensions/tree/main/images/bicep-sandbox) is one — only `execute`, `delete` (a `test` and an `rm -rf` through `execute`) and this package's own `upload_files` and `download_files` work. The image is the host's to choose, and the sample says so in its prompt.
+
+**No labels and no declared outputs.** MAF's information-flow declarations, the per-call guest path, declared outputs with a landing sink, and host tools called from inside the guest are the kinds' contract with the framework, and Deep Agents has no place to put them. A host that needs them attaches a kind to a MAF agent; this package is for a host that already has a Deep Agents agent.
+
+## Requirements
+
+- Python 3.12 or newer.
+- `deepagents` 0.7.x. Its backend protocol has changed between 0.x minors, so one minor is admitted at a time.
+- An image with `sh`, `mkdir`, `mv`, `rm`, `base64` and `wc` (the core's `SHELL_UTILITIES`), which the shell road runs for an upload or download outside the base (`test`, `printf` and `echo` are the shell's own in busybox, dash and bash). Docker's exec probe checks only `sh`, so an image without `base64` or `wc` constructs fine and fails on the first transfer outside the base; `python:3.12-alpine` and the bicep image have all six.
+- A `maf-sandbox` backend that implements `BoundedExec` (the adapter runs nothing through a sandbox that cannot bound its output), and declares `EXEC`, `FILES_IN` and `FILES_OUT` — [`maf-sandbox-docker`](https://github.com/sokolaidev/maf-extensions/tree/main/packages/maf-sandbox-docker) and [`maf-sandbox-acas`](https://github.com/sokolaidev/maf-extensions/tree/main/packages/maf-sandbox-acas) do; `maf-sandbox-wslc` does not declare `FILES_OUT`, so the router refuses it here.

maf_sandbox_deepagents-0.1.0/pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "maf-sandbox-deepagents"
+version = "0.1.0"
+description = "A maf-sandbox router as a Deep Agents sandbox backend — any backend the router admits (Docker, ACA Sandboxes) behind LangChain's BaseSandbox, with the router's isolation floor and egress policy still enforced."
+readme = "README.md"
+requires-python = ">=3.12,<3.15"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "deepagents",
+    "langchain",
+    "langgraph",
+    "sandbox",
+    "isolation",
+    "ai-agents",
+]
+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 :: Libraries :: Python Modules",
+]
+dependencies = [
+    "maf-sandbox>=0.38.0,<0.39",
+    "deepagents>=0.7.13,<0.8",
+]
+
+[[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_deepagents"
+module-root = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = [
+    "I",
+    "UP",
+    "D100",
+    "D101",
+    "D103",
+    "D104",
+    "E501",
+    "W505",
+    "TD",
+    "FIX",
+    "ERA001",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "D101",
+    "D103",
+    "E501",
+    "W505",
+]
+"examples/**" = [
+    "E501",
+    "W505",
+    "I001",
+]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 100
+
+[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_deepagents-0.1.0/pyproject.toml.orig

@@ -0,0 +1,80 @@
+[project]
+name = "maf-sandbox-deepagents"
+version = "0.1.0"
+description = "A maf-sandbox router as a Deep Agents sandbox backend — any backend the router admits (Docker, ACA Sandboxes) behind LangChain's BaseSandbox, with the router's isolation floor and egress policy still enforced."
+readme = "README.md"
+requires-python = ">=3.12,<3.15"
+authors = [{ name = "SOKOLAI BV", email = "info@sokolai.com" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "deepagents",
+    "langchain",
+    "langgraph",
+    "sandbox",
+    "isolation",
+    "ai-agents",
+]
+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 :: Libraries :: Python Modules",
+]
+dependencies = [
+    # The router and the protocol this adapter drives. Upper-bounded because maf-sandbox has
+    # not reached a stable API, so every release before 1.0.0 may include breaking changes;
+    # moving either end of this range has an order to it — see RELEASING.md. The number is
+    # what `scripts/set_dependents_range.py` moves.
+    "maf-sandbox>=0.38.0,<0.39",
+    # `BaseSandbox` and the response types this adapter answers with. Deep Agents changes its
+    # backend protocol between 0.x minors (0.6 and 0.7 both did), so one minor is admitted.
+    "deepagents>=0.7.13,<0.8",
+]
+
+[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_deepagents"
+module-root = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = ["I", "UP", "D100", "D101", "D103", "D104", "E501", "W505", "TD", "FIX", "ERA001"]
+
+[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", "E501", "W505"]
+# `examples/` holds a sample written to the root's rules, parked here until this package is on the
+# index; it keeps those rules so it moves to `samples/` unchanged.
+"examples/**" = ["E501", "W505", "I001"]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 100
+
+# 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_deepagents-0.1.0/src/maf_sandbox_deepagents/__init__.py

@@ -0,0 +1,61 @@
+"""A maf-sandbox router as a Deep Agents sandbox backend.
+
+```
+deepagents  ->  maf_sandbox_deepagents  ->  maf_sandbox (router)  ->  a backend  ->  the sandbox
+```
+
+:class:`MafSandbox` implements Deep Agents' ``BaseSandbox`` over a
+:class:`~maf_sandbox.SandboxRouter`: the agent gets Deep Agents' own ``execute`` and file tools,
+and the host keeps the router's decisions — the isolation floor, the egress mode, the
+capability match, keying from the request context, and purge by conversation.
+
+This package imports ``maf_sandbox`` and ``deepagents``, and no backend and no agent framework.
+"""
+
+from ._sandbox import (
+    DEEPAGENTS_KIND,
+    DEFAULT_EXEC_TIMEOUT_SECONDS,
+    DEFAULT_MAX_OUTPUT_BYTES,
+    DEFAULT_WORK_DIR,
+    REQUIRED_CAPABILITIES,
+    SANDBOX_UNAVAILABLE,
+    STORAGE_BASE,
+    MafSandbox,
+    deepagents_spec,
+)
+
+__all__ = [
+    "DEEPAGENTS_KIND",
+    "DEFAULT_EXEC_TIMEOUT_SECONDS",
+    "DEFAULT_MAX_OUTPUT_BYTES",
+    "DEFAULT_WORK_DIR",
+    "REQUIRED_CAPABILITIES",
+    "SANDBOX_UNAVAILABLE",
+    "STORAGE_BASE",
+    "MafSandbox",
+    "MafSandboxDeepagentsExperimentalWarning",
+    "deepagents_spec",
+]
+
+# 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 MafSandboxDeepagentsExperimentalWarning(UserWarning):
+    """Warning category for maf-sandbox-deepagents's experimental-package notice."""
+
+
+def _warn_experimental() -> None:
+    message = (
+        "maf_sandbox_deepagents is experimental and may change or be removed in future versions "
+        "without notice."
+    )
+    try:
+        _warnings.warn(message, category=MafSandboxDeepagentsExperimentalWarning, stacklevel=2)
+    except MafSandboxDeepagentsExperimentalWarning:
+        # Deliberate: under `-W error` an informational notice must not fail the import.
+        pass
+
+
+_warn_experimental()

maf_sandbox_deepagents-0.1.0/src/maf_sandbox_deepagents/_sandbox.py

@@ -0,0 +1,830 @@
+"""The adapter: a ``maf_sandbox`` router behind Deep Agents' ``BaseSandbox``.
+
+Deep Agents hands an agent one ``execute`` tool over a sandbox object the host constructs, and
+derives its file tools from ``execute`` and ``upload_files``. This module implements that
+object over a :class:`~maf_sandbox.SandboxRouter`: the router still refuses a backend below
+the host's isolation floor or one that cannot enforce the spec's egress mode, and the sandbox
+is still keyed from the host's request context and purged with the conversation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import dataclasses
+import hashlib
+import json
+import logging
+import math
+import posixpath
+import time
+import uuid
+from pathlib import PurePosixPath
+from typing import Any
+
+from deepagents.backends.protocol import (
+    FILE_NOT_FOUND,
+    INVALID_PATH,
+    IS_DIRECTORY,
+    PERMISSION_DENIED,
+    ExecuteResponse,
+    FileDownloadResponse,
+    FileUploadResponse,
+)
+from deepagents.backends.sandbox import BaseSandbox
+from maf_sandbox import (
+    DEFAULT_TRANSFER_LIMITS,
+    BoundedExec,
+    Capability,
+    Cleanup,
+    Egress,
+    EgressRule,
+    ExecResult,
+    FileRefusal,
+    Isolation,
+    IsolationScope,
+    NoSandboxBackend,
+    Sandbox,
+    SandboxExecOutputLimitExceeded,
+    SandboxFileRefused,
+    SandboxKey,
+    SandboxRouter,
+    SandboxShellTransferFailed,
+    SandboxShellTransferUnfinished,
+    SandboxSpec,
+    SandboxTransferCapExceeded,
+    SyncRunner,
+    TransferLimits,
+    entry_refusal,
+    file_refusal,
+    read_file_over_exec,
+    write_file_over_exec,
+)
+from maf_sandbox.paths import posix_work_dir_ancestors
+
+__all__ = [
+    "DEEPAGENTS_KIND",
+    "DEFAULT_EXEC_TIMEOUT_SECONDS",
+    "DEFAULT_MAX_OUTPUT_BYTES",
+    "DEFAULT_WORK_DIR",
+    "REQUIRED_CAPABILITIES",
+    "SANDBOX_UNAVAILABLE",
+    "STORAGE_BASE",
+    "MafSandbox",
+    "deepagents_spec",
+]
+
+logger = logging.getLogger(__name__)
+
+#: The ``kind`` a Deep Agents sandbox is keyed under. Part of the sandbox's identity, so an
+#: agent's shell never shares a container with a packaged kind serving the same conversation.
+DEEPAGENTS_KIND = "deepagents"
+
+#: What Deep Agents needs from a backend: a shell, files pushed in for ``upload_files`` and
+#: ``write_file``, files pulled out for ``download_files``. The other derived tools run on
+#: ``execute`` alone, and ``write_file`` runs a Python preflight there before it uploads.
+REQUIRED_CAPABILITIES: frozenset[Capability] = frozenset(
+    {Capability.EXEC, Capability.FILES_IN, Capability.FILES_OUT}
+)
+
+DEFAULT_EXEC_TIMEOUT_SECONDS = 120.0
+
+#: The most combined stdout and stderr one command may return, in bytes. Above the 500 KiB
+#: page Deep Agents' own ``read_file`` renders, so a large read still comes back whole; a
+#: command past it is refused rather than truncated, which is the suite's bounded-exec contract.
+DEFAULT_MAX_OUTPUT_BYTES = 1_048_576
+
+#: The protocol's default base, read off the spec rather than spelled a second time here.
+DEFAULT_WORK_DIR: str | None = SandboxSpec(kind=DEEPAGENTS_KIND).work_dir
+
+#: The acquired sandbox's storage base, addressed relatively: every command runs there and
+#: every upload and download path is relative to it. The backend resolves it to the base the
+#: spec named; a spec that names none is refused at construction.
+STORAGE_BASE = "."
+
+#: What the model reads when the router or the backend could not serve a call. Fixed, because
+#: the provider's own message can carry an endpoint or a tenant and a tool result is persisted
+#: into the transcript; the detail goes to the log.
+SANDBOX_UNAVAILABLE = "Error: sandbox unavailable — the command did not run."
+
+#: Says only what every backend can establish: the wait ended. Whether the command was
+#: stopped is the backend's own contract, and differs between them.
+_TIMED_OUT = "Error: the command did not finish within {seconds:g} seconds."
+#: Distinct from :data:`SANDBOX_UNAVAILABLE`: the command may have run, and the result is what
+#: did not come back.
+_EXEC_FAILED = "Error: the sandbox did not return the command's result; see the host log."
+#: The whole output is dropped, not cut: the backend refuses past the budget and returns none
+#: of it, so a partial result is never mistaken for a program that printed less.
+_OUTPUT_DROPPED = "Error: the command's output exceeded {limit} bytes and was dropped."
+_UNBOUNDED = (
+    "Error: sandbox unavailable — the backend cannot bound the command's output, so the "
+    "command did not run."
+)
+_UPLOAD_FAILED = "upload failed; see the host log"
+#: A shell transfer that did not finish — a timeout, an output overflow, the caller leaving —
+#: condemns the sandbox, and everything the batch had put there goes with it. Condemned, not
+#: disposed: the delete is queued with the router and may still be pending, or fail.
+_UPLOAD_BATCH_LOST = (
+    "the sandbox is condemned after a transfer did not finish; the batch did not land"
+)
+_DOWNLOAD_BATCH_LOST = (
+    "the sandbox is condemned after a transfer did not finish; the rest of the batch was not read"
+)
+_DOWNLOAD_FAILED = "download failed; see the host log"
+_SIZE_UNKNOWN = "the sandbox could not report the file's size"
+_TOO_MANY_FILES = "the batch has more files than {direction}.max_files allows"
+_NO_SHELL_ROAD = (
+    "the path is outside the storage base and the backend cannot run a bounded command to reach it"
+)
+
+_OVER_FILE_CAP = "the file is larger than {direction}.max_bytes_per_file"
+_OVER_TOTAL_CAP = "the batch would exceed {direction}.max_total_bytes"
+
+
+def deepagents_spec(
+    image: str | None = None,
+    *,
+    image_id: str | None = None,
+    egress_allow: tuple[str | EgressRule, ...] = (),
+    work_dir: str | None = DEFAULT_WORK_DIR,
+    files_in: TransferLimits = DEFAULT_TRANSFER_LIMITS,
+    files_out: TransferLimits = DEFAULT_TRANSFER_LIMITS,
+    min_isolation: Isolation | None = None,
+    kind: str = DEEPAGENTS_KIND,
+) -> SandboxSpec:
+    """The spec a Deep Agents sandbox asks for.
+
+    Egress is derived, never passed: named hosts run :data:`~maf_sandbox.Egress.ALLOWLIST` with
+    those hosts as the payload, and none runs :data:`~maf_sandbox.Egress.CLOSED`. The open
+    posture is not expressible, because the agent writes the shell commands this sandbox runs.
+
+    ``work_dir`` names the base the agent's file paths resolve under. It is the one field of
+    the spec :class:`MafSandbox` refuses ``None`` for.
+    """
+    return SandboxSpec(
+        kind=kind,
+        image=image,
+        image_id=image_id,
+        egress_allow=tuple(egress_allow),
+        egress=Egress.ALLOWLIST if egress_allow else Egress.CLOSED,
+        work_dir=work_dir,
+        requires=REQUIRED_CAPABILITIES,
+        files_in=files_in,
+        files_out=files_out,
+        min_isolation=min_isolation,
+    )
+
+
+#: One loop on a thread of its own for the synchronous surface, shared by every adapter in
+#: the process: Deep Agents calls that surface from sync tools, which LangGraph runs on a
+#: worker thread with no loop, and a backend may cache a client per loop (ACAS does).
+_SYNC = SyncRunner(thread_name="maf-sandbox-deepagents")
+
+
+def _response(result: ExecResult, *, max_output_bytes: int | None = None) -> ExecuteResponse:
+    """One combined stream, the way Deep Agents' own backends render it.
+
+    Each ``stderr`` line is prefixed so the model can tell the two apart, and the prefix says
+    whose words they are: a producer that took the field is speaking there, not the program.
+    The prefixes grow the stream, so it is held to ``max_output_bytes`` again once rendered:
+    the budget is what reaches the model, and a stream of short lines must not step over it.
+    """
+    parts: list[str] = []
+    if result.stdout:
+        parts.append(result.stdout)
+    if result.stderr:
+        label = "[note]" if result.producer_owns_stderr else "[stderr]"
+        parts.extend(f"{label} {line}" for line in result.stderr.strip().splitlines())
+    output = "\n".join(parts) if parts else "<no output>"
+    if max_output_bytes is not None and len(output.encode("utf-8")) > max_output_bytes:
+        return ExecuteResponse(
+            output=_OUTPUT_DROPPED.format(limit=max_output_bytes), exit_code=None, truncated=True
+        )
+    return ExecuteResponse(output=output, exit_code=result.exit_code, truncated=False)
+
+
+@dataclasses.dataclass
+class _Call:
+    """One admitted operation: its owner token, its admission, and the sandbox it acquired."""
+
+    owner: str
+    admission: Any
+    sandbox: Sandbox | None = None
+    condemned: bool = False
+
+
+class _BatchLost(Exception):
+    """The sandbox went in the middle of a batch; ``response`` answers the file that took it."""
+
+    def __init__(self, response: FileDownloadResponse | None = None) -> None:
+        super().__init__()
+        self.response = response
+
+
+#: Deep Agents' code for each refusal the core's file roads name.
+_CODES = {
+    FileRefusal.NOT_FOUND: FILE_NOT_FOUND,
+    FileRefusal.IS_DIRECTORY: IS_DIRECTORY,
+    FileRefusal.PERMISSION_DENIED: PERMISSION_DENIED,
+    FileRefusal.INVALID_PATH: INVALID_PATH,
+}
+
+
+class MafSandbox(BaseSandbox):
+    """A :class:`~maf_sandbox.SandboxRouter` as a Deep Agents sandbox.
+
+    One instance serves one conversation: ``key`` is the host's scope, thread and agent
+    directory, read from the host's request context and never from the model. The sandbox is
+    acquired on first use — get-or-create, so it stays warm across turns — and lives until the
+    host disposes it: :meth:`aclose` here, or the router's ``dispose_scope`` on the host's own
+    conversation-delete path, which is what every other sandbox in the suite answers to.
+
+    Construction refuses what the router refuses — no backend at all, one below the isolation
+    floor, one that cannot enforce the spec's egress mode, a missing capability — so a
+    misconfigured host fails before an agent is built, not on its first command.
+
+    Paths are guest paths, as they are for every sandbox Deep Agents ships: the agent's file
+    tools name them absolutely. Inside ``spec.work_dir`` the adapter's upload and download go
+    through the backend's file plane; outside it, where Deep Agents keeps its offloaded history
+    and its large-edit temporaries, they go through the shell the agent already has, in base64
+    chunks, under the same caps. The host puts ``spec.work_dir`` in the prompt so the model
+    knows where its own files are; a spec leaving the base to the backend is refused, because
+    nothing could then tell the model.
+
+    Deep Agents' derived file tools (``ls``, ``read_file``, ``write_file``, ``edit_file``,
+    ``glob``, ``grep``) run ``python3`` inside the guest, ``write_file`` for the preflight that
+    creates the parent directory before it uploads; on an image without it only ``execute``,
+    ``delete`` and this class's own upload and download work. The image is the host's to choose.
+
+    Every command runs under ``max_output_bytes``, enforced by the backend before it buffers
+    the output: the model writes the command, so what it prints is bounded on the host or the
+    command does not run.
+    """
+
+    def __init__(
+        self,
+        router: SandboxRouter,
+        key: SandboxKey,
+        spec: SandboxSpec,
+        *,
+        exec_timeout_seconds: float = DEFAULT_EXEC_TIMEOUT_SECONDS,
+        max_output_bytes: int = DEFAULT_MAX_OUTPUT_BYTES,
+    ) -> None:
+        missing = REQUIRED_CAPABILITIES - spec.requires
+        if missing:
+            raise ValueError(
+                f"the {spec.kind!r} spec does not require {sorted(str(c) for c in missing)}, "
+                "which Deep Agents' execute, write and download tools need; build it with "
+                "deepagents_spec()"
+            )
+        if spec.isolation_scope is not IsolationScope.CONVERSATION:
+            raise ValueError(
+                "a Deep Agents sandbox serves a whole conversation, so the spec cannot ask for "
+                f"isolation_scope={spec.isolation_scope!r}"
+            )
+        if key.call_id:
+            raise ValueError("key.call_id must be empty: one sandbox serves the conversation")
+        if spec.egress is Egress.UNRESTRICTED:
+            # `deepagents_spec` cannot express it; a spec built another way must not either.
+            raise ValueError(
+                "spec.egress must be CLOSED or ALLOWLIST: the model writes the commands, so an "
+                "open network is not a posture this sandbox takes"
+            )
+        if spec.work_dir is None:
+            # Deep Agents' file tools take guest paths the model spells out, so the host has to
+            # be able to tell it the base; a backend-allocated one is knowable to neither.
+            raise ValueError(
+                "spec.work_dir must name the storage base: Deep Agents addresses files by "
+                "guest path, and a base the backend allocates is one nothing can tell the model"
+            )
+        # The backends' own rule for a named base, applied here so a relative, empty or
+        # NUL-bearing base is a host configuration error at construction, not a sandbox
+        # unavailable on the first command.
+        posix_work_dir_ancestors(spec.work_dir)
+        if not math.isfinite(exec_timeout_seconds) or exec_timeout_seconds <= 0:
+            raise ValueError("exec_timeout_seconds must be a finite positive number of seconds")
+        if type(max_output_bytes) is not int or max_output_bytes <= 0:
+            raise ValueError("max_output_bytes must be a positive integer of bytes")
+        if not router.enabled:
+            raise NoSandboxBackend("no sandbox backend is configured")
+        router.ensure_can_serve(spec)
+        self._router = router
+        self._key = key
+        self._spec = spec
+        self._timeout = float(exec_timeout_seconds)
+        self._max_output_bytes = max_output_bytes
+        #: The engine instance the last acquire handed back, and what `aclose` deletes.
+        self._instance_id: str | None = None
+        backend = router.backend_for(spec)
+        identity = [
+            # The backend object, not only its name: two backends may carry one name and
+            # reach two engines (two Docker daemons, two ACA resources), and Deep Agents asks
+            # for an id unique to the backend it is given. The object lives as long as the
+            # router this adapter holds, so its identity cannot be reused under it.
+            "" if backend is None else f"{backend.name}@{id(backend):x}",
+            key.scope,
+            key.thread_id,
+            key.agent_dir,
+            spec.kind,
+            str(spec.egress),
+            sorted(str(entry) for entry in spec.egress_allow),
+        ]
+        digest = hashlib.sha256(json.dumps(identity, separators=(",", ":")).encode()).hexdigest()
+        # The id names the sandbox, as a provider's own id would: two adapters over one key,
+        # kind, backend and egress posture reach one sandbox through the router's get-or-create,
+        # and say so; a backend keys a container on the egress posture too. Opaque rather than
+        # the key spelled out, because Deep Agents may render it to the model and a scope is
+        # often a tenant or a user.
+        self._id = f"maf-sandbox-{digest[:16]}"
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def key(self) -> SandboxKey:
+        """What this sandbox is keyed by."""
+        return self._key
+
+    @property
+    def spec(self) -> SandboxSpec:
+        """The sandbox this instance asks the router for."""
+        return self._spec
+
+    @property
+    def router(self) -> SandboxRouter:
+        """The router serving this sandbox."""
+        return self._router
+
+    async def _open(self, bound: float) -> tuple[_Call, Sandbox] | None:
+        """Admit a call and acquire its sandbox under one deadline.
+
+        Admission is the router's call lifecycle, shared by every call over this key from
+        this adapter or another: a delete one call queued runs when the last of them leaves,
+        and a new call waits for it, so nothing in flight is cut off and nothing reaches an
+        instance being deleted. ``None`` when the sandbox is unavailable, with the reason in
+        the log; ``TimeoutError`` when the deadline passed.
+        """
+        owner = uuid.uuid4().hex
+        call: _Call | None = None
+        try:
+            async with asyncio.timeout(bound):
+                try:
+                    admission = await self._router.enter_call(
+                        self._key, self._spec, owner=owner, timeout=bound
+                    )
+                except TimeoutError:
+                    raise
+                except Exception:
+                    logger.exception("%s: the call was not admitted", self._id)
+                    return None
+                call = _Call(owner, admission)
+                try:
+                    sandbox = await self._router.acquire(
+                        self._key, self._spec, _admission=admission
+                    )
+                except asyncio.CancelledError:
+                    # The deadline, or the caller leaving: the admission must not outlive
+                    # the call, or an exclusive close and every queued delete wait on it.
+                    await self._leave(call, deferred=True)
+                    call = None
+                    raise
+                except Exception:
+                    logger.exception("%s: the sandbox could not be acquired", self._id)
+                    await self._leave(call)
+                    return None
+        except TimeoutError:
+            if call is not None:
+                await self._leave(call, deferred=True)
+            raise
+        self._instance_id = sandbox.instance_id
+        call.sandbox = sandbox
+        return call, sandbox
+
+    def _condemn(self, call: _Call) -> None:
+        """Queue the instance's delete with the router, for when the last call over this key
+        leaves. `aclose` keeps naming the instance: a delete that failed is retried there, and
+        one that landed makes that a no-op under the protocol."""
+        if call.condemned or call.sandbox is None:
+            return
+        call.condemned = True
+        self._router.queue_cleanup(
+            self._key,
+            self._spec,
+            admission=call.admission,
+            sandbox=call.sandbox,
+            owner=call.owner,
+            rung=Cleanup.DISPOSE,
+        )
+
+    def _log_unfinished(
+        self, what: str, path: str, unfinished: SandboxShellTransferUnfinished
+    ) -> None:
+        """A timeout or an overflow is a warning; a failure that kept the result from coming
+        back is an error, with the provider's words and traceback for the host."""
+        expected = isinstance(unfinished.__cause__, (TimeoutError, SandboxExecOutputLimitExceeded))
+        logger.log(
+            logging.WARNING if expected else logging.ERROR,
+            "%s: %s of %r did not finish: %s",
+            self._id,
+            what,
+            path,
+            unfinished,
+            exc_info=not expected,
+        )
+
+    async def _leave(self, call: _Call, *, deferred: bool = False) -> None:
+        """Release the admission; the last call out runs whatever delete was queued.
+
+        After an unfinished command that release goes to the process's own loop, so the
+        delete never extends the caller's wait and outlives a loop ``asyncio.run`` closes on
+        return; the next call over the key is admitted once it is done.
+        """
+        if not (call.condemned or deferred):
+            await self._router.release_call(self._key, self._spec.kind, owner=call.owner)
+            return
+        # `SyncRunner.submit` takes the coroutine itself and runs it on the process's loop.
+        released = _SYNC.submit(
+            self._router.release_call(self._key, self._spec.kind, owner=call.owner)
+        )
+        released.add_done_callback(self._left)
+
+    def _left(self, future: concurrent.futures.Future[None]) -> None:
+        if future.cancelled():
+            logger.warning("%s: the release after an unfinished command was cancelled", self._id)
+        elif (failure := future.exception()) is not None:
+            logger.error(
+                "%s: the release after an unfinished command failed: %s", self._id, failure
+            )
+
+    async def _run_bounded(
+        self, call: _Call, command: str, *, timeout: float, max_output_bytes: int
+    ) -> ExecResult:
+        """``exec_bounded``, with the instance condemned whenever the command's end is unknown.
+
+        A timeout says the wait ended, an overflow that the host stopped reading, a
+        cancellation that the caller left, and any other failure that the result did not come
+        back: none says the guest process stopped, and the backends do not establish it
+        either, so the instance goes before anything reuses it.
+        """
+        sandbox = call.sandbox
+        assert isinstance(sandbox, BoundedExec)
+        try:
+            return await sandbox.exec_bounded(
+                command,
+                working_directory=STORAGE_BASE,
+                timeout=timeout,
+                max_output_bytes=max_output_bytes,
+            )
+        except BaseException:
+            self._condemn(call)
+            raise
+
+    def _inside_base(self, path: str) -> bool:
+        """Whether ``path`` names something under the storage base, the file plane's reach."""
+        if not path.startswith("/"):
+            return True
+        # Both sides normalized: a spec may spell the base with `..`, and the backends resolve
+        # it before they confine to it.
+        base = PurePosixPath(posixpath.normpath(self._spec.work_dir or "/"))
+        normalized = PurePosixPath(posixpath.normpath(path))
+        return normalized == base or base in normalized.parents
+
+    # --- execute ---------------------------------------------------------------------------
+
+    async def aexecute(self, command: str, *, timeout: int | None = None) -> ExecuteResponse:
+        if not command or not isinstance(command, str):  # pyright: ignore[reportUnnecessaryIsInstance]
+            return ExecuteResponse(output="Error: Command must be a non-empty string.", exit_code=1)
+        bound = self._timeout if timeout is None else float(timeout)
+        if not math.isfinite(bound) or bound <= 0:
+            raise ValueError(f"timeout must be a finite positive number of seconds, got {timeout}")
+        # One deadline over the acquire and the command: a cold create spends part of the
+        # budget Deep Agents defines as the wait for the command, is cut off if it outlives
+        # it, and the command gets the rest.
+        started = time.monotonic()
+        try:
+            opened = await self._open(bound)
+        except TimeoutError:
+            return ExecuteResponse(output=_TIMED_OUT.format(seconds=bound), exit_code=None)
+        if opened is None:
+            return ExecuteResponse(output=SANDBOX_UNAVAILABLE, exit_code=None)
+        call, sandbox = opened
+        try:
+            if not isinstance(sandbox, BoundedExec):
+                logger.error("%s: the backend has no exec_bounded, so no command runs", self._id)
+                return ExecuteResponse(output=_UNBOUNDED, exit_code=None)
+            remaining = bound - (time.monotonic() - started)
+            if remaining <= 0:
+                return ExecuteResponse(output=_TIMED_OUT.format(seconds=bound), exit_code=None)
+            try:
+                result = await self._run_bounded(
+                    call, command, timeout=remaining, max_output_bytes=self._max_output_bytes
+                )
+            except TimeoutError:
+                return ExecuteResponse(output=_TIMED_OUT.format(seconds=bound), exit_code=None)
+            except SandboxExecOutputLimitExceeded:
+                return ExecuteResponse(
+                    output=_OUTPUT_DROPPED.format(limit=self._max_output_bytes),
+                    exit_code=None,
+                    truncated=True,
+                )
+            except Exception:
+                logger.exception("%s: the command's result could not be read", self._id)
+                return ExecuteResponse(output=_EXEC_FAILED, exit_code=None)
+            return _response(result, max_output_bytes=self._max_output_bytes)
+        finally:
+            await self._leave(call)
+
+    def execute(self, command: str, *, timeout: int | None = None) -> ExecuteResponse:
+        return _SYNC.run(self.aexecute(command, timeout=timeout))
+
+    # --- files in --------------------------------------------------------------------------
+
+    async def aupload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        if not files:
+            # Nothing to land: no call, so no sandbox is created for a batch of none.
+            return []
+        limits = self._spec.files_in
+        if len(files) > limits.max_files:
+            refusal = _TOO_MANY_FILES.format(direction="files_in")
+            return [FileUploadResponse(path=path, error=refusal) for path, _ in files]
+        try:
+            opened = await self._open(self._timeout)
+        except TimeoutError:
+            opened = None
+        if opened is None:
+            return [FileUploadResponse(path=path, error=_UPLOAD_FAILED) for path, _ in files]
+        call, sandbox = opened
+        try:
+            responses: list[FileUploadResponse] = []
+            sent = 0
+            for path, content in files:
+                # Checked before the write it would have prevented, and counted only for what
+                # crossed: a refused file leaves the budget where it was.
+                error: str | None
+                try:
+                    if len(content) > limits.max_bytes_per_file:
+                        error = _OVER_FILE_CAP.format(direction="files_in")
+                    elif sent + len(content) > limits.max_total_bytes:
+                        error = _OVER_TOTAL_CAP.format(direction="files_in")
+                    elif self._inside_base(path):
+                        error = await self._upload_via_plane(call, sandbox, path, content)
+                    elif isinstance(sandbox, BoundedExec):
+                        error = await self._upload_via_shell(call, sandbox, path, content)
+                    else:
+                        error = _NO_SHELL_ROAD
+                except _BatchLost:
+                    return [FileUploadResponse(path=p, error=_UPLOAD_BATCH_LOST) for p, _ in files]
+                if error is None:
+                    sent += len(content)
+                responses.append(FileUploadResponse(path=path, error=error))
+            return responses
+        finally:
+            await self._leave(call)
+
+    async def _upload_via_plane(
+        self, call: _Call, sandbox: Sandbox, path: str, content: bytes
+    ) -> str | None:
+        """Write under the base through the file plane; the error code, or ``None``.
+
+        A write the plane did not refuse and did not finish — a transport failure, the caller
+        leaving — may have left part of the file, and the plane does not promise otherwise, so
+        the instance is condemned and the batch ends, as on the shell road.
+        """
+        try:
+            await sandbox.write_file(path, content, working_directory=STORAGE_BASE)
+        except asyncio.CancelledError:
+            self._condemn(call)
+            raise
+        except Exception as failed:
+            refusal = file_refusal(failed)
+            if refusal is None:
+                logger.exception("%s: upload of %r failed", self._id, path)
+                self._condemn(call)
+                raise _BatchLost() from None
+            logger.info("%s: upload of %r refused: %s", self._id, path, failed)
+            return _CODES[refusal]
+        return None
+
+    async def _upload_via_shell(
+        self, call: _Call, sandbox: BoundedExec, path: str, content: bytes
+    ) -> str | None:
+        """Write outside the base through the shell the agent already has.
+
+        Deep Agents writes its offloaded history under ``/conversation_history`` and its
+        large-edit temporaries under ``/tmp``, which the file plane, confined to the base,
+        cannot reach; ``execute`` can, so this widens nothing. The caps were applied by the
+        caller. The road is the core's, and lands the file whole or not at all; a command
+        whose end is unknown condemns the instance and ends the batch, with every file it
+        had already put there.
+        """
+        try:
+            await write_file_over_exec(
+                sandbox, path, content, working_directory=STORAGE_BASE, timeout=self._timeout
+            )
+        except SandboxFileRefused as refused:
+            logger.info("%s: shell write of %r refused: %s", self._id, path, refused.detail)
+            return _CODES[refused.refusal]
+        except SandboxShellTransferUnfinished as unfinished:
+            self._log_unfinished("shell write", path, unfinished)
+            self._condemn(call)
+            raise _BatchLost() from None
+        except SandboxShellTransferFailed as failed:
+            # The command ended and said something the road does not read as a refusal: a
+            # missing utility, an I/O error. The file did not land; the sandbox is whole.
+            logger.warning("%s: shell write of %r failed: %s", self._id, path, failed)
+            return _UPLOAD_FAILED
+        except asyncio.CancelledError:
+            self._condemn(call)
+            raise
+        return None
+
+    def upload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        return _SYNC.run(self.aupload_files(files))
+
+    # --- files out -------------------------------------------------------------------------
+
+    async def _download(
+        self, call: _Call, sandbox: Sandbox, path: str, *, room: int
+    ) -> FileDownloadResponse:
+        """One file, read under the smaller of the per-file cap and ``room``, the batch's rest."""
+        per_file = self._spec.files_out.max_bytes_per_file
+        cap = min(per_file, room)
+        # Which ceiling `cap` is: read off the cap handed down, never off a stat that a
+        # growing file has already made stale.
+        over_cap = (_OVER_FILE_CAP if cap == per_file else _OVER_TOTAL_CAP).format(
+            direction="files_out"
+        )
+        if not self._inside_base(path):
+            if not isinstance(sandbox, BoundedExec):
+                return FileDownloadResponse(path=path, error=_NO_SHELL_ROAD)
+            return await self._download_via_shell(call, sandbox, path, cap=cap, over_cap=over_cap)
+        try:
+            entry = await sandbox.stat_file(path, working_directory=STORAGE_BASE)
+        except TimeoutError:
+            # Not condemned: a read changes nothing in the sandbox, and the bound is the
+            # backend's own, its refusal of an entry it cannot serve (ACAS reads a FIFO the
+            # guest planted as a regular file until the bound). The shell road condemns
+            # because a command whose end is unknown may still be running.
+            logger.warning("%s: stat of %r timed out", self._id, path)
+            return FileDownloadResponse(path=path, error=_DOWNLOAD_FAILED)
+        except Exception as failed:
+            refusal = file_refusal(failed)
+            if refusal is None:
+                raise
+            logger.info("%s: download of %r refused: %s", self._id, path, failed)
+            return FileDownloadResponse(path=path, error=_CODES[refusal])
+        refusal = entry_refusal(entry)
+        if entry is None or refusal is not None:
+            return FileDownloadResponse(path=path, error=_CODES[refusal or FileRefusal.NOT_FOUND])
+        # `None` fails closed: an unknown size read as free is how a cap stops bounding.
+        if entry.size_bytes is None:
+            return FileDownloadResponse(path=path, error=_SIZE_UNKNOWN)
+        if entry.size_bytes > cap:
+            return FileDownloadResponse(path=path, error=over_cap)
+        # A batch that has spent its total leaves no room, and the plane's cap must be
+        # positive; one byte lets an empty file through and the re-count below refuse the rest.
+        try:
+            content = await sandbox.read_file(
+                path, working_directory=STORAGE_BASE, max_bytes=max(cap, 1)
+            )
+        except SandboxTransferCapExceeded:
+            return FileDownloadResponse(path=path, error=over_cap)
+        except TimeoutError:
+            # Not condemned, for the reason given at the stat: the file is failed alone.
+            logger.warning("%s: read of %r timed out", self._id, path)
+            return FileDownloadResponse(path=path, error=_DOWNLOAD_FAILED)
+        except Exception as failed:
+            refusal = file_refusal(failed)
+            if refusal is None:
+                raise
+            logger.info("%s: download of %r refused: %s", self._id, path, failed)
+            return FileDownloadResponse(path=path, error=_CODES[refusal])
+        if len(content) > cap:
+            # The protocol has the caller re-count: a file can grow after the stat, and a
+            # backend whose SDK buffers the whole response can only refuse after the fact.
+            return FileDownloadResponse(path=path, error=over_cap)
+        return FileDownloadResponse(path=path, content=content)
+
+    async def _download_via_shell(
+        self, call: _Call, sandbox: BoundedExec, path: str, *, cap: int, over_cap: str
+    ) -> FileDownloadResponse:
+        """Read outside the base through the shell, under ``cap``; see :meth:`_upload_via_shell`."""
+        try:
+            # A batch that has spent its total leaves no room; one byte keeps the probe's
+            # classification and lets an empty file through, and the re-count refuses the rest.
+            content = await read_file_over_exec(
+                sandbox,
+                path,
+                working_directory=STORAGE_BASE,
+                timeout=self._timeout,
+                max_bytes=max(cap, 1),
+            )
+        except SandboxFileRefused as refused:
+            logger.info("%s: shell read of %r refused: %s", self._id, path, refused.detail)
+            return FileDownloadResponse(path=path, error=_CODES[refused.refusal])
+        except SandboxTransferCapExceeded:
+            return FileDownloadResponse(path=path, error=over_cap)
+        except SandboxShellTransferUnfinished as unfinished:
+            # The command may still be running: the instance goes, and the rest of the batch
+            # is not attempted. A read its own budget ended is over the cap, and says so.
+            self._log_unfinished("shell read", path, unfinished)
+            self._condemn(call)
+            error = over_cap if unfinished.over_cap else _DOWNLOAD_BATCH_LOST
+            raise _BatchLost(FileDownloadResponse(path=path, error=error)) from None
+        except SandboxShellTransferFailed as failed:
+            logger.warning("%s: shell read of %r failed: %s", self._id, path, failed)
+            return FileDownloadResponse(path=path, error=_DOWNLOAD_FAILED)
+        except asyncio.CancelledError:
+            self._condemn(call)
+            raise
+        if len(content) > cap:
+            return FileDownloadResponse(path=path, error=over_cap)
+        return FileDownloadResponse(path=path, content=content)
+
+    async def adownload_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        if not paths:
+            return []
+        limits = self._spec.files_out
+        if len(paths) > limits.max_files:
+            refusal = _TOO_MANY_FILES.format(direction="files_out")
+            return [FileDownloadResponse(path=path, error=refusal) for path in paths]
+        try:
+            opened = await self._open(self._timeout)
+        except TimeoutError:
+            opened = None
+        if opened is None:
+            return [FileDownloadResponse(path=path, error=_DOWNLOAD_FAILED) for path in paths]
+        call, sandbox = opened
+        try:
+            responses: list[FileDownloadResponse] = []
+            room = limits.max_total_bytes
+            for path in paths:
+                try:
+                    response = await self._download(call, sandbox, path, room=room)
+                except _BatchLost as lost:
+                    responses.append(
+                        lost.response or FileDownloadResponse(path=path, error=_DOWNLOAD_BATCH_LOST)
+                    )
+                    rest = paths[len(responses) :]
+                    responses.extend(
+                        FileDownloadResponse(path=p, error=_DOWNLOAD_BATCH_LOST) for p in rest
+                    )
+                    break
+                except Exception:
+                    logger.exception("%s: download of %r failed", self._id, path)
+                    response = FileDownloadResponse(path=path, error=_DOWNLOAD_FAILED)
+                if response.content is not None:
+                    room -= len(response.content)
+                responses.append(response)
+            return responses
+        finally:
+            await self._leave(call)
+
+    def download_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        return _SYNC.run(self.adownload_files(paths))
+
+    # --- lifecycle -------------------------------------------------------------------------
+
+    async def aclose(self) -> bool:
+        """Delete this conversation's sandbox; ``False`` when the delete did not land.
+
+        Admitted exclusively first, so every call over this key, from this adapter or another,
+        has left and a delete one of them queued has run. Then deletes the one instance this
+        adapter acquired, so a packaged kind serving the same conversation, or another adapter
+        over the same key with a different backend or egress, keeps its own; before any
+        acquire there is nothing of this adapter's to delete. An instance a sibling's queued
+        delete already took is named again here, which the protocol makes a no-op. The
+        router's ``dispose_scope`` on the host's conversation-delete path is the backstop for
+        a sandbox no ``aclose`` reached.
+        """
+        owner = uuid.uuid4().hex
+        timeout = self._router.reclaim.timeout
+        try:
+            await self._router.enter_call(
+                self._key, self._spec, owner=owner, exclusive=True, timeout=timeout
+            )
+        except TimeoutError:
+            logger.warning("%s: close timed out waiting for the calls in flight", self._id)
+            return False
+        except Exception:
+            logger.exception("%s: close was not admitted", self._id)
+            return False
+        try:
+            instance_id = self._instance_id
+            if instance_id is None:
+                return True
+            disposed = await self._router.dispose_kind(
+                self._key, self._spec.kind, instance_id=instance_id, timeout=timeout
+            )
+            # Forgotten only once the delete landed, so a retry reaches the same instance;
+            # kept as is if an acquire replaced it meanwhile.
+            if disposed and self._instance_id == instance_id:
+                self._instance_id = None
+            return disposed
+        finally:
+            await self._router.release_call(self._key, self._spec.kind, owner=owner)
+
+    def close(self) -> bool:
+        """Synchronous :meth:`aclose`."""
+        return _SYNC.run(self.aclose())