adk-code-mode 1.1.0__tar.gz → 1.3.0__tar.gz

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

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

{adk_code_mode-1.1.0 → adk_code_mode-1.3.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.3.0](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v1.2.0...adk-code-mode-v1.3.0) (2026-07-23)
+
+
+### Features
+
+* describe the sandbox to the model in a tagged `<code-mode>` block ([#14](https://github.com/a2anet/adk-code-mode/issues/14)) ([662a281](https://github.com/a2anet/adk-code-mode/commit/662a28138e8632b434e5f1ecd52793f7d83ee097))
+
+## [1.2.0](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v1.1.0...adk-code-mode-v1.2.0) (2026-07-23)
+
+
+### Features
+
+* add `custom_metadata` to the `save_artifact` tool ([dfd9a59](https://github.com/a2anet/adk-code-mode/commit/dfd9a59bf1718084a1d5c02cc1ea453269223f16))
+
 ## [1.1.0](https://github.com/a2anet/adk-code-mode/compare/adk-code-mode-v1.0.0...adk-code-mode-v1.1.0) (2026-07-15)
 
 

{adk_code_mode-1.1.0 → adk_code_mode-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adk-code-mode
-Version: 1.1.0
+Version: 1.3.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
@@ -39,7 +39,7 @@ Inspired by Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) and
 ## ✨ Features
 
 - **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.
+- **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. The sandbox reports what it has installed, so the model is told about it automatically.
 - **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.
@@ -280,14 +280,16 @@ RUN pip install --no-cache-dir pandas==2.2.*
 
 The same image works for both `RemoteBackend` and `UnsafeLocalDockerBackend`. To build directly from this repo, run `make docker-image`.
 
+Whatever you install is advertised to the model automatically — no host-side configuration. The sandbox reports its Python version and maps each top-level import name to the installed distribution and version that provides it; they appear in the `<code-mode>` block as `<python-version>` and `<installed-packages>`. Because the report only arrives once a container has booted, the first model call of a host process doesn't carry them yet; from then on the values are cached per sandbox image for the life of the process.
+
 ## ⚙️ Configuration
 
 All settings are `ExecuteCodeTool` constructor arguments:
 
 | Argument | Default | Purpose |
 | --- | --- | --- |
-| `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. |
+| `append_code_mode_metadata_to_system_instruction` | `True` | Appends the `<code-mode>` block — Python version, installed packages, and the function catalog — to the system instruction on every model turn. Set `False` for a bare system instruction; the tool description then points the model at `/tools/` instead, and the Python version and package list are not surfaced at all. |
+| `max_code_mode_metadata_chars` | `50_000` | Budget for the whole rendered `<code-mode>` block, tags included. Oversized blocks degrade in tiers rather than disappearing — see [What the model sees](#what-the-model-sees). |
 | `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 of one `execute_code` call. Defaults to the platform request timeout (e.g. Cloud Run `--timeout`); set explicitly for defense in depth. |
@@ -308,7 +310,7 @@ A sandbox container is held open for one **turn** (one ADK invocation) and reuse
 
 ## 🏗️ Architecture
 
-**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.
+**Host wheel (`adk-code-mode`).** Lives in the same process as your `LlmAgent`. `ExecuteCodeTool.process_llm_request` resolves tools and, when `append_code_mode_metadata_to_system_instruction` is enabled, renders the `<code-mode>` block 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.
 
@@ -321,16 +323,36 @@ The only things crossing the boundary are: code, tool call arguments, tool retur
 
 ### What the model sees
 
-`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:
+Two surfaces, deliberately kept apart. The **tool description** is the invariant contract of calling `execute_code` — the same for every deployment, and the model's only map when the `<code-mode>` block is disabled. `execute_code` has a single `code: string` parameter and this description:
 
 ~~~
-…your instruction…
+Execute Python code in a sandboxed container. Custom tools are Python functions to
+import from the `tools` package (e.g. `from tools.slack import send_message`). See
+the `<code-mode>` section of the system instruction for the Python version,
+preinstalled packages, and available functions. Print anything you want to see; only
+stdout/stderr are returned. Variables and the working directory persist across calls
+within the same turn and reset on the next turn — use `save_artifact` /
+`load_artifact` (imported the same way) to persist across turns. Files created or
+changed by the code are saved as artifacts automatically
+~~~
 
-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.
+With `append_code_mode_metadata_to_system_instruction` disabled that middle sentence is replaced by `List /tools/ and read a file's docstring to see what's available.`, so the description never points at a section that wasn't appended.
 
-<code-mode>
+The **`<code-mode>` block** is the per-deployment inventory of the sandbox, appended to the system instruction on every model turn:
 
+~~~
+…your instruction…
+
+<code-mode>
+  <how-to-use>
+This section describes the sandbox that `execute_code` runs in: the Python version available, the third-party packages preinstalled in it, and the functions you can import from the `tools` package.
+  </how-to-use>
+  <python-version>3.13.2</python-version>
+  <installed-packages>
+pandas: pandas 2.3.3
+yaml: PyYAML 6.0.2
+  </installed-packages>
+  <tools-package>
 # tools.slack
 
 from tools.slack import list_channels, send_message
@@ -347,13 +369,38 @@ def send_message(*, channel: str, text: str, thread_ts: str | None = ...) -> Any
 
 from tools import save_artifact, load_artifact, list_artifacts
 …
-
+  </tools-package>
 </code-mode>
 ~~~
 
+Tags are indented; their content is not. The `<tools-package>` body is Python source, where leading whitespace is meaningful. Each installed-package line is `<import name>: <distribution> <version>`; namespace imports supplied by multiple distributions list every provider in deterministic order. Import names and providers are sorted so the block stays byte-stable for prompt caching. `<python-version>` and `<installed-packages>` are omitted entirely — rather than rendered blank — when the sandbox hasn't reported yet or the image has no extra packages, since an empty tag reads as "none exist".
+
 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.
 
-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:
+#### Fitting the budget
+
+A block over `max_code_mode_metadata_chars` degrades in tiers instead of vanishing. The Python version and package list survive every tier — they're small, and the model cannot discover them any other way.
+
+1. **Full** — as above.
+2. **Names only** — signatures and docstrings dropped, import lines kept:
+
+   ~~~
+     <tools-package>
+   # tools.slack
+
+   from tools.slack import list_channels, send_message
+     </tools-package>
+   ~~~
+
+3. **Pointer** — the catalog is replaced by a discovery note, and this tier is emitted no matter how small the budget:
+
+   ~~~
+     <tools-package>
+   The full catalog is too large to include here. List `/tools/` and read a file's docstring to see what's available.
+     </tools-package>
+   ~~~
+
+At the last tier the model navigates the sandbox from Python instead:
 
 ```python
 import pathlib

{adk_code_mode-1.1.0 → adk_code_mode-1.3.0}/README.md

@@ -12,7 +12,7 @@ Inspired by Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) and
 ## ✨ Features
 
 - **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.
+- **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. The sandbox reports what it has installed, so the model is told about it automatically.
 - **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.
@@ -253,14 +253,16 @@ RUN pip install --no-cache-dir pandas==2.2.*
 
 The same image works for both `RemoteBackend` and `UnsafeLocalDockerBackend`. To build directly from this repo, run `make docker-image`.
 
+Whatever you install is advertised to the model automatically — no host-side configuration. The sandbox reports its Python version and maps each top-level import name to the installed distribution and version that provides it; they appear in the `<code-mode>` block as `<python-version>` and `<installed-packages>`. Because the report only arrives once a container has booted, the first model call of a host process doesn't carry them yet; from then on the values are cached per sandbox image for the life of the process.
+
 ## ⚙️ Configuration
 
 All settings are `ExecuteCodeTool` constructor arguments:
 
 | Argument | Default | Purpose |
 | --- | --- | --- |
-| `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. |
+| `append_code_mode_metadata_to_system_instruction` | `True` | Appends the `<code-mode>` block — Python version, installed packages, and the function catalog — to the system instruction on every model turn. Set `False` for a bare system instruction; the tool description then points the model at `/tools/` instead, and the Python version and package list are not surfaced at all. |
+| `max_code_mode_metadata_chars` | `50_000` | Budget for the whole rendered `<code-mode>` block, tags included. Oversized blocks degrade in tiers rather than disappearing — see [What the model sees](#what-the-model-sees). |
 | `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 of one `execute_code` call. Defaults to the platform request timeout (e.g. Cloud Run `--timeout`); set explicitly for defense in depth. |
@@ -281,7 +283,7 @@ A sandbox container is held open for one **turn** (one ADK invocation) and reuse
 
 ## 🏗️ Architecture
 
-**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.
+**Host wheel (`adk-code-mode`).** Lives in the same process as your `LlmAgent`. `ExecuteCodeTool.process_llm_request` resolves tools and, when `append_code_mode_metadata_to_system_instruction` is enabled, renders the `<code-mode>` block 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.
 
@@ -294,16 +296,36 @@ The only things crossing the boundary are: code, tool call arguments, tool retur
 
 ### What the model sees
 
-`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:
+Two surfaces, deliberately kept apart. The **tool description** is the invariant contract of calling `execute_code` — the same for every deployment, and the model's only map when the `<code-mode>` block is disabled. `execute_code` has a single `code: string` parameter and this description:
 
 ~~~
-…your instruction…
+Execute Python code in a sandboxed container. Custom tools are Python functions to
+import from the `tools` package (e.g. `from tools.slack import send_message`). See
+the `<code-mode>` section of the system instruction for the Python version,
+preinstalled packages, and available functions. Print anything you want to see; only
+stdout/stderr are returned. Variables and the working directory persist across calls
+within the same turn and reset on the next turn — use `save_artifact` /
+`load_artifact` (imported the same way) to persist across turns. Files created or
+changed by the code are saved as artifacts automatically
+~~~
 
-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.
+With `append_code_mode_metadata_to_system_instruction` disabled that middle sentence is replaced by `List /tools/ and read a file's docstring to see what's available.`, so the description never points at a section that wasn't appended.
 
-<code-mode>
+The **`<code-mode>` block** is the per-deployment inventory of the sandbox, appended to the system instruction on every model turn:
 
+~~~
+…your instruction…
+
+<code-mode>
+  <how-to-use>
+This section describes the sandbox that `execute_code` runs in: the Python version available, the third-party packages preinstalled in it, and the functions you can import from the `tools` package.
+  </how-to-use>
+  <python-version>3.13.2</python-version>
+  <installed-packages>
+pandas: pandas 2.3.3
+yaml: PyYAML 6.0.2
+  </installed-packages>
+  <tools-package>
 # tools.slack
 
 from tools.slack import list_channels, send_message
@@ -320,13 +342,38 @@ def send_message(*, channel: str, text: str, thread_ts: str | None = ...) -> Any
 
 from tools import save_artifact, load_artifact, list_artifacts
 …
-
+  </tools-package>
 </code-mode>
 ~~~
 
+Tags are indented; their content is not. The `<tools-package>` body is Python source, where leading whitespace is meaningful. Each installed-package line is `<import name>: <distribution> <version>`; namespace imports supplied by multiple distributions list every provider in deterministic order. Import names and providers are sorted so the block stays byte-stable for prompt caching. `<python-version>` and `<installed-packages>` are omitted entirely — rather than rendered blank — when the sandbox hasn't reported yet or the image has no extra packages, since an empty tag reads as "none exist".
+
 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.
 
-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:
+#### Fitting the budget
+
+A block over `max_code_mode_metadata_chars` degrades in tiers instead of vanishing. The Python version and package list survive every tier — they're small, and the model cannot discover them any other way.
+
+1. **Full** — as above.
+2. **Names only** — signatures and docstrings dropped, import lines kept:
+
+   ~~~
+     <tools-package>
+   # tools.slack
+
+   from tools.slack import list_channels, send_message
+     </tools-package>
+   ~~~
+
+3. **Pointer** — the catalog is replaced by a discovery note, and this tier is emitted no matter how small the budget:
+
+   ~~~
+     <tools-package>
+   The full catalog is too large to include here. List `/tools/` and read a file's docstring to see what's available.
+     </tools-package>
+   ~~~
+
+At the last tier the model navigates the sandbox from Python instead:
 
 ```python
 import pathlib

{adk_code_mode-1.1.0 → adk_code_mode-1.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__ = "1.1.0"  # x-release-please-version
+__version__ = "1.3.0"  # x-release-please-version

{adk_code_mode-1.1.0 → adk_code_mode-1.3.0}/sandbox-wheel/src/adk_code_mode_sandbox/_entry.py

@@ -23,8 +23,10 @@ its stdout/stderr captured and shipped back in a per-block ``OutputFrame``; any
 
 from __future__ import annotations
 
+import importlib.metadata
 import io
 import os
+import platform
 import socket
 import sys
 import traceback
@@ -40,6 +42,11 @@ from adk_code_mode_sandbox.protocol import (
     ShutdownFrame,
 )
 
+# Distributions that ship with the sandbox itself rather than being installed by
+# whoever built the image. Reporting them would tell the model it has tools it
+# was never meant to use (`websockets` is this wheel's only dependency).
+_PACKAGE_DENYLIST = frozenset({"adk-code-mode-sandbox", "websockets", "pip", "setuptools", "wheel"})
+
 CONTROL_FD_ENV = "ADK_CODE_MODE_CONTROL_FD"
 CONTROL_SOCKET_ENV = "ADK_CODE_MODE_CONTROL_SOCKET"
 CONTROL_TCP_ENV = "ADK_CODE_MODE_CONTROL_TCP"
@@ -50,6 +57,35 @@ TOOLS_DIR = os.environ.get(TOOLS_DIR_ENV, "/tools")
 WORKDIR = os.environ.get(WORKDIR_ENV, "/workspace")
 
 
+def ready_frame() -> ReadyFrame:
+    """Build the ``ReadyFrame`` announcing this image's Python and packages.
+
+    Both transports send this, so image introspection stays in one place.
+    """
+    distributions = {
+        dist.name.casefold(): (dist.name, dist.version)
+        for dist in sorted(
+            importlib.metadata.distributions(),
+            key=lambda dist: (dist.name.casefold(), dist.name, dist.version),
+        )
+        if dist.name.casefold() not in _PACKAGE_DENYLIST
+    }
+    packages: dict[str, dict[str, str]] = {}
+    package_distributions = importlib.metadata.packages_distributions()
+    for import_name in sorted(package_distributions, key=lambda name: (name.casefold(), name)):
+        providers: dict[str, str] = {}
+        for distribution_name in sorted(
+            package_distributions[import_name],
+            key=lambda name: (name.casefold(), name),
+        ):
+            distribution = distributions.get(distribution_name.casefold())
+            if distribution is not None:
+                providers[distribution[0]] = distribution[1]
+        if providers:
+            packages[import_name] = providers
+    return ReadyFrame(python_version=platform.python_version(), packages=packages)
+
+
 def _open_control_streams() -> tuple[Any, Any]:
     """Open the host control pipe as a (reader, writer) pair."""
     tcp_endpoint = os.environ.get(CONTROL_TCP_ENV)
@@ -204,7 +240,7 @@ def main() -> int:
     # 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())
+    client.send(ready_frame())
 
     while True:
         frame = client.recv()

{adk_code_mode-1.1.0 → adk_code_mode-1.3.0}/sandbox-wheel/src/adk_code_mode_sandbox/_http_server.py

@@ -49,6 +49,7 @@ from adk_code_mode_sandbox._entry import (
     _prepare_sys_path,
     _prepare_workdir,
     _sanitize_environ,
+    ready_frame,
     run_block,
 )
 from adk_code_mode_sandbox._rpc_client import RpcClient
@@ -57,7 +58,6 @@ from adk_code_mode_sandbox.protocol import (
     DoneFrame,
     OutputFrame,
     ProtocolError,
-    ReadyFrame,
     RunFrame,
     ShutdownFrame,
     decode,
@@ -188,8 +188,9 @@ async def _handle_connection(ws: Any) -> None:
         globs = _make_globals()
         loop = asyncio.get_running_loop()
 
-        # 4. Announce readiness once (carries the protocol version).
-        await ws.send(encode(ReadyFrame()).decode("utf-8"))
+        # 4. Announce readiness once (carries the protocol version, Python
+        #    version, and installed packages).
+        await ws.send(encode(ready_frame()).decode("utf-8"))
 
         # 5. Run code blocks until the client ends the turn or disconnects.
         while await _run_one_block(ws, loop, globs, workspace_dir, max_workspace):

{adk_code_mode-1.1.0/src/adk_code_mode/runtime → adk_code_mode-1.3.0/sandbox-wheel/src/adk_code_mode_sandbox}/protocol.py

@@ -39,10 +39,20 @@ FrameKind = Literal[
 
 @dataclass(frozen=True)
 class ReadyFrame:
-    """Sandbox → host. Sent once after boot."""
+    """Sandbox → host. Sent once after boot.
+
+    ``python_version`` / ``packages`` describe the image the sandbox runs in so
+    the host can tell the model what it can import. ``packages`` maps each
+    top-level import name to the distributions that provide it and their
+    versions. Both are additive fields with defaults, so a host and a sandbox
+    on different releases still speak: ``decode`` drops unknown keys, and an
+    older sandbox that sends neither just leaves them empty.
+    """
 
     kind: Literal["ready"] = "ready"
     protocol_version: int = PROTOCOL_VERSION
+    python_version: str = ""
+    packages: dict[str, dict[str, str]] = field(default_factory=dict)
 
 
 @dataclass(frozen=True)

{adk_code_mode-1.1.0 → adk_code_mode-1.3.0}/src/adk_code_mode/__about__.py

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

{adk_code_mode-1.1.0 → adk_code_mode-1.3.0}/src/adk_code_mode/_artifact_tools.py

@@ -43,6 +43,7 @@ async def save_artifact(
     filename: str,
     content: str,
     mime_type: str | None = None,
+    custom_metadata: dict[str, Any] | None = None,
     tool_context: ToolContext,
 ) -> int:
     """Save an artifact to the session. Returns the new version number.
@@ -62,6 +63,8 @@ async def save_artifact(
             content=base64.b64encode(image_bytes).decode("ascii"),
             mime_type="image/png",
         )
+
+    ``custom_metadata`` is custom metadata to associate with the artifact.
     """
     if _is_text_mime(mime_type):
         part = genai_types.Part(
@@ -77,7 +80,7 @@ async def save_artifact(
                 mime_type=mime_type or "application/octet-stream",
             )
         )
-    return await tool_context.save_artifact(filename, part)
+    return await tool_context.save_artifact(filename, part, custom_metadata=custom_metadata)
 
 
 async def load_artifact(

adk_code_mode-1.3.0/src/adk_code_mode/metadata.py

@@ -0,0 +1,149 @@
+# SPDX-FileCopyrightText: 2025-present A2A Net <hello@a2anet.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Assemble the ``<code-mode>`` block appended to the model's system instruction.
+
+The block is the sandbox's *inventory* — which Python, which preinstalled
+packages, which importable functions. The invariant contract of calling
+``execute_code`` lives in the tool's description instead, so the two never
+restate each other.
+
+The Python version and package list are reported by the sandbox itself in its
+``ReadyFrame``, which only arrives once a container has booted — i.e. after the
+first ``execute_code`` call. They are cached here, keyed by the backend's
+``identity`` (its URL or image) rather than on ``ExecuteCodeTool``, so one warm
+process serves every agent pointing at the same image and the value survives a
+tool being rebuilt. Recording is monotonic and rendering is sorted: the block
+must be byte-stable once known, because it sits in front of the whole prompt
+and any churn re-writes the model provider's cached prefix.
+
+Tags are indented; their text content is not. The ``<tools-package>`` body is
+Python source, where leading whitespace is meaningful.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from adk_code_mode.runtime.protocol import ReadyFrame
+from adk_code_mode.tools.catalog import render_catalog
+from adk_code_mode.tools.namespacing import NamespacedTool
+
+_OPEN = "<code-mode>"
+_CLOSE = "</code-mode>"
+_INDENT = "  "
+
+HOW_TO_USE = (
+    "This section describes the sandbox that `execute_code` runs in: the Python "
+    "version available, the third-party packages preinstalled in it, and the "
+    "functions you can import from the `tools` package."
+)
+
+DISCOVER_TOOLS = "List `/tools/` and read a file's docstring to see what's available."
+
+_TOOLS_TOO_LARGE = f"The full catalog is too large to include here. {DISCOVER_TOOLS}"
+
+# identity -> (python version, {import name: {distribution name: version}})
+_ENVIRONMENTS: dict[str, tuple[str, dict[str, dict[str, str]]]] = {}
+
+
+def backend_identity(backend: Any) -> str:
+    """Return the cache key for a backend's sandbox image.
+
+    Built-in backends expose ``identity`` (URL or image tag). Third-party
+    backends without one collapse to their class name, which is still stable
+    within a process.
+    """
+    return getattr(backend, "identity", None) or type(backend).__name__
+
+
+def record(identity: str, frame: ReadyFrame) -> None:
+    """Cache the environment a sandbox reported on connect.
+
+    A frame carrying neither field is ignored rather than stored: sandboxes
+    older than this field, and any future reconnect that fails to report, must
+    not blank out an environment we already know.
+    """
+    if not frame.python_version and not frame.packages:
+        return
+    packages = {
+        import_name: dict(distributions) for import_name, distributions in frame.packages.items()
+    }
+    _ENVIRONMENTS[identity] = (frame.python_version, packages)
+
+
+def reset() -> None:
+    """Drop every cached environment. For tests."""
+    _ENVIRONMENTS.clear()
+
+
+def _tag(name: str, content: str) -> str:
+    # The catalog's sections end in a newline; strip so every tag closes flush
+    # against its content rather than after a stray blank line.
+    body = content.strip("\n")
+    return f"{_INDENT}<{name}>\n{body}\n{_INDENT}</{name}>"
+
+
+def _inline_tag(name: str, value: str) -> str:
+    return f"{_INDENT}<{name}>{value}</{name}>"
+
+
+def _wrap(children: list[str]) -> str:
+    return "\n".join([_OPEN, *children, _CLOSE])
+
+
+def render(*, identity: str, namespaced: list[NamespacedTool], max_chars: int) -> str:
+    """Render the ``<code-mode>`` block, degrading until it fits ``max_chars``.
+
+    ``max_chars`` is measured against the final string, tags included. Tiers,
+    in order: the full catalog; import lines only (no signatures or
+    docstrings); a pointer telling the model to read ``/tools/`` itself. The
+    last tier is unconditional — an oversized tool surface must never cost the
+    model the Python version and package list, which are small and which it
+    cannot discover any other way.
+
+    Tags whose content is unknown (no ``ReadyFrame`` yet) or empty (a base
+    image with no extra packages, a tool with no tools) are omitted entirely
+    rather than rendered blank, which would read as "none available".
+    """
+    python_version, packages = _ENVIRONMENTS.get(identity, ("", {}))
+
+    head = [_tag("how-to-use", HOW_TO_USE)]
+    if python_version:
+        head.append(_inline_tag("python-version", python_version))
+    if packages:
+        lines = []
+        for import_name, distributions in sorted(
+            packages.items(),
+            key=lambda item: (item[0].casefold(), item[0]),
+        ):
+            providers = ", ".join(
+                f"{name} {version}"
+                for name, version in sorted(
+                    distributions.items(),
+                    key=lambda item: (item[0].casefold(), item[0]),
+                )
+            )
+            if providers:
+                lines.append(f"{import_name}: {providers}")
+        if lines:
+            head.append(_tag("installed-packages", "\n".join(lines)))
+
+    if not namespaced:
+        return _wrap(head)
+
+    for detail in ("full", "names"):
+        block = _wrap([*head, _tag("tools-package", render_catalog(namespaced, detail=detail))])
+        if len(block) <= max_chars:
+            return block
+    return _wrap([*head, _tag("tools-package", _TOOLS_TOO_LARGE)])
+
+
+__all__ = [
+    "DISCOVER_TOOLS",
+    "HOW_TO_USE",
+    "backend_identity",
+    "record",
+    "render",
+    "reset",
+]

{adk_code_mode-1.1.0 → adk_code_mode-1.3.0}/src/adk_code_mode/runtime/docker.py

@@ -88,6 +88,11 @@ class UnsafeLocalDockerBackend:
     extra_env: Mapping[str, str] = field(default_factory=dict)
     run_kwargs: Mapping[str, Any] = field(default_factory=dict)
 
+    @property
+    def identity(self) -> str:
+        """Cache key for what this backend's sandbox image contains."""
+        return self.image
+
     async def start(
         self,
         *,

{adk_code_mode-1.1.0/sandbox-wheel/src/adk_code_mode_sandbox → adk_code_mode-1.3.0/src/adk_code_mode/runtime}/protocol.py

@@ -39,10 +39,20 @@ FrameKind = Literal[
 
 @dataclass(frozen=True)
 class ReadyFrame:
-    """Sandbox → host. Sent once after boot."""
+    """Sandbox → host. Sent once after boot.
+
+    ``python_version`` / ``packages`` describe the image the sandbox runs in so
+    the host can tell the model what it can import. ``packages`` maps each
+    top-level import name to the distributions that provide it and their
+    versions. Both are additive fields with defaults, so a host and a sandbox
+    on different releases still speak: ``decode`` drops unknown keys, and an
+    older sandbox that sends neither just leaves them empty.
+    """
 
     kind: Literal["ready"] = "ready"
     protocol_version: int = PROTOCOL_VERSION
+    python_version: str = ""
+    packages: dict[str, dict[str, str]] = field(default_factory=dict)
 
 
 @dataclass(frozen=True)

{adk_code_mode-1.1.0 → adk_code_mode-1.3.0}/src/adk_code_mode/runtime/remote.py

@@ -77,6 +77,11 @@ class RemoteBackend:
     max_upload_workspace_bytes: int = 100 * 1024 * 1024
     max_download_workspace_bytes: int = 100 * 1024 * 1024
 
+    @property
+    def identity(self) -> str:
+        """Cache key for what this backend's sandbox image contains."""
+        return self.url
+
     async def start(
         self,
         *,