cdp-toolkit 2.2.0 → 2.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cdp-toolkit",
-  "version": "2.2.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. 45 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": "2.5.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.",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -84,7 +84,9 @@
     "lease:smoke": "bun run ./test/lease-smoke.ts",
     "staleness:smoke": "bun run ./test/staleness-smoke.ts",
     "input:smoke": "bun run ./test/input-smoke.ts",
-    "extension:smoke": "bun run ./test/extension-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"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",

package/src/cdp/driver.ts

@@ -651,7 +651,7 @@ const CDP_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
   "emulate.mediaFeatures", "emulate.deviceMetrics", "emulate.networkConditions",
   "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",
+  "capture.screencast", "input.raw", "input.html5Drag", "emulate.focus",
   "browser.downloads", "browser.permissions", "worker.targets",
 ]);
 /* ---------------------------------- PageDriver ---------------------------------- */

package/src/driver.ts

@@ -150,6 +150,7 @@ export type Capability =
   | "locate.xpath" // find a node by xpath
   | "input.raw" // raw single mouse-event dispatch (dispatch_mouse's move/down/up primitive); Chrome only
   | "input.html5Drag" // real HTML5 drag events (drag's mode:"html5"); Chrome only, see PageDriver.drag
+  | "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
@@ -172,6 +173,8 @@ export const REQUIRED_CAPABILITIES: Partial<Record<ToolName, readonly Capability
   list_mocks: ["network.intercept"],
   clear_mocks: ["network.intercept"],
   dispatch_mouse: ["input.raw"],
+  focus_emulation: ["emulate.focus"],
+  click_focus_gated: ["emulate.focus"],
   wait_for_download: ["browser.downloads"],
   grant_permissions: ["browser.permissions"],
 } as const;

package/src/firefox-tools.ts

@@ -1,17 +1,20 @@
 /**
  * The complete Firefox tool registry: the 23 tools shared with Chrome (src/shared-tools.ts), the
- * 7 Firefox-only console/network/mock tools (src/bidi-tools.ts), and the 3 lease tools
- * (src/leases-tools.ts), which are backend-neutral by construction. This is what src/neutral.ts
- * used to be; it now composes three files instead of reimplementing everything in one.
+ * 7 Firefox-only console/network/mock tools (src/bidi-tools.ts), the 3 lease tools
+ * (src/leases-tools.ts), and extract_page (src/tools/extract.ts), which is backend-neutral by
+ * construction (its page work runs entirely through Driver.evaluate). This is what src/neutral.ts
+ * used to be; it now composes four files instead of reimplementing everything in one.
  */
 import type { BrowserDriver } from "./driver.ts";
 import type { ToolName } from "./index.ts";
 import { SHARED_TOOLS } from "./shared-tools.ts";
 import { BIDI_ONLY_TOOLS } from "./bidi-tools.ts";
 import { LEASE_TOOLS } from "./leases-tools.ts";
+import { extractPage } from "./tools/extract.ts";
 
 export const FIREFOX_TOOLS: Partial<Record<ToolName, (driver: BrowserDriver, args: never) => Promise<unknown>>> = {
   ...SHARED_TOOLS,
   ...BIDI_ONLY_TOOLS,
   ...LEASE_TOOLS,
+  extract_page: extractPage,
 };

package/src/index.ts

@@ -4,7 +4,7 @@
  * Two exports:
  *   1. `TOOLS` : the registry mapping every chrome-devtools-mcp tool name
  *      (snake_case string, all 29 of them) plus the toolkit's own superset
- *      tools, 45 entries in all, to its raw-CDP implementation function. The
+ *      tools, 48 entries in all, to its raw-CDP implementation function. The
  *      CLI and any embedder dispatch through this single table.
  *   2. The client primitives, re-exported so consumers can build their own
  *      flows on the same connection/timeout machinery the tools use.
@@ -43,9 +43,13 @@ import { lighthouseAudit } from "./tools/lighthouse.ts";
 import { mockRequest, listMocks, clearMocks } from "./tools/network_mock.ts";
 // --- raw mouse dispatch (Input.dispatchMouseEvent, one event per call) : chrome-only, capability "input.raw" ---
 import { dispatchMouse } from "./tools/dispatch-mouse.ts";
+// --- focus emulation + focus-gated click (Emulation.setFocusEmulationEnabled) : chrome-only, capability "emulate.focus" ---
+import { focusEmulation, clickFocusGated } from "./tools/focus-emulation.ts";
 // --- downloads + permissions (browser-endpoint state on a standing connection) : chrome-only, 1.8.0 Track P3 ---
 import { waitForDownload } from "./tools/downloads.ts";
 import { grantPermissions } from "./tools/permissions.ts";
