@runtypelabs/persona 4.21.1 → 4.22.1

package/src/types.ts

@@ -826,6 +826,14 @@ export type ClientToolDefinition = {
     readOnlyHint?: boolean;
     untrustedContentHint?: boolean;
   };
+  /**
+   * Hoisted copy of `annotations.untrustedContentHint`. This is the field the
+   * server actually acts on (`InlineClientToolSchema`): it spotlights the
+   * tool's output before the model reads it, so instructions embedded in
+   * page-provided content (reviews, comments, emails) are not treated as
+   * instructions. `annotations` itself is trace/dashboard metadata only.
+   */
+  untrustedContentHint?: boolean;
 };
 
 /**
@@ -983,15 +991,15 @@ export type AgentMessageMetadata = {
    */
   parentStepId?: string;
   /**
-   * Set to `true` on a tool-variant message produced from a `step_await`
+   * Set to `true` on a tool-variant message produced from an `await`
    * event (`awaitReason: "local_tool_required"`). Signals to UI code that
    * the tool call is a LOCAL tool and the server is paused waiting for a
    * `POST /v1/dispatch/resume` with the user's answer keyed by tool name.
    */
   awaitingLocalTool?: boolean;
   /**
-   * The provider per-call id (`toolu_…`) carried on the `step_await` /
-   * `flow_await` events for a LOCAL tool (core#3878). Present only when the
+   * The provider per-call id (`toolu_…`) carried on the `await`
+   * event for a LOCAL tool (core#3878). Present only when the
    * server emits it. Two PARALLEL calls to the same tool in one turn share a
    * `toolName` (and a collapsed `toolId`) but get DISTINCT `webMcpToolCallId`s,
    * so this is the key the widget batches a single `/resume` on: preferred
@@ -2237,6 +2245,16 @@ export type AgentWidgetToolCallDisplayFeature = {
    * @default "stack"
    */
   groupedMode?: "stack" | "summary";
+  /**
+   * What happens to a tool call row once it completes.
+   *
+   * - `"kept"` (default): the finished row stays in the transcript.
+   * - `"removed"`: no row is rendered at all, so the transcript gap closes with
+   *   it. The tool call stays on the message and in `getMessages()`.
+   *
+   * @default "kept"
+   */
+  completedVisibility?: AgentWidgetToolCallCompletedVisibility;
   /**
    * When false, tool call bubbles show only the collapsed summary with no
    * expand/collapse toggle. Users see tool awareness without full details.
@@ -2255,6 +2273,9 @@ export type AgentWidgetToolCallDisplayFeature = {
   loadingAnimation?: AgentWidgetToolCallLoadingAnimation;
 };
 
+/** See `features.toolCallDisplay.completedVisibility`. */
+export type AgentWidgetToolCallCompletedVisibility = "kept" | "removed";
+
 export type AgentWidgetReasoningDisplayFeature = {
   /**
    * When true, active collapsed reasoning rows can render a lightweight preview block.
@@ -2300,14 +2321,30 @@ export type AgentWidgetReasoningDisplayFeature = {
    * - `"kept"` (default): the finished row stays in the transcript.
    * - `"removed"`: no row is rendered at all, so the transcript gap closes with
    *   it. The reasoning text stays on the message and in `getMessages()`.
+   * - `"removed-when-short"`: behaves as `"removed"` when the completed trace
+   *   is short (see `shortThinkThreshold`), and as `"kept"` otherwise.
    *
    * @default "kept"
    */
   completedVisibility?: AgentWidgetReasoningCompletedVisibility;
+  /**
+   * Thresholds used by `completedVisibility: "removed-when-short"` to decide
+   * whether a completed trace counts as short. Duration is checked first when
+   * the reasoning reports one; the character count is a fallback for traces
+   * with no reported duration.
+   * @default { durationMs: 15000, chars: 1200 }
+   */
+  shortThinkThreshold?: {
+    durationMs?: number;
+    chars?: number;
+  };
 };
 
 /** See `features.reasoningDisplay.completedVisibility`. */
