e2b-adk 0.1.0__tar.gz

e2b_adk-0.1.0/.env.example

@@ -0,0 +1,2 @@
+E2B_API_KEY=
+GOOGLE_API_KEY=

e2b_adk-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+/.agents/
+/.claude/
+/.planning/
+
+# Python
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Docs staged here for separate PRs to other repos (e2b-dev/docs, google/adk-docs)
+/docs/
+
+# Features
+/features/
+/CLAUDE.md
+/AGENTS.md
+/CLAUDE_ADDITIONS.md
+/AGENTS_ADDITIONS.md
+/DECISIONS.md
+
+# Environment
+.env
+!.env.example
+
+# Verification credentials (never commit)
+.env.verification
+/.claude/verification/auth-state.json

e2b_adk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FoundryLabs, Inc.
+
+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.

e2b_adk-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: e2b-adk
+Version: 0.1.0
+Summary: Google ADK plugin backed by E2B sandboxes.
+Project-URL: Homepage, https://github.com/e2b-dev/e2b-adk-plugin
+Project-URL: Repository, https://github.com/e2b-dev/e2b-adk-plugin
+Project-URL: Issues, https://github.com/e2b-dev/e2b-adk-plugin/issues
+Author-email: e2b <hello@e2b.dev>
+License: MIT
+License-File: LICENSE
+Keywords: adk,agent,code-interpreter,e2b,google-adk,sandbox
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: e2b-code-interpreter<3,>=2.8.1
+Requires-Dist: e2b<3,>=2.32.0
+Requires-Dist: google-adk<3,>=2.3.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: python-dotenv; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# e2b-adk
+
+A [Google ADK](https://google.github.io/adk-docs/) plugin backed by
+[E2B](https://e2b.dev) sandboxes. Attach it to an ADK agent and the agent can
+generate and run code, execute shell commands, read and write files, and start
+long-running processes — all inside an isolated E2B sandbox, with no
+infrastructure of your own.
+
+Under the hood every tool call runs in the
+[E2B Code Interpreter](https://e2b.dev/docs), so the model's code executes in a
+real Python kernel instead of being trusted blind.
+
+## Install
+
+```bash
+pip install e2b-adk
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install e2b-adk
+```
+
+## Credentials
+
+You need an E2B API key for the sandbox and a model key for the agent's LLM
+(Gemini is ADK's default):
+
+```bash
+export E2B_API_KEY="..."
+export GOOGLE_API_KEY="..."
+```
+
+Get an E2B key at [e2b.dev/dashboard](https://e2b.dev/dashboard).
+
+## Quickstart
+
+Create the plugin, hand its tools to an `Agent`, and register the plugin on the
+`App`. The plugin owns the sandbox lifecycle — you never create or tear one down
+yourself.
+
+```python
+import asyncio
+
+from google.adk.agents import Agent
+from google.adk.apps import App
+from google.adk.runners import InMemoryRunner
+
+from e2b_adk import E2BPlugin
+
+
+async def main() -> None:
+    plugin = E2BPlugin()
+    agent = Agent(
+        model="gemini-2.5-flash",
+        name="coder",
+        instruction="Write and run Python to answer the user. Verify with run_code.",
+        tools=plugin.get_tools(),
+    )
+    app = App(name="demo", root_agent=agent, plugins=[plugin])
+
+    async with InMemoryRunner(app=app) as runner:
+        # run_debug prints the conversation as it runs.
+        await runner.run_debug("Compute the 20th Fibonacci number.")
+
+
+asyncio.run(main())
+```
+
+## Tools
+
+`plugin.get_tools()` returns six tools. Each returns a JSON-serializable dict
+with a `success` flag — tools report failures in the result rather than raising,
+so a bad call never aborts the agent run. `success` means the tool *ran*: code
+that raised or a command that exited non-zero still returns `success: True` with
+the failure captured in `error` / `exit_code`. Only a call that could not run at
+all (sandbox unavailable, timeout) returns `success: False`.
+
+| Tool | Does | Key result fields |
+|------|------|-------------------|
+| `run_code` | Run code in a stateful kernel (variables persist across calls) | `stdout`, `stderr`, `text`, `error` |
+| `run_command` | Run a shell command (each call is independent) | `stdout`, `stderr`, `exit_code` |
+| `write_file` | Write a file in the sandbox | `path` |
+| `read_file` | Read a file back | `path`, `content` |
+| `list_files` | List a directory | `entries` (`[{name, type}]`) |
+| `start_background_command` | Start a long-running process; optional preview URL for a port | `pid`, `preview_url` (+ `readiness` when `port` is set) |
+
+### Configuration
+
+`E2BPlugin` takes keyword-only options, all optional. Anything you don't set
+falls back to the E2B SDK's own default — the plugin overrides none of them.
+
+```python
+E2BPlugin(
+    # Common options
+    api_key=None,               # defaults to the E2B_API_KEY env var
+    template=None,              # E2B sandbox template
+    metadata=None,              # dict[str, str] attached to the sandbox
+    envs=None,                  # dict[str, str] environment variables
+    timeout=None,               # sandbox timeout in seconds (re-applied on every tool call)
+    plugin_name="e2b_plugin",
+    # Passed straight through to AsyncSandbox.create() — see the E2B SDK docs
+    secure=None,
+    allow_internet_access=None,
+    mcp=None,
+    network=None,
+    lifecycle=None,             # e.g. pause/auto-resume; defaults to E2B's behavior
+    volume_mounts=None,
+    # **opts: any other AsyncSandbox.create() / connection param (proxy, request_timeout, …)
+)
+```
+
+## Examples
+
+- [`examples/data_analysis.py`](examples/data_analysis.py) — a data-analysis
+  agent that saves a dataset and computes real answers with pandas instead of
+  guessing.
+- [`examples/code_generator.py`](examples/code_generator.py) — a code generator
+  that executes every snippet before returning it.
+
+Run one with the credentials above:
+
+```bash
+uv run --extra examples python examples/data_analysis.py
+```
+
+## v1 notes
+
+- **Sequential tool calls.** One sandbox is shared per plugin; calls are meant
+  to run one at a time, not concurrently. Concurrent calls are safe for the
+  sandbox lifecycle (creation is locked) but share one filesystem and kernel.
+- **Text-only output.** Tools return text — `stdout`/`stderr`/file contents.
+  Rich results (charts, dataframes, images) are not surfaced yet.
+- **Lazy, shared sandbox lifecycle.** The sandbox is created on the first tool
+  call and reused for the agent's lifetime, then killed when the runner exits.
+- **Keep-alive while active, expiry when idle.** While a sandbox SDK operation
+  is active, a best-effort heartbeat refreshes its `timeout` (E2B's default is
+  300s), including when a foreground call runs longer than that timeout. A
+  final refresh starts the full idle window when the operation ends. An idle
+  gap longer than `timeout` still expires the sandbox under E2B's default
+  lifecycle (`on_timeout: kill`), and later tool calls return failure results —
+  pass e.g.
+  `lifecycle={"on_timeout": {"action": "pause"}, "auto_resume": True}` to pause
+  and auto-resume across idle gaps instead.
+- **Bounded output.** Output larger than 10 KB per field is truncated with a
+  `…[truncated N bytes]` marker so a single call can't flood the model's context.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

e2b_adk-0.1.0/README.md

@@ -0,0 +1,151 @@
+# e2b-adk
+
+A [Google ADK](https://google.github.io/adk-docs/) plugin backed by
+[E2B](https://e2b.dev) sandboxes. Attach it to an ADK agent and the agent can
+generate and run code, execute shell commands, read and write files, and start
+long-running processes — all inside an isolated E2B sandbox, with no
+infrastructure of your own.
+
+Under the hood every tool call runs in the
+[E2B Code Interpreter](https://e2b.dev/docs), so the model's code executes in a
+real Python kernel instead of being trusted blind.
+
+## Install
+
+```bash
+pip install e2b-adk
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv pip install e2b-adk
+```
+
+## Credentials
+
+You need an E2B API key for the sandbox and a model key for the agent's LLM
+(Gemini is ADK's default):
+
+```bash
+export E2B_API_KEY="..."
+export GOOGLE_API_KEY="..."
+```
+
+Get an E2B key at [e2b.dev/dashboard](https://e2b.dev/dashboard).
+
+## Quickstart
+
+Create the plugin, hand its tools to an `Agent`, and register the plugin on the
+`App`. The plugin owns the sandbox lifecycle — you never create or tear one down
+yourself.
+
+```python
+import asyncio
+
+from google.adk.agents import Agent
+from google.adk.apps import App
+from google.adk.runners import InMemoryRunner
+
+from e2b_adk import E2BPlugin
+
+
+async def main() -> None:
+    plugin = E2BPlugin()
+    agent = Agent(
+        model="gemini-2.5-flash",
+        name="coder",
+        instruction="Write and run Python to answer the user. Verify with run_code.",
+        tools=plugin.get_tools(),
+    )
+    app = App(name="demo", root_agent=agent, plugins=[plugin])
+
+    async with InMemoryRunner(app=app) as runner:
+        # run_debug prints the conversation as it runs.
+        await runner.run_debug("Compute the 20th Fibonacci number.")
+
+
+asyncio.run(main())
+```
+
+## Tools
+
+`plugin.get_tools()` returns six tools. Each returns a JSON-serializable dict
+with a `success` flag — tools report failures in the result rather than raising,
+so a bad call never aborts the agent run. `success` means the tool *ran*: code
+that raised or a command that exited non-zero still returns `success: True` with
+the failure captured in `error` / `exit_code`. Only a call that could not run at
+all (sandbox unavailable, timeout) returns `success: False`.
+
+| Tool | Does | Key result fields |
+|------|------|-------------------|
+| `run_code` | Run code in a stateful kernel (variables persist across calls) | `stdout`, `stderr`, `text`, `error` |
+| `run_command` | Run a shell command (each call is independent) | `stdout`, `stderr`, `exit_code` |
+| `write_file` | Write a file in the sandbox | `path` |
+| `read_file` | Read a file back | `path`, `content` |
+| `list_files` | List a directory | `entries` (`[{name, type}]`) |
+| `start_background_command` | Start a long-running process; optional preview URL for a port | `pid`, `preview_url` (+ `readiness` when `port` is set) |
+
+### Configuration
+
+`E2BPlugin` takes keyword-only options, all optional. Anything you don't set
+falls back to the E2B SDK's own default — the plugin overrides none of them.
+
+```python
+E2BPlugin(
+    # Common options
+    api_key=None,               # defaults to the E2B_API_KEY env var
+    template=None,              # E2B sandbox template
+    metadata=None,              # dict[str, str] attached to the sandbox
+    envs=None,                  # dict[str, str] environment variables
+    timeout=None,               # sandbox timeout in seconds (re-applied on every tool call)
+    plugin_name="e2b_plugin",
+    # Passed straight through to AsyncSandbox.create() — see the E2B SDK docs
+    secure=None,
+    allow_internet_access=None,
+    mcp=None,
+    network=None,
+    lifecycle=None,             # e.g. pause/auto-resume; defaults to E2B's behavior
+    volume_mounts=None,
+    # **opts: any other AsyncSandbox.create() / connection param (proxy, request_timeout, …)
+)
+```
+
+## Examples
+
+- [`examples/data_analysis.py`](examples/data_analysis.py) — a data-analysis
+  agent that saves a dataset and computes real answers with pandas instead of
+  guessing.
+- [`examples/code_generator.py`](examples/code_generator.py) — a code generator
+  that executes every snippet before returning it.
+
+Run one with the credentials above:
+
+```bash
+uv run --extra examples python examples/data_analysis.py
+```
+
+## v1 notes
+
+- **Sequential tool calls.** One sandbox is shared per plugin; calls are meant
+  to run one at a time, not concurrently. Concurrent calls are safe for the
+  sandbox lifecycle (creation is locked) but share one filesystem and kernel.
+- **Text-only output.** Tools return text — `stdout`/`stderr`/file contents.
+  Rich results (charts, dataframes, images) are not surfaced yet.
+- **Lazy, shared sandbox lifecycle.** The sandbox is created on the first tool
+  call and reused for the agent's lifetime, then killed when the runner exits.
+- **Keep-alive while active, expiry when idle.** While a sandbox SDK operation
+  is active, a best-effort heartbeat refreshes its `timeout` (E2B's default is
+  300s), including when a foreground call runs longer than that timeout. A
+  final refresh starts the full idle window when the operation ends. An idle
+  gap longer than `timeout` still expires the sandbox under E2B's default
+  lifecycle (`on_timeout: kill`), and later tool calls return failure results —
+  pass e.g.
+  `lifecycle={"on_timeout": {"action": "pause"}, "auto_resume": True}` to pause
+  and auto-resume across idle gaps instead.
+- **Bounded output.** Output larger than 10 KB per field is truncated with a
+  `…[truncated N bytes]` marker so a single call can't flood the model's context.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

e2b_adk-0.1.0/e2b_adk/__init__.py

@@ -0,0 +1,34 @@
+"""e2b-adk — Google ADK plugin backed by E2B sandboxes."""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+from e2b import ConnectionConfig
+
+from .plugin import E2BPlugin
+from .tools import (
+    ListFiles,
+    ReadFile,
+    RunCode,
+    RunCommand,
+    StartBackgroundCommand,
+    WriteFile,
+)
+
+# E2B's integration hook is process-wide and must be set before the SDK builds
+# a connection config. Importing the modules above has no runtime side effects;
+# plugin construction can only happen after package initialization completes.
+__version__ = version("e2b-adk")
+ConnectionConfig.set_integration(f"e2b-adk/{__version__}")
+
+__all__ = [
+    "E2BPlugin",
+    "__version__",
+    "ListFiles",
+    "ReadFile",
+    "RunCode",
+    "RunCommand",
+    "StartBackgroundCommand",
+    "WriteFile",
+]

e2b_adk-0.1.0/e2b_adk/_results.py

@@ -0,0 +1,96 @@
+"""Result-contract helpers and output truncation shared by all tools.
+
+Pure, dependency-free functions (no E2B/ADK imports). Every tool returns a
+JSON-serializable ``dict`` following a single shape:
+
+* Success results carry ``success: True`` plus tool-specific fields.
+* Failure results carry ``success: False``, a human-readable ``error``, the
+  echoed input relevant to the call (``path`` / ``command``), and any
+  ``partial_output`` captured before the failure.
+
+Oversized text output is trimmed to a byte bound with an explicit marker so a
+single tool call cannot exhaust the agent's context window.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+#: Default upper bound (in bytes) for a single truncatable text field.
+DEFAULT_MAX_OUTPUT_BYTES = 10_000
+
+
+def truncate_output(text: str, limit: int = DEFAULT_MAX_OUTPUT_BYTES) -> str:
+    """Trim ``text`` to at most ``limit`` *payload* bytes (UTF-8), plus a marker.
+
+    ``limit`` bounds the retained payload, not the final string: when truncation
+    occurs a short ``…[truncated N bytes]`` marker is appended *beyond* the
+    ``limit`` bytes, so the returned string may exceed ``limit`` by the marker's
+    length. This keeps a single tool call from exhausting the agent's context
+    while still reporting the exact omitted-byte count.
+
+    Text is first normalized to valid Unicode: well-formed surrogate pairs are
+    combined and lone surrogates are replaced with ``U+FFFD``. Text whose UTF-8
+    encoding is then within ``limit`` is returned without a marker. Otherwise
+    the first ``limit`` bytes are kept (decoded back at a valid character
+    boundary, dropping any partial trailing char).
+    """
+    if limit < 0:
+        raise ValueError(f"limit must be non-negative, got {limit}")
+    try:
+        encoded = text.encode("utf-8")
+        normalized = text
+    except UnicodeEncodeError:
+        # E2B builds streamed log text with json.loads(), which can produce
+        # Python strings containing UTF-16 surrogate code points. A UTF-16
+        # round-trip combines valid pairs and replaces only malformed lone
+        # surrogates, yielding text that is safe to encode and serialize.
+        normalized = text.encode("utf-16", errors="surrogatepass").decode(
+            "utf-16", errors="replace"
+        )
+        encoded = normalized.encode("utf-8")
+    total = len(encoded)
+    if total <= limit:
+        return normalized
+
+    # Decode the retained prefix, dropping any partial trailing char.
+    kept = encoded[:limit].decode("utf-8", errors="ignore")
+    omitted = total - len(kept.encode("utf-8"))
+    return f"{kept}…[truncated {omitted:,} bytes]"
+
+
+def success_result(**fields: Any) -> dict[str, Any]:
+    """Build a success result: ``{**fields, "success": True}``.
+
+    Callers pass the tool-specific fields (e.g. ``stdout``, ``path``,
+    ``exit_code``) as keyword arguments. The reserved ``success`` key is set
+    last so a caller-supplied ``success`` field can never override the contract.
+    """
+    return {**fields, "success": True}
+
+
+def failure_result(
+    error: str,
+    *,
+    path: str | None = None,
+    command: str | None = None,
+    partial_output: str = "",
+    **extra: Any,
+) -> dict[str, Any]:
+    """Build a failure result following the single failure contract.
+
+    Always includes ``success: False``, the ``error`` message, and
+    ``partial_output``. The echoed input (``path`` and/or ``command``) is
+    included only when supplied. Extra tool-specific fields may be passed via
+    ``**extra``. Reserved contract keys are applied *after* ``**extra`` so an
+    ``extra`` field can never override them.
+    """
+    result: dict[str, Any] = dict(extra)
+    result["success"] = False
+    result["error"] = error
+    result["partial_output"] = partial_output
+    if path is not None:
+        result["path"] = path
+    if command is not None:
+        result["command"] = command
+    return result

e2b_adk-0.1.0/e2b_adk/_sandbox.py

@@ -0,0 +1,127 @@
+"""Lazy E2B sandbox lifecycle management.
+
+``SandboxManager`` owns a single ``AsyncSandbox`` that is created lazily on the
+first tool call and reused for the lifetime of the plugin instance, then torn
+down on shutdown. An ``asyncio.Lock`` guards creation and teardown so that
+concurrent tool calls (an agent turn may dispatch several at once) can never
+create two sandboxes and leak one.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any, cast
+
+from e2b_code_interpreter import AsyncSandbox
+
+logger = logging.getLogger(__name__)
+
+
+class SandboxManager:
+    """Lazily creates and caches one ``AsyncSandbox``.
+
+    Any keyword arguments (``api_key``, ``template``, ``metadata``, ``envs``,
+    ``timeout``, ...) are stored and forwarded verbatim to
+    ``AsyncSandbox.create(...)`` on first use.
+    """
+
+    def __init__(self, **opts: Any) -> None:
+        self._opts: dict[str, Any] = opts
+        self._sandbox: AsyncSandbox | None = None
+        self._lock = asyncio.Lock()
+
+    async def get(self) -> AsyncSandbox:
+        """Return the live sandbox, creating it on the first call and caching it.
+
+        Subsequent calls return the cached instance without creating a second
+        sandbox. Creation is guarded by a lock with a double-check so that two
+        concurrent first calls create exactly one sandbox, never two.
+
+        The cached handle is returned as-is without a liveness check: an
+        already-created sandbox that has since expired is not detected or
+        re-created here (see :meth:`keep_alive` for the keep-alive scope that
+        prevents expiry during active use).
+        """
+        if self._sandbox is None:
+            async with self._lock:
+                if self._sandbox is None:
+                    self._sandbox = await AsyncSandbox.create(**self._opts)
+        return self._sandbox
+
+    async def refresh_timeout(self) -> None:
+        """Push the sandbox's expiry window forward (no-op when none exists).
+
+        An E2B sandbox expires ``timeout`` seconds (SDK default 300) after
+        creation or the last ``set_timeout`` call — *not* after the last use.
+        This one-shot operation is also used by :meth:`keep_alive`, whose
+        recurring heartbeat covers an SDK operation that runs longer than the
+        timeout. Best-effort: a keep-alive failure is logged and swallowed.
+        """
+        sandbox = self._sandbox
+        if sandbox is not None:
+            await self._refresh_sandbox(sandbox)
+
+    def _timeout_seconds(self) -> int:
+        """Return the caller-configured TTL or E2B's default."""
+        timeout = self._opts.get("timeout")
+        if isinstance(timeout, int) and timeout > 0:
+            return timeout
+        return int(AsyncSandbox.default_sandbox_timeout)
+
+    def _keepalive_interval_seconds(self) -> float:
+        """Refresh halfway through the TTL, with a small positive floor."""
+        return max(self._timeout_seconds() / 2, 0.1)
+
+    async def _refresh_sandbox(self, sandbox: AsyncSandbox) -> None:
+        """Best-effort refresh for the currently cached sandbox."""
+        if self._sandbox is not sandbox:
+            return
+        try:
+            # E2B's class_method_variant decorator exposes set_timeout to mypy
+            # as Any | None even though the bound instance method is awaitable.
+            await cast(Any, sandbox).set_timeout(self._timeout_seconds())
+        except Exception as exc:  # noqa: BLE001 — keep-alive is best-effort
+            logger.debug("sandbox keep-alive failed: %s", exc)
+
+    async def _keepalive_loop(self, sandbox: AsyncSandbox) -> None:
+        """Refresh ``sandbox`` until its active SDK operation finishes."""
+        while self._sandbox is sandbox:
+            await asyncio.sleep(self._keepalive_interval_seconds())
+            await self._refresh_sandbox(sandbox)
+
+    @asynccontextmanager
+    async def keep_alive(self, sandbox: AsyncSandbox) -> AsyncIterator[None]:
+        """Keep ``sandbox`` alive for the full duration of one SDK operation.
+
+        The first refresh handles cached sandboxes, the heartbeat prevents a
+        call longer than the TTL from expiring mid-run, and the final refresh
+        starts a full idle window when the operation completes. Every refresh
+        is best-effort so lifecycle maintenance never changes a tool result.
+        """
+        await self._refresh_sandbox(sandbox)
+        heartbeat = asyncio.create_task(self._keepalive_loop(sandbox))
+        try:
+            yield
+        finally:
+            heartbeat.cancel()
+            await asyncio.gather(heartbeat, return_exceptions=True)
+            await self._refresh_sandbox(sandbox)
+
+    async def shutdown(self) -> None:
+        """Kill the sandbox if one exists and clear the cache.
+
+        A no-op when no sandbox was ever created. The cache is cleared even if
+        ``kill()`` raises (the error still propagates), so a dead sandbox is
+        never handed back — after shutdown, a later ``get()`` lazily creates a
+        fresh sandbox. Holds the same lock as ``get()`` so teardown cannot race
+        with a concurrent create.
+        """
+        async with self._lock:
+            if self._sandbox is not None:
+                try:
+                    await self._sandbox.kill()
+                finally:
+                    self._sandbox = None