@vibevibes/mcp 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,18 +1,112 @@
 /**
- * vibevibes-mcp — standalone MCP server for joining vibevibes experiences.
+ * vibevibes-mcp — MCP server for agent participation in vibevibes experiences.
  *
- * Works with both local dev servers and remote shared tunnels.
+ * The `connect` tool is the single entry point: it joins the server, writes
+ * the state file (for the stop hook to poll), and returns room info.
  *
- * Usage:
- *   npx vibevibes-mcp                          # defaults to http://localhost:4321
- *   npx vibevibes-mcp https://xyz.trycloudflare.com  # join a shared room
- *   VIBEVIBES_SERVER_URL=https://... npx vibevibes-mcp
- *
- * 5 tools: connect, watch, act, memory, screenshot
+ * 4 tools: connect, act, look, disconnect
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, readdirSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn, spawnSync } from "node:child_process";
+/** Extract error message from unknown catch value. */
+function toErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// ── Server auto-start ──────────────────────────────────────
+let serverStarted = false;
+/**
+ * Check if the server is reachable. If not, start it in a child process.
+ * The server loads the experience from the given project root.
+ */
+async function ensureServerRunning(projectRoot) {
+    if (serverStarted)
+        return;
+    // Check if server is already running
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 2000);
+        const res = await fetch(`${SERVER_URL}/state`, { signal: controller.signal });
+        clearTimeout(timer);
+        if (res.ok) {
+            serverStarted = true;
+            return;
+        }
+    }
+    catch {
+        // Server not running — start it
+    }
+    // Find the server entry point (in mcp/dist/ or mcp/src/)
+    const serverScript = resolve(MCP_ROOT, "dist/server.js");
+    const serverTs = resolve(MCP_ROOT, "src/server.ts");
+    // Start server as a child process using a small bootstrap script
+    const bootstrapCode = `
+    import("${serverScript.replace(/\\/g, "/")}").then(m => {
+      m.startServer({ projectRoot: "${projectRoot.replace(/\\/g, "/")}" });
+    }).catch(e => {
+      // Fallback: try tsx for .ts source
+      import("${serverTs.replace(/\\/g, "/")}").then(m => {
+        m.startServer({ projectRoot: "${projectRoot.replace(/\\/g, "/")}" });
+      }).catch(e2 => {
+        console.error("Failed to start server:", e2.message);
+        process.exit(1);
+      });
+    });
+  `;
+    const child = spawn(process.execPath, ["--input-type=module", "-e", bootstrapCode], {
+        stdio: ["pipe", "pipe", "pipe"],
+        detached: true,
+        env: { ...process.env, PORT: new URL(SERVER_URL).port || "4321" },
+    });
+    child.unref();
+    // Store child for cleanup
+    serverChild = child;
+    child.stderr?.on("data", (chunk) => {
+        const msg = chunk.toString().trim();
+        if (msg)
+            console.error(`[server] ${msg}`);
+    });
+    // Wait for server to become available (up to 15 seconds)
+    const deadline = Date.now() + 15000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 500));
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 1500);
+            const res = await fetch(`${SERVER_URL}/state`, { signal: controller.signal });
+            clearTimeout(timer);
+            if (res.ok) {
+                serverStarted = true;
+                return;
+            }
+        }
+        catch {
+            // Keep waiting
+        }
+    }
+    throw new Error(`Server failed to start within 15 seconds at ${SERVER_URL}`);
+}
+let serverChild = null;
+// Cleanup server on exit
+process.on("exit", () => { if (serverChild)
+    try {
+        serverChild.kill();
+    }
+    catch { } });
+process.on("SIGINT", () => { if (serverChild)
+    try {
+        serverChild.kill();
+    }
+    catch { } process.exit(0); });
+process.on("SIGTERM", () => { if (serverChild)
+    try {
+        serverChild.kill();
+    }
+    catch { } process.exit(0); });
 // Resolve server URL: CLI arg > env var > localhost default
 const RAW_SERVER_URL = process.argv[2] ||
     process.env.VIBEVIBES_SERVER_URL ||
@@ -22,31 +116,165 @@ const parsedUrl = new URL(RAW_SERVER_URL);
 const ROOM_TOKEN = parsedUrl.searchParams.get("token");
 // Strip the token param from the base URL so it isn't duplicated in request paths
 parsedUrl.searchParams.delete("token");
-const SERVER_URL = parsedUrl.toString().replace(/\/$/, ""); // remove trailing slash
-// ── State ──────────────────────────────────────────────────
+let SERVER_URL = parsedUrl.toString().replace(/\/$/, ""); // remove trailing slash
+/** All active connections in this MCP session. Multiple subagents can each connect independently. */
+const connections = new Map(); // actorId → slot
+/** The most recently connected identity — used as default when only one connection exists. */
 let currentActorId = null;