+// --- structured extraction (cleaned page HTML -> OpenAI-compatible endpoint, both backends) ---
+import { extractPage } from "./tools/extract.ts";
 
 /** A toolkit tool: a single typed-args function returning JSON-serializable data. */
 export type ToolFn = (args: never) => Promise<unknown>;
@@ -81,8 +85,8 @@ function onCdp<A>(fn: (driver: ReturnType<typeof createCdpDriver>, args: A) => P
  * named path, and `grant_permissions`, which answers permission prompts for an origin; both
  * chrome-only and both driven from a standing browser-endpoint connection, see
  * tools/browser-session.ts).
- * 29 + 1 + 3 + 3 + 3 + 2 + 2 + 2 = 45 entries total. Listed explicitly so the mapping is auditable at a glance and
- * the CLI can `--list` it.
+ * 29 + 1 + 3 + 3 + 3 + 2 + 2 + 2 + 1 (extract_page) + 2 (focus pair) = 48 entries total. Listed explicitly so the mapping is auditable at a glance and
+ *  the CLI can `--list` it.
  *
  * 20 of the 29 MCP-parity tools (pages/navigation/evaluate/snapshot/interaction/
  * screenshot+emulation/dialogs) now route through shared-tools.ts's single Driver-based
@@ -145,12 +149,21 @@ export const TOOLS = {
   clear_mocks: clearMocks,
   // raw mouse dispatch (1) : 1.8.0 Track P1 toolkit addition, chrome-only (capability "input.raw")
   dispatch_mouse: dispatchMouse,
+  // focus emulation (2) : fake page focus without stealing OS focus; trusted click on a focus-gated
+  // button (e.g. Claude Code OAuth Authorize). chrome-only (capability "emulate.focus")
+  focus_emulation: focusEmulation,
+  click_focus_gated: clickFocusGated,
   // downloads + permissions (2) : 1.8.0 Track P3 toolkit additions, chrome-only (capabilities
   // "browser.downloads" / "browser.permissions"). Both drive browser-endpoint state that Chrome
   // reverts when the issuing client disconnects, so both run on tools/browser-session.ts's standing
   // connection rather than a per-call socket : see that module's header for the measurements.
   wait_for_download: waitForDownload,
   grant_permissions: grantPermissions,
+  // structured extraction (1) : toolkit addition, both backends — a page's cleaned HTML
+  // POSTed to an OpenAI-compatible /chat/completions endpoint (default: loopback
+  // llm-ferry) with the caller's JSON Schema as a strict response_format, returning
+  // schema-conformant JSON + token usage. API key is env-only (CDP_EXTRACT_API_KEY).
+  extract_page: onCdp(extractPage),
   // tab leases (3) : opt-in ownership so many agents can share one browser
   claim_page: onCdp(LEASE_TOOLS.claim_page),
   release_page: onCdp(LEASE_TOOLS.release_page),

package/src/manifest.ts

@@ -674,6 +674,70 @@ export const MANIFEST: ToolSpec[] = [
       "additionalProperties": false
     }
   },
