@runtypelabs/persona 3.16.0 → 3.18.0

package/src/animations/glyph-cycle.ts

@@ -0,0 +1,332 @@
+import type { StreamAnimationPlugin } from "../types";
+import { registerStreamAnimationPlugin } from "../utils/stream-animation";
+
+/**
+ * Glyph-cycle animation — "hacker-settling" reveal.
+ *
+ * Each arriving char briefly cycles through a sequence of random glyphs
+ * before locking in to its final character. Unlike a pure CSS effect, this
+ * needs JS because it mutates `textContent` per tick. To keep idiomorph from
+ * clobbering mid-cycle work, each cycling span carries
+ * `data-preserve-runtime="stream-glyph-cycle"` until its cycle completes —
+ * morph honors that attribute as an absolute skip marker.
+ *
+ * A short buffer (`BUFFER_THRESHOLD`) holds the bubble empty (with the
+ * typing indicator) until enough text has arrived to run a visible reveal.
+ * Once released, every char starts as a random glyph and settles in order
+ * from the start, staggered by one `--persona-stream-step` between chars.
+ * Live tokens arriving after release queue behind the stagger slot, so the
+ * settling wave flows through the full message.
+ *
+ * Ships as a subpath module so consumers who don't want it pay zero cost.
+ * Importing this module auto-registers the plugin globally — just add the
+ * import and set `features.streamAnimation.type = "glyph-cycle"`.
+ *
+ * ```ts
+ * import "@runtypelabs/persona/animations/glyph-cycle";
+ * createAgentExperience(el, {
+ *   features: { streamAnimation: { type: "glyph-cycle" } },
+ * });
+ * ```
+ */
+
+const STYLES = `
+[data-persona-root] .persona-stream-glyph-cycle .persona-stream-char {
+  animation: persona-stream-glyph-cycle-fade
+    calc(var(--persona-stream-step, 120ms) * 1.5) ease-out both;
+}
+[data-persona-root] .persona-stream-glyph-cycle .persona-stream-char[data-glyph-cycle-final] {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+@keyframes persona-stream-glyph-cycle-fade {
+  from { opacity: 0.35; }
+  to   { opacity: 1; }
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-persona-root] .persona-stream-glyph-cycle .persona-stream-char {
+    animation: none !important;
+    opacity: 1 !important;
+  }
+}
+`.trim();
+
+// Matches the source design: alphanumerics + a small set of symbols.
+const GLYPHS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789#$%&@";
+const TICK_COUNT = 10;
+// Base interval between glyph swaps (ms). Scaled by the widget's configured
+// `speed` so the cycle feels coherent with the rest of the stream animation —
+// faster speed → snappier cycling, slower speed → more deliberate flicker.
+const BASE_TICK_MS = 120;
+const DEFAULT_STEP_MS = 120;
+// Probability that each later still-cycling sibling gets re-randomized on
+// every tick. Matches the source prototype's cross-glyph jitter feel.
+const CROSS_FLICKER_PROBABILITY = 0.4;
+// Hold the stream back until at least this many chars have arrived. Once
+// released, every char is rendered as a random glyph and settles in order
+// from the start — so the visible animation carries through the full text.
+const BUFFER_THRESHOLD = 50;
+
+const getStepMs = (container: HTMLElement | null): number => {
+  if (!container) return DEFAULT_STEP_MS;
+  const raw = container.style.getPropertyValue("--persona-stream-step")?.trim();
+  const match = raw.match(/([\d.]+)\s*ms/);
+  return match ? parseFloat(match[1]) : DEFAULT_STEP_MS;
+};
+
+const getTickMs = (span: HTMLElement): number => {
+  const container = span.closest(".persona-stream-glyph-cycle") as HTMLElement | null;
+  const step = getStepMs(container);
+  return (BASE_TICK_MS * step) / DEFAULT_STEP_MS;
+};
+
+const randomGlyph = (avoid?: string): string => {
+  let ch = GLYPHS[Math.floor(Math.random() * GLYPHS.length)];
+  // Don't settle on the same random glyph twice in a row (small visual cue
+  // that something is actually cycling).
+  if (avoid && ch === avoid) {
+    ch = GLYPHS[(GLYPHS.indexOf(ch) + 1) % GLYPHS.length];
+  }
+  return ch;
+};
+
+// Mirrors the source prototype's "lightly randomize later glyphs" step: while
+// a char is cycling, every not-yet-settled char after it in DOM order has a
+// chance to flicker too. Keeps the un-settled tail feeling alive.
+const flickerLaterSiblings = (span: HTMLElement): void => {
+  const container = span.closest(".persona-stream-glyph-cycle") as HTMLElement | null;
+  if (!container) return;
+  // Any scheduled char that still has its final char stashed is "pending
+  // or cycling" — both kinds are valid flicker targets. Settled chars have
+  // `data-glyph-cycle-final` deleted and are excluded.
+  const unsettled = container.querySelectorAll<HTMLElement>(
+    ".persona-stream-char[data-glyph-cycle-final]"
+  );
+  let seenSelf = false;
+  for (const other of Array.from(unsettled)) {
+    if (other === span) {
+      seenSelf = true;
+      continue;
+    }
+    if (!seenSelf) continue;
+    if (Math.random() < CROSS_FLICKER_PROBABILITY) {
+      other.textContent = randomGlyph();
+    }
+  }
+};
+
+// Per-container timestamp tracking: when the next char's cycle should settle.
+// Each char starts cycling immediately on schedule — no static placeholder
+// wait — and finishes when `Date.now() >= settleAt`. This slot advances by
+// one stagger step per schedule, so the burst settles left-to-right while
+// every char is visibly flickering from the moment it enters the DOM.
+const containerNextSettleAt = new WeakMap<Element, number>();
+
+// Adaptive stagger state. We measure the real interval between scheduleCycle
+// calls (= the stream's arrival cadence) and pace the glyph wave to it, a
+// touch faster (DRAIN_FACTOR < 1) so any initial burst queue drains down to
+// live-tracking instead of permanently lagging behind the live cursor.
+const DEFAULT_ARRIVAL_MS = 25;
+const STAGGER_DRAIN_FACTOR = 0.5;
+const MIN_STAGGER_MS = 6;
+const EMA_ALPHA = 0.25;
+const containerLastScheduleAt = new WeakMap<Element, number>();
+const containerArrivalMs = new WeakMap<Element, number>();
+
+const observeStagger = (container: Element | null, now: number): number => {
+  if (!container) return DEFAULT_ARRIVAL_MS * STAGGER_DRAIN_FACTOR;
+  const last = containerLastScheduleAt.get(container);
+  containerLastScheduleAt.set(container, now);
+  let observed = containerArrivalMs.get(container) ?? DEFAULT_ARRIVAL_MS;
+  if (last !== undefined) {
+    const interval = now - last;
+    // Skip near-zero intervals (burst within one MutationObserver batch) —
+    // they don't reflect the real stream cadence.
+    if (interval > 1) {
+      observed = observed * (1 - EMA_ALPHA) + interval * EMA_ALPHA;
+      containerArrivalMs.set(container, observed);
+    }
+  }
+  return Math.max(MIN_STAGGER_MS, observed * STAGGER_DRAIN_FACTOR);
+};
+
+// Per-message count of in-flight cycles (scheduled or actively ticking).
+// Used by `isAnimating()` so message-bubble keeps rendering in animated
+// mode until the cycle wave finishes, even after `message.streaming` is
+// false.
+const activeCyclesByMessage = new Map<string, number>();
+
+const getMessageId = (span: HTMLElement): string | null => {
+  const bubble = span.closest<HTMLElement>("[data-message-id]");
+  return bubble?.dataset.messageId ?? null;
+};
+
+const incrementActive = (messageId: string | null): void => {
+  if (!messageId) return;
+  activeCyclesByMessage.set(messageId, (activeCyclesByMessage.get(messageId) ?? 0) + 1);
+};
+
+const decrementActive = (messageId: string | null): void => {
+  if (!messageId) return;
+  const count = activeCyclesByMessage.get(messageId) ?? 0;
+  if (count <= 1) activeCyclesByMessage.delete(messageId);
+  else activeCyclesByMessage.set(messageId, count - 1);
+};
+
+const scheduleCycle = (span: HTMLElement): void => {
+  if (span.dataset.glyphCycleScheduled === "true") return;
+  const finalChar = span.textContent ?? "";
+  if (!finalChar || /\s/.test(finalChar)) return;
+
+  span.dataset.glyphCycleScheduled = "true";
+  // Stash the target char and immediately paint a random glyph so the span
+  // reads as "cycling" even before its staggered kickoff. Also opt out of
+  // morph — without this, streamed token re-renders would overwrite our
+  // placeholder glyph with the final char.
+  span.dataset.glyphCycleFinal = finalChar;
+  span.setAttribute("data-preserve-runtime", "stream-glyph-cycle");
+  span.textContent = randomGlyph();
+  // Record the owning message so `isAnimating()` can report in-flight work
+  // even after streaming has ended.
+  const messageId = getMessageId(span);
+  if (messageId) span.dataset.glyphCycleMessageId = messageId;
+  incrementActive(messageId);
+
+  const container = span.closest(".persona-stream-glyph-cycle") as HTMLElement | null;
+  const now = Date.now();
+  const staggerMs = observeStagger(container, now);
+  const tickMs = getTickMs(span);
+  const baseDurationMs = TICK_COUNT * tickMs;
+
+  // Settle time = later of (this char's own cycle ends) or (previous settle
+  // slot + one stagger step). The `max()` keeps left-to-right order during
+  // bursts, while post-drain live chars just get the base cycle.
+  let settleAt = now + baseDurationMs;
+  if (container) {
+    const prev = containerNextSettleAt.get(container);
+    if (prev !== undefined) settleAt = Math.max(settleAt, prev);
+    containerNextSettleAt.set(container, settleAt + staggerMs);
+  }
+
+  startCycle(span, finalChar, settleAt);
+};
+
+const startCycle = (
+  span: HTMLElement,
+  finalChar: string,
+  settleAt: number
+): void => {
+  if (span.dataset.glyphCycleStarted === "true") return;
+  span.dataset.glyphCycleStarted = "true";
+
+  const tickMs = getTickMs(span);
+  // Seed `lastGlyph` from the placeholder scheduleCycle painted, so the
+  // first real tick guarantees a different glyph.
+  let lastGlyph: string | undefined = span.textContent ?? undefined;
+  const step = () => {
+    if (!span.isConnected) return;
+    if (Date.now() >= settleAt) {
+      span.textContent = finalChar;
+      span.removeAttribute("data-preserve-runtime");
+      delete span.dataset.glyphCycleStarted;
+      delete span.dataset.glyphCycleFinal;
+      decrementActive(span.dataset.glyphCycleMessageId ?? null);
+      delete span.dataset.glyphCycleMessageId;
+      // Keep `data-glyph-cycle-scheduled` set so the MutationObserver and
+      // processCharSpans selectors skip settled chars on future re-morphs.
+      return;
+    }
+    const glyph = randomGlyph(lastGlyph);
+    span.textContent = glyph;
+    lastGlyph = glyph;
+    flickerLaterSiblings(span);
+    setTimeout(step, tickMs);
+  };
+  setTimeout(step, tickMs);
+};
+
+const processCharSpans = (root: Element | Document | ShadowRoot): void => {
+  const spans = root.querySelectorAll?.(
+    ".persona-stream-glyph-cycle .persona-stream-char:not([data-glyph-cycle-scheduled])"
+  );
+  if (!spans) return;
+  for (const span of Array.from(spans)) {
+    scheduleCycle(span as HTMLElement);
+  }
+};
+
+const isElement = (node: Node): node is HTMLElement => node.nodeType === 1;
+
+export const glyphCycle: StreamAnimationPlugin = {
+  name: "glyph-cycle",
+  containerClass: "persona-stream-glyph-cycle",
+  wrap: "char",
+  // Narrow the default skip list so inline `<code>` and fenced `<pre>`
+  // code blocks both render as cycling glyphs along with everything else.
+  // Links stay clickable; <script>/<style> stay untouched.
+  skipTags: ["a", "script", "style"],
+  styles: STYLES,
+  bufferContent(content) {
+    // Hold the bubble empty until we've accumulated enough text to run a
+    // visible cycle from the start.
+    if (content.length < BUFFER_THRESHOLD) return "";
+    // Then trim to the last "safe" whitespace: one that sits outside any
+    // unclosed `**bold**` pair. Without this, whitespace INSIDE a partial
+    // bold pair (e.g. the space between `template` and `literal` in
+    // `**template literal**`) would trigger a render of the partial
+    // `**template`, which markdown emits as literal asterisks, gets
+    // wrapped + marked `data-preserve-runtime`, and leaks through later
+    // morphs — the final structure can't reconcile.
+    let boldPairs = 0;
+    let lastSafe = -1;
+    let i = 0;
+    while (i < content.length) {
+      if (content[i] === "*" && content[i + 1] === "*") {
+        boldPairs += 1;
+        i += 2;
+        continue;
+      }
+      if (/\s/.test(content[i]) && boldPairs % 2 === 0) {
+        lastSafe = i;
+      }
+      i += 1;
+    }
+    if (lastSafe < 0) return "";
+    return content.slice(0, lastSafe);
+  },
+  isAnimating(message) {
+    return (activeCyclesByMessage.get(message.id) ?? 0) > 0;
+  },
+  onAttach(root) {
+    // Process any chars already in the DOM when the plugin activates.
+    processCharSpans(root as Element | Document | ShadowRoot);
+
+    const observer = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        for (const node of Array.from(mutation.addedNodes)) {
+          if (!isElement(node)) continue;
+          // Either the added node is a char span inside a glyph-cycle
+          // container, or it contains char spans (a word-group, paragraph,
+          // or whole bubble that was just morphed in).
+          if (
+            node.classList.contains("persona-stream-char") &&
+            node.closest(".persona-stream-glyph-cycle")
+          ) {
+            scheduleCycle(node);
+          } else {
+            processCharSpans(node);
+          }
+        }
+      }
+    });
+    observer.observe(root, { childList: true, subtree: true });
+
+    return () => observer.disconnect();
+  },
+};
+
+// Auto-register on import. ESM consumers get zero cost if they don't import;
+// once imported, the plugin is available globally by name without requiring
+// an explicit `plugins: { "glyph-cycle": glyphCycle }` config.
+registerStreamAnimationPlugin(glyphCycle);
+
+export default glyphCycle;

