adk-code-mode 0.4.0__tar.gz → 1.0.0__tar.gz

adk_code_mode-1.0.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+    ".": "1.0.0"
+}

{adk_code_mode-0.4.0 → adk_code_mode-1.0.0}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [1.0.0](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v0.4.1...adk-code-mode-v1.0.0) (2026-07-15)
+
+
+### ⚠ BREAKING CHANGES
+
+* `CodeModeCodeExecutor`, `code_mode_before_model_callback`, and `CODE_MODE_SYSTEM_INSTRUCTION` no longer exist. Add `ExecuteCodeTool` to the agent's `tools=[...]` instead of wiring `code_executor=`; drop `before_model_callback=`, `generate_content_config=`, and `CODE_MODE_SYSTEM_INSTRUCTION` entirely; `release_invocation` is now `async`. See the README's migration section.
+
+### Features
+
+* replace `CodeModeCodeExecutor` with `ExecuteCodeTool` ([#10](https://github.com/a2anet/adk-code-mode/issues/10)) ([b78572e](https://github.com/a2anet/adk-code-mode/commit/b78572e72446930548760756255390d1a3cc388a))
+
+## [0.4.1](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v0.4.0...adk-code-mode-v0.4.1) (2026-07-10)
+
+
+### Documentation
+
+* note the sandbox writes to `/tools` in remote deployment guide ([96bb45e](https://github.com/a2anet/adk-code-mode/commit/96bb45e4e18d9d54709f4c10b6b09cf3567ee385))
+
 ## [0.4.0](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v0.3.0...adk-code-mode-v0.4.0) (2026-07-09)
 
 

{adk_code_mode-0.4.0 → adk_code_mode-1.0.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: adk-code-mode
-Version: 0.4.0
-Summary: A "Code Mode" Code Executor for ADK for agents to interact with tools, files, and custom packages with Python
+Version: 1.0.0
+Summary: A "Code Mode" sandboxed code-execution tool for ADK agents to interact with tools, files, and custom packages with Python
 Project-URL: Documentation, https://github.com/A2ANet/adk-code-mode#readme
 Project-URL: Issues, https://github.com/A2ANet/adk-code-mode/issues
 Project-URL: Source, https://github.com/A2ANet/adk-code-mode
 Author-email: A2A Net <hello@a2anet.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
-Keywords: a2a,adk,agents,code-executor,code-mode
+Keywords: a2a,adk,agents,code-mode,execute-code
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.10
@@ -27,12 +27,12 @@ Description-Content-Type: text/markdown
 
 # ADK Code Mode
 
-A [Code Mode](https://blog.cloudflare.com/code-mode/) code executor for [Agent Development Kit (ADK)](https://github.com/google/adk-python).
+A [Code Mode](https://blog.cloudflare.com/code-mode/) sandboxed code-execution tool for [Agent Development Kit (ADK)](https://github.com/google/adk-python).
 
-The `CodeModeCodeExecutor` allows ADK agents to write Python code to call tools and read and write files.
+`ExecuteCodeTool` lets ADK agents write Python code to call tools and read and write files.
 Code runs inside a sandboxed container, and tools (and their credentials) are executed on the host.
 The base image comes with the stdlib and can be extended with any Python package you want.
-It also supports `input_files` and `output_files`, and the sandboxed container can list, load, and save ADK Artifacts.
+The sandboxed container can list, load, and save ADK Artifacts, and files it creates are returned as artifacts.
 
 Inspired by Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) and Anthropic's [Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp).
 
@@ -40,22 +40,22 @@ Inspired by Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) and
 
 - **Call ADK tools from sandbox code** — imports against the `tools` package proxy back to the host and run through ADK's `before_tool` / `after_tool` / `on_error` callbacks and the plugin manager exactly as direct tool calls would.
 - **Bake any Python package into the image** — extend the published base image with anything the model's code needs to `import`, no runtime `pip install` required.
-- **Cross-turn persistence via ADK Artifacts** — `save_artifact` / `load_artifact` / `list_artifacts` are auto-injected and route through your configured `ArtifactService`.
+- **Cross-turn persistence via ADK Artifacts** — `save_artifact` / `load_artifact` / `list_artifacts` are auto-injected and route through your configured `ArtifactService`. Files the code creates or changes are saved as artifacts automatically too.
 - **Tool results saved as artifacts** — on by default; every tool's result is persisted as a `code_mode.tool_result` artifact (with optional model-supplied name/description) so hosts can forward outputs and large results stay out of the prompt. Opt out with `save_tool_results_as_artifacts=False`.
 - **Bounded stdout/stderr** — overflow lands in a session artifact instead of poisoning the prompt.
-- **Production-ready remote sandbox** — `RemoteBackend` connects to an isolated per-turn container over WebSocket, reused across the turn's code blocks. Deploy on any cloud platform (Cloud Run, Fargate, ACI, Kubernetes, Fly.io, etc.).
+- **Production-ready remote sandbox** — `RemoteBackend` connects to an isolated per-turn container over WebSocket, reused across the turn's `execute_code` calls. Deploy on any cloud platform (Cloud Run, Fargate, ACI, Kubernetes, Fly.io, etc.).
 - **Local development** — `UnsafeLocalDockerBackend` runs the sandbox against your local Docker daemon for fast iteration. **Not for production** — see [Safety](#-safety).
 
 |                                     | BuiltIn | AgentEngineSandbox              | VertexAi                        | Container | Gke | CodeMode                 |
-| ----------------------------------- | ------- | ------------------------------- | ------------------------------- | --------- | --- | ------------------------ |
-| Call ADK tools from code            | no      | no                              | no                              | no        | no  | yes (with limitations)   |
-| Extra Python packages               | no      | no (more than stdlib but fixed) | no (more than stdlib but fixed) | yes       | yes | yes                      |
-| Variables are stateful              | no      | yes                             | yes                             | no        | no  | yes (within a turn)      |
-| Input files                         | no      | yes                             | yes                             | no        | no  | yes                      |
-| Output files                        | no      | yes                             | yes                             | no        | no  | yes                      |
-| Storage                             | no      | yes (via variables)             | yes (via variables)             | no        | no  | yes (via ADK Artifacts)  |
-| Local development version available | no      | no                              | no                              | yes       | yes | yes                      |
-| Bounded stdout/stderr               | no      | no                              | no                              | no        | no  | yes (`max_output_chars`) |
+| ----------------------------------- | ------- | -------------------------------- | -------------------------------- | --------- | --- | ------------------------ |
+| Call ADK tools from code            | no      | no                                | no                                | no        | no  | yes (with limitations)   |
+| Extra Python packages               | no      | no (more than stdlib but fixed)  | no (more than stdlib but fixed)  | yes       | yes | yes                      |
+| Variables are stateful              | no      | yes                               | yes                               | no        | no  | yes (within a turn)      |
+| Input files                         | no      | yes                               | yes                               | no        | no  | no (use Artifacts)       |
+| Output files                        | no      | yes                               | yes                               | no        | no  | yes (as Artifacts)       |
+| Storage                             | no      | yes (via variables)               | yes (via variables)               | no        | no  | yes (via ADK Artifacts)  |
+| Local development version available | no      | no                                | no                                | yes       | yes | yes                      |
+| Bounded stdout/stderr               | no      | no                                | no                                | no        | no  | yes (`max_output_chars`) |
 
 ## 📦 Install
 
@@ -79,26 +79,15 @@ Requires Python 3.10+. Local development requires [Docker](https://docs.docker.c
 
 ## 🚀 Usage
 
-Build a `CodeModeCodeExecutor`, then wire four things into the agent:
-
-- **`CODE_MODE_SYSTEM_INSTRUCTION`** — append to the agent's `instruction`. Teaches the model how to write code blocks and use artifacts.
-- **`code_mode_before_model_callback`** — set as `before_model_callback`. Injects the tool catalog (`<code-mode>` block) into the system prompt on every model turn.
-- **`generate_content_config`** with `function_calling_config.mode="NONE"` — disables native function calling so the model writes Python instead of attempting tool calls that fail with `MALFORMED_FUNCTION_CALL` (since `tools=[]`).
-- **`release_invocation`** — call it from the agent's `after_agent_callback` to release the turn's sandbox container as soon as the turn ends. An idle reaper (`session_idle_timeout_seconds`, default `600`) is a backstop, so containers are still reclaimed without it — just later.
+Build an `ExecuteCodeTool`, give it the tools the sandboxed code may call, and attach it to your agent. Wire `release_invocation` into `after_agent_callback` to release the turn's sandbox container when the turn ends. An idle reaper (`session_idle_timeout_seconds`, default `600`) is a backstop.
 
 ### Production (remote sandbox)
 
 ```python
 from google.adk.agents import LlmAgent
-from google.genai import types as genai_types
-from adk_code_mode import (
-    CODE_MODE_SYSTEM_INSTRUCTION,
-    CodeModeCodeExecutor,
-    RemoteBackend,
-    code_mode_before_model_callback,
-)
+from adk_code_mode import ExecuteCodeTool, RemoteBackend
 
-executor = CodeModeCodeExecutor(
+tool = ExecuteCodeTool(
     tools=[my_fn_tool, McpToolset(...), OpenAPIToolset(...)],
     backend=RemoteBackend(
         url="https://sandbox-xyz.run.app",  # your deployed sandbox URL
@@ -106,21 +95,14 @@ executor = CodeModeCodeExecutor(
     ),
 )
 
-def _release_sandbox(callback_context):
-    executor.release_invocation(callback_context.invocation_id)
+async def _release_sandbox(callback_context):
+    await tool.release_invocation(callback_context.invocation_id)
 
 root_agent = LlmAgent(
     name="assistant",
-    model="gemini-2.5-pro",
-    instruction=f"You are a helpful assistant.\n\n{CODE_MODE_SYSTEM_INSTRUCTION}",
-    tools=[],  # do NOT also bind tools here; the executor owns them.
-    code_executor=executor,
-    generate_content_config=genai_types.GenerateContentConfig(
-        tool_config=genai_types.ToolConfig(
-            function_calling_config=genai_types.FunctionCallingConfig(mode="NONE"),
-        ),
-    ),
-    before_model_callback=code_mode_before_model_callback(executor),
+    model="gemini-3.5-flash",
+    instruction="You are a helpful assistant.",
+    tools=[tool],
     after_agent_callback=[_release_sandbox],
 )
 ```
@@ -130,14 +112,9 @@ root_agent = LlmAgent(
 > **`UnsafeLocalDockerBackend` is not safe for production or multi-tenant use.** See [Safety](#-safety).
 
 ```python
-from adk_code_mode import (
-    CODE_MODE_SYSTEM_INSTRUCTION,
-    CodeModeCodeExecutor,
-    UnsafeLocalDockerBackend,
-    code_mode_before_model_callback,
-)
+from adk_code_mode import ExecuteCodeTool, UnsafeLocalDockerBackend
 
-executor = CodeModeCodeExecutor(
+tool = ExecuteCodeTool(
     tools=[my_fn_tool, McpToolset(...), OpenAPIToolset(...)],
     backend=UnsafeLocalDockerBackend(image="ghcr.io/a2anet/adk-code-mode:latest"),
 )
@@ -217,9 +194,9 @@ RemoteBackend(
 
 The same pattern works on any platform that runs Docker containers as HTTP services (AWS Fargate/ECS, Azure Container Instances, Kubernetes, Fly.io, etc.):
 
-1. **One container per turn.** Each container handles exactly one turn (one or more code blocks) and exits.
+1. **One container per turn.** Each container handles exactly one turn (one or more `execute_code` calls) and exits.
 2. **Block all outbound network access.** Without egress restrictions, user code can exfiltrate data, access cloud metadata endpoints, or scan internal networks.
-3. **Set a read-only root filesystem** where the platform supports it (e.g., `readOnlyRootFilesystem: true` in Kubernetes). The sandbox only writes to `/workspace`.
+3. **Keep `/workspace` and `/tools` writable.** The sandbox stages the working directory and materialises the `tools` package into `/tools` at connect time. If you set a read-only root filesystem (e.g., `readOnlyRootFilesystem: true` in Kubernetes), mount both as writable volumes (e.g., an `emptyDir`).
 4. **Authenticate connections.** Set `ADK_CODE_MODE_AUTH_TOKEN` and layer platform-level auth (IAM, NetworkPolicy, security groups) on top.
 
 Required env vars:
@@ -252,9 +229,9 @@ RemoteBackend(
 
 Code Mode exposes two file surfaces:
 
-- **`/workspace`** — the turn's working directory. It persists across the turn's code blocks and resets between turns. ADK `input_files` for a block are staged here before that block runs (`open("input.csv")` works). Files whose content changed in a block are returned as that block's `CodeExecutionResult.output_files`; nothing under `/workspace` is re-hydrated on the next turn unless persisted via `save_artifact`.
+- **The working directory** — the turn's workspace. It persists across the turn's `execute_code` calls and resets between turns. Files created or changed by a call are collected afterward and saved as session artifacts automatically, returned to the model as a list of filenames (reloadable via `load_artifact`) — nothing is re-hydrated into the working directory on the next turn unless the model explicitly loads it back with `load_artifact`.
 
-- **ADK Artifacts** — persistent cross-turn storage. `CodeModeCodeExecutor` injects three tools into the catalog:
+- **ADK Artifacts** — persistent cross-turn storage. `ExecuteCodeTool` injects three tools into the sandbox:
 
 ```python
 import json
@@ -275,10 +252,11 @@ Pass `include_artifact_tools=False` to opt out. To react when the model saves an
 
 ```python
 async def on_saved(invocation_context, delta):
-    # delta is {filename: version} for everything saved this turn.
+    # delta is {filename: version} for everything the sandbox-side save_artifact
+    # calls (or wrapped tool results) saved this turn.
     ...
 
-CodeModeCodeExecutor(tools=..., backend=..., on_artifacts_saved=on_saved)
+ExecuteCodeTool(tools=..., backend=..., on_artifacts_saved=on_saved)
 ```
 
 ### Tool results as artifacts
@@ -288,7 +266,7 @@ By default (`save_tool_results_as_artifacts=True`) every non-artifact tool is wr
 Naming is transparent: the filename is derived from the tool name and call id. Each wrapped tool also gains two **optional** parameters — `artifact_name` and `artifact_description` — that the model may pass to name/describe the saved artifact; both land in the artifact's `custom_metadata` (`code_mode.artifact_name` / `code_mode.artifact_description`) alongside the marker. Set `save_tool_results_as_artifacts=False` to return tool results inline without persisting them.
 
 ```python
-CodeModeCodeExecutor(tools=..., backend=..., save_tool_results_as_artifacts=True)
+ExecuteCodeTool(tools=..., backend=..., save_tool_results_as_artifacts=True)
 ```
 
 ## 🐳 Sandbox Image
@@ -304,80 +282,52 @@ The same image works for both `RemoteBackend` and `UnsafeLocalDockerBackend`. To
 
 ## ⚙️ Configuration
 
-All settings are `CodeModeCodeExecutor` constructor arguments:
+All settings are `ExecuteCodeTool` constructor arguments:
 
 | Argument | Default | Purpose |
 | --- | --- | --- |
-| `max_catalog_chars` | `50_000` | Soft cap on the rendered tool catalog in the system prompt. When exceeded, the per-tool sections are replaced with a short note telling the model how to navigate `/tools/` from Python. |
-| `max_output_chars` | `50_000` | Caps stdout/stderr handed back to the model. Overflow is saved as a session artifact at `code_mode/stdout/<execution-id>.txt` and the model sees a head-and-tail view pointing to it. |
+| `append_function_stubs_to_system_instruction` | `True` | Appends a `<code-mode>` block listing available function signatures and docstrings to the system instruction on every model turn. If the rendered catalog would exceed `max_catalog_chars`, the model can still discover functions by listing `/tools/` and reading the generated stubs. |
+| `max_catalog_chars` | `50_000` | Maximum size of the appended function catalog. |
+| `max_output_chars` | `50_000` | Caps stdout/stderr handed back to the model. Overflow is saved as a session artifact at `code_mode/stdout/<call-id>.txt` and the model sees a head-and-tail view pointing to it. |
 | `max_code_chars` | `1_000_000` | Rejects oversized code payloads before starting a container. |
-| `timeout_seconds` | `None` | Caps overall execution time. Defaults to the platform request timeout (e.g. Cloud Run `--timeout`); set explicitly for defense in depth. |
-| `per_tool_timeout_seconds` | `None` | Caps each individual tool call. |
+| `timeout_seconds` | `None` | Caps overall execution time of one `execute_code` call. Defaults to the platform request timeout (e.g. Cloud Run `--timeout`); set explicitly for defense in depth. |
+| `per_tool_timeout_seconds` | `None` | Caps each individual tool call made from within the sandbox. |
 | `session_idle_timeout_seconds` | `600` | Idle reaper: closes a turn's container once it goes untouched this long. Backstop for turns that never call `release_invocation`. |
 
 The model can read spilled stdout back from the overflow artifact:
 
 ```python
 from tools import load_artifact
-spilled = load_artifact(filename="code_mode/stdout/<execution-id>.txt")
+spilled = load_artifact(filename="code_mode/stdout/<call-id>.txt")
 print(spilled["data"][-2000:])
 ```
 
 ### Turn-scoped sessions
 
-A sandbox container is held open for one **turn** (one ADK invocation) and reused across that turn's code blocks, so cold start is paid at most once per turn. Python globals **and** `/workspace` persist across a turn's blocks and reset between turns — use ADK Artifacts for cross-turn persistence. The container is released when the turn ends (via `release_invocation`, wired in [Usage](#-usage)) and destroyed by the platform, so no state survives into another turn or tenant.
+A sandbox container is held open for one **turn** (one ADK invocation) and reused across that turn's `execute_code` calls, so cold start is paid at most once per turn. Python globals **and** the working directory persist across a turn's calls and reset between turns — use ADK Artifacts for cross-turn persistence. The container is released when the turn ends (via `await tool.release_invocation(...)`, wired in [Usage](#-usage)) and destroyed by the platform, so no state survives into another turn or tenant.
 
 ## 🏗️ Architecture
 
-**Host wheel (`adk-code-mode`).** Lives in the same process as your `LlmAgent`. The `before_model_callback` resolves tools, renders the catalog, and appends it to the system prompt. At execution time, it generates a `tools/` Python package of thin stubs, stages the block's `input_files` into `/workspace`, and opens (or reuses) the turn's sandbox connection — the container spans the whole turn.
+**Host wheel (`adk-code-mode`).** Lives in the same process as your `LlmAgent`. `ExecuteCodeTool.process_llm_request` resolves tools and, when `append_function_stubs_to_system_instruction` is enabled, renders the catalog and appends it to the system instruction. At execution time (`run_async`), it generates a `tools/` Python package of thin stubs, stages the working directory, and opens (or reuses) the turn's sandbox connection — the container spans the whole turn.
 
 **Sandbox wheel (`adk-code-mode-sandbox`).** Pre-installed in the container image. When model code calls a stub, it sends a JSON-Lines frame over the control connection; the host runs the real tool (with callbacks and plugins) and sends the result back.
 
 The only things crossing the boundary are: code, tool call arguments, tool return values, and log frames.
 
 | Backend                    | Transport              | Multi-tenant safe? | When to use                     |
-| -------------------------- | ---------------------- | ------------------ | ------------------------------- |
+| -------------------------- | ---------------------- | ------------------- | -------------------------------- |
 | `RemoteBackend`            | WebSocket over HTTPS   | **Yes**            | Production — any cloud platform |
-| `UnsafeLocalDockerBackend` | TCP over Docker bridge | No                 | Local development only          |
+| `UnsafeLocalDockerBackend` | TCP over Docker bridge | No                  | Local development only          |
 
 ### What the model sees
 
-Your `instruction` (containing `CODE_MODE_SYSTEM_INSTRUCTION`) followed by a `<code-mode>` block appended by the callback:
+`execute_code` has a single `code: string` parameter. With `append_function_stubs_to_system_instruction` enabled, the system instruction also gets a `<code-mode>` reference catalog on every turn:
 
 ~~~
 …your instruction…
 
-# How to execute code and use tools
-You have no callable function tools. To use a tool you must write Python code in a fenced Python block (i.e. ```python\n...\n```). Do not emit a function or tool call.
-The Python Standard Library and a set of custom tools are available to you as an importable library, listed in the `<code-mode>` section below.
-To see the result of your code, you need to print it. For example, if you had the following tool:
-
-```
-<code-mode>
-
-from tools.slack import send_message
-
-def send_message(*, channel: str, text: str, thread_ts: str | None = ...) -> Any:
-    """Send a message to a Slack channel."""
-    ...
-
-</code-mode>
-```
-
-To call the tool, you should write:
-
-````
-```python
-from tools.slack import send_message
-
-print(send_message(channel="C123", text="hi"))
-```
-````
-
-# How to use files and variables in between executions
-You can reuse variables and files within a turn. Between turns, to reuse variables and files you must save and load Artifacts.
-To list available Artifacts, use the `list_artifacts` tool, to save an Artifact, use the `save_artifact` tool, and to load an Artifact, use the `load_artifact` tool.
-Tool results are automatically saved as Artifacts.
+Reference catalog of the Python functions available inside the execute_code sandbox.
+Import these functions from the `tools` package in the code you pass to execute_code.
 
 <code-mode>
 
@@ -403,17 +353,12 @@ from tools import save_artifact, load_artifact, list_artifacts
 
 With `save_tool_results_as_artifacts` enabled (the default), each non-artifact tool above — e.g. `list_channels` and `send_message` — also carries two optional `artifact_name: str | None = ...` / `artifact_description: str | None = ...` parameters for naming its saved result.
 
-When the rendered catalog exceeds `max_catalog_chars`, the per-tool sections are replaced with:
+If the rendered catalog would exceed `max_catalog_chars`, nothing is appended to the system instruction that turn — not even a fallback note. The model can still navigate the sandbox from Python:
 
-```
-<code-mode>
-A `tools` package is available in the sandbox. List `/tools/` with
-`pathlib.Path('/tools').iterdir()`. Each entry is either a `.py` file
-(a top-level tool, importable as `from tools import <name>`) or a
-subdirectory (a namespace, with tools importable as
-`from tools.<namespace> import <name>`). To see a tool's signature and
-docstring, read its `.py` file with `open(...).read()`.
-</code-mode>
+```python
+import pathlib
+print(list(pathlib.Path("/tools").iterdir()))
+print(open("/tools/slack/send_message.py").read())  # signature + docstring
 ```
 
 Text and JSON-like MIME types travel as plain strings in artifact tools; binary content is base64-encoded. `load_artifact` returns `{"kind": "text" | "bytes", "data": str, "mime_type": str | None}`.
@@ -424,7 +369,7 @@ Text and JSON-like MIME types travel as plain strings in artifact tools; binary
 
 `RemoteBackend` is designed for multi-tenant production use where untrusted users submit arbitrary Python code:
 
-- **One container per turn (one tenant, one invocation).** Within a turn the process/filesystem are reused across that turn's code blocks; the container is destroyed at turn end, with **no cross-turn or cross-tenant sharing**.
+- **One container per turn (one tenant, one invocation).** Within a turn the process/filesystem are reused across that turn's `execute_code` calls; the container is destroyed at turn end, with **no cross-turn or cross-tenant sharing**.
 - **Environment sanitization.** All env vars are stripped except a safe allowlist (`PATH`, `HOME`, `USER`, locale vars, Python config) before user code runs.
 - **Credentials never enter the sandbox.** API keys, OAuth tokens, and connection strings stay in the host process. The container only receives tool results.
 - **Bearer token authentication.** WebSocket connections without a valid token are rejected. Always set `ADK_CODE_MODE_AUTH_TOKEN` and layer platform-level auth on top.
@@ -449,7 +394,7 @@ Named "Unsafe" intentionally: it binds a TCP listener on `0.0.0.0`, communicates
 ## ⚠️ Limitations
 
 - **No credential-requesting tools.** Tools that need ADK to request credentials, confirmations, UI widgets, agent transfer, escalation, or that yield without an immediate response are rejected with a structured error.
-- **State is turn-scoped.** Variables and `/workspace` files persist across code blocks **within** a turn, but reset between turns. Use `save_artifact` / `load_artifact` to persist across turns.
+- **State is turn-scoped.** Variables and the working directory persist across `execute_code` calls **within** a turn, but reset between turns. Use `save_artifact` / `load_artifact` to persist across turns.
 - **No runtime package installation.** The sandbox ships with the Python Standard Library and the runtime's own dependencies only. Extra packages must be baked into the image at build time.
 
 ## 🛠️ Development