diff --git a/README.md b/README.md index 087cbba..cdb27d2 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ Inspired by Cloudflare's [Code Mode](https://blog.cloudflare.com/code-mode/) and - **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** — 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`. +- **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 later turns can reload them. The code always gets the full result. 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.). - **Local development** — `UnsafeLocalDockerBackend` runs the sandbox against your local Docker daemon for fast iteration. **Not for production** — see [Safety](#-safety). @@ -225,7 +225,7 @@ save_artifact( mime_type="application/json", ) print(list_artifacts()) -report = json.loads(load_artifact(filename="report.json")["data"]) +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`: @@ -241,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 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`. The code always gets the full 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. @@ -281,7 +281,7 @@ The model can read spilled stdout back from the overflow artifact: ```python from tools import load_artifact spilled = load_artifact(filename="code_mode/stdout/.txt") -print(spilled["data"][-2000:]) +print(spilled[-2000:]) ``` ### Turn-scoped sessions @@ -313,14 +313,13 @@ preinstalled packages, and available functions. Print function calls, variables, 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 +`load_artifact` (imported the same way) to read one in a later turn. 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 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 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 +364,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 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 +405,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 the content itself: 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/_artifact_tools.py b/src/adk_code_mode/_artifact_tools.py index bf3bcb2..becde1b 100644 --- a/src/adk_code_mode/_artifact_tools.py +++ b/src/adk_code_mode/_artifact_tools.py @@ -10,14 +10,14 @@ 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``. ``load_artifact`` returns the content itself: parsed JSON, +a ``str`` for other text, or ``{"mime_type", "bytes"}`` for binary. """ from __future__ import annotations import base64 +import json from typing import Any from google.adk.tools.function_tool import FunctionTool @@ -31,6 +31,7 @@ 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 +39,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, @@ -65,11 +83,13 @@ async def save_artifact( ) ``custom_metadata`` is custom metadata to associate with the artifact. + ``load_artifact`` gives back the parsed JSON, the text, or + ``{"mime_type", "bytes"}`` with the same base64 string. """ 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", ) ) @@ -88,50 +108,42 @@ async def load_artifact( filename: str, version: int | None = None, tool_context: ToolContext, -) -> dict[str, Any] | None: - """Load an artifact by filename. Returns ``None`` if not found. +) -> Any: + """Load an artifact by filename and return its content. Returns ``None`` if not found. - Returned dict shape: + The return value depends on the artifact's mime type: - { - "kind": "text" | "bytes", - "data": , # text: the string; bytes: base64-encoded - "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: - result = load_artifact(filename="report.json") - if result is None: - return - if result["kind"] == "text" and result["mime_type"] == "application/json": - payload = json.loads(result["data"]) - elif result["kind"] == "bytes": - blob = base64.b64decode(result["data"]) + 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 not None: - mime_type = inline.mime_type - data = inline.data or b"" - if isinstance(data, str): - data = data.encode("utf-8") - if _is_text_mime(mime_type): - return { - "kind": "text", - "data": data.decode("utf-8"), - "mime_type": mime_type, - } - return { - "kind": "bytes", - "data": base64.b64encode(data).decode("ascii"), - "mime_type": mime_type, - } - if part.text is not None: - return {"kind": "text", "data": part.text, "mime_type": None} - return {"kind": "text", "data": "", "mime_type": None} + if inline is None: + return part.text or "" + mime_type = inline.mime_type + data = inline.data or b"" + if isinstance(data, str): + data = data.encode("utf-8") + 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 async def list_artifacts(*, tool_context: ToolContext) -> list[str]: 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..c456459 100644 --- a/src/adk_code_mode/tool.py +++ b/src/adk_code_mode/tool.py @@ -161,8 +161,6 @@ 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: - 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 ( f"{_DESCRIPTION_PREFIX}{pointer}{_DESCRIPTION_OUTPUT}{saved}.{_DESCRIPTION_ERRORS}{limit}" @@ -248,9 +246,8 @@ def __init__( ``load_artifact``. Set ``False`` for a strict tool surface. 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. + reloadable in later turns via ``load_artifact``. The code always + gets the full result. Set ``False`` to skip saving. 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 diff --git a/src/adk_code_mode/tool_result_artifacts.py b/src/adk_code_mode/tool_result_artifacts.py index 211e9c3..e6118a9 100644 --- a/src/adk_code_mode/tool_result_artifacts.py +++ b/src/adk_code_mode/tool_result_artifacts.py @@ -16,10 +16,8 @@ markers, land in the artifact's ``custom_metadata`` so a host (e.g. an A2A layer) can decide whether and how to forward the result to the user. -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``. +The result is always returned unchanged; the artifact lets a later turn reload it +with ``load_artifact``. """ from __future__ import annotations @@ -32,6 +30,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 @@ -41,8 +40,6 @@ TOOL_RESULT_DESCRIPTION_KEY = "code_mode.artifact_description" TOOL_RESULT_FILENAME_KEY = "code_mode.artifact_filename" -DEFAULT_LARGE_RESULT_THRESHOLD = 50_000 - _ARTIFACT_NAME_PARAM = "artifact_name" _ARTIFACT_DESCRIPTION_PARAM = "artifact_description" @@ -55,19 +52,13 @@ class ToolResultArtifactTool(BaseTool): ``artifact_description``, for naming the saved artifact. """ - def __init__( - self, - wrapped: BaseTool, - *, - large_result_threshold: int = DEFAULT_LARGE_RESULT_THRESHOLD, - ) -> None: + def __init__(self, wrapped: BaseTool) -> None: super().__init__( name=wrapped.name, description=wrapped.description, is_long_running=wrapped.is_long_running, ) self._wrapped = wrapped - self._large_result_threshold = large_result_threshold # Don't shadow a real tool parameter that happens to share the name. existing = _declared_param_names(wrapped) self._inject_name = _ARTIFACT_NAME_PARAM not in existing @@ -134,23 +125,12 @@ 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: - return { - "tool_result_artifact": filename, - "note": ( - f"The tool result ({len(data):,} bytes) was saved as an artifact " - f"{filename!r} instead of being returned inline. Reload it with " - f"load_artifact(filename={filename!r})." - ), - } return result -def wrap_tool_result_as_artifact( - tool: BaseTool, *, large_result_threshold: int = DEFAULT_LARGE_RESULT_THRESHOLD -) -> ToolResultArtifactTool: +def wrap_tool_result_as_artifact(tool: BaseTool) -> ToolResultArtifactTool: """Wrap ``tool`` so its results are saved as session artifacts.""" - return ToolResultArtifactTool(tool, large_result_threshold=large_result_threshold) + return ToolResultArtifactTool(tool) def _declared_param_names(tool: BaseTool) -> set[str]: @@ -176,11 +156,10 @@ 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" + return json.dumps(json_safe(result), ensure_ascii=False).encode("utf-8"), "application/json" __all__ = [ - "DEFAULT_LARGE_RESULT_THRESHOLD", "TOOL_RESULT_DESCRIPTION_KEY", "TOOL_RESULT_FILENAME_KEY", "TOOL_RESULT_METADATA_KEY", diff --git a/src/adk_code_mode/tools/stubs.py b/src/adk_code_mode/tools/stubs.py index 3519675..90e8df7 100644 --- a/src/adk_code_mode/tools/stubs.py +++ b/src/adk_code_mode/tools/stubs.py @@ -30,16 +30,6 @@ from adk_code_mode.tool_result_artifacts import ToolResultArtifactTool from adk_code_mode.tools.namespacing import NamespacedTool, PythonNameCollisionError -_TOOL_RESULT_ARTIFACT_SCHEMA = { - "title": "ToolResultArtifact", - "type": "object", - "properties": { - "tool_result_artifact": {"type": "string"}, - "note": {"type": "string"}, - }, - "required": ["tool_result_artifact", "note"], -} - _PRIMITIVES = { "string": "str", "integer": "int", @@ -929,7 +919,6 @@ 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) inner = tool._wrapped if isinstance(tool, ToolResultArtifactTool) else tool response = response_schema(inner) or getattr(declaration, "response_json_schema", None) return_type = "Any" @@ -937,11 +926,6 @@ def _render_tool(nt: NamespacedTool, types: _ModuleTypes) -> RenderedTool: defs = {**(response.get("definitions") or {}), **(response.get("$defs") or {})} short = _pascal(nt.attribute) + "Response" return_type = types.type_of(response, short=short, parent="", defs=defs, own=True) - if wraps_result and return_type != "Any": - pointer = types.type_of( - _TOOL_RESULT_ARTIFACT_SCHEMA, short="ToolResultArtifact", parent="", defs={} - ) - return_type = f"{return_type} | {pointer}" return RenderedTool( attribute=nt.attribute, diff --git a/tests/test_artifact_tools.py b/tests/test_artifact_tools.py index bb5383a..4b8eb9d 100644 --- a/tests/test_artifact_tools.py +++ b/tests/test_artifact_tools.py @@ -154,40 +154,58 @@ async def test_save_artifact_defaults_custom_metadata_to_none() -> None: assert custom_metadata is None +@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_returns_text_kind_for_text_mime() -> None: - part = genai_types.Part( - inline_data=genai_types.Blob(data=b'{"ok": true}', mime_type="application/json") - ) +async def test_load_artifact_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( - filename="report.json", - tool_context=ctx, # type: ignore[arg-type] - ) - - assert result == { - "kind": "text", - "data": '{"ok": true}', - "mime_type": "application/json", - } + result = await load_artifact(filename="a", tool_context=ctx) # type: ignore[arg-type] + assert result == expected @pytest.mark.asyncio -async def test_load_artifact_returns_bytes_kind_for_binary_mime() -> None: - raw = b"\x00\x01\x02" - part = genai_types.Part( - inline_data=genai_types.Blob(data=raw, mime_type="application/octet-stream") - ) - ctx = _StubToolContext(load_result=part) - result = await load_artifact( - filename="blob.bin", - tool_context=ctx, # type: ignore[arg-type] +async def test_load_artifact_returns_text_part_as_str() -> None: + ctx = _StubToolContext(load_result=genai_types.Part(text="hello")) + assert await load_artifact(filename="a", tool_context=ctx) == "hello" # type: ignore[arg-type] + + +@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( + 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] ) - - assert result is not None - assert result["kind"] == "bytes" - assert result["mime_type"] == "application/octet-stream" - assert base64.b64decode(result["data"]) == raw + loader = _StubToolContext(load_result=saver.saved[0][1]) + assert await load_artifact(filename="a", tool_context=loader) == expected # type: ignore[arg-type] @pytest.mark.asyncio diff --git a/tests/test_integration.py b/tests/test_integration.py index 8c7debb..7c5d99c 100644 --- a/tests/test_integration.py +++ b/tests/test_integration.py @@ -201,7 +201,7 @@ async def test_artifact_helpers_save_list_and_load_json() -> None: ")\n" "print('items', list_artifacts())\n" "loaded = load_artifact(filename='report.json')\n" - "print('loaded', json.loads(loaded['data']))\n" + "print('loaded', loaded)\n" ) result = await _run(tool, ctx, code, call_id="run-ws") @@ -273,11 +273,11 @@ async def test_artifact_helpers_support_binary_content() -> None: "import base64\n" "from tools import load_artifact\n" "blob = load_artifact(filename='blob.bin')\n" - "print(blob['kind'], base64.b64decode(blob['data']), blob['mime_type'])\n" + "print(base64.b64decode(blob['bytes']), blob['mime_type'])\n" ) result = await _run(tool, ctx, load, call_id="run-bin-2") - assert "bytes b'\\x00\\x01\\x02' application/octet-stream" in result["stdout"] + assert "b'\\x00\\x01\\x02' application/octet-stream" in result["stdout"] @pytest.mark.asyncio @@ -314,7 +314,7 @@ async def test_workspace_is_fresh_each_turn_while_artifact_helpers_persist() -> "import os\n" "from tools import load_artifact\n" "print('workspace_has_temp', os.path.exists('temp.txt'))\n" - "print('artifact_value', load_artifact(filename='persist.txt')['data'])\n" + "print('artifact_value', load_artifact(filename='persist.txt'))\n" ) ctx.invocation_id = "inv-fresh-2" result = await _run(tool, ctx, second, call_id="run-fresh-2") 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..e7decca 100644 --- a/tests/test_stubs.py +++ b/tests/test_stubs.py @@ -553,15 +553,14 @@ def test_mcp_output_schema_becomes_typed_dict_return_type() -> None: assert _load_stub(source)["BookingsItem"].__name__ == "BookingsItem" -def test_wrapped_tool_return_type_includes_the_large_result_pointer() -> None: +def test_wrapped_tool_keeps_the_wrapped_return_type() -> None: + # Saving the result as an artifact never replaces it, so the type is unchanged. tool = ToolResultArtifactTool( _SchemaTool("count", description="Count records.", response={"type": "integer"}) ) rt = stubs.render_tool(_build([(tool, None)])[0]) - assert rt.return_type == "int | ToolResultArtifact" - assert rt.types == ( - "class ToolResultArtifact(TypedDict):\n tool_result_artifact: str\n note: str", - ) + assert rt.return_type == "int" + assert rt.types == () def test_identical_shapes_share_one_class_across_a_module() -> None: diff --git a/tests/test_tool.py b/tests/test_tool.py index 99a0256..5742962 100644 --- a/tests/test_tool.py +++ b/tests/test_tool.py @@ -107,6 +107,8 @@ def test_description_says_what_is_saved_and_how_to_load_it( save_tool_results_as_artifacts=tool_results, ) assert expected in tool.description + # The code always gets the full result, so there is no pointer to describe. + assert "tool_result_artifact" not in tool.description def test_tools_and_backend_properties_expose_the_configured_surface() -> None: diff --git a/tests/test_tool_result_artifacts.py b/tests/test_tool_result_artifacts.py index 6b2a995..e8077da 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 @@ -18,6 +19,8 @@ TOOL_RESULT_NAME_KEY, ToolResultArtifactTool, ) +from adk_code_mode._artifact_tools import load_artifact +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 @@ -84,12 +87,12 @@ def _get_declaration(self) -> types.FunctionDeclaration: @pytest.mark.asyncio -async def test_small_result_saved_and_returned_unchanged() -> None: +async def test_result_saved_and_returned_unchanged() -> None: ctx = cast(Any, _FakeToolContext()) result = await ToolResultArtifactTool(_ResultTool({"ok": True})).run_async( args={"q": "hi"}, tool_context=cast(ToolContext, ctx) ) - assert result == {"ok": True} # transparent for small results + assert result == {"ok": True} saved = ctx.saved[0] assert saved["custom_metadata"][TOOL_RESULT_METADATA_KEY] == "true" assert saved["filename"] == saved["custom_metadata"][TOOL_RESULT_FILENAME_KEY] @@ -112,20 +115,55 @@ async def test_optional_name_and_description_used() -> None: @pytest.mark.asyncio -async def test_large_result_elided_with_reload_tip() -> None: - big = {"blob": "x" * 100} +async def test_large_result_returned_in_full_and_saved() -> None: + big = {"blob": "x" * 200_000} ctx = cast(Any, _FakeToolContext()) - result = await ToolResultArtifactTool(_ResultTool(big), large_result_threshold=10).run_async( + result = await ToolResultArtifactTool(_ResultTool(big)).run_async( args={"q": "hi"}, tool_context=cast(ToolContext, ctx) ) - assert set(result) == {"tool_result_artifact", "note"} - assert result["tool_result_artifact"] == ctx.saved[0]["filename"] - assert result["note"] == ( - "The tool result (112 bytes) was saved as an artifact " - "'search_call-1.json' instead of being returned inline. Reload it with " - "load_artifact(filename='search_call-1.json')." + assert result == big + assert json.loads(ctx.saved[0]["artifact"].inline_data.data) == big + + +@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_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 json.loads(ctx.saved[0]["artifact"].inline_data.data) == big # full payload persisted + part: types.Part = ctx.saved[0]["artifact"] + + async def _load(filename: str, *, version: int | None = None) -> types.Part: + return part + + ctx.load_artifact = _load + assert await load_artifact(filename=ctx.saved[0]["filename"], tool_context=ctx) == value + + +@dataclass +class _Record: + label: str + + +@pytest.mark.asyncio +async def test_saved_result_reloads_as_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) + ) + part: types.Part = ctx.saved[0]["artifact"] + + async def _load(filename: str, *, version: int | None = None) -> types.Part: + return part + + ctx.load_artifact = _load + loaded = await load_artifact(filename=ctx.saved[0]["filename"], tool_context=ctx) + assert loaded == json_safe(record) == {"label": "ready"} @pytest.mark.asyncio