the-campfire 0.1.0

package/server/recording-hub/diagnostics.ts

@@ -0,0 +1,289 @@
+/**
+ * Recording diagnostics — analyzes session recordings for health issues.
+ *
+ * Goes beyond companion's disconnection-only analysis to include:
+ * - Disconnection patterns and data gaps
+ * - Message rate anomalies
+ * - Permission response time analysis
+ * - Cost tracking per turn
+ */
+
+import type { Recording } from "../replay.js";
+import type { RecordingEntry } from "../recorder.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface TimelineEvent {
+  ts: number;
+  event: string;
+  channel: "cli" | "browser";
+  detail?: string;
+}
+
+export interface DataGap {
+  startTs: number;
+  endTs: number;
+  gapMs: number;
+  channel: "cli" | "browser";
+  messagesBefore: number;
+  messagesAfter: number;
+}
+
+export interface DisconnectionEvent {
+  ts: number;
+  channel: "cli" | "browser";
+  gapMs: number;
+  messagesLostEstimate: number;
+}
+
+export interface PermissionTiming {
+  requestTs: number;
+  responseTs: number | null;
+  responseTimeMs: number | null;
+  toolName: string;
+}
+
+export interface DiagnosticsReport {
+  sessionId: string;
+  backendType: string;
+  totalDuration: number;
+  totalMessages: number;
+  messageRate: number;
+  disconnections: DisconnectionEvent[];
+  dataGaps: DataGap[];
+  patterns: string[];
+  permissionTimings: PermissionTiming[];
+  avgPermissionResponseMs: number | null;
+  messageTypeDistribution: Record<string, number>;
+}
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const CLI_GAP_THRESHOLD_MS = 30_000;
+const BROWSER_GAP_THRESHOLD_MS = 15_000;
+
+// ─── Diagnostics ────────────────────────────────────────────────────────────
+
+export function analyzeRecording(recording: Recording): DiagnosticsReport {
+  const entries = recording.entries;
+  if (entries.length === 0) {
+    return emptyReport(recording);
+  }
+
+  const firstTs = entries[0].ts;
+  const lastTs = entries[entries.length - 1].ts;
+  const totalDuration = lastTs - firstTs;
+
+  // Message type distribution
+  const typeDistribution: Record<string, number> = {};
+  for (const entry of entries) {
+    const parsed = safeParse(entry);
+    const msgType = parsed?.type as string || entry.ch;
+    typeDistribution[msgType] = (typeDistribution[msgType] || 0) + 1;
+  }
+
+  // Data gaps per channel
+  const dataGaps = findDataGaps(entries);
+
+  // Disconnection events
+  const disconnections = findDisconnections(entries);
+
+  // Permission timing analysis
+  const permissionTimings = analyzePermissions(entries);
+
+  // Patterns
+  const patterns = detectPatterns(disconnections, dataGaps, entries);
+
+  // Average permission response time
+  const responded = permissionTimings.filter((p) => p.responseTimeMs !== null);
+  const avgPermissionResponseMs = responded.length > 0
+    ? Math.round(responded.reduce((sum, p) => sum + (p.responseTimeMs || 0), 0) / responded.length)
+    : null;
+
+  return {
+    sessionId: recording.header.session_id,
+    backendType: recording.header.backend_type || "unknown",
+    totalDuration,
+    totalMessages: entries.length,
+    messageRate: totalDuration > 0 ? Math.round((entries.length / totalDuration) * 60_000) : 0,
+    disconnections,
+    dataGaps,
+    patterns,
+    permissionTimings,
+    avgPermissionResponseMs,
+    messageTypeDistribution: typeDistribution,
+  };
+}
+
+export function buildTimeline(recording: Recording): TimelineEvent[] {
+  const events: TimelineEvent[] = [];
+  for (const entry of recording.entries) {
+    const parsed = safeParse(entry);
+    const msgType = parsed?.type as string || "data";
+    events.push({
+      ts: entry.ts,
+      event: msgType,
+      channel: entry.ch,
+      detail: entry.dir,
+    });
+  }
+  return events;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function findDataGaps(entries: RecordingEntry[]): DataGap[] {
+  const gaps: DataGap[] = [];
+  const byChannel = new Map<string, RecordingEntry[]>();
+
+  for (const e of entries) {
+    const list = byChannel.get(e.ch) || [];
+    list.push(e);
+    byChannel.set(e.ch, list);
+  }
+
+  for (const [ch, channelEntries] of byChannel) {
+    const threshold = ch === "cli" ? CLI_GAP_THRESHOLD_MS : BROWSER_GAP_THRESHOLD_MS;
+    for (let i = 1; i < channelEntries.length; i++) {
+      const gapMs = channelEntries[i].ts - channelEntries[i - 1].ts;
+      if (gapMs > threshold) {
+        gaps.push({
+          startTs: channelEntries[i - 1].ts,
+          endTs: channelEntries[i].ts,
+          gapMs,
+          channel: ch as "cli" | "browser",
+          messagesBefore: i,
+          messagesAfter: channelEntries.length - i,
+        });
+      }
+    }
+  }
+
+  return gaps.sort((a, b) => a.startTs - b.startTs);
+}
+
+function findDisconnections(entries: RecordingEntry[]): DisconnectionEvent[] {
+  const disconnections: DisconnectionEvent[] = [];
+
+  for (const entry of entries) {
+    const parsed = safeParse(entry);
+    if (!parsed) continue;
+    const msgType = parsed.type as string;
+    if (msgType === "cli_disconnected" || msgType === "cli_connected") {
+      if (msgType === "cli_disconnected") {
+        disconnections.push({
+          ts: entry.ts,
+          channel: entry.ch,
+          gapMs: 0,
+          messagesLostEstimate: 0,
+        });
+      }
+    }
+  }
+
+  return disconnections;
+}
+
+function analyzePermissions(entries: RecordingEntry[]): PermissionTiming[] {
+  const pending = new Map<string, { ts: number; toolName: string }>();
+  const timings: PermissionTiming[] = [];
+
+  for (const entry of entries) {
+    const parsed = safeParse(entry);
+    if (!parsed) continue;
+    const msgType = parsed.type as string;
+
+    if (msgType === "permission_request") {
+      const req = parsed.request as Record<string, unknown> | undefined;
+      const requestId = req?.request_id as string || parsed.request_id as string;
+      const toolName = req?.tool_name as string || "unknown";
+      if (requestId) pending.set(requestId, { ts: entry.ts, toolName });
+    }
+
+    if (msgType === "permission_response" || msgType === "permission_cancelled") {
+      const requestId = parsed.request_id as string;
+      const req = pending.get(requestId);
+      if (req) {
+        timings.push({
+          requestTs: req.ts,
+          responseTs: entry.ts,
+          responseTimeMs: entry.ts - req.ts,
+          toolName: req.toolName,
+        });
+        pending.delete(requestId);
+      }
+    }
+  }
+
+  // Add unresolved permissions
+  for (const [, req] of pending) {
+    timings.push({
+      requestTs: req.ts,
+      responseTs: null,
+      responseTimeMs: null,
+      toolName: req.toolName,
+    });
+  }
+
+  return timings;
+}
+
+function detectPatterns(
+  disconnections: DisconnectionEvent[],
+  gaps: DataGap[],
+  entries: RecordingEntry[],
+): string[] {
+  const patterns: string[] = [];
+
+  if (disconnections.length >= 3) {
+    patterns.push(`Frequent disconnections: ${disconnections.length} events detected`);
+  }
+
+  const cliGaps = gaps.filter((g) => g.channel === "cli");
+  if (cliGaps.length >= 2) {
+    patterns.push(`CLI data gaps: ${cliGaps.length} periods with no CLI messages (>${CLI_GAP_THRESHOLD_MS / 1000}s each)`);
+  }
+
+  const browserGaps = gaps.filter((g) => g.channel === "browser");
+  if (browserGaps.length >= 2) {
+    patterns.push(`Browser data gaps: ${browserGaps.length} periods with no browser messages`);
+  }
+
+  if (entries.length > 0) {
+    const duration = (entries.at(-1)?.ts ?? 0) - entries[0].ts;
+    if (duration > 0 && entries.length / duration < 0.001) {
+      patterns.push("Very low message rate — possible idle or stalled session");
+    }
+  }
+
+  if (patterns.length === 0) {
+    patterns.push("No anomalies detected");
+  }
+
+  return patterns;
+}
+
+function emptyReport(recording: Recording): DiagnosticsReport {
+  return {
+    sessionId: recording.header.session_id,
+    backendType: recording.header.backend_type || "unknown",
+    totalDuration: 0,
+    totalMessages: 0,
+    messageRate: 0,
+    disconnections: [],
+    dataGaps: [],
+    patterns: ["Empty recording"],
+    permissionTimings: [],
+    avgPermissionResponseMs: null,
+    messageTypeDistribution: {},
+  };
+}
+
+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;
+  }
+}

