cdp-toolkit 2.6.0 → 3.0.0

package/dist/mcp.js

@@ -473,6 +473,37 @@ var init_workers = __esm(() => {
   WORKER_SELECTOR_PAGE_ONLY_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, and this tool is page-only " + "(closing, selecting or releasing a worker is meaningless). The tools that accept a worker: target are " + `${WORKER_CAPABLE_TOOLS.join(", ")}.`;
 });
 
+// src/frames.ts
+function isFrameSelector(selector) {
+  return typeof selector === "string" && selector.startsWith(FRAME_SELECTOR_PREFIX);
+}
+function frameNeedle(selector) {
+  return selector.slice(FRAME_SELECTOR_PREFIX.length);
+}
+function isFrameTargetType(type) {
+  return type === FRAME_TARGET_TYPE;
+}
+function resolveFrameTargets(targets, needle) {
+  const liveFrames = targets.filter((t) => isFrameTargetType(t.type));
+  return {
+    matches: needle === "" ? [] : liveFrames.filter((t) => t.url.includes(needle)),
+    liveFrames
+  };
+}
+function frameAmbiguityMessage(needle, matches) {
+  return `'frame:${needle}' matches more than one out-of-process iframe: ` + matches.map((m) => `${m.url} (${m.id})`).join(", ") + ". Narrow the substring, or pass the iframe's target id directly.";
+}
+function frameMissMessage(needle, liveFrames) {
+  const live = liveFrames.length ? ` (out-of-process iframes: ${liveFrames.map((f) => f.url).join(", ")})` : " (no out-of-process iframes are live)";
+  return `no out-of-process iframe whose url contains '${needle}'${live}. ` + "Only a CROSS-ORIGIN iframe gets its own process and therefore its own target; a same-origin iframe " + "runs inside its parent page and is NOT a target at all, so no substring can ever select it — reach a " + "same-origin iframe through its parent page instead (evaluate_script on the page, then the iframe " + "element's contentDocument). An out-of-process iframe whose document navigated away is likewise gone " + "from the listing: re-list with list_pages{all:true} and pass the new target id.";
+}
+var FRAME_SELECTOR_PREFIX = "frame:", FRAME_PAGE_ONLY_TOOLS, FRAME_TARGET_TYPE = "iframe", FRAME_EMPTY_NEEDLE_MESSAGE = "'frame:' needs a substring of the iframe's url, e.g. frame:ads.example.com or frame:player.html", FRAME_SELECTOR_UNSUPPORTED_MESSAGE, FRAME_SELECTOR_PAGE_ONLY_MESSAGE;
+var init_frames = __esm(() => {
+  FRAME_PAGE_ONLY_TOOLS = ["close_page", "select_page", "release_page", "claim_page"];
+  FRAME_SELECTOR_UNSUPPORTED_MESSAGE = "target 'frame:<substring>' selects an out-of-process iframe, which this backend cannot address " + "(WebDriver BiDi has no iframe target — an iframe is a realm inside its tab's browsing context, not a " + "selectable target; Capability 'frame.targets' is Chrome-only). Use --browser chrome to act on a cross-origin iframe.";
+  FRAME_SELECTOR_PAGE_ONLY_MESSAGE = "target 'frame:<substring>' selects an out-of-process iframe, and this tool is page-only " + "(closing, selecting, releasing or claiming an iframe is meaningless; these act on the embedder tab). " + `The page-only tools are ${FRAME_PAGE_ONLY_TOOLS.join(", ")}; every other tool that takes a 'target' ` + "accepts a frame: selector.";
+});
+
 // src/client.ts
 class CdpConnection {
   wsUrl;
@@ -671,6 +702,17 @@ async function pickTarget(targets, selector) {
       return matches[0];
     throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers }));
   }
+  if (isFrameSelector(selector)) {
+    const needle = frameNeedle(selector);
+    if (needle === "")
+      throw new CdpError(FRAME_EMPTY_NEEDLE_MESSAGE);
+    const { matches, liveFrames } = resolveFrameTargets(targets, needle);
+    if (matches.length > 1)
+      throw new CdpError(frameAmbiguityMessage(needle, matches));
+    if (matches.length === 1)
+      return matches[0];
+    throw new CdpError(frameMissMessage(needle, liveFrames));
+  }
   const byId = targets.find((t) => t.id === selector);
   if (!byId)
     throw new CdpError(`no target with id '${selector}'`);
