pi-browser-harness 0.11.0 → 0.13.0

package/src/prompt.ts

@@ -1,127 +1,52 @@
-/**
- * System prompt guidance for browser usage.
- *
- * Injects a compact browser control reference into the pi system prompt.
- * This prompt carries only cross-cutting knowledge — the mental model, tool
- * routing, workflows, and gotchas. Per-tool specifics (schemas, detailed usage)
- * are injected separately via promptGuidelines on each tool registration, so this
- * file intentionally does NOT restate full tool descriptions.
- */
+import { ALL_TOOLS } from "./registry";
+import type { BrowserTool, ToolConcurrency } from "./util/tool";
 
-export function getBrowserSystemPrompt(): string {
-  return `
-## Browser Control
-
-You drive a **real Chrome** (the user's running instance, not headless) through
-\`browser_*\` tools. These coexist with every standard pi tool — read, bash, edit,
-write — so mix them freely: \`browser_*\` for the page, everything else alongside.
-
-### The core handle: refs
-
-Interaction is ref-first. Call \`browser_snapshot\` to get an accessibility tree
-where every interactive element has a stable ref (\`[eN]\`) and \`@(x,y)\`. **Target
-elements by ref, not by coordinates or guessed selectors** — refs are keyed to
-element identity, so they survive the re-renders that React/Vue forms trigger on
-every edit and save. Coordinates go stale; guessed selectors miss.
-
-- Prefer \`browser_fill\` for text — it fires input/change so controlled components
-  update, and returns the value for verification. Use \`browser_click\` + \`browser_type\`
-  only for keystroke-sensitive widgets (autocomplete, masked inputs).
-- Mutating calls append a compact **"Page changes"** diff — read it to confirm the
-  change landed (form closed, new \`*[eN]\` appeared).
-- \`"ref is stale"\` means the page changed: re-run \`browser_snapshot\` for fresh refs.
-
-### Choosing a tool
-
-| To… | Reach for |
-|-----|-----------|
-| See the page structure (for interaction) | \`browser_snapshot\` (refs) |
-| See the page visually | \`browser_screenshot\` |
-| Search the web | \`browser_web_search\` → ranked {title, url, snippet} |
-| Read an article's clean text | \`browser_read_page\` (reader mode; url or owned tab) |
-| Extract specific DOM values | \`browser_execute_js\` |
-| Hit a JSON/API endpoint | \`browser_http_get\` (raw GET, outside the browser) |
-| Click / fill / type / select / focus / press a key | \`browser_click\` · \`browser_fill\` · \`browser_type\` · \`browser_select_option\` · \`browser_focus\` · \`browser_press_key\` |
-| Upload a file · drag · resize viewport | \`browser_upload_file\` · \`browser_drag_and_drop\` · \`browser_viewport_resize\` |
-| Go to a URL / open many / manage tabs | \`browser_navigate\` · \`browser_new_tab\` · \`browser_open_urls\` · \`browser_list_tabs\` · \`browser_switch_tab\` · \`browser_go_back\`/\`go_forward\`/\`reload\` |
-| Wait for content / load / a fixed delay | \`browser_wait_for\` (selector/text) · \`browser_wait_for_load\` (readyState) · \`browser_wait\` |
-| Inspect page / handle a dialog | \`browser_page_info\` · \`browser_current_tab\` · \`browser_handle_dialog\` |
-| Diagnose a broken action | \`browser_console\` (JS errors) · \`browser_get_network_log\` |
-| Save output / config downloads | \`browser_print_to_pdf\` · \`browser_download\` |
-| Anything the tools can't express | \`browser_run_script\` (see Extending) |
+// The lane text is derived from each tool's own `concurrency`, so a tool can never
+// be mis-described as observational while actually taking the mutation mutex.
+export type PromptTool = Pick<BrowserTool, "name" | "concurrency">;
 
-Each tool carries its own detailed guidelines — this table is only for routing.
+export type LaneNames = {
+  readonly serialized: ReadonlyArray<string>;
+  readonly parallel: ReadonlyArray<string>;
+};
 
-### Workflows
+const TOOL_PREFIX = "browser_";
 
-**Research (search → read):**
-\`\`\`
-browser_web_search("query")        // ranked links, no page content
-→ browser_read_page(url)           // clean article text for the top hits
-// fall back to browser_open_urls + browser_execute_js only when reader mode misses
-\`\`\`
+// Lane lists use the short form (click, not browser_click) to keep the prompt compact; the
+// prefix is universal and stated once in the prose above the list.
+export const shortToolName = (name: string): string =>
+  name.startsWith(TOOL_PREFIX) ? name.slice(TOOL_PREFIX.length) : name;
 
-**Form filling (ref-first — the reliable path on SPA forms):**
-\`\`\`
-browser_wait_for({ selector: "#email" })   // ensure the field is rendered
-browser_snapshot()                          // interactive elements get [eN] refs
-→ browser_fill({ ref: "e7", value: "a@b.com" })
-→ browser_select_option({ ref: "e9", label: "India" })
-→ browser_click({ ref: "e12" })             // re-resolves position even after reflow
-// read each "Page changes" diff to confirm the step landed
-\`\`\`
+export const laneNames = (tools: ReadonlyArray<PromptTool>): LaneNames => {
+  const lane = (c: ToolConcurrency): ReadonlyArray<string> => tools.filter((t) => t.concurrency === c).map((t) => t.name);
+  return { serialized: lane("serialized"), parallel: lane("parallel") };
+};
 
-**Navigate + verify:**
-\`\`\`
-browser_new_tab("https://example.com") → browser_wait_for_load() → browser_screenshot()
-\`\`\`
+const joinShort = (names: ReadonlyArray<string>): string => names.map(shortToolName).join(", ");
 
-**Scroll:** \`browser_scroll({ deltaY: 500 })\` — W3C wheel convention: positive = down,
-negative = up (default 300, down).
-
-### Parallelism
-
-Observation tools (\`browser_screenshot\`, \`browser_page_info\`, \`browser_execute_js\`,
-\`browser_list_tabs\`, \`browser_http_get\`, \`browser_web_search\`, \`browser_read_page\`, …)
-run in parallel with each other and with mutations. The harness serializes mutations
-(click, type, scroll, navigate, switch_tab) so they never race. Emit independent calls
-in one turn:
-\`\`\`
-browser_screenshot() + browser_page_info() + browser_execute_js("document.title")
-\`\`\`
-
-**Multi-agent:** tab switching by one agent changes the active tab for all agents,
-but per-tab data (console, network, dialogs) stays isolated. Call \`browser_current_tab\`
-before a mutation to confirm you're on the expected tab. Handle any dialog reported by
-\`browser_page_info\` promptly — dialogs block interaction and aren't queued across agents.
-
-**Session boundary & tab hygiene:** you operate only inside this session's own Chrome
-window. \`browser_switch_tab\`/\`browser_close_tab\` refuse tabs this session didn't open,
-and \`browser_list_tabs\` defaults to owned tabs — never reach into the user's other tabs
-or windows. Close tabs when you're done with them: call \`browser_close_tab\` on any tab
-you opened (via \`browser_new_tab\`/\`browser_open_urls\`) once you've extracted what you
-need. Don't leave a pile of stale tabs behind — keep only what a later step still needs.
-(Leftover tabs are closed automatically when the session ends, but close them yourself
-as you go.)
-
-### Extending: temporary scripts
+export function getBrowserSystemPrompt(connected = true, tools: ReadonlyArray<PromptTool> = ALL_TOOLS): string {
+  const connectionNotice = connected
+    ? ""
+    : "Browser is not connected. Run browser_setup or /browser-setup to connect.\n\n";
+  const lanes = laneNames(tools);
+  return `
+## Browser Control
 
-When built-in tools can't express a multi-step workflow, write a script to a temp file
-and run it with \`browser_run_script\`. It executes in the harness process with direct
-daemon + Node access.
-\`\`\`
-write(<tempfile>.js, \`
-  const results = [];
-  for (const url of params.urls) {
-    await daemon.cdp("Page.navigate", { url });
-    await new Promise(r => setTimeout(r, 2000));
-    results.push({ url, title: await daemon.evaluateJS("document.title") });
-  }
-  return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
-\`)
-browser_run_script(<tempfile>.js, { urls: [...] })
-\`\`\`
-Script bindings: params, daemon, require, signal, onUpdate, ctx, console, fetch, JSON,
-Buffer, setTimeout, clearTimeout. Use a real temp path from the OS — don't hardcode \`/tmp\`.
+${connectionNotice}You control the user's running Chrome through \`browser_*\` tools alongside the
+standard pi tools. Per-tool usage lives in tool descriptions, parameter schemas,
+and tool-specific guidelines.
+
+- Operate only inside this session's owned Chrome window. Never reach into the
+  user's other tabs or windows. Close owned tabs once no later step needs them.
+- Tools in the serialized lane (${joinShort(lanes.serialized)}) run one at a time.
+  Tools in the parallel lane (${joinShort(lanes.parallel)}) may run concurrently
+  with them. \`browser_run_script\` bypasses that lane: keep mutating scripts
+  sequential with other browser calls. Parallelize only independent calls.
+- Agents sharing a session share its active tab. Check \`browser_current_tab\`
+  before a mutation to confirm the expected tab when another agent may switch it.
+- Read any appended "Page changes" diff to confirm an interaction. Tools without a
+  diff, including \`browser_run_script\`, need explicit state verification.
+- If a tool reports "ref is stale", call \`browser_snapshot\` for fresh refs before
+  retrying; do not reuse the stale handle.
 `;
 }

