@hellcoder/companion 0.96.0

package/server/session-state-machine.ts

@@ -0,0 +1,207 @@
+// Formal session state machine for the Companion server.
+// Centralizes session phase definitions and validates transitions.
+
+import { metricsCollector } from "./metrics-collector.js";
+import { log } from "./logger.js";
+
+/**
+ * The formal phases a session can be in.
+ *
+ * - starting:            CLI process spawned, WS not yet connected
+ * - initializing:        CLI WS connected, awaiting system.init
+ * - ready:               Idle, awaiting user input
+ * - streaming:           Claude generating output (stream_event / assistant)
+ * - awaiting_permission: Tool call pending user approval
+ * - compacting:          Context window compaction in progress
+ * - reconnecting:        CLI socket dropped, within grace period
+ * - terminated:          Process exited or killed
+ */
+export type SessionPhase =
+  | "starting"
+  | "initializing"
+  | "ready"
+  | "streaming"
+  | "awaiting_permission"
+  | "compacting"
+  | "reconnecting"
+  | "terminated";
+
+/** Payload emitted on every successful state transition. */
+export interface SessionTransitionEvent {
+  sessionId: string;
+  from: SessionPhase;
+  to: SessionPhase;
+  trigger: string;
+  timestamp: number;
+}
+
+/**
+ * Defines which (from -> to) transitions are valid.
+ * Any transition not listed here will be blocked with a warning.
+ */
+export const VALID_TRANSITIONS: ReadonlyMap<
+  SessionPhase,
+  ReadonlySet<SessionPhase>
+> = new Map([
+  [
+    "starting",
+    new Set<SessionPhase>(["initializing", "streaming", "reconnecting", "terminated"]),
+  ],
+  [
+    "initializing",
+    new Set<SessionPhase>(["ready", "streaming", "reconnecting", "terminated"]),
+  ],
+  [
+    "ready",
+    new Set<SessionPhase>([
+      "streaming",
+      "compacting",
+      "reconnecting",
+      "terminated",
+    ]),
+  ],
+  [
+    "streaming",
+    new Set<SessionPhase>([
+      "ready",
+      "initializing",
+      "awaiting_permission",
+      "compacting",
+      "reconnecting",
+      "terminated",
+    ]),
+  ],
+  [
+    "awaiting_permission",
+    new Set<SessionPhase>(["streaming", "ready", "reconnecting", "terminated"]),
+  ],
+  [
+    "compacting",
+    new Set<SessionPhase>([
+      "ready",
+      "streaming",
+      "reconnecting",
+      "terminated",
+    ]),
+  ],
+  [
+    "reconnecting",
+    new Set<SessionPhase>(["initializing", "starting", "ready", "streaming", "terminated"]),
+  ],
+  ["terminated", new Set<SessionPhase>(["starting"])],
+]);
+
+type TransitionListener = (event: SessionTransitionEvent) => void;
+
+export class SessionStateMachine {
+  private _phase: SessionPhase;
+  private readonly _sessionId: string;
+  private _listeners: TransitionListener[] = [];
+
+  constructor(sessionId: string, initialPhase: SessionPhase = "starting") {
+    this._sessionId = sessionId;
+    this._phase = initialPhase;
+  }
+
+  get phase(): SessionPhase {
+    return this._phase;
+  }
+
+  get sessionId(): string {
+    return this._sessionId;
+  }
+
+  /**
+   * Attempt a state transition.
+   * Returns true if successful (or same-state no-op), false if blocked.
+   * Invalid transitions are logged but never throw.
+   */
+  transition(to: SessionPhase, trigger: string): boolean {
+    if (this._phase === to) return true;
+
+    const allowed = VALID_TRANSITIONS.get(this._phase);
+    if (!allowed || !allowed.has(to)) {
+      metricsCollector.recordError("invalid_state_transition");
+      log.warn("state-machine", "Blocked invalid transition", {
+        sessionId: this._sessionId,
+        from: this._phase,
+        to,
+        trigger,
+      });
+      return false;
+    }
+
+    const event: SessionTransitionEvent = {
+      sessionId: this._sessionId,
+      from: this._phase,
+      to,
+      trigger,
+      timestamp: Date.now(),
+    };
+
+    this._phase = to;
+
+    // Snapshot listeners so additions/removals during iteration are safe
+    const snapshot = this._listeners.slice();
+    for (const listener of snapshot) {
+      try {
+        listener(event);
+      } catch (err) {
+        console.error(
+          `[state-machine] Listener error for ${this._sessionId}:`,
+          err,
+        );
+      }
+    }
+
+    return true;
+  }
+
+  /** Subscribe to state transitions. Returns an unsubscribe function. */
+  onTransition(listener: TransitionListener): () => void {
+    this._listeners.push(listener);
+    return () => {
+      const idx = this._listeners.indexOf(listener);
+      if (idx !== -1) this._listeners.splice(idx, 1);
+    };
+  }
+
+  /**
+   * Force-set state without validation or listener notification.
+   * Used for restoring state from disk.
+   */
+  forceState(phase: SessionPhase): void {
+    this._phase = phase;
+  }
+
+  // -- Guard methods --
+
+  /** True only when session is idle and ready for a new user message. */
+  canAcceptUserMessage(): boolean {
+    return this._phase === "ready";
+  }
+
+  /** True only when a permission request is pending. */
+  canRespondToPermission(): boolean {
+    return this._phase === "awaiting_permission";
+  }
+
+  /** True when the CLI socket is expected to be reachable. */
+  canSendToCLI(): boolean {
+    return (
+      this._phase !== "terminated" &&
+      this._phase !== "reconnecting" &&
+      this._phase !== "starting"
+    );
+  }
+
+  /** True when the session has not terminated. */
+  isActive(): boolean {
+    return this._phase !== "terminated";
+  }
+
+  /** True only when the session is idle (ready). */
+  isIdle(): boolean {
+    return this._phase === "ready";
+  }
+}

