@assistant-ui/react-ag-ui 0.0.57 → 0.0.59

package/src/runtime/types.ts

@@ -56,10 +56,36 @@ export type UseAgUiRuntimeAdapters = {
   threadList?: UseAgUiThreadListAdapter;
 };
 
+export type AgUiResumeTranscript = "full" | "appended";
+
 export type UseAgUiRuntimeOptions = ExternalStoreSharedOptions & {
   agent: AbstractAgent;
   logger?: Partial<Logger>;
   showThinking?: boolean;
+  /**
+   * What `messages` carries on a resume run, meaning a `RunAgentInput` that
+   * also carries `resume`. The AG-UI interrupt spec leaves this undefined: its
+   * contract rules constrain the thread id, interrupt coverage, idempotency,
+   * and expiry, and none of them mentions `messages`. Hosts therefore disagree,
+   * and both readings are conformant.
+   *
+   * `"full"` sends the whole thread, which is what `@ag-ui/client` itself does.
+   * Hosts that resume from a checkpoint ignore the transcript, and hosts that
+   * rebuild the interrupted run from it need it.
+   *
+   * `"appended"` sends only what was appended locally after the interrupted
+   * assistant message, which is nothing for an approval or a denial and the new
+   * user turn for `steerAway`. Choose it for a host that owns the thread and
+   * seeds a resume request from its own stored snapshot, because such a host
+   * appends the request body to that snapshot and a re-sent transcript
+   * duplicates the interrupted turn in its stored history. A host that rebuilds
+   * the run from `messages` has nothing to resume from under `"appended"`, and
+   * a host that derives its outgoing `MESSAGES_SNAPSHOT` from the request body
+   * emits a truncated one.
+   *
+   * Defaults to `"full"`.
+   */
+  resumeTranscript?: AgUiResumeTranscript | undefined;
   /**
    * When the user sends, edits, or reloads a message while client-side tool
    * calls are still pending, automatically cancel the unresolved tool calls
@@ -127,6 +153,10 @@ export type AgUiRunFinishedOutcome =
   | { type: "success" }
   | { type: "interrupt"; interrupts: AgUiInterrupt[] };
 
+export type AgUiSubagentFinishedOutcome =
+  | { type: "success" }
+  | { type: "suspended"; interruptIds?: string[] };
+
 export type AgUiEvent =
   | { type: "RUN_STARTED"; runId: string }
   | {
@@ -136,40 +166,71 @@ export type AgUiEvent =
     }
   | { type: "RUN_CANCELLED"; runId?: string }
   | { type: "RUN_ERROR"; message?: string; code?: string }
-  | { type: "TEXT_MESSAGE_START"; messageId?: string }
-  | { type: "TEXT_MESSAGE_CONTENT"; messageId?: string; delta: string }
-  | { type: "TEXT_MESSAGE_END"; messageId?: string }
-  | { type: "TEXT_MESSAGE_CHUNK"; delta: string }
+  | { type: "TEXT_MESSAGE_START"; messageId?: string; subagentRunId?: string }
+  | {
+      type: "TEXT_MESSAGE_CONTENT";
+      messageId?: string;
+      delta: string;
+      subagentRunId?: string;
+    }
+  | { type: "TEXT_MESSAGE_END"; messageId?: string; subagentRunId?: string }
+  | {
+      type: "TEXT_MESSAGE_CHUNK";
+      messageId?: string;
+      delta: string;
+      subagentRunId?: string;
+    }
   | { type: "THINKING_START"; title?: string }
   | { type: "THINKING_TEXT_MESSAGE_START" }
   | { type: "THINKING_TEXT_MESSAGE_CONTENT"; delta: string }
   | { type: "THINKING_TEXT_MESSAGE_END" }
   | { type: "THINKING_END" }
-  | { type: "REASONING_START"; messageId?: string }
-  | { type: "REASONING_MESSAGE_START"; messageId?: string }
-  | { type: "REASONING_MESSAGE_CONTENT"; messageId?: string; delta: string }
-  | { type: "REASONING_MESSAGE_END"; messageId?: string }
+  | { type: "REASONING_START"; messageId?: string; subagentRunId?: string }
+  | {
+      type: "REASONING_MESSAGE_START";
+      messageId?: string;
+      subagentRunId?: string;
+    }
+  | {
+      type: "REASONING_MESSAGE_CONTENT";
+      messageId?: string;
+      delta: string;
+      subagentRunId?: string;
+    }
+  | {
+      type: "REASONING_MESSAGE_END";
+      messageId?: string;
+      subagentRunId?: string;
+    }
   | {
       type: "REASONING_ENCRYPTED_VALUE";
       subtype: "message" | "tool-call";
       entityId: string;
       encryptedValue: string;
+      subagentRunId?: string;
     }
-  | { type: "REASONING_END"; messageId?: string }
+  | { type: "REASONING_END"; messageId?: string; subagentRunId?: string }
   | {
       type: "TOOL_CALL_START";
       toolCallId: string;
       toolCallName?: string;
       parentMessageId?: string;
+      subagentRunId?: string;
+    }
+  | {
+      type: "TOOL_CALL_ARGS";
+      toolCallId: string;
+      delta: string;
+      subagentRunId?: string;
     }
-  | { type: "TOOL_CALL_ARGS"; toolCallId: string; delta: string }
-  | { type: "TOOL_CALL_END"; toolCallId: string }
+  | { type: "TOOL_CALL_END"; toolCallId: string; subagentRunId?: string }
   | {
       type: "TOOL_CALL_CHUNK";
       toolCallId?: string;
       toolCallName?: string;
       parentMessageId?: string;
       delta?: string;
+      subagentRunId?: string;
     }
   | {
       type: "TOOL_CALL_RESULT";
@@ -178,6 +239,7 @@ export type AgUiEvent =
       content: string;
       role?: "tool";
       mcpResult?: McpToolCallResult;
+      subagentRunId?: string;
     }
   | {
       type: "ACTIVITY_SNAPSHOT";
@@ -185,9 +247,31 @@ export type AgUiEvent =
       content: Record<string, unknown>;
       messageId?: string;
       replace?: boolean;
+      subagentRunId?: string;
     }
   | { type: "RAW"; event: any; source?: string }
   | { type: "CUSTOM"; name: string; value: any }
   | { type: "STATE_SNAPSHOT"; snapshot: any }
   | { type: "STATE_DELTA"; delta: any[] }
-  | { type: "MESSAGES_SNAPSHOT"; messages: any[] };
+  | { type: "MESSAGES_SNAPSHOT"; messages: any[] }
+  | {
+      type: "SUBAGENT_STARTED";
+      subagentRunId: string;
+      name: string;
+      description?: string;
+      parentSubagentRunId?: string;
+      parentToolCallId?: string;
+      parentMessageId?: string;
+    }
+  | {
+      type: "SUBAGENT_FINISHED";
+      subagentRunId: string;
+      result?: unknown;
+      outcome?: AgUiSubagentFinishedOutcome;
+    }
+  | {
+      type: "SUBAGENT_ERROR";
+      subagentRunId: string;
+      message: string;
+      code?: string;
+    };

package/src/useAgUiRuntime.approval.test.tsx

@@ -30,13 +30,23 @@ import { readRawResponseSchema } from "./runtime/interrupt-internals";
 
 type Subscriber = Record<string, ((payload: any) => void) | undefined>;
 
+const GATE_PROMPT = "Delete /tmp/a?";
+
 const GATE: AgUiInterrupt = {
   id: "int-1",
   reason: "tool_call",
   toolCallId: "tc-1",
-  message: "Delete /tmp/a?",
+  message: GATE_PROMPT,
 };
 
+// The gate's message reaches the renderer as the approval's prompt, so every
+// projection of GATE carries it.
+const gateApproval = (rest: Record<string, unknown> = {}) => ({
+  id: "int-1",
+  prompt: GATE_PROMPT,
+  ...rest,
+});
+
 // Gates the first run on an interrupt and lets every later run settle, so a
 // resumed run is observable as a second call rather than a second gate.
 const gatingAgent = (interrupts: readonly AgUiInterrupt[] = [GATE]) => {
@@ -145,7 +155,7 @@ describe("useAgUiRuntime tool approvals", () => {
   it("gates the tool call a tool_call interrupt names", async () => {
     const { runtime } = await gatedThread();
 
-    expect(allToolCalls(runtime.current)[0]!.approval).toEqual({ id: "int-1" });
+    expect(allToolCalls(runtime.current)[0]!.approval).toEqual(gateApproval());
     expect(gatedPart(runtime.current).getState().status).toMatchObject({
       type: "requires-action",
     });
@@ -200,10 +210,9 @@ describe("useAgUiRuntime tool approvals", () => {
     });
     expect(runAgent).toHaveBeenCalledTimes(1);
     // The first decision survives the rerender the second gate triggers.
-    expect(allToolCalls(runtime.current)[0]!.approval).toEqual({
-      id: "int-1",
-      approved: true,
-    });
+    expect(allToolCalls(runtime.current)[0]!.approval).toEqual(
+      gateApproval({ approved: true }),
+    );
 
     await act(async () => {
       gatedPart(runtime.current, "tc-2").respondToToolApproval({
@@ -222,10 +231,9 @@ describe("useAgUiRuntime tool approvals", () => {
       },
     ]);
     // Settlement consumes the resume array, so the approved gate stays approved.
-    expect(allToolCalls(runtime.current)[0]!.approval).toEqual({
-      id: "int-1",
-      approved: true,
-    });
+    expect(allToolCalls(runtime.current)[0]!.approval).toEqual(
+      gateApproval({ approved: true }),
+    );
     expect(
       allToolCalls(runtime.current).every((part) => part.result === undefined),
     ).toBe(true);
@@ -255,7 +263,7 @@ describe("useAgUiRuntime tool approvals", () => {
     // The wire cancelled both, so the gate approved while its sibling was
     // still open cannot keep displaying an approval that was never sent.
     expect(allToolCalls(runtime.current).map((part) => part.approval)).toEqual([
-      { id: "int-1", resolution: "cancelled" },
+      gateApproval({ resolution: "cancelled" }),
       { id: "int-2", resolution: "cancelled" },
     ]);
   });
@@ -286,7 +294,7 @@ describe("useAgUiRuntime tool approvals", () => {
     expect(
       allToolCalls(runtime.current).find((p) => p.approval?.id === "int-1")
         ?.approval,
-    ).toEqual({ id: "int-1", resolution: "cancelled" });
+    ).toEqual(gateApproval({ resolution: "cancelled" }));
   });
 
   it("shows a bespoke resolved override as the decision it carried", async () => {
@@ -305,7 +313,7 @@ describe("useAgUiRuntime tool approvals", () => {
     expect(
       allToolCalls(runtime.current).find((p) => p.approval?.id === "int-1")
         ?.approval,
-    ).toEqual({ id: "int-1", approved: true });
+    ).toEqual(gateApproval({ approved: true }));
   });
 
   it("leaves the tool call ungated when the live interrupt carries a rejecting schema", async () => {
@@ -344,7 +352,7 @@ describe("useAgUiRuntime tool approvals", () => {
     ]);
     const [interrupt] = interruptsRef.current;
 
-    expect(allToolCalls(runtime.current)[0]!.approval).toEqual({ id: "int-1" });
+    expect(allToolCalls(runtime.current)[0]!.approval).toEqual(gateApproval());
     expect(interrupt?.responseSchema).toBeUndefined();
     expect(interrupt && readRawResponseSchema(interrupt)).toBeUndefined();
   });
@@ -412,7 +420,7 @@ describe("useAgUiRuntime tool approvals", () => {
     // `{answer:42}` went out for the first gate, so the approval recorded while
     // its sibling was still open cannot keep displaying a decision never sent.
     expect(allToolCalls(runtime.current).map((part) => part.approval)).toEqual([
-      { id: "int-1", resolution: "cancelled" },
+      gateApproval({ resolution: "cancelled" }),
       { id: "int-2", resolution: "cancelled" },
     ]);
   });
@@ -469,7 +477,7 @@ describe("useAgUiRuntime tool approvals", () => {
       type: "requires-action",
       reason: "interrupt",
     });
-    expect(allToolCalls(runtime.current)[0]!.approval).toEqual({ id: "int-1" });
+    expect(allToolCalls(runtime.current)[0]!.approval).toEqual(gateApproval());
     expect(execute).not.toHaveBeenCalled();
 
     await act(async () => {
@@ -542,14 +550,14 @@ describe("useAgUiRuntime tool approvals under an unsettled run", () => {
       content: [{ type: "text", text: "delete it" }],
     });
     await waitFor(() =>
-      expect(allToolCalls(result.current)[0]?.approval).toEqual({
-        id: "int-1",
-      }),
+      expect(allToolCalls(result.current)[0]?.approval).toEqual(gateApproval()),
     );
     expect(result.current.thread.getState().isRunning).toBe(true);
 
     await act(async () => {
-      gatedPart(result.current).respondToToolApproval({ approved: true });
+      await expect(
+        gatedPart(result.current).respondToToolApproval({ approved: true }),
+      ).rejects.toThrow("a run is already in progress");
     });
     await waitFor(() => expect(onError).toHaveBeenCalledTimes(1));
     expect((onError.mock.calls[0]![0] as Error).message).toContain(
@@ -557,7 +565,7 @@ describe("useAgUiRuntime tool approvals under an unsettled run", () => {
     );
     // The rejected click must not have recorded a decision, or the retry
     // below would report the approval as already decided.
-    expect(allToolCalls(result.current)[0]!.approval).toEqual({ id: "int-1" });
+    expect(allToolCalls(result.current)[0]!.approval).toEqual(gateApproval());
 
     await act(async () => {
       release();
@@ -662,7 +670,7 @@ describe("useAgUiRuntime tool approvals across a messages snapshot", () => {
     const gated = allToolCalls(result.current).filter(
       (part) => part.approval !== undefined,
     );
-    expect(gated.map((part) => part.approval)).toEqual([{ id: "int-1" }]);
+    expect(gated.map((part) => part.approval)).toEqual([gateApproval()]);
 
     await act(async () => {
       await gatedPart(result.current).respondToToolApproval({ approved: true });
@@ -795,7 +803,9 @@ describe("useAgUiRuntime approvals on a run that fails after the interrupt", ()
     await waitFor(() => expect(runAgent).toHaveBeenCalledTimes(1));
 
     await act(async () => {
-      gatedPart(result.current).respondToToolApproval({ approved: true });
+      await expect(
+        gatedPart(result.current).respondToToolApproval({ approved: true }),
+      ).rejects.toThrow("resume failed");
     });
     await waitFor(() => expect(runAgent).toHaveBeenCalledTimes(2));
     await waitFor(() => expect(onError).toHaveBeenCalled());
@@ -879,7 +889,7 @@ describe("useAgUiRuntime approvals that cannot be completed through the seam", (
     // The interrupt is closed, so the gate must not stay actionable: a click
     // would find no pending interrupt on the thread.
     expect(allToolCalls(runtime.current).map((part) => part.approval)).toEqual([
-      { id: "int-1", resolution: "cancelled" },
+      gateApproval({ resolution: "cancelled" }),
     ]);
   });
 });

package/src/useAgUiRuntime.queue.test.tsx

@@ -1,6 +1,7 @@
 // @vitest-environment jsdom
 
 import { describe, it, expect, vi, afterEach } from "vitest";
+import { startTransition, useEffect } from "react";
 import {
   act,
   cleanup,
@@ -409,6 +410,59 @@ describe("useAgUiRuntime unstable_enableMessageQueue", () => {
     );
   });
 
+  it("does not clear the committed queue from a suspended render", async () => {
+    const { agent, runAgent } = gatedAgent();
+    let runtime: AssistantRuntime | undefined;
+    const never = new Promise<void>(() => {});
+
+    const Harness = ({
+      enabled,
+      suspend,
+    }: {
+      enabled: boolean;
+      suspend: boolean;
+    }) => {
+      const nextRuntime = useAgUiRuntime({
+        agent,
+        unstable_enableMessageQueue: enabled,
+      });
+      useEffect(() => {
+        runtime = nextRuntime;
+      }, [nextRuntime]);
+      if (suspend) throw never;
+      return null;
+    };
+
+    const view = render(<Harness enabled suspend={false} />);
+    await waitFor(() => expect(runtime).toBeDefined());
+    mount(runtime!);
+
+    await act(async () => {
+      await runtime!.thread.append({
+        role: "user",
+        content: [{ type: "text", text: "first" }],
+      });
+    });
+    await waitFor(() => expect(runAgent).toHaveBeenCalledTimes(1));
+
+    await act(async () => {
+      await runtime!.thread.append({
+        role: "user",
+        content: [{ type: "text", text: "second" }],
+        parentId: runtime!.thread.getState().messages.at(-1)?.id ?? null,
+      });
+    });
+    await waitFor(() =>
+      expect(screen.getByTestId("queued").textContent).toBe("second"),
+    );
+
+    act(() => {
+      startTransition(() => view.rerender(<Harness enabled={false} suspend />));
+    });
+
+    expect(screen.getByTestId("queued").textContent).toBe("second");
+  });
+
   it("leaves the queue capability off when the flag is not set", () => {
     const { agent } = gatedAgent();
 

package/src/useAgUiRuntime.thread-switch.test.tsx

@@ -0,0 +1,199 @@
+// @vitest-environment jsdom
+
+import { useState } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { act, cleanup, renderHook } from "@testing-library/react";
+import type { HttpAgent } from "@ag-ui/client";
+import type { ThreadMessage } from "@assistant-ui/core";
+import { AgUiThreadRuntimeCore } from "./runtime/AgUiThreadRuntimeCore";
+import type { UseAgUiThreadListAdapter } from "./runtime/types";
+import { useAgUiRuntime } from "./useAgUiRuntime";
+
+type ThreadLoad = Awaited<
+  ReturnType<NonNullable<UseAgUiThreadListAdapter["onSwitchToThread"]>>
+>;
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+
+function message(id: string): ThreadMessage {
+  return {
+    id,
+    role: "user",
+    content: [{ type: "text", text: id }],
+    attachments: [],
+    createdAt: new Date(0),
+    metadata: { custom: {} },
+  };
+}
+
+function renderRuntime(
+  load: (id: string) => Promise<ThreadLoad>,
+  create: () => Promise<void> = async () => {},
+) {
+  const agent = {
+    runAgent: vi.fn(),
+    abortRun: vi.fn(),
+  } as unknown as HttpAgent;
+  return renderHook(() => {
+    const [threadId, setThreadId] = useState("initial");
+    return useAgUiRuntime({
+      agent,
+      adapters: {
+        threadList: {
+          threadId,
+          onSwitchToThread: (id) => {
+            setThreadId(id);
+            return load(id);
+          },
+          onSwitchToNewThread: () => {
+            setThreadId("thread-new");
+            return create();
+          },
+        },
+      },
+    });
+  });
+}
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe("useAgUiRuntime thread switching", () => {
+  it.each([undefined, { owner: "thread-a" }])(
+    "ignores an older load and its resume request with state %j",
+    async (state) => {
+      const resume = vi
+        .spyOn(AgUiThreadRuntimeCore.prototype, "resumeInFlightRun")
+        .mockResolvedValue();
+      const first = deferred<ThreadLoad>();
+      const second = deferred<ThreadLoad>();
+      const { result } = renderRuntime((id) =>
+        id === "thread-a" ? first.promise : second.promise,
+      );
+
+      let switchA!: Promise<void>;
+      let switchB!: Promise<void>;
+      act(() => {
+        switchA = result.current.threads.switchToThread("thread-a");
+        switchB = result.current.threads.switchToThread("thread-b");
+      });
+      await act(async () => {
+        second.resolve({
+          messages: [message("thread-b")],
+          state: { owner: "thread-b" },
+        });
+        await switchB;
+      });
+      await act(async () => {
+        first.resolve({
+          messages: [message("thread-a")],
+          ...(state !== undefined && { state }),
+          unstable_resume: true,
+        });
+        await switchA;
+      });
+
+      expect(result.current.threads.getState().mainThreadId).toBe("thread-b");
+      expect(
+        result.current.thread.getState().messages.map((m) => m.id),
+      ).toEqual(["thread-b"]);
+      expect(result.current.thread.getState().state).toEqual({
+        owner: "thread-b",
+      });
+      expect(resume).not.toHaveBeenCalled();
+    },
+  );
+
+  it("ignores a load superseded by creating a new thread", async () => {
+    const resume = vi
+      .spyOn(AgUiThreadRuntimeCore.prototype, "resumeInFlightRun")
+      .mockResolvedValue();
+    const load = deferred<ThreadLoad>();
+    const { result } = renderRuntime(() => load.promise);
+
+    let switchA!: Promise<void>;
+    act(() => {
+      switchA = result.current.threads.switchToThread("thread-a");
+    });
+    await act(async () => {
+      await result.current.threads.switchToNewThread();
+    });
+    const newThreadState = result.current.thread.getState().state;
+    await act(async () => {
+      load.resolve({
+        messages: [message("thread-a")],
+        state: { owner: "thread-a" },
+        unstable_resume: true,
+      });
+      await switchA;
+    });
+
+    expect(result.current.threads.getState().mainThreadId).toBe("thread-new");
+    expect(result.current.thread.getState().messages).toEqual([]);
+    expect(result.current.thread.getState().state).toEqual(newThreadState);
+    expect(resume).not.toHaveBeenCalled();
+  });
+
+  it("does not clear a newer thread when an older creation finishes", async () => {
+    const creation = deferred<void>();
+    const { result } = renderRuntime(
+      async () => ({
+        messages: [message("thread-b")],
+        state: { owner: "thread-b" },
+      }),
+      () => creation.promise,
+    );
+
+    let switchNew!: Promise<void>;
+    act(() => {
+      switchNew = result.current.threads.switchToNewThread();
+    });
+    await act(async () => {
+      await result.current.threads.switchToThread("thread-b");
+    });
+    await act(async () => {
+      creation.resolve();
+      await switchNew;
+    });
+
+    expect(result.current.threads.getState().mainThreadId).toBe("thread-b");
+    expect(result.current.thread.getState().messages.map((m) => m.id)).toEqual([
+      "thread-b",
+    ]);
+    expect(result.current.thread.getState().state).toEqual({
+      owner: "thread-b",
+    });
+  });
+
+  it("applies the current load and resumes it", async () => {
+    const resume = vi
+      .spyOn(AgUiThreadRuntimeCore.prototype, "resumeInFlightRun")
+      .mockResolvedValue();
+    const messages = [message("thread-a")];
+    const { result } = renderRuntime(async () => ({
+      messages,
+      state: { owner: "thread-a" },
+      unstable_resume: true,
+    }));
+
+    await act(async () => {
+      await result.current.threads.switchToThread("thread-a");
+    });
+
+    expect(result.current.thread.getState().messages.map((m) => m.id)).toEqual([
+      "thread-a",
+    ]);
+    expect(result.current.thread.getState().state).toEqual({
+      owner: "thread-a",
+    });
+    expect(resume).toHaveBeenCalledExactlyOnceWith(messages);
+  });
+});