feat(antigravity): capture client-side tool outcomes for a function_response

A client-side tool's outcome never reaches the trajectory, so an ADK caller
saw the function_call and never the function_response. This adds the buffer
that captures the outcome from the SDK's post-tool-call and on-tool-error
hooks, and the converter that drains it into a matching function_response
event. Nothing calls it yet.

Co-authored-by: Haran Rajkumar <haranrk@google.com>
PiperOrigin-RevId: 967595598

Author: haranrk

src/google/adk/labs/antigravity/_antigravity_agent.py

@@ -66,32 +66,6 @@ def _derive_conversation_id(session_id: str, agent_name: str) -> str:
   return hashlib.sha256(f'{session_id}/{agent_name}'.encode()).hexdigest()
 
 
-def _final_model_text(event: Event, author: str) -> str | None:
-  """Returns an event's user-visible model text, or None if it carries none.
-
-  Partials, other authors, and thought/function parts do not count.
-
-  Args:
-    event: The event to inspect.
-    author: The agent name whose events count as model output.
-
-  Returns:
-    The concatenated user-visible text, or None if the event carries none.
-  """
-  if event.partial or event.author != author or not event.content:
-    return None
-  parts = event.content.parts or []
-  chunks = [
-      part.text
-      for part in parts
-      if part.text
-      and not part.thought
-      and not part.function_call
-      and not part.function_response
-  ]
-  return ''.join(chunks) if chunks else None
-
-
 class AntigravityAgent(BaseAgent):
   """Runs a Google Antigravity SDK agent as an ADK agent.
 
@@ -275,7 +249,8 @@ async def _run_impl(
         ctx.event_author = event.author
       if not event.node_info.path and event.author == self.name:
         event.node_info.path = ctx.node_path
-      if (text := _final_model_text(event, self.name)) is not None:
+      text = _event_converter.final_model_text(event, self.name)
+      if text is not None:
         last_text = text
       yield event
 

src/google/adk/labs/antigravity/_event_converter.py

@@ -18,22 +18,30 @@
 independently testable.
 
 Scope: model text (final and, in SSE streaming mode, partial thinking/text
-deltas), function calls, and function responses.
+deltas), function calls, function responses, and ``final_model_text`` for
+reading an event's text back out.
+
+A client-side tool's result never reaches the trajectory; it arrives through
+the post-tool-call hook instead (see ``_tool_result_capture``), which is why
+``drain_tool_results`` is also called once at the end of a turn.
 
 TODO: Surface SYSTEM_MESSAGE steps (emitted on turn cancellation) as ADK
 events; they are currently dropped.
 """
 
 from __future__ import annotations
 
+import json
 from typing import TYPE_CHECKING
 
 from google.antigravity import types as sdk_types
 from google.genai import types as genai_types
+from pydantic import JsonValue
 
 from ...events.event import Event
 
 if TYPE_CHECKING:
+  from . import _tool_result_capture
   from ...agents.invocation_context import InvocationContext
 
 
