@electric-agent/studio 1.5.0 → 1.12.0

package/dist/server.js

@@ -7,21 +7,26 @@ import { ts } from "@electric-agent/protocol";
 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 { addAgentSchema, addSessionToRoomSchema, createRoomSchema, createSandboxSchema, createSessionSchema, iterateRoomSessionSchema, iterateSessionSchema, resumeSessionSchema, sendRoomMessageSchema, } from "./api-schemas.js";
+import { PRODUCTION_ALLOWED_TOOLS } from "./bridge/claude-code-base.js";
 import { ClaudeCodeDockerBridge } from "./bridge/claude-code-docker.js";
 import { ClaudeCodeSpritesBridge, } from "./bridge/claude-code-sprites.js";
-import { createAppSkillContent, generateClaudeMd } from "./bridge/claude-md-generator.js";
+import { createAppSkillContent, generateClaudeMd, resolveRoleSkill, roomMessagingSkillContent, } from "./bridge/claude-md-generator.js";
 import { HostedStreamBridge } from "./bridge/hosted.js";
 import { DEFAULT_ELECTRIC_URL, getClaimUrl, provisionElectricResources } from "./electric-api.js";
 import { createGate, rejectAllGates, resolveGate } from "./gate.js";
 import { ghListAccounts, ghListBranches, ghListRepos, isGhAuthenticated } from "./git.js";
+import { generateInviteCode } from "./invite-code.js";
 import { resolveProjectDir } from "./project-utils.js";
-import { deriveSessionToken, validateSessionToken } from "./session-auth.js";
-import { generateInviteCode } from "./shared-sessions.js";
-import { getSharedStreamConnectionInfo, getStreamConnectionInfo, } from "./streams.js";
+import { RoomRouter } from "./room-router.js";
+import { deriveGlobalHookSecret, deriveHookToken, deriveRoomToken, deriveSessionToken, validateGlobalHookSecret, validateHookToken, validateRoomToken, validateSessionToken, } from "./session-auth.js";
+import { getRoomStreamConnectionInfo, getStreamConnectionInfo, } from "./streams.js";
+import { isResponse, validateBody } from "./validate.js";
 /** Active session bridges — one per running session */
 const bridges = new Map();
