pi-browser-harness 0.14.1 → 0.16.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
+## 0.16.0 — 2026-11-07
+
+### Added
+
+- **`browser_web_search` falls back across search engines.** With no `engine` given it tries Google, then Bing, DuckDuckGo and Brave, until one returns results, so a Google CAPTCHA or markup change no longer breaks search. `details.engine` says which engine answered and `details.fallbacks` lists the ones that failed first. When every engine fails the error is `all_engines_failed` with each engine's reason; when none found anything it stays `no_results`.
+- **`engine` parameter.** Name one engine (`google`, `bing`, `duckduckgo`, `brave`) to search it alone, with no fallback.
+- **Pluggable engines.** Each engine is a self-contained module mounted into a registry (`createEngineRegistry().mount(engine)`) that is injected into `createWebSearchTool`; mount order is the fallback order. Adding an engine is one module and one `mount`.
+
+## 0.15.1 — 2026-11-07
+
+- Re-release of 0.15.0, whose npm publish failed (the provenance log returned 502, then rejected the retry as a duplicate). No code changes.
+
+## 0.15.0 — 2026-11-07
+
+### Changed
+
+- **`browser_fill` and `browser_type` are one tool: `browser_type`.** Pass a `ref` (or `selector`) and it focuses the field, replaces its value (`clear:false` appends; `text: ""` empties it), types with real input events so autocomplete lists open, and reports the value read back. When typing does not produce the value (date or masked inputs) it sets the value directly and says so. With no ref it types into the focused element, appending as before. Saved recipes with `fill` steps still replay.
+
+### Fixed
+
+- **`browser_click` no longer clicks into nothing.** A ref is scrolled into view (nested scrolling lists included) and measured at click time; a point still outside the viewport, or an `x`/`y` outside it, is refused with the reason. When something covers the element (an overlay, a sticky header) the result says what was clicked instead. An `x`/`y` click names the element it landed on.
+- **`browser_press_key` runs Cmd/Ctrl shortcuts.** Cmd/Ctrl + A, C, X, V, Z, Y now carry Chrome's editing command, so select-all, copy, paste and undo work. Letter keys send the right `code` (`KeyA`) and key code (65).
+- **`browser_execute_js` waits up to 30s by default, and `timeoutMs` (max 120s) raises it.** It used to stop at 10s, mid-way through scripts that loop with waits. A timeout now says the script may have partly run.
+- **`browser_screenshot` says how its pixels map to click coordinates** when the image is not 1:1 with CSS pixels (2× on Retina, or after `maxDim`).
+
 ## 0.14.1 — 2026-11-07
 
 ### Fixed

package/README.md

@@ -18,7 +18,7 @@ no MCP hop, no second browser, no extra API keys.
 | **Browser** | Your running Chrome — real profile, live sessions | Launches a clean instance | Launches a clean instance | Launches a clean instance |
 | **Element targeting** | AX-tree refs (`[eN]`) that re-resolve at action time; coordinate and selector fallbacks | Selectors / AX locators | CSS selectors | LLM-inferred selectors |
 | **Input dispatch** | Compositor-level CDP input — works through iframes, shadow DOM, cross-origin frames | DOM-level | DOM-level | DOM-level |
-| **Framework-safe writes** | `browser_fill` writes via the native setter and fires bubbling events, so controlled inputs keep the value | Native fill | Manual | Native fill |
+| **Framework-safe writes** | `browser_type` types with real input events, reads the value back, and falls back to the native setter when typing doesn't take | Native fill | Manual | Native fill |
 | **Transport** | Native pi extension, in-process | MCP / JSON-RPC round trip | MCP / JSON-RPC round trip | In-process + its own LLM calls |
 | **Extra credentials** | None | None | None | Its own model API key |
 | **Concurrency** | Reads run in parallel; mutations auto-serialize through a shared mutex | Sequential | Sequential | Sequential |
@@ -76,10 +76,12 @@ interactive element carries a stable ref (`[eN]`) plus click coordinates `@(x,y)
 [e12] button   "Create account" @(456,412)
 ```
 
-Pass the ref — not the coordinates — to `browser_click`, `browser_fill`, `browser_select_option`,
+Pass the ref — not the coordinates — to `browser_click`, `browser_type`, `browser_select_option`,
 `browser_focus`, `browser_upload_file`, or `browser_dispatch_key`. Refs are keyed to element
 identity, so they re-resolve position at action time and survive the re-renders that SPA forms
