adk-code-mode 0.2.1__tar.gz → 0.3.0__tar.gz

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

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

{adk_code_mode-0.2.1 → adk_code_mode-0.3.0}/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.3.0](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v0.2.2...adk-code-mode-v0.3.0) (2026-07-06)
+
+
+### Features
+
+* hold one sandbox container open per turn (protocol v2) ([#6](https://github.com/a2anet/adk-code-mode/issues/6)) ([aebe17d](https://github.com/a2anet/adk-code-mode/commit/aebe17d2bbbf21cc0f05852efaf910ff6adc3154))
+
+
+### Documentation
+
+* lower startup probe period in `README.md` for faster cold starts ([e251af2](https://github.com/a2anet/adk-code-mode/commit/e251af2cf7307c9944361e1a0e37c7191822a9e1))
+* note HTTP `/health` startup probe in `README.md` Cloud Run section ([d58fb10](https://github.com/a2anet/adk-code-mode/commit/d58fb10f7aeda95e5c8cf29263a13e1333f661dd))
+
+## [0.2.2](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v0.2.1...adk-code-mode-v0.2.2) (2026-05-08)
+
+
+### Bug Fixes
+
+* use `python` fences instead of `tool_code` in `CodeModeCodeExecutor` ([efcc11e](https://github.com/a2anet/adk-code-mode/commit/efcc11e1020c7544223074e00a8649f9c85d4ad6))
+
 ## [0.2.1](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v0.2.0...adk-code-mode-v0.2.1) (2026-05-05)
 
 

{adk_code_mode-0.2.1 → adk_code_mode-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adk-code-mode
-Version: 0.2.1
+Version: 0.3.0
 Summary: A "Code Mode" Code Executor for ADK for 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
@@ -42,14 +42,14 @@ Inspired by Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) and
 - **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`.
 - **Bounded stdout/stderr** — overflow lands in a session artifact instead of poisoning the prompt.
-- **Production-ready remote sandbox** — `RemoteBackend` connects to an isolated, single-use container over WebSocket. 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 code blocks. 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  | no                       |
+| 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)  |
@@ -146,17 +146,16 @@ print(send_message(channel="C123", text="hi"))
 
 ## 🌐 Remote Deployment
 
-**Every execution runs in its own container.** The container accepts exactly one WebSocket connection, executes the user's code, returns results, and exits. The hosting platform destroys the container after each request — no cross-tenant data leakage, no residual state. You **must** configure your platform for one container per request (`--concurrency 1` on Cloud Run, or equivalent).
+**Every turn runs in its own container.** The container accepts exactly one WebSocket connection and holds it open for the whole turn, executing **one or more** code blocks with persistent globals + `/workspace`, then exits when the turn ends (`ShutdownFrame` or disconnect). The hosting platform destroys the container after each turn — no cross-turn or cross-tenant data leakage, no residual state. You **must** configure your platform for one container per turn (`--concurrency 1` on Cloud Run, or equivalent).
 
 Setting `ADK_CODE_MODE_CONTROL_HTTP=1` activates HTTP mode. The container:
 
 1. Starts a WebSocket server on port 8080 (configurable via `PORT`)
 2. Accepts exactly one connection (rejects further connections with 503)
-3. Receives tools and workspace as tar archives over binary WebSocket frames
+3. Receives the tools tar **once**, then announces readiness
 4. Sanitizes the environment (strips all env vars except a safe allowlist)
-5. Executes user code with tools proxied back to the host over the same WebSocket
-6. Returns stdout/stderr and updated workspace files
-7. Exits
+5. For each code block: receives that block's workspace tar, executes user code (tools proxied back to the host over the same WebSocket; globals + `/workspace` persist across blocks), then returns stdout/stderr and the updated workspace
+6. Exits when the turn ends (`ShutdownFrame` or disconnect)
 
 ### Deploy to Cloud Run
 
@@ -192,6 +191,8 @@ gcloud run deploy adk-code-mode-sandbox \
     --cpu 1 \
     --memory 1Gi \
     --concurrency 1 \
+    --timeout 3600 \
+    --max-instances 120 \
     --allow-unauthenticated \
     --vpc-connector=adk-sandbox-connector \
     --vpc-egress=all-traffic \
@@ -199,6 +200,8 @@ gcloud run deploy adk-code-mode-sandbox \
     --set-secrets "ADK_CODE_MODE_AUTH_TOKEN=<your-secret-name>:latest"
 ```
 
+> These flags are **recommendations to tune per deployment**, not hard requirements. `--timeout 3600` (Cloud Run's max) is the per-turn ceiling since the container holds the WebSocket for the whole turn; `--max-instances` should cover your peak concurrent *turns* (`120` covers a 10–100 target — verify your region's Cloud Run vCPU quota). Also add the `/health` startup probe below.
+
 Then in your agent:
 
 ```python
@@ -208,15 +211,17 @@ RemoteBackend(
 )
 ```
 
-> **`--concurrency 1` is critical for security.** Without this flag, Cloud Run may route multiple requests to the same container. The sandbox rejects the second connection, but the misconfiguration itself is a risk.
+> **`--concurrency 1` is critical for security.** It pins one turn to one container. Without this flag, Cloud Run may route multiple turns to the same container. The sandbox rejects the second connection, but the misconfiguration itself is a risk.
 
 > **`--vpc-egress=all-traffic` with a deny-all VPC is critical for security.** Without it, user code can make arbitrary outbound requests — including hitting the GCP metadata endpoint (`169.254.169.254`) to steal the service account token, exfiltrating data, or scanning your VPC. The sandbox only needs to _accept_ inbound connections; it never needs outbound access.
 
+> **Configure an HTTP startup probe against `/health`.** Cloud Run's default TCP probe opens a raw socket that the `websockets` server rejects as a malformed HTTP request, which can race with real traffic during cold starts and surface to clients as `HTTP 503` on the WebSocket handshake. Add `--startup-probe="httpGet.path=/health,httpGet.port=8080,timeoutSeconds=3,periodSeconds=3,failureThreshold=80"` (or equivalent) so probes hit the `/health` endpoint the sandbox handles natively. Keep `periodSeconds` small (e.g. `3`): it sets how long Cloud Run waits before re-probing, so a short period lets a ready container start serving in ~3s instead of ~10s — raise `failureThreshold` to keep the same overall startup budget (`periodSeconds × failureThreshold`). Turn-scoping already gives demand-driven warmth (a container stays up for the whole turn), so `--min-instances=0` is fine; only set `--min-instances` if you want to eliminate cold starts at the cost of a paid warm pool.
+
 ### Deploy on other platforms
 
 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 request.** Each container handles exactly one execution and exits.
+1. **One container per turn.** Each container handles exactly one turn (one or more code blocks) 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`.
 4. **Authenticate connections.** Set `ADK_CODE_MODE_AUTH_TOKEN` and layer platform-level auth (IAM, NetworkPolicy, security groups) on top.
@@ -231,23 +236,29 @@ Required env vars:
 | `ADK_CODE_MODE_MAX_UPLOAD_TOOLS`     | no       | 100 MiB | Max tools tar archive size       |
 | `ADK_CODE_MODE_MAX_UPLOAD_WORKSPACE` | no       | 100 MiB | Max workspace tar archive size   |
 
-The same upload limits (plus a download limit) are configurable on `RemoteBackend`:
+Connection tuning, retry, and the same upload limits (plus a download limit) are configurable on `RemoteBackend`:
 
 ```python
 RemoteBackend(
     url="...",
     token="...",
+    connect_timeout=10.0,             # seconds to wait for the WS handshake (default)
+    start_attempts=3,                 # connect attempts before giving up (default)
+    start_retry_delay_seconds=1.0,    # linear backoff base: delay * attempt (default)
+    start_retry_jitter_seconds=0.25,  # uniform jitter added per retry (default)
     max_upload_tools_bytes=100 * 1024 * 1024,       # 100 MiB (default)
     max_upload_workspace_bytes=100 * 1024 * 1024,    # 100 MiB (default)
     max_download_workspace_bytes=100 * 1024 * 1024,  # 100 MiB (default)
 )
 ```
 
+`connect_timeout` defaults to `10s` — fail a stalled connect fast and retry rather than block. `RemoteBackend` retries transient connect failures up to `start_attempts` times with linear backoff + jitter; raise `connect_timeout` (and/or `start_attempts`) for platforms with slow cold starts.
+
 ## 🗂️ Storage
 
 Code Mode exposes two file surfaces:
 
-- **`/workspace`** — per-run working directory. ADK `input_files` are staged here before code runs (`open("input.csv")` works). Files created or modified under `/workspace` are returned as `CodeExecutionResult.output_files` but are not re-hydrated next turn unless persisted via `save_artifact`.
+- **`/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`.
 
 - **ADK Artifacts** — persistent cross-turn storage. `CodeModeCodeExecutor` injects three tools into the catalog:
 
@@ -324,9 +335,40 @@ CodeModeCodeExecutor(
 )
 ```
 
+`timeout_seconds` / `per_tool_timeout_seconds` stay `None` by default; with turn-scoping the effective per-turn wall-clock ceiling is the platform request timeout (e.g. Cloud Run `--timeout`).
+
+### Turn-scoped sessions
+
+A sandbox container is held open for the duration of a **turn** (one ADK invocation) and reused across that turn's code blocks, so cold start is paid at most once per turn instead of once per block. State — Python globals **and** `/workspace` — persists across a turn's blocks and resets between turns (use ADK Artifacts for cross-turn persistence).
+
+The container is released when the turn ends. Wire `code_executor.release_invocation(callback_context.invocation_id)` into your agent's `after_agent_callback` to free it the moment the turn finishes:
+
+```python
+def _release(callback_context):
+    code_executor.release_invocation(callback_context.invocation_id)
+
+agent = LlmAgent(..., after_agent_callback=[_release])
+```
+
+Two safety nets cover turns that never signal a clean end: an idle reaper closes sessions idle longer than `session_idle_timeout_seconds` (default `600`), and a mid-turn connection loss (or a `timeout_seconds` firing) drops the session — in-turn state (globals + `/workspace`) is lost and the next block reconnects on a fresh container.
+
+If the connection drops **while a block is running**, the executor re-runs the block only when the code provably never reached the sandbox, so a reconnect can't duplicate a tool call's side effects. What happens depends on how far the block got before the drop:
+
+- **Not run** — the `RunFrame` never left the host, so the code did not execute; the executor reconnects on a fresh container and retries the block once automatically.
+- **Ran (output lost)** — a `DoneFrame` came back before the drop, so the code executed but its stdout/stderr and output files couldn't be returned; the block is **not** re-run.
+- **Unknown** — the `RunFrame` was sent but no `DoneFrame` arrived, so whether the code executed is unknowable; the block is **not** re-run.
+
+For the `Ran` and `Unknown` cases the block returns a short message in its `stderr` telling the model what happened, so it can decide whether to re-run the code or check for its effects rather than the executor silently repeating it.
+
+```python
+CodeModeCodeExecutor(tools=..., backend=..., session_idle_timeout_seconds=600)
+```
+
+> Turn-scoping is wire-protocol **v2**. The host wheel and the sandbox image must be upgraded together — a version mismatch fails fast with `ProtocolVersionMismatchError` — so rebuild and push the sandbox image when you upgrade.
+
 ## 🏗️ 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 `input_files` into `/workspace`, and launches the sandbox.
+**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.
 
 **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.
 
@@ -370,8 +412,8 @@ print(send_message(channel="C123", text="hi"))
 """
 
 # How to use files and variables in between executions
-Code is executed in a new environment each time.
-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.
+Within a turn the sandbox is stateful: variables you define and files you write under `/workspace` (the working directory) persist across the successive code blocks you run before replying to the user. They reset at the start of your next turn.
+To carry data across turns, use Artifacts: list them with the `list_artifacts` tool, save with `save_artifact`, and load with `load_artifact`.
 
 <code-mode>
 
@@ -416,7 +458,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 execution.** Fresh container per request — no shared filesystem, memory, or processes.
+- **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**.
 - **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.
@@ -441,7 +483,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.
-- **No state across executions.** Variables don't survive between turns. Use `save_artifact` / `load_artifact` to persist, or `/workspace` within a single run.
+- **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.
 - **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

{adk_code_mode-0.2.1 → adk_code_mode-0.3.0}/README.md

@@ -15,14 +15,14 @@ Inspired by Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) and
 - **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`.
 - **Bounded stdout/stderr** — overflow lands in a session artifact instead of poisoning the prompt.
-- **Production-ready remote sandbox** — `RemoteBackend` connects to an isolated, single-use container over WebSocket. 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 code blocks. 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  | no                       |
+| 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)  |
@@ -119,17 +119,16 @@ print(send_message(channel="C123", text="hi"))
 
 ## 🌐 Remote Deployment
 
-**Every execution runs in its own container.** The container accepts exactly one WebSocket connection, executes the user's code, returns results, and exits. The hosting platform destroys the container after each request — no cross-tenant data leakage, no residual state. You **must** configure your platform for one container per request (`--concurrency 1` on Cloud Run, or equivalent).
+**Every turn runs in its own container.** The container accepts exactly one WebSocket connection and holds it open for the whole turn, executing **one or more** code blocks with persistent globals + `/workspace`, then exits when the turn ends (`ShutdownFrame` or disconnect). The hosting platform destroys the container after each turn — no cross-turn or cross-tenant data leakage, no residual state. You **must** configure your platform for one container per turn (`--concurrency 1` on Cloud Run, or equivalent).
 
 Setting `ADK_CODE_MODE_CONTROL_HTTP=1` activates HTTP mode. The container:
 
 1. Starts a WebSocket server on port 8080 (configurable via `PORT`)
 2. Accepts exactly one connection (rejects further connections with 503)
-3. Receives tools and workspace as tar archives over binary WebSocket frames
+3. Receives the tools tar **once**, then announces readiness
 4. Sanitizes the environment (strips all env vars except a safe allowlist)
-5. Executes user code with tools proxied back to the host over the same WebSocket
-6. Returns stdout/stderr and updated workspace files
-7. Exits
+5. For each code block: receives that block's workspace tar, executes user code (tools proxied back to the host over the same WebSocket; globals + `/workspace` persist across blocks), then returns stdout/stderr and the updated workspace
+6. Exits when the turn ends (`ShutdownFrame` or disconnect)
 
 ### Deploy to Cloud Run
 
@@ -165,6 +164,8 @@ gcloud run deploy adk-code-mode-sandbox \
     --cpu 1 \
     --memory 1Gi \
     --concurrency 1 \
+    --timeout 3600 \
+    --max-instances 120 \
     --allow-unauthenticated \
     --vpc-connector=adk-sandbox-connector \
     --vpc-egress=all-traffic \
@@ -172,6 +173,8 @@ gcloud run deploy adk-code-mode-sandbox \
     --set-secrets "ADK_CODE_MODE_AUTH_TOKEN=<your-secret-name>:latest"
 ```
 
+> These flags are **recommendations to tune per deployment**, not hard requirements. `--timeout 3600` (Cloud Run's max) is the per-turn ceiling since the container holds the WebSocket for the whole turn; `--max-instances` should cover your peak concurrent *turns* (`120` covers a 10–100 target — verify your region's Cloud Run vCPU quota). Also add the `/health` startup probe below.
+
 Then in your agent:
 
 ```python
@@ -181,15 +184,17 @@ RemoteBackend(
 )
 ```
 
-> **`--concurrency 1` is critical for security.** Without this flag, Cloud Run may route multiple requests to the same container. The sandbox rejects the second connection, but the misconfiguration itself is a risk.
+> **`--concurrency 1` is critical for security.** It pins one turn to one container. Without this flag, Cloud Run may route multiple turns to the same container. The sandbox rejects the second connection, but the misconfiguration itself is a risk.
 
 > **`--vpc-egress=all-traffic` with a deny-all VPC is critical for security.** Without it, user code can make arbitrary outbound requests — including hitting the GCP metadata endpoint (`169.254.169.254`) to steal the service account token, exfiltrating data, or scanning your VPC. The sandbox only needs to _accept_ inbound connections; it never needs outbound access.
 
+> **Configure an HTTP startup probe against `/health`.** Cloud Run's default TCP probe opens a raw socket that the `websockets` server rejects as a malformed HTTP request, which can race with real traffic during cold starts and surface to clients as `HTTP 503` on the WebSocket handshake. Add `--startup-probe="httpGet.path=/health,httpGet.port=8080,timeoutSeconds=3,periodSeconds=3,failureThreshold=80"` (or equivalent) so probes hit the `/health` endpoint the sandbox handles natively. Keep `periodSeconds` small (e.g. `3`): it sets how long Cloud Run waits before re-probing, so a short period lets a ready container start serving in ~3s instead of ~10s — raise `failureThreshold` to keep the same overall startup budget (`periodSeconds × failureThreshold`). Turn-scoping already gives demand-driven warmth (a container stays up for the whole turn), so `--min-instances=0` is fine; only set `--min-instances` if you want to eliminate cold starts at the cost of a paid warm pool.
+
 ### Deploy on other platforms
 
 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 request.** Each container handles exactly one execution and exits.
+1. **One container per turn.** Each container handles exactly one turn (one or more code blocks) 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`.
 4. **Authenticate connections.** Set `ADK_CODE_MODE_AUTH_TOKEN` and layer platform-level auth (IAM, NetworkPolicy, security groups) on top.
@@ -204,23 +209,29 @@ Required env vars:
 | `ADK_CODE_MODE_MAX_UPLOAD_TOOLS`     | no       | 100 MiB | Max tools tar archive size       |
 | `ADK_CODE_MODE_MAX_UPLOAD_WORKSPACE` | no       | 100 MiB | Max workspace tar archive size   |
 
-The same upload limits (plus a download limit) are configurable on `RemoteBackend`:
+Connection tuning, retry, and the same upload limits (plus a download limit) are configurable on `RemoteBackend`:
 
 ```python
 RemoteBackend(
     url="...",
     token="...",
+    connect_timeout=10.0,             # seconds to wait for the WS handshake (default)
+    start_attempts=3,                 # connect attempts before giving up (default)
+    start_retry_delay_seconds=1.0,    # linear backoff base: delay * attempt (default)
+    start_retry_jitter_seconds=0.25,  # uniform jitter added per retry (default)
     max_upload_tools_bytes=100 * 1024 * 1024,       # 100 MiB (default)
     max_upload_workspace_bytes=100 * 1024 * 1024,    # 100 MiB (default)
     max_download_workspace_bytes=100 * 1024 * 1024,  # 100 MiB (default)
 )
 ```
 
+`connect_timeout` defaults to `10s` — fail a stalled connect fast and retry rather than block. `RemoteBackend` retries transient connect failures up to `start_attempts` times with linear backoff + jitter; raise `connect_timeout` (and/or `start_attempts`) for platforms with slow cold starts.
+
 ## 🗂️ Storage
 
 Code Mode exposes two file surfaces:
 
-- **`/workspace`** — per-run working directory. ADK `input_files` are staged here before code runs (`open("input.csv")` works). Files created or modified under `/workspace` are returned as `CodeExecutionResult.output_files` but are not re-hydrated next turn unless persisted via `save_artifact`.
+- **`/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`.
 
 - **ADK Artifacts** — persistent cross-turn storage. `CodeModeCodeExecutor` injects three tools into the catalog:
 
@@ -297,9 +308,40 @@ CodeModeCodeExecutor(
 )
 ```
 
+`timeout_seconds` / `per_tool_timeout_seconds` stay `None` by default; with turn-scoping the effective per-turn wall-clock ceiling is the platform request timeout (e.g. Cloud Run `--timeout`).
+
+### Turn-scoped sessions
+
+A sandbox container is held open for the duration of a **turn** (one ADK invocation) and reused across that turn's code blocks, so cold start is paid at most once per turn instead of once per block. State — Python globals **and** `/workspace` — persists across a turn's blocks and resets between turns (use ADK Artifacts for cross-turn persistence).
+
+The container is released when the turn ends. Wire `code_executor.release_invocation(callback_context.invocation_id)` into your agent's `after_agent_callback` to free it the moment the turn finishes:
+
+```python
+def _release(callback_context):
+    code_executor.release_invocation(callback_context.invocation_id)
+
+agent = LlmAgent(..., after_agent_callback=[_release])
+```
+
+Two safety nets cover turns that never signal a clean end: an idle reaper closes sessions idle longer than `session_idle_timeout_seconds` (default `600`), and a mid-turn connection loss (or a `timeout_seconds` firing) drops the session — in-turn state (globals + `/workspace`) is lost and the next block reconnects on a fresh container.
+
+If the connection drops **while a block is running**, the executor re-runs the block only when the code provably never reached the sandbox, so a reconnect can't duplicate a tool call's side effects. What happens depends on how far the block got before the drop:
+
+- **Not run** — the `RunFrame` never left the host, so the code did not execute; the executor reconnects on a fresh container and retries the block once automatically.
+- **Ran (output lost)** — a `DoneFrame` came back before the drop, so the code executed but its stdout/stderr and output files couldn't be returned; the block is **not** re-run.
+- **Unknown** — the `RunFrame` was sent but no `DoneFrame` arrived, so whether the code executed is unknowable; the block is **not** re-run.
+
+For the `Ran` and `Unknown` cases the block returns a short message in its `stderr` telling the model what happened, so it can decide whether to re-run the code or check for its effects rather than the executor silently repeating it.
+
+```python
+CodeModeCodeExecutor(tools=..., backend=..., session_idle_timeout_seconds=600)
+```
+
+> Turn-scoping is wire-protocol **v2**. The host wheel and the sandbox image must be upgraded together — a version mismatch fails fast with `ProtocolVersionMismatchError` — so rebuild and push the sandbox image when you upgrade.
+
 ## 🏗️ 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 `input_files` into `/workspace`, and launches the sandbox.
+**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.
 
 **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.
 
@@ -343,8 +385,8 @@ print(send_message(channel="C123", text="hi"))
 """
 
 # How to use files and variables in between executions
-Code is executed in a new environment each time.
-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.
+Within a turn the sandbox is stateful: variables you define and files you write under `/workspace` (the working directory) persist across the successive code blocks you run before replying to the user. They reset at the start of your next turn.
+To carry data across turns, use Artifacts: list them with the `list_artifacts` tool, save with `save_artifact`, and load with `load_artifact`.
 
 <code-mode>
 
@@ -389,7 +431,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 execution.** Fresh container per request — no shared filesystem, memory, or processes.
+- **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**.
 - **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.
@@ -414,7 +456,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.
-- **No state across executions.** Variables don't survive between turns. Use `save_artifact` / `load_artifact` to persist, or `/workspace` within a single run.
+- **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.
 - **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

{adk_code_mode-0.2.1 → adk_code_mode-0.3.0}/sandbox-wheel/src/adk_code_mode_sandbox/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present A2A Net <hello@a2anet.com>
 #
 # SPDX-License-Identifier: Apache-2.0
-__version__ = "0.2.1"  # x-release-please-version
+__version__ = "0.3.0"  # x-release-please-version

{adk_code_mode-0.2.1 → adk_code_mode-0.3.0}/sandbox-wheel/src/adk_code_mode_sandbox/_entry.py

@@ -14,13 +14,16 @@ are supported, chosen by env var (checked in order):
 - ``ADK_CODE_MODE_CONTROL_FD`` → inherited fd(s). Accepts one fd
   (bidirectional) or two comma-separated fds (read,write).
 
-Installs the RPC client, announces readiness, then waits for a ``run`` frame.
-On receipt, execs the user code with stdout/stderr on the normal streams and
-any ``tools.*`` calls funnelling through the RPC client.
+Installs the RPC client, announces readiness once, then loops handling ``run``
+frames until a ``shutdown`` frame (or disconnect) ends the turn. Each block
+runs against one persistent globals dict (state carries across the turn) with
+its stdout/stderr captured and shipped back in a per-block ``OutputFrame``; any
+``tools.*`` calls funnel through the RPC client.
 """
 
 from __future__ import annotations
 
+import io
 import os
 import socket
 import sys
@@ -31,6 +34,7 @@ from adk_code_mode_sandbox import _rpc_client
 from adk_code_mode_sandbox._rpc_client import RpcClient
 from adk_code_mode_sandbox.protocol import (
     DoneFrame,
+    OutputFrame,
     ReadyFrame,
     RunFrame,
     ShutdownFrame,
@@ -132,9 +136,12 @@ def _make_globals() -> dict[str, Any]:
     }
 
 
-def _run_code(code: str) -> int:
-    """Execute user code. Returns the exit code (0 ok, 1 on exception)."""
-    globs = _make_globals()
+def _exec_into(code: str, globs: dict[str, Any]) -> int:
+    """Execute user code into ``globs``. Returns the exit code (0 ok, 1 on exception).
+
+    ``globs`` is the persistent per-connection globals dict, so names bound by
+    one code block are visible to later blocks in the same turn.
+    """
     try:
         compiled = compile(code, "<code-mode>", "exec")
     except SyntaxError:
@@ -156,6 +163,26 @@ def _run_code(code: str) -> int:
     return 0
 
 
+def run_block(code: str, globs: dict[str, Any]) -> tuple[str, str, int]:
+    """Run one code block with its stdout/stderr captured.
+
+    Redirects ``sys.stdout`` / ``sys.stderr`` to in-memory buffers for the
+    duration of the block so the captured text can be shipped back in an
+    ``OutputFrame`` (both the TCP and HTTP transports emit one per block).
+    """
+    old_stdout, old_stderr = sys.stdout, sys.stderr
+    capture_out = io.StringIO()
+    capture_err = io.StringIO()
+    sys.stdout = capture_out
+    sys.stderr = capture_err
+    try:
+        exit_code = _exec_into(code, globs)
+    finally:
+        sys.stdout = old_stdout
+        sys.stderr = old_stderr
+    return capture_out.getvalue(), capture_err.getvalue(), exit_code
+
+
 def main() -> int:
     if os.environ.get("ADK_CODE_MODE_CONTROL_HTTP"):
         import asyncio
@@ -174,6 +201,9 @@ def main() -> int:
     _prepare_workdir()
     _sanitize_environ()
 
+    # One persistent globals dict + one /workspace for the whole connection, so
+    # variables and files carry across the turn's successive code blocks.
+    globs = _make_globals()
     client.send(ReadyFrame())
 
     while True:
@@ -181,10 +211,9 @@ def main() -> int:
         if isinstance(frame, ShutdownFrame):
             return 0
         if isinstance(frame, RunFrame):
-            exit_code = _run_code(frame.code)
-            sys.stdout.flush()
-            sys.stderr.flush()
+            stdout_text, stderr_text, exit_code = run_block(frame.code, globs)
             client.send(DoneFrame(exit_code=exit_code))
+            client.send(OutputFrame(stdout=stdout_text, stderr=stderr_text, exit_code=exit_code))
             continue
         # Any other frame kind is a host protocol error; keep going but log.
         print(