package/src/registry.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { BrowserClient } from "./client";
-import { type AnyBrowserToolDefinition, registerBrowserTool } from "./util/tool";
+import type { BrowserTool } from "./util/tool";
+import { type Result, err, ok } from "./util/result";
 import { clickTool } from "./domains/click";
 import { typeTool, pressKeyTool, dispatchKeyTool } from "./domains/keyboard";
 import { fillTool, selectOptionTool, focusTool, setCheckedTool } from "./domains/form";
@@ -16,6 +17,7 @@ import { uploadFileTool, downloadTool, printToPdfTool } from "./domains/files";
 import { viewportResizeTool } from "./domains/viewport";
 import { dragAndDropTool } from "./domains/drag";
 import { httpGetTool, networkRequestsTool } from "./domains/network";
+import { clearHeadersTool, setHeadersTool } from "./domains/headers";
 import { consoleTool } from "./domains/console";
 import { snapshotTool } from "./domains/snapshot";
 import { executeJsTool, runScriptTool } from "./domains/js";
@@ -23,7 +25,7 @@ import { setupTool } from "./domains/setup";
 import { webSearchTool } from "./domains/search/web-search";
 import { readPageTool } from "./domains/readpage/read-page";
 
-export const ALL_TOOLS: ReadonlyArray<AnyBrowserToolDefinition> = [
+export const ALL_TOOLS: ReadonlyArray<BrowserTool> = [
   setupTool,
   clickTool,
   typeTool,
@@ -58,6 +60,8 @@ export const ALL_TOOLS: ReadonlyArray<AnyBrowserToolDefinition> = [
   dragAndDropTool,
   httpGetTool,
   networkRequestsTool,
+  setHeadersTool,
+  clearHeadersTool,
   consoleTool,
   snapshotTool,
   executeJsTool,
@@ -66,6 +70,66 @@ export const ALL_TOOLS: ReadonlyArray<AnyBrowserToolDefinition> = [
   readPageTool,
 ];
 
-export const registerAllTools = (pi: ExtensionAPI, client: BrowserClient): void => {
-  for (const t of ALL_TOOLS) registerBrowserTool(pi, client, t);
+export type RegistryError = {
+  readonly kind: "duplicate_name";
+  readonly message: string;
+};
+
+// The only surface pi needs for tool registration; keeping it narrow lets tests pass a sink
+// instead of a full ExtensionAPI.
+export type ToolRegistrar = Pick<ExtensionAPI, "registerTool">;
+
+export type ToolRegistry = {
+  // Current contents, in insertion order. Built-ins come first, contributed tools after.
+  readonly tools: () => ReadonlyArray<BrowserTool>;
+  // Append one tool. Rejects a name already present so a contributor cannot shadow a built-in
+  // (or another contributor) silently; the first registration wins.
+  readonly add: (tool: BrowserTool) => Result<void, RegistryError>;
+  // Append a batch atomically: a name clash anywhere in it (with the registry or within the batch)
+  // rejects the whole call and leaves the registry untouched.
+  readonly addAll: (tools: ReadonlyArray<BrowserTool>) => Result<void, RegistryError>;
+  // Register every tool that has not been registered with pi yet. Safe to call on every
+  // session_start: tools added after an earlier call land on the next one.
+  readonly register: (pi: ToolRegistrar, client: BrowserClient) => void;
+};
+
+const duplicateName = (name: string): RegistryError => ({
+  kind: "duplicate_name",
+  message: `A browser tool named "${name}" is already registered; pick a distinct name`,
+});
+
+export const createToolRegistry = (initial: ReadonlyArray<BrowserTool> = ALL_TOOLS): ToolRegistry => {
+  const tools: BrowserTool[] = [];
+  const names = new Set<string>();
+  const registered = new Set<string>();
+
+  const addAll = (batch: ReadonlyArray<BrowserTool>): Result<void, RegistryError> => {
+    const seen = new Set<string>();
+    const clash = batch.find((t) => names.has(t.name) || seen.has(t.name) || (seen.add(t.name), false));
+    if (clash) return err(duplicateName(clash.name));
+    for (const tool of batch) {
+      names.add(tool.name);
+      tools.push(tool);
+    }
+    return ok(undefined);
+  };
+  const add = (tool: BrowserTool): Result<void, RegistryError> => addAll([tool]);
+
+  for (const tool of initial) {
+    const added = add(tool);
+    if (!added.success) throw new Error(added.error.message);
+  }
+
+  return {
+    tools: () => [...tools],
+    add,
+    addAll,
+    register: (pi, client) => {
+      for (const tool of tools) {
+        if (registered.has(tool.name)) continue;
+        tool.register(pi, client);
+        registered.add(tool.name);
+      }
+    },
+  };
 };

package/src/schemas/parse.ts

@@ -1,10 +1,10 @@
-import type { Static, TSchema } from "typebox";
+import type { Static, TProperties, TSchema } from "typebox";
 import type { Validator } from "typebox/compile";
 import { type Result, err, ok } from "../util/result";
 
 export const parseJson = <S extends TSchema>(
   raw: string,
-  validator: Validator<{}, S>,
+  validator: Validator<TProperties, S>,
 ): Result<Static<S>, string> => {
   let parsed: unknown;
   try {

package/src/setup.ts

@@ -4,12 +4,19 @@ import { ensureDaemon } from "./daemon/spawn";
 import { DAEMON_SOCKET_PATH } from "./daemon/protocol";
 import { isBrowserRunning } from "./profile/browser-process";
 import { promptForProfileIfUnset } from "./profile/command";
+import { type Result, err, ok } from "./util/result";
 
-export function registerSetupCommand(pi: ExtensionAPI, client: BrowserClient): void {
+// The machine probes setup runs before touching the client. Each defaults to the real implementation.
+export type SetupDeps = {
+  readonly isBrowserRunning?: () => Promise<boolean>;
+  readonly ensureDaemon?: () => Promise<boolean>;
+};
+
+export function registerSetupCommand(pi: ExtensionAPI, client: BrowserClient, deps: SetupDeps = {}): void {
   pi.registerCommand("browser-setup", {
     description: "Connect pi to your Chrome browser",
     handler: async (_args, ctx) => {
-      const result = await performSetup(client, ctx);
+      const result = await performSetup(client, ctx, deps);
       if (result.success) {
         ctx.ui.notify(result.data, "info");
       } else {
@@ -19,22 +26,26 @@ export function registerSetupCommand(pi: ExtensionAPI, client: BrowserClient): v
   });
 }
 
-export type SetupResult = { success: true; data: string } | { success: false; error: string };
+export type SetupResult = Result<string, string>;
 
-export async function performSetup(client: BrowserClient, ctx?: ExtensionContext): Promise<SetupResult> {
-  const chromeRunning = await isBrowserRunning();
+export async function performSetup(
+  client: BrowserClient,
+  ctx?: ExtensionContext,
+  deps: SetupDeps = {},
+): Promise<SetupResult> {
+  const chromeRunning = await (deps.isBrowserRunning ?? isBrowserRunning)();
   if (!chromeRunning) {
-    return { success: false, error: "No browser instance running. Please open your browser and then run /browser-setup." };
+    return err("No browser instance running. Please open your browser and then run /browser-setup.");
   }
 
-  const daemonReady = await ensureDaemon();
+  const daemonReady = await (deps.ensureDaemon ?? ensureDaemon)();
   if (!daemonReady) {
-    return { success: false, error: `Could not start the browser daemon. Check ${DAEMON_SOCKET_PATH}.` };
+    return err(`Could not start the browser daemon. Check ${DAEMON_SOCKET_PATH}.`);
   }
 
   const profileNote = await promptForProfileIfUnset(client, ctx);
 
-  const startResult = await client.start();
+  const startResult = await client.start({ reconnectNow: true });
   if (!startResult.success) {
     const msg = startResult.error.message;
     const lower = msg.toLowerCase();
@@ -45,35 +56,33 @@ export async function performSetup(client: BrowserClient, ctx?: ExtensionContext
       lower.includes("econnrefused") ||
       lower.includes("cannot reach chrome devtools")
     ) {
-      return {
-        success: false,
-        error:
-          "Browser remote debugging needs to be enabled.\n\n" +
+      return err(
+        "Browser remote debugging needs to be enabled.\n\n" +
           "Open chrome://inspect/#remote-debugging (or brave://inspect,\n" +
           "edge://inspect) in your browser, tick the\n" +
           '"Discover network targets" / Allow checkbox, then retry.\n\n' +
           "If that doesn't expose DevTools, relaunch the browser with\n" +
           "--remote-debugging-port=9222.\n\n" +
           "Or set BU_CDP_WS to a remote browser WebSocket URL.",
-      };
+      );
     }
 
-    return { success: false, error: `Connection failed: ${msg}` };
+    return err(`Connection failed: ${msg}`);
   }
 
   const tabResult = await client.newTab("https://github.com");
   if (!tabResult.success) {
-    return { success: false, error: `Browser connected but test navigation failed: ${tabResult.error.message}` };
+    return err(`Browser connected but test navigation failed: ${tabResult.error.message}`);
   }
 
   const info = await client.pageInfo();
-  if (info.success && "dialog" in info.data) {
+  if (info.success && info.data.kind === "dialog") {
     await client.session().call("Page.handleJavaScriptDialog", { accept: true });
   }
 
-  const pageUrl = info.success && !("dialog" in info.data) ? info.data.url : "github.com";
+  const pageUrl = info.success && info.data.kind === "page" ? info.data.url : "github.com";
   const lines = ["Browser connected ✓", `Navigated to: ${pageUrl}`];
   if (profileNote) lines.push(profileNote);
-  return { success: true, data: lines.join("\n") };
+  return ok(lines.join("\n"));
 }
 

package/src/state.ts

@@ -13,8 +13,39 @@ export const defaultState = (namespace = "default"): BrowserState => ({
   ownedTargetIds: [],
 });
 
-export const persistState = (pi: ExtensionAPI, state: BrowserState): void => {
-  pi.appendEntry<BrowserState>("browser-harness-state", state);
+// Pi session JSONL is append-only and every custom entry shows up in the branch navigator, so a
+// snapshot is only worth appending when it differs from the one the branch already holds (#26).
+// Tab order is not a difference: ownership is a set.
+const stateKey = (state: BrowserState): string =>
+  JSON.stringify({
+    namespace: state.namespace,
+    ownedTargetIds: [...(state.ownedTargetIds ?? [])].sort(),
+    harnessWindowTargetId: state.harnessWindowTargetId ?? null,
+    harnessWindowId: state.harnessWindowId ?? null,
+  });
+
+export type StatePersister = {
+  // Appends the snapshot unless it equals the last one persisted or restored. Returns whether it wrote.
+  readonly persist: (state: BrowserState) => boolean;
+  // Records a snapshot that already lives in the session (restored from the branch) without writing it.
+  readonly markPersisted: (state: BrowserState) => void;
+};
+
+// Only appendEntry is needed, so a test can hand in a plain object instead of a whole ExtensionAPI.
+export const createStatePersister = (pi: Pick<ExtensionAPI, "appendEntry">): StatePersister => {
+  let last: string | undefined;
+  return {
+    persist: (state) => {
+      const key = stateKey(state);
+      if (key === last) return false;
+      pi.appendEntry<BrowserState>("browser-harness-state", state);
+      last = key;
+      return true;
+    },
+    markPersisted: (state) => {
+      last = stateKey(state);
+    },
+  };
 };
 
 const asPersistedState = (v: unknown): Partial<BrowserState> | undefined => {

package/src/util/debug.ts

@@ -4,5 +4,11 @@ export const setDebugClicks = (on: boolean): void => {
   flagEnabled = on;
 };
 
+const TRUTHY: ReadonlySet<string> = new Set(["1", "true"]);
+
+// Only an explicit "1" or "true" counts: "0" and "false" are set to turn the overlay off, not on.
+const envFlagEnabled = (value: string | undefined): boolean =>
+  value !== undefined && TRUTHY.has(value.trim().toLowerCase());
+
 export const debugClicksEnabled = (env: NodeJS.ProcessEnv = process.env): boolean =>
-  flagEnabled || Boolean(env["BH_DEBUG_CLICKS"]);
+  flagEnabled || envFlagEnabled(env["BH_DEBUG_CLICKS"]);

package/src/util/guards.ts

@@ -6,6 +6,9 @@ export const asRecord = (v: unknown): Readonly<Record<string, unknown>> | undefi
 
 export const asString = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
 
+export const asNonEmptyString = (v: unknown): string | undefined =>
+  typeof v === "string" && v.length > 0 ? v : undefined;
+
 export const asNumber = (v: unknown): number | undefined => (typeof v === "number" ? v : undefined);
 
 export const asBoolean = (v: unknown): boolean | undefined => (typeof v === "boolean" ? v : undefined);

package/src/util/mutex.ts

@@ -7,7 +7,7 @@ export const createMutex = (): Mutex => {
 
   return {
     async acquire(): Promise<() => void> {
-      let release = () => {};
+      let release: () => void = () => undefined;
       const next = new Promise<void>((resolve) => {
         release = resolve;
       });

package/src/util/paths.ts

@@ -1,6 +1,17 @@
 import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+
+// `relative` rather than a string prefix: it is separator-agnostic and carries each platform's
+// own case rules, so a Windows path is not rejected for its backslashes or its drive-letter case.
+export const isPathWithin = (root: string, target: string): boolean => {
+  const absRoot = resolve(root);
+  const absTarget = resolve(target);
+  if (absTarget === absRoot) return true;
+  const rel = relative(absRoot, absTarget);
+  // A bare ".." or a ".."-led segment escapes; a sibling merely named "..foo" does not.
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+};
 
 const NAMESPACE_RE = /^[a-zA-Z0-9_-]+$/;
 

package/src/util/result.ts

@@ -7,3 +7,11 @@ export const err = <E>(error: E): Result<never, E> => ({ success: false, error }
 
 export const map = <T, U, E>(r: Result<T, E>, f: (t: T) => U): Result<U, E> =>
   r.success ? ok(f(r.data)) : r;
+
+export const andThen = <T, U, E, F>(r: Result<T, E>, f: (t: T) => Result<U, F>): Result<U, E | F> =>
+  r.success ? f(r.data) : r;
+
+export const mapErr = <T, E, F>(r: Result<T, E>, f: (e: E) => F): Result<T, F> =>
+  r.success ? r : err(f(r.error));
+
+export const unwrapOr = <T, E>(r: Result<T, E>, fallback: T): T => (r.success ? r.data : fallback);

package/src/util/sharp-shim.ts

@@ -1,5 +1,7 @@
 // `sharp` is an optional dependency not installed in every workspace, so the import must stay dynamic and unresolvable to tsc.
 
+import { errnoCode, isRecord } from "./guards";
+
 export type SharpInstance = {
   metadata(): Promise<{ width?: number; height?: number }>;
   composite(layers: ReadonlyArray<{ input: Buffer; top: number; left: number }>): SharpInstance;
@@ -14,29 +16,34 @@ export type SharpLoad =
   | { readonly kind: "missing" }
   | { readonly kind: "error"; readonly message: string };
 
-const SHARP_SPECIFIER: string = "sharp";
+// Kept as a variable so the bundler does not try to resolve the optional dependency statically.
+const SHARP_SPECIFIER = "sharp";
+
+// Node reports an absent package through the error code: ERR_MODULE_NOT_FOUND from the ESM loader
+// ("Cannot find package 'sharp' imported from …"), MODULE_NOT_FOUND from require. Matching the message
+// text misses the ESM form, so an uninstalled sharp used to be reported as a load failure.
+const MISSING_MODULE_CODES: ReadonlySet<string> = new Set(["ERR_MODULE_NOT_FOUND", "MODULE_NOT_FOUND"]);
 
-const MISSING_MODULE_MARKERS: ReadonlyArray<string> = [
-  "Cannot find module",
-  "MODULE_NOT_FOUND",
-  "ERR_MODULE_NOT_FOUND",
-];
+export const classifySharpImportFailure = (e: unknown): SharpLoad => {
+  const code = errnoCode(e);
+  if (code !== undefined && MISSING_MODULE_CODES.has(code)) return { kind: "missing" };
+  return { kind: "error", message: e instanceof Error ? e.message : String(e) };
+};
 
 export const loadSharp = async (): Promise<SharpLoad> => {
   let mod: unknown;
   try {
     mod = await import(SHARP_SPECIFIER);
   } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    if (MISSING_MODULE_MARKERS.some((marker) => msg.includes(marker))) return { kind: "missing" };
-    return { kind: "error", message: msg };
+    return classifySharpImportFailure(e);
   }
   if (mod === null || mod === undefined) return { kind: "missing" };
   // The CommonJS sharp module's default export IS the factory; ESM-wrapped sharp puts it on .default.
-  const m = mod as { default?: unknown };
-  const candidate: unknown = typeof m.default === "function" ? m.default : mod;
+  const candidate: unknown = isRecord(mod) && typeof mod["default"] === "function" ? mod["default"] : mod;
   if (typeof candidate !== "function") {
     return { kind: "error", message: "sharp module did not expose a callable factory" };
   }
+  // The only thing verifiable at runtime is that sharp exported a function; its signature is taken on trust.
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- optional-dependency boundary, see scripts/boundary-allowlist.ts
   return { kind: "ok", sharp: candidate as SharpFactory };
 };

package/src/util/sleep.ts

@@ -0,0 +1,18 @@
+// Resolves (never rejects) after `ms`, or as soon as `signal` aborts. Shared by every poll loop so
+// there is one spelling of "cancellable wait" across the cdp, profile and domain layers.
+export const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
+  new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });