@runtypelabs/persona 4.29.0 → 4.29.2

package/src/types.ts

@@ -5267,6 +5267,13 @@ export type VoiceDelegationRequest = {
   userUtteranceIds: string[];
   /** The voice model's view of the conversation it delegated from. */
   messages: Array<{ role: string; content: unknown }>;
+  /**
+   * `delegation_started.input.priorToolResults` as received: page tools the
+   * server already ran for this turn, each `{ toolCallId, name, arguments,
+   * result }`. Unvalidated. The chat turn records them as completed calls and
+   * never runs them again.
+   */
+  priorToolResults?: unknown;
   /**
    * Set when the server streams delegated answers (`delegation_stream`): called
    * with each speakable piece of the turn's answer, in order, while it renders.
@@ -6404,7 +6411,23 @@ export type ClientChatRequest = {
    * reads aloud: the server asks the agent for a speakable answer (the direct
    * answer first, in plain sentences). Not persisted into history.
    */
-  voice?: { spoken: true };
+  voice?: {
+    spoken: true;
+    /**
+     * Page tools the voice server already ran for this hand-back
+     * (`delegation_started.input.priorToolResults`), sent only when it carried
+     * some. The agent narrates their results instead of calling them again.
+     */
+    priorToolResults?: VoicePriorToolResult[];
+  };
+};
+
+/** A page tool call the voice server already ran, as `/v1/client/chat` takes it. */
+export type VoicePriorToolResult = {
+  toolCallId: string;
+  name: string;
+  arguments: Record<string, unknown>;
+  result: unknown;
 };
 
 /**
@@ -7206,7 +7229,8 @@ export type AgentWidgetPersistStateConfig = {
    */
   storage?: 'local' | 'session';
   /**
-   * Prefix for storage keys.
+   * Prefix for storage keys. Also scopes the default transcript key
+   * (`${keyPrefix}state` in localStorage) when no `storageAdapter` is given.
    * @default 'persona-'
    */
   keyPrefix?: string;
