the-campfire 0.1.0

package/server/recorder.ts

@@ -0,0 +1,359 @@
+import { mkdirSync, readdirSync, appendFileSync, statSync, unlinkSync, readFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { BackendType } from "./session-types.js";
+
+const DEFAULT_MAX_LINES = 100_000;
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface RecordingHeader {
+  _header: true;
+  version: 1;
+  session_id: string;
+  backend_type: BackendType;
+  started_at: number;
+  cwd: string;
+}
+
+export type RecordingDirection = "in" | "out";
+export type RecordingChannel = "cli" | "browser";
+
+export interface RecordingEntry {
+  ts: number;
+  dir: RecordingDirection;
+  raw: string;
+  ch: RecordingChannel;
+}
+
+export interface RecordingFileMeta {
+  filename: string;
+  sessionId: string;
+  backendType: string;
+  startedAt: string;
+  /** Number of lines in the file (header + entries). */
+  lines: number;
+  /** Whether the recording contains playable conversation content. */
+  hasContent: boolean;
+}
+
+// ─── SessionRecorder ─────────────────────────────────────────────────────────
+
+/**
+ * Writes raw messages for a single session to a JSONL file.
+ * First line is a header with session metadata; subsequent lines are entries.
+ * Tracks its own line count so the manager can enforce the global limit.
+ */
+export class SessionRecorder {
+  readonly filePath: string;
+  private closed = false;
+  /** Number of lines written (1 for the header at construction). */
+  lineCount = 1;
+
+  constructor(
+    sessionId: string,
+    backendType: BackendType,
+    cwd: string,
+    outputDir: string,
+  ) {
+    const ts = new Date().toISOString().replace(/:/g, "-");
+    const suffix = randomBytes(3).toString("hex");
+    const filename = `${sessionId}_${backendType}_${ts}_${suffix}.jsonl`;
+    this.filePath = join(outputDir, filename);
+
+    const header: RecordingHeader = {
+      _header: true,
+      version: 1,
+      session_id: sessionId,
+      backend_type: backendType,
+      started_at: Date.now(),
+      cwd,
+    };
+    appendFileSync(this.filePath, JSON.stringify(header) + "\n");
+  }
+
+  record(dir: RecordingDirection, raw: string, channel: RecordingChannel): void {
+    if (this.closed) return;
+    const entry: RecordingEntry = {
+      ts: Date.now(),
+      dir,
+      raw,
+      ch: channel,
+    };
+    try {
+      appendFileSync(this.filePath, JSON.stringify(entry) + "\n");
+      this.lineCount++;
+    } catch {
+      // Never throw — recording must not disrupt normal operation
+    }
+  }
+
+  close(): void {
+    this.closed = true;
+  }
+}
+
+// ─── RecorderManager ─────────────────────────────────────────────────────────
+
+/**
+ * Manages recording for all sessions.
+ *
+ * Always enabled by default. Disable explicitly with CAMPFIRE_RECORD=0.
+ *
+ * Automatic rotation: when total lines across all recording files exceed
+ * maxLines (default 100 000, override with CAMPFIRE_RECORDINGS_MAX_LINES),
+ * the oldest files are deleted until we're back under the limit.
+ */
+export class RecorderManager {
+  private globalEnabled: boolean;
+  private recordingsDir: string;
+  private maxLines: number;
+  private perSessionEnabled = new Set<string>();
+  private perSessionDisabled = new Set<string>();
+  private recorders = new Map<string, SessionRecorder>();
+  private dirCreated = false;
+  private cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(options?: {
+    globalEnabled?: boolean;
+    recordingsDir?: string;
+    maxLines?: number;
+  }) {
+    this.globalEnabled = options?.globalEnabled ?? RecorderManager.resolveEnabled();
+    this.recordingsDir =
+      options?.recordingsDir ??
+      process.env.CAMPFIRE_RECORDINGS_DIR ??
+      join(homedir(), ".campfire", "recordings");
+    this.maxLines =
+      options?.maxLines ??
+      (Number(process.env.CAMPFIRE_RECORDINGS_MAX_LINES) || DEFAULT_MAX_LINES);
+
+    if (this.globalEnabled) {
+      // Run cleanup at startup (async, non-blocking) and periodically
+      this.cleanup();
+      this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL_MS);
+      if (this.cleanupTimer.unref) this.cleanupTimer.unref();
+    }
+  }
+
+  /**
+   * Always on unless explicitly disabled with CAMPFIRE_RECORD=0|false.
+   */
+  private static resolveEnabled(): boolean {
+    const env = process.env.CAMPFIRE_RECORD;
+    if (env === "0" || env === "false") return false;
+    return true;
+  }
+
+  isGloballyEnabled(): boolean {
+    return this.globalEnabled;
+  }
+
+  getRecordingsDir(): string {
+    return this.recordingsDir;
+  }
+
+  getMaxLines(): number {
+    return this.maxLines;
+  }
+
+  isRecording(sessionId: string): boolean {
+    if (this.perSessionDisabled.has(sessionId)) return false;
+    return this.globalEnabled || this.perSessionEnabled.has(sessionId);
+  }
+
+  enableForSession(sessionId: string): void {
+    this.perSessionDisabled.delete(sessionId);
+    this.perSessionEnabled.add(sessionId);
+  }
+
+  disableForSession(sessionId: string): void {
+    this.perSessionEnabled.delete(sessionId);
+    this.perSessionDisabled.add(sessionId);
+    this.stopRecording(sessionId);
+  }
+
+  /**
+   * Record a raw message. No-op if recording is disabled for this session.
+   * Lazily creates the SessionRecorder on first call.
+   */
+  record(
+    sessionId: string,
+    dir: RecordingDirection,
+    raw: string,
+    channel: RecordingChannel,
+    backendType: BackendType,
+    cwd: string,
+  ): void {
+    if (!this.isRecording(sessionId)) return;
+
+    let recorder = this.recorders.get(sessionId);
+    if (!recorder) {
+      this.ensureDir();
+      recorder = new SessionRecorder(sessionId, backendType, cwd, this.recordingsDir);
+      this.recorders.set(sessionId, recorder);
+    }
+    recorder.record(dir, raw, channel);
+  }
+
+  stopRecording(sessionId: string): void {
+    const recorder = this.recorders.get(sessionId);
+    if (recorder) {
+      recorder.close();
+      this.recorders.delete(sessionId);
+    }
+  }
+
+  getRecordingStatus(sessionId: string): { filePath?: string } {
+    const recorder = this.recorders.get(sessionId);
+    return recorder ? { filePath: recorder.filePath } : {};
+  }
+
+  listRecordings(): RecordingFileMeta[] {
+    try {
+      const files = readdirSync(this.recordingsDir);
+      return files
+        .filter((f) => f.endsWith(".jsonl"))
+        .map((filename) => {
+          // Format: {sessionId}_{backendType}_{ISO-timestamp}_{suffix}.jsonl
+          const withoutExt = filename.replace(/\.jsonl$/, "");
+          const firstUnderscore = withoutExt.indexOf("_");
+          const secondUnderscore = withoutExt.indexOf("_", firstUnderscore + 1);
+          if (firstUnderscore === -1 || secondUnderscore === -1) {
+            return { filename, sessionId: "", backendType: "", startedAt: "", lines: 0, hasContent: false };
+          }
+          const filePath = join(this.recordingsDir, filename);
+          const { lines, hasContent } = countFileLinesAndContent(filePath);
+          return {
+            filename,
+            sessionId: withoutExt.substring(0, firstUnderscore),
+            backendType: withoutExt.substring(firstUnderscore + 1, secondUnderscore),
+            startedAt: withoutExt.substring(secondUnderscore + 1),
+            lines,
+            hasContent,
+          };
+        });
+    } catch {
+      return [];
+    }
+  }
+
+  closeAll(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    for (const [, recorder] of this.recorders) {
+      recorder.close();
+    }
+    this.recorders.clear();
+  }
+
+  /**
+   * Delete oldest recording files until total lines are under maxLines.
+   * Skips files that belong to active (currently recording) sessions.
+   */
+  cleanup(): number {
+    try {
+      this.ensureDir();
+      const files = readdirSync(this.recordingsDir).filter((f) => f.endsWith(".jsonl"));
+      if (files.length === 0) return 0;
+
+      // Build list with line counts and mtime, sorted oldest-first
+      const activeFiles = new Set<string>();
+      for (const rec of this.recorders.values()) {
+        activeFiles.add(rec.filePath);
+      }
+
+      const entries: { filename: string; path: string; lines: number; mtimeMs: number }[] = [];
+      let totalLines = 0;
+
+      for (const filename of files) {
+        const fullPath = join(this.recordingsDir, filename);
+        const { lines } = countFileLinesAndContent(fullPath);
+        let mtimeMs = 0;
+        try {
+          mtimeMs = statSync(fullPath).mtimeMs;
+        } catch {
+          continue;
+        }
+        entries.push({ filename, path: fullPath, lines, mtimeMs });
+        totalLines += lines;
+      }
+
+      if (totalLines <= this.maxLines) return 0;
+
+      // Sort oldest first (lowest mtime = oldest)
+      entries.sort((a, b) => a.mtimeMs - b.mtimeMs);
+
+      let deleted = 0;
+      for (const entry of entries) {
+        if (totalLines <= this.maxLines) break;
+        // Don't delete files that are actively being written to
+        if (activeFiles.has(entry.path)) continue;
+        try {
+          unlinkSync(entry.path);
+          totalLines -= entry.lines;
+          deleted++;
+        } catch {
+          // File may have been removed concurrently
+        }
+      }
+
+      if (deleted > 0) {
+        console.log(`[recorder] Cleanup: deleted ${deleted} old recording(s), ${totalLines} lines remaining`);
+      }
+      return deleted;
+    } catch {
+      return 0;
+    }
+  }
+
+  private ensureDir(): void {
+    if (this.dirCreated) return;
+    mkdirSync(this.recordingsDir, { recursive: true });
+    this.dirCreated = true;
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Count newlines and detect playable content in a recording file.
+ * Scans the raw buffer for line count AND checks for assistant/user_message
+ * type markers to determine if the recording has conversation content.
+ * This avoids full JSON parsing for the listing endpoint.
+ */
+function countFileLinesAndContent(path: string): { lines: number; hasContent: boolean } {
+  try {
+    const buf = readFileSync(path);
+    let lines = 0;
+    let hasContent = false;
+    // In JSONL recordings, the raw field contains escaped JSON, so type markers
+    // appear as \"type\":\"assistant\" (backslash-escaped quotes inside the outer JSON string).
+    // Check for multiple content types to cover all backends (Claude, Codex, Goose, etc.)
+    const contentMarkers = [
+      Buffer.from(String.raw`\"type\":\"assistant\"`),
+      Buffer.from(String.raw`\"type\":\"user_message\"`),
+      Buffer.from(String.raw`\"type\":\"stream_event\"`),
+      Buffer.from(String.raw`\"type\":\"result\"`),
+      Buffer.from(String.raw`\"type\":\"session_init\"`),
+    ];
+    for (let i = 0; i < buf.length; i++) {
+      if (buf[i] === 0x0a) lines++;
+      if (!hasContent) {
+        for (const marker of contentMarkers) {
+          if (i + marker.length <= buf.length && buf.subarray(i, i + marker.length).equals(marker)) {
+            hasContent = true;
+            break;
+          }
+        }
+      }
+    }
+    return { lines, hasContent };
+  } catch {
+    return { lines: 0, hasContent: false };
+  }
+}

package/server/recording-hub/compat-validator.ts

@@ -0,0 +1,122 @@
+/**
+ * Protocol compatibility validator for session recordings.
+ *
+ * Analyzes recorded messages to detect protocol drift — catches when
+ * backend CLIs change their message format between versions.
+ * Supports ALL 7 backends (not just Claude/Codex like companion).
+ */
+
+import type { Recording } from "../replay.js";
+import type { RecordingEntry } from "../recorder.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ProtocolDiff {
+  entryIndex: number;
+  messageType: string;
+  kind: "missing_field" | "extra_field" | "type_mismatch" | "unexpected_type";
+  field?: string;
+  details: string;
+}
+
+export interface ValidationResult {
+  compatible: boolean;
+  backendType: string;
+  totalMessages: number;
+  checkedMessages: number;
+  diffs: ProtocolDiff[];
+  messageTypeBreakdown: Record<string, { count: number; issues: number }>;
+}
+
+// ─── Ignored Fields (timestamps, IDs, costs — vary per session) ─────────────
+
+const IGNORED_FIELDS = new Set([
+  "ts", "timestamp", "created_at", "updated_at", "session_id",
+  "uuid", "id", "request_id", "client_msg_id",
+  "duration_ms", "duration_api_ms", "cost_usd", "total_cost_usd",
+  "api_tokens", "input_tokens", "output_tokens",
+  "cache_read_input_tokens", "cache_creation_input_tokens",
+  "seq", "last_seq",
+]);
+
+// ─── Expected Shapes per Message Type ───────────────────────────────────────
+
+// Required fields for known message types (applies to all backends)
+const REQUIRED_FIELDS: Record<string, string[]> = {
+  session_init: ["session"],
+  assistant: ["message"],
+  result: ["data"],
+  stream_event: ["event"],
+  permission_request: ["request"],
+  permission_cancelled: ["request_id"],
+  status_change: ["status"],
+  cli_connected: [],
+  cli_disconnected: [],
+  error: ["message"],
+  tool_progress: ["tool_use_id", "tool_name"],
+  presence_update: ["viewers"],
+  role_assigned: ["role", "viewerId"],
+  vote_update: ["request_id", "votes"],
+  vote_resolved: ["request_id", "result"],
+  mcp_status: ["servers"],
+  session_name_update: ["name"],
+  pr_status_update: ["available"],
+};
+
+// ─── Validator ──────────────────────────────────────────────────────────────
+
+function validateEntry(
+  entry: RecordingEntry, index: number,
+  diffs: ProtocolDiff[], breakdown: Record<string, { count: number; issues: number }>,
+): void {
+  if (entry.dir !== "out" || entry.ch !== "browser") return;
+  const parsed = safeParse(entry);
+  if (!parsed) return;
+
+  const msgType = typeof parsed.type === "string" ? parsed.type : "unknown";
+  if (!breakdown[msgType]) breakdown[msgType] = { count: 0, issues: 0 };
+  breakdown[msgType].count++;
+
+  const required = REQUIRED_FIELDS[msgType];
+  if (!required) {
+    diffs.push({ entryIndex: index, messageType: msgType, kind: "unexpected_type", details: `Unknown message type: ${msgType}` });
+    breakdown[msgType].issues++;
+    return;
+  }
+
+  for (const field of required) {
+    if (!(field in parsed)) {
+      diffs.push({ entryIndex: index, messageType: msgType, kind: "missing_field", field, details: `Required field "${field}" missing from ${msgType}` });
+      breakdown[msgType].issues++;
+    }
+  }
+}
+
+export function validateRecording(recording: Recording): ValidationResult {
+  const breakdown: Record<string, { count: number; issues: number }> = {};
+  const diffs: ProtocolDiff[] = [];
+
+  for (let i = 0; i < recording.entries.length; i++) {
+    validateEntry(recording.entries[i], i, diffs, breakdown);
+  }
+
+  const checked = Object.values(breakdown).reduce((sum, b) => sum + b.count, 0);
+
+  return {
+    compatible: diffs.length === 0,
+    backendType: recording.header.backend_type || "unknown",
+    totalMessages: recording.entries.length,
+    checkedMessages: checked,
+    diffs,
+    messageTypeBreakdown: breakdown,
+  };
+}
+
+function safeParse(entry: RecordingEntry): Record<string, unknown> | null {
+  try {
+    const obj = JSON.parse(entry.raw);
+    return typeof obj === "object" && obj !== null ? obj : null;
+  } catch {
+    return null;
+  }
+}