package/src/animations/wipe.ts

@@ -0,0 +1,66 @@
+import type { StreamAnimationPlugin } from "../types";
+import { registerStreamAnimationPlugin } from "../utils/stream-animation";
+
+/**
+ * Wipe animation — per-word left-to-right mask reveal.
+ *
+ * Each arriving word is revealed via a soft feathered mask that sweeps from
+ * right to left. Uses `mask-image` (not `background-clip: text`) so the
+ * text's normal color is preserved and nested markdown formatting works.
+ *
+ * ```ts
+ * import "@runtypelabs/persona/animations/wipe";
+ * createAgentExperience(el, {
+ *   features: { streamAnimation: { type: "wipe" } },
+ * });
+ * ```
+ */
+
+const STYLES = `
+@keyframes persona-stream-wipe {
+  from { -webkit-mask-position: 100% 0; mask-position: 100% 0; }
+  to   { -webkit-mask-position: 0% 0;   mask-position: 0% 0;   }
+}
+[data-persona-root] .persona-stream-wipe .persona-stream-word {
+  -webkit-mask-image: linear-gradient(
+    90deg,
+    black 0%,
+    black 45%,
+    transparent 55%,
+    transparent 100%
+  );
+          mask-image: linear-gradient(
+    90deg,
+    black 0%,
+    black 45%,
+    transparent 55%,
+    transparent 100%
+  );
+  -webkit-mask-size: 200% 100%;
+          mask-size: 200% 100%;
+  -webkit-mask-position: 100% 0;
+          mask-position: 100% 0;
+  -webkit-mask-repeat: no-repeat;
+          mask-repeat: no-repeat;
+  animation: persona-stream-wipe calc(var(--persona-stream-step, 120ms) * 3)
+    ease-out forwards;
+}
+@media (prefers-reduced-motion: reduce) {
+  [data-persona-root] .persona-stream-wipe .persona-stream-word {
+    animation: none !important;
+    -webkit-mask-image: none !important;
+            mask-image: none !important;
+  }
+}
+`.trim();
+
+export const wipe: StreamAnimationPlugin = {
+  name: "wipe",
+  containerClass: "persona-stream-wipe",
+  wrap: "word",
+  styles: STYLES,
+};
+
+registerStreamAnimationPlugin(wipe);
+
+export default wipe;