+  {
+    "name": "focus_emulation",
+    "description": "Toggle page focus emulation: the page reports focused/visible without the OS window moving; Chrome-only.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Lease token; omit for a tab this process already holds. See server instructions."
+        },
+        "target": {
+          "type": "string",
+          "description": "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
+        },
+        "enabled": {
+          "type": "boolean",
+          "description": "true = page reports focused; false = restore real focus state."
+        }
+      },
+      "required": [
+        "enabled"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "click_focus_gated",
+    "description": "Emulate page focus, wait for a focus-gated button to enable, trusted-click it, restore; Chrome-only.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Lease token; omit for a tab this process already holds. See server instructions."
+        },
+        "target": {
+          "type": "string",
+          "description": "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
+        },
+        "selector": {
+          "type": "string",
+          "description": "CSS selector of the button; exactly one of selector or text."
+        },
+        "text": {
+          "type": "string",
+          "description": "Visible-text match for the button (e.g. \"Authorize\"); exactly one of selector or text."
+        },
+        "timeoutMs": {
+          "type": "number",
+          "description": "Max ms to poll for the button to become enabled. Default 30000."
+        },
+        "pollMs": {
+          "type": "number",
+          "description": "Poll interval ms. Default 500."
+        },
+        "keepFocus": {
+          "type": "boolean",
+          "description": "Leave focus emulation on after the click (default false = restored)."
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    }
+  },
   {
     "name": "wait_for_download",
     "description": "Arm or collect a browser download; arm capture before triggering the download.",
@@ -1699,5 +1763,79 @@ export const MANIFEST: ToolSpec[] = [
       "required": [],
       "additionalProperties": false
     }
+  },
+  {
+    "name": "extract_page",
+    "description": "Extract schema-conformant JSON from the target page's cleaned HTML via an OpenAI-compatible endpoint; default endpoint is local loopback.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Lease token; omit for a tab this process already holds. See server instructions."
+        },
+        "target": {
+          "type": "string",
+          "description": "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
+        },
+        "schema": {
+          "type": "object",
+          "description": "JSON Schema (type object) the extracted JSON must conform to; extraction instructions live in its property descriptions."
+        },
+        "selector": {
+          "type": "string",
+          "description": "CSS selector scoping extraction to a subtree."
+        },
+        "source": {
+          "type": "string",
+          "enum": [
+            "dom",
+            "served"
+          ],
+          "description": "Page source to read; 'served' currently returns not-implemented."
+        },
+        "clean": {
+          "type": "string",
+          "enum": [
+            "standard",
+            "aggressive",
+            "none"
+          ],
+          "description": "HTML cleaning level."
+        },
+        "maxChars": {
+          "type": "integer",
+          "description": "Character cap on the cleaned HTML; default 300000."
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "description": "Timeout in milliseconds; default 90000, max 300000."
+        },
+        "prompt": {
+          "type": "string",
+          "enum": [
+            "html",
+            "schematron"
+          ],
+          "description": "Prompt shape: 'html' (default) sends cleaned HTML only; 'schematron' uses the open-weight Schematron model-card prompt with the schema inline (or CDP_EXTRACT_PROMPT)."
+        },
+        "model": {
+          "type": "string",
+          "description": "Extraction model name; default 'schematron' (or CDP_EXTRACT_MODEL)."
+        },
+        "baseUrl": {
+          "type": "string",
+          "description": "OpenAI-compatible endpoint base URL; default local loopback (or CDP_EXTRACT_BASE_URL)."
+        },
+        "savePath": {
+          "type": "string",
+          "description": "Output file path."
+        }
+      },
+      "required": [
+        "schema"
+      ],
+      "additionalProperties": false
+    }
   }
 ];

package/src/toolDocs.ts

@@ -173,6 +173,26 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
       "modifiers": "Modifier keys held for this one event, e.g. ['Shift']."
     }
   },