-trigger on every keystroke. Coordinates go stale the moment the layout reflows.
+trigger on every keystroke. Coordinates go stale the moment the layout reflows. `browser_click` by ref
+scrolls the element into view first (inside scrolling lists too) and warns when something covers it;
+an `x`/`y` outside the viewport is refused instead of clicking nothing.
 
 Three things follow from that:
 
@@ -117,7 +119,7 @@ Three things follow from that:
 
 | Tool | Purpose |
 |---|---|
-| `browser_web_search` | Query → ranked `{title, url, snippet, rank}`, by scraping a real Google SERP in your Chrome. No API key. Links only. |
+| `browser_web_search` | Query → ranked `{title, url, snippet, rank}`, by scraping a real search results page in your Chrome. No API key. Links only. Walks the fallback ladder Google → Bing → DuckDuckGo → Brave until one answers, or searches only the `engine` you name. |
 | `browser_read_page` | Reader mode. A `url` (opened and closed in its own tab) or an owned `targetId` → clean article text, boilerplate stripped. |
 
 Both run in isolated tabs and never disturb your current page.
@@ -127,10 +129,9 @@ Both run in isolated tabs and never disturb your current page.
 | Tool | Purpose |
 |---|---|
 | `browser_click` | Click by `ref` (preferred) or viewport `x`/`y`. Compositor-level, so iframes and shadow DOM work. |
-| `browser_fill` | Set an input, textarea, or contenteditable. Fires bubbling `input`/`change`, returns the value written. |
 | `browser_select_option` | Choose in a native `<select>` by value, label, or index. Returns available options on no match. |
 | `browser_focus` | Deterministic `.focus()` — no coordinate accuracy needed. |
-| `browser_type` | Type into the focused element. For keystroke-sensitive widgets; prefer `browser_fill` otherwise. |
+| `browser_type` | Enter text into a field by `ref`/selector (replaces its value; `clear:false` appends) or into the focused element. Real input events, so autocomplete opens; returns the value read back. |
 | `browser_press_key` | Press a key with an optional modifier bitfield. |
 | `browser_dispatch_key` | Synthetic DOM `KeyboardEvent` on one element, for pages that ignore raw CDP keys. |
 | `browser_scroll` | Scroll by delta. W3C wheel convention: positive `deltaY` = down. |
@@ -202,7 +203,7 @@ Wait, snapshot once, then act by ref. No screenshots anywhere in this loop.
 ```
 browser_wait_for({ selector: "#email" })
 browser_snapshot()                                  // → [e7] textbox, [e9] combobox, [e12] button
-browser_fill({ ref: "e7", value: "a@b.com" })
+browser_type({ ref: "e7", text: "a@b.com" })
 browser_select_option({ ref: "e9", label: "India" })
 browser_click({ ref: "e12" })                       // re-resolves position even after reflow
 ```