package/src/client.test.ts

@@ -2576,3 +2576,278 @@ describe('AgentWidgetClient - Out-of-Order Sequence Reordering', () => {
   });
 });
 
+// ============================================================================
+// stopReason wiring (agent_turn_complete / step_complete)
+// ============================================================================
+
+describe('AgentWidgetClient - stopReason propagation', () => {
+  const dispatchModeStream = (stopReason?: string) => {
+    const data: Record<string, unknown> = {
+      type: 'step_complete',
+      id: 'step_1',
+      stepType: 'prompt',
+      result: { response: 'Hello there.' },
+    };
+    if (stopReason) data.stopReason = stopReason;
+    return [
+      `data: ${JSON.stringify(data)}\n\n`,
+      `data: ${JSON.stringify({ type: 'flow_complete', success: true })}\n\n`,
+    ];
+  };
+
+  const collectFinalAssistant = (events: AgentWidgetEvent[]): AgentWidgetMessage | null => {
+    const messageEvents = events.filter(e => e.type === 'message');
+    for (let i = messageEvents.length - 1; i >= 0; i--) {
+      const ev = messageEvents[i];
+      if (ev.type === 'message' && ev.message.role === 'assistant' && !ev.message.streaming) {
+        return ev.message;
+      }
+    }
+    return null;
+  };
+
+  const runDispatch = async (chunks: string[]): Promise<AgentWidgetEvent[]> => {
+    global.fetch = vi.fn().mockImplementation(async (_url: string, _options: any) => {
+      const encoder = new TextEncoder();
+      const stream = new ReadableStream({
+        start(controller) {
+          for (const chunk of chunks) controller.enqueue(encoder.encode(chunk));
+          controller.close();
+        }
+      });
+      return { ok: true, body: stream };
+    });
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'usr_1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+    return events;
+  };
+
+  it.each(['end_turn', 'max_tool_calls', 'length', 'content_filter', 'error', 'unknown'] as const)(
+    'attaches stopReason=%s from step_complete (dispatch / flow path)',
+    async (stopReason) => {
+      const events = await runDispatch(dispatchModeStream(stopReason));
+      const final = collectFinalAssistant(events);
+      expect(final).not.toBeNull();
+      expect(final!.stopReason).toBe(stopReason);
+    }
+  );
+
+  it('leaves stopReason undefined when step_complete omits it (backcompat)', async () => {
+    const events = await runDispatch(dispatchModeStream(undefined));
+    const final = collectFinalAssistant(events);
+    expect(final).not.toBeNull();
+    expect(final!.stopReason).toBeUndefined();
+  });
+
+  it('captures the empty-content + max_tool_calls regression case', async () => {
+    // Symptom the upstream fix targets: model emits a tool call then gets cut
+    // off before producing follow-up text. Persona must record stopReason so
+    // the UI can render an affordance instead of an empty bubble.
+    const events = await runDispatch([
+      `data: ${JSON.stringify({
+        type: 'step_complete',
+        id: 'step_1',
+        stepType: 'prompt',
+        result: { response: '' },
+        stopReason: 'max_tool_calls',
+      })}\n\n`,
+      `data: ${JSON.stringify({ type: 'flow_complete', success: true })}\n\n`,
+    ]);
+    const final = collectFinalAssistant(events);
+    expect(final).not.toBeNull();
+    expect(final!.content).toBe('');
+    expect(final!.stopReason).toBe('max_tool_calls');
+  });
+
+  it('agent_turn_complete.stopReason overrides any earlier step_complete value (agent-loop path)', async () => {
+    // Build an agent-mode stream that emits both events. agent_turn_complete
+    // arrives last; its stopReason should win.
+    const execId = 'exec_stopreason';
+    global.fetch = createAgentStreamFetch([
+      sseEvent('agent_start', {
+        executionId: execId, agentId: 'virtual', agentName: 'Test',
+        maxTurns: 1, startedAt: new Date().toISOString(), seq: 1,
+      }),
+      sseEvent('agent_iteration_start', {
+        executionId: execId, iteration: 1, maxTurns: 1,
+        startedAt: new Date().toISOString(), seq: 2,
+      }),
+      sseEvent('agent_turn_start', {
+        executionId: execId, iteration: 1, turnIndex: 0,
+        role: 'assistant', turnId: 'turn_1', seq: 3,
+      }),
+      sseEvent('agent_turn_delta', {
+        executionId: execId, iteration: 1, delta: 'partial answer',
+        contentType: 'text', turnId: 'turn_1', seq: 4,
+      }),
+      sseEvent('agent_turn_complete', {
+        executionId: execId, iteration: 1, role: 'assistant',
+        turnId: 'turn_1', completedAt: new Date().toISOString(),
+        stopReason: 'max_tool_calls', seq: 5,
+      }),
+      sseEvent('agent_iteration_complete', {
+        executionId: execId, iteration: 1, toolCallsMade: 0,
+        stopConditionMet: true, completedAt: new Date().toISOString(), seq: 6,
+      }),
+      sseEvent('agent_complete', {
+        executionId: execId, agentId: 'virtual', success: true,
+        iterations: 1, stopReason: 'max_iterations',
+        completedAt: new Date().toISOString(), seq: 7,
+      }),
+    ]);
+
+    const client = new AgentWidgetClient({
+      apiUrl: 'http://localhost:8000',
+      agent: { name: 'Test', model: 'openai:gpt-4o-mini', systemPrompt: 'test' },
+    });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'usr_1', role: 'user', content: 'Hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+
+    const final = collectFinalAssistant(events);
+    expect(final).not.toBeNull();
+    expect(final!.stopReason).toBe('max_tool_calls');
+    expect(final!.agentMetadata?.turnId).toBe('turn_1');
+  });
+});
+
+// ============================================================================
+// step_await (LOCAL tool pause) + resumeFlow
+// ============================================================================
+
+describe('AgentWidgetClient — step_await parsing', () => {
+  const buildStepAwaitStream = (payload: Record<string, unknown>): ReadableStream<Uint8Array> => {
+    const encoder = new TextEncoder();
+    const body = `event: step_await\ndata: ${JSON.stringify({ type: 'step_await', ...payload })}\n\n`;
+    return new ReadableStream({
+      start(controller) {
+        controller.enqueue(encoder.encode(body));
+        controller.close();
+      },
+    });
+  };
+
+  it('emits a complete tool message with awaitingLocalTool=true for local_tool_required', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      body: buildStepAwaitStream({
+        awaitReason: 'local_tool_required',
+        id: 'step-1',
+        name: 'Test Step',
+        stepType: 'prompt',
+        index: 0,
+        toolId: 'runtime_ask_user_question_123',
+        toolName: 'ask_user_question',
+        executionId: 'exec_abc',
+        parameters: {
+          questions: [{ question: 'Who?', options: [{ label: 'A' }, { label: 'B' }] }],
+        },
+      }),
+    });
+
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+
+    const toolMsg = events
+      .filter((e) => e.type === 'message')
+      .map((e) => (e as { message: AgentWidgetMessage }).message)
+      .find((m) => m.variant === 'tool' && m.toolCall?.name === 'ask_user_question');
+
+    expect(toolMsg).toBeDefined();
+    expect(toolMsg!.toolCall!.id).toBe('runtime_ask_user_question_123');
+    expect(toolMsg!.toolCall!.status).toBe('complete');
+    expect(toolMsg!.toolCall!.args).toMatchObject({
+      questions: [{ question: 'Who?', options: [{ label: 'A' }, { label: 'B' }] }],
+    });
+    expect(toolMsg!.agentMetadata?.executionId).toBe('exec_abc');
+    expect(toolMsg!.agentMetadata?.awaitingLocalTool).toBe(true);
+  });
+
+  it('ignores step_await events whose awaitReason is not local_tool_required', async () => {
+    global.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      body: buildStepAwaitStream({
+        awaitReason: 'approval_required',
+        toolId: 't1',
+        toolName: 'some_tool',
+        executionId: 'exec_abc',
+        parameters: {},
+      }),
+    });
+
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:8000' });
+    const events: AgentWidgetEvent[] = [];
+    await client.dispatch(
+      { messages: [{ id: 'u1', role: 'user', content: 'hi', createdAt: new Date().toISOString() }] },
+      (e) => events.push(e)
+    );
+
+    const toolMsg = events
+      .filter((e) => e.type === 'message')
+      .map((e) => (e as { message: AgentWidgetMessage }).message)
+      .find((m) => m.agentMetadata?.awaitingLocalTool);
+    expect(toolMsg).toBeUndefined();
+  });
+});
+
+describe('AgentWidgetClient.resumeFlow', () => {
+  it('POSTs to ${apiUrl}/resume with the expected body shape', async () => {
+    let capturedUrl: string | undefined;
+    let capturedBody: Record<string, unknown> | undefined;
+    let capturedHeaders: Record<string, string> | undefined;
+    global.fetch = vi.fn().mockImplementation(async (url: string, init: RequestInit) => {
+      capturedUrl = url;
+      capturedBody = JSON.parse(init.body as string);
+      capturedHeaders = init.headers as Record<string, string>;
+      return { ok: true, body: null };
+    });
+
+    const client = new AgentWidgetClient({ apiUrl: 'https://api.runtype.com/v1/dispatch' });
+    await client.resumeFlow('exec_xyz', { ["ask_user_question"]: 'Hobbyists' });
+
+    expect(capturedUrl).toBe('https://api.runtype.com/v1/dispatch/resume');
+    expect(capturedBody).toEqual({
+      executionId: 'exec_xyz',
+      toolOutputs: { ["ask_user_question"]: 'Hobbyists' },
+      streamResponse: true,
+    });
+    expect(capturedHeaders!['Content-Type']).toBe('application/json');
+  });
+
+  it('honors a custom streamResponse option', async () => {
+    let capturedBody: Record<string, unknown> | undefined;
+    global.fetch = vi.fn().mockImplementation(async (_url: string, init: RequestInit) => {
+      capturedBody = JSON.parse(init.body as string);
+      return { ok: true, body: null };
+    });
+
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:43111/api/chat/dispatch' });
+    await client.resumeFlow('exec_abc', { t: 'ok' }, { streamResponse: false });
+
+    expect(capturedBody!.streamResponse).toBe(false);
+  });
+
+  it('derives the URL correctly for proxy-style dispatch paths', async () => {
+    let capturedUrl: string | undefined;
+    global.fetch = vi.fn().mockImplementation(async (url: string) => {
+      capturedUrl = url;
+      return { ok: true, body: null };
+    });
+
+    const client = new AgentWidgetClient({ apiUrl: 'http://localhost:43111/api/chat/dispatch' });
+    await client.resumeFlow('exec_abc', {});
+
+    expect(capturedUrl).toBe('http://localhost:43111/api/chat/dispatch/resume');
+  });
+});
+