heyhank 0.1.0

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.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
+  }
+}
+

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,121 @@
+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 interface NodeSocketData {
+  kind: "node";
+  nodeId: string;
+}
+
+export interface TelephonyAudioSocketData {
+  kind: "telephony-audio";
+  callId: string;
+}
+
+export interface TelephonyTranscriptSocketData {
+  kind: "telephony-transcript";
+  callId: string;
+}
+
+export type SocketData = CLISocketData | BrowserSocketData | TerminalSocketData | NoVncSocketData | NodeSocketData | TelephonyAudioSocketData | TelephonyTranscriptSocketData;
+
+/** 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,
+  };
+}