@electric-agent/studio 1.0.0 → 1.1.1

package/dist/server.js

@@ -8,6 +8,10 @@ import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
+import { ActiveSessions } from "./active-sessions.js";
+import { ClaudeCodeDockerBridge } from "./bridge/claude-code-docker.js";
+import { ClaudeCodeSpritesBridge, } from "./bridge/claude-code-sprites.js";
+import { generateClaudeMd } from "./bridge/claude-md-generator.js";
 import { DaytonaSessionBridge } from "./bridge/daytona.js";
 import { DockerStdioBridge } from "./bridge/docker-stdio.js";
 import { HostedStreamBridge } from "./bridge/hosted.js";
@@ -16,10 +20,12 @@ import { DEFAULT_ELECTRIC_URL, getClaimUrl, provisionElectricResources } from ".
 import { createGate, rejectAllGates, resolveGate } from "./gate.js";
 import { ghListAccounts, ghListBranches, ghListRepos, isGhAuthenticated } from "./git.js";
 import { resolveProjectDir } from "./project-utils.js";
-import { addSession, cleanupStaleSessions, deleteSession, getSession, readSessionIndex, updateSessionInfo, } from "./sessions.js";
-import { getStreamConnectionInfo, getStreamEnvVars, } from "./streams.js";
+import { generateInviteCode } from "./shared-sessions.js";
+import { getSharedStreamConnectionInfo, getStreamConnectionInfo, getStreamEnvVars, } from "./streams.js";
 /** Active session bridges — one per running session */
 const bridges = new Map();
