@assistant-ui/react-google-adk 0.0.25 → 0.0.26

package/src/adkToolApproval.test.ts

@@ -0,0 +1,345 @@
+import { describe, expect, it } from "vitest";
+import {
+  projectAdkToolApprovals,
+  toAdkConfirmationReply,
+  toAdkToolConfirmationReply,
+} from "./adkToolApproval";
+import type { AdkMessage } from "./types";
+
+const GATED_CALL = "adk-original-1";
+const CONFIRMATION_CALL = "adk-confirmation-1";
+
+const aiCall = (id: string, name: string, args = {}): AdkMessage => ({
+  id: `ai-${id}`,
+  type: "ai",
+  content: [],
+  tool_calls: [{ id, name, args }],
+});
+
+/**
+ * The shape ADK actually emits: the gated tool call, then a synthetic
+ * `adk_request_confirmation` call with an id of its own quoting the original.
+ */
+const requestedThread = (...tail: AdkMessage[]): AdkMessage[] => [
+  aiCall(GATED_CALL, "delete_file", { path: "/tmp/a" }),
+  aiCall(CONFIRMATION_CALL, "adk_request_confirmation", {
+    originalFunctionCall: { id: GATED_CALL, name: "delete_file" },
+    toolConfirmation: { hint: "Delete /tmp/a?" },
+  }),
+  ...tail,
+];
+
+const reply = (
+  content: string,
+  name = "adk_request_confirmation",
+): AdkMessage => ({
+  id: "tool-1",
+  type: "tool",
+  tool_call_id: CONFIRMATION_CALL,
+  name,
+  content,
+  status: "success",
+});
+
+/** The id the accumulator mints for a function response: `<eventId>:<part>`. */
+const eventReply = (
+  eventId: string,
+  partIndex: number,
+  toolCallId: string,
+  content: string,
+): AdkMessage => ({
+  id: `${eventId}:${partIndex}`,
+  type: "tool",
+  tool_call_id: toolCallId,
+  name: "adk_request_confirmation",
+  content,
+  status: "success",
+});
+
+describe("projectAdkToolApprovals", () => {
+  it.each([
+    ["pending", requestedThread(), { id: CONFIRMATION_CALL }],
+    [
+      "approved",
+      requestedThread(reply(JSON.stringify({ confirmed: true }))),
+      { id: CONFIRMATION_CALL, approved: true },
+    ],
+    [
+      "denied",
+      requestedThread(reply(JSON.stringify({ confirmed: false }))),
+      { id: CONFIRMATION_CALL, approved: false },
+    ],
+    [
+      "approved through the ADK client wrapper",
+      requestedThread(
+        reply(
+          JSON.stringify({ response: JSON.stringify({ confirmed: true }) }),
+        ),
+      ),
+      { id: CONFIRMATION_CALL, approved: true },
+    ],
+    [
+      "denied through the ADK client wrapper",
+      requestedThread(
+        reply(
+          JSON.stringify({ response: JSON.stringify({ confirmed: false }) }),
+        ),
+      ),
+      { id: CONFIRMATION_CALL, approved: false },
+    ],
+    // ADK reads a truthy response it cannot take a `confirmed` off — raw text,
+    // a scalar, an array — as a tool it resumes unconfirmed, so the gate is
+    // denied rather than left answerable.
+    [
+      "denied on a reply ADK resumes unconfirmed",
+      requestedThread(reply("not json")),
+      { id: CONFIRMATION_CALL, approved: false },
+    ],
+    [
+      "denied on a scalar reply",
+      requestedThread(reply("5")),
+      { id: CONFIRMATION_CALL, approved: false },
+    ],
+    [
+      "denied on a wrapped reply ADK parses to a scalar",
+      requestedThread(reply(JSON.stringify({ response: "5" }))),
+      { id: CONFIRMATION_CALL, approved: false },
+    ],
+    // A falsy response records no confirmation at all, so the gate stays open.
+    [
+      "still pending on a reply ADK records nothing for",
+      requestedThread(reply("false")),
+      { id: CONFIRMATION_CALL },
+    ],
+    [
+      "still pending on an empty reply",
+      requestedThread(reply("")),
+      { id: CONFIRMATION_CALL },
+    ],
+    // ADK parses the wrapped text without a `try`, so these raise.
+    [
+      "still pending on an unreadable wrapped reply",
+      requestedThread(reply(JSON.stringify({ response: "not json" }))),
+      { id: CONFIRMATION_CALL },
+    ],
+    [
+      "still pending on a wrapped reply ADK cannot stringify to JSON",
+      requestedThread(reply(JSON.stringify({ response: { confirmed: true } }))),
+      { id: CONFIRMATION_CALL },
+    ],
+    // `"response" in "x"` raises on a one-character response.
+    [
+      "still pending on a one-character reply",
+      requestedThread(reply("x")),
+      { id: CONFIRMATION_CALL },
+    ],
+    [
+      "still pending when some other tool answers",
+      requestedThread(
+        reply(JSON.stringify({ confirmed: true }), "delete_file"),
+      ),
+      { id: CONFIRMATION_CALL },
+    ],
+  ])(
+    "gates the confirmation and the call it gates: %s",
+    (_name, messages, expected) => {
+      const { approvals, key } = projectAdkToolApprovals(messages);
+      // Both calls are in the transcript, so both would otherwise render an
+      // approval control; the gated one carries the answerable synthetic id.
+      expect([...approvals.keys()]).toEqual([CONFIRMATION_CALL, GATED_CALL]);
+      expect(approvals.get(CONFIRMATION_CALL)).toEqual(expected);
+      expect(approvals.get(GATED_CALL)).toEqual(expected);
+      expect(key).not.toBe("");
+    },
+  );
+
+  /**
+   * ADK parses every function response in an event before running any tool, so
+   * the unreadable reply aborts its whole event and the readable sibling never
+   * executes either. Both gates stay answerable.
+   */
+  const UNREADABLE = JSON.stringify({ response: "not json" });
+
+  it("keeps every confirmation from one event pending when one reply is unreadable", () => {
+    const { approvals } = projectAdkToolApprovals([
+      aiCall("conf-a", "adk_request_confirmation"),
+      aiCall("conf-b", "adk_request_confirmation"),
+      eventReply("evt-1", 0, "conf-a", JSON.stringify({ confirmed: true })),
+      eventReply("evt-1", 1, "conf-b", UNREADABLE),
+    ]);
+
+    expect([...approvals.values()]).toEqual([
+      { id: "conf-a" },
+      { id: "conf-b" },
+    ]);
+  });
+
+  it("settles a readable reply when the unreadable one came from another event", () => {
+    const { approvals } = projectAdkToolApprovals([
+      aiCall("conf-a", "adk_request_confirmation"),
+      aiCall("conf-b", "adk_request_confirmation"),
+      eventReply("evt-1", 0, "conf-a", JSON.stringify({ confirmed: true })),
+      eventReply("evt-2", 0, "conf-b", UNREADABLE),
+    ]);
+
+    expect([...approvals.values()]).toEqual([
+      { id: "conf-a", approved: true },
+      { id: "conf-b" },
+    ]);
+  });
+
+  /**
+   * A reply ADK records nothing for does not raise, so its siblings in the same
+   * event are parsed and resumed as usual and keep their decisions.
+   */
+  it("settles a sibling when the unrecorded reply came from the same event", () => {
+    const { approvals } = projectAdkToolApprovals([
+      aiCall("conf-a", "adk_request_confirmation"),
+      aiCall("conf-b", "adk_request_confirmation"),
+      eventReply("evt-1", 0, "conf-a", JSON.stringify({ confirmed: true })),
+      eventReply("evt-1", 1, "conf-b", "false"),
+    ]);
+
+    expect([...approvals.values()]).toEqual([
+      { id: "conf-a", approved: true },
+      { id: "conf-b" },
+    ]);
+  });
+
+  /**
+   * ADK Python spells the confirmation args in snake_case, which the event
+   * accumulator already reads both ways.
+   */
+  it("gates the call named by a snake_case confirmation request", () => {
+    const { approvals } = projectAdkToolApprovals([
+      aiCall(GATED_CALL, "delete_file", { path: "/tmp/a" }),
+      aiCall(CONFIRMATION_CALL, "adk_request_confirmation", {
+        original_function_call: { id: GATED_CALL, name: "delete_file" },
+        tool_confirmation: { hint: "Delete /tmp/a?" },
+      }),
+    ]);
+
+    expect([...approvals.keys()]).toEqual([CONFIRMATION_CALL, GATED_CALL]);
+    expect(approvals.get(GATED_CALL)).toEqual({ id: CONFIRMATION_CALL });
+  });
+
+  it("gates nothing when no confirmation was requested", () => {
+    const { approvals, key } = projectAdkToolApprovals([
+      aiCall("tc-9", "search"),
+    ]);
+    expect(approvals.size).toBe(0);
+    expect(key).toBe("");
+  });
+});
+
+describe("toAdkToolConfirmationReply", () => {
+  const pending = projectAdkToolApprovals(requestedThread()).approvals;
+
+  it.each([
+    [true, JSON.stringify({ confirmed: true })],
+    [false, JSON.stringify({ confirmed: false })],
+  ])(
+    "serializes approved=%s as an ADK confirmation reply",
+    (approved, content) => {
+      expect(
+        toAdkToolConfirmationReply(
+          { approvalId: CONFIRMATION_CALL, approved, reason: "ignored" },
+          pending,
+        ),
+      ).toMatchObject({
+        type: "tool",
+        tool_call_id: CONFIRMATION_CALL,
+        name: "adk_request_confirmation",
+        content,
+        status: "success",
+      });
+    },
+  );
+
+  it.each([
+    ["unknown", "no-such-id", pending],
+    [
+      "already settled",
+      CONFIRMATION_CALL,
+      projectAdkToolApprovals(
+        requestedThread(reply(JSON.stringify({ confirmed: true }))),
+      ).approvals,
+    ],
+  ])("rejects an approval id that is %s", (_name, approvalId, approvals) => {
+    expect(() =>
+      toAdkToolConfirmationReply({ approvalId, approved: true }, approvals),
+    ).toThrow("No pending ADK tool confirmation");
+  });
+
+  it("still answers a gate whose earlier reply was unreadable", () => {
+    const approvals = projectAdkToolApprovals(
+      requestedThread(reply(JSON.stringify({ response: "not json" }))),
+    ).approvals;
+
+    expect(
+      toAdkToolConfirmationReply(
+        { approvalId: CONFIRMATION_CALL, approved: true },
+        approvals,
+      ),
+    ).toMatchObject({
+      tool_call_id: CONFIRMATION_CALL,
+      content: JSON.stringify({ confirmed: true }),
+    });
+  });
+});
+
+describe("toAdkConfirmationReply", () => {
+  it.each([
+    [undefined, JSON.stringify({ confirmed: true })],
+    [
+      { note: "ok" },
+      JSON.stringify({ confirmed: true, payload: { note: "ok" } }),
+    ],
+  ])(
+    "preserves useAdkConfirmTool payload serialization: %s",
+    (payload, content) => {
+      expect(toAdkConfirmationReply(CONFIRMATION_CALL, true, payload)).toEqual({
+        id: expect.any(String),
+        type: "tool",
+        tool_call_id: CONFIRMATION_CALL,
+        name: "adk_request_confirmation",
+        content,
+        status: "success",
+      });
+    },
+  );
+});
+
+describe("projectAdkToolApprovals gated call", () => {
+  it("answers through the gated call with the synthetic id", () => {
+    // ADK yields the gated call before the confirmation request, so it is in
+    // the transcript too; answering from its control must still quote the id
+    // ADK is waiting on.
+    const { approvals } = projectAdkToolApprovals(requestedThread());
+
+    const gated = approvals.get(GATED_CALL);
+    expect(gated).toEqual({ id: CONFIRMATION_CALL });
+    expect(
+      toAdkToolConfirmationReply(
+        { approvalId: gated!.id, approved: true },
+        approvals,
+      ),
+    ).toMatchObject({
+      tool_call_id: CONFIRMATION_CALL,
+      name: "adk_request_confirmation",
+      content: JSON.stringify({ confirmed: true }),
+    });
+  });
+
+  it("leaves a confirmation whose original call has no id ungated", () => {
+    const messages: AdkMessage[] = [
+      aiCall(CONFIRMATION_CALL, "adk_request_confirmation", {
+        toolConfirmation: { hint: "Delete /tmp/a?" },
+      }),
+    ];
+
+    expect([...projectAdkToolApprovals(messages).approvals.keys()]).toEqual([
+      CONFIRMATION_CALL,
+    ]);
+  });
+});

