@blackbelt-technology/pi-agent-dashboard 0.5.3 → 0.5.4

package/packages/extension/src/__tests__/bridge-shadow-queue-drain.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Tests for the bridge's per-entry shadow-queue drain on user message_start.
+ *
+ * Pi mirrors this exact algorithm internally (see
+ * `@earendil-works/pi-coding-agent/dist/core/agent-session.js`
+ * `_processAgentEvent`, around line 270-292):
+ *
+ *   if (event.type === "message_start" && event.message.role === "user") {
+ *     const text = _getUserMessageText(event.message);
+ *     const steeringIdx = _steeringMessages.indexOf(text);
+ *     if (steeringIdx !== -1) {
+ *       _steeringMessages.splice(steeringIdx, 1);
+ *       _emitQueueUpdate();
+ *     } else {
+ *       const followUpIdx = _followUpMessages.indexOf(text);
+ *       if (followUpIdx !== -1) {
+ *         _followUpMessages.splice(followUpIdx, 1);
+ *         _emitQueueUpdate();
+ *       }
+ *     }
+ *   }
+ *
+ * Pre-fix bug: bridge bulk-cleared `bridgeFollowUp = []` at every `agent_end`
+ * and `bridgeSteering = []` at every `turn_end`. With pi's `mode:"all"`
+ * (default), pi drains all queued follow-ups across multiple turns before
+ * emitting the final `agent_end`. The dashboard saw the entire queue stay
+ * visible for the whole drain window, then disappear all at once at the
+ * end — instead of shrinking one entry per drain as the user observes them
+ * being processed.
+ *
+ * Fix: bridge mirrors pi's per-entry matcher on user `message_start`. Bulk
+ * clears at `agent_end` / `turn_end` are removed (would otherwise wipe
+ * entries the user added DURING a drain).
+ *
+ * See change: add-followup-edit-and-steer-cancel (per-entry-drain scenario).
+ */
+import { describe, it, expect } from "vitest";
+
+interface ShadowQueue {
+  steering: string[];
+  followUp: string[];
+}
+
+/**
+ * Pure mirror of the per-entry drain matcher as it lives in bridge.ts'
+ * `message_start` handler. If production drifts from this shape, the
+ * test should drift in lockstep.
+ */
+function makeShadowDrainMatcher() {
+  const queue: ShadowQueue = { steering: [], followUp: [] };
+  const emits: ShadowQueue[] = [];
+  function emit() {
+    emits.push({ steering: [...queue.steering], followUp: [...queue.followUp] });
+  }
+
+  /** Mirrors pi's `_getUserMessageText` exactly. */
+  function getUserMessageText(message: { role: string; content: unknown }): string {
+    if (message.role !== "user") return "";
+    const content = message.content;
+    if (typeof content === "string") return content;
+    if (!Array.isArray(content)) return "";
+    return content
+      .filter((c: any) => c && c.type === "text")
+      .map((c: any) => c.text ?? "")
+      .join("");
+  }
+
+  /** Call when pi emits a user `message_start`. Mirrors pi's internal logic. */
+  function onUserMessageStart(message: { role: string; content: unknown }): void {
+    const text = getUserMessageText(message);
+    if (!text) return;
+    const steeringIdx = queue.steering.indexOf(text);
+    if (steeringIdx !== -1) {
+      queue.steering.splice(steeringIdx, 1);
+      emit();
+      return;
+    }
+    const followUpIdx = queue.followUp.indexOf(text);
+    if (followUpIdx !== -1) {
+      queue.followUp.splice(followUpIdx, 1);
+      emit();
+    }
+  }
+
+  return {
+    queue,
+    emits,
+    onUserMessageStart,
+    recordSteer: (t: string) => { queue.steering.push(t); emit(); },
+    recordFollowup: (t: string) => { queue.followUp.push(t); emit(); },
+    snapshotQueue: () => ({ steering: [...queue.steering], followUp: [...queue.followUp] }),
+    snapshotEmits: () => emits.map((e) => ({ steering: [...e.steering], followUp: [...e.followUp] })),
+  };
+}
+
+describe("Bridge shadow-queue per-entry drain on user message_start", () => {
+  it("removes the matching follow-up entry when pi drains it, leaves the rest", () => {
+    const m = makeShadowDrainMatcher();
+    m.recordFollowup("a");
+    m.recordFollowup("b");
+    m.recordFollowup("c");
+    expect(m.snapshotQueue().followUp).toEqual(["a", "b", "c"]);
+
+    // Pi drains "a" first.
+    m.onUserMessageStart({ role: "user", content: "a" });
+    expect(m.snapshotQueue().followUp).toEqual(["b", "c"]);
+
+    // Then "b".
+    m.onUserMessageStart({ role: "user", content: "b" });
+    expect(m.snapshotQueue().followUp).toEqual(["c"]);
+
+    // Then "c".
+    m.onUserMessageStart({ role: "user", content: "c" });
+    expect(m.snapshotQueue().followUp).toEqual([]);
+
+    // One emit per drain (plus the three initial record emits).
+    expect(m.emits).toHaveLength(6);
+  });
+
+  it("removes the matching steering entry when pi drains it", () => {
+    const m = makeShadowDrainMatcher();
+    m.recordSteer("focus on X");
+    m.recordSteer("ignore Y");
+    expect(m.snapshotQueue().steering).toEqual(["focus on X", "ignore Y"]);
+
+    m.onUserMessageStart({ role: "user", content: "focus on X" });
+    expect(m.snapshotQueue().steering).toEqual(["ignore Y"]);
+    expect(m.snapshotQueue().followUp).toEqual([]);
+  });
+
+  it("steering queue checked BEFORE follow-up when same text is in both", () => {
+    const m = makeShadowDrainMatcher();
+    m.recordSteer("hello");
+    m.recordFollowup("hello");
+
+    m.onUserMessageStart({ role: "user", content: "hello" });
+    // Steering entry consumed, follow-up untouched.
+    expect(m.snapshotQueue().steering).toEqual([]);
+    expect(m.snapshotQueue().followUp).toEqual(["hello"]);
+
+    // Second drain consumes the follow-up.
+    m.onUserMessageStart({ role: "user", content: "hello" });
+    expect(m.snapshotQueue().followUp).toEqual([]);
+  });
+
+  it("non-matching user message_start is a no-op (no queue mutation, no emit)", () => {
+    const m = makeShadowDrainMatcher();
+    m.recordFollowup("queued");
+    const baselineEmits = m.emits.length;
+
+    // Fresh user send not in any queue (e.g., the user typed something
+    // new on an idle session, or a steer was added by a non-dashboard
+    // consumer).
+    m.onUserMessageStart({ role: "user", content: "fresh send" });
+    expect(m.snapshotQueue().followUp).toEqual(["queued"]);
+    expect(m.emits.length).toBe(baselineEmits);
+  });
+
+  it("user message_start with array content joins text blocks (matches pi's _getUserMessageText)", () => {
+    const m = makeShadowDrainMatcher();
+    m.recordFollowup("describe this");
+
+    m.onUserMessageStart({
+      role: "user",
+      content: [
+        { type: "text", text: "describe " },
+        { type: "image", data: "<base64>", mimeType: "image/png" },
+        { type: "text", text: "this" },
+      ],
+    });
+    expect(m.snapshotQueue().followUp).toEqual([]);
+  });
+
+  it("ignores non-user message_start (assistant role does not touch the queue)", () => {
+    const m = makeShadowDrainMatcher();
+    m.recordFollowup("a");
+    const baselineEmits = m.emits.length;
+
+    m.onUserMessageStart({ role: "assistant", content: "a" });
+    expect(m.snapshotQueue().followUp).toEqual(["a"]);
+    expect(m.emits.length).toBe(baselineEmits);
+  });
+
+  it("removes only the FIRST occurrence on duplicate text (FIFO)", () => {
+    const m = makeShadowDrainMatcher();
+    m.recordFollowup("dup");
+    m.recordFollowup("other");
+    m.recordFollowup("dup");
+    expect(m.snapshotQueue().followUp).toEqual(["dup", "other", "dup"]);
+
+    m.onUserMessageStart({ role: "user", content: "dup" });
+    // First "dup" removed; second one still queued (FIFO).
+    expect(m.snapshotQueue().followUp).toEqual(["other", "dup"]);
+
+    m.onUserMessageStart({ role: "user", content: "dup" });
+    expect(m.snapshotQueue().followUp).toEqual(["other"]);
+  });
+
+  it("entries added DURING drain are preserved (no bulk wipe)", () => {
+    const m = makeShadowDrainMatcher();
+    m.recordFollowup("a");
+    m.recordFollowup("b");
+
+    // Pi drains "a"
+    m.onUserMessageStart({ role: "user", content: "a" });
+    expect(m.snapshotQueue().followUp).toEqual(["b"]);
+
+    // User adds a new entry "c" while pi is still draining
+    m.recordFollowup("c");
+    expect(m.snapshotQueue().followUp).toEqual(["b", "c"]);
+
+    // Pi drains "b"
+    m.onUserMessageStart({ role: "user", content: "b" });
+    // "c" must still be present
+    expect(m.snapshotQueue().followUp).toEqual(["c"]);
+
+    // Eventually pi drains "c"
+    m.onUserMessageStart({ role: "user", content: "c" });
+    expect(m.snapshotQueue().followUp).toEqual([]);
+  });
+});