-export type AgentWidgetReasoningCompletedVisibility = "kept" | "removed";
+export type AgentWidgetReasoningCompletedVisibility =
+  | "kept"
+  | "removed"
+  | "removed-when-short";
 
 /**
  * Reveal animation applied to assistant message text while it is streaming.
@@ -3381,7 +3418,7 @@ export type EventStreamConfig = {
   /**
    * Custom badge color mappings by event type prefix or exact type.
    * Keys are matched as exact match first, then prefix match (keys ending with "_").
-   * @example { "flow_": { bg: "#dcfce7", text: "#166534" }, "error": { bg: "#fecaca", text: "#991b1b" } }
+   * @example { "execution_": { bg: "#dcfce7", text: "#166534" }, "error": { bg: "#fecaca", text: "#991b1b" } }
    */
   badgeColors?: Record<string, EventStreamBadgeColor>;
   /**
@@ -4946,10 +4983,12 @@ export interface VoiceProvider {
    * `isFinal=false` is a live interim update (user partials, or assistant deltas
    * on providers that stream them); `isFinal=true` finalizes that role's text.
    * On the realtime `runtype` path, interim updates fire for the `user` only and
-   * the `assistant` arrives as a single final.
+   * the `assistant` arrives as a single final. Providers with overlapping turns
+   * must include the same turnId on user and assistant finals; without IDs,
+   * providers must discard cancelled output before emitting the next user final.
    */
   onTranscript?(
-    callback: (role: 'user' | 'assistant', text: string, isFinal: boolean) => void,
+    callback: (role: 'user' | 'assistant', text: string, isFinal: boolean, metadata?: { turnId?: string }) => void,
   ): void;
 
   /** Register a callback for per-turn latency metrics (realtime path). */
