cdp-toolkit 2.2.0 → 2.5.0

package/dist/mcp.js

@@ -1090,6 +1090,8 @@ var init_driver = __esm(() => {
     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"]
   };
@@ -1127,7 +1129,7 @@ class BidiConnection {
     return new Promise((resolve, reject) => {
       const ws = new WebSocket(this.wsUrl);
       this.ws = ws;
-      const openTimer = setTimeout(() => reject(new BidiError(`connect timeout: ${this.wsUrl}`)), this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS2);
+      const openTimer = setTimeout(() => reject(new BidiError(`connect timeout: ${this.wsUrl}`)), this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS3);
       ws.onopen = () => {
         clearTimeout(openTimer);
         resolve(this);
@@ -1187,7 +1189,7 @@ class BidiConnection {
     if (this.closed || !this.ws)
       return Promise.reject(new BidiError("connection not open"));
     const id = ++this.nextId;
-    const timeoutMs = opts.timeoutMs ?? this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS2;
+    const timeoutMs = opts.timeoutMs ?? this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS3;
     const payload = { id, method, params };
     return new Promise((resolve, reject) => {
       const start = Date.now();
@@ -1234,7 +1236,7 @@ class BidiConnection {
       }
     };
   }
-  waitFor(event, predicate, timeoutMs = this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS2) {
+  waitFor(event, predicate, timeoutMs = this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS3) {
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         off();
@@ -1278,9 +1280,9 @@ async function connectBidiSessionUrl(wsUrl, opts = {}) {
   conn.retain();
   return conn;
 }
-var DEFAULT_TIMEOUT_MS2, BidiError;
+var DEFAULT_TIMEOUT_MS3, BidiError;
 var init_client2 = __esm(() => {
-  DEFAULT_TIMEOUT_MS2 = Number(process.env.BIDI_TIMEOUT_MS ?? 15000);
+  DEFAULT_TIMEOUT_MS3 = Number(process.env.BIDI_TIMEOUT_MS ?? 15000);
   BidiError = class BidiError extends Error {
     code;
     data;
@@ -1294,16 +1296,16 @@ var init_client2 = __esm(() => {
 });
 
 // src/bidi/session-lease.ts
-import { mkdir as mkdir12, readFile as readFile8, rename as rename3, unlink as unlink5, writeFile as writeFile9 } from "node:fs/promises";
-import { join as join10 } from "node:path";
+import { mkdir as mkdir13, readFile as readFile8, rename as rename3, unlink as unlink5, writeFile as writeFile10 } from "node:fs/promises";
+import { join as join11 } from "node:path";
 function safeEndpoint(endpoint) {
   return endpoint.replace(/[^A-Za-z0-9._-]/g, "_");
 }
 function sessionSlotFile(endpoint) {
-  return join10(leaseDir(), `ff-session-${safeEndpoint(endpoint)}.json`);
+  return join11(leaseDir(), `ff-session-${safeEndpoint(endpoint)}.json`);
 }
 function muxDaemonLogFile(endpoint) {
-  return join10(leaseDir(), `ff-mux-${safeEndpoint(endpoint)}.log`);
+  return join11(leaseDir(), `ff-mux-${safeEndpoint(endpoint)}.log`);
 }
 function sessionWaitMs() {
   const raw = Number(process.env.CDP_FIREFOX_SESSION_WAIT_MS);
@@ -1341,7 +1343,7 @@ async function acquireSessionSlot(endpoint, opts) {
     record.marionettePort = opts.marionettePort;
   const handle = { endpoint, pid: process.pid, createdAt };
   const payload = JSON.stringify(record);
-  await mkdir12(leaseDir(), { recursive: true });
+  await mkdir13(leaseDir(), { recursive: true });
   const deadline = Date.now() + waitMs;
   const maxAttempts = Math.max(100, Math.ceil(waitMs / pollMs) + 100);
   let attempts = 0;
@@ -1351,7 +1353,7 @@ async function acquireSessionSlot(endpoint, opts) {
       throw new SessionSlotBusyError(endpoint, lastLiveHolder);
     attempts++;
     try {
-      await writeFile9(file, payload, { flag: "wx" });
+      await writeFile10(file, payload, { flag: "wx" });
       return { handle };
     } catch (err) {
       if (err.code !== "EEXIST")
@@ -1365,7 +1367,7 @@ async function acquireSessionSlot(endpoint, opts) {
         return;
       });
       try {
-        await writeFile9(file, payload, { flag: "wx" });
+        await writeFile10(file, payload, { flag: "wx" });
         return { handle, staleHolder: holder };
       } catch (err) {
         if (err.code !== "EEXIST")
@@ -1393,7 +1395,7 @@ async function advertiseMux(handle, muxEndpoint) {
   const tmp = `${file}.tmp-${process.pid}`;
   const next = { ...current, muxEndpoint };
   try {
-    await writeFile9(tmp, JSON.stringify(next), "utf8");
+    await writeFile10(tmp, JSON.stringify(next), "utf8");
     await rename3(tmp, file);
   } catch {
     await unlink5(tmp).catch(() => {
@@ -1967,7 +1969,7 @@ function isSlotFreedReply(frame) {
   return false;
 }
 function forceClearOrphanSession(marionettePort, opts = {}) {
-  const timeoutMs = opts.timeoutMs !== undefined && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0 ? opts.timeoutMs : DEFAULT_TIMEOUT_MS3;
+  const timeoutMs = opts.timeoutMs !== undefined && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0 ? opts.timeoutMs : DEFAULT_TIMEOUT_MS4;
   return new Promise((resolve) => {
     if (!Number.isFinite(marionettePort) || marionettePort <= 0 || marionettePort > 65535) {
       resolve(false);
@@ -2023,7 +2025,7 @@ function forceClearOrphanSession(marionettePort, opts = {}) {
     }
   });
 }
-var DEFAULT_MARIONETTE_PORT = 2828, DEFAULT_TIMEOUT_MS3 = 4000, HOST = "127.0.0.1", COLON = 58, DELETE_SESSION_FRAME, MarionetteProtocolError;
+var DEFAULT_MARIONETTE_PORT = 2828, DEFAULT_TIMEOUT_MS4 = 4000, HOST = "127.0.0.1", COLON = 58, DELETE_SESSION_FRAME, MarionetteProtocolError;
 var init_marionette = __esm(() => {
   DELETE_SESSION_FRAME = encodeFrame2([0, 1, "WebDriver:DeleteSession", {}]);
   MarionetteProtocolError = class MarionetteProtocolError extends Error {
@@ -4161,6 +4163,7 @@ var CDP_CAPABILITIES = new Set([
   "capture.screencast",
   "input.raw",
   "input.html5Drag",
+  "emulate.focus",
   "browser.downloads",
   "browser.permissions",
   "worker.targets"
@@ -7581,6 +7584,99 @@ async function dispatchMouse(args) {
   });
 }
 
+// src/tools/focus-emulation.ts
+init_activity();
+init_client();
+function validateFocusEmulationArgs(args) {
+  if (typeof args.enabled !== "boolean") {
+    throw new Error("focus_emulation requires { enabled } of true or false");
+  }
+}
+function validateClickFocusGatedArgs(args) {
+  const hasSel = typeof args.selector === "string" && args.selector.length > 0;
+  const hasText = typeof args.text === "string" && args.text.length > 0;
+  if (hasSel === hasText) {
+    throw new Error("click_focus_gated requires exactly one of { selector } or { text }");
+  }
+  if (args.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
+    throw new Error("click_focus_gated: timeoutMs must be a positive number");
+  }
+  if (args.pollMs !== undefined && (!Number.isFinite(args.pollMs) || args.pollMs <= 0)) {
+    throw new Error("click_focus_gated: pollMs must be a positive number");
+  }
+}
+var FIND_BUTTON = `(() => {
+  const SEL = %SEL%;
+  const TEXT = %TEXT%;
+  let btn = null;
+  let matchedBy = null;
+  if (SEL) {
+    btn = document.querySelector(SEL);
+    if (btn) matchedBy = "selector";
+  }
+  if (!btn && TEXT) {
+    btn = Array.from(document.querySelectorAll("button,[role=button],input[type=submit]"))
+      .find((b) => (b.textContent || b.value || "").trim() === TEXT);
+    if (btn) matchedBy = "text";
+  }
+  if (!btn) return null;
+  const r = btn.getBoundingClientRect();
+  if (r.width === 0 || r.height === 0) return null;
+  return { x: r.left + r.width / 2, y: r.top + r.height / 2,
+           disabled: !!btn.disabled || btn.getAttribute("aria-disabled") === "true",
+           matchedBy, hasFocus: document.hasFocus(), visibility: document.visibilityState };
+})()`;
+function findButtonExpression(selector, text) {
+  return FIND_BUTTON.replace("%SEL%", JSON.stringify(selector ?? null)).replace("%TEXT%", JSON.stringify(text ?? null));
+}
+async function focusEmulation(args) {
+  validateFocusEmulationArgs(args);
+  return withPage(args.target, async (conn) => {
+    await conn.send("Emulation.setFocusEmulationEnabled", { enabled: args.enabled });
+    return { enabled: args.enabled };
+  }, { lease: args.lease });
+}
+async function clickFocusGated(args) {
+  validateClickFocusGatedArgs(args);
+  const timeoutMs = args.timeoutMs ?? 30000;
+  const pollMs = args.pollMs ?? 500;
+  const start = Date.now();
+  return withPage(args.target, async (conn, target) => {
+    await conn.send("Emulation.setFocusEmulationEnabled", { enabled: true });
+    try {
+      const expression = findButtonExpression(args.selector, args.text);
+      for (;; ) {
+        const { result } = await conn.send("Runtime.evaluate", {
+          expression,
+          returnByValue: true
+        });
+        const btn = result?.value;
+        if (btn && !btn.disabled) {
+          const base = { x: btn.x, y: btn.y, button: "left", buttons: 1, clickCount: 1 };
+          await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { type: "mouseMoved", x: btn.x, y: btn.y });
+          await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { ...base, type: "mousePressed" });
+          await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { ...base, type: "mouseReleased" });
+          return {
+            clicked: true,
+            x: btn.x,
+            y: btn.y,
+            matchedBy: btn.matchedBy,
+            elapsedMs: Date.now() - start
+          };
+        }
+        if (Date.now() - start >= timeoutMs) {
+          throw new Error(`click_focus_gated: button never became clickable within ${timeoutMs}ms` + (btn ? " (found but stayed disabled — focus emulation may not satisfy this gate)" : " (never located)"));
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+      }
+    } finally {
+      if (!args.keepFocus) {
+        await conn.send("Emulation.setFocusEmulationEnabled", { enabled: false }).catch(() => {});
+      }
+    }
+  }, { lease: args.lease, timeoutMs: timeoutMs + 5000 });
+}
+
 // src/tools/downloads.ts
 init_client();
 import { readdir as readdir3, rename as rename2, stat as stat4 } from "node:fs/promises";
@@ -7809,6 +7905,421 @@ async function grantPermissions(args = {}) {
   return { granted: [...permissions], origin, ...reset ? { reset: true } : {}, target };
 }
 
+// src/tools/extract.ts
+init_client();
+import { mkdir as mkdir12, writeFile as writeFile9 } from "node:fs/promises";
+import { dirname as dirname3, join as join10 } from "node:path";
+var ARTIFACT_DIR7 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var DEFAULT_BASE_URL = "http://127.0.0.1:8090/v1";
+var DEFAULT_MODEL = "schematron";
+var DEFAULT_TIMEOUT_MS2 = 90000;
+var DEFAULT_MAX_CHARS = 300000;
+var MAX_TIMEOUT_MS = 300000;
+var DEFAULT_PROMPT_MODE = "html";
+var CHARS_PER_TOKEN = 3.5;
+var COMPLESION_TOKENS = 8192;
+var SAFETY_TOKENS = 8000;
+var CONTEXT_TOKEN_BUDGET = 128000;
+function extractBaseUrl() {
+  const raw = process.env.CDP_EXTRACT_BASE_URL?.trim();
+  return raw ? raw : DEFAULT_BASE_URL;
+}
+function extractModel() {
+  const raw = process.env.CDP_EXTRACT_MODEL?.trim();
+  return raw ? raw : DEFAULT_MODEL;
+}
+function extractPromptMode() {
+  const raw = process.env.CDP_EXTRACT_PROMPT?.trim();
+  return raw ? raw : DEFAULT_PROMPT_MODE;
+}
+function extractApiKey() {
+  const raw = process.env.CDP_EXTRACT_API_KEY;
+  return raw && raw.length > 0 ? raw : undefined;
+}
+function extractTimeoutMs() {
+  const raw = Number(process.env.CDP_EXTRACT_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? Math.min(raw, MAX_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS2;
+}
+function extractMaxChars() {
+  const raw = Number(process.env.CDP_EXTRACT_MAX_CHARS);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_MAX_CHARS;
+}
+function hasAnyDescription(node, seen = new Set) {
+  if (typeof node !== "object" || node === null || seen.has(node))
+    return false;
+  seen.add(node);
+  const n = node;
+  if (typeof n.description === "string" && n.description.trim() !== "")
+    return true;
+  const props = n.properties;
+  if (typeof props === "object" && props !== null) {
+    for (const value of Object.values(props))
+      if (hasAnyDescription(value, seen))
+        return true;
+  }
+  if (hasAnyDescription(n.items, seen))
+    return true;
+  for (const key of ["anyOf", "oneOf", "allOf", "prefixItems"]) {
+    const branches = n[key];
+    if (Array.isArray(branches)) {
+      for (const branch of branches)
+        if (hasAnyDescription(branch, seen))
+          return true;
+    }
+  }
+  return false;
+}
+function validateExtractArgs(args) {
+  if (args.schema === null || typeof args.schema !== "object" || Array.isArray(args.schema)) {
+    throw new CdpError("extract_page: 'schema' is required and must be a JSON Schema object");
+  }
+  if (args.schema.type !== "object") {
+    throw new CdpError(`extract_page: 'schema.type' must be "object" (got ${JSON.stringify(args.schema.type)})`);
+  }
+  if (args.schema.additionalProperties === true) {
+    throw new CdpError("extract_page: schema must not set additionalProperties:true — strict json_schema mode requires a closed object so the extraction cannot invent fields");
+  }
+  if (!hasAnyDescription(args.schema)) {
+    throw new CdpError("extract_page: no property in 'schema' carries a description. This is prompt-driven extraction: the property descriptions ARE the instructions the extractor follows ('the job title, exactly as printed'). Write them like prompts and retry.");
+  }
+  if (args.selector !== undefined && (typeof args.selector !== "string" || args.selector.length === 0)) {
+    throw new CdpError("extract_page: 'selector' must be a non-empty CSS selector string");
+  }
+  if (args.source !== undefined && args.source !== "dom" && args.source !== "served") {
+    throw new CdpError(`extract_page: 'source' must be "dom" or "served" (got ${JSON.stringify(args.source)})`);
+  }
+  if (args.source === "served") {
+    throw new CdpError("extract_page: source 'served' (the raw server response before rendering) is not implemented; use source 'dom' (the live rendered DOM).");
+  }
+  if (args.clean !== undefined && args.clean !== "standard" && args.clean !== "aggressive" && args.clean !== "none") {
+    throw new CdpError(`extract_page: 'clean' must be "standard", "aggressive" or "none" (got ${JSON.stringify(args.clean)})`);
+  }
+  if (args.prompt !== undefined && args.prompt !== "html" && args.prompt !== "schematron") {
+    throw new CdpError(`extract_page: 'prompt' must be "html" or "schematron" (got ${JSON.stringify(args.prompt)})`);
+  }
+  const envPrompt = process.env.CDP_EXTRACT_PROMPT?.trim();
+  if (args.prompt === undefined && envPrompt && envPrompt !== "html" && envPrompt !== "schematron") {
+    throw new CdpError(`extract_page: CDP_EXTRACT_PROMPT must be "html" or "schematron" (got ${JSON.stringify(envPrompt)})`);
+  }
+  if (args.maxChars !== undefined && (!Number.isFinite(args.maxChars) || args.maxChars <= 0)) {
+    throw new CdpError("extract_page: 'maxChars' must be a positive number");
+  }
+  if (args.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
+    throw new CdpError("extract_page: 'timeoutMs' must be a positive number");
+  }
+  if (args.model !== undefined && (typeof args.model !== "string" || args.model.length === 0)) {
+    throw new CdpError("extract_page: 'model' must be a non-empty string");
+  }
+  if (args.baseUrl !== undefined && (typeof args.baseUrl !== "string" || args.baseUrl.length === 0)) {
+    throw new CdpError("extract_page: 'baseUrl' must be a non-empty string (the API key is env-only: CDP_EXTRACT_API_KEY)");
+  }
+}
+function buildCleanFunctionSource(selector, clean) {
+  return `function() {
+    var SEL = ${JSON.stringify(selector ?? null)};
+    var CLEAN = ${JSON.stringify(clean)};
+    var STRIP = ["script","style","noscript","svg","canvas","iframe","video","audio","source","track","template","object","embed","link","meta"];
+    var AGGRO = ["nav","header","footer","aside","form","button"];
+    var WHITELIST = ["href","src","alt","title","value","placeholder","for","name","type","role","aria-label","selected","checked","disabled"];
+
+    function bytes(s) {
+      try { return new TextEncoder().encode(s).length; } catch (e) { return s.length; }
+    }
+
+    function collectShadowScopes(root, out) {
+      var els = root.querySelectorAll("*");
+      for (var i = 0; i < els.length; i++) {
+        var sr = els[i].shadowRoot;
+        if (sr) { out.push(sr); collectShadowScopes(sr, out); }
+      }
+    }
+
+    // Locate SEL piercing open shadow roots (querySelector on document first,
+    // then every open shadow scope). LIMIT: outerHTML serializes the matched
+    // element's light DOM only; a closed shadow root is invisible by design.
+    function deepQuery(sel) {
+      var direct = document.querySelector(sel);
+      if (direct) return direct;
+      var scopes = [];
+      collectShadowScopes(document, scopes);
+      for (var i = 0; i < scopes.length; i++) {
+        var hit = scopes[i].querySelector(sel);
+        if (hit) return hit;
+      }
+      return null;
+    }
+
+    // The visibility heuristic, same shape as bidi/snapshot.ts's isVisible:
+    // hidden attr, aria-hidden, computed display/visibility, then the 0x0
+    // paint check. OPTION/OPTGROUP skip the size check (a closed select's
+    // popup is unpainted though its options are real, extractable content).
+    function isHidden(el) {
+      if (el.hidden) return true;
+      if (el.getAttribute("aria-hidden") === "true") return true;
+      var style = null;
+      try { style = el.ownerDocument.defaultView.getComputedStyle(el); } catch (e) {}
+      if (style && (style.display === "none" || style.visibility === "hidden")) return true;
+      var tag = el.tagName;
+      if (tag !== "OPTION" && tag !== "OPTGROUP") {
+        var rect = el.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) return true;
+      }
+      return false;
+    }
+
+    function countDrop(dropped, tag) {
+      dropped.elements[tag] = (dropped.elements[tag] || 0) + 1;
+    }
+
+    function cleanRoot(root) {
+      var rawHtml = root.outerHTML;
+      var dropped = { comments: 0, hidden: 0, attributes: 0, elements: {} };
+      if (CLEAN === "none") {
+        return { matched: true, html: rawHtml, rawBytes: bytes(rawHtml), cleanBytes: bytes(rawHtml), dropped: dropped };
+      }
+      var live = root.querySelectorAll("*");
+      var clone = root.cloneNode(true);
+      var mirrored = clone.querySelectorAll("*");
+      for (var i = 0; i < mirrored.length; i++) {
+        var cel = mirrored[i];
+        if (!cel.parentNode) continue; // dropped already, with an ancestor
+        var low = cel.tagName.toLowerCase();
+        if (STRIP.indexOf(low) !== -1) { countDrop(dropped, low); cel.parentNode.removeChild(cel); continue; }
+        if (CLEAN === "aggressive" && AGGRO.indexOf(low) !== -1) { countDrop(dropped, low); cel.parentNode.removeChild(cel); continue; }
+        var lel = live[i];
+        if (lel && isHidden(lel)) { dropped.hidden++; cel.parentNode.removeChild(cel); continue; }
+        for (var j = cel.attributes.length - 1; j >= 0; j--) {
+          var attr = cel.attributes[j];
+          if (WHITELIST.indexOf(attr.name.toLowerCase()) === -1) {
+            cel.removeAttribute(attr.name);
+            dropped.attributes++;
+          }
+        }
+      }
+      var walker = clone.ownerDocument.createTreeWalker(clone, NodeFilter.SHOW_COMMENT);
+      var comments = [];
+      while (walker.nextNode()) comments.push(walker.currentNode);
+      for (var k = 0; k < comments.length; k++) {
+        var c = comments[k];
+        if (c.parentNode) c.parentNode.removeChild(c);
+      }
+      dropped.comments = comments.length;
+      // Whitespace collapse at the TEXT-NODE level, never on the serialized
+      // string: a regex over outerHTML would also flatten <pre> content.
+      var tw = clone.ownerDocument.createTreeWalker(clone, NodeFilter.SHOW_TEXT);
+      while (tw.nextNode()) {
+        var node = tw.currentNode;
+        node.nodeValue = node.nodeValue.replace(/\\s+/g, " ");
+      }
+      var html = clone.outerHTML;
+      return { matched: true, html: html, rawBytes: bytes(rawHtml), cleanBytes: bytes(html), dropped: dropped };
+    }
+
+    if (SEL) {
+      var found = deepQuery(SEL);
+      if (!found) return { matched: false };
+      return cleanRoot(found);
+    }
+    return cleanRoot(document.documentElement);
+  }`;
+}
+function coerceCleanOutcome(raw, selector) {
+  if (typeof raw !== "object" || raw === null) {
+    throw new CdpError("extract_page: in-page cleaning returned an unexpected shape");
+  }
+  const r = raw;
+  if (r.matched === false) {
+    throw new CdpError(`extract_page: no element matches selector '${selector}' (checked document and every open shadow root)`);
+  }
+  if (typeof r.html !== "string" || typeof r.rawBytes !== "number" || !Number.isFinite(r.rawBytes) || typeof r.cleanBytes !== "number" || !Number.isFinite(r.cleanBytes)) {
+    throw new CdpError("extract_page: in-page cleaning returned an unexpected shape");
+  }
+  return {
+    html: r.html,
+    rawBytes: r.rawBytes,
+    cleanBytes: r.cleanBytes,
+    dropped: typeof r.dropped === "object" && r.dropped !== null ? r.dropped : {}
+  };
+}
+function estimateTokens(chars) {
+  return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+function guardSize(outcome, maxChars) {
+  const estTokens = estimateTokens(outcome.html.length);
+  const overChars = outcome.html.length > maxChars;
+  const overContext = estTokens + COMPLESION_TOKENS + SAFETY_TOKENS > CONTEXT_TOKEN_BUDGET;
+  if (overChars || overContext) {
+    const why = overChars ? `cleaned HTML is ${outcome.html.length} chars (${outcome.cleanBytes} bytes), over the ${maxChars}-char cap` : `estimated ${estTokens} prompt tokens + ${COMPLESION_TOKENS} completion + ${SAFETY_TOKENS} safety exceeds the ${CONTEXT_TOKEN_BUDGET}-token context budget`;
+    throw new CdpError(`extract_page: html_too_large — ${why}. Shrink the payload with 'selector' to scope to a subtree, clean:"aggressive" to strip nav/footer/form/button too, or a larger maxChars if you truly need it all. No truncation: a partial page extracted as whole is a wrong answer that looks right.`);
+  }
+  return estTokens;
+}
+function redactSecrets(text, apiKey) {
+  let out = text;
+  if (apiKey && apiKey.length > 0) {
+    out = out.split(apiKey).join("[redacted]");
+  }
+  return out.replace(/sk-[A-Za-z0-9_-]{8,}/g, "[redacted]");
+}
+function pickCostUsd(usage) {
+  for (const v of [usage.cost_usd, usage.costUsd, usage.cost]) {
+    if (typeof v === "number" && Number.isFinite(v))
+      return v;
+  }
+  return;
+}
+function excerpt(text, max) {
+  const t = text.trim();
+  return t.length > max ? `${t.slice(0, max)}…` : t;
+}
+function buildExtractionMessages(mode, html, schema) {
+  if (mode !== "schematron")
+    return [{ role: "user", content: html }];
+  const user = "You are going to be given a JSON schema following the standardized JSON Schema format. You are going to be given a HTML page and you are going to apply the schema to the HTML page however you see it as applicable and return the results in a JSON object. The schema is as follows:" + `
+
+` + JSON.stringify(schema) + `
+
+` + "Here is the HTML page:" + `
+
+` + html + `
+
+` + "MAKE SURE ITS VALID JSON.";
+  return [
+    { role: "system", content: "You are a helpful assistant" },
+    { role: "user", content: user }
+  ];
+}
+async function callExtractionEndpoint(opts) {
+  const url = `${opts.baseUrl.replace(/\/+$/, "")}/chat/completions`;
+  const body = JSON.stringify({
+    model: opts.model,
+    messages: buildExtractionMessages(opts.prompt ?? "html", opts.html, opts.schema),
+    temperature: 0,
+    max_tokens: COMPLESION_TOKENS,
+    response_format: { type: "json_schema", json_schema: { name: "extract", strict: true, schema: opts.schema } }
+  });
+  const headers = { "content-type": "application/json" };
+  if (opts.apiKey)
+    headers.authorization = `Bearer ${opts.apiKey}`;
+  let lastStatus = 0;
+  let lastBody = "";
+  for (let attempt = 1;attempt <= 2; attempt++) {
+    let res;
+    try {
+      res = await fetch(url, { method: "POST", headers, body, signal: AbortSignal.timeout(opts.timeoutMs) });
+    } catch (e) {
+      const err = e;
+      if (err.name === "TimeoutError" || err.name === "AbortError") {
+        throw new CdpError(`extract_page: upstream call to ${opts.baseUrl} timed out after ${opts.timeoutMs}ms`);
+      }
+      throw new CdpError(`extract_page: could not reach ${opts.baseUrl} (${redactSecrets(err.message, opts.apiKey)}) — is ferry running?`);
+    }
+    const text = await res.text();
+    if (res.ok) {
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        throw new CdpError(`extract_page: endpoint returned a non-JSON 200 body: ${excerpt(redactSecrets(text, opts.apiKey), 200)}`);
+      }
+      if (parsed.error) {
+        throw new CdpError(`extract_page: upstream_error from ${opts.baseUrl}: ${excerpt(redactSecrets(String(parsed.error.message ?? JSON.stringify(parsed.error)), opts.apiKey), 600)}`);
+      }
+      const content = parsed.choices?.[0]?.message?.content;
+      if (typeof content !== "string" || content.length === 0) {
+        throw new CdpError(`extract_page: endpoint response carried no message content: ${excerpt(redactSecrets(text, opts.apiKey), 200)}`);
+      }
+      const u = parsed.usage ?? {};
+      const usage = {
+        promptTokens: u.prompt_tokens ?? 0,
+        completionTokens: u.completion_tokens ?? 0,
+        totalTokens: u.total_tokens ?? 0,
+        ...pickCostUsd(u) !== undefined ? { costUsd: pickCostUsd(u) } : {}
+      };
+      const fr = parsed.choices?.[0]?.finish_reason;
+      const finishReason = typeof fr === "string" ? fr : undefined;
+      return { content, usage, model: parsed.model ?? opts.model, finishReason };
+    }
+    lastStatus = res.status;
+    lastBody = text;
+    if (res.status === 429) {
+      const retryAfter = res.headers.get("retry-after");
+      throw new CdpError(`extract_page: upstream rate-limited (HTTP 429) from ${opts.baseUrl}${retryAfter !== null ? `, retry-after: ${retryAfter}` : " (no retry-after header)"}`);
+    }
+    if (res.status < 500 || res.status >= 600)
+      break;
+  }
+  throw new CdpError(`extract_page: upstream_error HTTP ${lastStatus} from POST ${url}: ${excerpt(redactSecrets(lastBody, opts.apiKey), 600)}`);
+}
+async function withPage3(driver, target, fn) {
+  const page = await driver.page(target);
+  try {
+    return await fn(page);
+  } finally {
+    await page.release();
+  }
+}
+async function extractPage(driver, args) {
+  validateExtractArgs(args);
+  const clean = args.clean ?? "standard";
+  const maxChars = args.maxChars ?? extractMaxChars();
+  const timeoutMs = Math.min(args.timeoutMs ?? extractTimeoutMs(), MAX_TIMEOUT_MS);
+  const baseUrl = args.baseUrl ?? extractBaseUrl();
+  const model = args.model ?? extractModel();
+  const prompt = args.prompt ?? extractPromptMode();
+  const apiKey = extractApiKey();
+  return withPage3(driver, args.target, async (page) => {
+    const source = `(${buildCleanFunctionSource(args.selector, clean)})()`;
+    const outcome = coerceCleanOutcome(await page.evaluate(source, { awaitPromise: true }), args.selector);
+    const estTokens = guardSize(outcome, maxChars);
+    const { content, usage, model: respondedModel, finishReason } = await callExtractionEndpoint({
+      baseUrl,
+      apiKey,
+      model,
+      html: outcome.html,
+      schema: args.schema,
+      timeoutMs,
+      prompt
+    });
+    if (finishReason === "length") {
+      throw new CdpError(`extract_page: completion truncated at max_tokens=${COMPLESION_TOKENS} (finish_reason=length, ${usage.completionTokens} completion tokens); ` + `narrow the payload with 'selector' or ask the schema for less: ${excerpt(redactSecrets(content, apiKey), 200)}`);
+    }
+    let data;
+    try {
+      data = JSON.parse(content);
+    } catch (e) {
+      throw new CdpError(`extract_page: endpoint returned invalid JSON (${e.message}${finishReason !== undefined ? `, finish_reason=${finishReason}` : ""}): ${excerpt(redactSecrets(content, apiKey), 200)}`);
+    }
+    const result = {
+      data,
+      model: respondedModel,
+      usage,
+      html: {
+        source: "dom",
+        rawBytes: outcome.rawBytes,
+        cleanBytes: outcome.cleanBytes,
+        estTokens,
+        dropped: outcome.dropped
+      },
+      target: { id: page.info.id, url: page.info.url, title: page.info.title }
+    };
+    if (args.savePath === undefined || args.savePath === "")
+      return result;
+    const path = args.savePath.startsWith("/") ? args.savePath : join10(ARTIFACT_DIR7, args.savePath);
+    await mkdir12(dirname3(path), { recursive: true });
+    const json = JSON.stringify(result, null, 2);
+    await writeFile9(path, json, "utf8");
+    const saved = {
+      path,
+      bytes: Buffer.byteLength(json, "utf8"),
+      model: respondedModel,
+      usage,
+      target: result.target
+    };
+    return saved;
+  });
+}
+
 // src/index.ts
 init_client();
 var cdpDriver = createCdpDriver();
@@ -7856,8 +8367,11 @@ var TOOLS = {
   list_mocks: listMocks,
   clear_mocks: clearMocks,
   dispatch_mouse: dispatchMouse,
+  focus_emulation: focusEmulation,
+  click_focus_gated: clickFocusGated,
   wait_for_download: waitForDownload,
   grant_permissions: grantPermissions,
+  extract_page: onCdp(extractPage),
   claim_page: onCdp(LEASE_TOOLS.claim_page),
   release_page: onCdp(LEASE_TOOLS.release_page),
   list_leases: onCdp(LEASE_TOOLS.list_leases)
@@ -8517,6 +9031,70 @@ var MANIFEST = [
       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.",
@@ -9542,6 +10120,80 @@ var MANIFEST = [
       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
+    }
   }
 ];
 
@@ -9553,7 +10205,7 @@ import { spawn as spawn4 } from "node:child_process";
 import { existsSync as existsSync2, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createConnection, createServer as createServer2 } from "node:net";
 import { tmpdir } from "node:os";
-import { join as join11 } from "node:path";
+import { join as join12 } from "node:path";
 function resolveBinary() {
   const candidates = [
     process.env.FIREFOX_BIN,
@@ -9633,7 +10285,7 @@ var LAUNCH_USER_JS_PREFS = {
   "dom.file.createInChild": true
 };
 function writeLaunchUserJs(profilePath) {
-  const target = join11(profilePath, "user.js");
+  const target = join12(profilePath, "user.js");
   const existing = existsSync2(target) ? readFileSync(target, "utf8") : "";
   const present = new Set;
   for (const line of existing.split(`
@@ -9655,7 +10307,7 @@ async function launchFirefox(opts = {}) {
   const binary = resolveBinary();
   const port = await pickPort(opts.port);
   const isThrowaway = opts.profilePath === undefined;
-  const profilePath = opts.profilePath ?? mkdtempSync(join11(tmpdir(), "cdp-toolkit-ff-profile-"));
+  const profilePath = opts.profilePath ?? mkdtempSync(join12(tmpdir(), "cdp-toolkit-ff-profile-"));
   if (isThrowaway)
     writeLaunchUserJs(profilePath);
   const args = ["--profile", profilePath, "--remote-debugging-port", String(port), "--no-remote"];
@@ -9847,7 +10499,7 @@ init_workers();
 
 class BidiToolError extends Error {
 }
-async function withPage3(driver, target, fn) {
+async function withPage4(driver, target, fn) {
   const page = await driver.page(target);
   try {
     return await fn(page);
@@ -9891,7 +10543,7 @@ async function captureFresh(page, durationMs) {
 }
 async function listConsoleMessages2(driver, args = {}) {
   refuseWorkerSelector(driver, args.target);
-  return withPage3(driver, args.target, async (page) => {
+  return withPage4(driver, args.target, async (page) => {
     if (args.reload)
       await captureFresh(page, args.durationMs ?? 2500);
     const buf = bufferFor(consoleBuffers, page.info.id);
@@ -9900,7 +10552,7 @@ async function listConsoleMessages2(driver, args = {}) {
 }
 async function getConsoleMessage2(driver, args = {}) {
   refuseWorkerSelector(driver, args.target);
-  return withPage3(driver, args.target, async (page) => {
+  return withPage4(driver, args.target, async (page) => {
     const buf = bufferFor(consoleBuffers, page.info.id);
     const idx = args.index ?? 0;
     const entry = buf[idx];
@@ -9911,7 +10563,7 @@ async function getConsoleMessage2(driver, args = {}) {
 }
 async function listNetworkRequests2(driver, args = {}) {
   refuseWorkerSelector(driver, args.target);
-  return withPage3(driver, args.target, async (page) => {
+  return withPage4(driver, args.target, async (page) => {
     if (args.reload)
       await captureFresh(page, args.durationMs ?? 2500);
     let buf = bufferFor(networkBuffers, page.info.id);
@@ -9924,7 +10576,7 @@ async function getNetworkRequest2(driver, args = {}) {
   refuseWorkerSelector(driver, args.target);
   if (!args.requestId && !args.url)
     throw new BidiToolError("get_network_request requires requestId or url");
-  return withPage3(driver, args.target, async (page) => {
+  return withPage4(driver, args.target, async (page) => {
     const buf = bufferFor(networkBuffers, page.info.id);
     const found = args.requestId ? buf.find((r) => r.requestId === args.requestId || r.request === args.requestId) : buf.find((r) => typeof r.url === "string" && r.url.includes(args.url));
     if (!found)
@@ -9936,7 +10588,7 @@ var mockSessions = new Map;
 async function mockRequest2(driver, args) {
   if (!args.urlPattern)
     throw new BidiToolError("mock_request requires a { urlPattern }");
-  return withPage3(driver, args.target, async (page) => {
+  return withPage4(driver, args.target, async (page) => {
     const existing = mockSessions.get(page.info.id);
     const rule = {
       urlPattern: args.urlPattern,
@@ -9984,7 +10636,7 @@ async function clearMocks2(driver, args = {}) {
     mockSessions.clear();
     return { cleared: n };
   }
-  return withPage3(driver, args.target, async (page) => {
+  return withPage4(driver, args.target, async (page) => {
     const existing = mockSessions.get(page.info.id);
     if (!existing)
       return { cleared: 0 };
@@ -10009,7 +10661,8 @@ var BIDI_ONLY_TOOLS = {
 var FIREFOX_TOOLS = {
   ...SHARED_TOOLS,
   ...BIDI_ONLY_TOOLS,
-  ...LEASE_TOOLS
+  ...LEASE_TOOLS,
+  extract_page: extractPage
 };
 
 // src/mcp.ts
@@ -10029,7 +10682,8 @@ var TOOL_GROUPS = [
   "leases",
   "permissions",
   "dialogs",
-  "downloads"
+  "downloads",
+  "extraction"
 ];
 var GROUP_TOOLS = {
   core: [
@@ -10053,7 +10707,9 @@ var GROUP_TOOLS = {
     "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"],
@@ -10072,7 +10728,8 @@ var GROUP_TOOLS = {
   leases: ["claim_page", "release_page", "list_leases"],
   permissions: ["grant_permissions"],
   dialogs: ["handle_dialog"],
-  downloads: ["wait_for_download"]
+  downloads: ["wait_for_download"],
+  extraction: ["extract_page"]
 };
 var TOOL_GROUP = {};
 for (const group of TOOL_GROUPS) {
@@ -10278,6 +10935,26 @@ var TOOL_DOCS = {
       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: {
@@ -10569,11 +11246,28 @@ var TOOL_DOCS = {
   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."
+    }
   }
 };
 
 // src/version.ts
-var VERSION = "2.2.0";
+var VERSION = "2.5.0";
 
 // src/mcp.ts
 var { kind: BROWSER, endpoint: FIREFOX_ENDPOINT } = resolveBackend(process.argv.slice(2));