@hellcoder/companion 0.96.0

package/server/ws-bridge-persist.test.ts

@@ -0,0 +1,296 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+  appendAndPersist,
+  appendHistory,
+  persistSession,
+  serializeForStore,
+  MESSAGE_HISTORY_LIMIT,
+} from "./ws-bridge-persist.js";
+import type { Session } from "./ws-bridge-types.js";
+import type { BrowserIncomingMessage } from "./session-types.js";
+import { SessionStateMachine } from "./session-state-machine.js";
+import { SessionStore } from "./session-store.js";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+function makeSession(overrides: Partial<Session> = {}): Session {
+  return {
+    id: "test-session",
+    backendType: "claude",
+    backendAdapter: null,
+    browserSockets: new Set(),
+    state: {
+      session_id: "test-session",
+      model: "claude-sonnet-4-6",
+      cwd: "/test",
+      tools: [],
+      permissionMode: "default",
+      claude_code_version: "1.0",
+      mcp_servers: [],
+      agents: [],
+      slash_commands: [],
+      skills: [],
+      total_cost_usd: 0,
+      num_turns: 0,
+      context_used_percent: 0,
+      is_compacting: false,
+      git_branch: "",
+      is_worktree: false,
+      is_containerized: false,
+      repo_root: "",
+      git_ahead: 0,
+      git_behind: 0,
+      total_lines_added: 0,
+      total_lines_removed: 0,
+      aiValidationEnabled: false,
+      aiValidationAutoApprove: false,
+      aiValidationAutoDeny: false,
+    },
+    pendingPermissions: new Map(),
+    messageHistory: [],
+    pendingMessages: [],
+    nextEventSeq: 1,
+    eventBuffer: [],
+    lastAckSeq: 0,
+    processedClientMessageIds: [],
+    processedClientMessageIdSet: new Set(),
+    lastCliActivityTs: Date.now(),
+    stateMachine: new SessionStateMachine("test-session"),
+    ...overrides,
+  };
+}
+
+function makeAssistantMsg(id: string): BrowserIncomingMessage {
+  return {
+    type: "assistant",
+    message: { id, type: "message", role: "assistant", model: "claude", content: [], stop_reason: "end_turn", usage: { input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0, cache_read_input_tokens: 0 } },
+    parent_tool_use_id: null,
+    timestamp: Date.now(),
+  };
+}
+
+// ─── appendHistory ────────────────────────────────────────────────────────────
+
+describe("appendHistory", () => {
+  it("appends message to session history", () => {
+    const session = makeSession();
+    const msg = makeAssistantMsg("m1");
+    appendHistory(session, msg);
+
+    expect(session.messageHistory).toHaveLength(1);
+    expect(session.messageHistory[0]).toBe(msg);
+  });
+
+  it("appends multiple messages in order", () => {
+    const session = makeSession();
+    const msg1 = makeAssistantMsg("m1");
+    const msg2 = makeAssistantMsg("m2");
+    const msg3 = makeAssistantMsg("m3");
+
+    appendHistory(session, msg1);
+    appendHistory(session, msg2);
+    appendHistory(session, msg3);
+
+    expect(session.messageHistory).toHaveLength(3);
+    // Verify ordering is preserved
+    expect((session.messageHistory[0] as any).message.id).toBe("m1");
+    expect((session.messageHistory[1] as any).message.id).toBe("m2");
+    expect((session.messageHistory[2] as any).message.id).toBe("m3");
+  });
+
+  it("trims oldest messages when history exceeds limit", () => {
+    const session = makeSession();
+    const limit = 5;
+
+    // Add 7 messages with limit of 5
+    for (let i = 0; i < 7; i++) {
+      appendHistory(session, makeAssistantMsg(`m${i}`), limit);
+    }
+
+    expect(session.messageHistory).toHaveLength(5);
+    // Oldest 2 (m0, m1) should be trimmed; m2-m6 remain
+    expect((session.messageHistory[0] as any).message.id).toBe("m2");
+    expect((session.messageHistory[4] as any).message.id).toBe("m6");
+  });
+
+  it("uses MESSAGE_HISTORY_LIMIT as default", () => {
+    expect(MESSAGE_HISTORY_LIMIT).toBe(2000);
+  });
+});
+
+// ─── persistSession ───────────────────────────────────────────────────────────
+
+describe("persistSession", () => {
+  let tempDir: string;
+  let store: SessionStore;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "persist-test-"));
+    store = new SessionStore(tempDir);
+    // Suppress console output
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    store.dispose();
+    rmSync(tempDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("calls store.save with serialized session data", () => {
+    const session = makeSession();
+    const saveSpy = vi.spyOn(store, "save");
+
+    persistSession(session, store);
+
+    expect(saveSpy).toHaveBeenCalledTimes(1);
+    const saved = saveSpy.mock.calls[0][0];
+    expect(saved.id).toBe("test-session");
+    expect(saved.state).toBe(session.state);
+    expect(saved.messageHistory).toBe(session.messageHistory);
+  });
+
+  it("is a no-op when store is null", () => {
+    const session = makeSession();
+    // Should not throw
+    expect(() => persistSession(session, null)).not.toThrow();
+  });
+});
+
+// ─── appendAndPersist ─────────────────────────────────────────────────────────
+
+describe("appendAndPersist", () => {
+  let tempDir: string;
+  let store: SessionStore;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "persist-test-"));
+    store = new SessionStore(tempDir);
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    store.dispose();
+    rmSync(tempDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("appends message to history AND calls store.save", () => {
+    const session = makeSession();
+    const msg = makeAssistantMsg("m1");
+    const saveSpy = vi.spyOn(store, "save");
+
+    appendAndPersist(session, msg, store);
+
+    expect(session.messageHistory).toHaveLength(1);
+    expect(saveSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("enforces history cap while persisting", () => {
+    const session = makeSession();
+    const limit = 3;
+
+    for (let i = 0; i < 5; i++) {
+      appendAndPersist(session, makeAssistantMsg(`m${i}`), store, limit);
+    }
+
+    expect(session.messageHistory).toHaveLength(3);
+    expect((session.messageHistory[0] as any).message.id).toBe("m2");
+  });
+
+  it("works with null store (append only)", () => {
+    const session = makeSession();
+    const msg = makeAssistantMsg("m1");
+
+    appendAndPersist(session, msg, null);
+
+    expect(session.messageHistory).toHaveLength(1);
+  });
+});
+
+// ─── serializeForStore ────────────────────────────────────────────────────────
+
+describe("serializeForStore", () => {
+  it("converts pendingPermissions Map to array of entries", () => {
+    const session = makeSession();
+    session.pendingPermissions.set("req-1", {
+      request_id: "req-1",
+      tool_name: "Bash",
+      input: { command: "ls" },
+      timestamp: 1000,
+    } as any);
+    session.pendingPermissions.set("req-2", {
+      request_id: "req-2",
+      tool_name: "Read",
+      input: { file_path: "/test" },
+      timestamp: 2000,
+    } as any);
+
+    const serialized = serializeForStore(session);
+
+    expect(serialized.pendingPermissions).toHaveLength(2);
+    expect(serialized.pendingPermissions[0][0]).toBe("req-1");
+    expect(serialized.pendingPermissions[0][1].tool_name).toBe("Bash");
+    expect(serialized.pendingPermissions[1][0]).toBe("req-2");
+    expect(serialized.pendingPermissions[1][1].tool_name).toBe("Read");
+  });
+
+  it("includes eventBuffer and sequence counters", () => {
+    const session = makeSession({
+      eventBuffer: [{ seq: 1, message: { type: "cli_connected" } }],
+      nextEventSeq: 42,
+      lastAckSeq: 10,
+    });
+
+    const serialized = serializeForStore(session);
+
+    expect(serialized.eventBuffer).toHaveLength(1);
+    expect(serialized.nextEventSeq).toBe(42);
+    expect(serialized.lastAckSeq).toBe(10);
+  });
+
+  it("includes processedClientMessageIds for browser dedup restoration", () => {
+    const session = makeSession({
+      processedClientMessageIds: ["id-1", "id-2", "id-3"],
+    });
+
+    const serialized = serializeForStore(session);
+    expect(serialized.processedClientMessageIds).toEqual(["id-1", "id-2", "id-3"]);
+  });
+
+  it("preserves message ordering through serialization", () => {
+    const session = makeSession();
+    for (let i = 0; i < 5; i++) {
+      session.messageHistory.push(makeAssistantMsg(`m${i}`));
+    }
+
+    const serialized = serializeForStore(session);
+    const parsed = JSON.parse(JSON.stringify(serialized));
+
+    // Message ordering should survive JSON round-trip
+    for (let i = 0; i < 5; i++) {
+      expect(parsed.messageHistory[i].message.id).toBe(`m${i}`);
+    }
+  });
+
+  it("produces identical output for same session state (idempotent)", () => {
+    const session = makeSession();
+    session.messageHistory.push(makeAssistantMsg("m1"));
+    session.pendingPermissions.set("req-1", {
+      request_id: "req-1",
+      tool_name: "Bash",
+      input: {},
+      timestamp: 1000,
+    } as any);
+
+    const first = JSON.stringify(serializeForStore(session));
+    const second = JSON.stringify(serializeForStore(session));
+
+    expect(first).toBe(second);
+  });
+});

package/server/ws-bridge-persist.ts

@@ -0,0 +1,66 @@
+import type { BrowserIncomingMessage } from "./session-types.js";
+import type { Session } from "./ws-bridge-types.js";
+import type { SessionStore, PersistedSession } from "./session-store.js";
+
+// ─── Persistence Pipeline ───────────────────────────────────────────────────
+// Extracted from WsBridge to consolidate history append + disk persistence
+// into explicit, testable functions.
+
+export const MESSAGE_HISTORY_LIMIT = 2000;
+
+/**
+ * Append a message to session history with cap enforcement, then persist to disk.
+ * Consolidates the common appendHistory + persistSession pattern into one call,
+ * eliminating the risk of appending without persisting.
+ */
+export function appendAndPersist(
+  session: Session,
+  msg: BrowserIncomingMessage,
+  store: SessionStore | null,
+  historyLimit: number = MESSAGE_HISTORY_LIMIT,
+): void {
+  appendHistory(session, msg, historyLimit);
+  persistSession(session, store);
+}
+
+/**
+ * Append a message to session history with cap enforcement.
+ * Trims oldest messages when the history exceeds the limit.
+ */
+export function appendHistory(
+  session: Session,
+  msg: BrowserIncomingMessage,
+  historyLimit: number = MESSAGE_HISTORY_LIMIT,
+): void {
+  session.messageHistory.push(msg);
+  if (session.messageHistory.length > historyLimit) {
+    session.messageHistory.splice(0, session.messageHistory.length - historyLimit);
+  }
+}
+
+/**
+ * Persist session state to disk (debounced via SessionStore).
+ * No-op if no store is attached.
+ */
+export function persistSession(session: Session, store: SessionStore | null): void {
+  if (!store) return;
+  store.save(serializeForStore(session));
+}
+
+/**
+ * Serialize a Session into the shape expected by SessionStore.save().
+ * Converts Maps to arrays and selects the persisted fields.
+ */
+export function serializeForStore(session: Session): PersistedSession {
+  return {
+    id: session.id,
+    state: session.state,
+    messageHistory: session.messageHistory,
+    pendingMessages: session.pendingMessages,
+    pendingPermissions: Array.from(session.pendingPermissions.entries()),
+    eventBuffer: session.eventBuffer,
+    nextEventSeq: session.nextEventSeq,
+    lastAckSeq: session.lastAckSeq,
+    processedClientMessageIds: session.processedClientMessageIds,
+  };
+}

package/server/ws-bridge-publish.test.ts

@@ -0,0 +1,234 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+  broadcastToBrowsers,
+  sendToBrowser,
+  EVENT_BUFFER_LIMIT,
+} from "./ws-bridge-publish.js";
+import type { Session, SocketData } from "./ws-bridge-types.js";
+import type { BrowserIncomingMessage } from "./session-types.js";
+import { SessionStateMachine } from "./session-state-machine.js";
+import type { ServerWebSocket } from "bun";
+
+function makeMockSocket(sessionId = "test-session") {
+  return {
+    data: { kind: "browser", sessionId } as SocketData,
+    send: vi.fn(),
+    close: vi.fn(),
+    readyState: 1,
+  } as unknown as ServerWebSocket<SocketData>;
+}
+
+function makeSession(overrides: Partial<Session> = {}): Session {
+  return {
+    id: "test-session",
+    backendType: "claude",
+    backendAdapter: null,
+    browserSockets: new Set(),
+    state: {
+      session_id: "test-session",
+      model: "claude-sonnet-4-6",
+      cwd: "/test",
+      tools: [],
+      permissionMode: "default",
+      claude_code_version: "1.0",
+      mcp_servers: [],
+      agents: [],
+      slash_commands: [],
+      skills: [],
+      total_cost_usd: 0,
+      num_turns: 0,
+      context_used_percent: 0,
+      is_compacting: false,
+      git_branch: "",
+      is_worktree: false,
+      is_containerized: false,
+      repo_root: "",
+      git_ahead: 0,
+      git_behind: 0,
+      total_lines_added: 0,
+      total_lines_removed: 0,
+      aiValidationEnabled: false,
+      aiValidationAutoApprove: false,
+      aiValidationAutoDeny: false,
+    },
+    pendingPermissions: new Map(),
+    messageHistory: [],
+    pendingMessages: [],
+    nextEventSeq: 1,
+    eventBuffer: [],
+    lastAckSeq: 0,
+    processedClientMessageIds: [],
+    processedClientMessageIdSet: new Set(),
+    lastCliActivityTs: Date.now(),
+    stateMachine: new SessionStateMachine("test-session"),
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  vi.spyOn(console, "log").mockImplementation(() => {});
+  vi.spyOn(console, "warn").mockImplementation(() => {});
+  vi.spyOn(console, "error").mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ─── broadcastToBrowsers ──────────────────────────────────────────────────────
+
+describe("broadcastToBrowsers", () => {
+  it("sends message to all connected browser sockets", () => {
+    const ws1 = makeMockSocket();
+    const ws2 = makeMockSocket();
+    const session = makeSession();
+    session.browserSockets.add(ws1);
+    session.browserSockets.add(ws2);
+
+    const msg: BrowserIncomingMessage = { type: "cli_connected" };
+    broadcastToBrowsers(session, msg, {
+      eventBufferLimit: EVENT_BUFFER_LIMIT,
+      recorder: null,
+      persistFn: vi.fn(),
+    });
+
+    expect(ws1.send).toHaveBeenCalledTimes(1);
+    expect(ws2.send).toHaveBeenCalledTimes(1);
+
+    // Both should receive the same JSON
+    const sent1 = (ws1.send as any).mock.calls[0][0];
+    const sent2 = (ws2.send as any).mock.calls[0][0];
+    expect(sent1).toBe(sent2);
+  });
+
+  it("removes broken sockets that throw on send", () => {
+    const goodWs = makeMockSocket();
+    const badWs = makeMockSocket();
+    (badWs.send as any).mockImplementation(() => { throw new Error("broken"); });
+
+    const session = makeSession();
+    session.browserSockets.add(goodWs);
+    session.browserSockets.add(badWs);
+
+    broadcastToBrowsers(session, { type: "cli_connected" }, {
+      eventBufferLimit: EVENT_BUFFER_LIMIT,
+      recorder: null,
+      persistFn: vi.fn(),
+    });
+
+    // Good socket still connected, bad one removed
+    expect(session.browserSockets.has(goodWs)).toBe(true);
+    expect(session.browserSockets.has(badWs)).toBe(false);
+  });
+
+  it("assigns monotonically increasing seq numbers", () => {
+    const ws = makeMockSocket();
+    const session = makeSession();
+    session.browserSockets.add(ws);
+
+    const opts = {
+      eventBufferLimit: EVENT_BUFFER_LIMIT,
+      recorder: null,
+      persistFn: vi.fn(),
+    };
+
+    // Send 3 messages
+    broadcastToBrowsers(session, { type: "cli_connected" }, opts);
+    broadcastToBrowsers(session, { type: "cli_disconnected" }, opts);
+    broadcastToBrowsers(session, { type: "cli_connected" }, opts);
+
+    const seqs = (ws.send as any).mock.calls.map((call: any) => {
+      const parsed = JSON.parse(call[0]);
+      return parsed.seq;
+    });
+
+    // seq numbers should be strictly increasing
+    expect(seqs[0]).toBeLessThan(seqs[1]);
+    expect(seqs[1]).toBeLessThan(seqs[2]);
+  });
+
+  it("calls recorder.record when recorder is provided", () => {
+    const ws = makeMockSocket();
+    const session = makeSession();
+    session.browserSockets.add(ws);
+
+    const recorder = {
+      record: vi.fn(),
+    };
+
+    broadcastToBrowsers(session, { type: "cli_connected" }, {
+      eventBufferLimit: EVENT_BUFFER_LIMIT,
+      recorder: recorder as any,
+      persistFn: vi.fn(),
+    });
+
+    expect(recorder.record).toHaveBeenCalledTimes(1);
+    expect(recorder.record).toHaveBeenCalledWith(
+      "test-session", "out", expect.any(String), "browser", "claude", "/test",
+    );
+  });
+
+  it("logs warning when broadcasting to 0 browsers for assistant/stream_event/result", () => {
+    const session = makeSession(); // no browser sockets
+    const logSpy = vi.mocked(console.log);
+
+    broadcastToBrowsers(session, { type: "assistant", message: {} as any, parent_tool_use_id: null, timestamp: 1 }, {
+      eventBufferLimit: EVENT_BUFFER_LIMIT,
+      recorder: null,
+      persistFn: vi.fn(),
+    });
+
+    expect(logSpy).toHaveBeenCalledWith(
+      expect.stringContaining("Broadcasting assistant to 0 browsers"),
+    );
+  });
+
+  it("does not warn for non-critical message types with 0 browsers", () => {
+    const session = makeSession();
+    const logSpy = vi.mocked(console.log);
+    logSpy.mockClear();
+
+    broadcastToBrowsers(session, { type: "cli_connected" }, {
+      eventBufferLimit: EVENT_BUFFER_LIMIT,
+      recorder: null,
+      persistFn: vi.fn(),
+    });
+
+    // Should not have the "Broadcasting ... to 0 browsers" warning
+    const warningCalls = logSpy.mock.calls.filter(
+      (call) => typeof call[0] === "string" && call[0].includes("0 browsers"),
+    );
+    expect(warningCalls).toHaveLength(0);
+  });
+});
+
+// ─── sendToBrowser ────────────────────────────────────────────────────────────
+
+describe("sendToBrowser", () => {
+  it("sends JSON-serialized message to socket", () => {
+    const ws = makeMockSocket();
+    const msg: BrowserIncomingMessage = { type: "cli_connected" };
+
+    sendToBrowser(ws, msg);
+
+    expect(ws.send).toHaveBeenCalledTimes(1);
+    const sent = JSON.parse((ws.send as any).mock.calls[0][0]);
+    expect(sent.type).toBe("cli_connected");
+  });
+
+  it("does not throw when socket.send fails", () => {
+    const ws = makeMockSocket();
+    (ws.send as any).mockImplementation(() => { throw new Error("broken"); });
+
+    // Should not throw
+    expect(() => sendToBrowser(ws, { type: "cli_connected" })).not.toThrow();
+  });
+});
+
+// ─── EVENT_BUFFER_LIMIT ───────────────────────────────────────────────────────
+
+describe("EVENT_BUFFER_LIMIT", () => {
+  it("is 600", () => {
+    expect(EVENT_BUFFER_LIMIT).toBe(600);
+  });
+});

package/server/ws-bridge-publish.ts

@@ -0,0 +1,79 @@
+import type { ServerWebSocket } from "bun";
+import type { BrowserIncomingMessage } from "./session-types.js";
+import type { Session, SocketData } from "./ws-bridge-types.js";
+import type { RecorderManager } from "./recorder.js";
+import { sequenceEvent } from "./ws-bridge-replay.js";
+
+// ─── Publish Pipeline ───────────────────────────────────────────────────────
+// Transport functions for sending messages to CLI and browser sockets.
+// Extracted from WsBridge to enable isolated testing of message delivery,
+// sequencing, and recording behavior.
+
+export const EVENT_BUFFER_LIMIT = 600;
+
+/**
+ * Broadcast a message to all connected browsers for a session.
+ * Assigns a monotonic sequence number via sequenceEvent, records the
+ * outgoing message, and sends to every browser socket (removing broken ones).
+ *
+ * Note: sequenceEvent internally calls persistFn when buffering events.
+ * Callers that also call persistSession after broadcastToBrowsers will
+ * trigger a redundant (but harmless) debounced save. This is intentional —
+ * the caller-side persist covers state mutations beyond the event buffer
+ * (e.g. messageHistory, pendingPermissions), while the internal persist
+ * covers the event buffer/seq counters. SessionStore's debouncer coalesces
+ * them into a single write.
+ */
+export function broadcastToBrowsers(
+  session: Session,
+  msg: BrowserIncomingMessage,
+  opts: {
+    eventBufferLimit: number;
+    recorder: RecorderManager | null;
+    persistFn: (session: Session) => void;
+  },
+): void {
+  // Warn when messages that should be visible to users are broadcast to 0 browsers
+  if (
+    session.browserSockets.size === 0
+    && (msg.type === "assistant" || msg.type === "stream_event" || msg.type === "result")
+  ) {
+    console.log(
+      `[ws-bridge] ⚠ Broadcasting ${msg.type} to 0 browsers for session ${session.id} (stored in history: ${msg.type === "assistant" || msg.type === "result"})`,
+    );
+  }
+
+  const json = JSON.stringify(
+    sequenceEvent(session, msg, opts.eventBufferLimit, opts.persistFn),
+  );
+
+  // Record raw outgoing browser message
+  opts.recorder?.record(
+    session.id, "out", json, "browser", session.backendType, session.state.cwd,
+  );
+
+  for (const ws of session.browserSockets) {
+    try {
+      ws.send(json);
+    } catch {
+      session.browserSockets.delete(ws);
+    }
+  }
+}
+
+/**
+ * Send a message to a single browser socket (no sequencing).
+ * Used for replay, session_init, and message_history — messages that
+ * should NOT go through the event buffer.
+ */
+export function sendToBrowser(
+  ws: ServerWebSocket<SocketData>,
+  msg: BrowserIncomingMessage,
+): void {
+  try {
+    ws.send(JSON.stringify(msg));
+  } catch {
+    // Socket will be cleaned up on close
+  }
+}
+