@runtypelabs/persona 4.21.1 → 4.22.1

package/src/session.ts

@@ -78,7 +78,8 @@ import {
   ReadAloudController,
   type ReadAloudListener,
 } from "./voice/read-aloud-controller";
-import { isVoiceSupportedProbe } from "./utils/voice-support";
+import { isVoiceSupportedProbe, usesSessionVoice, voiceConnectionChanged } from "./utils/voice-support";
+import { VoiceTurnTracker } from "./voice/voice-turn-tracker";
 import { loadVoiceRuntime } from "./voice-runtime-loader";
 import { resolveSpeakableText } from "./utils/speech-text";
 import { loadRuntypeTts } from "./voice/runtype-tts-loader";
@@ -275,7 +276,7 @@ const getWebMcpErrorMessage = (
 };
 
 /**
- * Tool names whose `step_await` the widget resolves automatically (no user
+ * Tool names whose `await` the widget resolves automatically (no user
  * pill click): `webmcp:*` page tools and the built-in fire-and-forget
  * `suggest_replies`. These share the await-batch / dedupe / resume machinery;
  * `ask_user_question` is NOT one of them: it blocks on the answer sheet.
@@ -334,7 +335,7 @@ export class AgentWidgetSession {
   //                         concurrent re-fire during the resolve round-trip.
   //   webMcpResolvedKeys: /resume HTTP returned 2xx; not cleared on a new
   //                         dispatch (executionId scoping makes that
-  //                         unnecessary). Blocks stale step_await re-emits
+  //                         unnecessary). Blocks stale await re-emits
   //                         for the same execution.
   //
   // If `/resume` throws (network error, server 5xx), we DO want a retry path:
@@ -343,10 +344,10 @@ export class AgentWidgetSession {
   private webMcpInflightKeys: Set<string> = new Set();
   private webMcpResolvedKeys: Set<string> = new Set();
   // Per-resolve AbortControllers, kept in a set so multiple `webmcp:*`
-  // step_await resolves in one turn never abort one another. The shared
+  // await resolves in one turn never abort one another. The shared
   // `this.abortController` is intentionally NOT used by resolveWebMcpToolCall:
   // in a CHAINED turn (tool A → /resume → tool B, where the server emits B's
-  // step_await inside A's resume SSE stream) the shared controller is still
+  // await inside A's resume SSE stream) the shared controller is still
   // piping A's resume stream: the very stream that just delivered B. Aborting
   // it mid-chain (the prior shared-controller pre-abort) tore that stream down,
   // so B never reached execute() and its /resume was never POSTed, pausing the
@@ -369,7 +370,7 @@ export class AgentWidgetSession {
     new Map();
   private webMcpApprovalSeq = 0;
   // Parallel local-tool batching (core#3878). A single model turn can emit
-  // multiple `step_await(local_tool_required)` events for ONE paused
+  // multiple `await(local_tool_required)` events for ONE paused
   // executionId: including two PARALLEL calls to the SAME tool ("add SHOE-001
   // and SHOE-007"). Those collapse to an identical `toolId`/`index` and differ
   // only by the per-call `webMcpToolCallId`. We collect all awaits for an
@@ -377,7 +378,7 @@ export class AgentWidgetSession {
   // keyed by `webMcpToolCallId`: NOT one `/resume` per tool keyed by name
   // (which collides for same-tool calls, and whose concurrent posts on one
   // execution raced → the second 404'd → the turn hung). Keyed by executionId;
-  // `seen` dedupes duplicate step_await re-emits within a batch. Cleared on
+  // `seen` dedupes duplicate await re-emits within a batch. Cleared on
   // every teardown via `abortWebMcpResolves`.
   private webMcpAwaitBatches: Map<
     string,
@@ -576,6 +577,7 @@ export class AgentWidgetSession {
    */
   public stopVoicePlayback(): void {
     if (this.voiceProvider?.stopPlayback) {
+      this.voiceTurns.cancel();
       this.voiceProvider.stopPlayback();
     }
   }