@@ -7524,16 +7563,16 @@ export type AgentWidgetConfig = {
    *
    * @example
    * ```typescript
-   * // For Runtype API format
+   * // For a custom backend (Runtype unified events are handled natively)
    * config: {
    *   parseSSEEvent: (data) => {
-   *     if ((data.type === 'step_delta' || data.type === 'step_chunk') && (data.delta || data.chunk)) {
-   *       return { text: data.delta ?? data.chunk };
+   *     if (data.type === 'token' && typeof data.value === 'string') {
+   *       return { text: data.value };
    *     }
-   *     if (data.type === 'flow_complete') {
+   *     if (data.type === 'done') {
    *       return { done: true };
    *     }
-   *     if (data.type === 'step_error') {
+   *     if (data.type === 'failure') {
    *       return { error: data.error };
    *     }
    *     return null; // Ignore other events
@@ -7750,7 +7789,7 @@ export type AgentWidgetReasoning = {
   /**
    * Reasoning channel scope (wire spec). `"turn"` is ordinary per-turn
    * thinking; `"loop"` is a cross-iteration agent reflection (the fold that
-   * replaced the legacy `agent_reflection` event). Absent for legacy streams.
+   * replaced the legacy `agent_reflection` event). Optional when the stream does not specify a scope.
    */
   scope?: "turn" | "loop";
   startedAt?: number;
@@ -7765,6 +7804,9 @@ export type AgentWidgetToolCall = {
   args?: unknown;
   chunks?: string[];
   result?: unknown;
+  /** Whether the tool succeeded; failure does not necessarily end the execution. */
+  success?: boolean;
+  error?: string;
   duration?: number;
   startedAt?: number;
   completedAt?: number;
@@ -7798,7 +7840,7 @@ export type AgentWidgetMessageVariant = "assistant" | "reasoning" | "tool" | "ap
 
 /**
  * Per-turn / per-step stop reason emitted by the runtime on
- * `agent_turn_complete` and `step_complete` SSE events. The vocabulary is
+ * `turn_complete` and `step_complete` SSE events. The vocabulary is
  * owned by the upstream Runtype API: do not extend without coordination.
  *
  * - `end_turn`: natural completion (no affordance needed)
@@ -7930,7 +7972,7 @@ export type AgentWidgetMessage = {
    */
   agentMetadata?: AgentMessageMetadata;
   /**
-   * Per-turn stop reason reported by the runtime on `agent_turn_complete`
+   * Per-turn stop reason reported by the runtime on `turn_complete`
    * (agent-loop path) or the last `step_complete` for a prompt step
    * (dispatch / flow path). Absent when the API did not report a value.
    *

package/src/ui.ask-user-question-plugin.test.ts

@@ -174,7 +174,7 @@ describe("renderAskUserQuestion plugin hook", () => {
       ok: true,
       body: new ReadableStream({
         start(c) {
-          c.enqueue(new TextEncoder().encode('data: {"type":"flow_complete","success":true}\n\n'));
+          c.enqueue(new TextEncoder().encode('data: {"type":"execution_complete","success":true}\n\n'));
           c.close();
         },
       }),
@@ -217,7 +217,7 @@ describe("renderAskUserQuestion plugin hook", () => {
       ok: true,
       body: new ReadableStream({
         start(c) {
-          c.enqueue(new TextEncoder().encode('data: {"type":"flow_complete","success":true}\n\n'));
+          c.enqueue(new TextEncoder().encode('data: {"type":"execution_complete","success":true}\n\n'));
           c.close();
         },
       }),
@@ -284,7 +284,7 @@ describe("renderAskUserQuestion plugin hook", () => {
       ok: true,
       body: new ReadableStream({
         start(c) {
-          c.enqueue(new TextEncoder().encode('data: {"type":"flow_complete","success":true}\n\n'));
+          c.enqueue(new TextEncoder().encode('data: {"type":"execution_complete","success":true}\n\n'));
           c.close();
         },
       }),
@@ -366,7 +366,7 @@ describe("renderAskUserQuestion plugin hook", () => {
       ok: true,
       body: new ReadableStream({
         start(c) {
-          c.enqueue(new TextEncoder().encode('data: {"type":"flow_complete","success":true}\n\n'));
+          c.enqueue(new TextEncoder().encode('data: {"type":"execution_complete","success":true}\n\n'));
           c.close();
         },
       }),
@@ -434,7 +434,7 @@ describe("renderAskUserQuestion plugin hook", () => {
       ok: true,
       body: new ReadableStream({
         start(c) {
-          c.enqueue(new TextEncoder().encode('data: {"type":"flow_complete","success":true}\n\n'));
+          c.enqueue(new TextEncoder().encode('data: {"type":"execution_complete","success":true}\n\n'));
           c.close();
         },
       }),
@@ -631,7 +631,7 @@ describe("renderAskUserQuestion plugin hook", () => {
       ok: true,
       body: new ReadableStream({
         start(c) {
-          c.enqueue(new TextEncoder().encode('data: {"type":"flow_complete","success":true}\n\n'));
+          c.enqueue(new TextEncoder().encode('data: {"type":"execution_complete","success":true}\n\n'));
           c.close();
         },
       }),
@@ -645,7 +645,7 @@ describe("renderAskUserQuestion plugin hook", () => {
       ok: true,
       body: new ReadableStream({
         start(c) {
-          c.enqueue(new TextEncoder().encode('data: {"type":"flow_complete","success":true}\n\n'));
+          c.enqueue(new TextEncoder().encode('data: {"type":"execution_complete","success":true}\n\n'));
           c.close();
         },
       }),

package/src/ui.composer-defer-one.test.ts

@@ -3,42 +3,14 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { createAgentExperience } from "./ui";
-import { createUnifiedEventWrite } from "./utils/__fixtures__/unified-translator.oracle";
-
-const legacyEvent = (type: string, data: Record<string, unknown>) =>
-  `event: ${type}\ndata: ${JSON.stringify({ type, ...data })}\n\n`;
+import { buildAssistantTurnFrames } from "./testing/mock-stream";
 
 /** One complete assistant turn, in the same wire shape the widget expects. */
-const unifiedFrames = (): string => {
-  let out = "";
-  const write = createUnifiedEventWrite((chunk) => {
-    out += chunk;
-  });
-  write(legacyEvent("flow_start", { flowId: "flow_1", flowName: "T", totalSteps: 1 }));
-  write(
-    legacyEvent("step_start", {
-      id: "step_1",
-      name: "Prompt",
-      stepType: "prompt",
-      index: 0,
-      totalSteps: 1,
-    })
-  );
-  write(legacyEvent("text_start", { messageId: "message_1" }));
-  write(legacyEvent("step_delta", { id: "step_1", text: "answer" }));
-  write(legacyEvent("text_end", { messageId: "message_1" }));
-  write(
-    legacyEvent("step_complete", {
-      id: "step_1",
-      name: "Prompt",
-      stepType: "prompt",
-      success: true,
-      result: { response: "answer" },
-    })
-  );
-  write(legacyEvent("flow_complete", { flowId: "flow_1", success: true }));
-  return out;
-};
+const unifiedFrames = (): string => [
+  { type: "execution_start", executionId: "exec-1", kind: "agent" },
+  ...buildAssistantTurnFrames({ executionId: "exec-1", text: "answer" }),
+  { type: "execution_complete", executionId: "exec-1", kind: "agent", success: true },
+].map((frame) => `data: ${JSON.stringify(frame)}\n\n`).join("");
 
 const mounts: HTMLElement[] = [];
 const controllers: ReturnType<typeof createAgentExperience>[] = [];

package/src/ui.composer-draft-persistence.test.ts

@@ -17,7 +17,7 @@ const streamResponse = () => {
     body: new ReadableStream({
       start(controller) {
         controller.enqueue(
-          encoder.encode('data: {"type":"flow_complete","success":true}\n\n')
+          encoder.encode('data: {"type":"execution_complete","success":true}\n\n')
         );
         controller.close();
       },

package/src/ui.composer-quote.test.ts

@@ -17,7 +17,7 @@ const streamResponse = () => {
     body: new ReadableStream({
       start(controller) {
         controller.enqueue(
-          encoder.encode('data: {"type":"flow_complete","success":true}\n\n')
+          encoder.encode('data: {"type":"execution_complete","success":true}\n\n')
         );
         controller.close();
       },

package/src/ui.message-history-actions.test.ts

@@ -17,7 +17,7 @@ const streamResponse = () => {
     body: new ReadableStream({
       start(controller) {
         controller.enqueue(
-          encoder.encode('data: {"type":"flow_complete","success":true}\n\n')
+          encoder.encode('data: {"type":"execution_complete","success":true}\n\n')
         );
         controller.close();
       },

package/src/ui.reasoning-display.test.ts

@@ -25,7 +25,8 @@ const injectReasoning = (
   controller: ReturnType<typeof createAgentExperience>,
   id: string,
   status: "streaming" | "complete",
-  chunks: string[] = ["Weighing the options"]
+  chunks: string[] = ["Weighing the options"],
+  durationMs?: number
 ) => {
   controller.injectTestMessage({
     type: "message",
@@ -36,7 +37,26 @@ const injectReasoning = (
       createdAt: new Date().toISOString(),
       streaming: status !== "complete",
       variant: "reasoning",
-      reasoning: { id, status, chunks },
+      reasoning: { id, status, chunks, durationMs },
+    },
+  });
+};
+
+const injectToolCall = (
+  controller: ReturnType<typeof createAgentExperience>,
+  id: string,
+  status: "pending" | "running" | "complete"
+) => {
+  controller.injectTestMessage({
+    type: "message",
+    message: {
+      id,
+      role: "assistant",
+      content: "",
+      createdAt: new Date().toISOString(),
+      streaming: status !== "complete",
+      variant: "tool",
+      toolCall: { id, name: "search", status, chunks: [] },
     },
   });
 };
@@ -161,4 +181,118 @@ describe("features.reasoningDisplay.completedVisibility", () => {
         ?.chunks
     ).toEqual(["Weighing the options"]);
   });
+
+  it('"removed-when-short" drops a completed trace with a short reported duration', () => {
+    const { mount, controller } = makeController({
+      features: { reasoningDisplay: { completedVisibility: "removed-when-short" } },
+    });
+    injectReasoning(controller, "r1", "complete", ["Weighing the options"], 5_000);
+    expect(rowOf(mount, "r1")).toBeNull();
+  });
+
+  it('"removed-when-short" keeps a completed trace with a long reported duration', () => {
+    const { mount, controller } = makeController({
+      features: { reasoningDisplay: { completedVisibility: "removed-when-short" } },
+    });
+    injectReasoning(controller, "r1", "complete", ["Weighing the options"], 20_000);
+    expect(rowOf(mount, "r1")).not.toBeNull();
+  });
+
+  it('"removed-when-short" drops a completed trace with no duration and few chars', () => {
+    const { mount, controller } = makeController({
+      features: { reasoningDisplay: { completedVisibility: "removed-when-short" } },
+    });
+    injectReasoning(controller, "r1", "complete", ["Short thought"]);
+    expect(rowOf(mount, "r1")).toBeNull();
+  });
+
+  it('"removed-when-short" keeps a completed trace with no duration and many chars', () => {
+    const { mount, controller } = makeController({
+      features: { reasoningDisplay: { completedVisibility: "removed-when-short" } },
+    });
+    injectReasoning(controller, "r1", "complete", ["x".repeat(1_500)]);
+    expect(rowOf(mount, "r1")).not.toBeNull();
+  });
+
+  it('"removed-when-short" honors custom duration and char thresholds', () => {
+    const { mount, controller } = makeController({
+      features: {
+        reasoningDisplay: {
+          completedVisibility: "removed-when-short",
+          shortThinkThreshold: { durationMs: 1_000, chars: 50 },
+        },
+      },
+    });
+    // 5s exceeds the custom 1s threshold, so this long-by-default trace is kept.
+    injectReasoning(controller, "r1", "complete", ["Weighing the options"], 5_000);
+    expect(rowOf(mount, "r1")).not.toBeNull();
+
+    // 60 chars exceeds the custom 50-char threshold, so this trace is kept too.
+    injectReasoning(controller, "r2", "complete", ["y".repeat(60)]);
+    expect(rowOf(mount, "r2")).not.toBeNull();
+
+    // Under both custom thresholds, so this trace is dropped.
+    injectReasoning(controller, "r3", "complete", ["z".repeat(10)], 500);
+    expect(rowOf(mount, "r3")).toBeNull();
+  });
+});
+
+describe("features.toolCallDisplay.completedVisibility", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    vi.stubGlobal("requestAnimationFrame", (cb: (time: number) => void) => {
+      cb(0);
+      return 1;
+    });
+    vi.stubGlobal("cancelAnimationFrame", () => {});
+    window.scrollTo = vi.fn();
+  });
+
+  afterEach(() => {
+    controllers.splice(0).forEach((controller) => controller.destroy());
+    mounts.splice(0).forEach((mount) => mount.remove());
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("keeps a finished tool call row by default", () => {
+    const { mount, controller } = makeController();
+    injectToolCall(controller, "t1", "complete");
+    expect(rowOf(mount, "t1")).not.toBeNull();
+  });
+
+  it('removes the whole row under "removed", leaving no transcript gap', () => {
+    const { mount, controller } = makeController({
+      features: { toolCallDisplay: { completedVisibility: "removed" } },
+    });
+    injectToolCall(controller, "t1", "complete");
+    injectText(controller, "a1", "Here is the answer");
+
+    expect(rowOf(mount, "t1")).toBeNull();
+    const rows = mount.querySelectorAll("[data-wrapper-id]");
+    expect(Array.from(rows).map((row) => row.getAttribute("data-wrapper-id")))
+      .toEqual(["a1"]);
+  });
+
+  it('shows a running tool call under "removed" and drops it once it completes', () => {
+    const { mount, controller } = makeController({
+      features: { toolCallDisplay: { completedVisibility: "removed" } },
+    });
+    injectToolCall(controller, "t1", "running");
+    expect(rowOf(mount, "t1")).not.toBeNull();
+
+    injectToolCall(controller, "t1", "complete");
+    expect(rowOf(mount, "t1")).toBeNull();
+  });
+
+  it('keeps the tool call message in the session under "removed"', () => {
+    const { controller } = makeController({
+      features: { toolCallDisplay: { completedVisibility: "removed" } },
+    });
+    injectToolCall(controller, "t1", "complete");
+    expect(
+      controller.getMessages().find((message) => message.id === "t1")?.toolCall
+        ?.status
+    ).toEqual("complete");
+  });
 });

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

@@ -4,7 +4,6 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import { createAgentExperience } from "./ui";
 import type { AgentWidgetStoredState } from "./types";
-import { createUnifiedEventWrite } from "./utils/__fixtures__/unified-translator.oracle";
 
 // The approval UI ships in a lazy chunk; provide it eagerly so this file's
 // synchronous render assertions hold. Per-file module isolation keeps the
@@ -48,7 +47,7 @@ const flushMicrotasks = async (times = 20) => {
   }
 };
 
-const legacyEvent = (type: string, data: Record<string, unknown>) =>
+const sseEvent = (type: string, data: Record<string, unknown>) =>
   `event: ${type}\ndata: ${JSON.stringify({ type, ...data })}\n\n`;
 
 const createStreamHarness = () => {
@@ -59,9 +58,7 @@ const createStreamHarness = () => {
     new Response(new ReadableStream<Uint8Array>({
       start(streamController) {
         controller = streamController;
-        write = createUnifiedEventWrite((chunk) => {
-          streamController.enqueue(encoder.encode(chunk));
-        });
+        write = (chunk) => streamController.enqueue(encoder.encode(chunk));
       },
     }))
   );
@@ -69,7 +66,7 @@ const createStreamHarness = () => {
     fetchMock,
     send(type: string, data: Record<string, unknown>) {
       if (!write) throw new Error("stream not started");
-      write(legacyEvent(type, data));
+      write(sseEvent(type, data));
     },
     close() {
       controller?.close();
@@ -85,7 +82,7 @@ const startTurn = async (mount: HTMLElement) => {
 };
 
 const startText = (stream: ReturnType<typeof createStreamHarness>, deltas: string[]) => {
-  stream.send("flow_start", { flowId: "flow_1", flowName: "Test", totalSteps: 1 });
+  stream.send("execution_start", { kind: "flow", executionId: "exec-1", flowId: "flow_1", flowName: "Test", totalSteps: 1 });
   stream.send("step_start", {
     id: "step_1",
     name: "Prompt",
@@ -93,12 +90,12 @@ const startText = (stream: ReturnType<typeof createStreamHarness>, deltas: strin
     index: 0,
     totalSteps: 1,
   });
-  stream.send("text_start", { messageId: "message_1" });
-  deltas.forEach((text) => stream.send("step_delta", { id: "step_1", text }));
+  stream.send("text_start", { id: "message_1" });
+  deltas.forEach((text) => stream.send("text_delta", { id: "message_1", delta: text }));
 };
 
 const finishText = (stream: ReturnType<typeof createStreamHarness>) => {
-  stream.send("text_end", { messageId: "message_1" });
+  stream.send("text_complete", { id: "message_1" });
   stream.send("step_complete", {
     id: "step_1",
     name: "Prompt",
@@ -106,7 +103,7 @@ const finishText = (stream: ReturnType<typeof createStreamHarness>) => {
     success: true,
     result: { response: "Hello world" },
   });
-  stream.send("flow_complete", { flowId: "flow_1", success: true });
+  stream.send("execution_complete", { kind: "flow", executionId: "exec-1", flowId: "flow_1", success: true });
   stream.close();
 };
 
@@ -145,8 +142,8 @@ describe("pure streaming text update coalescing", () => {
     startText(stream, ["Hel"]);
     await flushMicrotasks();
     const afterFirstDelta = saves.length;
-    stream.send("step_delta", { id: "step_1", text: "lo" });
-    stream.send("step_delta", { id: "step_1", text: " world" });
+    stream.send("text_delta", { id: "message_1", delta: "lo" });
+    stream.send("text_delta", { id: "message_1", delta: " world" });
     await flushMicrotasks();
 
     expect(saves).toHaveLength(afterFirstDelta);