pi-feats 0.1.2 → 0.1.4

package/extensions/browser-harness/domains/form.ts

@@ -0,0 +1,283 @@
+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 { interactiveDiff } from "./ref-resolve";
+
+const FillArgs = Type.Object({
+  ref: Type.Optional(
+    Type.String({
+      description:
+        "Stable element ref from browser_snapshot (e.g. 'e7'). PREFERRED over selector — survives re-renders. When set, selector is ignored.",
+    }),
+  ),
+  selector: Type.Optional(Type.String({ description: "CSS selector of the form field to fill (fallback when no ref)" })),
+  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" };
+
+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: [
+    "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.",
+  ],
+  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,
+    });
+    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 },
+      });
+    }
+    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: `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} = ${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 } : {}),
+      },
+    });
+  },
+});
+
+const FocusArgs = Type.Object({
+  ref: Type.Optional(
+    Type.String({ description: "Stable element ref from browser_snapshot (e.g. 'e7'). PREFERRED over selector." }),
+  ),
+  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 };
+`;
+
+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.",
+  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: "" });
+    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 } });
+    }
+    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 ok({ text: `Focused ${target}`, details: { ref: args.ref, selector: args.selector, tag: res.tag } });
+  },
+});
+
+const SelectOptionArgs = Type.Object({
+  ref: Type.Optional(
+    Type.String({ description: "Stable element ref of the <select> from browser_snapshot. PREFERRED over selector." }),
+  ),
+  selector: Type.Optional(Type.String({ description: "CSS selector of the <select> element (fallback when no ref)" })),
+  value: Type.Optional(Type.String({ description: "Option value attribute to select" })),
+  label: Type.Optional(Type.String({ description: "Visible option text to select (exact match)" })),
+  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 } =>
+  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 };
+  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 };
+`;
+
+export const selectOptionTool = defineBrowserTool({
+  name: "browser_select_option",
+  label: "Browser Select Option",
+  description:
+    "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." });
+    }
+    // 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 });
+    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 } });
+    }
+    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 } });
+    }
+    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 },
+      });
+    }
+    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 },
+    });
+  },
+});
+
+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/extensions/browser-harness/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 === undefined || 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_state", 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 },
+    });
+  },
+});

package/extensions/browser-harness/domains/history.ts

@@ -0,0 +1,80 @@
+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 cdpCall(client, "Page.getNavigationHistory", {});
+  if (!r.success) return r;
+  return ok(r.data);
+};
+
+export const goBackTool = defineBrowserTool({
+  name: "browser_go_back",
+  label: "Browser Go Back",
+  description: "Navigate back one page in history.",
+  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 cdpCall(client, "Page.navigateToHistoryEntry", { entryId: target.id });
+    if (!nav.success) return nav;
+    return ok({ text: `Navigated back to: ${target.url}`, details: { url: target.url } });
+  },
+});
+
+export const goForwardTool = defineBrowserTool({
+  name: "browser_go_forward",
+  label: "Browser Go Forward",
+  description: "Navigate forward one page in history.",
+  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 cdpCall(client, "Page.navigateToHistoryEntry", { entryId: target.id });
+    if (!nav.success) return nav;
+    return ok({ text: `Navigated forward to: ${target.url}`, details: { url: target.url } });
+  },
+});
+
+export const reloadTool = defineBrowserTool({
+  name: "browser_reload",
+  label: "Browser Reload",
+  description: "Reload the current page.",
+  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 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) {
+      return ok({
+        text: `Reloaded. ⚠️ Dialog open: ${info.data.dialog.type}`,
+        details: { dialog: info.data.dialog },
+      });
+    }
+    return ok({
+      text: `Reloaded: ${info.data.title} (${info.data.url})`,
+      details: { page: info.data },
+    });
+  },
+});

package/extensions/browser-harness/domains/isolated-tab.ts

@@ -0,0 +1,91 @@
+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";
+
+export type IsolatedTab = {
+  readonly targetId: string;
+  readonly sessionId: string;
+};
+
+const EVAL_TIMEOUT_MS = 15_000;
+const READY_POLL_INTERVAL_MS = 50;
+
+export const openIsolatedTab = async (client: BrowserClient): Promise<Result<IsolatedTab, ToolErr>> => {
+  // 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(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(cdpErrToToolErr(opened.error, "Target.createTarget"));
+    targetId = opened.data;
+  }
+
+  const attached = await cdpCallBrowser(client, "Target.attachToTarget", { targetId, flatten: true });
+  if (!attached.success) {
+    await client.closeTab(targetId);
+    return attached;
+  }
+  const { sessionId } = attached.data;
+
+  const enabled = await cdpCallOnTarget(client, "Page.enable", {}, sessionId);
+  if (!enabled.success) {
+    await client.closeTab(targetId);
+    return enabled;
+  }
+  return ok({ targetId, sessionId });
+};
+
+export const navigateIsolatedTab = async (
+  client: BrowserClient,
+  tab: IsolatedTab,
+  url: string,
+): Promise<Result<void, ToolErr>> => {
+  const nav = await cdpCallOnTarget(client, "Page.navigate", { url }, tab.sessionId, {
+    timeoutMs: EVAL_TIMEOUT_MS,
+  });
+  if (!nav.success) return nav;
+  return ok(undefined);
+};
+
+export const waitForIsolatedLoad = async (
+  client: BrowserClient,
+  tab: IsolatedTab,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<Result<void, ToolErr>> => {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    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({ kind: "timeout", message: `page did not finish loading in ${Math.round(timeoutMs / 1000)}s` });
+};
+
+export const isJsonText = (v: unknown): v is string => typeof v === "string";
+
+export const evalInIsolatedTab = async <T>(
+  client: BrowserClient,
+  tab: IsolatedTab,
+  expression: string,
+  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);
+};
+
+export const closeIsolatedTab = async (client: BrowserClient, tab: IsolatedTab): Promise<void> => {
+  await client.closeTab(tab.targetId).catch(() => {});
+};