@vibevibes/runtime 0.2.0

package/dist/server.js

@@ -0,0 +1,3339 @@
+/**
+ * @vibevibes/runtime — the server engine for vibevibes experiences.
+ *
+ * Single-experience architecture with tool gate, WebSocket broadcasts, and room spawning.
+ *
+ * The server loads one experience from the project root (manifest.json for protocol
+ * experiences, or src/index.tsx for TypeScript experiences). Multiple rooms can be
+ * spawned, all running the same experience.
+ *
+ * AI agents join rooms via MCP or HTTP.
+ */
+import express from "express";
+import { WebSocketServer, WebSocket } from "ws";
+import http from "http";
+import path from "path";
+import fs from "fs";
+import { fileURLToPath } from "url";
+import { z, ZodError } from "zod";
+import { EventEmitter } from "events";
+import { bundleForServer, bundleForClient, evalServerBundle, validateClientBundle } from "./bundler.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { TickEngine } from "./tick-engine.js";
+import { isProtocolExperience, loadProtocolManifest, createProtocolModule, SubprocessExecutor } from "./protocol.js";
+import { createChatTools } from "@vibevibes/sdk";
+function formatZodError(err, toolName, tool) {
+    const issues = err.issues.map((issue) => {
+        const path = issue.path.length > 0 ? `'${issue.path.join(".")}'` : "input";
+        const extra = [];
+        const detail = issue;
+        if (detail.expected)
+            extra.push(`expected ${detail.expected}`);
+        if (detail.received && detail.received !== "undefined")
+            extra.push(`got ${detail.received}`);
+        const suffix = extra.length > 0 ? ` (${extra.join(", ")})` : "";
+        return `  ${path}: ${issue.message}${suffix}`;
+    });
+    let msg = `Invalid input for '${toolName}':\n${issues.join("\n")}`;
+    if (tool?.input_schema) {
+        try {
+            const schema = (tool.input_schema._jsonSchema || zodToJsonSchema(tool.input_schema));
+            const props = schema.properties;
+            const req = schema.required || [];
+            if (props) {
+                const fields = Object.entries(props).map(([k, v]) => {
+                    const optional = !req.includes(k);
+                    return `${k}${optional ? "?" : ""}: ${v.type || "any"}`;
+                });
+                msg += `\n\nExpected schema: { ${fields.join(", ")} }`;
+            }
+        }
+        catch { }
+    }
+    if (tool?.description)
+        msg += `\nTool description: ${tool.description}`;
+    msg += `\n\nHint: Provide all required fields with correct types.`;
+    return msg;
+}
+function formatHandlerError(err, toolName, tool, input) {
+    const message = err.message || String(err);
+    let msg = `Tool '${toolName}' failed: ${message}`;
+    if (input !== undefined) {
+        try {
+            msg += `\n\nInput provided: ${JSON.stringify(input)}`;
+        }
+        catch { }
+    }
+    if (tool?.input_schema) {
+        try {
+            const schema = (tool.input_schema._jsonSchema || zodToJsonSchema(tool.input_schema));
+            const props = schema.properties;
+            const req = schema.required || [];
+            if (props) {
+                const fields = Object.entries(props).map(([k, v]) => {
+                    const optional = !req.includes(k);
+                    return `${k}${optional ? "?" : ""}: ${v.type || "any"}`;
+                });
+                msg += `\nTool expects: { ${fields.join(", ")} }`;
+            }
+        }
+        catch { }
+    }
+    // Pattern-match common errors for specific hints
+    if (message.includes("Cannot read properties of undefined") || message.includes("Cannot read property")) {
+        msg += `\n\nHint: The handler accessed a property that doesn't exist on the current state. Check that initialState includes all fields your tools read from.`;
+    }
+    else if (message.includes("is not a function")) {
+        msg += `\n\nHint: Something expected to be a function is not. Check for missing imports or incorrect variable types in the tool handler.`;
+    }
+    else if (message.includes("Maximum call stack")) {
+        msg += `\n\nHint: Infinite recursion detected. A tool handler or function is calling itself without a base case.`;
+    }
+    else {
+        msg += `\n\nHint: The tool handler threw an error. Check the handler logic and ensure the current state matches what the handler expects.`;
+    }
+    return msg;
+}
+/** Safely extract an error message from an unknown thrown value. */
+function toErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Safely extract a string from an Express query parameter value. */
+function queryString(val) {
+    return typeof val === "string" ? val : undefined;
+}
+/** Safely parse an Express query parameter as an integer (returns 0 if absent/invalid). */
+function queryInt(val, radix = 10) {
+    return typeof val === "string" ? (parseInt(val, radix) || 0) : 0;
+}
+const __runtimeDir = path.dirname(fileURLToPath(import.meta.url));
+// PROJECT_ROOT is set by startServer() from ServerConfig.projectRoot.
+// It points to the experience project root (where src/, experiences/, registry live).
+let PROJECT_ROOT = "";
+// ── Custom error types ───────────────────────────────────────
+class ToolNotFoundError extends Error {
+    constructor(message) { super(message); this.name = "ToolNotFoundError"; }
+}
+class ToolForbiddenError extends Error {
+    constructor(message) { super(message); this.name = "ToolForbiddenError"; }
+}
+class Room {
+    id;
+    experienceId;
+    sharedState = {};
+    participants = new Map();
+    events = [];
+    wsConnections = new Map(); // ws → actorId
+    kickedActors = new Set();
+    kickedOwners = new Set();
+    parentRoomId;
+    childRoomIds = [];
+    /** Immutable config set at spawn time. Defines this room's modality/parameters. */
+    config;
+    /** Pre-created rooms (from registry) are exempt from empty-room GC. */
+    preCreated = false;
+    /** Per-room promise chain to serialize tool execution and prevent state interleaving. */
+    _executionQueue = Promise.resolve();
+    /** Monotonically increasing version counter for delta broadcasting. */
+    stateVersion = 0;
+    /** Previous state snapshot for computing deltas. null = first broadcast sends full state. */
+    _prevState = null;
+    constructor(id, experienceId, initialState, config) {
+        this.id = id;
+        this.experienceId = experienceId;
+        this.config = Object.freeze(config || {});
+        if (initialState) {
+            this.sharedState = initialState;
+        }
+    }
+    broadcastToAll(message) {
+        const data = JSON.stringify(message);
+        for (const ws of this.wsConnections.keys()) {
+            if (ws.readyState === WebSocket.OPEN) {
+                try {
+                    ws.send(data);
+                }
+                catch { /* client disconnected mid-send */ }
+            }
+        }
+    }
+    /**
+     * Broadcast a state update using delta compression.
+     * Compares current sharedState to _prevState using top-level key reference equality.
+     * Sends only changed/deleted keys (delta mode), or full state if no previous snapshot.
+     * @param forceFullState - If true, always sends full state (used for reset).
+     */
+    broadcastStateUpdate(extra, forceFullState = false) {
+        this.stateVersion++;
+        const prev = this._prevState;
+        this._prevState = this.sharedState;
+        // First broadcast or forced full state — send everything
+        if (!prev || forceFullState) {
+            this.broadcastToAll({
+                type: "shared_state_update",
+                roomId: this.id,
+                stateVersion: this.stateVersion,
+                state: this.sharedState,
+                ...extra,
+            });
+            return;
+        }
+        // Compute delta: compare top-level keys by reference equality (===)
+        const changed = {};
+        const deleted = [];
+        let changeCount = 0;
+        for (const key of Object.keys(this.sharedState)) {
+            if (this.sharedState[key] !== prev[key]) {
+                changed[key] = this.sharedState[key];
+                changeCount++;
+            }
+        }
+        for (const key of Object.keys(prev)) {
+            if (!(key in this.sharedState)) {
+                deleted.push(key);
+                changeCount++;
+            }
+        }
+        // No state changes — still broadcast if there's an event (tools that don't modify state)
+        if (changeCount === 0 && !extra.event)
+            return;
+        if (changeCount === 0) {
+            // Event-only broadcast (tool ran but didn't change state)
+            this.broadcastToAll({
+                type: "shared_state_update",
+                roomId: this.id,
+                stateVersion: this.stateVersion,
+                delta: {},
+                ...extra,
+            });
+        }
+        else {
+            this.broadcastToAll({
+                type: "shared_state_update",
+                roomId: this.id,
+                stateVersion: this.stateVersion,
+                delta: changed,
+                ...(deleted.length > 0 ? { deletedKeys: deleted } : {}),
+                ...extra,
+            });
+        }
+    }
+    /** Reset delta tracking (call after room reset to force full state on next broadcast). */
+    resetDeltaTracking() {
+        this._prevState = null;
+    }
+    participantList() {
+        return Array.from(this.participants.keys());
+    }
+    /** Returns participant objects with actorId, type, owner, agentMode, and metadata (for WebSocket broadcasts and stop hook discovery). */
+    participantDetails() {
+        return Array.from(this.participants.entries()).map(([actorId, p]) => {
+            const detail = {
+                actorId,
+                type: p.type,
+                role: p.role,
+                owner: p.owner,
+            };
+            if (p.agentMode)
+                detail.agentMode = p.agentMode;
+            if (p.metadata && Object.keys(p.metadata).length > 0)
+                detail.metadata = p.metadata;
+            return detail;
+        });
+    }
+    appendEvent(event) {
+        this.events.push(event);
+        if (this.events.length > MAX_EVENTS_PER_ROOM) {
+            this.events.splice(0, this.events.length - MAX_EVENTS_PER_ROOM);
+        }
+    }
+    /** Serialize an async operation against this room's tool execution queue.
+     *  Prevents concurrent tool calls from interleaving on shared state. */
+    enqueueExecution(fn) {
+        const next = this._executionQueue.then(() => fn());
+        // Swallow rejections on the chain so one failed tool doesn't block the next
+        this._executionQueue = next.then(() => { }, () => { });
+        return next;
+    }
+}
+// ── Constants ─────────────────────────────────────────────
+const DEFAULT_PORT = 4321;
+const MAX_EVENTS_PER_ROOM = 200;
+const JOIN_EVENT_HISTORY = 20;
+const ROOM_STATE_EVENT_HISTORY = 50;
+const HISTORY_DEFAULT_LIMIT = 50;
+const HISTORY_MAX_LIMIT = 200;
+const DEFAULT_STREAM_RATE_LIMIT = 60;
+const STREAM_RATE_WINDOW_MS = 1000;
+const EVENT_BATCH_DEBOUNCE_MS = 50;
+const DEFAULT_TICK_RATE_MS = 50;
+const MAX_BATCH_CALLS = 10;
+const LONG_POLL_MAX_TIMEOUT_MS = 55000;
+const AGENT_CONTEXT_MAX_TIMEOUT_MS = 10000;
+const WS_MAX_PAYLOAD_BYTES = 1024 * 1024; // 1MB
+const WS_EPHEMERAL_MAX_BYTES = 65536; // 64KB
+const WS_HEARTBEAT_INTERVAL_MS = 30000;
+const ROOM_GC_INTERVAL_MS = 60_000;
+const IDEMPOTENCY_CLEANUP_INTERVAL_MS = 60000;
+const SCREENSHOT_DEFAULT_TIMEOUT_MS = 10000;
+const SCREENSHOT_MAX_TIMEOUT_MS = 30000;
+const HOT_RELOAD_DEBOUNCE_MS = 300;
+const WS_CLOSE_GRACE_MS = 3000; // Grace period before deleting participant on WS close (allows reconnect on refresh)
+const JSON_BODY_LIMIT = "256kb";
+const TOOL_HTTP_TIMEOUT_MS = 30_000;
+const TOOL_REGEX_MAX_LENGTH = 100;
+const ROOM_EVENTS_MAX_LISTENERS = 200;
+const STREAM_RATE_LIMIT_STALE_MS = 5000;
+const STREAM_RATE_LIMIT_CLEANUP_INTERVAL_MS = 10000;
+const BLOB_CACHE_MAX_AGE_SECONDS = 300; // 5 minutes — blobs can be overwritten
+// ── Default observe (used when experience has no observe function) ─────
+function defaultObserve(state, _event, _actorId) {
+    const result = {};
+    for (const [k, v] of Object.entries(state)) {
+        if (!k.startsWith("_"))
+            result[k] = v;
+    }
+    const phase = typeof state.phase === "string" ? state.phase : null;
+    result.directive = phase ? `Current phase: ${phase}` : "Observe the current state and act accordingly.";
+    return result;
+}
+// ── Global state ──────────────────────────────────────────
+const DEFAULT_ROOM_ID = "local";
+let PORT = parseInt(process.env.PORT || String(DEFAULT_PORT), 10);
+let publicUrl = null;
+const rooms = new Map();
+const tickEngines = new Map();
+const roomLinks = [];
+let _actorCounter = 0;
+const agentMemory = new Map();
+const roomEmptySince = new Map(); // roomId → timestamp when first noticed empty (for GC)
+const roomEvents = new EventEmitter();
+roomEvents.setMaxListeners(ROOM_EVENTS_MAX_LISTENERS);
+/** Remove all parent-child room links involving the given roomId and update parent's childRoomIds. */
+function cleanupRoomLinks(roomId, room) {
+    for (let i = roomLinks.length - 1; i >= 0; i--) {
+        if (roomLinks[i].childRoomId === roomId || roomLinks[i].parentRoomId === roomId) {
+            roomLinks.splice(i, 1);
+        }
+    }
+    if (room.parentRoomId) {
+        const parent = rooms.get(room.parentRoomId);
+        if (parent) {
+            const idx = parent.childRoomIds.indexOf(roomId);
+            if (idx !== -1)
+                parent.childRoomIds.splice(idx, 1);
+        }
+    }
+}
+function roomNotFoundError(roomId) {
+    return `Room '${roomId}' not found. Use list_rooms to see available rooms.`;
+}
+/** Set no-cache response headers for dynamic content. */
+function setNoCacheHeaders(res) {
+    res.setHeader("Cache-Control", "no-cache, no-store, must-revalidate");
+    res.setHeader("Pragma", "no-cache");
+    res.setHeader("Expires", "0");
+}
+/** Broadcast a presence update to all WebSocket clients in a room. */
+function broadcastPresenceUpdate(room) {
+    room.broadcastToAll({
+        type: "presence_update",
+        participants: room.participantList(),
+        participantDetails: room.participantDetails(),
+    });
+}
+// ── Blob store ──────────────────────────────────────────
+const blobStore = new Map();
+const blobMeta = new Map();
+const MAX_BLOB_SIZE = 10 * 1024 * 1024; // 10MB per blob
+const MAX_TOTAL_BLOBS = 50 * 1024 * 1024; // 50MB total
+// ── Experience cache (replaces single global `experience`) ──
+const experienceCache = new Map();
+const experienceErrors = new Map(); // Last build error per experience ID
+let hostExperienceId = "";
+// Hot-reload rebuild gate — bundle endpoints await this during in-progress rebuilds
+let rebuildingResolve = null;
+let rebuildingPromise = null;
+// Spawn rate limiting: max 5 spawns per source room per 5 minutes
+const spawnCounts = new Map();
+const SPAWN_WINDOW_MS = 5 * 60 * 1000;
+const MAX_SPAWNS_PER_WINDOW = 5;
+const MAX_ROOMS = 100; // Hard cap on total rooms to prevent resource exhaustion
+const pendingSpawns = new Set(); // Room IDs currently being spawned (TOCTOU guard)
+const RESERVED_ROOM_IDS = new Set(["spawn", "config-schema", "local", "library", "rooms", "participants", "events", "memory", "agent-context", "screenshot", "blob", "__proto__", "constructor", "prototype"]);
+// Stream rate limiting: per actor, per stream, per room
+const streamRateLimits = new Map();
+// Periodic cleanup for stream rate limits (every 10 seconds)
+const _streamRateCleanupTimer = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of streamRateLimits) {
+        if (now - entry.windowStart > STREAM_RATE_LIMIT_STALE_MS)
+            streamRateLimits.delete(key);
+    }
+}, STREAM_RATE_LIMIT_CLEANUP_INTERVAL_MS);
+// Periodic cleanup for spawn rate limits (every 5 minutes)
+const _spawnRateCleanupTimer = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of spawnCounts) {
+        if (now - entry.windowStart > SPAWN_WINDOW_MS)
+            spawnCounts.delete(key);
+    }
+}, SPAWN_WINDOW_MS);
+/** Set the public tunnel URL (called from dev.ts when --share is active). */
+export function setPublicUrl(url) {
+    publicUrl = url;
+}
+/** Get the base URL clients should use (tunnel URL if sharing, localhost otherwise). */
+export function getBaseUrl() {
+    return publicUrl || `http://localhost:${PORT}`;
+}
+// ── Helpers ────────────────────────────────────────────────
+const FORBIDDEN_MERGE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        if (FORBIDDEN_MERGE_KEYS.has(key))
+            continue;
+        const sv = source[key];
+        const tv = target[key];
+        if (sv !== null && typeof sv === "object" && !Array.isArray(sv) &&
+            tv !== null && typeof tv === "object" && !Array.isArray(tv)) {
+            result[key] = deepMerge(tv, sv);
+        }
+        else {
+            result[key] = sv;
+        }
+    }
+    return result;
+}
+function assignActorId(username, type, owner) {
+    // Use owner as prefix when available (agents pass unique owner like "agent-abc123")
+    // This ensures two agents get truly distinct actorIds instead of "agent-ai-1" / "agent-ai-2"
+    const base = owner || `${username}-${type}`;
+    _actorCounter++;
+    return `${base}-${_actorCounter}`;
+}
+function getToolList(mod, allowedTools) {
+    if (!mod?.tools)
+        return [];
+    let tools = mod.tools;
+    if (allowedTools)
+        tools = tools.filter((t) => allowedTools.includes(t.name));
+    return tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        risk: t.risk || "low",
+        input_schema: t.input_schema?._jsonSchema
+            ? t.input_schema._jsonSchema
+            : t.input_schema ? zodToJsonSchema(t.input_schema) : {},
+    }));
+}
+function getRoom(roomId) {
+    return rooms.get(roomId);
+}
+function getDefaultRoom() {
+    const room = rooms.get(DEFAULT_ROOM_ID);
+    if (!room)
+        throw new Error(`Default room '${DEFAULT_ROOM_ID}' not found. Server may still be starting up.`);
+    return room;
+}
+/** Get the loaded experience for a room. Returns undefined if not loaded. */
+function getExperienceForRoom(room) {
+    return experienceCache.get(room.experienceId);
+}
+/** Get the host experience module (convenience). */
+function getHostExperience() {
+    return experienceCache.get(hostExperienceId)?.module;
+}
+function generateRoomId() {
+    return `room-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function checkSpawnRate(sourceRoomId) {
+    const now = Date.now();
+    const entry = spawnCounts.get(sourceRoomId);
+    if (!entry || now - entry.windowStart > SPAWN_WINDOW_MS) {
+        spawnCounts.set(sourceRoomId, { count: 1, windowStart: now });
+        return true;
+    }
+    if (entry.count >= MAX_SPAWNS_PER_WINDOW) {
+        return false;
+    }
+    entry.count++;
+    return true;
+}
+/**
+ * Resolve room config against a specific experience's roomConfig definition.
+ * Handles: preset names, explicit config objects, defaults, and validation.
+ */
+function resolveRoomConfig(experienceModule, configInput) {
+    const roomConfigDef = experienceModule?.roomConfig;
+    if (!roomConfigDef) {
+        // No config schema defined — shallow-copy (don't hold caller's reference) and reject arrays/null
+        return (typeof configInput === "object" && configInput !== null && !Array.isArray(configInput))
+            ? { ...configInput } : {};
+    }
+    let resolved;
+    if (typeof configInput === "string") {
+        // Preset name
+        const preset = roomConfigDef.presets?.[configInput];
+        if (!preset) {
+            const available = Object.keys(roomConfigDef.presets || {}).join(", ");
+            throw new Error(`Unknown config preset '${configInput}'. Available: ${available || "(none)"}`);
+        }
+        resolved = { ...roomConfigDef.defaults, ...preset };
+    }
+    else if (configInput && Object.keys(configInput).length > 0) {
+        // Explicit config values merged over defaults
+        resolved = { ...roomConfigDef.defaults, ...configInput };
+    }
+    else {
+        // No config provided — use defaults
+        resolved = roomConfigDef.defaults ? { ...roomConfigDef.defaults } : {};
+    }
+    // Validate against schema if available
+    if (roomConfigDef.schema?.parse) {
+        try {
+            resolved = roomConfigDef.schema.parse(resolved);
+        }
+        catch (err) {
+            if (err instanceof ZodError) {
+                const issues = err.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n");
+                throw new Error(`Invalid room config:\n${issues}`);
+            }
+            throw err;
+        }
+    }
+    return resolved;
+}
+/**
+ * Resolve the initial state for a room from its experience module.
+ * Checks for `initialState` (function or object) on the module.
+ * Falls back to empty object if not defined.
+ */
+function resolveInitialState(experienceModule, config) {
+    const init = experienceModule?.initialState;
+    if (typeof init === "function") {
+        try {
+            return init(config) || {};
+        }
+        catch (err) {
+            console.warn(`[resolveInitialState] initialState(config) threw:`, err);
+            return {};
+        }
+    }
+    if (init && typeof init === "object") {
+        return { ...init };
+    }
+    // Auto-generate initial state from stateSchema defaults (Zod .default() values)
+    const schema = experienceModule?.stateSchema;
+    if (schema && typeof schema.parse === "function") {
+        try {
+            return schema.parse({});
+        }
+        catch { /* schema has required fields without defaults */ }
+    }
+    return {};
+}
+// ── Experience discovery ────────────────────────────────────
+/** Discover the experience entry point in the project root. */
+function discoverEntryPath() {
+    // Protocol experience: manifest.json in project root
+    const manifestPath = path.join(PROJECT_ROOT, "manifest.json");
+    if (fs.existsSync(manifestPath))
+        return manifestPath;
+    // TypeScript experience: src/index.tsx
+    const tsxPath = path.join(PROJECT_ROOT, "src", "index.tsx");
+    if (fs.existsSync(tsxPath))
+        return tsxPath;
+    // TypeScript experience: index.tsx in root
+    const rootTsx = path.join(PROJECT_ROOT, "index.tsx");
+    if (fs.existsSync(rootTsx))
+        return rootTsx;
+    throw new Error(`No experience found in ${PROJECT_ROOT}. ` +
+        `Create a manifest.json (protocol) or src/index.tsx (TypeScript).`);
+}
+// ── Experience loading ─────────────────────────────────────
+/**
+ * Load an experience from an arbitrary entry path.
+ * Bundles server + client, evals server bundle, caches the result.
+ */
+async function loadExperienceFromPath(entryPath) {
+    // Protocol-based experience (manifest.json + subprocess)
+    if (isProtocolExperience(entryPath)) {
+        return loadProtocolExperienceFromPath(entryPath);
+    }
+    const [sCode, cCode] = await Promise.all([
+        bundleForServer(entryPath),
+        bundleForClient(entryPath),
+    ]);
+    const mod = await evalServerBundle(sCode);
+    if (!mod?.manifest || !mod?.tools) {
+        throw new Error(`Experience at ${entryPath} missing manifest or tools`);
+    }
+    // Auto-inject chat tools (_chat.send, _chat.team, _chat.clear) if not already present
+    if (!mod.tools.some((t) => t.name === '_chat.send')) {
+        mod.tools.push(...createChatTools(z));
+    }
+    // Validate client bundle for syntax errors and unresolved references
+    const clientError = validateClientBundle(cCode);
+    if (clientError) {
+        throw new Error(`Client bundle validation failed for ${entryPath}: ${clientError}`);
+    }
+    const loaded = {
+        module: mod,
+        clientBundle: cCode,
+        serverCode: sCode,
+        loadedAt: Date.now(),
+        sourcePath: entryPath,
+    };
+    experienceCache.set(mod.manifest.id, loaded);
+    experienceErrors.delete(mod.manifest.id); // Clear any previous build error
+    return loaded;
+}
+// Track protocol executors for cleanup
+const protocolExecutors = new Map();
+async function loadProtocolExperienceFromPath(manifestPath) {
+    const manifestDir = path.dirname(manifestPath);
+    const manifest = loadProtocolManifest(manifestPath);
+    // Stop existing executor if reloading
+    const existing = protocolExecutors.get(manifest.id);
+    if (existing)
+        existing.stop();
+    // Spawn the tool process
+    const executor = new SubprocessExecutor(manifest.toolProcess.command, manifest.toolProcess.args || [], manifestDir);
+    executor.start();
+    protocolExecutors.set(manifest.id, executor);
+    // Send init
+    try {
+        await executor.send("init", { experienceId: manifest.id }, 5000);
+    }
+    catch {
+        // init is optional — process may not implement it
+    }
+    const mod = createProtocolModule(manifest, executor, manifestDir);
+    // Auto-inject chat tools if not present
+    if (!mod.tools.some((t) => t.name === '_chat.send')) {
+        mod.tools.push(...createChatTools(z));
+    }
+    // For protocol experiences, clientBundle is empty (HTML canvas served separately)
+    // and serverCode is the manifest JSON (for reference)
+    const loaded = {
+        module: mod,
+        clientBundle: "", // No JS bundle — HTML canvas served directly
+        serverCode: JSON.stringify(manifest),
+        loadedAt: Date.now(),
+        sourcePath: manifestPath,
+    };
+    experienceCache.set(manifest.id, loaded);
+    experienceErrors.delete(manifest.id);
+    console.log(`[protocol] Loaded ${manifest.title} (${manifest.id}) — ${manifest.tools.length} tools, process: ${manifest.toolProcess.command}`);
+    return loaded;
+}
+/**
+ * Get the loaded experience. Returns cached if available.
+ */
+async function getLoadedExperience() {
+    const cached = experienceCache.get(hostExperienceId);
+    if (cached)
+        return cached;
+    return loadHost();
+}
+/**
+ * Load the experience from the project root.
+ */
+async function loadHost() {
+    const entryPath = discoverEntryPath();
+    const loaded = await loadExperienceFromPath(entryPath);
+    hostExperienceId = loaded.module.manifest.id;
+    return loaded;
+}
+// ── Spawn room (async — can load external experiences) ─────
+async function spawnRoom(sourceRoomId, opts) {
+    if (!opts.skipRateLimit && !checkSpawnRate(sourceRoomId)) {
+        throw new Error(`Rate limited: max ${MAX_SPAWNS_PER_WINDOW} spawns per ${SPAWN_WINDOW_MS / 60000} minutes`);
+    }
+    let roomId = opts.name || generateRoomId();
+    // Sanitize room name: strip path traversal and unsafe characters
+    if (opts.name) {
+        roomId = roomId.replace(/[^a-zA-Z0-9._\-]/g, "-");
+        if (!roomId || roomId.length > 128)
+            throw new Error("Invalid room name");
+    }
+    // Reject reserved room IDs that would shadow API route segments or cause prototype pollution
+    if (RESERVED_ROOM_IDS.has(roomId)) {
+        throw new Error(`Room name '${roomId}' is reserved and cannot be used`);
+    }
+    // TOCTOU guard: check both committed and pending rooms atomically (single-threaded JS)
+    if (rooms.has(roomId) || pendingSpawns.has(roomId)) {
+        throw new Error(`Room '${roomId}' already exists`);
+    }
+    if (rooms.size + pendingSpawns.size >= MAX_ROOMS) {
+        throw new Error(`Room limit reached (${MAX_ROOMS}). Delete unused rooms before spawning new ones.`);
+    }
+    // Reserve the room ID before async work to prevent concurrent spawns
+    pendingSpawns.add(roomId);
+    let room;
+    try {
+        // Always use the host experience (single-experience server)
+        const targetExperienceLoaded = await getLoadedExperience();
+        // Resolve and validate config against the TARGET experience's schema
+        const config = resolveRoomConfig(targetExperienceLoaded.module, opts.config);
+        // Resolve initial state: experience default, merged with explicit initialState, plus linkBack
+        const expInitialState = resolveInitialState(targetExperienceLoaded.module, config);
+        // Filter FORBIDDEN_MERGE_KEYS from initialState to prevent prototype pollution
+        const safeInitialState = {};
+        if (opts.initialState && typeof opts.initialState === "object" && !Array.isArray(opts.initialState)) {
+            for (const [k, v] of Object.entries(opts.initialState)) {
+                if (!FORBIDDEN_MERGE_KEYS.has(k))
+                    safeInitialState[k] = v;
+            }
+        }
+        const mergedState = { ...expInitialState, ...safeInitialState };
+        const initialState = opts.linkBack
+            ? { ...mergedState, _parentRoom: sourceRoomId }
+            : mergedState;
+        room = new Room(roomId, opts.experienceId, initialState, config);
+        room.parentRoomId = sourceRoomId;
+        rooms.set(roomId, room);
+        pendingSpawns.delete(roomId);
+    }
+    catch (err) {
+        pendingSpawns.delete(roomId);
+        throw err;
+    }
+    // Track parent-child link
+    const sourceRoom = rooms.get(sourceRoomId);
+    if (sourceRoom) {
+        sourceRoom.childRoomIds.push(roomId);
+    }
+    // Store RoomLink (include config in metadata)
+    // Cap roomLinks to prevent unbounded growth under rapid spawn/GC cycling
+    if (roomLinks.length >= 1000) {
+        roomLinks.splice(0, roomLinks.length - 999);
+    }
+    roomLinks.push({
+        parentRoomId: sourceRoomId,
+        childRoomId: roomId,
+        linkType: "spawned",
+        metadata: { experienceId: opts.experienceId, config: room.config },
+        createdAt: new Date().toISOString(),
+    });
+    // Start tick engine if experience uses tick netcode
+    const loadedExp = experienceCache.get(opts.experienceId);
+    if (loadedExp)
+        maybeStartTickEngine(room, loadedExp);
+    const url = `${getBaseUrl()}/room/${roomId}`;
+    return { roomId, url, config: room.config };
+}
+// ── Tick Engine lifecycle ──────────────────────────────────
+/** Start a tick engine for a room if its experience uses tick netcode. */
+function maybeStartTickEngine(room, loaded) {
+    const manifest = loaded.module?.manifest;
+    if (manifest?.netcode !== "tick")
+        return;
+    // Stop existing engine first to prevent ghost intervals on hot-reload
+    stopTickEngine(room.id);
+    const tickRateMs = manifest.tickRateMs || DEFAULT_TICK_RATE_MS;
+    const engine = new TickEngine(room, loaded, roomEvents, tickRateMs);
+    engine.start();
+    tickEngines.set(room.id, engine);
+}
+/** Stop and remove the tick engine for a room. */
+function stopTickEngine(roomId) {
+    const engine = tickEngines.get(roomId);
+    if (engine) {
+        engine.stop();
+        tickEngines.delete(roomId);
+    }
+}
+// ── Express app ────────────────────────────────────────────
+const app = express();
+app.use(express.json({ limit: JSON_BODY_LIMIT }));
+// CORS for local development
+app.use((_req, res, next) => {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET,POST,PATCH,DELETE,OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type,Authorization,X-Idempotency-Key");
+    if (_req.method === "OPTIONS") {
+        res.sendStatus(200);
+        return;
+    }
+    next();
+});
+// Serve viewer (no-cache so changes are picked up immediately)
+app.get("/", (_req, res) => {
+    setNoCacheHeaders(res);
+    res.sendFile(path.join(__runtimeDir, "viewer", "index.html"));
+});
+app.use("/viewer", express.static(path.join(__runtimeDir, "viewer")));
+// Serve SDK ESM bundle (for scene engine and other SDK features in browser)
+app.get("/sdk.js", (_req, res) => {
+    const sdkPath = path.join(PROJECT_ROOT, "node_modules", "@vibevibes", "sdk", "dist", "index.js");
+    if (fs.existsSync(sdkPath)) {
+        res.setHeader("Content-Type", "application/javascript");
+        res.sendFile(sdkPath);
+    }
+    else {
+        res.status(404).send("// SDK not found");
+    }
+});
+// ── Room state endpoint (flat = default room) ──────────────
+app.get("/state", (req, res) => {
+    const room = getDefaultRoom();
+    const exp = getExperienceForRoom(room);
+    let observation;
+    const observeFn = exp?.module?.observe ?? defaultObserve;
+    const observeActorId = typeof req.query.actorId === "string" ? req.query.actorId : "viewer";
+    try {
+        observation = observeFn(room.sharedState, null, observeActorId);
+    }
+    catch (err) {
+        console.warn(`[observe] Error: ${toErrorMessage(err)}`);
+    }
+    res.json({
+        roomId: room.id,
+        experienceId: exp?.module?.manifest?.id ?? room.experienceId,
+        sharedState: room.sharedState,
+        stateVersion: room.stateVersion,
+        participants: room.participantList(),
+        events: room.events.slice(-ROOM_STATE_EVENT_HISTORY),
+        config: room.config,
+        observation,
+    });
+});
+// ── Slots endpoint (default room) ───────────────────────────
+app.get("/slots", (_req, res) => {
+    const room = getDefaultRoom();
+    const exp = getExperienceForRoom(room);
+    const slots = exp?.module?.manifest?.participantSlots || exp?.module?.participants || [];
+    res.json({ slots, participantDetails: room.participantDetails() });
+});
+// ── Participants endpoint ──────────────────────────────────
+app.get("/participants", (_req, res) => res.json({ participants: getDefaultRoom().participantDetails() }));
+app.get("/rooms/:roomId/participants", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room)
+        return res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    res.json({ participants: room.participantDetails() });
+});
+// ── Tools list endpoint (structured tool discovery for agents) ──
+function handleToolsList(room, req, res) {
+    const exp = getExperienceForRoom(room);
+    if (!exp) {
+        res.status(500).json({ error: experienceNotLoadedError(room.experienceId) });
+        return;
+    }
+    // If actorId is provided, filter tools by the participant's allowedTools
+    const actorId = queryString(req.query.actorId);
+    let allowedTools;
+    if (actorId) {
+        const participant = room.participants.get(actorId);
+        allowedTools = participant?.allowedTools;
+    }
+    const tools = getToolList(exp.module, allowedTools);
+    // Also return stream definitions if the experience defines them
+    const streams = exp.module.streams
+        ? exp.module.streams.map((s) => ({
+            name: s.name,
+            description: s.description || "",
+            rateLimit: s.rateLimit || DEFAULT_STREAM_RATE_LIMIT,
+            input_schema: s.input_schema ? zodToJsonSchema(s.input_schema) : {},
+        }))
+        : [];
+    res.json({
+        roomId: room.id,
+        experienceId: exp.module.manifest?.id || room.experienceId,
+        tools,
+        streams,
+        toolCount: tools.length,
+        streamCount: streams.length,
+    });
+}
+app.get("/tools-list", (req, res) => handleToolsList(getDefaultRoom(), req, res));
+app.get("/rooms/:roomId/tools-list", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room)
+        return res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    handleToolsList(room, req, res);
+});
+// ── History endpoint (filtered event log) ────────────────────
+function handleHistory(room, req, res) {
+    const limit = Math.min(queryInt(req.query.limit) || HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT);
+    const since = queryInt(req.query.since);
+    const actor = queryString(req.query.actor);
+    const tool = queryString(req.query.tool);
+    const owner = queryString(req.query.owner);
+    let events = room.events;
+    // Filter by timestamp
+    if (since > 0) {
+        events = events.filter(e => e.ts > since);
+    }
+    // Filter by actor
+    if (actor) {
+        events = events.filter(e => e.actorId === actor);
+    }
+    // Filter by owner
+    if (owner) {
+        events = events.filter(e => e.owner === owner);
+    }
+    // Filter by tool name — only allow safe literal characters (no regex metacharacters)
+    // This prevents user-controlled ReDoS via crafted patterns
+    if (tool) {
+        const SAFE_TOOL_REGEX = /^[a-zA-Z0-9._:\-]+$/;
+        if (tool.length <= TOOL_REGEX_MAX_LENGTH && SAFE_TOOL_REGEX.test(tool)) {
+            // Safe literal pattern — escape dots (regex metachar) for exact matching
+            try {
+                const escaped = tool.replace(/\./g, '\\.');
+                const toolRegex = new RegExp('^' + escaped + '$');
+                events = events.filter(e => toolRegex.test(e.tool));
+            }
+            catch {
+                events = events.filter(e => e.tool === tool);
+            }
+        }
+        else {
+            events = events.filter(e => e.tool === tool);
+        }
+    }
+    // Take last N events
+    const filteredTotal = events.length;
+    const result = events.slice(-limit);
+    res.json({
+        roomId: room.id,
+        events: result,
+        total: room.events.length,
+        filtered: filteredTotal,
+        returned: result.length,
+        hasMore: filteredTotal > limit,
+    });
+}
+app.get("/history", (req, res) => handleHistory(getDefaultRoom(), req, res));
+app.get("/rooms/:roomId/history", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room)
+        return res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    handleHistory(room, req, res);
+});
+// ── Who endpoint (rich participant info) ─────────────────────
+function handleWho(room, _req, res) {
+    const participants = Array.from(room.participants.entries()).map(([actorId, p]) => {
+        // Find this participant's last action
+        let lastAction;
+        for (let i = room.events.length - 1; i >= 0; i--) {
+            if (room.events[i].actorId === actorId) {
+                lastAction = { tool: room.events[i].tool, ts: room.events[i].ts };
+                break;
+            }
+        }
+        return {
+            actorId,
+            owner: p.owner,
+            type: p.type,
+            role: p.role,
+            joinedAt: p.joinedAt,
+            lastAction,
+            allowedTools: p.allowedTools,
+        };
+    });
+    res.json({
+        roomId: room.id,
+        participants,
+        count: participants.length,
+        humans: participants.filter(p => p.type === "human").length,
+        agents: participants.filter(p => p.type === "ai").length,
+    });
+}
+app.get("/who", (req, res) => handleWho(getDefaultRoom(), req, res));
+app.get("/rooms/:roomId/who", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room)
+        return res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+    handleWho(room, req, res);
+});
+// ── Join (flat = default room) ─────────────────────────────
+function experienceNotLoadedError(experienceId) {
+    const lastError = experienceErrors.get(experienceId);
+    const hint = lastError
+        ? `\nLast build error: ${lastError}\nFix the source and save to hot-reload.`
+        : `\nCheck that src/index.tsx exists and exports a valid experience.`;
+    return `Experience '${experienceId}' not loaded.${hint}`;
+}
+function handleJoin(room, req, res) {
+    const exp = getExperienceForRoom(room);
+    if (!exp) {
+        res.status(500).json({ error: experienceNotLoadedError(room.experienceId) });
+        return;
+    }
+    const { username = "user", actorType: rawActorType = "human", owner, role: requestedRole, agentMode: rawAgentMode, metadata: rawMetadata } = req.body;
+    const actorType = rawActorType === "ai" ? "ai" : "human";
+    const resolvedOwner = owner || username;
+    // Validate agentMode (only for AI participants)
+    const VALID_AGENT_MODES = ["behavior", "manual", "hybrid"];
+    const agentMode = actorType === "ai" && typeof rawAgentMode === "string" && VALID_AGENT_MODES.includes(rawAgentMode) ? rawAgentMode : undefined;
+    // Validate metadata (string→string record, max 20 keys, max 200 chars per value)
+    let metadata;
+    if (rawMetadata && typeof rawMetadata === "object" && !Array.isArray(rawMetadata)) {
+        metadata = {};
+        let keyCount = 0;
+        for (const [k, v] of Object.entries(rawMetadata)) {
+            if (keyCount >= 20)
+                break;
+            if (typeof k === "string" && typeof v === "string" && k.length <= 50) {
+                metadata[k] = String(v).slice(0, 200);
+                keyCount++;
+            }
+        }
+        if (Object.keys(metadata).length === 0)
+            metadata = undefined;
+    }
+    // Reject empty owner — would bypass kick enforcement
+    if (!resolvedOwner) {
+        res.status(400).json({ error: "owner or username required" });
+        return;
+    }
+    // Dedup: if same owner already has a participant in this room, reuse the existing entry
+    if (resolvedOwner) {
+        // Check kick status before allowing reconnect
+        if (room.kickedOwners.has(resolvedOwner)) {
+            res.status(403).json({ error: "You have been kicked from this room." });
+            return;
+        }
+        for (const [existingId, existingP] of room.participants.entries()) {
+            if (existingP.owner === resolvedOwner) {
+                // Check if this specific actorId was kicked
+                if (room.kickedActors.has(existingId)) {
+                    res.status(403).json({ error: "You have been kicked from this room." });
+                    return;
+                }
+                // Same owner reconnecting — return existing identity (preserves actorId continuity)
+                existingP.joinedAt = Date.now();
+                // Ensure _agentRoles stays current on reconnect
+                if (existingP.type === "ai" && existingP.role) {
+                    room.sharedState = {
+                        ...room.sharedState,
+                        _agentRoles: { ...(room.sharedState._agentRoles ?? {}), [existingId]: existingP.role },
+                    };
+                }
+                // Clean up stale WS mapping and close the old WebSocket if still alive
+                for (const [ws, wsActor] of room.wsConnections.entries()) {
+                    if (wsActor === existingId) {
+                        room.wsConnections.delete(ws);
+                        try {
+                            ws.close(1000, "Replaced by reconnect");
+                        }
+                        catch { }
+                        break;
+                    }
+                }
+                // Broadcast presence update
+                broadcastPresenceUpdate(room);
+                // Compute observation for the reconnected agent
+                let observation;
+                let observeError;
+                const reconnectObserve = exp.module.observe ?? defaultObserve;
+                try {
+                    observation = reconnectObserve(room.sharedState, null, existingId);
+                }
+                catch (e) {
+                    console.error(`[observe] Error in ${exp.module.manifest.id}:`, toErrorMessage(e));
+                    observeError = toErrorMessage(e);
+                }
+                res.json({
+                    roomId: room.id,
+                    actorId: existingId,
+                    owner: resolvedOwner,
+                    role: existingP.role,
+                    systemPrompt: existingP.systemPrompt,
+                    reconnected: true,
+                    observation,
+                    observeError,
+                    tools: getToolList(exp.module, existingP.allowedTools),
+                });
+                return;
+            }
+        }
+    }
+    // Unified participant slot matching — works for BOTH humans and AI.
+    // Resolution: (1) manifest.participantSlots, (2) module.participants, (3) legacy agentSlots.
+    const participantSlots = exp.module.manifest?.participantSlots || exp.module.participants;
+    const agentSlots = exp.module.agents || exp.module.manifest?.agentSlots;
+    let slotRole;
+    let slotAllowedTools;
+    let actorIdBase;
+    let slotSystemPrompt;
+    if (participantSlots?.length) {
+        // Count occupants per role (respecting maxInstances)
+        const roleOccupancy = new Map();
+        for (const [, p] of room.participants) {
+            if (p.role)
+                roleOccupancy.set(p.role, (roleOccupancy.get(p.role) || 0) + 1);
+        }
+        // Match: (1) requested role → (2) first open slot matching type → (3) "any" slots
+        const typeMatches = (slotType, joinType) => {
+            if (!slotType || slotType === "any")
+                return true;
+            return slotType === joinType;
+        };
+        const hasCapacity = (slot) => {
+            const max = slot.maxInstances ?? 1;
+            const current = roleOccupancy.get(slot.role) || 0;
+            return current < max;
+        };
+        let matched;
+        if (requestedRole) {
+            matched = participantSlots.find((s) => s.role === requestedRole && typeMatches(s.type, actorType) && hasCapacity(s));
+        }
+        if (!matched) {
+            matched = participantSlots.find((s) => s.type === actorType && hasCapacity(s));
+        }
+        if (!matched) {
+            matched = participantSlots.find((s) => typeMatches(s.type, actorType) && hasCapacity(s));
+        }
+        // Fallback: if all matching slots are full, use the first type-compatible slot anyway
+        // (matches old behavior where agents overflow to agentSlots[0])
+        if (!matched) {
+            matched = participantSlots.find((s) => typeMatches(s.type, actorType));
+        }
+        if (matched) {
+            slotRole = matched.role;
+            slotAllowedTools = matched.allowedTools;
+            slotSystemPrompt = matched.systemPrompt;
+            // actorId uses the owner name, not the role — role lives in participant record
+        }
+    }
+    else if (actorType === "ai" && agentSlots && agentSlots.length > 0) {
+        // Legacy fallback: agentSlots only match AI joins
+        const occupiedRoles = new Set();
+        for (const [, p] of room.participants) {
+            if (p.type === "ai" && p.role)
+                occupiedRoles.add(p.role);
+        }
+        const slot = agentSlots.find((s) => !occupiedRoles.has(s.role)) || agentSlots[0];
+        slotRole = slot.role;
+        slotAllowedTools = slot.allowedTools;
+        slotSystemPrompt = slot.systemPrompt;
+    }
+    const actorId = assignActorId(username, actorType, actorIdBase || resolvedOwner);
+    const participant = {
+        type: actorType, joinedAt: Date.now(), owner: resolvedOwner,
+    };
+    if (slotRole) {
+        participant.role = slotRole;
+    }
+    if (slotAllowedTools) {
+        participant.allowedTools = slotAllowedTools;
+    }
+    if (slotSystemPrompt) {
+        participant.systemPrompt = slotSystemPrompt;
+    }
+    if (!slotRole && requestedRole) {
+        participant.role = requestedRole;
+    }
+    if (agentMode) {
+        participant.agentMode = agentMode;
+    }
+    if (metadata) {
+        participant.metadata = metadata;
+    }
+    room.participants.set(actorId, participant);
+    // Auto-populate _agentRoles when an AI participant joins with a role
+    if (actorType === "ai" && participant.role) {
+        room.sharedState = {
+            ...room.sharedState,
+            _agentRoles: { ...(room.sharedState._agentRoles ?? {}), [actorId]: participant.role },
+        };
+    }
+    // Broadcast presence update
+    broadcastPresenceUpdate(room);
+    // Compute observation so agents get a curated view from the start
+    let observation;
+    let observeError;
+    const joinObserve = exp.module.observe ?? defaultObserve;
+    try {
+        observation = joinObserve(room.sharedState, null, actorId);
+    }
+    catch (e) {
+        console.error(`[observe] Error in ${exp.module.manifest.id}:`, toErrorMessage(e));
+        observeError = toErrorMessage(e);
+    }
+    res.json({
+        roomId: room.id,
+        actorId,
+        owner: resolvedOwner,
+        experienceId: exp.module.manifest.id,
+        sharedState: room.sharedState,
+        participants: room.participantList(),
+        events: room.events.slice(-JOIN_EVENT_HISTORY),
+        tools: getToolList(exp.module, participant.allowedTools),
+        browserUrl: getBaseUrl(),
+        config: room.config,
+        hasRoomConfig: !!exp.module.roomConfig,
+        observation,
+        role: participant.role,
+        allowedTools: participant.allowedTools,
+        systemPrompt: slotSystemPrompt,
+    });
+}
+app.post("/join", (req, res) => handleJoin(getDefaultRoom(), req, res));
+// ── Leave (flat = default room) ────────────────────────────
+function handleLeave(room, req, res) {
+    const { actorId } = req.body;
+    if (!actorId || typeof actorId !== "string") {
+        res.status(400).json({ error: "actorId required" });
+        return;
+    }
+    if (!room.participants.has(actorId)) {
+        res.status(404).json({ error: `Participant '${actorId}' not found in room '${room.id}'` });
+        return;
+    }
+    room.participants.delete(actorId);
+    // Clean up agent memory for this actor (key must match executeTool's memoryKey format)
+    const exp = getExperienceForRoom(room);
+    const memKey = exp ? `${exp.module.manifest.id}:${actorId}` : `${room.id}:${actorId}`;
+    agentMemory.delete(memKey);
+    // Clean up any associated WebSocket connections
+    for (const [ws, wsActorId] of room.wsConnections.entries()) {
+        if (wsActorId === actorId) {
+            room.wsConnections.delete(ws);
+            try {
+                ws.close();
+            }
+            catch { }
+        }
+    }
+    broadcastPresenceUpdate(room);
+    res.json({ left: true, actorId });
+}
+app.post("/leave", (req, res) => handleLeave(getDefaultRoom(), req, res));
+function handleKick(room, kickerActorId, targetActorId) {
+    if (kickerActorId === targetActorId)
+        return { error: "Cannot kick yourself" };
+    const kicker = room.participants.get(kickerActorId);
+    if (!kicker || kicker.type !== "human")
+        return { error: "Only human participants can kick" };
+    if (!room.participants.has(targetActorId))
+        return { error: "Participant not found" };
+    // Remove participant and mark as kicked (track both actorId and owner)
+    const targetParticipant = room.participants.get(targetActorId);
+    room.participants.delete(targetActorId);
+    // Cap kicked sets to prevent unbounded growth on long-running rooms
+    if (room.kickedActors.size >= 500) {
+        const oldest = room.kickedActors.values().next().value;
+        if (oldest)
+            room.kickedActors.delete(oldest);
+    }
+    room.kickedActors.add(targetActorId);
+    if (targetParticipant?.owner) {
+        if (room.kickedOwners.size >= 500) {
+            const oldest = room.kickedOwners.values().next().value;
+            if (oldest)
+                room.kickedOwners.delete(oldest);
+        }
+        room.kickedOwners.add(targetParticipant.owner);
+    }
+    // Close their WS if connected
+    for (const [targetWs, wsActorId] of room.wsConnections.entries()) {
+        if (wsActorId === targetActorId) {
+            try {
+                targetWs.send(JSON.stringify({ type: "kicked", by: kickerActorId }));
+                targetWs.close();
+            }
+            catch { }
+            room.wsConnections.delete(targetWs);
+            break;
+        }
+    }
+    // Broadcast updated presence
+    broadcastPresenceUpdate(room);
+    // Wake up any long-polling agent-context for the kicked agent
+    roomEvents.emit(`room:${room.id}`);
+    return { kicked: true, actorId: targetActorId };
+}
+app.post("/kick", (req, res) => {
+    const result = handleKick(getDefaultRoom(), req.body.kickerActorId, req.body.targetActorId);
+    res.status(result.error ? 400 : 200).json(result);
+});
+// ── Idempotency cache ────────────────────────────────────────
+const idempotencyCache = new Map();
+const IDEMPOTENCY_TTL = 30000; // 30 seconds
+// Cleanup expired entries every 60 seconds
+const _idempotencyCleanupTimer = setInterval(() => {
+    const now = Date.now();
+    for (const [key, entry] of idempotencyCache) {
+        if (now - entry.ts > IDEMPOTENCY_TTL)
+            idempotencyCache.delete(key);
+    }
+}, IDEMPOTENCY_CLEANUP_INTERVAL_MS);
+async function executeTool(room, toolName, actorId, input = {}, owner, expiredFlag) {
+    const exp = getExperienceForRoom(room);
+    if (!exp)
+        throw new Error(experienceNotLoadedError(room.experienceId));
+    // Handle scoped tool calls from embedded experiences
+    let scopeKey;
+    let resolvedToolName = toolName;
+    if (toolName.includes(':')) {
+        const colonIdx = toolName.indexOf(':');
+        scopeKey = toolName.slice(0, colonIdx);
+        resolvedToolName = toolName.slice(colonIdx + 1);
+        // Validate scopeKey against safe identifier pattern and forbidden keys
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(scopeKey) || FORBIDDEN_MERGE_KEYS.has(scopeKey)) {
+            throw new Error(`Invalid scope key in tool name: '${scopeKey}'`);
+        }
+    }
+    // Find tool from the room's experience
+    const tool = exp.module.tools.find((t) => t.name === resolvedToolName);
+    if (!tool) {
+        const available = exp.module.tools.map((t) => t.name).join(", ");
+        throw new ToolNotFoundError(`Tool '${resolvedToolName}' not found. Available tools: ${available}`);
+    }
+    // Check role-based tool restrictions for AI actors
+    // Check both bare name and fully-scoped name (e.g. "hero.move" and "scope:hero.move")
+    const callingParticipant = room.participants.get(actorId);
+    if (callingParticipant?.allowedTools &&
+        !callingParticipant.allowedTools.includes(resolvedToolName) &&
+        !callingParticipant.allowedTools.includes(toolName)) {
+        const role = callingParticipant.role || "ai";
+        const allowed = callingParticipant.allowedTools.join(", ");
+        throw new ToolForbiddenError(`Tool '${resolvedToolName}' is not allowed for role '${role}'. Allowed tools: ${allowed}`);
+    }
+    // Validate input
+    let validatedInput = input;
+    if (tool.input_schema?.parse) {
+        validatedInput = tool.input_schema.parse(input);
+    }
+    // Build ToolCtx
+    const participant = room.participants.get(actorId);
+    const resolvedOwner = participant?.owner || owner || actorId;
+    const memoryKey = `${exp.module.manifest.id}:${actorId}`;
+    const ctx = {
+        roomId: room.id,
+        actorId,
+        owner: resolvedOwner,
+        get state() { return room.sharedState; },
+        setState: (newState) => {
+            if (expiredFlag?.value)
+                return; // Tool timed out — discard late writes
+            room.sharedState = newState;
+            // Warn if state is getting large (>1MB serialized)
+            if (process.env.NODE_ENV !== "test") {
+                try {
+                    const size = JSON.stringify(newState).length;
+                    if (size > 1_000_000) {
+                        console.warn(`[room:${room.id}] State size warning: ${(size / 1_000_000).toFixed(1)}MB. Consider pruning old data.`);
+                    }
+                }
+                catch { }
+            }
+        },
+        timestamp: Date.now(),
+        memory: agentMemory.get(memoryKey) || {},
+        setMemory: (updates) => {
+            const current = agentMemory.get(memoryKey) || {};
+            const merged = deepMerge(current, updates);
+            // Cap per-actor memory at 100 keys to prevent unbounded growth
+            const keys = Object.keys(merged);
+            if (keys.length > 100) {
+                for (const k of keys.slice(0, keys.length - 100))
+                    delete merged[k];
+            }
+            agentMemory.set(memoryKey, merged);
+        },
+        roomConfig: room.config,
+    };
+    // Scope state for embedded experience tool calls
+    if (scopeKey) {
+        Object.defineProperty(ctx, 'state', {
+            get() { return room.sharedState[scopeKey] || {}; },
+            configurable: true,
+        });
+        ctx.setState = (newState) => {
+            if (expiredFlag?.value)
+                return; // Tool timed out — discard late writes
+            room.sharedState = { ...room.sharedState, [scopeKey]: newState };
+        };
+    }
+    // Wire spawnRoom if experience requests the capability
+    const capabilities = exp.module.manifest.requested_capabilities || [];
+    if (capabilities.includes("room.spawn")) {
+        ctx.spawnRoom = async (opts) => {
+            return spawnRoom(room.id, opts);
+        };
+    }
+    // Wire blob operations
+    ctx.setBlob = (key, data) => {
+        const buf = Buffer.from(data);
+        if (buf.length > MAX_BLOB_SIZE)
+            throw new Error(`Blob too large (${buf.length} bytes)`);
+        // Enforce total blob size cap (same logic as REST endpoint)
+        let totalSize = 0;
+        for (const [, meta] of blobMeta)
+            totalSize += meta.size;
+        if (totalSize + buf.length > MAX_TOTAL_BLOBS) {
+            const sorted = [...blobMeta.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+            while (totalSize + buf.length > MAX_TOTAL_BLOBS && sorted.length > 0) {
+                const entry = sorted.shift();
+                if (!entry)
+                    break;
+                const [oldKey, oldMeta] = entry;
+                blobStore.delete(oldKey);
+                blobMeta.delete(oldKey);
+                totalSize -= oldMeta.size;
+            }
+        }
+        blobStore.set(key, buf);
+        blobMeta.set(key, { size: buf.length, createdAt: Date.now(), roomId: room.id });
+        return key;
+    };
+    ctx.getBlob = (key) => {
+        const buf = blobStore.get(key);
+        return buf ? buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) : undefined;
+    };
+    // Execute handler
+    const output = await tool.handler(ctx, validatedInput);
+    // Create event
+    const callerRole = callingParticipant?.role;
+    const event = {
+        id: `${Date.now()}-${actorId}-${Math.random().toString(36).slice(2, 6)}`,
+        ts: Date.now(),
+        actorId,
+        owner: ctx.owner,
+        role: callerRole,
+        tool: toolName,
+        input: validatedInput,
+        output,
+    };
+    // Compute observation (falls back to defaultObserve when experience has none)
+    let observation;
+    const toolObserve = exp.module.observe ?? defaultObserve;
+    try {
+        observation = toolObserve(room.sharedState, event, actorId);
+    }
+    catch (e) {
+        console.error(`[observe] Error in ${exp.module.manifest.id}:`, toErrorMessage(e));
+    }
+    if (observation) {
+        event.observation = observation;
+    }
+    // Append event
+    room.appendEvent(event);
+    // Broadcast state update (delta-compressed)
+    room.broadcastStateUpdate({
+        event,
+        changedBy: actorId,
+        tool: toolName,
+        observation,
+    });
+    // Emit for long-poll listeners
+    roomEvents.emit(`room:${room.id}`);
+    // Notify tick engine if behavior tools were modified (handle scoped tools like "scope:_behavior.set")
+    const baseTool = toolName.includes(':') ? toolName.split(':').pop() : toolName;
+    if (baseTool.startsWith("_behavior.")) {
+        const engine = tickEngines.get(room.id);
+        if (engine)
+            engine.markDirty();
+    }
+    return { tool: toolName, output, observation };
+}
+// ── Single tool HTTP endpoint ───────────────────────────────
+async function handleTool(room, req, res) {
+    const exp = getExperienceForRoom(room);
+    if (!exp) {
+        res.status(500).json({ error: experienceNotLoadedError(room.experienceId) });
+        return;
+    }
+    const toolName = req.params.toolName;
+    const { actorId, input: rawInput = {}, owner } = req.body;
+    // Ensure input is a plain object (not array or primitive)
+    const input = rawInput !== null && typeof rawInput === "object" && !Array.isArray(rawInput) ? rawInput : {};
+    // Reject requests without actorId (prevents bypassing participant/allowedTools checks)
+    if (!actorId) {
+        res.status(400).json({ error: "actorId is required" });
+        return;
+    }
+    // Verify the caller is a participant in this room
+    if (!room.participants.has(actorId)) {
+        res.status(403).json({ error: `Actor '${actorId}' is not a participant in room '${room.id}'. Call /join first.` });
+        return;
+    }
+    // Idempotency: return cached result if same key seen recently (room-scoped)
+    // Placed AFTER participant check to prevent kicked/non-participant actors from replaying cached results
+    const rawIdempotencyKey = req.headers["x-idempotency-key"];
+    // Skip idempotency for excessively long keys (memory amplification prevention)
+    const idempotencyKey = (rawIdempotencyKey && rawIdempotencyKey.length <= 128) ? `${room.id}:${rawIdempotencyKey}` : undefined;
+    if (idempotencyKey) {
+        const cached = idempotencyCache.get(idempotencyKey);
+        if (cached && Date.now() - cached.ts < IDEMPOTENCY_TTL) {
+            res.json({ output: cached.output, cached: true });
+            return;
+        }
+    }
+    try {
+        // Serialize tool execution through per-room queue to prevent state interleaving
+        // Wrap in timeout to prevent a hung handler from permanently blocking the room queue
+        // expiredFlag prevents timed-out handlers from mutating state after the queue moves on
+        const expiredFlag = { value: false };
+        let timeoutHandle;
+        const result = await room.enqueueExecution(() => Promise.race([
+            executeTool(room, toolName, actorId, input, owner, expiredFlag),
+            new Promise((_, reject) => {
+                timeoutHandle = setTimeout(() => {
+                    expiredFlag.value = true;
+                    reject(new Error(`Tool '${toolName}' timed out after ${TOOL_HTTP_TIMEOUT_MS}ms`));
+                }, TOOL_HTTP_TIMEOUT_MS);
+            }),
+        ]));
+        if (timeoutHandle !== undefined)
+            clearTimeout(timeoutHandle);
+        // Cache for idempotency
+        if (idempotencyKey) {
+            idempotencyCache.set(idempotencyKey, { output: result.output, ts: Date.now() });
+        }
+        res.json({ output: result.output, observation: result.observation });
+    }
+    catch (err) {
+        // Determine HTTP status code based on error type
+        let statusCode = 400;
+        if (err instanceof ToolNotFoundError)
+            statusCode = 404;
+        else if (err instanceof ToolForbiddenError)
+            statusCode = 403;
+        // Look up tool for better error formatting (may be undefined if tool not found)
+        const expForError = getExperienceForRoom(room);
+        const toolForError = expForError?.module?.tools?.find((t) => t.name === toolName);
+        const errorMsg = err instanceof ZodError
+            ? formatZodError(err, toolName, toolForError)
+            : (err instanceof Error ? formatHandlerError(err, toolName, toolForError, input) : String(err));
+        const resolvedOwner = owner || room.participants.get(actorId)?.owner;
+        const event = {
+            id: `${Date.now()}-${actorId}-${Math.random().toString(36).slice(2, 6)}`,
+            ts: Date.now(),
+            actorId,
+            ...(resolvedOwner ? { owner: resolvedOwner } : {}),
+            tool: toolName,
+            input,
+            error: errorMsg,
+        };
+        room.appendEvent(event);
+        roomEvents.emit(`room:${room.id}`);
+        res.status(statusCode).json({ error: errorMsg });
+    }
+}
+app.post("/tools/:toolName", (req, res) => handleTool(getDefaultRoom(), req, res));
+// ── Batch tool endpoint ─────────────────────────────────────
+// Execute multiple tools sequentially in a single HTTP request.
+// Each tool sees the state left by the previous call, so order matters.
+// On error, previously successful calls are NOT rolled back.
+// Returns results for all calls, including errors.
+app.post("/tools-batch", (req, res) => handleBatch(getDefaultRoom(), req, res));
+async function handleBatch(room, req, res) {
+    const exp = getExperienceForRoom(room);
+    if (!exp) {
+        res.status(500).json({ error: experienceNotLoadedError(room.experienceId) });
+        return;
+    }
+    const { actorId, owner, calls } = req.body;
+    if (!actorId) {
+        res.status(400).json({ error: "actorId is required" });
+        return;
+    }
+    // Verify the caller is a participant in this room
+    if (actorId && !room.participants.has(actorId)) {
+        res.status(403).json({ error: `Actor '${actorId}' is not a participant in room '${room.id}'. Call /join first.` });
+        return;
+    }
+    if (!Array.isArray(calls) || calls.length === 0) {
+        res.status(400).json({ error: "Missing or empty 'calls' array. Expected: [{ tool, input? }, ...]" });
+        return;
+    }
+    if (calls.length > MAX_BATCH_CALLS) {
+        res.status(400).json({ error: `Too many calls in batch (${calls.length}). Maximum is ${MAX_BATCH_CALLS}.` });
+        return;
+    }
+    // Serialize entire batch through per-room queue so all calls in the batch
+    // are atomic with respect to other concurrent tool calls.
+    // Per-call timeout prevents a hung handler from permanently blocking the room queue.
+    // Aggregate batch timeout prevents total queue hold > 60s.
+    const BATCH_TOTAL_TIMEOUT_MS = 60_000;
+    const batchStart = Date.now();
+    const { results, lastObservation, hasError } = await room.enqueueExecution(async () => {
+        const results = [];
+        let lastObservation;
+        let hasError = false;
+        for (const call of calls) {
+            // Check aggregate batch timeout
+            if (Date.now() - batchStart > BATCH_TOTAL_TIMEOUT_MS) {
+                results.push({ tool: call.tool || "?", error: `Batch total timeout exceeded (${BATCH_TOTAL_TIMEOUT_MS}ms)` });
+                hasError = true;
+                continue;
+            }
+            if (!call.tool) {
+                results.push({ tool: "?", error: "Missing 'tool' field in call" });
+                hasError = true;
+                continue;
+            }
+            try {
+                const batchExpiredFlag = { value: false };
+                let batchTimeoutHandle;
+                const result = await Promise.race([
+                    executeTool(room, call.tool, actorId, (call.input !== null && typeof call.input === 'object' && !Array.isArray(call.input)) ? call.input : {}, owner, batchExpiredFlag),
+                    new Promise((_, reject) => {
+                        batchTimeoutHandle = setTimeout(() => {
+                            batchExpiredFlag.value = true;
+                            reject(new Error(`Tool '${call.tool}' timed out after ${TOOL_HTTP_TIMEOUT_MS}ms`));
+                        }, TOOL_HTTP_TIMEOUT_MS);
+                    }),
+                ]);
+                if (batchTimeoutHandle !== undefined)
+                    clearTimeout(batchTimeoutHandle);
+                results.push(result);
+                if (result.observation)
+                    lastObservation = result.observation;
+            }
+            catch (err) {
+                const errorMsg = err instanceof ZodError
+                    ? formatZodError(err, call.tool)
+                    : (err instanceof Error ? err.message : String(err));
+                // Log error event
+                const resolvedBatchOwner = owner || room.participants.get(actorId)?.owner;
+                const event = {
+                    id: `${Date.now()}-${actorId}-${Math.random().toString(36).slice(2, 6)}`,
+                    ts: Date.now(),
+                    actorId,
+                    ...(resolvedBatchOwner ? { owner: resolvedBatchOwner } : {}),
+                    tool: call.tool,
+                    input: call.input || {},
+                    error: errorMsg,
+                };
+                room.appendEvent(event);
+                roomEvents.emit(`room:${room.id}`);
+                results.push({ tool: call.tool, error: errorMsg });
+                hasError = true;
+            }
+        }
+        return { results, lastObservation, hasError };
+    });
+    // Return 207 (Multi-Status) if there were mixed results, 200 if all succeeded
+    const statusCode = hasError ? 207 : 200;
+    res.status(statusCode).json({ results, observation: lastObservation });
+}
+// ── Get events (supports long-poll via ?timeout=N) ──────────
+function handleEvents(room, req, res) {
+    const since = queryInt(req.query.since);
+    const timeout = Math.min(queryInt(req.query.timeout), LONG_POLL_MAX_TIMEOUT_MS);
+    const requestingActorId = queryString(req.query.actorId);
+    // Helper: compute observation for current state
+    const computeObservation = (events) => {
+        const exp = getExperienceForRoom(room);
+        if (!requestingActorId)
+            return undefined;
+        const agentObserve = exp?.module?.observe ?? defaultObserve;
+        try {
+            const lastEvent = events.length > 0 ? events[events.length - 1] : null;
+            return agentObserve(room.sharedState, lastEvent, requestingActorId);
+        }
+        catch (e) {
+            console.error(`[observe] Error in ${exp?.module?.manifest?.id}:`, toErrorMessage(e));
+            return undefined;
+        }
+    };
+    const getNewEvents = () => room.events.filter((e) => e.ts > since && e.actorId !== requestingActorId);
+    let newEvents = getNewEvents();
+    if (newEvents.length > 0 || timeout === 0) {
+        const observation = computeObservation(newEvents);
+        res.json({
+            events: newEvents,
+            sharedState: room.sharedState,
+            participants: room.participantList(),
+            observation,
+        });
+        return;
+    }
+    // Long-poll: wait for event emission or timeout
+    let responded = false;
+    let batchTimer = null;
+    const respond = () => {
+        if (responded)
+            return;
+        responded = true;
+        clearTimeout(timer);
+        if (batchTimer) {
+            clearTimeout(batchTimer);
+            batchTimer = null;
+        }
+        roomEvents.removeListener(`room:${room.id}`, onEvent);
+        newEvents = getNewEvents();
+        const observation = computeObservation(newEvents);
+        res.json({
+            events: newEvents,
+            sharedState: room.sharedState,
+            participants: room.participantList(),
+            observation,
+        });
+    };
+    const timer = setTimeout(respond, timeout);
+    const onEvent = () => {
+        if (responded)
+            return;
+        if (batchTimer)
+            return; // Deduplicate rapid events
+        // Small delay to batch rapid events
+        batchTimer = setTimeout(() => {
+            batchTimer = null;
+            if (responded)
+                return;
+            // Only respond if there are actual new tool events.
+            // Streams modify state and emit roomEvents but don't create
+            // event log entries — ignore those wake-ups so the long-poll
+            // keeps waiting for real tool events (like _chat.send).
+            const pending = getNewEvents();
+            if (pending.length > 0) {
+                respond();
+            }
+        }, EVENT_BATCH_DEBOUNCE_MS);
+    };
+    roomEvents.on(`room:${room.id}`, onEvent);
+    // Cleanup on client disconnect
+    req.on("close", () => {
+        responded = true;
+        clearTimeout(timer);
+        if (batchTimer)
+            clearTimeout(batchTimer);
+        roomEvents.removeListener(`room:${room.id}`, onEvent);
+    });
+}
+app.get("/events", (req, res) => handleEvents(getDefaultRoom(), req, res));
+// ── Cross-room events (watch all rooms) ────────────────────
+app.get("/events/all", (req, res) => {
+    const since = queryInt(req.query.since);
+    const timeout = Math.min(queryInt(req.query.timeout), LONG_POLL_MAX_TIMEOUT_MS);
+    const requestingActorId = queryString(req.query.actorId);
+    const getAllEvents = () => {
+        const allEvents = [];
+        for (const room of rooms.values()) {
+            for (const e of room.events) {
+                if (e.ts > since) {
+                    // Self-filter: skip own events (consistent with /events and /agent-context)
+                    if (requestingActorId && e.actorId === requestingActorId)
+                        continue;
+                    allEvents.push({ ...e, roomId: room.id });
+                }
+            }
+        }
+        allEvents.sort((a, b) => a.ts - b.ts);
+        return allEvents;
+    };
+    const getRoomSummaries = () => Array.from(rooms.values()).map((room) => ({
+        roomId: room.id,
+        experienceId: room.experienceId,
+        participants: room.participantList(),
+        eventCount: room.events.length,
+    }));
+    let newEvents = getAllEvents();
+    if (newEvents.length > 0 || timeout === 0) {
+        res.json({ events: newEvents, rooms: getRoomSummaries() });
+        return;
+    }
+    // Long-poll: wait for any room event
+    let responded = false;
+    let batchTimer = null;
+    const respond = () => {
+        if (responded)
+            return;
+        responded = true;
+        clearTimeout(timer);
+        if (batchTimer) {
+            clearTimeout(batchTimer);
+            batchTimer = null;
+        }
+        clearInterval(newRoomCheck);
+        for (const rid of subscribedRoomIds) {
+            roomEvents.removeListener(`room:${rid}`, onEvent);
+        }
+        res.json({ events: getAllEvents(), rooms: getRoomSummaries() });
+    };
+    const timer = setTimeout(respond, timeout);
+    const onEvent = () => {
+        if (responded)
+            return;
+        if (batchTimer)
+            return;
+        batchTimer = setTimeout(() => {
+            batchTimer = null;
+            if (responded)
+                return;
+            // Only respond if there are actual new tool events — ignore
+            // stream-only wake-ups (streams don't create event log entries).
+            const pending = getAllEvents();
+            if (pending.length > 0)
+                respond();
+        }, EVENT_BATCH_DEBOUNCE_MS);
+    };
+    // Listen on all existing rooms + track subscribed IDs for cleanup
+    const subscribedRoomIds = new Set();
+    for (const room of rooms.values()) {
+        roomEvents.on(`room:${room.id}`, onEvent);
+        subscribedRoomIds.add(room.id);
+    }
+    // Also check periodically for newly spawned rooms during long-poll
+    const newRoomCheck = setInterval(() => {
+        if (responded) {
+            clearInterval(newRoomCheck);
+            return;
+        }
+        for (const room of rooms.values()) {
+            if (!subscribedRoomIds.has(room.id)) {
+                roomEvents.on(`room:${room.id}`, onEvent);
+                subscribedRoomIds.add(room.id);
+            }
+        }
+    }, 2000);
+    req.on("close", () => {
+        responded = true;
+        clearTimeout(timer);
+        if (batchTimer)
+            clearTimeout(batchTimer);
+        clearInterval(newRoomCheck);
+        for (const rid of subscribedRoomIds) {
+            roomEvents.removeListener(`room:${rid}`, onEvent);
+        }
+    });
+});
+// ── Browser error capture ──────────────────────────────────────
+// The viewer POSTs browser errors here so the agent can see them
+// via /agent-context and fix them automatically.
+const roomBrowserErrors = new Map();
+const MAX_BROWSER_ERRORS = 20;
+const lastBrowserErrorAt = new Map(); // Rate limit per room
+const BROWSER_ERROR_COOLDOWN_MS = 200; // Min interval between error-triggered wake-ups
+const MAX_BROWSER_ERROR_MSG_LEN = 500; // Truncate overlong error messages
+app.post("/browser-error", (req, res) => {
+    const { message, roomId: errorRoomId } = req.body || {};
+    if (typeof message === "string" && message.trim()) {
+        // Truncate message to prevent memory bloat
+        const trimmed = message.trim().slice(0, MAX_BROWSER_ERROR_MSG_LEN);
+        const now = Date.now();
+        // Scope errors to the room they came from
+        const targetRoom = (typeof errorRoomId === "string" && rooms.has(errorRoomId))
+            ? errorRoomId
+            : getDefaultRoom().id;
+        let errors = roomBrowserErrors.get(targetRoom);
+        if (!errors) {
+            errors = [];
+            roomBrowserErrors.set(targetRoom, errors);
+        }
+        errors.push({ message: trimmed, ts: now });
+        if (errors.length > MAX_BROWSER_ERRORS) {
+            errors.splice(0, errors.length - MAX_BROWSER_ERRORS);
+        }
+        // Rate-limit wake-ups per room
+        const lastErrorAt = lastBrowserErrorAt.get(targetRoom) || 0;
+        if (now - lastErrorAt >= BROWSER_ERROR_COOLDOWN_MS) {
+            lastBrowserErrorAt.set(targetRoom, now);
+            roomEvents.emit(`room:${targetRoom}`);
+        }
+    }
+    res.json({ ok: true });
+});
+// ── Agent context (combined events + observe for Stop hook) ──
+app.get("/agent-context", (req, res) => {
+    const rawSince = queryInt(req.query.since);
+    const timeout = Math.min(queryInt(req.query.timeout), AGENT_CONTEXT_MAX_TIMEOUT_MS);
+    const actorId = queryString(req.query.actorId) || "unknown";
+    const requestedRoomId = queryString(req.query.roomId);
+    // Find the agent's actual room:
+    // 1. Explicit roomId query param (preferred)
+    // 2. Search all rooms for the actorId
+    // 3. Fall back to default room
+    let agentRoom = getDefaultRoom();
+    if (requestedRoomId) {
+        const r = getRoom(requestedRoomId);
+        if (r)
+            agentRoom = r;
+    }
+    else {
+        for (const room of rooms.values()) {
+            if (room.participants.has(actorId)) {
+                agentRoom = room;
+                break;
+            }
+        }
+    }
+    // Resolve owner: explicit query param > participant record from agent's room
+    // Never fall back to actorId.split — that caused multi-agent collisions
+    // where two agents both resolved to the same prefix and filtered each other out
+    const participantEntry = agentRoom.participants.get(actorId);
+    const requestingOwner = queryString(req.query.owner) || participantEntry?.owner;
+    // Use server-tracked cursor when client sends since=0 (e.g. stop hook runs
+    // as a fresh process each time and can't persist cursors between invocations).
+    // This makes the server the true source of truth for cursor state.
+    const since = (rawSince === 0 && participantEntry?.eventCursor)
+        ? participantEntry.eventCursor
+        : rawSince;
+    // Update lastPollAt for AI heartbeat tracking
+    if (participantEntry) {
+        participantEntry.lastPollAt = Date.now();
+    }
+    // Gather events from ALL rooms (not just default) so the agent sees sub-room activity
+    const getAllNewEvents = () => {
+        const allEvents = [];
+        for (const room of rooms.values()) {
+            for (const e of room.events) {
+                // Self-filter: skip events from the same owner
+                // If either side has no owner, don't filter (safe default: show the event)
+                if (requestingOwner && e.owner === requestingOwner)
+                    continue;
+                // Skip tick engine events — agents react to observations, not individual ticks
+                if (e.actorId === "_tick-engine" || e.owner === "_system")
+                    continue;
+                if (e.ts > since) {
+                    allEvents.push({ ...e, roomId: room.id });
+                }
+            }
+        }
+        return allEvents.sort((a, b) => a.ts - b.ts);
+    };
+    // Collect all participants and available tools across rooms
+    const getAllParticipants = () => {
+        const all = new Set();
+        for (const room of rooms.values()) {
+            for (const p of room.participantList())
+                all.add(p);
+        }
+        return [...all];
+    };
+    // Resolve the requesting agent's allowed tools from their participant record in their actual room
+    const requestingParticipant = agentRoom.participants.get(actorId);
+    const agentAllowedTools = requestingParticipant?.allowedTools;
+    const getAllRoomInfo = () => {
+        const info = {};
+        for (const room of rooms.values()) {
+            const exp = getExperienceForRoom(room);
+            let toolNames = exp?.module?.tools?.map((t) => t.name) || [];
+            if (agentAllowedTools)
+                toolNames = toolNames.filter((n) => agentAllowedTools.includes(n));
+            info[room.id] = {
+                experience: exp?.module?.manifest?.id || room.experienceId || "unknown",
+                tools: toolNames,
+                participants: room.participantList(),
+            };
+        }
+        return info;
+    };
+    const buildResponse = () => {
+        // Check if agentRoom was deleted during long-poll
+        if (!rooms.has(agentRoom.id)) {
+            return {
+                events: [],
+                observation: { done: true, reason: "room_deleted" },
+                participants: getAllParticipants(),
+                rooms: getAllRoomInfo(),
+            };
+        }
+        const events = getAllNewEvents();
+        // Check if this agent was kicked — return done:true so the stop hook archives the state file
+        if (agentRoom.kickedActors.has(actorId)) {
+            agentRoom.kickedActors.delete(actorId); // One-shot: clear after notifying
+            return {
+                events: [],
+                observation: { done: true, reason: "kicked" },
+                participants: getAllParticipants(),
+                rooms: getAllRoomInfo(),
+            };
+        }
+        // Compute observation from the agent's actual room (not always default)
+        const observeExp = getExperienceForRoom(agentRoom);
+        let observation;
+        let observeError;
+        if (observeExp?.module?.observe) {
+            try {
+                const lastEvent = events.length > 0 ? events[events.length - 1] : null;
+                observation = observeExp.module.observe(agentRoom.sharedState, lastEvent, actorId);
+            }
+            catch (e) {
+                console.error(`[observe] Error in ${observeExp.module.manifest?.id}:`, toErrorMessage(e));
+                observeError = toErrorMessage(e);
+            }
+        }
+        // Find the agent's most recent error (own events are filtered from `events`,
+        // so scan raw room events for this actor's errors since the last poll)
+        let lastError;
+        for (const room of rooms.values()) {
+            for (const e of room.events) {
+                if (e.ts > since && e.error && e.actorId === actorId) {
+                    lastError = { tool: e.tool, error: e.error };
+                }
+            }
+        }
+        // Collect tick engine status across all rooms
+        const tickStatus = {};
+        for (const [roomId, engine] of tickEngines) {
+            const status = engine.getStatus();
+            tickStatus[roomId] = {
+                enabled: status.enabled,
+                tickCount: status.tickCount,
+            };
+        }
+        // Collect browser errors for this agent's room since last poll
+        const roomErrors = roomBrowserErrors.get(agentRoom.id) || [];
+        const recentBrowserErrors = roomErrors.filter(e => e.ts > since);
+        // Clear reported errors for this room so they don't repeat
+        if (recentBrowserErrors.length > 0) {
+            roomBrowserErrors.set(agentRoom.id, roomErrors.filter(e => e.ts <= since));
+        }
+        // Track eventCursor server-side so agents don't need local state files
+        let eventCursor;
+        if (events.length > 0 && participantEntry) {
+            eventCursor = Math.max(participantEntry.eventCursor || 0, ...events.map(e => e.ts));
+            participantEntry.eventCursor = eventCursor;
+        }
+        else if (participantEntry?.eventCursor) {
+            eventCursor = participantEntry.eventCursor;
+        }
+        return {
+            events,
+            observation: observation || {},
+            observeError,
+            lastError,
+            browserErrors: recentBrowserErrors.length > 0 ? recentBrowserErrors : undefined,
+            participants: getAllParticipants(),
+            rooms: getAllRoomInfo(),
+            tickEngines: Object.keys(tickStatus).length > 0 ? tickStatus : undefined,
+            eventCursor,
+        };
+    };
+    // If events, browser errors, or kicked status are already available, respond immediately
+    let newEvents = getAllNewEvents();
+    const pendingBrowserErrors = (roomBrowserErrors.get(agentRoom.id) || []).filter(e => e.ts > since);
+    const isKicked = agentRoom.kickedActors.has(actorId);
+    if (newEvents.length > 0 || pendingBrowserErrors.length > 0 || isKicked || timeout === 0) {
+        res.json(buildResponse());
+        return;
+    }
+    // Long-poll: wait for events or timeout
+    let responded = false;
+    let batchTimer = null;
+    const respond = () => {
+        if (responded)
+            return;
+        responded = true;
+        clearTimeout(timer);
+        if (batchTimer) {
+            clearTimeout(batchTimer);
+            batchTimer = null;
+        }
+        clearInterval(newRoomCheck);
+        // Remove listeners from all subscribed rooms (tracked set handles deleted rooms)
+        for (const rid of subscribedRoomIds) {
+            roomEvents.removeListener(`room:${rid}`, onEvent);
+        }
+        res.json(buildResponse());
+    };
+    const timer = setTimeout(respond, timeout);
+    const onEvent = () => {
+        if (responded)
+            return;
+        if (batchTimer)
+            return;
+        batchTimer = setTimeout(() => {
+            batchTimer = null;
+            if (responded)
+                return;
+            const pending = getAllNewEvents();
+            if (pending.length > 0 || agentRoom.kickedActors.has(actorId))
+                respond();
+        }, EVENT_BATCH_DEBOUNCE_MS);
+    };
+    // Listen on ALL rooms + track subscribed IDs for cleanup
+    const subscribedRoomIds = new Set();
+    for (const room of rooms.values()) {
+        roomEvents.on(`room:${room.id}`, onEvent);
+        subscribedRoomIds.add(room.id);
+    }
+    // Check periodically for newly spawned rooms during long-poll
+    const newRoomCheck = setInterval(() => {
+        if (responded) {
+            clearInterval(newRoomCheck);
+            return;
+        }
+        for (const room of rooms.values()) {
+            if (!subscribedRoomIds.has(room.id)) {
+                roomEvents.on(`room:${room.id}`, onEvent);
+                subscribedRoomIds.add(room.id);
+            }
+        }
+    }, 2000);
+    req.on("close", () => {
+        responded = true;
+        clearTimeout(timer);
+        if (batchTimer)
+            clearTimeout(batchTimer);
+        clearInterval(newRoomCheck);
+        for (const rid of subscribedRoomIds) {
+            roomEvents.removeListener(`room:${rid}`, onEvent);
+        }
+    });
+});
+// ── Serve client bundle ────────────────────────────────────
+app.get("/bundle", async (_req, res) => {
+    // Wait for any in-progress hot-reload to complete before serving
+    if (rebuildingPromise)
+        await rebuildingPromise;
+    const host = experienceCache.get(hostExperienceId);
+    res.setHeader("Content-Type", "text/javascript");
+    setNoCacheHeaders(res);
+    res.send(host?.clientBundle || "");
+});
+// ── Memory endpoints ───────────────────────────────────────
+app.get("/memory", (req, res) => {
+    const key = queryString(req.query.key);
+    if (!key) {
+        res.json({});
+        return;
+    }
+    res.json(agentMemory.get(key) || {});
+});
+app.post("/memory", (req, res) => {
+    const { key, updates } = req.body;
+    if (!key) {
+        res.status(400).json({ error: "key required" });
+        return;
+    }
+    if (!updates || typeof updates !== "object" || Array.isArray(updates)) {
+        res.status(400).json({ error: "updates must be a plain object" });
+        return;
+    }
+    const current = agentMemory.get(key) || {};
+    const merged = deepMerge(current, updates);
+    // Cap per-key object to 100 keys (same limit as tool-path setMemory)
+    const keys = Object.keys(merged);
+    if (keys.length > 100) {
+        res.status(400).json({ error: `Memory key limit exceeded (${keys.length}/100)` });
+        return;
+    }
+    agentMemory.set(key, merged);
+    res.json({ saved: true });
+});
+// ── Blob store endpoints ──────────────────────────────────
+app.get("/blobs/:key", (req, res) => {
+    const blob = blobStore.get(req.params.key);
+    if (!blob) {
+        res.status(404).json({ error: "Blob not found" });
+        return;
+    }
+    res.setHeader("Content-Type", "application/octet-stream");
+    res.setHeader("Content-Length", String(blob.length));
+    res.setHeader("Cache-Control", `public, max-age=${BLOB_CACHE_MAX_AGE_SECONDS}`);
+    res.send(blob);
+});
+app.post("/blobs/:key", express.raw({ limit: "10mb", type: "*/*" }), (req, res) => {
+    const key = req.params.key;
+    const { roomId, actorId } = req.query;
+    // Validate blob key: safe characters only, no prototype-pollution keys
+    if (!/^[a-zA-Z0-9._\-]+$/.test(key) || key.length > 256) {
+        res.status(400).json({ error: "Invalid blob key format" });
+        return;
+    }
+    if (key === "__proto__" || key === "constructor" || key === "prototype") {
+        res.status(400).json({ error: "Reserved blob key name" });
+        return;
+    }
+    if (!Buffer.isBuffer(req.body) || req.body.length === 0) {
+        res.status(400).json({ error: "Empty or invalid blob data" });
+        return;
+    }
+    if (req.body.length > MAX_BLOB_SIZE) {
+        res.status(413).json({ error: `Blob too large (${req.body.length} bytes, max ${MAX_BLOB_SIZE})` });
+        return;
+    }
+    // Check total size
+    let totalSize = 0;
+    for (const [, meta] of blobMeta)
+        totalSize += meta.size;
+    if (totalSize + req.body.length > MAX_TOTAL_BLOBS) {
+        // Garbage collect: remove oldest blobs until we have space
+        const sorted = [...blobMeta.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+        while (totalSize + req.body.length > MAX_TOTAL_BLOBS && sorted.length > 0) {
+            const [oldKey, oldMeta] = sorted.shift();
+            blobStore.delete(oldKey);
+            blobMeta.delete(oldKey);
+            totalSize -= oldMeta.size;
+        }
+    }
+    blobStore.set(key, req.body);
+    blobMeta.set(key, { size: req.body.length, createdAt: Date.now(), roomId: roomId || "local" });
+    res.json({ key, size: req.body.length });
+});
+app.delete("/blobs/:key", (req, res) => {
+    const key = req.params.key;
+    // Validate key format (same safe-char check as POST)
+    if (!/^[a-zA-Z0-9_\-.:]+$/.test(key) || key.length > 200) {
+        res.status(400).json({ error: "Invalid blob key" });
+        return;
+    }
+    if (!blobStore.has(key)) {
+        res.status(404).json({ error: "Blob not found" });
+        return;
+    }
+    blobStore.delete(key);
+    blobMeta.delete(key);
+    res.json({ deleted: true });
+});
+app.get("/blobs", (_req, res) => {
+    const list = [...blobMeta.entries()].map(([key, meta]) => ({ key, ...meta }));
+    res.json(list);
+});
+// ── Screenshot capture ────────────────────────────────────
+const pendingScreenshots = new Map();
+app.get("/screenshot", (req, res) => {
+    // Find an open viewer WebSocket connection (check default room first, then all rooms)
+    let viewerWs = null;
+    for (const room of rooms.values()) {
+        for (const [ws] of room.wsConnections) {
+            if (ws.readyState === WebSocket.OPEN) {
+                viewerWs = ws;
+                break;
+            }
+        }
+        if (viewerWs)
+            break;
+    }
+    if (!viewerWs) {
+        res.status(503).json({ error: `No browser viewer connected. Open ${getBaseUrl()} first.` });
+        return;
+    }
+    const requestId = `ss-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    const timeoutMs = Math.min(queryInt(req.query.timeout) || SCREENSHOT_DEFAULT_TIMEOUT_MS, SCREENSHOT_MAX_TIMEOUT_MS);
+    const promise = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            pendingScreenshots.delete(requestId);
+            reject(new Error("Screenshot timeout"));
+        }, timeoutMs);
+        pendingScreenshots.set(requestId, { resolve, reject, timer, viewerWs: viewerWs });
+    });
+    // Clean up if HTTP client disconnects before screenshot arrives
+    req.on("close", () => {
+        const p = pendingScreenshots.get(requestId);
+        if (p) {
+            clearTimeout(p.timer);
+            pendingScreenshots.delete(requestId);
+            p.reject(new Error("Client disconnected"));
+        }
+    });
+    // Ask the viewer to capture
+    try {
+        viewerWs.send(JSON.stringify({ type: "screenshot_request", id: requestId }));
+    }
+    catch (err) {
+        const p = pendingScreenshots.get(requestId);
+        if (p) {
+            clearTimeout(p.timer);
+            pendingScreenshots.delete(requestId);
+            p.reject(new Error("WebSocket send failed"));
+        }
+    }
+    promise
+        .then((pngBuffer) => {
+        res.setHeader("Content-Type", "image/png");
+        res.setHeader("Content-Length", String(pngBuffer.length));
+        res.send(pngBuffer);
+    })
+        .catch((err) => {
+        res.status(500).json({ error: toErrorMessage(err) });
+    });
+});
+// ── Sync (re-bundle) ──────────────────────────────────────
+app.post("/sync", async (_req, res) => {
+    try {
+        // Stop tick engines for host rooms before reloading (prevents ghost tick loops)
+        for (const room of rooms.values()) {
+            if (room.experienceId === hostExperienceId) {
+                stopTickEngine(room.id);
+            }
+        }
+        await loadHost();
+        const hostLoaded = experienceCache.get(hostExperienceId);
+        // Broadcast and restart tick engines for rooms running the host experience
+        for (const room of rooms.values()) {
+            if (room.experienceId === hostExperienceId) {
+                room.broadcastToAll({ type: "experience_updated" });
+                if (hostLoaded)
+                    maybeStartTickEngine(room, hostLoaded);
+            }
+        }
+        const host = getHostExperience();
+        res.json({ synced: true, title: host?.manifest?.title });
+    }
+    catch (err) {
+        res.status(500).json({ error: toErrorMessage(err) });
+    }
+});
+// ── Room management routes ─────────────────────────────────
+app.get("/rooms", (_req, res) => {
+    const roomList = Array.from(rooms.values()).map((room) => {
+        const exp = experienceCache.get(room.experienceId);
+        const st = room.sharedState;
+        const flags = {};
+        if (st._recruitment)
+            flags._recruitment = st._recruitment;
+        if (st._announcement)
+            flags._announcement = st._announcement;
+        return {
+            roomId: room.id,
+            experienceId: room.experienceId,
+            experienceTitle: exp?.module?.manifest?.title || room.experienceId,
+            participants: room.participantDetails(),
+            participantCount: room.participants.size,
+            eventCount: room.events.length,
+            parentRoomId: room.parentRoomId,
+            childRoomIds: room.childRoomIds,
+            config: room.config,
+            flags,
+        };
+    });
+    res.json(roomList);
+});
+app.post("/rooms/spawn", async (req, res) => {
+    try {
+        const { experienceId, name, initialState, linkBack, sourceRoomId, config } = req.body;
+        const source = sourceRoomId || DEFAULT_ROOM_ID;
+        // Validate sourceRoomId exists (prevents rate limit bypass via crafted sourceRoomId)
+        if (sourceRoomId && !rooms.has(source)) {
+            res.status(400).json({ error: `Source room '${source}' not found` });
+            return;
+        }
+        // Only the actual library room bypasses rate limiting
+        const skipRateLimit = source === "library" && rooms.has("library");
+        const result = await spawnRoom(source, {
+            experienceId: experienceId || hostExperienceId,
+            name,
+            initialState,
+            linkBack,
+            config,
+            skipRateLimit,
+        });
+        res.json(result);
+    }
+    catch (err) {
+        res.status(400).json({ error: toErrorMessage(err) });
+    }
+});
+// ── Room config schema endpoint ────────────────────────────
+app.get("/rooms/config-schema", async (req, res) => {
+    try {
+        const loaded = await getLoadedExperience();
+        const roomConfigDef = loaded.module?.roomConfig;
+        if (!roomConfigDef) {
+            res.json({ hasConfig: false, experienceId: hostExperienceId });
+            return;
+        }
+        const schema = roomConfigDef.schema
+            ? zodToJsonSchema(roomConfigDef.schema)
+            : {};
+        res.json({
+            hasConfig: true,
+            experienceId: hostExperienceId,
+            schema,
+            defaults: roomConfigDef.defaults || {},
+            presets: Object.keys(roomConfigDef.presets || {}),
+            description: roomConfigDef.description || "",
+        });
+    }
+    catch (err) {
+        res.status(400).json({ error: toErrorMessage(err) });
+    }
+});
+// ── Tick status endpoint ───────────────────────────────────
+app.get("/rooms/:roomId/tick-status", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room) {
+        res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+        return;
+    }
+    const engine = tickEngines.get(room.id);
+    if (!engine) {
+        res.json({ enabled: false, tickRateMs: 0, tickCount: 0, behaviorsTotal: 0, behaviorsEnabled: 0, lastTick: null });
+        return;
+    }
+    res.json(engine.getStatus());
+});
+// ── Experiences endpoint (discovery for agents) ────────────
+app.get("/experiences", async (_req, res) => {
+    try {
+        const loaded = await getLoadedExperience();
+        res.json([{
+                id: loaded.module.manifest.id,
+                title: loaded.module.manifest.title,
+                description: loaded.module.manifest.description,
+                version: loaded.module.manifest.version,
+                loaded: true,
+                hasRoomConfig: !!loaded.module.roomConfig,
+                category: loaded.module.manifest.category,
+                tags: loaded.module.manifest.tags,
+            }]);
+    }
+    catch (err) {
+        res.json([]);
+    }
+});
+app.get("/rooms/:roomId", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room) {
+        res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+        return;
+    }
+    const exp = getExperienceForRoom(room);
+    let observation;
+    const roomObserve = exp?.module?.observe ?? defaultObserve;
+    const observeActorId = typeof req.query.actorId === "string" ? req.query.actorId : "viewer";
+    try {
+        observation = roomObserve(room.sharedState, null, observeActorId);
+    }
+    catch (err) {
+        console.warn(`[observe] Error: ${toErrorMessage(err)}`);
+    }
+    res.json({
+        roomId: room.id,
+        experienceId: room.experienceId,
+        sharedState: room.sharedState,
+        stateVersion: room.stateVersion,
+        participants: room.participantList(),
+        events: room.events.slice(-ROOM_STATE_EVENT_HISTORY),
+        parentRoomId: room.parentRoomId,
+        childRoomIds: room.childRoomIds,
+        config: room.config,
+        observation,
+    });
+});
+app.get("/rooms/:roomId/links", (req, res) => {
+    const roomId = req.params.roomId;
+    const links = roomLinks.filter((l) => l.parentRoomId === roomId || l.childRoomId === roomId);
+    res.json(links);
+});
+// ── Slots (query participant slot definitions + occupancy) ────
+app.get("/rooms/:roomId/slots", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room) {
+        res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+        return;
+    }
+    const exp = getExperienceForRoom(room);
+    const slots = exp?.module?.manifest?.participantSlots || exp?.module?.participants || [];
+    res.json({
+        slots,
+        participantDetails: room.participantDetails(),
+    });
+});
+app.post("/rooms/:roomId/join", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room) {
+        res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+        return;
+    }
+    handleJoin(room, req, res);
+});
+app.post("/rooms/:roomId/leave", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room) {
+        res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+        return;
+    }
+    handleLeave(room, req, res);
+});
+app.post("/rooms/:roomId/kick", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room) {
+        res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+        return;
+    }
+    const result = handleKick(room, req.body.kickerActorId, req.body.targetActorId);
+    res.status(result.error ? 400 : 200).json(result);
+});
+// ── Reset room to initial state ──────────────────────────────
+app.post("/rooms/:roomId/reset", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room) {
+        res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+        return;
+    }
+    const loaded = getExperienceForRoom(room);
+    if (!loaded) {
+        res.status(500).json({ error: experienceNotLoadedError(room.experienceId) });
+        return;
+    }
+    const config = resolveRoomConfig(loaded.module, room.config);
+    const initialState = resolveInitialState(loaded.module, config);
+    room.sharedState = initialState;
+    room.events.length = 0;
+    // Reset all participant event cursors so agents see the reset event
+    for (const [, p] of room.participants) {
+        p.eventCursor = 0;
+    }
+    // Append a reset event so stop hooks see it
+    const resetEvent = {
+        id: `${Date.now()}-system-${Math.random().toString(36).slice(2, 6)}`,
+        ts: Date.now(),
+        actorId: "system",
+        tool: "_reset",
+        input: {},
+        output: { reset: true },
+    };
+    room.appendEvent(resetEvent);
+    roomEvents.emit(`room:${room.id}`);
+    // Reset sends full state (not delta) since the entire state changed
+    room.resetDeltaTracking();
+    room.broadcastStateUpdate({
+        changedBy: "system",
+        tool: "_reset",
+    }, true);
+    res.json({ ok: true });
+});
+// ── Delete room (cleanup spawned rooms) ─────────────────────
+app.delete("/rooms/:roomId", (req, res) => {
+    const roomId = req.params.roomId;
+    if (roomId === DEFAULT_ROOM_ID) {
+        res.status(400).json({ error: "Cannot delete the default room." });
+        return;
+    }
+    const room = getRoom(roomId);
+    if (!room) {
+        res.status(404).json({ error: roomNotFoundError(roomId) });
+        return;
+    }
+    // Stop tick engine
+    stopTickEngine(roomId);
+    cleanupRoomLinks(roomId, room);
+    // Clean up agent memory entries before clearing participants
+    const expForDelete = getExperienceForRoom(room);
+    const expIdForDelete = expForDelete?.module?.manifest?.id || room.experienceId;
+    for (const [actorId] of room.participants) {
+        agentMemory.delete(`${expIdForDelete}:${actorId}`);
+    }
+    // Close all WebSocket connections for this room
+    for (const [ws] of room.wsConnections) {
+        try {
+            ws.close(1001, "Room deleted");
+        }
+        catch { }
+    }
+    room.wsConnections.clear();
+    room.participants.clear();
+    // Clean up blobs associated with this room
+    for (const [key, meta] of blobMeta) {
+        if (meta.roomId === roomId) {
+            blobStore.delete(key);
+            blobMeta.delete(key);
+        }
+    }
+    // Wake up any long-poll listeners waiting on this room
+    roomEvents.emit(`room:${roomId}`);
+    // Clean up event listeners, GC tracking, and room data
+    roomEvents.removeAllListeners(`room:${roomId}`);
+    rooms.delete(roomId);
+    roomBrowserErrors.delete(roomId);
+    lastBrowserErrorAt.delete(roomId);
+    spawnCounts.delete(roomId);
+    roomEmptySince.delete(roomId);
+    res.json({ deleted: true, roomId });
+});
+app.post("/rooms/:roomId/tools/:toolName", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room) {
+        res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+        return;
+    }
+    handleTool(room, req, res);
+});
+app.post("/rooms/:roomId/tools-batch", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room) {
+        res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+        return;
+    }
+    handleBatch(room, req, res);
+});
+// ── Stream endpoints (REST API for MCP agents) ──────────────
+function handleStreamRequest(room, streamName, req, res) {
+    const exp = getExperienceForRoom(room);
+    if (!exp?.module?.streams) {
+        res.status(404).json({ error: "No streams defined" });
+        return;
+    }
+    const streamDef = exp.module.streams.find((s) => s.name === streamName);
+    if (!streamDef) {
+        res.status(404).json({ error: `Stream '${streamName}' not found` });
+        return;
+    }
+    const { actorId, input } = req.body;
+    // Require actorId — anonymous stream writes are not allowed
+    if (!actorId) {
+        res.status(400).json({ error: "actorId is required for stream updates" });
+        return;
+    }
+    // Verify the caller is a participant
+    if (!room.participants.has(actorId)) {
+        res.status(403).json({ error: `Actor '${actorId}' is not a participant in room '${room.id}'. Call /join first.` });
+        return;
+    }
+    // Rate limiting
+    const rateLimitKey = `${room.id}:${actorId}:${streamName}`;
+    const now = Date.now();
+    const rateLimit = streamDef.rateLimit || DEFAULT_STREAM_RATE_LIMIT;
+    const windowMs = STREAM_RATE_WINDOW_MS;
+    if (!streamRateLimits.has(rateLimitKey)) {
+        streamRateLimits.set(rateLimitKey, { count: 0, windowStart: now });
+    }
+    const rl = streamRateLimits.get(rateLimitKey);
+    if (now - rl.windowStart > windowMs) {
+        rl.count = 0;
+        rl.windowStart = now;
+    }
+    if (rl.count >= rateLimit) {
+        res.status(429).json({ error: `Rate limited: max ${rateLimit} updates/sec for stream '${streamName}'. Try again shortly.` });
+        return;
+    }
+    rl.count++;
+    // Validate input
+    let validatedInput = input;
+    if (streamDef.input_schema?.parse) {
+        try {
+            validatedInput = streamDef.input_schema.parse(input);
+        }
+        catch (err) {
+            res.status(400).json({ error: toErrorMessage(err) });
+            return;
+        }
+    }
+    // Execute merge
+    try {
+        room.sharedState = streamDef.merge(room.sharedState, validatedInput, actorId);
+    }
+    catch (err) {
+        res.status(400).json({ error: toErrorMessage(err) });
+        return;
+    }
+    // Broadcast state update (no event log entry for streams, delta-compressed)
+    room.broadcastStateUpdate({
+        changedBy: actorId,
+        stream: streamName,
+    });
+    roomEvents.emit(`room:${room.id}`);
+    res.json({ ok: true });
+}
+app.post("/streams/:streamName", (req, res) => {
+    handleStreamRequest(getDefaultRoom(), req.params.streamName, req, res);
+});
+app.post("/rooms/:roomId/streams/:streamName", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room) {
+        res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+        return;
+    }
+    handleStreamRequest(room, req.params.streamName, req, res);
+});
+app.get("/rooms/:roomId/events", (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room) {
+        res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+        return;
+    }
+    handleEvents(room, req, res);
+});
+// ── Room-specific bundle (serves the correct experience's client bundle) ──
+app.get("/rooms/:roomId/bundle", async (req, res) => {
+    // Wait for any in-progress hot-reload to complete before serving
+    if (rebuildingPromise)
+        await rebuildingPromise;
+    const room = getRoom(req.params.roomId);
+    if (!room) {
+        res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+        return;
+    }
+    const loaded = getExperienceForRoom(room);
+    if (!loaded) {
+        res.status(500).json({ error: experienceNotLoadedError(room.experienceId) });
+        return;
+    }
+    res.setHeader("Content-Type", "text/javascript");
+    setNoCacheHeaders(res);
+    res.send(loaded.clientBundle);
+});
+// ── Protocol experience HTML canvas ───────────────────────
+app.get("/rooms/:roomId/canvas", async (req, res) => {
+    const room = getRoom(req.params.roomId);
+    if (!room) {
+        res.status(404).json({ error: roomNotFoundError(req.params.roomId) });
+        return;
+    }
+    const loaded = getExperienceForRoom(room);
+    if (!loaded) {
+        res.status(500).json({ error: experienceNotLoadedError(room.experienceId) });
+        return;
+    }
+    const canvasPath = loaded.module?._canvasPath;
+    if (!canvasPath) {
+        res.status(404).json({ error: "This experience has no HTML canvas" });
+        return;
+    }
+    res.setHeader("Content-Type", "text/html");
+    setNoCacheHeaders(res);
+    res.sendFile(canvasPath);
+});
+// ── MCP config (for remote joiners) ───────────────────────
+app.get("/mcp-config", (_req, res) => {
+    const serverUrl = getBaseUrl();
+    res.json({
+        mcpServers: {
+            "vibevibes-remote": {
+                command: "npx",
+                args: ["-y", "@vibevibes/mcp@latest"],
+                env: {
+                    VIBEVIBES_SERVER_URL: serverUrl,
+                },
+            },
+        },
+        instructions: [
+            `Add the above to your .mcp.json to join this room.`,
+            `Or run: npx @vibevibes/mcp@latest ${serverUrl}`,
+        ],
+    });
+});
+// ── Catch-all: serve viewer for path-based room routing (e.g. /room/room-abc123) ──
+// Must be AFTER all API routes so it doesn't shadow them.
+app.get("*", (req, res, next) => {
+    // Skip API-like paths and static assets
+    if (req.path.startsWith("/rooms/") || req.path.startsWith("/tools/") ||
+        req.path.startsWith("/viewer/") || req.path.startsWith("/blobs/") ||
+        req.path.startsWith("/streams/") || req.path.endsWith(".js") ||
+        req.path.endsWith(".css") || req.path.endsWith(".map")) {
+        next();
+        return;
+    }
+    // Serve the viewer — client-side JS will extract room ID from the path
+    setNoCacheHeaders(res);
+    res.sendFile(path.join(__runtimeDir, "viewer", "index.html"));
+});
+// ── Client bundle smoke test ──────────────────────────────────
+// Fetches the client bundle from the running server and tries to parse it.
+// Catches SyntaxErrors (like duplicate declarations) before the user sees them.
+async function smokeTestClientBundle(port) {
+    try {
+        const res = await fetch(`http://localhost:${port}/bundle`);
+        const bundleCode = await res.text();
+        if (bundleCode) {
+            const error = validateClientBundle(bundleCode);
+            if (error) {
+                console.error(`\n  ⚠ SMOKE TEST FAILED — client bundle has errors:`);
+                console.error(`    ${error}`);
+                console.error(`    The viewer will fail to load. Fix the source and save to hot-reload.\n`);
+            }
+            else {
+                console.log(`  Smoke test: client bundle OK`);
+            }
+        }
+    }
+    catch (err) {
+        console.error(`\n  ⚠ SMOKE TEST FAILED — client bundle has errors:`);
+        console.error(`    ${toErrorMessage(err)}`);
+        console.error(`    The viewer will fail to load. Fix the source and save to hot-reload.\n`);
+    }
+}
+// ── Start server ───────────────────────────────────────────
+export async function startServer(config) {
+    // Apply config
+    if (config?.projectRoot) {
+        PROJECT_ROOT = config.projectRoot;
+    }
+    if (config?.port) {
+        PORT = config.port;
+    }
+    if (!PROJECT_ROOT) {
+        throw new Error("@vibevibes/runtime: projectRoot is required. Pass it via ServerConfig.");
+    }
+    await loadHost();
+    // Create default room (with default config + initial state from experience)
+    const hostExp = getHostExperience();
+    const defaultConfig = resolveRoomConfig(hostExp, undefined);
+    const hostInitialState = resolveInitialState(hostExp, defaultConfig);
+    const defaultRoom = new Room(DEFAULT_ROOM_ID, hostExperienceId, hostInitialState, defaultConfig);
+    rooms.set(DEFAULT_ROOM_ID, defaultRoom);
+    // Start tick engine for default room if host experience uses tick netcode
+    const hostLoaded = experienceCache.get(hostExperienceId);
+    if (hostLoaded) {
+        maybeStartTickEngine(defaultRoom, hostLoaded);
+    }
+    console.log(`  Experience: ${hostExperienceId}`);
+    const server = http.createServer(app);
+    const wss = new WebSocketServer({ server, maxPayload: WS_MAX_PAYLOAD_BYTES });
+    wss.on("error", (err) => { console.error("[WSS] server error:", err.message); });
+    // Grace period timers for WS close → participant deletion (allows page-refresh reconnects)
+    const wsCloseTimers = new Map();
+    wss.on("connection", (ws) => {
+        // Heartbeat: mark alive on connection and on pong
+        const hbWs = ws;
+        hbWs.isAlive = true;
+        ws.on("pong", () => { hbWs.isAlive = true; });
+        ws.on("error", (err) => { console.error("[WS] connection error:", err.message); });
+        ws.on("message", (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+                if (msg.type === "join") {
+                    const username = (msg.username || "viewer").slice(0, 100);
+                    const wsOwner = msg.owner || username;
+                    const roomId = msg.roomId || DEFAULT_ROOM_ID;
+                    const room = getRoom(roomId);
+                    if (!room) {
+                        ws.send(JSON.stringify({ type: "error", error: roomNotFoundError(roomId) }));
+                        return;
+                    }
+                    // Reuse actorId if the viewer sends one back (e.g. on refresh)
+                    let actorId;
+                    if (msg.actorId) {
+                        // Check kick status BEFORE evicting stale WS or reusing actorId
+                        if (room.kickedActors.has(msg.actorId)) {
+                            ws.send(JSON.stringify({ type: "error", error: "You have been kicked from this room." }));
+                            return;
+                        }
+                        if (room.kickedOwners.has(wsOwner)) {
+                            ws.send(JSON.stringify({ type: "error", error: "You have been kicked from this room." }));
+                            return;
+                        }
+                        // Check if the old actorId is held by a stale WS (refresh scenario)
+                        let staleWs = null;
+                        for (const [existingWs, existingId] of room.wsConnections.entries()) {
+                            if (existingId === msg.actorId && existingWs !== ws) {
+                                staleWs = existingWs;
+                                break;
+                            }
+                        }
+                        if (staleWs) {
+                            // Evict the stale connection
+                            room.wsConnections.delete(staleWs);
+                            try {
+                                staleWs.close();
+                            }
+                            catch { }
+                        }
+                        // Cancel any pending close grace timer for this actorId
+                        const closeTimer = wsCloseTimers.get(msg.actorId);
+                        if (closeTimer) {
+                            clearTimeout(closeTimer);
+                            wsCloseTimers.delete(msg.actorId);
+                        }
+                        // Re-add participant if it was deleted during grace window
+                        if (!room.participants.has(msg.actorId)) {
+                            room.participants.set(msg.actorId, { type: "human", joinedAt: Date.now(), owner: wsOwner });
+                        }
+                        // Reuse the old actorId
+                        actorId = msg.actorId;
+                    }
+                    else {
+                        // Block kicked owners before burning an actorId counter slot
+                        if (room.kickedOwners.has(wsOwner)) {
+                            ws.send(JSON.stringify({ type: "error", error: "You have been kicked from this room." }));
+                            return;
+                        }
+                        // Dedup by owner: reuse existing participant if same owner already joined (matches HTTP join logic)
+                        let existingActorId;
+                        for (const [aid, p] of room.participants) {
+                            if (p.owner === wsOwner) {
+                                existingActorId = aid;
+                                break;
+                            }
+                        }
+                        if (existingActorId) {
+                            actorId = existingActorId;
+                            // Evict any stale WS for this actorId
+                            for (const [existingWs, existingId] of room.wsConnections.entries()) {
+                                if (existingId === existingActorId && existingWs !== ws) {
+                                    room.wsConnections.delete(existingWs);
+                                    try {
+                                        existingWs.close();
+                                    }
+                                    catch { }
+                                    break;
+                                }
+                            }
+                        }
+                        else {
+                            // Match human join against participant slots (if defined)
+                            const exp = getExperienceForRoom(room);
+                            const pSlots = exp?.module?.manifest?.participantSlots || exp?.module?.participants;
+                            let wsSlotRole;
+                            if (pSlots?.length) {
+                                const roleOccupancy = new Map();
+                                for (const [, p] of room.participants) {
+                                    if (p.role)
+                                        roleOccupancy.set(p.role, (roleOccupancy.get(p.role) || 0) + 1);
+                                }
+                                const hasCapacity = (slot) => {
+                                    const max = slot.maxInstances ?? 1;
+                                    const current = roleOccupancy.get(slot.role) || 0;
+                                    return current < max;
+                                };
+                                // Match: requested role → type-specific → any
+                                let matched;
+                                if (msg.role) {
+                                    matched = pSlots.find((s) => s.role === msg.role && (!s.type || s.type === "human" || s.type === "any") && hasCapacity(s));
+                                }
+                                if (!matched) {
+                                    matched = pSlots.find((s) => s.type === "human" && hasCapacity(s));
+                                }
+                                if (!matched) {
+                                    matched = pSlots.find((s) => (!s.type || s.type === "any") && hasCapacity(s));
+                                }
+                                // Fallback: if all human-compatible slots are full, use first compatible
+                                if (!matched) {
+                                    matched = pSlots.find((s) => !s.type || s.type === "human" || s.type === "any");
+                                }
+                                if (matched) {
+                                    wsSlotRole = matched.role;
+                                    const base = matched.role.toLowerCase().replace(/\s+/g, "-");
+                                    actorId = assignActorId(username, "human", base);
+                                }
+                                else {
+                                    actorId = assignActorId(username, "human");
+                                }
+                            }
+                            else {
+                                actorId = assignActorId(username, "human");
+                            }
+                            const wsRole = wsSlotRole || msg.role || undefined;
+                            room.participants.set(actorId, { type: "human", joinedAt: Date.now(), owner: wsOwner, role: wsRole });
+                        } // end: new actorId assignment block
+                    }
+                    // For reconnect case: if msg.actorId no longer has a participant entry
+                    // (e.g., after room reset), reject the stale reconnect. Viewer must do a fresh join.
+                    if (msg.actorId && !room.participants.has(msg.actorId)) {
+                        ws.send(JSON.stringify({ type: "error", error: "Session expired. Please rejoin the room." }));
+                        return;
+                    }
+                    // Track this WS → actorId in the room
+                    room.wsConnections.set(ws, actorId);
+                    // Resolve role from participant entry
+                    const resolvedWsRole = room.participants.get(actorId)?.role;
+                    // Send initial state (includes stateVersion for delta tracking)
+                    ws.send(JSON.stringify({
+                        type: "joined",
+                        roomId: room.id,
+                        actorId,
+                        role: resolvedWsRole,
+                        sharedState: room.sharedState,
+                        stateVersion: room.stateVersion,
+                        participants: room.participantList(),
+                        participantDetails: room.participantDetails(),
+                        events: room.events.slice(-JOIN_EVENT_HISTORY),
+                        config: room.config,
+                    }));
+                    // Broadcast presence update to others in this room
+                    broadcastPresenceUpdate(room);
+                }
+                if (msg.type === "ephemeral") {
+                    // Relay ephemeral data to all OTHER clients in the same room.
+                    // No validation, no persistence — this is the fast path for cursors,
+                    // typing indicators, follow mode, and other high-frequency cosmetic data.
+                    // Size guard: reject oversized payloads to prevent DoS amplification
+                    const ephPayload = JSON.stringify(msg.data);
+                    if (ephPayload.length > WS_EPHEMERAL_MAX_BYTES) {
+                        ws.send(JSON.stringify({ type: "error", error: "Ephemeral payload too large (max 64KB)" }));
+                        return;
+                    }
+                    for (const room of rooms.values()) {
+                        const senderActorId = room.wsConnections.get(ws);
+                        if (senderActorId) {
+                            const payload = JSON.stringify({
+                                type: "ephemeral",
+                                actorId: senderActorId,
+                                data: msg.data,
+                            });
+                            for (const [otherWs, otherId] of room.wsConnections.entries()) {
+                                if (otherWs !== ws && otherWs.readyState === WebSocket.OPEN) {
+                                    otherWs.send(payload);
+                                }
+                            }
+                            break;
+                        }
+                    }
+                }
+                if (msg.type === "stream") {
+                    // Validate stream name
+                    if (typeof msg.name !== "string" || !msg.name) {
+                        ws.send(JSON.stringify({ type: "stream_error", error: "stream.name must be a non-empty string" }));
+                        return;
+                    }
+                    // High-frequency continuous state channel
+                    // Find which room this WS belongs to
+                    for (const room of rooms.values()) {
+                        const senderActorId = room.wsConnections.get(ws);
+                        if (!senderActorId)
+                            continue;
+                        const exp = getExperienceForRoom(room);
+                        if (!exp?.module?.streams)
+                            break;
+                        const streamDef = exp.module.streams.find((s) => s.name === msg.name);
+                        if (!streamDef) {
+                            ws.send(JSON.stringify({ type: "stream_error", error: `Stream '${msg.name}' not found` }));
+                            break;
+                        }
+                        // Rate limiting
+                        const rateLimitKey = `${room.id}:${senderActorId}:${msg.name}`;
+                        const now = Date.now();
+                        const rateLimit = streamDef.rateLimit || DEFAULT_STREAM_RATE_LIMIT;
+                        const windowMs = STREAM_RATE_WINDOW_MS;
+                        if (!streamRateLimits.has(rateLimitKey)) {
+                            streamRateLimits.set(rateLimitKey, { count: 0, windowStart: now });
+                        }
+                        const rl = streamRateLimits.get(rateLimitKey);
+                        if (now - rl.windowStart > windowMs) {
+                            rl.count = 0;
+                            rl.windowStart = now;
+                        }
+                        if (rl.count >= rateLimit) {
+                            ws.send(JSON.stringify({ type: "stream_error", error: `Rate limited: max ${rateLimit}/sec for '${msg.name}'` }));
+                            break;
+                        }
+                        rl.count++;
+                        // Validate input
+                        let validatedInput = msg.input;
+                        if (streamDef.input_schema?.parse) {
+                            try {
+                                validatedInput = streamDef.input_schema.parse(msg.input);
+                            }
+                            catch (err) {
+                                ws.send(JSON.stringify({ type: "stream_error", error: `Invalid input for stream '${msg.name}': ${toErrorMessage(err)}` }));
+                                break;
+                            }
+                        }
+                        // Execute merge
+                        try {
+                            room.sharedState = streamDef.merge(room.sharedState, validatedInput, senderActorId);
+                        }
+                        catch (err) {
+                            ws.send(JSON.stringify({ type: "stream_error", error: `Stream '${msg.name}' merge failed: ${toErrorMessage(err)}` }));
+                            break;
+                        }
+                        // Broadcast state update (no event log entry for streams, delta-compressed)
+                        room.broadcastStateUpdate({
+                            changedBy: senderActorId,
+                            stream: msg.name,
+                        });
+                        roomEvents.emit(`room:${room.id}`);
+                        break;
+                    }
+                }
+                if (msg.type === "kick") {
+                    let found = false;
+                    for (const room of rooms.values()) {
+                        const kickerActorId = room.wsConnections.get(ws);
+                        if (!kickerActorId)
+                            continue;
+                        found = true;
+                        const result = handleKick(room, kickerActorId, msg.targetActorId);
+                        if (result.error) {
+                            console.warn(`[kick] ${kickerActorId} failed to kick ${msg.targetActorId}: ${result.error}`);
+                            ws.send(JSON.stringify({ type: "kick_error", error: result.error }));
+                        }
+                        else {
+                            ws.send(JSON.stringify({ type: "kick_success", actorId: msg.targetActorId }));
+                        }
+                        break;
+                    }
+                    if (!found) {
+                        ws.send(JSON.stringify({ type: "kick_error", error: "You are not in any room" }));
+                    }
+                }
+                if (msg.type === "screenshot_response") {
+                    const pending = pendingScreenshots.get(msg.id);
+                    if (pending && pending.viewerWs === ws) {
+                        clearTimeout(pending.timer);
+                        pendingScreenshots.delete(msg.id);
+                        if (msg.error) {
+                            pending.reject(new Error(msg.error));
+                        }
+                        else if (msg.dataUrl) {
+                            // Validate data URL format before decoding
+                            if (typeof msg.dataUrl !== "string" || !msg.dataUrl.startsWith("data:image/png;base64,")) {
+                                pending.reject(new Error("Invalid screenshot data URL format"));
+                            }
+                            else {
+                                const base64Data = msg.dataUrl.slice("data:image/png;base64,".length);
+                                const buffer = Buffer.from(base64Data, "base64");
+                                pending.resolve(buffer);
+                            }
+                        }
+                        else {
+                            pending.reject(new Error("Empty screenshot response"));
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                // Log unexpected errors (not JSON parse failures) for debugging
+                if (!(err instanceof SyntaxError)) {
+                    console.error("[WS] Unexpected handler error:", err instanceof Error ? err.message : String(err));
+                }
+            }
+        });
+        ws.on("close", () => {
+            // Clean up participant from whichever room this WS belongs to.
+            // Only delete human participants — AI agents join via HTTP and don't rely on WS for presence.
+            for (const room of rooms.values()) {
+                const actorId = room.wsConnections.get(ws);
+                if (actorId) {
+                    room.wsConnections.delete(ws);
+                    const participant = room.participants.get(actorId);
+                    if (!participant || participant.type === "human") {
+                        // Grace period: delay participant deletion to allow page refresh reconnects.
+                        // If the same actorId reconnects within the grace period, the deletion is cancelled.
+                        const timer = setTimeout(() => {
+                            wsCloseTimers.delete(actorId);
+                            // Only delete if no new WS reconnected for this actorId
+                            let reconnected = false;
+                            for (const [, wsActorId] of room.wsConnections) {
+                                if (wsActorId === actorId) {
+                                    reconnected = true;
+                                    break;
+                                }
+                            }
+                            if (!reconnected) {
+                                room.participants.delete(actorId);
+                                broadcastPresenceUpdate(room);
+                            }
+                        }, WS_CLOSE_GRACE_MS);
+                        // Cancel any previous timer for this actorId and store the new one
+                        const prev = wsCloseTimers.get(actorId);
+                        if (prev)
+                            clearTimeout(prev);
+                        wsCloseTimers.set(actorId, timer);
+                    }
+                    break;
+                }
+            }
+        });
+    });
+    // ── WebSocket heartbeat interval ──────────────────────────
+    const heartbeatInterval = setInterval(() => {
+        for (const ws of wss.clients) {
+            if (ws.isAlive === false) {
+                // Dead connection — clean up from rooms and terminate
+                for (const room of rooms.values()) {
+                    const actorId = room.wsConnections.get(ws);
+                    if (actorId) {
+                        room.participants.delete(actorId);
+                        room.wsConnections.delete(ws);
+                        broadcastPresenceUpdate(room);
+                        break;
+                    }
+                }
+                ws.terminate();
+                continue;
+            }
+            ws.isAlive = false;
+            ws.ping();
+        }
+    }, WS_HEARTBEAT_INTERVAL_MS);
+    // ── AI agent heartbeat sweep ──────────────────────────────
+    // Evict AI participants that haven't polled /agent-context within the timeout.
+    // This cleans up zombie agents after crashes, SIGKILLs, etc.
+    // 5 minutes — generous enough for Claude Code's turn model.
+    const AI_HEARTBEAT_TIMEOUT_MS = 300_000;
+    const aiHeartbeatInterval = setInterval(() => {
+        const now = Date.now();
+        for (const room of rooms.values()) {
+            const toEvict = [];
+            for (const [actorId, p] of room.participants) {
+                if (p.type !== "ai")
+                    continue;
+                // "behavior" agents run autonomously via tick engine — they never poll, so skip heartbeat eviction
+                if (p.agentMode === "behavior")
+                    continue;
+                const lastSeen = p.lastPollAt || p.joinedAt;
+                if (now - lastSeen > AI_HEARTBEAT_TIMEOUT_MS)
+                    toEvict.push(actorId);
+            }
+            for (const actorId of toEvict) {
+                room.participants.delete(actorId);
+                // Clean up memory entries keyed by this actorId
+                const exp = getExperienceForRoom(room);
+                const expId = exp?.module?.manifest?.id || room.experienceId;
+                agentMemory.delete(`${expId}:${actorId}`);
+            }
+            if (toEvict.length > 0) {
+                broadcastPresenceUpdate(room);
+                // Notify long-pollers that participants changed
+                roomEvents.emit(`room:${room.id}`);
+            }
+        }
+    }, WS_HEARTBEAT_INTERVAL_MS);
+    // ── Room garbage collection sweep ──────────────────────────
+    // Auto-delete spawned rooms that have been empty (zero participants) for over 5 minutes.
+    // The default "local" room is never deleted. Rooms with active WebSocket connections
+    // or recent participants are kept alive. This prevents zombie rooms from accumulating.
+    const ROOM_EMPTY_TTL_MS = 5 * 60 * 1000; // 5 minutes
+    const roomGcInterval = setInterval(() => {
+        const now = Date.now();
+        for (const [roomId, room] of rooms) {
+            if (roomId === DEFAULT_ROOM_ID || room.preCreated)
+                continue; // Never GC the default or pre-created rooms
+            if (room.participants.size === 0 && room.wsConnections.size === 0) {
+                // Room is empty — track when we first noticed
+                if (!roomEmptySince.has(roomId)) {
+                    roomEmptySince.set(roomId, now);
+                }
+                const emptySince = roomEmptySince.get(roomId);
+                if (now - emptySince >= ROOM_EMPTY_TTL_MS) {
+                    // TTL expired — garbage collect this room
+                    console.log(`[GC] Deleting empty room '${roomId}' (empty for ${Math.round((now - emptySince) / 1000)}s)`);
+                    stopTickEngine(roomId);
+                    cleanupRoomLinks(roomId, room);
+                    // Clean up memory entries only for actors that were in this room.
+                    // Per-actor cleanup already happens during heartbeat eviction (line ~2846).
+                    // Don't wildcard-delete all memory for the experience — other rooms
+                    // running the same experience would lose their agents' memory.
+                    const exp = getExperienceForRoom(room);
+                    const expId = exp?.module?.manifest?.id || room.experienceId;
+                    for (const [actorId] of room.participants) {
+                        agentMemory.delete(`${expId}:${actorId}`);
+                    }
+                    // Clean up blobs associated with this room
+                    for (const [key, meta] of blobMeta) {
+                        if (meta.roomId === roomId) {
+                            blobStore.delete(key);
+                            blobMeta.delete(key);
+                        }
+                    }
+                    // Wake any long-poll listeners before deletion, then clean up event emitter
+                    roomEvents.emit(`room:${roomId}`);
+                    roomEvents.removeAllListeners(`room:${roomId}`);
+                    rooms.delete(roomId);
+                    roomEmptySince.delete(roomId);
+                    roomBrowserErrors.delete(roomId);
+                    lastBrowserErrorAt.delete(roomId);
+                    spawnCounts.delete(roomId);
+                }
+            }
+            else {
+                // Room has participants — reset the empty timer
+                roomEmptySince.delete(roomId);
+            }
+        }
+    }, ROOM_GC_INTERVAL_MS);
+    // Watch src/ and experiences/ directories for changes (host experience only)
+    // Check both PROJECT_ROOT/experiences/ and PROJECT_ROOT/../experiences/ (top-level monorepo)
+    const watchDirs = [
+        path.join(PROJECT_ROOT, "src"),
+        path.join(PROJECT_ROOT, "experiences"),
+        path.resolve(PROJECT_ROOT, "..", "experiences"),
+    ].filter((d) => fs.existsSync(d));
+    let debounceTimer = null;
+    function onSrcChange(filename) {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        // Signal that a rebuild is starting (so bundle endpoints can wait)
+        if (!rebuildingPromise) {
+            rebuildingPromise = new Promise((resolve) => { rebuildingResolve = resolve; });
+        }
+        debounceTimer = setTimeout(async () => {
+            console.log(`\nFile changed${filename ? ` (${filename})` : ""}, rebuilding...`);
+            // Determine which experiences are affected by this file change
+            // Stop tick engines before reloading
+            for (const room of rooms.values()) {
+                stopTickEngine(room.id);
+            }
+            try {
+                // Reload the experience
+                await loadHost();
+                const reloaded = experienceCache.get(hostExperienceId);
+                for (const room of rooms.values()) {
+                    room.broadcastToAll({ type: "experience_updated" });
+                    if (reloaded)
+                        maybeStartTickEngine(room, reloaded);
+                }
+                smokeTestClientBundle(PORT);
+                console.log("Hot reload complete.");
+            }
+            catch (err) {
+                experienceErrors.set(hostExperienceId, toErrorMessage(err));
+                console.error("Hot reload failed:", toErrorMessage(err));
+                // Restart tick engines with last-known-good experience so rooms don't stay frozen
+                const lastGood = experienceCache.get(hostExperienceId);
+                for (const room of rooms.values()) {
+                    if (room.experienceId === hostExperienceId) {
+                        room.broadcastToAll({ type: "build_error", error: toErrorMessage(err) });
+                        if (lastGood)
+                            maybeStartTickEngine(room, lastGood);
+                    }
+                }
+            }
+            finally {
+                // Always resolve the rebuilding promise so bundle endpoints unblock
+                if (rebuildingResolve) {
+                    rebuildingResolve();
+                    rebuildingResolve = null;
+                    rebuildingPromise = null;
+                }
+            }
+        }, HOT_RELOAD_DEBOUNCE_MS);
+    }
+    for (const watchDir of watchDirs) {
+        try {
+            // recursive: true works on Windows and macOS
+            fs.watch(watchDir, { recursive: true }, (_event, filename) => {
+                if (filename && /\.(tsx?|jsx?|css|json)$/.test(filename)) {
+                    // Resolve filename against watchDir (fs.watch gives paths relative to watched dir)
+                    onSrcChange(path.join(path.relative(PROJECT_ROOT, watchDir), filename));
+                }
+            });
+        }
+        catch {
+            // Fallback for Linux: watch individual directories
+            function watchDirRecursive(dir) {
+                fs.watch(dir, (_event, filename) => {
+                    if (filename && /\.(tsx?|jsx?|css|json)$/.test(filename)) {
+                        onSrcChange(path.join(path.relative(PROJECT_ROOT, dir), filename));
+                    }
+                });
+                for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                    if (entry.isDirectory())
+                        watchDirRecursive(path.join(dir, entry.name));
+                }
+            }
+            watchDirRecursive(watchDir);
+        }
+    }
+    server.listen(PORT, async () => {
+        console.log(`\n  vibe-vibe local runtime`);
+        console.log(`  ───────────────────────`);
+        console.log(`  Viewer:  http://localhost:${PORT}`);
+        // Verify the client bundle can be parsed without errors
+        smokeTestClientBundle(PORT);
+        if (publicUrl) {
+            const shareUrl = getBaseUrl();
+            console.log(``);
+            console.log(`  ┌─────────────────────────────────────────────────┐`);
+            console.log(`  │  SHARE WITH FRIENDS:                            │`);
+            console.log(`  │                                                 │`);
+            console.log(`  │  ${shareUrl.padEnd(47)} │`);
+            console.log(`  │                                                 │`);
+            console.log(`  │  Open in browser to join the room.              │`);
+            console.log(`  │  AI: npx @vibevibes/mcp ${(shareUrl).padEnd(23)} │`);
+            console.log(`  └─────────────────────────────────────────────────┘`);
+        }
+        console.log(`\n  Watching src/ and experiences/ for changes\n`);
+    });
+    // Cleanup all intervals on server close
+    server.on("close", () => {
+        clearInterval(heartbeatInterval);
+        clearInterval(aiHeartbeatInterval);
+        clearInterval(roomGcInterval);
+        clearInterval(_streamRateCleanupTimer);
+        clearInterval(_spawnRateCleanupTimer);
+        clearInterval(_idempotencyCleanupTimer);
+    });
+    return server;
+}
+// Convenience: allow setting PROJECT_ROOT before startServer() is called
+// (e.g., for registry loading during setup).
+export function setProjectRoot(root) {
+    PROJECT_ROOT = root;
+}
+//# sourceMappingURL=server.js.map