cdp-toolkit 2.5.1 → 2.7.0

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

@@ -1,14 +1,20 @@
 #!/usr/bin/env bun
 /**
- * cdp-toolkit MCP server (stdio).
+ * cdp-toolkit MCP server (stdio by default, streamable-http on request).
  *
  * Exposes the toolkit's raw-CDP tools to any MCP client (Claude Code, etc.) over
- * the standard stdio transport. It does NOT connect to Chrome at startup: each
- * tool call lazily opens a single-target CDP connection (with its own timeout),
- * so the server loads cleanly even when Chrome isn't running; individual calls
- * then fail with a clear error if the browser is unreachable.
+ * the standard stdio transport, or — with `--transport streamable-http` — over
+ * an HTTP/SSE listener served by Bun. It does NOT connect to Chrome at startup:
+ * each tool call lazily opens a single-target CDP connection (with its own
+ * timeout), so the server loads cleanly even when Chrome isn't running;
+ * individual calls then fail with a clear error if the browser is unreachable.
+ *
+ * Importing this module is side-effect-free: the server starts only when the
+ * file is the directly executed entry (bin invocation or `bun run src/mcp.ts`),
+ * never when imported (see isDirectRun below).
  *
  * Launch: `bunx -y cdp-toolkit`  (or `bun run src/mcp.ts` from a checkout)
+ *   HTTP:  `bun run src/mcp.ts --transport streamable-http [--port 3000] [--host 127.0.0.1]`
  * Config:  CDP_BASE (default http://127.0.0.1:9222), CDP_TIMEOUT_MS, CDP_ARTIFACT_DIR,
  *          CDP_TOOL_PROFILE (`full` — the default — advertises every group; `core` advertises
  *          just the 12 everyday tools; or a comma-separated group list, e.g. `core,network`.
@@ -21,6 +27,15 @@
 import { Server } from "@modelcontextprotocol/server";
 import type { Tool } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import {
+  createMcpHandler,
+  hostHeaderValidationResponse,
+  localhostAllowedHostnames,
+  localhostAllowedOrigins,
+  originValidationResponse,
+} from "@modelcontextprotocol/server";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { TOOLS, TOOL_NAMES, BASE } from "./index.ts";
 import { MANIFEST } from "./manifest.ts";
 import { resolveBackend, getOrCreateFirefoxSession, disposeFirefoxSession } from "./backend.ts";
@@ -32,6 +47,84 @@ import { resolveProfile, TOOL_GROUP, TOOL_GROUPS, GROUP_TOOLS } from "./toolGrou
 import { TOOL_DOCS } from "./toolDocs.ts";
 import { VERSION } from "./version.ts";
 
+// Bun.serve is the HTTP transport's listener: a Bun-only global, typed here (not via bun-types,
+// which CONTRACT.md keeps out of the dependency set) in the narrow shape this file uses. The code
+// below never touches it unless --transport streamable-http was requested, and checks
+// `typeof Bun === "undefined"` first so running under plain node fails with a clear message
+// instead of a ReferenceError. The declaration emits nothing — at runtime the identifier resolves
+// to the real global when one exists.
+declare const Bun: {
+  serve(opts: {
+    port: number;
+    hostname: string;
+    fetch(req: Request): Promise<Response> | Response;
+  }): { stop(): void; port: number };
+};
+
+/**
+ * True when this module is the process's entry script — the ONLY condition under which the
+ * server starts. Works under both node and bun, ESM included: compare this module's real path
+ * with the realpath of argv[1]. realpathSync resolves the bunx/npm bin symlink (argv[1] is the
+ * symlink, the module URL is its target) and any /tmp-style symlinked directory; when argv[1] is
+ * absent (e.g. `node -e`/REPL importing this file) the answer is simply "not direct". A plain
+ * `import(".../mcp.js")` from another module leaves argv[1] pointing at that other entry, so the
+ * import stays silent.
+ */
+function isDirectRun(): boolean {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return fileURLToPath(import.meta.url) === realpathSync(entry);
+  } catch {
+    // argv[1] may not exist as a file (eval strings, wrappers); never treat that as direct.
+    return false;
+  }
+}
+
+/** What --transport/--port/--host asked for. stdio is the default and stays byte-for-byte unchanged. */
+interface ServeOptions {
+  transport: "stdio" | "streamable-http";
+  port: number;
+  host: string;
+}
+
+/**
+ * Parse the serving flags from the same argv resolveBackend reads (it scans only --browser and
+ * --connect, so these extra tokens were already invisible to it). An unknown --transport value or
+ * a non-port --port is a hard configuration error, mirroring resolveBackend's loud failures.
+ */
+function parseServeOptions(argv: readonly string[]): ServeOptions {
+  const out: ServeOptions = { transport: "stdio", port: 3000, host: "127.0.0.1" };
+  const transportIdx = argv.indexOf("--transport");
+  if (transportIdx !== -1) {
+    const value = argv[transportIdx + 1];
+    if (value !== "stdio" && value !== "streamable-http") {
+      throw new Error(`unknown --transport '${value ?? ""}': expected 'stdio' or 'streamable-http'`);
+    }
+    out.transport = value;
+  }
+  const portIdx = argv.indexOf("--port");
+  if (portIdx !== -1) {
+    const raw = argv[portIdx + 1];
+    const port = Number(raw);
+    // 0 is valid HERE (unlike backend.ts's dial-out endpoints): for a listener it means "let the
+    // OS pick a free port", and the resolved port is then announced on stderr (see run()).
+    if (raw === undefined || !/^\d+$/.test(raw) || port < 0 || port > 65_535) {
+      throw new Error(`invalid --port '${raw ?? ""}': expected an integer 0-65535`);
+    }
+    out.port = port;
+  }
+  const hostIdx = argv.indexOf("--host");
+  if (hostIdx !== -1) {
+    const raw = argv[hostIdx + 1];
+    if (raw === undefined || raw === "") {
+      throw new Error(`invalid --host '${raw ?? ""}': expected a hostname or address`);
+    }
+    out.host = raw;
+  }
+  return out;
+}
+
 // Backend + (Firefox only) attach endpoint are read once at startup (MCP has no per-call notion
 // of backend): --browser flag / CDP_BROWSER env, else "chrome" (zero behavior change for existing
 // users/configs); --connect flag / CDP_FIREFOX_ENDPOINT env selects Firefox ATTACH mode and
