iframer-toolkit 0.8.0 → 0.10.1

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,42 +80,76 @@ 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 BASE_PORT = parseInt(process.env.IFRAMER_LOCAL_PORT || "3022", 10);
-var PORT_SCAN_ATTEMPTS = 200;
+var PORT_SCAN_ATTEMPTS = 21;
 var STARTUP_TIMEOUT_MS = 15000;
 var HEALTH_POLL_MS = 300;
+var SPAWN_LOCK_STALE_MS = 20000;
 
 class LocalServerManager {
-  child = null;
   startingPromise = null;
-  port = null;
   baseUrl = "";
   logPath;
   constructor() {
-    this.logPath = import_path3.default.join(getDataDir(), "local-server.log");
+    this.logPath = import_path4.default.join(getDataDir(), "local-server.log");
   }
   getBaseUrl() {
     if (!this.baseUrl) {
@@ -123,113 +158,154 @@ class LocalServerManager {
     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() {
-    this.port = await findFreePort(BASE_PORT, PORT_SCAN_ATTEMPTS);
-    this.baseUrl = `http://127.0.0.1:${this.port}`;
+  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(this.port),
-      IFRAMER_MODE: "local",
-      IFRAMER_DATA_DIR: dataDir,
-      IFRAMER_PARENT_PID: String(process.pid)
-    };
-    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 ${this.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() {
+    const serverTs = import_path4.default.join(__dirname, "..", "..", "index.ts");
+    const serverCjs = import_path4.default.join(__dirname, "..", "..", "dist", "local-server.cjs");
+    if (import_fs3.default.existsSync(serverCjs)) {
+      return { command: "node", args: [serverCjs] };
+    }
+    if (import_fs3.default.existsSync(serverTs)) {
+      try {
+        require.resolve("/Users/eduardoverona/tools/iframer-toolkit/node_modules/tsx/dist/loader.mjs");
+        return { command: "node", args: ["--import", "tsx", serverTs] };
+      } catch {}
+    }
     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)) {
-        return { command: bunPath, args: ["run", serverTs2] };
+      if (bunPath && import_fs3.default.existsSync(serverTs)) {
+        console.error("[iframer] running local server under bun — extension mode (connectOverCDP) will not work; run `bun run build` to get the node bundle");
+        return { command: bunPath, args: ["run", serverTs] };
       }
     } catch {}
-    const serverCjs = import_path3.default.join(__dirname, "..", "..", "dist", "local-server.cjs");
-    if (import_fs2.default.existsSync(serverCjs)) {
-      return { command: "node", args: [serverCjs] };
-    }
-    const serverTs = import_path3.default.join(__dirname, "..", "..", "index.ts");
-    return { command: "node", args: ["--import", "tsx", serverTs] };
+    throw new Error("No runnable iframer server entry found: dist/local-server.cjs is missing, tsx is not " + "installed, and bun is unavailable. Run `bun install && bun run build` in the iframer repo.");
   }
   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(() => {
+      const deadline = Date.now() + 12000;
+      while (Date.now() < deadline && isPidAlive(info.pid)) {
+        await sleep(200);
+      }
+      if (isPidAlive(info.pid)) {
         try {
-          if (!c.killed)
-            c.kill("SIGKILL");
+          process.kill(info.pid, "SIGKILL");
         } catch {}
-      }, 2000);
-    }
-    this.child = null;
-  }
-  async healthCheck() {
-    if (!this.baseUrl)
-      return false;
-    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(`
@@ -242,6 +318,15 @@ ${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) => {
@@ -263,8 +348,13 @@ function findFreePort(start, attempts) {
   });
 }
 
+// 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;
@@ -290,7 +380,7 @@ async function apiPost(endpoint, body) {
   return res.json();
 }
 async function apiGet(endpoint) {
-  const res = await fetch(`${BASE_URL}${endpoint}`, { headers: authHeaders() });
+  const res = await fetch(`${BASE_URL}${endpoint}`, { headers: authHeaders(), signal: AbortSignal.timeout(30000) });
   return res.json();
 }
 async function localApiPost(endpoint, body) {
@@ -307,13 +397,13 @@ async function localApiPost(endpoint, body) {
 async function localApiGet(endpoint) {
   await ensureLocalServer();
   const url = localServer.getBaseUrl();
-  const res = await fetch(`${url}${endpoint}`, { headers: authHeaders(LOCAL_TOKEN) });
+  const res = await fetch(`${url}${endpoint}`, { headers: authHeaders(LOCAL_TOKEN), signal: AbortSignal.timeout(30000) });
   return res.json();
 }
 async function localApiDelete(endpoint) {
   await ensureLocalServer();
   const url = localServer.getBaseUrl();
-  const res = await fetch(`${url}${endpoint}`, { method: "DELETE", headers: authHeaders(LOCAL_TOKEN) });
+  const res = await fetch(`${url}${endpoint}`, { method: "DELETE", headers: authHeaders(LOCAL_TOKEN), signal: AbortSignal.timeout(30000) });
   return res.json();
 }
 async function isDockerRunning() {
@@ -330,8 +420,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;
     }
@@ -339,11 +429,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;
@@ -352,16 +442,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"];
@@ -442,8 +529,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 = {};
@@ -451,10 +538,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);
     }
   }
 }
@@ -542,7 +629,7 @@ var import_zod2 = require("zod");
 var stepSchema = import_zod2.z.discriminatedUnion("type", [
   import_zod2.z.object({ type: import_zod2.z.literal("navigate"), url: import_zod2.z.string(), waitUntil: import_zod2.z.string().optional() }),
   import_zod2.z.object({ type: import_zod2.z.literal("click"), selector: import_zod2.z.string() }),
-  import_zod2.z.object({ type: import_zod2.z.literal("fill"), selector: import_zod2.z.string(), value: import_zod2.z.string() }),
+  import_zod2.z.object({ type: import_zod2.z.literal("fill"), selector: import_zod2.z.string(), value: import_zod2.z.string().describe("Sets an input/textarea's value. Framework-aware: fires the React-safe native setter + input/change/blur, so controlled forms (React, react-hook-form, Formik, Vue) register the value AND mark the field touched. This is the fix for 'I filled the field but submit says it's still empty' — always use fill for form fields, not evaluate.") }),
   import_zod2.z.object({ type: import_zod2.z.literal("human-click"), selector: import_zod2.z.string().optional(), x: import_zod2.z.number().optional(), y: import_zod2.z.number().optional() }),
   import_zod2.z.object({ type: import_zod2.z.literal("right-click"), selector: import_zod2.z.string().optional(), x: import_zod2.z.number().optional(), y: import_zod2.z.number().optional() }),
   import_zod2.z.object({ type: import_zod2.z.literal("human-type"), selector: import_zod2.z.string(), value: import_zod2.z.string() }),
@@ -550,8 +637,12 @@ var stepSchema = import_zod2.z.discriminatedUnion("type", [
   import_zod2.z.object({ type: import_zod2.z.literal("extract"), expression: import_zod2.z.string() }),
   import_zod2.z.object({ type: import_zod2.z.literal("wait"), ms: import_zod2.z.number() }),
   import_zod2.z.object({ type: import_zod2.z.literal("wait-for"), selector: import_zod2.z.string(), timeout: import_zod2.z.number().optional() }),
-  import_zod2.z.object({ type: import_zod2.z.literal("scroll"), deltaY: import_zod2.z.number().optional() }),
-  import_zod2.z.object({ type: import_zod2.z.literal("keyboard"), key: import_zod2.z.string() }),
+  import_zod2.z.object({ type: import_zod2.z.literal("scroll"), deltaY: import_zod2.z.number().optional(), selector: import_zod2.z.string().optional().describe("Scroll within this element instead of the window") }),
+  import_zod2.z.object({ type: import_zod2.z.literal("keyboard"), key: import_zod2.z.string(), meta: import_zod2.z.boolean().optional(), ctrl: import_zod2.z.boolean().optional(), shift: import_zod2.z.boolean().optional(), alt: import_zod2.z.boolean().optional() }),
+  import_zod2.z.object({ type: import_zod2.z.literal("read"), selector: import_zod2.z.string().optional().describe("Element to read visible text from (CSS or @e ref). Omit for the whole page body."), maxChars: import_zod2.z.number().optional().describe("Cap the returned text length (default 6000). Raise it only when you actually need more — larger reads cost proportionally more context.") }),
+  import_zod2.z.object({ type: import_zod2.z.literal("upload"), selector: import_zod2.z.string().describe("The <input type=file> to set (CSS, @e ref, or @a anchor)."), files: import_zod2.z.array(import_zod2.z.string()).describe("Absolute local file path(s) to upload. Paths must exist on this machine (same machine as the browser).") }),
+  import_zod2.z.object({ type: import_zod2.z.literal("paste"), selector: import_zod2.z.string().optional().describe("Field to paste the OS clipboard into (CSS, @e ref, or @a anchor). Omit to insert at the currently focused element. Reliable — inserts via CDP Input.insertText, unlike a ⌘V keyboard step (the extension relay ignores modifier keys).") }),
+  import_zod2.z.object({ type: import_zod2.z.literal("download"), url: import_zod2.z.string().describe("URL of the file to download. Fetched through the browser's session (cookies included, so auth'd downloads work) and written to disk server-side — no Save-As dialog."), path: import_zod2.z.string().optional().describe("Absolute local path to save to. Omit to save into ~/.iframer/downloads/ with the URL's filename. Read the returned path to open the file.") }),
   import_zod2.z.object({ type: import_zod2.z.literal("type-code"), value: import_zod2.z.string(), selector: import_zod2.z.string().optional() }),
   import_zod2.z.object({ type: import_zod2.z.literal("login"), domain: import_zod2.z.string(), usernameSelector: import_zod2.z.string().optional(), passwordSelector: import_zod2.z.string().optional(), submitSelector: import_zod2.z.string().optional(), totpSelector: import_zod2.z.string().optional() }),
   import_zod2.z.object({ type: import_zod2.z.literal("solve-captcha") }),
@@ -567,6 +658,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.
 
@@ -585,6 +679,10 @@ Key step types:
 
 IMPORTANT — Element refs (@e1, @e2...): All selector fields accept @e refs from snapshot, find, or annotated screenshot. PREFER refs over CSS selectors.
 
+IMPORTANT — Saved anchors (@a:<name>): Selector fields also accept persisted, per-domain anchors from the \`remember\` tool. Call \`remember get <domain>\` before a UI task; if an anchor exists, target it directly (e.g. selector="@a:composer") — no snapshot needed. After finding a new element that works, \`remember save\` it. Unlike @e refs (which reset every snapshot), @a: anchors persist across runs.
+
+FILLING FORMS: Always use the \`fill\` step for text inputs/textareas — NOT \`evaluate\` to set .value. \`fill\` is framework-aware: it fires the React-safe native setter plus input/change/blur, so controlled forms (React, react-hook-form, Formik, Vue) actually register the value and mark the field "touched". This prevents the common "I filled every field but submit still says they're required/empty" failure — which is a form-framework state issue, not a real empty field. If a submit is still rejected as incomplete after filling, re-run \`fill\` on the flagged field (it re-triggers the blur/validation) rather than assuming the value didn't land.
+
 Returns: ok, completedSteps, results, obstacles, capturedApi, and on failure: errorContext with screenshot path, URL, errorType, suggestion, retryable.`, {
     steps: import_zod3.z.array(stepSchema).describe("Pipeline steps to execute sequentially"),
     options: import_zod3.z.object({
@@ -593,12 +691,33 @@ Returns: ok, completedSteps, results, obstacles, capturedApi, and on failure: er
       continueOnObstacle: import_zod3.z.boolean().optional().describe("Try to auto-resolve obstacles (default: true)"),
       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."),
+      mode: import_zod3.z.enum(["headless", "binary-headful", "docker-headful", "extension"]).optional().describe("DO NOT SET THIS unless user explicitly requests a mode. iframer auto-selects and auto-escalates. Use 'extension' ONLY to drive a tab in the user's real Chrome via the iframer extension — requires options.tabId (get it from the `tabs` tool)."),
       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.")
+      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."),
+      tabId: import_zod3.z.number().optional().describe("Only with mode='extension': the id of the real Chrome tab to drive (from the `tabs` tool). Input is trusted OS-level (chrome.debugger); Chrome shows its 'is being debugged' bar while the run is in progress."),
+      clientId: import_zod3.z.string().optional().describe("Only with mode='extension', and only needed when several profiles/browsers are connected and a tab is ambiguous: the clientId of the profile that owns the tab (from the `tabs` tool)."),
+      focus: import_zod3.z.boolean().optional().describe("Only with mode='extension': bring the tab's window to the OS foreground while driving. Default false — the tab is driven in the background (activated in its window, focus-emulated) without interrupting the user. Set true only if a site ignores background input.")
     }).optional()
   }, async (params) => {
     try {
+      if (params.options?.mode === "extension") {
+        const tabId = params.options?.tabId;
+        if (typeof tabId !== "number") {
+          return err("mode='extension' requires options.tabId. Call the `tabs` tool first to " + "find the id of the tab the user wants to drive.");
+        }
+        const extResult = await localApiPost("/extension/execute", {
+          tabId,
+          clientId: params.options?.clientId,
+          steps: params.steps,
+          options: params.options
+        });
+        const extLines = formatExecuteResult(extResult);
+        const content2 = [{ type: "text", text: extLines.join(`
+`) }];
+        if (!extResult.ok)
+          return { content: content2, isError: true };
+        return { content: content2 };
+      }
       const dockerRunning = await isDockerRunning();
       async function runWithMode(mode) {
         if (mode === "docker-headful") {
@@ -638,9 +757,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 {}
@@ -663,7 +782,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;
@@ -716,22 +835,44 @@ Final page: ${data.finalState.title}`);
 Knowledge cache updated for ${domain}. Before the next browser run on this domain, call \`knowledge get ${domain}\` — you may be able to skip the browser entirely.`);
     } catch {}
   }
+  for (const r of data.results || []) {
+    if (r.tabSwitchedTo) {
+      lines.push(`
+↳ step ${r.stepIndex} opened a new tab — pipeline is now on: ${r.tabSwitchedTo}`);
+    }
+  }
   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);
-    } else if (r.result !== undefined && r.result !== null) {
+        lines.push(res.refs);
+      }
+    } else if (r.step.type === "read") {
+      const res = r.result;
+      if (res?.text !== undefined) {
+        lines.push(`
+--- Read (step ${r.stepIndex}${res.truncated ? ", truncated" : ""}) ---`);
+        lines.push(res.text);
+      }
+    } else if (r.step.type === "extract" || r.step.type === "evaluate") {
       lines.push(`
-step ${r.stepIndex}: ${JSON.stringify(r.result)}`);
+step ${r.stepIndex} (${r.step.type}): ${JSON.stringify(r.result)}`);
     }
   }
   if (data.obstacles && data.obstacles.length > 0) {
@@ -774,8 +915,8 @@ ${api.domain} (${api.baseUrl})`);
 
 // src/mcp/tools/session.ts
 var import_zod5 = require("zod");
-var import_path6 = __toESM(require("path"));
-var import_fs4 = __toESM(require("fs"));
+var import_path7 = __toESM(require("path"));
+var import_fs5 = __toESM(require("fs"));
 
 // src/mcp/tools/reverse-engineer.ts
 var import_zod4 = require("zod");
@@ -830,7 +971,9 @@ The outputDir defaults to ./<domain>/. Ask the user where to save if unclear.`,
       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")
+      mode: import_zod4.z.enum(["headless", "binary-headful", "docker-headful", "extension"]).optional().describe("Browser mode override. Use 'extension' to capture the API of a tab already open in the user's real Chrome — requires options.tabId from the `tabs` tool. Chrome shows its 'is being debugged' bar while the capture runs."),
+      tabId: import_zod4.z.number().optional().describe("Only with mode='extension': the real Chrome tab to reverse-engineer (from the `tabs` tool)."),
+      clientId: import_zod4.z.string().optional().describe("Only with mode='extension', when multiple profiles are connected and the tab is ambiguous: the owning profile's clientId (from the `tabs` tool).")
     }).optional()
   }, async (params) => {
     try {
@@ -840,7 +983,22 @@ The outputDir defaults to ./<domain>/. Ask the user where to save if unclear.`,
       };
       const mode = params.options?.mode;
       const dockerRunning = await isDockerRunning();
-      const captureResult = mode === "docker-headful" && dockerRunning ? await apiPost("/execute", execParams) : await localApiPost("/execute", execParams);
+      let captureResult;
+      if (mode === "extension") {
+        if (typeof params.options?.tabId !== "number") {
+          return err("mode='extension' requires options.tabId. Call the `tabs` tool first to find the tab to reverse-engineer.");
+        }
+        captureResult = await localApiPost("/extension/execute", {
+          tabId: params.options.tabId,
+          clientId: params.options.clientId,
+          steps: params.steps,
+          options: { ...params.options, captureApi: true }
+        });
+      } else if (mode === "docker-headful" && dockerRunning) {
+        captureResult = await apiPost("/execute", execParams);
+      } else {
+        captureResult = await localApiPost("/execute", execParams);
+      }
       const lines = [];
       lines.push(`ok: ${captureResult.ok}`);
       lines.push(`steps: ${captureResult.completedSteps}/${captureResult.totalSteps}`);
@@ -883,11 +1041,11 @@ Screenshot saved: ${filePath}`);
         const mainDomain = captureResult.capturedApi[0]?.domain || "api";
         const outDir = params.outputDir || `./${mainDomain}`;
         try {
-          const fs4 = await import("fs");
-          const path6 = await import("path");
-          fs4.mkdirSync(outDir, { recursive: true });
-          const jsonPath = path6.join(outDir, "captured-api.json");
-          fs4.writeFileSync(jsonPath, JSON.stringify(captureResult.capturedApi, null, 2));
+          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.");
@@ -898,10 +1056,10 @@ Full captured data saved to: ${jsonPath}`);
       }
       let text = lines.join(`
 `);