package/src/adkToolApproval.ts

@@ -0,0 +1,215 @@
+import type {
+  RespondToToolApprovalOptions,
+  ToolCallMessagePart,
+} from "@assistant-ui/core";
+import type { ReadonlyJSONValue } from "assistant-stream/utils";
+import { v4 as uuidv4 } from "uuid";
+import type { AdkMessage } from "./types";
+
+export type AdkToolApproval = NonNullable<ToolCallMessagePart["approval"]>;
+
+export const ADK_REQUEST_CONFIRMATION = "adk_request_confirmation";
+
+const parseJson = (raw: string): unknown => {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+};
+
+type AdkConfirmationRead = {
+  /**
+   * False only where ADK raises reading the reply, which aborts every function
+   * response in the same event rather than denying this one.
+   */
+  readable: boolean;
+  /** Undefined where ADK records no confirmation and the gate stays open. */
+  confirmed: boolean | undefined;
+};
+
+/**
+ * The value the transport puts on `functionResponse.response`: the reply
+ * content parsed, or the raw text where it is not JSON.
+ */
+const wireResponseOf = (content: string): unknown => {
+  const parsed = parseJson(content);
+  return parsed === undefined ? content : parsed;
+};
+
+/**
+ * Mirrors ADK's own reading of a confirmation reply, whose three outcomes the
+ * gate has to distinguish. A falsy response records nothing, so the gate stays
+ * open and its siblings are untouched. Otherwise ADK either unwraps its client
+ * wrapper — a lone `response` key whose value it parses as JSON text — or reads
+ * `confirmed` off the response directly, and resumes the tool unconfirmed
+ * (a denial) for anything that is not explicitly `true`; a bare string, number,
+ * or array is such a denial, not an unreadable reply. Only where that reading
+ * raises is the reply unreadable, and the raise is uncaught in ADK, so the
+ * whole event it belongs to is abandoned.
+ */
+const readConfirmation = (content: unknown): AdkConfirmationRead => {
+  if (typeof content !== "string")
+    return { readable: false, confirmed: undefined };
+  const response = wireResponseOf(content);
+  try {
+    if (!response) return { readable: true, confirmed: undefined };
+    const record = response as Record<string, unknown>;
+    const decide = (value: unknown) =>
+      typeof value === "object" &&
+      value !== null &&
+      (value as { confirmed?: unknown }).confirmed === true;
+    // `in` raises on a primitive response, as ADK's own wrapper test does.
+    if (Object.keys(record).length === 1 && "response" in record) {
+      const inner = parseJson(String(record.response));
+      // ADK parses the wrapped text without a `try`, so it raises here.
+      if (inner === undefined) return { readable: false, confirmed: undefined };
+      if (!inner) return { readable: true, confirmed: undefined };
+      return { readable: true, confirmed: decide(inner) };
+    }
+    return { readable: true, confirmed: decide(record) };
+  } catch {
+    return { readable: false, confirmed: undefined };
+  }
+};
+
+/**
+ * ADK's confirmation processor parses every function response in an event
+ * before running any tool, so one unreadable reply aborts the event and none of
+ * its siblings execute. The accumulator mints a tool message id of
+ * `<eventId>:<partIndex>` per response, so that prefix is the batch ADK either
+ * runs whole or not at all; a locally minted reply carries a bare uuid and is
+ * its own batch.
+ */
+const sourceEventOf = (toolMessageId: string): string =>
+  toolMessageId.replace(/:\d+$/, "");
+
+/**
+ * ADK builds the confirmation request around the call it gates, carrying that
+ * call verbatim in `originalFunctionCall` — spelled `original_function_call` by
+ * ADK Python, which the accumulator reads the same way.
+ */
+const gatedCallIdOf = (args: unknown): string | undefined => {
+  if (typeof args !== "object" || args === null) return undefined;
+  const record = args as {
+    originalFunctionCall?: unknown;
+    original_function_call?: unknown;
+  };
+  const original = record.originalFunctionCall ?? record.original_function_call;
+  if (typeof original !== "object" || original === null) return undefined;
+  const id = (original as { id?: unknown }).id;
+  return typeof id === "string" && id.length > 0 ? id : undefined;
+};
+
+export type AdkToolApprovalProjection = {
+  approvals: ReadonlyMap<string, AdkToolApproval>;
+  /**
+   * Identity of the decision state. Core re-converts a cached message object
+   * only when the converter callback changes, so the callback is rebuilt when
+   * this key moves rather than on every render.
+   */
+  key: string;
+};
+
+/**
+ * ADK requests a confirmation by emitting a synthetic `adk_request_confirmation`
+ * tool call carrying a fresh id, and resumes only when a reply quotes that id.
+ * The gated tool's own id is never answerable, so every approval carries the
+ * synthetic id — but ADK yields the gated call to the client first, in its own
+ * event, so both calls sit result-less in the transcript and both would render
+ * an approval control. The gated call is therefore mapped to the same approval
+ * rather than left bare, which would let it answer by writing a tool result the
+ * agent never produced.
+ */
+export const projectAdkToolApprovals = (
+  messages: readonly AdkMessage[],
+): AdkToolApprovalProjection => {
+  const batches = new Map<
+    string,
+    { readable: boolean; entries: [string, boolean | undefined][] }
+  >();
+  for (const message of messages) {
+    if (message.type !== "tool") continue;
+    if (message.name !== ADK_REQUEST_CONFIRMATION) continue;
+    const key = sourceEventOf(message.id);
+    let batch = batches.get(key);
+    if (batch === undefined) {
+      batch = { readable: true, entries: [] };
+      batches.set(key, batch);
+    }
+    const { readable, confirmed } = readConfirmation(message.content);
+    if (!readable) batch.readable = false;
+    batch.entries.push([message.tool_call_id, confirmed]);
+  }
+
+  const replies = new Map<string, boolean>();
+  for (const batch of batches.values()) {
+    for (const [toolCallId, confirmed] of batch.entries) {
+      if (batch.readable && confirmed !== undefined)
+        replies.set(toolCallId, confirmed);
+      else replies.delete(toolCallId);
+    }
+  }
+
+  const approvals = new Map<string, AdkToolApproval>();
+  for (const message of messages) {
+    if (message.type !== "ai") continue;
+    for (const call of message.tool_calls ?? []) {
+      if (call.name !== ADK_REQUEST_CONFIRMATION) continue;
+      const approved = replies.get(call.id);
+      const approval: AdkToolApproval = {
+        id: call.id,
+        ...(approved !== undefined && { approved }),
+      };
+      approvals.set(call.id, approval);
+      // ADK yields the gated call in its own event before the confirmation is
+      // requested, so that call is also in the transcript, result-less, and
+      // inherits the message's `requires-action` status. Left ungated it
+      // renders a second approval control with no approval behind it, which
+      // answers by writing a tool result the agent never produced. The same
+      // approval carries the synthetic id, so answering either one replies to
+      // the gate ADK is actually waiting on.
+      const gatedId = gatedCallIdOf(call.args);
+      if (gatedId !== undefined) approvals.set(gatedId, approval);
+    }
+  }
+
+  return {
+    approvals,
+    key: approvals.size === 0 ? "" : JSON.stringify([...approvals]),
+  };
+};
+
+export const toAdkConfirmationReply = (
+  toolCallId: string,
+  confirmed: boolean,
+  payload?: ReadonlyJSONValue,
+): AdkMessage & { type: "tool" } => ({
+  id: uuidv4(),
+  type: "tool",
+  tool_call_id: toolCallId,
+  name: ADK_REQUEST_CONFIRMATION,
+  content: JSON.stringify({
+    confirmed,
+    ...(payload != null && { payload }),
+  }),
+  status: "success",
+});
+
+/**
+ * ADK confirmations are a plain confirm/reject pair, so no option or reason
+ * from core has a field to land in. An id that is not an open gate would send a
+ * reply ADK silently ignores, so it throws instead.
+ */
+export const toAdkToolConfirmationReply = (
+  { approvalId, approved }: RespondToToolApprovalOptions,
+  approvals: ReadonlyMap<string, AdkToolApproval>,
+): AdkMessage & { type: "tool" } => {
+  const approval = approvals.get(approvalId);
+  if (approval === undefined || approval.approved !== undefined)
+    throw new Error(
+      `No pending ADK tool confirmation for approval id "${approvalId}"`,
+    );
+
+  return toAdkConfirmationReply(approvalId, approved);
+};

