cdp-toolkit 1.8.0 → 1.9.1

package/dist/cli.js

@@ -278,6 +278,185 @@ async function listLeases(opts = {}) {
   return out;
 }
 
+// src/origins.ts
+import { mkdir as mkdir2, readFile as readFile2, readdir as readdir2, unlink as unlink2, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+function safeId2(id) {
+  return id.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+function originFile(backend, targetId) {
+  return join2(leaseDir(), `origin-${backend}-${safeId2(targetId)}.json`);
+}
+var ORIGIN_FILE_RE = /^origin-(chrome|firefox)-(.+)\.json$/;
+async function recordOrigin(backend, targetId, opts = {}) {
+  const record = {
+    backend,
+    targetId,
+    label: typeof opts.label === "string" && opts.label.length ? opts.label : defaultLabel(),
+    pid: process.pid,
+    createdAt: opts.now ?? Date.now()
+  };
+  const file = originFile(backend, targetId);
+  try {
+    await mkdir2(leaseDir(), { recursive: true });
+    try {
+      await writeFile2(file, JSON.stringify(record), { flag: "wx" });
+      return;
+    } catch (err) {
+      if (err.code !== "EEXIST")
+        throw err;
+    }
+    await unlink2(file).catch(() => {
+      return;
+    });
+    await writeFile2(file, JSON.stringify(record), { flag: "wx" });
+  } catch {}
+}
+async function readOrigin(backend, targetId) {
+  let raw;
+  try {
+    raw = await readFile2(originFile(backend, targetId), "utf8");
+  } catch {
+    return;
+  }
+  try {
+    const rec = JSON.parse(raw);
+    if (typeof rec?.targetId === "string" && typeof rec?.label === "string" && typeof rec?.createdAt === "number")
+      return rec;
+  } catch {}
+  return;
+}
+async function listOrigins(opts = {}) {
+  let names = [];
+  try {
+    names = await readdir2(leaseDir());
+  } catch {
+    return [];
+  }
+  const live = opts.liveIds === undefined ? undefined : new Set(opts.liveIds.map((id) => safeId2(id)));
+  const out = [];
+  for (const name of names) {
+    const parts = ORIGIN_FILE_RE.exec(name);
+    if (!parts)
+      continue;
+    const backend = parts[1];
+    const nameId = parts[2];
+    const scoped = live !== undefined && (opts.liveBackend === undefined || opts.liveBackend === backend);
+    if (scoped && !live.has(nameId)) {
+      await unlink2(join2(leaseDir(), name)).catch(() => {
+        return;
+      });
+      continue;
+    }
+    const fromName = { backend, targetId: nameId, label: "", pid: 0, createdAt: 0 };
+    let rec;
+    try {
+      rec = JSON.parse(await readFile2(join2(leaseDir(), name), "utf8"));
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT")
+        continue;
+      out.push({ ...fromName, unreadable: code ?? "unparseable" });
+      continue;
+    }
+    if (typeof rec?.targetId !== "string" || typeof rec?.label !== "string" || typeof rec?.createdAt !== "number") {
+      out.push({ ...fromName, unreadable: "unparseable" });
+      continue;
+    }
+    out.push({ backend: rec.backend, targetId: rec.targetId, label: rec.label, pid: rec.pid, createdAt: rec.createdAt });
+  }
+  return out;
+}
+async function originIndex(backend, liveIds) {
+  const rows = await listOrigins({ liveIds, liveBackend: backend }).catch(() => []);
+  const index = new Map;
+  for (const row of rows) {
+    if (row.backend !== backend)
+      continue;
+    index.set(row.targetId, row);
+  }
+  return index;
+}
+async function newTrackedPage(driver, backend, opts = {}) {
+  const page = await driver.newPage(opts.url);
+  await recordOrigin(backend, page.id, { label: opts.label });
+  return page;
+}
+async function resolveLiveLabel(backend, label, liveIds) {
+  const live = new Set(liveIds);
+  const [origins, leases] = await Promise.all([originIndex(backend), listLeases({ liveBackend: backend })]);
+  const knownLabels = new Set;
+  const matchIds = new Set;
+  for (const rec of origins.values()) {
+    if (rec.unreadable !== undefined || !live.has(rec.targetId))
+      continue;
+    knownLabels.add(rec.label);
+    if (rec.label === label)
+      matchIds.add(rec.targetId);
+  }
+  for (const rec of leases) {
+    if (rec.backend !== backend || rec.unreadable !== undefined || !live.has(rec.targetId))
+      continue;
+    knownLabels.add(rec.label);
+    if (rec.label === label)
+      matchIds.add(rec.targetId);
+  }
+  return { matchIds: [...matchIds], knownLabels: [...knownLabels].sort() };
+}
+
+// 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);
+}
+function workerNeedle(selector) {
+  return selector.slice(WORKER_SELECTOR_PREFIX.length);
+}
+function isWorkerTargetType(type) {
+  return type !== undefined && WORKER_TARGET_TYPES.has(type);
+}
+function resolveWorkerTargets(targets, needle) {
+  const liveWorkers = targets.filter((t) => isWorkerTargetType(t.type));
+  return {
+    matches: needle === "" ? [] : liveWorkers.filter((t) => t.url.includes(needle)),
+    liveWorkers
+  };
+}
+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, 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(", ");
+}
+function workerAmbiguityMessage(needle, matches) {
+  return `'worker:${needle}' matches more than one running worker: ` + matches.map((m) => `${m.url} (${m.id})`).join(", ") + ". Narrow the substring, or pass the worker's target id directly.";
+}
+function workerMissMessage(needle, opts) {
+  const running = opts.liveWorkers?.length ? ` (running workers: ${urlList(opts.liveWorkers)})` : " (no workers are running)";
+  if (!opts.wakeAttempted) {
+    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. You passed wake:false; " + "wake:true (the default) asks Chrome to start it first.";
+  }
+  const scopes = opts.registeredScopes?.length ? ` Registered service-worker scopes in this browser: ${opts.registeredScopes.join(", ")}.` : " No service-worker registrations were reported by this browser at all.";
+  return `no worker whose url contains '${needle}' could be reached${running}. ` + `A start was requested (wake:true) and no matching worker appeared.${scopes} ` + "If the extension is installed but its worker never starts, check the worker script for a top-level throw.";
+}
+
 // src/client.ts
 var BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
 var DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15000);
