pi-feats 0.1.2 → 0.1.4

package/extensions/browser-harness/domains/ax-tree.ts

@@ -0,0 +1,179 @@
+import type { AxNodeResult } from "../cdp/commands";
+import type { BrowserClient } from "../client";
+import type { Box } from "./box";
+import { cdpCall } from "./cdp-call";
+
+export type RawAxNode = AxNodeResult;
+type AxValue = NonNullable<RawAxNode["role"]>;
+
+export type SlimNode = {
+  role: string;
+  name?: string;
+  value?: string;
+  description?: string;
+  state?: string;
+  children: SlimNode[];
+  _backendId?: number;
+  ref?: string;
+  box?: Box;
+};
+
+export const INTERACTIVE_ROLES = new Set([
+  "button",
+  "link",
+  "textbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "menuitem",
+  "tab",
+  "switch",
+  "slider",
+  "searchbox",
+  "spinbutton",
+]);
+
+// The AX `value` is stale for freshly-typed or controlled inputs, so for these roles the live DOM property is read instead.
+export const VALUE_ROLES = new Set([
+  "textbox",
+  "searchbox",
+  "spinbutton",
+  "combobox",
+  "checkbox",
+  "radio",
+  "switch",
+  "slider",
+]);
+
+const stringOf = (v: AxValue | undefined): string | undefined => {
+  const x = v?.value;
+  if (typeof x === "string" && x !== "") return x;
+  if (typeof x === "number") return String(x);
+  return undefined;
+};
+
+const collectState = (props: RawAxNode["properties"]): string | undefined => {
+  if (!props || props.length === 0) return undefined;
+  const flags: string[] = [];
+  for (const p of props) {
+    const name = p.name;
+    if (!name) continue;
+    const raw = p.value?.value;
+    if (raw === true && (name === "focused" || name === "required" || name === "disabled" || name === "checked" || name === "expanded" || name === "selected" || name === "pressed" || name === "modal")) {
+      flags.push(name);
+    }
+    if (typeof raw === "number" && name === "level") flags.push(`level ${raw}`);
+  }
+  return flags.length > 0 ? flags.join(", ") : undefined;
+};
+
+export const buildTree = (
+  rawNodes: ReadonlyArray<RawAxNode>,
+  opts: { interestingOnly: boolean; maxNodes: number },
+): SlimNode[] => {
+  const byId = new Map<string, RawAxNode>();
+  for (const n of rawNodes) byId.set(n.nodeId, n);
+
+  const rootIds: string[] = [];
+  for (const n of rawNodes) {
+    if (!n.parentId || !byId.has(n.parentId)) rootIds.push(n.nodeId);
+  }
+
+  let budget = opts.maxNodes;
+
+  const slim = (node: RawAxNode): SlimNode | undefined => {
+    if (budget <= 0) return undefined;
+    if (opts.interestingOnly && node.ignored) {
+      // Chrome often ignores wrapper divs while their descendants remain meaningful, so recurse through an ignored node's children.
+      const out: SlimNode[] = [];
+      for (const cid of node.childIds ?? []) {
+        const child = byId.get(cid);
+        if (!child) continue;
+        const slimChild = slim(child);
+        if (slimChild) out.push(slimChild);
+      }
+      return out.length > 0 ? { role: "_hoist", children: out } : undefined;
+    }
+    budget--;
+    const role = stringOf(node.role) ?? "unknown";
+    const name = stringOf(node.name);
+    const value = stringOf(node.value);
+    const description = stringOf(node.description);
+    const state = collectState(node.properties);
+    const children: SlimNode[] = [];
+    for (const cid of node.childIds ?? []) {
+      const child = byId.get(cid);
+      if (!child) continue;
+      const slimChild = slim(child);
+      if (!slimChild) continue;
+      if (slimChild.role === "_hoist") children.push(...slimChild.children);
+      else children.push(slimChild);
+    }
+    const out: SlimNode = { role, children };
+    if (name !== undefined) out.name = name;
+    if (value !== undefined) out.value = value;
+    if (description !== undefined) out.description = description;
+    if (state !== undefined) out.state = state;
+    if (node.backendDOMNodeId !== undefined) out._backendId = node.backendDOMNodeId;
+    return out;
+  };
+
+  const result: SlimNode[] = [];
+  for (const rid of rootIds) {
+    const root = byId.get(rid);
+    if (!root) continue;
+    const s = slim(root);
+    if (!s) continue;
+    if (s.role === "_hoist") result.push(...s.children);
+    else result.push(s);
+  }
+  return result;
+};
+
+export const countNodes = (nodes: ReadonlyArray<SlimNode>): number => {
+  let n = 0;
+  for (const node of nodes) n += 1 + countNodes(node.children);
+  return n;
+};
+
+export const stripInternals = (nodes: ReadonlyArray<SlimNode>): SlimNode[] =>
+  nodes.map((n) => {
+    const { _backendId: _bid, ...rest } = n;
+    return { ...rest, children: stripInternals(n.children) };
+  });
+
+export const collectInteractiveTargets = (
+  nodes: ReadonlyArray<SlimNode>,
+): Array<{ node: SlimNode; backendId: number }> => {
+  const out: Array<{ node: SlimNode; backendId: number }> = [];
+  const walk = (ns: ReadonlyArray<SlimNode>): void => {
+    for (const n of ns) {
+      if (n._backendId !== undefined && INTERACTIVE_ROLES.has(n.role)) {
+        out.push({ node: n, backendId: n._backendId });
+      }
+      walk(n.children);
+    }
+  };
+  walk(nodes);
+  return out;
+};
+
+export const liveValue = async (client: BrowserClient, backendId: number): Promise<string | undefined> => {
+  const resolved = await cdpCall(client, "DOM.resolveNode", { backendNodeId: backendId });
+  if (!resolved.success) return undefined;
+  const objectId = resolved.data.object.objectId;
+  if (!objectId) return undefined;
+  const fn = `function () {
+    if (this.type === "checkbox" || this.type === "radio") return this.checked ? "checked" : "unchecked";
+    if (typeof this.value === "string") return this.value;
+    return null;
+  }`;
+  const r = await cdpCall(client, "Runtime.callFunctionOn", {
+    objectId,
+    functionDeclaration: fn,
+    returnByValue: true,
+  });
+  if (!r.success) return undefined;
+  const value = r.data.result.value;
+  return typeof value === "string" ? value : undefined;
+};

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