package/src/convertAdkMessages.ts

@@ -2,6 +2,10 @@
 
 import type { ToolCallMessagePart } from "@assistant-ui/core";
 import type { useExternalMessageConverter } from "@assistant-ui/core/react";
+import {
+  ADK_REQUEST_CONFIRMATION,
+  type AdkToolApproval,
+} from "./adkToolApproval";
 import type { AdkMessage, AdkMessageContentPart } from "./types";
 
 type ContentPart =
@@ -81,50 +85,75 @@ const contentToParts = (
     .filter((p): p is NonNullable<typeof p> => p !== null);
 };
 
-export const convertAdkMessage: useExternalMessageConverter.Callback<
-  AdkMessage
-> = (message) => {
-  switch (message.type) {
-    case "human":
-      return {
-        role: "user",
-        id: message.id,
-        content: contentToParts(message.content, "user"),
-      };
+const EMPTY_APPROVALS: ReadonlyMap<string, AdkToolApproval> = new Map();
 
-    case "ai": {
-      const toolCallParts: ToolCallMessagePart[] =
-        message.tool_calls?.map((tc) => ({
-          type: "tool-call",
-          toolCallId: tc.id,
-          toolName: tc.name,
-          args: tc.args,
-          argsText: tc.argsText ?? JSON.stringify(tc.args),
-        })) ?? [];
+export const createAdkMessageConverter =
+  (
+    approvals: ReadonlyMap<string, AdkToolApproval>,
+  ): useExternalMessageConverter.Callback<AdkMessage> =>
+  (message) => {
+    switch (message.type) {
+      case "human":
+        return {
+          role: "user",
+          id: message.id,
+          content: contentToParts(message.content, "user"),
+        };
 
-      return {
-        role: "assistant",
-        id: message.id,
-        content: [
-          ...contentToParts(message.content, "assistant"),
-          ...toolCallParts,
-        ],
-        ...(message.status && { status: message.status }),
-        ...(message.author && {
-          metadata: {
-            custom: { author: message.author, branch: message.branch },
-          },
-        }),
-      };
+      case "ai": {
+        const toolCallParts: ToolCallMessagePart[] =
+          message.tool_calls?.map((tc) => {
+            const approval = approvals.get(tc.id);
+            return {
+              type: "tool-call",
+              toolCallId: tc.id,
+              toolName: tc.name,
+              args: tc.args,
+              argsText: tc.argsText ?? JSON.stringify(tc.args),
+              ...(approval && { approval }),
+            };
+          }) ?? [];
+
+        return {
+          role: "assistant",
+          id: message.id,
+          content: [
+            ...contentToParts(message.content, "assistant"),
+            ...toolCallParts,
+          ],
+          ...(message.status && { status: message.status }),
+          ...(message.author && {
+            metadata: {
+              custom: { author: message.author, branch: message.branch },
+            },
+          }),
+        };
+      }
+
+      case "tool": {
+        // A confirmation reply ADK could not read leaves its gate undecided.
+        // Any result settles the tool call in core, so the reply is dropped
+        // here to keep the gate requiring action and answerable again. Only a
+        // reply to the confirmation itself is dropped: the gated call carries
+        // the same approval, and its own result is the agent's real output.
+        const approval = approvals.get(message.tool_call_id);
+        if (
+          message.name === ADK_REQUEST_CONFIRMATION &&
+          approval !== undefined &&
+          approval.approved === undefined
+        )
+          return [];
+
+        return {
+          role: "tool",
+          toolCallId: message.tool_call_id,
+          toolName: message.name,
+          result: message.content,
+          isError: message.status === "error",
+        };
+      }
     }
+  };
 
-    case "tool":
-      return {
-        role: "tool",
-        toolCallId: message.tool_call_id,
-        toolName: message.name,
-        result: message.content,
-        isError: message.status === "error",
-      };
-  }
-};
+export const convertAdkMessage: useExternalMessageConverter.Callback<AdkMessage> =
+  createAdkMessageConverter(EMPTY_APPROVALS);