cdp-toolkit 1.8.0 → 1.9.0

package/src/manifest.ts

@@ -89,7 +89,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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": [
@@ -110,7 +110,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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": [
@@ -131,7 +131,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -181,7 +181,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -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.",
+    "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": {
@@ -214,11 +214,15 @@ 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."
+          "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",
@@ -251,7 +255,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -282,7 +286,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -338,7 +342,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -373,7 +377,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -396,7 +400,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -449,7 +453,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -476,7 +480,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -562,7 +566,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -605,7 +609,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -671,7 +675,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -698,7 +702,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -732,7 +736,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -765,7 +769,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -811,7 +815,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -844,7 +848,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -876,7 +880,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -915,7 +919,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -966,7 +970,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -1066,7 +1070,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -1104,7 +1108,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -1141,7 +1145,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -1168,7 +1172,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -1191,7 +1195,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -1222,7 +1226,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -1257,7 +1261,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -1283,7 +1287,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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": [],
@@ -1321,7 +1325,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -1359,7 +1363,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -1406,7 +1410,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -1429,7 +1433,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -1496,7 +1500,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",
@@ -1604,7 +1608,7 @@ export const MANIFEST: ToolSpec[] = [
       "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",
@@ -1639,7 +1643,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "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",

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.8.0";
+const VERSION = "1.9.0";
 
 // --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).

package/src/origins.ts

@@ -32,7 +32,7 @@
 import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import type { BrowserDriver, PageInfo } from "./driver.ts";
-import { defaultLabel, leaseDir, type LeaseBackend } from "./leases.ts";
+import { defaultLabel, leaseDir, listLeases, type LeaseBackend } from "./leases.ts";
 
 /** What list_pages can say about where a tab came from. There is deliberately
  *  no "human": see the file header. */
@@ -264,3 +264,43 @@ export async function newTrackedPage(
   await recordOrigin(backend, page.id, { label: opts.label });
   return page;
 }
+
+/** What "label:<name>" resolution found, common to all three selector-grammar
+ *  copies (shared-tools.ts's pickPage, client.ts's pickTarget, bidi/driver.ts's
+ *  pickContext): 0, 1 or >1 live targetIds carrying the queried label, plus
+ *  every label actually in use, for a miss error that teaches something. */
+export interface LabelResolution {
+  matchIds: string[];
+  /** Deduped, sorted. Empty when no live target has any recorded label. */
+  knownLabels: string[];
+}
+
+/**
+ * The shared core of "label:<name>" resolution: exact match against BOTH the
+ * origin ledger (agent-created tabs) and live lease records (covers a
+ * taken-over tab claimed with a label, which has no origin record — see
+ * leases-tools.ts's claimPage), scoped to `liveIds` so a label whose tab is
+ * gone neither matches nor pollutes the miss list.
+ *
+ * PURE OVER ITS INPUTS BEYOND THE TWO READS: no reap, no write, no lease gate.
+ * Each of the three callers formats its own error in its own idiom
+ * (SharedToolError, CdpError, DriverError), so this returns data, never
+ * throws — a caller decides what "matches.length !== 1" means to it.
+ */
+export async function resolveLiveLabel(backend: LeaseBackend, label: string, liveIds: readonly string[]): Promise<LabelResolution> {
+  const live = new Set(liveIds);
+  const [origins, leases] = await Promise.all([originIndex(backend), listLeases({ liveBackend: backend })]);
+  const knownLabels = new Set<string>();
+  const matchIds = new Set<string>();
+  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() };
+}

package/src/shared-tools.ts

@@ -44,7 +44,8 @@ import {
   type LeaseBackend, type LeaseStaleReason, type LeaseToken,
 } from "./leases.ts";
 import { installBeacon, probeRendererActivity, rendererProbeSupported } from "./activity.ts";
-import { newTrackedPage, originIndex, type PageOrigin } from "./origins.ts";
+import { newTrackedPage, originIndex, resolveLiveLabel, type PageOrigin } from "./origins.ts";
+import { isWorkerSelector, WORKER_SELECTOR_PAGE_ONLY_MESSAGE, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "./workers.ts";
 import { reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
 
 const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
@@ -132,6 +133,21 @@ export async function pickPage(driver: BrowserDriver, pages: PageInfo[], selecto
     if (!p) throw new SharedToolError(`no page title containing '${needle}'`);
     return p;
   }
+  if (selector.startsWith("label:")) return pickByLabel(driver, pages, selector.slice(6));
+  if (isWorkerSelector(selector)) {
+    // THE PAGE-ONLY CONTRACT, STATED OUT LOUD. Every caller of pickPage
+    // (resolvePage -> close_page / select_page / release_page, claim_page's
+    // takeover) acts on a TAB, and the 1.9.0 "worker:" arm is deliberately NOT
+    // implemented here: it resolves against the page-only listing these callers
+    // pass, which by construction never contains a worker, so the arm could
+    // only ever miss. Refusing with the reason beats falling through to the
+    // bare-id lookup, whose "no target with id 'worker:foo'" reads as a typo.
+    // The arm lives in client.ts's pickTarget (Chrome's all-targets resolver),
+    // and only evaluate_script routes to it.
+    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;
   const all = await driver.listPages({ all: true });
@@ -140,6 +156,35 @@ export async function pickPage(driver: BrowserDriver, pages: PageInfo[], selecto
   throw new SharedToolError(`no target with id '${selector}'`);
 }
 
+/**
+ * "label:<name>" resolution for pickPage. The lookup itself (both stores,
+ * live-scoped) is shared with client.ts's pickTarget and bidi/driver.ts's
+ * pickContext via origins.ts's resolveLiveLabel, so the three copies of the
+ * selector grammar cannot drift on what counts as a hit, a miss or an
+ * ambiguity. Only the error wording is local, matching this file's
+ * SharedToolError idiom.
+ *
+ * Nothing is reaped here: this is a read, not a maintenance pass, and pickPage
+ * stays gate-free and side-effect-free over its inputs.
+ */
+async function pickByLabel(driver: BrowserDriver, pages: PageInfo[], label: string): Promise<PageInfo> {
+  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)`,
+  );
+}
+
 /* -------------------------------- element locators -------------------------------- */
 
 function locatorOf(args: { uid?: DriverUid; selector?: string }): ElementLocator {
@@ -476,14 +521,70 @@ function sinkRequested(savePath?: string): savePath is string {
   return savePath !== undefined && savePath !== "";
 }
 
+/** Keys a caller reaches for out of habit from other automation APIs, none of
+ *  which this tool reads: the code always goes in 'expression'. Checked in
+ *  this order so the error names one wrong key, deterministically, when a
+ *  caller happens to pass more than one. */
+const EXPRESSION_ALIAS_KEYS = ["function", "code", "js", "script", "fn", "body"] as const;
+
+/**
+ * Turn a `worker:<substring>` target into a concrete target id, waking an
+ * idle-evicted MV3 service worker on the way when `wake` is not false.
+ *
+ * WHY THIS RETURNS AN ID RATHER THAN DRIVING THE WORKER ITSELF. Once resolved,
+ * a worker is just a target with its own webSocketDebuggerUrl, and a DIRECT
+ * connection to it evaluates exactly like a page does — `Runtime.evaluate` with
+ * `awaitPromise` returns real awaited values there (measured on Chrome 151;
+ * `chrome.storage.local.get(null)` comes back as an object, not undefined). So
+ * the worker rides the ordinary page() acquisition path from here, and every
+ * behavior around it — the args/function form, exception reporting, and above
+ * all savePath's no-value-in-the-response secret hygiene — is the SAME CODE,
+ * not a parallel copy that could quietly diverge on the leak-shaped edge.
+ *
+ * Exported for the unit tests, which need to reach the capability refusal
+ * without a browser.
+ */
+export async function resolveWorkerSelectorFor(
+  driver: BrowserDriver,
+  selector: string,
+  wake: boolean,
+): Promise<PageInfo> {
+  if (!driver.capabilities.has("worker.targets") || typeof driver.resolveWorkerTarget !== "function") {
+    throw new SharedToolError(`evaluateScript: ${WORKER_SELECTOR_UNSUPPORTED_MESSAGE}`);
+  }
+  return driver.resolveWorkerTarget(selector, { wake });
+}
+
 export async function evaluateScript(
   driver: BrowserDriver,
-  args: { target?: TargetSelector; expression: string; awaitPromise?: boolean; args?: unknown[]; savePath?: string },
+  args: { target?: TargetSelector; expression: string; awaitPromise?: boolean; args?: unknown[]; savePath?: string; wake?: boolean },
 ): Promise<unknown> {
   if (typeof args.expression !== "string" || args.expression.length === 0) {
+    const wrongKey = EXPRESSION_ALIAS_KEYS.find((k) => (args as Record<string, unknown>)[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 withPage(driver, args.target, async (page) => {
+  if (args.wake !== undefined && typeof args.wake !== "boolean") {
+    throw new SharedToolError("evaluateScript: 'wake' must be a boolean");
+  }
+  // `wake` is REFUSED on a page selector rather than ignored. Accepting it there
+  // would read as "this call will wake something", and the caller would never
+  // learn that the argument did nothing at all.
+  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.",
+    );
+  }
+  // Resolved to a bare target id BEFORE acquisition, so the page() call below is
+  // the same one every other selector makes.
+  const target = isWorkerSelector(args.target)
+    ? (await resolveWorkerSelectorFor(driver, args.target, args.wake ?? true)).id
+    : args.target;
+  return withPage(driver, target, async (page) => {
     const value = await page.evaluate(args.expression, { args: args.args, awaitPromise: args.awaitPromise ?? true });
     // No savePath: byte-identical to the pre-sink behavior, the value itself.
     // A thrown page-side exception never reaches here, so it still surfaces as

package/src/types.ts

@@ -41,6 +41,26 @@ export interface CdpEvent<P = Record<string, unknown>> {
  *   - "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 whose label EXACTLY
+ *     matches `name`, checked against both the origin ledger (agent-created
+ *     tabs, see src/origins.ts) and live lease records (covers a taken-over
+ *     tab claimed with a label, which has no origin record — see
+ *     src/leases-tools.ts's claimPage). The resolved id must be present in
+ *     the listing this call is resolving against; a label whose tab is gone
+ *     falls through to the normal no-match error. A miss enumerates the
+ *     labels that DO exist; two live targets sharing a label is an ambiguity
+ *     error naming both ids, never a silent first-match. See pickPage in
+ *     src/shared-tools.ts.
+ *   - "worker:<substring>"    -> a service_worker/shared_worker target whose
+ *     URL contains the substring (an MV3 extension's background worker is
+ *     `chrome-extension://<id>/<script>`, so both the extension id and the
+ *     script name match). NOT UNIVERSAL, unlike every arm above it: resolved
+ *     only by Chrome's pickTarget (this file's resolveTarget), accepted only by
+ *     evaluate_script, refused with a capability error on Firefox and by the
+ *     page-only resolvers. It reads the UNFILTERED target listing, because a
+ *     worker is not a page target — and a worker that is idle-evicted is in no
+ *     listing at all, which is what evaluate_script's `wake` exists for. See
+ *     src/workers.ts and src/cdp/workers.ts.
  */
 export type TargetSelector = string | undefined;