@hellcoder/companion 0.96.0

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

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "vitest";
+import { isHistoryBackedEvent } from "./ws-bridge-replay.js";
+import type { ReplayableBrowserIncomingMessage } from "./session-types.js";
+
+describe("isHistoryBackedEvent", () => {
+  it("treats persisted system_event subtypes as history-backed", () => {
+    // compact_boundary is persisted in messageHistory, so replay fallback can
+    // safely skip it and rely on message_history payload.
+    const msg: ReplayableBrowserIncomingMessage = {
+      type: "system_event",
+      event: {
+        subtype: "compact_boundary",
+        compact_metadata: { trigger: "auto", pre_tokens: 1234 },
+        uuid: "u1",
+        session_id: "s1",
+      },
+      timestamp: 1000,
+    };
+
+    expect(isHistoryBackedEvent(msg)).toBe(true);
+  });
+
+  it("treats hook_progress as transient (not history-backed)", () => {
+    // hook_progress is intentionally not persisted to avoid history bloat,
+    // so replay fallback must keep sending missed events from the buffer.
+    const msg: ReplayableBrowserIncomingMessage = {
+      type: "system_event",
+      event: {
+        subtype: "hook_progress",
+        hook_id: "hk-1",
+        hook_name: "lint",
+        hook_event: "post_tool_use",
+        stdout: "running",
+        stderr: "",
+        output: "running",
+        uuid: "u2",
+        session_id: "s1",
+      },
+      timestamp: 1001,
+    };
+
+    expect(isHistoryBackedEvent(msg)).toBe(false);
+  });
+});

package/server/ws-bridge-replay.ts

@@ -0,0 +1,61 @@
+import type {
+  BrowserIncomingMessage,
+  ReplayableBrowserIncomingMessage,
+} from "./session-types.js";
+import type { Session } from "./ws-bridge-types.js";
+
+export function isDuplicateClientMessage(session: Session, clientMsgId: string): boolean {
+  return session.processedClientMessageIdSet.has(clientMsgId);
+}
+
+export function rememberClientMessage(
+  session: Session,
+  clientMsgId: string,
+  processedClientMsgIdLimit: number,
+  persistSession: (session: Session) => void,
+): void {
+  session.processedClientMessageIds.push(clientMsgId);
+  session.processedClientMessageIdSet.add(clientMsgId);
+  if (session.processedClientMessageIds.length > processedClientMsgIdLimit) {
+    const overflow = session.processedClientMessageIds.length - processedClientMsgIdLimit;
+    const removed = session.processedClientMessageIds.splice(0, overflow);
+    for (const id of removed) {
+      session.processedClientMessageIdSet.delete(id);
+    }
+  }
+  persistSession(session);
+}
+
+export function shouldBufferForReplay(
+  msg: BrowserIncomingMessage,
+): msg is ReplayableBrowserIncomingMessage {
+  return msg.type !== "session_init"
+    && msg.type !== "message_history"
+    && msg.type !== "event_replay";
+}
+
+export function isHistoryBackedEvent(msg: ReplayableBrowserIncomingMessage): boolean {
+  return msg.type === "assistant"
+    || msg.type === "result"
+    || msg.type === "user_message"
+    || (msg.type === "system_event" && msg.event.subtype !== "hook_progress")
+    || msg.type === "error";
+}
+
+export function sequenceEvent(
+  session: Session,
+  msg: BrowserIncomingMessage,
+  eventBufferLimit: number,
+  persistSession: (session: Session) => void,
+): BrowserIncomingMessage {
+  const seq = session.nextEventSeq++;
+  const sequenced = { ...msg, seq };
+  if (shouldBufferForReplay(msg)) {
+    session.eventBuffer.push({ seq, message: msg });
+    if (session.eventBuffer.length > eventBufferLimit) {
+      session.eventBuffer.splice(0, session.eventBuffer.length - eventBufferLimit);
+    }
+    persistSession(session);
+  }
+  return sequenced;
+}

package/server/ws-bridge-types.ts

@@ -0,0 +1,106 @@
+import type { ServerWebSocket } from "bun";
+import type {
+  BackendType,
+  BrowserIncomingMessage,
+  PermissionRequest,
+  SessionState,
+  BufferedBrowserEvent,
+} from "./session-types.js";
+import type { IBackendAdapter } from "./backend-adapter.js";
+import type { SessionStateMachine } from "./session-state-machine.js";
+import { getSettings } from "./settings-manager.js";
+
+export interface CLISocketData {
+  kind: "cli";
+  sessionId: string;
+}
+
+export interface BrowserSocketData {
+  kind: "browser";
+  sessionId: string;
+  subscribed?: boolean;
+  lastAckSeq?: number;
+}
+
+export interface TerminalSocketData {
+  kind: "terminal";
+  terminalId: string;
+}
+
+export interface NoVncSocketData {
+  kind: "novnc";
+  sessionId: string;
+}
+
+export type SocketData = CLISocketData | BrowserSocketData | TerminalSocketData | NoVncSocketData;
+
+/** Tracks a pending control_request sent to CLI that expects a control_response. */
+export interface PendingControlRequest {
+  subtype: string;
+  resolve: (response: unknown) => void;
+}
+
+export interface Session {
+  id: string;
+  backendType: BackendType;
+  /** Unified backend adapter — replaces the former cliSocket (Claude) / codexAdapter (Codex) fields. */
+  backendAdapter: IBackendAdapter | null;
+  browserSockets: Set<ServerWebSocket<SocketData>>;
+  state: SessionState;
+  pendingPermissions: Map<string, PermissionRequest>;
+  messageHistory: BrowserIncomingMessage[];
+  pendingMessages: string[];
+  nextEventSeq: number;
+  eventBuffer: BufferedBrowserEvent[];
+  lastAckSeq: number;
+  processedClientMessageIds: string[];
+  processedClientMessageIdSet: Set<string>;
+  /** Timestamp of last non-keepalive CLI message (for idle detection) */
+  lastCliActivityTs: number;
+  /** Formal session state machine tracking phase and validating transitions. */
+  stateMachine: SessionStateMachine;
+  /** Cleanup function for state machine transition listener — call on session teardown. */
+  unsubscribeStateMachine?: () => void;
+}
+
+export type GitSessionKey =
+  | "git_branch"
+  | "is_worktree"
+  | "is_containerized"
+  | "repo_root"
+  | "git_ahead"
+  | "git_behind";
+
+export function makeDefaultState(
+  sessionId: string,
+  backendType: BackendType = "claude",
+): SessionState {
+  return {
+    session_id: sessionId,
+    backend_type: backendType,
+    model: "",
+    cwd: "",
+    tools: [],
+    permissionMode: "default",
+    claude_code_version: "",
+    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: getSettings().aiValidationEnabled,
+    aiValidationAutoApprove: getSettings().aiValidationAutoApprove,
+    aiValidationAutoDeny: getSettings().aiValidationAutoDeny,
+  };
+}