iframer-toolkit 0.7.1 → 0.9.0

package/dist/mcp-server.cjs

@@ -35,8 +35,8 @@ var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
 // src/mcp/helpers.ts
-var import_path4 = __toESM(require("path"));
-var import_os2 = __toESM(require("os"));
+var import_path5 = __toESM(require("path"));
+var import_os3 = __toESM(require("os"));
 
 // src/lib/logger.ts
 var LEVELS = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
@@ -66,6 +66,7 @@ function createLogger(tag) {
 // src/lib/auth/crypto.ts
 var import_crypto = __toESM(require("crypto"));
 var import_fs = __toESM(require("fs"));
+var import_os2 = __toESM(require("os"));
 var import_path2 = __toESM(require("path"));
 
 // src/lib/paths.ts
@@ -79,164 +80,226 @@ function getDataDir() {
 function getLocalToken() {
   if (process.env.IFRAMER_SECRET)
     return process.env.IFRAMER_SECRET;
-  const dir = getDataDir();
-  const file = import_path2.default.join(dir, "secret");
-  try {
-    const existing = import_fs.default.readFileSync(file, "utf8").trim();
-    if (existing)
-      return existing;
-  } catch {}
-  try {
-    import_fs.default.mkdirSync(dir, { recursive: true });
-    const secret = import_crypto.default.randomBytes(32).toString("hex");
-    import_fs.default.writeFileSync(file, secret, { mode: 384 });
-    return secret;
-  } catch {
-    return "iframer-local-default-token";
+  const candidates = [
+    import_path2.default.join(getDataDir(), "secret"),
+    import_path2.default.join(process.env.XDG_RUNTIME_DIR || import_os2.default.tmpdir(), "iframer-secret")
+  ];
+  for (const file of candidates) {
+    try {
+      const existing = import_fs.default.readFileSync(file, "utf8").trim();
+      if (existing)
+        return existing;
+    } catch {}
+  }
+  for (const file of candidates) {
+    try {
+      import_fs.default.mkdirSync(import_path2.default.dirname(file), { recursive: true });
+      const secret = import_crypto.default.randomBytes(32).toString("hex");
+      import_fs.default.writeFileSync(file, secret, { mode: 384 });
+      return secret;
+    } catch {}
   }
+  throw new Error("iframer: could not read or create a persistent encryption secret in any " + `writable location (${candidates.join(", ")}). Set IFRAMER_SECRET to a ` + "stable value shared between the MCP server and CLI (openssl rand -hex 32).");
 }
 
 // src/mcp/local-server.ts
 var import_child_process = require("child_process");
+var import_net = __toESM(require("net"));
+var import_fs3 = __toESM(require("fs"));
+var import_path4 = __toESM(require("path"));
+
+// src/lib/browser/registry.ts
 var import_fs2 = __toESM(require("fs"));
 var import_path3 = __toESM(require("path"));
+var log = createLogger("registry");
+function serverInfoPath() {
+  return import_path3.default.join(getDataDir(), "server.json");
+}
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 1)
+    return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readServerInfo() {
+  try {
+    const info = JSON.parse(import_fs2.default.readFileSync(serverInfoPath(), "utf8"));
+    if (!Number.isInteger(info.pid) || !Number.isInteger(info.port))
+      return null;
+    return info;
+  } catch {
+    return null;
+  }
+}
+
+// src/mcp/local-server.ts
 var __dirname = "/Users/eduardoverona/tools/iframer-toolkit/src/mcp";
-var PORT = parseInt(process.env.IFRAMER_LOCAL_PORT || "3022", 10);
+var BASE_PORT = parseInt(process.env.IFRAMER_LOCAL_PORT || "3022", 10);
+var PORT_SCAN_ATTEMPTS = 200;
 var STARTUP_TIMEOUT_MS = 15000;
 var HEALTH_POLL_MS = 300;
+var SPAWN_LOCK_STALE_MS = 20000;
 
 class LocalServerManager {
-  child = null;
   startingPromise = null;
-  baseUrl;
+  baseUrl = "";
   logPath;
   constructor() {
-    this.baseUrl = `http://127.0.0.1:${PORT}`;
-    this.logPath = import_path3.default.join(getDataDir(), "local-server.log");
+    this.logPath = import_path4.default.join(getDataDir(), "local-server.log");
   }
   getBaseUrl() {
+    if (!this.baseUrl) {
+      throw new Error("Local server not started yet — call ensureRunning() first.");
+    }
     return this.baseUrl;
   }
   async ensureRunning() {
-    if (this.child && !this.child.killed && await this.healthCheck())
-      return;
     if (this.startingPromise)
       return this.startingPromise;
-    this.startingPromise = this.doStart().finally(() => {
+    if (await this.adoptExisting())
+      return;
+    this.startingPromise = this.startShared().finally(() => {
       this.startingPromise = null;
     });
     return this.startingPromise;
   }
-  async doStart() {
-    await this.killExisting();
+  async adoptExisting() {
+    const info = readServerInfo();
+    if (!info || !isPidAlive(info.pid))
+      return false;
+    const url = `http://127.0.0.1:${info.port}`;
+    if (await healthCheck(url)) {
+      this.baseUrl = url;
+      return true;
+    }
+    return false;
+  }
+  async startShared() {
     const dataDir = getDataDir();
-    import_fs2.default.mkdirSync(dataDir, { recursive: true });
-    const { command, args } = this.resolveRuntime();
-    const logFd = import_fs2.default.openSync(this.logPath, "a");
-    const env = {
-      ...process.env,
-      PORT: String(PORT),
-      IFRAMER_MODE: "local",
-      IFRAMER_DATA_DIR: dataDir
-    };
-    if (process.env.IFRAMER_SECRET) {
-      env.IFRAMER_SECRET = process.env.IFRAMER_SECRET;
-    } else {
-      try {
-        const secret = import_fs2.default.readFileSync(import_path3.default.join(dataDir, "secret"), "utf8").trim();
-        if (secret)
-          env.IFRAMER_SECRET = secret;
-      } catch {}
+    import_fs3.default.mkdirSync(dataDir, { recursive: true });
+    const lockDir = import_path4.default.join(dataDir, "server.spawn-lock");
+    let holdingLock = false;
+    try {
+      import_fs3.default.mkdirSync(lockDir);
+      holdingLock = true;
+    } catch {
+      const stale = (() => {
+        try {
+          return Date.now() - import_fs3.default.statSync(lockDir).mtimeMs > SPAWN_LOCK_STALE_MS;
+        } catch {
+          return true;
+        }
+      })();
+      if (stale) {
+        try {
+          import_fs3.default.rmdirSync(lockDir);
+          import_fs3.default.mkdirSync(lockDir);
+          holdingLock = true;
+        } catch {}
+      }
     }
-    this.child = import_child_process.spawn(command, args, {
-      env,
-      stdio: ["ignore", logFd, logFd],
-      detached: false
-    });
-    import_fs2.default.closeSync(logFd);
-    this.child.on("exit", (code) => {
-      this.child = null;
-    });
-    const deadline = Date.now() + STARTUP_TIMEOUT_MS;
-    while (Date.now() < deadline) {
-      if (await this.healthCheck())
+    try {
+      if (!holdingLock) {
+        const deadline2 = Date.now() + STARTUP_TIMEOUT_MS;
+        while (Date.now() < deadline2) {
+          if (await this.adoptExisting())
+            return;
+          await sleep(HEALTH_POLL_MS);
+        }
+        throw new Error("Timed out waiting for another session to start the shared iframer server.");
+      }
+      if (await this.adoptExisting())
         return;
-      await sleep(HEALTH_POLL_MS);
-    }
-    this.kill();
-    const logTail = this.readLogTail();
-    throw new Error(`Local iframer server failed to start on port ${PORT} within ${STARTUP_TIMEOUT_MS}ms.
+      const port = await findFreePort(BASE_PORT, PORT_SCAN_ATTEMPTS);
+      const url = `http://127.0.0.1:${port}`;
+      const { command, args } = this.resolveRuntime();
+      const logFd = import_fs3.default.openSync(this.logPath, "a");
+      const env = {
+        ...process.env,
+        PORT: String(port),
+        IFRAMER_MODE: "local",
+        IFRAMER_DATA_DIR: dataDir
+      };
+      if (process.env.IFRAMER_SECRET) {
+        env.IFRAMER_SECRET = process.env.IFRAMER_SECRET;
+      } else {
+        try {
+          const secret = import_fs3.default.readFileSync(import_path4.default.join(dataDir, "secret"), "utf8").trim();
+          if (secret)
+            env.IFRAMER_SECRET = secret;
+        } catch {}
+      }
+      const child = import_child_process.spawn(command, args, {
+        env,
+        stdio: ["ignore", logFd, logFd],
+        detached: true
+      });
+      child.unref();
+      import_fs3.default.closeSync(logFd);
+      const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+      while (Date.now() < deadline) {
+        if (await healthCheck(url)) {
+          this.baseUrl = url;
+          return;
+        }
+        await sleep(HEALTH_POLL_MS);
+      }
+      try {
+        child.kill("SIGKILL");
+      } catch {}
+      throw new Error(`Local iframer server failed to start on port ${port} within ${STARTUP_TIMEOUT_MS}ms.
 ` + `Last log lines:
-${logTail}`);
+${this.readLogTail()}`);
+    } finally {
+      if (holdingLock) {
+        try {
+          import_fs3.default.rmdirSync(lockDir);
+        } catch {}
+      }
+    }
   }
   resolveRuntime() {
     try {
       const bunPath = require("child_process").execSync("which bun", { encoding: "utf8" }).trim();
-      const serverTs2 = import_path3.default.join(__dirname, "..", "..", "index.ts");
-      if (import_fs2.default.existsSync(serverTs2)) {
+      const serverTs2 = import_path4.default.join(__dirname, "..", "..", "index.ts");
+      if (import_fs3.default.existsSync(serverTs2)) {
         return { command: bunPath, args: ["run", serverTs2] };
       }
     } catch {}
-    const serverCjs = import_path3.default.join(__dirname, "..", "..", "dist", "local-server.cjs");
-    if (import_fs2.default.existsSync(serverCjs)) {
+    const serverCjs = import_path4.default.join(__dirname, "..", "..", "dist", "local-server.cjs");
+    if (import_fs3.default.existsSync(serverCjs)) {
       return { command: "node", args: [serverCjs] };
     }
-    const serverTs = import_path3.default.join(__dirname, "..", "..", "index.ts");
+    const serverTs = import_path4.default.join(__dirname, "..", "..", "index.ts");
     return { command: "node", args: ["--import", "tsx", serverTs] };
   }
   async restart() {
-    this.kill();
-    await sleep(500);
-    await this.ensureRunning();
-  }
-  shutdown() {
-    this.kill();
-  }
-  kill() {
-    if (this.child && !this.child.killed) {
+    const info = readServerInfo();
+    if (info && this.baseUrl) {
       try {
-        this.child.kill("SIGTERM");
+        await fetch(`${this.baseUrl}/shutdown`, { method: "POST", signal: AbortSignal.timeout(3000) });
       } catch {}
-      const c = this.child;
-      setTimeout(() => {
-        try {
-          if (!c.killed)
-            c.kill("SIGKILL");
-        } catch {}
-      }, 2000);
-    }
-    this.child = null;
-  }
-  async killExisting() {
-    try {
-      const res = await fetch(`${this.baseUrl}/health`, {
-        signal: AbortSignal.timeout(2000)
-      });
-      if (res.ok) {
+      const deadline = Date.now() + 12000;
+      while (Date.now() < deadline && isPidAlive(info.pid)) {
+        await sleep(200);
+      }
+      if (isPidAlive(info.pid)) {
         try {
-          await fetch(`${this.baseUrl}/shutdown`, {
-            method: "POST",
-            signal: AbortSignal.timeout(2000)
-          });
+          process.kill(info.pid, "SIGKILL");
         } catch {}
-        await sleep(500);
       }
-    } catch {}
-  }
-  async healthCheck() {
-    try {
-      const res = await fetch(`${this.baseUrl}/health`, {
-        signal: AbortSignal.timeout(2000)
-      });
-      const data = await res.json();
-      return data.ok === true;
-    } catch {
-      return false;
     }
+    this.baseUrl = "";
+    await this.ensureRunning();
   }
+  shutdown() {}
   readLogTail() {
     try {
-      const content = import_fs2.default.readFileSync(this.logPath, "utf8");
+      const content = import_fs3.default.readFileSync(this.logPath, "utf8");
       const lines = content.trim().split(`
 `);
       return lines.slice(-10).join(`
@@ -249,9 +312,43 @@ ${logTail}`);
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
+async function healthCheck(baseUrl) {
+  try {
+    const res = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(2000) });
+    const data = await res.json();
+    return data.ok === true;
+  } catch {
+    return false;
+  }
+}
+function findFreePort(start, attempts) {
+  return new Promise((resolve, reject) => {
+    const tryPort = (p) => {
+      if (p >= start + attempts) {
+        reject(new Error(`No free port found in ${start}-${start + attempts}`));
+        return;
+      }
+      const srv = import_net.default.createServer();
+      srv.once("error", () => {
+        srv.close();
+        tryPort(p + 1);
+      });
+      srv.once("listening", () => {
+        srv.close(() => resolve(p));
+      });
+      srv.listen(p, "127.0.0.1");
+    };
+    tryPort(start);
+  });
+}
+
+// src/lib/errors.ts
+function getErrorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
 
 // src/mcp/helpers.ts
-var log = createLogger("mcp");
+var log2 = createLogger("mcp");
 var BASE_URL = process.env.IFRAMER_URL || "http://localhost:3021";
 var IFRAMER_SECRET = process.env.IFRAMER_SECRET;
 var IFRAMER_MODE = process.env.IFRAMER_MODE;
@@ -317,8 +414,8 @@ async function resolveScreenshotPath(url) {
     if (url.startsWith("file://")) {
       const { fileURLToPath } = await import("url");
       const filePath2 = fileURLToPath(url);
-      const fs4 = await import("fs");
-      if (fs4.existsSync(filePath2))
+      const fs5 = await import("fs");
+      if (fs5.existsSync(filePath2))
         return filePath2;
       return null;
     }
@@ -326,11 +423,11 @@ async function resolveScreenshotPath(url) {
     if (!res.ok)
       return null;
     const buf = Buffer.from(await res.arrayBuffer());
-    const fs3 = await import("fs");
-    const dir = import_path4.default.join(import_os2.default.tmpdir(), "iframer-screenshots", "screenshots");
-    fs3.mkdirSync(dir, { recursive: true });
-    const filePath = import_path4.default.join(dir, `docker-${Date.now()}.jpg`);
-    fs3.writeFileSync(filePath, buf);
+    const fs4 = await import("fs");
+    const dir = import_path5.default.join(import_os3.default.tmpdir(), "iframer-screenshots", "screenshots");
+    fs4.mkdirSync(dir, { recursive: true });
+    const filePath = import_path5.default.join(dir, `docker-${Date.now()}.jpg`);
+    fs4.writeFileSync(filePath, buf);
     return filePath;
   } catch {
     return null;
@@ -339,16 +436,13 @@ async function resolveScreenshotPath(url) {
 function err(message) {
   return { content: [{ type: "text", text: message }], isError: true };
 }
-function getErrorMessage(err2) {
-  return err2 instanceof Error ? err2.message : String(err2);
-}
 
 // src/lib/domain-modes.ts
-var import_fs3 = __toESM(require("fs"));
-var import_path5 = __toESM(require("path"));
-var log2 = createLogger("domain-modes");
+var import_fs4 = __toESM(require("fs"));
+var import_path6 = __toESM(require("path"));
+var log3 = createLogger("domain-modes");
 function defaultFile() {
-  return import_path5.default.join(getDataDir(), "domain-modes.json");
+  return import_path6.default.join(getDataDir(), "domain-modes.json");
 }
 var TTL_DAYS = 14;
 var ESCALATION_LADDER = ["headless", "docker-headful", "binary-headful"];
@@ -429,8 +523,8 @@ class DomainModeStore {
   }
   load() {
     try {
-      if (import_fs3.default.existsSync(this.filePath)) {
-        this.data = JSON.parse(import_fs3.default.readFileSync(this.filePath, "utf-8"));
+      if (import_fs4.default.existsSync(this.filePath)) {
+        this.data = JSON.parse(import_fs4.default.readFileSync(this.filePath, "utf-8"));
       }
     } catch {
       this.data = {};
@@ -438,10 +532,10 @@ class DomainModeStore {
   }
   save() {
     try {
-      import_fs3.default.mkdirSync(import_path5.default.dirname(this.filePath), { recursive: true });
-      import_fs3.default.writeFileSync(this.filePath, JSON.stringify(this.data, null, 2));
+      import_fs4.default.mkdirSync(import_path6.default.dirname(this.filePath), { recursive: true });
+      import_fs4.default.writeFileSync(this.filePath, JSON.stringify(this.data, null, 2));
     } catch (err2) {
-      log2.error("Failed to save:", err2);
+      log3.error("Failed to save:", err2);
     }
   }
 }
@@ -554,6 +648,9 @@ var stepSchema = import_zod2.z.discriminatedUnion("type", [
 ]);
 
 // src/mcp/tools/execute.ts
+function resultOf(r, _type) {
+  return r.result;
+}
 function registerExecuteTool(server) {
   server.tool("execute", `Execute a pipeline of browser steps. Auto-starts a session if needed. Handles obstacles (captcha, cookie banners) automatically.
 
@@ -581,7 +678,8 @@ Returns: ok, completedSteps, results, obstacles, capturedApi, and on failure: er
       continueOnError: import_zod3.z.boolean().optional().describe("Continue past failing steps (default: false)"),
       captureApi: import_zod3.z.boolean().optional().describe("Record all API calls (XHR/fetch) the page makes."),
       mode: import_zod3.z.enum(["headless", "binary-headful", "docker-headful"]).optional().describe("DO NOT SET THIS unless user explicitly requests a mode. iframer auto-selects and auto-escalates."),
-      autoEscalate: import_zod3.z.boolean().optional().describe("Auto-retry with a stronger mode if blocked (default: true)")
+      autoEscalate: import_zod3.z.boolean().optional().describe("Auto-retry with a stronger mode if blocked (default: true)"),
+      instanceId: import_zod3.z.string().optional().describe("Run in a named parallel browser within this session (default: 'default'). Use distinct ids to drive several browsers at once, e.g. one per account — each keeps its own login/session state.")
     }).optional()
   }, async (params) => {
     try {
@@ -624,9 +722,9 @@ Returns: ok, completedSteps, results, obstacles, capturedApi, and on failure: er
         execResult = await runWithMode(params.options?.mode);
       } catch (execErr) {
         const msg = execErr instanceof Error ? execErr.message : String(execErr);
-        const isCrash = /connect|ECONNREFUSED|EPIPE|closed|timed out|abort|fetch failed/i.test(msg);
+        const isCrash = /ECONNREFUSED|ECONNRESET|EPIPE|socket hang up|fetch failed/i.test(msg);
         if (isCrash) {
-          log.info(`Execute crashed (${msg.slice(0, 80)}), restarting local server and retrying...`);
+          log2.info(`Execute crashed (${msg.slice(0, 80)}), restarting local server and retrying...`);
           try {
             await localServer.restart();
           } catch {}
@@ -649,7 +747,7 @@ Retry: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}
         for (const nextMode of escalation) {
           if (nextMode === "docker-headful" && !dockerRunning)
             continue;
-          log.info(`Auto-escalating to ${nextMode}`);
+          log2.info(`Auto-escalating to ${nextMode}`);
           execResult = await runWithMode(nextMode);
           if (execResult.ok)
             break;
@@ -704,17 +802,26 @@ Knowledge cache updated for ${domain}. Before the next browser run on this domai
   }
   const meaningful = (data.results || []).filter((r) => r.ok && r.result !== undefined && r.result !== null);
   for (const r of meaningful) {
-    if (r.step?.type === "snapshot" && r.result?.snapshot) {
-      lines.push(`
---- Snapshot (${r.result.elementCount} elements) ---`);
-      lines.push(r.result.snapshot);
-    } else if (r.step?.type === "find" && r.result?.ref) {
-      lines.push(`
-Found: ${r.result.ref} ${r.result.role} "${r.result.name}" (${r.result.matchCount} match${r.result.matchCount > 1 ? "es" : ""})`);
-    } else if (r.step?.type === "screenshot" && r.result?.refs) {
-      lines.push(`
+    if (r.step.type === "snapshot") {
+      const res = resultOf(r, "snapshot");
+      if (res?.snapshot) {
+        lines.push(`
+--- Snapshot (${res.elementCount} elements) ---`);
+        lines.push(res.snapshot);
+      }
+    } else if (r.step.type === "find") {
+      const res = resultOf(r, "find");
+      if (res?.ref) {
+        lines.push(`
+Found: ${res.ref} ${res.role} "${res.name}" (${res.matchCount} match${res.matchCount > 1 ? "es" : ""})`);
+      }
+    } else if (r.step.type === "screenshot") {
+      const res = resultOf(r, "screenshot");
+      if (res?.refs) {
+        lines.push(`
 --- Annotated screenshot refs ---`);
-      lines.push(r.result.refs);
+        lines.push(res.refs);
+      }
     } else if (r.result !== undefined && r.result !== null) {
       lines.push(`
 step ${r.stepIndex}: ${JSON.stringify(r.result)}`);
@@ -759,71 +866,419 @@ ${api.domain} (${api.baseUrl})`);
 }
 
 // src/mcp/tools/session.ts
+var import_zod5 = require("zod");
+var import_path7 = __toESM(require("path"));
+var import_fs5 = __toESM(require("fs"));
+
+// src/mcp/tools/reverse-engineer.ts
 var import_zod4 = require("zod");
-function registerSessionTool(server) {
-  server.tool("session", `Manage the browser session and lifecycle.
+function registerReverseEngineerTool(server) {
+  server.tool("reverse-engineer", `Reverse-engineer a website's API. Navigates to a URL, performs the steps you specify, and captures every XHR/fetch request the page makes — including auth tokens, cookies, headers, request/response bodies, and ready-to-use curl commands.
 
-Actions:
-- **stop**: save cookies/localStorage to the store, then close the browser. Session data persists for the next run.
-- **clear**: wipe all stored session data (cookies/localStorage) from the database. Does NOT kill running browsers.
-- **restart**: kill all running browser instances (local + Docker) and reset state. The next \`execute\` call will launch a fresh browser automatically. Use this when the browser is frozen, crashed, or in a bad state. Credentials and knowledge cache are NOT affected.
+Use this when the user asks to:
+- "reverse engineer" or "map" a site's API
+- "capture the endpoints" or "save the API"
+- "figure out how this site works under the hood"
+- "record the API calls" so they can be replayed later
 
-Sessions live in the single local SQLite database (~/.iframer/iframer.db), shared across every browser mode.`, {
-    action: import_zod4.z.enum(["stop", "clear", "restart"]).describe("stop: save session state + close browser | clear: wipe stored session data | restart: kill all browsers, fresh start on next execute")
-  }, async ({ action }) => {
+How it works:
+1. You provide steps (same as execute) — navigate, click, fill, extract, etc.
+2. iframer runs them while recording all API calls the page makes
+3. Returns structured data per domain: shared auth + endpoints classified by protocol (rest, graphql, json-rpc, grpc-web, form-rpc, soap) with method, path, action, verb, headers, body, response, curl
+
+IMPORTANT — one request ≠ one endpoint. Each endpoint has (protocol, action):
+- REST: action = "METHOD /parameterized/path". Verb from HTTP method.
+- GraphQL: action = operationName (or doc_id for persisted queries). Many ops share the single /graphql URL — EACH operation is its own endpoint.
+- JSON-RPC: action = body.method (e.g. eth_getBalance, user.list).
+- gRPC-web: action = request path.
+- Form-RPC (FB-style urlencoded): action = fb_api_req_friendly_name / doc_id.
+- SOAP: action = SOAPAction header.
+
+Generate ONE function per (protocol, action). Do NOT merge different GraphQL operations into one function just because they share the URL.
+
+Output layout — save as RUNNABLE CODE to <outputDir>/:
+  auth.{js,ts}                  — shared cookies, tokens, authorization
+  transport/
+    rest.{js,ts}                — shared REST helper (only if any rest endpoints)
+    graphql.{js,ts}             — shared GraphQL client: post(operationName|docId, variables)
+    jsonRpc.{js,ts}             — shared JSON-RPC client (if any)
+    grpc.{js,ts}                — shared gRPC-web client (if any)
+  <protocol>/<verb>/<functionName>.{js,ts}
+    e.g. graphql/queries/getTimelineFeed.ts
+         graphql/mutations/reactToPost.ts
+         rest/read/getChannelMessages.ts
+         rest/create/createMessage.ts
+         jsonRpc/ethGetBalance.ts
+  index.{js,ts}                 — re-exports all endpoint functions
+  types.ts                      — (typed mode only) inferred interfaces from responses
+  README.md                     — endpoints grouped by protocol + verb, dependency chain, auth expiry warning
+
+Use capturedApi[i].endpoints[j].protocol, .action, .verb, .functionName directly — iframer already classified them. Put queries (verb=read|list) under queries/, mutations (verb=create|update|delete|action) under mutations/ for GraphQL. For REST, group by verb dir.
+
+The outputDir defaults to ./<domain>/. Ask the user where to save if unclear.`, {
+    steps: import_zod4.z.array(stepSchema).describe("Pipeline steps to execute while capturing API calls"),
+    outputDir: import_zod4.z.string().optional().describe("Directory to save the captured API files. If not provided, ask the user or default to ./<domain>/"),
+    typed: import_zod4.z.boolean().optional().describe("Save as .ts with inferred types instead of .js. Set to true when the user asks for types, typescript, or type inference."),
+    options: import_zod4.z.object({
+      staleTimeoutMs: import_zod4.z.number().optional().describe("Override the 20s stale-state timeout per step"),
+      continueOnObstacle: import_zod4.z.boolean().optional().describe("Try to auto-resolve obstacles (default: true)"),
+      continueOnError: import_zod4.z.boolean().optional().describe("Continue past failing steps (default: false)"),
+      mode: import_zod4.z.enum(["headless", "binary-headful", "docker-headful"]).optional().describe("Browser mode override")
+    }).optional()
+  }, async (params) => {
     try {
-      if (action === "stop") {
-        const result = await localApiPost("/interactive/stop").catch(() => ({ ok: true, sessionSaved: false }));
-        return { content: [{ type: "text", text: `Session stopped. State saved: ${result.sessionSaved ?? false}` }] };
+      const execParams = {
+        steps: params.steps,
+        options: { ...params.options, captureApi: true }
+      };
+      const mode = params.options?.mode;
+      const dockerRunning = await isDockerRunning();
+      const captureResult = mode === "docker-headful" && dockerRunning ? await apiPost("/execute", execParams) : await localApiPost("/execute", execParams);
+      const lines = [];
+      lines.push(`ok: ${captureResult.ok}`);
+      lines.push(`steps: ${captureResult.completedSteps}/${captureResult.totalSteps}`);
+      if (captureResult.durationMs)
+        lines.push(`duration: ${captureResult.durationMs}ms`);
+      if (captureResult.finalState) {
+        lines.push(`
+Final page: ${captureResult.finalState.title}`);
+        lines.push(`URL: ${captureResult.finalState.url}`);
       }
-      if (action === "clear") {
-        await localApiDelete("/session").catch(() => {});
-        return { content: [{ type: "text", text: "Session data cleared from database." }] };
+      if (captureResult.capturedApi && captureResult.capturedApi.length > 0) {
+        formatCapturedApi(lines, captureResult.capturedApi, params);
+      } else {
+        lines.push(`
+No API calls were captured. The page may not have made any XHR/fetch requests during the steps, or the steps may not have triggered the expected behavior.`);
       }
-      if (action === "restart") {
-        const parts = [];
-        try {
-          await localApiPost("/browser/restart");
-          parts.push("Local browser restarted.");
-        } catch {
-          try {
-            await localServer.restart();
-            parts.push("Local server respawned.");
-          } catch (e) {
-            parts.push(`Local restart failed: ${e instanceof Error ? e.message : String(e)}`);
-          }
+      if (captureResult.error) {
+        lines.push(`
+--- Failure ---`);
+        if (typeof captureResult.error === "string") {
+          lines.push(`Error: ${captureResult.error}`);
+        } else {
+          lines.push(`Failed at step ${captureResult.error.failedAtStep}: ${JSON.stringify(captureResult.error.failedStep)}`);
+          lines.push(`Error type: ${captureResult.error.errorType}`);
+          lines.push(`Message: ${captureResult.error.message}`);
+          if (captureResult.error.suggestion)
+            lines.push(`Suggestion: ${captureResult.error.suggestion}`);
+        }
+      }
+      const screenshotUrl = captureResult.error?.pageState?.screenshotUrl ?? captureResult.finalState?.screenshotUrl;
+      if (screenshotUrl) {
+        const filePath = await resolveScreenshotPath(screenshotUrl);
+        if (filePath) {
+          lines.push(`
+Screenshot saved: ${filePath}`);
+          lines.push("Use the Read tool on the path above to view the screenshot.");
         }
+      }
+      if (captureResult.capturedApi && captureResult.capturedApi.length > 0) {
+        const mainDomain = captureResult.capturedApi[0]?.domain || "api";
+        const outDir = params.outputDir || `./${mainDomain}`;
         try {
-          if (await isDockerRunning()) {
-            await apiPost("/browser/restart");
-            parts.push("Docker browser restarted.");
-          }
-        } catch {}
-        parts.push("Credentials and knowledge cache are untouched. Next execute launches a fresh browser.");
-        return { content: [{ type: "text", text: parts.join(" ") }] };
+          const fs5 = await import("fs");
+          const path7 = await import("path");
+          fs5.mkdirSync(outDir, { recursive: true });
+          const jsonPath = path7.join(outDir, "captured-api.json");
+          fs5.writeFileSync(jsonPath, JSON.stringify(captureResult.capturedApi, null, 2));
+          lines.push(`
+Full captured data saved to: ${jsonPath}`);
+          lines.push("Read this file for complete curl commands, request/response bodies, and auth data.");
+        } catch (writeErr) {
+          lines.push(`
+(Could not save captured JSON: ${writeErr instanceof Error ? writeErr.message : String(writeErr)})`);
+        }
       }
-      return err("Unknown action");
-    } catch (e) {
-      return err(`Error: ${getErrorMessage(e)}`);
+      let text = lines.join(`
+`);
+      if (text.length > 80000) {
+        text = text.slice(0, 80000) + `
+
+[... response truncated — read captured-api.json for full data]`;
+      }
+      const content = [{ type: "text", text }];
+      if (!captureResult.ok)
+        return { content, isError: true };
+      return { content };
+    } catch (e) {
+      return err(`Connection error: ${getErrorMessage(e)}. Try \`session restart\` and retry.`);
+    }
+  });
+}
+function formatCapturedApi(lines, capturedApi, params) {
+  for (const api of capturedApi) {
+    lines.push(`
+━━━ ${api.domain} (${api.baseUrl}) ━━━`);
+    const authParts = [];
+    if (api.auth?.authorization)
+      authParts.push(`Authorization: ${api.auth.authorization.slice(0, 30)}...`);
+    if (api.auth?.cookies && Object.keys(api.auth.cookies).length > 0)
+      authParts.push(`${Object.keys(api.auth.cookies).length} cookies`);
+    if (api.auth?.tokens && Object.keys(api.auth.tokens).length > 0) {
+      for (const [k, v] of Object.entries(api.auth.tokens)) {
+        authParts.push(`${k}: ${String(v).slice(0, 30)}...`);
+      }
+    }
+    if (authParts.length > 0) {
+      lines.push(`
+Auth:`);
+      for (const part of authParts)
+        lines.push(`  ${part}`);
+    }
+    const byProtocol = new Map;
+    for (const ep of api.endpoints) {
+      const p = ep.protocol || "rest";
+      if (!byProtocol.has(p))
+        byProtocol.set(p, []);
+      byProtocol.get(p).push(ep);
+    }
+    const protocolSummary = Array.from(byProtocol.entries()).map(([p, eps]) => `${p}=${eps.length}`).join(", ");
+    lines.push(`
+Endpoints (${api.endpoints.length}) [${protocolSummary}]:`);
+    for (const ep of api.endpoints) {
+      lines.push(`
+  [${ep.protocol}/${ep.verb}] ${ep.functionName}`);
+      lines.push(`    Action: ${ep.action}`);
+      lines.push(`    ${ep.method} ${ep.path}  →  ${ep.responseStatus}`);
+      if (ep.requestBody) {
+        const body = ep.requestBody;
+        const signalKeys = extractSignalKeys(body);
+        if (signalKeys)
+          lines.push(`    Params: ${signalKeys}`);
+      }
+    }
+  }
+  const mainDomain = capturedApi[0]?.domain || "api";
+  const dir = params.outputDir || `./${mainDomain}`;
+  const ext = params.typed ? ".ts" : ".js";
+  lines.push(`
+━━━ Save instructions ━━━`);
+  lines.push(`Save to: ${dir}`);
+  lines.push(`Format: ${ext} files`);
+  const protocolsSeen = new Set;
+  for (const api of capturedApi)
+    for (const ep of api.endpoints)
+      protocolsSeen.add(ep.protocol);
+  lines.push(`
+Layout (protocols present: ${Array.from(protocolsSeen).join(", ")}):`);
+  lines.push(`  auth${ext}`);
+  if (protocolsSeen.has("rest"))
+    lines.push(`  transport/rest${ext}            — shared fetch wrapper with auth headers`);
+  if (protocolsSeen.has("graphql"))
+    lines.push(`  transport/graphql${ext}         — post(operationName|docId, variables) → shared GraphQL client`);
+  if (protocolsSeen.has("json-rpc"))
+    lines.push(`  transport/jsonRpc${ext}         — shared JSON-RPC client`);
+  if (protocolsSeen.has("grpc-web"))
+    lines.push(`  transport/grpc${ext}            — shared gRPC-web client`);
+  if (protocolsSeen.has("form-rpc"))
+    lines.push(`  transport/formRpc${ext}         — shared urlencoded RPC client`);
+  if (protocolsSeen.has("soap"))
+    lines.push(`  transport/soap${ext}            — shared SOAP client`);
+  lines.push(`  <protocol>/<verb>/<functionName>${ext}  — one file per endpoint, uses shared transport`);
+  lines.push(`    e.g. graphql/queries/<fn>${ext}, graphql/mutations/<fn>${ext}, rest/read/<fn>${ext}, rest/create/<fn>${ext}`);
+  lines.push(`  index${ext}                         — re-export all endpoint functions`);
+  if (params.typed)
+    lines.push(`  types.ts                         — interfaces inferred from response bodies`);
+  lines.push(`  README.md                        — endpoints grouped by protocol + verb, auth expiry warning`);
+  lines.push(`
+Rules:`);
+  lines.push(`  - One function per (protocol, action). Use the functionName field verbatim for the file + export name.`);
+  lines.push(`  - verb=read|list → queries/ (GraphQL) or read/ (REST). verb=create|update|delete|action → mutations/ (GraphQL) or verb dir (REST).`);
+  lines.push(`  - Each endpoint file is minimal: import transport + auth, call transport with the action id, pass variables, return typed result.`);
+  lines.push(`  - GraphQL transport signature: post(opNameOrDocId: string, variables: object). Pick doc_id when present in captured body, else operationName.`);
+  lines.push(`  - Do NOT inline auth headers per endpoint — they live in auth${ext} and the transport reads them.`);
+  lines.push(`
+IMPORTANT: Auth data contains real tokens/cookies — they expire. Remind the user.`);
+}
+function extractSignalKeys(body) {
+  const NOISE = new Set([
+    "__csr",
+    "__hsdp",
+    "__hblp",
+    "__dyn",
+    "__a",
+    "__req",
+    "__hs",
+    "__comet_req",
+    "__ccg",
+    "__spin_r",
+    "__spin_b",
+    "__spin_t",
+    "__jssesw",
+    "lsd",
+    "fb_dtsg",
+    "fb_api_caller_class",
+    "fb_api_req_friendly_name",
+    "jazoest",
+    "server_timestamps",
+    "__s",
+    "__user",
+    "dpr",
+    "__rev"
+  ]);
+  const signalEntries = [];
+  for (const [k, v] of Object.entries(body)) {
+    if (NOISE.has(k))
+      continue;
+    if (typeof v === "string" && v.length > 80) {
+      signalEntries.push(`${k}=${v.slice(0, 40)}...`);
+    } else if (typeof v === "object" && v !== null) {
+      const keys = Object.keys(v).slice(0, 5).join(",");
+      signalEntries.push(`${k}={${keys}${Object.keys(v).length > 5 ? ",..." : ""}}`);
+    } else {
+      signalEntries.push(`${k}=${String(v).slice(0, 40)}`);
+    }
+  }
+  return signalEntries.length > 0 ? signalEntries.join(", ") : null;
+}
+
+// src/mcp/tools/session.ts
+function registerSessionTool(server) {
+  server.tool("session", `Manage the browser session and lifecycle.
+
+Actions:
+- **stop**: save cookies/localStorage to the store, then close the browser. Session data persists for the next run.
+- **clear**: wipe all stored session data (cookies/localStorage) from the database. Does NOT kill running browsers.
+- **restart**: kill all running browser instances (local + Docker) and reset state. The next \`execute\` call will launch a fresh browser automatically. Use this when the browser is frozen, crashed, or in a bad state. Credentials and knowledge cache are NOT affected.
+- **capture-start**: attach a persistent XHR/fetch listener to the running browser. Accumulates ALL requests indefinitely — not tied to any pipeline. Use before triggering the action you want to capture (e.g. upload, delete, async mutation).
+- **capture-stop**: stop the persistent listener and return all captured endpoints + save to disk. Call this when you're satisfied you've seen the requests you need.
+- **get-cookies**: extract ALL cookies from the browser context via CDP (including HttpOnly/Secure — below the JS sandbox). Pass urls to scope. Returns name, value, domain, path, httpOnly, secure, expiry.
+- **get-auth**: extract cookies + localStorage + sessionStorage in one shot. Everything needed to replay authenticated requests from Node.js.
+
+Sessions live in the single local SQLite database (~/.iframer/iframer.db), shared across every browser mode.`, {
+    action: import_zod5.z.enum(["stop", "clear", "restart", "capture-start", "capture-stop", "get-cookies", "get-auth"]).describe("stop | clear | restart | capture-start | capture-stop | get-cookies | get-auth"),
+    mode: import_zod5.z.enum(["headless", "binary-headful"]).optional().describe("Browser mode (default: binary-headful)"),
+    urls: import_zod5.z.array(import_zod5.z.string()).optional().describe("URLs to scope cookie extraction (get-cookies/get-auth). Omit for all cookies."),
+    instanceId: import_zod5.z.string().optional().describe("Target a named parallel browser within this session (default: 'default'). Match the instanceId used in execute."),
+    outputDir: import_zod5.z.string().optional().describe("Where to save captured-api.json for capture-stop")
+  }, async ({ action, mode, urls, instanceId, outputDir }) => {
+    try {
+      if (action === "stop") {
+        const result = await localApiPost("/interactive/stop").catch(() => ({ ok: true, sessionSaved: false }));
+        return { content: [{ type: "text", text: `Session stopped. State saved: ${result.sessionSaved ?? false}` }] };
+      }
+      if (action === "clear") {
+        await localApiDelete("/session").catch(() => {});
+        return { content: [{ type: "text", text: "Session data cleared from database." }] };
+      }
+      if (action === "restart") {
+        const parts = [];
+        try {
+          await localApiPost("/browser/restart");
+          parts.push("Local browser restarted.");
+        } catch {
+          try {
+            await localServer.restart();
+            parts.push("Local server respawned.");
+          } catch (e) {
+            parts.push(`Local restart failed: ${e instanceof Error ? e.message : String(e)}`);
+          }
+        }
+        try {
+          if (await isDockerRunning()) {
+            await apiPost("/browser/restart");
+            parts.push("Docker browser restarted.");
+          }
+        } catch {}
+        parts.push("Credentials and knowledge cache are untouched. Next execute launches a fresh browser.");
+        return { content: [{ type: "text", text: parts.join(" ") }] };
+      }
+      if (action === "capture-start") {
+        const result = await localApiPost("/capture/start", { mode: mode ?? "binary-headful", instanceId });
+        return { content: [{ type: "text", text: result.message }] };
+      }
+      if (action === "capture-stop") {
+        const result = await localApiPost("/capture/stop", { mode: mode ?? "binary-headful", instanceId });
+        const lines = [result.message];
+        if (result.capturedApi && result.capturedApi.length > 0) {
+          formatCapturedApi(lines, result.capturedApi, { outputDir, typed: false });
+          const outDir = outputDir || import_path7.default.join(getDataDir(), "capture");
+          try {
+            import_fs5.default.mkdirSync(outDir, { recursive: true });
+            const jsonPath = import_path7.default.join(outDir, "captured-api.json");
+            import_fs5.default.writeFileSync(jsonPath, JSON.stringify(result.capturedApi, null, 2));
+            lines.push(`
+Full data saved to: ${jsonPath}`);
+          } catch (writeErr) {
+            lines.push(`
+(Could not save: ${writeErr instanceof Error ? writeErr.message : String(writeErr)})`);
+          }
+        }
+        let text = lines.join(`
+`);
+        if (text.length > 80000)
+          text = text.slice(0, 80000) + `
+
+[truncated — read captured-api.json]`;
+        return { content: [{ type: "text", text }] };
+      }
+      if (action === "get-cookies") {
+        const result = await localApiPost("/auth/cookies", { mode: mode ?? "binary-headful", urls, instanceId });
+        const lines = [result.message, ""];
+        for (const c of result.cookies) {
+          lines.push(`${c.name}=${c.value}  [domain=${c.domain} path=${c.path} httpOnly=${c.httpOnly} secure=${c.secure}]`);
+        }
+        return { content: [{ type: "text", text: lines.join(`
+`) }] };
+      }
+      if (action === "get-auth") {
+        const result = await localApiPost("/auth/full", { mode: mode ?? "binary-headful", urls, instanceId });
+        const lines = [result.message, ""];
+        lines.push("=== Cookies ===");
+        for (const c of result.cookies) {
+          lines.push(`${c.name}=${c.value}  [domain=${c.domain} httpOnly=${c.httpOnly}]`);
+        }
+        if (Object.keys(result.localStorage || {}).length > 0) {
+          lines.push(`
+=== localStorage ===`);
+          for (const [origin, store] of Object.entries(result.localStorage)) {
+            lines.push(`[${origin}]`);
+            for (const [k, v] of Object.entries(store)) {
+              const val = String(v);
+              lines.push(`  ${k}: ${val.length > 120 ? val.slice(0, 120) + "…" : val}`);
+            }
+          }
+        }
+        if (Object.keys(result.sessionStorage || {}).length > 0) {
+          lines.push(`
+=== sessionStorage ===`);
+          for (const [origin, store] of Object.entries(result.sessionStorage)) {
+            lines.push(`[${origin}]`);
+            for (const [k, v] of Object.entries(store)) {
+              const val = String(v);
+              lines.push(`  ${k}: ${val.length > 120 ? val.slice(0, 120) + "…" : val}`);
+            }
+          }
+        }
+        let text = lines.join(`
+`);
+        if (text.length > 80000)
+          text = text.slice(0, 80000) + `
+[truncated]`;
+        return { content: [{ type: "text", text }] };
+      }
+      return err("Unknown action");
+    } catch (e) {
+      return err(`Error: ${getErrorMessage(e)}`);
     }
   });
 }
 
 // src/mcp/tools/credentials.ts
-var import_zod5 = require("zod");
-var import_fs5 = __toESM(require("fs"));
-var import_path7 = __toESM(require("path"));
+var import_zod6 = require("zod");
+var import_fs7 = __toESM(require("fs"));
+var import_path9 = __toESM(require("path"));
 
 // src/lib/knowledge.ts
-var import_fs4 = __toESM(require("fs"));
-var import_path6 = __toESM(require("path"));
-var log3 = createLogger("knowledge");
+var import_fs6 = __toESM(require("fs"));
+var import_path8 = __toESM(require("path"));
+var log4 = createLogger("knowledge");
 function getKnowledgeDir() {
-  return import_path6.default.join(getDataDir(), "knowledge");
+  return import_path8.default.join(getDataDir(), "knowledge");
 }
 function getKnowledgePath(domain) {
   const safe = sanitizeDomain(domain);
-  return import_path6.default.join(getKnowledgeDir(), `${safe}.md`);
+  return import_path8.default.join(getKnowledgeDir(), `${safe}.md`);
 }
 function normalizeDomain(input) {
   let d = (input || "").trim().toLowerCase();
@@ -847,7 +1302,7 @@ function sanitizeDomain(input) {
 function readKnowledge(domain) {
   const p = getKnowledgePath(domain);
   try {
-    return import_fs4.default.readFileSync(p, "utf8");
+    return import_fs6.default.readFileSync(p, "utf8");
   } catch {
     return null;
   }
@@ -856,7 +1311,7 @@ function listKnowledge() {
   const dir = getKnowledgeDir();
   let entries = [];
   try {
-    entries = import_fs4.default.readdirSync(dir);
+    entries = import_fs6.default.readdirSync(dir);
   } catch {
     return [];
   }
@@ -864,10 +1319,10 @@ function listKnowledge() {
   for (const file of entries) {
     if (!file.endsWith(".md"))
       continue;
-    const full = import_path6.default.join(dir, file);
+    const full = import_path8.default.join(dir, file);
     try {
-      const stat = import_fs4.default.statSync(full);
-      const raw = import_fs4.default.readFileSync(full, "utf8");
+      const stat = import_fs6.default.statSync(full);
+      const raw = import_fs6.default.readFileSync(full, "utf8");
       const parsed = parseMarkdown(raw);
       results.push({
         domain: parsed?.domain ?? file.replace(/\.md$/, ""),
@@ -885,7 +1340,7 @@ function clearKnowledge(domain) {
   if (domain) {
     const p = getKnowledgePath(domain);
     try {
-      import_fs4.default.unlinkSync(p);
+      import_fs6.default.unlinkSync(p);
       return { removed: 1 };
     } catch {
       return { removed: 0 };
@@ -893,11 +1348,11 @@ function clearKnowledge(domain) {
   }
   let removed = 0;
   try {
-    const entries = import_fs4.default.readdirSync(dir);
+    const entries = import_fs6.default.readdirSync(dir);
     for (const f of entries) {
       if (f.endsWith(".md")) {
         try {
-          import_fs4.default.unlinkSync(import_path6.default.join(dir, f));
+          import_fs6.default.unlinkSync(import_path8.default.join(dir, f));
           removed++;
         } catch {}
       }
@@ -977,8 +1432,8 @@ var ELICIT_TIMEOUT_MS = 45000;
 function mcpLog(event, data) {
   try {
     const dir = getDataDir();
-    import_fs5.default.mkdirSync(dir, { recursive: true });
-    import_fs5.default.appendFileSync(import_path7.default.join(dir, "mcp.log"), JSON.stringify({ ts: new Date().toISOString(), event, ...data }) + `
+    import_fs7.default.mkdirSync(dir, { recursive: true });
+    import_fs7.default.appendFileSync(import_path9.default.join(dir, "mcp.log"), JSON.stringify({ ts: new Date().toISOString(), event, ...data }) + `
 `);
   } catch {}
 }
@@ -1009,9 +1464,9 @@ CRITICAL RULES
 5. **NEVER ask the user to paste their password in chat.**
 
 6. **\`force: true\` on store is ONLY for explicit password changes.**`, {
-    action: import_zod5.z.enum(["store", "list"]).describe("store: prompt for credentials | list: show stored domains"),
-    domain: import_zod5.z.string().optional().describe("Domain (required for store). Use the bare registrable domain."),
-    force: import_zod5.z.boolean().optional().describe("Overwrite existing. ONLY for explicit password changes.")
+    action: import_zod6.z.enum(["store", "list"]).describe("store: prompt for credentials | list: show stored domains"),
+    domain: import_zod6.z.string().optional().describe("Domain (required for store). Use the bare registrable domain."),
+    force: import_zod6.z.boolean().optional().describe("Overwrite existing. ONLY for explicit password changes.")
   }, async ({ action, domain, force }) => {
     try {
       if (action === "list") {
@@ -1096,262 +1551,6 @@ ${domains.map((d) => `  - ${d}`).join(`
   });
 }
 
-// src/mcp/tools/reverse-engineer.ts
-var import_zod6 = require("zod");
-function registerReverseEngineerTool(server) {
-  server.tool("reverse-engineer", `Reverse-engineer a website's API. Navigates to a URL, performs the steps you specify, and captures every XHR/fetch request the page makes — including auth tokens, cookies, headers, request/response bodies, and ready-to-use curl commands.
-
-Use this when the user asks to:
-- "reverse engineer" or "map" a site's API
-- "capture the endpoints" or "save the API"
-- "figure out how this site works under the hood"
-- "record the API calls" so they can be replayed later
-
-How it works:
-1. You provide steps (same as execute) — navigate, click, fill, extract, etc.
-2. iframer runs them while recording all API calls the page makes
-3. Returns structured data per domain: shared auth + endpoints classified by protocol (rest, graphql, json-rpc, grpc-web, form-rpc, soap) with method, path, action, verb, headers, body, response, curl
-
-IMPORTANT — one request ≠ one endpoint. Each endpoint has (protocol, action):
-- REST: action = "METHOD /parameterized/path". Verb from HTTP method.
-- GraphQL: action = operationName (or doc_id for persisted queries). Many ops share the single /graphql URL — EACH operation is its own endpoint.
-- JSON-RPC: action = body.method (e.g. eth_getBalance, user.list).
-- gRPC-web: action = request path.
-- Form-RPC (FB-style urlencoded): action = fb_api_req_friendly_name / doc_id.
-- SOAP: action = SOAPAction header.
-
-Generate ONE function per (protocol, action). Do NOT merge different GraphQL operations into one function just because they share the URL.
-
-Output layout — save as RUNNABLE CODE to <outputDir>/:
-  auth.{js,ts}                  — shared cookies, tokens, authorization
-  transport/
-    rest.{js,ts}                — shared REST helper (only if any rest endpoints)
-    graphql.{js,ts}             — shared GraphQL client: post(operationName|docId, variables)
-    jsonRpc.{js,ts}             — shared JSON-RPC client (if any)
-    grpc.{js,ts}                — shared gRPC-web client (if any)
-  <protocol>/<verb>/<functionName>.{js,ts}
-    e.g. graphql/queries/getTimelineFeed.ts
-         graphql/mutations/reactToPost.ts
-         rest/read/getChannelMessages.ts
-         rest/create/createMessage.ts
-         jsonRpc/ethGetBalance.ts
-  index.{js,ts}                 — re-exports all endpoint functions
-  types.ts                      — (typed mode only) inferred interfaces from responses
-  README.md                     — endpoints grouped by protocol + verb, dependency chain, auth expiry warning
-
-Use capturedApi[i].endpoints[j].protocol, .action, .verb, .functionName directly — iframer already classified them. Put queries (verb=read|list) under queries/, mutations (verb=create|update|delete|action) under mutations/ for GraphQL. For REST, group by verb dir.
-
-The outputDir defaults to ./<domain>/. Ask the user where to save if unclear.`, {
-    steps: import_zod6.z.array(stepSchema).describe("Pipeline steps to execute while capturing API calls"),
-    outputDir: import_zod6.z.string().optional().describe("Directory to save the captured API files. If not provided, ask the user or default to ./<domain>/"),
-    typed: import_zod6.z.boolean().optional().describe("Save as .ts with inferred types instead of .js. Set to true when the user asks for types, typescript, or type inference."),
-    options: import_zod6.z.object({
-      staleTimeoutMs: import_zod6.z.number().optional().describe("Override the 20s stale-state timeout per step"),
-      continueOnObstacle: import_zod6.z.boolean().optional().describe("Try to auto-resolve obstacles (default: true)"),
-      continueOnError: import_zod6.z.boolean().optional().describe("Continue past failing steps (default: false)"),
-      mode: import_zod6.z.enum(["headless", "binary-headful", "docker-headful"]).optional().describe("Browser mode override")
-    }).optional()
-  }, async (params) => {
-    try {
-      const execParams = {
-        steps: params.steps,
-        options: { ...params.options, captureApi: true }
-      };
-      const mode = params.options?.mode;
-      const dockerRunning = await isDockerRunning();
-      const captureResult = mode === "docker-headful" && dockerRunning ? await apiPost("/execute", execParams) : await localApiPost("/execute", execParams);
-      const lines = [];
-      lines.push(`ok: ${captureResult.ok}`);
-      lines.push(`steps: ${captureResult.completedSteps}/${captureResult.totalSteps}`);
-      if (captureResult.durationMs)
-        lines.push(`duration: ${captureResult.durationMs}ms`);
-      if (captureResult.finalState) {
-        lines.push(`
-Final page: ${captureResult.finalState.title}`);
-        lines.push(`URL: ${captureResult.finalState.url}`);
-      }
-      if (captureResult.capturedApi && captureResult.capturedApi.length > 0) {
-        formatCapturedApi(lines, captureResult.capturedApi, params);
-      } else {
-        lines.push(`
-No API calls were captured. The page may not have made any XHR/fetch requests during the steps, or the steps may not have triggered the expected behavior.`);
-      }
-      if (captureResult.error) {
-        lines.push(`
---- Failure ---`);
-        if (typeof captureResult.error === "string") {
-          lines.push(`Error: ${captureResult.error}`);
-        } else {
-          lines.push(`Failed at step ${captureResult.error.failedAtStep}: ${JSON.stringify(captureResult.error.failedStep)}`);
-          lines.push(`Error type: ${captureResult.error.errorType}`);
-          lines.push(`Message: ${captureResult.error.message}`);
-          if (captureResult.error.suggestion)
-            lines.push(`Suggestion: ${captureResult.error.suggestion}`);
-        }
-      }
-      const screenshotUrl = captureResult.error?.pageState?.screenshotUrl ?? captureResult.finalState?.screenshotUrl;
-      if (screenshotUrl) {
-        const filePath = await resolveScreenshotPath(screenshotUrl);
-        if (filePath) {
-          lines.push(`
-Screenshot saved: ${filePath}`);
-          lines.push("Use the Read tool on the path above to view the screenshot.");
-        }
-      }
-      if (captureResult.capturedApi && captureResult.capturedApi.length > 0) {
-        const mainDomain = captureResult.capturedApi[0]?.domain || "api";
-        const outDir = params.outputDir || `./${mainDomain}`;
-        try {
-          const fs6 = await import("fs");
-          const path8 = await import("path");
-          fs6.mkdirSync(outDir, { recursive: true });
-          const jsonPath = path8.join(outDir, "captured-api.json");
-          fs6.writeFileSync(jsonPath, JSON.stringify(captureResult.capturedApi, null, 2));
-          lines.push(`
-Full captured data saved to: ${jsonPath}`);
-          lines.push("Read this file for complete curl commands, request/response bodies, and auth data.");
-        } catch (writeErr) {
-          lines.push(`
-(Could not save captured JSON: ${writeErr instanceof Error ? writeErr.message : String(writeErr)})`);
-        }
-      }
-      const content = [{ type: "text", text: lines.join(`
-`) }];
-      if (!captureResult.ok)
-        return { content, isError: true };
-      return { content };
-    } catch (e) {
-      return err(`Connection error: ${getErrorMessage(e)}. Try \`session restart\` and retry.`);
-    }
-  });
-}
-function formatCapturedApi(lines, capturedApi, params) {
-  for (const api of capturedApi) {
-    lines.push(`
-━━━ ${api.domain} (${api.baseUrl}) ━━━`);
-    const authParts = [];
-    if (api.auth?.authorization)
-      authParts.push(`Authorization: ${api.auth.authorization.slice(0, 30)}...`);
-    if (api.auth?.cookies && Object.keys(api.auth.cookies).length > 0)
-      authParts.push(`${Object.keys(api.auth.cookies).length} cookies`);
-    if (api.auth?.tokens && Object.keys(api.auth.tokens).length > 0) {
-      for (const [k, v] of Object.entries(api.auth.tokens)) {
-        authParts.push(`${k}: ${String(v).slice(0, 30)}...`);
-      }
-    }
-    if (authParts.length > 0) {
-      lines.push(`
-Auth:`);
-      for (const part of authParts)
-        lines.push(`  ${part}`);
-    }
-    const byProtocol = new Map;
-    for (const ep of api.endpoints) {
-      const p = ep.protocol || "rest";
-      if (!byProtocol.has(p))
-        byProtocol.set(p, []);
-      byProtocol.get(p).push(ep);
-    }
-    const protocolSummary = Array.from(byProtocol.entries()).map(([p, eps]) => `${p}=${eps.length}`).join(", ");
-    lines.push(`
-Endpoints (${api.endpoints.length}) [${protocolSummary}]:`);
-    for (const ep of api.endpoints) {
-      lines.push(`
-  [${ep.protocol}/${ep.verb}] ${ep.functionName}`);
-      lines.push(`    Action: ${ep.action}`);
-      lines.push(`    ${ep.method} ${ep.path}  →  ${ep.responseStatus}`);
-      if (ep.requestBody) {
-        const body = ep.requestBody;
-        const signalKeys = extractSignalKeys(body);
-        if (signalKeys)
-          lines.push(`    Params: ${signalKeys}`);
-      }
-    }
-  }
-  const mainDomain = capturedApi[0]?.domain || "api";
-  const dir = params.outputDir || `./${mainDomain}`;
-  const ext = params.typed ? ".ts" : ".js";
-  lines.push(`
-━━━ Save instructions ━━━`);
-  lines.push(`Save to: ${dir}`);
-  lines.push(`Format: ${ext} files`);
-  const protocolsSeen = new Set;
-  for (const api of capturedApi)
-    for (const ep of api.endpoints)
-      protocolsSeen.add(ep.protocol);
-  lines.push(`
-Layout (protocols present: ${Array.from(protocolsSeen).join(", ")}):`);
-  lines.push(`  auth${ext}`);
-  if (protocolsSeen.has("rest"))
-    lines.push(`  transport/rest${ext}            — shared fetch wrapper with auth headers`);
-  if (protocolsSeen.has("graphql"))
-    lines.push(`  transport/graphql${ext}         — post(operationName|docId, variables) → shared GraphQL client`);
-  if (protocolsSeen.has("json-rpc"))
-    lines.push(`  transport/jsonRpc${ext}         — shared JSON-RPC client`);
-  if (protocolsSeen.has("grpc-web"))
-    lines.push(`  transport/grpc${ext}            — shared gRPC-web client`);
-  if (protocolsSeen.has("form-rpc"))
-    lines.push(`  transport/formRpc${ext}         — shared urlencoded RPC client`);
-  if (protocolsSeen.has("soap"))
-    lines.push(`  transport/soap${ext}            — shared SOAP client`);
-  lines.push(`  <protocol>/<verb>/<functionName>${ext}  — one file per endpoint, uses shared transport`);
-  lines.push(`    e.g. graphql/queries/<fn>${ext}, graphql/mutations/<fn>${ext}, rest/read/<fn>${ext}, rest/create/<fn>${ext}`);
-  lines.push(`  index${ext}                         — re-export all endpoint functions`);
-  if (params.typed)
-    lines.push(`  types.ts                         — interfaces inferred from response bodies`);
-  lines.push(`  README.md                        — endpoints grouped by protocol + verb, auth expiry warning`);
-  lines.push(`
-Rules:`);
-  lines.push(`  - One function per (protocol, action). Use the functionName field verbatim for the file + export name.`);
-  lines.push(`  - verb=read|list → queries/ (GraphQL) or read/ (REST). verb=create|update|delete|action → mutations/ (GraphQL) or verb dir (REST).`);
-  lines.push(`  - Each endpoint file is minimal: import transport + auth, call transport with the action id, pass variables, return typed result.`);
-  lines.push(`  - GraphQL transport signature: post(opNameOrDocId: string, variables: object). Pick doc_id when present in captured body, else operationName.`);
-  lines.push(`  - Do NOT inline auth headers per endpoint — they live in auth${ext} and the transport reads them.`);
-  lines.push(`
-IMPORTANT: Auth data contains real tokens/cookies — they expire. Remind the user.`);
-}
-function extractSignalKeys(body) {
-  const NOISE = new Set([
-    "__csr",
-    "__hsdp",
-    "__hblp",
-    "__dyn",
-    "__a",
-    "__req",
-    "__hs",
-    "__comet_req",
-    "__ccg",
-    "__spin_r",
-    "__spin_b",
-    "__spin_t",
-    "__jssesw",
-    "lsd",
-    "fb_dtsg",
-    "fb_api_caller_class",
-    "fb_api_req_friendly_name",
-    "jazoest",
-    "server_timestamps",
-    "__s",
-    "__user",
-    "dpr",
-    "__rev"
-  ]);
-  const signalEntries = [];
-  for (const [k, v] of Object.entries(body)) {
-    if (NOISE.has(k))
-      continue;
-    if (typeof v === "string" && v.length > 80) {
-      signalEntries.push(`${k}=${v.slice(0, 40)}...`);
-    } else if (typeof v === "object" && v !== null) {
-      const keys = Object.keys(v).slice(0, 5).join(",");
-      signalEntries.push(`${k}={${keys}${Object.keys(v).length > 5 ? ",..." : ""}}`);
-    } else {
-      signalEntries.push(`${k}=${String(v).slice(0, 40)}`);
-    }
-  }
-  return signalEntries.length > 0 ? signalEntries.join(", ") : null;
-}
-
 // src/mcp/tools/knowledge.ts
 var import_zod7 = require("zod");
 function registerKnowledgeTool(server) {
@@ -1456,6 +1655,7 @@ CRITICAL RULES:
 5. ALWAYS check "knowledge get <domain>" before launching a browser. Skip the browser if the cache has what you need.
 6. If execute fails, read the FULL error. It tells you the step, error type, and suggestion.
 7. If the browser crashes, call "session restart" and retry. Don't panic.
+8. ALWAYS call "session" action=stop when you are done with browser work. It saves session state and frees the browser. Idle browsers are auto-reclaimed, but don't rely on that.
 
 BROWSER MODES: Don't specify options.mode — iframer auto-selects and auto-escalates (headless → binary-headful). Only set a mode if the user explicitly asks.
 
@@ -1470,18 +1670,8 @@ registerSessionTool(server);
 registerCredentialsTool(server);
 registerReverseEngineerTool(server);
 registerKnowledgeTool(server);
-function cleanup() {
-  localServer.shutdown();
-}
-process.on("exit", cleanup);
-process.on("SIGTERM", () => {
-  cleanup();
-  process.exit(0);
-});
-process.on("SIGINT", () => {
-  cleanup();
-  process.exit(0);
-});
+process.on("SIGTERM", () => process.exit(0));
+process.on("SIGINT", () => process.exit(0));
 process.on("uncaughtException", (err2) => {
   try {
     console.error(`[mcp] uncaughtException: ${err2?.message}`);