package/packages/extension/src/__tests__/bridge-shadow-queue-gate.test.ts

@@ -0,0 +1,299 @@
+/**
+ * Tests for the bridge's shadow-queue streaming gate.
+ *
+ * Repro for the bug "STEERING (1) appears on the very first message to an
+ * idle session". The fix has TWO layers:
+ *
+ * 1. Capture-before-send (primary gate): at the call site of
+ *    `pi.sendUserMessage`, the caller MUST snapshot
+ *    `isAgentStreaming` BEFORE invoking sendUserMessage. Pi flips
+ *    idle→streaming synchronously inside sendUserMessage by emitting
+ *    `agent_start`, whose handler in bridge.ts flips the flag in its
+ *    first sync line. Checking the flag AFTER the send always reads
+ *    true — the original bug. Tests `record*Sent + wasStreaming`
+ *    encode that contract.
+ *
+ * 2. Internal gate (defense in depth): `recordSteerSent` /
+ *    `recordFollowupSent` themselves re-check `isStreaming()` so a
+ *    caller that forgets to capture pre-send still doesn't corrupt
+ *    the shadow queue.
+ *
+ * See change: add-followup-edit-and-steer-cancel.
+ */
+import { describe, it, expect, vi } from "vitest";
+
+interface ShadowQueue {
+  steering: string[];
+  followUp: string[];
+}
+
+/**
+ * Pure version of the gate as it lives in bridge.ts. Mirrors the closure
+ * logic 1:1; if the production code drifts from this shape, this test
+ * should drift in lockstep.
+ */
+function makeShadowRecorder(opts: {
+  isStreaming: () => boolean;
+  onEmit: (snapshot: ShadowQueue) => void;
+}) {
+  const queue: ShadowQueue = { steering: [], followUp: [] };
+  function emit() { opts.onEmit({ steering: [...queue.steering], followUp: [...queue.followUp] }); }
+  function recordSteer(text: string) {
+    if (!opts.isStreaming()) return;
+    queue.steering.push(text);
+    emit();
+  }
+  function recordFollowup(text: string) {
+    if (!opts.isStreaming()) return;
+    queue.followUp = [text];
+    emit();
+  }
+  function clearSteer() { queue.steering = []; emit(); }
+  function clearFollowup() { queue.followUp = []; emit(); }
+  function drainSteerOnTurnEnd() { if (queue.steering.length > 0) { queue.steering = []; emit(); } }
+  function drainFollowupOnAgentEnd() { if (queue.followUp.length > 0) { queue.followUp = []; emit(); } }
+  return { recordSteer, recordFollowup, clearSteer, clearFollowup, drainSteerOnTurnEnd, drainFollowupOnAgentEnd, snapshot: () => ({ ...queue, steering: [...queue.steering], followUp: [...queue.followUp] }) };
+}
+
+describe("bridge shadow queue: streaming gate", () => {
+  it("recordSteer is a no-op when isStreaming === false (idle first message)", () => {
+    let streaming = false;
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => streaming, onEmit });
+
+    r.recordSteer("hello");
+
+    expect(r.snapshot().steering).toEqual([]);
+    expect(onEmit).not.toHaveBeenCalled();
+  });
+
+  it("recordFollowup is a no-op when isStreaming === false (idle first message)", () => {
+    let streaming = false;
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => streaming, onEmit });
+
+    r.recordFollowup("after done");
+
+    expect(r.snapshot().followUp).toEqual([]);
+    expect(onEmit).not.toHaveBeenCalled();
+  });
+
+  it("recordSteer appends + emits when streaming", () => {
+    let streaming = true;
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => streaming, onEmit });
+
+    r.recordSteer("A");
+    r.recordSteer("B");
+
+    expect(r.snapshot().steering).toEqual(["A", "B"]);
+    expect(onEmit).toHaveBeenCalledTimes(2);
+    expect(onEmit.mock.calls[1][0]).toEqual({ steering: ["A", "B"], followUp: [] });
+  });
+
+  it("recordFollowup replaces slot + emits when streaming (capacity 1)", () => {
+    let streaming = true;
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => streaming, onEmit });
+
+    r.recordFollowup("first");
+    r.recordFollowup("second");
+
+    expect(r.snapshot().followUp).toEqual(["second"]);
+    expect(onEmit).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("bridge shadow queue: drain boundaries", () => {
+  it("turn_end drains steering only (followUp untouched)", () => {
+    let streaming = true;
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => streaming, onEmit });
+    r.recordSteer("s1");
+    r.recordFollowup("f1");
+    onEmit.mockClear();
+
+    r.drainSteerOnTurnEnd();
+
+    expect(r.snapshot()).toEqual({ steering: [], followUp: ["f1"] });
+    expect(onEmit).toHaveBeenCalledTimes(1);
+  });
+
+  it("agent_end drains followUp only (steering untouched)", () => {
+    let streaming = true;
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => streaming, onEmit });
+    r.recordSteer("s1");
+    r.recordFollowup("f1");
+    onEmit.mockClear();
+
+    r.drainFollowupOnAgentEnd();
+
+    expect(r.snapshot()).toEqual({ steering: ["s1"], followUp: [] });
+    expect(onEmit).toHaveBeenCalledTimes(1);
+  });
+
+  it("turn_end on empty steering does NOT emit (idempotent / no spurious broadcasts)", () => {
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => true, onEmit });
+
+    r.drainSteerOnTurnEnd();
+
+    expect(onEmit).not.toHaveBeenCalled();
+  });
+
+  it("agent_end on empty followUp does NOT emit", () => {
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => true, onEmit });
+
+    r.drainFollowupOnAgentEnd();
+
+    expect(onEmit).not.toHaveBeenCalled();
+  });
+});
+
+describe("bridge shadow queue: clears", () => {
+  it("clearSteer wipes + emits regardless of streaming state", () => {
+    let streaming = false;
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => streaming, onEmit });
+    // Populate via a streaming-on phase, then go idle and clear.
+    streaming = true; r.recordSteer("x"); streaming = false; onEmit.mockClear();
+
+    r.clearSteer();
+
+    expect(r.snapshot().steering).toEqual([]);
+    expect(onEmit).toHaveBeenCalledTimes(1);
+  });
+
+  it("clearFollowup wipes + emits regardless of streaming state", () => {
+    let streaming = false;
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => streaming, onEmit });
+    streaming = true; r.recordFollowup("y"); streaming = false; onEmit.mockClear();
+
+    r.clearFollowup();
+
+    expect(r.snapshot().followUp).toEqual([]);
+    expect(onEmit).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("bridge shadow queue: capture-before-send semantics (PRIMARY gate)", () => {
+  // Simulates the command-handler / sessionPrompt call sites where the bug
+  // originally lived. The fix: capture streaming state into a local var
+  // BEFORE calling pi.sendUserMessage. The internal recordX gate is a
+  // safety net only.
+
+  /** Stand-in for the simplified call-site logic in command-handler.ts. */
+  function send(opts: {
+    text: string;
+    delivery: "steer" | "followUp";
+    isStreaming: () => boolean;
+    piSendUserMessage: () => void; // simulates the synchronous agent_start flip
+    onSteer: (text: string) => void;
+    onFollowup: (text: string) => void;
+  }) {
+    const wasStreaming = opts.isStreaming();
+    opts.piSendUserMessage();
+    if (wasStreaming) {
+      if (opts.delivery === "steer") opts.onSteer(opts.text);
+      else opts.onFollowup(opts.text);
+    }
+  }
+
+  it("idle send DOES NOT record even when pi flips isStreaming synchronously inside sendUserMessage", () => {
+    let streaming = false;
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => streaming, onEmit });
+
+    send({
+      text: "first message",
+      delivery: "steer",
+      isStreaming: () => streaming,
+      // Pi receives the message, fires agent_start synchronously, which
+      // flips `streaming` to true. This was the original bug.
+      piSendUserMessage: () => { streaming = true; },
+      onSteer: r.recordSteer,
+      onFollowup: r.recordFollowup,
+    });
+
+    expect(r.snapshot()).toEqual({ steering: [], followUp: [] });
+    expect(onEmit).not.toHaveBeenCalled();
+  });
+
+  it("streaming send DOES record (chip appears for mid-turn steer)", () => {
+    let streaming = true;
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => streaming, onEmit });
+
+    send({
+      text: "redirect",
+      delivery: "steer",
+      isStreaming: () => streaming,
+      piSendUserMessage: () => { /* still streaming */ },
+      onSteer: r.recordSteer,
+      onFollowup: r.recordFollowup,
+    });
+
+    expect(r.snapshot().steering).toEqual(["redirect"]);
+    expect(onEmit).toHaveBeenCalledTimes(1);
+  });
+
+  it("idle followUp also DOES NOT record (same race shape)", () => {
+    let streaming = false;
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => streaming, onEmit });
+
+    send({
+      text: "after done",
+      delivery: "followUp",
+      isStreaming: () => streaming,
+      piSendUserMessage: () => { streaming = true; },
+      onSteer: r.recordSteer,
+      onFollowup: r.recordFollowup,
+    });
+
+    expect(r.snapshot()).toEqual({ steering: [], followUp: [] });
+    expect(onEmit).not.toHaveBeenCalled();
+  });
+});
+
+describe("bridge shadow queue: realistic follow-up scenario", () => {
+  it("send followUp while idle (first message of session) shows no chip", () => {
+    let streaming = false;
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => streaming, onEmit });
+
+    // User sends their initial prompt; pi starts a new turn directly,
+    // it doesn't queue. The bridge must NOT record a chip.
+    r.recordFollowup("kick off the task");
+
+    expect(r.snapshot().followUp).toEqual([]);
+    expect(onEmit).not.toHaveBeenCalled();
+
+    // Pi fires agent_start → streaming flips on.
+    streaming = true;
+
+    // User adds a follow-up mid-stream → chip appears.
+    r.recordFollowup("when you finish, run the tests");
+    expect(r.snapshot().followUp).toEqual(["when you finish, run the tests"]);
+    expect(onEmit).toHaveBeenCalledTimes(1);
+
+    // Agent finishes → followUp drains.
+    r.drainFollowupOnAgentEnd();
+    expect(r.snapshot().followUp).toEqual([]);
+  });
+
+  it("rapid edit (steering still active) replaces slot atomically", () => {
+    const onEmit = vi.fn();
+    const r = makeShadowRecorder({ isStreaming: () => true, onEmit });
+
+    r.recordFollowup("v1");
+    r.recordFollowup("v2");
+    r.recordFollowup("v3");
+
+    expect(r.snapshot().followUp).toEqual(["v3"]);
+    expect(onEmit).toHaveBeenCalledTimes(3);
+  });
+});