+  "focus_emulation": {
+    "description": "Toggles CDP Emulation.setFocusEmulationEnabled on a tab: the page then BELIEVES it is focused (document.hasFocus()→true, visibilitychange stays 'visible', focus events fire) while the real OS window and active tab stay put — no focus theft. This is the primitive that unlocks focus-GATED UI (a button the site disables unless its tab is focused, e.g. Anthropic's Claude Code OAuth Authorize button on claude.ai/oauth/*) on a background tab. Chrome-only: WebDriver BiDi's emulation module has no focus primitive, so this tool is absent from tools/list under --browser firefox. Ports the core mechanism of the danbuhler/claude-code-auto-authorize extension. Remember to call with enabled:false to restore, or use click_focus_gated which restores automatically.",
+    "params": {
+      "lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process. 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>'.",
+      "enabled": "true = page reports focused/visible; false = restore the real focus state."
+    }
+  },
+  "click_focus_gated": {
+    "description": "One-call compose of focus emulation + trusted click for a focus-gated button: enables Emulation.setFocusEmulationEnabled, polls until the button (located by CSS selector OR exact visible-text match, e.g. 'Authorize') exists AND is enabled, dispatches a trusted move/press/release click via Input.dispatchMouseEvent (isTrusted:true — a content script's synthesized events can never satisfy a focus gate), then restores focus emulation off unless keepFocus. Built for the Claude Code OAuth Authorize button but works on any focus-gated control on a background tab. Throws with a diagnostic ('never located' vs 'found but stayed disabled') on timeout. Chrome-only; absent under --browser firefox.",
+    "params": {
+      "lease": "Lease token from claim_page. Omit for a tab this process holds. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease).",
+      "target": "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'.",
+      "selector": "CSS selector of the button. Give exactly one of selector or text.",
+      "text": "Exact visible-text match of the button (trims whitespace, matches button/[role=button]/submit inputs), e.g. 'Authorize'. Give exactly one of selector or text.",
+      "timeoutMs": "Max ms to poll for the button to appear and become enabled. Default 30000.",
+      "pollMs": "Poll interval in ms. Default 500.",
+      "keepFocus": "Leave focus emulation ON after the click (default false — restored even on throw, so a failed click never strands the page fake-focused)."
+    }
+  },
   "wait_for_download": {
     "description": "Wait for a file download to finish and return it as a real file on disk: {path,suggestedFilename,bytes,url,target}, written under the artifact dir's downloads/. ORDERING RULE, not optional: capture must be ARMED BEFORE the click that starts the download — call wait_for_download{arm:true} first (returns {armed:true,downloadPath,pending}), then click, then call again to collect the file. The download-behavior override is per-connection state Chrome REVERTS the moment the arming client disconnects, and an unarmed headless Chrome denies the download outright, so one triggered before arming is lost. SIDE EFFECT, browser-global: arming redirects EVERY download in this browser (all tabs, all origins) into the toolkit's downloads dir until this server exits — they no longer land in the user's normal Downloads folder. The arm lives on a connection this server holds open (an MCP-server capability): under the one-shot CLI the connection dies with the process and nothing is captured. Chrome-only (capability 'browser.downloads'): absent from tools/list under Firefox.",
     "params": {
@@ -464,5 +484,22 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
   "list_leases": {
     "description": "Enumerate every active lease for diagnosis - backend, target id, label, pid, createdAt, lastUsedAt, ttlMs, whether the owning process is alive, and whether the lease is reclaimable and why. No token required; it never returns the lease nonce, so it cannot be used to forge one. An unreadable or unparseable lease row instead carries unreadable, with label, pid and timestamps zeroed and stale forced false (an unreadable lease must never read as free to take). Under CDP_REQUIRE_LEASE it reaps abandoned agent tabs exactly as list_pages does, into an additive reaped array, omitting their rows. Where the tab can answer, a row also carries humanActiveMs, ms since input this server did not dispatch - note lastUsedAt tracks TOOLKIT calls only, so a tab a person has typed in for ten minutes looks idle, which is what this exposes; the field is absent, never null, when the tab cannot answer, and that absence means 'no answer', never 'nobody is there'. idleMs (now - lastUsedAt) and expiresAt (lastUsedAt + ttlMs) are computed fresh each call and omitted on an unreadable row.",
     "params": {}
+  },
+  "extract_page": {
+    "description": "Structured extraction: take the target page's HTML, clean it, and send it to an OpenAI-compatible /chat/completions endpoint along with your JSON Schema, getting back schema-conformant JSON instead of prose. THE DEFAULT ENDPOINT IS LOOPBACK - llm-ferry at http://127.0.0.1:8090/v1 with model 'schematron' - so page content stays ON THIS MACHINE unless the operator overrides baseUrl (or sets CDP_EXTRACT_BASE_URL). Configuration: CDP_EXTRACT_BASE_URL (endpoint override), CDP_EXTRACT_MODEL (model override), CDP_EXTRACT_API_KEY (bearer token; never logged and REDACTED from every error), CDP_EXTRACT_TIMEOUT_MS, CDP_EXTRACT_MAX_CHARS, CDP_EXTRACT_PROMPT. PROMPT SHAPE: by default only the cleaned HTML is sent and the schema rides in response_format, which is what the HOSTED Schematron API expects (it injects the schema server-side); set prompt:'schematron' when baseUrl points at a LOCALLY SERVED open-weight Schematron (e.g. an MLX schematron8B), because that model was fine-tuned on a prompt with the schema INSIDE the user message and an HTML-only prompt returns garbage from it even under constrained decoding. THE SCHEMA-DESCRIPTION RULE: this is prompt-driven extraction, and the extraction INSTRUCTIONS live in the schema's property descriptions - write them like prompts ('the job title, exactly as printed', 'ISO date, not 'yesterday'). A schema whose properties carry no descriptions is REJECTED up front with an error saying so, because it would produce garbage extraction with no hint why. Source: 'dom' (live DOM, the rendered, JS-executed page) is the default; 'served' (the raw server response before rendering) currently returns a not-implemented error rather than guessing. Size guard: cleaned HTML over maxChars (default 300000) fails with html_too_large naming the actual size - shrink the payload with 'selector' to scope to a subtree, clean:'aggressive' to strip harder (standard already drops scripts/styles/hidden), or a larger maxChars if you truly need it all. Endpoint failures surface as upstream_error (with status and body, API key redacted) or timeout; the response never contains the key. A completion the endpoint cut off at its 8192-token output cap fails naming finish_reason=length and the fix (narrow with 'selector', or ask the schema for less) - it is NOT reported as invalid JSON, because a truncated tail is a size problem, not a model one. COST IS ALWAYS VISIBLE: every successful call reports the endpoint's usage token counts inline, so a slow/bloated extraction is visible in the answer itself, not discovered on a bill later.",
+    "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.",
+      "schema": "REQUIRED JSON Schema object (type object) describing the JSON you want back. This is both the contract AND the prompt: each property's 'description' tells the extractor what to put there, so make them specific instructions. A schema with no property descriptions at all is rejected before any page work happens - empty descriptions extract garbage and the error says exactly what to fix. Nested objects and arrays of objects work; their inner descriptions count too.",
+      "selector": "CSS selector scoping extraction to that subtree's HTML only (pierces open shadow roots). The cheapest fix for html_too_large: extract the article or table, not the whole page. Omit to send the full cleaned document.",
+      "source": "'dom' (default) reads the live, rendered DOM - what the page shows after JS ran. 'served' would read the raw HTTP response before rendering; it currently returns a not-implemented error naming the arm, so callers can detect and fall back rather than guessing.",
+      "clean": "HTML cleaning level before the payload is measured and sent. 'standard' (default) strips scripts, styles, hidden elements and other non-content noise. 'aggressive' additionally collapses whitespace, drops nav/footer/boilerplate - use when html_too_large bites or the extractor chases junk. 'none' sends the raw HTML; almost never what you want.",
+      "maxChars": "Character cap on the cleaned HTML payload. Default 300000 (also settable via CDP_EXTRACT_MAX_CHARS). Exceeding it fails with html_too_large reporting actual vs cap - it does NOT silently truncate, because a half page extracted as though it were whole is a wrong answer that looks right.",
+      "timeoutMs": "Total budget in ms for the endpoint call. Default 90000, hard max 300000 (CDP_EXTRACT_TIMEOUT_MS overrides the default). Expiry fails with a timeout error, never a hang.",
+      "prompt": "Prompt shape sent upstream. 'html' (default, also CDP_EXTRACT_PROMPT=html) sends the cleaned HTML as the only user message and lets response_format carry the schema - correct for the hosted Schematron API, which injects the schema server-side. 'schematron' sends the open-weight Schematron model card's own messages: a 'You are a helpful assistant' system message plus a user message with the compact JSON-stringified schema inline, then the HTML, then 'MAKE SURE ITS VALID JSON.' - use it when baseUrl points at a locally served open-weight Schematron. It adds roughly the stringified schema's length to the prompt (maxChars caps the HTML only); response_format is sent in both modes. The arg wins over CDP_EXTRACT_PROMPT, and any other value is rejected up front.",
+      "model": "Model name for the endpoint call. Default 'schematron' on the loopback llm-ferry; override per-call or via CDP_EXTRACT_MODEL.",
+      "baseUrl": "OpenAI-compatible endpoint base URL (the server appends /chat/completions). DEFAULT IS http://127.0.0.1:8090/v1 - loopback llm-ferry, page content never leaves the machine. Setting this (or CDP_EXTRACT_BASE_URL) to a remote host is an operator decision about where page content may travel; the response never echoes the URL with credentials.",
+      "savePath": "Write the extracted JSON here instead of returning it inline: the response then carries the file path and usage counts only, keeping large payloads out of the transcript. An absolute path (starting with /) is used as-is; a relative path resolves under the artifact dir (/tmp/cdp-toolkit); missing parents are created."
+    }
   }
 };

package/src/toolGroups.ts

@@ -1,7 +1,7 @@
 export const TOOL_GROUPS = [
   "core", "input", "cookies", "network", "console", "mocking",
   "emulation", "performance", "recording", "leases", "permissions",
-  "dialogs", "downloads",
+  "dialogs", "downloads", "extraction",
 ] as const;
 
 export type ToolGroup = (typeof TOOL_GROUPS)[number];
@@ -14,7 +14,7 @@ export const GROUP_TOOLS: Record<ToolGroup, readonly string[]> = {
   ],
   input: [
     "hover", "drag", "scroll", "dispatch_mouse", "press_key", "fill_form",
-    "upload_file",
+    "upload_file", "focus_emulation", "click_focus_gated",
   ],
   cookies: ["list_cookies", "set_cookie", "delete_cookies"],
   network: ["list_network_requests", "get_network_request"],
@@ -31,6 +31,7 @@ export const GROUP_TOOLS: Record<ToolGroup, readonly string[]> = {
   permissions: ["grant_permissions"],
   dialogs: ["handle_dialog"],
   downloads: ["wait_for_download"],
+  extraction: ["extract_page"],
 } as const;
 
 export const TOOL_GROUP: Record<string, ToolGroup> = {};