-      if (text.length > 80000) {
-        text = text.slice(0, 80000) + `
+      if (text.length > 30000) {
+        text = text.slice(0, 30000) + `
 
-[... response truncated — read captured-api.json for full data]`;
+[... index truncated — read captured-api.json for the full endpoint list and all detail]`;
       }
       const content = [{ type: "text", text }];
       if (!captureResult.ok)
@@ -941,18 +1099,11 @@ Auth:`);
     }
     const protocolSummary = Array.from(byProtocol.entries()).map(([p, eps]) => `${p}=${eps.length}`).join(", ");
     lines.push(`
-Endpoints (${api.endpoints.length}) [${protocolSummary}]:`);
+Endpoints (${api.endpoints.length}) [${protocolSummary}] — full detail in captured-api.json:`);
     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 params2 = ep.requestBody ? extractSignalKeys(ep.requestBody) : null;
+      const tail = params2 ? `  {${params2}}` : "";
+      lines.push(`  [${ep.protocol}/${ep.verb}] ${ep.method} ${ep.path} → ${ep.functionName}${tail}`);
     }
   }
   const mainDomain = capturedApi[0]?.domain || "api";
@@ -1029,6 +1180,9 @@ function extractSignalKeys(body) {
       continue;
     if (typeof v === "string" && v.length > 80) {
       signalEntries.push(`${k}=${v.slice(0, 40)}...`);
+    } else if (Array.isArray(v)) {
+      const items = v.slice(0, 8).map((x) => String(x)).join(",");
+      signalEntries.push(`${k}=[${items}${v.length > 8 ? ",…" : ""}]`);
     } 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 ? ",..." : ""}}`);
@@ -1099,11 +1253,11 @@ Sessions live in the single local SQLite database (~/.iframer/iframer.db), share
         const lines = [result.message];
         if (result.capturedApi && result.capturedApi.length > 0) {
           formatCapturedApi(lines, result.capturedApi, { outputDir, typed: false });
-          const outDir = outputDir || import_path6.default.join(getDataDir(), "capture");
+          const outDir = outputDir || import_path7.default.join(getDataDir(), "capture");
           try {
-            import_fs4.default.mkdirSync(outDir, { recursive: true });
-            const jsonPath = import_path6.default.join(outDir, "captured-api.json");
-            import_fs4.default.writeFileSync(jsonPath, JSON.stringify(result.capturedApi, null, 2));
+            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) {
@@ -1173,19 +1327,19 @@ Full data saved to: ${jsonPath}`);
 
 // src/mcp/tools/credentials.ts
 var import_zod6 = require("zod");
