From b2c349d429c7c9b599d4f4a20e5fa8f8377d3b24 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Nov 2026 18:03:09 +0000 Subject: [PATCH] feat: opt in to full tool results and parsed load_artifact #27 returned full tool results and parsed artifact content, but #29's squash put the 2.x formats back before 2.1.0. Bring #27's behaviour back as opt-ins on `ExecuteCodeTool`, keeping the 2.x formats as the defaults. - `large_result_threshold` (default 50,000 bytes): `None` never swaps a tool result for the `tool_result_artifact` pointer, so the code always gets the full result, which is still saved as an artifact. Stubs, the catalog and the tool description only mention the pointer when it can occur. `ToolResultArtifactTool` and `wrap_tool_result_as_artifact` also accept `None` - `load_artifact_format` (default `"envelope"`): `"parsed"` injects a `load_artifact` that returns parsed JSON, a `str` for other text, or `{"mime_type", "bytes"}` for binary, with a docstring to match - Save tool results with the same JSON-safe conversion as the reply to the code, so a saved result reloads as the value the code received - Encode and decode artifact text with the mime type's charset (UTF-8 by default), and ignore mime parameters when deciding what is text - `RemoteBackend` refuses a frame over `max_message_size` before sending it, so an oversized tool reply reaches the code as an error instead of closing the sandbox connection - Export `DEFAULT_LARGE_RESULT_THRESHOLD` and `LoadArtifactFormat` Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013TYQ7F1kLDzPsAwBRC5KV1 --- README.md | 16 ++- src/adk_code_mode/__init__.py | 4 + src/adk_code_mode/_artifact_tools.py | 120 +++++++++++++++++-- src/adk_code_mode/_json.py | 2 +- src/adk_code_mode/runtime/remote.py | 10 ++ src/adk_code_mode/tool.py | 38 ++++-- src/adk_code_mode/tool_result_artifacts.py | 23 +++- src/adk_code_mode/tools/stubs.py | 5 +- tests/test_artifact_tools.py | 127 +++++++++++++++++++++ tests/test_integration.py | 83 ++++++++++++++ tests/test_remote_backend.py | 28 ++++- tests/test_stubs.py | 11 ++ tests/test_tool.py | 37 ++++++ tests/test_tool_result_artifacts.py | 76 ++++++++++++ 14 files changed, 551 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 087cbba..3f2735e 100644 --- a/README.md +++ b/README.md @@ -228,6 +228,12 @@ print(list_artifacts()) report = json.loads(load_artifact(filename="report.json")["data"]) ``` +Pass `load_artifact_format="parsed"` to have `load_artifact` return the content itself instead: the parsed value for JSON, a `str` for other text, and `{"mime_type": str, "bytes": str}` (base64) for binary. Its docstring in the stubs and catalog follows the format, so the model is told which one it gets: + +```python +report = load_artifact(filename="report.json") # {"status": "ready"}, already parsed +``` + Pass `include_artifact_tools=False` to opt out. To react when the model saves an artifact, pass `on_artifacts_saved`: ```python @@ -241,7 +247,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 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. +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. Pass `large_result_threshold` to change the limit, or `None` so the code always gets the full result. It is still saved as an artifact, and the stubs, catalog and tool description stop mentioning the pointer. 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. @@ -272,6 +278,8 @@ All settings are `ExecuteCodeTool` constructor arguments: | `max_code_mode_metadata_chars` | `50_000` | Budget for the whole rendered `` 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/.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. | +| `large_result_threshold` | `50_000` | With `save_tool_results_as_artifacts`, a tool result whose serialised form is over this many bytes is replaced with a `tool_result_artifact` pointer to its saved artifact. `None` always returns the full result. See [Tool results as artifacts](#tool-results-as-artifacts). | +| `load_artifact_format` | `"envelope"` | What `load_artifact` returns: `"envelope"` for `{"kind", "data", "mime_type"}`, or `"parsed"` for the content itself. See [Storage](#-storage). | | `timeout_seconds` | `60` | Caps overall execution time of one `execute_code` call, and with it every tool the block calls. A block past the cap is stopped with its output so far, keeping the turn's variables and working directory. If it won't stop within a few seconds or leaves a worker thread or child process running, its sandbox is restarted and its output and state are lost. The model is told the cap. `None` lifts it, leaving the platform request timeout (e.g. Cloud Run `--timeout`) as the only bound. | | `per_tool_timeout_seconds` | `None` | Caps each individual tool call made from within the sandbox. | | `session_idle_timeout_seconds` | `600` | Idle reaper: closes a turn's container once it goes untouched this long. Backstop for turns that never call `release_invocation`. | @@ -320,7 +328,7 @@ other failures raise `ToolError`. Import both from `tools`. Each call can run fo to 60s. ~~~ -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`. +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, with `large_result_threshold=None` it drops only 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 **`` block** is the per-deployment inventory of the sandbox, appended to the system instruction on every model turn: @@ -365,7 +373,7 @@ from tools import save_artifact, load_artifact, list_artifacts ~~~ -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. +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, unless `large_result_threshold=None`. 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 `` body is Python source, where leading whitespace is meaningful. Each installed-package line is `: `; 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. `` and `` 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". @@ -406,7 +414,7 @@ print(open("/tools/slack/send_message.py").read()) # types, signature + docstri 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 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`. +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`. With `load_artifact_format="parsed"` it returns the parsed value for JSON, a `str` for other text, and `{"mime_type": str, "bytes": str}` (base64) for binary. ## 🛡️ Safety diff --git a/src/adk_code_mode/__init__.py b/src/adk_code_mode/__init__.py index 6f31748..7f7c764 100644 --- a/src/adk_code_mode/__init__.py +++ b/src/adk_code_mode/__init__.py @@ -2,6 +2,7 @@ # # SPDX-License-Identifier: Apache-2.0 from adk_code_mode.__about__ import __version__ +from adk_code_mode._artifact_tools import LoadArtifactFormat from adk_code_mode.runtime import ( RemoteBackend, SandboxBackend, @@ -10,6 +11,7 @@ ) from adk_code_mode.tool import ArtifactsSavedCallback, ExecuteCodeTool from adk_code_mode.tool_result_artifacts import ( + DEFAULT_LARGE_RESULT_THRESHOLD, TOOL_RESULT_DESCRIPTION_KEY, TOOL_RESULT_FILENAME_KEY, TOOL_RESULT_METADATA_KEY, @@ -20,7 +22,9 @@ __all__ = [ "ArtifactsSavedCallback", + "DEFAULT_LARGE_RESULT_THRESHOLD", "ExecuteCodeTool", + "LoadArtifactFormat", "RemoteBackend", "SandboxBackend", "SandboxSession", diff --git a/src/adk_code_mode/_artifact_tools.py b/src/adk_code_mode/_artifact_tools.py index bf3bcb2..9fb11f2 100644 --- a/src/adk_code_mode/_artifact_tools.py +++ b/src/adk_code_mode/_artifact_tools.py @@ -10,15 +10,18 @@ The wire format is JSON. Binary content is base64 over the wire — the model encodes it before calling ``save_artifact`` and decodes it after -``load_artifact``. Loaded artifacts return a flat ``{"kind", "data", -"mime_type"}`` dict so the model dispatches on ``kind`` without importing -host-side types. +``load_artifact``. By default loaded artifacts return a flat ``{"kind", +"data", "mime_type"}`` dict so the model dispatches on ``kind`` without +importing host-side types. ``ExecuteCodeTool(load_artifact_format="parsed")`` +swaps in a ``load_artifact`` that returns the content itself: parsed JSON, a +``str`` for other text, or ``{"mime_type", "bytes"}`` for binary. """ from __future__ import annotations import base64 -from typing import Any +import json +from typing import Any, Literal from google.adk.tools.function_tool import FunctionTool from google.adk.tools.tool_context import ToolContext @@ -27,10 +30,19 @@ _TEXT_MIME_PREFIXES = ("text/",) _TEXT_MIME_TYPES = {"application/json", "application/xml", "application/javascript"} +LoadArtifactFormat = Literal["envelope", "parsed"] +"""What ``load_artifact`` returns. + +``"envelope"`` (the default) is ``{"kind", "data", "mime_type"}``. ``"parsed"`` +is the content itself: parsed JSON, a ``str`` for other text, or +``{"mime_type", "bytes"}`` for binary. +""" + def _is_text_mime(mime_type: str | None) -> bool: if not mime_type: return False + mime_type = _base_mime(mime_type) if mime_type.startswith(_TEXT_MIME_PREFIXES): return True if mime_type in _TEXT_MIME_TYPES: @@ -38,6 +50,23 @@ def _is_text_mime(mime_type: str | None) -> bool: return mime_type.endswith("+json") or mime_type.endswith("+xml") +def _is_json_mime(mime_type: str | None) -> bool: + base = _base_mime(mime_type or "") + return base == "application/json" or base.endswith("+json") + + +def _base_mime(mime_type: str) -> str: + return mime_type.split(";", 1)[0].strip().lower() + + +def _charset(mime_type: str | None) -> str: + for param in (mime_type or "").split(";")[1:]: + key, _, value = param.partition("=") + if key.strip().lower() == "charset": + return value.strip().strip('"') + return "utf-8" + + async def save_artifact( *, filename: str, @@ -69,7 +98,7 @@ async def save_artifact( if _is_text_mime(mime_type): part = genai_types.Part( inline_data=genai_types.Blob( - data=content.encode("utf-8"), + data=content.encode(_charset(mime_type)), mime_type=mime_type or "text/plain", ) ) @@ -115,13 +144,11 @@ async def load_artifact( inline = part.inline_data if inline is not None: mime_type = inline.mime_type - data = inline.data or b"" - if isinstance(data, str): - data = data.encode("utf-8") + data = _inline_bytes(inline) if _is_text_mime(mime_type): return { "kind": "text", - "data": data.decode("utf-8"), + "data": data.decode(_charset(mime_type)), "mime_type": mime_type, } return { @@ -134,6 +161,56 @@ async def load_artifact( return {"kind": "text", "data": "", "mime_type": None} +async def load_artifact_parsed( + *, + filename: str, + version: int | None = None, + tool_context: ToolContext, +) -> Any: + """Load an artifact by filename and return its content. Returns ``None`` if not found. + + The return value depends on the artifact's mime type: + + - JSON (``application/json``, ``*+json``): the parsed value — for a saved + tool result, exactly what the original call returned. + - Other text (``text/*``, XML, JavaScript): the text as a ``str``. + - Binary: ``{"mime_type": , "bytes": }``. + + Example: + + rows = load_artifact(filename="search_call-1.json") # list/dict, already parsed + notes = load_artifact(filename="notes.txt") # str + image = load_artifact(filename="chart.png") + png = base64.b64decode(image["bytes"]) + """ + part = await tool_context.load_artifact(filename, version=version) + if part is None: + return None + inline = part.inline_data + if inline is None: + return part.text or "" + mime_type = inline.mime_type + data = _inline_bytes(inline) + if not _is_text_mime(mime_type): + return {"mime_type": mime_type, "bytes": base64.b64encode(data).decode("ascii")} + text = data.decode(_charset(mime_type)) + if _is_json_mime(mime_type): + try: + return json.loads(text) + except ValueError: + return text + return text + + +# Code imports it as ``load_artifact`` whichever format the host picked. +load_artifact_parsed.__name__ = load_artifact_parsed.__qualname__ = "load_artifact" + + +def _inline_bytes(inline: genai_types.Blob) -> bytes: + data = inline.data or b"" + return data.encode("utf-8") if isinstance(data, str) else data + + async def list_artifacts(*, tool_context: ToolContext) -> list[str]: """Return the filenames of artifacts visible to this session. @@ -151,5 +228,28 @@ async def list_artifacts(*, tool_context: ToolContext) -> list[str]: FunctionTool(list_artifacts), ) +_PARSED_ARTIFACT_TOOLS: tuple[FunctionTool, ...] = ( + ARTIFACT_TOOLS[0], + FunctionTool(load_artifact_parsed), + ARTIFACT_TOOLS[2], +) + -__all__ = ["ARTIFACT_TOOLS", "list_artifacts", "load_artifact", "save_artifact"] +def artifact_tools(load_format: LoadArtifactFormat = "envelope") -> tuple[FunctionTool, ...]: + """Return the artifact tools, with ``load_artifact`` returning ``load_format``.""" + if load_format == "envelope": + return ARTIFACT_TOOLS + if load_format == "parsed": + return _PARSED_ARTIFACT_TOOLS + raise ValueError(f"load_artifact_format must be 'envelope' or 'parsed', not {load_format!r}") + + +__all__ = [ + "ARTIFACT_TOOLS", + "LoadArtifactFormat", + "artifact_tools", + "list_artifacts", + "load_artifact", + "load_artifact_parsed", + "save_artifact", +] diff --git a/src/adk_code_mode/_json.py b/src/adk_code_mode/_json.py index 541c2cc..14f7cc2 100644 --- a/src/adk_code_mode/_json.py +++ b/src/adk_code_mode/_json.py @@ -1,7 +1,7 @@ # SPDX-FileCopyrightText: 2025-present Agenta # # SPDX-License-Identifier: Apache-2.0 -"""JSON-safe conversion for the sandbox RPC reply.""" +"""JSON-safe conversion shared by the RPC reply and saved tool results.""" from __future__ import annotations diff --git a/src/adk_code_mode/runtime/remote.py b/src/adk_code_mode/runtime/remote.py index 5e10f1e..42a95df 100644 --- a/src/adk_code_mode/runtime/remote.py +++ b/src/adk_code_mode/runtime/remote.py @@ -137,6 +137,7 @@ async def _connect( return _RemoteSandboxSession( ws=ws, workdir_path=workdir_path, + max_message_size=self.max_message_size, max_upload_workspace_bytes=self.max_upload_workspace_bytes, max_download_workspace_bytes=self.max_download_workspace_bytes, ) @@ -148,11 +149,13 @@ def __init__( *, ws: Any, workdir_path: str, + max_message_size: int, max_upload_workspace_bytes: int, max_download_workspace_bytes: int, ) -> None: self._ws = ws self._workdir_path = workdir_path + self._max_message_size = max_message_size self._max_upload_workspace_bytes = max_upload_workspace_bytes self._max_download_workspace_bytes = max_download_workspace_bytes @@ -172,6 +175,13 @@ async def begin_block(self, input_paths: Sequence[str]) -> None: async def send(self, frame: Frame) -> None: payload = encode(frame) + # The sandbox closes the connection on an oversized message, so refuse it + # here instead; a tool reply then reaches the code as an error. + if len(payload) > self._max_message_size: + raise ValueError( + f"{type(frame).__name__} ({len(payload):,} bytes) exceeds " + f"max_message_size ({self._max_message_size:,})" + ) try: await self._ws.send(payload.decode("utf-8")) except websockets.ConnectionClosed as exc: diff --git a/src/adk_code_mode/tool.py b/src/adk_code_mode/tool.py index 51000c9..9b5dfeb 100644 --- a/src/adk_code_mode/tool.py +++ b/src/adk_code_mode/tool.py @@ -41,7 +41,7 @@ from google.genai import types as genai_types from adk_code_mode import metadata -from adk_code_mode._artifact_tools import ARTIFACT_TOOLS +from adk_code_mode._artifact_tools import ARTIFACT_TOOLS, LoadArtifactFormat, artifact_tools from adk_code_mode._json import json_safe from adk_code_mode.output import truncate from adk_code_mode.runtime.base import ( @@ -62,7 +62,10 @@ ToolErrorPayload, ToolResultFrame, ) -from adk_code_mode.tool_result_artifacts import ToolResultArtifactTool +from adk_code_mode.tool_result_artifacts import ( + DEFAULT_LARGE_RESULT_THRESHOLD, + ToolResultArtifactTool, +) from adk_code_mode.tools import namespacing, normaliser, stubs from adk_code_mode.tools.dispatcher import DispatchResult, Dispatcher from adk_code_mode.workspace.files import hash_file, walk_workspace @@ -151,6 +154,7 @@ def _build_description( append_metadata: bool, artifact_tools: bool, tool_results: bool, + result_pointers: bool, timeout_seconds: int | None, ) -> str: """Build the tool description for this tool's configured surface.""" @@ -161,7 +165,7 @@ def _build_description( saved = f" {saved} is saved as an artifact" if artifact_tools: saved += "; use `load_artifact` (imported the same way) to read one in a later turn" - if tool_results: + if tool_results and result_pointers: saved += ". Large tool results return a `tool_result_artifact` pointer" limit = f" Each call can run for up to {timeout_seconds}s." if timeout_seconds else "" return ( @@ -226,6 +230,8 @@ def __init__( backend: SandboxBackend, include_artifact_tools: bool = True, save_tool_results_as_artifacts: bool = True, + large_result_threshold: int | None = DEFAULT_LARGE_RESULT_THRESHOLD, + load_artifact_format: LoadArtifactFormat = "envelope", append_code_mode_metadata_to_system_instruction: bool = True, max_code_mode_metadata_chars: int = 50_000, max_output_chars: int = 50_000, @@ -249,8 +255,20 @@ def __init__( save_tool_results_as_artifacts: If true (default), every non-artifact tool is wrapped so its result is also saved as a session artifact, reloadable in later turns via ``load_artifact``. Large results - return an artifact pointer. Set ``False`` to skip saving and - always get the full result inline. + return an artifact pointer (see ``large_result_threshold``). Set + ``False`` to skip saving and always get the full result inline. + large_result_threshold: With ``save_tool_results_as_artifacts``, a + result whose serialised form is over this many bytes (default + 50,000) is replaced in the reply with a ``{"tool_result_artifact", + "note"}`` pointer to its saved artifact. ``None`` never replaces a + result: the code always gets it in full, and it is still saved. + Stubs and the tool description only mention the pointer when it + can occur. + load_artifact_format: What the injected ``load_artifact`` returns. + ``"envelope"`` (default) returns ``{"kind", "data", "mime_type"}``. + ``"parsed"`` returns the content itself: the parsed value for JSON, + a ``str`` for other text, and ``{"mime_type", "bytes"}`` (base64) + for binary. Its docstring in the stubs matches the format. append_code_mode_metadata_to_system_instruction: If true (default), every model turn's system instruction gets a ```` block describing the sandbox: its Python version, its preinstalled @@ -296,13 +314,15 @@ def __init__( append_metadata=append_code_mode_metadata_to_system_instruction, artifact_tools=include_artifact_tools, tool_results=save_tool_results_as_artifacts, + result_pointers=large_result_threshold is not None, timeout_seconds=timeout_seconds, ), ) + builtin_artifact_tools = artifact_tools(load_artifact_format) adapted: list[BaseTool | BaseToolset] = [] if include_artifact_tools: - adapted.extend(ARTIFACT_TOOLS) + adapted.extend(builtin_artifact_tools) for item in tools: if isinstance(item, (BaseTool, BaseToolset)): adapted.append(item) @@ -317,6 +337,7 @@ def __init__( self._tools = adapted self._backend = backend self._save_tool_results_as_artifacts = save_tool_results_as_artifacts + self._large_result_threshold = large_result_threshold self._append_code_mode_metadata_to_system_instruction = ( append_code_mode_metadata_to_system_instruction ) @@ -545,7 +566,10 @@ def _apply_tool_result_wrapping( if isinstance(rt.tool, ToolResultArtifactTool) or rt.tool.name in _ARTIFACT_TOOL_NAMES: wrapped.append(rt) else: - wrapped.append(dataclasses.replace(rt, tool=ToolResultArtifactTool(rt.tool))) + tool = ToolResultArtifactTool( + rt.tool, large_result_threshold=self._large_result_threshold + ) + wrapped.append(dataclasses.replace(rt, tool=tool)) return wrapped async def _run_attempt( diff --git a/src/adk_code_mode/tool_result_artifacts.py b/src/adk_code_mode/tool_result_artifacts.py index 211e9c3..6b09145 100644 --- a/src/adk_code_mode/tool_result_artifacts.py +++ b/src/adk_code_mode/tool_result_artifacts.py @@ -19,7 +19,8 @@ Small results are returned to the model unchanged. Results whose serialised form exceeds ``large_result_threshold`` are replaced with a short notice pointing at the artifact, keeping large payloads out of the model's context while remaining -reloadable with ``load_artifact``. +reloadable with ``load_artifact``. With ``large_result_threshold=None`` every +result is returned unchanged and is still saved. """ from __future__ import annotations @@ -32,6 +33,7 @@ from google.adk.tools.tool_context import ToolContext from google.genai import types +from adk_code_mode._json import json_safe from adk_code_mode.tool_failures import raise_for_failed_result # Transport-neutral metadata stamped on saved tool-result artifacts. Downstream @@ -53,13 +55,17 @@ class ToolResultArtifactTool(BaseTool): Preserves the wrapped tool's declaration (the model still sees the original parameters) and injects two optional parameters, ``artifact_name`` and ``artifact_description``, for naming the saved artifact. + + A result whose serialised form is over ``large_result_threshold`` bytes is + replaced with a ``{"tool_result_artifact", "note"}`` pointer to the saved + artifact. ``None`` never replaces a result. """ def __init__( self, wrapped: BaseTool, *, - large_result_threshold: int = DEFAULT_LARGE_RESULT_THRESHOLD, + large_result_threshold: int | None = DEFAULT_LARGE_RESULT_THRESHOLD, ) -> None: super().__init__( name=wrapped.name, @@ -73,6 +79,11 @@ def __init__( self._inject_name = _ARTIFACT_NAME_PARAM not in existing self._inject_description = _ARTIFACT_DESCRIPTION_PARAM not in existing + @property + def large_result_threshold(self) -> int | None: + """Size in bytes above which a result becomes a pointer; ``None`` for never.""" + return self._large_result_threshold + def _get_declaration(self) -> Optional[types.FunctionDeclaration]: base = self._wrapped._get_declaration() if base is None: @@ -134,7 +145,8 @@ async def run_async(self, *, args: dict[str, Any], tool_context: ToolContext) -> ) raise_for_failed_result(self._wrapped, result) - if len(data) > self._large_result_threshold: + threshold = self._large_result_threshold + if threshold is not None and len(data) > threshold: return { "tool_result_artifact": filename, "note": ( @@ -147,7 +159,7 @@ async def run_async(self, *, args: dict[str, Any], tool_context: ToolContext) -> def wrap_tool_result_as_artifact( - tool: BaseTool, *, large_result_threshold: int = DEFAULT_LARGE_RESULT_THRESHOLD + tool: BaseTool, *, large_result_threshold: int | None = DEFAULT_LARGE_RESULT_THRESHOLD ) -> ToolResultArtifactTool: """Wrap ``tool`` so its results are saved as session artifacts.""" return ToolResultArtifactTool(tool, large_result_threshold=large_result_threshold) @@ -176,7 +188,8 @@ def _serialise_result(result: Any) -> tuple[bytes, str]: return bytes(result), "application/octet-stream" if isinstance(result, str): return result.encode("utf-8"), "text/plain; charset=utf-8" - return json.dumps(result, default=str, ensure_ascii=False).encode("utf-8"), "application/json" + # The same conversion as the reply to the code, so reloading gives that value. + return json.dumps(json_safe(result), ensure_ascii=False).encode("utf-8"), "application/json" __all__ = [ diff --git a/src/adk_code_mode/tools/stubs.py b/src/adk_code_mode/tools/stubs.py index 3519675..6d12d02 100644 --- a/src/adk_code_mode/tools/stubs.py +++ b/src/adk_code_mode/tools/stubs.py @@ -929,7 +929,10 @@ def _render_tool(nt: NamespacedTool, types: _ModuleTypes) -> RenderedTool: docstring = _format_docstring(description=description, param_docs=param_docs) tool = nt.resolved.tool - wraps_result = isinstance(tool, ToolResultArtifactTool) + # Only a wrapper with a threshold can hand back the pointer instead. + wraps_result = ( + isinstance(tool, ToolResultArtifactTool) and tool.large_result_threshold is not None + ) inner = tool._wrapped if isinstance(tool, ToolResultArtifactTool) else tool response = response_schema(inner) or getattr(declaration, "response_json_schema", None) return_type = "Any" diff --git a/tests/test_artifact_tools.py b/tests/test_artifact_tools.py index bb5383a..ad996cc 100644 --- a/tests/test_artifact_tools.py +++ b/tests/test_artifact_tools.py @@ -19,8 +19,10 @@ from adk_code_mode._artifact_tools import ( ARTIFACT_TOOLS, + artifact_tools, list_artifacts, load_artifact, + load_artifact_parsed, save_artifact, ) @@ -190,6 +192,107 @@ async def test_load_artifact_returns_bytes_kind_for_binary_mime() -> None: assert base64.b64decode(result["data"]) == raw +@pytest.mark.parametrize( + ("data", "mime_type", "text"), + [ + # Mime parameters no longer turn JSON into ``kind="bytes"``. + (b"[1, 2]", "application/json; charset=utf-8", "[1, 2]"), + ("é".encode("iso-8859-1"), "application/xml; charset=iso-8859-1", "é"), + ("café".encode("iso-8859-1"), "text/plain; charset=iso-8859-1", "café"), + ], +) +@pytest.mark.asyncio +async def test_load_artifact_decodes_text_with_its_charset( + data: bytes, mime_type: str, text: str +) -> None: + part = genai_types.Part(inline_data=genai_types.Blob(data=data, mime_type=mime_type)) + ctx = _StubToolContext(load_result=part) + result = await load_artifact(filename="a", tool_context=ctx) # type: ignore[arg-type] + assert result == {"kind": "text", "data": text, "mime_type": mime_type} + + +@pytest.mark.asyncio +async def test_save_artifact_encodes_text_with_its_charset() -> None: + ctx = _StubToolContext() + await save_artifact( + filename="notes.txt", + content="café", + mime_type="text/plain; charset=iso-8859-1", + tool_context=ctx, # type: ignore[arg-type] + ) + _, part, _ = ctx.saved[0] + assert part.inline_data is not None + assert part.inline_data.data == "café".encode("iso-8859-1") + + +@pytest.mark.parametrize( + ("data", "mime_type", "expected"), + [ + (b'{"ok": true, "rows": [1, 2]}', "application/json", {"ok": True, "rows": [1, 2]}), + (b"[1, 2]", "application/json; charset=utf-8", [1, 2]), + (b'{"a": 1}', "application/ld+json", {"a": 1}), + (b"not json", "application/json", "not json"), + (b"# Report", "text/markdown", "# Report"), + (b"plain", "text/plain; charset=utf-8", "plain"), + ("é".encode("iso-8859-1"), "application/xml; charset=iso-8859-1", "é"), + (b"\x00\x01\x02", "image/png", {"mime_type": "image/png", "bytes": "AAEC"}), + ], +) +@pytest.mark.asyncio +async def test_load_artifact_parsed_returns_the_content( + data: bytes, mime_type: str, expected: Any +) -> None: + part = genai_types.Part(inline_data=genai_types.Blob(data=data, mime_type=mime_type)) + ctx = _StubToolContext(load_result=part) + result = await load_artifact_parsed(filename="a", tool_context=ctx) # type: ignore[arg-type] + assert result == expected + + +@pytest.mark.asyncio +async def test_load_artifact_parsed_returns_text_part_as_str() -> None: + ctx = _StubToolContext(load_result=genai_types.Part(text="hello")) + result = await load_artifact_parsed(filename="a", tool_context=ctx) # type: ignore[arg-type] + assert result == "hello" + + +@pytest.mark.asyncio +async def test_load_artifact_parsed_returns_none_when_missing() -> None: + ctx = _StubToolContext(load_result=None) + result = await load_artifact_parsed( + filename="missing.txt", + version=2, + tool_context=ctx, # type: ignore[arg-type] + ) + assert result is None + assert ctx.loaded == [("missing.txt", 2)] + + +@pytest.mark.parametrize( + ("content", "mime_type", "expected"), + [ + ('{"status": "ok", "n": [1, 2]}', "application/json", {"status": "ok", "n": [1, 2]}), + ("# Notes", "text/markdown", "# Notes"), + ("café", "text/plain; charset=iso-8859-1", "café"), + ("AAEC", "image/png", {"mime_type": "image/png", "bytes": "AAEC"}), + ("AAEC", None, {"mime_type": "application/octet-stream", "bytes": "AAEC"}), + ], +) +@pytest.mark.asyncio +async def test_save_artifact_round_trips_through_load_artifact_parsed( + content: str, mime_type: str | None, expected: Any +) -> None: + saver = _StubToolContext() + await save_artifact( + filename="a", + content=content, + mime_type=mime_type, + tool_context=saver, # type: ignore[arg-type] + ) + loader = _StubToolContext(load_result=saver.saved[0][1]) + result = await load_artifact_parsed(filename="a", tool_context=loader) # type: ignore[arg-type] + assert result == expected + + @pytest.mark.asyncio async def test_load_artifact_returns_none_when_missing() -> None: ctx = _StubToolContext(load_result=None) @@ -224,6 +327,30 @@ def test_artifact_tools_constant_exposes_all_three() -> None: assert names == {"save_artifact", "load_artifact", "list_artifacts"} +def test_artifact_tools_default_to_the_envelope_load_artifact() -> None: + assert artifact_tools() is ARTIFACT_TOOLS + assert artifact_tools("envelope") is ARTIFACT_TOOLS + + +def test_parsed_artifact_tools_swap_in_the_parsed_load_artifact() -> None: + parsed = artifact_tools("parsed") + assert [t.name for t in parsed] == [t.name for t in ARTIFACT_TOOLS] + by_name = {t.name: t for t in parsed} + assert by_name["save_artifact"] is ARTIFACT_TOOLS[0] + assert by_name["list_artifacts"] is ARTIFACT_TOOLS[2] + load = by_name["load_artifact"] + assert load.func is load_artifact_parsed + declaration = load._get_declaration() + assert declaration is not None and declaration.name == "load_artifact" + assert '{"mime_type": , "bytes": }' in (declaration.description or "") + assert '"kind"' not in (declaration.description or "") + + +def test_artifact_tools_reject_an_unknown_format() -> None: + with pytest.raises(ValueError, match="'envelope' or 'parsed'"): + artifact_tools("raw") # type: ignore[arg-type] + + def test_artifact_tools_declarations_omit_tool_context_param() -> None: by_name = {t.name: t for t in ARTIFACT_TOOLS} save_decl = by_name["save_artifact"]._get_declaration() diff --git a/tests/test_integration.py b/tests/test_integration.py index 8c7debb..1b14717 100644 --- a/tests/test_integration.py +++ b/tests/test_integration.py @@ -55,6 +55,21 @@ async def run_async(self, *, args: dict[str, Any], tool_context: Any) -> Any: return {"echoed": args.get("message", "")} +class _BigTool(BaseTool): + def __init__(self) -> None: + super().__init__(name="big", description="Return a result over the default threshold.") + + def _get_declaration(self) -> genai_types.FunctionDeclaration | None: + return genai_types.FunctionDeclaration( + name=self.name, + description=self.description, + parameters_json_schema={"type": "object", "properties": {}}, + ) + + async def run_async(self, *, args: dict[str, Any], tool_context: Any) -> Any: + return {"blob": "x" * 60_000} + + class _OptionalArgTool(BaseTool): def __init__(self) -> None: super().__init__(name="optional_lookup", description="Optional-arg tool.") @@ -280,6 +295,74 @@ async def test_artifact_helpers_support_binary_content() -> None: assert "bytes b'\\x00\\x01\\x02' application/octet-stream" in result["stdout"] +@pytest.mark.asyncio +async def test_large_tool_result_returns_a_pointer_by_default() -> None: + artifact_service = InMemoryArtifactService() + session = Session( + id="s2-pointer", + app_name="test-app", + user_id="u1", + state={}, + events=[], + last_update_time=0.0, + ) + ctx = _make_invocation_context(artifact_service, session) + tool = ExecuteCodeTool(tools=[_BigTool()], backend=FakeRuntime(), max_output_chars=10_000) + code = ( + "import json\n" + "from tools import big, load_artifact\n" + "result = big()\n" + "print('keys', sorted(result))\n" + "saved = load_artifact(filename=result['tool_result_artifact'])\n" + "print('saved', saved['kind'], len(json.loads(saved['data'])['blob']))\n" + ) + result = await _run(tool, ctx, code, call_id="run-pointer") + + assert "keys ['note', 'tool_result_artifact']" in result["stdout"] + assert "saved text 60000" in result["stdout"] + + +@pytest.mark.asyncio +async def test_opt_ins_return_full_tool_results_and_parsed_artifacts() -> None: + artifact_service = InMemoryArtifactService() + session = Session( + id="s2-opt-in", app_name="test-app", user_id="u1", state={}, events=[], last_update_time=0.0 + ) + ctx = _make_invocation_context(artifact_service, session) + tool = ExecuteCodeTool( + tools=[_BigTool()], + backend=FakeRuntime(), + max_output_chars=10_000, + large_result_threshold=None, + load_artifact_format="parsed", + ) + code = ( + "import base64, json\n" + "from tools import big, list_artifacts, load_artifact, save_artifact\n" + "result = big()\n" + "print('blob', len(result['blob']))\n" + "[saved] = [name for name in list_artifacts() if name.startswith('big_')]\n" + "print('saved', load_artifact(filename=saved) == result)\n" + "save_artifact(\n" + " filename='report.json', content=json.dumps({'ok': True}), mime_type='application/json'\n" + ")\n" + "print('json', load_artifact(filename='report.json'))\n" + "save_artifact(\n" + " filename='blob.bin',\n" + " content=base64.b64encode(b'\\x00\\x01').decode('ascii'),\n" + " mime_type='application/octet-stream',\n" + ")\n" + "blob = load_artifact('blob.bin')\n" + "print('bin', base64.b64decode(blob['bytes']), blob['mime_type'])\n" + ) + result = await _run(tool, ctx, code, call_id="run-opt-in") + + assert "blob 60000" in result["stdout"] + assert "saved True" in result["stdout"] + assert "json {'ok': True}" in result["stdout"] + assert "bin b'\\x00\\x01' application/octet-stream" in result["stdout"] + + @pytest.mark.asyncio async def test_workspace_is_fresh_each_turn_while_artifact_helpers_persist() -> None: artifact_service = InMemoryArtifactService() diff --git a/tests/test_remote_backend.py b/tests/test_remote_backend.py index 0392c7f..5cf75a9 100644 --- a/tests/test_remote_backend.py +++ b/tests/test_remote_backend.py @@ -12,7 +12,8 @@ from adk_code_mode import RemoteBackend from adk_code_mode.runtime.base import SandboxResult, SandboxSession -from adk_code_mode.runtime.protocol import Frame +from adk_code_mode.runtime.protocol import Frame, ToolResultFrame +from adk_code_mode.runtime.remote import _RemoteSandboxSession class _NoopSession: @@ -80,3 +81,28 @@ async def fake_connect(*, tools_files: Mapping[str, str], workdir_path: str) -> await backend.start(tools_files={}, workdir_path="/tmp", timeout_seconds=None) assert calls == 1 + + +@pytest.mark.asyncio +async def test_send_refuses_a_frame_over_max_message_size() -> None: + class _Ws: + def __init__(self) -> None: + self.sent: list[str] = [] + + async def send(self, message: str) -> None: + self.sent.append(message) + + ws = _Ws() + session = _RemoteSandboxSession( + ws=ws, + workdir_path="/tmp", + max_message_size=1_000, + max_upload_workspace_bytes=0, + max_download_workspace_bytes=0, + ) + + await session.send(ToolResultFrame(id="1", ok=True, value="small")) + with pytest.raises(ValueError, match="exceeds max_message_size"): + await session.send(ToolResultFrame(id="2", ok=True, value="x" * 2_000)) + + assert len(ws.sent) == 1 diff --git a/tests/test_stubs.py b/tests/test_stubs.py index b50b59e..42df0ab 100644 --- a/tests/test_stubs.py +++ b/tests/test_stubs.py @@ -564,6 +564,17 @@ def test_wrapped_tool_return_type_includes_the_large_result_pointer() -> None: ) +def test_wrapped_tool_without_a_threshold_keeps_the_wrapped_return_type() -> None: + # With no threshold the result is never replaced, so there is no pointer to type. + tool = ToolResultArtifactTool( + _SchemaTool("count", description="Count records.", response={"type": "integer"}), + large_result_threshold=None, + ) + rt = stubs.render_tool(_build([(tool, None)])[0]) + assert rt.return_type == "int" + assert rt.types == () + + def test_identical_shapes_share_one_class_across_a_module() -> None: user = {"type": "object", "properties": {"gid": {"type": "string"}}} other = {"type": "object", "properties": {"email": {"type": "string"}}} diff --git a/tests/test_tool.py b/tests/test_tool.py index 99a0256..2613fb8 100644 --- a/tests/test_tool.py +++ b/tests/test_tool.py @@ -25,6 +25,7 @@ from google.adk.tools.tool_context import ToolContext from google.genai import types as genai_types +from adk_code_mode._artifact_tools import ARTIFACT_TOOLS, load_artifact, load_artifact_parsed from adk_code_mode.tool import ExecuteCodeTool from tests._fake_runtime import FakeRuntime @@ -109,6 +110,42 @@ def test_description_says_what_is_saved_and_how_to_load_it( assert expected in tool.description +_POINTER_SENTENCE = " Large tool results return a `tool_result_artifact` pointer." + + +def test_description_mentions_the_large_result_pointer_by_default() -> None: + assert _POINTER_SENTENCE in ExecuteCodeTool(backend=FakeRuntime()).description + + +def test_description_drops_the_pointer_when_large_results_are_returned_in_full() -> None: + tool = ExecuteCodeTool(backend=FakeRuntime(), large_result_threshold=None) + assert "tool_result_artifact" not in tool.description + assert "to read one in a later turn. Tool calls that call APIs" in tool.description + + +def _load_artifact_func(tool: ExecuteCodeTool) -> Any: + [load] = [t for t in tool.tools if isinstance(t, BaseTool) and t.name == "load_artifact"] + return getattr(load, "func") + + +def test_load_artifact_returns_the_envelope_by_default() -> None: + tool = ExecuteCodeTool(backend=FakeRuntime()) + assert _load_artifact_func(tool) is load_artifact + assert all(t in tool.tools for t in ARTIFACT_TOOLS) + + +def test_load_artifact_format_parsed_injects_the_parsed_load_artifact() -> None: + tool = ExecuteCodeTool(backend=FakeRuntime(), load_artifact_format="parsed") + assert _load_artifact_func(tool) is load_artifact_parsed + names = [t.name for t in tool.tools if isinstance(t, BaseTool)] + assert names == ["save_artifact", "load_artifact", "list_artifacts"] + + +def test_load_artifact_format_rejects_an_unknown_value() -> None: + with pytest.raises(ValueError, match="load_artifact_format"): + ExecuteCodeTool(backend=FakeRuntime(), load_artifact_format="raw") # type: ignore[arg-type] + + def test_tools_and_backend_properties_expose_the_configured_surface() -> None: schema_tool = _SchemaTool("ping", "Ping.") backend = FakeRuntime() diff --git a/tests/test_tool_result_artifacts.py b/tests/test_tool_result_artifacts.py index 6b2a995..d8e45e1 100644 --- a/tests/test_tool_result_artifacts.py +++ b/tests/test_tool_result_artifacts.py @@ -4,6 +4,7 @@ from __future__ import annotations import json +from dataclasses import dataclass from typing import Any, cast import pytest @@ -12,12 +13,16 @@ from google.genai import types from adk_code_mode import ( + DEFAULT_LARGE_RESULT_THRESHOLD, TOOL_RESULT_DESCRIPTION_KEY, TOOL_RESULT_FILENAME_KEY, TOOL_RESULT_METADATA_KEY, TOOL_RESULT_NAME_KEY, ToolResultArtifactTool, + wrap_tool_result_as_artifact, ) +from adk_code_mode._artifact_tools import load_artifact_parsed +from adk_code_mode._json import json_safe from adk_code_mode.tool import ExecuteCodeTool from adk_code_mode.tools import normaliser from tests._fake_runtime import FakeRuntime @@ -128,6 +133,68 @@ async def test_large_result_elided_with_reload_tip() -> None: assert json.loads(ctx.saved[0]["artifact"].inline_data.data) == big # full payload persisted +@pytest.mark.asyncio +async def test_default_threshold_elides_a_result_over_50_000_bytes() -> None: + assert DEFAULT_LARGE_RESULT_THRESHOLD == 50_000 + big = {"blob": "x" * 60_000} + ctx = cast(Any, _FakeToolContext()) + tool = ToolResultArtifactTool(_ResultTool(big)) + assert tool.large_result_threshold == DEFAULT_LARGE_RESULT_THRESHOLD + result = await tool.run_async(args={"q": "hi"}, tool_context=cast(ToolContext, ctx)) + assert set(result) == {"tool_result_artifact", "note"} + + +@pytest.mark.asyncio +async def test_no_threshold_returns_a_large_result_in_full_and_saves_it() -> None: + big = {"blob": "x" * 200_000} + ctx = cast(Any, _FakeToolContext()) + tool = wrap_tool_result_as_artifact(_ResultTool(big), large_result_threshold=None) + assert tool.large_result_threshold is None + result = await tool.run_async(args={"q": "hi"}, tool_context=cast(ToolContext, ctx)) + assert result == big + assert json.loads(ctx.saved[0]["artifact"].inline_data.data) == big + + +def _reload(ctx: Any) -> Any: + part: types.Part = ctx.saved[0]["artifact"] + + async def _load(filename: str, *, version: int | None = None) -> types.Part: + return part + + ctx.load_artifact = _load + return load_artifact_parsed(filename=ctx.saved[0]["filename"], tool_context=ctx) + + +@pytest.mark.parametrize( + "value", + [{"rows": [{"id": 1, "name": "Ada"}], "next": None}, [1, "two", 3.0], "plain text", None], +) +@pytest.mark.asyncio +async def test_saved_result_reloads_parsed_as_the_original_value(value: Any) -> None: + ctx = cast(Any, _FakeToolContext()) + await ToolResultArtifactTool(_ResultTool(value)).run_async( + args={"q": "hi"}, tool_context=cast(ToolContext, ctx) + ) + assert await _reload(ctx) == value + + +@dataclass +class _Record: + label: str + + +@pytest.mark.asyncio +async def test_saved_result_holds_the_value_sent_to_the_code() -> None: + record = _Record(label="ready") + ctx = cast(Any, _FakeToolContext()) + await ToolResultArtifactTool(_ResultTool(record)).run_async( + args={"q": "hi"}, tool_context=cast(ToolContext, ctx) + ) + # Saved with the RPC reply's conversion, not ``str(record)``. + assert json.loads(ctx.saved[0]["artifact"].inline_data.data) == {"label": "ready"} + assert await _reload(ctx) == json_safe(record) == {"label": "ready"} + + @pytest.mark.asyncio async def test_no_artifact_service_is_passthrough() -> None: ctx = cast(Any, _FakeToolContext(has_artifact_service=False)) @@ -146,6 +213,15 @@ def test_tool_wraps_non_artifact_tools_by_default() -> None: tool = ExecuteCodeTool(tools=[_ResultTool({}, name="search")], backend=FakeRuntime()) wrapped = tool._apply_tool_result_wrapping([_resolved(_ResultTool({}, name="search"))]) assert isinstance(wrapped[0].tool, ToolResultArtifactTool) + assert wrapped[0].tool.large_result_threshold == DEFAULT_LARGE_RESULT_THRESHOLD + + +@pytest.mark.parametrize("threshold", [None, 10]) +def test_tool_passes_its_large_result_threshold_to_the_wrapper(threshold: int | None) -> None: + tool = ExecuteCodeTool(tools=[], backend=FakeRuntime(), large_result_threshold=threshold) + wrapped = tool._apply_tool_result_wrapping([_resolved(_ResultTool({}, name="search"))]) + assert isinstance(wrapped[0].tool, ToolResultArtifactTool) + assert wrapped[0].tool.large_result_threshold == threshold def test_tool_skips_artifact_tools_and_avoids_double_wrap() -> None: