cdp-toolkit 2.6.0 → 3.0.0

package/src/client.ts

@@ -15,6 +15,14 @@ import {
   workerNeedle,
   WORKER_EMPTY_NEEDLE_MESSAGE,
 } from "./workers.ts";
+import {
+  frameAmbiguityMessage,
+  frameMissMessage,
+  frameNeedle,
+  isFrameSelector,
+  resolveFrameTargets,
+  FRAME_EMPTY_NEEDLE_MESSAGE,
+} from "./frames.ts";
 
 /** Base HTTP origin of the DevTools endpoint. Override with CDP_BASE. */
 export const BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
@@ -284,6 +292,20 @@ async function pickTarget(targets: Target[], selector: TargetSelector): Promise<
     if (matches.length === 1) return matches[0]!;
     throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers }));
   }
+  if (isFrameSelector(selector)) {
+    // Also resolved against the UNFILTERED listing: an out-of-process iframe is
+    // its own target (site isolation), but not a PAGE target, so `pages` never
+    // contains it. Unlike the worker arm, the returned hit deliberately still
+    // flows through resolveTarget's lease gate below — a bare iframe id does
+    // too today, and this arm is a way of NAMING that same target, not a new
+    // permission to bypass who holds the embedder tab's lease.
+    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));
+  }
   // bare id
   const byId = targets.find((t) => t.id === selector);
   if (!byId) throw new CdpError(`no target with id '${selector}'`);

package/src/driver.ts

@@ -153,7 +153,8 @@ export type Capability =
   | "emulate.focus" // fake page focus without moving the OS window (focus_emulation / click_focus_gated); Chrome only — BiDi's emulation module has no focus primitive
   | "browser.downloads" // capture a file download to a known path (wait_for_download); Chrome only
   | "browser.permissions" // grant/reset browser permissions for an origin (grant_permissions); Chrome only
