@assistant-ui/react-ag-ui 0.0.56 → 0.0.58

package/src/runtime/adapter/subscriber.ts

@@ -34,6 +34,9 @@ type Subscriber = {
   onMessagesSnapshotEvent?: (payload: { event: unknown }) => void;
   onCustomEvent?: (payload: { event: unknown }) => void;
   onRawEvent?: (payload: { event: unknown }) => void;
+  onSubagentStartedEvent?: (payload: { event: unknown }) => void;
+  onSubagentFinishedEvent?: (payload: { event: unknown }) => void;
+  onSubagentErrorEvent?: (payload: { event: unknown }) => void;
   onRunFinishedEvent?: (payload: { event: unknown }) => void;
   onRunErrorEvent?: (payload: { event: unknown }) => void;
   onRunFinalized?: () => void;
@@ -97,7 +100,7 @@ export const createAgUiSubscriber = (
         // Typed handlers will receive this via the discriminated callbacks; avoid duplicates.
         return;
       }
-      const parsed = parseAgUiEvent(event);
+      const parsed = parseAgUiEvent(event, logger ? { logger } : undefined);
       if (parsed) dispatch(parsed);
     },
     onTextMessageStartEvent: ({ event }) =>
@@ -146,6 +149,12 @@ export const createAgUiSubscriber = (
       dispatchIfValid(event, "MESSAGES_SNAPSHOT"),
     onCustomEvent: ({ event }) => dispatchIfValid(event, "CUSTOM"),
     onRawEvent: ({ event }) => dispatchIfValid(event, "RAW"),
+    onSubagentStartedEvent: ({ event }) =>
+      dispatchIfValid(event, "SUBAGENT_STARTED"),
+    onSubagentFinishedEvent: ({ event }) =>
+      dispatchIfValid(event, "SUBAGENT_FINISHED"),
+    onSubagentErrorEvent: ({ event }) =>
+      dispatchIfValid(event, "SUBAGENT_ERROR"),
     onRunFinishedEvent: ({ event }) => {
       if (runFinishedDispatched) return;
       const parsed = ensureEvent(event, "RUN_FINISHED", logger);

package/src/runtime/adapter/tool-approval.test.ts

@@ -36,6 +36,16 @@ describe("projectAgUiToolApprovals", () => {
     ]);
   });
 