@@ -8354,6 +8378,8 @@ export type AgentWidgetReasoning = {
 export type AgentWidgetToolCall = {
   /** Optional approval state for activity-row status chrome. */
   approvalStatus?: "pending" | "approved" | "denied" | "timeout";
+  /** Terminal browser work whose callback was lost when the chat restarted. */
+  interrupted?: boolean;
   id: string;
   name?: string;
   status: "pending" | "running" | "complete";
@@ -8381,6 +8407,8 @@ export type AgentWidgetToolCall = {
 export type AgentWidgetApproval = {
   id: string;
   status: "pending" | "approved" | "denied" | "timeout";
+  /** A browser callback lost on restart. The approval expires with status `timeout`. */
+  interrupted?: boolean;
   agentId: string;
   executionId: string;
   toolName: string;
@@ -8505,6 +8533,13 @@ export type AgentWidgetMessage = {
    * model as conversation.
    */
   voiceCaption?: boolean;
+  /**
+   * Set on widget-generated failure notices (a failed dispatch, a rejected
+   * approval decision, a reconnect that gave up). The bubble renders in this
+   * browser only: it is never sent to the model as conversation history and
+   * never written to the storage adapter.
+   */
+  localOnly?: boolean;
   /**
    * Raw structured payload for this message (e.g., JSON action response).
    * Populated automatically when structured parsers run.

package/src/ui.restored-browser-tools.test.ts

@@ -0,0 +1,128 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createAgentExperience } from "./ui";
+import { provideApprovalUi } from "./approval-ui-loader";
+import * as approvalUiEntry from "./approval-ui-entry";
+import type { AgentWidgetMessage, AgentWidgetStoredState } from "./types";
+import { createDemoHistoryProvider } from "./internal/demo-history-provider";
+
+provideApprovalUi(approvalUiEntry);
+let controller: ReturnType<typeof createAgentExperience> | undefined;
+afterEach(() => { controller?.destroy(); document.body.replaceChildren(); localStorage.clear(); vi.restoreAllMocks(); });
+
+const snapshot = (): AgentWidgetStoredState => ({
+  metadata: { custom: "retained" }, draft: { text: "My unsent proposal" },
+  messages: [
+    { id: "tool-1", role: "assistant", content: "", createdAt: "2026-01-01", sequence: 1, streaming: true, variant: "tool", agentMetadata: { executionId: "exec", awaitingLocalTool: true }, toolCall: { id: "call-1", name: "webmcp:purchase", status: "running", startedAt: 1, args: { quantity: 2 }, approvalStatus: "pending" } },
+    { id: "tool-2", role: "assistant", content: "", createdAt: "2026-01-01", sequence: 2, variant: "tool", toolCall: { id: "call-2", name: "webmcp:search", status: "complete", result: "Found two items", durationMs: 2000 } },
+    { id: "approval-webmcp-1", role: "assistant", content: "", createdAt: "2026-01-01", sequence: 3, variant: "approval", approval: { id: "webmcp-1", status: "pending", agentId: "", executionId: "", toolType: "webmcp", toolName: "webmcp:purchase", description: "Buy items", parameters: { quantity: 2 } } },
+  ] satisfies AgentWidgetMessage[],
+});
+
+for (const source of ["sync", "async", "initial", "hook"] as const) {
+  describe.each(["card", "row"] as const)(`${source} restoration (%s)`, variant => {
+    it("renders historical controls and activity as interrupted while preserving drafts", async () => {
+      const stored = snapshot();
+      const before = structuredClone(stored);
+      const mount = document.createElement("div"); document.body.appendChild(mount);
+      const fetchSpy = vi.spyOn(globalThis, "fetch");
+      controller = createAgentExperience(mount, {
+        apiUrl: "/test", launcher: { enabled: false }, webmcp: { enabled: true },
+        ...(source === "initial" ? { initialMessages: stored.messages, persistState: false } : source === "hook" ? { onStateLoaded: () => stored, persistState: false } : {
+          storageAdapter: { load: () => source === "async" ? Promise.resolve(stored) : stored, save: vi.fn(), clear: vi.fn() },
+        }),
+        features: { toolCallDisplay: { variant, grouped: true, groupedMode: "collapsible" } },
+        toolCall: { completeTextTemplate: "Finished {toolName} ~{duration}~" },
+      });
+      await vi.waitFor(() => expect(mount.textContent).toContain("chat restarted"));
+      expect(mount.querySelector('[data-action="allow"], [data-action="deny"], [data-approval-buttons]')).toBeNull();
+      expect(mount.querySelector('[data-tool-elapsed], [data-activity-state="running"], [data-activity-state="awaiting-approval"]')).toBeNull();
+      expect(mount.querySelector('[data-message-id="tool-1"]')?.textContent).toContain("Interrupted");
+      expect(mount.querySelector('[data-message-id="tool-1"]')?.textContent).not.toContain("Finished");
+      if (variant === "row") {
+        expect(mount.querySelector('[data-persona-tool-group]')?.getAttribute("data-activity-state")).toBe("interrupted");
+        expect(mount.textContent).toContain("2s");
+      }
+      if (source === "sync" || source === "async") expect(controller.getComposerState().text).toBe("My unsent proposal");
+      expect(stored).toEqual(before);
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+  });
+}
+
+it("keeps a cardless interrupted tool visible when completed rows are removed", async () => {
+  const stored = snapshot();
+  const mount = document.createElement("div"); document.body.appendChild(mount);
+  controller = createAgentExperience(mount, {
+    launcher: { enabled: false }, persistState: false,
+    initialMessages: [stored.messages![0]],
+    features: { toolCallDisplay: { variant: "row", completedVisibility: "removed" } },
+    toolCall: { renderCollapsedSummary: ({ createElapsedElement }) => createElapsedElement() },
+  });
+  expect(mount.querySelector('[data-message-id="tool-1"]')).not.toBeNull();
+  expect(mount.querySelector('[data-tool-elapsed]')).toBeNull();
+  expect(mount.textContent).toContain("chat restarted");
+});
+
+it("supports a custom approval renderer that only handles the original statuses", () => {
+  const labels = { pending: "Waiting", approved: "Allowed", denied: "Denied", timeout: "Expired" };
+  const mount = document.createElement("div"); document.body.appendChild(mount);
+  const render = vi.fn(({ message }: { message: AgentWidgetMessage }) => {
+    const node = document.createElement("span");
+    node.textContent = message.approval ? labels[message.approval.status] : "";
+    return node;
+  });
+  controller = createAgentExperience(mount, {
+    launcher: { enabled: false }, persistState: false,
+    initialMessages: [snapshot().messages![2]],
+    plugins: [{ id: "existing-approval-renderer", renderApproval: render }],
+  });
+  expect(mount.textContent).toContain("Expired");
+  expect(render).toHaveBeenCalled();
+  expect(render.mock.calls[0][0].message.approval).toMatchObject({ status: "timeout", interrupted: true });
+});
+
+it.each(["card", "row"] as const)("loading earlier messages retires browser activity in %s display", async variant => {
+  const stored = snapshot();
+  const before = structuredClone(stored);
+  const provider = createDemoHistoryProvider();
+  const summary = { id: "restored", title: "Restored", targetId: null, preview: "", createdAt: "2026-01-01", updatedAt: "2026-01-02", messageCount: 4 };
+  vi.spyOn(provider, "prepareOpen").mockResolvedValue({ conversationId: summary.id, conversationRevision: "r1", commit: vi.fn(), discard: vi.fn() });
+  vi.spyOn(provider, "getPage").mockImplementation(async (_id, options) => ({
+    summary, conversationRevision: "r1", nextCursor: options?.cursor ? null : "older",
+    messages: options?.cursor ? stored.messages! : [{ id: "newer", role: "assistant", content: "Newer reply", createdAt: "2026-01-02" }],
+  }));
+  const mount = document.createElement("div"); document.body.appendChild(mount);
+  const fetchSpy = vi.spyOn(globalThis, "fetch");
+  controller = createAgentExperience(mount, {
+    apiUrl: "/test", launcher: { enabled: false }, persistState: false,
+    features: { history: { enabled: true, provider }, toolCallDisplay: { variant, grouped: true } },
+  });
+  await controller.openConversation(summary.id);
+  const earlier = mount.querySelector<HTMLButtonElement>("[data-persona-history-earlier]");
+  expect(earlier).not.toBeNull();
+  earlier!.click();
+  await vi.waitFor(() => expect(mount.textContent).toContain("chat restarted"));
+  expect(mount.querySelector('[data-action="allow"], [data-action="deny"], [data-tool-elapsed], [data-activity-state="running"], [data-activity-state="awaiting-approval"]')).toBeNull();
+  expect(mount.textContent).toContain("Interrupted");
+  expect(mount.textContent).toContain("Newer reply");
+  expect(stored).toEqual(before);
+  expect(fetchSpy).not.toHaveBeenCalled();
+});
+
+it.each(["button", "controller"] as const)("restored server WebMCP approval uses its transport via %s", async route => {
+  const message = snapshot().messages![2];
+  message.approval!.executionId = "durable-exec";
+  const onDecision = vi.fn(async () => undefined);
+  const mount = document.createElement("div"); document.body.appendChild(mount);
+  controller = createAgentExperience(mount, {
+    launcher: { enabled: false }, persistState: false, initialMessages: [message], approval: { onDecision },
+  });
+  expect(onDecision).not.toHaveBeenCalled();
+  if (route === "button") mount.querySelector<HTMLButtonElement>('[data-action="allow"]')!.click();
+  else await controller.resolveApproval(message.approval!.id, "approved");
+  await vi.waitFor(() => expect(onDecision).toHaveBeenCalledTimes(1));
+  expect(onDecision.mock.calls[0]).toEqual([{
+    approvalId: "webmcp-1", executionId: "durable-exec", agentId: "", toolName: "webmcp:purchase",
+  }, "approved", undefined]);
+});

package/src/ui.scroll.test.ts

@@ -441,8 +441,9 @@ describe("createAgentExperience streaming scroll", () => {
     metrics.setScrollHeight(1080);
     emitStreamingMessage(controller, "Chunk two");
 
-    // Only run the scheduled auto-scroll frame, not the whole animation.
-    raf.step(1);
+    // Run the coalesced render frame and the auto-scroll frame it schedules,
+    // not the whole animation.
+    raf.step(2);
 
     expect(metrics.getScrollTop()).toBe(metrics.getBottomScrollTop());
 
@@ -1077,6 +1078,8 @@ describe("createAgentExperience streaming scroll", () => {
     // header of the streaming reply). No handoff.
     metrics.setScrollHeight(1284);
     emitStreamingMessage(controller, "Streaming response");
+    // Streaming updates render on the next animation frame.
+    raf.step(1);
     const streamBubble = scrollContainer!.querySelector<HTMLElement>(
       `[data-message-id="${STREAM_MESSAGE_ID}"]`
     );
@@ -1269,6 +1272,8 @@ describe("createAgentExperience streaming scroll", () => {
     // so the anchor hands off to the block: target = 600 - 16 = 584. This is
     // the stranded case the handoff exists for (tall send / tool prelude).
     emitStreamingMessage(controller, "Streaming response");
+    // Streaming updates render on the next animation frame.
+    raf.step(1);
     const streamBubble = scrollContainer!.querySelector<HTMLElement>(
       `[data-message-id="${STREAM_MESSAGE_ID}"]`
     );

package/src/ui.stream-replay.test.ts

@@ -0,0 +1,86 @@
+// @vitest-environment jsdom
+
+import { afterEach, expect, it, vi } from "vitest";
+
+import { createAgentExperience } from "./ui";
+import * as morph from "./utils/morph";
+
+vi.mock("./utils/morph", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("./utils/morph")>();
+  return { ...actual, morphMessages: vi.fn(actual.morphMessages) };
+});
+
+// A finished, tool-heavy agent run replayed through `connectStream` arrives as
+// one burst of already-queued frames. Each frame used to render the whole
+// transcript synchronously, so replay cost O(frames²) and crashed the tab
+// (#506). The burst now coalesces into a bounded number of render passes.
+const replayFrames = (pairs: number): string[] => {
+  const frames: string[] = [];
+  let seq = 0;
+  const push = (event: Record<string, unknown>) => {
+    seq += 1;
+    frames.push(
+      `id: ${seq}\nevent: ${event.type}\ndata: ${JSON.stringify({ ...event, seq, executionId: "exec_1" })}\n\n`
+    );
+  };
+  push({ type: "execution_start", kind: "agent", startedAt: new Date().toISOString() });
+  for (let index = 0; index < pairs; index += 1) {
+    const toolCallId = `call_${index}`;
+    push({
+      type: "tool_start",
+      toolCallId,
+      toolName: "get_item",
+      toolType: "mcp",
+      parameters: { id: `item_${index}` },
+      startedAt: new Date().toISOString(),
+    });
+    push({
+      type: "tool_complete",
+      toolCallId,
+      toolName: "get_item",
+      success: true,
+      result: `{"id":"item_${index}","description":"${"x".repeat(150)}"}`,
+      executionTime: 12,
+    });
+  }
+  push({
+    type: "execution_complete",
+    kind: "agent",
+    success: true,
+    outcome: "completed",
+    completedAt: new Date().toISOString(),
+  });
+  return frames;
+};
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  vi.mocked(morph.morphMessages).mockClear();
+});
+
+it("replays a long tool-heavy transcript in a bounded number of render passes", async () => {
+  const pairs = 200;
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  const controller = createAgentExperience(mount, {
+    apiUrl: "https://api.example.com/chat",
+    launcher: { enabled: false },
+    features: { showToolCalls: true, toolCallDisplay: { collapsedMode: "tool-name" } },
+  });
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream<Uint8Array>({
+    start(streamController) {
+      for (const frame of replayFrames(pairs)) streamController.enqueue(encoder.encode(frame));
+      streamController.close();
+    },
+  });
+  vi.mocked(morph.morphMessages).mockClear();
+
+  await controller.connectStream(stream);
+
+  expect(mount.querySelectorAll(".persona-tool-bubble")).toHaveLength(pairs);
+  expect(controller.getState().streaming).toBe(false);
+  // 2 × pairs frames; a handful of passes for stream start/end bookkeeping.
+  expect(vi.mocked(morph.morphMessages).mock.calls.length).toBeLessThan(10);
+  controller.destroy();
+});

package/src/ui.streaming-coalescing.test.ts

@@ -316,3 +316,186 @@ describe("pure streaming text update coalescing", () => {
     stream.close();
   });
 });
+
+describe("streaming tool update coalescing", () => {
+  const originalFetch = global.fetch;
+
+  beforeEach(() => {
+    window.scrollTo = vi.fn();
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  const sendToolPair = (stream: ReturnType<typeof createStreamHarness>, index: number) => {
+    const toolCallId = `call_${index}`;
+    stream.send("tool_start", {
+      executionId: "exec-1",
+      toolCallId,
+      toolName: "get_item",
+      toolType: "mcp",
+      parameters: { id: `item_${index}` },
+      startedAt: new Date().toISOString(),
+    });
+    stream.send("tool_complete", {
+      executionId: "exec-1",
+      toolCallId,
+      toolName: "get_item",
+      success: true,
+      result: `{"id":"item_${index}"}`,
+      executionTime: 12,
+    });
+  };
+
+  const toolRows = (mount: HTMLElement) => mount.querySelectorAll(".persona-tool-bubble").length;
+
+  it("renders a burst of tool frames once per animation frame", async () => {
+    const raf = installRafMock();
+    const stream = createStreamHarness();
+    global.fetch = stream.fetchMock;
+    const saves: AgentWidgetStoredState[] = [];
+    const { mount, controller } = createWidget((state) => saves.push(state));
+    await startTurn(mount);
+    stream.send("execution_start", { kind: "agent", executionId: "exec-1" });
+    await flushMicrotasks();
+    raf.flush();
+    const beforeBurst = saves.length;
+
+    for (let index = 0; index < 5; index += 1) sendToolPair(stream, index);
+    await flushMicrotasks(60);
+
+    expect(toolRows(mount)).toBe(0);
+    expect(saves).toHaveLength(beforeBurst);
+    raf.step();
+    expect(toolRows(mount)).toBe(5);
+    expect(saves).toHaveLength(beforeBurst + 1);
+
+    controller.destroy();
+    stream.close();
+  });
+
+  it("emits assistant:complete for a message that starts and finishes within one frame", async () => {
+    const raf = installRafMock();
+    const stream = createStreamHarness();
+    global.fetch = stream.fetchMock;
+    const { mount, controller } = createWidget(() => {});
+    const completed = vi.fn();
+    controller.on("assistant:complete", completed);
+    await startTurn(mount);
+
+    startText(stream, ["Hello", " world"]);
+    finishText(stream);
+    await flushMicrotasks(60);
+    raf.flush();
+
+    expect(controller.getState().streaming).toBe(false);
+    expect(completed).toHaveBeenCalledTimes(1);
+    expect(completed.mock.calls[0][0].content).toBe("Hello world");
+    controller.destroy();
+  });
+
+  it("leaves unchanged transcript rows in place across render passes", async () => {
+    const raf = installRafMock();
+    const stream = createStreamHarness();
+    global.fetch = stream.fetchMock;
+    const { mount, controller } = createWidget(() => {});
+    await startTurn(mount);
+    stream.send("execution_start", { kind: "agent", executionId: "exec-1" });
+    sendToolPair(stream, 0);
+    await flushMicrotasks(40);
+    raf.flush();
+
+    const firstRow = mount
+      .querySelector<HTMLElement>(".persona-tool-bubble")!
+      .closest<HTMLElement>("[data-wrapper-id]")!;
+    // A marker no render produces: re-morphing the row from the cache strips it.
+    firstRow.setAttribute("data-test-live", "true");
+
+    sendToolPair(stream, 1);
+    await flushMicrotasks(40);
+    raf.flush();
+
+    expect(toolRows(mount)).toBe(2);
+    const rowAfter = mount.querySelector<HTMLElement>(
+      `[data-wrapper-id="${firstRow.getAttribute("data-wrapper-id")}"]`
+    );
+    expect(rowAfter).toBe(firstRow);
+    expect(rowAfter?.getAttribute("data-test-live")).toBe("true");
+    expect(rowAfter?.querySelector(".persona-tool-bubble")).not.toBeNull();
+    controller.destroy();
+    stream.close();
+  });
+  it("saves the newest coalesced snapshot alongside the durable cursor", async () => {
+    const raf = installRafMock();
+    const saves: AgentWidgetStoredState[] = [];
+    const mount = document.createElement("div");
+    document.body.appendChild(mount);
+    const controller = createAgentExperience(mount, {
+      apiUrl: "https://api.example.com/chat",
+      clientToken: "ct_test",
+      launcher: { enabled: false },
+      storageAdapter: { save: (state) => { saves.push(state); } },
+    });
+    const at = (second: number) => `2026-07-11T00:00:0${second}.000Z`;
+    controller.injectTestMessage({ type: "status", status: "connecting" });
+    controller.injectTestMessage({
+      type: "message",
+      message: {
+        id: "reply-1",
+        role: "assistant",
+        content: "Working",
+        createdAt: at(0),
+        streaming: true,
+        agentMetadata: { executionId: "exec-1" },
+      },
+    });
+    controller.injectTestMessage({ type: "cursor", id: "1" });
+    raf.flush();
+    await flushMicrotasks();
+
+    // One SSE chunk: an approval (applied now, its save queued) then a tool
+    // update (coalesced to the next frame) that advances the cursor.
+    controller.injectTestMessage({
+      type: "message",
+      message: {
+        id: "approval-1",
+        role: "assistant",
+        content: "",
+        createdAt: at(1),
+        streaming: false,
+        variant: "approval",
+        approval: {
+          id: "approval-1",
+          status: "pending",
+          agentId: "agent-1",
+          executionId: "exec-1",
+          toolName: "Approve search",
+          description: "Approval test",
+        },
+      },
+    });
+    controller.injectTestMessage({
+      type: "message",
+      message: {
+        id: "tool-1",
+        role: "assistant",
+        content: "",
+        createdAt: at(2),
+        streaming: true,
+        variant: "tool",
+        toolCall: { id: "tool-1", name: "search", status: "running", chunks: [] },
+      },
+    });
+    controller.injectTestMessage({ type: "cursor", id: "2" });
+    await flushMicrotasks();
+
+    const saved = saves.at(-1)!;
+    expect(saved.metadata?.durableResume).toMatchObject({ after: "2" });
+    expect(saved.messages?.map((message) => message.id)).toContain("tool-1");
+    controller.destroy();
+  });
+});