adk-code-mode 2.0.1__tar.gz → 2.1.0__tar.gz

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

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

{adk_code_mode-2.0.1 → adk_code_mode-2.1.0}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [2.1.0](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v2.0.1...adk-code-mode-v2.1.0) (2026-11-08)
+
+
+### Features
+
+* show return types in the catalog and point the names tier at stubs ([#29](https://github.com/buildagenta/adk-code-mode/issues/29)) ([a238bfd](https://github.com/buildagenta/adk-code-mode/commit/a238bfd0eecf0acf371fe879a529a85a9e1f2dba))
+* type stub return values and escape docstrings ([#28](https://github.com/buildagenta/adk-code-mode/issues/28)) ([dcb15ab](https://github.com/buildagenta/adk-code-mode/commit/dcb15abfcecc841dc06f5051f41251a1f6ab9100))
+
 ## [2.0.1](https://github.com/buildagenta/adk-code-mode/compare/adk-code-mode-v2.0.0...adk-code-mode-v2.0.1) (2026-11-02)
 
 

{adk_code_mode-2.0.1 → adk_code_mode-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: adk-code-mode
-Version: 2.0.1
+Version: 2.1.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/buildagenta/adk-code-mode#readme
 Project-URL: Issues, https://github.com/buildagenta/adk-code-mode/issues
@@ -41,7 +41,7 @@ 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.
 - **Failed tool calls raise** — a REST tool whose API answers with an HTTP error raises `HTTPStatusError` (with `status_code` and `body`), and any other failure, including an MCP tool that reports one, raises `ToolError`. ADK returns these as values for a model to read, but sandbox code reads return values, so it would otherwise carry on as if the call had worked.
 - **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.
+- **Cross-turn persistence via ADK Artifacts** — files the code creates or changes are saved as artifacts automatically, and `save_artifact` / `load_artifact` / `list_artifacts` are auto-injected and route through your configured `ArtifactService`.
 - **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 `execute_code` calls. Deploy on any cloud platform (Cloud Run, Fargate, ACI, Kubernetes, Fly.io, etc.).
@@ -252,9 +252,7 @@ save_artifact(
     mime_type="application/json",
 )
 print(list_artifacts())
-report = load_artifact(filename="report.json")
-if report is not None and report["kind"] == "text":
-    payload = json.loads(report["data"])
+report = json.loads(load_artifact(filename="report.json")["data"])
 ```
 
 Pass `include_artifact_tools=False` to opt out. To react when the model saves an artifact, pass `on_artifacts_saved`:
@@ -270,7 +268,7 @@ ExecuteCodeTool(tools=..., backend=..., on_artifacts_saved=on_saved)
 
 ### Tool results as artifacts
 
-By default (`save_tool_results_as_artifacts=True`) every non-artifact tool is wrapped so its return value is saved as a session artifact tagged `code_mode.tool_result = "true"`. This lets a host forward tool outputs to the user (read the marker in `on_artifacts_saved`) and keeps large results out of the model's context — a result whose serialised form exceeds the threshold is replaced in the reply with a short note pointing at the artifact, which the model reloads with `load_artifact`.
+By default (`save_tool_results_as_artifacts=True`) every non-artifact tool is wrapped so its return value is saved as a session artifact tagged `code_mode.tool_result = "true"`. This lets a host forward tool outputs to the user (read the marker in `on_artifacts_saved`) and lets a later turn reload a result with `load_artifact`. Results over 50,000 bytes return a dictionary with a `tool_result_artifact` filename and a `note` instead of the inline result.
 
 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.
 
@@ -338,14 +336,18 @@ Two surfaces, deliberately kept apart. The **tool description** is the invariant
 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
+preinstalled packages, and available functions. Print function calls, variables, etc.
+to see output, only stdout/stderr are returned. Variables and files persist across
+calls within the same turn and reset on the next turn. Every file the code writes in
+the working directory, and every tool's result, is saved as an artifact; use
+`load_artifact` (imported the same way) to read one in a later turn. Large tool
+results return a `tool_result_artifact` pointer. Tool calls that
+call APIs raise HTTP errors as `HTTPStatusError` (with `status_code` and `body`);
+other failures raise `ToolError`. Import both from `tools`. Each call can run for up
+to 60s.
 ~~~
 
-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.
+With `append_code_mode_metadata_to_system_instruction` disabled that middle sentence is replaced by the discovery text the pointer tier uses (see [Fitting the budget](#fitting-the-budget)), so the description never points at a section that wasn't appended. With `save_tool_results_as_artifacts=False` the description drops "and every tool's result" and the sentence about large results, and with `include_artifact_tools=False` it drops the `load_artifact` clause. The last sentence follows `timeout_seconds` and is left out when it's `None`.
 
 The **`<code-mode>` block** is the per-deployment inventory of the sandbox, appended to the system instruction on every model turn:
 
@@ -366,7 +368,15 @@ yaml: PyYAML 6.0.2
 
 from tools.slack import list_channels, send_message
 
-def list_channels() -> Any:
+class ListChannelsResponse(TypedDict):
+    channels: list[ChannelsItem]
+    next_cursor: NotRequired[str]
+
+class ChannelsItem(TypedDict):
+    id: str
+    name: str
+
+def list_channels() -> ListChannelsResponse:
     """List Slack channels."""
     ...
 
@@ -382,6 +392,8 @@ from tools import save_artifact, load_artifact, list_artifacts
 </code-mode>
 ~~~
 
+Return types come from each tool's `response_json_schema`, or an MCP tool's `outputSchema`; a tool without one returns `Any`. Objects become `TypedDict` classes named after their `$defs` key or `title`, else the property holding them. Identical shapes share one class across a module, defined once at the top of its catalog section; a name clash with another module's class falls back to the tool's or parent's name; each stub file carries the classes its tool uses. An MCP tool's `outputSchema` describes the `structuredContent` field in its result. A saved tool result can also be a `ToolResultArtifact` pointer when it exceeds the size threshold. A tool with exactly one required parameter takes it positionally (`load_artifact("report.csv", version=2)`); every other parameter is keyword-only.
+
 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.
@@ -391,7 +403,10 @@ With `save_tool_results_as_artifacts` enabled (the default), each non-artifact t
 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:
+2. **Names only** — types, signatures and docstrings dropped, import lines kept. `<how-to-use>` gains:
+
+   > Before calling a function you haven't used, print its stub to see its signature, docstring and the fields of its return type: `/tools/<module>/<fn>.py`, or `/tools/<fn>.py` for a function imported from `tools`. Print every stub you need in one `execute_code` call.
+
 
    ~~~
      <tools-package>
@@ -401,11 +416,11 @@ A block over `max_code_mode_metadata_chars` degrades in tiers instead of vanishi
      </tools-package>
    ~~~
 
-3. **Pointer** — the catalog is replaced by a discovery note, and this tier is emitted no matter how small the budget:
+3. **Pointer** — the catalog is replaced by a note, and this tier is emitted no matter how small the budget. `<how-to-use>` gains the same text, prefixed with "List `/tools/` and its module directories to find the functions available.":
 
    ~~~
      <tools-package>
-   The full catalog is too large to include here. List `/tools/` and read a file's docstring to see what's available.
+   The full catalog is too large to include here.
      </tools-package>
    ~~~
 
@@ -413,11 +428,12 @@ At the last tier the model navigates the sandbox from Python instead:
 
 ```python
 import pathlib
-print(list(pathlib.Path("/tools").iterdir()))
-print(open("/tools/slack/send_message.py").read())  # signature + docstring
+print(sorted(pathlib.Path("/tools").rglob("*.py")))
+print(open("/tools/slack/send_message.py").read())  # types, signature + docstring
+print(open("/tools/slack/list_channels.py").read())
 ```
 
-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}`.
+Text and JSON-like MIME types travel as plain strings in artifact tools; binary content is base64-encoded. `load_artifact` returns a dictionary with `kind`, `data`, and `mime_type`. Text and JSON use `kind="text"` and keep the string in `data`. Binary artifacts use `kind="bytes"` and store base64 in `data`.
 
 ## 🛡️ Safety
 
@@ -450,7 +466,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 the working directory persist across `execute_code` calls **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. Files the code writes and tool results are saved as artifacts; use `load_artifact` to read them in a later turn.
 - **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-2.0.1 → adk_code_mode-2.1.0}/README.md

@@ -14,7 +14,7 @@ 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.
 - **Failed tool calls raise** — a REST tool whose API answers with an HTTP error raises `HTTPStatusError` (with `status_code` and `body`), and any other failure, including an MCP tool that reports one, raises `ToolError`. ADK returns these as values for a model to read, but sandbox code reads return values, so it would otherwise carry on as if the call had worked.
 - **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.
+- **Cross-turn persistence via ADK Artifacts** — files the code creates or changes are saved as artifacts automatically, and `save_artifact` / `load_artifact` / `list_artifacts` are auto-injected and route through your configured `ArtifactService`.
 - **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 `execute_code` calls. Deploy on any cloud platform (Cloud Run, Fargate, ACI, Kubernetes, Fly.io, etc.).
@@ -225,9 +225,7 @@ save_artifact(
     mime_type="application/json",
 )
 print(list_artifacts())
-report = load_artifact(filename="report.json")
-if report is not None and report["kind"] == "text":
-    payload = json.loads(report["data"])
+report = json.loads(load_artifact(filename="report.json")["data"])
 ```
 
 Pass `include_artifact_tools=False` to opt out. To react when the model saves an artifact, pass `on_artifacts_saved`:
@@ -243,7 +241,7 @@ ExecuteCodeTool(tools=..., backend=..., on_artifacts_saved=on_saved)
 
 ### Tool results as artifacts
 
-By default (`save_tool_results_as_artifacts=True`) every non-artifact tool is wrapped so its return value is saved as a session artifact tagged `code_mode.tool_result = "true"`. This lets a host forward tool outputs to the user (read the marker in `on_artifacts_saved`) and keeps large results out of the model's context — a result whose serialised form exceeds the threshold is replaced in the reply with a short note pointing at the artifact, which the model reloads with `load_artifact`.
+By default (`save_tool_results_as_artifacts=True`) every non-artifact tool is wrapped so its return value is saved as a session artifact tagged `code_mode.tool_result = "true"`. This lets a host forward tool outputs to the user (read the marker in `on_artifacts_saved`) and lets a later turn reload a result with `load_artifact`. Results over 50,000 bytes return a dictionary with a `tool_result_artifact` filename and a `note` instead of the inline result.
 
 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.
 
@@ -311,14 +309,18 @@ Two surfaces, deliberately kept apart. The **tool description** is the invariant
 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
+preinstalled packages, and available functions. Print function calls, variables, etc.
+to see output, only stdout/stderr are returned. Variables and files persist across
+calls within the same turn and reset on the next turn. Every file the code writes in
+the working directory, and every tool's result, is saved as an artifact; use
+`load_artifact` (imported the same way) to read one in a later turn. Large tool
+results return a `tool_result_artifact` pointer. Tool calls that
+call APIs raise HTTP errors as `HTTPStatusError` (with `status_code` and `body`);
+other failures raise `ToolError`. Import both from `tools`. Each call can run for up
+to 60s.
 ~~~
 
-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.
+With `append_code_mode_metadata_to_system_instruction` disabled that middle sentence is replaced by the discovery text the pointer tier uses (see [Fitting the budget](#fitting-the-budget)), so the description never points at a section that wasn't appended. With `save_tool_results_as_artifacts=False` the description drops "and every tool's result" and the sentence about large results, and with `include_artifact_tools=False` it drops the `load_artifact` clause. The last sentence follows `timeout_seconds` and is left out when it's `None`.
 
 The **`<code-mode>` block** is the per-deployment inventory of the sandbox, appended to the system instruction on every model turn:
 
@@ -339,7 +341,15 @@ yaml: PyYAML 6.0.2
 
 from tools.slack import list_channels, send_message
 
-def list_channels() -> Any:
+class ListChannelsResponse(TypedDict):
+    channels: list[ChannelsItem]
+    next_cursor: NotRequired[str]
+
+class ChannelsItem(TypedDict):
+    id: str
+    name: str
+
+def list_channels() -> ListChannelsResponse:
     """List Slack channels."""
     ...
 
@@ -355,6 +365,8 @@ from tools import save_artifact, load_artifact, list_artifacts
 </code-mode>
 ~~~
 
+Return types come from each tool's `response_json_schema`, or an MCP tool's `outputSchema`; a tool without one returns `Any`. Objects become `TypedDict` classes named after their `$defs` key or `title`, else the property holding them. Identical shapes share one class across a module, defined once at the top of its catalog section; a name clash with another module's class falls back to the tool's or parent's name; each stub file carries the classes its tool uses. An MCP tool's `outputSchema` describes the `structuredContent` field in its result. A saved tool result can also be a `ToolResultArtifact` pointer when it exceeds the size threshold. A tool with exactly one required parameter takes it positionally (`load_artifact("report.csv", version=2)`); every other parameter is keyword-only.
+
 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.
@@ -364,7 +376,10 @@ With `save_tool_results_as_artifacts` enabled (the default), each non-artifact t
 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:
+2. **Names only** — types, signatures and docstrings dropped, import lines kept. `<how-to-use>` gains:
+
+   > Before calling a function you haven't used, print its stub to see its signature, docstring and the fields of its return type: `/tools/<module>/<fn>.py`, or `/tools/<fn>.py` for a function imported from `tools`. Print every stub you need in one `execute_code` call.
+
 
    ~~~
      <tools-package>
@@ -374,11 +389,11 @@ A block over `max_code_mode_metadata_chars` degrades in tiers instead of vanishi
      </tools-package>
    ~~~
 
-3. **Pointer** — the catalog is replaced by a discovery note, and this tier is emitted no matter how small the budget:
+3. **Pointer** — the catalog is replaced by a note, and this tier is emitted no matter how small the budget. `<how-to-use>` gains the same text, prefixed with "List `/tools/` and its module directories to find the functions available.":
 
    ~~~
      <tools-package>
-   The full catalog is too large to include here. List `/tools/` and read a file's docstring to see what's available.
+   The full catalog is too large to include here.
      </tools-package>
    ~~~
 
@@ -386,11 +401,12 @@ At the last tier the model navigates the sandbox from Python instead:
 
 ```python
 import pathlib
-print(list(pathlib.Path("/tools").iterdir()))
-print(open("/tools/slack/send_message.py").read())  # signature + docstring
+print(sorted(pathlib.Path("/tools").rglob("*.py")))
+print(open("/tools/slack/send_message.py").read())  # types, signature + docstring
+print(open("/tools/slack/list_channels.py").read())
 ```
 
-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}`.
+Text and JSON-like MIME types travel as plain strings in artifact tools; binary content is base64-encoded. `load_artifact` returns a dictionary with `kind`, `data`, and `mime_type`. Text and JSON use `kind="text"` and keep the string in `data`. Binary artifacts use `kind="bytes"` and store base64 in `data`.
 
 ## 🛡️ Safety
 
@@ -423,7 +439,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 the working directory persist across `execute_code` calls **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. Files the code writes and tool results are saved as artifacts; use `load_artifact` to read them in a later turn.
 - **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-2.0.1 → adk_code_mode-2.1.0}/sandbox-wheel/src/adk_code_mode_sandbox/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present Agenta <hello@buildagenta.com>
 #
 # SPDX-License-Identifier: Apache-2.0
-__version__ = "2.0.1"  # x-release-please-version
+__version__ = "2.1.0"  # x-release-please-version

{adk_code_mode-2.0.1 → adk_code_mode-2.1.0}/src/adk_code_mode/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2025-present Agenta <hello@buildagenta.com>
 #
 # SPDX-License-Identifier: Apache-2.0
-__version__ = "2.0.1"  # x-release-please-version
+__version__ = "2.1.0"  # x-release-please-version

adk_code_mode-2.1.0/src/adk_code_mode/_json.py

@@ -0,0 +1,43 @@
+# SPDX-FileCopyrightText: 2025-present Agenta <hello@buildagenta.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""JSON-safe conversion for the sandbox RPC reply."""
+
+from __future__ import annotations
+
+import base64
+import dataclasses
+import datetime as dt
+from decimal import Decimal
+from pathlib import Path
+from typing import Any
+
+
+def json_safe(value: Any) -> Any:
+    """Best-effort conversion of a tool result to a JSON-safe value."""
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, (bytes, bytearray)):
+        return {
+            "kind": "bytes",
+            "data": base64.b64encode(bytes(value)).decode("ascii"),
+            "encoding": "base64",
+        }
+    if isinstance(value, (dt.datetime, dt.date)):
+        return value.isoformat()
+    if isinstance(value, Decimal):
+        return str(value)
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [json_safe(v) for v in value]
+    if isinstance(value, dict):
+        return {str(k): json_safe(v) for k, v in value.items()}
+    if hasattr(value, "model_dump"):
+        try:
+            return json_safe(value.model_dump(mode="json"))
+        except Exception:
+            pass
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return json_safe(dataclasses.asdict(value))
+    return repr(value)

adk_code_mode-2.1.0/src/adk_code_mode/mcp_results.py

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2025-present Agenta <hello@buildagenta.com>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Describe the MCP result envelope returned by ADK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from google.adk.tools.base_tool import BaseTool
+from google.adk.tools.mcp_tool.mcp_tool import McpTool
+
+
+def response_schema(tool: BaseTool) -> dict[str, Any] | None:
+    """Describe an MCP result and type its structured content from the tool's output schema."""
+    if not isinstance(tool, McpTool) or not (output := tool.raw_mcp_tool.outputSchema):
+        return None
+    return {
+        **{key: output[key] for key in ("$defs", "definitions") if key in output},
+        "type": "object",
+        "properties": {
+            "content": {"type": "array", "items": {}},
+            "isError": {"type": "boolean"},
+            "structuredContent": {"anyOf": [output, {"type": "null"}]},
+        },
+        "required": ["content", "isError"],
+    }
+
+
+__all__ = ["response_schema"]

{adk_code_mode-2.0.1 → adk_code_mode-2.1.0}/src/adk_code_mode/metadata.py

@@ -26,7 +26,7 @@ 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.catalog import Detail, render_catalog
 from adk_code_mode.tools.namespacing import NamespacedTool
 
 _OPEN = "<code-mode>"
@@ -39,9 +39,20 @@ HOW_TO_USE = (
     "functions you can import from the `tools` package."
 )
 
-DISCOVER_TOOLS = "List `/tools/` and read a file's docstring to see what's available."
+# Every tier without signatures needs these: the full tier shows them inline.
+READ_BEFORE_CALLING = (
+    "Before calling a function you haven't used, print its stub to see its "
+    "signature, docstring and the fields of its return type: "
+    "`/tools/<module>/<fn>.py`, or `/tools/<fn>.py` for a function imported from "
+    "`tools`. Print every stub you need in one `execute_code` call."
+)
+
+DISCOVER_TOOLS = (
+    f"List `/tools/` and its module directories to find the functions available. "
+    f"{READ_BEFORE_CALLING}"
+)
 
-_TOOLS_TOO_LARGE = f"The full catalog is too large to include here. {DISCOVER_TOOLS}"
+_TOOLS_TOO_LARGE = "The full catalog is too large to include here."
 
 # identity -> (python version, {import name: {distribution name: version}})
 _ENVIRONMENTS: dict[str, tuple[str, dict[str, dict[str, str]]]] = {}
@@ -96,8 +107,10 @@ def render(*, identity: str, namespaced: list[NamespacedTool], max_chars: int) -
     """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
+    in order: the full catalog; import lines only (no types, signatures or
+    docstrings), with ``READ_BEFORE_CALLING`` added to the how-to-use text; a
+    pointer, with ``DISCOVER_TOOLS`` added instead, 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.
@@ -108,9 +121,9 @@ def render(*, identity: str, namespaced: list[NamespacedTool], max_chars: int) -
     """
     python_version, packages = _ENVIRONMENTS.get(identity, ("", {}))
 
-    head = [_tag("how-to-use", HOW_TO_USE)]
+    environment: list[str] = []
     if python_version:
-        head.append(_inline_tag("python-version", python_version))
+        environment.append(_inline_tag("python-version", python_version))
     if packages:
         lines = []
         for import_name, distributions in sorted(
@@ -127,21 +140,29 @@ def render(*, identity: str, namespaced: list[NamespacedTool], max_chars: int) -
             if providers:
                 lines.append(f"{import_name}: {providers}")
         if lines:
-            head.append(_tag("installed-packages", "\n".join(lines)))
+            environment.append(_tag("installed-packages", "\n".join(lines)))
 
+    how_to_use = _tag("how-to-use", HOW_TO_USE)
     if not namespaced:
-        return _wrap(head)
-
-    for detail in ("full", "names"):
-        block = _wrap([*head, _tag("tools-package", render_catalog(namespaced, detail=detail))])
+        return _wrap([how_to_use, *environment])
+
+    tiers: list[tuple[Detail, str]] = [
+        ("full", how_to_use),
+        ("names", _tag("how-to-use", f"{HOW_TO_USE} {READ_BEFORE_CALLING}")),
+    ]
+    for detail, tier_how_to_use in tiers:
+        catalog = _tag("tools-package", render_catalog(namespaced, detail=detail))
+        block = _wrap([tier_how_to_use, *environment, catalog])
         if len(block) <= max_chars:
             return block
-    return _wrap([*head, _tag("tools-package", _TOOLS_TOO_LARGE)])
+    discover = _tag("how-to-use", f"{HOW_TO_USE} {DISCOVER_TOOLS}")
+    return _wrap([discover, *environment, _tag("tools-package", _TOOLS_TOO_LARGE)])
 
 
 __all__ = [
     "DISCOVER_TOOLS",
     "HOW_TO_USE",
+    "READ_BEFORE_CALLING",
     "backend_identity",
     "record",
     "render",