@runtypelabs/persona 3.14.0 → 3.15.1

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

@@ -0,0 +1,256 @@
+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

@@ -0,0 +1,130 @@
+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();
+  }
+}