+  it("carries the gate's message as the approval prompt", () => {
+    expect([
+      ...projectAgUiToolApprovals([
+        { ...gate("int-1", "tc-1"), message: "Delete the release branch?" },
+      ]),
+    ]).toEqual([
+      ["tc-1", { id: "int-1", prompt: "Delete the release branch?" }],
+    ]);
+  });
+
   it("gates a batch whose every tool call is rendered", () => {
     expect([
       ...projectAgUiToolApprovals(
@@ -679,3 +689,68 @@ describe("restored snapshots", () => {
     }
   });
 });
+
+describe("nested tool-call approval seams", () => {
+  const nestedContent = (
+    approval?: Record<string, unknown>,
+  ): ThreadAssistantMessagePart[] => [
+    {
+      ...(toolCall("tc-spawn") as any),
+      messages: [
+        {
+          id: "sub-1",
+          role: "assistant",
+          createdAt: new Date(),
+          status: { type: "requires-action", reason: "interrupt" },
+          content: [toolCall("tc-nested", approval ?? { id: "int-nested" })],
+          metadata: {
+            unstable_state: null,
+            unstable_annotations: [],
+            unstable_data: [],
+            steps: [],
+            custom: {},
+          },
+        },
+      ],
+    } as ThreadAssistantMessagePart,
+  ];
+
+  it("records a decision on a nested gate", () => {
+    const next = withToolApprovalDecision(nestedContent(), {
+      approvalId: "int-nested",
+      approved: true,
+    });
+    const nested = (next[0] as any).messages[0].content[0];
+    expect(nested.approval).toEqual({ id: "int-nested", approved: true });
+  });
+
+  it("reads a nested decision into the resume array", () => {
+    const decided = nestedContent({ id: "int-nested", approved: false });
+    const resume = buildToolApprovalResume(decided, [
+      {
+        id: "int-nested",
+        reason: "tool_call",
+        toolCallId: "tc-nested",
+        message: "Delete?",
+      },
+    ]);
+    expect(resume).toEqual([
+      expect.objectContaining({
+        interruptId: "int-nested",
+        status: "resolved",
+        payload: { approved: false },
+      }),
+    ]);
+  });
+
+  it("settles a nested gate that a cancellation resumes", () => {
+    const next = withSettledToolApprovals(nestedContent(), [
+      { interruptId: "int-nested", status: "cancelled" },
+    ]);
+    const nested = (next[0] as any).messages[0].content[0];
+    expect(nested.approval).toEqual({
+      id: "int-nested",
+      resolution: "cancelled",
+    });
+  });
+});

package/src/runtime/adapter/tool-approval.ts

@@ -1,3 +1,7 @@
+import {
+  iterateToolCallParts,
+  mapToolCallPartsDeep,
+} from "@assistant-ui/core/internal";
 import { buildResumeArray } from "@ag-ui/client";
 import type {
   RespondToToolApprovalOptions,
@@ -193,7 +197,9 @@ const isPending = (approval: ToolCallMessagePart["approval"]) =>
  * render can never be decided through this seam, so the batch it belongs to
  * could never be completed either: the decisions taken on its visible siblings
  * would sit on the message while the run waited for a response that no click
- * can produce. `boundToolCallIds` leaves such a batch bespoke instead.
+ * can produce. `boundToolCallIds` spans every call the run produced — root or
+ * nested on ToolCallMessagePart.messages — so only a gate naming a call the
+ * message renders nowhere leaves the batch bespoke.
  */
 export const projectAgUiToolApprovals = (
   interrupts: readonly AgUiInterrupt[] | undefined,
@@ -212,7 +218,13 @@ export const projectAgUiToolApprovals = (
   const toolCallIds = interrupts.map((interrupt) => interrupt.toolCallId);
   if (new Set(toolCallIds).size !== toolCallIds.length) return EMPTY_APPROVALS;
   return new Map(
-    interrupts.map((interrupt) => [interrupt.toolCallId, { id: interrupt.id }]),
+    interrupts.map((interrupt) => [
+      interrupt.toolCallId,
+      {
+        id: interrupt.id,
+        ...(interrupt.message !== undefined && { prompt: interrupt.message }),
+      },
+    ]),
   );
 };
 
@@ -228,12 +240,9 @@ export const withToolApprovalDecision = (
   content: readonly ThreadAssistantMessagePart[],
   { approvalId, approved, reason }: RespondToToolApprovalOptions,
 ): readonly ThreadAssistantMessagePart[] => {
-  let changed = false;
-  const next = content.map((part) => {
-    if (part.type !== "tool-call") return part;
+  const { content: next, changed } = mapToolCallPartsDeep(content, (part) => {
     const approval = part.approval;
     if (approval?.id !== approvalId || !isPending(approval)) return part;
-    changed = true;
     return {
       ...part,
       approval: {
@@ -263,8 +272,7 @@ export const buildToolApprovalResume = (
   // instead of recording a response, and `constructor` or `toString` would
   // report themselves as answered while undecided.
   const responses = new Map<string, { status: "resolved"; payload: unknown }>();
-  for (const part of content) {
-    if (part.type !== "tool-call") continue;
+  for (const part of iterateToolCallParts(content)) {
     const approval = part.approval;
     if (!approval || approval.approved === undefined) continue;
     if (!open.has(approval.id)) continue;
@@ -350,16 +358,13 @@ export const withSettledToolApprovals = (
 ): readonly ThreadAssistantMessagePart[] => {
   if (resume.length === 0) return content;
   const byId = new Map(resume.map((entry) => [entry.interruptId, entry]));
-  let changed = false;
-  const next = content.map((part) => {
-    if (part.type !== "tool-call") return part;
+  const { content: next, changed } = mapToolCallPartsDeep(content, (part) => {
     const approval = part.approval;
     if (!approval) return part;
     const entry = byId.get(approval.id);
     if (!entry) return part;
     const settled = settle(approval, entry);
     if (!settled) return part;
-    changed = true;
     return { ...part, approval: settled };
   });
   return changed ? next : content;

package/src/runtime/event-parser.ts

@@ -1,4 +1,9 @@
-import type { AgUiEvent, AgUiInterrupt, AgUiRunFinishedOutcome } from "./types";
+import type {
+  AgUiEvent,
+  AgUiInterrupt,
+  AgUiRunFinishedOutcome,
+  AgUiSubagentFinishedOutcome,
+} from "./types";
 import type { Logger } from "./logger";
 import { parseMcpToolCallResult } from "./mcp-tool-result";
 import { withRawResponseSchema } from "./interrupt-internals";
@@ -26,6 +31,16 @@ const withOptional = <T extends object>(
 const isPlainObject = (value: unknown): value is Record<string, unknown> =>
   !!value && typeof value === "object" && !Array.isArray(value);
 
+const logRejectedEvent = (
+  logger: Logger | undefined,
+  type: unknown,
+  payload: unknown,
+  reason: string,
+) => {
+  const typeLabel = isString(type) ? type : "unknown";
+  logger?.debug?.(`[agui] ${typeLabel} ${reason}`, payload);
+};
+
 const parseInterrupt = (raw: unknown): AgUiInterrupt | null => {
   if (!isPlainObject(raw)) return null;
   const id = raw.id;
@@ -51,30 +66,61 @@ const parseInterrupt = (raw: unknown): AgUiInterrupt | null => {
 
 const parseRunFinishedOutcome = (
   raw: unknown,
+  runId: string,
   logger: Logger | undefined,
 ): AgUiRunFinishedOutcome | undefined => {
-  if (!isPlainObject(raw)) return undefined;
+  if (raw == null) return undefined;
+  if (!isPlainObject(raw)) {
+    logRejectedEvent(
+      logger,
+      "RUN_FINISHED",
+      { runId, outcome: raw },
+      "has invalid outcome",
+    );
+    return undefined;
+  }
   if (raw.type === "success") return { type: "success" };
   if (raw.type === "interrupt") {
     if (!Array.isArray(raw.interrupts)) {
-      logger?.debug?.(
-        "[agui] RUN_FINISHED interrupt outcome missing interrupts array",
-        raw,
+      logRejectedEvent(
+        logger,
+        "RUN_FINISHED",
+        { runId, outcome: raw },
+        "has an interrupt outcome missing interrupts array",
       );
       return undefined;
     }
     const parsed = raw.interrupts
-      .map((entry) => parseInterrupt(entry))
+      .map((entry) => {
+        const interrupt = parseInterrupt(entry);
+        if (interrupt === null) {
+          logRejectedEvent(
+            logger,
+            "RUN_FINISHED",
+            { runId, interrupt: entry },
+            "has malformed interrupt",
+          );
+        }
+        return interrupt;
+      })
       .filter((entry): entry is AgUiInterrupt => entry !== null);
     if (parsed.length === 0) {
-      logger?.debug?.(
-        "[agui] RUN_FINISHED interrupt outcome has no valid interrupts",
-        raw.interrupts,
+      logRejectedEvent(
+        logger,
+        "RUN_FINISHED",
+        { runId, interrupts: raw.interrupts },
+        "has an interrupt outcome with no valid interrupts",
       );
       return undefined;
     }
     return { type: "interrupt", interrupts: parsed };
   }
+  logRejectedEvent(
+    logger,
+    "RUN_FINISHED",
+    { runId, outcome: raw },
+    "has unsupported outcome type",
+  );
   return undefined;
 };
 
@@ -82,10 +128,21 @@ export const parseAgUiEvent = (
   event: unknown,
   options?: ParseAgUiEventOptions,
 ): AgUiEvent | null => {
-  if (!event || typeof event !== "object") return null;
+  if (!event || typeof event !== "object") {
+    logRejectedEvent(options?.logger, undefined, event, "is not an object");
+    return null;
+  }
   const payload = event as Record<string, unknown>;
   const typeValue = payload.type;
-  if (!isString(typeValue)) return null;
+  if (!isString(typeValue)) {
+    logRejectedEvent(options?.logger, typeValue, payload, "has no string type");
+    return null;
+  }
+
+  const reject = (reason: string): null => {
+    logRejectedEvent(options?.logger, typeValue, payload, reason);
+    return null;
+  };
 
   const getString = (key: string) =>
     isString(payload[key]) ? (payload[key] as string) : undefined;
@@ -93,15 +150,19 @@ export const parseAgUiEvent = (
   switch (typeValue) {
     case "RUN_STARTED": {
       const runId = getString("runId");
-      return runId ? { type: "RUN_STARTED", runId } : null;
+      return runId ? { type: "RUN_STARTED", runId } : reject("missing runId");
     }
     case "RUN_FINISHED": {
       const runId = getString("runId");
-      if (!runId) return null;
+      if (!runId) return reject("missing runId");
       return withOptional(
         { type: "RUN_FINISHED" as const, runId },
         {
-          outcome: parseRunFinishedOutcome(payload.outcome, options?.logger),
+          outcome: parseRunFinishedOutcome(
+            payload.outcome,
+            runId,
+            options?.logger,
+          ),
         },
       );
     }
@@ -121,26 +182,38 @@ export const parseAgUiEvent = (
     case "TEXT_MESSAGE_START":
       return withOptional(
         { type: "TEXT_MESSAGE_START" as const },
-        { messageId: getString("messageId") },
+        {
+          messageId: getString("messageId"),
+          subagentRunId: getString("subagentRunId"),
+        },
       );
     case "TEXT_MESSAGE_CONTENT": {
       const delta = getString("delta");
-      if (!isNonEmptyString(delta)) return null;
+      if (!isNonEmptyString(delta)) return reject("missing non-empty delta");
       return withOptional(
         { type: "TEXT_MESSAGE_CONTENT" as const, delta },
-        { messageId: getString("messageId") },
+        {
+          messageId: getString("messageId"),
+          subagentRunId: getString("subagentRunId"),
+        },
       );
     }
     case "TEXT_MESSAGE_END":
       return withOptional(
         { type: "TEXT_MESSAGE_END" as const },
-        { messageId: getString("messageId") },
+        {
+          messageId: getString("messageId"),
+          subagentRunId: getString("subagentRunId"),
+        },
       );
     case "TEXT_MESSAGE_CHUNK": {
       const delta = getString("delta") ?? "";
       return withOptional(
         { type: "TEXT_MESSAGE_CHUNK" as const, delta },
-        { messageId: getString("messageId") },
+        {
+          messageId: getString("messageId"),
+          subagentRunId: getString("subagentRunId"),
+        },
       );
     }
     case "THINKING_START":
@@ -161,63 +234,94 @@ export const parseAgUiEvent = (
     case "REASONING_START":
       return withOptional(
         { type: "REASONING_START" as const },
-        { messageId: getString("messageId") },
+        {
+          messageId: getString("messageId"),
+          subagentRunId: getString("subagentRunId"),
+        },
       );
     case "REASONING_MESSAGE_START":
       return withOptional(
         { type: "REASONING_MESSAGE_START" as const },
-        { messageId: getString("messageId") },
+        {
+          messageId: getString("messageId"),
+          subagentRunId: getString("subagentRunId"),
+        },
       );
     case "REASONING_MESSAGE_CONTENT": {
       const delta = getString("delta") ?? "";
       return withOptional(
         { type: "REASONING_MESSAGE_CONTENT" as const, delta },
-        { messageId: getString("messageId") },
+        {
+          messageId: getString("messageId"),
+          subagentRunId: getString("subagentRunId"),
+        },
       );
     }
     case "REASONING_MESSAGE_END":
       return withOptional(
         { type: "REASONING_MESSAGE_END" as const },
-        { messageId: getString("messageId") },
+        {
+          messageId: getString("messageId"),
+          subagentRunId: getString("subagentRunId"),
+        },
       );
     case "REASONING_ENCRYPTED_VALUE": {
       const entityId = getString("entityId");
       const encryptedValue = getString("encryptedValue");
       const subtype = getString("subtype");
-      if (!entityId || !encryptedValue) return null;
-      if (subtype !== "message" && subtype !== "tool-call") return null;
+      if (!entityId || !encryptedValue) {
+        return reject("missing entityId or encryptedValue");
+      }
+      if (subtype !== "message" && subtype !== "tool-call") {
+        return reject("has an invalid subtype");
+      }
+      // Spread rather than withOptional: routing the narrowed `subtype` through
+      // a generic helper widens it back to string.
+      const subagentRunId = getString("subagentRunId");
       return {
         type: "REASONING_ENCRYPTED_VALUE" as const,
         subtype,
         entityId,
         encryptedValue,
+        ...(subagentRunId !== undefined ? { subagentRunId } : {}),
       };
     }
     case "REASONING_END":
       return withOptional(
         { type: "REASONING_END" as const },
-        { messageId: getString("messageId") },
+        {
+          messageId: getString("messageId"),
+          subagentRunId: getString("subagentRunId"),
+        },
       );
     case "TOOL_CALL_START": {
       const toolCallId = getString("toolCallId");
-      if (!toolCallId) return null;
+      if (!toolCallId) return reject("missing toolCallId");
       return withOptional(
         { type: "TOOL_CALL_START" as const, toolCallId },
         {
           toolCallName: getString("toolCallName"),
           parentMessageId: getString("parentMessageId"),
+          subagentRunId: getString("subagentRunId"),
         },
       );
     }
     case "TOOL_CALL_ARGS": {
       const toolCallId = getString("toolCallId");
-      if (!toolCallId) return null;
+      if (!toolCallId) return reject("missing toolCallId");
       const delta = getString("delta") ?? "";
-      return { type: "TOOL_CALL_ARGS", toolCallId, delta };
+      return withOptional(
+        { type: "TOOL_CALL_ARGS" as const, toolCallId, delta },
+        { subagentRunId: getString("subagentRunId") },
+      );
     }
     case "TOOL_CALL_END": {
       const toolCallId = getString("toolCallId");
-      return toolCallId ? { type: "TOOL_CALL_END", toolCallId } : null;
+      if (!toolCallId) return reject("missing toolCallId");
+      return withOptional(
+        { type: "TOOL_CALL_END" as const, toolCallId },
+        { subagentRunId: getString("subagentRunId") },
+      );
     }
     case "TOOL_CALL_CHUNK":
       return withOptional(
@@ -227,11 +331,12 @@ export const parseAgUiEvent = (
           toolCallName: getString("toolCallName"),
           parentMessageId: getString("parentMessageId"),
           delta: getString("delta"),
+          subagentRunId: getString("subagentRunId"),
         },
       );
     case "TOOL_CALL_RESULT": {
       const toolCallId = getString("toolCallId");
-      if (!toolCallId) return null;
+      if (!toolCallId) return reject("missing toolCallId");
       const content = getString("content") ?? "";
       return withOptional(
         {
@@ -243,10 +348,14 @@ export const parseAgUiEvent = (
           messageId: getString("messageId"),
           role: payload.role === "tool" ? "tool" : undefined,
           mcpResult: parseMcpToolCallResult(payload, content),
+          subagentRunId: getString("subagentRunId"),
         },
       );
     }
     case "STATE_SNAPSHOT":
+      if (payload.snapshot === undefined) {
+        return reject("missing snapshot");
+      }
       return { type: "STATE_SNAPSHOT", snapshot: payload.snapshot };
     case "STATE_DELTA":
       return {
@@ -254,15 +363,18 @@ export const parseAgUiEvent = (
         delta: Array.isArray(payload.delta) ? (payload.delta as any[]) : [],
       };
     case "MESSAGES_SNAPSHOT":
+      if (!Array.isArray(payload.messages)) {
+        return reject("missing messages array");
+      }
       return {
         type: "MESSAGES_SNAPSHOT",
-        messages: Array.isArray(payload.messages)
-          ? (payload.messages as any[])
-          : [],
+        messages: payload.messages as any[],
       };
     case "ACTIVITY_SNAPSHOT": {
       const activityType = getString("activityType");
-      if (!activityType || !isPlainObject(payload.content)) return null;
+      if (!activityType || !isPlainObject(payload.content)) {
+        return reject("missing activityType or object content");
+      }
       return withOptional(
         {
           type: "ACTIVITY_SNAPSHOT" as const,
@@ -273,6 +385,7 @@ export const parseAgUiEvent = (
           messageId: getString("messageId"),
           replace:
             typeof payload.replace === "boolean" ? payload.replace : undefined,
+          subagentRunId: getString("subagentRunId"),
         },
       );
     }
@@ -283,9 +396,76 @@ export const parseAgUiEvent = (
       );
     case "CUSTOM": {
       const name = getString("name");
-      if (!name) return null;
+      if (!name) return reject("missing name");
       return { type: "CUSTOM", name, value: payload.value };
     }
+    case "SUBAGENT_STARTED": {
+      const subagentRunId = getString("subagentRunId");
+      const name = getString("name");
+      if (!subagentRunId || !name) {
+        return reject("missing subagentRunId or name");
+      }
+      return withOptional(
+        { type: "SUBAGENT_STARTED" as const, subagentRunId, name },
+        {
+          description: getString("description"),
+          parentSubagentRunId: getString("parentSubagentRunId"),
+          parentToolCallId: getString("parentToolCallId"),
+          parentMessageId: getString("parentMessageId"),
+        },
+      );
+    }
+    case "SUBAGENT_FINISHED": {
+      const subagentRunId = getString("subagentRunId");
+      if (!subagentRunId) return reject("missing subagentRunId");
+      const rawOutcome = payload.outcome;
+      let outcome: AgUiSubagentFinishedOutcome | undefined;
+      if (rawOutcome == null) {
+        outcome = undefined;
+      } else if (!isPlainObject(rawOutcome)) {
+        logRejectedEvent(
+          options?.logger,
+          "SUBAGENT_FINISHED",
+          { subagentRunId, outcome: rawOutcome },
+          "has invalid outcome",
+        );
+        outcome = undefined;
+      } else if (rawOutcome.type === "success") {
+        outcome = { type: "success" as const };
+      } else if (rawOutcome.type === "suspended") {
+        outcome = withOptional(
+          { type: "suspended" as const },
+          {
+            interruptIds: Array.isArray(rawOutcome.interruptIds)
+              ? (rawOutcome.interruptIds as unknown[]).filter(isString)
+              : undefined,
+          },
+        );
+      } else {
+        logRejectedEvent(
+          options?.logger,
+          "SUBAGENT_FINISHED",
+          { subagentRunId, outcome: rawOutcome },
+          "has unsupported outcome type",
+        );
+        outcome = undefined;
+      }
+      return withOptional(
+        { type: "SUBAGENT_FINISHED" as const, subagentRunId },
+        { result: payload.result, outcome },
+      );
+    }
+    case "SUBAGENT_ERROR": {
+      const subagentRunId = getString("subagentRunId");
+      const message = getString("message");
+      if (!subagentRunId || !message) {
+        return reject("missing subagentRunId or message");
+      }
+      return withOptional(
+        { type: "SUBAGENT_ERROR" as const, subagentRunId, message },
+        { code: getString("code") },
+      );
+    }
     default:
       return withOptional(
         { type: "RAW" as const, event: payload },