pi-browser-harness 0.10.2 → 0.11.0

package/src/domains/form.ts

@@ -1,9 +1,9 @@
 import { Type } from "typebox";
-import type { BrowserClient } from "../client";
-import { safeJs } from "../util/js-template";
 import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
-import { interactiveDiff, resolveRefToObjectId } from "./ref-resolve";
+import { detailsOf, isPageResult, type PageResult, resolveAndCall, runOnElement } from "./element-call";
+import { fillBody } from "./fill-engine";
+import { interactiveDiff } from "./ref-resolve";
 
 const FillArgs = Type.Object({
   ref: Type.Optional(
@@ -16,107 +16,21 @@ const FillArgs = Type.Object({
   value: Type.String({ description: "Value to set in the field" }),
 });
 
-/**
- * Run an element-scoped function either against a CSS selector (querySelector +
- * apply) or a ref (resolve to objectId, callFunctionOn with element as `this`).
- * The shared `fnBody` is a function body where `this` is the target element and
- * the single argument is the value — identical logic on both paths. Returns the
- * function's return value (parsed) or a ToolErr.
- *
- * On the ref path a detached node yields a stale-ref error; on the selector path
- * a missing element returns { status: "not_found" } from the function body.
- */
-const runOnElement = async (
-  client: BrowserClient,
-  opts: { ref?: string | undefined; selector?: string | undefined; fnBody: string; arg: unknown },
-): Promise<Result<unknown, ToolErr>> => {
-  if (opts.ref !== undefined) {
-    const objectId = await resolveRefToObjectId(client, opts.ref);
-    if (!objectId.success) return objectId;
-    const r = await client.session().call("Runtime.callFunctionOn", {
-      objectId: objectId.data,
-      functionDeclaration: `function (arg) { ${opts.fnBody} }`,
-      arguments: [{ value: opts.arg }],
-      returnByValue: true,
-    });
-    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
-    return ok((r.data as { result?: { value?: unknown } }).result?.value);
-  }
-  if (opts.selector === undefined) {
-    return err({ kind: "invalid_state", message: "Provide either `ref` or `selector`." });
-  }
-  // Selector path: bind the same trusted function body to the matched element
-  // via .call(). fnBody is harness-authored (not user input); only the selector
-  // and value are interpolated, and those go through safeJs.
-  const prelude = safeJs`
-    (() => {
-      const el = document.querySelector(${opts.selector});
-      if (!el) return { status: "not_found" };
-      const __arg = ${opts.arg};
-      return (function (arg) {`;
-  const expr = `${prelude} ${opts.fnBody} }).call(el, __arg); })()`;
-  const r = await client.evaluateJs(expr);
-  if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
-  return ok(r.data);
-};
+const FILL_BODY = `const value = arg;\n${fillBody({ rejectSelect: true, focusFirst: false })}`;
 
-/**
- * Result shape returned by the in-page fill script. Discriminated by `status`
- * so the handler can map page-level outcomes to typed ToolErr kinds.
- */
-type FillResult =
-  | { status: "ok"; tag: string; kind: string; value: string }
-  | { status: "not_found" }
-  | { status: "not_fillable"; tag: string };
-
-// Element-scoped fill logic. `this` is the target element, `arg` is the value.
-// Write via the native prototype value setter so React's _valueTracker
-// registers the change — assigning el.value directly does NOT, which is why
-// controlled inputs revert on re-render. Shared verbatim by the ref path
-// (callFunctionOn) and the selector path (querySelector + .call).
-const FILL_FN = `
-  const el = this;
-  const tag = el.tagName;
-  const proto =
-    el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype
-    : el instanceof HTMLInputElement ? HTMLInputElement.prototype
-    : null;
-  if (proto) {
-    const desc = Object.getOwnPropertyDescriptor(proto, "value");
-    const setter = desc && desc.set;
-    if (setter) setter.call(el, arg);
-    else el.value = arg;
-    el.dispatchEvent(new Event("input", { bubbles: true }));
-    el.dispatchEvent(new Event("change", { bubbles: true }));
-    return { status: "ok", tag, kind: el.type || tag.toLowerCase(), value: el.value };
-  }
-  if (el.isContentEditable) {
-    // Rich-text editors (Slack/Notion/ProseMirror) listen for beforeinput/input.
-    el.focus();
-    let done = false;
-    try {
-      const sel = window.getSelection();
-      if (sel) { sel.removeAllRanges(); const rng = document.createRange(); rng.selectNodeContents(el); sel.addRange(rng); }
-      done = document.execCommand("insertText", false, arg);
-    } catch (e) { done = false; }
-    if (!done) {
-      el.textContent = arg;
-      el.dispatchEvent(new InputEvent("input", { bubbles: true }));
-    }
-    return { status: "ok", tag, kind: "contenteditable", value: el.textContent || "" };
-  }
-  return { status: "not_fillable", tag };
-`;
+const NOT_FOUND: PageResult = { ok: false, reason: "not_found" };
 
 export const fillTool = defineBrowserTool({
   name: "browser_fill",
   label: "Browser Fill",
   description:
-    "Fill a form field (input/textarea/contenteditable). 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. Returns the field's value after writing, plus a compact diff of page changes.",
+    "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.",
@@ -124,29 +38,52 @@ export const fillTool = defineBrowserTool({
     "The result reports the field's value after writing and an appended page-changes diff — confirm both match what you intended before moving on.",
   ],
   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_FN, arg: args.value });
+    const r = await runOnElement(client, {
+      ref: args.ref,
+      selector: args.selector,
+      fnBody: FILL_BODY,
+      arg: args.value,
+      notFound: NOT_FOUND,
+    });
     if (!r.success) return r;
-    const res = r.data as FillResult | undefined;
+    const res = isPageResult(r.data) ? r.data : undefined;
     const target = args.ref ?? args.selector ?? "";
-    if (res === undefined || res.status === "not_found") {
+    if (res === undefined || res.reason === "not_found") {
       return err({
         kind: "invalid_state",
         message: `No element matched: ${target}`,
         details: { ref: args.ref, selector: args.selector },
       });
     }
-    if (res.status === "not_fillable") {
+    if (!res.ok) {
+      const details = { ref: args.ref, selector: args.selector, ...(res.tag !== undefined ? { tag: res.tag } : {}) };
+      if (res.kind === "select") {
+        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: `Element <${res.tag.toLowerCase()}> is not fillable (not an input, textarea, or contenteditable): ${target}. For <select> use browser_select_option.`,
-        details: { ref: args.ref, selector: args.selector, tag: res.tag },
+        message: `Could not fill ${target}: ${res.reason ?? "unknown reason"}`,
+        details,
       });
     }
+    const shown = res.value !== undefined ? JSON.stringify(res.value) : `checked=${res.checked === true}`;
     const diff = await interactiveDiff(client);
     return ok({
-      text: `Filled ${target} = ${JSON.stringify(res.value)}${diff}`,
-      details: { ref: args.ref, selector: args.selector, value: args.value, verified: res.value, tag: res.tag, kind: res.kind },
+      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 } : {}),
+      },
     });
   },
 });