-  | "worker.targets"; // address a service/shared worker as a target ("worker:<substr>"), incl. waking an evicted MV3 worker; Chrome only
+  | "worker.targets" // address a service/shared worker as a target ("worker:<substr>"), incl. waking an evicted MV3 worker; Chrome only
+  | "frame.targets"; // address an out-of-process (cross-origin) iframe as a target ("frame:<substr>"); Chrome only — same-site iframes are not targets at all
 
 /**
  * Tools whose availability depends on a capability. A tool absent from this

package/src/frames.ts

@@ -0,0 +1,169 @@
+/**
+ * The "frame:<url-substring>" arm of the TargetSelector grammar (issue #7).
+ *
+ * WHAT IT IS FOR. Chrome site isolation gives a CROSS-ORIGIN iframe its own
+ * process, and with it its own CDP target that shows up in /json/list with
+ * type "iframe" and its own webSocketDebuggerUrl. Until now the only way to
+ * name one was its 32-hex targetId, discovered by reading list_pages{all:true}
+ * output by eye. This arm names it by a substring of its url — `frame:ads.example.com`,
+ * `frame:player.html` — exactly the way `url:` names a tab.
+ *
+ * THE OOPIF FACT, which is what the miss message below exists to teach: only
+ * OUT-OF-PROCESS iframes appear as targets at all. A SAME-ORIGIN iframe runs
+ * inside its parent page's process and has no target, no id, no listing entry —
+ * no substring can ever select it, and a caller who does not know that goes
+ * hunting for a typo that is not there. This is the frame arm's counterpart of
+ * the MV3-eviction fact the worker messages teach (see workers.ts).
+ *
+ * WHY DATA, NEVER THROWS (the resolveLiveLabel precedent in origins.ts, and
+ * workers.ts's copy of this rule). The grammar has three independent resolver
+ * copies — `pickTarget` in client.ts, `pickPage` in shared-tools.ts,
+ * `pickContext` in bidi/driver.ts — each with its own error class (CdpError /
+ * SharedToolError / DriverError). A shared resolver that threw would force one
+ * class on all three, so this returns the facts and each caller raises its own
+ * error. What IS shared is the message TEXT below, because the teaching in it
+ * is the point of the feature and three hand-written variants of it would drift
+ * apart within one release.
+ *
+ * WHY THE ALL-TARGETS LISTING. An iframe is not a page target, so the page-only
+ * listing the other url:/title: arms resolve against never contains one. This
+ * arm reads the unfiltered listing, same as the worker: arm. That does NOT
+ * merge the id sets that reap and leases keep apart: see ReapInput.livePageIds's
+ * header. Unlike a worker, an iframe hit is NOT exempted from the lease gate in
+ * client.ts's resolveTarget — a bare iframe id goes through that gate today, and
+ * `frame:` is a way of NAMING the same target, not a new permission for it.
+ */
+
+/** Selector prefix owned by this arm. */
+export const FRAME_SELECTOR_PREFIX = "frame:";
+
+/**
+ * The page-only tools that REFUSE this arm, and the single source of truth for
+ * it: the page-only refusal message below is built from this list.
+ *
+ * WHY A REFUSAL LIST AND NOT workers.ts's WORKER_CAPABLE_TOOLS allowlist: the
+ * worker arm is resolved per-tool (evaluate_script and the three recorders route
+ * it through resolveWorkerSelectorFor), so which tools accept it is a finite,
+ * deliberate list. The frame arm instead lives in client.ts's pickTarget, the
+ * ONE resolver every Chrome tool's `target` argument already flows through, so
+ * every target-taking tool accepts it with no per-tool work — the finite,
+ * deliberate list is the four that must NOT (closing, selecting, releasing or
+ * claiming an iframe is meaningless; those act on the embedder TAB).
+ */
+export const FRAME_PAGE_ONLY_TOOLS = ["close_page", "select_page", "release_page", "claim_page"] as const;
+
+/**
+ * The CDP target type this arm resolves: "iframe". /json/list reports an
+ * out-of-process iframe under exactly this type (a same-origin one is absent
+ * entirely, which is the OOPIF fact the miss message teaches).
+ */
+export const FRAME_TARGET_TYPE = "iframe";
+
+/** The two fields every listing shape (CDP Target, PageInfo) already carries. */
+export interface FrameTargetLike {
+  id: string;
+  url: string;
+  type?: string;
+}
+
+export function isFrameSelector(selector: string | undefined): selector is string {
+  return typeof selector === "string" && selector.startsWith(FRAME_SELECTOR_PREFIX);
+}
+
+/** The substring half of "frame:<substring>". May be empty; callers reject that. */
+export function frameNeedle(selector: string): string {
+  return selector.slice(FRAME_SELECTOR_PREFIX.length);
+}
+
+export function isFrameTargetType(type: string | undefined): boolean {
+  return type === FRAME_TARGET_TYPE;
+}
+
+export interface FrameResolution<T> {
+  /** Out-of-process iframe targets whose url contains the needle. */
+  matches: T[];
+  /** Every live iframe target, for a miss message that lists the alternatives. */
+  liveFrames: T[];
+}
+
+/**
+ * Pure: split a target listing into "iframes matching the needle" and "all live
+ * iframes". An EMPTY needle matches nothing here rather than matching
+ * everything, because `"anything".includes("")` is true and a bare `frame:`
+ * would otherwise silently mean "whichever iframe happens to be first".
+ * Callers reject the empty needle outright with FRAME_EMPTY_NEEDLE_MESSAGE.
+ */
+export function resolveFrameTargets<T extends FrameTargetLike>(targets: readonly T[], needle: string): FrameResolution<T> {
+  const liveFrames = targets.filter((t) => isFrameTargetType(t.type));
+  return {
+    matches: needle === "" ? [] : liveFrames.filter((t) => t.url.includes(needle)),
+    liveFrames,
+  };
+}
+
+/* -------------------------------- shared message text -------------------------------- */
+
+export const FRAME_EMPTY_NEEDLE_MESSAGE =
+  "'frame:' needs a substring of the iframe's url, e.g. frame:ads.example.com or frame:player.html";
+
+/**
+ * The Firefox refusal. A PARAM-level gap, exactly like drag's mode:'html5' and
+ * the worker arm's WORKER_SELECTOR_UNSUPPORTED_MESSAGE: the target-taking tools
+ * stay in tools/list on Firefox because every tab selector still works there,
+ * and only this one arm is refused. Naming the reason matters — WebDriver BiDi
+ * has no iframe TARGET: iframes are realms inside a browsing context, and a
+ * context IS a tab, so there is nothing for a target selector to resolve to.
+ * This is a protocol-model gap, not an unimplemented to-do.
+ */
+export const 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.";
+
+/**
+ * Refusal from the page-only resolvers (close_page / select_page /
+ * release_page / claim_page): those act on the embedder TAB, and an iframe has
+ * no independent existence to close, select, release or claim. Because the arm
+ * is accepted by every OTHER target-taking tool (it resolves inside the shared
+ * pickTarget), the message names the refusing minority rather than an allowlist
+ * of the accepting majority.
+ */
+export const 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.";
+
+/** Ambiguity never resolves to a silent first match: name every candidate. */
+export function frameAmbiguityMessage(needle: string, matches: readonly FrameTargetLike[]): string {
+  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."
+  );
+}
+
+/**
+ * The miss message, and the whole reason this module owns its text. A miss
+ * here is usually NOT a typo, for one of two reasons the caller can act on:
+ *   - the iframe is SAME-ORIGIN: it runs inside its parent page's process, has
+ *     no target at all, and can never be selected by any substring. The fix is
+ *     to go through the parent page (evaluate_script on the page, then
+ *     contentDocument through the iframe element).
+ *   - the frame navigated away or was removed: an OOPIF target is as
+ *     short-lived as the document inside it, so the id seen a moment ago is
+ *     simply gone. The fix is to re-list.
+ */
+export function frameMissMessage(needle: string, liveFrames: readonly FrameTargetLike[]): string {
+  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."
+  );
+}