package/server/session-store.test.ts

@@ -0,0 +1,290 @@
+import { mkdtempSync, rmSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { SessionStore, type PersistedSession } from "./session-store.js";
+
+let tempDir: string;
+let store: SessionStore;
+
+function makeSession(id: string, overrides: Partial<PersistedSession> = {}): PersistedSession {
+  return {
+    id,
+    state: {
+      session_id: id,
+      model: "claude-sonnet-4-6",
+      cwd: "/test",
+      tools: [],
+      permissionMode: "default",
+      claude_code_version: "1.0.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,
+    },
+    messageHistory: [],
+    pendingMessages: [],
+    pendingPermissions: [],
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), "ss-test-"));
+  store = new SessionStore(tempDir);
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+// ─── saveSync / load ──────────────────────────────────────────────────────────
+
+describe("saveSync / load", () => {
+  it("writes a session to disk and reads it back", () => {
+    const session = makeSession("s1");
+    store.saveSync(session);
+
+    const filePath = join(tempDir, "s1.json");
+    expect(existsSync(filePath)).toBe(true);
+
+    const loaded = store.load("s1");
+    expect(loaded).toEqual(session);
+  });
+
+  it("returns null for a non-existent session", () => {
+    const loaded = store.load("does-not-exist");
+    expect(loaded).toBeNull();
+  });
+
+  it("returns null for a corrupt JSON file", () => {
+    writeFileSync(join(tempDir, "corrupt.json"), "{{not valid json!!", "utf-8");
+    const loaded = store.load("corrupt");
+    expect(loaded).toBeNull();
+  });
+
+  it("preserves all session fields through round-trip", () => {
+    const session = makeSession("s2", {
+      messageHistory: [{ type: "error", message: "test error" }],
+      pendingMessages: ["msg1", "msg2"],
+      pendingPermissions: [
+        [
+          "req-1",
+          {
+            request_id: "req-1",
+            tool_name: "Write",
+            input: { path: "/tmp/test.txt" },
+            tool_use_id: "tu-1",
+            timestamp: Date.now(),
+          },
+        ],
+      ],
+      eventBuffer: [
+        { seq: 1, message: { type: "cli_connected" } },
+      ],
+      nextEventSeq: 2,
+      lastAckSeq: 1,
+      processedClientMessageIds: ["client-msg-1", "client-msg-2"],
+      archived: true,
+    });
+
+    store.saveSync(session);
+    const loaded = store.load("s2");
+    expect(loaded).toEqual(session);
+    expect(loaded!.archived).toBe(true);
+    expect(loaded!.pendingPermissions).toHaveLength(1);
+    expect(loaded!.pendingMessages).toEqual(["msg1", "msg2"]);
+    expect(loaded!.eventBuffer).toEqual([{ seq: 1, message: { type: "cli_connected" } }]);
+    expect(loaded!.nextEventSeq).toBe(2);
+    expect(loaded!.lastAckSeq).toBe(1);
+    expect(loaded!.processedClientMessageIds).toEqual(["client-msg-1", "client-msg-2"]);
+  });
+});
+
+// ─── save (debounced) ─────────────────────────────────────────────────────────
+
+describe("save (debounced)", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("does not write immediately", () => {
+    const session = makeSession("debounce-1");
+    store.save(session);
+
+    const filePath = join(tempDir, "debounce-1.json");
+    expect(existsSync(filePath)).toBe(false);
+  });
+
+  it("writes after the 150ms debounce period", () => {
+    const session = makeSession("debounce-2");
+    store.save(session);
+
+    vi.advanceTimersByTime(150);
+
+    const filePath = join(tempDir, "debounce-2.json");
+    expect(existsSync(filePath)).toBe(true);
+
+    const loaded = store.load("debounce-2");
+    expect(loaded).toEqual(session);
+  });
+
+  it("coalesces rapid calls and only writes the last version", () => {
+    const session1 = makeSession("debounce-3", {
+      pendingMessages: ["first"],
+    });
+    const session2 = makeSession("debounce-3", {
+      pendingMessages: ["second"],
+    });
+    const session3 = makeSession("debounce-3", {
+      pendingMessages: ["third"],
+    });
+
+    store.save(session1);
+    vi.advanceTimersByTime(50);
+    store.save(session2);
+    vi.advanceTimersByTime(50);
+    store.save(session3);
+
+    // Not yet written (timer restarted with session3)
+    expect(existsSync(join(tempDir, "debounce-3.json"))).toBe(false);
+
+    vi.advanceTimersByTime(150);
+
+    const loaded = store.load("debounce-3");
+    expect(loaded!.pendingMessages).toEqual(["third"]);
+  });
+});
+
+// ─── loadAll ──────────────────────────────────────────────────────────────────
+
+describe("loadAll", () => {
+  it("returns all saved sessions", () => {
+    store.saveSync(makeSession("a"));
+    store.saveSync(makeSession("b"));
+    store.saveSync(makeSession("c"));
+
+    const all = store.loadAll();
+    const ids = all.map((s) => s.id).sort();
+    expect(ids).toEqual(["a", "b", "c"]);
+  });
+
+  it("skips corrupt JSON files", () => {
+    store.saveSync(makeSession("good"));
+    writeFileSync(join(tempDir, "bad.json"), "not-json!", "utf-8");
+
+    const all = store.loadAll();
+    expect(all).toHaveLength(1);
+    expect(all[0].id).toBe("good");
+  });
+
+  it("excludes launcher.json from results", () => {
+    store.saveSync(makeSession("session-1"));
+    store.saveLauncher({ some: "launcher data" });
+
+    const all = store.loadAll();
+    expect(all).toHaveLength(1);
+    expect(all[0].id).toBe("session-1");
+  });
+
+  it("returns an empty array for an empty directory", () => {
+    const all = store.loadAll();
+    expect(all).toEqual([]);
+  });
+});
+
+// ─── setArchived ──────────────────────────────────────────────────────────────
+
+describe("setArchived", () => {
+  it("sets archived flag to true and persists it", () => {
+    store.saveSync(makeSession("arch-1"));
+    const result = store.setArchived("arch-1", true);
+
+    expect(result).toBe(true);
+
+    const loaded = store.load("arch-1");
+    expect(loaded!.archived).toBe(true);
+  });
+
+  it("sets archived flag to false and persists it", () => {
+    store.saveSync(makeSession("arch-2", { archived: true }));
+    const result = store.setArchived("arch-2", false);
+
+    expect(result).toBe(true);
+
+    const loaded = store.load("arch-2");
+    expect(loaded!.archived).toBe(false);
+  });
+
+  it("returns false for a non-existent session", () => {
+    const result = store.setArchived("no-such-session", true);
+    expect(result).toBe(false);
+  });
+});
+
+// ─── remove ───────────────────────────────────────────────────────────────────
+
+describe("remove", () => {
+  it("deletes the session file from disk", () => {
+    store.saveSync(makeSession("rm-1"));
+    expect(existsSync(join(tempDir, "rm-1.json"))).toBe(true);
+
+    store.remove("rm-1");
+    expect(existsSync(join(tempDir, "rm-1.json"))).toBe(false);
+    expect(store.load("rm-1")).toBeNull();
+  });
+
+  it("cancels a pending debounced save so it never writes", () => {
+    vi.useFakeTimers();
+    try {
+      const session = makeSession("rm-2");
+      store.save(session);
+
+      // Remove before the debounce fires
+      store.remove("rm-2");
+
+      // Advance past the debounce window
+      vi.advanceTimersByTime(300);
+
+      expect(existsSync(join(tempDir, "rm-2.json"))).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("does not throw when removing a non-existent session", () => {
+    expect(() => store.remove("ghost-session")).not.toThrow();
+  });
+});
+
+// ─── saveLauncher / loadLauncher ──────────────────────────────────────────────
+
+describe("saveLauncher / loadLauncher", () => {
+  it("writes and reads launcher data", () => {
+    const data = { pids: [123, 456], lastBoot: "2025-01-01T00:00:00Z" };
+    store.saveLauncher(data);
+
+    const loaded = store.loadLauncher<{ pids: number[]; lastBoot: string }>();
+    expect(loaded).toEqual(data);
+  });
+
+  it("returns null when no launcher file exists", () => {
+    const loaded = store.loadLauncher();
+    expect(loaded).toBeNull();
+  });
+});

package/server/session-store.ts

@@ -0,0 +1,146 @@
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type {
+  SessionState,
+  BrowserIncomingMessage,
+  PermissionRequest,
+  BufferedBrowserEvent,
+} from "./session-types.js";
+
+// ─── Serializable session shape ─────────────────────────────────────────────
+
+export interface PersistedSession {
+  id: string;
+  state: SessionState;
+  messageHistory: BrowserIncomingMessage[];
+  pendingMessages: string[];
+  pendingPermissions: [string, PermissionRequest][];
+  eventBuffer?: BufferedBrowserEvent[];
+  nextEventSeq?: number;
+  lastAckSeq?: number;
+  processedClientMessageIds?: string[];
+  archived?: boolean;
+}
+
+// ─── Store ──────────────────────────────────────────────────────────────────
+
+const DEFAULT_DIR = join(tmpdir(), "vibe-sessions");
+
+export class SessionStore {
+  private dir: string;
+  private debounceTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  constructor(dir?: string) {
+    this.dir = dir || DEFAULT_DIR;
+    mkdirSync(this.dir, { recursive: true });
+  }
+
+  private filePath(sessionId: string): string {
+    return join(this.dir, `${sessionId}.json`);
+  }
+
+  /** Debounced write — batches rapid changes (e.g. multiple stream events). */
+  save(session: PersistedSession): void {
+    const existing = this.debounceTimers.get(session.id);
+    if (existing) clearTimeout(existing);
+
+    const timer = setTimeout(() => {
+      this.debounceTimers.delete(session.id);
+      this.saveSync(session);
+    }, 150);
+    this.debounceTimers.set(session.id, timer);
+  }
+
+  /** Immediate write — use for critical state changes. */
+  saveSync(session: PersistedSession): void {
+    try {
+      writeFileSync(this.filePath(session.id), JSON.stringify(session), "utf-8");
+    } catch (err) {
+      console.error(`[session-store] Failed to save session ${session.id}:`, err);
+    }
+  }
+
+  /** Load a single session from disk. */
+  load(sessionId: string): PersistedSession | null {
+    try {
+      const raw = readFileSync(this.filePath(sessionId), "utf-8");
+      return JSON.parse(raw) as PersistedSession;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Load all sessions from disk. */
+  loadAll(): PersistedSession[] {
+    const sessions: PersistedSession[] = [];
+    try {
+      const files = readdirSync(this.dir).filter((f) => f.endsWith(".json") && f !== "launcher.json");
+      for (const file of files) {
+        try {
+          const raw = readFileSync(join(this.dir, file), "utf-8");
+          sessions.push(JSON.parse(raw));
+        } catch {
+          // Skip corrupt files
+        }
+      }
+    } catch {
+      // Dir doesn't exist yet
+    }
+    return sessions;
+  }
+
+  /** Set the archived flag on a persisted session. */
+  setArchived(sessionId: string, archived: boolean): boolean {
+    const session = this.load(sessionId);
+    if (!session) return false;
+    session.archived = archived;
+    this.saveSync(session);
+    return true;
+  }
+
+  /** Remove a session file from disk. */
+  remove(sessionId: string): void {
+    const timer = this.debounceTimers.get(sessionId);
+    if (timer) {
+      clearTimeout(timer);
+      this.debounceTimers.delete(sessionId);
+    }
+    try {
+      unlinkSync(this.filePath(sessionId));
+    } catch {
+      // File may not exist
+    }
+  }
+
+  /** Persist launcher state (separate file). */
+  saveLauncher(data: unknown): void {
+    try {
+      writeFileSync(join(this.dir, "launcher.json"), JSON.stringify(data), "utf-8");
+    } catch (err) {
+      console.error("[session-store] Failed to save launcher state:", err);
+    }
+  }
+
+  /** Load launcher state. */
+  loadLauncher<T>(): T | null {
+    try {
+      const raw = readFileSync(join(this.dir, "launcher.json"), "utf-8");
+      return JSON.parse(raw) as T;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Cancel all pending debounce timers (for clean test teardown). */
+  dispose(): void {
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.debounceTimers.clear();
+  }
+
+  get directory(): string {
+    return this.dir;
+  }
+}