@@ -244,8 +245,14 @@ browser_network_requests({                          // did a request 4xx/5xx?
 ```
 browser_web_search({ query: "chrome devtools protocol overview", limit: 5 })
 browser_read_page({ url: "<the best result's url>" })
+
+// Search one engine only, with no fallback:
+browser_web_search({ query: "chrome devtools protocol overview", engine: "bing" })
 ```
 
+`details.engine` names the engine that answered, and `details.fallbacks` lists any engines that failed
+first (CAPTCHA, no results, markup change, load failure).
+
 Both tools open their own isolated tab, so neither disturbs the tab you are working in.
 
 ### Keyboard modifiers
@@ -352,7 +359,7 @@ re-runnable.
 
 Another extension can add its own `browser_*` tools to this harness. Contributed tools share the
 same client, mutation mutex, tab ownership, and lane prompt as the built-ins, so a `serialized` tool
-you add queues behind `browser_click` exactly as `browser_fill` does.
+you add queues behind `browser_click` exactly as `browser_type` does.
 
 Define the tool with `defineBrowserTool` and hand it to `registerBrowserTools` at your extension's
 load time, before pi emits `session_start`. The harness registers it with pi on the next

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "Browser control extension for pi — navigate, click, type, screenshot, and extract data from real Chrome via CDP",
   "keywords": [
     "pi-package",

package/skills/pi-browser-harness/SKILL.md

@@ -61,7 +61,6 @@ Generated from `src/registry.ts` by `npm run gen:skill`; do not edit by hand.
 | `browser_download` | serialized | Configure download directory |
 | `browser_drag_and_drop` | serialized | Drag and drop between two coordinates |
 | `browser_execute_js` | parallel | Execute JS in the page — surgical DOM reads (preferred over screenshot) |
-| `browser_fill` | serialized | Fill a form field by ref (preferred) or selector (works with React/Vue controlled inputs) |
 | `browser_fill_form` | serialized | Fill many form fields at once by ref — React-safe, self-confirming |
 | `browser_focus` | serialized | Focus an element by ref (preferred) or selector |
 | `browser_go_back` | serialized | Go back one page |
@@ -89,7 +88,7 @@ Generated from `src/registry.ts` by `npm run gen:skill`; do not edit by hand.
 | `browser_setup` | parallel | Initialize browser connection |
 | `browser_snapshot` | parallel | Get accessibility-tree snapshot with stable element refs (default for page inspection) |
 | `browser_switch_tab` | serialized | Switch tabs |
-| `browser_type` | serialized | Type text into the focused element |
+| `browser_type` | serialized | Type text into a field by ref (preferred), selector, or the focused element |
 | `browser_upload_file` | serialized | Upload a file to a file input by ref (preferred) or selector |
 | `browser_viewport_resize` | serialized | Resize the viewport (responsive testing) |
 | `browser_wait` | parallel | Wait N seconds |

package/src/cdp/commands.ts

@@ -271,6 +271,18 @@ export const COMMANDS = {
     }),
     Type.Object({ data: Type.String(), stream: Type.Optional(Type.String()) }),
   ),
+  "Page.getLayoutMetrics": cmd(
+    Empty,
+    Type.Object(
+      {
+        cssLayoutViewport: Type.Object(
+          { clientWidth: Type.Number(), clientHeight: Type.Number() },
+          { additionalProperties: true },
+        ),
+      },
+      { additionalProperties: true },
+    ),
+  ),
   "Page.handleJavaScriptDialog": cmd(
     Type.Object({ accept: Type.Boolean(), promptText: Type.Optional(Type.String()) }),
     Empty,
@@ -322,6 +334,22 @@ export const COMMANDS = {
       ),
     }),
   ),
