forge-remote 0.1.0

package/src/session-manager.js

@@ -0,0 +1,1539 @@
+// Forge Remote Relay — Desktop Agent for Forge Remote
+// Copyright (c) 2025-2026 Iron Forge Apps
+// Created by Daniel Wendel, CEO/Founder of Iron Forge Apps
+// AGPL-3.0 License — See LICENSE
+
+import { getDb, FieldValue } from "./firebase.js";
+import { spawn, execSync } from "child_process";
+import * as log from "./logger.js";
+import { startTunnel, stopTunnel } from "./tunnel-manager.js";
+import {
+  startCapturing,
+  stopCapturing,
+  hasActiveSimulator,
+} from "./screenshot-manager.js";
+
+// ---------------------------------------------------------------------------
+// Resolve the user's shell environment so spawned processes inherit PATH,
+// API keys (ANTHROPIC_API_KEY), etc.  Node's default `process.env` may be
+// stripped down when launched from certain contexts (launchd, cron, etc.).
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an env for spawning Claude processes.
+ *
+ * Strategy: start with process.env (preserves auth, PATH, etc.) then merge
+ * any extra vars from the user's shell profile (picks up PATH additions,
+ * ANTHROPIC_API_KEY, etc.).  Finally, strip any CLAUDECODE / CLAUDE_CODE_*
+ * vars that block nested launches.
+ */
+function buildSpawnEnv() {
+  // Start with current runtime env — this has auth context.
+  const env = { ...process.env };
+
+  // Try to merge shell profile vars (picks up PATH changes, API keys, etc.).
+  try {
+    const shell = process.env.SHELL || "/bin/zsh";
+    const raw = execSync(`${shell} -ilc env`, {
+      timeout: 5000,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    for (const line of raw.split("\n")) {
+      const idx = line.indexOf("=");
+      if (idx > 0) {
+        const key = line.slice(0, idx);
+        // Only add vars that aren't already set — don't overwrite runtime env.
+        if (!(key in env)) {
+          env[key] = line.slice(idx + 1);
+        }
+      }
+    }
+  } catch {
+    log.warn("Could not resolve user shell profile — using process.env only");
+  }
+
+  // Remove ALL env vars that block Claude from spawning.
+  const BLOCKED_PREFIXES = ["CLAUDECODE", "CLAUDE_CODE"];
+  for (const key of Object.keys(env)) {
+    if (BLOCKED_PREFIXES.some((prefix) => key.startsWith(prefix))) {
+      log.info(`Removing blocking env var: ${key}`);
+      delete env[key];
+    }
+  }
+
+  return env;
+}
+
+const shellEnv = buildSpawnEnv();
+
+// Verify claude is findable.
+function resolveClaudePath() {
+  try {
+    const p = execSync("which claude", {
+      encoding: "utf-8",
+      env: shellEnv,
+      timeout: 5000,
+    }).trim();
+    if (p) {
+      log.success(`Claude CLI found at: ${p}`);
+      return p;
+    }
+  } catch {
+    // Fall through.
+  }
+  log.warn("Could not find 'claude' in PATH — will try spawning directly");
+  return "claude";
+}
+
+const claudeBinary = resolveClaudePath();
+
+/**
+ * Tracks active sessions.
+ *
+ * Each entry stores the session config (cwd, model) and optionally a
+ * running Claude process.  Between turns the process is null and the
+ * session status is "idle".  A new process is spawned for each prompt
+ * using `--continue` so Claude picks up the conversation history.
+ */
+const activeSessions = new Map();
+
+/**
+ * Maximum number of concurrent sessions this relay will run.
+ * Can be overridden via the FORGE_MAX_SESSIONS environment variable.
+ */
+const MAX_SESSIONS = parseInt(process.env.FORGE_MAX_SESSIONS, 10) || 3;
+
+/**
+ * Returns the count of real sessions (excluding command-watcher sentinel keys).
+ */
+function getActiveSessionCount() {
+  let count = 0;
+  for (const key of activeSessions.keys()) {
+    if (!key.startsWith("cmd-watcher-")) count++;
+  }
+  return count;
+}
+
+// ---------------------------------------------------------------------------
+// Command listeners
+// ---------------------------------------------------------------------------
+
+export function listenForCommands(desktopId) {
+  const db = getDb();
+
+  // Desktop-level commands (start_session, etc.).
+  db.collection("desktops")
+    .doc(desktopId)
+    .collection("commands")
+    .where("status", "==", "pending")
+    .onSnapshot((snap) => {
+      for (const change of snap.docChanges()) {
+        if (change.type === "added") {
+          handleDesktopCommand(desktopId, change.doc);
+        }
+      }
+    });
+
+  // Watch for existing sessions → subscribe to their commands.
+  db.collection("sessions")
+    .where("desktopId", "==", desktopId)
+    .onSnapshot((snap) => {
+      for (const doc of snap.docs) {
+        watchSessionCommands(doc.id);
+      }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Desktop commands
+// ---------------------------------------------------------------------------
+
+async function handleDesktopCommand(desktopId, commandDoc) {
+  const data = commandDoc.data();
+  const db = getDb();
+  const cmdRef = db
+    .collection("desktops")
+    .doc(desktopId)
+    .collection("commands")
+    .doc(commandDoc.id);
+
+  log.command(data.type, data.payload?.projectPath || "");
+  await cmdRef.update({ status: "processing" });
+
+  try {
+    switch (data.type) {
+      case "start_session":
+        await startNewSession(desktopId, data.payload);
+        break;
+      default:
+        log.warn(`Unknown desktop command type: ${data.type}`);
+    }
+    await cmdRef.update({ status: "completed" });
+  } catch (e) {
+    log.error(`Desktop command failed: ${e.message}`);
+    await cmdRef.update({ status: "failed", error: e.message });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Session commands
+// ---------------------------------------------------------------------------
+
+function watchSessionCommands(sessionId) {
+  if (activeSessions.has(`cmd-watcher-${sessionId}`)) return;
+  activeSessions.set(`cmd-watcher-${sessionId}`, true);
+
+  const db = getDb();
+  db.collection("sessions")
+    .doc(sessionId)
+    .collection("commands")
+    .where("status", "==", "pending")
+    .onSnapshot((snap) => {
+      for (const change of snap.docChanges()) {
+        if (change.type === "added") {
+          handleSessionCommand(sessionId, change.doc);
+        }
+      }
+    });
+}
+
+async function handleSessionCommand(sessionId, commandDoc) {
+  const data = commandDoc.data();
+  const db = getDb();
+  const cmdRef = db
+    .collection("sessions")
+    .doc(sessionId)
+    .collection("commands")
+    .doc(commandDoc.id);
+
+  await cmdRef.update({ status: "processing" });
+
+  try {
+    switch (data.type) {
+      case "send_prompt":
+        log.command(
+          "send_prompt",
+          `"${(data.payload?.prompt || "").slice(0, 60)}..."`,
+        );
+        await sendFollowUpPrompt(sessionId, data.payload?.prompt);
+        break;
+      case "stop_session":
+        log.command("stop_session", sessionId.slice(0, 8));
+        await stopSession(sessionId);
+        break;
+      case "kill_session":
+        log.command("kill_session", sessionId.slice(0, 8));
+        await killSession(sessionId);
+        break;
+      default:
+        log.warn(`Unknown session command type: ${data.type}`);
+    }
+    await cmdRef.update({ status: "completed" });
+  } catch (e) {
+    log.error(`Session command failed: ${e.message}`);
+    await cmdRef.update({ status: "failed", error: e.message });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Start a new session
+// ---------------------------------------------------------------------------
+
+const MODEL_DISPLAY_NAMES = {
+  sonnet: "Claude Sonnet 4.6",
+  opus: "Claude Opus 4.6",
+  haiku: "Claude Haiku 4.5",
+};
+
+function modelDisplayName(model) {
+  return (
+    MODEL_DISPLAY_NAMES[model?.toLowerCase()] || model || "Claude Sonnet 4.6"
+  );
+}
+
+export async function startNewSession(desktopId, payload) {
+  // Enforce session limit.
+  const currentCount = getActiveSessionCount();
+  if (currentCount >= MAX_SESSIONS) {
+    throw new Error(
+      `Session limit reached (${currentCount}/${MAX_SESSIONS}). ` +
+        `End an existing session before starting a new one. ` +
+        `Set FORGE_MAX_SESSIONS env var to increase the limit.`,
+    );
+  }
+
+  const { prompt, projectPath, model } = payload || {};
+  const db = getDb();
+  const resolvedModel = model || "sonnet";
+  const resolvedPath = projectPath || process.cwd();
+  const projectName = resolvedPath.split("/").pop();
+
+  // Create session document.
+  const sessionRef = db.collection("sessions").doc();
+  const sessionId = sessionRef.id;
+
+  await sessionRef.set({
+    desktopId,
+    ownerUid: "",
+    projectPath: resolvedPath,
+    projectName,
+    type: "managed",
+    status: "active",
+    model: resolvedModel,
+    tokenUsage: { input: 0, output: 0, totalCost: 0 },
+    startedAt: FieldValue.serverTimestamp(),
+    lastActivity: FieldValue.serverTimestamp(),
+  });
+
+  // Copy ownerUid from desktop.
+  const desktopDoc = await db.collection("desktops").doc(desktopId).get();
+  if (desktopDoc.exists) {
+    await sessionRef.update({ ownerUid: desktopDoc.data().ownerUid });
+  }
+
+  // Register session in active sessions map (no process yet).
+  activeSessions.set(sessionId, {
+    process: null,
+    desktopId,
+    projectPath: resolvedPath,
+    model: resolvedModel,
+    startTime: Date.now(),
+    messageCount: 0,
+    toolCallCount: 0,
+    isFirstPrompt: true,
+    lastToolCall: null, // Last tool_use block (for permission requests)
+    permissionNeeded: false, // True when Claude reports permission denial
+    permissionWatcher: null, // Firestore unsubscribe for permission doc
+  });
+
+  // Desktop terminal banner.
+  log.sessionStarted({
+    sessionId,
+    project: resolvedPath,
+    model: modelDisplayName(resolvedModel),
+    prompt,
+  });
+
+  // System message in Firestore.
+  const configSummary = [
+    `Session started on ${projectName}`,
+    `Model: ${modelDisplayName(resolvedModel)}`,
+    `Project: ${resolvedPath}`,
+  ].join(" · ");
+
+  await db.collection("sessions").doc(sessionId).collection("messages").add({
+    type: "system",
+    content: configSummary,
+    timestamp: FieldValue.serverTimestamp(),
+  });
+
+  // Store the initial prompt as a user message.
+  if (prompt) {
+    await db.collection("sessions").doc(sessionId).collection("messages").add({
+      type: "user",
+      content: prompt,
+      timestamp: FieldValue.serverTimestamp(),
+    });
+  }
+
+  watchSessionCommands(sessionId);
+
+  // Run the initial prompt.
+  if (prompt) {
+    await runClaudeProcess(sessionId, prompt);
+  }
+
+  return sessionId;
+}
+
+// ---------------------------------------------------------------------------
+// Send a follow-up prompt (spawns a new process with --continue)
+// ---------------------------------------------------------------------------
+
+async function sendFollowUpPrompt(sessionId, prompt) {
+  const session = activeSessions.get(sessionId);
+  if (!session) {
+    throw new Error("Session not found. It may have ended.");
+  }
+
+  if (session.process) {
+    throw new Error(
+      "Claude is still processing. Wait for the current turn to finish.",
+    );
+  }
+
+  // Cancel any pending permission watcher — user is overriding with a prompt.
+  if (session.permissionWatcher) {
+    session.permissionWatcher();
+    session.permissionWatcher = null;
+  }
+  session.permissionNeeded = false;
+
+  // Store the user's message in Firestore.
+  const db = getDb();
+  await db.collection("sessions").doc(sessionId).collection("messages").add({
+    type: "user",
+    content: prompt,
+    timestamp: FieldValue.serverTimestamp(),
+  });
+
+  log.session(
+    sessionId,
+    `Follow-up prompt: "${prompt.slice(0, 80)}${prompt.length > 80 ? "..." : ""}"`,
+  );
+
+  // Run Claude with --continue to pick up conversation history.
+  await runClaudeProcess(sessionId, prompt);
+}
+
+// ---------------------------------------------------------------------------
+// Core: spawn a Claude process for a single turn
+// ---------------------------------------------------------------------------
+
+async function runClaudeProcess(sessionId, prompt) {
+  const session = activeSessions.get(sessionId);
+  if (!session) return;
+
+  // Reset permission state for this new turn.
+  session.permissionNeeded = false;
+  session.lastToolCall = null;
+
+  const db = getDb();
+  const sessionRef = db.collection("sessions").doc(sessionId);
+
+  // Mark session as active.
+  await sessionRef.update({
+    status: "active",
+    lastActivity: FieldValue.serverTimestamp(),
+  });
+
+  // Build args.
+  const args = ["--output-format", "stream-json", "--verbose", "-p"];
+  if (session.model) args.push("--model", session.model);
+
+  // Use --continue for follow-up prompts to maintain conversation context.
+  if (!session.isFirstPrompt) {
+    args.push("--continue");
+  }
+  session.isFirstPrompt = false;
+
+  args.push(prompt);
+
+  log.session(sessionId, `Spawning: ${claudeBinary} ${args.join(" ")}`);
+
+  const claudeProcess = spawn(claudeBinary, args, {
+    cwd: session.projectPath,
+    env: shellEnv,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  session.process = claudeProcess;
+
+  // Close stdin immediately — `-p` mode reads the prompt from args, not stdin.
+  // Leaving stdin open can cause Claude CLI to hang waiting for input.
+  claudeProcess.stdin.end();
+
+  log.session(sessionId, `Process started — PID ${claudeProcess.pid}`);
+
+  // Watchdog: warn if no output received. Opus is much slower to start.
+  const watchdogMs = session.model === "opus" ? 45_000 : 20_000;
+  const killAfterMs = 120_000; // Auto-kill if completely stuck after 2 min.
+  let receivedOutput = false;
+
+  const watchdog = setTimeout(() => {
+    if (!receivedOutput) {
+      // Check if process is still alive.
+      let alive = false;
+      try {
+        process.kill(claudeProcess.pid, 0); // Signal 0 = check existence.
+        alive = true;
+      } catch {
+        alive = false;
+      }
+      log.warn(
+        `[${sessionId.slice(0, 8)}] No output from Claude after ${watchdogMs / 1000}s — PID ${claudeProcess.pid} ${alive ? "still running" : "DEAD"}`,
+      );
+    }
+  }, watchdogMs);
+
+  // Hard kill if process never produces output.
+  const killTimer = setTimeout(async () => {
+    if (!receivedOutput) {
+      log.error(
+        `[${sessionId.slice(0, 8)}] No output after ${killAfterMs / 1000}s — auto-killing stuck process (PID ${claudeProcess.pid})`,
+      );
+      claudeProcess.kill("SIGKILL");
+
+      await sessionRef.update({
+        status: "error",
+        lastActivity: FieldValue.serverTimestamp(),
+        errorMessage:
+          "Process timed out — no output received. Claude CLI may need re-authentication or the model may be unavailable.",
+      });
+
+      await db
+        .collection("sessions")
+        .doc(sessionId)
+        .collection("messages")
+        .add({
+          type: "system",
+          content:
+            "Session timed out — Claude produced no output. Try restarting the relay or using a different model.",
+          timestamp: FieldValue.serverTimestamp(),
+        });
+    }
+  }, killAfterMs);
+
+  // ── Parse stdout (stream-json) ──
+  let stdoutBuffer = "";
+
+  claudeProcess.stdout.on("data", async (data) => {
+    if (!receivedOutput) {
+      receivedOutput = true;
+      clearTimeout(watchdog);
+      clearTimeout(killTimer);
+      log.session(sessionId, "First output received from Claude");
+    }
+
+    stdoutBuffer += data.toString();
+    const lines = stdoutBuffer.split("\n");
+    stdoutBuffer = lines.pop();
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const event = JSON.parse(line);
+        await handleStreamEvent(sessionId, sessionRef, event);
+      } catch {
+        if (line.trim()) {
+          const text = line.trim();
+          log.claudeOutput(sessionId, text);
+
+          // Detect auth / login errors that come as plain text.
+          if (/not logged in|please run.*login/i.test(text)) {
+            log.error(
+              `[${sessionId.slice(0, 8)}] Claude CLI auth error: ${text}`,
+            );
+            await db
+              .collection("sessions")
+              .doc(sessionId)
+              .collection("messages")
+              .add({
+                type: "system",
+                content: `Auth error: ${text}. Run "claude /login" in your terminal, then restart the relay.`,
+                timestamp: FieldValue.serverTimestamp(),
+              });
+          } else {
+            await storeAssistantMessage(sessionId, text);
+          }
+        }
+      }
+    }
+  });
+
+  // ── Stderr ──
+  let stderrBuffer = "";
+
+  claudeProcess.stderr.on("data", async (data) => {
+    if (!receivedOutput) {
+      receivedOutput = true;
+      clearTimeout(watchdog);
+      clearTimeout(killTimer);
+    }
+    const raw = data.toString();
+    stderrBuffer += raw;
+    const lines = stderrBuffer.split("\n");
+    stderrBuffer = lines.pop();
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      log.warn(`[stderr] ${line.trim()}`);
+      await db
+        .collection("sessions")
+        .doc(sessionId)
+        .collection("messages")
+        .add({
+          type: "system",
+          content: line.trim(),
+          timestamp: FieldValue.serverTimestamp(),
+        });
+      // Dev servers often print to stderr.
+      await detectAndTunnelDevServer(sessionId, line);
+      // Native app build output often goes to stderr too.
+      detectAndStartScreenshots(sessionId, line);
+    }
+  });
+
+  // ── Process exit — mark session idle (not completed) so user can continue ──
+  claudeProcess.on("close", async (code, signal) => {
+    clearTimeout(watchdog);
+    clearTimeout(killTimer);
+    log.session(
+      sessionId,
+      `Process exited — code: ${code}, signal: ${signal}, PID: ${claudeProcess.pid}`,
+    );
+
+    // Flush any remaining data in buffers.
+    if (stdoutBuffer.trim()) {
+      log.claudeOutput(sessionId, `[flush] ${stdoutBuffer.trim()}`);
+    }
+    if (stderrBuffer.trim()) {
+      log.warn(`[stderr/flush] ${stderrBuffer.trim()}`);
+      await db
+        .collection("sessions")
+        .doc(sessionId)
+        .collection("messages")
+        .add({
+          type: "system",
+          content: stderrBuffer.trim(),
+          timestamp: FieldValue.serverTimestamp(),
+        });
+    }
+
+    const sess = activeSessions.get(sessionId);
+    if (sess) sess.process = null; // Clear process so follow-ups can spawn.
+
+    if (code === 0) {
+      if (sess?.permissionNeeded && sess?.lastToolCall) {
+        // Claude was denied a tool call — create a permission request and wait.
+        const permDocId = await createPermissionRequest(
+          sessionId,
+          sess.lastToolCall,
+        );
+        await sessionRef.update({
+          status: "waiting_permission",
+          lastActivity: FieldValue.serverTimestamp(),
+        });
+        watchPermissionDecision(sessionId, permDocId);
+        log.session(
+          sessionId,
+          "Permission needed — waiting for mobile approval",
+        );
+      } else {
+        // Turn completed successfully — session goes idle, awaiting next prompt.
+        await sessionRef.update({
+          status: "idle",
+          lastActivity: FieldValue.serverTimestamp(),
+        });
+
+        await db
+          .collection("sessions")
+          .doc(sessionId)
+          .collection("messages")
+          .add({
+            type: "system",
+            content:
+              "Claude finished — send another message or end the session.",
+            timestamp: FieldValue.serverTimestamp(),
+          });
+
+        log.session(
+          sessionId,
+          "Turn complete — session idle, waiting for input",
+        );
+      }
+    } else {
+      // Error — end the session.
+      const duration = sess
+        ? Math.round((Date.now() - sess.startTime) / 1000)
+        : 0;
+      const durationStr = formatDuration(duration);
+      const toolCount = sess?.toolCallCount || 0;
+      const msgCount = sess?.messageCount || 0;
+
+      activeSessions.delete(sessionId);
+
+      await sessionRef.update({
+        status: "error",
+        lastActivity: FieldValue.serverTimestamp(),
+        durationSeconds: duration,
+        errorMessage: `Process exited with code ${code}`,
+      });
+
+      await db
+        .collection("sessions")
+        .doc(sessionId)
+        .collection("messages")
+        .add({
+          type: "system",
+          content: `Session ended with error (code ${code}) · Duration: ${durationStr}`,
+          timestamp: FieldValue.serverTimestamp(),
+        });
+
+      log.sessionEnded({
+        sessionId,
+        status: "error",
+        duration: durationStr,
+        toolCalls: toolCount,
+        messages: msgCount,
+      });
+    }
+  });
+
+  claudeProcess.on("error", async (err) => {
+    log.error(`Failed to start Claude process: ${err.message}`);
+    const sess = activeSessions.get(sessionId);
+    if (sess) sess.process = null;
+
+    await sessionRef.update({
+      status: "error",
+      lastActivity: FieldValue.serverTimestamp(),
+      errorMessage: `Failed to start: ${err.message}`,
+    });
+
+    await db
+      .collection("sessions")
+      .doc(sessionId)
+      .collection("messages")
+      .add({
+        type: "system",
+        content: `Failed to start Claude: ${err.message}. Is Claude Code CLI installed?`,
+        timestamp: FieldValue.serverTimestamp(),
+      });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Stop a session
+// ---------------------------------------------------------------------------
+
+async function stopSession(sessionId) {
+  const session = activeSessions.get(sessionId);
+
+  // Kill running process if any.
+  if (session?.process) {
+    session.process.kill("SIGTERM");
+  }
+
+  // Cancel permission watcher if active.
+  if (session?.permissionWatcher) {
+    session.permissionWatcher();
+    session.permissionWatcher = null;
+  }
+
+  // Stop any active tunnel and screenshot capture.
+  await stopTunnel(sessionId);
+  tunneledPorts.delete(sessionId);
+  stopCapturing(sessionId);
+  capturingSessions.delete(sessionId);
+
+  const db = getDb();
+  const sessionRef = db.collection("sessions").doc(sessionId);
+  const duration = session
+    ? Math.round((Date.now() - session.startTime) / 1000)
+    : 0;
+  const durationStr = formatDuration(duration);
+
+  activeSessions.delete(sessionId);
+
+  await sessionRef.update({
+    status: "completed",
+    lastActivity: FieldValue.serverTimestamp(),
+    durationSeconds: duration,
+  });
+
+  await db
+    .collection("sessions")
+    .doc(sessionId)
+    .collection("messages")
+    .add({
+      type: "system",
+      content: `Session ended by user · Duration: ${durationStr}`,
+      timestamp: FieldValue.serverTimestamp(),
+    });
+
+  log.sessionEnded({
+    sessionId,
+    status: "completed",
+    duration: durationStr,
+    toolCalls: session?.toolCallCount || 0,
+    messages: session?.messageCount || 0,
+  });
+
+  log.session(sessionId, "Session stopped by mobile user");
+}
+
+// ---------------------------------------------------------------------------
+// Kill a session (force — SIGKILL if SIGTERM doesn't work)
+// ---------------------------------------------------------------------------
+
+async function killSession(sessionId) {
+  const session = activeSessions.get(sessionId);
+
+  // Cancel permission watcher if active.
+  if (session?.permissionWatcher) {
+    session.permissionWatcher();
+    session.permissionWatcher = null;
+  }
+
+  // Stop any active tunnel and screenshot capture.
+  await stopTunnel(sessionId);
+  tunneledPorts.delete(sessionId);
+  stopCapturing(sessionId);
+  capturingSessions.delete(sessionId);
+
+  // Force-kill running process.
+  if (session?.process) {
+    log.warn(
+      `Force-killing Claude process for session ${sessionId.slice(0, 8)}`,
+    );
+    session.process.kill("SIGKILL");
+  }
+
+  const db = getDb();
+  const sessionRef = db.collection("sessions").doc(sessionId);
+  const duration = session
+    ? Math.round((Date.now() - session.startTime) / 1000)
+    : 0;
+  const durationStr = formatDuration(duration);
+
+  activeSessions.delete(sessionId);
+
+  await sessionRef.update({
+    status: "completed",
+    lastActivity: FieldValue.serverTimestamp(),
+    durationSeconds: duration,
+  });
+
+  await db
+    .collection("sessions")
+    .doc(sessionId)
+    .collection("messages")
+    .add({
+      type: "system",
+      content: `Session killed by user · Duration: ${durationStr}`,
+      timestamp: FieldValue.serverTimestamp(),
+    });
+
+  log.sessionEnded({
+    sessionId,
+    status: "completed",
+    duration: durationStr,
+    toolCalls: session?.toolCallCount || 0,
+    messages: session?.messageCount || 0,
+  });
+
+  log.session(sessionId, "Session force-killed by mobile user");
+}
+
+// ---------------------------------------------------------------------------
+// Stream-JSON event handler
+// ---------------------------------------------------------------------------
+
+async function handleStreamEvent(sessionId, sessionRef, event) {
+  const db = getDb();
+  const session = activeSessions.get(sessionId);
+
+  // Result event — end of a turn (token usage).
+  if (event.type === "result") {
+    const tokenUsage = {
+      input: event.input_tokens || 0,
+      output: event.output_tokens || 0,
+      totalCost: event.cost_usd || 0,
+    };
+
+    await sessionRef.update({
+      tokenUsage,
+      lastActivity: FieldValue.serverTimestamp(),
+    });
+
+    if (session) session.tokenUsage = tokenUsage;
+
+    log.session(
+      sessionId,
+      `Tokens: ${tokenUsage.input} in / ${tokenUsage.output} out ($${tokenUsage.totalCost.toFixed(4)})`,
+    );
+    return;
+  }
+
+  // Assistant message.
+  if (event.type === "assistant") {
+    const contentBlocks = event.message?.content || [];
+
+    for (const block of contentBlocks) {
+      if (block.type === "text" && block.text?.trim()) {
+        log.claudeOutput(sessionId, block.text);
+        await storeAssistantMessage(sessionId, block.text);
+        // Check for dev server URLs in Claude's text output.
+        await detectAndTunnelDevServer(sessionId, block.text);
+        // Check for native app build/run patterns.
+        detectAndStartScreenshots(sessionId, block.text);
+      }
+
+      if (block.type === "tool_use") {
+        log.toolCall(sessionId, block.name, block.input);
+        await storeToolCall(sessionId, block);
+        // Track the last tool call for permission detection.
+        if (session) {
+          session.lastToolCall = {
+            name: block.name,
+            input: block.input,
+            id: block.id,
+          };
+        }
+        // Check tool output for dev server URLs (e.g., Bash running npm start).
+        const toolStr =
+          typeof block.input === "string"
+            ? block.input
+            : JSON.stringify(block.input || {});
+        await detectAndTunnelDevServer(sessionId, toolStr);
+        // Check for native app build/run patterns.
+        detectAndStartScreenshots(sessionId, toolStr);
+      }
+    }
+
+    await sessionRef.update({ lastActivity: FieldValue.serverTimestamp() });
+    return;
+  }
+
+  // Content block start (tool use).
+  if (event.type === "content_block_start") {
+    const block = event.content_block;
+    if (block?.type === "tool_use") {
+      log.toolCall(sessionId, block.name, block.input);
+      await storeToolCall(sessionId, block);
+      // Track for permission detection.
+      if (session) {
+        session.lastToolCall = {
+          name: block.name,
+          input: block.input,
+          id: block.id,
+        };
+      }
+    }
+    return;
+  }
+
+  // Content block stop — may carry the final accumulated tool input.
+  if (event.type === "content_block_stop") {
+    // Some stream formats include the final content block here; not always
+    // actionable but we log it for debugging.
+    return;
+  }
+
+  // Tool result — contains the output from a tool execution.
+  if (event.type === "tool_result") {
+    const toolUseId = event.tool_use_id;
+    const isError = event.is_error === true;
+
+    // Extract result text from the content blocks.
+    let resultText = "";
+    if (typeof event.content === "string") {
+      resultText = event.content;
+    } else if (Array.isArray(event.content)) {
+      resultText = event.content
+        .map((block) => {
+          if (block.type === "text") return block.text;
+          return JSON.stringify(block);
+        })
+        .join("\n");
+    } else if (event.output) {
+      resultText =
+        typeof event.output === "string"
+          ? event.output
+          : JSON.stringify(event.output);
+    }
+
+    if (toolUseId) {
+      await updateToolCallResult(sessionId, toolUseId, resultText, !isError);
+
+      // Store result as a message for the chat view.
+      if (resultText) {
+        await db
+          .collection("sessions")
+          .doc(sessionId)
+          .collection("messages")
+          .add({
+            type: "tool_result",
+            content: resultText.slice(0, 5000), // Cap at 5KB for Firestore.
+            toolUseId,
+            isError,
+            timestamp: FieldValue.serverTimestamp(),
+          });
+      }
+    }
+
+    // Check tool result output for dev server URLs.
+    if (resultText) {
+      await detectAndTunnelDevServer(sessionId, resultText);
+      detectAndStartScreenshots(sessionId, resultText);
+    }
+
+    await sessionRef.update({ lastActivity: FieldValue.serverTimestamp() });
+    return;
+  }
+
+  // System init.
+  if (event.type === "system" && event.subtype === "init") {
+    log.session(sessionId, "Claude Code initialized");
+    return;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Firestore write helpers
+// ---------------------------------------------------------------------------
+
+// Patterns that indicate Claude was denied permission for a tool call.
+const PERMISSION_PATTERNS = [
+  /need your approval/i,
+  /permission (?:required|denied|blocked)/i,
+  /could you approve/i,
+  /keeps? getting blocked/i,
+  /permission system/i,
+  /being blocked by/i,
+  /approve the command/i,
+  /blocked by.+permission/i,
+  /can'?t (?:execute|run).+(?:permission|approval)/i,
+];
+
+async function storeAssistantMessage(sessionId, text) {
+  const db = getDb();
+  const session = activeSessions.get(sessionId);
+  if (session) session.messageCount = (session.messageCount || 0) + 1;
+
+  await db.collection("sessions").doc(sessionId).collection("messages").add({
+    type: "assistant",
+    content: text,
+    timestamp: FieldValue.serverTimestamp(),
+  });
+
+  // Check if Claude's message indicates a permission denial.
+  if (session?.lastToolCall && !session.permissionNeeded) {
+    for (const pattern of PERMISSION_PATTERNS) {
+      if (pattern.test(text)) {
+        session.permissionNeeded = true;
+        log.info(
+          `[${sessionId.slice(0, 8)}] Permission denial detected for ${session.lastToolCall.name}`,
+        );
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * Maps Claude tool_use block IDs to Firestore toolCall doc IDs so we can
+ * update tool call documents with their results when they arrive later in
+ * the stream (via content_block_stop or tool_result events).
+ *
+ * Key: `${sessionId}:${block.id}` — Value: Firestore doc ID
+ */
+const toolCallDocIds = new Map();
+
+async function storeToolCall(sessionId, block) {
+  const db = getDb();
+  const session = activeSessions.get(sessionId);
+  if (session) session.toolCallCount = (session.toolCallCount || 0) + 1;
+
+  const toolName = block.name || "unknown";
+  const toolInput =
+    typeof block.input === "string"
+      ? block.input
+      : JSON.stringify(block.input || {});
+
+  const docRef = await db
+    .collection("sessions")
+    .doc(sessionId)
+    .collection("toolCalls")
+    .add({
+      toolName,
+      toolInput,
+      toolUseId: block.id || null,
+      result: null,
+      timestamp: FieldValue.serverTimestamp(),
+      success: true,
+    });
+
+  // Track the mapping so we can update this doc when the result arrives.
+  if (block.id) {
+    toolCallDocIds.set(`${sessionId}:${block.id}`, docRef.id);
+  }
+
+  await db
+    .collection("sessions")
+    .doc(sessionId)
+    .collection("messages")
+    .add({
+      type: "tool_call",
+      content: `${toolName}: ${toolInput.slice(0, 200)}`,
+      toolName,
+      timestamp: FieldValue.serverTimestamp(),
+    });
+}
+
+/**
+ * Update a previously stored tool call with its result.
+ */
+async function updateToolCallResult(sessionId, toolUseId, resultText, success) {
+  const key = `${sessionId}:${toolUseId}`;
+  const firestoreDocId = toolCallDocIds.get(key);
+  if (!firestoreDocId) {
+    log.warn(
+      `[${sessionId.slice(0, 8)}] No tool call doc found for tool_use ID ${toolUseId}`,
+    );
+    return;
+  }
+
+  const db = getDb();
+  await db
+    .collection("sessions")
+    .doc(sessionId)
+    .collection("toolCalls")
+    .doc(firestoreDocId)
+    .update({
+      result: resultText,
+      success: success !== false,
+    });
+
+  // Clean up the mapping entry.
+  toolCallDocIds.delete(key);
+
+  log.session(
+    sessionId,
+    `Tool result stored (${toolUseId?.slice(0, 12)}): ${resultText?.slice(0, 80)}...`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Dev server URL detection + tunnel creation
+// ---------------------------------------------------------------------------
+
+// Patterns that indicate a native mobile app is being built/run.
+// When matched, we start periodic simulator screenshot capture.
+const NATIVE_APP_PATTERNS = [
+  /flutter\s+run/i,
+  /react-native\s+run/i,
+  /npx\s+expo\s+start/i,
+  /npx\s+react-native\s+start/i,
+  /Launching\s+lib\/main\.dart/i,
+  /Running\s+Xcode\s+build/i,
+  /Installing.*\.app/i,
+  /BUILD\s+SUCCEEDED/i,
+];
+
+// Sessions that already have screenshot capture running.
+const capturingSessions = new Set();
+
+function detectAndStartScreenshots(sessionId, text) {
+  if (!text || capturingSessions.has(sessionId)) return;
+
+  for (const pattern of NATIVE_APP_PATTERNS) {
+    if (pattern.test(text)) {
+      // Double-check that a simulator/emulator is actually running.
+      if (hasActiveSimulator()) {
+        capturingSessions.add(sessionId);
+        startCapturing(sessionId);
+        return;
+      }
+    }
+  }
+}
+
+// Matches localhost URLs from common dev server output.
+const LOCALHOST_PATTERNS = [
+  // Full URLs: http://localhost:3000, https://127.0.0.1:5173
+  /https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0):(\d+)/i,
+  // Server startup messages: "ready on http://localhost:3000"
+  /(?:ready on|listening on|server running at|started at|Local:)\s*https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0):(\d+)/i,
+  // Server startup with port only: "listening on :3000"
+  /(?:ready on|listening on|server running at|started at|Local:)\s*:?(\d{3,5})/i,
+  // Bare localhost:port references (catches Claude's text like "running on localhost:3000")
+  /(?:localhost|127\.0\.0\.1):(\d{3,5})/i,
+  // "port 3000" in context of dev server discussion
+  /(?:running|serving|available|dev server)\b.*?\bport\s+(\d{3,5})/i,
+];
+
+// Ports we've already tunneled for a session (avoid duplicates).
+const tunneledPorts = new Map(); // sessionId → Set<port>
+
+async function detectAndTunnelDevServer(sessionId, text) {
+  if (!text) return;
+
+  for (const pattern of LOCALHOST_PATTERNS) {
+    const match = text.match(pattern);
+    if (match) {
+      const port = parseInt(match[1], 10);
+      if (port < 1024 || port > 65535) continue;
+
+      // Skip if we already tunneled this port for this session.
+      const ported = tunneledPorts.get(sessionId) || new Set();
+      if (ported.has(port)) return;
+      ported.add(port);
+      tunneledPorts.set(sessionId, ported);
+
+      log.info(`Dev server detected on port ${port} — creating tunnel...`);
+
+      const tunnelUrl = await startTunnel(sessionId, port);
+      if (tunnelUrl) {
+        // Store tunnel URL in Firestore session doc.
+        const db = getDb();
+        await db.collection("sessions").doc(sessionId).update({
+          devServerUrl: tunnelUrl,
+          devServerPort: port,
+        });
+
+        // Notify in messages.
+        await db
+          .collection("sessions")
+          .doc(sessionId)
+          .collection("messages")
+          .add({
+            type: "system",
+            content: `Live preview available — dev server on port ${port} tunneled to ${tunnelUrl}`,
+            timestamp: FieldValue.serverTimestamp(),
+          });
+
+        log.success(
+          `[${sessionId.slice(0, 8)}] Preview: localhost:${port} → ${tunnelUrl}`,
+        );
+      }
+      return; // Only tunnel the first detected port.
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Graceful shutdown — mark all active sessions as completed
+// ---------------------------------------------------------------------------
+
+export async function shutdownAllSessions() {
+  const db = getDb();
+  const sessionIds = [...activeSessions.keys()].filter(
+    (k) => !k.startsWith("cmd-watcher-"),
+  );
+
+  if (sessionIds.length === 0) return;
+
+  log.info(`Shutting down ${sessionIds.length} active session(s)...`);
+
+  for (const sessionId of sessionIds) {
+    const session = activeSessions.get(sessionId);
+    if (!session) continue;
+
+    // Kill running process.
+    if (session.process) {
+      session.process.kill("SIGTERM");
+    }
+
+    // Cancel permission watcher.
+    if (session.permissionWatcher) {
+      session.permissionWatcher();
+      session.permissionWatcher = null;
+    }
+
+    const duration = Math.round((Date.now() - session.startTime) / 1000);
+
+    try {
+      await db.collection("sessions").doc(sessionId).update({
+        status: "completed",
+        lastActivity: FieldValue.serverTimestamp(),
+        durationSeconds: duration,
+      });
+
+      await db
+        .collection("sessions")
+        .doc(sessionId)
+        .collection("messages")
+        .add({
+          type: "system",
+          content: "Session ended — relay was shut down.",
+          timestamp: FieldValue.serverTimestamp(),
+        });
+
+      log.session(sessionId, "Marked completed (relay shutdown)");
+    } catch (e) {
+      log.error(
+        `Failed to clean up session ${sessionId.slice(0, 8)}: ${e.message}`,
+      );
+    }
+
+    activeSessions.delete(sessionId);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Startup cleanup — mark orphaned sessions from previous runs as interrupted
+// ---------------------------------------------------------------------------
+
+/**
+ * On startup, check Firestore for sessions that were active for this desktop
+ * but no longer have a running Claude process (because the relay restarted).
+ * Mark them as `interrupted` so the mobile app shows the correct status.
+ */
+export async function cleanupOrphanedSessions(desktopId) {
+  const db = getDb();
+
+  // Query for sessions that were active, idle, or waiting_permission.
+  const activeStatuses = ["active", "idle", "waiting_permission"];
+  const snapshot = await db
+    .collection("sessions")
+    .where("desktopId", "==", desktopId)
+    .where("status", "in", activeStatuses)
+    .get();
+
+  if (snapshot.empty) {
+    log.info("No orphaned sessions found from previous runs");
+    return;
+  }
+
+  log.info(
+    `Found ${snapshot.size} orphaned session(s) from a previous run — marking as interrupted`,
+  );
+
+  for (const doc of snapshot.docs) {
+    const sessionId = doc.id;
+    const data = doc.data();
+
+    try {
+      await db.collection("sessions").doc(sessionId).update({
+        status: "interrupted",
+        lastActivity: FieldValue.serverTimestamp(),
+        interruptedAt: FieldValue.serverTimestamp(),
+        interruptReason: "relay_restart",
+      });
+
+      await db
+        .collection("sessions")
+        .doc(sessionId)
+        .collection("messages")
+        .add({
+          type: "system",
+          content:
+            "Session interrupted — the relay was restarted. " +
+            "This session cannot be resumed because the Claude process is gone. " +
+            "Start a new session to continue working.",
+          timestamp: FieldValue.serverTimestamp(),
+        });
+
+      log.session(
+        sessionId,
+        `Marked as interrupted (was ${data.status}, project: ${data.projectName || data.projectPath || "unknown"})`,
+      );
+    } catch (e) {
+      log.error(
+        `Failed to clean up orphaned session ${sessionId.slice(0, 8)}: ${e.message}`,
+      );
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Permission handling
+// ---------------------------------------------------------------------------
+
+/**
+ * Build human-readable text for the permission modal.
+ */
+function buildPermissionDisplayText(toolName, input) {
+  const inp = typeof input === "object" ? input || {} : {};
+  switch (toolName) {
+    case "Bash":
+      return inp.command || JSON.stringify(inp);
+    case "Write":
+    case "Edit":
+    case "MultiEdit":
+      return `${inp.file_path || inp.path || "unknown file"}`;
+    case "Read":
+      return inp.file_path || inp.path || JSON.stringify(inp);
+    default:
+      return typeof input === "string" ? input : JSON.stringify(inp, null, 2);
+  }
+}
+
+/**
+ * Create a permission request doc in Firestore.
+ * Returns the doc ID so we can watch it for decisions.
+ */
+async function createPermissionRequest(sessionId, toolCall) {
+  const db = getDb();
+  const displayText = buildPermissionDisplayText(toolCall.name, toolCall.input);
+  const toolInput =
+    typeof toolCall.input === "object" ? toolCall.input || {} : {};
+
+  const timeoutAt = new Date(Date.now() + 5 * 60 * 1000); // 5 minute timeout
+
+  const docRef = await db
+    .collection("sessions")
+    .doc(sessionId)
+    .collection("permissions")
+    .add({
+      toolName: toolCall.name,
+      toolInput,
+      displayText,
+      status: "pending",
+      requestedAt: FieldValue.serverTimestamp(),
+      timeoutAt,
+    });
+
+  // System message to show in the chat.
+  await db
+    .collection("sessions")
+    .doc(sessionId)
+    .collection("messages")
+    .add({
+      type: "system",
+      content: `Permission required — Claude wants to use ${toolCall.name}: ${displayText.slice(0, 200)}`,
+      timestamp: FieldValue.serverTimestamp(),
+    });
+
+  log.info(
+    `[${sessionId.slice(0, 8)}] Permission request created: ${toolCall.name} — ${displayText.slice(0, 80)}`,
+  );
+
+  return docRef.id;
+}
+
+/**
+ * Watch a permission doc for the user's decision.
+ */
+function watchPermissionDecision(sessionId, permDocId) {
+  const db = getDb();
+  const session = activeSessions.get(sessionId);
+  if (!session) return;
+
+  const docRef = db
+    .collection("sessions")
+    .doc(sessionId)
+    .collection("permissions")
+    .doc(permDocId);
+
+  const unsubscribe = docRef.onSnapshot(async (doc) => {
+    if (!doc.exists) return;
+    const data = doc.data();
+
+    if (data.status === "approved" || data.status === "always_allow") {
+      unsubscribe();
+      if (session.permissionWatcher === unsubscribe) {
+        session.permissionWatcher = null;
+      }
+      await handlePermissionApproved(sessionId, data);
+    } else if (data.status === "denied") {
+      unsubscribe();
+      if (session.permissionWatcher === unsubscribe) {
+        session.permissionWatcher = null;
+      }
+      await handlePermissionDenied(sessionId);
+    }
+  });
+
+  // Store unsubscribe for cleanup.
+  session.permissionWatcher = unsubscribe;
+
+  // Auto-deny after 5 minutes.
+  setTimeout(
+    async () => {
+      const sess = activeSessions.get(sessionId);
+      if (sess?.permissionNeeded) {
+        log.warn(
+          `[${sessionId.slice(0, 8)}] Permission timed out — auto-denying`,
+        );
+        // Update Firestore doc to denied.
+        try {
+          await docRef.update({
+            status: "denied",
+            decidedAt: FieldValue.serverTimestamp(),
+            decidedBy: "timeout",
+          });
+        } catch {
+          // Doc may already be updated.
+        }
+      }
+    },
+    5 * 60 * 1000,
+  );
+}
+
+/**
+ * Handle permission approval.
+ *
+ * When a user approves a tool call, we send a follow-up prompt to Claude
+ * asking it to proceed with the approved tool.  We do NOT execute commands
+ * directly on the relay — Claude's own CLI handles tool execution.
+ *
+ * This ensures all tool calls flow through Claude's safety and context
+ * tracking, and avoids duplicating execution logic or bypassing the CLI's
+ * permission system.
+ */
+async function handlePermissionApproved(sessionId, permData) {
+  const session = activeSessions.get(sessionId);
+  if (!session) return;
+
+  const toolCall = session.lastToolCall;
+  session.permissionNeeded = false;
+
+  log.success(
+    `[${sessionId.slice(0, 8)}] Permission approved for ${permData.toolName}`,
+  );
+
+  const db = getDb();
+
+  // Build a descriptive summary for the approval message.
+  const toolInput =
+    typeof toolCall.input === "object" ? toolCall.input || {} : toolCall.input;
+  const inputSummary =
+    toolCall.name === "Bash"
+      ? (typeof toolInput === "object" ? toolInput.command : toolInput) || ""
+      : typeof toolInput === "string"
+        ? toolInput
+        : JSON.stringify(toolInput).slice(0, 200);
+
+  await db
+    .collection("sessions")
+    .doc(sessionId)
+    .collection("messages")
+    .add({
+      type: "system",
+      content: `Permission approved — asking Claude to retry ${toolCall.name}${inputSummary ? `: ${inputSummary.slice(0, 120)}` : ""}.`,
+      timestamp: FieldValue.serverTimestamp(),
+    });
+
+  // Send a follow-up prompt to Claude so it re-executes the tool itself.
+  const prompt =
+    `The user has approved the ${toolCall.name} tool call` +
+    (inputSummary ? ` (${inputSummary.slice(0, 200)})` : "") +
+    `. Please go ahead and execute it now, then continue with the original task.`;
+
+  await runClaudeProcess(sessionId, prompt);
+}
+
+/**
+ * Handle permission denial — mark session idle.
+ */
+async function handlePermissionDenied(sessionId) {
+  const session = activeSessions.get(sessionId);
+  if (!session) return;
+
+  session.permissionNeeded = false;
+  session.lastToolCall = null;
+
+  log.info(`[${sessionId.slice(0, 8)}] Permission denied`);
+
+  const db = getDb();
+  await db.collection("sessions").doc(sessionId).update({
+    status: "idle",
+    lastActivity: FieldValue.serverTimestamp(),
+  });
+
+  await db.collection("sessions").doc(sessionId).collection("messages").add({
+    type: "system",
+    content:
+      "Permission denied — command was not executed. Send another message or end the session.",
+    timestamp: FieldValue.serverTimestamp(),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function formatDuration(seconds) {
+  if (seconds < 60) return `${seconds}s`;
+  const mins = Math.floor(seconds / 60);
+  const secs = seconds % 60;
+  if (mins < 60) return `${mins}m ${secs}s`;
+  const hours = Math.floor(mins / 60);
+  const remainMins = mins % 60;
+  return `${hours}h ${remainMins}m`;
+}