@@ -697,6 +739,7 @@ var init_client = __esm(() => {
   init_leases();
   init_origins();
   init_workers();
+  init_frames();
   BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
   DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15000);
   CdpError = class CdpError extends Error {
@@ -2844,6 +2887,9 @@ async function pickContext(conn, contexts, selector) {
   if (isWorkerSelector(selector)) {
     throw driverError2("unsupported", WORKER_SELECTOR_UNSUPPORTED_MESSAGE);
   }
+  if (isFrameSelector(selector)) {
+    throw driverError2("unsupported", FRAME_SELECTOR_UNSUPPORTED_MESSAGE);
+  }
   const exact = contexts.find((c) => c.context === selector);
   if (exact)
     return exact;
@@ -3055,6 +3101,7 @@ var init_driver2 = __esm(() => {
   init_leases();
   init_origins();
   init_workers();
+  init_frames();
   init_activity();
   init_client2();
   init_session_lease();
@@ -4175,7 +4222,8 @@ var CDP_CAPABILITIES = new Set([
   "emulate.focus",
   "browser.downloads",
   "browser.permissions",
-  "worker.targets"
+  "worker.targets",
+  "frame.targets"
 ]);
 
 class CdpPageDriver {
@@ -4308,6 +4356,7 @@ class CdpPageDriver {
     const interactiveOnly = opts?.interactiveOnly ?? false;
     await this.ensureDomain("Accessibility");
     const { nodes } = await this.conn.send("Accessibility.getFullAXTree");
+    const oopifFrames = await this.detectOopifFrames();
     const byId = new Map;
     for (const n of nodes)
       byId.set(n.nodeId, n);
@@ -4316,11 +4365,17 @@ class CdpPageDriver {
     const walk = (node, depth) => {
       const role = axString(node.role);
       const name = axString(node.name);
-      const backendNodeId = node.backendDOMNodeId;
-      const emitted = !node.ignored && backendNodeId !== undefined && (interactiveOnly ? isInteractive(role) : !!(role || name));
+      const backendDOMNodeId = node.backendDOMNodeId;
+      const marker = backendDOMNodeId !== undefined ? oopifFrames.get(backendDOMNodeId) : undefined;
+      const emitted = !node.ignored && backendDOMNodeId !== undefined && (interactiveOnly ? isInteractive(role) || marker !== undefined : !!(role || name));
       if (emitted) {
         const extras = axExtras(node);
-        out.push({ uid: encodeUid(backendNodeId), role: role ?? "generic", depth, ...name ? { name } : {}, ...Object.keys(extras).length ? { extras } : {} });
+        if (marker) {
+          extras.frame = marker.frameId;
+          if (marker.frameUrl)
+            extras.frameUrl = marker.frameUrl;
+        }
+        out.push({ uid: encodeUid(backendDOMNodeId), role: role ?? "generic", depth, ...name ? { name } : {}, ...Object.keys(extras).length ? { extras } : {} });
       }
       const childDepth = emitted && !interactiveOnly ? depth + 1 : depth;
       for (const childId of node.childIds ?? []) {
@@ -4333,6 +4388,20 @@ class CdpPageDriver {
       walk(root, 0);
     return out;
   }
+  async detectOopifFrames() {
+    const markers = new Map;
+    try {
+      await this.ensureDomainSoft("DOM");
+      const iframeTargets = (await listTargets()).filter((t) => t.type === "iframe");
+      for (const target of iframeTargets) {
+        const owner = await this.conn.send("DOM.getFrameOwner", { frameId: target.id }).catch(() => ({ backendNodeId: undefined }));
+        if (typeof owner.backendNodeId === "number") {
+          markers.set(owner.backendNodeId, { frameId: target.id, ...target.url ? { frameUrl: target.url } : {} });
+        }
+      }
+    } catch {}
+    return markers;
+  }
   async locate(loc) {
     return encodeUid(await backendNodeIdOf(this.conn, loc));
   }
@@ -5510,6 +5579,7 @@ init_leases();
 init_activity();
 init_origins();
 init_workers();
+init_frames();
 var ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 
@@ -5566,6 +5636,9 @@ async function pickPage(driver, pages, selector) {
   if (isWorkerSelector(selector)) {
     throw new SharedToolError(backendOf(driver) === "firefox" ? WORKER_SELECTOR_UNSUPPORTED_MESSAGE : WORKER_SELECTOR_PAGE_ONLY_MESSAGE);
   }
+  if (isFrameSelector(selector)) {
+    throw new SharedToolError(backendOf(driver) === "firefox" ? FRAME_SELECTOR_UNSUPPORTED_MESSAGE : FRAME_SELECTOR_PAGE_ONLY_MESSAGE);
+  }
   const exactPage = pages.find((x) => x.id === selector);
   if (exactPage)
     return exactPage;
@@ -8405,7 +8478,7 @@ var MANIFEST = [
         },
         all: {
           type: "boolean",
-          description: "Include non-page targets."
+          description: "Include non-page targets (workers, iframes)."
         },
         probe: {
           type: "boolean",
@@ -10750,38 +10823,54 @@ for (const group of TOOL_GROUPS) {
     TOOL_GROUP[tool] = group;
   }
 }
+var GATEWAY_TOOLS = ["navigate_page", "take_snapshot", "click", "fill", "evaluate_script"];
 var PROFILES = {
+  gateway: [],
   core: ["core"],
   full: [...TOOL_GROUPS]
 };
+function isListed(profile, name) {
+  const group = TOOL_GROUP[name];
+  return profile.tools.has(name) || group !== undefined && profile.groups.has(group);
+}
 function resolveProfile(spec) {
-  const all = () => ({ groups: new Set(TOOL_GROUPS), label: "full" });
+  const all = () => ({ groups: new Set(TOOL_GROUPS), tools: new Set, label: "full" });
   const raw = (spec ?? "").trim();
-  if (raw === "" || raw.toLowerCase() === "full")
+  if (raw === "")
+    return { groups: new Set, tools: new Set(GATEWAY_TOOLS), label: "gateway" };
+  if (raw.toLowerCase() === "full")
     return all();
   const tokens = raw.split(",").map((t) => t.trim().toLowerCase()).filter((t) => t !== "");
   if (tokens.includes("full"))
     return all();
+  const gateway = tokens.includes("gateway");
   const known = new Set(TOOL_GROUPS);
-  const picked = new Set(["core"]);
+  const picked = new Set(gateway ? [] : ["core"]);
   for (const token of tokens) {
+    if (token === "gateway")
+      continue;
     if (!known.has(token)) {
-      throw new Error(`CDP_TOOL_PROFILE: unknown tool group '${token}'. Known: full, core, ${TOOL_GROUPS.filter((g) => g !== "core").join(", ")}`);
+      throw new Error(`CDP_TOOL_PROFILE: unknown tool group '${token}'. Known: gateway, full, core, ${TOOL_GROUPS.filter((g) => g !== "core").join(", ")}`);
     }
     picked.add(token);
   }
   if (picked.size === TOOL_GROUPS.length)
     return all();
-  return { groups: picked, label: TOOL_GROUPS.filter((g) => picked.has(g)).join(",") };
+  const groupLabel = TOOL_GROUPS.filter((g) => picked.has(g));
+  return {
+    groups: picked,
+    tools: new Set(gateway ? GATEWAY_TOOLS : []),
+    label: (gateway ? ["gateway", ...groupLabel] : groupLabel).join(",")
+  };
 }
 
 // src/toolDocs.ts
 var TOOL_DOCS = {
   list_pages: {
-    description: "Enumerate browser page targets (GET /json/list); page-type tabs only unless all=true. Each entry carries its targetId plus an origin field: 'agent' means this toolkit created it (also carries the creating label/createdAt, and stays 'agent' after the lease is released or the creator dies, making stray agent tabs findable), 'unknown' means no creation record - it never says 'human', the honest word for any tab it did not create; a record that exists but won't read adds originUnreadable. An entry under an active, readable lease also carries a 'lease' object {label,pid,idleMs,expiresAt,stale}, with idleMs and expiresAt computed fresh every call (never off disk), independent of probe. Under CDP_REQUIRE_LEASE this call also reaps abandoned agent tabs into an additive reaped array - but a lease reads reclaimable the moment its TTL elapses, while the tab is CLOSED only after a further grace (CDP_REAP_GRACE_MS, default 2700000ms/45min, so 60min total after last use); a dead-pid lease is reaped at once, a tab with no lease never. With probe, each page-type entry also gets 'responsive' (and humanActiveMs where human input is seen); both are absent, never false/null, without probe.",
+    description: "Enumerate browser page targets (GET /json/list); page-type tabs only unless all=true, which also lists workers and out-of-process (OOPIF) iframes. Each entry carries its targetId plus an origin field: 'agent' means this toolkit created it (also carries the creating label/createdAt, and stays 'agent' after the lease is released or the creator dies, making stray agent tabs findable), 'unknown' means no creation record - it never says 'human', the honest word for any tab it did not create; a record that exists but won't read adds originUnreadable. An entry under an active, readable lease also carries a 'lease' object {label,pid,idleMs,expiresAt,stale}, with idleMs and expiresAt computed fresh every call (never off disk), independent of probe. Under CDP_REQUIRE_LEASE this call also reaps abandoned agent tabs into an additive reaped array - but a lease reads reclaimable the moment its TTL elapses, while the tab is CLOSED only after a further grace (CDP_REAP_GRACE_MS, default 2700000ms/45min, so 60min total after last use); a dead-pid lease is reaped at once, a tab with no lease never. With probe, each page-type entry also gets 'responsive' (and humanActiveMs where human input is seen); both are absent, never false/null, without probe.",
     params: {
       lease: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
-      all: "Include non-page targets (service/shared workers, background pages); default false lists page-type tabs only.",
+      all: "Include non-page targets (service/shared workers, background pages, out-of-process (OOPIF) iframes); default false lists page-type tabs only. A returned non-page targetId is accepted as a bare id by any tool's `target` param.",
       probe: "Ping each page-type renderer before returning, one bounded 500ms check per target and never more, so a wedged tab can't stall the listing. Adds 'responsive' (false on timeout/exception/unreachable, never an error for the whole call) and, where the same round trip finds human input, humanActiveMs. Default false. On a backend that cannot answer the ping, responsive is absent too (not false)."
     }
   },
@@ -10882,7 +10971,7 @@ var TOOL_DOCS = {
     }
   },
   take_snapshot: {
-    description: "Captures the page's accessibility tree as an indented text tree, each line prefixed [uid] (a CDP backendDOMNodeId). Every interaction tool (click/hover/fill/etc.) resolves that uid via DOM.resolveNode — run this first to discover uids to act on.",
+    description: `Captures the page's accessibility tree as an indented text tree, each line prefixed [uid] (a CDP backendDOMNodeId). Every interaction tool (click/hover/fill/etc.) resolves that uid via DOM.resolveNode — run this first to discover uids to act on. Cross-origin iframe subtrees are not walked (they live in a separate renderer process); the iframe node itself is emitted with a frame="<targetId>" marker (also in interactiveOnly mode), so the frame is discoverable and driveable via that id or frame:<url-substring>.`,
     params: {
       lease: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process or one claimed explicitly. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
       target: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'. Grammar: see server instructions.",
@@ -11280,7 +11369,7 @@ var TOOL_DOCS = {
 };
 
 // src/version.ts
-var VERSION = "2.6.0";
+var VERSION = "3.0.0";
 
 // src/mcp.ts
 function isDirectRun() {
@@ -11338,15 +11427,18 @@ function auditCoverage() {
     console.error(`[cdp-toolkit] WARN: manifest schemas with no registered tool: ${orphanSchema.join(", ")}`);
 }
 var INSTRUCTIONS = [
-  "cdp-toolkit drives a real browser over Chrome DevTools Protocol (or Firefox WebDriver-BiDi): open and drive pages, click/fill/type, screenshot and accessibility-snapshot, read console + network, set cookies, emulate devices, run Lighthouse and performance traces, record screencasts. Conventions shared across its tools:",
-  "TOOL AVAILABILITY: tools/list is complete and fixed for this process's life — cache it. Its one-liners are not the full docs: call describe_tool {name} on an unfamiliar tool, or describe_tool {} for the grouped catalog. CDP_TOOL_PROFILE=core (or a group list) lists only those groups; unlisted tools stay callable by name.",
-  "TARGET SELECTOR (the `target` param, unless a tool says otherwise): 'active' (default = first page) | 'index:N' (0-based) | 'url:<substr>' | 'title:<substr>' | 'label:<name>' (exact, from the origin ledger or a live lease) | a 32-hex '<targetId>'. Four Chrome-only tools (evaluate_script, list_network_requests, get_network_request, list_console_messages) also accept 'worker:<substr>' to reach a service/shared worker — e.g. an MV3 extension's background worker (worker:<extension-id> or worker:background.js); an idle-evicted worker is started first (see each tool's `wake`).",
-  "LEASES (the `lease` param): claim_page, and new_page{claim:true}, mint an opaque token. Omit it for a tab THIS process already holds. It is required for a tab held by ANOTHER process, or one claimed explicitly. Under CDP_REQUIRE_LEASE the gate auto-acquires a lease for any tab this process drives — no token is surfaced, so pass `target`, not `lease` — while an explicit claim:true still demands its token on every later call. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all.",
+  "cdp-toolkit drives a real browser over CDP (or Firefox WebDriver-BiDi): pages, input, screenshots, snapshots, console, network, cookies, emulation, Lighthouse, traces, screencasts.",
+  "TOOLS: by default only 5 are listed (navigate_page, take_snapshot, click, fill, evaluate_script). ~45 more exist: find one with search_tools {query} (returns its schema; no query = catalog), run it with call_tool {name, arguments}. No tab yet? call_tool {name:'new_page'}. The listing is fixed for the process's life; CDP_TOOL_PROFILE=full lists everything.",
+  "TARGET SELECTOR (the `target` param, unless a tool says otherwise): 'active' (default = first page) | 'index:N' (0-based) | 'url:<substr>' | 'title:<substr>' | 'label:<name>' (exact, ledger or live lease) | a 32-hex '<targetId>' of any target type — an iframe id from list_pages{all:true} drives like a tab. Chrome tools also accept 'frame:<substr>' for OOPIF iframe targets. Four Chrome-only tools (evaluate_script, list_network_requests, get_network_request, list_console_messages) also accept 'worker:<substr>' to reach a service/shared worker (e.g. an MV3 background worker); an idle-evicted worker is started first (see `wake`).",
+  "LEASES (the `lease` param): claim_page, and new_page{claim:true}, mint an opaque token. Omit it for a tab THIS process already holds. It is required for a tab held by ANOTHER process, or one claimed explicitly. Under CDP_REQUIRE_LEASE the gate auto-acquires a lease for any tab this process drives — no token is surfaced, so pass `target`, not `lease` — while an explicit claim:true still demands its token on every later call.",
   "ORIGIN: list_pages and list_leases tag each tab's `origin` as 'agent' (this toolkit created it) or 'unknown' — never 'human', because the toolkit cannot prove a person opened a tab. An 'agent' tab stays findable after its creator releases the lease or dies."
 ].join(`
 
 `);
 var PROFILE = startupProfile();
+var META_TOOLS = new Set(["search_tools", "call_tool", "describe_tool"]);
+var SEARCH_DEFAULT_LIMIT = 8;
+var SEARCH_MAX_LIMIT = 20;
 function startupProfile() {
   try {
     return resolveProfile(process.env.CDP_TOOL_PROFILE);
@@ -11357,20 +11449,37 @@ function startupProfile() {
 }
 var LISTING = Object.freeze([
   {
-    name: "describe_tool",
-    description: "Full description and per-parameter docs for any cdp-toolkit tool by name, including tools not in tools/list (unlisted tools stay callable by name). Call it before using an unfamiliar tool: the live tools/list carries only terse one-liners. With no name it returns the grouped catalog of every tool the selected browser supports.",
+    name: "search_tools",
+    description: "Find a cdp-toolkit tool that is not in your tool list (cookies, network, console, screenshots, tabs, emulation, performance, recording, leases, downloads, …). Returns the best matches with full docs and inputSchema; run one with call_tool. With no query, returns the catalog of every tool by group.",
     inputSchema: {
       type: "object",
       properties: {
-        name: {
+        query: {
           type: "string",
-          description: "Tool name, e.g. take_screenshot. Omit it to get the catalog: every group, its tool names, and whether the group is in tools/list."
+          description: "Keywords or an exact tool name, e.g. 'screenshot', 'network requests', 'new_page'. Omit for the catalog."
+        },
+        limit: {
+          type: "integer",
+          description: `Max matches to return (default ${SEARCH_DEFAULT_LIMIT}, max ${SEARCH_MAX_LIMIT}).`
         }
       },
       additionalProperties: false
     }
   },
-  ...MANIFEST.filter((s) => AVAILABLE_NAMES.has(s.name) && PROFILE.groups.has(TOOL_GROUP[s.name])).map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema }))
+  {
+    name: "call_tool",
+    description: "Run any cdp-toolkit tool by name, including the ones not in your tool list. Look its arguments up with search_tools first. Behaves exactly like calling the tool directly (same leases, same errors).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Tool name from search_tools, e.g. new_page." },
+        arguments: { type: "object", description: "That tool's arguments, per its inputSchema.", additionalProperties: true }
+      },
+      required: ["name"],
+      additionalProperties: false
+    }
+  },
+  ...MANIFEST.filter((s) => AVAILABLE_NAMES.has(s.name) && isListed(PROFILE, s.name)).map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema }))
 ]);
 function renderCatalog() {
   const lines = [
@@ -11380,12 +11489,65 @@ function renderCatalog() {
     const shown = GROUP_TOOLS[g].filter((n) => AVAILABLE_NAMES.has(n));
     if (!shown.length)
       continue;
-    lines.push(`${PROFILE.groups.has(g) ? "[listed]" : "[hidden]"} ${g} (${shown.length}): ${shown.join(", ")}`);
+    const listed = shown.filter((n) => isListed(PROFILE, n));
+    const state = listed.length === shown.length ? "[listed]" : listed.length === 0 ? "[hidden]" : "[partly listed]";
+    lines.push(`${state} ${g} (${shown.length}): ${shown.join(", ")}`);
   }
-  lines.push("Unlisted tools are callable by name; describe_tool {name} documents any of them.");
+  lines.push("Run any tool with call_tool {name, arguments}; search_tools {query:<name>} returns its docs and inputSchema.");
   return lines.join(`
 `);
 }
+function tokenize(text) {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 1);
+}
+var MANIFEST_BY_NAME = new Map(MANIFEST.map((s) => [s.name, s]));
+function searchTools(query, rawLimit) {
+  const limit = typeof rawLimit === "number" && Number.isInteger(rawLimit) && rawLimit > 0 ? Math.min(rawLimit, SEARCH_MAX_LIMIT) : SEARCH_DEFAULT_LIMIT;
+  const q = query.trim().toLowerCase();
+  const describe = (name) => {
+    const spec = MANIFEST_BY_NAME.get(name);
+    return {
+      name,
+      group: TOOL_GROUP[name] ?? null,
+      listed: isListed(PROFILE, name),
+      description: TOOL_DOCS[name]?.description ?? spec.description,
+      inputSchema: spec.inputSchema
+    };
+  };
+  const candidates = MANIFEST.map((s) => s.name).filter((n) => AVAILABLE_NAMES.has(n));
+  let ranked;
+  if (candidates.includes(q)) {
+    ranked = [q];
+  } else {
+    const tokens = tokenize(q);
+    const scored = candidates.map((name, order) => {
+      const nameTokens = tokenize(name);
+      const group = TOOL_GROUP[name] ?? "";
+      const docs = `${MANIFEST_BY_NAME.get(name).description} ${TOOL_DOCS[name]?.description ?? ""}`.toLowerCase();
+      let score = 0;
+      for (const t of tokens) {
+        if (nameTokens.includes(t))
+          score += 5;
+        else if (name.includes(t))
+          score += 3;
+        if (group === t || group.includes(t))
+          score += 2;
+        if (docs.includes(t))
+          score += 1;
+      }
+      return { name, order, score };
+    });
+    ranked = scored.filter((s) => s.score > 0).sort((a, b) => b.score - a.score || a.order - b.order).map((s) => s.name);
+  }
+  const unavailable = AVAILABILITY.unavailable.find((u) => u.name === q);
+  return {
+    query,
+    total: ranked.length,
+    matches: ranked.slice(0, limit).map(describe),
+    ...unavailable ? { unavailable: `${q} is not available under --browser ${BROWSER} (needs: ${unavailable.missing.join(", ")})` } : {},
+    next: ranked.length ? "Run one with call_tool {name, arguments}." : "No match. Call search_tools with no query for the full catalog."
+  };
+}
 function renderToolDoc(toolName) {
   const doc = TOOL_DOCS[toolName];
   if (!doc)
@@ -11412,6 +11574,13 @@ function buildServer() {
   server.setRequestHandler("tools/call", async (request) => {
     const { name } = request.params;
     const args = request.params.arguments ?? {};
+    if (name === "search_tools") {
+      const { query, limit } = args;
+      if (typeof query !== "string" || query.trim() === "") {
+        return { content: [{ type: "text", text: renderCatalog() }] };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(searchTools(query, limit), null, 2) }] };
+    }
     if (name === "describe_tool") {
       const requested = args.name;
       if (typeof requested !== "string" || requested === "") {
@@ -11420,40 +11589,57 @@ function buildServer() {
       const known = Boolean(TOOL_DOCS[requested]);
       return { content: [{ type: "text", text: renderToolDoc(requested) }], isError: !known };
     }
-    if (!AVAILABLE_NAMES.has(name)) {
-      const gap = AVAILABILITY.unavailable.find((u) => u.name === name);
-      return {
-        content: [{ type: "text", text: `unknown tool: ${name}${gap ? ` (not available under --browser ${BROWSER}, needs: ${gap.missing.join(", ")})` : ""}` }],
-        isError: true
-      };
-    }
-    return withLeaseScope(leaseFromArgs(args), async () => {
-      if (BROWSER === "chrome") {
-        const fn = dispatch[name];
-        if (!fn)
-          return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
-        try {
-          const result = await fn(args);
-          return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
-        }
+    if (name === "call_tool") {
+      const inner = args;
+      if (typeof inner.name !== "string" || inner.name === "") {
+        return { content: [{ type: "text", text: "call_tool: `name` is required (find one with search_tools)" }], isError: true };
+      }
+      if (META_TOOLS.has(inner.name)) {
+        return { content: [{ type: "text", text: `call_tool: '${inner.name}' is a meta-tool; call it directly` }], isError: true };
+      }
+      const innerArgs = inner.arguments ?? {};
+      if (typeof innerArgs !== "object" || Array.isArray(innerArgs)) {
+        return { content: [{ type: "text", text: "call_tool: `arguments` must be an object" }], isError: true };
       }
-      const neutralFn = neutralDispatch[name];
-      if (!neutralFn)
+      return runTool(inner.name, innerArgs);
+    }
+    return runTool(name, args);
+  });
+  return server;
+}
+async function runTool(name, args) {
+  if (!AVAILABLE_NAMES.has(name)) {
+    const gap = AVAILABILITY.unavailable.find((u) => u.name === name);
+    return {
+      content: [{ type: "text", text: `unknown tool: ${name}${gap ? ` (not available under --browser ${BROWSER}, needs: ${gap.missing.join(", ")})` : ""}` }],
+      isError: true
+    };
+  }
+  return withLeaseScope(leaseFromArgs(args), async () => {
+    if (BROWSER === "chrome") {
+      const fn = dispatch[name];
+      if (!fn)
         return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
       try {
-        const session = await getOrCreateFirefoxSession({ endpoint: FIREFOX_ENDPOINT });
-        const result = await neutralFn(session.driver, args);
+        const result = await fn(args);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
       }
-    });
+    }
+    const neutralFn = neutralDispatch[name];
+    if (!neutralFn)
+      return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
+    try {
+      const session = await getOrCreateFirefoxSession({ endpoint: FIREFOX_ENDPOINT });
+      const result = await neutralFn(session.driver, args);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+    }
   });
-  return server;
 }
 async function run2(argv) {
   const serve = parseServeOptions(argv);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cdp-toolkit",
-  "version": "2.6.0",
-  "description": "A lightweight chrome-devtools-mcp alternative: an MCP server + CLI that drives the tabs you name, one target per call over one direct WebSocket, with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome over CDP and Firefox over WebDriver BiDi, with tools a backend can't run absent from tools/list rather than throwing mid-task. 48 tools including built-in network mocking, a cookie group, tab leases with human-activity detection, real HTML5 drag-and-drop, raw mouse/scroll dispatch, downloads, permission grants, and tab-to-video screen recording so several agents can drive one browser without stealing each other's tabs or a human's. No Puppeteer, no all-target fan-out.",
+  "version": "3.0.0",
+  "description": "A lightweight chrome-devtools-mcp alternative: an MCP server + CLI that drives the tabs you name, one target per call over one direct WebSocket, with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome over CDP and Firefox over WebDriver BiDi, with tools a backend can't run absent from tools/list rather than throwing mid-task. 48 tools (only 5 core tools listed by default, plus search_tools/call_tool to reach the rest) including built-in network mocking, a cookie group, tab leases with human-activity detection, real HTML5 drag-and-drop, raw mouse/scroll dispatch, downloads, permission grants, and tab-to-video screen recording so several agents can drive one browser without stealing each other's tabs or a human's. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -75,6 +75,7 @@
     "test": "bun test",
     "test:runtime": "bun test test/runtime-entry.test.ts",
     "smoke": "bun run ./test/smoke.ts",
+    "bench:wedge": "bun run scripts/wedge-bench.ts",
     "mock:smoke": "bun run ./test/mock-smoke.ts",
     "screencast:smoke": "bun run ./test/screencast-smoke.ts",
     "mcp:smoke": "bun run ./test/mcp-smoke.ts",
@@ -87,7 +88,8 @@
     "input:smoke": "bun run ./test/input-smoke.ts",
     "extension:smoke": "bun run ./test/extension-smoke.ts",
     "focus:smoke": "bun run ./test/focus-emulation-smoke.ts",
-    "extract:smoke": "bun run ./test/extract-smoke.ts"
+    "extract:smoke": "bun run ./test/extract-smoke.ts",
+    "gateway:smoke": "bun run ./test/gateway-smoke.ts"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",

package/src/bidi/driver.ts

@@ -46,6 +46,7 @@ import {
 import { assertLeaseOk, defaultLabel, isPidAlive } from "../leases.ts";
 import { resolveLiveLabel } from "../origins.ts";
 import { isWorkerSelector, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "../workers.ts";
+import { FRAME_SELECTOR_UNSUPPORTED_MESSAGE, isFrameSelector } from "../frames.ts";
 import { BEACON_FUNCTION_DECLARATION, BEACON_READ_EXPRESSION, BEACON_SOURCE, recordDispatch } from "../activity.ts";
 import { BidiConnection, BidiError, connectBidiSessionUrl } from "./client.ts";
 import {
@@ -845,6 +846,13 @@ async function pickContext(
     // "no context matching 'worker:abc'" that reads like a typo.
     throw driverError("unsupported", WORKER_SELECTOR_UNSUPPORTED_MESSAGE);
   }
+  if (isFrameSelector(selector)) {
+    // Capability-gated for the same reason as the worker: arm above. WebDriver
+    // BiDi has no iframe TARGET to resolve to — an iframe is a realm inside its
+    // tab's browsing context — so the honest error names the capability
+    // ('frame.targets', Chrome-only) rather than retrying or reading as a typo.
+    throw driverError("unsupported", FRAME_SELECTOR_UNSUPPORTED_MESSAGE);
+  }
   const exact = contexts.find((c) => c.context === selector);
   if (exact) return exact;
   throw driverError("no-such-target", `no context matching '${selector}'`);

package/src/cdp/driver.ts

@@ -652,7 +652,7 @@ const CDP_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
   "screenshot.fullPage", "screenshot.element", "screenshot.scale", "screenshot.renderSize", "screenshot.tile", "network.intercept",
   "snapshot.accessibilityTree", "input.insertTextAtomic", "locate.text", "locate.xpath",
   "capture.screencast", "input.raw", "input.html5Drag", "emulate.focus",
-  "browser.downloads", "browser.permissions", "worker.targets",
+  "browser.downloads", "browser.permissions", "worker.targets", "frame.targets",
 ]);
 /* ---------------------------------- PageDriver ---------------------------------- */
 class CdpPageDriver implements PageDriver {
@@ -820,10 +820,36 @@ class CdpPageDriver implements PageDriver {
     const { objectId } = await resolveElementLocator(this.conn, loc);
     return this.callFn(objectId, functionDeclaration, args, true);
   }
+  /**
+ * OOPIF MARKERS (issue #7 fix 1): which emitted snapshot nodes own an out-of-process iframe.
+ *
+ * Chrome's Accessibility.getFullAXTree includes the <iframe> ELEMENT's AX node (role "Iframe",
+ * with a backendDOMNodeId) but not the subtree of an out-of-process iframe (OOPIF): that subtree
+ * lives in a separate renderer/AX tree, so its contents are simply absent and a caller reading
+ * the snapshot has no signal that an entire interactable document ends at that line. Same-origin
+ * iframes ARE merged into the one response, so they need no marker — only process-isolated
+ * frames do, and process isolation is decided by Chrome, not by any origin heuristic here.
+ *
+ * Truth source: the browser's target list (`/json/list`) names every OOPIF as its own target of
+ * type "iframe", and an OOPIF's target id IS its frame id. `Page.getFrameTree` is deliberately
+ * NOT used here: on a page-level websocket attachment it omits out-of-process child frames
+ * (observed Chrome 153: same DOM with the <iframe>, frame tree with no childFrames), which is
+ * exactly the set this marker exists for. DOM.getFrameOwner maps each candidate frame id to the
+ * backendNodeId of the owning <iframe> element — the node snapshot() is about to emit; it throws
+ * for frame ids this page doesn't own, which is the filter.
+ *
+ * The marker rides the node's existing `extras` map ("frame" = frame/target id, "frameUrl" when
+ * the frame tree reported one) because SnapshotNode is owned by ../driver.ts and shared with the
+ * BiDi driver; renderSnapshotLine renders unknown extras keys quoted, which is the desired shape
+ * (`[frame="A1B2..."]`). Everything here is failure-soft by design: a snapshot must never fail
+ * because marker detection did, so any error returns an empty map and the snapshot degrades to
+ * exactly its pre-marker output.
+ */
   async snapshot(opts?: { interactiveOnly?: boolean }): Promise<SnapshotNode[]> {
     const interactiveOnly = opts?.interactiveOnly ?? false;
     await this.ensureDomain("Accessibility");
     const { nodes } = await this.conn.send<{ nodes: AxNode[] }>("Accessibility.getFullAXTree");
+    const oopifFrames = await this.detectOopifFrames();
     const byId = new Map<string, AxNode>();
     for (const n of nodes) byId.set(n.nodeId, n);
     const roots = nodes.filter((n) => !n.parentId || !byId.has(n.parentId));
@@ -837,11 +863,20 @@ class CdpPageDriver implements PageDriver {
     const walk = (node: AxNode, depth: number): void => {
       const role = axString(node.role);
       const name = axString(node.name);
-      const backendNodeId = node.backendDOMNodeId;
-      const emitted = !node.ignored && backendNodeId !== undefined && (interactiveOnly ? isInteractive(role) : !!(role || name));
+      const backendDOMNodeId = node.backendDOMNodeId;
+      const marker = backendDOMNodeId !== undefined ? oopifFrames.get(backendDOMNodeId) : undefined;
+      // interactiveOnly drops "Iframe" (not in INTERACTIVE_ROLES), but an iframe carrying an
+      // OOPIF marker is itself the accessibility boundary of an entire process, so it is
+      // emitted anyway: the default view must surface that the boundary exists. Everything
+      // else about the emit rule is unchanged, and the depth rule below is untouched.
+      const emitted = !node.ignored && backendDOMNodeId !== undefined && (interactiveOnly ? isInteractive(role) || marker !== undefined : !!(role || name));
       if (emitted) {
         const extras = axExtras(node);
-        out.push({ uid: encodeUid(backendNodeId as number), role: role ?? "generic", depth, ...(name ? { name } : {}), ...(Object.keys(extras).length ? { extras } : {}) });
+        if (marker) {
+          extras.frame = marker.frameId;
+          if (marker.frameUrl) extras.frameUrl = marker.frameUrl;
+        }
+        out.push({ uid: encodeUid(backendDOMNodeId as number), role: role ?? "generic", depth, ...(name ? { name } : {}), ...(Object.keys(extras).length ? { extras } : {}) });
       }
       const childDepth = emitted && !interactiveOnly ? depth + 1 : depth;
       for (const childId of node.childIds ?? []) {
@@ -852,6 +887,36 @@ class CdpPageDriver implements PageDriver {
     for (const root of roots) walk(root, 0);
     return out;
   }
+  /**
+   * The marker map behind snapshot()'s OOPIF annotations (see snapshot()'s OOPIF MARKERS block):
+   * backendNodeId of the owning <iframe> element -> { frameId (= CDP target id), frameUrl }.
+   * Failure-soft end to end: any error anywhere in the round-trip yields an EMPTY map, never a
+   * failed snapshot. DOM.getFrameOwner throws for the main frame, which is why only non-main
+   * frames are visited; ensureDomainSoft covers the DOM.enable it requires without making a
+   * failed enable break anything else (getFrameOwner would simply throw into the same catch).
+   */
+  private async detectOopifFrames(): Promise<Map<number, { frameId: string; frameUrl?: string }>> {
+    const markers = new Map<number, { frameId: string; frameUrl?: string }>();
+    try {
+      await this.ensureDomainSoft("DOM");
+      // Process-isolation truth, not an origin heuristic: every OOPIF has its own iframe-type
+      // CDP target whose id IS its frame id (listTargets is client.ts's /json/list). This page
+      // owns only some of them — DOM.getFrameOwner throws for any frame id the page doesn't own
+      // (notably iframe targets inside OTHER tabs), and that throw is the ownership filter.
+      const iframeTargets = (await listTargets()).filter((t) => t.type === "iframe");
+      for (const target of iframeTargets) {
+        const owner = await this.conn
+          .send<{ backendNodeId?: number }>("DOM.getFrameOwner", { frameId: target.id })
+          .catch(() => ({ backendNodeId: undefined }));
+        if (typeof owner.backendNodeId === "number") {
+          markers.set(owner.backendNodeId, { frameId: target.id, ...(target.url ? { frameUrl: target.url } : {}) });
+        }
+      }
+    } catch {
+      // Deliberately empty: see the doc comment. Markers are an annotation, not a guarantee.
+    }
+    return markers;
+  }
   async locate(loc: ElementLocator): Promise<DriverUid> {
     return encodeUid(await backendNodeIdOf(this.conn, loc));
   }