-let lastEventTs = 0;
-let connected = false;
+let currentOwner = null;
+/** Resolve the effective identity for a tool call. If actorId is provided, use that connection.
+ *  If only one connection exists, use it. If multiple exist and no actorId given, error. */
+function resolveIdentity(actorId) {
+    if (actorId) {
+        const slot = connections.get(actorId);
+        if (!slot)
+            throw new Error(`Unknown actorId '${actorId}'. Connected actors: ${[...connections.keys()].join(", ") || "none"}`);
+        return slot;
+    }
+    if (connections.size === 1) {
+        return connections.values().next().value;
+    }
+    if (connections.size > 1) {
+        throw new Error(`Multiple agents connected. You MUST pass actorId to identify yourself.\n` +
+            `Connected actors: ${[...connections.keys()].join(", ")}`);
+    }
+    // No connections — fall back to currentActorId for backward compat (e.g. loadIdentity)
+    if (currentActorId && currentOwner) {
+        return { actorId: currentActorId, owner: currentOwner };
+    }
+    throw new Error("Not connected. Call the connect tool first.");
+}
+// Derive paths from this module's location.
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// mcp/src/ or mcp/dist/ → MCP package root is ..
+const MCP_ROOT = resolve(__dirname, "..");
+// Project root = cwd (where the experience lives)
+const PROJECT_ROOT = process.cwd();
+const AGENTS_DIR = resolve(PROJECT_ROOT, ".claude/vibevibes-agents");
+const SETTINGS_PATH = resolve(PROJECT_ROOT, ".claude/settings.json");
+// ── Dynamic Hook Registration ─────────────────────────────────────
+/**
+ * Ensure the Stop hook is registered in .claude/settings.json.
+ * Called on connect. Idempotent — skips if already present.
+ * Uses absolute path because hook CWD may differ from project root.
+ */
+function ensureStopHook() {
+    try {
+        const hookScript = resolve(MCP_ROOT, "hooks/stop-hook.js");
+        const command = `node "${hookScript}"`;
+        let settings = {};
+        if (existsSync(SETTINGS_PATH)) {
+            settings = JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
+        }
+        const hooks = (settings.hooks ?? {});
+        const stopHooks = (hooks.Stop ?? []);
+        const alreadyRegistered = stopHooks.some((entry) => entry.hooks?.some((h) => h.type === "command" && h.command === command));
+        if (alreadyRegistered)
+            return;
+        stopHooks.push({
+            hooks: [{ type: "command", command, timeout: 60 }],
+        });
+        hooks.Stop = stopHooks;
+        settings.hooks = hooks;
+        // Ensure directory exists
+        const settingsDir = dirname(SETTINGS_PATH);
+        if (!existsSync(settingsDir))
+            mkdirSync(settingsDir, { recursive: true });
+        writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+    }
+    catch {
+        // Hook registration is best-effort
+    }
+}
+function removeStopHook() {
+    try {
+        if (!existsSync(SETTINGS_PATH))
+            return;
+        const hookScript = resolve(MCP_ROOT, "hooks/stop-hook.js");
+        const command = `node "${hookScript}"`;
+        const settings = JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
+        const hooks = (settings.hooks ?? {});
+        const stopHooks = (hooks.Stop ?? []);
+        hooks.Stop = stopHooks.filter((entry) => !entry.hooks?.some((h) => h.type === "command" && h.command === command));
+        settings.hooks = hooks;
+        writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2));
+    }
+    catch {
+        // Best-effort cleanup
+    }
+}
+function loadIdentity() {
+    if (currentOwner && currentActorId) {
+        return { actorId: currentActorId, serverUrl: SERVER_URL, owner: currentOwner };
+    }
+    throw new Error("Not connected. Call the connect tool first.");
+}
+// ── Name Generator ─────────────────────────────────────────
+const ADJECTIVES = [
+    "swift", "brave", "calm", "bold", "keen",
+    "wild", "sly", "warm", "cool", "bright",
+    "quick", "sharp", "wise", "kind", "fair",
+    "proud", "free", "dark", "lost", "glad",
+];
+const ANIMALS = [
+    "fox", "wolf", "bear", "hawk", "lynx",
+    "deer", "owl", "crow", "hare", "pike",
+    "dove", "wren", "newt", "moth", "orca",
+    "lion", "toad", "crab", "swan", "mole",
+];
+function generateName() {
+    const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+    const animal = ANIMALS[Math.floor(Math.random() * ANIMALS.length)];
+    const suffix = Math.random().toString(36).slice(2, 6);
+    return `${adj}-${animal}-${suffix}`;
+}
 // ── Helpers ────────────────────────────────────────────────
 async function fetchJSON(path, opts) {
-    const headers = {
-        "Content-Type": "application/json",
-        ...(opts?.headers || {}),
-    };
-    // Attach room token as Authorization header when available
-    if (ROOM_TOKEN) {
-        headers["Authorization"] = `Bearer ${ROOM_TOKEN}`;
-    }
-    const res = await fetch(`${SERVER_URL}${path}`, {
-        ...opts,
-        headers,
-    });
-    const text = await res.text();
+    const timeoutMs = opts?.timeoutMs ?? 30000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
-        return JSON.parse(text);
+        const headers = {
+            "Content-Type": "application/json",
+            ...(opts?.headers || {}),
+        };
+        // Attach room token as Authorization header when available
+        if (ROOM_TOKEN) {
+            headers["Authorization"] = `Bearer ${ROOM_TOKEN}`;
+        }
+        const res = await fetch(`${SERVER_URL}${path}`, {
+            ...opts,
+            signal: controller.signal,
+            headers,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            // Try to parse error JSON, fall back to status text
+            let message = `HTTP ${res.status}: ${res.statusText}`;
+            try {
+                const j = JSON.parse(text);
+                if (j.error)
+                    message = `HTTP ${res.status}: ${j.error}`;
+            }
+            catch { }
+            throw new Error(message);
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new Error(`Server returned non-JSON: ${text.slice(0, 200)}`);
+        }
     }
-    catch {
-        throw new Error(`Server returned non-JSON: ${text.slice(0, 200)}`);
+    catch (err) {
+        if (err instanceof Error && err.name === "AbortError") {
+            throw new Error(`Request timed out after ${timeoutMs}ms: ${path}`);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
     }
 }
 function formatToolList(tools) {
@@ -54,248 +282,542 @@ function formatToolList(tools) {
         return "No tools available.";
     return tools
         .map((t) => {
-        const schema = t.input_schema?.properties
-            ? Object.entries(t.input_schema.properties)
-                .map(([k, v]) => `${k}: ${v.type || "any"}`)
+        const props = t.input_schema?.properties;
+        const schema = props && typeof props === "object"
+            ? Object.entries(props)
+                .map(([k, v]) => `${k}: ${typeof v.type === "string" ? v.type : "any"}`)
                 .join(", ")
             : "{}";
         return `  ${t.name} (${t.risk || "low"}) — ${t.description}\n    input: { ${schema} }`;
     })
         .join("\n");
 }
-async function joinRoom() {
-    const join = await fetchJSON("/join", {
-        method: "POST",
-        body: JSON.stringify({ username: "claude", actorType: "ai" }),
-    });
-    if (join.error)
-        throw new Error(join.error);
-    currentActorId = join.actorId;
-    lastEventTs = Date.now();
-    connected = true;
-    return join;
-}
-async function ensureConnected() {
-    if (connected)
-        return;
-    await joinRoom();
+/**
+ * Format state for agent consumption.
+ * If the experience defines observe(), show the curated observation.
+ * Otherwise fall back to raw state.
+ */
+function formatState(state, observation) {
+    if (observation) {
+        return `Observation: ${JSON.stringify(observation, null, 2)}`;
+    }
+    return `State: ${JSON.stringify(state, null, 2)}`;
 }
 // ── MCP Server ─────────────────────────────────────────────
 const server = new McpServer({
     name: "vibevibes",
-    version: "0.1.0",
+    version: "0.4.0",
 });
 // ── Tool: connect ──────────────────────────────────────────
-server.tool("connect", `Connect to the running experience.
-
-Returns: available tools, current state, participants, and the browser URL.
-
-Call this first before using watch or act.`, {}, async () => {
+server.tool("connect", `Connect to the running experience.
+
+Joins the server as an AI participant, creates a session file for the stop hook,
+and returns available tools, current state, participants, and the browser URL.
+
+Call this first, then use act to interact. The stop hook keeps you present.`, {
+    url: z.string().optional().describe("Server URL to connect to. Defaults to the MCP server's configured URL."),
+    role: z.string().optional().describe("Preferred participant slot role to request (e.g. 'Blue Tank', 'Red ADC'). Server assigns the first available slot if omitted."),
+    subscription: z.enum(["all", "phase"]).optional().describe("Event subscription mode. 'all' (default) wakes on every event. 'phase' wakes only on phase changes — use for orchestrator agents."),
+    agentMode: z.enum(["behavior", "manual", "hybrid"]).optional().describe("Agent operating mode. 'behavior': autonomous via tick engine (no stop hook). 'manual': all decisions via act(). 'hybrid' (default): both behaviors and act()."),
+    metadata: z.record(z.string()).optional().describe("Arbitrary metadata (model, team, tags). Flows to server and viewer. E.g. { model: 'haiku', team: 'blue' }"),
+}, async ({ url, role: requestedRole, subscription, agentMode, metadata }) => {
     try {
-        const join = await joinRoom();
-        const output = [
-            `Connected as ${currentActorId}`,
-            `Experience: ${join.experienceId}`,
-            `Browser: ${join.browserUrl}`,
-            `Server: ${SERVER_URL}`,
-            ``,
-            `State: ${JSON.stringify(join.sharedState, null, 2)}`,
-            `Participants: ${join.participants?.join(", ")}`,
-            ``,
-            `Tools:`,
-            formatToolList(join.tools),
-        ].join("\n");
-        return { content: [{ type: "text", text: output }] };
+        if (url) {
+            SERVER_URL = url.replace(/\/$/, "");
+        }
+        // Auto-start server if not running
+        await ensureServerRunning(PROJECT_ROOT);
+        // Check if already connected (same process re-calling connect)
+        let identity = null;
+        if (currentOwner && existsSync(AGENTS_DIR)) {
+            const agentFiles = readdirSync(AGENTS_DIR).filter(f => f.endsWith(".json"));
+            for (const file of agentFiles) {
+                try {
+                    const session = JSON.parse(readFileSync(resolve(AGENTS_DIR, file), "utf-8"));
+                    if (session.owner !== currentOwner)
+                        continue;
+                    // Verify the agent still exists on the server
+                    let networkError = false;
+                    try {
+                        const controller = new AbortController();
+                        const timer = setTimeout(() => controller.abort(), 3000);
+                        const verifyHeaders = {};
+                        if (ROOM_TOKEN)
+                            verifyHeaders["Authorization"] = `Bearer ${ROOM_TOKEN}`;
+                        const verifyRes = await fetch(`${SERVER_URL}/participants`, { signal: controller.signal, headers: verifyHeaders });
+                        clearTimeout(timer);
+                        if (verifyRes.ok) {
+                            const data = await verifyRes.json();
+                            const alive = data.participants?.some((p) => p.actorId === session.actorId);
+                            if (alive) {
+                                identity = { actorId: session.actorId, owner: session.owner, id: session.owner };
+                                currentActorId = session.actorId;
+                                currentOwner = session.owner;
+                                break;
+                            }
+                        }
+                    }
+                    catch {
+                        networkError = true;
+                    }
+                    if (!identity && !networkError) {
+                        try {
+                            unlinkSync(resolve(AGENTS_DIR, file));
+                        }
+                        catch { }
+                    }
+                }
+                catch {
+                    try {
+                        unlinkSync(resolve(AGENTS_DIR, file));
+                    }
+                    catch { }
+                }
+            }
+        }
+        let joinData = null;
+        if (!identity) {
+            const id = generateName();
+            const joinBody = { username: id, actorType: "ai", owner: id };
+            if (requestedRole)
+                joinBody.role = requestedRole;
+            if (agentMode)
+                joinBody.agentMode = agentMode;
+            if (metadata && Object.keys(metadata).length > 0)
+                joinBody.metadata = metadata;
+            joinData = await fetchJSON("/join", {
+                method: "POST",
+                body: JSON.stringify(joinBody),
+                timeoutMs: 10000,
+            });
+            if (joinData.error) {
+                throw new Error(joinData.error);
+            }
+            // Write agent file
+            if (!existsSync(AGENTS_DIR)) {
+                mkdirSync(AGENTS_DIR, { recursive: true });
+            }
+            const sessionData = {
+                serverUrl: SERVER_URL,
+                owner: id,
+                actorId: joinData.actorId,
+                role: joinData.role || undefined,
+            };
+            if (subscription && subscription !== "all") {
+                sessionData.subscription = subscription;
+            }
+            if (agentMode) {
+                sessionData.agentMode = agentMode;
+            }
+            writeFileSync(resolve(AGENTS_DIR, `${id}.json`), JSON.stringify(sessionData, null, 2));
+            identity = { actorId: joinData.actorId, owner: id, id };
+            currentActorId = joinData.actorId;
+            currentOwner = id;
+            connections.set(joinData.actorId, {
+                actorId: joinData.actorId,
+                owner: id,
+            });
+        }
+        // Fetch state
+        const wroteNewFile = joinData !== null;
+        let state;
+        try {
+            state = await fetchJSON("/state", { timeoutMs: 10000 });
+        }
+        catch (stateErr) {
+            if (wroteNewFile && identity?.owner) {
+                try {
+                    unlinkSync(resolve(AGENTS_DIR, `${identity.owner}.json`));
+                }
+                catch { }
+            }
+            throw stateErr;
+        }
+        // Fetch slot definitions to detect unfilled autoSpawn AI slots
+        let unfilledSlots = [];
+        try {
+            const slotsData = await fetchJSON("/slots", { timeoutMs: 5000 });
+            if (slotsData?.slots) {
+                const currentParticipants = slotsData.participantDetails || [];
+                for (const slot of slotsData.slots) {
+                    if (slot.type !== "ai" && slot.type !== "any")
+                        continue;
+                    if (!slot.autoSpawn)
+                        continue;
+                    const max = slot.maxInstances ?? 1;
+                    const filled = currentParticipants.filter(p => p.role === slot.role && p.type === "ai").length;
+                    if (filled < max) {
+                        unfilledSlots.push({ role: slot.role, autoSpawn: slot.autoSpawn, maxInstances: max });
+                    }
+                }
+            }
+        }
+        catch {
+            // Slots endpoint not available — skip silently
+        }
+        const outputParts = [
+            `Connected as ${identity.actorId}`,
+            connections.size > 1
+                ? `IMPORTANT: Multiple agents connected (${connections.size}). Pass actorId="${identity.actorId}" in all act/look calls.`
+                : "",
+            `Experience: ${state.experienceId || "unknown"}`,
+        ];
+        const role = joinData?.role;
+        const systemPrompt = joinData?.systemPrompt;
+        if (role)
+            outputParts.push(`Role: ${role}`);
+        outputParts.push(`Browser: ${state.browserUrl || SERVER_URL}`, `Server: ${SERVER_URL}`, ``);
+        if (systemPrompt) {
+            outputParts.push(`Your instructions:`, systemPrompt, ``);
+        }
+        outputParts.push(formatState(state.sharedState, joinData?.observation || state.observation), `Participants: ${state.participants?.join(", ")}`, ``, `Tools:`, formatToolList(joinData?.tools || state.tools || []), ``);
+        // Surface unfilled autoSpawn slots
+        if (unfilledSlots.length > 0) {
+            outputParts.push(`UNFILLED AI SLOTS (autoSpawn):`, ...unfilledSlots.map(s => `  - ${s.role} (max ${s.maxInstances ?? 1})`), ``, `These roles need AI agents. Spawn independent teammates — each gets its own MCP session and identity.`, `  Agent(subagent_type="general-purpose", model="sonnet", run_in_background=true,`, `    prompt="Call connect with role='ROLE'. Then play your role.")`, ``);
+        }
+        // Mode-specific instructions
+        if (agentMode === "behavior") {
+            outputParts.push(`BEHAVIOR MODE:`, `  You are a behavior-only agent. All actions run autonomously via the tick engine.`, `  No stop hook — you will NOT receive wake-up events.`, `  Set up behaviors now, then disconnect. The tick engine runs them automatically.`, ``);
+        }
+        else if (agentMode === "manual") {
+            outputParts.push(`MANUAL MODE:`, `  You are a manual agent. Use act() for all decisions. No behaviors.`, `  The stop hook keeps you present — use act to interact.`, `  COMMUNICATE: Use _chat.send to share strategy. Use _chat.team for team-only coordination.`, ``);
+        }
+        else {
+            outputParts.push(`FAST BRAIN / SLOW BRAIN:`, `  Fast brain: Register behaviors via _behavior.set for reactive, per-tick actions that run automatically.`, `  Slow brain: Use act() for strategic decisions and adapting to new situations.`, `  Set up your fast brain FIRST, then use your slow brain to observe and adapt.`, `  COMMUNICATE: Use _chat.send to share strategy. Use _chat.team for team-only coordination.`, ``, `You are now a live participant. The stop hook keeps you present — use act to interact.`);
+        }
+        // Register the stop hook so Claude Code wakes us on events
+        ensureStopHook();
+        return { content: [{ type: "text", text: outputParts.filter(Boolean).join("\n") }] };
     }
     catch (err) {
         return {
             content: [{
                     type: "text",
-                    text: `Failed to connect to ${SERVER_URL}.\n\nIs the dev server running? (npm run dev)\n\nError: ${err.message}`,
+                    text: `Failed to connect.\n\nIs the dev server running? (npm run dev)\n\nError: ${toErrorMessage(err)}`,
                 }],
         };
     }
 });
-// ── Tool: watch ────────────────────────────────────────────
-server.tool("watch", `Wait for activity in the experience. Blocks until events arrive or timeout.
-
-Use predicate to wait for a condition, e.g. "state.count > 5".
-Use filterTools to only wake for specific tools, e.g. ["pixel.place"].
-Use filterActors to only wake for specific actors.
-
-Auto-connects if not already connected.`, {
-    timeout: z.number().optional().describe("Max wait ms (default 30000, max 55000)"),
-    predicate: z.string().optional().describe('JS expression, e.g. "state.count > 5"'),
-    filterTools: z.array(z.string()).optional().describe("Only wake for these tools"),
-    filterActors: z.array(z.string()).optional().describe("Only wake for these actors"),
-}, async ({ timeout, predicate, filterTools, filterActors }) => {
+// ── Tool: act ──────────────────────────────────────────────
+server.tool("act", `Execute a tool to mutate shared state. All state changes go through tools.
+
+Supports batching: pass a "batch" array to execute multiple tool calls sequentially in one round-trip.
+Each call sees the state left by the previous call, so order matters.
+
+Single call:
+  act(toolName="counter.increment", input={amount: 2})
+
+Batch call (multiple tools in one round-trip):
+  act(batch=[
+    {toolName: "counter.increment", input: {amount: 2}},
+    {toolName: "counter.increment", input: {amount: 3}},
+    {toolName: "phase.set", input: {phase: "playing"}}
+  ])`, {
+    toolName: z.string().optional().describe("Tool to call, e.g. 'counter.increment'. Required if batch is not provided."),
+    input: z.record(z.unknown()).optional().describe("Tool input parameters (for single call)"),
+    batch: z.array(z.object({
+        toolName: z.string().describe("Tool to call"),
+        input: z.record(z.unknown()).optional().describe("Tool input parameters"),
+    })).optional().describe("Array of tool calls to execute sequentially in one round-trip. Each call sees the state from the previous call."),
+    actorId: z.string().optional().describe("Your actorId from the connect response. Required when multiple agents are connected in the same session."),
+}, async ({ toolName, input, batch, actorId }) => {
+    let slot;
     try {
-        await ensureConnected();
+        slot = resolveIdentity(actorId);
     }
     catch (err) {
-        return { content: [{ type: "text", text: `Not connected: ${err.message}` }] };
-    }
-    const t = Math.min(timeout || 30000, 55000);
-    // Check if predicate already matches
-    if (predicate) {
         try {
-            const current = await fetchJSON("/state");
-            const fn = new Function("state", "actorId", `return ${predicate}`);
-            if (fn(current.sharedState, currentActorId)) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: [
-                                `Predicate already true: ${predicate}`,
-                                `State: ${JSON.stringify(current.sharedState, null, 2)}`,
-                                `Participants: ${current.participants?.join(", ")}`,
-                            ].join("\n"),
-                        }],
-                };
-            }
+            loadIdentity();
         }
-        catch {
-            // Predicate eval failed, continue to long-poll
+        catch { }
+        try {
+            slot = resolveIdentity(actorId);
+        }
+        catch (err2) {
+            return { content: [{ type: "text", text: `Not connected: ${toErrorMessage(err2)}` }] };
         }
     }
-    // Long-poll for events
-    const data = await fetchJSON(`/events?since=${lastEventTs}&timeout=${t}`);
-    let events = data.events || [];
-    if (filterTools?.length) {
-        events = events.filter((e) => filterTools.includes(e.tool));
-    }
-    if (filterActors?.length) {
-        events = events.filter((e) => filterActors.includes(e.actorId));
+    const effectiveActorId = slot.actorId;
+    // Build the list of calls: either from batch or single toolName+input
+    const calls = batch && batch.length > 0
+        ? batch
+        : toolName
+            ? [{ toolName, input }]
+            : [];
+    if (calls.length === 0) {
+        return { content: [{ type: "text", text: `Provide either toolName or batch.` }] };
     }
-    if (events.length > 0) {
-        lastEventTs = Math.max(...events.map((e) => e.ts));
+    // Validate tool names to prevent path traversal
+    const SAFE_TOOL_NAME = /^[a-zA-Z0-9_.\-]+$/;
+    for (const call of calls) {
+        if (!SAFE_TOOL_NAME.test(call.toolName)) {
+            return { content: [{ type: "text", text: `Invalid tool name: "${call.toolName}". Tool names may only contain letters, digits, dots, hyphens, and underscores.` }] };
+        }
     }
-    let predicateMatched = false;
-    if (predicate) {
+    const effectiveOwner = slot.owner || currentOwner || undefined;
+    const results = [];
+    if (calls.length === 1) {
+        const call = calls[0];
         try {
-            const fn = new Function("state", "actorId", `return ${predicate}`);
-            predicateMatched = !!fn(data.sharedState, currentActorId);
+            const idempotencyKey = `${effectiveActorId}-${call.toolName}-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+            const result = await fetchJSON(`/tools/${call.toolName}`, {
+                method: "POST",
+                headers: { "X-Idempotency-Key": idempotencyKey },
+                body: JSON.stringify({
+                    actorId: effectiveActorId || "mcp-client",
+                    owner: effectiveOwner,
+                    input: call.input || {},
+                }),
+                timeoutMs: 30000,
+            });
+            if (result.error) {
+                results.push({ toolName: call.toolName, error: result.error });
+            }
+            else {
+                results.push({ toolName: call.toolName, output: result.output, observation: result.observation });
+            }
         }
-        catch {
-            // ignore
+        catch (err) {
+            results.push({ toolName: call.toolName, error: toErrorMessage(err) });
         }
     }
-    const parts = [];
-    if (events.length > 0) {
-        parts.push(`${events.length} event(s):`);
-        for (const e of events) {
-            parts.push(`  [${e.actorId}] ${e.tool}(${JSON.stringify(e.input)}) → ${e.error ? `ERROR: ${e.error}` : JSON.stringify(e.output)}`);
+    else {
+        try {
+            const batchResult = await fetchJSON(`/tools-batch`, {
+                method: "POST",
+                body: JSON.stringify({
+                    actorId: effectiveActorId || "mcp-client",
+                    owner: effectiveOwner,
+                    calls: calls.map(c => ({ tool: c.toolName, input: c.input || {} })),
+                }),
+                timeoutMs: 30000,
+            });
+            if (batchResult.results && Array.isArray(batchResult.results)) {
+                for (const r of batchResult.results) {
+                    if (r.error) {
+                        results.push({ toolName: r.tool, error: r.error });
+                    }
+                    else {
+                        results.push({ toolName: r.tool, output: r.output, observation: r.observation });
+                    }
+                }
+            }
+            else if (batchResult.error) {
+                results.push({ toolName: calls[0].toolName, error: batchResult.error });
+            }
+        }
+        catch (_batchErr) {
+            // Fallback: if batch endpoint fails, run calls individually
+            for (const call of calls) {
+                try {
+                    const result = await fetchJSON(`/tools/${call.toolName}`, {
+                        method: "POST",
+                        body: JSON.stringify({
+                            actorId: effectiveActorId || "mcp-client",
+                            owner: effectiveOwner,
+                            input: call.input || {},
+                        }),
+                        timeoutMs: 30000,
+                    });
+                    if (result.error) {
+                        results.push({ toolName: call.toolName, error: result.error });
+                    }
+                    else {
+                        results.push({ toolName: call.toolName, output: result.output, observation: result.observation });
+                    }
+                }
+                catch (e) {
+                    results.push({ toolName: call.toolName, error: toErrorMessage(e) });
+                }
+            }
         }
     }
-    else {
-        parts.push("No new events (timeout).");
+    // Build compact response
+    const outputParts = [];
+    let lastObservation = null;
+    for (const r of results) {
+        if (r.error) {
+            outputParts.push(`${r.toolName} → ERROR: ${r.error}`);
+        }
+        else {
+            outputParts.push(`${r.toolName} → ${JSON.stringify(r.output)}`);
+            if (r.observation)
+                lastObservation = r.observation;
+        }
     }
-    parts.push(`State: ${JSON.stringify(data.sharedState, null, 2)}`);
-    parts.push(`Participants: ${data.participants?.join(", ")}`);
-    if (predicate) {
-        parts.push(`Predicate "${predicate}": ${predicateMatched}`);
+    if (lastObservation) {
+        outputParts.push(`Observation: ${JSON.stringify(lastObservation)}`);
     }
-    return { content: [{ type: "text", text: parts.join("\n") }] };
+    return { content: [{ type: "text", text: outputParts.join("\n") }] };
 });
-// ── Tool: act ──────────────────────────────────────────────
-server.tool("act", `Execute a tool to mutate shared state. All state changes go through tools.
-
-Example: act(toolName="counter.increment", input={amount: 2})
-
-Auto-connects if not already connected.`, {
-    toolName: z.string().describe("Tool to call, e.g. 'counter.increment'"),
-    input: z.record(z.any()).optional().describe("Tool input parameters"),
-}, async ({ toolName, input }) => {
+// ── Tool: look ─────────────────────────────────────────────
+server.tool("look", `Observe the current state without taking any action.
+
+Returns the observation (or raw state), participants, and available tools.
+Read-only — no mutations, no events created.
+
+Use this to orient yourself before deciding whether to act.`, {
+    actorId: z.string().optional().describe("Your actorId from connect. Required when multiple agents connected."),
+}, async ({ actorId }) => {
+    let slot;
     try {
-        await ensureConnected();
+        slot = resolveIdentity(actorId);
     }
-    catch (err) {
-        return { content: [{ type: "text", text: `Not connected: ${err.message}` }] };
-    }
-    const result = await fetchJSON(`/tools/${toolName}`, {
-        method: "POST",
-        body: JSON.stringify({
-            actorId: currentActorId || "mcp-client",
-            input: input || {},
-        }),
-    });
-    if (result.error) {
-        return { content: [{ type: "text", text: `Tool error: ${result.error}` }] };
-    }
-    const state = await fetchJSON("/state");
-    const output = [
-        `${toolName} → ${JSON.stringify(result.output)}`,
-        `State: ${JSON.stringify(state.sharedState, null, 2)}`,
-    ].join("\n");
-    return { content: [{ type: "text", text: output }] };
-});
-// ── Tool: memory ───────────────────────────────────────────
-server.tool("memory", `Persistent agent memory (per-session). Survives across tool calls.
-
-Actions:
-  get — Retrieve current memory
-  set — Merge updates into memory`, {
-    action: z.enum(["get", "set"]).describe("What to do"),
-    updates: z.record(z.any()).optional().describe("Key-value pairs to merge (for set)"),
-}, async ({ action, updates }) => {
-    const key = currentActorId
-        ? `local:${currentActorId}`
-        : "default";
-    if (action === "get") {
-        const data = await fetchJSON(`/memory?key=${encodeURIComponent(key)}`);
-        return {
-            content: [{
-                    type: "text",
-                    text: `Memory: ${JSON.stringify(data, null, 2)}`,
-                }],
-        };
-    }
-    if (action === "set") {
-        if (!updates || Object.keys(updates).length === 0) {
-            return { content: [{ type: "text", text: "No updates provided." }] };
+    catch {
+        try {
+            loadIdentity();
+            slot = resolveIdentity(actorId);
         }
-        await fetchJSON("/memory", {
-            method: "POST",
-            body: JSON.stringify({ key, updates }),
-        });
-        return { content: [{ type: "text", text: `Memory updated: ${JSON.stringify(updates)}` }] };
+        catch (err) {
+            return { content: [{ type: "text", text: `Not connected: ${toErrorMessage(err)}` }] };
+        }
+    }
+    try {
+        const actorParam = slot.actorId ? `?actorId=${encodeURIComponent(slot.actorId)}` : "";
+        const state = await fetchJSON(`/state${actorParam}`, { timeoutMs: 10000 });
+        const outputParts = [];
+        outputParts.push(`Experience: ${state.experienceId || "unknown"}`);
+        outputParts.push(formatState(state.sharedState, state.observation));
+        outputParts.push(`Participants: ${(state.participants || []).join(", ")}`);
+        return { content: [{ type: "text", text: outputParts.join("\n") }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Look failed: ${toErrorMessage(err)}` }] };
     }
-    return { content: [{ type: "text", text: `Unknown action: ${action}` }] };
 });
-// ── Tool: screenshot ──────────────────────────────────────
-server.tool("screenshot", `Capture a screenshot of the experience as seen in the browser.
-
-Returns the current visual state as a PNG image.
-Requires the browser viewer to be open.
-
-Use this to see what the user sees — inspect paintings, check layouts, read rendered text, etc.`, {
-    timeout: z.number().optional().describe("Max wait ms (default 10000)"),
-}, async ({ timeout }) => {
+// ── Tool: disconnect ────────────────────────────────────────
+server.tool("disconnect", `Disconnect from the current experience.
+
+Removes the agent as a participant, deletes the session file, and cleans up.
+After disconnecting, the stop hook will no longer fire.
+If the experience has locked agent participation (canDisconnect: false in observe()),
+the disconnect will be rejected unless force=true is passed.`, {
+    force: z.boolean().optional().describe("Force disconnect even if the experience has locked participation"),
+    actorId: z.string().optional().describe("Disconnect a specific agent by actorId. Defaults to most recent connection. Use 'all' to disconnect all agents."),
+}, async ({ force, actorId: disconnectActorId }) => {
     try {
-        const t = Math.min(timeout || 10000, 30000);
-        const screenshotHeaders = {};
-        if (ROOM_TOKEN) {
-            screenshotHeaders["Authorization"] = `Bearer ${ROOM_TOKEN}`;
+        // Handle "disconnect all"
+        if (disconnectActorId === "all") {
+            const allSlots = [...connections.values()];
+            for (const s of allSlots) {
+                try {
+                    await fetchJSON("/leave", { method: "POST", body: JSON.stringify({ actorId: s.actorId }), timeoutMs: 5000 });
+                }
+                catch { }
+                try {
+                    unlinkSync(resolve(AGENTS_DIR, `${s.owner}.json`));
+                }
+                catch { }
+                connections.delete(s.actorId);
+            }
+            currentActorId = null;
+            currentOwner = null;
+            removeStopHook();
+            return { content: [{ type: "text", text: `Disconnected all ${allSlots.length} agent(s).` }] };
         }
-        const res = await fetch(`${SERVER_URL}/screenshot?timeout=${t}`, {
-            headers: screenshotHeaders,
-        });
-        if (!res.ok) {
-            const err = await res.json().catch(() => ({ error: res.statusText }));
-            return {
-                content: [{
-                        type: "text",
-                        text: `Screenshot failed: ${err.error || "Unknown error"}`,
-                    }],
-            };
+        // Resolve which identity to disconnect
+        let identity;
+        if (disconnectActorId && connections.has(disconnectActorId)) {
+            const s = connections.get(disconnectActorId);
+            identity = { actorId: s.actorId, serverUrl: SERVER_URL, owner: s.owner };
+        }
+        else {
+            try {
+                identity = loadIdentity();
+            }
+            catch {
+                // Fallback: scan agent files on disk (handles MCP process restart)
+                const cleaned = [];
+                if (existsSync(AGENTS_DIR)) {
+                    for (const file of readdirSync(AGENTS_DIR).filter(f => f.endsWith(".json"))) {
+                        try {
+                            const agent = JSON.parse(readFileSync(resolve(AGENTS_DIR, file), "utf-8"));
+                            try {
+                                const sUrl = agent.serverUrl || SERVER_URL;
+                                await fetch(`${sUrl}/leave`, {
+                                    method: "POST",
+                                    headers: { "Content-Type": "application/json" },
+                                    body: JSON.stringify({ actorId: agent.actorId }),
+                                    signal: AbortSignal.timeout(3000),
+                                });
+                            }
+                            catch { }
+                            unlinkSync(resolve(AGENTS_DIR, file));
+                            cleaned.push(agent.owner || file);
+                        }
+                        catch {
+                            try {
+                                unlinkSync(resolve(AGENTS_DIR, file));
+                            }
+                            catch { }
+                            cleaned.push(file);
+                        }
+                    }
+                }
+                removeStopHook();
+                if (cleaned.length > 0) {
+                    return { content: [{ type: "text", text: `Recovered from stale state. Cleaned up ${cleaned.length} agent(s): ${cleaned.join(", ")}` }] };
+                }
+                return { content: [{ type: "text", text: `Not connected. No agent files found to clean up.` }] };
+            }
+        }
+        // Check canDisconnect via agent-context
+        if (!force) {
+            try {
+                const ownerParam = identity.owner ? `&owner=${encodeURIComponent(identity.owner)}` : "";
+                const ctxUrl = `/agent-context?timeout=0&actorId=${encodeURIComponent(identity.actorId)}${ownerParam}`;
+                const ctx = await fetchJSON(ctxUrl, { timeoutMs: 10000 });
+                if (ctx?.observation?.canDisconnect === false) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `The experience has locked agent participation (canDisconnect: false). The experience controls when agents can leave. Use force=true to override.`,
+                            }],
+                    };
+                }
+            }
+            catch {
+                // If we can't check, allow disconnect (server may be down)
+            }
+        }
+        // POST /leave to remove participant from server
+        try {
+            await fetchJSON("/leave", {
+                method: "POST",
+                body: JSON.stringify({ actorId: identity.actorId }),
+                timeoutMs: 5000,
+            });
+        }
+        catch {
+            // Server may already be down — continue with local cleanup
+        }
+        // Delete own agent file
+        if (identity.owner) {
+            try {
+                unlinkSync(resolve(AGENTS_DIR, `${identity.owner}.json`));
+            }
+            catch { }
+        }
+        // Remove from connections map
+        connections.delete(identity.actorId);
+        // Clean up if no connections remain
+        if (connections.size === 0) {
+            removeStopHook();
+            currentActorId = null;
+            currentOwner = null;
+        }
+        else {
+            // Update current to the last remaining connection
+            const last = [...connections.values()].pop();
+            currentActorId = last.actorId;
+            currentOwner = last.owner;
         }
-        const arrayBuffer = await res.arrayBuffer();
-        const base64 = Buffer.from(arrayBuffer).toString("base64");
         return {
             content: [{
-                    type: "image",
-                    data: base64,
-                    mimeType: "image/png",
+                    type: "text",
+                    text: connections.size === 0
+                        ? `Disconnected from experience. You are no longer a participant.`
+                        : `Disconnected ${identity.actorId}. ${connections.size} agent(s) still connected.`,
                 }],
         };
     }
@@ -303,7 +825,7 @@ Use this to see what the user sees — inspect paintings, check layouts, read re
         return {
             content: [{
                     type: "text",
-                    text: `Screenshot failed: ${err.message}. Is the dev server running? Is the browser open?`,
+                    text: `Disconnect failed: ${toErrorMessage(err)}`,
                 }],
         };
     }
@@ -317,3 +839,27 @@ main().catch((err) => {
     console.error("MCP server failed:", err);
     process.exit(1);
 });
+// ── Exit handler: best-effort cleanup on process exit ──────
+let cleaned = false;
+function cleanup() {
+    if (cleaned)
+        return;
+    cleaned = true;
+    if (currentActorId) {
+        try {
+            const leaveUrl = `${SERVER_URL}/leave`;
+            const script = `fetch(process.argv[1],{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({actorId:process.argv[2]})}).catch(()=>{})`;
+            spawnSync("node", ["-e", script, leaveUrl, currentActorId], { timeout: 3000, stdio: "ignore" });
+        }
+        catch { }
+    }
+    if (currentOwner) {
+        try {
+            unlinkSync(resolve(AGENTS_DIR, `${currentOwner}.json`));
+        }
+        catch { }
+    }
+    removeStopHook();
+}
+process.on("SIGINT", () => { cleanup(); process.exit(0); });
+process.on("SIGTERM", () => { cleanup(); process.exit(0); });