package/server/recording-hub/hub-routes.ts

@@ -0,0 +1,146 @@
+/**
+ * Recording Hub REST API routes.
+ *
+ * Provides CRUD for hub recordings, validation, diagnostics,
+ * timeline, import/upload, and tag management.
+ */
+
+import type { Hono } from "hono";
+import type { RouteDeps } from "../routes/route-deps.js";
+import { loadRecording } from "../replay.js";
+import { validateRecording } from "./compat-validator.js";
+import { analyzeRecording, buildTimeline } from "./diagnostics.js";
+import * as hubStore from "./hub-store.js";
+
+export function registerHubRoutes(api: Hono, deps: RouteDeps): void {
+  const { recorder } = deps;
+
+  // ─── List hub recordings ────────────────────────────────────────────
+  api.get("/hub/recordings", (c) => {
+    if (recorder) {
+      try {
+        hubStore.indexExistingRecordings(recorder);
+      } catch {
+        // Listing should remain available even if a filesystem scan fails.
+      }
+    }
+    return c.json(hubStore.listHubRecordings());
+  });
+
+  // ─── Get single recording metadata ─────────────────────────────────
+  api.get("/hub/recordings/:id", (c) => {
+    const meta = hubStore.getHubRecording(c.req.param("id"));
+    if (!meta) return c.json({ error: "Recording not found" }, 404);
+    return c.json(meta);
+  });
+
+  // ─── Get recording summary (with tool names, permission count) ─────
+  api.get("/hub/recordings/:id/summary", (c) => {
+    const summary = hubStore.getSummary(c.req.param("id"));
+    if (!summary) return c.json({ error: "Recording not found" }, 404);
+    return c.json(summary);
+  });
+
+  // ─── Update tags ───────────────────────────────────────────────────
+  api.put("/hub/recordings/:id/tags", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    if (!Array.isArray(body.tags)) return c.json({ error: "tags must be an array" }, 400);
+    const meta = hubStore.updateTags(c.req.param("id"), body.tags);
+    if (!meta) return c.json({ error: "Recording not found" }, 404);
+    return c.json(meta);
+  });
+
+  // ─── Delete hub recording (from index only, not the file) ──────────
+  api.delete("/hub/recordings/:id", (c) => {
+    const deleted = hubStore.deleteHubRecording(c.req.param("id"));
+    if (!deleted) return c.json({ error: "Recording not found" }, 404);
+    return c.json({ ok: true });
+  });
+
+  // ─── Upload recording (JSONL content) ──────────────────────────────
+  api.post("/hub/recordings/upload", async (c) => {
+    const contentType = c.req.header("content-type") || "";
+    let content: string;
+    let filename: string | undefined;
+
+    if (contentType.includes("application/json")) {
+      const body = await c.req.json().catch(() => ({}));
+      content = typeof body.content === "string" ? body.content : "";
+      filename = typeof body.filename === "string" ? body.filename : undefined;
+    } else {
+      content = await c.req.text();
+    }
+
+    if (!content.trim()) return c.json({ error: "Empty content" }, 400);
+
+    try {
+      const meta = hubStore.uploadRecording(content, filename);
+      return c.json(meta, 201);
+    } catch (e: unknown) {
+      return c.json({ error: e instanceof Error ? e.message : "Upload failed" }, 400);
+    }
+  });
+
+  // ─── Import from existing auto-recording ───────────────────────────
+  api.post("/hub/recordings/import", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const filename = typeof body.filename === "string" ? body.filename : "";
+    if (!filename) return c.json({ error: "filename is required" }, 400);
+
+    const recordings = recorder?.listRecordings() || [];
+    const match = recordings.find((r) => r.filename === filename);
+    if (!match) return c.json({ error: "Recording file not found" }, 404);
+
+    try {
+      const recDir = process.env.CAMPFIRE_RECORDINGS_DIR || `${process.env.HOME || ""}/.campfire/recordings`;
+      const filePath = `${recDir}/${filename}`;
+      const meta = hubStore.importRecording(filePath);
+      return c.json(meta, 201);
+    } catch (e: unknown) {
+      return c.json({ error: e instanceof Error ? e.message : "Import failed" }, 400);
+    }
+  });
+
+  // ─── Index all existing auto-recordings ────────────────────────────
+  api.post("/hub/recordings/index-all", (c) => {
+    if (!recorder) return c.json({ error: "Recorder not available" }, 500);
+    const count = hubStore.indexExistingRecordings(recorder);
+    return c.json({ ok: true, imported: count });
+  });
+
+  // ─── Validate recording (compat check) ─────────────────────────────
+  api.get("/hub/recordings/:id/validate", (c) => {
+    const meta = hubStore.getHubRecording(c.req.param("id"));
+    if (!meta) return c.json({ error: "Recording not found" }, 404);
+    try {
+      const recording = loadRecording(meta.filePath);
+      return c.json(validateRecording(recording));
+    } catch (e: unknown) {
+      return c.json({ error: e instanceof Error ? e.message : "Validation failed" }, 500);
+    }
+  });
+
+  // ─── Diagnostics (health report) ───────────────────────────────────
+  api.get("/hub/recordings/:id/diagnostics", (c) => {
+    const meta = hubStore.getHubRecording(c.req.param("id"));
+    if (!meta) return c.json({ error: "Recording not found" }, 404);
+    try {
+      const recording = loadRecording(meta.filePath);
+      return c.json(analyzeRecording(recording));
+    } catch (e: unknown) {
+      return c.json({ error: e instanceof Error ? e.message : "Diagnostics failed" }, 500);
+    }
+  });
+
+  // ─── Timeline ──────────────────────────────────────────────────────
+  api.get("/hub/recordings/:id/timeline", (c) => {
+    const meta = hubStore.getHubRecording(c.req.param("id"));
+    if (!meta) return c.json({ error: "Recording not found" }, 404);
+    try {
+      const recording = loadRecording(meta.filePath);
+      return c.json(buildTimeline(recording));
+    } catch (e: unknown) {
+      return c.json({ error: e instanceof Error ? e.message : "Timeline failed" }, 500);
+    }
+  });
+}