@@ -433,11 +612,13 @@ async function browserWsUrl() {
 }
 async function resolveTarget(selector, opts = {}) {
   const targets = await listTargets();
-  const hit = pickTarget(targets, selector);
+  const hit = await pickTarget(targets, selector);
+  if (isWorkerTargetType(hit.type))
+    return hit;
   await assertLeaseOk("chrome", hit.id, { lease: opts.lease, url: hit.url, title: hit.title });
   return hit;
 }
-function pickTarget(targets, selector) {
+async function pickTarget(targets, selector) {
   const pages = targets.filter((t) => t.type === "page");
   if (!selector || selector === "active") {
     if (!pages.length)
@@ -464,6 +645,30 @@ function pickTarget(targets, selector) {
       throw new CdpError(`no page title containing '${needle}'`);
     return hit;
   }
+  if (selector.startsWith("label:")) {
+    const label = selector.slice(6);
+    const { matchIds, knownLabels } = await resolveLiveLabel("chrome", label, pages.map((t) => t.id));
+    if (matchIds.length > 1) {
+      throw new CdpError(`label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`);
+    }
+    if (matchIds.length === 1) {
+      const hit = pages.find((t) => t.id === matchIds[0]);
+      if (hit)
+        return hit;
+    }
+    throw new CdpError(knownLabels.length ? `no live target with label '${label}' (labels currently in use: ${knownLabels.join(", ")})` : `no live target with label '${label}' (no labels are currently assigned to any open target)`);
+  }
+  if (isWorkerSelector(selector)) {
+    const needle = workerNeedle(selector);
+    if (needle === "")
+      throw new CdpError(WORKER_EMPTY_NEEDLE_MESSAGE);
+    const { matches, liveWorkers } = resolveWorkerTargets(targets, needle);
+    if (matches.length > 1)
+      throw new CdpError(workerAmbiguityMessage(needle, matches));
+    if (matches.length === 1)
+      return matches[0];
+    throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers }));
+  }
   const byId = targets.find((t) => t.id === selector);
   if (!byId)
     throw new CdpError(`no target with id '${selector}'`);