@@ -0,0 +1,51 @@
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import type { ToolErr } from "../util/tool";
+import { cdpCall } from "./cdp-call";
+
+export type Box = {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly cx: number;
+  readonly cy: number;
+};
+
+type BoxModel = {
+  readonly content: ReadonlyArray<number>;
+  readonly width: number;
+  readonly height: number;
+};
+
+export const centreOf = (model: BoxModel): Box => {
+  const x = model.content[0] ?? 0;
+  const y = model.content[1] ?? 0;
+  return {
+    x: Math.round(x),
+    y: Math.round(y),
+    width: Math.round(model.width),
+    height: Math.round(model.height),
+    cx: Math.round(x + model.width / 2),
+    cy: Math.round(y + model.height / 2),
+  };
+};
+
+export const boxOf = async (
+  client: BrowserClient,
+  backendNodeId: number,
+): Promise<Result<Box, ToolErr>> => {
+  const r = await cdpCall(client, "DOM.getBoxModel", { backendNodeId });
+  if (!r.success) return r;
+  const model = r.data.model;
+  if (model.content.length < 8) {
+    return err({ kind: "invalid_state", message: "DOM.getBoxModel returned an incomplete content quad" });
+  }
+  if (model.width <= 0 || model.height <= 0) {
+    return err({
+      kind: "invalid_state",
+      message: "element has a zero-size box and cannot be clicked",
+    });
+  }
+  return ok(centreOf(model));
+};

package/extensions/browser-harness/domains/cdp-call.ts

