pi-browser-harness 0.11.0 → 0.13.0

package/src/domains/files.ts

@@ -1,4 +1,4 @@
-import { mkdir, access, constants, stat, readFile, writeFile } from "node:fs/promises";
+import { mkdir, access, constants, stat } from "node:fs/promises";
 import { basename } from "node:path";
 import { Type } from "typebox";
 import type { BrowserClient } from "../client";
@@ -7,6 +7,7 @@ import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { safeJs } from "../util/js-template";
 import { pdfPath } from "../util/paths";
 import { cdpCall, cdpCallBrowser, evalJs } from "./cdp-call";
+import { readFileResult, statResult, writeFileResult } from "./io";
 import { resolveRefToBackendId } from "./ref-resolve";
 
 const UploadArgs = Type.Object({
@@ -73,18 +74,20 @@ const jsFallbackUpload = async (
   selector: string,
   filePath: string,
 ): Promise<Result<void, ToolErr>> => {
-  const buf = await readFile(filePath);
-  const st = await stat(filePath);
+  const buf = await readFileResult(filePath);
+  if (!buf.success) return buf;
+  const st = await statResult(filePath);
+  if (!st.success) return st;
   const name = basename(filePath);
   const mime = inferMime(name);
   const expr = safeJs`
     (() => {
       const input = document.querySelector(${selector});
       if (!input || input.type !== 'file') throw new Error('File input not found');
-      const bin = atob(${buf.toString("base64")});
+      const bin = atob(${buf.data.toString("base64")});
       const bytes = new Uint8Array(bin.length);
       for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
-      const file = new File([bytes], ${name}, { type: ${mime}, lastModified: ${st.mtimeMs} });
+      const file = new File([bytes], ${name}, { type: ${mime}, lastModified: ${st.data.mtimeMs} });
       const dt = new DataTransfer();
       dt.items.add(file);
       input.files = dt.files;
@@ -104,7 +107,7 @@ export const uploadFileTool = defineBrowserTool({
   description: "Set files on a file <input> via CDP, with a JS-DataTransfer fallback for stubborn pages. PREFERRED: pass `ref` from browser_snapshot; fallback: a CSS `selector`.",
   promptSnippet: "Upload a file to a file input by ref (preferred) or selector",
   promptGuidelines: [
-    "PREFER `ref` from browser_snapshot over a CSS selector — survives re-renders. (File inputs are often hidden; snapshot still surfaces them.)",
+    "File inputs are often hidden; browser_snapshot still surfaces them.",
     "File path must be absolute and readable.",
   ],
   parameters: UploadArgs,
@@ -122,7 +125,7 @@ export const uploadFileTool = defineBrowserTool({
     }
 
     if (args.selector === undefined) {
-      return err({ kind: "invalid_state", message: "Provide either `ref` or `selector`." });
+      return err({ kind: "invalid_args", message: "Provide either `ref` or `selector`." });
     }
     const cdp = await tryCdpUpload(client, args.selector, args.filePath);
     if (cdp.success) {
@@ -145,22 +148,70 @@ export const uploadFileTool = defineBrowserTool({
   },
 });
 
+// Chrome stores the override in its default browser context, so it outlives this client and
+// silently redirects the user's own downloads. Track it, so session teardown can undo it.
+// The flag only records what THIS process set: the daemon is shared by every pi process on the
+// machine and the CDP primitive is last-writer-wins, so another session may have reset or
+// re-pointed it since. A crashed or killed session never reaches teardown, so the override can
+// also outlive the process that set it.
+let activeDownloadOverride: string | undefined;
+
+// Shutdown must not block on a browser that is already gone: a pending restore against a
+// disconnected daemon would otherwise trigger the one-shot reconnect (and Chrome's consent
+// prompt) that 0.11.1 confined to explicit tool calls, and wait up to the connect timeout.
+const SHUTDOWN_RESTORE_TIMEOUT_MS = 2_000;
+
+export const restoreDownloadBehavior = async (client: BrowserClient): Promise<Result<void, ToolErr>> => {
+  const pending = activeDownloadOverride;
+  if (pending === undefined) return ok(undefined);
+  if (!client.status().alive) {
+    return err({ kind: "not_connected", message: `browser not connected; downloads may keep going to ${pending} until Chrome restarts` });
+  }
+  const r = await cdpCallBrowser(client, "Browser.setDownloadBehavior", { behavior: "default" }, { timeoutMs: SHUTDOWN_RESTORE_TIMEOUT_MS });
+  if (!r.success) {
+    return err({ ...r.error, message: `${r.error.message} (downloads may keep going to ${pending})` });
+  }
+  activeDownloadOverride = undefined;
+  return ok(undefined);
+};
+
 const DownloadArgs = Type.Object({
-  downloadPath: Type.String({ description: "Absolute path to a writable directory where downloads should be saved" }),
+  downloadPath: Type.Optional(
+    Type.String({ description: "Absolute path to a writable directory where downloads should be saved" }),
+  ),
+  restore: Type.Optional(
+    Type.Boolean({
+      description:
+        "Undo a previous browser_download: reset Chrome's download behavior back to the user's own default.",
+    }),
+  ),
 });
 
 export const downloadTool = defineBrowserTool({
   name: "browser_download",
   label: "Browser Download",
-  description: "Configure Chrome's download behavior: set the save directory and disable the save-as prompt.",
+  description:
+    "Configure Chrome's download behavior: set the save directory and disable the save-as prompt, or restore the user's default. Restored automatically when this session shuts down cleanly.",
   promptSnippet: "Configure download directory",
   promptGuidelines: [
     "Pass an absolute path to an existing writable directory.",
-    "Affects all subsequent downloads on this browser.",
+    "The override applies to the user's own downloads too, not just yours, and only a clean session shutdown undoes it. Call browser_download({restore:true}) as soon as you are done.",
   ],
   parameters: DownloadArgs,
   concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    if (args.restore === true) {
+      if (args.downloadPath !== undefined) {
+        return err({ kind: "invalid_args", message: "Pass either downloadPath or restore, not both" });
+      }
+      const r = await cdpCallBrowser(client, "Browser.setDownloadBehavior", { behavior: "default" });
+      if (!r.success) return r;
+      activeDownloadOverride = undefined;
+      return ok({ text: "Downloads restored to Chrome's default location", details: { restored: true } });
+    }
+    if (args.downloadPath === undefined) {
+      return err({ kind: "invalid_args", message: "Provide downloadPath to set a directory, or restore:true to undo" });
+    }
     try {
       await mkdir(args.downloadPath, { recursive: true });
     } catch (e) {
@@ -187,6 +238,7 @@ export const downloadTool = defineBrowserTool({
       eventsEnabled: true,
     });
     if (!r.success) return r;
+    activeDownloadOverride = args.downloadPath;
     return ok({
       text: `Downloads will save to: ${args.downloadPath}`,
       details: { downloadPath: args.downloadPath },
@@ -213,7 +265,8 @@ export const printToPdfTool = defineBrowserTool({
     });
     if (!r.success) return r;
     const path = args.outputPath ?? pdfPath(client.namespace);
-    await writeFile(path, Buffer.from(r.data.data, "base64"));
+    const written = await writeFileResult(path, Buffer.from(r.data.data, "base64"));
+    if (!written.success) return written;
     return ok({ text: `PDF saved: ${path}`, details: { path } });
   },
 });

package/src/domains/form-batch.ts

@@ -1,10 +1,12 @@
 import { Type } from "typebox";
 import { type Result, err, ok } from "../util/result";
-import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
-import { fillDeclaration } from "./fill-engine";
+import { defineBrowserTool, type JsonObject, type ToolErr, type ToolOk } from "../util/tool";
 import { detailsOf, resolveAndCall } from "./element-call";
+import { fillField, type FillOptions } from "./page/fill.page";
+import { elementFunctionSource } from "./page/inject";
 
-const FILL_FN = fillDeclaration({ rejectSelect: false, focusFirst: true });
+const FILL_FN = elementFunctionSource(fillField);
+const FILL_OPTIONS: FillOptions = { rejectSelect: false, focusFirst: true };
 
 const FieldValue = Type.Union([Type.String(), Type.Boolean()], {
   description: "Value to set. String for text inputs / textareas / selects / contenteditable; boolean for checkboxes & radios.",
@@ -28,30 +30,30 @@ export const fillFormTool = defineBrowserTool({
   promptSnippet: "Fill many form fields at once by ref — React-safe, self-confirming",
   promptGuidelines: [
     "Preferred for forms: snapshot once, then fill all fields in a single browser_fill_form call.",
-    "Each field: { ref, value }. value is a string for text/select/contenteditable, boolean for checkbox/radio.",
     "The result summarizes how many fields filled cleanly and flags any value mismatches or per-field errors.",
     "Re-run browser_snapshot afterwards to verify the form state if needed.",
   ],
   parameters: FillFormArgs,
   concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    const results: Array<Readonly<Record<string, unknown>>> = [];
+    const results: JsonObject[] = [];
     let okCount = 0;
     const issues: string[] = [];
     for (const f of args.fields) {
-      const r = await resolveAndCall(client, f.ref, FILL_FN, [f.value]);
+      const r = await resolveAndCall(client, f.ref, FILL_FN, [f.value, FILL_OPTIONS]);
       if (!r.success) {
         results.push({ ref: f.ref, ok: false, error: r.error.message });
         issues.push(`ref ${f.ref} (${r.error.message})`);
         continue;
       }
       const res = r.data;
-      const wanted = typeof f.value === "boolean" ? undefined : String(f.value);
-      const got = res.value !== undefined ? String(res.value) : undefined;
-      const mismatch = wanted !== undefined && got !== undefined && got !== wanted && res.text !== wanted;
-      const fieldOk = res.ok === true && !mismatch;
+      const wanted = typeof f.value === "boolean" ? undefined : f.value;
+      const got = res.ok && "value" in res ? res.value : undefined;
+      const label = res.ok && res.kind === "select" ? res.text : undefined;
+      const mismatch = wanted !== undefined && got !== undefined && got !== wanted && label !== wanted;
+      const fieldOk = res.ok && !mismatch;
       if (fieldOk) okCount++;
-      else issues.push(`ref ${f.ref} (${res.ok === false ? (res.reason ?? "failed") : "value mismatch"})`);
+      else issues.push(`ref ${f.ref} (${res.ok ? "value mismatch" : res.reason})`);
       results.push({ ref: f.ref, ok: fieldOk, mismatch, ...detailsOf(f.ref, res) });
     }
     const text =

package/src/domains/form.ts

@@ -1,10 +1,47 @@
 import { Type } from "typebox";
 import { type Result, err, ok } from "../util/result";
-import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
-import { detailsOf, isPageResult, type PageResult, resolveAndCall, runOnElement } from "./element-call";
-import { fillBody } from "./fill-engine";
+import { defineBrowserTool, type JsonObject, type ToolErr, type ToolOk } from "../util/tool";
+import { detailsOf, type ElementOutcome, isPageResult, resolveAndCall, runOnElement } from "./element-call";
+import { fillField, type FillOptions } from "./page/fill.page";
+import { type FocusResult, focusElement, type SelectOption, type SelectResult, type SelectWanted, selectOption, setChecked } from "./page/form.page";
+import { elementFunctionSource } from "./page/inject";
 import { interactiveDiff } from "./ref-resolve";
 
+type Target = { readonly ref?: string | undefined; readonly selector?: string | undefined };
+
+const targetLabel = (t: Target): string => t.ref ?? t.selector ?? "";
+
+// Only the locator the caller actually passed goes into details; an undefined key would not survive pi's JSON store.
+const targetDetails = (t: Target): JsonObject => ({
+  ...(t.ref !== undefined ? { ref: t.ref } : {}),
+  ...(t.selector !== undefined ? { selector: t.selector } : {}),
+});
+
+const noMatch = (t: Target): ToolErr => ({
+  kind: "invalid_state",
+  message: `No element matched: ${targetLabel(t)}`,
+  details: targetDetails(t),
+});
+
+// A page function that returned something the guard does not recognise is a harness bug, not a missing element.
+const badShape = (t: Target, what: string): ToolErr => ({
+  kind: "internal",
+  message: `unexpected page result shape from ${what}`,
+  details: targetDetails(t),
+});
+
+// Narrows an element outcome to the page's typed result, or returns the error to surface.
+const narrow = <T>(
+  outcome: ElementOutcome,
+  t: Target,
+  what: string,
+  guard: (v: unknown) => v is T,
+): Result<T, ToolErr> => {
+  if (!outcome.found) return err(noMatch(t));
+  if (!guard(outcome.value)) return err(badShape(t, what));
+  return ok(outcome.value);
+};
+
 const FillArgs = Type.Object({
   ref: Type.Optional(
     Type.String({
@@ -16,9 +53,8 @@ const FillArgs = Type.Object({
   value: Type.String({ description: "Value to set in the field" }),
 });
 
-const FILL_BODY = `const value = arg;\n${fillBody({ rejectSelect: true, focusFirst: false })}`;
-
-const NOT_FOUND: PageResult = { ok: false, reason: "not_found" };
+const FILL_FN = elementFunctionSource(fillField);
+const FILL_OPTIONS: FillOptions = { rejectSelect: true, focusFirst: false };
 
 export const fillTool = defineBrowserTool({
   name: "browser_fill",
@@ -27,63 +63,39 @@ export const fillTool = defineBrowserTool({
     "Fill a form field (input/textarea/contenteditable), or tick a checkbox/radio by passing 'true'/'false'. PREFERRED: pass `ref` (e.g. 'e7') from browser_snapshot — survives re-renders. Fallback: a CSS `selector`. Writes through the native value setter and fires bubbling 'input'/'change' events, so React/Vue/Angular controlled components and rich-text editors update correctly — unlike browser_type. Refuses a disabled field rather than writing a value the page will ignore. Returns the field's value after writing, plus a compact diff of page changes.",
   promptSnippet: "Fill a form field by ref (preferred) or selector (works with React/Vue controlled inputs)",
   promptGuidelines: [
-    "PREFER `ref` from browser_snapshot (the '[eN]' handle) over a guessed CSS selector — refs survive re-renders and don't require you to invent a selector.",
     "Pass the desired value; no browser_click is needed first.",
     "For a checkbox or radio pass 'true' or 'false' — it toggles `checked`, not the submit value. browser_set_checked does the same thing with a boolean.",
-    "A disabled field is refused: the error says so, rather than reporting a write the page never accepted.",
-    "A 'ref is stale' error means the page changed — re-run browser_snapshot to get fresh refs.",
     "Use browser_type instead only for keystroke-sensitive widgets (autocomplete, masked/segmented inputs).",
     "Fill sets the value but does not focus or submit. To submit a tag/autocomplete input, follow with browser_dispatch_key({ ref, key: 'Enter' }) — not browser_press_key, which targets the focused element and may miss this field.",
     "For a custom (div-based) dropdown, browser_fill won't validate against its option list — open it, run browser_snapshot, then browser_click the option's ref.",
-    "The result reports the field's value after writing and an appended page-changes diff — confirm both match what you intended before moving on.",
+    "Confirm the field value browser_fill returns matches what you intended.",
   ],
   parameters: FillArgs,
   concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    const r = await runOnElement(client, {
-      ref: args.ref,
-      selector: args.selector,
-      fnBody: FILL_BODY,
-      arg: args.value,
-      notFound: NOT_FOUND,
-    });
+    const r = await runOnElement(client, { ref: args.ref, selector: args.selector, functionDeclaration: FILL_FN, args: [args.value, FILL_OPTIONS] });
     if (!r.success) return r;
-    const res = isPageResult(r.data) ? r.data : undefined;
-    const target = args.ref ?? args.selector ?? "";
-    if (res === undefined || res.reason === "not_found") {
-      return err({
-        kind: "invalid_state",
-        message: `No element matched: ${target}`,
-        details: { ref: args.ref, selector: args.selector },
-      });
-    }
+    const narrowed = narrow(r.data, args, "browser_fill", isPageResult);
+    if (!narrowed.success) return narrowed;
+    const res = narrowed.data;
+    const target = targetLabel(args);
     if (!res.ok) {
       const details = { ref: args.ref, selector: args.selector, ...(res.tag !== undefined ? { tag: res.tag } : {}) };
-      if (res.kind === "select") {
+      if (res.code === "select_rejected") {
         return err({
           kind: "invalid_state",
           message: `Element <select> is not fillable (not an input, textarea, or contenteditable): ${target}. For <select> use browser_select_option.`,
           details,
         });
       }
-      return err({
-        kind: "invalid_state",
-        message: `Could not fill ${target}: ${res.reason ?? "unknown reason"}`,
-        details,
-      });
+      return err({ kind: "invalid_state", message: `Could not fill ${target}: ${res.reason}`, details });
     }
-    const shown = res.value !== undefined ? JSON.stringify(res.value) : `checked=${res.checked === true}`;
+    const verified = "checked" in res ? res.checked : res.value;
+    const shown = "checked" in res ? `checked=${res.checked}` : JSON.stringify(res.value);
     const diff = await interactiveDiff(client);
     return ok({
       text: `Filled ${target} = ${shown}${diff}`,
-      details: {
-        ref: args.ref,
-        selector: args.selector,
-        value: args.value,
-        verified: res.value ?? res.checked,
-        ...(res.tag !== undefined ? { tag: res.tag } : {}),
-        ...(res.kind !== undefined ? { kind: res.kind } : {}),
-      },
+      details: { ...targetDetails(args), value: args.value, verified, tag: res.tag, kind: res.kind },
     });
   },
 });
@@ -95,21 +107,13 @@ const FocusArgs = Type.Object({
   selector: Type.Optional(Type.String({ description: "CSS selector of the element to focus (fallback when no ref)" })),
 });
 
-type FocusResult = { status: "ok"; tag: string } | { status: "not_found" } | { status: "not_focusable"; tag: string };
-
 const isFocusResult = (v: unknown): v is FocusResult => {
   if (typeof v !== "object" || v === null || !("status" in v)) return false;
-  if (v.status === "not_found") return true;
   if (v.status === "ok" || v.status === "not_focusable") return "tag" in v && typeof v.tag === "string";
   return false;
 };
 
-const FOCUS_FN = `
-  const el = this;
-  if (typeof el.focus !== "function") return { status: "not_focusable", tag: el.tagName };
-  el.focus();
-  return document.activeElement === el ? { status: "ok", tag: el.tagName } : { status: "not_focusable", tag: el.tagName };
-`;
+const FOCUS_FN = elementFunctionSource(focusElement);
 
 export const focusTool = defineBrowserTool({
   name: "browser_focus",
@@ -118,24 +122,21 @@ export const focusTool = defineBrowserTool({
     "Focus an element via the DOM .focus() method — deterministic, no coordinate accuracy needed. PREFERRED: pass `ref` from browser_snapshot; fallback: a CSS `selector`. Use before browser_type when a click might miss the field.",
   promptSnippet: "Focus an element by ref (preferred) or selector",
   promptGuidelines: [
-    "PREFER `ref` from browser_snapshot over a CSS selector — survives re-renders.",
-    "Use before browser_type to guarantee the right field is focused without relying on click coordinates.",
     "For simply setting a value, prefer browser_fill (it doesn't need a separate focus step).",
   ],
   parameters: FocusArgs,
   concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    const r = await runOnElement(client, { ref: args.ref, selector: args.selector, fnBody: FOCUS_FN, arg: "" });
+    const r = await runOnElement(client, { ref: args.ref, selector: args.selector, functionDeclaration: FOCUS_FN, args: [] });
     if (!r.success) return r;
-    const res = isFocusResult(r.data) ? r.data : undefined;
-    const target = args.ref ?? args.selector ?? "";
-    if (res === undefined || res.status === "not_found") {
-      return err({ kind: "invalid_state", message: `No element matched: ${target}`, details: { ref: args.ref, selector: args.selector } });
-    }
+    const narrowed = narrow(r.data, args, "browser_focus", isFocusResult);
+    if (!narrowed.success) return narrowed;
+    const res = narrowed.data;
+    const target = targetLabel(args);
     if (res.status === "not_focusable") {
-      return err({ kind: "invalid_state", message: `Element <${res.tag.toLowerCase()}> could not be focused: ${target}`, details: { ref: args.ref, selector: args.selector, tag: res.tag } });
+      return err({ kind: "invalid_state", message: `Element <${res.tag.toLowerCase()}> could not be focused: ${target}`, details: { ...targetDetails(args), tag: res.tag } });
     }
-    return ok({ text: `Focused ${target}`, details: { ref: args.ref, selector: args.selector, tag: res.tag } });
+    return ok({ text: `Focused ${target}`, details: { ...targetDetails(args), tag: res.tag } });
   },
 });
 
@@ -149,20 +150,13 @@ const SelectOptionArgs = Type.Object({
   index: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based option index to select" })),
 });
 
-type SelectResult =
-  | { status: "ok"; value: string; label: string }
-  | { status: "not_found" }
-  | { status: "not_select"; tag: string }
-  | { status: "no_match"; options: ReadonlyArray<{ value: string; label: string }> };
-
-const isSelectOption = (v: unknown): v is { value: string; label: string } =>
+const isSelectOption = (v: unknown): v is SelectOption =>
   typeof v === "object" && v !== null
   && "value" in v && typeof v.value === "string"
   && "label" in v && typeof v.label === "string";
 
 const isSelectResult = (v: unknown): v is SelectResult => {
   if (typeof v !== "object" || v === null || !("status" in v)) return false;
-  if (v.status === "not_found") return true;
   if (v.status === "not_select") return "tag" in v && typeof v.tag === "string";
   if (v.status === "ok") {
     return "value" in v && typeof v.value === "string" && "label" in v && typeof v.label === "string";
@@ -173,21 +167,7 @@ const isSelectResult = (v: unknown): v is SelectResult => {
   return false;
 };
 
-const SELECT_FN = `
-  const el = this;
-  if (el.tagName !== "SELECT") return { status: "not_select", tag: el.tagName };
-  const opts = Array.from(el.options);
-  const wv = arg.wv, wl = arg.wl, wi = arg.wi;
-  let opt = null;
-  if (wi !== null) opt = opts[wi] || null;
-  else if (wv !== null) opt = opts.find(o => o.value === wv) || null;
-  else if (wl !== null) opt = opts.find(o => o.text === wl) || null;
-  if (!opt) return { status: "no_match", options: opts.map(o => ({ value: o.value, label: o.text })) };
-  el.value = opt.value;
-  el.dispatchEvent(new Event("input", { bubbles: true }));
-  el.dispatchEvent(new Event("change", { bubbles: true }));
-  return { status: "ok", value: opt.value, label: opt.text };
-`;
+const SELECT_FN = elementFunctionSource(selectOption);
 
 export const selectOptionTool = defineBrowserTool({
   name: "browser_select_option",
@@ -196,60 +176,41 @@ export const selectOptionTool = defineBrowserTool({
     "Select an option in a native <select> element by value, visible label, or index. PREFERRED: pass `ref` from browser_snapshot; fallback: a CSS `selector`. Sets the selection and fires bubbling 'input'/'change' events so framework listeners update. On no match, returns the available options.",
   promptSnippet: "Select an option in a native <select> by ref (preferred) or selector",
   promptGuidelines: [
-    "PREFER `ref` from browser_snapshot over a CSS selector — survives re-renders.",
     "Provide exactly one of value, label, or index to choose the option.",
     "For custom (non-native) dropdowns built from divs, click to open then browser_click the option instead.",
-    "If no option matches, the error details list the available options so you can retry.",
   ],
   parameters: SelectOptionArgs,
   concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
     if (args.value === undefined && args.label === undefined && args.index === undefined) {
-      return err({ kind: "invalid_state", message: "Provide one of value, label, or index." });
+      return err({ kind: "invalid_args", message: "Provide one of value, label, or index." });
     }
-    // null sentinels distinguish "not provided" from a real empty-string match.
-    const arg = { wv: args.value ?? null, wl: args.label ?? null, wi: args.index ?? null };
-    const r = await runOnElement(client, { ref: args.ref, selector: args.selector, fnBody: SELECT_FN, arg });
+    const wanted: SelectWanted = { wv: args.value ?? null, wl: args.label ?? null, wi: args.index ?? null };
+    const r = await runOnElement(client, { ref: args.ref, selector: args.selector, functionDeclaration: SELECT_FN, args: [wanted] });
     if (!r.success) return r;
-    const res = isSelectResult(r.data) ? r.data : undefined;
-    const target = args.ref ?? args.selector ?? "";
-    if (res === undefined || res.status === "not_found") {
-      return err({ kind: "invalid_state", message: `No element matched: ${target}`, details: { ref: args.ref, selector: args.selector } });
-    }
+    const narrowed = narrow(r.data, args, "browser_select_option", isSelectResult);
+    if (!narrowed.success) return narrowed;
+    const res = narrowed.data;
+    const target = targetLabel(args);
     if (res.status === "not_select") {
-      return err({ kind: "invalid_state", message: `Element <${res.tag.toLowerCase()}> is not a <select>: ${target}`, details: { ref: args.ref, selector: args.selector, tag: res.tag } });
+      return err({ kind: "invalid_state", message: `Element <${res.tag.toLowerCase()}> is not a <select>: ${target}`, details: { ...targetDetails(args), tag: res.tag } });
     }
     if (res.status === "no_match") {
       return err({
         kind: "invalid_state",
         message: `No matching option in ${target}. Available: ${res.options.map((o) => o.label).join(", ")}`,
-        details: { ref: args.ref, selector: args.selector, options: res.options },
+        details: { ...targetDetails(args), options: res.options },
       });
     }
     const diff = await interactiveDiff(client);
     return ok({
       text: `Selected "${res.label}" (value=${JSON.stringify(res.value)}) in ${target}${diff}`,
-      details: { ref: args.ref, selector: args.selector, value: res.value, label: res.label },
+      details: { ...targetDetails(args), value: res.value, label: res.label },
     });
   },
 });
 
-const CHECK_FN = `
-function(checked) {
-  const el = this;
-  const tag = (el.tagName || "").toLowerCase();
-  const type = (el.type || "").toLowerCase();
-  if (tag !== "input" || (type !== "checkbox" && type !== "radio")) return { ok: false, reason: "ref is not a checkbox or radio" };
-  if (el.disabled) return { ok: false, reason: "element is disabled" };
-  const want = checked === true;
-  let changed = false;
-  if (el.checked !== want) {
-    try { el.click(); } catch (e) {}
-    if (el.checked !== want) { el.checked = want; el.dispatchEvent(new Event("change", { bubbles: true })); }
-    changed = true;
-  }
-  return { ok: true, checked: el.checked, changed: changed };
-}`;
+const CHECK_FN = elementFunctionSource(setChecked);
 
 const SetCheckedArgs = Type.Object({
   ref: Type.String({ description: "Stable element ref of a checkbox or radio from browser_snapshot (e.g. 'e7')." }),
@@ -263,7 +224,6 @@ export const setCheckedTool = defineBrowserTool({
     "Set a checkbox or radio to a desired checked state by ref. Only acts if the current state differs, fires change, and reports the final state. Get the ref from browser_snapshot's [eN].",
   promptSnippet: "Set a checkbox/radio checked state by ref",
   promptGuidelines: [
-    "checked:true ticks the box, checked:false unticks it. Idempotent — no-op if already in the desired state.",
     "For radios, set checked:true on the option you want; the group deselects the others.",
   ],
   parameters: SetCheckedArgs,
@@ -273,10 +233,13 @@ export const setCheckedTool = defineBrowserTool({
     if (!r.success) return r;
     const res = r.data;
     if (!res.ok) {
-      return err({ kind: "invalid_state", message: `Could not set checked on ref ${args.ref}: ${res.reason ?? "unknown reason"}`, details: detailsOf(args.ref, res) });
+      return err({ kind: "invalid_state", message: `Could not set checked on ref ${args.ref}: ${res.reason}`, details: detailsOf(args.ref, res) });
+    }
+    if (!("checked" in res)) {
+      return err({ kind: "internal", message: `unexpected page result shape from browser_set_checked (kind ${res.kind})`, details: { ref: args.ref } });
     }
     return ok({
-      text: `Set ref ${args.ref} checked=${res.checked}` + (res.changed === false ? " (already)" : ""),
+      text: `Set ref ${args.ref} checked=${res.checked}` + (res.changed ? "" : " (already)"),
       details: detailsOf(args.ref, res),
     });
   },

package/src/domains/headers.ts

@@ -0,0 +1,89 @@
+import { Type } from "typebox";
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { cdpCall } from "./cdp-call";
+
+const HeaderValue = Type.String({
+  maxLength: 8192,
+  pattern: "^[^\\r\\n]*$",
+});
+
+const SetHeadersArgs = Type.Object({
+  headers: Type.Record(Type.String(), HeaderValue, {
+    minProperties: 1,
+    maxProperties: 64,
+    description: "Extra HTTP request headers for the current owned tab. Names must be valid HTTP tokens.",
+  }),
+});
+
+const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+
+const currentOwnedTarget = (
+  client: BrowserClient,
+): Result<{ readonly targetId: string }, ToolErr> => {
+  const current = client.current();
+  if (current === null) {
+    return err({ kind: "invalid_state", message: "No tab attached." });
+  }
+  if (!client.owns(current.targetId)) {
+    return err({
+      kind: "invalid_state",
+      message: `Current tab ${current.targetId} is not owned by this harness session.`,
+    });
+  }
+  return ok({ targetId: current.targetId });
+};
+
+export const setHeadersTool = defineBrowserTool({
+  name: "browser_set_headers",
+  label: "Browser Set Headers",
+  description:
+    "Set extra HTTP request headers on the current owned tab. Headers persist for subsequent document, subresource, fetch, and XHR requests until cleared or the tab closes.",
+  promptSnippet: "Set extra request headers on the current owned tab",
+  promptGuidelines: [
+    "If no tab is attached yet, call browser_new_tab without a URL first.",
+    "Call before navigation when a site requires routing or environment headers.",
+    "Call browser_clear_headers before switching tabs or navigating this tab to another origin.",
+    "Header values are never echoed in tool output.",
+  ],
+  parameters: SetHeadersArgs,
+  concurrency: "serialized",
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const target = currentOwnedTarget(client);
+    if (!target.success) return target;
+    const invalidName = Object.keys(args.headers).find((name) => !HEADER_NAME.test(name));
+    if (invalidName !== undefined) {
+      return err({ kind: "invalid_args", message: `Invalid HTTP header name: ${JSON.stringify(invalidName)}` });
+    }
+    const result = await cdpCall(client, "Network.setExtraHTTPHeaders", { headers: args.headers });
+    if (!result.success) return result;
+    const headerNames = Object.keys(args.headers).sort();
+    return ok({
+      text: `Set ${headerNames.length} extra HTTP header(s) on tab ${target.data.targetId}: ${headerNames.join(", ")}. Values are hidden. Clear them before switching tabs or navigating to another origin.`,
+      details: { targetId: target.data.targetId, headerNames, count: headerNames.length },
+    });
+  },
+});
+
+export const clearHeadersTool = defineBrowserTool({
+  name: "browser_clear_headers",
+  label: "Browser Clear Headers",
+  description: "Clear all extra HTTP request headers previously set on the current owned tab.",
+  promptSnippet: "Clear extra request headers from the current owned tab",
+  promptGuidelines: [
+    "Call after finishing an environment-specific workflow, before switching tabs, or before navigating to another origin.",
+  ],
+  parameters: Type.Object({}),
+  concurrency: "serialized",
+  async handler(_args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const target = currentOwnedTarget(client);
+    if (!target.success) return target;
+    const result = await cdpCall(client, "Network.setExtraHTTPHeaders", { headers: {} });
+    if (!result.success) return result;
+    return ok({
+      text: `Cleared extra HTTP headers from tab ${target.data.targetId}.`,
+      details: { targetId: target.data.targetId },
+    });
+  },
+});