pi-browser-harness 0.12.0 → 0.13.0

package/src/domains/page.ts

@@ -1,25 +1,9 @@
 import { Type } from "typebox";
 import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
-import { evalJs } from "./cdp-call";
+import { fromClient } from "./cdp-call";
 import { safeJs } from "../util/js-template";
-
-const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
-  new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(signal.reason ?? new Error("aborted"));
-      return;
-    }
-    const onAbort = (): void => {
-      clearTimeout(timer);
-      reject(signal?.reason ?? new Error("aborted"));
-    };
-    const timer = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
+import { pollUntil, READY_STATE_COMPLETE, sleep } from "./poll";
 
 export const pageInfoTool = defineBrowserTool({
   name: "browser_page_info",
@@ -33,9 +17,9 @@ export const pageInfoTool = defineBrowserTool({
   parameters: Type.Object({}),
   concurrency: "parallel",
   async handler(_args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    const r = await client.pageInfo();
-    if (!r.success) return err({ kind: "cdp_error", message: r.error.message });
-    if ("dialog" in r.data) {
+    const r = fromClient(await client.pageInfo(), "pageInfo");
+    if (!r.success) return r;
+    if (r.data.kind === "dialog") {
       const d = r.data.dialog;
       return ok({
         text: `⚠️  DIALOG OPEN: ${d.type}\nMessage: ${d.message}${d.defaultPrompt ? `\nDefault: ${d.defaultPrompt}` : ""}\n\nUse browser_handle_dialog to accept or dismiss.`,
@@ -63,12 +47,9 @@ export const waitTool = defineBrowserTool({
   parameters: WaitArgs,
   concurrency: "parallel",
   async handler(args, { signal }): Promise<Result<ToolOk, ToolErr>> {
-    try {
-      await sleep(Math.round(args.seconds * 1000), signal);
-      return ok({ text: `Waited ${args.seconds}s` });
-    } catch (e) {
-      return err({ kind: "internal", message: e instanceof Error ? e.message : String(e) });
-    }
+    await sleep(Math.round(args.seconds * 1000), signal);
+    if (signal?.aborted) return err({ kind: "timeout", message: `Aborted before ${args.seconds}s elapsed` });
+    return ok({ text: `Waited ${args.seconds}s` });
   },
 });
 
@@ -89,17 +70,10 @@ export const waitForLoadTool = defineBrowserTool({
   concurrency: "serialized",
   async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
     const timeoutMs = (args.timeout ?? 15) * 1000;
-    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`);
-      if (r.success && r.data === "complete") {
-        const ms = Date.now() - start;
-        return ok({ text: `Page loaded in ${Math.round(ms / 100) / 10}s`, details: { ms } });
-      }
-      await new Promise((res) => setTimeout(res, 50));
-    }
-    return err({ kind: "timeout", message: `Page did not finish loading in ${args.timeout ?? 15}s` });
+    const r = await pollUntil(client, READY_STATE_COMPLETE, { timeoutMs, signal, what: "page load" });
+    if (!r.success) return r;
+    const ms = r.data.elapsedMs;
+    return ok({ text: `Page loaded in ${Math.round(ms / 100) / 10}s`, details: { ms } });
   },
 });
 
@@ -123,7 +97,7 @@ export const waitForTool = defineBrowserTool({
   concurrency: "parallel",
   async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
     if (args.selector === undefined && args.text === undefined) {
-      return err({ kind: "invalid_state", message: "Provide a selector or text to wait for." });
+      return err({ kind: "invalid_args", message: "Provide a selector or text to wait for." });
     }
     const gone = args.gone ?? false;
     const timeoutMs = (args.timeout ?? 5) * 1000;
@@ -131,18 +105,11 @@ export const waitForTool = defineBrowserTool({
       args.selector !== undefined
         ? safeJs`(() => { const found = !!document.querySelector(${args.selector}); return ${gone} ? !found : found; })()`
         : safeJs`(() => { const t = document.body ? document.body.innerText : ""; return t.includes(${args.text}); })()`;
-    const start = Date.now();
-    while (Date.now() - start < timeoutMs) {
-      if (signal?.aborted) return err({ kind: "internal", message: "aborted" });
-      const r = await evalJs(client, expr);
-      if (r.success && r.data === true) {
-        const ms = Date.now() - start;
-        const what = args.selector !== undefined ? `${args.selector}${gone ? " gone" : ""}` : `text "${args.text}"`;
-        return ok({ text: `Condition met (${what}) in ${Math.round(ms / 100) / 10}s`, details: { ms } });
-      }
-      await sleep(50, signal);
-    }
     const what = args.selector !== undefined ? `${args.selector}${gone ? " to disappear" : ""}` : `text "${args.text}"`;
-    return err({ kind: "timeout", message: `Timed out after ${args.timeout ?? 5}s waiting for ${what}` });
+    const r = await pollUntil(client, expr, { timeoutMs, signal, what });
+    if (!r.success) return r;
+    const ms = r.data.elapsedMs;
+    const met = args.selector !== undefined ? `${args.selector}${gone ? " gone" : ""}` : `text "${args.text}"`;
+    return ok({ text: `Condition met (${met}) in ${Math.round(ms / 100) / 10}s`, details: { ms } });
   },
 });

package/src/domains/poll.ts

@@ -0,0 +1,42 @@
+import { sleep } from "../util/sleep";
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import type { ToolErr } from "../util/tool";
+import { evalJs } from "./cdp-call";
+
+export type PollOptions = {
+  readonly timeoutMs: number;
+  readonly signal?: AbortSignal | undefined;
+  readonly sessionId?: string | undefined;
+  readonly intervalMs?: number | undefined;
+  // Names the condition in the timeout message, e.g. "page load".
+  readonly what?: string | undefined;
+};
+
+const DEFAULT_INTERVAL_MS = 50;
+
+export { sleep } from "../util/sleep";
+
+// Evaluates `expression` in the page until it yields `true`. A deadline or an abort both surface as kind "timeout";
+// evaluation errors (e.g. mid-navigation) are retried until the deadline.
+export const pollUntil = async (
+  client: BrowserClient,
+  expression: string,
+  opts: PollOptions,
+): Promise<Result<{ readonly elapsedMs: number }, ToolErr>> => {
+  const start = Date.now();
+  const interval = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const what = opts.what ?? "condition";
+  const seconds = Math.round(opts.timeoutMs / 100) / 10;
+  while (Date.now() - start < opts.timeoutMs) {
+    if (opts.signal?.aborted) {
+      return err({ kind: "timeout", message: `Aborted while waiting for ${what}` });
+    }
+    const r = await evalJs(client, expression, opts.sessionId);
+    if (r.success && r.data === true) return ok({ elapsedMs: Date.now() - start });
+    await sleep(interval, opts.signal);
+  }
+  return err({ kind: "timeout", message: `Timed out after ${seconds}s waiting for ${what}` });
+};
+
+export const READY_STATE_COMPLETE = `document.readyState === "complete"`;

package/src/domains/readpage/read-page.ts

@@ -1,10 +1,15 @@
+import { borrowSession } from "../../cdp/target-factory";
 import { Type } from "typebox";
 import { Compile } from "typebox/compile";
 import { parseJson } from "../../schemas/parse";
 import { type Result, err, ok } from "../../util/result";
 import { applyTruncation } from "../../util/truncate";
-import { defineBrowserTool, type ToolErr, type ToolOk } from "../../util/tool";
-import { cdpCallBrowser, evalJs } from "../cdp-call";
+import { type DetailsOf, defineBrowserTool, type ToolErr, type ToolOk } from "../../util/tool";
+import type { BrowserClient } from "../../client";
+import { evalJs, fromClient } from "../cdp-call";
+import { pageCallExpression } from "../page/inject";
+import { capturePage } from "../page/read-page.page";
+import type * as captured from "../page/read-page.page";
 import {
   closeIsolatedTab,
   evalInIsolatedTab,
@@ -14,7 +19,7 @@ import {
   openIsolatedTab,
   waitForIsolatedLoad,
 } from "../isolated-tab";
-import { renderExpandableText } from "../render";
+import { ExpandableTextSchema, renderExpandableText } from "../render";
 import { extractReadable, type PageCapture, type ReadablePage } from "./readability";
 
 const LOAD_TIMEOUT_MS = 15_000;
@@ -48,42 +53,28 @@ const PageCaptureSchema = Type.Object({
 
 const pageCaptureValidator = Compile(PageCaptureSchema);
 
+const ReadPageDetailsSchema = Type.Object({
+  title: Type.String(),
+  url: Type.String(),
+  wordCount: Type.Number(),
+  render: ExpandableTextSchema,
+  fullOutputPath: Type.Optional(Type.String()),
+});
+
+export type ReadPageDetails = DetailsOf<typeof ReadPageDetailsSchema>;
+
 const BODY_TEXT_LIMIT = 20_000;
 
-const buildPageCaptureExpr = (): string => `
-  (() => {
-    const BOILERPLATE = new Set(['NAV', 'HEADER', 'FOOTER', 'ASIDE']);
-    const inBoilerplate = (el) => {
-      for (let n = el; n; n = n.parentElement) {
-        if (BOILERPLATE.has(n.tagName)) return true;
-        const role = n.getAttribute && n.getAttribute('role');
-        if (role === 'navigation' || role === 'banner' || role === 'contentinfo') return true;
-      }
-      return false;
-    };
-    const kindOf = (tag) => {
-      if (/^H[1-6]$/.test(tag)) return 'heading';
-      if (tag === 'LI') return 'listitem';
-      if (tag === 'BLOCKQUOTE') return 'blockquote';
-      if (tag === 'P') return 'paragraph';
-      return 'other';
-    };
-    const selector = 'p, h1, h2, h3, h4, h5, h6, li, blockquote';
-    const root = document.querySelector('article, main, [role=main]') || document.body;
-    const blocks = [];
-    for (const el of root.querySelectorAll(selector)) {
-      const text = (el.innerText || '').replace(/\\s+/g, ' ').trim();
-      if (!text) continue;
-      let linkTextLength = 0;
-      for (const a of el.querySelectorAll('a')) linkTextLength += (a.innerText || '').length;
-      blocks.push({ kind: kindOf(el.tagName), text, linkTextLength, inBoilerplate: inBoilerplate(el) });
-    }
-    const bodyText = (document.body.innerText || '').replace(/\\n{3,}/g, '\\n\\n').slice(0, ${BODY_TEXT_LIMIT});
-    return JSON.stringify({ url: location.href, title: document.title, blocks, bodyText });
-  })()
-`;
+// The page function declares the capture shape it produces; this pins it to the shape the readability pass consumes,
+// so the two cannot drift apart silently (the runtime validator above still guards the actual wire value).
+type Pinned<T extends PageCapture> = T;
+export type CaptureFromPage = Pinned<captured.PageCapture>;
 
-const toPageCapture = (raw: unknown): PageCapture | undefined => {
+// Built once: stringifying the page function per call was the only cost of the thunk.
+const PAGE_CAPTURE_EXPR = pageCallExpression(capturePage, BODY_TEXT_LIMIT);
+
+// Accepts the capture either as JSON text (isolated tab) or as the already-decoded value (owned tab).
+export const toPageCapture = (raw: unknown): PageCapture | undefined => {
   if (typeof raw === "string") {
     const parsed = parseJson(raw, pageCaptureValidator);
     return parsed.success ? parsed.data : undefined;
@@ -91,7 +82,7 @@ const toPageCapture = (raw: unknown): PageCapture | undefined => {
   return pageCaptureValidator.Check(raw) ? raw : undefined;
 };
 
-const captureToResult = async (raw: unknown): Promise<Result<ToolOk, ToolErr>> => {
+const captureToResult = async (raw: unknown): Promise<Result<ToolOk<ReadPageDetails>, ToolErr>> => {
   const parsed = toPageCapture(raw);
   if (parsed === undefined) return err({ kind: "internal", message: "page capture returned an unexpected shape" });
   const page: ReadablePage = extractReadable(parsed);
@@ -115,10 +106,10 @@ const captureToResult = async (raw: unknown): Promise<Result<ToolOk, ToolErr>> =
 };
 
 const readOpenedUrl = async (
-  client: Parameters<typeof openIsolatedTab>[0],
+  client: BrowserClient,
   url: string,
   signal: AbortSignal | undefined,
-): Promise<Result<ToolOk, ToolErr>> => {
+): Promise<Result<ToolOk<ReadPageDetails>, ToolErr>> => {
   const opened = await openIsolatedTab(client);
   if (!opened.success) return err(opened.error);
   const tab: IsolatedTab = opened.data;
@@ -127,27 +118,30 @@ const readOpenedUrl = async (
     if (!navigated.success) return err(navigated.error);
     const loaded = await waitForIsolatedLoad(client, tab, LOAD_TIMEOUT_MS, signal);
     if (!loaded.success) return err(loaded.error);
-    const captured = await evalInIsolatedTab(client, tab, buildPageCaptureExpr(), isJsonText);
+    const captured = await evalInIsolatedTab(client, tab, PAGE_CAPTURE_EXPR, isJsonText);
     if (!captured.success) return err(captured.error);
-    return captureToResult(captured.data);
+    return await captureToResult(captured.data);
   } finally {
     await closeIsolatedTab(client, tab);
   }
 };
 
 const readOwnedTab = async (
-  client: Parameters<typeof openIsolatedTab>[0],
+  client: BrowserClient,
   targetId: string,
-): Promise<Result<ToolOk, ToolErr>> => {
+): Promise<Result<ToolOk<ReadPageDetails>, ToolErr>> => {
   if (!client.owns(targetId)) {
     return err({ kind: "invalid_state", message: `Tab ${targetId} is not owned by this session.` });
   }
-  const attached = await cdpCallBrowser(client, "Target.attachToTarget", { targetId, flatten: true });
-  if (!attached.success) return attached;
-  const sessionId = attached.data.sessionId;
-  const captured = await evalJs(client, buildPageCaptureExpr(), sessionId);
-  if (!captured.success) return captured;
-  return captureToResult(captured.data);
+  const borrowed = await borrowSession(client, targetId);
+  if (!borrowed.success) return fromClient(borrowed, "Target.attachToTarget");
+  try {
+    const captured = await evalJs(client, PAGE_CAPTURE_EXPR, borrowed.data.sessionId);
+    if (!captured.success) return captured;
+    return await captureToResult(captured.data);
+  } finally {
+    await borrowed.data.release();
+  }
 };
 
 export const readPageTool = defineBrowserTool({
@@ -161,13 +155,14 @@ export const readPageTool = defineBrowserTool({
     "Boilerplate-heavy or structure-less pages fall back to bounded body text rather than erroring.",
   ],
   parameters: ReadPageArgs,
+  details: ReadPageDetailsSchema,
   concurrency: "parallel",
-  async handler(args, { client, signal }): Promise<Result<ToolOk, ToolErr>> {
+  async handler(args, { client, signal }): Promise<Result<ToolOk<ReadPageDetails>, ToolErr>> {
     if (args.url !== undefined && args.url.length > 0) return readOpenedUrl(client, args.url, signal);
     if (args.targetId !== undefined && args.targetId.length > 0) return readOwnedTab(client, args.targetId);
-    return err({ kind: "invalid_state", message: "provide either url or targetId" });
+    return err({ kind: "invalid_args", message: "provide either url or targetId" });
   },
-  renderResult(result, expanded, theme) {
-    return renderExpandableText("read_page", result, expanded, theme);
+  renderResult(result, expanded) {
+    return renderExpandableText(result.details.render, expanded);
   },
 });

package/src/domains/ref-resolve.ts

@@ -3,7 +3,8 @@ import { type Result, err, ok } from "../util/result";
 import type { ToolErr } from "../util/tool";
 import { type Box, boxOf } from "./box";
 import { cdpCall } from "./cdp-call";
-import { buildTree, collectInteractiveTargets, type SlimNode } from "./ax-tree";
+import { buildTree, collectInteractiveTargets } from "./ax-tree";
+import { type RefSignature, signatureOf } from "./ref-signature";
 
 const staleErr = (ref: string): ToolErr => ({
   kind: "invalid_state",
@@ -43,17 +44,20 @@ export const resolveRefToBox = async (
   return ok(box.data);
 };
 
-const sigOf = (n: SlimNode): string => `${n.role}|${n.name ?? ""}|${n.value ?? ""}|${n.state ?? ""}`;
-const keyOf = (n: SlimNode): string => `${n.role}|${n.name ?? ""}`;
+export type RefRefresh = {
+  readonly prev: ReadonlyMap<string, RefSignature>;
+  readonly cur: ReadonlyMap<string, RefSignature>;
+};
 
-export const interactiveDiff = async (client: BrowserClient): Promise<string> => {
+// Re-reads the AX tree and republishes the session's ref map: an element seen before keeps its ref, a new one gets
+// the next unused index. Returns the signatures before and after so the caller can diff them.
+export const refreshRefs = async (client: BrowserClient): Promise<Result<RefRefresh, ToolErr>> => {
   const session = client.session();
   const prev = session.refSignatures();
 
   const axRes = await cdpCall(client, "Accessibility.getFullAXTree", {});
-  if (!axRes.success) return "";
-  const rawNodes = axRes.data.nodes;
-  const slim = buildTree(rawNodes, { interestingOnly: true, maxNodes: 1000 });
+  if (!axRes.success) return axRes;
+  const slim = buildTree(axRes.data.nodes, { interestingOnly: true, maxNodes: 1000 });
   const targets = collectInteractiveTargets(slim);
 
   const priorRefs = session.refMappings();
@@ -65,7 +69,7 @@ export const interactiveDiff = async (client: BrowserClient): Promise<string> =>
     if (digits !== undefined) nextIndex = Math.max(nextIndex, Number(digits) + 1);
   }
   const refMap = new Map<string, number>();
-  const refSig = new Map<string, string>();
+  const cur = new Map<string, RefSignature>();
   const taken = new Set<string>();
   for (const { node, backendId } of targets) {
     const prior = refByBackendId.get(backendId);
@@ -73,38 +77,40 @@ export const interactiveDiff = async (client: BrowserClient): Promise<string> =>
     taken.add(ref);
     node.ref = ref;
     refMap.set(ref, backendId);
-    refSig.set(ref, sigOf(node));
+    cur.set(ref, signatureOf(node));
   }
-  session.setRefMap(refMap, refSig);
+  session.setRefMap(refMap, cur);
+  return ok({ prev, cur });
+};
 
-  const prevByKey = new Map<string, string>();
-  for (const sig of prev.values()) {
-    const parts = sig.split("|");
-    prevByKey.set(`${parts[0]}|${parts[1]}`, sig);
-  }
-  const curByKey = new Map<string, { ref: string; sig: string }>();
-  for (const { node } of targets) {
-    if (node.ref) curByKey.set(keyOf(node), { ref: node.ref, sig: sigOf(node) });
-  }
+const identityKey = (s: RefSignature): string => JSON.stringify([s.role, s.name]);
+const describe = (s: RefSignature): string => `${s.role} "${s.name}"`;
+
+// Pure: renders what changed between two signature sets, keyed by role+name. Empty string when nothing changed.
+export const diffSignatures = (
+  prev: ReadonlyMap<string, RefSignature>,
+  cur: ReadonlyMap<string, RefSignature>,
+): string => {
+  const prevByKey = new Map<string, RefSignature>();
+  for (const sig of prev.values()) prevByKey.set(identityKey(sig), sig);
+  const curByKey = new Map<string, { readonly ref: string; readonly sig: RefSignature }>();
+  for (const [ref, sig] of cur) curByKey.set(identityKey(sig), { ref, sig });
 
   const appeared: string[] = [];
   const changed: string[] = [];
   for (const [key, { ref, sig }] of curByKey) {
     const before = prevByKey.get(key);
     if (before === undefined) {
-      appeared.push(`  *[${ref}] ${key.replace("|", ' "')}"`);
-    } else if (before !== sig) {
-      const va = before.split("|")[2] ?? "";
-      const vb = sig.split("|")[2] ?? "";
-      const sa = before.split("|")[3] ?? "";
-      const sb = sig.split("|")[3] ?? "";
-      const detail = va !== vb ? `value ${JSON.stringify(va)} → ${JSON.stringify(vb)}` : `state ${JSON.stringify(sa)} → ${JSON.stringify(sb)}`;
-      changed.push(`  [${ref}] ${key.replace("|", ' "')}": ${detail}`);
+      appeared.push(`  *[${ref}] ${describe(sig)}`);
+    } else if (before.value !== sig.value) {
+      changed.push(`  [${ref}] ${describe(sig)}: value ${JSON.stringify(before.value)} → ${JSON.stringify(sig.value)}`);
+    } else if (before.state !== sig.state) {
+      changed.push(`  [${ref}] ${describe(sig)}: state ${JSON.stringify(before.state)} → ${JSON.stringify(sig.state)}`);
     }
   }
   const removed: string[] = [];
-  for (const key of prevByKey.keys()) {
-    if (!curByKey.has(key)) removed.push(`  ${key.replace("|", ' "')}"`);
+  for (const [key, sig] of prevByKey) {
+    if (!curByKey.has(key)) removed.push(`  ${describe(sig)}`);
   }
 
   if (appeared.length === 0 && changed.length === 0 && removed.length === 0) return "";
@@ -116,3 +122,11 @@ export const interactiveDiff = async (client: BrowserClient): Promise<string> =>
   if (overflow > 0) lines.push(`  …and ${overflow} more (browser_snapshot for full state)`);
   return lines.join("\n");
 };
+
+// Convenience for action tools: refresh refs and append a diff to the action's text. A failed refresh is reported
+// inline rather than failing the action that already happened.
+export const interactiveDiff = async (client: BrowserClient): Promise<string> => {
+  const refreshed = await refreshRefs(client);
+  if (!refreshed.success) return `\n(page diff unavailable: ${refreshed.error.message})`;
+  return diffSignatures(refreshed.data.prev, refreshed.data.cur);
+};

package/src/domains/ref-signature.ts

@@ -0,0 +1,11 @@
+import type { RefSignature } from "../cdp/types";
+import type { SlimNode } from "./ax-tree";
+
+export type { RefSignature };
+
+export const signatureOf = (n: SlimNode): RefSignature => ({
+  role: n.role,
+  name: n.name ?? "",
+  value: n.value ?? "",
+  state: n.state ?? "",
+});

package/src/domains/render.ts

@@ -1,32 +1,21 @@
-import { Markdown, Text } from "@mariozechner/pi-tui";
+import { Type } from "typebox";
+import { Markdown } from "@mariozechner/pi-tui";
 import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
 import type { Component } from "@mariozechner/pi-tui";
-import type { Theme } from "@mariozechner/pi-coding-agent";
-import { isRecord } from "../util/guards";
+import type { DetailsOf } from "../util/tool";
 
 const COMPACT_PREVIEW_LINES = 6;
 
-type ExpandableText = {
-  readonly summary: string;
-  readonly body: string;
-  readonly fullOutputPath?: string;
-};
-
-const isExpandableText = (value: unknown): value is ExpandableText =>
-  isRecord(value) && typeof value["summary"] === "string" && typeof value["body"] === "string";
-
-const extractRender = (details: unknown): unknown =>
-  isRecord(details) ? details["render"] : undefined;
+// A tool whose details embed this under `render` gets a compact/expanded text view for free.
+export const ExpandableTextSchema = Type.Object({
+  summary: Type.String(),
+  body: Type.String(),
+  fullOutputPath: Type.Optional(Type.String()),
+});
 
-export const renderExpandableText = (
-  label: string,
-  result: { readonly details?: unknown },
-  expanded: boolean,
-  theme: Theme,
-): Component => {
-  const render = extractRender(result.details);
-  if (!isExpandableText(render)) return new Text(theme.fg("error", `${label}: no details`), 0, 0);
+export type ExpandableText = DetailsOf<typeof ExpandableTextSchema>;
 
+export const renderExpandableText = (render: ExpandableText, expanded: boolean): Component => {
   if (!expanded) {
     const lines = render.body.split("\n");
     const preview = lines.slice(0, COMPACT_PREVIEW_LINES).join("\n");
@@ -35,7 +24,7 @@ export const renderExpandableText = (
     return new Markdown(md, 0, 0, getMarkdownTheme());
   }
 
-  const tail = render.fullOutputPath
+  const tail = render.fullOutputPath !== undefined
     ? `\n\nFull output at \`${render.fullOutputPath}\` · ${keyHint("app.tools.expand", "to collapse")}`
     : `\n\n${keyHint("app.tools.expand", "to collapse")}`;
   const md = `**${render.summary}**\n\n${render.body}${tail}`;

package/src/domains/screenshot-capture.ts

@@ -1,4 +1,4 @@
-import { rename, writeFile } from "node:fs/promises";
+import { rename } from "node:fs/promises";
 import type { BrowserClient } from "../client";
 import { type Result, ok } from "../util/result";
 import type { ToolErr } from "../util/tool";
@@ -6,6 +6,7 @@ import { screenshotPath } from "../util/paths";
 import { loadSharp } from "../util/sharp-shim";
 import { safeJs } from "../util/js-template";
 import { cdpCall, evalJs } from "./cdp-call";
+import { writeFileResult } from "./io";
 
 export type CaptureArgs = {
   readonly fullPage?: boolean;
@@ -26,7 +27,8 @@ export const captureBase = async (
     ...(format === "jpeg" ? { quality } : {}),
   });
   if (!r.success) return r;
-  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({ path, format });
 };
 

package/src/domains/screenshot.ts

@@ -2,8 +2,7 @@ import { readFileSync } from "node:fs";
 import { Type } from "typebox";
 import { Image, type ImageTheme, Text, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 import { type Result, ok } from "../util/result";
-import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
-import { asRecord, asString } from "../util/guards";
+import { type DetailsOf, defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
 import { captureBase, resizeIfNeeded } from "./screenshot-capture";
 
 const ScreenshotArgs = Type.Object({
@@ -13,6 +12,14 @@ const ScreenshotArgs = Type.Object({
   maxDim: Type.Optional(Type.Integer({ minimum: 100, maximum: 8000, description: "If max(w,h) exceeds this, resize via sharp." })),
 });
 
+const ScreenshotDetailsSchema = Type.Object({
+  path: Type.String(),
+  format: Type.Union([Type.Literal("png"), Type.Literal("jpeg")]),
+  attached: Type.Boolean(),
+});
+
+export type ScreenshotDetails = DetailsOf<typeof ScreenshotDetailsSchema>;
+
 export const screenshotTool = defineBrowserTool({
   name: "browser_screenshot",
   label: "Browser Screenshot",
@@ -23,8 +30,9 @@ export const screenshotTool = defineBrowserTool({
     "format='jpeg' with quality 60-90 keeps screenshots small for photo-heavy pages. Use maxDim if the page is huge.",
   ],
   parameters: ScreenshotArgs,
+  details: ScreenshotDetailsSchema,
   concurrency: "parallel",
-  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+  async handler(args, { client }): Promise<Result<ToolOk<ScreenshotDetails>, ToolErr>> {
     const cap = await captureBase(client, args);
     if (!cap.success) return cap;
     let note = "";
@@ -39,12 +47,7 @@ export const screenshotTool = defineBrowserTool({
   },
 
   renderResult(result, _expanded, theme) {
-    const raw = asRecord(result.details);
-    const filePath = raw === undefined ? undefined : asString(raw["path"]);
-    if (!filePath) {
-      return new Text(theme.fg("error", "Screenshot path missing"), 0, 0);
-    }
-    const format = raw === undefined ? undefined : asString(raw["format"]);
+    const { path: filePath, format } = result.details;
     try {
       const buf = readFileSync(filePath);
       const b64 = buf.toString("base64");
@@ -59,7 +62,7 @@ export const screenshotTool = defineBrowserTool({
       });
       // Image's text fallback does not respect the rendered width, so an unwrapped long path can blow past the terminal width and crash the host TUI.
       return {
-        invalidate: () => image.invalidate(),
+        invalidate: () => { image.invalidate(); },
         render: (width: number) =>
           image.render(width).map((line) =>
             visibleWidth(line) > width ? truncateToWidth(line, width) : line,

package/src/domains/scroll.ts

@@ -1,7 +1,7 @@
 import { Type } from "typebox";
 import { type Result, err, ok } from "../util/result";
 import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
-import { cdpCall } from "./cdp-call";
+import { cdpCall, fromClient } from "./cdp-call";
 
 const ScrollArgs = Type.Object({
   x: Type.Optional(Type.Number({ description: "X coordinate where to scroll. Default: viewport center" })),
@@ -25,9 +25,9 @@ export const scrollTool = defineBrowserTool({
   parameters: ScrollArgs,
   concurrency: "serialized",
   async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
-    const info = await client.pageInfo();
-    if (!info.success) return err({ kind: "cdp_error", message: info.error.message });
-    if ("dialog" in info.data) {
+    const info = fromClient(await client.pageInfo(), "pageInfo");
+    if (!info.success) return info;
+    if (info.data.kind === "dialog") {
       return err({
         kind: "invalid_state",
         message: `Dialog open: ${info.data.dialog.type} — ${info.data.dialog.message}`,

package/src/domains/search/google-serp.ts

@@ -29,7 +29,7 @@ const CAPTCHA_MARKERS: ReadonlyArray<string> = [
 ];
 
 const unwrapRedirect = (href: string): string => {
-  const wrapper = href.match(/^(?:https?:\/\/[^/]*google\.[^/]*)?\/url\?/i);
+  const wrapper = /^(?:https?:\/\/[^/]*google\.[^/]*)?\/url\?/i.exec(href);
   if (!wrapper) return href;
   const query = href.slice(href.indexOf("?") + 1);
   const target = new URLSearchParams(query).get("q");