forge-remote 2.1.5 → 2.2.0

package/src/claude-session-watcher.js

@@ -0,0 +1,569 @@
+// Forge Remote — External Claude Code session watcher.
+//
+// Tails ~/.claude/projects/<encoded-project>/<sessionId>.jsonl for projects
+// the user has explicitly enabled mirroring on, and streams new entries
+// into Firestore as `messages` so the mobile app can show what's happening
+// on the desktop without the user having to start the session through the
+// app.
+//
+// Sessions surfaced this way are tagged `type: 'observed'` so the mobile
+// handoff banner offers a "Take Over" button — that path respawns Claude
+// under the relay with `--continue`, killing the original terminal session.
+//
+// Privacy: per-project opt-in. Only paths in `desktops/{id}.mirroredProjects`
+// are watched. Default is empty.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+
+import { FieldValue, getDb } from "./firebase.js";
+import * as log from "./logger.js";
+
+const CLAUDE_PROJECTS_DIR = join(homedir(), ".claude", "projects");
+const CURSOR_FILE = join(homedir(), ".forge-remote", "jsonl-cursors.json");
+
+// How long to wait without new bytes before flipping a session from
+// `active` → `idle` in Firestore. Claude doesn't emit a clean session-end
+// event so we use silence as a proxy.
+const IDLE_AFTER_MS = 30_000;
+
+// Cap individual tool-result payloads written to Firestore. A single Read
+// of a large file can be MBs; Firestore caps documents at 1MB, and the
+// mobile UI doesn't need the full thing — just enough to give context.
+const TOOL_RESULT_TRUNCATE_BYTES = 8 * 1024;
+
+// Cap individual user/assistant text messages similarly. Long generated
+// outputs occasionally exceed Firestore limits; truncate with a marker.
+const TEXT_TRUNCATE_BYTES = 64 * 1024;
+
+// File-event types in the .jsonl that aren't user-visible — skip silently.
+const SKIP_TYPES = new Set([
+  "queue-operation",
+  "file-history-snapshot",
+  "summary",
+  "compact-summary",
+  "file-edit-record",
+]);
+
+// Per-file state: read offset + idle timer + bookkeeping for the synthetic
+// session document we created in Firestore for this jsonl.
+const fileState = new Map();
+// Per-desktop config: the set of absolute project paths the user enabled
+// mirroring on. Updated whenever the desktop doc changes.
+let mirroredProjects = new Set();
+let watcher = null;
+let chokidarLib = null;
+let cursorPersistTimer = null;
+let desktopId = null;
+
+/**
+ * Encode an absolute filesystem path the same way Claude Code does when
+ * naming session directories under ~/.claude/projects/. The convention is
+ * "replace every `/` with `-`", so `/Users/dan/foo` becomes `-Users-dan-foo`.
+ *
+ * Note: this collides for paths that *contain* `-` (e.g., `/Users/iron-forge`
+ * encodes to the same folder as `/Users/iron/forge`). We accept that — it
+ * mirrors Claude's own ambiguity and we only mirror projects the user has
+ * explicitly opted in to, so the user already knows which path they meant.
+ */
+function encodeProjectPath(absolutePath) {
+  return absolutePath.replaceAll("/", "-");
+}
+
+function decodeFolderName(folder) {
+  return folder.replaceAll("-", "/");
+}
+
+function loadCursors() {
+  try {
+    if (!existsSync(CURSOR_FILE)) return {};
+    const raw = readFileSync(CURSOR_FILE, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function saveCursorsNow(cursors) {
+  try {
+    mkdirSync(dirname(CURSOR_FILE), { recursive: true });
+    writeFileSync(CURSOR_FILE, JSON.stringify(cursors, null, 2));
+  } catch (e) {
+    log.warn(`claude-session-watcher: cursor save failed — ${e.message}`);
+  }
+}
+
+function scheduleCursorPersist() {
+  if (cursorPersistTimer) return;
+  cursorPersistTimer = setTimeout(() => {
+    cursorPersistTimer = null;
+    const snapshot = {};
+    for (const [path, state] of fileState.entries()) {
+      snapshot[path] = { offset: state.offset, sessionId: state.sessionId };
+    }
+    saveCursorsNow(snapshot);
+  }, 2_000);
+  // .unref() so this timer doesn't keep the Node event loop alive when
+  // SIGINT fires — otherwise Ctrl-C can hang waiting for the persist tick.
+  if (typeof cursorPersistTimer.unref === "function") {
+    cursorPersistTimer.unref();
+  }
+}
+
+function truncateBuffer(text, max, label) {
+  if (typeof text !== "string") return text;
+  if (Buffer.byteLength(text, "utf-8") <= max) return text;
+  // Use a generous Buffer slice so multibyte characters at the boundary
+  // don't crash JSON serialization. Leave a clear marker for the user.
+  const buf = Buffer.from(text, "utf-8").subarray(0, max);
+  const decoded = buf.toString("utf-8");
+  return `${decoded}\n\n…[${label} truncated; showing first ${max.toLocaleString()} bytes]`;
+}
+
+/**
+ * Translate a single jsonl entry into the message shape the mobile app
+ * expects. Returns null for entries we don't surface (internal state,
+ * unknown types, etc.). Returns an array because one assistant entry can
+ * fan out into multiple messages (assistant text + N tool calls).
+ */
+function eventsToMessages(entry) {
+  if (!entry || typeof entry !== "object") return null;
+  if (SKIP_TYPES.has(entry.type)) return null;
+
+  const ts = entry.timestamp ? new Date(entry.timestamp) : new Date();
+  const messageId = entry.uuid || entry.id || null;
+
+  if (entry.type === "user") {
+    const content = extractText(entry.message?.content ?? entry.content);
+    if (!content) return null;
+    return [
+      {
+        type: "user",
+        content: truncateBuffer(content, TEXT_TRUNCATE_BYTES, "prompt"),
+        timestamp: ts,
+        externalId: messageId,
+      },
+    ];
+  }
+
+  if (entry.type === "assistant") {
+    const blocks = Array.isArray(entry.message?.content)
+      ? entry.message.content
+      : [];
+    const out = [];
+    for (const block of blocks) {
+      if (!block || typeof block !== "object") continue;
+      if (block.type === "text" && typeof block.text === "string") {
+        out.push({
+          type: "assistant",
+          content: truncateBuffer(block.text, TEXT_TRUNCATE_BYTES, "response"),
+          timestamp: ts,
+          externalId: messageId,
+        });
+      } else if (block.type === "tool_use") {
+        out.push({
+          type: "tool_call",
+          content: block.name || "tool",
+          toolName: block.name || null,
+          toolInput: safeStringify(block.input, TOOL_RESULT_TRUNCATE_BYTES),
+          toolUseId: block.id || null,
+          timestamp: ts,
+          externalId: messageId,
+        });
+      }
+    }
+    return out.length ? out : null;
+  }
+
+  if (entry.type === "tool_result" || entry.type === "user-tool-result") {
+    const content = extractText(entry.message?.content ?? entry.content);
+    return [
+      {
+        type: "tool_result",
+        content: truncateBuffer(
+          content ?? "",
+          TOOL_RESULT_TRUNCATE_BYTES,
+          "tool result",
+        ),
+        toolUseId: entry.tool_use_id || entry.message?.tool_use_id || null,
+        isError: Boolean(entry.is_error || entry.message?.is_error),
+        timestamp: ts,
+        externalId: messageId,
+      },
+    ];
+  }
+
+  if (entry.type === "system") {
+    const content = extractText(entry.message?.content ?? entry.content);
+    if (!content) return null;
+    return [
+      {
+        type: "system",
+        content: truncateBuffer(content, TEXT_TRUNCATE_BYTES, "system message"),
+        timestamp: ts,
+        externalId: messageId,
+      },
+    ];
+  }
+
+  return null;
+}
+
+/**
+ * Pull a string out of the various shapes Claude emits for `content`. May
+ * be a bare string, an array of `{type:'text',text}` blocks, or an array
+ * of `{type:'tool_result', content: ...}`. We flatten the text bits and
+ * drop the rest.
+ */
+function extractText(value) {
+  if (typeof value === "string") return value;
+  if (!Array.isArray(value)) return null;
+  const parts = [];
+  for (const block of value) {
+    if (!block || typeof block !== "object") continue;
+    if (typeof block.text === "string") parts.push(block.text);
+    else if (typeof block.content === "string") parts.push(block.content);
+  }
+  return parts.length ? parts.join("\n") : null;
+}
+
+function safeStringify(value, max) {
+  try {
+    const s = typeof value === "string" ? value : JSON.stringify(value);
+    return truncateBuffer(s, max, "tool input");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ensure a `sessions/{sessionId}` document exists. First-time call creates
+ * one tagged `observed` so the mobile UI shows the takeover banner. The
+ * relay's session-manager will not touch this doc (it only manages docs
+ * it created itself), so the watcher is the sole writer.
+ */
+async function ensureSessionDoc(sessionId, projectPath) {
+  const db = getDb();
+  const ref = db.collection("sessions").doc(sessionId);
+  const snap = await ref.get();
+  if (snap.exists) return;
+
+  // Read the desktop's ownerUid so the session is reachable by the mobile
+  // user's queries. If the desktop doc is missing for any reason we fall
+  // back to "" — security rules will hide it but the relay can still
+  // append messages.
+  let ownerUid = "";
+  try {
+    const desktopDoc = await db.collection("desktops").doc(desktopId).get();
+    ownerUid = desktopDoc.exists ? desktopDoc.data()?.ownerUid || "" : "";
+  } catch {
+    /* best effort */
+  }
+
+  const projectName =
+    projectPath.split("/").filter(Boolean).pop() || projectPath;
+  await ref.set({
+    desktopId,
+    ownerUid,
+    projectPath,
+    projectName,
+    type: "observed",
+    status: "active",
+    model: "sonnet",
+    agentType: "claude",
+    tokenUsage: { input: 0, output: 0, totalCost: 0 },
+    startedAt: FieldValue.serverTimestamp(),
+    lastActivity: FieldValue.serverTimestamp(),
+    externalSource: "claude-jsonl",
+  });
+  log.info(
+    `claude-session-watcher: surfaced ${sessionId.slice(0, 8)} (${projectName})`,
+  );
+}
+
+async function appendMessages(sessionId, messages) {
+  if (!messages.length) return;
+  const db = getDb();
+  const batch = db.batch();
+  const col = db.collection("sessions").doc(sessionId).collection("messages");
+  for (const msg of messages) {
+    const docRef = msg.externalId ? col.doc(msg.externalId) : col.doc();
+    batch.set(docRef, {
+      ...msg,
+      timestamp: msg.timestamp instanceof Date ? msg.timestamp : new Date(),
+    });
+  }
+  batch.update(db.collection("sessions").doc(sessionId), {
+    lastActivity: FieldValue.serverTimestamp(),
+    status: "active",
+  });
+  await batch.commit();
+}
+
+async function markIdle(sessionId) {
+  try {
+    const db = getDb();
+    await db.collection("sessions").doc(sessionId).update({
+      status: "idle",
+      lastActivity: FieldValue.serverTimestamp(),
+    });
+  } catch {
+    /* best effort */
+  }
+}
+
+function scheduleIdleCheck(state) {
+  if (state.idleTimer) clearTimeout(state.idleTimer);
+  state.idleTimer = setTimeout(() => {
+    markIdle(state.sessionId);
+  }, IDLE_AFTER_MS);
+  // Same unref as the cursor timer — never block process exit on this.
+  if (typeof state.idleTimer.unref === "function") {
+    state.idleTimer.unref();
+  }
+}
+
+/**
+ * Read whatever's been appended to a single .jsonl since the last cursor,
+ * translate each line, and flush to Firestore. Updates the in-memory
+ * cursor on success and schedules a persist.
+ */
+async function processFile(absPath) {
+  let state = fileState.get(absPath);
+
+  // Derive context from the path on first sight.
+  if (!state) {
+    const parts = absPath.split("/");
+    const filename = parts.pop() || "";
+    const folder = parts.pop() || "";
+    const sessionId = filename.replace(/\.jsonl$/, "");
+    const decodedPath = decodeFolderName(folder);
+    if (!sessionId || !decodedPath) return;
+    state = {
+      sessionId,
+      projectPath: decodedPath,
+      offset: 0,
+      idleTimer: null,
+      sessionDocReady: false,
+    };
+    fileState.set(absPath, state);
+
+    // Restore cursor from disk so we don't replay everything on restart.
+    const cursors = loadCursors();
+    const saved = cursors[absPath];
+    if (saved && typeof saved.offset === "number") {
+      state.offset = saved.offset;
+    }
+  }
+
+  // Only mirror if the user opted in for this project.
+  if (!mirroredProjects.has(state.projectPath)) return;
+
+  let stat;
+  try {
+    stat = statSync(absPath);
+  } catch {
+    return;
+  }
+  if (stat.size <= state.offset) return;
+
+  // If the file shrunk (rotation? unlikely for jsonl but possible), reset.
+  if (stat.size < state.offset) state.offset = 0;
+
+  let handle;
+  try {
+    handle = await fs.open(absPath, "r");
+    const buffer = Buffer.alloc(stat.size - state.offset);
+    await handle.read(buffer, 0, buffer.length, state.offset);
+    await handle.close();
+    handle = null;
+
+    const text = buffer.toString("utf-8");
+    // Only consume up to the last complete line. Partial line stays for
+    // the next pass — Claude streams writes, so half-lines are common.
+    const lastNewline = text.lastIndexOf("\n");
+    if (lastNewline === -1) return;
+
+    const consumed = text.slice(0, lastNewline + 1);
+    const lines = consumed.split("\n").filter(Boolean);
+
+    if (!state.sessionDocReady) {
+      await ensureSessionDoc(state.sessionId, state.projectPath);
+      state.sessionDocReady = true;
+    }
+
+    const messages = [];
+    for (const line of lines) {
+      let entry;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const out = eventsToMessages(entry);
+      if (out) messages.push(...out);
+    }
+
+    if (messages.length) {
+      await appendMessages(state.sessionId, messages);
+    }
+
+    state.offset += Buffer.byteLength(consumed, "utf-8");
+    scheduleCursorPersist();
+    scheduleIdleCheck(state);
+  } catch (e) {
+    log.warn(`claude-session-watcher: ${absPath} — ${e.message}`);
+    if (handle) await handle.close().catch(() => {});
+  }
+}
+
+/**
+ * Pull the current `mirroredProjects` list from the desktop doc and
+ * subscribe to changes so toggling a project on/off in the mobile app
+ * takes effect within seconds.
+ */
+function watchDesktopConfig(id) {
+  const db = getDb();
+  return db
+    .collection("desktops")
+    .doc(id)
+    .onSnapshot((snap) => {
+      const list = snap.exists ? snap.data()?.mirroredProjects || [] : [];
+      const next = new Set(
+        Array.isArray(list)
+          ? list.filter((p) => typeof p === "string" && p.length > 0)
+          : [],
+      );
+      // Resolve to absolute paths defensively — the mobile app stores
+      // them as-is from the project list, but normalize to be safe.
+      const normalized = new Set();
+      for (const p of next) {
+        try {
+          normalized.add(resolve(p));
+        } catch {
+          normalized.add(p);
+        }
+      }
+      mirroredProjects = normalized;
+    });
+}
+
+/**
+ * Boot the watcher. Idempotent — calling twice is a no-op.
+ */
+export async function startClaudeSessionWatcher(id) {
+  if (watcher) return;
+  desktopId = id;
+
+  if (!existsSync(CLAUDE_PROJECTS_DIR)) {
+    log.info(
+      "claude-session-watcher: ~/.claude/projects not found — skipping " +
+        "(no external sessions to mirror)",
+    );
+    return;
+  }
+
+  // chokidar is optional. If the relay package didn't pull it in (older
+  // installs, or trimmed deps), fall back to a poll-based watcher built
+  // on Node's fs.watch + a 2s interval scan.
+  try {
+    chokidarLib = (await import("chokidar")).default;
+  } catch {
+    chokidarLib = null;
+  }
+
+  // Subscribe to per-desktop mirror config.
+  const unsubConfig = watchDesktopConfig(desktopId);
+
+  if (chokidarLib) {
+    watcher = chokidarLib.watch(`${CLAUDE_PROJECTS_DIR}/**/*.jsonl`, {
+      ignoreInitial: false,
+      // Polling falls back gracefully on filesystems where inotify isn't
+      // reliable (network mounts, SSHFS). The native option is faster.
+      usePolling: false,
+      awaitWriteFinish: false,
+    });
+    watcher.on("add", (path) => processFile(path));
+    watcher.on("change", (path) => processFile(path));
+    watcher.unsubConfig = unsubConfig;
+    log.info("claude-session-watcher: started (chokidar)");
+  } else {
+    // Polling fallback: scan every 2 seconds.
+    log.info(
+      "claude-session-watcher: started (polling, install chokidar for inotify)",
+    );
+    const pollInterval = setInterval(async () => {
+      try {
+        const projects = await fs.readdir(CLAUDE_PROJECTS_DIR);
+        for (const proj of projects) {
+          const projDir = join(CLAUDE_PROJECTS_DIR, proj);
+          let entries;
+          try {
+            entries = await fs.readdir(projDir);
+          } catch {
+            continue;
+          }
+          for (const f of entries) {
+            if (!f.endsWith(".jsonl")) continue;
+            await processFile(join(projDir, f));
+          }
+        }
+      } catch (e) {
+        log.warn(`claude-session-watcher: scan error — ${e.message}`);
+      }
+    }, 2_000);
+    watcher = { close: () => clearInterval(pollInterval), unsubConfig };
+  }
+}
+
+/**
+ * Tear down the watcher and cancel any pending idle timers. Called from
+ * the relay's SIGINT handler.
+ *
+ * Bounded — chokidar's close() can stall on macOS when there are many
+ * watched files. We race it against a 1-second timeout so Ctrl-C never
+ * gets stuck waiting on the watcher to wind down.
+ */
+export async function stopClaudeSessionWatcher() {
+  if (!watcher) return;
+  // Cancel the Firestore config listener immediately — that one's cheap.
+  try {
+    if (watcher.unsubConfig) watcher.unsubConfig();
+  } catch {
+    /* best effort */
+  }
+  // Persist cursors synchronously up front so a hung close() doesn't lose
+  // the last few offsets we accumulated this session.
+  if (cursorPersistTimer) clearTimeout(cursorPersistTimer);
+  const snapshot = {};
+  for (const [path, state] of fileState.entries()) {
+    snapshot[path] = { offset: state.offset, sessionId: state.sessionId };
+    if (state.idleTimer) clearTimeout(state.idleTimer);
+  }
+  if (Object.keys(snapshot).length) saveCursorsNow(snapshot);
+
+  // Race chokidar.close() against a 1s deadline. If it doesn't return in
+  // time, give up — the process is exiting anyway and the OS will reclaim
+  // the file watches.
+  const closePromise = (async () => {
+    try {
+      if (typeof watcher.close === "function") await watcher.close();
+    } catch {
+      /* best effort */
+    }
+  })();
+  const timeout = new Promise((resolve) => {
+    const t = setTimeout(resolve, 1_000);
+    if (typeof t.unref === "function") t.unref();
+  });
+  await Promise.race([closePromise, timeout]);
+  watcher = null;
+}

package/src/cli.js

@@ -32,6 +32,10 @@ import { stopAllCaptures } from "./screenshot-manager.js";
 import { scanProjects } from "./project-scanner.js";
 import { startWebhookServer, stopWebhookServer } from "./webhook-server.js";
 import { watchWebhookConfigs, stopWatching } from "./webhook-watcher.js";
+import {
+  startClaudeSessionWatcher,
+  stopClaudeSessionWatcher,
+} from "./claude-session-watcher.js";
 import * as log from "./logger.js";
 import { checkForUpdate } from "./update-checker.js";
 import { deployFirestoreRules } from "./google-auth.js";
@@ -200,6 +204,12 @@ program
       log.info(`Webhook server ready at ${webhookServer.tunnelUrl}`);
     }
 
+    // Mirror externally-spawned Claude Code sessions (those launched in
+    // a terminal, not via the mobile app). Reads from ~/.claude/projects
+    // and surfaces messages to Firestore for projects the user opted in
+    // to mirror. Per-project opt-in lives on the desktop doc.
+    await startClaudeSessionWatcher(desktopId);
+
     // Print startup banner.
     log.banner(hostname(), getPlatformName(), desktopId, projects.length);
 
@@ -224,6 +234,7 @@ program
       try {
         stopWatching();
         await stopWebhookServer();
+        await stopClaudeSessionWatcher();
         await shutdownAllSessions();
         stopAllTunnels();
         stopAllCaptures();