@runtypelabs/persona 3.37.0 → 4.1.0

package/src/utils/sequence-buffer.test.ts

@@ -1,256 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { SequenceReorderBuffer } from "./sequence-buffer";
-
-describe("SequenceReorderBuffer", () => {
-  let emitted: Array<{ payloadType: string; payload: any }>;
-  let emitter: (payloadType: string, payload: any) => void;
-
-  beforeEach(() => {
-    vi.useFakeTimers();
-    emitted = [];
-    emitter = (payloadType, payload) => {
-      emitted.push({ payloadType, payload });
-    };
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it("passes in-order events through immediately", () => {
-    const buf = new SequenceReorderBuffer(emitter);
-    buf.push("step_delta", { seq: 1, text: "a" });
-    buf.push("step_delta", { seq: 2, text: "b" });
-    buf.push("step_delta", { seq: 3, text: "c" });
-
-    expect(emitted).toHaveLength(3);
-    expect(emitted[0].payload.text).toBe("a");
-    expect(emitted[1].payload.text).toBe("b");
-    expect(emitted[2].payload.text).toBe("c");
-    buf.destroy();
-  });
-
-  it("reorders leading out-of-order events (3, 1, 2 → 1, 2, 3)", () => {
-    const buf = new SequenceReorderBuffer(emitter);
-    // seq=3 arrives first: should be buffered (3 > nextExpected=1)
-    buf.push("step_delta", { seq: 3, text: "c" });
-    expect(emitted).toHaveLength(0);
-
-    // seq=1 arrives: matches nextExpected, emits, then drains seq=2 (not present), stops
-    buf.push("step_delta", { seq: 1, text: "a" });
-    expect(emitted).toHaveLength(1);
-    expect(emitted[0].payload.text).toBe("a");
-
-    // seq=2 arrives: matches nextExpected=2, emits, drains seq=3 from buffer
-    buf.push("step_delta", { seq: 2, text: "b" });
-    expect(emitted).toHaveLength(3);
-    expect(emitted[1].payload.text).toBe("b");
-    expect(emitted[2].payload.text).toBe("c");
-    buf.destroy();
-  });
-
-  it("reorders mid-stream out-of-order events", () => {
-    const buf = new SequenceReorderBuffer(emitter);
-    buf.push("step_delta", { seq: 1, text: "a" });
-    buf.push("step_delta", { seq: 3, text: "c" }); // buffered
-    buf.push("step_delta", { seq: 2, text: "b" }); // emits, drains 3
-
-    expect(emitted).toHaveLength(3);
-    expect(emitted[0].payload.text).toBe("a");
-    expect(emitted[1].payload.text).toBe("b");
-    expect(emitted[2].payload.text).toBe("c");
-    buf.destroy();
-  });
-
-  it("flushes buffered events after gap timeout when a seq is missing", () => {
-    const buf = new SequenceReorderBuffer(emitter, 50);
-    buf.push("step_delta", { seq: 1, text: "a" }); // emits
-    buf.push("step_delta", { seq: 3, text: "c" }); // buffered (waiting for seq 2)
-
-    expect(emitted).toHaveLength(1);
-
-    // Advance past gap timeout: seq=2 never arrives, flush seq=3 anyway
-    vi.advanceTimersByTime(60);
-
-    expect(emitted).toHaveLength(2);
-    expect(emitted[1].payload.text).toBe("c");
-    buf.destroy();
-  });
-
-  it("passes no-seq events through immediately (backward compat)", () => {
-    const buf = new SequenceReorderBuffer(emitter);
-    buf.push("flow_start", { flowId: "abc" });
-    buf.push("step_start", { name: "test" });
-
-    expect(emitted).toHaveLength(2);
-    expect(emitted[0].payload.flowId).toBe("abc");
-    expect(emitted[1].payload.name).toBe("test");
-    buf.destroy();
-  });
-
-  it("emits late/duplicate events (seq < nextExpected)", () => {
-    const buf = new SequenceReorderBuffer(emitter);
-    // Process seq 1-3 normally to advance nextExpected to 4
-    buf.push("step_delta", { seq: 1, text: "a" });
-    buf.push("step_delta", { seq: 2, text: "b" });
-    buf.push("step_delta", { seq: 3, text: "c" });
-    expect(emitted).toHaveLength(3);
-
-    // Now seq=1 arrives again: it's a duplicate (1 < nextExpected=4), still emitted
-    buf.push("step_delta", { seq: 1, text: "a-dup" });
-    expect(emitted).toHaveLength(4);
-    expect(emitted[3].payload.text).toBe("a-dup");
-    buf.destroy();
-  });
-
-  it("handles mixed seq and no-seq events", () => {
-    const buf = new SequenceReorderBuffer(emitter);
-    buf.push("step_delta", { seq: 1, text: "a" });
-    buf.push("status", { status: "streaming" }); // no seq
-    buf.push("step_delta", { seq: 2, text: "b" });
-    buf.push("error", { error: "oops" }); // no seq
-
-    expect(emitted).toHaveLength(4);
-    expect(emitted[0].payload.text).toBe("a");
-    expect(emitted[1].payload.status).toBe("streaming");
-    expect(emitted[2].payload.text).toBe("b");
-    expect(emitted[3].payload.error).toBe("oops");
-    buf.destroy();
-  });
-
-  it("handles large burst of out-of-order events correctly", () => {
-    const buf = new SequenceReorderBuffer(emitter);
-    // Send events in reverse order: 10, 9, 8, ..., 1
-    // All are buffered until seq=1 arrives (last), then everything drains
-    const seqs = [10, 9, 8, 7, 6, 5, 4, 3, 2, 1];
-    for (const seq of seqs) {
-      buf.push("step_delta", { seq, text: `chunk-${seq}` });
-    }
-
-    expect(emitted).toHaveLength(10);
-    const emittedTexts = emitted.map(e => e.payload.text);
-    expect(emittedTexts).toEqual([
-      "chunk-1", "chunk-2", "chunk-3", "chunk-4", "chunk-5",
-      "chunk-6", "chunk-7", "chunk-8", "chunk-9", "chunk-10"
-    ]);
-    buf.destroy();
-  });
-
-  it("handles scrambled arrival order", () => {
-    const buf = new SequenceReorderBuffer(emitter);
-    const scrambled = [1, 5, 3, 2, 4, 8, 6, 7, 10, 9];
-    for (const seq of scrambled) {
-      buf.push("step_delta", { seq, text: `chunk-${seq}` });
-    }
-
-    expect(emitted).toHaveLength(10);
-    const emittedTexts = emitted.map(e => e.payload.text);
-    expect(emittedTexts).toEqual([
-      "chunk-1", "chunk-2", "chunk-3", "chunk-4", "chunk-5",
-      "chunk-6", "chunk-7", "chunk-8", "chunk-9", "chunk-10"
-    ]);
-    buf.destroy();
-  });
-
-  it("no-seq event flushes pending buffer and cancels the gap timer", () => {
-    const buf = new SequenceReorderBuffer(emitter, 50);
-    buf.push("step_delta", { seq: 1, text: "a" });
-    buf.push("step_delta", { seq: 3, text: "c" }); // buffered, starts gap timer
-    expect(emitted).toHaveLength(1);
-
-    // A no-seq event triggers flushAll, which drains the buffer in seq order
-    // and cancels the gap timer.
-    buf.push("flow_complete", { flowId: "done" });
-    expect(emitted).toHaveLength(3); // a, c, flow_complete
-
-    // The gap timer must no longer fire after the flushAll.
-    vi.advanceTimersByTime(100);
-    expect(emitted).toHaveLength(3);
-    buf.destroy();
-  });
-
-  it("supports sequenceIndex as an alternative to seq", () => {
-    const buf = new SequenceReorderBuffer(emitter);
-    buf.push("reason_delta", { sequenceIndex: 1, text: "a" });
-    buf.push("reason_delta", { sequenceIndex: 3, text: "c" });
-    buf.push("reason_delta", { sequenceIndex: 2, text: "b" });
-
-    expect(emitted).toHaveLength(3);
-    expect(emitted[0].payload.text).toBe("a");
-    expect(emitted[1].payload.text).toBe("b");
-    expect(emitted[2].payload.text).toBe("c");
-    buf.destroy();
-  });
-
-  it("leading gap flushes via timeout when seq=1 never arrives", () => {
-    const buf = new SequenceReorderBuffer(emitter, 50);
-    // Only seq=2 and seq=3 arrive: seq=1 is missing
-    buf.push("step_delta", { seq: 2, text: "b" });
-    buf.push("step_delta", { seq: 3, text: "c" });
-    expect(emitted).toHaveLength(0); // both buffered
-
-    vi.advanceTimersByTime(50);
-    // Gap timer flushes in seq order
-    expect(emitted).toHaveLength(2);
-    expect(emitted[0].payload.text).toBe("b");
-    expect(emitted[1].payload.text).toBe("c");
-    buf.destroy();
-  });
-
-  it("handles a stream whose first seq is > 1 via the gap timeout (no loss)", () => {
-    // Defensive: if the server's counter ever starts above 1 (e.g. a resumed
-    // stream), the hardcoded nextExpectedSeq=1 would buffer the first event.
-    // The gap timer must still flush it so nothing is lost.
-    const buf = new SequenceReorderBuffer(emitter, 50);
-    buf.push("step_delta", { seq: 5, text: "first" });
-    buf.push("step_delta", { seq: 6, text: "second" });
-    expect(emitted).toHaveLength(0);
-
-    vi.advanceTimersByTime(50);
-
-    expect(emitted).toHaveLength(2);
-    expect(emitted[0].payload.text).toBe("first");
-    expect(emitted[1].payload.text).toBe("second");
-
-    // Subsequent in-order events should pass through immediately.
-    buf.push("step_delta", { seq: 7, text: "third" });
-    expect(emitted).toHaveLength(3);
-    expect(emitted[2].payload.text).toBe("third");
-    buf.destroy();
-  });
-
-  it("warns and emits both events on seq collision (does not silently drop)", () => {
-    // Server invariant: seq is unique per stream. If it's ever violated
-    // (bug, replay, mixed counters), Map.set would silently overwrite. The
-    // buffer must detect this, warn, and emit the prior event so nothing is
-    // dropped.
-    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-    const buf = new SequenceReorderBuffer(emitter, 50);
-
-    buf.push("step_delta", { seq: 1, text: "a" });
-    // seq=3 buffered, waiting for seq=2
-    buf.push("step_delta", { seq: 3, text: "first-at-3" });
-    expect(emitted).toHaveLength(1);
-
-    // Second event with same seq=3: prior one should be emitted out-of-order
-    buf.push("reason_delta", { seq: 3, text: "second-at-3" });
-
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    expect(warnSpy.mock.calls[0][0]).toContain("duplicate seq=3");
-    expect(warnSpy.mock.calls[0][0]).toContain("step_delta");
-    expect(warnSpy.mock.calls[0][0]).toContain("reason_delta");
-
-    // Prior event flushed immediately (out of seq order), nothing lost
-    expect(emitted).toHaveLength(2);
-    expect(emitted[1].payload.text).toBe("first-at-3");
-
-    // seq=2 arrives: advances nextExpected through the buffered second-at-3
-    buf.push("step_delta", { seq: 2, text: "b" });
-    expect(emitted).toHaveLength(4);
-    expect(emitted[2].payload.text).toBe("b");
-    expect(emitted[3].payload.text).toBe("second-at-3");
-
-    warnSpy.mockRestore();
-    buf.destroy();
-  });
-});

package/src/utils/sequence-buffer.ts

@@ -1,130 +0,0 @@
-type BufferedEvent = { payloadType: string; payload: any; seq: number };
-
-export class SequenceReorderBuffer {
-  private nextExpectedSeq: number | null = null;
-  private buffer: Map<number, BufferedEvent> = new Map();
-  private flushTimer: ReturnType<typeof setTimeout> | null = null;
-  private emitter: (payloadType: string, payload: any) => void;
-  private gapTimeoutMs: number;
-
-  constructor(emitter: (payloadType: string, payload: any) => void, gapTimeoutMs = 50) {
-    this.emitter = emitter;
-    this.gapTimeoutMs = gapTimeoutMs;
-  }
-
-  push(payloadType: string, payload: any): void {
-    // All three fields are sourced from the same FlowExecutionEngine.sequenceCounter:
-    //   - `seq`: step_delta, text_start, text_end, agent_* events (top-level)
-    //   - `sequenceIndex`: reason_start, reason_delta, reason_complete, source
-    //   - `agentContext.seq`: tool_start, tool_delta, tool_complete (agent loop)
-    const seq = payload?.seq ?? payload?.sequenceIndex ?? payload?.agentContext?.seq;
-
-    // No seq field: emit immediately (backward compat).
-    // If there are buffered events waiting for a gap to fill, flush them
-    // first: the server sending an unsequenced event means it has moved on
-    // and the missing seq numbers are not coming.
-    if (seq === undefined || seq === null) {
-      if (this.buffer.size > 0) {
-        this.flushAll();
-      }
-      this.emitter(payloadType, payload);
-      return;
-    }
-
-    // Server's sequenceCounter resets to 0 on each execution and pre-increments,
-    // so the first sequenced event in any stream is expected to have seq=1.
-    // If a server ever starts at a different number (e.g. a resumed stream),
-    // the 50ms gap timer below is the safety net: the first event gets
-    // buffered, then flushed after the gap elapses. Correctness is preserved;
-    // the only cost is a one-time latency on the leading event.
-    if (this.nextExpectedSeq === null) {
-      this.nextExpectedSeq = 1;
-    }
-
-    // If this is the expected event, emit it and drain consecutive buffered events
-    if (seq === this.nextExpectedSeq) {
-      this.emitter(payloadType, payload);
-      this.nextExpectedSeq = (seq as number) + 1;
-      this.drainConsecutive();
-      return;
-    }
-
-    // If seq < nextExpected, it's a duplicate or late arrival: emit anyway (don't drop)
-    if (seq < this.nextExpectedSeq!) {
-      this.emitter(payloadType, payload);
-      return;
-    }
-
-    // seq > nextExpected: buffer it and start gap timer.
-    // If another event with the same seq is already buffered, the server
-    // broke its "seq is unique per stream" invariant. Rather than silently
-    // overwrite (losing one event) or swallow the new one, emit the prior
-    // event immediately, out of order, but better than dropping it, and
-    // warn so the issue is visible.
-    const existing = this.buffer.get(seq);
-    if (existing !== undefined) {
-      if (typeof console !== "undefined" && typeof console.warn === "function") {
-        console.warn(
-          `[persona] SequenceReorderBuffer: duplicate seq=${seq} ` +
-            `(${existing.payloadType} vs ${payloadType}); ` +
-            `emitting earlier event out-of-order to avoid loss`
-        );
-      }
-      this.emitter(existing.payloadType, existing.payload);
-    }
-    this.buffer.set(seq, { payloadType, payload, seq });
-    this.startGapTimer();
-  }
-
-  private drainConsecutive(): void {
-    while (this.buffer.has(this.nextExpectedSeq!)) {
-      const event = this.buffer.get(this.nextExpectedSeq!)!;
-      this.buffer.delete(this.nextExpectedSeq!);
-      this.emitter(event.payloadType, event.payload);
-      this.nextExpectedSeq!++;
-    }
-    // If buffer is empty, clear the gap timer
-    if (this.buffer.size === 0) {
-      this.clearGapTimer();
-    }
-  }
-
-  private startGapTimer(): void {
-    if (this.flushTimer !== null) return;
-    this.flushTimer = setTimeout(() => {
-      this.flushAll();
-    }, this.gapTimeoutMs);
-  }
-
-  private clearGapTimer(): void {
-    if (this.flushTimer !== null) {
-      clearTimeout(this.flushTimer);
-      this.flushTimer = null;
-    }
-  }
-
-  private flushAll(): void {
-    this.clearGapTimer();
-    if (this.buffer.size === 0) return;
-
-    // Flush all buffered events in seq order
-    const sorted = [...this.buffer.entries()].sort((a, b) => a[0] - b[0]);
-    for (const [seq, event] of sorted) {
-      this.buffer.delete(seq);
-      this.emitter(event.payloadType, event.payload);
-    }
-    // Update nextExpectedSeq to after the last flushed
-    if (sorted.length > 0) {
-      this.nextExpectedSeq = sorted[sorted.length - 1][0] + 1;
-    }
-  }
-
-  destroy(): void {
-    this.clearGapTimer();
-    this.buffer.clear();
-  }
-
-  flushPending(): void {
-    this.flushAll();
-  }
-}

package/src/utils/unified-event-bridge.test.ts

@@ -1,263 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { UnifiedToLegacyBridge, isUnifiedLifecycleStart, type LegacyEvent } from "./unified-event-bridge";
-import { createUnifiedEventWrite } from "./__fixtures__/unified-translator.oracle";
-
-type Frame = Record<string, unknown> & { type: string };
-
-/** legacy frames → api oracle → parsed unified frames */
-function legacyToUnified(legacy: Frame[], executionId?: string): Frame[] {
-  const unified: Frame[] = [];
-  const sink = (chunk: string) => {
-    for (const part of chunk.split("\n\n")) {
-      const dataLine = part.split("\n").find((l) => l.startsWith("data: "));
-      if (!dataLine) continue;
-      const json = dataLine.slice(6);
-      if (json.trim() === "[DONE]") continue;
-      try {
-        unified.push(JSON.parse(json) as Frame);
-      } catch {
-        /* ignore */
-      }
-    }
-  };
-  const write = createUnifiedEventWrite(sink, executionId ? { executionId } : undefined);
-  for (const f of legacy) write(`data: ${JSON.stringify(f)}\n\n`);
-  return unified;
-}
-
-/** unified frames → widget bridge → legacy' events */
-function unifiedToLegacy(unified: Frame[], executionId?: string): LegacyEvent[] {
-  const bridge = new UnifiedToLegacyBridge(executionId ? { executionId } : undefined);
-  const out: LegacyEvent[] = [];
-  for (const f of unified) out.push(...bridge.push(f.type, f));
-  return out;
-}
-
-/** full round-trip: legacy → unified → legacy' */
-function roundTrip(legacy: Frame[], executionId = "exec_test"): { unified: Frame[]; legacy2: LegacyEvent[] } {
-  const unified = legacyToUnified(legacy, executionId);
-  return { unified, legacy2: unifiedToLegacy(unified, executionId) };
-}
-
-const byType = (evs: LegacyEvent[], t: string) => evs.filter((e) => e.payloadType === t);
-const field = (e: LegacyEvent | undefined, k: string): unknown => e?.payload[k];
-const textOf = (evs: LegacyEvent[]) =>
-  byType(evs, "agent_turn_delta")
-    .filter((e) => e.payload.contentType === "text")
-    .map((e) => String(e.payload.delta ?? ""))
-    .join("");
-const thinkingOf = (evs: LegacyEvent[]) =>
-  byType(evs, "agent_turn_delta")
-    .filter((e) => e.payload.contentType === "thinking")
-    .map((e) => String(e.payload.delta ?? ""))
-    .join("");
-
-describe("UnifiedToLegacyBridge — round-trip against the api oracle", () => {
-  it("agent text stream preserves text, turnId, and lifecycle", () => {
-    const { unified, legacy2 } = roundTrip([
-      { type: "agent_start", executionId: "exec_test", agentId: "virtual", startedAt: "t0" },
-      { type: "agent_turn_start", turnId: "turn_1", iteration: 1 },
-      { type: "agent_turn_delta", executionId: "exec_test", iteration: 1, turnId: "turn_1", contentType: "text", delta: "Hello " },
-      { type: "agent_turn_delta", executionId: "exec_test", iteration: 1, turnId: "turn_1", contentType: "text", delta: "world" },
-      { type: "agent_turn_complete", turnId: "turn_1", iteration: 1, stopReason: "end_turn", completedAt: "t1" },
-      { type: "agent_complete", executionId: "exec_test", success: true, stopReason: "end_turn", completedAt: "t1" },
-    ]);
-
-    // the oracle really did produce the neutral vocabulary
-    expect(unified[0].type).toBe("execution_start");
-    expect(unified.some((f) => f.type === "text_delta")).toBe(true);
-
-    expect(byType(legacy2, "agent_start")).toHaveLength(1);
-    expect(textOf(legacy2)).toBe("Hello world");
-    // turnId recovered from the open turn (unified decouples block-id from turn)
-    expect(field(byType(legacy2, "agent_turn_delta")[0], "turnId")).toBe("turn_1");
-    expect(field(byType(legacy2, "agent_turn_complete")[0], "stopReason")).toBe("end_turn");
-    const complete = byType(legacy2, "agent_complete")[0];
-    expect(field(complete, "success")).toBe(true);
-    expect(field(complete, "executionId")).toBe("exec_test");
-  });
-
-  it("agent text WITHOUT an explicit turn still renders (block-id fallback)", () => {
-    // the verified minimal adapter omits agent_turn_start
-    const { legacy2 } = roundTrip([
-      { type: "agent_start", executionId: "exec_test", agentId: "virtual" },
-      { type: "agent_turn_delta", executionId: "exec_test", iteration: 1, turnId: "turn_x", contentType: "text", delta: "hi" },
-      { type: "agent_complete", executionId: "exec_test", success: true },
-    ]);
-    expect(textOf(legacy2)).toBe("hi");
-    // no turn_start → bridge falls back to the unified text block id (stable, non-empty)
-    expect(field(byType(legacy2, "agent_turn_delta")[0], "turnId")).toBeTruthy();
-  });
-
-  it("agent thinking round-trips through the reasoning channel", () => {
-    const { unified, legacy2 } = roundTrip([
-      { type: "agent_start", executionId: "exec_test", agentId: "virtual" },
-      { type: "agent_turn_start", turnId: "turn_1", iteration: 1 },
-      { type: "agent_turn_delta", executionId: "exec_test", iteration: 1, turnId: "turn_1", contentType: "thinking", delta: "let me think" },
-      { type: "agent_turn_complete", turnId: "turn_1", iteration: 1 },
-      { type: "agent_complete", executionId: "exec_test", success: true },
-    ]);
-    expect(unified.some((f) => f.type === "reasoning_delta")).toBe(true);
-    expect(thinkingOf(legacy2)).toBe("let me think");
-  });
-
-  it("agent tool call preserves name, args, result, and toolCallId", () => {
-    const { unified, legacy2 } = roundTrip([
-      { type: "agent_start", executionId: "exec_test", agentId: "virtual" },
-      { type: "agent_tool_start", executionId: "exec_test", iteration: 1, toolCallId: "tc1", toolName: "search", parameters: { q: "shoes" } },
-      { type: "agent_tool_delta", toolCallId: "tc1", delta: "partial" },
-      { type: "agent_tool_complete", toolCallId: "tc1", result: { hits: 3 }, executionTime: 42 },
-      { type: "agent_complete", executionId: "exec_test", success: true },
-    ]);
-    expect(unified.some((f) => f.type === "tool_start")).toBe(true);
-
-    const start = byType(legacy2, "agent_tool_start")[0];
-    expect(field(start, "toolCallId")).toBe("tc1");
-    expect(field(start, "toolName")).toBe("search");
-    expect(field(start, "parameters")).toEqual({ q: "shoes" });
-
-    expect(field(byType(legacy2, "agent_tool_delta")[0], "delta")).toBe("partial");
-
-    const done = byType(legacy2, "agent_tool_complete")[0];
-    expect(field(done, "result")).toEqual({ hits: 3 });
-    expect(field(done, "executionTime")).toBe(42);
-  });
-
-  it("WebMCP agent_await maps onto the 3.35.0 step_await local-tool path with the webmcp: prefix", () => {
-    const { unified, legacy2 } = roundTrip([
-      { type: "agent_start", executionId: "exec_test", agentId: "virtual" },
-      {
-        type: "agent_await",
-        executionId: "exec_test",
-        toolId: "runtime_add_to_cart_1",
-        toolName: "add_to_cart", // BARE on the wire
-        origin: "webmcp",
-        toolCallId: "toolu_123",
-        parameters: { sku: "SHOE-003" },
-        awaitedAt: "t2",
-      },
-    ]);
-    // the oracle collapses agent_await → the neutral `await`
-    expect(unified.some((f) => f.type === "await")).toBe(true);
-    expect(unified.some((f) => f.type === "agent_await")).toBe(false);
-
-    const awaitEv = byType(legacy2, "step_await")[0];
-    expect(awaitEv).toBeDefined();
-    expect(field(awaitEv, "awaitReason")).toBe("local_tool_required");
-    expect(field(awaitEv, "toolName")).toBe("webmcp:add_to_cart"); // prefix synthesized by the bridge
-    expect(field(awaitEv, "toolCallId")).toBe("toolu_123");
-    expect(field(awaitEv, "parameters")).toEqual({ sku: "SHOE-003" });
-    expect(field(awaitEv, "executionId")).toBe("exec_test");
-  });
-
-  it("tool-produced media round-trips to a single agent_media", () => {
-    const { unified, legacy2 } = roundTrip([
-      { type: "agent_start", executionId: "exec_test", agentId: "virtual" },
-      {
-        type: "agent_media",
-        executionId: "exec_test",
-        toolCallId: "tc1",
-        media: [{ type: "image-url", url: "https://x/img.png", mediaType: "image/png" }],
-      },
-      { type: "agent_complete", executionId: "exec_test", success: true },
-    ]);
-    // oracle expands to the media triad
-    expect(unified.filter((f) => f.type.startsWith("media_"))).toHaveLength(3);
-
-    const media = byType(legacy2, "agent_media");
-    expect(media).toHaveLength(1);
-    const parts = field(media[0], "media") as Array<Record<string, unknown>>;
-    expect(parts[0].type).toBe("image-url");
-    expect(parts[0].url).toBe("https://x/img.png");
-    expect(parts[0].mediaType).toBe("image/png");
-  });
-
-  it("approval round-trips", () => {
-    const { legacy2 } = roundTrip([
-      { type: "agent_start", executionId: "exec_test", agentId: "virtual" },
-      { type: "agent_approval_start", approvalId: "ap1", toolName: "delete_file", toolType: "builtin", description: "Delete?", parameters: { path: "/x" } },
-      { type: "agent_approval_complete", approvalId: "ap1", decision: "approved" },
-    ]);
-    const start = byType(legacy2, "agent_approval_start")[0];
-    expect(field(start, "approvalId")).toBe("ap1");
-    expect(field(start, "toolName")).toBe("delete_file");
-    expect(field(byType(legacy2, "agent_approval_complete")[0], "decision")).toBe("approved");
-  });
-
-  it("artifacts round-trip 1:1", () => {
-    const { legacy2 } = roundTrip([
-      { type: "agent_start", executionId: "exec_test", agentId: "virtual" },
-      { type: "artifact_start", id: "a1", artifactType: "markdown", title: "Doc" },
-      { type: "artifact_delta", id: "a1", delta: "# Hello" },
-      { type: "artifact_complete", id: "a1" },
-    ]);
-    expect(field(byType(legacy2, "artifact_start")[0], "title")).toBe("Doc");
-    expect(field(byType(legacy2, "artifact_delta")[0], "delta")).toBe("# Hello");
-    expect(byType(legacy2, "artifact_complete")).toHaveLength(1);
-  });
-});
-
-describe("UnifiedToLegacyBridge — unit: kind routing, drops, and error mapping", () => {
-  it("flow-kind text routes to step_delta (not agent_turn_delta)", () => {
-    const b = new UnifiedToLegacyBridge();
-    b.push("execution_start", { kind: "flow", executionId: "exec_test" });
-    b.push("step_start", { id: "step_1", name: "Generate" });
-    const evs = b.push("text_delta", { id: "text_1", delta: "flow text" });
-    expect(evs).toHaveLength(1);
-    expect(evs[0].payloadType).toBe("step_delta");
-    expect(evs[0].payload.id).toBe("step_1"); // recovered from the open step
-    expect(evs[0].payload.text).toBe("flow text");
-  });
-
-  it("drops events with no legacy renderer", () => {
-    const b = new UnifiedToLegacyBridge();
-    b.push("execution_start", { kind: "agent", executionId: "exec_test" });
-    expect(b.push("source", { url: "https://x" })).toHaveLength(0);
-    expect(b.push("custom", { name: "runtype.fallback", value: {} })).toHaveLength(0);
-    expect(b.push("step_skip", { id: "s2" })).toHaveLength(0);
-    expect(b.push("tool_input_complete", { toolCallId: "tc1", parameters: {} })).toHaveLength(0);
-  });
-
-  it("unified `error` (recoverable) → agent_error{recoverable:true}, never the terminal `error`", () => {
-    const b = new UnifiedToLegacyBridge();
-    b.push("execution_start", { kind: "agent", executionId: "exec_test" });
-    const evs = b.push("error", { recoverable: true, error: { message: "transient" } });
-    expect(evs[0].payloadType).toBe("agent_error");
-    expect(evs[0].payload.recoverable).toBe(true);
-  });
-
-  it("execution_error{kind:agent} → terminal agent_error{recoverable:false}", () => {
-    const b = new UnifiedToLegacyBridge();
-    b.push("execution_start", { kind: "agent", executionId: "exec_test" });
-    const evs = b.push("execution_error", { kind: "agent", error: { message: "boom" } });
-    expect(evs[0].payloadType).toBe("agent_error");
-    expect(evs[0].payload.recoverable).toBe(false);
-  });
-
-  it("loop-scoped reasoning_complete folds into agent_reflection", () => {
-    const b = new UnifiedToLegacyBridge();
-    b.push("execution_start", { kind: "agent", executionId: "exec_test" });
-    b.push("reasoning_start", { id: "reason_1", scope: "loop" });
-    const evs = b.push("reasoning_complete", { id: "reason_1", text: "I should retry", scope: "loop" });
-    expect(evs[0].payloadType).toBe("agent_reflection");
-    expect(evs[0].payload.reflection).toBe("I should retry");
-  });
-
-  it("ask_user_question (non-webmcp local tool) await keeps its bare name", () => {
-    const b = new UnifiedToLegacyBridge();
-    b.push("execution_start", { kind: "agent", executionId: "exec_test" });
-    const evs = b.push("await", { toolName: "ask_user_question", toolCallId: "tc9", parameters: {} });
-    expect(evs[0].payloadType).toBe("step_await");
-    expect(evs[0].payload.awaitReason).toBe("local_tool_required");
-    expect(evs[0].payload.toolName).toBe("ask_user_question"); // no webmcp prefix
-  });
-});
-
-describe("isUnifiedLifecycleStart", () => {
-  it("identifies the unified vocabulary from the first lifecycle frame", () => {
-    expect(isUnifiedLifecycleStart("execution_start")).toBe(true);
-    expect(isUnifiedLifecycleStart("agent_start")).toBe(false);
-    expect(isUnifiedLifecycleStart("flow_start")).toBe(false);
-    expect(isUnifiedLifecycleStart("step_start")).toBe(false);
-  });
-});