+  "DOM.scrollIntoViewIfNeeded": cmd(
+    Type.Object({ nodeId: Type.Optional(Type.Number()), backendNodeId: Type.Optional(Type.Number()) }),
+    Empty,
+  ),
+  "DOM.getNodeForLocation": cmd(
+    Type.Object({
+      x: Type.Integer(),
+      y: Type.Integer(),
+      includeUserAgentShadowDOM: Type.Optional(Type.Boolean()),
+      ignorePointerEventsNone: Type.Optional(Type.Boolean()),
+    }),
+    Type.Object(
+      { backendNodeId: Type.Number(), frameId: Type.Optional(Type.String()), nodeId: Type.Optional(Type.Number()) },
+      { additionalProperties: true },
+    ),
+  ),
   "DOM.resolveNode": cmd(
     Type.Object({ nodeId: Type.Optional(Type.Number()), backendNodeId: Type.Optional(Type.Number()) }),
     Type.Object({ object: RemoteObject }),

package/src/client.ts

@@ -59,7 +59,7 @@ export type BrowserClient = {
   stop(): Promise<void>;
   detach(): Promise<void>;
   closeOwnedTabs(): Promise<void>;
-  evaluateJs(expression: string, sessionId?: string): Promise<Result<unknown, CdpError>>;
+  evaluateJs(expression: string, sessionId?: string, opts?: { readonly timeoutMs?: number }): Promise<Result<unknown, CdpError>>;
   pageInfo(): Promise<Result<PageInfoResult, CdpError>>;
   takeDialog(): DialogInfo | null;
   listTabs(includeInternal?: boolean): Promise<Result<ReadonlyArray<TabInfo>, CdpError>>;
@@ -260,9 +260,16 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     return running;
   };
 
-  const evaluateJs = async (expression: string, sessionId?: string): Promise<Result<unknown, CdpError>> => {
+  const evaluateJs = async (
+    expression: string,
+    sessionId?: string,
+    opts?: { readonly timeoutMs?: number },
+  ): Promise<Result<unknown, CdpError>> => {
     const params = evaluateParams(expression);
-    const r = sessionId ? await session.callOnTarget("Runtime.evaluate", params, sessionId) : await session.call("Runtime.evaluate", params);
+    const callOpts = opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {};
+    const r = sessionId
+      ? await session.callOnTarget("Runtime.evaluate", params, sessionId, callOpts)
+      : await session.call("Runtime.evaluate", params, callOpts);
     if (!r.success) return r;
     if (r.data.exceptionDetails !== undefined) {
       return err(cdpError("remote_error", `JS evaluation failed: ${JSON.stringify(r.data.exceptionDetails)}`, "Runtime.evaluate"));

package/src/daemon/bridge.ts

@@ -1,7 +1,7 @@
 import { isCdpRawMessage } from "../cdp/types";
 import type { CdpRawMessage } from "../cdp/types";
 import type { WireRequest, WireResponse, WireEvent } from "./protocol";
-import { CDP_COMMAND_TIMEOUT_MS, DAEMON_RECONNECT_METHOD } from "./protocol";
+import { DAEMON_RECONNECT_METHOD, commandTimeoutFor } from "./protocol";
 import { asString, isRecord } from "../util/guards";
 import { type ChromeConnectionDependencies, type ConnectionStatus, createChromeConnection } from "./connection";
 
@@ -246,6 +246,7 @@ export const createCdpBridge = (options: ChromeConnectionDependencies = {}): Cdp
       if (sessionId !== undefined) router.release(sessionId);
     }
 
+    const timeoutMs = commandTimeoutFor(req);
     const daemonId = mux.allocate(
       {
         clientId,
@@ -257,8 +258,8 @@ export const createCdpBridge = (options: ChromeConnectionDependencies = {}): Cdp
       (id) =>
         setTimeout(() => {
           mux.take(id);
-          send(clientId, errorResponse(req.id, `Timeout after ${CDP_COMMAND_TIMEOUT_MS}ms: ${req.method}`));
-        }, CDP_COMMAND_TIMEOUT_MS),
+          send(clientId, errorResponse(req.id, `Timeout after ${timeoutMs}ms: ${req.method}`));
+        }, timeoutMs),
     );
 
     const payload: Record<string, unknown> = {

package/src/daemon/protocol.ts

@@ -6,6 +6,8 @@ export type WireRequest = {
   readonly method: string;
   readonly params?: Record<string, unknown>;
   readonly sessionId?: string;
+  // How long the daemon waits for Chrome's answer; see commandTimeoutFor.
+  readonly timeoutMs?: number;
 };
 
 export type WireResponse = {
@@ -71,6 +73,7 @@ const isWireMessage = (v: unknown): v is WireMessage => {
       if (typeof v["id"] !== "number") return false;
       if (typeof v["method"] !== "string") return false;
       if (!isOptionalRecord(v["params"])) return false;
+      if (v["timeoutMs"] !== undefined && typeof v["timeoutMs"] !== "number") return false;
       return isOptionalString(v["sessionId"]);
     }
     case "response": {
@@ -138,3 +141,11 @@ export const CDP_RECONNECT_COOLDOWN_MAX_MS = 5 * 60 * 1000;
 export const DAEMON_RECONNECT_METHOD = "Daemon.reconnect";
 
 export const CDP_COMMAND_TIMEOUT_MS = 10_000;
+
+// The longest a caller may ask the daemon to wait for one command (browser_execute_js's timeoutMs).
+export const CDP_COMMAND_TIMEOUT_MAX_MS = 120_000;
+
+// A request may lengthen the daemon's wait (a long-running script) but never shorten it below the default: short
+// client-side probes already give up on their own, and a shorter daemon timer would only race them.
+export const commandTimeoutFor = (req: { readonly timeoutMs?: number }): number =>
+  Math.min(Math.max(req.timeoutMs ?? CDP_COMMAND_TIMEOUT_MS, CDP_COMMAND_TIMEOUT_MS), CDP_COMMAND_TIMEOUT_MAX_MS);

package/src/daemon/transport.ts

@@ -194,6 +194,7 @@ export const createDaemonTransport = (clientId: string, socketPath: string = DAE
       method,
       params,
       ...(sessionId !== null ? { sessionId } : {}),
+      ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
     };
 
     return sendWithTimeout(pending, id, method, timeoutMs, "Daemon", () => sock.write(serialize(req) + "\n"));

package/src/domains/cdp-call.ts

@@ -55,8 +55,9 @@ export const evalJs = async (
   client: BrowserClient,
   expression: string,
   sessionId?: string,
+  opts?: { readonly timeoutMs?: number },
 ): Promise<Result<unknown, ToolErr>> => {
-  const r = await client.evaluateJs(expression, sessionId);
+  const r = await client.evaluateJs(expression, sessionId, opts);
   if (!r.success) return err(cdpErrToToolErr(r.error, "Runtime.evaluate"));
   return r;
 };

package/src/domains/click.ts

@@ -55,7 +55,7 @@ export const clickTool = defineBrowserTool({
   name: "browser_click",
   label: "Browser Click",
   description:
-    "Click an element. PREFERRED: pass `ref` (e.g. 'e12') from browser_snapshot — it re-resolves the element's position at click time, so it works even after the page re-renders and moves things. Fallback: pass viewport CSS-pixel `x`/`y`. Compositor-level click works through iframes, shadow DOM, and cross-origin content. After clicking, a compact diff of page changes is appended.",
+    "Click an element. PREFERRED: pass `ref` (e.g. 'e12') from browser_snapshot — it scrolls the element into view (inside scrolling lists too), measures it at click time, and warns if something covers it. Fallback: pass viewport CSS-pixel `x`/`y` (refused when outside the viewport; the result names the element that was hit). Compositor-level click works through iframes, shadow DOM, and cross-origin content. After clicking, a compact diff of page changes is appended.",
   promptSnippet: "Click an element by ref (preferred) or pixel coordinates",
   promptGuidelines: [
     "If a click doesn't register, run pi with --browser-debug-clicks (or set BH_DEBUG_CLICKS=1) to get annotated screenshots. For React/Vue components ignoring clicks, try browser_dispatch_key.",
@@ -69,7 +69,10 @@ export const clickTool = defineBrowserTool({
 
     const resolved = await resolveTarget(client, args);
     if (!resolved.success) return resolved;
-    const { x, y, label: target } = resolved.data;
+    const { x, y, label, covered, hit } = resolved.data;
+    const target = label
+      + (hit !== undefined ? ` on ${hit}` : "")
+      + (covered !== undefined ? `\n⚠ The point was covered by ${covered}, so the click went to that element, not [${args.ref ?? ""}]. Close the overlay or scroll, then re-snapshot.` : "");
 
     const clicked = await dispatchClick(client, x, y, button, count);
     if (!clicked.success) return clicked;

package/src/domains/form.ts

@@ -2,7 +2,8 @@ import { Type } from "typebox";
 import { type Result, err, ok } from "../util/result";
 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 { fillField, type FillOptions, type PageResult } from "./page/fill.page";
+import type { BrowserClient } from "../client";
 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";
@@ -56,45 +57,53 @@ const FillArgs = Type.Object({
 const FILL_FN = elementFunctionSource(fillField);
 const FILL_OPTIONS: FillOptions = { rejectSelect: true, focusFirst: false };
 
+type FilledField = Extract<PageResult, { readonly ok: true }>;
+
+// Writes `value` through the page's native value setter (the fill engine in page/fill.page.ts) and returns what the
+// field holds afterwards. browser_type falls back to it when typing did not produce the value; recipe "fill" steps
+// (recorded by the old browser_fill and by browser_fill_form) replay through it.
+export const nativeFill = async (
+  client: BrowserClient,
+  t: Target,
+  value: string,
+): Promise<Result<FilledField, ToolErr>> => {
+  const r = await runOnElement(client, { ref: t.ref, selector: t.selector, functionDeclaration: FILL_FN, args: [value, FILL_OPTIONS] });
+  if (!r.success) return r;
+  const narrowed = narrow(r.data, t, "browser_fill", isPageResult);
+  if (!narrowed.success) return narrowed;
+  const res = narrowed.data;
+  if (res.ok) return ok(res);
+  const target = targetLabel(t);
+  const details = { ...targetDetails(t), ...(res.tag !== undefined ? { tag: res.tag } : {}) };
+  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}`, details });
+};
+
+// Not registered for the agent any more (browser_type replaces it); kept so saved recipes' "fill" steps replay.
 export const fillTool = defineBrowserTool({
   name: "browser_fill",
   label: "Browser Fill",
   description:
-    "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: [
-    "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.",
-    "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.",
-    "Confirm the field value browser_fill returns matches what you intended.",
-  ],
+    "Recipe replay only: set a form field's value through the native setter, or tick a checkbox/radio with 'true'/'false'.",
+  promptSnippet: "Set a form field's value (recipe replay)",
+  promptGuidelines: [],
   parameters: FillArgs,
   concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    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 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.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}`, details });
-    }
+    const filled = await nativeFill(client, args, args.value);
+    if (!filled.success) return filled;
+    const res = filled.data;
     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}`,
+      text: `Filled ${targetLabel(args)} = ${shown}${diff}`,
       details: { ...targetDetails(args), value: args.value, verified, tag: res.tag, kind: res.kind },
     });
   },
@@ -119,10 +128,10 @@ export const focusTool = defineBrowserTool({
   name: "browser_focus",
   label: "Browser Focus",
   description:
-    "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.",
+    "Focus an element via the DOM .focus() method — deterministic, no coordinate accuracy needed. PREFERRED: pass `ref` from browser_snapshot; fallback: a CSS `selector`.",
   promptSnippet: "Focus an element by ref (preferred) or selector",
   promptGuidelines: [
-    "For simply setting a value, prefer browser_fill (it doesn't need a separate focus step).",
+    "To enter text, pass the ref straight to browser_type — it focuses the field itself.",
   ],
   parameters: FocusArgs,
   concurrency: "serialized",

package/src/domains/js.ts

@@ -40,6 +40,13 @@ const prettyJson = (text: string): string => {
 const ExecuteJsArgs = Type.Object({
   expression: Type.String({ description: "A JavaScript expression, or a function body: a body with a top-level `return` (after any statements) runs inside an async function and returns that value." }),
   targetId: Type.Optional(Type.String({ description: "Optional iframe targetId; default = current page." })),
+  timeoutMs: Type.Optional(
+    Type.Integer({
+      minimum: 1_000,
+      maximum: 120_000,
+      description: "How long to wait for the result (an awaited promise included). Default 30000, max 120000. Raise it for scripts that loop with waits.",
+    }),
+  ),
 });
 
 const ExecuteJsDetailsSchema = Type.Object({
@@ -51,6 +58,8 @@ const ExecuteJsDetailsSchema = Type.Object({
 
 export type ExecuteJsDetails = DetailsOf<typeof ExecuteJsDetailsSchema>;
 
+const EXECUTE_JS_DEFAULT_TIMEOUT_MS = 30_000;
+
 export const executeJsTool = defineBrowserTool({
   name: "browser_execute_js",
   label: "Browser Execute JS",
@@ -63,13 +72,22 @@ export const executeJsTool = defineBrowserTool({
     "For 'is this element visible / enabled / checked / focused', a one-liner here beats a screenshot every time.",
     "For iframes, first run `Object.values(document.querySelectorAll('iframe'))` to find the iframe, then pass its targetId.",
     "Result must be JSON-serializable (Runtime.evaluate returnByValue=true).",
+    "A script that awaits (loops with setTimeout, waits for UI) gets 30s by default; pass timeoutMs (max 120000) for longer ones.",
   ],
   parameters: ExecuteJsArgs,
   details: ExecuteJsDetailsSchema,
   concurrency: "parallel",
   async handler(args, { client }): Promise<Result<ToolOk<ExecuteJsDetails>, ToolErr>> {
-    const r = await evalJs(client, args.expression, args.targetId);
-    if (!r.success) return r;
+    const timeoutMs = args.timeoutMs ?? EXECUTE_JS_DEFAULT_TIMEOUT_MS;
+    const r = await evalJs(client, args.expression, args.targetId, { timeoutMs });
+    if (!r.success) {
+      if (r.error.kind !== "timeout" && !/timeout/i.test(r.error.message)) return r;
+      return err({
+        kind: "timeout",
+        message: `${r.error.message}. The script may have partly run before the wait ran out — check the page's state before retrying. Pass a larger timeoutMs (max 120000) or split the work into several calls.`,
+        details: { ...(r.error.details ?? {}), timeoutMs },
+      });
+    }
     const valueStr = r.data === undefined ? "undefined" : JSON.stringify(r.data);
     // The full value lives in the text (and in fullOutputPath when truncated); details carry only what the
     // renderer needs so a large result is not persisted twice.