+/** Active room routers — one per room with agent-to-agent messaging */
+const roomRouters = new Map();
 /** Inflight hook session creations — prevents duplicate sessions from concurrent hooks */
 const inflightHookCreations = new Map();
 function parseRepoNameFromUrl(url) {
@@ -34,9 +39,9 @@ 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);
+/** Get stream connection info for a room */
+function roomStream(config, roomId) {
+    return getRoomStreamConnectionInfo(roomId, config.streamConfig);
 }
 /** Create or retrieve the SessionBridge for a session */
 function getOrCreateBridge(config, sessionId) {
@@ -64,11 +69,92 @@ function resolveStudioUrl(port) {
     // Fallback — won't work from sprites VMs, but at least logs a useful URL
     return `http://localhost:${port}`;
 }
+// ---------------------------------------------------------------------------
+// Rate limiting — in-memory sliding window per IP
+// ---------------------------------------------------------------------------
+const MAX_SESSIONS_PER_IP_PER_HOUR = Number(process.env.MAX_SESSIONS_PER_IP_PER_HOUR) || 5;
+const RATE_LIMIT_WINDOW_MS = 60 * 60 * 1000; // 1 hour
+const sessionCreationsByIp = new Map();
+function extractClientIp(c) {
+    return (c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ||
+        c.req.header("cf-connecting-ip") ||
+        "unknown");
+}
+function checkSessionRateLimit(ip) {
+    const now = Date.now();
+    const cutoff = now - RATE_LIMIT_WINDOW_MS;
+    let timestamps = sessionCreationsByIp.get(ip) ?? [];
+    // Prune stale entries
+    timestamps = timestamps.filter((t) => t > cutoff);
+    if (timestamps.length >= MAX_SESSIONS_PER_IP_PER_HOUR) {
+        sessionCreationsByIp.set(ip, timestamps);
+        return false;
+    }
+    timestamps.push(now);
+    sessionCreationsByIp.set(ip, timestamps);
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Per-session cost budget
+// ---------------------------------------------------------------------------
+const MAX_SESSION_COST_USD = Number(process.env.MAX_SESSION_COST_USD) || 5;
+/**
+ * Accumulate cost and turn metrics from a session_end event into the session's totals.
+ * Called each time a Claude Code run finishes (initial + iterate runs).
+ * In production mode, enforces a per-session cost budget.
+ */
+function accumulateSessionCost(config, sessionId, event) {
+    if (event.type !== "session_end")
+        return;
+    const { cost_usd, num_turns, duration_ms } = event;
+    if (cost_usd == null && num_turns == null && duration_ms == null)
+        return;
+    const existing = config.sessions.get(sessionId);
+    const updates = {};
+    if (cost_usd != null) {
+        updates.totalCostUsd = (existing?.totalCostUsd ?? 0) + cost_usd;
+    }
+    if (num_turns != null) {
+        updates.totalTurns = (existing?.totalTurns ?? 0) + num_turns;
+    }
+    if (duration_ms != null) {
+        updates.totalDurationMs = (existing?.totalDurationMs ?? 0) + duration_ms;
+    }
+    config.sessions.update(sessionId, updates);
+    console.log(`[session:${sessionId}] Cost: $${updates.totalCostUsd?.toFixed(4) ?? "?"} (${updates.totalTurns ?? "?"} turns)`);
+    // Enforce budget in production mode
+    if (!config.devMode &&
+        updates.totalCostUsd != null &&
+        updates.totalCostUsd > MAX_SESSION_COST_USD) {
+        console.log(`[session:${sessionId}] Budget exceeded: $${updates.totalCostUsd.toFixed(2)} > $${MAX_SESSION_COST_USD}`);
+        const bridge = bridges.get(sessionId);
+        if (bridge) {
+            bridge
+                .emit({
+                type: "budget_exceeded",
+                budget_usd: MAX_SESSION_COST_USD,
+                spent_usd: updates.totalCostUsd,
+                ts: ts(),
+            })
+                .catch(() => { });
+        }
+        config.sessions.update(sessionId, { status: "error" });
+        closeBridge(sessionId);
+    }
+}
 /**
  * Create a Claude Code bridge for a session.
  * Spawns `claude` CLI with stream-json I/O inside the sandbox.
+ * In production mode, enforces tool restrictions and hardcodes the model.
  */
 function createClaudeCodeBridge(config, sessionId, claudeConfig) {
+    // Production mode: restrict tools and hardcode model
+    if (!config.devMode) {
+        if (!claudeConfig.allowedTools) {
+            claudeConfig.allowedTools = PRODUCTION_ALLOWED_TOOLS;
+        }
+        claudeConfig.model = undefined; // force default (claude-sonnet-4-6)
+    }
     const conn = sessionStream(config, sessionId);
     let bridge;
     if (config.sandbox.runtime === "sprites") {
@@ -198,12 +284,26 @@ function mapHookToEngineEvent(body) {
                 text: body.last_assistant_message || "",
                 ts: now,
             };
-        case "SessionEnd":
-            return {
+        case "SessionEnd": {
+            const endEvent = {
                 type: "session_end",
                 success: true,
                 ts: now,
             };
+            // Claude Code SessionEnd hook may include session stats
+            const session = body.session;
+            if (session) {
+                if (typeof session.cost_usd === "number")
+                    endEvent.cost_usd = session.cost_usd;
+                if (typeof session.num_turns === "number")
+                    endEvent.num_turns = session.num_turns;
+                if (typeof session.duration_ms === "number")
+                    endEvent.duration_ms = session.duration_ms;
+                if (typeof session.duration_api_ms === "number")
+                    endEvent.duration_api_ms = session.duration_api_ms;
+            }
+            return endEvent;
+        }
         case "UserPromptSubmit":
             return {
                 type: "user_prompt",
@@ -224,8 +324,6 @@ function mapHookToEngineEvent(body) {
 }
 export function createApp(config) {
     const app = new Hono();
-    // CORS for local development
-    app.use("*", cors({ origin: "*" }));
     // --- API Routes ---
     // Health check
     app.get("/api/health", (c) => {
@@ -243,6 +341,10 @@ export function createApp(config) {
         checks.sandbox = config.sandbox.runtime;
         return c.json({ healthy, checks }, healthy ? 200 : 503);
     });
+    // Public config — exposes non-sensitive flags to the client
+    app.get("/api/config", (c) => {
+        return c.json({ devMode: config.devMode });
+    });
     // Provision Electric Cloud resources via the Claim API
     app.post("/api/provision-electric", async (c) => {
         try {
@@ -267,7 +369,7 @@ export function createApp(config) {
     // Hono's wildcard middleware matches creation routes like /api/sessions/local as
     // :id="local", so we must explicitly skip those.
     const authExemptIds = new Set(["local", "auto", "resume"]);
-    const hookExemptSuffixes = new Set(["/hook-event"]);
+    // Hook-event auth is handled in the endpoint handler via validateHookToken
     /** Extract session token from Authorization header or query param. */
     function extractToken(c) {
         const authHeader = c.req.header("Authorization");
@@ -281,7 +383,8 @@ export function createApp(config) {
         if (authExemptIds.has(id))
             return next();
         const subPath = c.req.path.replace(/^\/api\/sessions\/[^/]+/, "");
-        if (hookExemptSuffixes.has(subPath))
+        // Hook-event uses a purpose-scoped hook token (validated in the handler)
+        if (subPath === "/hook-event")
             return next();
         const token = extractToken(c);
         if (!token || !validateSessionToken(config.streamConfig.secret, id, token)) {
@@ -342,8 +445,9 @@ export function createApp(config) {
         // Pre-create a bridge so hook-event can emit to it immediately
         getOrCreateBridge(config, sessionId);
         const sessionToken = deriveSessionToken(config.streamConfig.secret, sessionId);
+        const hookToken = deriveHookToken(config.streamConfig.secret, sessionId);
         console.log(`[local-session] Created session: ${sessionId}`);
-        return c.json({ sessionId, sessionToken }, 201);
+        return c.json({ sessionId, sessionToken, hookToken }, 201);
     });
     // Auto-register a local session on first hook event (SessionStart).
     // Eliminates the manual `curl POST /api/sessions/local` step.
@@ -389,14 +493,20 @@ export function createApp(config) {
             await bridge.emit(hookEvent);
         }
         const sessionToken = deriveSessionToken(config.streamConfig.secret, sessionId);
+        const hookToken = deriveHookToken(config.streamConfig.secret, sessionId);
         console.log(`[auto-session] Created session: ${sessionId} (project: ${projectName})`);
-        return c.json({ sessionId, sessionToken }, 201);
+        return c.json({ sessionId, sessionToken, hookToken }, 201);
     });
     // Receive a hook event from Claude Code (via forward.sh) and write it
     // to the session's durable stream as an EngineEvent.
     // For AskUserQuestion, this blocks until the user answers in the web UI.
     app.post("/api/sessions/:id/hook-event", async (c) => {
         const sessionId = c.req.param("id");
+        // Validate hook token (scoped per-session, separate from session token)
+        const token = extractToken(c);
+        if (!token || !validateHookToken(config.streamConfig.secret, sessionId, token)) {
+            return c.json({ error: "Invalid or missing hook token" }, 401);
+        }
         const body = (await c.req.json());
         const bridge = getOrCreateBridge(config, sessionId);
         // Map Claude Code hook JSON → EngineEvent
@@ -421,6 +531,7 @@ export function createApp(config) {
         config.sessions.update(sessionId, {});
         // SessionEnd: mark session complete and close the bridge
         if (hookEvent.type === "session_end") {
+            accumulateSessionCost(config, sessionId, hookEvent);
             if (!isClaudeCodeBridge) {
                 config.sessions.update(sessionId, { status: "complete" });
                 closeBridge(sessionId);
@@ -457,6 +568,16 @@ export function createApp(config) {
         return c.json({ ok: true });
     });
     // --- Unified Hook Endpoint (transcript_path correlation) ---
+    // Protect the unified hook endpoint with a global hook secret derived from
+    // the DS secret. The hook setup script embeds this secret in the forwarder
+    // so that only local Claude Code instances can post events.
+    app.use("/api/hook", async (c, next) => {
+        const token = extractToken(c);
+        if (!token || !validateGlobalHookSecret(config.streamConfig.secret, token)) {
+            return c.json({ error: "Invalid or missing hook secret" }, 401);
+        }
+        return next();
+    });
     // 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.
@@ -553,6 +674,7 @@ export function createApp(config) {
         config.sessions.update(sessionId, {});
         // SessionEnd: mark complete and close bridge (keep mapping for potential re-open)
         if (hookEvent.type === "session_end") {
+            accumulateSessionCost(config, sessionId, hookEvent);
             config.sessions.update(sessionId, { status: "complete" });
             closeBridge(sessionId);
             return c.json({ ok: true, sessionId });
@@ -593,6 +715,7 @@ export function createApp(config) {
     // Usage: cd <project> && curl -s http://localhost:4400/api/hooks/setup | bash
     app.get("/api/hooks/setup", (c) => {
         const port = config.port;
+        const hookSecret = deriveGlobalHookSecret(config.streamConfig.secret);
         const script = `#!/bin/bash
 # Electric Agent — Claude Code hook installer (project-scoped)
 # Installs the hook forwarder into the current project's .claude/ directory.
@@ -613,10 +736,12 @@ cat > "\${FORWARD_SH}" << 'HOOKEOF'
 # Installed by: curl -s http://localhost:EA_PORT/api/hooks/setup | bash
 
 EA_PORT="\${EA_PORT:-EA_PORT_PLACEHOLDER}"
+EA_HOOK_SECRET="\${EA_HOOK_SECRET:-EA_HOOK_SECRET_PLACEHOLDER}"
 BODY="$(cat)"
 
 RESPONSE=$(curl -s -X POST "http://localhost:\${EA_PORT}/api/hook" \\
   -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer \${EA_HOOK_SECRET}" \\
   -d "\${BODY}" \\
   --max-time 360 \\
   --connect-timeout 2 \\
@@ -630,8 +755,9 @@ fi
 exit 0
 HOOKEOF
 
-# Replace placeholder with actual port
+# Replace placeholders with actual values
 sed -i.bak "s/EA_PORT_PLACEHOLDER/${port}/" "\${FORWARD_SH}" && rm -f "\${FORWARD_SH}.bak"
+sed -i.bak "s/EA_HOOK_SECRET_PLACEHOLDER/${hookSecret}/" "\${FORWARD_SH}" && rm -f "\${FORWARD_SH}.bak"
 chmod +x "\${FORWARD_SH}"
 
 # Merge hook config into project-level settings.local.json
@@ -673,9 +799,19 @@ echo "Start claude in this project — the session will appear in the studio UI.
     });
     // 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);
+        const body = await validateBody(c, createSessionSchema);
+        if (isResponse(body))
+            return body;
+        // Block freeform sessions in production mode
+        if (body.freeform && !config.devMode) {
+            return c.json({ error: "Freeform sessions are not available" }, 403);
+        }
+        // Rate-limit session creation in production mode
+        if (!config.devMode) {
+            const ip = extractClientIp(c);
+            if (!checkSessionRateLimit(ip)) {
+                return c.json({ error: "Too many sessions. Please try again later." }, 429);
+            }
         }
         const sessionId = crypto.randomUUID();
         const inferredName = body.name ||
@@ -717,74 +853,84 @@ echo "Start claude in this project — the session will appear in the studio UI.
         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
-        // Only check if the client provided a token — never fall back to server-side GH_TOKEN
+        // Freeform sessions skip the infra config gate — no Electric/DB setup needed
         let ghAccounts = [];
-        if (body.ghToken && isGhAuthenticated(body.ghToken)) {
-            try {
-                ghAccounts = ghListAccounts(body.ghToken);
-            }
-            catch {
-                // gh not available — no repo setup
+        if (!body.freeform) {
+            // Gather GitHub accounts for the merged setup gate
+            // Only check if the client provided a token — never fall back to server-side GH_TOKEN
+            if (body.ghToken && isGhAuthenticated(body.ghToken)) {
+                try {
+                    ghAccounts = ghListAccounts(body.ghToken);
+                }
+                catch {
+                    // gh not available — no repo setup
+                }
             }
+            // Emit combined infra + repo setup gate
+            await bridge.emit({
+                type: "infra_config_prompt",
+                projectName,
+                ghAccounts,
+                runtime: config.sandbox.runtime,
+                ts: ts(),
+            });
         }
-        // Emit combined infra + repo setup gate
-        await bridge.emit({
-            type: "infra_config_prompt",
-            projectName,
-            ghAccounts,
-            runtime: config.sandbox.runtime,
-            ts: ts(),
-        });
         // Launch async flow: wait for setup gate → create sandbox → start agent
         const asyncFlow = async () => {
-            // 1. Wait for combined infra + repo config
+            // 1. Wait for combined infra + repo config (skip for freeform)
             let infra;
             let repoConfig = null;
-            console.log(`[session:${sessionId}] Waiting for infra_config gate...`);
             let claimId;
-            try {
-                const gateValue = await createGate(sessionId, "infra_config");
-                console.log(`[session:${sessionId}] Infra gate resolved: mode=${gateValue.mode}`);
-                if (gateValue.mode === "cloud" || gateValue.mode === "claim") {
-                    // Normalize claim → cloud for the sandbox layer (same env vars)
-                    infra = {
-                        mode: "cloud",
-                        databaseUrl: gateValue.databaseUrl,
-                        electricUrl: gateValue.electricUrl,
-                        sourceId: gateValue.sourceId,
-                        secret: gateValue.secret,
-                    };
-                    if (gateValue.mode === "claim") {
-                        claimId = gateValue.claimId;
+            if (body.freeform) {
+                // Freeform sessions don't need Electric infrastructure
+                infra = { mode: "none" };
+                console.log(`[session:${sessionId}] Freeform session — skipping infra gate`);
+            }
+            else {
+                console.log(`[session:${sessionId}] Waiting for infra_config gate...`);
+                try {
+                    const gateValue = await createGate(sessionId, "infra_config");
+                    console.log(`[session:${sessionId}] Infra gate resolved: mode=${gateValue.mode}`);
+                    if (gateValue.mode === "cloud" || gateValue.mode === "claim") {
+                        // Normalize claim → cloud for the sandbox layer (same env vars)
+                        infra = {
+                            mode: "cloud",
+                            databaseUrl: gateValue.databaseUrl,
+                            electricUrl: gateValue.electricUrl,
+                            sourceId: gateValue.sourceId,
+                            secret: gateValue.secret,
+                        };
+                        if (gateValue.mode === "claim") {
+                            claimId = gateValue.claimId;
+                        }
+                    }
+                    else {
+                        infra = { mode: "local" };
+                    }
+                    // Extract repo config if provided
+                    if (gateValue.repoAccount && gateValue.repoName?.trim()) {
+                        repoConfig = {
+                            account: gateValue.repoAccount,
+                            repoName: gateValue.repoName,
+                            visibility: gateValue.repoVisibility ?? "private",
+                        };
+                        config.sessions.update(sessionId, {
+                            git: {
+                                branch: "main",
+                                remoteUrl: null,
+                                repoName: `${repoConfig.account}/${repoConfig.repoName}`,
+                                repoVisibility: repoConfig.visibility,
+                                lastCommitHash: null,
+                                lastCommitMessage: null,
+                                lastCheckpointAt: null,
+                            },
+                        });
                     }
                 }
-                else {
+                catch (err) {
+                    console.log(`[session:${sessionId}] Infra gate error (defaulting to local):`, err);
                     infra = { mode: "local" };
                 }
-                // Extract repo config if provided
-                if (gateValue.repoAccount && gateValue.repoName?.trim()) {
-                    repoConfig = {
-                        account: gateValue.repoAccount,
-                        repoName: gateValue.repoName,
-                        visibility: gateValue.repoVisibility ?? "private",
-                    };
-                    config.sessions.update(sessionId, {
-                        git: {
-                            branch: "main",
-                            remoteUrl: null,
-                            repoName: `${repoConfig.account}/${repoConfig.repoName}`,
-                            repoVisibility: repoConfig.visibility,
-                            lastCommitHash: null,
-                            lastCommitMessage: null,
-                            lastCheckpointAt: null,
-                        },
-                    });
-                }
-            }
-            catch (err) {
-                console.log(`[session:${sessionId}] Infra gate error (defaulting to local):`, err);
-                infra = { mode: "local" };
             }
             // 2. Create sandbox — emit progress events so the UI shows feedback
             await bridge.emit({
@@ -817,76 +963,119 @@ echo "Start claude in this project — the session will appear in the studio UI.
             // 3. Write CLAUDE.md and create a ClaudeCode bridge.
             {
                 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`);
-                    }
-                    console.log(`[session:${sessionId}] Project setup complete`);
+                if (!body.freeform) {
+                    // Copy pre-scaffolded project from the image and customize per-session
                     await bridge.emit({
                         type: "log",
-                        level: "done",
-                        message: "Project ready",
+                        level: "build",
+                        message: "Setting up project...",
                         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(),
+                    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.replace(/[^a-z0-9_-]/gi, "-")}"/' package.json`);
+                        }
+                        else {
+                            // Sprites: 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`);
+                        }
+                        console.log(`[session:${sessionId}] Project setup complete`);
+                        await bridge.emit({
+                            type: "log",
+                            level: "done",
+                            message: "Project ready",
+                            ts: ts(),
+                        });
+                        // Log the agent package version installed in the sandbox
+                        try {
+                            const agentVersion = (await config.sandbox.exec(handle, "electric-agent --version 2>/dev/null | tail -1")).trim();
+                            await bridge.emit({
+                                type: "log",
+                                level: "verbose",
+                                message: `electric-agent@${agentVersion}`,
+                                ts: ts(),
+                            });
+                        }
+                        catch {
+                            // Non-critical — don't block session creation
+                        }
+                    }
+                    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.
+                    // Our generator includes hardcoded playbook paths and reading order
+                    // so we don't depend on @tanstack/intent generating a skill block.
+                    const claudeMd = generateClaudeMd({
+                        description: body.description,
+                        projectName,
+                        projectDir: handle.projectDir,
+                        runtime: config.sandbox.runtime,
+                        production: !config.devMode,
+                        ...(repoConfig
+                            ? {
+                                git: {
+                                    mode: "create",
+                                    repoName: `${repoConfig.account}/${repoConfig.repoName}`,
+                                    visibility: repoConfig.visibility,
+                                },
+                            }
+                            : {}),
                     });
+                    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);
+                    }
+                    // Ensure the create-app skill is present in the project.
+                    // The npm-installed electric-agent may be an older version that
+                    // doesn't include .claude/skills/ in its template directory.
+                    if (createAppSkillContent) {
+                        try {
+                            const skillDir = `${handle.projectDir}/.claude/skills/create-app`;
+                            const skillB64 = Buffer.from(createAppSkillContent).toString("base64");
+                            await config.sandbox.exec(handle, `mkdir -p '${skillDir}' && echo '${skillB64}' | base64 -d > '${skillDir}/SKILL.md'`);
+                        }
+                        catch (err) {
+                            console.error(`[session:${sessionId}] Failed to write create-app skill:`, err);
+                        }
+                    }
                 }
-                // 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);
-                }
-                // Ensure the create-app skill is present in the project.
-                // The npm-installed electric-agent may be an older version that
-                // doesn't include .claude/skills/ in its template directory.
-                if (createAppSkillContent) {
+                // Ensure the room-messaging skill is present so agents have
+                // persistent access to the multi-agent protocol reference.
+                if (roomMessagingSkillContent) {
                     try {
-                        const skillDir = `${handle.projectDir}/.claude/skills/create-app`;
-                        const skillB64 = Buffer.from(createAppSkillContent).toString("base64");
+                        const skillDir = `${handle.projectDir}/.claude/skills/room-messaging`;
+                        const skillB64 = Buffer.from(roomMessagingSkillContent).toString("base64");
                         await config.sandbox.exec(handle, `mkdir -p '${skillDir}' && echo '${skillB64}' | base64 -d > '${skillDir}/SKILL.md'`);
                     }
                     catch (err) {
-                        console.error(`[session:${sessionId}] Failed to write create-app skill:`, err);
+                        console.error(`[session:${sessionId}] Failed to write room-messaging skill:`, err);
                     }
                 }
+                const sessionPrompt = body.freeform ? body.description : `/create-app ${body.description}`;
+                const sessionHookToken = deriveHookToken(config.streamConfig.secret, sessionId);
                 const claudeConfig = config.sandbox.runtime === "sprites"
                     ? {
-                        prompt: `/create-app ${body.description}`,
+                        prompt: sessionPrompt,
                         cwd: handle.projectDir,
                         studioUrl: resolveStudioUrl(config.port),
+                        hookToken: sessionHookToken,
                     }
                     : {
-                        prompt: `/create-app ${body.description}`,
+                        prompt: sessionPrompt,
                         cwd: handle.projectDir,
                         studioPort: config.port,
+                        hookToken: sessionHookToken,
                     };
                 bridge = createClaudeCodeBridge(config, sessionId, claudeConfig);
             }
@@ -900,7 +1089,7 @@ echo "Start claude in this project — the session will appear in the studio UI.
                 });
             }
             // 5. Start listening for agent events via the bridge
-            // Track Claude Code session ID for --resume on iterate
+            // Track Claude Code session ID and cost from agent events
             bridge.onAgentEvent((event) => {
                 if (event.type === "session_start") {
                     const ccSessionId = event.session_id;
@@ -909,6 +1098,9 @@ echo "Start claude in this project — the session will appear in the studio UI.
                         config.sessions.update(sessionId, { lastCoderSessionId: ccSessionId });
                     }
                 }
+                if (event.type === "session_end") {
+                    accumulateSessionCost(config, sessionId, event);
+                }
             });
             bridge.onComplete(async (success) => {
                 const updates = {
@@ -957,29 +1149,37 @@ echo "Start claude in this project — the session will appear in the studio UI.
             await bridge.emit({
                 type: "log",
                 level: "build",
-                message: `Running: claude "/create-app ${body.description}"`,
+                message: body.freeform
+                    ? `Running: claude "${body.description}"`
+                    : `Running: claude "/create-app ${body.description}"`,
                 ts: ts(),
             });
             console.log(`[session:${sessionId}] Starting bridge listener...`);
             await bridge.start();
             console.log(`[session:${sessionId}] Bridge started, sending 'new' command...`);
             // 5. Send the new command via the bridge
-            const newCmd = {
+            await bridge.sendCommand({
                 command: "new",
                 description: body.description,
                 projectName,
                 baseDir: "/home/agent/workspace",
-            };
-            if (repoConfig) {
-                newCmd.gitRepoName = `${repoConfig.account}/${repoConfig.repoName}`;
-                newCmd.gitRepoVisibility = repoConfig.visibility;
-            }
-            await bridge.sendCommand(newCmd);
+            });
             console.log(`[session:${sessionId}] Command sent, waiting for agent...`);
         };
         asyncFlow().catch(async (err) => {
             console.error(`[session:${sessionId}] Session creation flow failed:`, err);
             config.sessions.update(sessionId, { status: "error" });
+            try {
+                await bridge.emit({
+                    type: "log",
+                    level: "error",
+                    message: `Session failed: ${err instanceof Error ? err.message : String(err)}`,
+                    ts: ts(),
+                });
+            }
+            catch {
+                // Bridge may not be usable if the failure happened early
+            }
         });
         const sessionToken = deriveSessionToken(config.streamConfig.secret, sessionId);
         return c.json({ sessionId, session, sessionToken }, 201);
@@ -990,10 +1190,9 @@ echo "Start claude in this project — the session will appear in the studio UI.
         const session = config.sessions.get(sessionId);
         if (!session)
             return c.json({ error: "Session not found" }, 404);
-        const body = (await c.req.json());
-        if (!body.request) {
-            return c.json({ error: "request is required" }, 400);
-        }
+        const body = await validateBody(c, iterateSessionSchema);
+        if (isResponse(body))
+            return body;
         // Intercept operational commands (start/stop/restart the app/server)
         const normalised = body.request
             .toLowerCase()
@@ -1122,6 +1321,22 @@ echo "Start claude in this project — the session will appear in the studio UI.
             }
             // No pending gate — fall through to bridge.sendGateResponse()
         }
+        // Outbound message gates (room agent → room stream): resolved in-process
+        if (gate === "outbound_message_gate") {
+            const gateId = body.gateId;
+            const action = body.action;
+            if (!gateId || !action) {
+                return c.json({ error: "gateId and action are required for outbound_message_gate" }, 400);
+            }
+            const resolved = resolveGate(sessionId, gateId, {
+                action,
+                editedBody: body.editedBody,
+            });
+            if (resolved) {
+                return c.json({ ok: true });
+            }
+            return c.json({ error: "No pending gate found" }, 404);
+        }
         // Server-side gates are resolved in-process (they run on the server, not inside the container)
         const serverGates = new Set(["infra_config"]);
         // Forward agent gate responses via the bridge
@@ -1347,7 +1562,9 @@ echo "Start claude in this project — the session will appear in the studio UI.
     });
     // Create a standalone sandbox (not tied to session creation flow)
     app.post("/api/sandboxes", async (c) => {
-        const body = (await c.req.json());
+        const body = await validateBody(c, createSandboxSchema);
+        if (isResponse(body))
+            return body;
         const sessionId = body.sessionId ?? crypto.randomUUID();
         try {
             const handle = await config.sandbox.create(sessionId, {
@@ -1377,30 +1594,40 @@ echo "Start claude in this project — the session will appear in the studio UI.
         await config.sandbox.destroy(handle);
         return c.json({ ok: true });
     });
-    // --- Shared Sessions ---
-    // Protect /api/shared-sessions/:id/* (all sub-routes)
-    // Exempt: "join" (Hono matches join/:code as :id/*)
-    const sharedSessionExemptIds = new Set(["join"]);
-    app.use("/api/shared-sessions/:id/*", async (c, next) => {
+    // --- Room Routes (agent-to-agent messaging) ---
+    // Extract room token from X-Room-Token header or ?token= query param.
+    // This is separate from extractToken() (which reads Authorization) so that
+    // Authorization remains available for session tokens on endpoints that need both.
+    function extractRoomToken(c) {
+        return c.req.header("X-Room-Token") ?? c.req.query("token") ?? undefined;
+    }
+    // Protect room-scoped routes via X-Room-Token header
+    app.use("/api/rooms/:id/*", async (c, next) => {
         const id = c.req.param("id");
-        if (sharedSessionExemptIds.has(id))
-            return next();
-        const token = extractToken(c);
-        if (!token || !validateSessionToken(config.streamConfig.secret, id, token)) {
+        const token = extractRoomToken(c);
+        if (!token || !validateRoomToken(config.streamConfig.secret, id, token)) {
             return c.json({ error: "Invalid or missing room token" }, 401);
         }
         return next();
     });
-    // 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);
+    app.use("/api/rooms/:id", async (c, next) => {
+        if (c.req.method !== "GET" && c.req.method !== "DELETE")
+            return next();
+        const id = c.req.param("id");
+        const token = extractRoomToken(c);
+        if (!token || !validateRoomToken(config.streamConfig.secret, id, token)) {
+            return c.json({ error: "Invalid or missing room token" }, 401);
         }
-        const id = crypto.randomUUID();
-        const code = generateInviteCode();
-        // Create the shared session durable stream
-        const conn = sharedSessionStream(config, id);
+        return next();
+    });
+    // Create a room
+    app.post("/api/rooms", async (c) => {
+        const body = await validateBody(c, createRoomSchema);
+        if (isResponse(body))
+            return body;
+        const roomId = crypto.randomUUID();
+        // Create the room's durable stream
+        const conn = roomStream(config, roomId);
         try {
             await DurableStream.create({
                 url: conn.url,
@@ -1409,148 +1636,341 @@ echo "Start claude in this project — the session will appear in the studio UI.
             });
         }
         catch (err) {
-            console.error(`[shared-session] Failed to create durable stream:`, err);
-            return c.json({ error: "Failed to create shared session stream" }, 500);
+            console.error(`[room] Failed to create durable stream:`, err);
+            return c.json({ error: "Failed to create room stream" }, 500);
         }
-        // Write shared_session_created event
-        const stream = new DurableStream({
-            url: conn.url,
-            headers: conn.headers,
-            contentType: "application/json",
+        // Create and start the router
+        const router = new RoomRouter(roomId, body.name, config.streamConfig, {
+            maxRounds: body.maxRounds,
         });
-        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 router.start();
+        roomRouters.set(roomId, router);
+        // Save to room registry for persistence
+        const code = generateInviteCode();
         await config.rooms.addRoom({
-            id,
+            id: roomId,
             code,
             name: body.name,
             createdAt: new Date().toISOString(),
             revoked: false,
         });
-        const roomToken = deriveSessionToken(config.streamConfig.secret, id);
-        console.log(`[shared-session] Created: id=${id} code=${code}`);
-        return c.json({ id, code, roomToken }, 201);
+        const roomToken = deriveRoomToken(config.streamConfig.secret, roomId);
+        console.log(`[room] Created: id=${roomId} name=${body.name} code=${code}`);
+        return c.json({ roomId, code, roomToken }, 201);
     });
-    // Resolve invite code → shared session ID + room token
-    app.get("/api/shared-sessions/join/:code", (c) => {
+    // Join an agent room by id + invite code
+    app.get("/api/rooms/join/:id/:code", (c) => {
+        const id = c.req.param("id");
         const code = c.req.param("code");
-        const entry = config.rooms.getRoomByCode(code);
-        if (!entry)
-            return c.json({ error: "Shared session not found" }, 404);
-        const roomToken = deriveSessionToken(config.streamConfig.secret, entry.id);
-        return c.json({ id: entry.id, code: entry.code, revoked: entry.revoked, roomToken });
+        const room = config.rooms.getRoom(id);
+        if (!room || room.code !== code)
+            return c.json({ error: "Room not found" }, 404);
+        if (room.revoked)
+            return c.json({ error: "Room has been revoked" }, 410);
+        const roomToken = deriveRoomToken(config.streamConfig.secret, room.id);
+        return c.json({ id: room.id, code: room.code, name: room.name, roomToken });
     });
-    // 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",
+    // Get room state
+    app.get("/api/rooms/:id", (c) => {
+        const roomId = c.req.param("id");
+        const router = roomRouters.get(roomId);
+        if (!router)
+            return c.json({ error: "Room not found" }, 404);
+        return c.json({
+            roomId,
+            state: router.state,
+            roundCount: router.roundCount,
+            participants: router.participants.map((p) => ({
+                sessionId: p.sessionId,
+                name: p.name,
+                role: p.role,
+                running: p.bridge.isRunning(),
+            })),
         });
-        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);
+    // Add an agent to a room
+    app.post("/api/rooms/:id/agents", async (c) => {
+        const roomId = c.req.param("id");
+        const router = roomRouters.get(roomId);
+        if (!router)
+            return c.json({ error: "Room not found" }, 404);
+        const body = await validateBody(c, addAgentSchema);
+        if (isResponse(body))
+            return body;
+        const sessionId = crypto.randomUUID();
+        const randomSuffix = sessionId.slice(0, 6);
+        const agentName = body.name?.trim() || `agent-${randomSuffix}`;
+        const projectName = `room-${agentName}-${sessionId.slice(0, 8)}`;
+        console.log(`[room:${roomId}] Adding agent: name=${agentName} session=${sessionId}`);
+        // Create the session's durable stream
+        const conn = sessionStream(config, sessionId);
+        try {
+            await DurableStream.create({
+                url: conn.url,
+                headers: conn.headers,
+                contentType: "application/json",
+            });
         }
-        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(),
+        catch (err) {
+            console.error(`[room:${roomId}] Failed to create session stream:`, err);
+            return c.json({ error: "Failed to create session stream" }, 500);
+        }
+        // Create bridge
+        const bridge = getOrCreateBridge(config, sessionId);
+        // Record session
+        const sandboxProjectDir = `/home/agent/workspace/${projectName}`;
+        const session = {
+            id: sessionId,
+            projectName,
+            sandboxProjectDir,
+            description: `Room agent: ${agentName} (${body.role ?? "participant"})`,
+            createdAt: new Date().toISOString(),
+            lastActiveAt: new Date().toISOString(),
+            status: "running",
         };
-        await stream.append(JSON.stringify(event));
-        return c.json({ ok: true });
+        config.sessions.add(session);
+        // Return early so the client can store the session token and show the
+        // session in the sidebar immediately. The sandbox setup continues in
+        // the background — events stream to the session's durable stream so
+        // the UI stays up to date.
+        const sessionToken = deriveSessionToken(config.streamConfig.secret, sessionId);
+        (async () => {
+            await bridge.emit({
+                type: "log",
+                level: "build",
+                message: `Creating sandbox for room agent "${agentName}"...`,
+                ts: ts(),
+            });
+            try {
+                const handle = await config.sandbox.create(sessionId, {
+                    projectName,
+                    infra: { mode: "local" },
+                    apiKey: body.apiKey,
+                    oauthToken: body.oauthToken,
+                    ghToken: body.ghToken,
+                });
+                config.sessions.update(sessionId, {
+                    appPort: handle.port,
+                    sandboxProjectDir: handle.projectDir,
+                    previewUrl: handle.previewUrl,
+                });
+                // Inject room-messaging skill so agents know the @room protocol
+                if (roomMessagingSkillContent) {
+                    try {
+                        const skillDir = `${handle.projectDir}/.claude/skills/room-messaging`;
+                        const skillB64 = Buffer.from(roomMessagingSkillContent).toString("base64");
+                        await config.sandbox.exec(handle, `mkdir -p '${skillDir}' && echo '${skillB64}' | base64 -d > '${skillDir}/SKILL.md'`);
+                        // Append room-messaging reference to CLAUDE.md so the agent knows to read it
+                        const roomRef = `\n\n## Room Messaging (CRITICAL)\nYou are a participant in a multi-agent room. Read .claude/skills/room-messaging/SKILL.md for the messaging protocol.\nAll communication with other agents MUST use @room or @<name> messages as described in that skill.\n`;
+                        const refB64 = Buffer.from(roomRef).toString("base64");
+                        await config.sandbox.exec(handle, `echo '${refB64}' | base64 -d >> '${handle.projectDir}/CLAUDE.md'`);
+                    }
+                    catch (err) {
+                        console.error(`[session:${sessionId}] Failed to write room-messaging skill:`, err);
+                    }
+                }
+                // Resolve role skill (behavioral guidelines + tool permissions)
+                const roleSkill = resolveRoleSkill(body.role);
+                // Inject role skill file into sandbox
+                if (roleSkill) {
+                    try {
+                        const skillDir = `${handle.projectDir}/.claude/skills/role`;
+                        const skillB64 = Buffer.from(roleSkill.skillContent).toString("base64");
+                        await config.sandbox.exec(handle, `mkdir -p '${skillDir}' && echo '${skillB64}' | base64 -d > '${skillDir}/SKILL.md'`);
+                    }
+                    catch (err) {
+                        console.error(`[session:${sessionId}] Failed to write role skill:`, err);
+                    }
+                }
+                // Build prompt — reference the role skill if available
+                const rolePromptSuffix = roleSkill
+                    ? `\nRead .claude/skills/role/SKILL.md for your role guidelines before proceeding.`
+                    : "";
+                const agentPrompt = `You are "${agentName}"${body.role ? `, role: ${body.role}` : ""}. You are joining a multi-agent room.${rolePromptSuffix}`;
+                // Create Claude Code bridge (with role-specific tool permissions)
+                const agentHookToken = deriveHookToken(config.streamConfig.secret, sessionId);
+                const claudeConfig = config.sandbox.runtime === "sprites"
+                    ? {
+                        prompt: agentPrompt,
+                        cwd: handle.projectDir,
+                        studioUrl: resolveStudioUrl(config.port),
+                        hookToken: agentHookToken,
+                        agentName: agentName,
+                        ...(roleSkill?.allowedTools && { allowedTools: roleSkill.allowedTools }),
+                    }
+                    : {
+                        prompt: agentPrompt,
+                        cwd: handle.projectDir,
+                        studioPort: config.port,
+                        hookToken: agentHookToken,
+                        agentName: agentName,
+                        ...(roleSkill?.allowedTools && { allowedTools: roleSkill.allowedTools }),
+                    };
+                const ccBridge = createClaudeCodeBridge(config, sessionId, claudeConfig);
+                // Track Claude Code session ID and cost
+                ccBridge.onAgentEvent((event) => {
+                    if (event.type === "session_start") {
+                        const ccSessionId = event.session_id;
+                        if (ccSessionId) {
+                            config.sessions.update(sessionId, { lastCoderSessionId: ccSessionId });
+                        }
+                    }
+                    if (event.type === "session_end") {
+                        accumulateSessionCost(config, sessionId, event);
+                    }
+                    // Route assistant_message output to the room router
+                    if (event.type === "assistant_message" && "text" in event) {
+                        router
+                            .handleAgentOutput(sessionId, event.text)
+                            .catch((err) => {
+                            console.error(`[room:${roomId}] handleAgentOutput error:`, err);
+                        });
+                    }
+                });
+                await bridge.emit({
+                    type: "log",
+                    level: "done",
+                    message: `Sandbox ready for "${agentName}"`,
+                    ts: ts(),
+                });
+                await ccBridge.start();
+                // Add participant to room router
+                const participant = {
+                    sessionId,
+                    name: agentName,
+                    role: body.role,
+                    bridge: ccBridge,
+                };
+                await router.addParticipant(participant, body.gated ?? false);
+                // If there's an initial prompt, send it directly to this agent only (not broadcast)
+                if (body.initialPrompt) {
+                    await ccBridge.sendCommand({ command: "iterate", request: body.initialPrompt });
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : "Failed to create agent sandbox";
+                console.error(`[room:${roomId}] Agent creation failed:`, err);
+                await bridge.emit({ type: "log", level: "error", message: msg, ts: ts() });
+            }
+        })();
+        return c.json({ sessionId, participantName: agentName, sessionToken }, 201);
     });
-    // 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);
+    // Add an existing running session to a room
+    app.post("/api/rooms/:id/sessions", async (c) => {
+        const roomId = c.req.param("id");
+        const router = roomRouters.get(roomId);
+        if (!router)
+            return c.json({ error: "Room not found" }, 404);
+        const body = await validateBody(c, addSessionToRoomSchema);
+        if (isResponse(body))
+            return body;
+        const { sessionId } = body;
+        // Require a valid session token — caller must already own this session.
+        // Room auth is handled by middleware via X-Room-Token; Authorization
+        // carries the session ownership proof here.
+        const authHeader = c.req.header("Authorization");
+        const sessionToken = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : undefined;
+        if (!sessionToken ||
+            !validateSessionToken(config.streamConfig.secret, sessionId, sessionToken)) {
+            return c.json({ error: "Invalid or missing session token" }, 401);
         }
-        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 });
+        // Verify the session exists
+        const sessionInfo = config.sessions.get(sessionId);
+        if (!sessionInfo) {
+            return c.json({ error: "Session not found" }, 404);
+        }
+        // Get the sandbox handle — must be running
+        const handle = config.sandbox.get(sessionId);
+        if (!handle) {
+            return c.json({ error: "Session sandbox not found or not running" }, 400);
+        }
+        // Get or create bridge (it should already exist for a running session)
+        const bridge = getOrCreateBridge(config, sessionId);
+        console.log(`[room:${roomId}] Adding existing session: name=${body.name} session=${sessionId}`);
+        try {
+            // Inject room-messaging skill
+            if (roomMessagingSkillContent) {
+                try {
+                    const skillDir = `${handle.projectDir}/.claude/skills/room-messaging`;
+                    const skillB64 = Buffer.from(roomMessagingSkillContent).toString("base64");
+                    await config.sandbox.exec(handle, `mkdir -p '${skillDir}' && echo '${skillB64}' | base64 -d > '${skillDir}/SKILL.md'`);
+                    // Append room-messaging reference to CLAUDE.md so the agent knows to read it
+                    const roomRef = `\n\n## Room Messaging (CRITICAL)\nYou are a participant in a multi-agent room. Read .claude/skills/room-messaging/SKILL.md for the messaging protocol.\nAll communication with other agents MUST use @room or @<name> messages as described in that skill.\n`;
+                    const refB64 = Buffer.from(roomRef).toString("base64");
+                    await config.sandbox.exec(handle, `echo '${refB64}' | base64 -d >> '${handle.projectDir}/CLAUDE.md'`);
+                }
+                catch (err) {
+                    console.error(`[session:${sessionId}] Failed to write room-messaging skill:`, err);
+                }
+            }
+            // The existing bridge is already a Claude Code bridge — wire up room output handling
+            bridge.onAgentEvent((event) => {
+                if (event.type === "assistant_message" && "text" in event) {
+                    router
+                        .handleAgentOutput(sessionId, event.text)
+                        .catch((err) => {
+                        console.error(`[room:${roomId}] handleAgentOutput error:`, err);
+                    });
+                }
+            });
+            // Add participant to room router
+            const participant = {
+                sessionId,
+                name: body.name,
+                bridge,
+            };
+            await router.addParticipant(participant, false);
+            // If there's an initial prompt, send it directly to this agent
+            if (body.initialPrompt) {
+                await bridge.sendCommand({ command: "iterate", request: body.initialPrompt });
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : "Failed to add session to room";
+            console.error(`[room:${roomId}] Add session failed:`, err);
+            return c.json({ error: msg }, 500);
+        }
+        // No need to return sessionToken — caller already proved they have it
+        return c.json({ sessionId, participantName: body.name }, 201);
     });
-    // Unlink a session from a shared session
-    app.delete("/api/shared-sessions/:id/sessions/:sessionId", async (c) => {
-        const id = c.req.param("id");
+    // Send a message directly to a specific session in a room (bypasses room stream)
+    app.post("/api/rooms/:id/sessions/:sessionId/iterate", async (c) => {
+        const roomId = 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 router = roomRouters.get(roomId);
+        if (!router)
+            return c.json({ error: "Room not found" }, 404);
+        const participant = router.participants.find((p) => p.sessionId === sessionId);
+        if (!participant)
+            return c.json({ error: "Session not found in this room" }, 404);
+        const body = await validateBody(c, iterateRoomSessionSchema);
+        if (isResponse(body))
+            return body;
+        await participant.bridge.sendCommand({
+            command: "iterate",
+            request: body.request,
         });
-        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);
+    // Send a message to a room (from human or API)
+    app.post("/api/rooms/:id/messages", async (c) => {
+        const roomId = c.req.param("id");
+        const router = roomRouters.get(roomId);
+        if (!router)
+            return c.json({ error: "Room not found" }, 404);
+        const body = await validateBody(c, sendRoomMessageSchema);
+        if (isResponse(body))
+            return body;
+        await router.sendMessage(body.from, body.body, body.to);
+        return c.json({ ok: true });
+    });
+    // SSE proxy for room events
+    app.get("/api/rooms/:id/events", async (c) => {
+        const roomId = c.req.param("id");
+        const router = roomRouters.get(roomId);
+        if (!router)
+            return c.json({ error: "Room not found" }, 404);
+        const connection = roomStream(config, roomId);
         const lastEventId = c.req.header("Last-Event-ID") || c.req.query("offset") || "-1";
         const reader = new DurableStream({
             url: connection.url,
@@ -1589,23 +2009,27 @@ echo "Start claude in this project — the session will appear in the studio UI.
             },
         });
     });
-    // 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);
+    // Close a room
+    app.post("/api/rooms/:id/close", async (c) => {
+        const roomId = c.req.param("id");
+        const router = roomRouters.get(roomId);
+        if (!router)
+            return c.json({ error: "Room not found" }, 404);
+        // Emit room_closed event
+        const conn = roomStream(config, roomId);
         const stream = new DurableStream({
             url: conn.url,
             headers: conn.headers,
             contentType: "application/json",
         });
         const event = {
-            type: "code_revoked",
+            type: "room_closed",
+            closedBy: "human",
+            summary: "Room closed by user",
             ts: ts(),
         };
         await stream.append(JSON.stringify(event));
+        router.close();
         return c.json({ ok: true });
     });
     // --- SSE Proxy ---
@@ -1675,6 +2099,46 @@ echo "Start claude in this project — the session will appear in the studio UI.
             },
         });
     });
+    // --- Stream Append Proxy ---
+    // Proxy endpoint for writing events to a session's durable stream.
+    // Authenticates via session token so the caller never needs DS_SECRET.
+    // Used by sandbox agents to write events back to the session stream.
+    app.post("/api/sessions/:id/stream/append", async (c) => {
+        const sessionId = c.req.param("id");
+        const contentType = c.req.header("content-type") ?? "";
+        if (!contentType.includes("application/json")) {
+            return c.json({ error: "Content-Type must be application/json" }, 415);
+        }
+        const body = await c.req.text();
+        if (!body) {
+            return c.json({ error: "Request body is required" }, 400);
+        }
+        // Guard against oversized payloads (64 KB limit)
+        if (body.length > 65_536) {
+            return c.json({ error: "Payload too large" }, 413);
+        }
+        // Validate JSON before forwarding to the stream
+        try {
+            JSON.parse(body);
+        }
+        catch {
+            return c.json({ error: "Invalid JSON body" }, 400);
+        }
+        const connection = sessionStream(config, sessionId);
+        try {
+            const writer = new DurableStream({
+                url: connection.url,
+                headers: connection.headers,
+                contentType: "application/json",
+            });
+            await writer.append(body);
+            return c.json({ ok: true });
+        }
+        catch (err) {
+            console.error(`[stream-proxy] Append failed: session=${sessionId}`, err);
+            return c.json({ error: "Failed to append to stream" }, 500);
+        }
+    });
     // --- Git/GitHub Routes ---
     // Get git status for a session
     app.get("/api/sessions/:id/git-status", async (c) => {
@@ -1722,7 +2186,9 @@ echo "Start claude in this project — the session will appear in the studio UI.
         if (!handle || !sandboxDir) {
             return c.json({ error: "Container not available" }, 404);
         }
-        if (!filePath.startsWith(sandboxDir)) {
+        const resolvedPath = path.resolve(filePath);
+        const resolvedDir = path.resolve(sandboxDir) + path.sep;
+        if (!resolvedPath.startsWith(resolvedDir) && resolvedPath !== path.resolve(sandboxDir)) {
             return c.json({ error: "Path outside project directory" }, 403);
         }
         const content = await config.sandbox.readFile(handle, filePath);
@@ -1771,32 +2237,41 @@ echo "Start claude in this project — the session will appear in the studio UI.
             return c.json({ error: e instanceof Error ? e.message : "Failed to list branches" }, 500);
         }
     });
-    // Read Claude credentials from macOS Keychain (dev convenience)
-    app.get("/api/credentials/keychain", (c) => {
-        if (process.platform !== "darwin") {
-            return c.json({ apiKey: null });
-        }
-        try {
-            const raw = execFileSync("security", ["find-generic-password", "-s", "Claude Code-credentials", "-w"], { encoding: "utf-8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] }).trim();
-            const parsed = JSON.parse(raw);
-            const token = parsed.claudeAiOauth?.accessToken ?? null;
-            if (token) {
-                console.log(`[dev] Loaded OAuth token from keychain: ${token.slice(0, 20)}...${token.slice(-10)}`);
+    // Read Claude credentials from macOS Keychain (dev convenience).
+    // Disabled by default — enable via devMode: true or STUDIO_DEV_MODE=1.
+    if (config.devMode) {
+        app.get("/api/credentials/keychain", (c) => {
+            if (process.platform !== "darwin") {
+                return c.json({ apiKey: null });
             }
-            else {
-                console.log("[dev] No OAuth token found in keychain");
+            try {
+                const raw = execFileSync("security", ["find-generic-password", "-s", "Claude Code-credentials", "-w"], { encoding: "utf-8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] }).trim();
+                const parsed = JSON.parse(raw);
+                const token = parsed.claudeAiOauth?.accessToken ?? null;
+                if (token) {
+                    console.log(`[dev] Loaded OAuth token from keychain (length: ${token.length})`);
+                }
+                else {
+                    console.log("[dev] No OAuth token found in keychain");
+                }
+                return c.json({ oauthToken: token });
             }
-            return c.json({ oauthToken: token });
-        }
-        catch {
-            return c.json({ oauthToken: null });
-        }
-    });
+            catch {
+                return c.json({ oauthToken: null });
+            }
+        });
+    }
     // Resume a project from a GitHub repo
     app.post("/api/sessions/resume", async (c) => {
-        const body = (await c.req.json());
-        if (!body.repoUrl) {
-            return c.json({ error: "repoUrl is required" }, 400);
+        const body = await validateBody(c, resumeSessionSchema);
+        if (isResponse(body))
+            return body;
+        // Rate-limit session creation in production mode
+        if (!config.devMode) {
+            const ip = extractClientIp(c);
+            if (!checkSessionRateLimit(ip)) {
+                return c.json({ error: "Too many sessions. Please try again later." }, 429);
+            }
         }
         const sessionId = crypto.randomUUID();
         const repoName = body.repoUrl
@@ -1877,6 +2352,12 @@ echo "Start claude in this project — the session will appear in the studio UI.
                 projectName: repoName,
                 projectDir: handle.projectDir,
                 runtime: config.sandbox.runtime,
+                production: !config.devMode,
+                git: {
+                    mode: "existing",
+                    repoName: parseRepoNameFromUrl(body.repoUrl) ?? repoName,
+                    branch: gs.branch ?? body.branch ?? "main",
+                },
             });
             try {
                 await config.sandbox.exec(handle, `cat > '${handle.projectDir}/CLAUDE.md' << 'CLAUDEMD_EOF'\n${claudeMd}\nCLAUDEMD_EOF`);
@@ -1895,18 +2376,33 @@ echo "Start claude in this project — the session will appear in the studio UI.
                     console.error(`[session:${sessionId}] Failed to write create-app skill:`, err);
                 }
             }
+            // Ensure the room-messaging skill is present so agents have
+            // persistent access to the multi-agent protocol reference.
+            if (roomMessagingSkillContent) {
+                try {
+                    const skillDir = `${handle.projectDir}/.claude/skills/room-messaging`;
+                    const skillB64 = Buffer.from(roomMessagingSkillContent).toString("base64");
+                    await config.sandbox.exec(handle, `mkdir -p '${skillDir}' && echo '${skillB64}' | base64 -d > '${skillDir}/SKILL.md'`);
+                }
+                catch (err) {
+                    console.error(`[session:${sessionId}] Failed to write room-messaging skill:`, err);
+                }
+            }
             // 3. Create Claude Code bridge with a resume prompt
             const resumePrompt = "You are resuming work on an existing project. Explore the codebase to understand its structure, then wait for instructions from the user.";
+            const resumeHookToken = deriveHookToken(config.streamConfig.secret, sessionId);
             const claudeConfig = config.sandbox.runtime === "sprites"
                 ? {
                     prompt: resumePrompt,
                     cwd: handle.projectDir,
                     studioUrl: resolveStudioUrl(config.port),
+                    hookToken: resumeHookToken,
                 }
                 : {
                     prompt: resumePrompt,
                     cwd: handle.projectDir,
                     studioPort: config.port,
+                    hookToken: resumeHookToken,
                 };
             const ccBridge = createClaudeCodeBridge(config, sessionId, claudeConfig);
             // 4. Register event listeners (reuse pattern from normal flow)
@@ -1918,6 +2414,9 @@ echo "Start claude in this project — the session will appear in the studio UI.
                         config.sessions.update(sessionId, { lastCoderSessionId: ccSessionId });
                     }
                 }
+                if (event.type === "session_end") {
+                    accumulateSessionCost(config, sessionId, event);
+                }
             });
             ccBridge.onComplete(async (success) => {
                 const updates = {
@@ -1983,6 +2482,17 @@ echo "Start claude in this project — the session will appear in the studio UI.
         asyncFlow().catch(async (err) => {
             console.error(`[session:${sessionId}] Resume flow failed:`, err);
             config.sessions.update(sessionId, { status: "error" });
+            try {
+                await bridge.emit({
+                    type: "log",
+                    level: "error",
+                    message: `Resume failed: ${err instanceof Error ? err.message : String(err)}`,
+                    ts: ts(),
+                });
+            }
+            catch {
+                // Bridge may not be usable if the failure happened early
+            }
         });
         const sessionToken = deriveSessionToken(config.streamConfig.secret, sessionId);
         return c.json({ sessionId, session, sessionToken }, 201);
@@ -2007,6 +2517,10 @@ echo "Start claude in this project — the session will appear in the studio UI.
     return app;
 }
 export async function startWebServer(opts) {
+    const devMode = opts.devMode ?? process.env.STUDIO_DEV_MODE === "1";
+    if (devMode) {
+        console.log("[studio] Dev mode enabled — keychain endpoint active");
+    }
     const config = {
         port: opts.port ?? 4400,
         dataDir: opts.dataDir ?? path.resolve(process.cwd(), ".electric-agent"),
@@ -2015,6 +2529,7 @@ export async function startWebServer(opts) {
         sandbox: opts.sandbox,
         streamConfig: opts.streamConfig,
         bridgeMode: opts.bridgeMode ?? "claude-code",
+        devMode,
     };
     fs.mkdirSync(config.dataDir, { recursive: true });
     const app = createApp(config);