@@ -65,8 +158,8 @@ function auditCoverage(): void {
 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.",
+  "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");
 
@@ -163,7 +256,7 @@ const LIST_CACHE_HINT = { ttlMs: 3_600_000, cacheScope: "public" } as const;
  * our manifest is plain JSON Schema (src/manifest.ts). McpServer also cannot express
  * "hidden tools remain callable by name", which is the whole point of CDP_TOOL_PROFILE.
  */
-function buildServer(): Server {
+export function buildServer(): Server {
   const server = new Server(
     { name: "cdp-toolkit", version: VERSION },
     {
@@ -236,47 +329,105 @@ function buildServer(): Server {
   return server;
 }
 
-auditCoverage();
-// This process is the long-lived MCP server, which is what makes strict mode
-// (CDP_REQUIRE_LEASE) safe to honor here and unsafe in cli.ts. See requireLease.
-markLongLivedProcess();
+/**
+ * Start serving: stdio (the default) or the streamable-http listener. Only ever called from the
+ * isDirectRun guard below — importing this module must stay silent.
+ */
+async function run(argv: string[]): Promise<void> {
+  const serve = parseServeOptions(argv);
+  auditCoverage();
+  // This process is the long-lived MCP server, which is what makes strict mode
+  // (CDP_REQUIRE_LEASE) safe to honor here and unsafe in cli.ts. See requireLease.
+  markLongLivedProcess();
 
-// serveStdio owns the era decision for the connection: a modern opening (server/discover
-// with the per-request _meta envelope) pins a 2026-07-28 instance, a 2025-era `initialize`
-// pins a legacy one. legacy:'serve' (the default) is deliberate — 2025-era clients keep the
-// initialize handshake they expect, so this upgrade is invisible to them.
-const handle = serveStdio(
-  ({ era }) => {
-    console.error(`[cdp-toolkit] connection pinned to the ${era} protocol era`);
-    return buildServer();
-  },
-  { onerror: (err) => console.error(`[cdp-toolkit] stdio: ${err.message}`) },
-);
-console.error(
-  `[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}${FIREFOX_ENDPOINT ? ` (attach ${FIREFOX_ENDPOINT})` : ""}, ${AVAILABILITY.available.length} tools available, ${LISTING.length} listed (CDP_TOOL_PROFILE=${PROFILE.label}), CDP_BASE=${BASE}`,
-);
+  // Per-transport state the shutdown path closes (only one is ever set).
+  let stdioHandle: Awaited<ReturnType<typeof serveStdio>> | undefined;
+  let httpHandler: ReturnType<typeof createMcpHandler> | undefined;
+  let listener: { stop(): void; port: number } | undefined;
+
+  // LAUNCH-mode Firefox owns a real OS process (see bidi/launch.ts): it must be reaped on every
+  // shutdown path, not just a clean exit. ATTACH-mode Firefox (CDP_FIREFOX_ENDPOINT / --connect)
+  // owns no process here — disposeFirefoxSession() below only ends its BiDi session (freeing
+  // Firefox's single session slot) and closes the socket, leaving the user's browser running.
+  // SIGINT/SIGTERM cover ctrl-C and a supervising client killing the server; in stdio mode the
+  // stdin 'close' event covers the normal MCP shutdown (the client closes the pipe). All are
+  // idempotent through disposeFirefoxSession(), and a no-op entirely when Firefox was never
+  // launched/attached.
+  let shuttingDown = false;
+  async function shutdown(): Promise<void> {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    await disposeFirefoxSession();
+    // The standing browser-endpoint connection behind wait_for_download / grant_permissions (1.8.0
+    // Track P3). Unlike Firefox it owns no OS process, so process.exit would collect it anyway; it is
+    // closed explicitly so shutdown does not depend on that, and is a no-op when neither tool ran.
+    await disposeBrowserSession();
+    // Close the active transport last, so a tool call still in flight over it cannot outlive the
+    // browser resources it was driving. For http this also stops accepting new connections.
+    if (stdioHandle) await stdioHandle.close().catch(() => undefined);
+    if (httpHandler) await httpHandler.close().catch(() => undefined);
+    if (listener) listener.stop();
+    process.exit(0);
+  }
+  process.on("SIGINT", () => void shutdown());
+  process.on("SIGTERM", () => void shutdown());
 
-// LAUNCH-mode Firefox owns a real OS process (see bidi/launch.ts): it must be reaped on every
-// shutdown path, not just a clean exit. ATTACH-mode Firefox (CDP_FIREFOX_ENDPOINT / --connect)
-// owns no process here — disposeFirefoxSession() below only ends its BiDi session (freeing
-// Firefox's single session slot) and closes the socket, leaving the user's browser running.
-// SIGINT/SIGTERM cover ctrl-C and a supervising client killing the server; stdin 'close' covers
-// the normal MCP shutdown (the client closes the stdio pipe). All three are idempotent through
-// disposeFirefoxSession(), and a no-op entirely when Firefox was never launched/attached.
-let shuttingDown = false;
-async function shutdown(): Promise<void> {
-  if (shuttingDown) return;
-  shuttingDown = true;
-  await disposeFirefoxSession();
-  // The standing browser-endpoint connection behind wait_for_download / grant_permissions (1.8.0
-  // Track P3). Unlike Firefox it owns no OS process, so process.exit would collect it anyway; it is
-  // closed explicitly so shutdown does not depend on that, and is a no-op when neither tool ran.
-  await disposeBrowserSession();
-  // Close the stdio connection (pinned instance + transport) last, so a tool call still
-  // in flight over it cannot outlive the browser resources it was driving.
-  await handle.close().catch(() => undefined);
-  process.exit(0);
+  if (serve.transport === "stdio") {
+    // serveStdio owns the era decision for the connection: a modern opening (server/discover
+    // with the per-request _meta envelope) pins a 2026-07-28 instance, a 2025-era `initialize`
+    // pins a legacy one. legacy:'serve' (the default) is deliberate — 2025-era clients keep the
+    // initialize handshake they expect, so this upgrade is invisible to them.
+    stdioHandle = serveStdio(
+      ({ era }) => {
+        console.error(`[cdp-toolkit] connection pinned to the ${era} protocol era`);
+        return buildServer();
+      },
+      { onerror: (err) => console.error(`[cdp-toolkit] stdio: ${err.message}`) },
+    );
+    process.stdin.on("close", () => void shutdown());
+    console.error(
+      `[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}${FIREFOX_ENDPOINT ? ` (attach ${FIREFOX_ENDPOINT})` : ""}, ${AVAILABILITY.available.length} tools available, ${LISTING.length} listed (CDP_TOOL_PROFILE=${PROFILE.label}), CDP_BASE=${BASE}`,
+    );
+    return;
+  }
+
+  // streamable-http: Bun.serve + the SDK's web-standard handler. DNS-rebinding protection comes
+  // from the SDK's host/origin validators composed in front (each returns an error Response for a
+  // disallowed request, undefined to fall through); the localhost allowlists match the default
+  // loopback bind. Everything diagnostic goes to stderr — stdout stays the stdio JSON-RPC channel
+  // only, and even here it must carry nothing (an http client never reads it).
+  if (typeof Bun === "undefined") {
+    console.error(
+      "[cdp-toolkit] --transport streamable-http needs Bun's HTTP listener (Bun.serve). Re-run with bun, or use the default stdio transport.",
+    );
+    process.exit(1);
+  }
+  httpHandler = createMcpHandler(
+    ({ era }) => {
+      console.error(`[cdp-toolkit] connection pinned to the ${era} protocol era`);
+      return buildServer();
+    },
+    { onerror: (err) => console.error(`[cdp-toolkit] http: ${err.message}`) },
+  );
+  listener = Bun.serve({
+    port: serve.port,
+    hostname: serve.host,
+    fetch: (req) =>
+      hostHeaderValidationResponse(req, localhostAllowedHostnames()) ??
+      originValidationResponse(req, localhostAllowedOrigins()) ??
+      httpHandler!.fetch(req),
+  });
+  // The resolved port is announced as a bare `port N` token BEFORE the URL text, so a stderr
+  // scanner finds the real listening port first (matters under --port 0, where N is the
+  // OS-assigned one and the only place it is knowable).
+  console.error(
+    `[cdp-toolkit] MCP server v${VERSION} listening on streamable-http port ${listener.port} (http://${serve.host}:${listener.port}/), browser=${BROWSER}${FIREFOX_ENDPOINT ? ` (attach ${FIREFOX_ENDPOINT})` : ""}, ${AVAILABILITY.available.length} tools available, ${LISTING.length} listed (CDP_TOOL_PROFILE=${PROFILE.label}), CDP_BASE=${BASE}`,
+  );
+}
+
+if (isDirectRun()) {
+  run(process.argv.slice(2)).catch((err: unknown) => {
+    console.error(`[cdp-toolkit] ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  });
 }
-process.on("SIGINT", () => void shutdown());
-process.on("SIGTERM", () => void shutdown());
-process.stdin.on("close", () => void shutdown());

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.",

package/src/types.ts

@@ -63,6 +63,19 @@ export interface CdpEvent<P = Record<string, unknown>> {
  *     listing, because a worker is not a page target — and a worker that is
  *     idle-evicted is in no listing at all, which is what `wake` exists for.
  *     See src/workers.ts and src/cdp/workers.ts.
+ *   - "frame:<substring>"    -> the out-of-process (cross-origin) IFRAME target
+ *     whose url contains the substring (site isolation gives an OOPIF its own
+ *     process and its own target, type "iframe"). Chrome-only, like "worker:",
+ *     but accepted by EVERY target-taking tool except the four page-only ones
+ *     (close/select/release/claim act on the embedder tab): the arm lives in
+ *     pickTarget itself, the one resolver every Chrome tool's target flows
+ *     through, so no per-tool wiring was needed or added. Reads the UNFILTERED
+ *     listing; a SAME-ORIGIN iframe is not a target at all (it runs inside its
+ *     parent page) and can only be reached through the parent. Refused with a
+ *     capability error on Firefox (no iframe targets exist in BiDi's context
+ *     model) and by the page-only resolvers. See src/frames.ts. A bare iframe
+ *     targetId from list_pages{all:true} also still resolves via the bare-id
+ *     arm below.
  */
 export type TargetSelector = string | undefined;
 

package/src/version.ts

@@ -6,4 +6,4 @@
  * ready line; keeping it in its own module means a release bump touches one
  * line here plus package.json, not a const buried in the server.
  */
-export const VERSION = "2.5.1";
+export const VERSION = "2.7.0";