diff --git a/src/adk_code_mode/mcp_results.py b/src/adk_code_mode/mcp_results.py new file mode 100644 index 0000000..a41d847 --- /dev/null +++ b/src/adk_code_mode/mcp_results.py @@ -0,0 +1,36 @@ +# SPDX-FileCopyrightText: 2025-present Agenta +# +# SPDX-License-Identifier: Apache-2.0 +"""Return an MCP tool's ``structuredContent`` to code instead of the whole result. + +ADK's ``McpTool`` returns the full ``CallToolResult`` (``content``, +``structuredContent``, ``isError``). When the tool declares an ``outputSchema``, +the MCP spec requires ``structuredContent`` to match it, and ``content`` is meant to +be a serialised copy for older clients. So code gets ``structuredContent`` alone, +and the stub's return type is built from the ``outputSchema``. +""" + +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 output_schema(tool: BaseTool) -> dict[str, Any] | None: + """Return the ``outputSchema`` of an MCP tool, or ``None`` for any other tool. + + ``tool`` is the tool itself, not a ``ToolResultArtifactTool`` wrapping it. + """ + return tool.raw_mcp_tool.outputSchema if isinstance(tool, McpTool) else None + + +def structured_result(tool: BaseTool, result: Any) -> Any: + """Return ``structuredContent`` when ``tool`` is an MCP tool with an ``outputSchema``.""" + if output_schema(tool) and isinstance(result, dict) and "structuredContent" in result: + return result["structuredContent"] + return result + + +__all__ = ["output_schema", "structured_result"] diff --git a/src/adk_code_mode/tool_result_artifacts.py b/src/adk_code_mode/tool_result_artifacts.py index 211e9c3..dcd8c08 100644 --- a/src/adk_code_mode/tool_result_artifacts.py +++ b/src/adk_code_mode/tool_result_artifacts.py @@ -32,6 +32,7 @@ from google.adk.tools.tool_context import ToolContext from google.genai import types +from adk_code_mode.mcp_results import structured_result from adk_code_mode.tool_failures import raise_for_failed_result # Transport-neutral metadata stamped on saved tool-result artifacts. Downstream @@ -115,7 +116,8 @@ async def run_async(self, *, args: dict[str, Any], tool_context: ToolContext) -> stem = artifact_name or _default_stem(self.name, tool_context) filename = f"{stem}.json" - data, mime_type = _serialise_result(result) + # Save what code receives, so reloading the artifact gives the same value. + data, mime_type = _serialise_result(structured_result(self._wrapped, result)) metadata: dict[str, Any] = { TOOL_RESULT_METADATA_KEY: "true", TOOL_RESULT_FILENAME_KEY: filename, diff --git a/src/adk_code_mode/tools/catalog.py b/src/adk_code_mode/tools/catalog.py index 2d2dbf4..dfa8066 100644 --- a/src/adk_code_mode/tools/catalog.py +++ b/src/adk_code_mode/tools/catalog.py @@ -16,7 +16,7 @@ from typing import Literal from adk_code_mode.tools.namespacing import NamespacedTool -from adk_code_mode.tools.stubs import RenderedTool, render_tool +from adk_code_mode.tools.stubs import RenderedTool, render_tools Detail = Literal["full", "names"] @@ -54,7 +54,7 @@ def render_catalog(namespaced: list[NamespacedTool], *, detail: Detail = "full") for ns in sorted(n for n in grouped if n is not None): tools = sorted(grouped[ns], key=lambda t: t.attribute) - rendered = [render_tool(t) for t in tools] + rendered = render_tools(tools) names = ", ".join(rt.attribute for rt in rendered) entries = [_render_entry(rt) for rt in rendered] if detail == "full" else [] sections.append( @@ -67,7 +67,7 @@ def render_catalog(namespaced: list[NamespacedTool], *, detail: Detail = "full") top_level = sorted(grouped.get(None, []), key=lambda t: t.attribute) if top_level: - rendered = [render_tool(t) for t in top_level] + rendered = render_tools(top_level) names = ", ".join(rt.attribute for rt in rendered) entries = [_render_entry(rt) for rt in rendered] if detail == "full" else [] sections.append( diff --git a/src/adk_code_mode/tools/dispatcher.py b/src/adk_code_mode/tools/dispatcher.py index f51eedf..af7bc6a 100644 --- a/src/adk_code_mode/tools/dispatcher.py +++ b/src/adk_code_mode/tools/dispatcher.py @@ -17,6 +17,9 @@ ``agent.canonical_on_tool_error_callbacks``. If no replacement, re-raise. 5. ``plugin_manager.run_after_tool_callback`` 6. ``agent.canonical_after_tool_callbacks`` (first non-``None`` replaces result) + +Callbacks see the result in ADK's shape; only then does an MCP tool with an +``outputSchema`` hand code its ``structuredContent`` (see ``mcp_results``). """ from __future__ import annotations @@ -33,6 +36,7 @@ from google.adk.tools.tool_context import ToolContext from google.genai import types as genai_types +from adk_code_mode.mcp_results import structured_result from adk_code_mode.tool_failures import HTTPStatusError, raise_for_failed_result from adk_code_mode.tool_result_artifacts import ToolResultArtifactTool from adk_code_mode.tools.namespacing import Registry @@ -178,7 +182,8 @@ async def _run_and_merge(self, tool: BaseTool, args: dict[str, Any]) -> Any: async with self._merge_lock: _deep_merge_dicts(self._ctx.session.state, tool_context.actions.state_delta) self._artifact_delta.update(tool_context.actions.artifact_delta) - return response + inner = tool._wrapped if isinstance(tool, ToolResultArtifactTool) else tool + return structured_result(inner, response) async def _run_with_callbacks( self, diff --git a/src/adk_code_mode/tools/stubs.py b/src/adk_code_mode/tools/stubs.py index a0e5b3c..f06343a 100644 --- a/src/adk_code_mode/tools/stubs.py +++ b/src/adk_code_mode/tools/stubs.py @@ -5,8 +5,10 @@ Each stub is a real ``.py`` file the sandbox writes into ``/tools/``. The function body is a single delegation into the host via the RPC client, so the -generated file is small and robust. Type hints come from the tool's JSON -Schema (``BaseTool._get_declaration().parameters_json_schema``). +generated file is small and robust. Parameter types come from the tool's +JSON Schema (``BaseTool._get_declaration().parameters_json_schema``); the return +type comes from ``response_json_schema`` (an MCP tool's ``outputSchema``), with +objects rendered as ``TypedDict`` classes shared by the tools of one module. ``render_tool`` returns a structured ``RenderedTool``; ``render_tool_source`` turns one into the on-disk ``.py`` stub. The catalog renderer (in @@ -16,12 +18,16 @@ from __future__ import annotations +import itertools +import json import keyword import re import textwrap from dataclasses import dataclass from typing import Any, Literal +from adk_code_mode.mcp_results import output_schema +from adk_code_mode.tool_result_artifacts import ToolResultArtifactTool from adk_code_mode.tools.namespacing import NamespacedTool, PythonNameCollisionError _PRIMITIVES = { @@ -529,10 +535,213 @@ def _format_docstring( for extra in rest: lines.append(f" {extra}") lines.extend(_describe_fields(schema, indent=" ")) - body = "\n ".join(lines) + body = "\n ".join(lines).replace("\\", "\\\\").replace('"""', '""\\"') return f'"""{body}\n """' +# Names a generated class must not take: the stub's own imports. +_TYPING_NAMES = frozenset({"Any", "Literal", "NotRequired", "TYPE_CHECKING", "TypedDict"}) + +_REF_PREFIXES = ("#/$defs/", "#/definitions/") + +_Fields = tuple[tuple[str, str], ...] + + +def _pascal(raw: str) -> str: + """``first_name`` / ``firstName`` / ``first-name`` -> ``FirstName``.""" + return "".join(part[:1].upper() + part[1:] for part in re.split(r"[^0-9a-zA-Z]+", raw)) + + +def _is_object(schema: dict[str, Any]) -> bool: + properties = schema.get("properties") + return ( + schema.get("type") in ("object", None) and isinstance(properties, dict) and bool(properties) + ) + + +def _typed_dict_source(name: str, fields: _Fields, optional: bool) -> str: + """Class syntax, or the functional syntax when a key isn't an identifier.""" + total = ", total=False" if optional else "" + if all(key.isidentifier() and not keyword.iskeyword(key) for key, _ in fields): + body = "".join(f"\n {key}: {ty}" for key, ty in fields) + return f"class {name}(TypedDict{total}):{body}" + items = ", ".join(f"{key!r}: {ty!r}" for key, ty in fields) + return f"{name} = TypedDict({name!r}, {{{items}}}{total})" + + +def _referenced_defs(schema: Any, defs: dict[str, Any]) -> dict[str, Any]: + """The ``defs`` entries ``schema`` refers to, transitively.""" + found: dict[str, Any] = {} + + def visit(node: Any) -> None: + if isinstance(node, list): + for item in node: + visit(item) + elif isinstance(node, dict): + ref = node.get("$ref") + if isinstance(ref, str) and ref.startswith(_REF_PREFIXES): + name = ref.split("/")[-1] + if name in defs and name not in found: + found[name] = defs[name] + visit(defs[name]) + for value in node.values(): + visit(value) + + visit(schema) + return found + + +class _ModuleTypes: + """The ``TypedDict`` return types of one module's tools, shared by shape. + + Identical shapes get one class, so the catalog defines a shape that many + tools return once. A class is named after its schema (a ``$defs`` key or + ``title``), else the property holding it; when a different shape already + has that name, the parent's name is prefixed, then a number appended. An + untitled top-level object is the tool's own ``Response``, never shared. + """ + + def __init__(self, reserved: set[str]) -> None: + self.sources: dict[str, str] = {} + self._by_shape: dict[str, str] = {} + self._reserved = _TYPING_NAMES | reserved + + def uses(self, type_expr: str) -> tuple[str, ...]: + """Sources of the classes ``type_expr`` refers to, transitively, parents first.""" + names: dict[str, None] = {} + + def visit(text: str) -> None: + for word in re.findall(r"\w+", text): + if word in self.sources and word not in names: + names[word] = None + visit(self.sources[word]) + + visit(type_expr) + return tuple(self.sources[name] for name in names) + + def type_of( + self, + schema: Any, + *, + short: str, + parent: str, + defs: dict[str, Any], + depth: int = 0, + own: bool = False, + ) -> str: + """Convert a response schema to a type expression, defining its classes. + + ``short`` names an object found here; ``parent`` is the enclosing + class's preferred name, used to qualify ``short`` on a clash. ``own`` + marks the tool's top level, whose untitled object isn't shared. + """ + schema = _effective_schema(schema) + if depth >= _MAX_SCHEMA_DEPTH: + return "Any" + ty = schema.get("type") + ref = schema.get("$ref") + variants = schema.get("anyOf") or schema.get("oneOf") + extra = schema.get("additionalProperties") + title = schema.get("title") + + def child(sub: Any, short: str, own: bool = False) -> str: + return self.type_of( + sub, short=short, parent=parent, defs=defs, depth=depth + 1, own=own + ) + + if isinstance(ref, str) and ref.startswith(_REF_PREFIXES) and ref.split("/")[-1] in defs: + name = ref.split("/")[-1] + parts = [self._ref(name, defs[name], parent=parent, defs=defs, depth=depth)] + elif "enum" in schema: + return _schema_to_type(schema) + elif isinstance(variants, list) and variants: + parts = [child(v, short, own) for v in variants] + elif isinstance(ty, list): + rest = {k: v for k, v in schema.items() if k not in ("type", "nullable")} + parts = [child({**rest, "type": t}, short, own) for t in ty] + elif _is_object(schema): + candidates = [_pascal(title)] if isinstance(title, str) and title else [] + names = [*candidates, short, parent + short] + share = bool(candidates) or not own + parts = [self._object(schema, names, defs, depth, share=share)] + elif ty == "object" and isinstance(extra, dict) and extra: + parts = [f"dict[str, {child(extra, f'{short}Value')}]"] + elif ty == "array" and (isinstance(schema.get("items"), dict) or schema.get("prefixItems")): + # JSON arrays reach code as lists, so `prefixItems` slots join the item union. + items = schema.get("items") + slots = [ + *(schema.get("prefixItems") or []), + *([items] if isinstance(items, dict) else []), + ] + elements = list(dict.fromkeys(child(slot, f"{short}Item") for slot in slots)) + parts = [f"list[{'Any' if 'Any' in elements else ' | '.join(elements)}]"] + else: + return _schema_to_type(schema) + unique = list(dict.fromkeys(parts)) + if "Any" in unique: + return "Any" + if schema.get("nullable") and "None" not in unique: + unique.append("None") + return " | ".join(unique) + + def _claim(self, candidates: list[str]) -> str: + valid = [ + name + for name in candidates + if name.isidentifier() and not keyword.iskeyword(name) and name not in self._reserved + ] or ["Type"] + numbered = (f"{valid[0]}{n}" for n in itertools.count(2)) + name = next(name for name in itertools.chain(valid, numbered) if name not in self.sources) + self.sources[name] = "" # Taken; the source follows once the fields are rendered. + return name + + def _fields( + self, schema: dict[str, Any], *, parent: str, defs: dict[str, Any], depth: int + ) -> tuple[_Fields, bool]: + """Each property's type, and whether every key is optional (none required).""" + required = {key for key in schema.get("required") or [] if isinstance(key, str)} + fields = [] + for key, raw in schema["properties"].items(): + ty = self.type_of(raw, short=_pascal(key), parent=parent, defs=defs, depth=depth + 1) + fields.append((key, f"NotRequired[{ty}]" if required and key not in required else ty)) + return tuple(fields), not required + + def _object( + self, + schema: dict[str, Any], + candidates: list[str], + defs: dict[str, Any], + depth: int, + *, + share: bool, + ) -> str: + fields, optional = self._fields(schema, parent=candidates[0], defs=defs, depth=depth) + shape = repr((fields, optional)) + if share and shape in self._by_shape: + return self._by_shape[shape] + name = self._claim(candidates) + self.sources[name] = _typed_dict_source(name, fields, optional) + if share: + self._by_shape[shape] = name + return name + + def _ref(self, name: str, target: Any, *, parent: str, defs: dict[str, Any], depth: int) -> str: + """A ``$defs`` entry, named after its key. Claimed before its fields, so it may recurse.""" + target = _effective_schema(target) + if not _is_object(target): + return self.type_of( + target, short=_pascal(name), parent=parent, defs=defs, depth=depth + 1 + ) + key = [target, _referenced_defs(target, defs)] + shape = "$ref " + json.dumps(key, sort_keys=True, default=str) + if shape not in self._by_shape: + cls = self._by_shape[shape] = self._claim([_pascal(name), parent + _pascal(name)]) + fields, optional = self._fields(target, parent=cls, defs=defs, depth=depth) + self.sources[cls] = _typed_dict_source(cls, fields, optional) + self._by_shape.setdefault(repr((fields, optional)), cls) + return self._by_shape[shape] + + def _sanitise_param(raw: str) -> str: cleaned = re.sub(r"[^a-zA-Z0-9_]", "_", raw).strip("_") if not cleaned: @@ -560,6 +769,9 @@ class RenderedParam: class RenderedTool: """Structured tool ready for stub or catalog rendering. + A tool with exactly one required parameter takes it positionally or by + keyword; every other parameter is keyword-only. + Argument forwarding rules (Option A): - Required, no schema default: ``name: T``; always forwarded. @@ -579,10 +791,14 @@ class RenderedTool: namespace: str | None docstring: str params: tuple[RenderedParam, ...] + return_type: str + types: tuple[str, ...] + """Source of each ``TypedDict`` the return type uses, transitively, parents first.""" def signature_for(self, target: Target) -> str: - """Return the ``def name(...) -> Any:`` line for the requested target.""" - return f"def {self.attribute}({_render_params(self.params, target=target)}) -> Any:" + """Return the ``def name(...) -> T:`` line for the requested target.""" + params = _render_params(self.params, target=target) + return f"def {self.attribute}({params}) -> {self.return_type}:" @property def needs_missing_sentinel(self) -> bool: @@ -590,12 +806,13 @@ def needs_missing_sentinel(self) -> bool: def _render_params(params: tuple[RenderedParam, ...], *, target: Target) -> str: - """Render the keyword-only parameter list.""" - if not params: - return "" - pieces: list[str] = ["*"] + """Render the parameter list; a sole required parameter may be positional.""" + pieces: list[str] = [] optional_default = "_MISSING" if target == "stub" else "..." - for p in params: + positional = sum(p.is_required for p in params) == 1 + for i, p in enumerate(params): + if i == int(positional): + pieces.append("*") if p.is_required: if p.schema_default is None: pieces.append(f"{p.py_name}: {p.type_expr}") @@ -630,12 +847,31 @@ class StubFile: source: str -def render_tool(nt: NamespacedTool) -> RenderedTool: - """Build a ``RenderedTool`` for a normalised tool. +def render_tools(tools: list[NamespacedTool]) -> list[RenderedTool]: + """Build a ``RenderedTool`` for each tool, in order. Captures everything stub and catalog rendering need: signature parts, - formatted docstring, dotted path, namespace. + return type and its ``TypedDict``s, formatted docstring, dotted path, + namespace. Tools of one module share their ``TypedDict``s; names are + claimed in attribute order, so stubs and the catalog agree on them. """ + modules = { + ns: _ModuleTypes({t.attribute for t in tools if t.namespace == ns}) + for ns in {t.namespace for t in tools} + } + rendered = { + id(nt): _render_tool(nt, modules[nt.namespace]) + for nt in sorted(tools, key=lambda t: t.attribute) + } + return [rendered[id(nt)] for nt in tools] + + +def render_tool(nt: NamespacedTool) -> RenderedTool: + """Build a ``RenderedTool`` for a single tool; see ``render_tools``.""" + return render_tools([nt])[0] + + +def _render_tool(nt: NamespacedTool, types: _ModuleTypes) -> RenderedTool: declaration = nt.resolved.tool._get_declaration() schema: dict[str, Any] = _schema_dict_from_declaration(declaration) @@ -681,30 +917,48 @@ def render_tool(nt: NamespacedTool) -> RenderedTool: description = nt.resolved.tool.description docstring = _format_docstring(description=description, param_docs=param_docs) + tool = nt.resolved.tool + inner = tool._wrapped if isinstance(tool, ToolResultArtifactTool) else tool + response = output_schema(inner) or getattr(declaration, "response_json_schema", None) + return_type = "Any" + if isinstance(response, dict) and response: + 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) + return RenderedTool( attribute=nt.attribute, dotted_path=nt.dotted_path, namespace=nt.namespace, docstring=docstring, params=tuple(params), + return_type=return_type, + types=types.uses(return_type), ) def render_tool_source(rt: RenderedTool) -> str: """Render the on-disk Python stub source for a tool.""" sig = rt.signature_for("stub") + # `NotRequired` is 3.11+; annotations are never evaluated, so a sandbox on + # 3.10 only needs the import kept out of runtime. + not_required = any("NotRequired[" in t for t in rt.types) lines: list[str] = [ "# Generated by adk-code-mode. Do not edit.", "from __future__ import annotations", "", - "from typing import Any, Literal", + f"from typing import {'TYPE_CHECKING, ' if not_required else ''}Any, Literal, TypedDict", "", "from adk_code_mode_sandbox._rpc_client import call as _call", "", - "", ] + if not_required: + lines.extend(["if TYPE_CHECKING:", " from typing import NotRequired", ""]) + lines.append("") if rt.needs_missing_sentinel: lines.extend(["_MISSING = object()", "", ""]) + for source in rt.types: + lines.extend([source, "", ""]) lines.append(sig) lines.append(f" {rt.docstring}") @@ -784,10 +1038,8 @@ def render_tree(namespaced: list[NamespacedTool]) -> list[StubFile]: for nt in per_tool: grouped.setdefault(nt.namespace, []).append(nt) - for nt in per_tool: - ns = nt.namespace - sub = "" if ns is None else f"{ns}/" - rendered = render_tool(nt) + for nt, rendered in zip(per_tool, render_tools(per_tool)): + sub = "" if nt.namespace is None else f"{nt.namespace}/" files.append(StubFile(path=f"{sub}{nt.attribute}.py", source=render_tool_source(rendered))) for ns, tools in grouped.items(): @@ -813,5 +1065,6 @@ def render_tree(namespaced: list[NamespacedTool]) -> list[StubFile]: "render_root_init", "render_tool", "render_tool_source", + "render_tools", "render_tree", ] diff --git a/tests/test_catalog.py b/tests/test_catalog.py index 2327d96..e1221d3 100644 --- a/tests/test_catalog.py +++ b/tests/test_catalog.py @@ -80,7 +80,7 @@ def test_render_catalog_includes_top_level_tools_section() -> None: catalog = render_catalog(_build([(echo, None)])) assert "# tools" in catalog assert "from tools import echo" in catalog - assert "def echo(*, message: str) -> Any:" in catalog + assert "def echo(message: str) -> Any:" in catalog def test_render_catalog_keeps_a_shared_tool_name_in_both_namespaces() -> None: diff --git a/tests/test_dispatcher.py b/tests/test_dispatcher.py index 7f059b8..edaac9d 100644 --- a/tests/test_dispatcher.py +++ b/tests/test_dispatcher.py @@ -4,15 +4,19 @@ from __future__ import annotations import asyncio +import json from dataclasses import dataclass, field from typing import Any +from unittest.mock import MagicMock import pytest from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService from google.adk.plugins.plugin_manager import PluginManager from google.adk.sessions.session import Session from google.adk.tools.base_tool import BaseTool +from google.adk.tools.mcp_tool.mcp_tool import McpTool from google.genai import types as genai_types +from mcp.types import Tool as McpToolSpec from adk_code_mode.tool_failures import HTTPStatusError from adk_code_mode.tool_result_artifacts import ToolResultArtifactTool @@ -416,3 +420,52 @@ async def test_other_tools_returning_an_error_key_are_left_alone() -> None: result = await d.dispatch("lookup", {}) assert result.ok is True assert result.value == {"error": "Nothing matched"} + + +class _FakeMcpTool(McpTool): + def __init__(self, result: Any, *, output_schema: dict[str, Any] | None) -> None: + spec = McpToolSpec( + name="lookup", inputSchema={"type": "object"}, outputSchema=output_schema + ) + super().__init__(mcp_tool=spec, mcp_session_manager=MagicMock()) + self._result = result + + async def run_async(self, *, args: dict[str, Any], tool_context: Any) -> Any: + return self._result + + +_MCP_RESULT = { + "content": [{"type": "text", "text": '{"id": "b1"}'}], + "structuredContent": {"id": "b1"}, + "isError": False, +} + + +async def test_mcp_tool_with_output_schema_returns_structured_content() -> None: + seen: list[Any] = [] + + def after(tool: BaseTool, args: dict[str, Any], tool_context: Any, tool_response: Any) -> Any: + seen.append(tool_response) + return None + + tool = ToolResultArtifactTool(_FakeMcpTool(_MCP_RESULT, output_schema={"type": "object"})) + ctx = _make_ctx(_FakeAgent(canonical_after_tool_callbacks=[after])) + d = Dispatcher(invocation_context=ctx, registry=_registry(tool), execution_id="e1") # type: ignore[arg-type] + result = await d.dispatch("lookup", {}) + assert result.ok is True + assert result.value == {"id": "b1"} + assert seen == [_MCP_RESULT] # Callbacks still see ADK's result. + # The artifact holds what code got, so reloading it gives the same value. + [key] = await ctx.artifact_service.list_artifact_keys(app_name="a", user_id="u", session_id="s") + saved = await ctx.artifact_service.load_artifact( + app_name="a", user_id="u", session_id="s", filename=key + ) + assert saved is not None and saved.inline_data is not None + assert json.loads(saved.inline_data.data or b"") == {"id": "b1"} + + +async def test_mcp_tool_without_output_schema_returns_the_whole_result() -> None: + tool = _FakeMcpTool(_MCP_RESULT, output_schema=None) + d = Dispatcher(invocation_context=_make_ctx(), registry=_registry(tool), execution_id="e1") # type: ignore[arg-type] + result = await d.dispatch("lookup", {}) + assert result.value == _MCP_RESULT diff --git a/tests/test_stubs.py b/tests/test_stubs.py index 56c1ba9..08a80ca 100644 --- a/tests/test_stubs.py +++ b/tests/test_stubs.py @@ -3,8 +3,14 @@ # SPDX-License-Identifier: Apache-2.0 from __future__ import annotations +import warnings +from typing import Any +from unittest.mock import MagicMock + from google.adk.tools.base_tool import BaseTool +from google.adk.tools.mcp_tool.mcp_tool import McpTool from google.genai import types as genai_types +from mcp.types import Tool as McpToolSpec from adk_code_mode.tools import namespacing, stubs from adk_code_mode.tools.normaliser import ResolvedTool @@ -17,15 +23,18 @@ def __init__( *, description: str, schema: dict[str, object] | None = None, + response: dict[str, object] | None = None, ) -> None: super().__init__(name=name, description=description) self._schema = schema or {} + self._response = response def _get_declaration(self) -> genai_types.FunctionDeclaration | None: return genai_types.FunctionDeclaration( name=self.name, description=self.description, parameters_json_schema=self._schema, + response_json_schema=self._response, ) @@ -38,6 +47,18 @@ def _stub_source(nt: namespacing.NamespacedTool) -> str: return stubs.render_tool_source(stubs.render_tool(nt)) +def _load_stub(source: str) -> dict[str, Any]: + """Execute a stub with warnings as errors; its namespace records calls in ``calls``.""" + namespace: dict[str, Any] = {} + with warnings.catch_warnings(): + warnings.simplefilter("error") + exec(compile(source, "", "exec"), namespace) + calls: list[tuple[str, dict[str, Any]]] = [] + namespace["_call"] = lambda path, args: calls.append((path, args)) + namespace["calls"] = calls + return namespace + + def test_render_tool_emits_typed_signature_and_call() -> None: tool = _SchemaTool( "send_message", @@ -190,7 +211,7 @@ def test_render_tool_sanitises_keyword_parameter_names() -> None: ) ns = _build([(tool, None)]) source = _stub_source(ns[0]) - assert "def search(*, from_: str) -> Any:" in source + assert "def search(from_: str) -> Any:" in source assert "'from': from_," in source @@ -387,3 +408,301 @@ def test_render_tool_stops_recursing_on_self_referential_schema() -> None: source = _stub_source(ns[0]) assert "root: A tree node." in source assert source.count("child: dict[str, Any]") == stubs._MAX_SCHEMA_DEPTH + + +_NASTY = ( + r"Match ^\S+@\S+\.\S+$ or C:\new\table. " + + 'Quotes: " "" """ """" """"" and \'\'\'.\n' + + "Ends in a backslash \\" +) + + +def test_stubs_compile_without_warnings() -> None: + """Backslashes, quotes and regexes in any description must not warn or break the stub.""" + nasty: dict[str, object] = {"type": "string", "description": _NASTY, "pattern": _NASTY} + tools: list[tuple[BaseTool, object | None]] = [ + ( + _SchemaTool( + f"tool_{i}", + description=_NASTY, + schema={ + "type": "object", + "properties": { + "email": nasty, + "items": {"type": "array", "items": nasty, "description": _NASTY}, + "nested": { + "type": "object", + "properties": {"inner": nasty}, + "patternProperties": {_NASTY: nasty}, + "examples": [_NASTY], + }, + "choice": {"enum": [_NASTY, '"""']}, + }, + "required": ["email"][:i], + }, + response={"type": "object", "properties": {_NASTY: nasty, "class": nasty}}, + ), + None, + ) + for i in range(2) + ] + for file in stubs.render_tree(_build(tools)): + with warnings.catch_warnings(): + warnings.simplefilter("error") + compile(file.source, file.path, "exec") + namespace = _load_stub(_stub_source(_build(tools)[0])) + assert namespace["tool_0"].__doc__.startswith(_NASTY.splitlines()[0]) + + +def test_sole_required_parameter_is_positional() -> None: + tool = _SchemaTool( + "load_artifact", + description="Load.", + schema={ + "type": "object", + "properties": {"filename": {"type": "string"}, "version": {"type": "integer"}}, + "required": ["filename"], + }, + ) + source = _stub_source(_build([(tool, None)])[0]) + assert "def load_artifact(filename: str, *, version: int | None = _MISSING)" in source + namespace = _load_stub(source) + namespace["load_artifact"]("x", version=2) + namespace["load_artifact"](filename="y") + assert namespace["calls"] == [ + ("load_artifact", {"filename": "x", "version": 2}), + ("load_artifact", {"filename": "y"}), + ] + + +def test_several_required_parameters_stay_keyword_only() -> None: + tool = _SchemaTool( + "move", + description="Move.", + schema={ + "type": "object", + "properties": {"src": {"type": "string"}, "dst": {"type": "string"}}, + "required": ["src", "dst"], + }, + ) + assert "def move(*, dst: str, src: str) -> Any:" in _stub_source(_build([(tool, None)])[0]) + + +_OUTPUT_SCHEMA: dict[str, object] = { + "type": "object", + "properties": { + "bookings": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": {"type": "string"}, + "status": {"type": "string", "enum": ["open", "closed"]}, + "guest": { + "anyOf": [ + {"type": "object", "properties": {"name": {"type": "string"}}}, + {"type": "null"}, + ] + }, + "first-name": {"type": ["string", "null"]}, + }, + "required": ["id", "status"], + }, + }, + "totals": {"type": "object", "additionalProperties": {"type": "integer"}}, + "cursor": {"type": "string", "nullable": True}, + "raw": {}, + "pair": {"type": "array", "prefixItems": [{"type": "string"}, {"type": "integer"}]}, + }, +} + + +def test_mcp_output_schema_becomes_typed_dict_return_type() -> None: + """Read from the MCP tool itself, so ADK's JSON-schema feature flag isn't needed.""" + tool = McpTool( + mcp_tool=McpToolSpec( + name="get_bookings", + description="List bookings.", + inputSchema={"type": "object", "properties": {}}, + outputSchema=_OUTPUT_SCHEMA, + ), + mcp_session_manager=MagicMock(), + ) + rt = stubs.render_tool(_build([(tool, None)])[0]) + assert rt.signature_for("catalog") == "def get_bookings() -> GetBookingsResponse:" + assert rt.types == ( + "class GetBookingsResponse(TypedDict, total=False):\n" + " bookings: list[BookingsItem]\n" + " totals: dict[str, int]\n" + " cursor: str | None\n" + " raw: Any\n" + " pair: list[str | int]", + "BookingsItem = TypedDict('BookingsItem', " + "{'id': 'str', 'status': \"Literal['open', 'closed']\", " + "'guest': 'NotRequired[Guest | None]', " + "'first-name': 'NotRequired[str | None]'})", + "class Guest(TypedDict, total=False):\n name: str", + ) + source = stubs.render_tool_source(rt) + assert " from typing import NotRequired\n" in source + assert _load_stub(source)["BookingsItem"].__name__ == "BookingsItem" + + +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"}}} + task = _SchemaTool( + "get_task", + description="Task.", + response={"type": "object", "properties": {"assignee": user, "owner": other}}, + ) + project = _SchemaTool( + "get_project", + description="Project.", + response={"type": "object", "properties": {"owner": user, "assignee": other}}, + ) + project_rt, task_rt = stubs.render_tools(_build([(project, None), (task, None)])) + assert project_rt.types == ( + "class GetProjectResponse(TypedDict, total=False):\n" + " owner: Owner\n" + " assignee: Assignee", + "class Owner(TypedDict, total=False):\n gid: str", + "class Assignee(TypedDict, total=False):\n email: str", + ) + # Same shapes, so the same classes, though the properties holding them swapped. + assert task_rt.types == ( + "class GetTaskResponse(TypedDict, total=False):\n assignee: Owner\n owner: Assignee", + "class Owner(TypedDict, total=False):\n gid: str", + "class Assignee(TypedDict, total=False):\n email: str", + ) + + +def test_a_name_taken_by_another_shape_is_qualified_by_its_parent() -> None: + a = _SchemaTool( + "a", + description="A.", + response={"type": "object", "properties": {"data": {"properties": {"x": {}}}}}, + ) + b = _SchemaTool( + "b", + description="B.", + response={"type": "object", "properties": {"data": {"properties": {"y": {}}}}}, + ) + a_rt, b_rt = stubs.render_tools(_build([(a, None), (b, None)])) + assert a_rt.types[1] == "class Data(TypedDict, total=False):\n x: Any" + assert b_rt.types[1] == "class BResponseData(TypedDict, total=False):\n y: Any" + + +def test_an_untitled_top_level_type_belongs_to_its_tool() -> None: + shape: dict[str, object] = {"type": "object", "properties": {"id": {"type": "string"}}} + first, second = (_SchemaTool(n, description=".", response=shape) for n in ("first", "second")) + first_rt, second_rt = stubs.render_tools(_build([(first, None), (second, None)])) + assert first_rt.return_type == "FirstResponse" + assert second_rt.return_type == "SecondResponse" + # Items of a top-level array are shared like any nested object. + rows = [ + _SchemaTool(n, description=".", response={"type": "array", "items": shape}) + for n in ("rows_a", "rows_b") + ] + a_rt, b_rt = stubs.render_tools(_build([(rows[0], None), (rows[1], None)])) + assert a_rt.return_type == b_rt.return_type == "list[RowsAResponseItem]" + + +def test_defs_and_titles_name_classes_and_refs_may_recurse() -> None: + tool = _SchemaTool( + "get_team", + description="Team.", + response={ + "title": "Team", + "type": "object", + "properties": { + "lead": {"$ref": "#/$defs/User"}, + "members": {"type": "array", "items": {"$ref": "#/$defs/User"}}, + }, + "required": ["lead", "members"], + "$defs": { + "User": { + "type": "object", + "properties": { + "name": {"type": "string"}, + "manager": {"anyOf": [{"$ref": "#/$defs/User"}, {"type": "null"}]}, + }, + "required": ["name"], + } + }, + }, + ) + rt = stubs.render_tool(_build([(tool, None)])[0]) + assert rt.return_type == "Team" + assert rt.types == ( + "class Team(TypedDict):\n lead: User\n members: list[User]", + "class User(TypedDict):\n name: str\n manager: NotRequired[User | None]", + ) + _load_stub(stubs.render_tool_source(rt)) + + +def test_shared_refs_follow_each_schemas_own_defs() -> None: + def envelope(id_type: str) -> dict[str, object]: + return { + "type": "object", + "properties": {"envelope": {"$ref": "#/$defs/Envelope"}}, + "$defs": { + "Envelope": {"type": "object", "properties": {"item": {"$ref": "#/$defs/Item"}}}, + "Item": {"type": "object", "properties": {"id": {"type": id_type}}}, + }, + } + + a = _SchemaTool("a", description="A.", response=envelope("string")) + b = _SchemaTool("b", description="B.", response=envelope("integer")) + a_rt, b_rt = stubs.render_tools(_build([(a, None), (b, None)])) + assert a_rt.types[1:] == ( + "class Envelope(TypedDict, total=False):\n item: Item", + "class Item(TypedDict, total=False):\n id: str", + ) + assert b_rt.types[1:] == ( + "class BResponseEnvelope(TypedDict, total=False):\n item: BResponseEnvelopeItem", + "class BResponseEnvelopeItem(TypedDict, total=False):\n id: int", + ) + # The same `$defs` in another tool still share one class. + c = _SchemaTool("c", description="C.", response=envelope("string")) + a_rt, c_rt = stubs.render_tools(_build([(a, None), (c, None)])) + assert a_rt.types[1:] == c_rt.types[1:] + + +def test_class_names_avoid_stub_imports_and_tool_names() -> None: + tool = _SchemaTool( + "Any", + description="Clash.", + response={"title": "Literal", "type": "object", "properties": {"x": {}}}, + ) + rt = stubs.render_tool(_build([(tool, None)])[0]) + assert rt.return_type == "AnyResponse" + _load_stub(stubs.render_tool_source(rt)) + + +def test_return_type_without_objects_or_schema() -> None: + plain = _SchemaTool("count", description="Count.", response={"type": "integer"}) + rows = _SchemaTool( + "rows", + description="Rows.", + response={ + "type": "array", + "items": {"type": "object", "properties": {"id": {"type": "integer"}}}, + }, + ) + untyped = _SchemaTool("ping", description="Ping.") + pair = _SchemaTool( + "pair", + description="Pair.", + response={"type": "array", "prefixItems": [{"type": "integer"}] * 2, "items": False}, + ) + count_rt, pair_rt, ping_rt, rows_rt = ( + stubs.render_tool(nt) + for nt in _build([(plain, None), (pair, None), (untyped, None), (rows, None)]) + ) + assert count_rt.signature_for("stub") == "def count() -> int:" + assert pair_rt.signature_for("stub") == "def pair() -> list[int]:" # JSON gives a list. + assert ping_rt.signature_for("stub") == "def ping() -> Any:" + assert ping_rt.types == () + assert rows_rt.signature_for("stub") == "def rows() -> list[RowsResponseItem]:" + assert "TYPE_CHECKING" not in _stub_source(_build([(rows, None)])[0])