cdp-toolkit 1.9.0 → 1.9.1

package/dist/mcp.js

@@ -406,6 +406,12 @@ async function resolveLiveLabel(backend, label, liveIds) {
 
 // src/workers.ts
 var WORKER_SELECTOR_PREFIX = "worker:";
+var WORKER_CAPABLE_TOOLS = [
+  "evaluate_script",
+  "list_network_requests",
+  "get_network_request",
+  "list_console_messages"
+];
 var WORKER_TARGET_TYPES = new Set(["service_worker", "shared_worker"]);
 function isWorkerSelector(selector) {
   return typeof selector === "string" && selector.startsWith(WORKER_SELECTOR_PREFIX);
@@ -424,8 +430,18 @@ function resolveWorkerTargets(targets, needle) {
   };
 }
 var WORKER_EMPTY_NEEDLE_MESSAGE = "'worker:' needs a substring of the worker's url, e.g. worker:<extension-id> or worker:background.js";
-var WORKER_SELECTOR_UNSUPPORTED_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, which this backend cannot address " + "(WebDriver BiDi has no extension service-worker target; Capability 'worker.targets' is Chrome-only). " + "Use --browser chrome to evaluate in an extension's background worker.";
-var WORKER_SELECTOR_PAGE_ONLY_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, and this tool is page-only " + "(closing, selecting or releasing a worker is meaningless). evaluate_script is the one tool that " + "accepts a worker: target.";
+var WORKER_SELECTOR_UNSUPPORTED_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, which this backend cannot address " + "(WebDriver BiDi has no extension service-worker target; Capability 'worker.targets' is Chrome-only). " + "Use --browser chrome to evaluate in, or record console/network from, an extension's background worker.";
+var WORKER_SELECTOR_PAGE_ONLY_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, and this tool is page-only " + "(closing, selecting or releasing a worker is meaningless). The tools that accept a worker: target are " + `${WORKER_CAPABLE_TOOLS.join(", ")}.`;
+function workerWakeMisuseMessage(kind) {
+  if (kind === "not-a-worker-selector") {
+    return "'wake' only applies to a target of the form 'worker:<substring>'. A page is never asleep, and a bare " + "worker target id cannot be woken either: Chrome destroys the target when an MV3 worker is evicted and " + "mints a NEW id when it restarts, so only the url-substring form can name a worker that is not running.";
+  }
+  return "'wake' only applies when a capture is being started (reload:true, or includeBody with url). Reading an " + "existing buffer cannot use a woken worker: a restarted MV3 worker gets a NEW target id, and the buffer is " + "keyed by id, so the wake would hand back an empty capture. Re-run with reload:true to record a fresh one.";
+}
+function workerBufferReadMissMessage(needle, liveWorkers) {
+  const running = liveWorkers.length ? ` (running workers: ${urlList(liveWorkers)})` : " (no workers are running)";
+  return `no running worker whose url contains '${needle}'${running}. ` + "An MV3 extension service worker is idle-evicted after seconds of inactivity and then appears in NO target " + "listing, so this is usually a sleeping worker rather than a wrong substring. This call only READS a buffer " + "recorded earlier, and that buffer is keyed by the worker's target id, which Chrome re-mints on restart — so " + "re-run with reload:true, which starts the worker and records a fresh capture window.";
+}
 function urlList(workers) {
   return workers.map((w) => w.url).join(", ");
 }
@@ -2840,6 +2856,31 @@ function captureFile(targetId, captureId) {
 function delay2(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
+async function resolveRecorderTarget(target, opts) {
+  if (!isWorkerSelector(target))
+    return resolveTarget(target);
+  if (opts.capture)
+    return resolveWorkerSelector(target, { wake: opts.wake ?? true });
+  const needle = workerNeedle(target);
+  if (needle === "")
+    throw new CdpError(WORKER_EMPTY_NEEDLE_MESSAGE);
+  const { matches, liveWorkers } = resolveWorkerTargets(await listTargets(), needle);
+  if (matches.length > 1)
+    throw new CdpError(workerAmbiguityMessage(needle, matches));
+  if (matches.length === 1)
+    return matches[0];
+  throw new CdpError(workerBufferReadMissMessage(needle, liveWorkers));
+}
+function assertWakeApplies(target, wake, capture) {
+  if (wake === undefined)
+    return;
+  if (typeof wake !== "boolean")
+    throw new CdpError("'wake' must be a boolean");
+  if (!isWorkerSelector(target))
+    throw new CdpError(workerWakeMisuseMessage("not-a-worker-selector"));
+  if (!capture)
+    throw new CdpError(workerWakeMisuseMessage("read-only-call"));
+}
 var NETWORK_EVENTS = [
   "Network.requestWillBeSent",
   "Network.responseReceived",
@@ -2905,7 +2946,8 @@ async function startRecorder(target, opts = {}) {
   };
 }
 async function captureWindow(target, durationMs, opts = {}) {
-  const resolved = await resolveTarget(target);
+  const resolved = await resolveRecorderTarget(target, { capture: true, wake: opts.wake });
+  const isWorker = isWorkerTargetType(resolved.type);
   const captureId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
   const file = captureFile(resolved.id, captureId);
   const rec = await startRecorder(resolved.id, {
@@ -2915,13 +2957,16 @@ async function captureWindow(target, durationMs, opts = {}) {
     file,
     timeoutMs: opts.timeoutMs
   });
-  await rec.conn.send("Page.enable");
-  await rec.conn.send("Page.reload", { ignoreCache: false });
+  if (!isWorker) {
+    await rec.conn.send("Page.enable");
+    await rec.conn.send("Page.reload", { ignoreCache: false });
+  }
   await delay2(durationMs);
   return {
     file: rec.file,
     conn: rec.conn,
     resolved: { id: rec.target.id, url: rec.target.url, title: rec.target.title },
+    mode: isWorker ? "listen" : "reload",
     droppedWrites: rec.droppedWrites,
     flush: () => rec.flush(),
     async stop() {
@@ -3021,8 +3066,9 @@ async function readConsoleEntries(file) {
   return out;
 }
 async function listConsoleMessages(args = {}) {
+  assertWakeApplies(args.target, args.wake, args.reload === true);
   if (args.reload) {
-    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS);
+    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS, { wake: args.wake });
     await cap.stop();
     const messages2 = await readConsoleEntries(cap.file);
     return {
@@ -3032,7 +3078,7 @@ async function listConsoleMessages(args = {}) {
       droppedWrites: cap.droppedWrites()
     };
   }
-  const target = await resolveTarget(args.target);
+  const target = await resolveRecorderTarget(args.target, { capture: false });
   const messages = await readConsoleEntries(recFile(target.id));
   return {
     target: { id: target.id, url: target.url, title: target.title },
@@ -3041,7 +3087,7 @@ async function listConsoleMessages(args = {}) {
   };
 }
 async function getConsoleMessage(args = {}) {
-  const target = await resolveTarget(args.target);
+  const target = await resolveRecorderTarget(args.target, { capture: false });
   const messages = await readConsoleEntries(recFile(target.id));
   const index = args.index ?? 0;
   const entry = messages[index];
@@ -3139,14 +3185,15 @@ async function listNetworkRequests(args = {}) {
   let file;
   let resolved;
   let droppedWrites;
+  assertWakeApplies(args.target, args.wake, args.reload === true);
   if (args.reload) {
-    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2);
+    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2, { wake: args.wake });
     await cap.stop();
     file = cap.file;
     resolved = cap.resolved;
     droppedWrites = cap.droppedWrites();
   } else {
-    const target = await resolveTarget(args.target);
+    const target = await resolveRecorderTarget(args.target, { capture: false });
     file = recFile(target.id);
     resolved = { id: target.id, url: target.url, title: target.title };
   }
@@ -3167,8 +3214,9 @@ async function getNetworkRequest(args = {}) {
     return requests.find((r) => r.url.includes(args.url));
   };
   const describeSelector = () => args.requestId ? `requestId ${args.requestId}` : `url ~ '${args.url}'`;
+  assertWakeApplies(args.target, args.wake, Boolean(args.includeBody && args.url));
   if (args.includeBody && args.url) {
-    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2);
+    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2, { wake: args.wake });
     try {
       await cap.flush();
       const match2 = (await readNetworkRequests(cap.file)).find((r) => r.url.includes(args.url));
@@ -3185,7 +3233,7 @@ async function getNetworkRequest(args = {}) {
       await cap.stop();
     }
   }
-  const target = await resolveTarget(args.target);
+  const target = await resolveRecorderTarget(args.target, { capture: false });
   const match = pick(await readNetworkRequests(recFile(target.id)));
   if (!match) {
     throw new CdpError(`no network request matched ${describeSelector()}; run list_network_requests with reload:true first` + (args.includeBody ? `, then fetch the body with the url selector (reload re-mints requestIds)` : ``));
@@ -4481,7 +4529,7 @@ var MANIFEST = [
   },
   {
     name: "evaluate_script",
-    description: "Run arbitrary JavaScript in the target page's main-world context over raw CDP and return the evaluated value (returnByValue). With no 'args' the 'expression' is evaluated as a raw expression; when 'args' is provided 'expression' must be a function literal (arrow or classic) invoked on globalThis with the args passed positionally. A thrown exception surfaces as an error; non-serializable returns (DOM nodes, functions) come back as their CDP description string. Pass 'savePath' to write the evaluated value to a JSON file instead: the response then carries only {path,bytes,type,target} and the value itself never appears in it, in any form. That is the way to read a credential (a JWT or session token out of localStorage, for example) without putting the secret into the caller's transcript. This is also the one tool that can evaluate inside an MV3 extension's background SERVICE WORKER rather than a page: pass target 'worker:<extension-id>' (Chrome only) and read chrome.storage.local, chrome.runtime and the worker's own globals directly, with an idle-evicted worker started for you first (see 'wake').",
+    description: "Run arbitrary JavaScript in the target page's main-world context over raw CDP and return the evaluated value (returnByValue). With no 'args' the 'expression' is evaluated as a raw expression; when 'args' is provided 'expression' must be a function literal (arrow or classic) invoked on globalThis with the args passed positionally. A thrown exception surfaces as an error; non-serializable returns (DOM nodes, functions) come back as their CDP description string. Pass 'savePath' to write the evaluated value to a JSON file instead: the response then carries only {path,bytes,type,target} and the value itself never appears in it, in any form. That is the way to read a credential (a JWT or session token out of localStorage, for example) without putting the secret into the caller's transcript. This is the one tool that can EVALUATE inside an MV3 extension's background SERVICE WORKER rather than a page (list_network_requests/get_network_request/list_console_messages OBSERVE one): pass target 'worker:<extension-id>' (Chrome only) and read chrome.storage.local, chrome.runtime and the worker's own globals directly, with an idle-evicted worker started for you first (see 'wake').",
     inputSchema: {
       type: "object",
       properties: {
@@ -4491,7 +4539,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Page selector: 'active' (or omit) -> first page-type target | '<32-hex targetId>' -> exact target by id | 'index:N' -> Nth page-type target (0-based) | 'url:<substring>' -> first page whose url contains substring | 'title:<substring>' -> first page whose title contains substring | 'label:<name>' -> the page-type target with exactly this label (checked against the origin ledger and live leases) | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js) and read chrome.storage.local from it. The worker: arm is CHROME-ONLY (Capability 'worker.targets') and is accepted by this tool only; an MV3 worker that has been idle-evicted is started automatically first, see 'wake'."
+          description: "Page selector: 'active' (or omit) -> first page-type target | '<32-hex targetId>' -> exact target by id | 'index:N' -> Nth page-type target (0-based) | 'url:<substring>' -> first page whose url contains substring | 'title:<substring>' -> first page whose title contains substring | 'label:<name>' -> the page-type target with exactly this label (checked against the origin ledger and live leases) | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js) and read chrome.storage.local from it. The worker: arm is CHROME-ONLY (Capability 'worker.targets') and is accepted by four tools only — evaluate_script, list_network_requests, get_network_request and list_console_messages — never as universal grammar; an MV3 worker that has been idle-evicted is started automatically first, see 'wake'."
         },
         wake: {
           type: "boolean",
@@ -5412,7 +5460,7 @@ var MANIFEST = [
   },
   {
     name: "list_console_messages",
-    description: "Read console output (logs, warnings, exceptions) captured for the target page. By default reads the target's existing shared buffer and returns parsed console entries (empty if no capture has run); with reload:true it reloads the page and records a fresh capture window (both console+network) so a network reload never wipes console history.",
+    description: "Read console output (logs, warnings, exceptions) captured for the target page. By default reads the target's existing shared buffer and returns parsed console entries (empty if no capture has run); with reload:true it reloads the page and records a fresh capture window (both console+network) so a network reload never wipes console history. SERVICE WORKERS (Chrome only, Capability 'worker.targets'): pass target 'worker:<extension-id>' to watch an MV3 extension's BACKGROUND SERVICE WORKER. The outbound request that worker makes to your backend is recorded from CDP's Network domain on the worker's own session, which observes what the code ACTUALLY SENT and so needs neither of the two tricks a caller reaches for first. Both of those fail for ordinary JavaScript reasons rather than service-worker ones: a value bound at module top level is not visible from evaluate_script's global scope (plain lexical scoping, exactly the same in a page), and assigning self.fetch cannot rebind a fetch reference the module already captured. A worker's console.log arrives as Runtime.consoleAPICalled on its own session. A worker capture has no reload to drive it: reload:true means 'listen for durationMs while the worker runs', so trigger the worker's work (another tool call, an extension message, an alarm) during the window; a worker woken by the call has already run its top-level code by the time the recorder attaches, so a request it makes at startup can be missed. SIDE EFFECT, deliberate and documented: the recording holds a CDP session on the worker, and that KEEPS THE WORKER ALIVE for as long as the capture runs — an MV3 worker is otherwise idle-evicted within seconds — and Chrome resumes evicting it once the capture stops.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5422,15 +5470,19 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>' | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js). The worker: arm is CHROME-ONLY (Capability 'worker.targets'), is refused on Firefox, and a bare worker target id works too."
         },
         reload: {
           type: "boolean",
-          description: "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer)."
+          description: "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer). With a worker: target there is nothing to reload: the window records for durationMs while the worker runs, and the session it holds keeps that worker from being idle-evicted until the capture stops."
         },
         durationMs: {
           type: "number",
           description: "Capture window for reload mode, in milliseconds. Default 2500."
+        },
+        wake: {
+          type: "boolean",
+          description: "Worker targets only, and only when a capture is being started (reload:true). Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so the capture asks Chrome to start it (ServiceWorker.startWorker over a page session) and then re-reads the target list to confirm it actually came up. Pass false to fail fast instead of starting anything. Rejected rather than ignored on a page target, on a bare target id (Chrome re-mints a worker's target id when it restarts, so only the url-substring form can name a worker that is not running), and on a read-only call (the buffer is keyed by target id, so a woken worker's buffer would be empty)."
         }
       },
       required: [],
@@ -5462,7 +5514,7 @@ var MANIFEST = [
   },
   {
     name: "list_network_requests",
-    description: "Return correlated network request rows (one per requestId, with status/headers/state) for the target page. By default reads the target's existing buffer; with reload:true it reloads and records a fresh both-domains capture window. Use filterUrl to keep only requests whose URL contains a substring.",
+    description: "Return correlated network request rows (one per requestId, with status/headers/state) for the target page. By default reads the target's existing buffer; with reload:true it reloads and records a fresh both-domains capture window. Use filterUrl to keep only requests whose URL contains a substring. SERVICE WORKERS (Chrome only, Capability 'worker.targets'): pass target 'worker:<extension-id>' to watch an MV3 extension's BACKGROUND SERVICE WORKER. The outbound request that worker makes to your backend is recorded from CDP's Network domain on the worker's own session, which observes what the code ACTUALLY SENT and so needs neither of the two tricks a caller reaches for first. Both of those fail for ordinary JavaScript reasons rather than service-worker ones: a value bound at module top level is not visible from evaluate_script's global scope (plain lexical scoping, exactly the same in a page), and assigning self.fetch cannot rebind a fetch reference the module already captured. A worker capture has no reload to drive it: reload:true means 'listen for durationMs while the worker runs', so trigger the worker's work (another tool call, an extension message, an alarm) during the window; a worker woken by the call has already run its top-level code by the time the recorder attaches, so a request it makes at startup can be missed. SIDE EFFECT, deliberate and documented: the recording holds a CDP session on the worker, and that KEEPS THE WORKER ALIVE for as long as the capture runs — an MV3 worker is otherwise idle-evicted within seconds — and Chrome resumes evicting it once the capture stops.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5472,11 +5524,11 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>' | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js). The worker: arm is CHROME-ONLY (Capability 'worker.targets'), is refused on Firefox, and a bare worker target id works too."
         },
         reload: {
           type: "boolean",
-          description: "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer)."
+          description: "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer). With a worker: target there is nothing to reload: the window records for durationMs while the worker runs, and the session it holds keeps that worker from being idle-evicted until the capture stops."
         },
         durationMs: {
           type: "number",
@@ -5485,6 +5537,10 @@ var MANIFEST = [
         filterUrl: {
           type: "string",
           description: "Only return requests whose URL contains this substring."
+        },
+        wake: {
+          type: "boolean",
+          description: "Worker targets only, and only when a capture is being started (reload:true). Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so the capture asks Chrome to start it (ServiceWorker.startWorker over a page session) and then re-reads the target list to confirm it actually came up. Pass false to fail fast instead of starting anything. Rejected rather than ignored on a page target, on a bare target id (Chrome re-mints a worker's target id when it restarts, so only the url-substring form can name a worker that is not running), and on a read-only call (the buffer is keyed by target id, so a woken worker's buffer would be empty)."
         }
       },
       required: [],
@@ -5493,7 +5549,7 @@ var MANIFEST = [
   },
   {
     name: "get_network_request",
-    description: "Return one network request (matched by exact requestId, else by url substring) including status/headers. Requires at least one of requestId or url (throws otherwise). With includeBody:true the body fetch drives a fresh reload capture and is matched by url ONLY (reload re-mints requestIds, so a carried-over requestId cannot fetch a body, so it returns metadata plus bodyUnavailableReason).",
+    description: "Return one network request (matched by exact requestId, else by url substring) including status/headers. Requires at least one of requestId or url (throws otherwise). With includeBody:true the body fetch drives a fresh capture (a reload for a page, a listen window for a worker) and is matched by url ONLY (a fresh capture re-mints requestIds, so a carried-over requestId cannot fetch a body, so it returns metadata plus bodyUnavailableReason). SERVICE WORKERS (Chrome only, Capability 'worker.targets'): pass target 'worker:<extension-id>' to watch an MV3 extension's BACKGROUND SERVICE WORKER. The outbound request that worker makes to your backend is recorded from CDP's Network domain on the worker's own session, which observes what the code ACTUALLY SENT and so needs neither of the two tricks a caller reaches for first. Both of those fail for ordinary JavaScript reasons rather than service-worker ones: a value bound at module top level is not visible from evaluate_script's global scope (plain lexical scoping, exactly the same in a page), and assigning self.fetch cannot rebind a fetch reference the module already captured. A worker capture has no reload to drive it: reload:true means 'listen for durationMs while the worker runs', so trigger the worker's work (another tool call, an extension message, an alarm) during the window; a worker woken by the call has already run its top-level code by the time the recorder attaches, so a request it makes at startup can be missed. SIDE EFFECT, deliberate and documented: the recording holds a CDP session on the worker, and that KEEPS THE WORKER ALIVE for as long as the capture runs — an MV3 worker is otherwise idle-evicted within seconds — and Chrome resumes evicting it once the capture stops.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5503,7 +5559,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>' | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js). The worker: arm is CHROME-ONLY (Capability 'worker.targets'), is refused on Firefox, and a bare worker target id works too."
         },
         requestId: {
           type: "string",
@@ -5520,6 +5576,10 @@ var MANIFEST = [
         durationMs: {
           type: "number",
           description: "Capture window for the reload-driven body fetch, in milliseconds. Default 2500."
+        },
+        wake: {
+          type: "boolean",
+          description: "Worker targets only, and only when a capture is being started (includeBody together with url). Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so the capture asks Chrome to start it (ServiceWorker.startWorker over a page session) and then re-reads the target list to confirm it actually came up. Pass false to fail fast instead of starting anything. Rejected rather than ignored on a page target, on a bare target id (Chrome re-mints a worker's target id when it restarts, so only the url-substring form can name a worker that is not running), and on a read-only call (the buffer is keyed by target id, so a woken worker's buffer would be empty)."
         }
       },
       required: [],
@@ -7643,6 +7703,11 @@ async function withPage3(driver, target, fn) {
 }
 var consoleBuffers = new Map;
 var networkBuffers = new Map;
+function refuseWorkerSelector(driver, target) {
+  if (isWorkerSelector(target) && !driver.capabilities.has("worker.targets")) {
+    throw new BidiToolError(WORKER_SELECTOR_UNSUPPORTED_MESSAGE);
+  }
+}
 function bufferFor(map, id) {
   let b = map.get(id);
   if (!b) {
@@ -7671,6 +7736,7 @@ async function captureFresh(page, durationMs) {
   }
 }
 async function listConsoleMessages2(driver, args = {}) {
+  refuseWorkerSelector(driver, args.target);
   return withPage3(driver, args.target, async (page) => {
     if (args.reload)
       await captureFresh(page, args.durationMs ?? 2500);
@@ -7679,6 +7745,7 @@ async function listConsoleMessages2(driver, args = {}) {
   });
 }
 async function getConsoleMessage2(driver, args = {}) {
+  refuseWorkerSelector(driver, args.target);
   return withPage3(driver, args.target, async (page) => {
     const buf = bufferFor(consoleBuffers, page.info.id);
     const idx = args.index ?? 0;
@@ -7689,6 +7756,7 @@ async function getConsoleMessage2(driver, args = {}) {
   });
 }
 async function listNetworkRequests2(driver, args = {}) {
+  refuseWorkerSelector(driver, args.target);
   return withPage3(driver, args.target, async (page) => {
     if (args.reload)
       await captureFresh(page, args.durationMs ?? 2500);
@@ -7699,6 +7767,7 @@ async function listNetworkRequests2(driver, args = {}) {
   });
 }
 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) => {
@@ -7790,7 +7859,7 @@ var FIREFOX_TOOLS = {
 };
 
 // src/mcp.ts
-var VERSION = "1.9.0";
+var VERSION = "1.9.1";
 var BROWSER = resolveBrowserKind(stripBrowserFlag(process.argv.slice(2)));
 var AVAILABILITY = toolAvailability(BROWSER);
 var AVAILABLE_NAMES = new Set(AVAILABILITY.available);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-toolkit",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "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.",
   "type": "module",
   "license": "MIT",

package/src/bidi-tools.ts

@@ -10,6 +10,7 @@
 import type { BrowserDriver, InterceptRule, PageDriver, PageInfo } from "./driver.ts";
 import { selectRule, buildFulfillParams, effectiveAction } from "./tools/network_mock.ts";
 import type { TargetSelector } from "./types.ts";
+import { isWorkerSelector, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "./workers.ts";
 
 class BidiToolError extends Error {}
 
@@ -33,6 +34,22 @@ async function withPage<T>(driver: BrowserDriver, target: TargetSelector | undef
 const consoleBuffers = new Map<string, Array<Record<string, unknown>>>();
 const networkBuffers = new Map<string, Array<Record<string, unknown>>>();
 
+/**
+ * Refuse the Chrome-only `worker:<substring>` arm BEFORE a browser is launched.
+ *
+ * pickContext already refuses it (bidi/driver.ts), but only after driver.page()
+ * has dialed — and on Firefox that means LAUNCHING a browser for a call that
+ * cannot possibly succeed. The gate is written as a capability check rather than
+ * "this file is the BiDi one" so it stays true if a future BiDi driver ever
+ * gains the capability, and the message is the shared one, so the teaching does
+ * not fork.
+ */
+function refuseWorkerSelector(driver: BrowserDriver, target: TargetSelector): void {
+  if (isWorkerSelector(target) && !driver.capabilities.has("worker.targets")) {
+    throw new BidiToolError(WORKER_SELECTOR_UNSUPPORTED_MESSAGE);
+  }
+}
+
 function bufferFor(map: Map<string, Array<Record<string, unknown>>>, id: string): Array<Record<string, unknown>> {
   let b = map.get(id);
   if (!b) { b = []; map.set(id, b); }
@@ -59,6 +76,7 @@ export async function listConsoleMessages(
   driver: BrowserDriver,
   args: { target?: TargetSelector; reload?: boolean; durationMs?: number } = {},
 ): Promise<{ messages: Array<Record<string, unknown>>; count: number }> {
+  refuseWorkerSelector(driver, args.target);
   return withPage(driver, args.target, async (page) => {
     if (args.reload) await captureFresh(page, args.durationMs ?? 2500);
     const buf = bufferFor(consoleBuffers, page.info.id);
@@ -70,6 +88,7 @@ export async function getConsoleMessage(
   driver: BrowserDriver,
   args: { target?: TargetSelector; index?: number } = {},
 ): Promise<Record<string, unknown>> {
+  refuseWorkerSelector(driver, args.target);
   return withPage(driver, args.target, async (page) => {
     const buf = bufferFor(consoleBuffers, page.info.id);
     const idx = args.index ?? 0;
@@ -83,6 +102,7 @@ export async function listNetworkRequests(
   driver: BrowserDriver,
   args: { target?: TargetSelector; reload?: boolean; durationMs?: number; filterUrl?: string } = {},
 ): Promise<{ requests: Array<Record<string, unknown>>; count: number }> {
+  refuseWorkerSelector(driver, args.target);
   return withPage(driver, args.target, async (page) => {
     if (args.reload) await captureFresh(page, args.durationMs ?? 2500);
     let buf = bufferFor(networkBuffers, page.info.id);
@@ -95,6 +115,7 @@ export async function getNetworkRequest(
   driver: BrowserDriver,
   args: { target?: TargetSelector; requestId?: string; url?: string } = {},
 ): Promise<Record<string, unknown>> {
+  refuseWorkerSelector(driver, args.target);
   if (!args.requestId && !args.url) throw new BidiToolError("get_network_request requires requestId or url");
   return withPage(driver, args.target, async (page) => {
     const buf = bufferFor(networkBuffers, page.info.id);

package/src/cli.ts

@@ -49,8 +49,10 @@ zero behavior change for existing users). Firefox is LAUNCHED per invocation (it
 to), used for exactly one tool call, then disposed before the process exits.
 
 Target selector grammar: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>
-  plus worker:<substr> for evaluate_script ONLY (Chrome only): an MV3 extension's background service
-  worker, e.g. worker:<extension-id>. An idle-evicted worker is started first unless wake:false.
+  plus worker:<substr> (Chrome only) for evaluate_script, list_network_requests, get_network_request
+  and list_console_messages ONLY: an MV3 extension's background service worker, e.g.
+  worker:<extension-id>. An idle-evicted worker is started first unless wake:false. Recording a
+  worker keeps it alive for the length of the capture.
 Leases: pass --lease <token> to act on a tab another agent claimed with claim_page (MCP only).
 Run list_leases to see who holds what; release_page --lease <token> gives a lease back.
 Run with --list to print every tool name available under the selected backend.

package/src/manifest.ts

@@ -204,7 +204,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "evaluate_script",
-    "description": "Run arbitrary JavaScript in the target page's main-world context over raw CDP and return the evaluated value (returnByValue). With no 'args' the 'expression' is evaluated as a raw expression; when 'args' is provided 'expression' must be a function literal (arrow or classic) invoked on globalThis with the args passed positionally. A thrown exception surfaces as an error; non-serializable returns (DOM nodes, functions) come back as their CDP description string. Pass 'savePath' to write the evaluated value to a JSON file instead: the response then carries only {path,bytes,type,target} and the value itself never appears in it, in any form. That is the way to read a credential (a JWT or session token out of localStorage, for example) without putting the secret into the caller's transcript. This is also the one tool that can evaluate inside an MV3 extension's background SERVICE WORKER rather than a page: pass target 'worker:<extension-id>' (Chrome only) and read chrome.storage.local, chrome.runtime and the worker's own globals directly, with an idle-evicted worker started for you first (see 'wake').",
+    "description": "Run arbitrary JavaScript in the target page's main-world context over raw CDP and return the evaluated value (returnByValue). With no 'args' the 'expression' is evaluated as a raw expression; when 'args' is provided 'expression' must be a function literal (arrow or classic) invoked on globalThis with the args passed positionally. A thrown exception surfaces as an error; non-serializable returns (DOM nodes, functions) come back as their CDP description string. Pass 'savePath' to write the evaluated value to a JSON file instead: the response then carries only {path,bytes,type,target} and the value itself never appears in it, in any form. That is the way to read a credential (a JWT or session token out of localStorage, for example) without putting the secret into the caller's transcript. This is the one tool that can EVALUATE inside an MV3 extension's background SERVICE WORKER rather than a page (list_network_requests/get_network_request/list_console_messages OBSERVE one): pass target 'worker:<extension-id>' (Chrome only) and read chrome.storage.local, chrome.runtime and the worker's own globals directly, with an idle-evicted worker started for you first (see 'wake').",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -214,7 +214,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Page selector: 'active' (or omit) -> first page-type target | '<32-hex targetId>' -> exact target by id | 'index:N' -> Nth page-type target (0-based) | 'url:<substring>' -> first page whose url contains substring | 'title:<substring>' -> first page whose title contains substring | 'label:<name>' -> the page-type target with exactly this label (checked against the origin ledger and live leases) | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js) and read chrome.storage.local from it. The worker: arm is CHROME-ONLY (Capability 'worker.targets') and is accepted by this tool only; an MV3 worker that has been idle-evicted is started automatically first, see 'wake'."
+          "description": "Page selector: 'active' (or omit) -> first page-type target | '<32-hex targetId>' -> exact target by id | 'index:N' -> Nth page-type target (0-based) | 'url:<substring>' -> first page whose url contains substring | 'title:<substring>' -> first page whose title contains substring | 'label:<name>' -> the page-type target with exactly this label (checked against the origin ledger and live leases) | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js) and read chrome.storage.local from it. The worker: arm is CHROME-ONLY (Capability 'worker.targets') and is accepted by four tools only — evaluate_script, list_network_requests, get_network_request and list_console_messages — never as universal grammar; an MV3 worker that has been idle-evicted is started automatically first, see 'wake'."
         },
         "wake": {
           "type": "boolean",
@@ -1135,7 +1135,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "list_console_messages",
-    "description": "Read console output (logs, warnings, exceptions) captured for the target page. By default reads the target's existing shared buffer and returns parsed console entries (empty if no capture has run); with reload:true it reloads the page and records a fresh capture window (both console+network) so a network reload never wipes console history.",
+    "description": "Read console output (logs, warnings, exceptions) captured for the target page. By default reads the target's existing shared buffer and returns parsed console entries (empty if no capture has run); with reload:true it reloads the page and records a fresh capture window (both console+network) so a network reload never wipes console history. SERVICE WORKERS (Chrome only, Capability 'worker.targets'): pass target 'worker:<extension-id>' to watch an MV3 extension's BACKGROUND SERVICE WORKER. The outbound request that worker makes to your backend is recorded from CDP's Network domain on the worker's own session, which observes what the code ACTUALLY SENT and so needs neither of the two tricks a caller reaches for first. Both of those fail for ordinary JavaScript reasons rather than service-worker ones: a value bound at module top level is not visible from evaluate_script's global scope (plain lexical scoping, exactly the same in a page), and assigning self.fetch cannot rebind a fetch reference the module already captured. A worker's console.log arrives as Runtime.consoleAPICalled on its own session. A worker capture has no reload to drive it: reload:true means 'listen for durationMs while the worker runs', so trigger the worker's work (another tool call, an extension message, an alarm) during the window; a worker woken by the call has already run its top-level code by the time the recorder attaches, so a request it makes at startup can be missed. SIDE EFFECT, deliberate and documented: the recording holds a CDP session on the worker, and that KEEPS THE WORKER ALIVE for as long as the capture runs — an MV3 worker is otherwise idle-evicted within seconds — and Chrome resumes evicting it once the capture stops.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1145,15 +1145,19 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
+          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>' | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js). The worker: arm is CHROME-ONLY (Capability 'worker.targets'), is refused on Firefox, and a bare worker target id works too."
         },
         "reload": {
           "type": "boolean",
-          "description": "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer)."
+          "description": "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer). With a worker: target there is nothing to reload: the window records for durationMs while the worker runs, and the session it holds keeps that worker from being idle-evicted until the capture stops."
         },
         "durationMs": {
           "type": "number",
           "description": "Capture window for reload mode, in milliseconds. Default 2500."
+        },
+        "wake": {
+          "type": "boolean",
+          "description": "Worker targets only, and only when a capture is being started (reload:true). Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so the capture asks Chrome to start it (ServiceWorker.startWorker over a page session) and then re-reads the target list to confirm it actually came up. Pass false to fail fast instead of starting anything. Rejected rather than ignored on a page target, on a bare target id (Chrome re-mints a worker's target id when it restarts, so only the url-substring form can name a worker that is not running), and on a read-only call (the buffer is keyed by target id, so a woken worker's buffer would be empty)."
         }
       },
       "required": [],
@@ -1185,7 +1189,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "list_network_requests",
-    "description": "Return correlated network request rows (one per requestId, with status/headers/state) for the target page. By default reads the target's existing buffer; with reload:true it reloads and records a fresh both-domains capture window. Use filterUrl to keep only requests whose URL contains a substring.",
+    "description": "Return correlated network request rows (one per requestId, with status/headers/state) for the target page. By default reads the target's existing buffer; with reload:true it reloads and records a fresh both-domains capture window. Use filterUrl to keep only requests whose URL contains a substring. SERVICE WORKERS (Chrome only, Capability 'worker.targets'): pass target 'worker:<extension-id>' to watch an MV3 extension's BACKGROUND SERVICE WORKER. The outbound request that worker makes to your backend is recorded from CDP's Network domain on the worker's own session, which observes what the code ACTUALLY SENT and so needs neither of the two tricks a caller reaches for first. Both of those fail for ordinary JavaScript reasons rather than service-worker ones: a value bound at module top level is not visible from evaluate_script's global scope (plain lexical scoping, exactly the same in a page), and assigning self.fetch cannot rebind a fetch reference the module already captured. A worker capture has no reload to drive it: reload:true means 'listen for durationMs while the worker runs', so trigger the worker's work (another tool call, an extension message, an alarm) during the window; a worker woken by the call has already run its top-level code by the time the recorder attaches, so a request it makes at startup can be missed. SIDE EFFECT, deliberate and documented: the recording holds a CDP session on the worker, and that KEEPS THE WORKER ALIVE for as long as the capture runs — an MV3 worker is otherwise idle-evicted within seconds — and Chrome resumes evicting it once the capture stops.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1195,11 +1199,11 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
+          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>' | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js). The worker: arm is CHROME-ONLY (Capability 'worker.targets'), is refused on Firefox, and a bare worker target id works too."
         },
         "reload": {
           "type": "boolean",
-          "description": "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer)."
+          "description": "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer). With a worker: target there is nothing to reload: the window records for durationMs while the worker runs, and the session it holds keeps that worker from being idle-evicted until the capture stops."
         },
         "durationMs": {
           "type": "number",
@@ -1208,6 +1212,10 @@ export const MANIFEST: ToolSpec[] = [
         "filterUrl": {
           "type": "string",
           "description": "Only return requests whose URL contains this substring."
+        },
+        "wake": {
+          "type": "boolean",
+          "description": "Worker targets only, and only when a capture is being started (reload:true). Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so the capture asks Chrome to start it (ServiceWorker.startWorker over a page session) and then re-reads the target list to confirm it actually came up. Pass false to fail fast instead of starting anything. Rejected rather than ignored on a page target, on a bare target id (Chrome re-mints a worker's target id when it restarts, so only the url-substring form can name a worker that is not running), and on a read-only call (the buffer is keyed by target id, so a woken worker's buffer would be empty)."
         }
       },
       "required": [],
@@ -1216,7 +1224,7 @@ export const MANIFEST: ToolSpec[] = [
   },
   {
     "name": "get_network_request",
-    "description": "Return one network request (matched by exact requestId, else by url substring) including status/headers. Requires at least one of requestId or url (throws otherwise). With includeBody:true the body fetch drives a fresh reload capture and is matched by url ONLY (reload re-mints requestIds, so a carried-over requestId cannot fetch a body, so it returns metadata plus bodyUnavailableReason).",
+    "description": "Return one network request (matched by exact requestId, else by url substring) including status/headers. Requires at least one of requestId or url (throws otherwise). With includeBody:true the body fetch drives a fresh capture (a reload for a page, a listen window for a worker) and is matched by url ONLY (a fresh capture re-mints requestIds, so a carried-over requestId cannot fetch a body, so it returns metadata plus bodyUnavailableReason). SERVICE WORKERS (Chrome only, Capability 'worker.targets'): pass target 'worker:<extension-id>' to watch an MV3 extension's BACKGROUND SERVICE WORKER. The outbound request that worker makes to your backend is recorded from CDP's Network domain on the worker's own session, which observes what the code ACTUALLY SENT and so needs neither of the two tricks a caller reaches for first. Both of those fail for ordinary JavaScript reasons rather than service-worker ones: a value bound at module top level is not visible from evaluate_script's global scope (plain lexical scoping, exactly the same in a page), and assigning self.fetch cannot rebind a fetch reference the module already captured. A worker capture has no reload to drive it: reload:true means 'listen for durationMs while the worker runs', so trigger the worker's work (another tool call, an extension message, an alarm) during the window; a worker woken by the call has already run its top-level code by the time the recorder attaches, so a request it makes at startup can be missed. SIDE EFFECT, deliberate and documented: the recording holds a CDP session on the worker, and that KEEPS THE WORKER ALIVE for as long as the capture runs — an MV3 worker is otherwise idle-evicted within seconds — and Chrome resumes evicting it once the capture stops.",
     "inputSchema": {
       "type": "object",
       "properties": {
@@ -1226,7 +1234,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "target": {
           "type": "string",
-          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
+          "description": "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>' | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js). The worker: arm is CHROME-ONLY (Capability 'worker.targets'), is refused on Firefox, and a bare worker target id works too."
         },
         "requestId": {
           "type": "string",
@@ -1243,6 +1251,10 @@ export const MANIFEST: ToolSpec[] = [
         "durationMs": {
           "type": "number",
           "description": "Capture window for the reload-driven body fetch, in milliseconds. Default 2500."
+        },
+        "wake": {
+          "type": "boolean",
+          "description": "Worker targets only, and only when a capture is being started (includeBody together with url). Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so the capture asks Chrome to start it (ServiceWorker.startWorker over a page session) and then re-reads the target list to confirm it actually came up. Pass false to fail fast instead of starting anything. Rejected rather than ignored on a page target, on a bare target id (Chrome re-mints a worker's target id when it restarts, so only the url-substring form can name a worker that is not running), and on a read-only call (the buffer is keyed by target id, so a woken worker's buffer would be empty)."
         }
       },
       "required": [],

package/src/mcp.ts

@@ -24,7 +24,7 @@ import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, markLongLivedProcess, withLeaseScope } from "./leases.ts";
 
-const VERSION = "1.9.0";
+const VERSION = "1.9.1";
 
 // --browser is read once at startup (MCP has no per-call notion of backend): explicit flag,
 // else CDP_BROWSER env var, else "chrome" (zero behavior change for existing users/configs).