-var import_fs6 = __toESM(require("fs"));
-var import_path8 = __toESM(require("path"));
+var import_fs7 = __toESM(require("fs"));
+var import_path9 = __toESM(require("path"));
 
 // src/lib/knowledge.ts
-var import_fs5 = __toESM(require("fs"));
-var import_path7 = __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_path7.default.join(getDataDir(), "knowledge");
+  return import_path8.default.join(getDataDir(), "knowledge");
 }
 function getKnowledgePath(domain) {
   const safe = sanitizeDomain(domain);
-  return import_path7.default.join(getKnowledgeDir(), `${safe}.md`);
+  return import_path8.default.join(getKnowledgeDir(), `${safe}.md`);
 }
 function normalizeDomain(input) {
   let d = (input || "").trim().toLowerCase();
@@ -1209,7 +1363,7 @@ function sanitizeDomain(input) {
 function readKnowledge(domain) {
   const p = getKnowledgePath(domain);
   try {
-    return import_fs5.default.readFileSync(p, "utf8");
+    return import_fs6.default.readFileSync(p, "utf8");
   } catch {
     return null;
   }
@@ -1218,7 +1372,7 @@ function listKnowledge() {
   const dir = getKnowledgeDir();
   let entries = [];
   try {
-    entries = import_fs5.default.readdirSync(dir);
+    entries = import_fs6.default.readdirSync(dir);
   } catch {
     return [];
   }
@@ -1226,10 +1380,10 @@ function listKnowledge() {
   for (const file of entries) {
     if (!file.endsWith(".md"))
       continue;
-    const full = import_path7.default.join(dir, file);
+    const full = import_path8.default.join(dir, file);
     try {
-      const stat = import_fs5.default.statSync(full);
-      const raw = import_fs5.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$/, ""),
@@ -1247,7 +1401,7 @@ function clearKnowledge(domain) {
   if (domain) {
     const p = getKnowledgePath(domain);
     try {
-      import_fs5.default.unlinkSync(p);
+      import_fs6.default.unlinkSync(p);
       return { removed: 1 };
     } catch {
       return { removed: 0 };
@@ -1255,11 +1409,11 @@ function clearKnowledge(domain) {
   }
   let removed = 0;
   try {
-    const entries = import_fs5.default.readdirSync(dir);
+    const entries = import_fs6.default.readdirSync(dir);
     for (const f of entries) {
       if (f.endsWith(".md")) {
         try {
-          import_fs5.default.unlinkSync(import_path7.default.join(dir, f));
+          import_fs6.default.unlinkSync(import_path8.default.join(dir, f));
           removed++;
         } catch {}
       }
@@ -1339,8 +1493,8 @@ var ELICIT_TIMEOUT_MS = 45000;
 function mcpLog(event, data) {
   try {
     const dir = getDataDir();
-    import_fs6.default.mkdirSync(dir, { recursive: true });
-    import_fs6.default.appendFileSync(import_path8.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 {}
 }
@@ -1540,6 +1694,452 @@ Actions:
   });
 }
 
+// src/mcp/tools/tabs.ts
+var import_zod8 = require("zod");
+function registerTabsTool(server) {
+  server.tool("tabs", `List the tabs currently open in the user's REAL Chrome browser, through the iframer browser extension.
+
+Use this when the user says something like "use my open tab", "the tab I have here", "my Gmail tab", or references a site/screenshot they already have open. Match their reference against the returned tabs (by url or title), pick the tab id, then call \`execute\` with options.mode="extension" and options.tabId=<id> to drive that exact tab on their real logged-in session (Chrome shows its "is being debugged" bar while a run is in progress).
+
+Requires the iframer Chrome extension to be installed and connected (paired once with the token). Once connected, iframer can see and drive any open tab. If nothing is connected, this returns a clear message telling the user how to connect.
+
+Returns: connected (bool), and tabs: [{ id, title, url, active, windowId }]. If several tabs match the user's reference, ask them which one rather than guessing.
+
+action="open" opens a NEW tab in the user's real Chrome (native — not a page popup) at options.url, and returns its tab id so you can immediately drive it with \`execute\` mode="extension".
+
+Tab GROUP management (native Chrome tab groups):
+- action="group": put tabIds into a group (new, or add to an existing groupId); optionally title/color/collapsed.
+- action="ungroup": remove tabIds from their group.
+- action="update-group": rename/recolor/collapse an EXISTING group by groupId (no tabIds needed).
+- action="groups": list all current groups (id, title, color, collapsed) — use to find a groupId to update.`, {
+    action: import_zod8.z.enum(["list", "open", "group", "ungroup", "update-group", "groups"]).optional().describe("'list' (default) lists open tabs; 'open' opens a new tab; 'group'/'ungroup' add/remove tabIds to a group; 'update-group' renames/recolors an existing group by groupId; 'groups' lists all groups."),
+    url: import_zod8.z.string().optional().describe("With action='open': the URL to open (omit for a blank tab)."),
+    active: import_zod8.z.boolean().optional().describe("With action='open': focus the new tab (default true)."),
+    tabIds: import_zod8.z.array(import_zod8.z.number()).optional().describe("With action='group': the tab ids to group (must be in the same window)."),
+    title: import_zod8.z.string().optional().describe("With action='group': the group's label."),
+    color: import_zod8.z.enum(["grey", "blue", "red", "yellow", "green", "pink", "purple", "cyan", "orange"]).optional().describe("With action='group': the group's color."),
+    collapsed: import_zod8.z.boolean().optional().describe("With action='group': collapse the group."),
+    groupId: import_zod8.z.number().optional().describe("With action='group': add tabs to this existing group instead of creating a new one."),
+    clientId: import_zod8.z.string().optional().describe("With action='open'/'group' and multiple profiles connected: which profile to act in."),
+    filter: import_zod8.z.string().optional().describe("With action='list': case-insensitive substring to match against tab url or title (e.g. 'gmail', 'github.com'). Omit to list every open tab.")
+  }, async ({ action, url, active, tabIds, title, color, collapsed, groupId, clientId, filter }) => {
+    try {
+      if (action === "open") {
+        const res = await localApiPost("/extension/tab/create", { url, active, clientId });
+        if (!res.ok || !res.tab)
+          return err(res.error || "Failed to open tab.");
+        const t = res.tab;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Opened tab [id ${t.id}] ${t.title || t.url}
+${t.url}
+Drive it with: execute mode="extension", tabId=${t.id}.`
+            }
+          ]
+        };
+      }
+      if (action === "group") {
+        if (!tabIds || tabIds.length === 0)
+          return err("action='group' requires tabIds (array of tab ids).");
+        const res = await localApiPost("/extension/tab/group", { tabIds, title, color, collapsed, groupId, clientId });
+        if (!res.ok || !res.group)
+          return err(res.error || "Failed to group tabs.");
+        const g = res.group;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Grouped ${tabIds.length} tab(s) into group ${g.groupId}${g.title ? ` "${g.title}"` : ""}${g.color ? ` (${g.color})` : ""}${g.collapsed ? ", collapsed" : ""}.`
+            }
+          ]
+        };
+      }
+      if (action === "ungroup") {
+        if (!tabIds || tabIds.length === 0)
+          return err("action='ungroup' requires tabIds.");
+        const res = await localApiPost("/extension/tab/ungroup", { tabIds, clientId });
+        if (!res.ok)
+          return err(res.error || "Failed to ungroup tabs.");
+        return { content: [{ type: "text", text: `Ungrouped ${tabIds.length} tab(s).` }] };
+      }
+      if (action === "update-group") {
+        if (typeof groupId !== "number")
+          return err("action='update-group' requires groupId (from action='groups'). Pass any of title, color, collapsed.");
+        const res = await localApiPost("/extension/group/update", { groupId, title, color, collapsed, clientId });
+        if (!res.ok || !res.group)
+          return err(res.error || "Failed to update group.");
+        const g = res.group;
+        return { content: [{ type: "text", text: `Updated group ${g.groupId} → title "${g.title}", color ${g.color}${g.collapsed ? ", collapsed" : ""}.` }] };
+      }
+      if (action === "groups") {
+        const res = await localApiPost("/extension/groups", { clientId });
+        if (!res.ok)
+          return err(res.error || "Failed to list groups.");
+        const groups = res.groups || [];
+        if (groups.length === 0)
+          return { content: [{ type: "text", text: "No tab groups open." }] };
+        const lines2 = [`${groups.length} tab group(s):`, ""];
+        for (const g of groups)
+          lines2.push(`  [group ${g.groupId}] "${g.title || "(untitled)"}" — ${g.color}${g.collapsed ? ", collapsed" : ""} (window ${g.windowId})`);
+        return { content: [{ type: "text", text: lines2.join(`
+`) }] };
+      }
+      const status = await localApiGet("/extension/status");
+      if (!status.connected) {
+        return err(`No iframer extension is connected.
+
+` + `To use your real Chrome tabs:
+` + "1. Install the iframer extension (chrome://extensions → Load unpacked → the `extension/` folder).\n" + "2. Run `iframer install extension` in a terminal, then restart the browser — the extension pairs itself.\n" + "   (Manual fallback: click the iframer icon and paste the token from `cat ~/.iframer/secret`.)\n" + "Once the dot is green, run `tabs` again — iframer can then see and drive any open tab.");
+      }
+      const data = await localApiPost("/extension/tabs", {});
+      let tabs = data.tabs || [];
+      const clients = data.clients || [];
+      const multiProfile = clients.length > 1;
+      if (filter) {
+        const f = filter.toLowerCase();
+        tabs = tabs.filter((t) => t.url.toLowerCase().includes(f) || (t.title || "").toLowerCase().includes(f));
+      }
+      if (tabs.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: filter ? `Extension connected, but no open tab matches "${filter}".` : "Extension connected, but no tabs were reported."
+            }
+          ]
+        };
+      }
+      const profiles = clients.map((c) => c.profileName || c.clientId.slice(0, 8)).join(", ");
+      const ver = clients[0]?.extVersion ? ` [ext v${clients[0].extVersion}]` : "";
+      const lines = [
+        `Connected: ${clients.length} profile${clients.length > 1 ? "s" : ""}${profiles ? ` (${profiles})` : ""}${ver}.`,
+        `${tabs.length} tab${tabs.length > 1 ? "s" : ""}${filter ? ` matching "${filter}"` : ""}:`,
+        ""
+      ];
+      for (const t of tabs) {
+        const prof = multiProfile ? `  «${t.profileName || t.clientId.slice(0, 8)}»` : "";
+        lines.push(`  [id ${t.id}]${t.active ? " (active)" : ""}${prof} ${t.title}`);
+        lines.push(`         ${t.url}`);
+        if (multiProfile)
+          lines.push(`         clientId: ${t.clientId}`);
+      }
+      lines.push("");
+      lines.push('To drive one: execute with options.mode="extension", options.tabId=<id>.');
+      if (multiProfile) {
+        lines.push("Multiple profiles are connected — if two tabs share a title, also pass options.clientId " + "(shown as «profile» above maps to a clientId) so the right profile is driven.");
+      }
+      return { content: [{ type: "text", text: lines.join(`
+`) }] };
+    } catch (e) {
+      return err(`Error listing tabs: ${getErrorMessage(e)}`);
+    }
+  });
+}
+
+// src/mcp/tools/anchors.ts
+var import_zod9 = require("zod");
+
+// src/lib/knowledge/component-map.ts
+var import_fs8 = __toESM(require("fs"));
+var import_path10 = __toESM(require("path"));
+function anchorsPath(domain) {
+  return import_path10.default.join(getKnowledgeDir(), `${sanitizeDomain(domain)}.anchors.json`);
+}
+function loadComponentMap(domain) {
+  const norm = normalizeDomain(domain);
+  try {
+    const raw = import_fs8.default.readFileSync(anchorsPath(norm), "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+      domain: parsed.domain || norm,
+      anchors: parsed.anchors || {},
+      quirks: Array.isArray(parsed.quirks) ? parsed.quirks : []
+    };
+  } catch {
+    return { domain: norm, anchors: {}, quirks: [] };
+  }
+}
+function write(cm) {
+  import_fs8.default.mkdirSync(getKnowledgeDir(), { recursive: true });
+  import_fs8.default.writeFileSync(anchorsPath(cm.domain), JSON.stringify(cm, null, 2), "utf8");
+}
+function saveAnchor(domain, input, now) {
+  const cm = loadComponentMap(domain);
+  cm.anchors[input.name] = {
+    name: input.name,
+    selector: input.selector,
+    role: input.role,
+    description: input.description,
+    quirks: input.quirks && input.quirks.length ? input.quirks : undefined,
+    uses: 0,
+    fails: 0,
+    lastVerified: now
+  };
+  write(cm);
+}
+function removeAnchor(domain, name) {
+  const cm = loadComponentMap(domain);
+  if (!(name in cm.anchors))
+    return false;
+  delete cm.anchors[name];
+  write(cm);
+  return true;
+}
+function setDomainQuirks(domain, quirks) {
+  const cm = loadComponentMap(domain);
+  cm.quirks = Array.from(new Set([...cm.quirks, ...quirks]));
+  write(cm);
+}
+function listAnchorDomains() {
+  try {
+    return import_fs8.default.readdirSync(getKnowledgeDir()).filter((f) => f.endsWith(".anchors.json")).map((f) => f.replace(/\.anchors\.json$/, ""));
+  } catch {
+    return [];
+  }
+}
+
+// src/mcp/tools/anchors.ts
+function registerRememberTool(server) {
+  server.tool("remember", `Persisted per-domain map of a website's UI elements ("anchors"), so the agent recalls where things are instead of re-exploring the DOM every run.
+
+WORKFLOW:
+1. Before a UI task on a site, call \`remember get <domain>\`. If an anchor exists (e.g. "composer", "send-button"), use it directly: put \`@a:<name>\` in any selector field of an \`execute\` step (click/fill/etc.). It resolves to the saved selector — no snapshot needed.
+2. If the site is new or the anchor you need is missing, discover the element with a \`snapshot\` or \`find\` step, act on it, then \`remember save\` it (name + the selector that worked, plus any quirks) so future runs are instant.
+3. SELF-HEAL: if a step using \`@a:<name>\` FAILS, the page changed — do NOT keep retrying the same anchor. Re-discover with snapshot/find, then \`remember save\` the new selector under the same name (overwrites, resets the health counters). Prefer stable selectors (aria-label, data-qa, role+name) over brittle generated CSS.
+4. Record site quirks with \`remember quirk\` (e.g. "synthetic clicks ignored — use trusted/coordinate clicks", "@here triggers a confirmation modal — click Send"). \`get\` surfaces them so the agent isn't surprised.
+
+Anchors live at ~/.iframer/knowledge/<domain>.anchors.json, alongside the API knowledge cache.`, {
+    action: import_zod9.z.enum(["get", "save", "forget", "list", "quirk"]).describe("get: show a domain's anchors+quirks | save: create/overwrite an anchor | forget: delete an anchor | list: all domains with anchors | quirk: add site-wide quirk note(s)"),
+    domain: import_zod9.z.string().optional().describe("Site domain, e.g. 'slack.com' or 'app.slack.com' (required for all actions except list)."),
+    name: import_zod9.z.string().optional().describe("Anchor name for save/forget, e.g. 'composer', 'send-button', 'search'. Short, stable, kebab-case."),
+    selector: import_zod9.z.string().optional().describe("With save: the CSS selector that locates the element. Prefer stable attributes: [aria-label=...], [data-qa=...], role+name. Avoid brittle generated class chains."),
+    role: import_zod9.z.string().optional().describe("With save (optional): the element role, e.g. textbox, button, link."),
+    description: import_zod9.z.string().optional().describe("With save (optional): a short human note about the element."),
+    quirks: import_zod9.z.array(import_zod9.z.string()).optional().describe("With save: element-specific gotchas. With quirk: site-wide gotchas to append.")
+  }, async ({ action, domain, name, selector, role, description, quirks }) => {
+    try {
+      if (action === "list") {
+        const domains = listAnchorDomains();
+        if (domains.length === 0) {
+          return { content: [{ type: "text", text: "No anchors saved yet. Use `remember save` after locating an element with snapshot/find." }] };
+        }
+        const lines = [`Domains with saved anchors:
+`];
+        for (const d of domains) {
+          const cm = loadComponentMap(d);
+          lines.push(`  ${d} — ${Object.keys(cm.anchors).length} anchor(s)${cm.quirks.length ? `, ${cm.quirks.length} quirk(s)` : ""}`);
+        }
+        lines.push("\nCall `remember get <domain>` for details.");
+        return { content: [{ type: "text", text: lines.join(`
+`) }] };
+      }
+      if (!domain)
+        return err(`\`${action}\` requires a domain (e.g. 'app.slack.com').`);
+      if (action === "get") {
+        const cm = loadComponentMap(domain);
+        const names = Object.keys(cm.anchors);
+        if (names.length === 0 && cm.quirks.length === 0) {
+          return { content: [{ type: "text", text: `No anchors saved for ${domain} yet. Discover elements with snapshot/find, then \`remember save\` them.` }] };
+        }
+        const lines = [`Component map for ${domain}:
+`];
+        if (cm.quirks.length) {
+          lines.push("Site quirks:");
+          for (const q of cm.quirks)
+            lines.push(`  - ${q}`);
+          lines.push("");
+        }
+        lines.push(`Anchors (use as @a:<name> in any selector):`);
+        for (const a of Object.values(cm.anchors)) {
+          const health = a.fails > 0 ? `  [${a.uses}✓/${a.fails}✗${a.fails >= a.uses && a.fails >= 2 ? " — likely STALE, re-verify" : ""}]` : a.uses > 0 ? `  [${a.uses}✓]` : "";
+          lines.push(`  @a:${a.name}${a.role ? ` (${a.role})` : ""} → ${a.selector}${health}`);
+          if (a.description)
+            lines.push(`      ${a.description}`);
+          if (a.quirks?.length)
+            for (const q of a.quirks)
+              lines.push(`      • ${q}`);
+        }
+        return { content: [{ type: "text", text: lines.join(`
+`) }] };
+      }
+      if (action === "quirk") {
+        if (!quirks || quirks.length === 0)
+          return err("`quirk` requires a non-empty `quirks` array.");
+        setDomainQuirks(domain, quirks);
+        return { content: [{ type: "text", text: `Added ${quirks.length} quirk(s) to ${domain}.` }] };
+      }
+      if (action === "forget") {
+        if (!name)
+          return err("`forget` requires the anchor `name`.");
+        const removed = removeAnchor(domain, name);
+        return { content: [{ type: "text", text: removed ? `Removed anchor @a:${name} from ${domain}.` : `No anchor named '${name}' for ${domain}.` }] };
+      }
+      if (!name)
+        return err("`save` requires an anchor `name`.");
+      if (!selector)
+        return err("`save` requires a `selector` (the CSS that locates the element).");
+      saveAnchor(domain, { name, selector, role, description, quirks }, new Date().toISOString());
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Saved anchor @a:${name} for ${domain} → ${selector}
+Use it in any selector field: e.g. {"type":"click","selector":"@a:${name}"}.`
+          }
+        ]
+      };
+    } catch (e) {
+      return err(`remember failed: ${getErrorMessage(e)}`);
+    }
+  });
+}
+
+// src/mcp/tools/clipboard.ts
+var import_zod10 = require("zod");
+
+// src/lib/clipboard.ts
+var import_child_process2 = require("child_process");
+function platformTools(mode) {
+  if (process.platform === "darwin")
+    return [[mode === "read" ? "pbpaste" : "pbcopy"]];
+  if (mode === "read")
+    return [["wl-paste", "-n"], ["xclip", "-selection", "clipboard", "-o"], ["xsel", "-b", "-o"]];
+  return [["wl-copy"], ["xclip", "-selection", "clipboard", "-i"], ["xsel", "-b", "-i"]];
+}
+function run(cmd, input) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = import_child_process2.spawn(cmd[0], cmd.slice(1));
+    } catch {
+      resolve({ ok: false, out: "", err: `spawn ${cmd[0]} failed` });
+      return;
+    }
+    let out = "";
+    let errOut = "";
+    child.stdout?.on("data", (d) => out += d);
+    child.stderr?.on("data", (d) => errOut += d);
+    child.on("error", (e) => resolve({ ok: false, out: "", err: e.message }));
+    child.on("close", (code) => resolve({ ok: code === 0, out, err: errOut }));
+    if (input !== undefined) {
+      child.stdin?.write(input);
+      child.stdin?.end();
+    }
+  });
+}
+async function clipboardWrite(text) {
+  const tools = platformTools("write");
+  for (const cmd of tools) {
+    if ((await run(cmd, text)).ok)
+      return;
+  }
+  throw new Error(`No working clipboard tool found (${tools.map((t) => t[0]).join(", ")}).`);
+}
+async function clipboardRead() {
+  const tools = platformTools("read");
+  let lastErr = "";
+  for (const cmd of tools) {
+    const r = await run(cmd);
+    if (r.ok)
+      return r.out;
+    lastErr = r.err;
+  }
+  throw new Error(`No working clipboard tool found (${tools.map((t) => t[0]).join(", ")}). ${lastErr}`);
+}
+
+// src/mcp/tools/clipboard.ts
+function registerClipboardTool(server) {
+  server.tool("clipboard", `Read or write the machine's clipboard (the same one the user's Chrome pastes from — iframer runs locally).
+
+Use this instead of trying to grant a page clipboard permission (not possible via the extension):
+- To READ something a site copied (a code, a link): clipboard get.
+- To WRITE text to the clipboard: clipboard set <text>.
+- To PASTE the clipboard into a page field: use the \`paste\` execute step (do NOT rely on a ⌘V keyboard step — the extension relay ignores modifier keys).`, {
+    action: import_zod10.z.enum(["get", "set"]).describe("get: read clipboard text | set: write text to clipboard"),
+    text: import_zod10.z.string().optional().describe("With action='set': the text to put on the clipboard.")
+  }, async ({ action, text }) => {
+    try {
+      if (action === "set") {
+        if (text === undefined)
+          return err("action='set' requires `text`.");
+        await clipboardWrite(text);
+        return { content: [{ type: "text", text: `Clipboard set (${text.length} chars). To paste into a field, use the \`paste\` execute step.` }] };
+      }
+      const value = await clipboardRead();
+      return { content: [{ type: "text", text: value.length ? value : "(clipboard is empty)" }] };
+    } catch (e) {
+      return err(`clipboard failed: ${getErrorMessage(e)}`);
+    }
+  });
+}
+
+// src/mcp/telemetry.ts
+var import_fs9 = __toESM(require("fs"));
+var import_path11 = __toESM(require("path"));
+var CHARS_PER_TOKEN = 4;
+var est = (chars) => Math.round(chars / CHARS_PER_TOKEN);
+var enabled = process.env.IFRAMER_TELEMETRY !== "0";
+var sessionId = `${new Date().toISOString().slice(0, 10)}-${process.pid}`;
+function telemetryPath() {
+  return import_path11.default.join(getDataDir(), "telemetry.jsonl");
+}
+var sessionCalls = 0;
+var sessionChars = 0;
+function write2(rec) {
+  if (!enabled)
+    return;
+  try {
+    import_fs9.default.appendFileSync(telemetryPath(), JSON.stringify({ ts: new Date().toISOString(), session: sessionId, ...rec }) + `
+`);
+  } catch {}
+}
+function recordDefinitions(toolCount, defChars, instructionChars) {
+  write2({
+    kind: "definitions",
+    toolCount,
+    defChars,
+    instructionChars,
+    estTokens: est(defChars + instructionChars)
+  });
+}
+function recordCall(tool, inChars, outChars, ms, isError) {
+  sessionCalls++;
+  sessionChars += inChars + outChars;
+  write2({
+    kind: "call",
+    tool,
+    inChars,
+    outChars,
+    estTokens: est(inChars + outChars),
+    ms,
+    isError,
+    sessionCalls,
+    sessionEstTokens: est(sessionChars)
+  });
+}
+function contentChars(res) {
+  const r = res;
+  if (!r || !Array.isArray(r.content))
+    return 0;
+  let n = 0;
+  for (const c of r.content) {
+    if (typeof c?.text === "string")
+      n += c.text.length;
+    else if (typeof c?.data === "string")
+      n += c.data.length;
+  }
+  return n;
+}
+function safeJsonLen(v) {
+  try {
+    return v === undefined ? 0 : JSON.stringify(v).length;
+  } catch {
+    return 0;
+  }
+}
+
 // src/mcp/server.ts
 var IS_DEV = process.env.IFRAMER_URL?.includes("localhost") || process.env.IFRAMER_URL?.includes("127.0.0.1");
 var INSTRUCTIONS = IS_DEV ? `iframer-dev — local development instance of iframer (connects to ${BASE_URL}).
@@ -1560,8 +2160,10 @@ CRITICAL RULES:
 3. DO NOT present options when you can just act. Check status, credentials, execute.
 4. NEVER re-store credentials when login fails. Login failures are browser-mode problems, not credential problems.
 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.
+6. For UI tasks on a site, check "remember get <domain>" first — saved anchors let you target elements as @a:<name> (in any selector) instead of re-finding them. After you locate a new element with snapshot/find and it works, "remember save" it. If an @a: anchor fails, the page changed: re-discover and "remember save" the new selector (don't retry the stale one).
+7. 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.
 
@@ -1569,6 +2171,28 @@ CAPTCHA: In binary-headful mode, ask the user to solve it in the visible window.
 
 REVERSE ENGINEERING: Use the "reverse-engineer" tool when the user asks to capture/map/save API endpoints.`;
 var server = new import_mcp.McpServer({ name: "iframer", version: "3.0.0" }, { instructions: INSTRUCTIONS });
+var defChars = 0;
+var defCount = 0;
+{
+  const origTool = server.tool.bind(server);
+  server.tool = (...a) => {
+    const name = String(a[0]);
+    defCount++;
+    defChars += name.length + (typeof a[1] === "string" ? a[1].length : 0);
+    const hIdx = a.length - 1;
+    const handler = a[hIdx];
+    if (typeof handler === "function") {
+      a[hIdx] = async (...ha) => {
+        const started = Date.now();
+        const res = await handler(...ha);
+        const r = res;
+        recordCall(name, safeJsonLen(ha[0]), contentChars(res), Date.now() - started, !!r?.isError);
+        return res;
+      };
+    }
+    return origTool(...a);
+  };
+}
 registerStatusTool(server);
 registerBrowseTool(server);
 registerExecuteTool(server);
@@ -1576,18 +2200,20 @@ 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);
-});
+registerTabsTool(server);
+registerRememberTool(server);
+registerClipboardTool(server);
+recordDefinitions(defCount, defChars, INSTRUCTIONS.length);
+process.on("SIGTERM", () => process.exit(0));
+process.on("SIGINT", () => process.exit(0));
+process.stdin.on("end", () => process.exit(0));
+process.stdin.on("close", () => process.exit(0));
+var originalPpid = process.ppid;
+var orphanCheck = setInterval(() => {
+  if (process.ppid !== originalPpid || process.ppid === 1)
+    process.exit(0);
+}, 30000);
+orphanCheck.unref?.();
 process.on("uncaughtException", (err2) => {
   try {
     console.error(`[mcp] uncaughtException: ${err2?.message}`);