heyhank 0.1.0

package/server/recording-hub/diagnostics.ts

@@ -0,0 +1,299 @@
+/**
+ * Disconnection diagnostics for recorded sessions.
+ *
+ * Analyzes recording entries for connection lifecycle events and data gaps
+ * to identify disconnection patterns and potential causes.
+ */
+
+import type { Recording } from "../replay.js";
+import type { RecordingEntry } from "../recorder.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface TimelineEntry {
+  ts: number;
+  event: string;
+  channel: "cli" | "browser";
+  detail?: string;
+}
+
+export interface DisconnectionEvent {
+  ts: number;
+  channel: "cli" | "browser";
+  closeCode?: number;
+  closeReason?: string;
+  reconnectedAt?: number;
+  gapMs: number;
+  messagesLostEstimate: number;
+}
+
+export interface DisconnectionReport {
+  sessionId: string;
+  backendType: string;
+  totalDuration: number;
+  totalDisconnections: number;
+  disconnections: DisconnectionEvent[];
+  patterns: string[];
+  dataGaps: DataGap[];
+}
+
+export interface DataGap {
+  startTs: number;
+  endTs: number;
+  gapMs: number;
+  channel: "cli" | "browser";
+  messagesBefore: number;
+  messagesAfter: number;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/** Gaps longer than this in CLI messages suggest a disconnection. */
+const CLI_GAP_THRESHOLD_MS = 30_000;
+/** Minimum number of disconnections to detect a pattern. */
+const PATTERN_MIN_COUNT = 3;
+/** Tolerance for regular interval detection (±20%). */
+const INTERVAL_TOLERANCE = 0.2;
+
+// ─── Analysis ────────────────────────────────────────────────────────────────
+
+/**
+ * Analyze a recording for disconnection patterns.
+ *
+ * Works with both legacy recordings (data messages only) and enhanced
+ * recordings that include connection lifecycle events.
+ */
+export function analyzeDisconnections(recording: Recording): DisconnectionReport {
+  const entries = recording.entries;
+  const header = recording.header;
+
+  // Build timeline from both lifecycle events and data gap analysis
+  const timeline = buildTimeline(recording);
+  const disconnections = detectDisconnections(entries, timeline);
+  const dataGaps = detectDataGaps(entries);
+  const patterns = detectPatterns(disconnections, dataGaps);
+
+  const firstTs = entries[0]?.ts ?? header.started_at;
+  const lastTs = entries[entries.length - 1]?.ts ?? firstTs;
+
+  return {
+    sessionId: header.session_id,
+    backendType: header.backend_type,
+    totalDuration: lastTs - firstTs,
+    totalDisconnections: disconnections.length,
+    disconnections,
+    patterns,
+    dataGaps,
+  };
+}
+
+/**
+ * Build a timeline of connection events from a recording.
+ *
+ * Extracts both explicit lifecycle events (ws_open, ws_close, etc.) from
+ * enhanced recordings and infers events from data gaps in legacy recordings.
+ */
+export function buildTimeline(recording: Recording): TimelineEntry[] {
+  const timeline: TimelineEntry[] = [];
+
+  for (const entry of recording.entries) {
+    // Enhanced recordings have explicit lifecycle events
+    const enhanced = entry as RecordingEntry & { event?: string; meta?: Record<string, unknown> };
+    if (enhanced.event) {
+      timeline.push({
+        ts: entry.ts,
+        event: enhanced.event,
+        channel: entry.ch,
+        detail: enhanced.meta ? JSON.stringify(enhanced.meta) : undefined,
+      });
+      continue;
+    }
+
+    // For data messages, track key protocol events
+    if (entry.dir === "out" && entry.ch === "browser") {
+      try {
+        const msg = JSON.parse(entry.raw);
+        if (msg.type === "cli_connected") {
+          timeline.push({ ts: entry.ts, event: "cli_connected", channel: "cli" });
+        } else if (msg.type === "cli_disconnected") {
+          timeline.push({ ts: entry.ts, event: "cli_disconnected", channel: "cli" });
+        } else if (msg.type === "session_init") {
+          timeline.push({ ts: entry.ts, event: "session_init", channel: "cli" });
+        }
+      } catch {
+        // Skip unparseable
+      }
+    }
+  }
+
+  return timeline.sort((a, b) => a.ts - b.ts);
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────────────
+
+function detectDisconnections(
+  entries: RecordingEntry[],
+  timeline: TimelineEntry[],
+): DisconnectionEvent[] {
+  const disconnections: DisconnectionEvent[] = [];
+
+  // From explicit timeline events
+  for (let i = 0; i < timeline.length; i++) {
+    const event = timeline[i];
+    if (event.event === "ws_close" || event.event === "cli_disconnected") {
+      // Find next reconnect/connect event on same channel
+      let reconnectedAt: number | undefined;
+      for (let j = i + 1; j < timeline.length; j++) {
+        if (
+          timeline[j].channel === event.channel &&
+          (timeline[j].event === "ws_open" || timeline[j].event === "cli_connected" || timeline[j].event === "reconnect_success")
+        ) {
+          reconnectedAt = timeline[j].ts;
+          break;
+        }
+      }
+
+      // Estimate messages lost during the gap
+      let messagesLost = 0;
+      if (reconnectedAt) {
+        // Count messages that arrived on the other channel during the gap
+        messagesLost = entries.filter(
+          (e) =>
+            e.ts > event.ts &&
+            e.ts < reconnectedAt! &&
+            e.ch !== event.channel,
+        ).length;
+      }
+
+      let meta: Record<string, unknown> | undefined;
+      try {
+        meta = event.detail ? JSON.parse(event.detail) : undefined;
+      } catch {
+        // ignore
+      }
+
+      disconnections.push({
+        ts: event.ts,
+        channel: event.channel,
+        closeCode: meta?.code as number | undefined,
+        closeReason: meta?.reason as string | undefined,
+        reconnectedAt,
+        gapMs: reconnectedAt ? reconnectedAt - event.ts : 0,
+        messagesLostEstimate: messagesLost,
+      });
+    }
+  }
+
+  // Deduplicate: ws_close and cli_disconnected for the same outage.
+  // Only dedup if the second disconnect happens before the first one reconnected.
+  const deduped: DisconnectionEvent[] = [];
+  for (const d of disconnections) {
+    const isDuplicate = deduped.some(
+      (existing) =>
+        existing.channel === d.channel &&
+        // Only dedup if this disconnect happened before the previous one reconnected
+        // (i.e. same outage, not a new one after recovery)
+        (!existing.reconnectedAt || d.ts < existing.reconnectedAt),
+    );
+    if (!isDuplicate) deduped.push(d);
+  }
+  return deduped;
+}
+
+function detectDataGaps(entries: RecordingEntry[]): DataGap[] {
+  const gaps: DataGap[] = [];
+
+  // Group entries by channel
+  const cliEntries = entries.filter((e) => e.ch === "cli" && e.dir === "in" && !e.event);
+  const browserEntries = entries.filter((e) => e.ch === "browser" && e.dir === "in" && !e.event);
+
+  for (const [channel, channelEntries] of [
+    ["cli", cliEntries],
+    ["browser", browserEntries],
+  ] as const) {
+    for (let i = 1; i < channelEntries.length; i++) {
+      const gapMs = channelEntries[i].ts - channelEntries[i - 1].ts;
+      if (gapMs > CLI_GAP_THRESHOLD_MS) {
+        gaps.push({
+          startTs: channelEntries[i - 1].ts,
+          endTs: channelEntries[i].ts,
+          gapMs,
+          channel,
+          messagesBefore: i,
+          messagesAfter: channelEntries.length - i,
+        });
+      }
+    }
+  }
+
+  return gaps.sort((a, b) => a.startTs - b.startTs);
+}
+
+function detectPatterns(
+  disconnections: DisconnectionEvent[],
+  dataGaps: DataGap[],
+): string[] {
+  const patterns: string[] = [];
+
+  // Pattern: Keep-alive failure (regular interval disconnections)
+  if (disconnections.length >= PATTERN_MIN_COUNT) {
+    const cliDisconnections = disconnections.filter((d) => d.channel === "cli");
+    if (cliDisconnections.length >= PATTERN_MIN_COUNT) {
+      const intervals = [];
+      for (let i = 1; i < cliDisconnections.length; i++) {
+        intervals.push(cliDisconnections[i].ts - cliDisconnections[i - 1].ts);
+      }
+      const avgInterval = intervals.reduce((a, b) => a + b, 0) / intervals.length;
+      const allClose = intervals.every(
+        (iv) => Math.abs(iv - avgInterval) / avgInterval < INTERVAL_TOLERANCE,
+      );
+      if (allClose) {
+        patterns.push(
+          `Regular CLI disconnections every ~${Math.round(avgInterval / 1000)}s — possible keep-alive or timeout issue`,
+        );
+      }
+    }
+  }
+
+  // Pattern: Rapid reconnect cycling
+  const rapidReconnects = disconnections.filter(
+    (d) => d.reconnectedAt && d.gapMs < 5000,
+  );
+  if (rapidReconnects.length >= PATTERN_MIN_COUNT) {
+    patterns.push(
+      `${rapidReconnects.length} rapid reconnections (< 5s gap) — possible flapping connection`,
+    );
+  }
+
+  // Pattern: Large data gaps without explicit disconnect events
+  const unexplainedGaps = dataGaps.filter((g) => {
+    // Check if any disconnection event falls within this gap
+    return !disconnections.some(
+      (d) => d.ts >= g.startTs && d.ts <= g.endTs,
+    );
+  });
+  if (unexplainedGaps.length > 0) {
+    patterns.push(
+      `${unexplainedGaps.length} data gap(s) without recorded disconnect events — possible silent connection drops`,
+    );
+  }
+
+  // Pattern: Asymmetric disconnection (CLI drops but browser stays)
+  const cliOnly = disconnections.filter((d) => d.channel === "cli");
+  const browserOnly = disconnections.filter((d) => d.channel === "browser");
+  if (cliOnly.length > 0 && browserOnly.length === 0) {
+    patterns.push(
+      `All ${cliOnly.length} disconnection(s) are CLI-side — browser connections are stable. Check CLI process health.`,
+    );
+  } else if (browserOnly.length > 0 && cliOnly.length === 0) {
+    patterns.push(
+      `All ${browserOnly.length} disconnection(s) are browser-side — CLI connection is stable. Check network/proxy.`,
+    );
+  }
+
+  if (patterns.length === 0 && disconnections.length === 0 && dataGaps.length === 0) {
+    patterns.push("No disconnection issues detected in this recording.");
+  }
+
+  return patterns;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Feature gate for the Recording Hub.
+ *
+ * The hub is disabled by default. Enable with HEYHANK_RECORDING_HUB=1 (or COMPANION_RECORDING_HUB=1).
+ * When disabled, hub routes are not registered and hub storage is not initialized.
+ */
+
+const DEFAULT_MAX_UPLOAD_MB = 50;
+
+export function isRecordingHubEnabled(): boolean {
+  const env = process.env.HEYHANK_RECORDING_HUB || process.env.COMPANION_RECORDING_HUB;
+  return env === "1" || env === "true";
+}
+
+export function getMaxUploadBytes(): number {
+  const parsed = Number(process.env.HEYHANK_HUB_MAX_UPLOAD_MB || process.env.COMPANION_HUB_MAX_UPLOAD_MB);
+  const mb = Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_UPLOAD_MB;
+  return mb * 1024 * 1024;
+}

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

@@ -0,0 +1,236 @@
+/**
+ * REST API routes for the Recording Hub.
+ *
+ * All routes are under /api/hub/ and only registered when HEYHANK_RECORDING_HUB=1.
+ */
+
+import type { Hono } from "hono";
+import { join, resolve, sep } from "node:path";
+import { existsSync } from "node:fs";
+import { HubStore } from "./hub-store.js";
+import type { ReplayAdapter } from "./replay-adapter.js";
+import type { WsBridge } from "../ws-bridge.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface HubRoutesOptions {
+  wsBridge: WsBridge;
+  recordingsDir: string; // Auto-recording directory for import-local
+}
+
+// ─── Route Registration ─────────────────────────────────────────────────────
+
+export function registerHubRoutes(api: Hono, options: HubRoutesOptions): void {
+  const store = new HubStore();
+  const replayAdapters = new Map<string, ReplayAdapter>();
+
+  // ── Recording CRUD ────────────────────────────────────────────────────
+
+  api.get("/hub/recordings", (c) => {
+    return c.json(store.list());
+  });
+
+  api.get("/hub/recordings/:id", (c) => {
+    const meta = store.get(c.req.param("id"));
+    if (!meta) return c.json({ error: "Recording not found" }, 404);
+    return c.json(meta);
+  });
+
+  api.get("/hub/recordings/:id/summary", (c) => {
+    const summary = store.getSummary(c.req.param("id"));
+    if (!summary) return c.json({ error: "Recording not found" }, 404);
+    return c.json(summary);
+  });
+
+  api.delete("/hub/recordings/:id", (c) => {
+    const deleted = store.delete(c.req.param("id"));
+    if (!deleted) return c.json({ error: "Recording not found" }, 404);
+    return c.json({ ok: true });
+  });
+
+  // ── Upload (raw JSONL content in body) ────────────────────────────────
+
+  api.post("/hub/recordings/upload", async (c) => {
+    try {
+      const contentType = c.req.header("content-type") || "";
+
+      let content: string;
+      let originalFilename: string | undefined;
+
+      if (contentType.includes("multipart/form-data")) {
+        const formData = await c.req.formData();
+        const file = formData.get("file");
+        if (!file || !(file instanceof File)) {
+          return c.json({ error: "Missing 'file' field in multipart form" }, 400);
+        }
+        content = await file.text();
+        originalFilename = file.name;
+      } else {
+        // Plain text body
+        content = await c.req.text();
+      }
+
+      const meta = store.importContent(content, originalFilename);
+      return c.json(meta, 201);
+    } catch (e: unknown) {
+      return c.json({ error: e instanceof Error ? e.message : String(e) }, 400);
+    }
+  });
+
+  // ── Import from local auto-recordings ─────────────────────────────────
+
+  api.post("/hub/recordings/import-local", async (c) => {
+    try {
+      const body = await c.req.json().catch(() => ({} as { filename?: string }));
+      if (!body.filename) {
+        return c.json({ error: "Missing 'filename' field" }, 400);
+      }
+      const sourcePath = join(options.recordingsDir, body.filename);
+      const resolvedSource = resolve(sourcePath);
+      const resolvedBase = resolve(options.recordingsDir);
+      if (!resolvedSource.startsWith(resolvedBase + sep) && resolvedSource !== resolvedBase) {
+        return c.json({ error: "Invalid filename" }, 400);
+      }
+      if (!existsSync(sourcePath)) {
+        return c.json({ error: "Recording file not found in auto-recordings directory" }, 404);
+      }
+      const meta = store.importLocal(sourcePath);
+      return c.json(meta, 201);
+    } catch (e: unknown) {
+      return c.json({ error: e instanceof Error ? e.message : String(e) }, 400);
+    }
+  });
+
+  // ── Tags ──────────────────────────────────────────────────────────────
+
+  api.put("/hub/recordings/:id/tags", async (c) => {
+    const body = await c.req.json().catch(() => ({} as { tags?: string[] }));
+    if (!Array.isArray(body.tags)) {
+      return c.json({ error: "Missing 'tags' array" }, 400);
+    }
+    const meta = store.updateTags(c.req.param("id"), body.tags);
+    if (!meta) return c.json({ error: "Recording not found" }, 404);
+    return c.json(meta);
+  });
+
+  // ── Replay Sessions ───────────────────────────────────────────────────
+
+  api.post("/hub/replay", async (c) => {
+    try {
+      const body = await c.req.json().catch(() => ({} as { recordingId?: string; speed?: number }));
+      if (!body.recordingId) {
+        return c.json({ error: "Missing 'recordingId'" }, 400);
+      }
+
+      if (body.speed !== undefined && (typeof body.speed !== "number" || body.speed <= 0)) {
+        return c.json({ error: "Invalid 'speed' value" }, 400);
+      }
+
+      const recording = store.loadRecording(body.recordingId);
+      if (!recording) {
+        return c.json({ error: "Recording not found" }, 404);
+      }
+
+      // Lazy import to avoid circular dependency at module load time
+      const { ReplayAdapter } = await import("./replay-adapter.js");
+
+      const replaySessionId = `replay-${Date.now().toString(36)}`;
+      const speed = body.speed ?? 1;
+      const adapter = new ReplayAdapter(recording, speed);
+
+      options.wsBridge.attachBackendAdapter(
+        replaySessionId,
+        adapter,
+        recording.header.backend_type,
+      );
+
+      replayAdapters.set(replaySessionId, adapter);
+
+      // Clean up when replay finishes
+      adapter.onDisconnect(() => {
+        replayAdapters.delete(replaySessionId);
+      });
+
+      // Start playback
+      adapter.play();
+
+      return c.json({
+        sessionId: replaySessionId,
+        backendType: recording.header.backend_type,
+        speed,
+        entryCount: recording.entries.length,
+      }, 201);
+    } catch (e: unknown) {
+      return c.json({ error: e instanceof Error ? e.message : String(e) }, 400);
+    }
+  });
+
+  api.post("/hub/replay/:sessionId/pause", (c) => {
+    const adapter = replayAdapters.get(c.req.param("sessionId"));
+    if (!adapter) return c.json({ error: "Replay session not found" }, 404);
+    adapter.pause();
+    return c.json({ ok: true, paused: true });
+  });
+
+  api.post("/hub/replay/:sessionId/resume", (c) => {
+    const adapter = replayAdapters.get(c.req.param("sessionId"));
+    if (!adapter) return c.json({ error: "Replay session not found" }, 404);
+    adapter.play();
+    return c.json({ ok: true, paused: false });
+  });
+
+  api.post("/hub/replay/:sessionId/speed", async (c) => {
+    const adapter = replayAdapters.get(c.req.param("sessionId"));
+    if (!adapter) return c.json({ error: "Replay session not found" }, 404);
+    const body = await c.req.json().catch(() => ({} as { speed?: number }));
+    if (typeof body.speed !== "number" || body.speed <= 0) {
+      return c.json({ error: "Invalid 'speed' value" }, 400);
+    }
+    adapter.setSpeed(body.speed);
+    return c.json({ ok: true, speed: body.speed });
+  });
+
+  api.get("/hub/replay/:sessionId/progress", (c) => {
+    const adapter = replayAdapters.get(c.req.param("sessionId"));
+    if (!adapter) return c.json({ error: "Replay session not found" }, 404);
+    return c.json(adapter.getProgress());
+  });
+
+  // ── Compatibility Validation ──────────────────────────────────────────
+
+  api.post("/hub/recordings/:id/validate", async (c) => {
+    try {
+      const recording = store.loadRecording(c.req.param("id"));
+      if (!recording) return c.json({ error: "Recording not found" }, 404);
+      const { validateRecording } = await import("./compat-validator.js");
+      const result = validateRecording(recording);
+      return c.json(result);
+    } catch (e: unknown) {
+      return c.json({ error: e instanceof Error ? e.message : String(e) }, 500);
+    }
+  });
+
+  // ── Disconnection Diagnostics ─────────────────────────────────────────
+
+  api.get("/hub/recordings/:id/diagnostics", async (c) => {
+    try {
+      const recording = store.loadRecording(c.req.param("id"));
+      if (!recording) return c.json({ error: "Recording not found" }, 404);
+      const { analyzeDisconnections } = await import("./diagnostics.js");
+      return c.json(analyzeDisconnections(recording));
+    } catch (e: unknown) {
+      return c.json({ error: e instanceof Error ? e.message : String(e) }, 500);
+    }
+  });
+
+  api.get("/hub/recordings/:id/timeline", async (c) => {
+    try {
+      const recording = store.loadRecording(c.req.param("id"));
+      if (!recording) return c.json({ error: "Recording not found" }, 404);
+      const { buildTimeline } = await import("./diagnostics.js");
+      return c.json(buildTimeline(recording));
+    } catch (e: unknown) {
+      return c.json({ error: e instanceof Error ? e.message : String(e) }, 500);
+    }
+  });
+}