@@ -162,11 +170,62 @@ def _convert_function_calls(
   return events
 
 
+def _function_response_event(
+    *,
+    ctx: InvocationContext,
+    name: str,
+    call_id: str,
+    response: dict[str, JsonValue],
+) -> Event:
+  """Builds the ADK event recording one tool's answer to one call."""
+  return Event(
+      invocation_id=ctx.invocation_id,
+      # Author is the tool name so session history attributes the response to
+      # the tool, mirroring ADK's own function-response events.
+      author=name,
+      branch=ctx.branch,
+      content=genai_types.Content(
+          role='user',
+          parts=[
+              genai_types.Part(
+                  function_response=genai_types.FunctionResponse(
+                      name=name,
+                      id=call_id,
+                      response=response,
+                  )
+              )
+          ],
+      ),
+  )
+
+
+def _buffered_result_payload(
+    result: _tool_result_capture.ToolResult,
+) -> dict[str, JsonValue]:
+  """Returns the ``FunctionResponse.response`` dict for one captured result."""
+  if result.error:
+    return {'error': result.error}
+
+  # The harness hands back a client tool's value as the JSON string
+  # ``json.dumps(tool_result_to_dict(...))``, so it usually needs unwrapping.
+  value = result.result
+  if isinstance(value, str):
+    try:
+      value = json.loads(value)
+    except ValueError:
+      pass  # Not JSON; the raw text is wrapped below rather than raising.
+  if isinstance(value, dict):
+    return value
+  return {'result': 'success' if value is None else value}
+
+
 def _convert_function_responses(
     step: sdk_types.Step,
     *,
     ctx: InvocationContext,
+    seen_tool_calls: set[str],
     seen_tool_results: set[str],
+    tool_results: _tool_result_capture.ToolResultBuffer | None = None,
 ) -> list[Event]:
   """Converts completed tool-execution steps into function-response events."""
   is_tool_response = (
@@ -177,16 +236,38 @@ def _convert_function_responses(
           sdk_types.StepStatus.ERROR,
       )
   )
-  if not is_tool_response or not step.tool_calls:
+  if not is_tool_response:
     return []
 
+  # A client-side tool: the SDK blanks its ``tool_calls`` and ``Step`` has no
+  # field for a result, so the step names nothing and holds nothing.
+  if not step.tool_calls:
+    return drain_tool_results(
+        ctx=ctx,
+        seen_tool_calls=seen_tool_calls,
+        seen_tool_results=seen_tool_results,
+        tool_results=tool_results,
+    )
+
+  # The hook fires for these tools too, but its copy is keyed by an id this
+  # side never sees: the SDK gives a built-in's ``ToolCall.id`` the step id
+  # ``f'{trajectory_id}:{step_index}'``, while the hook is handed the model's
+  # own call id, or a SHA-256 of that step id when there is none
+  # (``localharness/tool_metadata.go``, ``ResolveStepCallID``). That copy
+  # therefore cannot be dropped by id here -- and need not be: the same
+  # mismatch keeps it out of ``drain_tool_results``, which only takes ids in
+  # ``seen_tool_calls``. The turn clears the buffer at its end.
+  # ``ToolResult.step_id`` would be the key that does match -- at head the SDK
+  # already sets it to that same ``f'{trajectory_id}:{step_index}'`` -- but the
+  # SDK vendored here predates the field.
   events = []
   for call in step.tool_calls:
     call_id = _build_tool_call_id(step, call)
     if call_id in seen_tool_results:
       continue
     seen_tool_results.add(call_id)
 
+    response: dict[str, JsonValue]
     if step.status == sdk_types.StepStatus.ERROR:
       response = {
           'error': (
@@ -198,24 +279,49 @@ def _convert_function_responses(
       response = {'result': step.content or 'success'}
 
     events.append(
-        Event(
-            invocation_id=ctx.invocation_id,
-            # Author is the tool name so session history attributes the
-            # response to the tool, mirroring ADK's own function-response events.
-            author=call.name,
-            branch=ctx.branch,
-            content=genai_types.Content(
-                role='user',
-                parts=[
-                    genai_types.Part(
-                        function_response=genai_types.FunctionResponse(
-                            name=call.name,
-                            id=call_id,
-                            response=response,
-                        )
-                    )
-                ],
-            ),
+        _function_response_event(
+            ctx=ctx, name=call.name, call_id=call_id, response=response
+        )
+    )
+  return events
+
+
+def drain_tool_results(
+    *,
+    ctx: InvocationContext,
+    seen_tool_calls: set[str],
+    seen_tool_results: set[str],
+    tool_results: _tool_result_capture.ToolResultBuffer | None = None,
+) -> list[Event]:
+  """Answers emitted calls that have a captured outcome and no response yet.
+
+  Args:
+    ctx: The active invocation context, used for event correlation fields.
+    seen_tool_calls: Ids of tool calls already emitted. Read to decide what may
+      be answered; not mutated.
+    seen_tool_results: Ids of tool results already emitted, mutated in place to
+      record the ones answered here.
+    tool_results: This conversation's client-tool outcomes, or None when no
+      capture hook was registered, in which case nothing is answered. Drained of
+      every id this call answers.
+
+  Returns:
+    One function-response event per answered call, in the order the tools
+    finished in. Empty when nothing is owed a response.
+  """
+  if tool_results is None:
+    return []
+
+  events = []
+  # A response may not precede the call it answers, hence ``seen_tool_calls``.
+  for call_id, result in tool_results.take(seen_tool_calls - seen_tool_results):
+    seen_tool_results.add(call_id)
+    events.append(
+        _function_response_event(
+            ctx=ctx,
+            name=result.name,
+            call_id=call_id,
+            response=_buffered_result_payload(result),
         )
     )
   return events
@@ -228,6 +334,7 @@ def convert_step_to_events(
     author: str,
     seen_tool_calls: set[str],
     seen_tool_results: set[str],
+    tool_results: _tool_result_capture.ToolResultBuffer | None = None,
     streaming: bool = False,
 ) -> list[Event]:
   """Translates one Antigravity ``Step`` into the ADK events it maps to.
@@ -240,6 +347,8 @@ def convert_step_to_events(
       deduplicate calls repeated across step transitions.
     seen_tool_results: Ids of tool results already emitted, mutated in place to
       deduplicate results repeated across step transitions.
+    tool_results: This conversation's client-tool results, or None when no
+      capture hook was registered.
     streaming: When True (SSE mode), incremental thinking/text deltas are also
       emitted as ``partial=True`` events. When False, only final events are
       emitted.
@@ -259,6 +368,36 @@ def convert_step_to_events(
           step, ctx=ctx, author=author, seen_tool_calls=seen_tool_calls
       ),
       *_convert_function_responses(
-          step, ctx=ctx, seen_tool_results=seen_tool_results
+          step,
+          ctx=ctx,
+          seen_tool_calls=seen_tool_calls,
+          seen_tool_results=seen_tool_results,
+          tool_results=tool_results,
       ),
   ]
+
+
+def final_model_text(event: Event, author: str) -> str | None:
+  """Returns an event's user-visible model text, or None if it carries none.
+
+  Partials, other authors, and thought/function parts do not count.
+
+  Args:
+    event: The event to inspect.
+    author: The agent name whose events count as model output.
+
+  Returns:
+    The concatenated user-visible text, or None if the event carries none.
+  """
+  if event.partial or event.author != author or not event.content:
+    return None
+  parts = event.content.parts or []
+  chunks = [
+      part.text
+      for part in parts
+      if part.text
+      and not part.thought
+      and not part.function_call
+      and not part.function_response
+  ]
+  return ''.join(chunks) if chunks else None