package/src/manifest.ts

@@ -35,7 +35,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "all": {
           "type": "boolean",
-          "description": "Include non-page targets."
+          "description": "Include non-page targets (workers, iframes)."
         },
         "probe": {
           "type": "boolean",

package/src/mcp.ts

@@ -43,7 +43,7 @@ import { disposeBrowserSession } from "./tools/browser-session.ts";
 import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, markLongLivedProcess, withLeaseScope } from "./leases.ts";
-import { resolveProfile, TOOL_GROUP, TOOL_GROUPS, GROUP_TOOLS } from "./toolGroups.ts";
+import { isListed, resolveProfile, TOOL_GROUP, TOOL_GROUPS, GROUP_TOOLS } from "./toolGroups.ts";
 import { TOOL_DOCS } from "./toolDocs.ts";
 import { VERSION } from "./version.ts";
 
@@ -156,10 +156,10 @@ function auditCoverage(): void {
 // payload without losing a single behavior. Kept under Claude Code's 2KB instructions
 // cap and front-loaded (grammar + leases before origin) so nothing critical is clipped.
 const 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("\n\n");
 
@@ -168,12 +168,17 @@ const INSTRUCTIONS = [
 // it (the 2026-07-28 revision requires the tool set not to change as a side effect of
 // other requests, which is exactly what the 2.0 browser_tools toggle did). Discovery is
 // the HOST's job per the MCP client best-practices: the client picks which of the listed
-// tools to put in front of the model. `describe_tool` is the inspect layer — one call
-// returns the full prose for any tool, listed or not — and CDP_TOOL_PROFILE is the only
-// filter, applied once at startup by whoever configures the server. A tool that the
-// profile hides is still callable by name; hiding only trims the listing's token cost.
+// tools to put in front of the model. CDP_TOOL_PROFILE is the only filter, applied once at
+// startup by whoever configures the server. 3.0 defaults it to `gateway` (5 tools) and adds
+// two STATIC meta-tools, search_tools (inspect) and call_tool (execute), so a model whose host
+// forwards only the listing can still reach every tool — without the listing ever changing.
 const PROFILE = startupProfile();
 
+/** Names handled at the MCP layer rather than dispatched to a browser tool. */
+const META_TOOLS = new Set(["search_tools", "call_tool", "describe_tool"]);
+const SEARCH_DEFAULT_LIMIT = 8;
+const SEARCH_MAX_LIMIT = 20;
+
 /** Read CDP_TOOL_PROFILE once; an unknown group name is a configuration error, not a warning. */
 function startupProfile() {
   try {
@@ -187,35 +192,53 @@ function startupProfile() {
 /**
  * The one and only tools/list payload, in manifest order (a stable order is a spec
  * SHOULD, and it keeps the response byte-identical across calls so caching is real):
- * describe_tool first, then every manifest tool the selected backend can run whose
- * group the profile advertises. Descriptions here are the compressed one-liners —
- * full prose is served on demand by describe_tool.
+ * the two meta-tools first, then every manifest tool the selected backend can run that
+ * the profile advertises. Descriptions here are the compressed one-liners — full prose
+ * is served on demand by search_tools.
  *
  * Frozen at runtime (the handler hands the SAME array to every caller); the cast back to
  * a mutable Tool[] is only because ListToolsResult declares `tools` mutable.
  */
 const LISTING: Tool[] = Object.freeze([
   {
-    name: "describe_tool",
+    name: "search_tools",
     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.",
+      "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,
     } as Tool["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,
+    } as Tool["inputSchema"],
+  },
   ...MANIFEST
-    .filter((s) => AVAILABLE_NAMES.has(s.name) && PROFILE.groups.has(TOOL_GROUP[s.name]!))
+    .filter((s) => AVAILABLE_NAMES.has(s.name) && isListed(PROFILE, s.name))
     .map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema as Tool["inputSchema"] })),
 ] satisfies Tool[]) as Tool[];
 
-/** describe_tool with no name: every group the backend supports, and whether it is listed. */
+/** search_tools with no query: every group the backend supports, and what of it is listed. */
 function renderCatalog(): string {
   const lines = [
     `cdp-toolkit ${VERSION} · browser=${BROWSER} · ${AVAILABILITY.available.length} tools available, ${LISTING.length} in tools/list (CDP_TOOL_PROFILE=${PROFILE.label})`,
@@ -223,12 +246,76 @@ function renderCatalog(): string {
   for (const g of TOOL_GROUPS) {
     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("\n");
 }
 
+/** Lowercased word tokens: 'list_network_requests' and 'Network requests' both split cleanly. */
+function tokenize(text: string): string[] {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 1);
+}
+
+const MANIFEST_BY_NAME = new Map(MANIFEST.map((s) => [s.name, s]));
+
+/**
+ * search_tools with a query: rank the backend's available tools against it. An exact tool
+ * name returns just that tool. Otherwise each query token scores against the tool's name
+ * (strongest), its group, and its full docs; ties keep manifest order. Capped, because an
+ * uncapped broad query would hand back the very 49-schema payload the gateway exists to avoid.
+ */
+function searchTools(query: string, rawLimit: unknown) {
+  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: string) => {
+    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: string[];
+  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.",
+  };
+}
+
 /** describe_tool body: full prose for one tool from the on-demand docs map. */
 function renderToolDoc(toolName: string): string {
   const doc = TOOL_DOCS[toolName];
@@ -273,9 +360,19 @@ export function buildServer(): Server {
     const { name } = request.params;
     const args = (request.params.arguments ?? {}) as unknown;
 
-    // describe_tool is handled at the MCP layer (it reads only static docs) and never
-    // enters the browser dispatch or a lease scope. With a name it documents one tool —
-    // listed or not; with no name it returns the grouped catalog.
+    // The meta-tools are handled at the MCP layer (they read only static docs) and never
+    // enter the browser dispatch or a lease scope.
+    if (name === "search_tools") {
+      const { query, limit } = args as { query?: unknown; limit?: unknown };
+      if (typeof query !== "string" || query.trim() === "") {
+        return { content: [{ type: "text" as const, text: renderCatalog() }] };
+      }
+      return { content: [{ type: "text" as const, text: JSON.stringify(searchTools(query, limit), null, 2) }] };
+    }
+
+    // describe_tool is the 2.x inspect tool: no longer listed (search_tools {query:<name>}
+    // replaces it), still answered so 2.x callers keep working. With a name it documents
+    // one tool — listed or not; with no name it returns the grouped catalog.
     if (name === "describe_tool") {
       const requested = (args as { name?: unknown }).name;
       if (typeof requested !== "string" || requested === "") {
@@ -285,48 +382,73 @@ export function buildServer(): Server {
       return { content: [{ type: "text" as const, text: renderToolDoc(requested) }], isError: !known };
     }
 
-    if (!AVAILABLE_NAMES.has(name)) {
-      const gap = AVAILABILITY.unavailable.find((u) => u.name === name);
-      return {
-        content: [{ type: "text" as const, text: `unknown tool: ${name}${gap ? ` (not available under --browser ${BROWSER}, needs: ${gap.missing.join(", ")})` : ""}` }],
-        isError: true,
-      };
+    // call_tool unwraps to the inner tool and re-enters the SAME dispatch below, so the
+    // availability check, the lease scope (read off the INNER arguments) and the error
+    // shapes are identical to calling the tool directly. It exists because a model can
+    // only invoke tools its host put in front of it — an unlisted tool is callable by name
+    // over the wire, but not by a model whose host only forwards tools/list.
+    if (name === "call_tool") {
+      const inner = args as { name?: unknown; arguments?: unknown };
+      if (typeof inner.name !== "string" || inner.name === "") {
+        return { content: [{ type: "text" as const, text: "call_tool: `name` is required (find one with search_tools)" }], isError: true };
+      }
+      if (META_TOOLS.has(inner.name)) {
+        return { content: [{ type: "text" as const, 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" as const, text: "call_tool: `arguments` must be an object" }], isError: true };
+      }
+      return runTool(inner.name, innerArgs);
     }
 
-    // ONE lease scope per dispatch, wrapping BOTH backend branches. This is the
-    // reason no tool takes a lease parameter: the token rides the async context
-    // down to whichever resolution path the tool eventually reaches, so a tool
-    // added tomorrow is covered with no action from whoever writes it. Reading
-    // 'lease' off args here is the only place the MCP layer knows the key exists.
-    return withLeaseScope(leaseFromArgs(args), async () => {
-      if (BROWSER === "chrome") {
-        const fn = dispatch[name];
-        if (!fn) return { content: [{ type: "text" as const, text: `unknown tool: ${name}` }], isError: true };
-        try {
-          const result = await fn(args);
-          return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
-        }
-      }
+    return runTool(name, args);
+  });
+
+  return server;
+}
 
-      // Firefox: one BiDi session memoized for the life of this server process (lifetime "session",
-      // ADR-001); launched lazily on the first Firefox tool call, torn down on shutdown below.
-      const neutralFn = neutralDispatch[name];
-      if (!neutralFn) return { content: [{ type: "text" as const, text: `unknown tool: ${name}` }], isError: true };
+/** Dispatch one browser tool by name: the path both a direct call and call_tool take. */
+async function runTool(name: string, args: unknown) {
+  if (!AVAILABLE_NAMES.has(name)) {
+    const gap = AVAILABILITY.unavailable.find((u) => u.name === name);
+    return {
+      content: [{ type: "text" as const, text: `unknown tool: ${name}${gap ? ` (not available under --browser ${BROWSER}, needs: ${gap.missing.join(", ")})` : ""}` }],
+      isError: true,
+    };
+  }
+
+  // ONE lease scope per dispatch, wrapping BOTH backend branches. This is the
+  // reason no tool takes a lease parameter: the token rides the async context
+  // down to whichever resolution path the tool eventually reaches, so a tool
+  // added tomorrow is covered with no action from whoever writes it. Reading
+  // 'lease' off args here is the only place the MCP layer knows the key exists.
+  return withLeaseScope(leaseFromArgs(args), async () => {
+    if (BROWSER === "chrome") {
+      const fn = dispatch[name];
+      if (!fn) return { content: [{ type: "text" as const, 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" as const, text: JSON.stringify(result, null, 2) }] };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
       }
-    });
-  });
+    }
 
-  return server;
+    // Firefox: one BiDi session memoized for the life of this server process (lifetime "session",
+    // ADR-001); launched lazily on the first Firefox tool call, torn down on shutdown below.
+    const neutralFn = neutralDispatch[name];
+    if (!neutralFn) return { content: [{ type: "text" as const, 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" as const, text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
+    }
+  });
 }
 
 /**

package/src/shared-tools.ts

@@ -48,6 +48,7 @@ import {
 import { installBeacon, probeRendererActivity, rendererProbeSupported } from "./activity.ts";
 import { newTrackedPage, originIndex, resolveLiveLabel, type PageOrigin } from "./origins.ts";
 import { isWorkerSelector, WORKER_SELECTOR_PAGE_ONLY_MESSAGE, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "./workers.ts";
+import { FRAME_SELECTOR_PAGE_ONLY_MESSAGE, FRAME_SELECTOR_UNSUPPORTED_MESSAGE, isFrameSelector } from "./frames.ts";
 import { reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
 
 const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
@@ -150,6 +151,18 @@ export async function pickPage(driver: BrowserDriver, pages: PageInfo[], selecto
       backendOf(driver) === "firefox" ? WORKER_SELECTOR_UNSUPPORTED_MESSAGE : WORKER_SELECTOR_PAGE_ONLY_MESSAGE,
     );
   }
+  if (isFrameSelector(selector)) {
+    // Same contract as the worker: arm above, same reason. Every caller of
+    // pickPage (close_page / select_page / release_page via resolvePage, and
+    // claim_page's takeover) acts on a TAB; an out-of-process iframe has no
+    // independent existence to close, select, release or claim. Refusing with
+    // the reason beats the bare-id fall-through's "no target with id
+    // 'frame:foo'", which reads as a typo. The arm itself lives in client.ts's
+    // pickTarget and every other target-taking tool accepts it.
+    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;
   const all = await driver.listPages({ all: true });

package/src/toolDocs.ts

@@ -3,10 +3,10 @@ export type ToolDoc = { readonly description: string; readonly params: Record<st
 
 export const TOOL_DOCS: Record<string, ToolDoc> = {
   "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)."
     }
   },
@@ -107,7 +107,7 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
     }
   },
   "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.",