@@ -653,6 +858,91 @@ async function resolveUid(conn, uid) {
   return { objectId: object.objectId };
 }
 
+// src/cdp/workers.ts
+var INVENTORY_FIRST_EVENT_MS = 1500;
+var INVENTORY_SETTLE_MS = 250;
+var WAKE_POLL_MS = 300;
+var WAKE_POLL_ATTEMPTS = 30;
+var NO_HOST_PAGE_MESSAGE = "cannot start a service worker: the ServiceWorker CDP domain is only reachable over a page session, " + "and this browser has no page target open. Open any tab (new_page) and retry — the tab does not have " + "to belong to the extension.";
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function requestWorkerStart(needle) {
+  const conn = await openBrowser();
+  try {
+    const host = (await listTargets()).find((t) => t.type === "page");
+    if (!host)
+      throw new CdpError(NO_HOST_PAGE_MESSAGE);
+    const { sessionId } = await conn.send("Target.attachToTarget", {
+      targetId: host.id,
+      flatten: true
+    });
+    if (!sessionId)
+      throw new CdpError("could not attach a session to host the ServiceWorker domain");
+    const scopeById = new Map;
+    const versions = [];
+    conn.on("ServiceWorker.workerRegistrationUpdated", (params) => {
+      for (const r of params.registrations ?? []) {
+        if (r.isDeleted === true)
+          continue;
+        scopeById.set(String(r.registrationId), String(r.scopeURL ?? ""));
+      }
+    });
+    conn.on("ServiceWorker.workerVersionUpdated", (params) => {
+      for (const v of params.versions ?? []) {
+        versions.push({ registrationId: String(v.registrationId), scriptURL: String(v.scriptURL ?? "") });
+      }
+    });
+    await conn.send("ServiceWorker.enable", {}, { sessionId });
+    await conn.waitFor("ServiceWorker.workerVersionUpdated", undefined, INVENTORY_FIRST_EVENT_MS).catch(() => {
+      return;
+    });
+    await sleep(INVENTORY_SETTLE_MS);
+    const scopes = [...new Set(scopeById.values())].filter((s) => s.length > 0).sort();
+    const matched = new Set;
+    for (const v of versions) {
+      const scope = scopeById.get(v.registrationId);
+      if (scope === undefined)
+        continue;
+      if (v.scriptURL.includes(needle) || scope.includes(needle))
+        matched.add(scope);
+    }
+    if (matched.size === 0)
+      return { startRequested: false, scopes };
+    if (matched.size > 1) {
+      throw new CdpError(`'worker:${needle}' matches more than one registered service-worker scope: ${[...matched].sort().join(", ")}. ` + "Narrow the substring.");
+    }
+    await conn.send("ServiceWorker.startWorker", { scopeURL: [...matched][0] }, { sessionId });
+    return { startRequested: true, scopes };
+  } finally {
+    conn.close();
+  }
+}
+async function resolveWorkerSelector(selector, opts) {
+  const needle = workerNeedle(selector);
+  if (needle === "")
+    throw new CdpError(WORKER_EMPTY_NEEDLE_MESSAGE);
+  const first = resolveWorkerTargets(await listTargets(), needle);
+  if (first.matches.length > 1)
+    throw new CdpError(workerAmbiguityMessage(needle, first.matches));
+  if (first.matches.length === 1)
+    return first.matches[0];
+  if (!opts.wake) {
+    throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers: first.liveWorkers }));
+  }
+  const { startRequested, scopes } = await requestWorkerStart(needle);
+  if (startRequested) {
+    for (let i = 0;i < WAKE_POLL_ATTEMPTS; i++) {
+      await sleep(WAKE_POLL_MS);
+      const again = resolveWorkerTargets(await listTargets(), needle);
+      if (again.matches.length > 1)
+        throw new CdpError(workerAmbiguityMessage(needle, again.matches));
+      if (again.matches.length === 1)
+        return again.matches[0];
+    }
+  }
+  const final = resolveWorkerTargets(await listTargets(), needle);
+  throw new CdpError(workerMissMessage(needle, { wakeAttempted: true, liveWorkers: final.liveWorkers, registeredScopes: scopes }));
+}
+
 // src/tools/network_mock.ts
 function escapeRegExpChar(ch) {
   return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
@@ -1134,7 +1424,8 @@ var CDP_CAPABILITIES = new Set([
   "input.raw",
   "input.html5Drag",
   "browser.downloads",
-  "browser.permissions"
+  "browser.permissions",
+  "worker.targets"
 ]);
 
 class CdpPageDriver {
@@ -1702,6 +1993,10 @@ class CdpBrowserDriver {
     await withBrowserConn((conn) => conn.send("Target.activateTarget", { targetId: target.id }));
     return { id: target.id, url: target.url, title: target.title };
   }
+  async resolveWorkerTarget(selector, opts) {
+    const target = await resolveWorkerSelector(selector, opts).catch(noSuchTarget);
+    return { id: target.id, url: target.url, title: target.title, type: target.type };
+  }
   async page(selector) {
     const { conn, target } = await openPage(selector).catch(noSuchTarget);
     return new CdpPageDriver(conn, target, this);
@@ -1788,111 +2083,6 @@ function createCdpDriver() {
   return new CdpBrowserDriver;
 }
 
-// src/origins.ts
-import { mkdir as mkdir2, readFile as readFile2, readdir as readdir2, unlink as unlink2, writeFile as writeFile2 } from "node:fs/promises";
-import { join as join2 } from "node:path";
-function safeId2(id) {
-  return id.replace(/[^A-Za-z0-9._-]/g, "_");
-}
-function originFile(backend, targetId) {
-  return join2(leaseDir(), `origin-${backend}-${safeId2(targetId)}.json`);
-}
-var ORIGIN_FILE_RE = /^origin-(chrome|firefox)-(.+)\.json$/;
-async function recordOrigin(backend, targetId, opts = {}) {
-  const record = {
-    backend,
-    targetId,
-    label: typeof opts.label === "string" && opts.label.length ? opts.label : defaultLabel(),
-    pid: process.pid,
-    createdAt: opts.now ?? Date.now()
-  };
-  const file = originFile(backend, targetId);
-  try {
-    await mkdir2(leaseDir(), { recursive: true });
-    try {
-      await writeFile2(file, JSON.stringify(record), { flag: "wx" });
-      return;
-    } catch (err) {
-      if (err.code !== "EEXIST")
-        throw err;
-    }
-    await unlink2(file).catch(() => {
-      return;
-    });
-    await writeFile2(file, JSON.stringify(record), { flag: "wx" });
-  } catch {}
-}
-async function readOrigin(backend, targetId) {
-  let raw;
-  try {
-    raw = await readFile2(originFile(backend, targetId), "utf8");
-  } catch {
-    return;
-  }
-  try {
-    const rec = JSON.parse(raw);
-    if (typeof rec?.targetId === "string" && typeof rec?.label === "string" && typeof rec?.createdAt === "number")
-      return rec;
-  } catch {}
-  return;
-}
-async function listOrigins(opts = {}) {
-  let names = [];
-  try {
-    names = await readdir2(leaseDir());
-  } catch {
-    return [];
-  }
-  const live = opts.liveIds === undefined ? undefined : new Set(opts.liveIds.map((id) => safeId2(id)));
-  const out = [];
-  for (const name of names) {
-    const parts = ORIGIN_FILE_RE.exec(name);
-    if (!parts)
-      continue;
-    const backend = parts[1];
-    const nameId = parts[2];
-    const scoped = live !== undefined && (opts.liveBackend === undefined || opts.liveBackend === backend);
-    if (scoped && !live.has(nameId)) {
-      await unlink2(join2(leaseDir(), name)).catch(() => {
-        return;
-      });
-      continue;
-    }
-    const fromName = { backend, targetId: nameId, label: "", pid: 0, createdAt: 0 };
-    let rec;
-    try {
-      rec = JSON.parse(await readFile2(join2(leaseDir(), name), "utf8"));
-    } catch (err) {
-      const code = err.code;
-      if (code === "ENOENT")
-        continue;
-      out.push({ ...fromName, unreadable: code ?? "unparseable" });
-      continue;
-    }
-    if (typeof rec?.targetId !== "string" || typeof rec?.label !== "string" || typeof rec?.createdAt !== "number") {
-      out.push({ ...fromName, unreadable: "unparseable" });
-      continue;
-    }
-    out.push({ backend: rec.backend, targetId: rec.targetId, label: rec.label, pid: rec.pid, createdAt: rec.createdAt });
-  }
-  return out;
-}
-async function originIndex(backend, liveIds) {
-  const rows = await listOrigins({ liveIds, liveBackend: backend }).catch(() => []);
-  const index = new Map;
-  for (const row of rows) {
-    if (row.backend !== backend)
-      continue;
-    index.set(row.targetId, row);
-  }
-  return index;
-}
-async function newTrackedPage(driver, backend, opts = {}) {
-  const page = await driver.newPage(opts.url);
-  await recordOrigin(backend, page.id, { label: opts.label });
-  return page;
-}
-
 // src/reap.ts
 function staleAgentTabs(input) {
   const live = new Set(input.livePageIds);
@@ -1993,6 +2183,11 @@ async function pickPage(driver, pages, selector) {
       throw new SharedToolError(`no page title containing '${needle}'`);
     return p;
   }
+  if (selector.startsWith("label:"))
+    return pickByLabel(driver, pages, selector.slice(6));
+  if (isWorkerSelector(selector)) {
+    throw new SharedToolError(backendOf(driver) === "firefox" ? WORKER_SELECTOR_UNSUPPORTED_MESSAGE : WORKER_SELECTOR_PAGE_ONLY_MESSAGE);
+  }
   const exactPage = pages.find((x) => x.id === selector);
   if (exactPage)
     return exactPage;
@@ -2002,6 +2197,18 @@ async function pickPage(driver, pages, selector) {
     return exact;
   throw new SharedToolError(`no target with id '${selector}'`);
 }
+async function pickByLabel(driver, pages, label) {
+  const { matchIds, knownLabels } = await resolveLiveLabel(backendOf(driver), label, pages.map((x) => x.id));
+  if (matchIds.length > 1) {
+    throw new SharedToolError(`label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`);
+  }
+  if (matchIds.length === 1) {
+    const p = pages.find((x) => x.id === matchIds[0]);
+    if (p)
+      return p;
+  }
+  throw new SharedToolError(knownLabels.length ? `no live target with label '${label}' (labels currently in use: ${knownLabels.join(", ")})` : `no live target with label '${label}' (no labels are currently assigned to any open target)`);
+}
 function locatorOf(args) {
   const hasUid = args.uid !== undefined && args.uid !== null && args.uid !== "";
   const hasSelector = typeof args.selector === "string" && args.selector.length > 0;
@@ -2143,11 +2350,29 @@ async function writeJsonSink(savePath, value) {
 function sinkRequested(savePath) {
   return savePath !== undefined && savePath !== "";
 }
+var EXPRESSION_ALIAS_KEYS = ["function", "code", "js", "script", "fn", "body"];
+async function resolveWorkerSelectorFor(driver, selector, wake) {
+  if (!driver.capabilities.has("worker.targets") || typeof driver.resolveWorkerTarget !== "function") {
+    throw new SharedToolError(`evaluateScript: ${WORKER_SELECTOR_UNSUPPORTED_MESSAGE}`);
+  }
+  return driver.resolveWorkerTarget(selector, { wake });
+}
 async function evaluateScript(driver, args) {
   if (typeof args.expression !== "string" || args.expression.length === 0) {
+    const wrongKey = EXPRESSION_ALIAS_KEYS.find((k) => args[k] !== undefined);
+    if (wrongKey !== undefined) {
+      throw new SharedToolError(`evaluateScript: you passed '${wrongKey}'; the key is 'expression' — function literals go in 'expression', invoked with 'args'.`);
+    }
     throw new SharedToolError("evaluateScript: 'expression' must be a non-empty string");
   }
-  return withPage2(driver, args.target, async (page) => {
+  if (args.wake !== undefined && typeof args.wake !== "boolean") {
+    throw new SharedToolError("evaluateScript: 'wake' must be a boolean");
+  }
+  if (args.wake !== undefined && !isWorkerSelector(args.target)) {
+    throw new SharedToolError("evaluateScript: 'wake' only applies to a target of the form 'worker:<substring>'; a page target is never asleep.");
+  }
+  const target = isWorkerSelector(args.target) ? (await resolveWorkerSelectorFor(driver, args.target, args.wake ?? true)).id : args.target;
+  return withPage2(driver, target, async (page) => {
     const value = await page.evaluate(args.expression, { args: args.args, awaitPromise: args.awaitPromise ?? true });
     if (!sinkRequested(args.savePath))
       return value;
@@ -2511,7 +2736,7 @@ async function claimPage(driver, args = {}) {
   const hasTarget = typeof args.target === "string" && args.target.length > 0;
   const hasTargetId = typeof args.targetId === "string" && args.targetId.length > 0;
   if (hasTarget && hasTargetId) {
-    throw new LeaseToolError("claim_page takes at most one of 'target' (any selector: active | index:N | url:<substr> | title:<substr> | <targetId>) or 'targetId' (an exact target id, kept for back-compat). Pass 'target' alone to claim an open tab, or neither to open a fresh one.");
+    throw new LeaseToolError("claim_page takes at most one of 'target' (any selector: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>) or 'targetId' (an exact target id, kept for back-compat). Pass 'target' alone to claim an open tab, or neither to open a fresh one.");
   }
   const backend = backendOf2(driver);
   const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
@@ -2631,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",
@@ -2696,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, {
@@ -2706,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() {
@@ -2812,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 {
@@ -2823,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 },
@@ -2832,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];
@@ -2930,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 };
   }
@@ -2958,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));
@@ -2976,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)` : ``));
@@ -4906,6 +5163,22 @@ async function pickContext(conn, contexts, selector) {
         return c;
     throw driverError2("no-such-target", `no context with title containing '${needle}'`);
   }
+  if (selector.startsWith("label:")) {
+    const label = selector.slice(6);
+    const { matchIds, knownLabels } = await resolveLiveLabel("firefox", label, contexts.map((c) => c.context));
+    if (matchIds.length > 1) {
+      throw driverError2("no-such-target", `label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`);
+    }
+    if (matchIds.length === 1) {
+      const hit = contexts.find((c) => c.context === matchIds[0]);
+      if (hit)
+        return hit;
+    }
+    throw driverError2("no-such-target", knownLabels.length ? `no live target with label '${label}' (labels currently in use: ${knownLabels.join(", ")})` : `no live target with label '${label}' (no labels are currently assigned to any open target)`);
+  }
+  if (isWorkerSelector(selector)) {
+    throw driverError2("unsupported", WORKER_SELECTOR_UNSUPPORTED_MESSAGE);
+  }
   const exact = contexts.find((c) => c.context === selector);
   if (exact)
     return exact;
@@ -5768,6 +6041,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) {
@@ -5796,6 +6074,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);
@@ -5804,6 +6083,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;
@@ -5814,6 +6094,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);
@@ -5824,6 +6105,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) => {
@@ -5935,7 +6217,11 @@ Backend selection: --browser chrome|firefox, else the CDP_BROWSER env var, else
 zero behavior change for existing users). Firefox is LAUNCHED per invocation (it cannot be attached
 to), used for exactly one tool call, then disposed before the process exits.
 
-Target selector grammar: active | index:N | url:<substr> | title:<substr> | <targetId>
+Target selector grammar: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>
+  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.