@@ -160,6 +97,13 @@ const FocusArgs = Type.Object({
 
 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 };
@@ -179,10 +123,11 @@ export const focusTool = defineBrowserTool({
     "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: "" });
     if (!r.success) return r;
-    const res = r.data as FocusResult | undefined;
+    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 } });
@@ -210,7 +155,24 @@ type SelectResult =
   | { status: "not_select"; tag: string }
   | { status: "no_match"; options: ReadonlyArray<{ value: string; label: string }> };
 
-// `this` is the <select>; `arg` is { wv, wl, wi } (null = not provided).
+const isSelectOption = (v: unknown): v is { value: string; label: string } =>
+  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";
+  }
+  if (v.status === "no_match") {
+    return "options" in v && Array.isArray(v.options) && v.options.every(isSelectOption);
+  }
+  return false;
+};
+
 const SELECT_FN = `
   const el = this;
   if (el.tagName !== "SELECT") return { status: "not_select", tag: el.tagName };
@@ -240,6 +202,7 @@ export const selectOptionTool = defineBrowserTool({
     "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." });
@@ -248,7 +211,7 @@ export const selectOptionTool = defineBrowserTool({
     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 });
     if (!r.success) return r;
-    const res = r.data as SelectResult | undefined;
+    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 } });
@@ -270,3 +233,51 @@ export const selectOptionTool = defineBrowserTool({
     });
   },
 });
+
+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 SetCheckedArgs = Type.Object({
+  ref: Type.String({ description: "Stable element ref of a checkbox or radio from browser_snapshot (e.g. 'e7')." }),
+  checked: Type.Boolean({ description: "Desired checked state." }),
+});
+
+export const setCheckedTool = defineBrowserTool({
+  name: "browser_set_checked",
+  label: "Browser Set Checked",
+  description:
+    "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,
+  concurrency: "serialized",
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const r = await resolveAndCall(client, args.ref, CHECK_FN, [args.checked]);
+    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 ok({
+      text: `Set ref ${args.ref} checked=${res.checked}` + (res.changed === false ? " (already)" : ""),
+      details: detailsOf(args.ref, res),
+    });
+  },
+});

package/src/domains/history.ts

@@ -2,14 +2,15 @@ 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";
 
 type HistoryEntry = { readonly id: number; readonly url: string; readonly title: string };
 type History = { readonly entries: ReadonlyArray<HistoryEntry>; readonly currentIndex: number };
 
 const fetchHistory = async (client: BrowserClient): Promise<Result<History, ToolErr>> => {
-  const r = await client.session().call("Page.getNavigationHistory");
-  if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
-  return ok(r.data as History);
+  const r = await cdpCall(client, "Page.getNavigationHistory", {});
+  if (!r.success) return r;
+  return ok(r.data);
 };
 
 export const goBackTool = defineBrowserTool({
@@ -19,14 +20,15 @@ export const goBackTool = defineBrowserTool({
   promptSnippet: "Go back one page",
   promptGuidelines: ["Use to return to the previous page after navigating."],
   parameters: Type.Object({}),
+  concurrency: "serialized",
   async handler(_a, { client }): Promise<Result<ToolOk, ToolErr>> {
     const h = await fetchHistory(client);
     if (!h.success) return h;
     if (h.data.currentIndex <= 0) return ok({ text: "Already at the beginning of history." });
     const target = h.data.entries[h.data.currentIndex - 1];
     if (!target) return err({ kind: "internal", message: "history entry missing at index" });
-    const nav = await client.session().call("Page.navigateToHistoryEntry", { entryId: target.id });
-    if (!nav.success) return err({ kind: "cdp_error", message: nav.error.message });
+    const nav = await cdpCall(client, "Page.navigateToHistoryEntry", { entryId: target.id });
+    if (!nav.success) return nav;
     return ok({ text: `Navigated back to: ${target.url}`, details: { url: target.url } });
   },
 });
@@ -38,14 +40,15 @@ export const goForwardTool = defineBrowserTool({
   promptSnippet: "Go forward one page",
   promptGuidelines: ["Use to undo a browser_go_back."],
   parameters: Type.Object({}),
+  concurrency: "serialized",
   async handler(_a, { client }): Promise<Result<ToolOk, ToolErr>> {
     const h = await fetchHistory(client);
     if (!h.success) return h;
     if (h.data.currentIndex >= h.data.entries.length - 1) return ok({ text: "Already at the end of history." });
     const target = h.data.entries[h.data.currentIndex + 1];
     if (!target) return err({ kind: "internal", message: "history entry missing at index" });
-    const nav = await client.session().call("Page.navigateToHistoryEntry", { entryId: target.id });
-    if (!nav.success) return err({ kind: "cdp_error", message: nav.error.message });
+    const nav = await cdpCall(client, "Page.navigateToHistoryEntry", { entryId: target.id });
+    if (!nav.success) return nav;
     return ok({ text: `Navigated forward to: ${target.url}`, details: { url: target.url } });
   },
 });
@@ -57,9 +60,10 @@ export const reloadTool = defineBrowserTool({
   promptSnippet: "Reload the page",
   promptGuidelines: ["Use to refresh the page, e.g. after server-side changes."],
   parameters: Type.Object({}),
+  concurrency: "serialized",
   async handler(_a, { client }): Promise<Result<ToolOk, ToolErr>> {
-    const r = await client.session().call("Page.reload");
-    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
+    const r = await cdpCall(client, "Page.reload", {});
+    if (!r.success) return r;
     const info = await client.pageInfo();
     if (!info.success) return err({ kind: "cdp_error", message: info.error.message });
     if ("dialog" in info.data) {

package/src/domains/isolated-tab.ts

@@ -1,22 +1,11 @@
-/**
- * Isolated-attach tab lifecycle (ADR-0002 v1). Opens a harness-owned tab,
- * attaches to it by its own CDP sessionId, and drives it via callOnTarget /
- * evaluateJs(expr, sid) WITHOUT ever touching the global "current" tab — so a
- * search or page-read never disturbs the tab the user is looking at, even when
- * several subagents run concurrently.
- *
- * Mirrors the create/attach sequence in browser_open_urls
- * (src/domains/navigate.ts:84-139). Every page evaluation is bounded by a
- * timeout, so a JS dialog on the (uninstrumented) isolated tab surfaces as a
- * typed timeout rather than hanging — see the dialog-hang caveat in plan.md.
- */
 import type { BrowserClient } from "../client";
 import { type Result, err, ok } from "../util/result";
 import { safeJs } from "../util/js-template";
 import { ensureHarnessWindow, openHarnessTab } from "../cdp/target-factory";
+import { evaluateJson } from "../cdp/session";
 import type { ToolErr } from "../util/tool";
+import { cdpCallBrowser, cdpCallOnTarget, cdpErrToToolErr, evalJs } from "./cdp-call";
 
-/** A tab attached by its own sessionId, ready to drive via callOnTarget. */
 export type IsolatedTab = {
   readonly targetId: string;
   readonly sessionId: string;
@@ -25,56 +14,46 @@ export type IsolatedTab = {
 const EVAL_TIMEOUT_MS = 15_000;
 const READY_POLL_INTERVAL_MS = 50;
 
-const toToolErr = (message: string, kind: ToolErr["kind"] = "cdp_error"): ToolErr => ({ kind, message });
-
-/**
- * Open a harness-owned tab and attach to it, returning its targetId + private
- * sessionId. Does not navigate. The caller MUST `closeIsolatedTab` when done.
- */
 export const openIsolatedTab = async (client: BrowserClient): Promise<Result<IsolatedTab, ToolErr>> => {
-  // Routed through the target factory so an isolated tab lands in the pinned
-  // profile like every other harness tab — otherwise a search or page read
-  // would run with a different profile's cookies than the visible tabs.
+  // Routed through the target factory so an isolated tab lands in the pinned profile, not another profile's cookies.
   const window = await ensureHarnessWindow(client);
-  if (!window.success) return err(toToolErr(window.error.message));
+  if (!window.success) return err(cdpErrToToolErr(window.error, "Target.createTarget"));
   let targetId: string;
   if (window.data.freshlyCreated) {
     targetId = window.data.targetId;
   } else {
     const opened = await openHarnessTab(client, window.data.targetId);
-    if (!opened.success) return err(toToolErr(opened.error.message));
+    if (!opened.success) return err(cdpErrToToolErr(opened.error, "Target.createTarget"));
     targetId = opened.data;
   }
 
-  const attached = await client.session().callBrowser("Target.attachToTarget", { targetId, flatten: true });
+  const attached = await cdpCallBrowser(client, "Target.attachToTarget", { targetId, flatten: true });
   if (!attached.success) {
     await client.closeTab(targetId);
-    return err(toToolErr(attached.error.message));
+    return attached;
   }
-  const { sessionId } = attached.data as { sessionId: string };
+  const { sessionId } = attached.data;
 
-  const enabled = await client.session().callOnTarget("Page.enable", {}, sessionId);
+  const enabled = await cdpCallOnTarget(client, "Page.enable", {}, sessionId);
   if (!enabled.success) {
     await client.closeTab(targetId);
-    return err(toToolErr(enabled.error.message));
+    return enabled;
   }
   return ok({ targetId, sessionId });
 };
 
-/** Navigate an isolated tab to a URL (does not wait for load). */
 export const navigateIsolatedTab = async (
   client: BrowserClient,
   tab: IsolatedTab,
   url: string,
 ): Promise<Result<void, ToolErr>> => {
-  const nav = await client.session().callOnTarget("Page.navigate", { url }, tab.sessionId, {
+  const nav = await cdpCallOnTarget(client, "Page.navigate", { url }, tab.sessionId, {
     timeoutMs: EVAL_TIMEOUT_MS,
   });
-  if (!nav.success) return err(toToolErr(nav.error.message));
+  if (!nav.success) return nav;
   return ok(undefined);
 };
 
-/** Poll the isolated tab until document.readyState === 'complete' or timeout. */
 export const waitForIsolatedLoad = async (
   client: BrowserClient,
   tab: IsolatedTab,
@@ -83,38 +62,30 @@ export const waitForIsolatedLoad = async (
 ): Promise<Result<void, ToolErr>> => {
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
-    if (signal?.aborted) return err(toToolErr("aborted", "internal"));
-    const r = await client.evaluateJs(safeJs`document.readyState`, tab.sessionId);
+    if (signal?.aborted) return err({ kind: "internal", message: "aborted" });
+    const r = await evalJs(client, safeJs`document.readyState`, tab.sessionId);
     if (r.success && r.data === "complete") return ok(undefined);
     await new Promise((res) => setTimeout(res, READY_POLL_INTERVAL_MS));
   }
-  return err(toToolErr(`page did not finish loading in ${Math.round(timeoutMs / 1000)}s`, "timeout"));
+  return err({ kind: "timeout", message: `page did not finish loading in ${Math.round(timeoutMs / 1000)}s` });
 };
 
-/**
- * Evaluate an expression in the isolated tab and return the raw value. Bounds
- * the eval with a timeout so a blocking dialog cannot hang the tool.
- */
-export const evalInIsolatedTab = async (
+export const isJsonText = (v: unknown): v is string => typeof v === "string";
+
+export const evalInIsolatedTab = async <T>(
   client: BrowserClient,
   tab: IsolatedTab,
   expression: string,
-): Promise<Result<unknown, ToolErr>> => {
-  const r = await client.session().callOnTarget(
-    "Runtime.evaluate",
-    { expression, returnByValue: true, awaitPromise: true },
-    tab.sessionId,
-    { timeoutMs: EVAL_TIMEOUT_MS },
-  );
-  if (!r.success) return err(toToolErr(r.error.message, r.error.kind === "timeout" ? "timeout" : "cdp_error"));
-  const data = r.data as { result?: { value?: unknown }; exceptionDetails?: unknown };
-  if (data.exceptionDetails) {
-    return err(toToolErr(`page evaluation failed: ${JSON.stringify(data.exceptionDetails)}`));
-  }
-  return ok(data.result?.value);
+  check: (v: unknown) => v is T,
+): Promise<Result<T, ToolErr>> => {
+  const r = await evaluateJson(client.session(), expression, check, {
+    sessionId: tab.sessionId,
+    timeoutMs: EVAL_TIMEOUT_MS,
+  });
+  if (!r.success) return err(cdpErrToToolErr(r.error, "Runtime.evaluate"));
+  return ok(r.data);
 };
 
-/** Close an isolated tab and drop its ownership. Best-effort; never throws. */
 export const closeIsolatedTab = async (client: BrowserClient, tab: IsolatedTab): Promise<void> => {
   await client.closeTab(tab.targetId).catch(() => {});
 };