@@ -0,0 +1,55 @@
+import type { BrowserClient } from "../client";
+import type { CdpMethod, ParamsOf, ResultOf } from "../cdp/commands";
+import type { CdpError } from "../cdp/errors";
+import { type Result, err } from "../util/result";
+import type { ToolErr } from "../util/tool";
+
+export const cdpErrToToolErr = (e: CdpError, method: string): ToolErr => ({
+  kind: e.kind === "timeout" ? "timeout" : "cdp_error",
+  message: e.message,
+  details: { method },
+});
+
+export const cdpCall = async <M extends CdpMethod>(
+  client: BrowserClient,
+  method: M,
+  params: ParamsOf<M>,
+  opts?: { timeoutMs?: number },
+): Promise<Result<ResultOf<M>, ToolErr>> => {
+  const r = await client.session().call(method, params, opts);
+  if (!r.success) return err(cdpErrToToolErr(r.error, method));
+  return r;
+};
+
+export const cdpCallOnTarget = async <M extends CdpMethod>(
+  client: BrowserClient,
+  method: M,
+  params: ParamsOf<M>,
+  sessionId: string,
+  opts?: { timeoutMs?: number },
+): Promise<Result<ResultOf<M>, ToolErr>> => {
+  const r = await client.session().callOnTarget(method, params, sessionId, opts);
+  if (!r.success) return err(cdpErrToToolErr(r.error, method));
+  return r;
+};
+
+export const cdpCallBrowser = async <M extends CdpMethod>(
+  client: BrowserClient,
+  method: M,
+  params?: ParamsOf<M>,
+  opts?: { timeoutMs?: number },
+): Promise<Result<ResultOf<M>, ToolErr>> => {
+  const r = await client.session().callBrowser(method, params, opts);
+  if (!r.success) return err(cdpErrToToolErr(r.error, method));
+  return r;
+};
+
+export const evalJs = async (
+  client: BrowserClient,
+  expression: string,
+  sessionId?: string,
+): Promise<Result<unknown, ToolErr>> => {
+  const r = await client.evaluateJs(expression, sessionId);
+  if (!r.success) return err(cdpErrToToolErr(r.error, "Runtime.evaluate"));
+  return r;
+};

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

@@ -0,0 +1,97 @@
+import { Type } from "typebox";
+import { Text } from "@earendil-works/pi-tui";
+import type { BrowserClient } from "../client";
+import { Coords, MouseButton } from "../schemas/common";
+import { type Result, ok } from "../util/result";
+import { debugClicksEnabled } from "../util/debug";
+import { defineBrowserTool, type ToolErr } from "../util/tool";
+import { cdpCall } from "./cdp-call";
+import { captureWithCrosshair } from "./screenshot-capture";
+import { interactiveDiff } from "./ref-resolve";
+import { resolveTarget } from "./target";
+
+const ClickArgs = Type.Object({
+  ref: Type.Optional(
+    Type.String({
+      description:
+        "Stable element ref from browser_snapshot (e.g. 'e12'). PREFERRED over x/y — survives re-renders. When set, x/y are ignored.",
+    }),
+  ),
+  x: Type.Optional(Coords.properties.x),
+  y: Type.Optional(Coords.properties.y),
+  button: Type.Optional(MouseButton),
+  count: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: 3,
+      default: 1,
+      description: "Number of clicks (1 = single, 2 = double). Default: 1",
+    }),
+  ),
+});
+
+const dispatchClick = async (
+  client: BrowserClient,
+  x: number,
+  y: number,
+  button: "left" | "right" | "middle",
+  count: number,
+): Promise<Result<void, ToolErr>> => {
+  // Some focus/hover handlers and React synthetic events only fire when a mousemove precedes the press, so without it a click lands without focusing.
+  const moved = await cdpCall(client, "Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
+  if (!moved.success) return moved;
+  const pressed = await cdpCall(client, "Input.dispatchMouseEvent", {
+    type: "mousePressed", x, y, button, clickCount: count,
+  });
+  if (!pressed.success) return pressed;
+  const released = await cdpCall(client, "Input.dispatchMouseEvent", {
+    type: "mouseReleased", x, y, button, clickCount: count,
+  });
+  if (!released.success) return released;
+  return ok(undefined);
+};
+
+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.",
+  promptSnippet: "Click an element by ref (preferred) or pixel coordinates",
+  promptGuidelines: [
+    "PREFER `ref` from browser_snapshot (the outline shows '[eN]' for every interactive element) — it survives re-renders, unlike coordinates which go stale after a save/edit reflows the page.",
+    "Fallback: pass (x, y) from the snapshot's '@(x,y)' hint when there's no ref.",
+    "A 'ref is stale' error means the page changed — re-run browser_snapshot to get fresh refs.",
+    "After clicking, read the appended page-changes diff to confirm the action landed before moving on (no separate snapshot needed for a quick check).",
+    "Coordinates are viewport CSS pixels (not device pixels). Compositor-level clicks pass through iframes, shadow DOM, and cross-origin content.",
+    "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.",
+  ],
+  parameters: ClickArgs,
+  concurrency: "serialized",
+  renderCall: (a) => new Text(`🖱️ Click ${a.ref ? `[${a.ref}]` : `(${a.x}, ${a.y})`}`, 0, 0),
+  async handler(args, { client }) {
+    const button = args.button ?? "left";
+    const count = args.count ?? 1;
+
+    const resolved = await resolveTarget(client, args);
+    if (!resolved.success) return resolved;
+    const { x, y, label: target } = resolved.data;
+
+    const clicked = await dispatchClick(client, x, y, button, count);
+    if (!clicked.success) return clicked;
+
+    const diff = await interactiveDiff(client);
+    if (debugClicksEnabled()) {
+      const debug = await captureWithCrosshair(client, { x, y });
+      if (debug.success) {
+        return ok({
+          text: `Clicked at ${target}\n[DEBUG] Overlay screenshot: ${debug.data.path}${diff}`,
+          details: { debugScreenshotPath: debug.data.path, x, y, ref: args.ref },
+        });
+      }
+    }
+    return ok({
+      text: `Clicked at ${target}${diff}`,
+      details: { x, y, ref: args.ref },
+    });
+  },
+});

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