package/server/recording-hub/hub-store.ts

@@ -0,0 +1,224 @@
+/**
+ * Recording Hub Store — metadata index overlay on existing recordings.
+ *
+ * Unlike companion (separate ~/.companion/hub/ storage), this extends
+ * the existing ~/.campfire/recordings/ with an index.json for metadata,
+ * tags, and summaries. No duplicate file storage.
+ */
+
+import {
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  existsSync,
+} from "node:fs";
+import { join, basename } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { loadRecording, type Recording } from "../replay.js";
+import type { RecorderManager } from "../recorder.js";
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface HubRecordingMeta {
+  id: string;
+  filename: string;
+  filePath: string;
+  sessionId: string;
+  backendType: string;
+  startedAt: number;
+  duration: number;
+  entryCount: number;
+  tags: string[];
+  importedAt: number;
+  messageTypeSummary: Record<string, number>;
+}
+
+export interface HubRecordingSummary extends HubRecordingMeta {
+  toolNames: string[];
+  permissionCount: number;
+}
+
+// ─── Paths ──────────────────────────────────────────────────────────────────
+
+const CAMPFIRE_DIR = join(homedir(), ".campfire");
+const RECORDINGS_DIR = process.env.CAMPFIRE_RECORDINGS_DIR || join(CAMPFIRE_DIR, "recordings");
+const INDEX_PATH = join(RECORDINGS_DIR, "hub-index.json");
+
+// ─── Store ──────────────────────────────────────────────────────────────────
+
+let index: HubRecordingMeta[] = [];
+let loaded = false;
+
+function ensureLoaded(): void {
+  if (loaded) return;
+  try {
+    if (existsSync(INDEX_PATH)) {
+      const raw = readFileSync(INDEX_PATH, "utf-8");
+      index = JSON.parse(raw);
+    }
+  } catch {
+    index = [];
+  }
+  loaded = true;
+}
+
+function persist(): void {
+  mkdirSync(RECORDINGS_DIR, { recursive: true });
+  writeFileSync(INDEX_PATH, JSON.stringify(index, null, 2), "utf-8");
+}
+
+// ─── CRUD ───────────────────────────────────────────────────────────────────
+
+export function listHubRecordings(): HubRecordingMeta[] {
+  ensureLoaded();
+  return [...index].sort((a, b) => b.importedAt - a.importedAt);
+}
+
+export function getHubRecording(id: string): HubRecordingMeta | null {
+  ensureLoaded();
+  return index.find((r) => r.id === id) || null;
+}
+
+export function importRecording(filePath: string): HubRecordingMeta {
+  const recording = loadRecording(filePath);
+  const meta = buildMeta(recording, filePath);
+
+  ensureLoaded();
+  // Deduplicate by filename
+  const existing = index.findIndex((r) => r.filename === meta.filename);
+  if (existing >= 0) {
+    index[existing] = meta;
+  } else {
+    index.push(meta);
+  }
+  persist();
+  return meta;
+}
+
+export function uploadRecording(content: string, originalFilename?: string): HubRecordingMeta {
+  mkdirSync(RECORDINGS_DIR, { recursive: true });
+  const filename = originalFilename || `uploaded_${Date.now()}_${randomUUID().slice(0, 6)}.jsonl`;
+  const destPath = join(RECORDINGS_DIR, filename);
+  writeFileSync(destPath, content, "utf-8");
+
+  const recording = loadRecording(destPath);
+  const meta = buildMeta(recording, destPath);
+
+  ensureLoaded();
+  index.push(meta);
+  persist();
+  return meta;
+}
+
+export function updateTags(id: string, tags: string[]): HubRecordingMeta | null {
+  ensureLoaded();
+  const entry = index.find((r) => r.id === id);
+  if (!entry) return null;
+  entry.tags = tags;
+  persist();
+  return entry;
+}
+
+export function deleteHubRecording(id: string): boolean {
+  ensureLoaded();
+  const idx = index.findIndex((r) => r.id === id);
+  if (idx < 0) return false;
+  index.splice(idx, 1);
+  persist();
+  return true;
+}
+
+function extractToolNames(parsed: Record<string, unknown>, toolNames: Set<string>): void {
+  const msg = parsed.message as Record<string, unknown> | undefined;
+  const content = msg?.content as Array<Record<string, unknown>> | undefined;
+  if (!Array.isArray(content)) return;
+  for (const block of content) {
+    if (block.type === "tool_use" && typeof block.name === "string") {
+      toolNames.add(block.name);
+    }
+  }
+}
+
+function extractSummaryFromRecording(recording: Recording): { toolNames: string[]; permissionCount: number } {
+  const toolNames = new Set<string>();
+  let permissionCount = 0;
+
+  for (const entry of recording.entries) {
+    try {
+      const parsed = JSON.parse(entry.raw) as Record<string, unknown>;
+      if (parsed.type === "permission_request") permissionCount++;
+      if (parsed.type === "assistant") extractToolNames(parsed, toolNames);
+    } catch { /* skip malformed */ }
+  }
+
+  return { toolNames: [...toolNames].sort((a, b) => a.localeCompare(b)), permissionCount };
+}
+
+export function getSummary(id: string): HubRecordingSummary | null {
+  ensureLoaded();
+  const meta = index.find((r) => r.id === id);
+  if (!meta) return null;
+
+  try {
+    const recording = loadRecording(meta.filePath);
+    const { toolNames, permissionCount } = extractSummaryFromRecording(recording);
+    return { ...meta, toolNames, permissionCount };
+  } catch {
+    return { ...meta, toolNames: [], permissionCount: 0 };
+  }
+}
+
+/** Import all existing auto-recordings into the hub index. */
+export function indexExistingRecordings(recorder: RecorderManager): number {
+  const recordings = recorder.listRecordings();
+  let imported = 0;
+  ensureLoaded();
+  const existingFilenames = new Set(index.map((r) => r.filename));
+
+  for (const rec of recordings) {
+    if (existingFilenames.has(rec.filename)) continue;
+    try {
+      const filePath = join(RECORDINGS_DIR, rec.filename);
+      if (!existsSync(filePath)) continue;
+      const recording = loadRecording(filePath);
+      const meta = buildMeta(recording, filePath);
+      index.push(meta);
+      imported++;
+    } catch { /* skip corrupt files */ }
+  }
+
+  if (imported > 0) persist();
+  return imported;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function buildMeta(recording: Recording, filePath: string): HubRecordingMeta {
+  const entries = recording.entries;
+  const duration = entries.length > 1 ? entries[entries.length - 1].ts - entries[0].ts : 0;
+
+  const typeSummary: Record<string, number> = {};
+  for (const entry of entries) {
+    if (entry.dir !== "out" || entry.ch !== "browser") continue;
+    try {
+      const parsed = JSON.parse(entry.raw) as Record<string, unknown>;
+      const t = typeof parsed.type === "string" ? parsed.type : "unknown";
+      typeSummary[t] = (typeSummary[t] || 0) + 1;
+    } catch { /* skip */ }
+  }
+
+  return {
+    id: randomUUID().slice(0, 12),
+    filename: basename(filePath),
+    filePath,
+    sessionId: recording.header.session_id,
+    backendType: recording.header.backend_type || "unknown",
+    startedAt: recording.header.started_at,
+    duration,
+    entryCount: entries.length,
+    tags: [],
+    importedAt: Date.now(),
+    messageTypeSummary: typeSummary,
+  };
+}