cdp-toolkit 1.8.0 → 1.9.0

package/dist/mcp.js

@@ -278,6 +278,169 @@ 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_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 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.";
+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 +596,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 +629,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 +842,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 +1408,8 @@ var CDP_CAPABILITIES = new Set([
   "input.raw",
   "input.html5Drag",
   "browser.downloads",
-  "browser.permissions"
+  "browser.permissions",
+  "worker.targets"
 ]);
 
 class CdpPageDriver {
@@ -1702,6 +1977,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 +2067,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 +2167,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 +2181,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 +2334,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 +2720,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();
@@ -4157,7 +4366,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         }
       },
       required: [
@@ -4178,7 +4387,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         }
       },
       required: [
@@ -4199,7 +4408,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         url: {
           type: "string",
@@ -4249,7 +4458,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         text: {
           type: "string",
@@ -4272,7 +4481,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.",
+    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').",
     inputSchema: {
       type: "object",
       properties: {
@@ -4282,11 +4491,15 @@ 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."
+          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'."
+        },
+        wake: {
+          type: "boolean",
+          description: "Only valid with a 'worker:<substring>' target, and rejected on a page target rather than ignored. Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so a wake 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; the error then says the worker may simply be asleep."
         },
         expression: {
           type: "string",
-          description: "JavaScript to run. Evaluated as an expression when 'args' is omitted; must be a function literal (arrow or classic) whose parameters receive 'args' when 'args' is provided."
+          description: "JavaScript to run. Evaluated as an expression when 'args' is omitted; must be a function literal (arrow or classic) whose parameters receive 'args' when 'args' is provided. REQUIRED — the code always goes in this key, never in 'function', 'code', 'js', 'script', 'fn' or 'body'; a call using one of those instead is rejected with an error naming the wrong key."
         },
         awaitPromise: {
           type: "boolean",
@@ -4319,7 +4532,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
         },
         domain: {
           type: "string",
@@ -4350,7 +4563,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
         },
         name: {
           type: "string",
@@ -4406,7 +4619,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
         },
         name: {
           type: "string",
@@ -4441,7 +4654,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default, = first page-type target) | 'index:N' (Nth page-type target, 0-based) | 'url:<substring>' | 'title:<substring>' | '<32-hex targetId>' (exact target by id)."
+          description: "Target page selector: 'active' (default, = first page-type target) | 'index:N' (Nth page-type target, 0-based) | 'url:<substring>' | 'title:<substring>' | 'label:<name>' (exact label match, origin ledger or live lease) | '<32-hex targetId>' (exact target by id)."
         },
         interactiveOnly: {
           type: "boolean",
@@ -4464,7 +4677,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         uid: {
           type: "number",
@@ -4517,7 +4730,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         uid: {
           type: "number",
@@ -4544,7 +4757,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         from: {
           type: "object",
@@ -4630,7 +4843,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         uid: {
           type: "number",
@@ -4673,7 +4886,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         action: {
           type: "string",
@@ -4739,7 +4952,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'. A download is browser-scoped, so this names the tab for the lease check and for the echoed target, not which download is returned."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'. A download is browser-scoped, so this names the tab for the lease check and for the echoed target, not which download is returned."
         },
         arm: {
           type: "boolean",
@@ -4766,7 +4979,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'. Used for the lease check and, when 'origin' is omitted, as the source of the origin to grant for."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'. Used for the lease check and, when 'origin' is omitted, as the source of the origin to grant for."
         },
         permissions: {
           type: "array",
@@ -4800,7 +5013,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         uid: {
           type: "number",
@@ -4833,7 +5046,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         fields: {
           type: "array",
@@ -4879,7 +5092,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         uid: {
           type: "number",
@@ -4912,7 +5125,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         key: {
           type: "string",
@@ -4944,7 +5157,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         uid: {
           type: "number",
@@ -4983,7 +5196,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector. undefined or 'active' -> first page target; '<32-hex targetId>' -> exact target by id; 'index:N' -> Nth page target (0-based); 'url:<substring>' -> first page whose url contains substring; 'title:<substring>' -> first page whose title contains substring."
+          description: "Target page selector. undefined or 'active' -> first page target; '<32-hex targetId>' -> exact target by id; 'index:N' -> Nth page target (0-based); 'url:<substring>' -> first page whose url contains substring; 'title:<substring>' -> first page whose title contains substring; 'label:<name>' -> the page with exactly this label (origin ledger or live lease)."
         },
         format: {
           type: "string",
@@ -5034,7 +5247,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         width: {
           type: "number",
@@ -5134,7 +5347,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         width: {
           type: "number",
@@ -5172,7 +5385,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (or omitted) for the first page-type target | 'index:N' (0-based) | 'url:<substring>' | 'title:<substring>' | a 32-hex <targetId>."
+          description: "Target page selector: 'active' (or omitted) for the first page-type target | 'index:N' (0-based) | 'url:<substring>' | 'title:<substring>' | 'label:<name>' (exact label match, origin ledger or live lease) | a 32-hex <targetId>."
         },
         accept: {
           type: "boolean",
@@ -5209,7 +5422,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
         },
         reload: {
           type: "boolean",
@@ -5236,7 +5449,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
         },
         index: {
           type: "number",
@@ -5259,7 +5472,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
         },
         reload: {
           type: "boolean",
@@ -5290,7 +5503,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
         },
         requestId: {
           type: "string",
@@ -5325,7 +5538,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         categories: {
           type: "array",
@@ -5351,7 +5564,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         }
       },
       required: [],
@@ -5389,7 +5602,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         durationMs: {
           type: "number",
@@ -5427,7 +5640,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         format: {
           type: "string",
@@ -5474,7 +5687,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Which recording to stop: 'active' (default, valid only when exactly one recording is in flight) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Which recording to stop: 'active' (default, valid only when exactly one recording is in flight) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         savePath: {
           type: "string",
@@ -5497,7 +5710,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
         },
         savePath: {
           type: "string",
@@ -5564,7 +5777,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target selector: active | index:N | url:<substr> | title:<substr> | <targetId>. Defaults to the active page."
+          description: "Target selector: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>. Defaults to the active page."
         },
         urlPattern: {
           type: "string",
@@ -5672,7 +5885,7 @@ var MANIFEST = [
       properties: {
         target: {
           type: "string",
-          description: "Take over an already-open tab, e.g. one the human has open, when asked to: pass any target selector — active | index:N | url:<substr> | title:<substr> | <targetId>. Resolved against the live page list only, so it NEVER opens a tab: a selector that matches nothing is an error, not a new blank tab. The tab is left open on release because the toolkit did not create it. Refused if another live process holds it, including a lease the gate acquired for that process automatically under CDP_REQUIRE_LEASE: this takes over unleased (human) tabs and never steals one from a live agent. Mutually exclusive with targetId."
+          description: "Take over an already-open tab, e.g. one the human has open, when asked to: pass any target selector — active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>. Resolved against the live page list only, so it NEVER opens a tab: a selector that matches nothing is an error, not a new blank tab. The tab is left open on release because the toolkit did not create it. Refused if another live process holds it, including a lease the gate acquired for that process automatically under CDP_REQUIRE_LEASE: this takes over unleased (human) tabs and never steals one from a live agent. Mutually exclusive with targetId."
         },
         targetId: {
           type: "string",
@@ -5707,7 +5920,7 @@ var MANIFEST = [
         },
         target: {
           type: "string",
-          description: "Target selector for a tab this process holds: active | index:N | url:<substr> | title:<substr> | <targetId>. Mutually exclusive with 'lease'. Refused if another process holds the tab."
+          description: "Target selector for a tab this process holds: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>. Mutually exclusive with 'lease'. Refused if another process holds the tab."
         },
         close: {
           type: "boolean",
@@ -6552,6 +6765,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;
@@ -7561,7 +7790,7 @@ var FIREFOX_TOOLS = {
 };
 
 // src/mcp.ts
-var VERSION = "1.8.0";
+var VERSION = "1.9.0";
 var BROWSER = resolveBrowserKind(stripBrowserFlag(process.argv.slice(2)));
 var AVAILABILITY = toolAvailability(BROWSER);
 var AVAILABLE_NAMES = new Set(AVAILABILITY.available);