@@ -0,0 +1,219 @@
+import { Type } from "typebox";
+import { Markdown, Text } from "@earendil-works/pi-tui";
+import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
+import { type Result, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { applyTruncation } from "../util/truncate";
+import type { ConsoleRecord, ConsoleLevel } from "../cdp/console-buffer";
+import { asArrayOf, asBoolean, asNumber, asRecord, asString } from "../util/guards";
+
+const ConsoleArgs = Type.Object({
+  levels: Type.Optional(
+    Type.Array(
+      Type.Union(
+        [
+          Type.Literal("log"),
+          Type.Literal("info"),
+          Type.Literal("warn"),
+          Type.Literal("error"),
+          Type.Literal("debug"),
+        ],
+      ),
+      { description: 'Filter to these levels only, e.g. ["error","warn"]. Default: all levels.' },
+    ),
+  ),
+  textPattern: Type.Optional(
+    Type.String({ description: "Substring match by default. Wrap in slashes (e.g. /TypeError/) for regex." }),
+  ),
+  sinceSeq: Type.Optional(
+    Type.Integer({ minimum: 0, description: "Only records with seq strictly greater than this. Use the previous call's nextCursor to see only what's new." }),
+  ),
+  sinceMs: Type.Optional(
+    Type.Integer({ minimum: 0, description: "Only records from the last N ms." }),
+  ),
+  limit: Type.Optional(
+    Type.Integer({ default: 50, minimum: 1, maximum: 500, description: "Max records to return." }),
+  ),
+});
+
+const levelTag = (lvl: ConsoleLevel): string => {
+  switch (lvl) {
+    case "error": return "[error]";
+    case "warn":  return "[warn] ";
+    case "info":  return "[info] ";
+    case "debug": return "[debug]";
+    default:      return "[log]  ";
+  }
+};
+
+const formatLocation = (r: ConsoleRecord): string => {
+  if (r.url === undefined || r.url === "") return "";
+  const short = r.url.length > 60 ? "…" + r.url.slice(-59) : r.url;
+  return r.lineNumber !== undefined ? `${short}:${r.lineNumber}` : short;
+};
+
+const renderConsoleMarkdown = (
+  records: ReadonlyArray<ConsoleRecord>,
+  opts: { total: number; bufferOverflowed: boolean; expanded: boolean; nextCursor: number | undefined },
+): string => {
+  if (records.length === 0) {
+    if (opts.bufferOverflowed) return "_No matching console records. (Buffer overflowed since last drain — some events were dropped.)_";
+    return "_No matching console records captured yet._";
+  }
+
+  const counts = records.reduce<Record<ConsoleLevel, number>>(
+    (acc, r) => { acc[r.level]++; return acc; },
+    { log: 0, info: 0, warn: 0, error: 0, debug: 0 },
+  );
+
+  const summaryParts: string[] = [];
+  if (counts.error > 0) summaryParts.push(`${counts.error} error${counts.error === 1 ? "" : "s"}`);
+  if (counts.warn  > 0) summaryParts.push(`${counts.warn} warning${counts.warn === 1 ? "" : "s"}`);
+  if (counts.info  > 0) summaryParts.push(`${counts.info} info`);
+  if (counts.log   > 0) summaryParts.push(`${counts.log} log${counts.log === 1 ? "" : "s"}`);
+  if (counts.debug > 0) summaryParts.push(`${counts.debug} debug`);
+
+  const headerLines: string[] = [`**${summaryParts.join(" · ")}**`];
+  if (opts.bufferOverflowed) headerLines.push("⚠ buffer overflowed since last drain — older entries dropped");
+  if (opts.total > records.length) headerLines.push(`(${records.length} of ${opts.total} matches shown — increase \`limit\` for more)`);
+
+  const renderRow = (r: ConsoleRecord, compact: boolean): string => {
+    const tag = levelTag(r.level);
+    const loc = formatLocation(r);
+    const maxText = compact ? 80 : 200;
+    const text = r.text.length > maxText ? r.text.slice(0, maxText - 1) + "…" : r.text;
+    const locSuffix = loc !== "" ? `  _at ${loc}_` : "";
+    const main = `\`${tag}\` ${text}${locSuffix}`;
+    if (!compact && r.stackTrace !== undefined) return `${main}\n\`\`\`\n${r.stackTrace}\n\`\`\``;
+    return main;
+  };
+
+  const visible = !opts.expanded && records.length > 5 ? records.slice(-5) : records;
+  const rows = visible.map((r) => renderRow(r, !opts.expanded)).join(opts.expanded ? "\n\n" : "\n");
+
+  const more = !opts.expanded && records.length > 5 ? `\n  … ${records.length - 5} earlier (expand to see all)` : "";
+  const cursor = opts.nextCursor !== undefined ? `\n\n_nextCursor=${opts.nextCursor}_` : "";
+
+  return `${headerLines.join("\n")}\n\n${rows}${more}${cursor}`;
+};
+
+type ConsoleDetails = {
+  total: number;
+  returned: number;
+  bufferOverflowed: boolean;
+  truncated: boolean;
+  fullOutputPath?: string;
+  records: ReadonlyArray<ConsoleRecord>;
+  nextCursor?: number;
+};
+
+const CONSOLE_LEVELS: ReadonlyArray<ConsoleLevel> = ["log", "info", "warn", "error", "debug"];
+
+const asConsoleLevel = (v: unknown): ConsoleLevel | undefined =>
+  CONSOLE_LEVELS.find((l) => l === v);
+
+const asConsoleRecord = (v: unknown): ConsoleRecord | undefined => {
+  const o = asRecord(v);
+  if (o === undefined) return undefined;
+  const level = asConsoleLevel(o["level"]);
+  const text = asString(o["text"]);
+  if (level === undefined || text === undefined) return undefined;
+  const url = asString(o["url"]);
+  const lineNumber = asNumber(o["lineNumber"]);
+  const stackTrace = asString(o["stackTrace"]);
+  return {
+    seq: asNumber(o["seq"]) ?? 0,
+    timestampMs: asNumber(o["timestampMs"]) ?? 0,
+    level,
+    text,
+    source: o["source"] === "log-entry" ? "log-entry" : "console-api",
+    ...(url !== undefined ? { url } : {}),
+    ...(lineNumber !== undefined ? { lineNumber } : {}),
+    ...(stackTrace !== undefined ? { stackTrace } : {}),
+  };
+};
+
+const asConsoleDetails = (v: unknown): ConsoleDetails | undefined => {
+  const o = asRecord(v);
+  if (o === undefined) return undefined;
+  const records = asArrayOf(o["records"], asConsoleRecord);
+  if (records === undefined) return undefined;
+  const fullOutputPath = asString(o["fullOutputPath"]);
+  const nextCursor = asNumber(o["nextCursor"]);
+  return {
+    total: asNumber(o["total"]) ?? records.length,
+    returned: asNumber(o["returned"]) ?? records.length,
+    bufferOverflowed: asBoolean(o["bufferOverflowed"]) ?? false,
+    truncated: asBoolean(o["truncated"]) ?? false,
+    records,
+    ...(fullOutputPath !== undefined ? { fullOutputPath } : {}),
+    ...(nextCursor !== undefined ? { nextCursor } : {}),
+  };
+};
+
+export const consoleTool = defineBrowserTool({
+  name: "browser_console",
+  label: "Browser Console",
+  description:
+    "Read JS errors and console messages from the active tab. Diagnostic — use when an action looks broken or silent.",
+  promptSnippet: "Read JS errors / console output on the current tab",
+  promptGuidelines: [
+    "Use after a click, submit, or navigate produced no visible change — errors often explain it.",
+    "Pass `sinceSeq` from the previous call's `nextCursor` to see only new messages after an action.",
+    "Buffer is reset on tab switch (capacity 500 records). bufferOverflowed:true means older entries were dropped.",
+    "Don't use as a default observation tool — prefer browser_snapshot for page structure.",
+  ],
+  parameters: ConsoleArgs,
+  concurrency: "parallel",
+
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const session = client.session();
+    const drained = session.drainConsoleBuffer({
+      ...(args.levels !== undefined ? { levels: args.levels } : {}),
+      ...(args.textPattern !== undefined ? { textPattern: args.textPattern } : {}),
+      ...(args.sinceSeq !== undefined ? { sinceSeq: args.sinceSeq } : {}),
+      ...(args.sinceMs !== undefined ? { sinceMs: args.sinceMs } : {}),
+      limit: args.limit ?? 50,
+    });
+
+    const last = drained.records.at(-1);
+    const nextCursor = last?.seq;
+
+    const text = renderConsoleMarkdown(drained.records, {
+      total: drained.total,
+      bufferOverflowed: drained.bufferOverflowed,
+      expanded: true,
+      nextCursor,
+    });
+    const trunc = await applyTruncation(text, "console");
+
+    const details: ConsoleDetails = {
+      total: drained.total,
+      returned: drained.records.length,
+      bufferOverflowed: drained.bufferOverflowed,
+      truncated: trunc.wasTruncated,
+      records: drained.records,
+      ...(nextCursor !== undefined ? { nextCursor } : {}),
+    };
+    if (trunc.fullOutputPath !== undefined) details.fullOutputPath = trunc.fullOutputPath;
+
+    return ok({ text: trunc.text, details });
+  },
+
+  renderResult(result, expanded, theme) {
+    const details = asConsoleDetails(result.details);
+    if (!details) return new Text(theme.fg("error", "console: no details"), 0, 0);
+
+    const md = renderConsoleMarkdown(details.records, {
+      total: details.total,
+      bufferOverflowed: details.bufferOverflowed,
+      expanded,
+      nextCursor: details.nextCursor,
+    });
+    const tail = expanded
+      ? `\n\n${keyHint("app.tools.expand", "to collapse")}${details.fullOutputPath ? ` · full payload at \`${details.fullOutputPath}\`` : ""}`
+      : `\n\n${keyHint("app.tools.expand", "to expand")}`;
+
+    return new Markdown(md + tail, 0, 0, getMarkdownTheme());
+  },
+});

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

@@ -0,0 +1,34 @@
+import { Type } from "typebox";
+import { type Result, ok } from "../util/result";
+import { defineBrowserTool, type ToolErr, type ToolOk } from "../util/tool";
+import { cdpCall } from "./cdp-call";
+
+const HandleDialogArgs = Type.Object({
+  accept: Type.Boolean({ description: "true = accept, false = dismiss" }),
+  promptText: Type.Optional(Type.String({ description: "Text to type if dialog is a prompt()" })),
+});
+
+export const handleDialogTool = defineBrowserTool({
+  name: "browser_handle_dialog",
+  label: "Browser Handle Dialog",
+  description:
+    "Accept or dismiss the currently open JS dialog (alert/confirm/prompt/beforeunload).",
+  promptSnippet: "Accept or dismiss a JS dialog",
+  promptGuidelines: [
+    "Use after browser_page_info reports a dialog is open. Until handled, no other browser action will work.",
+    "For prompt() dialogs, supply promptText with the value to submit.",
+  ],
+  parameters: HandleDialogArgs,
+  concurrency: "serialized",
+  async handler(args, { client }): Promise<Result<ToolOk, ToolErr>> {
+    const r = await cdpCall(client, "Page.handleJavaScriptDialog", {
+      accept: args.accept,
+      ...(args.promptText !== undefined ? { promptText: args.promptText } : {}),
+    });
+    if (!r.success) return r;
+    return ok({
+      text: `Dialog ${args.accept ? "accepted" : "dismissed"}`,
+      details: { accept: args.accept },
+    });
+  },
+});