@@ -595,6 +597,8 @@ export class AgentWidgetSession {
   // Pending placeholder IDs for Runtype two-phase voice flow
   private pendingVoiceUserMessageId: string | null = null;
   private pendingVoiceAssistantMessageId: string | null = null;
+  private voiceTurns = new VoiceTurnTracker();
+  private voiceDisconnectPromise: Promise<void> = Promise.resolve();
 
   // Track message IDs where the Runtype provider already played TTS audio
   // so browser TTS doesn't double-speak them
@@ -688,6 +692,9 @@ export class AgentWidgetSession {
         throw new Error('Voice configuration not provided');
       }
 
+      this.cleanupVoice();
+      const disconnected = this.voiceDisconnectPromise;
+
       // The provider runtime ships in the lazy voice-runtime chunk. The sync
       // signature is preserved: construction + wiring + connect() happen when
       // the chunk resolves (prefetched at session construction when a
@@ -696,7 +703,8 @@ export class AgentWidgetSession {
       // discarded via the generation token.
       const generation = ++this.voiceSetupGeneration;
       this.voiceSetupPromise = loadVoiceRuntime()
-        .then((mod) => {
+        .then(async (mod) => {
+          await disconnected;
           if (generation !== this.voiceSetupGeneration) return;
           this.wireVoiceProvider(mod.createVoiceProvider(voiceConfig));
         })
@@ -717,6 +725,8 @@ export class AgentWidgetSession {
   private wireVoiceProvider(provider: VoiceProvider): void {
     try {
       this.voiceProvider = provider;
+      const generation = this.voiceSetupGeneration;
+      const isCurrent = () => this.voiceProvider === provider && generation === this.voiceSetupGeneration;
 
       // Read configurable text from widget config
       const voiceRecognitionConfig = this.config.voiceRecognition ?? {};
@@ -727,6 +737,7 @@ export class AgentWidgetSession {
       // via the standard SSE chat path. Only the realtime `runtype` provider is
       // excluded here: it owns the whole turn and drives onTranscript below.
       this.voiceProvider.onResult((result) => {
+        if (!isCurrent()) return;
         if (result.provider !== 'runtype') {
           if (result.text && result.text.trim()) {
             this.sendMessage(result.text, { viaVoice: true });
@@ -741,7 +752,8 @@ export class AgentWidgetSession {
       // In-flight bubbles carry voiceProcessing=true so consumers can style
       // them via messageTransform; it clears once the text is final.
       if (this.voiceProvider.onTranscript) {
-        this.voiceProvider.onTranscript((role, text, isFinal) => {
+        this.voiceProvider.onTranscript((role, text, isFinal, metadata) => {
+          if (!isCurrent()) return;
           if (role === 'user') {
             if (!this.pendingVoiceUserMessageId) {
               const msg = this.injectMessage({
@@ -763,6 +775,7 @@ export class AgentWidgetSession {
             }
 
             if (isFinal) {
+              this.voiceTurns.start(metadata?.turnId);
               // User finished: the agent is now thinking. Release the user
               // bubble (a new interim starts a fresh turn) and show a typing
               // indicator in a fresh assistant placeholder.
@@ -777,6 +790,7 @@ export class AgentWidgetSession {
               this.setStreaming(true);
             }
           } else {
+            if (!this.voiceTurns.accepts(metadata?.turnId)) return;
             // assistant: runtype sends a single final; the isFinal=false path
             // is reserved for delta-streaming providers (future BYO).
             if (this.pendingVoiceAssistantMessageId) {
@@ -816,6 +830,7 @@ export class AgentWidgetSession {
       // not forwarded per callback: the UI samples it on its own frame loop.
       if (this.voiceProvider.onLevel) {
         this.voiceProvider.onLevel((level) => {
+          if (!isCurrent()) return;
           this.voiceLevel = Number.isFinite(level)
             ? Math.max(0, Math.min(1, level))
             : 0;
@@ -825,11 +840,13 @@ export class AgentWidgetSession {
       // Surface per-turn latency metrics to the optional config hook.
       if (this.voiceProvider.onMetrics) {
         this.voiceProvider.onMetrics((metrics) => {
+          if (!isCurrent()) return;
           this.config.voiceRecognition?.onMetrics?.(metrics);
         });
       }
 
       this.voiceProvider.onError((error) => {
+        if (!isCurrent()) return;
         console.error('Voice error:', error);
 
         // If error occurs while placeholders are pending, update assistant with error text
@@ -849,8 +866,12 @@ export class AgentWidgetSession {
       });
 
       this.voiceProvider.onStatusChange((status) => {
+        if (!isCurrent()) return;
         this.voiceStatus = status;
         this.voiceActive = status === 'listening';
+        if (status === 'listening' || status === 'idle' || status === 'disconnected') {
+          this.settlePendingVoiceTurn(status !== 'listening');
+        }
         this.callbacks.onVoiceStatusChanged?.(status);
       });
 
@@ -892,14 +913,44 @@ export class AgentWidgetSession {
    * Cleanup voice resources
    */
   public cleanupVoice() {
+    const notifyDisconnected = this.voiceProvider !== null;
     this.voiceSetupGeneration++;
     this.voiceSetupPromise = null;
     if (this.voiceProvider) {
-      this.voiceProvider.disconnect();
+      const provider = this.voiceProvider;
       this.voiceProvider = null;
+      this.voiceDisconnectPromise = this.disconnectVoice(provider);
     }
     this.voiceActive = false;
     this.voiceStatus = 'disconnected';
+    this.settlePendingVoiceTurn(true);
+    this.voiceTurns = new VoiceTurnTracker();
+    if (notifyDisconnected) this.callbacks.onVoiceStatusChanged?.('disconnected');
+  }
+
+  private async disconnectVoice(provider: VoiceProvider): Promise<void> {
+    try {
+      await provider.disconnect();
+    } catch (error) {
+      console.error('Failed to disconnect voice:', error);
+    }
+  }
+
+  private settlePendingVoiceTurn(includeUser: boolean): void {
+    const userId = includeUser ? this.pendingVoiceUserMessageId : null;
+    const assistantId = this.pendingVoiceAssistantMessageId;
+    if (!userId && !assistantId) return;
+    if (assistantId) this.voiceTurns.cancel();
+    if (includeUser) this.pendingVoiceUserMessageId = null;
+    this.pendingVoiceAssistantMessageId = null;
+    if (assistantId) this.ttsSpokenMessageIds.add(assistantId);
+    this.messages = this.messages.flatMap((message) => {
+      if (message.id !== userId && message.id !== assistantId) return [message];
+      if (message.id === assistantId && !message.content.trim()) return [];
+      return [{ ...message, streaming: false, voiceProcessing: false }];
+    });
+    this.callbacks.onMessagesChanged([...this.messages]);
+    if (assistantId) this.setStreaming(false);
   }
 
   /**
@@ -1088,6 +1139,7 @@ export class AgentWidgetSession {
 
   /** Widget teardown: release the visitor-store subscription. */
   public destroy(): void {
+    this.cleanupVoice();
     this.visitorStoreUnsubscribe?.();
     this.visitorStoreUnsubscribe = null;
     this.subscribedVisitorStore = null;
@@ -2103,6 +2155,15 @@ export class AgentWidgetSession {
   public updateConfig(next: AgentWidgetConfig) {
     const previousArtifactDisplay = this.config.features?.artifacts?.display;
     const merged = { ...this.config, ...next };
+    const replaceVoice = voiceConnectionChanged(this.config, merged);
+    const replaceClient = connectionConfigChanged(this.config, merged);
+    this.config = merged;
+    if (replaceVoice) {
+      this.cleanupVoice();
+      if (merged.voiceRecognition?.enabled === true && usesSessionVoice(merged.voiceRecognition.provider)) {
+        this.setupVoice();
+      }
+    }
     const artifactDisplayChanged =
       JSON.stringify(previousArtifactDisplay) !==
       JSON.stringify(merged.features?.artifacts?.display);
@@ -2114,8 +2175,7 @@ export class AgentWidgetSession {
     // self-styling widget work: a `webmcp:*` theme tool mutates config and
     // re-renders mid-turn; recreating the client there would abort the very
     // turn that's restyling the widget and strand the paused execution.
-    if (!connectionConfigChanged(this.config, merged)) {
-      this.config = merged;
+    if (!replaceClient) {
       this.client.updateConfig(merged);
       if (artifactDisplayChanged) this.refreshArtifactReferenceBlocks();
       return;
@@ -2132,7 +2192,6 @@ export class AgentWidgetSession {
     this.webMcpInflightKeys.clear();
     this.webMcpResolvedKeys.clear();
     const prevSSECallback = this.client.getSSEEventCallback();
-    this.config = merged;
     this.client = new AgentWidgetClient(this.config, this.historyInternals);
     if (artifactDisplayChanged) this.refreshArtifactReferenceBlocks();
     this.wireDefaultWebMcpConfirm();
@@ -3169,7 +3228,7 @@ export class AgentWidgetSession {
   /**
    * Resolve a paused `ask_user_question` LOCAL tool call.
    *
-   * When the server emits `step_await` for `ask_user_question`, the widget
+   * When the server emits `await` for `ask_user_question`, the widget
    * renders the answer-pill sheet and calls this method once the user
    * picks. Steps:
    *   1. POST the answer to `/resume` via `client.resumeFlow`.
@@ -3389,10 +3448,10 @@ export class AgentWidgetSession {
   }
 
   /**
-   * Collect an auto-resolving LOCAL-tool `step_await` (`webmcp:*` page tools
+   * Collect an auto-resolving LOCAL-tool `await` (`webmcp:*` page tools
    * and the built-in `suggest_replies`) into a per-executionId batch
    * and schedule a single deferred flush. Parallel calls (core#3878) emit
-   * several `step_await`s for ONE paused execution within the same stream tick;
+   * several `await`s for ONE paused execution within the same stream tick;
    * buffering them and flushing once lets us post ONE `/resume` keyed by the
    * per-call `webMcpToolCallId` rather than racing N name-keyed resumes on the
    * same execution (which 404'd on the second and hung the turn).
@@ -3423,14 +3482,14 @@ export class AgentWidgetSession {
       batch = { snapshots: [], seen: new Set() };
       this.webMcpAwaitBatches.set(executionId, batch);
     }
-    // Duplicate step_await re-emit for a call already in this batch: ignore.
+    // Duplicate await re-emit for a call already in this batch: ignore.
     if (batch.seen.has(callId)) return;
     batch.seen.add(callId);
     batch.snapshots.push(toolMessage);
     // NB: no flush is scheduled here. Flushing happens once the stream that is
     // delivering these awaits ENDS (handleEvent's `status: idle` →
     // scheduleWebMcpBatchFlush). Flushing per-await on the next microtask would
-    // race SSE chunk boundaries: two PARALLEL step_awaits split across separate
+    // race SSE chunk boundaries: two PARALLEL awaits split across separate
     // `read()` chunks would flush the first alone and post a partial resume.
     // Waiting for stream end guarantees every parallel await is collected first.
   }
@@ -3438,7 +3497,7 @@ export class AgentWidgetSession {
   /**
    * Flush every buffered local-tool await batch, one `/resume` per executionId.
    * Called once a stream ends (`status: idle` / `error`): by then all parallel
-   * `step_await`s the stream carried have been collected, even if split across
+   * `await`s the stream carried have been collected, even if split across
    * SSE chunks. Deferred via `queueMicrotask` (epoch-guarded) so the idle
    * handler returns first and the stream's end-of-stream teardown (streaming /
    * abortController) settles before a resolve grabs them: the same ordering the
@@ -3495,7 +3554,7 @@ export class AgentWidgetSession {
    * Persisted-resolution guard for `suggest_replies`. The in-memory dedupe
    * sets (`webMcpInflightKeys` / `webMcpResolvedKeys`) are cleared by
    * hydrateMessages/clearMessages/cancel, but `suggestRepliesResolved`
-   * survives on the stored message, so a stale `step_await` re-emit after a
+   * survives on the stored message, so a stale `await` re-emit after a
    * hydration must not re-POST `/resume` for an already-resolved call (the
    * historical double-resume failure mode the batching work exists to avoid).
    * Checks the LIVE message first; the handleEvent snapshot is a fresh wire
@@ -3631,7 +3690,7 @@ export class AgentWidgetSession {
       claimedKeys.push(dedupeKey);
 
       // Clear the awaiting flag and keep the tool bubble running while the
-      // browser-side WebMCP promise is in flight. The initial `step_await`
+      // browser-side WebMCP promise is in flight. The initial `await`
       // only means the server paused for a local tool; it is not completion.
       const startedAt = this.markWebMcpToolRunning(toolMessage);
 
@@ -3809,12 +3868,12 @@ export class AgentWidgetSession {
    * resumes with a canned "shown" result (the chips render from the message
    * list, not from this resolve).
    *
-   * Triggered automatically from `handleEvent` when a `step_await`-derived
+   * Triggered automatically from `handleEvent` when an `await`-derived
    * message arrives for such a tool: the user does not click a pill; the
    * bridge's confirm-bubble gate (WebMCP only) is the only interactive
    * surface.
    *
-   * Idempotent on the message's `toolCall.id`: re-emits of the same step_await
+   * Idempotent on the message's `toolCall.id`: re-emits of the same await
    * (e.g. from message coalescing) won't double-fire `tool.execute`. Failure
    * modes, declined, timed out, throw, unknown tool, all resolve into a
    * `{ isError: true, content: [...] }` payload that resumes the dispatch
@@ -3831,7 +3890,7 @@ export class AgentWidgetSession {
     const wireToolName = toolMessage.toolCall?.name;
     const toolCallId = toolMessage.toolCall?.id;
 
-    // Malformed step_await wire shapes shouldn't silently strand the
+    // Malformed await wire shapes shouldn't silently strand the
     // server-side dispatch. Three failure modes:
     //   - no executionId: no /resume target exists; surface to the host
     //     via onError so an operator can react. This is a server-side
@@ -3846,7 +3905,7 @@ export class AgentWidgetSession {
     if (!executionId) {
       this.callbacks.onError?.(
         new Error(
-          "WebMCP step_await missing executionId: dispatch left paused.",
+          "WebMCP await missing executionId: dispatch left paused.",
         ),
       );
       return;
@@ -3870,7 +3929,7 @@ export class AgentWidgetSession {
           content: [
             {
               type: "text",
-              text: "WebMCP step_await missing toolCall.id: cannot execute the page tool.",
+              text: "WebMCP await missing toolCall.id: cannot execute the page tool.",
             },
           ],
         });
@@ -3992,7 +4051,7 @@ export class AgentWidgetSession {
     this.teardownReconnect();
     // Tear down every in-flight WebMCP resolve (each owns its own controller,
     // independent of the shared one above). Clear the inflight set so retries
-    // are possible if the user re-issues the same step_await context.
+    // are possible if the user re-issues the same await context.
     this.abortWebMcpResolves();
     this.webMcpInflightKeys.clear();
     // Stop any in-progress audio too: when the user hits "stop", they want
@@ -4283,7 +4342,7 @@ export class AgentWidgetSession {
         this.activeAssistantMessageId = event.message.id;
       }
 
-      // Local-tool auto-resolve: when a step_await emits a tool-variant
+      // Local-tool auto-resolve: when a await emits a tool-variant
       // message for a `webmcp:*` tool, or the built-in fire-and-forget
       // `suggest_replies`: resolve it and post the result to /resume.
       // Unlike ask_user_question, no user pill click is required; for WebMCP
@@ -4294,7 +4353,7 @@ export class AgentWidgetSession {
       // Defer via `queueMicrotask` so handleEvent returns FIRST. The current
       // SSE consumer is still mid-loop; once we return, the dispatch's
       // `connectStream` sees end-of-stream (server closes the SSE at
-      // step_await), flips status to "idle", and clears `abortController`
+      // await), flips status to "idle", and clears `abortController`
       // before our resolve grabs them. Without this, the original dispatch's
       // finalizer would clobber the new abort controller and `streaming=true`
       // set inside `resolveWebMcpToolCall`.
@@ -4319,7 +4378,7 @@ export class AgentWidgetSession {
       ) {
         // Collect the await into its executionId's batch instead of resolving
         // it on the spot. Parallel same-tool calls (core#3878) arrive as
-        // separate `step_await`s in the same stream; batching lets us post ONE
+        // separate `await`s in the same stream; batching lets us post ONE
         // `/resume` keyed by per-call id (see `enqueueWebMcpAwait`).
         this.enqueueWebMcpAwait(event.message);
       }
@@ -4348,7 +4407,7 @@ export class AgentWidgetSession {
     } else if (event.type === "status") {
       // A plain `idle` (no `terminal`) on the durable lane, while the run is
       // genuinely mid-turn, is a dropped connection, not a finish and not an
-      // intentional `step_await` pause. Reconnect instead of finalizing.
+      // intentional `await` pause. Reconnect instead of finalizing.
       if (event.status === "idle" && !event.terminal && this.isDurableDrop()) {
         this.beginReconnect();
         return;
@@ -4391,7 +4450,7 @@ export class AgentWidgetSession {
             this.agentExecution.status = 'complete';
           }
         }
-        // The stream that delivered any local-tool `step_await`s has now ended,
+        // The stream that delivered any local-tool `await`s has now ended,
         // so every parallel await it carried is collected. Flush them as ONE
         // batched `/resume` per executionId (deferred: see
         // scheduleWebMcpBatchFlush). Runs AFTER the teardown above so a resolve
@@ -4455,7 +4514,7 @@ export class AgentWidgetSession {
 
   /**
    * The drop gate: is this stream-end a dropped connection we should reconnect,
-   * rather than a graceful finish or an intentional `step_await` pause? ALL must
+   * rather than a graceful finish or an intentional `await` pause? ALL must
    * hold (see plan §Design overview keystone 3).
    */
   private isDurableDrop(): boolean {
@@ -4857,7 +4916,7 @@ export class AgentWidgetSession {
       // suggest_replies equivalent: preserve the persisted fire-and-forget
       // resolution across re-emissions. It is the only dedupe signal that
       // survives a hydration (the in-memory key sets are cleared), so a
-      // stale step_await re-emit must not wipe it before
+      // stale await re-emit must not wipe it before
       // `isSuggestRepliesAlreadyResolved` checks it in the resolve path.
       if (
         existing.agentMetadata?.suggestRepliesResolved === true &&
@@ -4898,11 +4957,11 @@ export class AgentWidgetSession {
       }
       // Auto-resolved local-tool equivalent (`webmcp:*` and the built-in
       // `suggest_replies`): once such a tool has started resolving (inflight)
-      // or resolved, a duplicate `step_await` re-emit must not flip
+      // or resolved, a duplicate `await` re-emit must not flip
       // `awaitingLocalTool` back to true and resurrect the "waiting on
       // local tool" UI. It also must not overwrite an existing running or
       // completed toolCall with the fresh running skeleton emitted by client.ts
-      // for every step_await. resolveWebMcpToolCall's dedupe path returns
+      // for every await. resolveWebMcpToolCall's dedupe path returns
       // without re-touching the message, so correct the merge here (also avoids
       // a one-frame flash before that microtask runs).
       const reTcName = withSequence.toolCall?.name;

package/src/suggest-replies-tool.ts

@@ -4,7 +4,7 @@
  * The widget can advertise this tool to the agent on every dispatch via
  * `clientTools[]` (set `suggestions.followUps.expose: true`): the same
  * wire surface as `ask_user_question` and WebMCP page tools. When the model
- * calls it, the execution pauses with a `step_await` (a local-tool pause
+ * calls it, the execution pauses with an `await` (a local-tool pause
  * carries no `awaitReason`; that discriminator is internal). Unlike
  * `ask_user_question`, the widget resolves it FIRE-AND-FORGET: it renders the
  * configured follow-up surface and immediately resumes the execution with a

package/src/testing/mock-stream.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, it } from "vitest";
+import { AgentWidgetClient } from "../client";
+import type { AgentWidgetEvent, AgentWidgetMessage } from "../types";
 
 import {
   buildAssistantTurnFrames,
@@ -21,15 +23,15 @@ async function readAll(stream: ReadableStream<Uint8Array>): Promise<string> {
 describe("createMockSSEStream", () => {
   it("emits bare `data:` frames by default", async () => {
     const frames = [
-      { type: "agent_turn_start", executionId: "e-1", turnId: "t-1" },
-      { type: "agent_turn_delta", executionId: "e-1", turnId: "t-1", delta: "hi" },
-      { type: "agent_turn_complete", executionId: "e-1", turnId: "t-1" },
+      { type: "text_start", executionId: "e-1", turnId: "t-1" },
+      { type: "text_delta", executionId: "e-1", turnId: "t-1", delta: "hi" },
+      { type: "text_complete", executionId: "e-1", turnId: "t-1" },
     ];
     const text = await readAll(createMockSSEStream(frames, { delayMs: 0 }));
 
     expect(text).not.toContain("event:");
     expect(text.split("\n\n").filter(Boolean)).toHaveLength(3);
-    expect(text).toContain('"type":"agent_turn_delta"');
+    expect(text).toContain('"type":"text_delta"');
     expect(text).toContain('"delta":"hi"');
   });
 
@@ -43,7 +45,7 @@ describe("createMockSSEStream", () => {
   it("rejects reads with AbortError once the signal aborts, like a real fetch", async () => {
     const abort = new AbortController();
     const frames = Array.from({ length: 5 }, (_, i) => ({
-      type: "agent_turn_delta",
+      type: "text_delta",
       delta: `chunk-${i}`,
     }));
     const reader = createMockSSEStream(frames, {
@@ -69,26 +71,45 @@ describe("buildAssistantTurnFrames", () => {
       chunkSize: 4,
     });
 
-    expect(frames[0]).toEqual({ type: "agent_turn_start", executionId: "exec-1", turnId: "turn-1" });
-    expect(frames[frames.length - 1]).toEqual({
-      type: "agent_turn_complete",
-      executionId: "exec-1",
-      turnId: "turn-1",
-    });
-
-    const deltas = frames.filter((f) => f.type === "agent_turn_delta");
+    expect(frames.map((f) => f.type)).toEqual([
+      "turn_start", "text_start", "text_delta", "text_delta", "text_delta", "text_complete", "turn_complete",
+    ]);
+    expect(frames[0]).toMatchObject({ id: "turn-1", role: "assistant" });
+    const deltas = frames.filter((f) => f.type === "text_delta");
     expect(deltas.map((f) => f.delta)).toEqual(["abcd", "efgh", "ij"]);
-    expect(deltas.every((f) => f.executionId === "exec-1" && f.turnId === "turn-1")).toBe(true);
+    expect(deltas.every((f) => f.executionId === "exec-1" && f.id === "turn-1-text")).toBe(true);
+    expect(frames.at(-2)).toMatchObject({ id: "turn-1-text", text: "abcdefghij" });
+    expect(frames.at(-1)).toMatchObject({ id: "turn-1", content: "abcdefghij" });
   });
 
   it("defaults turnId and chunkSize", () => {
     const frames = buildAssistantTurnFrames({ executionId: "exec-2", text: "hello" });
-    expect(frames[0].turnId).toBe("turn-1");
-    const deltaCount = frames.filter((f) => f.type === "agent_turn_delta").length;
+    expect(frames[0].id).toBe("turn-1");
+    const deltaCount = frames.filter((f) => f.type === "text_delta").length;
     expect(deltaCount).toBeGreaterThanOrEqual(1);
   });
 });
 
+it("renders helper-generated turns through the real client without duplicating completed text", async () => {
+  const events: AgentWidgetEvent[] = [];
+  const client = new AgentWidgetClient({
+    apiUrl: "https://example.test/chat",
+    customFetch: async () => createMockSSEResponse([
+      { type: "execution_start", executionId: "exec-1", kind: "agent" },
+      ...buildAssistantTurnFrames({ executionId: "exec-1", turnId: "turn-1", text: "First reply", chunkSize: 3 }),
+      ...buildAssistantTurnFrames({ executionId: "exec-1", turnId: "turn-2", text: "Second reply", chunkSize: 4 }),
+      { type: "execution_complete", executionId: "exec-1", kind: "agent", success: true },
+    ], { delayMs: 0 }),
+  });
+  await client.dispatch({ messages: [] }, (event) => events.push(event));
+  const messages = new Map<string, AgentWidgetMessage>();
+  for (const event of events) {
+    if (event.type === "message") messages.set(event.message.id, { ...event.message });
+  }
+  expect([...messages.values()].map((message) => message.content)).toEqual(["First reply", "Second reply"]);
+  expect([...messages.values()].every((message) => !message.streaming)).toBe(true);
+});
+
 describe("createMockSSEResponse", () => {
   it("wraps the stream in a text/event-stream Response", async () => {
     const res = createMockSSEResponse([{ type: "ping" }], { delayMs: 0 });

package/src/testing/mock-stream.ts

@@ -66,30 +66,35 @@ export interface AssistantTurnFramesOptions {
   turnId?: string;
   /** Assistant text content to stream. */
   text: string;
-  /** Approximate characters per `agent_turn_delta` frame. Default: 32. */
+  /** Approximate characters per `text_delta` frame. Default: 32. */
   chunkSize?: number;
 }
 
 /**
- * Builds the standard `agent_turn_start` → many `agent_turn_delta` → `agent_turn_complete`
- * frame sequence for simulating a streaming assistant reply. The frames drive the same
- * client pipeline as real SSE, so stream animations (typewriter, word-fade, etc.) engage.
+ * Builds a unified assistant turn with a text block. Execution lifecycle frames
+ * can be supplied by the caller when composing a multi-turn execution.
  */
 export function buildAssistantTurnFrames(options: AssistantTurnFramesOptions): MockSSEFrame[] {
   const { executionId, text } = options;
   const turnId = options.turnId ?? "turn-1";
+  const textId = `${turnId}-text`;
   const chunkSize = Math.max(1, options.chunkSize ?? 32);
-
-  const frames: MockSSEFrame[] = [{ type: "agent_turn_start", executionId, turnId }];
+  const frames: MockSSEFrame[] = [
+    { type: "turn_start", executionId, id: turnId, role: "assistant" },
+    { type: "text_start", executionId, id: textId, turnId, role: "assistant" },
+  ];
   for (let i = 0; i < text.length; i += chunkSize) {
     frames.push({
-      type: "agent_turn_delta",
+      type: "text_delta",
       executionId,
-      turnId,
+      id: textId,
       delta: text.slice(i, i + chunkSize),
     });
   }
-  frames.push({ type: "agent_turn_complete", executionId, turnId });
+  frames.push(
+    { type: "text_complete", executionId, id: textId, text },
+    { type: "turn_complete", executionId, id: turnId, role: "assistant", content: text },
+  );
   return frames;
 }
 

package/src/types/theme.ts

@@ -26,7 +26,11 @@ export interface ColorPalette {
   warning: ColorShade;
   error: ColorShade;
   info: ColorShade;
-  [key: string]: ColorShade;
+  /** Event-stream tool badge family. */
+  purple?: ColorShade;
+  /** Event-stream agent badge family. */
+  teal?: ColorShade;
+  [key: string]: ColorShade | undefined;
 }
 
 export interface SpacingScale {
@@ -628,6 +632,40 @@ export interface ReasoningBubbleTokens {
   shadow: string;
 }
 
+/** One event-stream badge chip: fill + text pair. The chip border derives
+ * from `foreground` at ~31% alpha. */
+export interface EventStreamBadgePairTokens {
+  background: TokenReference<'color'>;
+  foreground: TokenReference<'color'>;
+}
+
+/**
+ * Event-stream inspector badge chips (`features.eventStream`), one pair per
+ * unified event family. Materialized into every theme and emitted as
+ * `--persona-event-badge-<family>-{bg,fg}`, with scheme-appropriate defaults:
+ * light themes pair a 100-tone fill with a 700-tone text, the built-in dark
+ * layer flips to a 900-tone fill with a 300-tone text. `badge.default` colors
+ * event types no family matches.
+ */
+export interface EventStreamTokens {
+  badge: {
+    /** `flow_*` events. */
+    flow: EventStreamBadgePairTokens;
+    /** `step_*` events. */
+    step: EventStreamBadgePairTokens;
+    /** `reasoning_*` events. */
+    reasoning: EventStreamBadgePairTokens;
+    /** `tool_*` events. */
+    tool: EventStreamBadgePairTokens;
+    /** `agent_*` events. */
+    agent: EventStreamBadgePairTokens;
+    /** `error` / `execution_error` events. */
+    error: EventStreamBadgePairTokens;
+    /** Any event type no other family matches. */
+    default: EventStreamBadgePairTokens;
+  };
+}
+
 /** Scrollbar appearance shared by every scroller in the widget. */
 export interface ScrollbarTokens {
   /** Thumb color. @default semantic.colors.border */
@@ -994,6 +1032,8 @@ export interface ComponentTokens {
   attachment: AttachmentTokens;
   toolBubble: ToolBubbleTokens;
   reasoningBubble: ReasoningBubbleTokens;
+  /** Event-stream inspector badge chips. */
+  eventStream?: EventStreamTokens;
   composer: ComposerChromeTokens;
   /** Shared motion timing for composer chrome animation. */
   motion?: MotionTokens;