+/** Inflight hook session creations — prevents duplicate sessions from concurrent hooks */
+const inflightHookCreations = new Map();
 function parseRepoNameFromUrl(url) {
     if (!url)
         return null;
@@ -30,6 +36,10 @@ function parseRepoNameFromUrl(url) {
 function sessionStream(config, sessionId) {
     return getStreamConnectionInfo(sessionId, config.streamConfig);
 }
+/** Get stream connection info for a shared session */
+function sharedSessionStream(config, sharedSessionId) {
+    return getSharedStreamConnectionInfo(sharedSessionId, config.streamConfig);
+}
 /** Create or retrieve the SessionBridge for a session */
 function getOrCreateBridge(config, sessionId) {
     let bridge = bridges.get(sessionId);
@@ -76,6 +86,34 @@ function createStdioBridge(config, sessionId) {
     bridges.set(sessionId, bridge);
     return bridge;
 }
+/**
+ * Create a Claude Code bridge for a session.
+ * Spawns `claude` CLI with stream-json I/O inside the sandbox.
+ */
+function createClaudeCodeBridge(config, sessionId, claudeConfig) {
+    const conn = sessionStream(config, sessionId);
+    let bridge;
+    if (config.sandbox.runtime === "sprites") {
+        const spritesProvider = config.sandbox;
+        const sprite = spritesProvider.getSpriteObject(sessionId);
+        if (!sprite) {
+            throw new Error(`No Sprites sandbox object for session ${sessionId}`);
+        }
+        bridge = new ClaudeCodeSpritesBridge(sessionId, conn, sprite, claudeConfig);
+    }
+    else {
+        // Docker (default for claude-code mode)
+        const dockerProvider = config.sandbox;
+        const containerId = dockerProvider.getContainerId(sessionId);
+        if (!containerId) {
+            throw new Error(`No Docker container found for session ${sessionId}`);
+        }
+        bridge = new ClaudeCodeDockerBridge(sessionId, conn, containerId, claudeConfig);
+    }
+    closeBridge(sessionId);
+    bridges.set(sessionId, bridge);
+    return bridge;
+}
 /** Close and remove a bridge */
 function closeBridge(sessionId) {
     const bridge = bridges.get(sessionId);
@@ -245,15 +283,9 @@ export function createApp(config) {
             return c.json({ error: message }, 500);
         }
     });
-    // List all sessions (lazily clean up stale ones)
-    app.get("/api/sessions", (c) => {
-        cleanupStaleSessions(config.dataDir);
-        const index = readSessionIndex(config.dataDir);
-        return c.json(index);
-    });
-    // Get single session
+    // Get single session (from in-memory active sessions)
     app.get("/api/sessions/:id", (c) => {
-        const session = getSession(config.dataDir, c.req.param("id"));
+        const session = config.sessions.get(c.req.param("id"));
         if (!session)
             return c.json({ error: "Session not found" }, 404);
         return c.json(session);
@@ -288,7 +320,7 @@ export function createApp(config) {
             lastActiveAt: new Date().toISOString(),
             status: "running",
         };
-        addSession(config.dataDir, session);
+        config.sessions.add(session);
         // Pre-create a bridge so hook-event can emit to it immediately
         getOrCreateBridge(config, sessionId);
         console.log(`[local-session] Created session: ${sessionId}`);
@@ -330,7 +362,7 @@ export function createApp(config) {
             status: "running",
             claudeSessionId: claudeSessionId || undefined,
         };
-        addSession(config.dataDir, session);
+        config.sessions.add(session);
         // Create bridge and emit the SessionStart event
         const bridge = getOrCreateBridge(config, sessionId);
         const hookEvent = mapHookToEngineEvent(body);
@@ -360,10 +392,10 @@ export function createApp(config) {
             return c.json({ error: "Failed to write event" }, 500);
         }
         // Bump lastActiveAt on every hook event
-        updateSessionInfo(config.dataDir, sessionId, {});
+        config.sessions.update(sessionId, {});
         // SessionEnd: mark session complete and close the bridge
         if (hookEvent.type === "session_end") {
-            updateSessionInfo(config.dataDir, sessionId, { status: "complete" });
+            config.sessions.update(sessionId, { status: "complete" });
             closeBridge(sessionId);
             return c.json({ ok: true });
         }
@@ -396,12 +428,229 @@ export function createApp(config) {
         }
         return c.json({ ok: true });
     });
+    // --- Unified Hook Endpoint (transcript_path correlation) ---
+    // Single endpoint for all Claude Code hook events. Uses transcript_path
+    // from the hook JSON as the correlation key — stable across resume/compact,
+    // changes on /clear. Replaces the need for client-side session tracking.
+    app.post("/api/hook", async (c) => {
+        const body = (await c.req.json());
+        const transcriptPath = body.transcript_path;
+        // Look up or create session via transcript_path
+        let sessionId;
+        if (transcriptPath) {
+            sessionId = config.sessions.getByTranscript(transcriptPath);
+        }
+        if (!sessionId) {
+            // Check inflight creation to prevent duplicate sessions from concurrent hooks
+            if (transcriptPath && inflightHookCreations.has(transcriptPath)) {
+                // Another request is already creating a session for this transcript — wait for it
+                sessionId = await inflightHookCreations.get(transcriptPath);
+            }
+        }
+        if (!sessionId) {
+            // Create a new session (with inflight guard)
+            const createPromise = (async () => {
+                const newId = crypto.randomUUID();
+                // Create the durable stream
+                const conn = sessionStream(config, newId);
+                try {
+                    await DurableStream.create({
+                        url: conn.url,
+                        headers: conn.headers,
+                        contentType: "application/json",
+                    });
+                }
+                catch (err) {
+                    console.error(`[hook] Failed to create durable stream:`, err);
+                    throw err;
+                }
+                // Derive project name from cwd
+                const cwd = body.cwd;
+                const projectName = cwd ? path.basename(cwd) : "local-session";
+                const session = {
+                    id: newId,
+                    projectName,
+                    sandboxProjectDir: cwd || "",
+                    description: `Local session: ${projectName}`,
+                    createdAt: new Date().toISOString(),
+                    lastActiveAt: new Date().toISOString(),
+                    status: "running",
+                };
+                config.sessions.add(session);
+                // Durably map transcript_path → session
+                if (transcriptPath) {
+                    config.sessions.mapTranscript(transcriptPath, newId);
+                }
+                console.log(`[hook] Created session: ${newId} (project: ${session.projectName}, transcript: ${transcriptPath ?? "none"})`);
+                return newId;
+            })();
+            if (transcriptPath) {
+                inflightHookCreations.set(transcriptPath, createPromise);
+            }
+            try {
+                sessionId = await createPromise;
+            }
+            catch {
+                return c.json({ error: "Failed to create event stream" }, 500);
+            }
+            finally {
+                if (transcriptPath) {
+                    inflightHookCreations.delete(transcriptPath);
+                }
+            }
+        }
+        // Ensure bridge exists
+        const bridge = getOrCreateBridge(config, sessionId);
+        // On SessionStart (resume/compact), re-activate the session
+        const hookName = body.hook_event_name;
+        if (hookName === "SessionStart") {
+            const session = config.sessions.get(sessionId);
+            if (session && session.status !== "running") {
+                config.sessions.update(sessionId, { status: "running" });
+            }
+        }
+        // Map hook JSON → EngineEvent
+        const hookEvent = mapHookToEngineEvent(body);
+        if (!hookEvent) {
+            return c.json({ ok: true, sessionId });
+        }
+        try {
+            await bridge.emit(hookEvent);
+        }
+        catch (err) {
+            console.error(`[hook] Failed to emit:`, err);
+            return c.json({ error: "Failed to write event" }, 500);
+        }
+        // Bump lastActiveAt
+        config.sessions.update(sessionId, {});
+        // SessionEnd: mark complete and close bridge (keep mapping for potential re-open)
+        if (hookEvent.type === "session_end") {
+            config.sessions.update(sessionId, { status: "complete" });
+            closeBridge(sessionId);
+            return c.json({ ok: true, sessionId });
+        }
+        // AskUserQuestion: block until the user answers via the web UI
+        if (hookEvent.type === "ask_user_question") {
+            const toolUseId = hookEvent.tool_use_id;
+            console.log(`[hook] Blocking for ask_user_question gate: ${toolUseId}`);
+            try {
+                const gateTimeout = 5 * 60 * 1000;
+                const answer = await Promise.race([
+                    createGate(sessionId, `ask_user_question:${toolUseId}`),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("AskUserQuestion gate timed out")), gateTimeout)),
+                ]);
+                console.log(`[hook] ask_user_question gate resolved: ${toolUseId}`);
+                return c.json({
+                    sessionId,
+                    hookSpecificOutput: {
+                        hookEventName: "PreToolUse",
+                        permissionDecision: "allow",
+                        updatedInput: {
+                            questions: body.tool_input?.questions,
+                            answers: { [hookEvent.question]: answer.answer },
+                        },
+                    },
+                });
+            }
+            catch (err) {
+                console.error(`[hook] ask_user_question gate error:`, err);
+                return c.json({ ok: true, sessionId });
+            }
+        }
+        return c.json({ ok: true, sessionId });
+    });
+    // --- Hook Setup Installer ---
+    // Returns a shell script that installs forward.sh and configures Claude Code hooks
+    // in the current project directory (.claude/hooks/ and .claude/settings.local.json).
+    // Usage: cd <project> && curl -s http://localhost:4400/api/hooks/setup | bash
+    app.get("/api/hooks/setup", (c) => {
+        const port = config.port;
+        const script = `#!/bin/bash
+# Electric Agent — Claude Code hook installer (project-scoped)
+# Installs the hook forwarder into the current project's .claude/ directory.
+
+set -e
+
+HOOKS_DIR=".claude/hooks"
+SETTINGS_FILE=".claude/settings.local.json"
+FORWARD_SH="\${HOOKS_DIR}/forward.sh"
+EA_PORT="${port}"
+
+mkdir -p "\${HOOKS_DIR}"
+
+# Write the forwarder script
+cat > "\${FORWARD_SH}" << 'HOOKEOF'
+#!/bin/bash
+# Forward Claude Code hook events to Electric Agent studio.
+# Installed by: curl -s http://localhost:EA_PORT/api/hooks/setup | bash
+
+EA_PORT="\${EA_PORT:-EA_PORT_PLACEHOLDER}"
+BODY="$(cat)"
+
+RESPONSE=$(curl -s -X POST "http://localhost:\${EA_PORT}/api/hook" \\
+  -H "Content-Type: application/json" \\
+  -d "\${BODY}" \\
+  --max-time 360 \\
+  --connect-timeout 2 \\
+  2>/dev/null)
+
+# If the response contains hookSpecificOutput, print it so Claude Code reads it
+if echo "\${RESPONSE}" | grep -q '"hookSpecificOutput"'; then
+  echo "\${RESPONSE}"
+fi
+
+exit 0
+HOOKEOF
+
+# Replace placeholder with actual port
+sed -i.bak "s/EA_PORT_PLACEHOLDER/${port}/" "\${FORWARD_SH}" && rm -f "\${FORWARD_SH}.bak"
+chmod +x "\${FORWARD_SH}"
+
+# Merge hook config into project-level settings.local.json
+HOOK_ENTRY="\${FORWARD_SH}"
+
+if command -v node > /dev/null 2>&1; then
+  node -e "
+const fs = require('fs');
+const file = process.argv[1];
+const hook = process.argv[2];
+let settings = {};
+try { settings = JSON.parse(fs.readFileSync(file, 'utf-8')); } catch {}
+if (!settings.hooks) settings.hooks = {};
+const events = ['PreToolUse','PostToolUse','PostToolUseFailure','Stop','SessionStart','SessionEnd','UserPromptSubmit','SubagentStart','SubagentStop'];
+for (const ev of events) {
+  if (!settings.hooks[ev]) settings.hooks[ev] = [];
+  const arr = settings.hooks[ev];
+  if (!arr.some(h => h.command === hook)) {
+    arr.push({ type: 'command', command: hook });
+  }
+}
+fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\\\\n');
+" "\${SETTINGS_FILE}" "\${HOOK_ENTRY}"
+else
+  echo "Warning: node not found. Please add the hook manually to \${SETTINGS_FILE}"
+  echo "See: https://docs.anthropic.com/en/docs/claude-code/hooks"
+  exit 1
+fi
+
+echo ""
+echo "Electric Agent hooks installed in project: $(pwd)"
+echo "  Forwarder: $(pwd)/\${FORWARD_SH}"
+echo "  Settings:  $(pwd)/\${SETTINGS_FILE}"
+echo "  Server:    http://localhost:\${EA_PORT}"
+echo ""
+echo "Start claude in this project — the session will appear in the studio UI."
+`;
+        return c.text(script, 200, { "Content-Type": "text/plain" });
+    });
     // Start new project
     app.post("/api/sessions", async (c) => {
         const body = (await c.req.json());
         if (!body.description) {
             return c.json({ error: "description is required" }, 400);
         }
+        // Per-session bridge mode: "claude-code" if explicitly requested, else server default
+        const sessionBridgeMode = body.agentMode === "claude-code" ? "claude-code" : config.bridgeMode;
         const sessionId = crypto.randomUUID();
         const inferredName = body.name ||
             (config.inferProjectName
@@ -440,8 +689,9 @@ export function createApp(config) {
             createdAt: new Date().toISOString(),
             lastActiveAt: new Date().toISOString(),
             status: "running",
+            agentMode: sessionBridgeMode === "claude-code" ? "claude-code" : "electric-agent",
         };
-        addSession(config.dataDir, session);
+        config.sessions.add(session);
         // Write user prompt to the stream so it shows in the UI
         await bridge.emit({ type: "user_prompt", message: body.description, ts: ts() });
         // Gather GitHub accounts for the merged setup gate
@@ -495,7 +745,7 @@ export function createApp(config) {
                         repoName: gateValue.repoName,
                         visibility: gateValue.repoVisibility ?? "private",
                     };
-                    updateSessionInfo(config.dataDir, sessionId, {
+                    config.sessions.update(sessionId, {
                         git: {
                             branch: "main",
                             remoteUrl: null,
@@ -519,14 +769,16 @@ export function createApp(config) {
                 message: `Creating ${config.sandbox.runtime} sandbox...`,
                 ts: ts(),
             });
-            // Only pass stream env vars when using hosted stream bridge (not stdio)
-            const streamEnv = config.bridgeMode === "stdio" ? undefined : getStreamEnvVars(sessionId, config.streamConfig);
-            console.log(`[session:${sessionId}] Creating sandbox: runtime=${config.sandbox.runtime} project=${projectName} bridgeMode=${config.bridgeMode}`);
+            // Only pass stream env vars when using hosted stream bridge (not stdio or claude-code)
+            const streamEnv = sessionBridgeMode === "stdio" || sessionBridgeMode === "claude-code"
+                ? undefined
+                : getStreamEnvVars(sessionId, config.streamConfig);
+            console.log(`[session:${sessionId}] Creating sandbox: runtime=${config.sandbox.runtime} project=${projectName} bridgeMode=${sessionBridgeMode}`);
             const handle = await config.sandbox.create(sessionId, {
                 projectName,
                 infra,
                 streamEnv,
-                deferAgentStart: config.bridgeMode === "stdio",
+                deferAgentStart: sessionBridgeMode === "stdio" || sessionBridgeMode === "claude-code",
                 apiKey: body.apiKey,
                 oauthToken: body.oauthToken,
                 ghToken: body.ghToken,
@@ -538,16 +790,75 @@ export function createApp(config) {
                 message: `Sandbox ready (${config.sandbox.runtime})`,
                 ts: ts(),
             });
-            updateSessionInfo(config.dataDir, sessionId, {
+            config.sessions.update(sessionId, {
                 appPort: handle.port,
                 sandboxProjectDir: handle.projectDir,
                 previewUrl: handle.previewUrl,
                 ...(claimId ? { claimId } : {}),
             });
             // 3. If stdio bridge mode, create the stdio bridge now that the sandbox exists.
+            // If claude-code mode, write CLAUDE.md and create a ClaudeCode bridge.
+            // If stdio mode, create the stdio bridge now that the sandbox exists.
             // If stream bridge mode with Sprites, launch the agent process in the sprite
             // (it connects directly to the hosted Durable Stream via DS_URL env vars).
-            if (config.bridgeMode === "stdio") {
+            if (sessionBridgeMode === "claude-code") {
+                console.log(`[session:${sessionId}] Setting up Claude Code bridge...`);
+                // Copy pre-scaffolded project from the image and customize per-session
+                await bridge.emit({
+                    type: "log",
+                    level: "build",
+                    message: "Setting up project...",
+                    ts: ts(),
+                });
+                try {
+                    if (config.sandbox.runtime === "docker") {
+                        // Docker: copy the pre-built scaffold base (baked into the image)
+                        await config.sandbox.exec(handle, `cp -r /opt/scaffold-base '${handle.projectDir}'`);
+                        await config.sandbox.exec(handle, `cd '${handle.projectDir}' && sed -i 's/"name": "scaffold-base"/"name": "${projectName}"/' package.json`);
+                    }
+                    else {
+                        // Sprites/Daytona: run scaffold from globally installed electric-agent
+                        await config.sandbox.exec(handle, `source /etc/profile.d/npm-global.sh 2>/dev/null; electric-agent scaffold '${handle.projectDir}' --name '${projectName}' --skip-git`);
+                    }
+                    // Ensure _agent/ working memory directory exists
+                    await config.sandbox.exec(handle, `mkdir -p '${handle.projectDir}/_agent' && echo '# Error Log\n' > '${handle.projectDir}/_agent/errors.md' && echo '# Session State\n' > '${handle.projectDir}/_agent/session.md'`);
+                    console.log(`[session:${sessionId}] Project setup complete`);
+                    await bridge.emit({
+                        type: "log",
+                        level: "done",
+                        message: "Project ready",
+                        ts: ts(),
+                    });
+                }
+                catch (err) {
+                    console.error(`[session:${sessionId}] Project setup failed:`, err);
+                    await bridge.emit({
+                        type: "log",
+                        level: "error",
+                        message: `Project setup failed: ${err instanceof Error ? err.message : "unknown"}`,
+                        ts: ts(),
+                    });
+                }
+                // Write CLAUDE.md to the sandbox workspace
+                const claudeMd = generateClaudeMd({
+                    description: body.description,
+                    projectName,
+                    projectDir: handle.projectDir,
+                    runtime: config.sandbox.runtime,
+                });
+                try {
+                    await config.sandbox.exec(handle, `cat > '${handle.projectDir}/CLAUDE.md' << 'CLAUDEMD_EOF'\n${claudeMd}\nCLAUDEMD_EOF`);
+                }
+                catch (err) {
+                    console.error(`[session:${sessionId}] Failed to write CLAUDE.md:`, err);
+                }
+                const claudeConfig = {
+                    prompt: body.description,
+                    cwd: handle.projectDir,
+                };
+                bridge = createClaudeCodeBridge(config, sessionId, claudeConfig);
+            }
+            else if (sessionBridgeMode === "stdio") {
                 console.log(`[session:${sessionId}] Creating stdio bridge...`);
                 bridge = createStdioBridge(config, sessionId);
             }
@@ -592,6 +903,15 @@ export function createApp(config) {
                 });
             }
             // 5. Start listening for agent events via the bridge
+            // Track Claude Code session ID for --resume on iterate
+            bridge.onAgentEvent((event) => {
+                if (event.type === "session_start" && "session_id" in event) {
+                    const ccSessionId = event.session_id;
+                    if (ccSessionId) {
+                        config.sessions.update(sessionId, { lastCoderSessionId: ccSessionId });
+                    }
+                }
+            });
             bridge.onComplete(async (success) => {
                 const updates = {
                     status: success ? "complete" : "error",
@@ -599,7 +919,7 @@ export function createApp(config) {
                 try {
                     const gs = await config.sandbox.gitStatus(handle, handle.projectDir);
                     if (gs.initialized) {
-                        const existing = getSession(config.dataDir, sessionId);
+                        const existing = config.sessions.get(sessionId);
                         updates.git = {
                             branch: gs.branch ?? "main",
                             remoteUrl: existing?.git?.remoteUrl ?? null,
@@ -614,7 +934,24 @@ export function createApp(config) {
                 catch {
                     // Container may already be stopped
                 }
-                updateSessionInfo(config.dataDir, sessionId, updates);
+                config.sessions.update(sessionId, updates);
+                // For Claude Code mode: check if the app is running after completion
+                // and emit app_ready so the UI shows the preview link
+                if (sessionBridgeMode === "claude-code" && success) {
+                    try {
+                        const appRunning = await config.sandbox.isAppRunning(handle);
+                        if (appRunning) {
+                            await bridge.emit({
+                                type: "app_ready",
+                                port: handle.port ?? session.appPort,
+                                ts: ts(),
+                            });
+                        }
+                    }
+                    catch {
+                        // Container may already be stopped
+                    }
+                }
             });
             console.log(`[session:${sessionId}] Starting bridge listener...`);
             await bridge.start();
@@ -633,16 +970,16 @@ export function createApp(config) {
             await bridge.sendCommand(newCmd);
             console.log(`[session:${sessionId}] Command sent, waiting for agent...`);
         };
-        asyncFlow().catch((err) => {
+        asyncFlow().catch(async (err) => {
             console.error(`[session:${sessionId}] Session creation flow failed:`, err);
-            updateSessionInfo(config.dataDir, sessionId, { status: "error" });
+            config.sessions.update(sessionId, { status: "error" });
         });
-        return c.json({ sessionId }, 201);
+        return c.json({ sessionId, session }, 201);
     });
     // Send iteration request
     app.post("/api/sessions/:id/iterate", async (c) => {
         const sessionId = c.req.param("id");
-        const session = getSession(config.dataDir, sessionId);
+        const session = config.sessions.get(sessionId);
         if (!session)
             return c.json({ error: "Session not found" }, 404);
         const body = (await c.req.json());
@@ -699,11 +1036,20 @@ export function createApp(config) {
             if (!handle || !config.sandbox.isAlive(handle)) {
                 return c.json({ error: "Container is not running" }, 400);
             }
-            await bridge.sendCommand({
-                command: "git",
-                projectDir: session.sandboxProjectDir || handle.projectDir,
-                ...gitOp,
-            });
+            if (session.agentMode === "claude-code") {
+                // In Claude Code mode, send git requests as user messages
+                await bridge.sendCommand({
+                    command: "iterate",
+                    request: body.request,
+                });
+            }
+            else {
+                await bridge.sendCommand({
+                    command: "git",
+                    projectDir: session.sandboxProjectDir || handle.projectDir,
+                    ...gitOp,
+                });
+            }
             return c.json({ ok: true });
         }
         const handle = config.sandbox.get(sessionId);
@@ -713,7 +1059,7 @@ export function createApp(config) {
         // Write user prompt to the stream
         const bridge = getOrCreateBridge(config, sessionId);
         await bridge.emit({ type: "user_prompt", message: body.request, ts: ts() });
-        updateSessionInfo(config.dataDir, sessionId, { status: "running" });
+        config.sessions.update(sessionId, { status: "running" });
         await bridge.sendCommand({
             command: "iterate",
             projectDir: session.sandboxProjectDir || handle.projectDir,
@@ -734,6 +1080,12 @@ export function createApp(config) {
         }
         // Client may pass a human-readable summary of the decision for replay display
         const summary = body._summary || undefined;
+        // Extract participant info from headers for gate attribution
+        const participantId = c.req.header("X-Participant-Id");
+        const participantName = c.req.header("X-Participant-Name");
+        const resolvedBy = participantId && participantName
+            ? { id: participantId, displayName: participantName }
+            : undefined;
         // AskUserQuestion gates: resolve the blocking hook-event and emit gate_resolved
         if (gate === "ask_user_question") {
             const toolUseId = body.toolUseId;
@@ -748,7 +1100,13 @@ export function createApp(config) {
             // Emit gate_resolved for replay
             try {
                 const bridge = getOrCreateBridge(config, sessionId);
-                await bridge.emit({ type: "gate_resolved", gate: "ask_user_question", summary, ts: ts() });
+                await bridge.emit({
+                    type: "gate_resolved",
+                    gate: "ask_user_question",
+                    summary,
+                    resolvedBy,
+                    ts: ts(),
+                });
             }
             catch {
                 // Non-critical
@@ -767,7 +1125,7 @@ export function createApp(config) {
             await bridge.sendGateResponse(gate, value);
             // Persist gate resolution for replay
             try {
-                await bridge.emit({ type: "gate_resolved", gate, summary, ts: ts() });
+                await bridge.emit({ type: "gate_resolved", gate, summary, resolvedBy, ts: ts() });
             }
             catch {
                 // Non-critical
@@ -836,7 +1194,7 @@ export function createApp(config) {
         // Persist gate resolution so replays mark the gate as resolved
         try {
             const bridge = getOrCreateBridge(config, sessionId);
-            await bridge.emit({ type: "gate_resolved", gate, summary, details, ts: ts() });
+            await bridge.emit({ type: "gate_resolved", gate, summary, details, resolvedBy, ts: ts() });
         }
         catch {
             // Non-critical
@@ -847,7 +1205,7 @@ export function createApp(config) {
     // Check app status
     app.get("/api/sessions/:id/app-status", async (c) => {
         const sessionId = c.req.param("id");
-        const session = getSession(config.dataDir, sessionId);
+        const session = config.sessions.get(sessionId);
         if (!session)
             return c.json({ error: "Session not found" }, 404);
         const handle = config.sandbox.get(sessionId);
@@ -864,7 +1222,7 @@ export function createApp(config) {
     // Start the generated app
     app.post("/api/sessions/:id/start-app", async (c) => {
         const sessionId = c.req.param("id");
-        const session = getSession(config.dataDir, sessionId);
+        const session = config.sessions.get(sessionId);
         if (!session)
             return c.json({ error: "Session not found" }, 404);
         const handle = config.sandbox.get(sessionId);
@@ -877,7 +1235,7 @@ export function createApp(config) {
     // Stop the generated app
     app.post("/api/sessions/:id/stop-app", async (c) => {
         const sessionId = c.req.param("id");
-        const session = getSession(config.dataDir, sessionId);
+        const session = config.sessions.get(sessionId);
         if (!session)
             return c.json({ error: "Session not found" }, 404);
         const handle = config.sandbox.get(sessionId);
@@ -894,7 +1252,7 @@ export function createApp(config) {
         if (handle)
             await config.sandbox.destroy(handle);
         rejectAllGates(sessionId);
-        updateSessionInfo(config.dataDir, sessionId, { status: "cancelled" });
+        config.sessions.update(sessionId, { status: "cancelled" });
         return c.json({ ok: true });
     });
     // Delete a session
@@ -905,7 +1263,7 @@ export function createApp(config) {
         if (handle)
             await config.sandbox.destroy(handle);
         rejectAllGates(sessionId);
-        const deleted = deleteSession(config.dataDir, sessionId);
+        const deleted = config.sessions.delete(sessionId);
         if (!deleted)
             return c.json({ error: "Session not found" }, 404);
         return c.json({ ok: true });
@@ -975,18 +1333,230 @@ export function createApp(config) {
         await config.sandbox.destroy(handle);
         return c.json({ ok: true });
     });
+    // --- Shared Sessions ---
+    // Create a shared session
+    app.post("/api/shared-sessions", async (c) => {
+        const body = (await c.req.json());
+        if (!body.name || !body.participant?.id || !body.participant?.displayName) {
+            return c.json({ error: "name and participant (id, displayName) are required" }, 400);
+        }
+        const id = crypto.randomUUID();
+        const code = generateInviteCode();
+        // Create the shared session durable stream
+        const conn = sharedSessionStream(config, id);
+        try {
+            await DurableStream.create({
+                url: conn.url,
+                headers: conn.headers,
+                contentType: "application/json",
+            });
+        }
+        catch (err) {
+            console.error(`[shared-session] Failed to create durable stream:`, err);
+            return c.json({ error: "Failed to create shared session stream" }, 500);
+        }
+        // Write shared_session_created event
+        const stream = new DurableStream({
+            url: conn.url,
+            headers: conn.headers,
+            contentType: "application/json",
+        });
+        const createdEvent = {
+            type: "shared_session_created",
+            name: body.name,
+            code,
+            createdBy: body.participant,
+            ts: ts(),
+        };
+        await stream.append(JSON.stringify(createdEvent));
+        // Write participant_joined for the creator
+        const joinedEvent = {
+            type: "participant_joined",
+            participant: body.participant,
+            ts: ts(),
+        };
+        await stream.append(JSON.stringify(joinedEvent));
+        // Save to room registry
+        await config.rooms.addRoom({
+            id,
+            code,
+            name: body.name,
+            createdAt: new Date().toISOString(),
+            revoked: false,
+        });
+        console.log(`[shared-session] Created: id=${id} code=${code}`);
+        return c.json({ id, code }, 201);
+    });
+    // Resolve invite code → shared session ID
+    app.get("/api/shared-sessions/join/:code", (c) => {
+        const code = c.req.param("code");
+        const entry = config.rooms.getRoomByCode(code);
+        if (!entry)
+            return c.json({ error: "Shared session not found" }, 404);
+        return c.json({ id: entry.id, code: entry.code, revoked: entry.revoked });
+    });
+    // Join a shared session as participant
+    app.post("/api/shared-sessions/:id/join", async (c) => {
+        const id = c.req.param("id");
+        const entry = config.rooms.getRoom(id);
+        if (!entry)
+            return c.json({ error: "Shared session not found" }, 404);
+        if (entry.revoked)
+            return c.json({ error: "Invite code has been revoked" }, 403);
+        const body = (await c.req.json());
+        if (!body.participant?.id || !body.participant?.displayName) {
+            return c.json({ error: "participant (id, displayName) is required" }, 400);
+        }
+        const conn = sharedSessionStream(config, id);
+        const stream = new DurableStream({
+            url: conn.url,
+            headers: conn.headers,
+            contentType: "application/json",
+        });
+        const event = {
+            type: "participant_joined",
+            participant: body.participant,
+            ts: ts(),
+        };
+        await stream.append(JSON.stringify(event));
+        return c.json({ ok: true });
+    });
+    // Leave a shared session
+    app.post("/api/shared-sessions/:id/leave", async (c) => {
+        const id = c.req.param("id");
+        const body = (await c.req.json());
+        if (!body.participantId) {
+            return c.json({ error: "participantId is required" }, 400);
+        }
+        const conn = sharedSessionStream(config, id);
+        const stream = new DurableStream({
+            url: conn.url,
+            headers: conn.headers,
+            contentType: "application/json",
+        });
+        const event = {
+            type: "participant_left",
+            participantId: body.participantId,
+            ts: ts(),
+        };
+        await stream.append(JSON.stringify(event));
+        return c.json({ ok: true });
+    });
+    // Link a session to a shared session (room)
+    // The client sends session metadata since sessions are private (localStorage).
+    app.post("/api/shared-sessions/:id/sessions", async (c) => {
+        const id = c.req.param("id");
+        const body = (await c.req.json());
+        if (!body.sessionId || !body.linkedBy) {
+            return c.json({ error: "sessionId and linkedBy are required" }, 400);
+        }
+        const conn = sharedSessionStream(config, id);
+        const stream = new DurableStream({
+            url: conn.url,
+            headers: conn.headers,
+            contentType: "application/json",
+        });
+        const event = {
+            type: "session_linked",
+            sessionId: body.sessionId,
+            sessionName: body.sessionName || "",
+            sessionDescription: body.sessionDescription || "",
+            linkedBy: body.linkedBy,
+            ts: ts(),
+        };
+        await stream.append(JSON.stringify(event));
+        return c.json({ ok: true });
+    });
+    // Unlink a session from a shared session
+    app.delete("/api/shared-sessions/:id/sessions/:sessionId", async (c) => {
+        const id = c.req.param("id");
+        const sessionId = c.req.param("sessionId");
+        const conn = sharedSessionStream(config, id);
+        const stream = new DurableStream({
+            url: conn.url,
+            headers: conn.headers,
+            contentType: "application/json",
+        });
+        const event = {
+            type: "session_unlinked",
+            sessionId,
+            ts: ts(),
+        };
+        await stream.append(JSON.stringify(event));
+        return c.json({ ok: true });
+    });
+    // SSE proxy for shared session events
+    app.get("/api/shared-sessions/:id/events", async (c) => {
+        const id = c.req.param("id");
+        const entry = config.rooms.getRoom(id);
+        if (!entry)
+            return c.json({ error: "Shared session not found" }, 404);
+        const connection = sharedSessionStream(config, id);
+        const lastEventId = c.req.header("Last-Event-ID") || "-1";
+        const reader = new DurableStream({
+            url: connection.url,
+            headers: connection.headers,
+            contentType: "application/json",
+        });
+        const { readable, writable } = new TransformStream();
+        const writer = writable.getWriter();
+        const encoder = new TextEncoder();
+        let cancelled = false;
+        const response = await reader.stream({
+            offset: lastEventId,
+            live: true,
+        });
+        const cancel = response.subscribeJson((batch) => {
+            if (cancelled)
+                return;
+            for (const item of batch.items) {
+                const data = JSON.stringify(item);
+                writer.write(encoder.encode(`id:${batch.offset}\ndata:${data}\n\n`)).catch(() => {
+                    cancelled = true;
+                });
+            }
+        });
+        c.req.raw.signal.addEventListener("abort", () => {
+            cancelled = true;
+            cancel();
+            writer.close().catch(() => { });
+        });
+        return new Response(readable, {
+            headers: {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+                "Access-Control-Allow-Origin": "*",
+            },
+        });
+    });
+    // Revoke a shared session's invite code
+    app.post("/api/shared-sessions/:id/revoke", async (c) => {
+        const id = c.req.param("id");
+        const revoked = await config.rooms.revokeRoom(id);
+        if (!revoked)
+            return c.json({ error: "Shared session not found" }, 404);
+        const conn = sharedSessionStream(config, id);
+        const stream = new DurableStream({
+            url: conn.url,
+            headers: conn.headers,
+            contentType: "application/json",
+        });
+        const event = {
+            type: "code_revoked",
+            ts: ts(),
+        };
+        await stream.append(JSON.stringify(event));
+        return c.json({ ok: true });
+    });
     // --- SSE Proxy ---
     // Server-side SSE proxy: reads from the hosted durable stream and proxies
     // events to the React client. The client never sees DS credentials.
     app.get("/api/sessions/:id/events", async (c) => {
         const sessionId = c.req.param("id");
         console.log(`[sse] Client connected: session=${sessionId}`);
-        const session = getSession(config.dataDir, sessionId);
-        if (!session) {
-            console.log(`[sse] Session not found: ${sessionId}`);
-            return c.json({ error: "Session not found" }, 404);
-        }
-        // Get the stream connection info
+        // Get the stream connection info (no session lookup needed —
+        // the DS stream may exist from a previous server lifetime)
         const connection = sessionStream(config, sessionId);
         // Last-Event-ID allows reconnection from where the client left off
         const lastEventId = c.req.header("Last-Event-ID") || "-1";
@@ -1046,7 +1616,7 @@ export function createApp(config) {
     // Get git status for a session
     app.get("/api/sessions/:id/git-status", async (c) => {
         const sessionId = c.req.param("id");
-        const session = getSession(config.dataDir, sessionId);
+        const session = config.sessions.get(sessionId);
         if (!session)
             return c.json({ error: "Session not found" }, 404);
         const handle = config.sandbox.get(sessionId);
@@ -1064,7 +1634,7 @@ export function createApp(config) {
     // List all files in the project directory
     app.get("/api/sessions/:id/files", async (c) => {
         const sessionId = c.req.param("id");
-        const session = getSession(config.dataDir, sessionId);
+        const session = config.sessions.get(sessionId);
         if (!session)
             return c.json({ error: "Session not found" }, 404);
         const handle = config.sandbox.get(sessionId);
@@ -1078,7 +1648,7 @@ export function createApp(config) {
     // Read a file's content
     app.get("/api/sessions/:id/file-content", async (c) => {
         const sessionId = c.req.param("id");
-        const session = getSession(config.dataDir, sessionId);
+        const session = config.sessions.get(sessionId);
         if (!session)
             return c.json({ error: "Session not found" }, 404);
         const filePath = c.req.query("path");
@@ -1203,7 +1773,7 @@ export function createApp(config) {
                     lastCheckpointAt: null,
                 },
             };
-            addSession(config.dataDir, session);
+            config.sessions.add(session);
             // Write initial message to stream
             const bridge = getOrCreateBridge(config, sessionId);
             await bridge.emit({
@@ -1212,7 +1782,7 @@ export function createApp(config) {
                 message: `Resumed from ${body.repoUrl}`,
                 ts: ts(),
             });
-            return c.json({ sessionId, appPort: handle.port }, 201);
+            return c.json({ sessionId, session, appPort: handle.port }, 201);
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : "Failed to resume from repo";
@@ -1242,17 +1812,14 @@ export async function startWebServer(opts) {
     const config = {
         port: opts.port ?? 4400,
         dataDir: opts.dataDir ?? path.resolve(process.cwd(), ".electric-agent"),
+        sessions: new ActiveSessions(),
+        rooms: opts.rooms,
         sandbox: opts.sandbox,
         streamConfig: opts.streamConfig,
         bridgeMode: opts.bridgeMode ?? "stream",
         inferProjectName: opts.inferProjectName,
     };
     fs.mkdirSync(config.dataDir, { recursive: true });
-    // Clean up stale sessions from previous runs
-    const cleaned = cleanupStaleSessions(config.dataDir);
-    if (cleaned > 0) {
-        console.log(`[startup] Cleaned up ${cleaned} stale session(s)`);
-    }
     const app = createApp(config);
     const hostname = process.env.NODE_ENV === "production" ? "0.0.0.0" : "127.0.0.1";
     serve({