@oh-my-pi/pi-coding-agent 16.1.9 → 16.1.11

package/src/tools/browser/cmux/cmux-tab.ts

@@ -10,6 +10,7 @@ import { resizeImage } from "../../../utils/image-resize";
 import { resolveToCwd } from "../../path-utils";
 import { formatScreenshot } from "../../render-utils";
 import { ToolAbortError, ToolError } from "../../tool-errors";
+import { type AriaSnapshotOptions, buildAriaSnapshotScript } from "../aria/aria-snapshot";
 import { DEFAULT_VIEWPORT } from "../launch";
 import { extractReadableFromHtml, type ReadableFormat } from "../readable";
 import type { Observation, ReadyInfo, RunResultOk, ScreenshotResult, SessionSnapshot } from "../tab-protocol";
@@ -49,7 +50,7 @@ interface RunContext {
 
 type WaitUntil = "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
 type DragTarget = string | { readonly x: number; readonly y: number };
-type SelectorKind = "css" | "ref" | "text" | "aria" | "xpath" | "pierce" | "ax";
+type SelectorKind = "css" | "ref" | "aria-ref" | "text" | "aria" | "xpath" | "pierce" | "ax";
 
 interface SelectorSpec {
 	kind: SelectorKind;
@@ -124,6 +125,20 @@ const accessibleName = element =>
 const findElement = spec => {
 	if (spec.kind === "css") return document.querySelector(spec.value);
 	if (spec.kind === "pierce") return pierceQuery(document, spec.value);
+	if (spec.kind === "aria-ref") {
+		const wanted = spec.value;
+		const scan = root => {
+			for (const el of Array.from(root.querySelectorAll("*"))) {
+				if (el._ariaRef && el._ariaRef.ref === wanted) return el;
+				if (el.shadowRoot) {
+					const found = scan(el.shadowRoot);
+					if (found) return found;
+				}
+			}
+			return null;
+		};
+		return scan(document);
+	}
 	if (spec.kind === "xpath") {
 		const result = document.evaluate(spec.value, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null);
 		return result.singleNodeValue instanceof Element ? result.singleNodeValue : null;
@@ -352,6 +367,24 @@ export class CmuxTab {
 		return observation;
 	}
 
+	async ariaSnapshot(selector?: string, opts?: AriaSnapshotOptions): Promise<string> {
+		const timeoutMs = Math.min(this.#runContext?.timeoutMs ?? 30_000, 30_000);
+		const result = (await this.#request(
+			"browser.eval",
+			{ script: buildAriaSnapshotScript(selector, opts) },
+			timeoutMs,
+		)) as CmuxEvalResult;
+		return result.value as string;
+	}
+
+	async ref(id: string): Promise<CmuxElementHandle> {
+		const refId = /^e\d+$/.test(id.trim()) ? id.trim() : id.trim().replace(/^(?:aria-ref=|aria-ref\/|ariaref\/)/, "");
+		const selector = `aria-ref=${refId}`;
+		const timeoutMs = this.#runContext?.timeoutMs ?? 30_000;
+		await this.#waitForSelector(selector, timeoutMs);
+		return new CmuxElementHandle(this, selector);
+	}
+
 	async click(selector: string): Promise<void> {
 		await this.#selectorAction(selector, "click");
 	}
@@ -401,6 +434,12 @@ export class CmuxTab {
 		return new CmuxElementHandle(this, selector);
 	}
 
+	async waitForSelector(selector: string, opts?: { timeout?: number }): Promise<CmuxElementHandle> {
+		const timeoutMs = opts?.timeout ?? this.#runContext?.timeoutMs ?? 30_000;
+		await this.#waitForSelector(selector, timeoutMs);
+		return new CmuxElementHandle(this, selector);
+	}
+
 	async evaluate<TResult, TArgs extends unknown[]>(
 		fn: string | ((...args: TArgs) => TResult | Promise<TResult>),
 		...args: TArgs
@@ -516,6 +555,37 @@ export class CmuxTab {
 		throw new ToolError(`tab.waitForUrl() timed out after ${timeoutMs}ms`);
 	}
 
+	async waitForNavigation(opts?: { waitUntil?: WaitUntil; timeout?: number }): Promise<null> {
+		const timeoutMs = opts?.timeout ?? this.#runContext?.timeoutMs ?? 30_000;
+		// Cmux has no native "next navigation" wait — snapshot the current URL via a fresh
+		// `browser.url.get` (never the possibly-stale `#lastUrl`), then poll for a change
+		// from it (mirroring headless `page.waitForNavigation` intent) and optionally settle
+		// on the requested load state. Start it BEFORE the click/submit that navigates; after
+		// a completed nav it times out like puppeteer does.
+		const baseline = (await this.#request("browser.url.get", {}, Math.min(timeoutMs, 5_000))) as CmuxUrlGetResult;
+		const startUrl = typeof baseline.url === "string" && baseline.url.length > 0 ? baseline.url : this.#lastUrl;
+		if (typeof baseline.url === "string" && baseline.url.length > 0) this.#lastUrl = baseline.url;
+		const deadline = Date.now() + timeoutMs;
+		while (Date.now() <= deadline) {
+			const result = (await this.#request("browser.url.get", {}, Math.min(timeoutMs, 5_000))) as CmuxUrlGetResult;
+			if (typeof result.url === "string" && result.url.length > 0) {
+				this.#lastUrl = result.url;
+				if (result.url !== startUrl) {
+					if (opts?.waitUntil) {
+						await this.#request(
+							"browser.wait",
+							{ load_state: mapWaitUntil(opts.waitUntil), timeout_ms: timeoutMs },
+							timeoutMs,
+						);
+					}
+					return null;
+				}
+			}
+			await Bun.sleep(200);
+		}
+		throw new ToolError(`tab.waitForNavigation() timed out after ${timeoutMs}ms`);
+	}
+
 	async drag(from: DragTarget, to: DragTarget): Promise<void> {
 		const start = await this.#dragPoint(from);
 		const end = await this.#dragPoint(to);
@@ -893,6 +963,8 @@ export class CmuxTab {
 		else if (normalized.startsWith("p-aria/")) normalized = `aria/${normalized.slice("p-aria/".length)}`;
 		else if (normalized.startsWith("p-xpath/")) normalized = `xpath/${normalized.slice("p-xpath/".length)}`;
 		else if (normalized.startsWith("p-pierce/")) normalized = `pierce/${normalized.slice("p-pierce/".length)}`;
+		const ariaRef = /^(?:aria-ref=|aria-ref\/|ariaref\/)(e\d+)$/.exec(normalized);
+		if (ariaRef) return { kind: "aria-ref", value: ariaRef[1]!, raw };
 		const ref = /^@?e(\d+)$/.exec(normalized);
 		if (ref) return { kind: "ref", value: ref[1]!, raw, ref: `@e${ref[1]}` };
 		const slash = normalized.indexOf("/");

package/src/tools/browser/tab-worker.ts

@@ -22,6 +22,12 @@ import { resizeImage } from "../../utils/image-resize";
 import { resolveToCwd } from "../path-utils";
 import { formatScreenshot } from "../render-utils";
 import { ToolAbortError, ToolError, throwIfAborted } from "../tool-errors";
+import {
+	type AriaSnapshotOptions,
+	captureAriaSnapshot,
+	parseAriaRefSelector,
+	resolveAriaRefHandle,
+} from "./aria/aria-snapshot";
 import {
 	applyStealthPatches,
 	applyViewport,
@@ -76,17 +82,85 @@ const INTERACTIVE_AX_ROLES = new Set([
 
 const LEGACY_SELECTOR_PREFIXES = ["p-aria/", "p-text/", "p-xpath/", "p-pierce/"] as const;
 
+const SELECTOR_HANDLER_PREFIXES = [
+	"aria/",
+	"text/",
+	"xpath/",
+	"pierce/",
+	"aria-ref=",
+	"aria-ref/",
+	"ariaref/",
+	"p-",
+] as const;
+
+/**
+ * Playwright-only selector engines/pseudos puppeteer cannot parse. Without this guard a
+ * `tab.click(":has-text(...)")` would wait the full action timeout and fail opaquely;
+ * fail fast instead with a pointer to the puppeteer-native alternative. Skipped for
+ * explicit query-handler prefixes (`text/`, `aria/`, …) whose payload is literal text.
+ */
+const PLAYWRIGHT_ONLY_SELECTOR_RE =
+	/:has-text\(|:text\(|:text-is\(|:text-matches\(|:visible\b|:hidden\b|:nth-match\(|:near\(|:above\(|:below\(|:right-of\(|:left-of\(/;
+
 type DialogPolicy = "accept" | "dismiss";
 type DragTarget = string | { readonly x: number; readonly y: number };
 type ActionabilityResult = { ok: true; x: number; y: number } | { ok: false; reason: string };
 
 /**
- * Per-op ceiling for puppeteer-internal helpers that should resolve quickly
- * (`observe`, `screenshot`, `extract`). Kept below the default 30s cell budget so a
- * single stalled helper fails fast with a named error and leaves budget for the rest
- * of the cell. Effective cap is `min(cellBudget, QUICK_OP_TIMEOUT_MS)`.
+ * Per-op fail-fast ceilings for `tab.*` helpers. All are kept strictly under the cell
+ * budget (`timeoutMs - OP_DEADLINE_SLACK_MS`) so a stalled helper rejects with a named,
+ * attributable error that leaves recovery budget — never the opaque whole-cell
+ * "Browser code execution timed out" path that consumed the entire run.
+ *
+ * - `QUICK_OP_TIMEOUT_MS`: page-coupled reads that should resolve fast (`observe`,
+ *   `screenshot`, `extract`, `ariaSnapshot`).
+ * - `ACTION_OP_TIMEOUT_MS`: interactive point actions (`click`, `fill`, `type`, …) and
+ *   the default for wait helpers when no explicit `{ timeout }` is given.
+ *
+ * `goto` and `evaluate` stay uncapped (`Number.POSITIVE_INFINITY`): navigation and user
+ * code legitimately use the full cell budget.
  */
 const QUICK_OP_TIMEOUT_MS = 20_000;
+const ACTION_OP_TIMEOUT_MS = 15_000;
+/** Headroom subtracted from the cell budget so a per-op deadline fires before it. */
+const OP_DEADLINE_SLACK_MS = 1_000;
+
+export interface OpTimeouts {
+	/** Largest per-op deadline allowed — strictly below the cell budget. */
+	budgetBound: number;
+	/** Ceiling for quick page reads. */
+	quickOpMs: number;
+	/** Ceiling for interactive actions + default for waits. */
+	actionOpMs: number;
+}
+
+/** Resolve the per-op fail-fast ceilings for a given cell budget. */
+export function resolveOpTimeouts(cellTimeoutMs: number): OpTimeouts {
+	const budgetBound = Math.max(1, cellTimeoutMs - OP_DEADLINE_SLACK_MS);
+	return {
+		budgetBound,
+		quickOpMs: Math.min(budgetBound, QUICK_OP_TIMEOUT_MS),
+		actionOpMs: Math.min(budgetBound, ACTION_OP_TIMEOUT_MS),
+	};
+}
+
+/**
+ * Effective timeout for a wait helper (`waitFor*`). A positive explicit `{ timeout }` is
+ * honored but clamped to the cell budget so it still fails fast + named; raising the tool
+ * `timeout` raises that cap, so a longer budget stays meaningful. No `{ timeout }` → the
+ * action ceiling. Puppeteer's `{ timeout: 0 }` / `Infinity` ("disable") maps to the largest
+ * bounded wait (`budgetBound`) — the harness never permits an unbounded wait. Garbage input
+ * (negative, `NaN`) falls back to the action ceiling rather than the longest wait.
+ */
+export function resolveWaitTimeout(cellTimeoutMs: number, explicit?: number): number {
+	const { budgetBound, actionOpMs } = resolveOpTimeouts(cellTimeoutMs);
+	if (explicit === undefined) return actionOpMs;
+	// Puppeteer "disable" sentinels — still bounded by the budget here.
+	if (explicit === 0 || explicit === Number.POSITIVE_INFINITY) return budgetBound;
+	// Positive finite → honored + clamped. Negative/NaN garbage → default, not the longest wait.
+	if (Number.isFinite(explicit) && explicit > 0) return Math.min(explicit, budgetBound);
+	return actionOpMs;
+}
 
 interface ScreenshotOptions {
 	selector?: string;
@@ -106,6 +180,7 @@ interface TabApi {
 		opts?: { waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2" },
 	): Promise<void>;
 	observe(opts?: { includeAll?: boolean; viewportOnly?: boolean }): Promise<Observation>;
+	ariaSnapshot(selector?: string, opts?: AriaSnapshotOptions): Promise<string>;
 	screenshot(opts?: ScreenshotOptions): Promise<ScreenshotResult>;
 	extract(format?: ReadableFormat): Promise<string>;
 	click(selector: string): Promise<void>;
@@ -114,7 +189,7 @@ interface TabApi {
 	press(key: KeyInput, opts?: { selector?: string }): Promise<void>;
 	scroll(deltaX: number, deltaY: number): Promise<void>;
 	drag(from: DragTarget, to: DragTarget): Promise<void>;
-	waitFor(selector: string): Promise<ElementHandle>;
+	waitFor(selector: string, opts?: { timeout?: number }): Promise<ElementHandle>;
 	evaluate<TResult, TArgs extends unknown[]>(
 		fn: string | ((...args: TArgs) => TResult | Promise<TResult>),
 		...args: TArgs
@@ -127,11 +202,29 @@ interface TabApi {
 		pattern: string | RegExp | ((response: HTTPResponse) => boolean | Promise<boolean>),
 		opts?: { timeout?: number },
 	): Promise<HTTPResponse>;
+	waitForSelector(
+		selector: string,
+		opts?: { timeout?: number; visible?: boolean; hidden?: boolean },
+	): Promise<ElementHandle | null>;
+	waitForNavigation(opts?: {
+		waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+		timeout?: number;
+	}): Promise<HTTPResponse | null>;
 	id(n: number): Promise<ElementHandle>;
+	ref(id: string): Promise<ElementHandle>;
 }
 
-function normalizeSelector(selector: string): string {
+export function normalizeSelector(selector: string): string {
 	if (!selector) return selector;
+	if (
+		!SELECTOR_HANDLER_PREFIXES.some(prefix => selector.startsWith(prefix)) &&
+		PLAYWRIGHT_ONLY_SELECTOR_RE.test(selector)
+	) {
+		throw new ToolError(
+			`Playwright-only selector ${JSON.stringify(selector)} is not supported by the browser tool. ` +
+				`Use a puppeteer text selector ("text/Allow all"), an aria selector ("aria/Name"), CSS, or "xpath/...".`,
+		);
+	}
 	if (selector.startsWith("p-") && !LEGACY_SELECTOR_PREFIXES.some(prefix => selector.startsWith(prefix))) {
 		throw new ToolError(
 			`Unsupported selector prefix. Use CSS or puppeteer query handlers (aria/, text/, xpath/, pierce/). Got: ${selector}`,
@@ -753,8 +846,15 @@ export class WorkerCore {
 		try {
 			return await fn(opSignal);
 		} catch (err) {
-			// Per-op deadline fired (not the cell budget, not an explicit abort) → named, actionable error.
-			if (opTimeout?.aborted && !cellSignal.aborted) {
+			// Fail fast with a named, attributable error instead of the opaque whole-cell timeout:
+			// our per-op deadline fired, or puppeteer's own (equal) timeout fired first — having
+			// already torn down the CDP action via the op signal, so no work is left dangling.
+			// Cell-budget aborts and uncapped helpers (goto/evaluate) keep their native errors.
+			if (
+				capped &&
+				!cellSignal.aborted &&
+				(opTimeout?.aborted || (err instanceof Error && err.name === "TimeoutError"))
+			) {
 				throw new ToolError(`${label} timed out after ${perOpTimeoutMs}ms`);
 			}
 			throw err;
@@ -773,7 +873,8 @@ export class WorkerCore {
 		active: ActiveRun,
 	): TabApi {
 		const page = this.#requirePage();
-		const quickOpMs = Math.min(timeoutMs, QUICK_OP_TIMEOUT_MS);
+		const { quickOpMs, actionOpMs } = resolveOpTimeouts(timeoutMs);
+		const waitMs = (explicit?: number): number => resolveWaitTimeout(timeoutMs, explicit);
 		const INF = Number.POSITIVE_INFINITY;
 		const op = <T>(label: string, perOpMs: number, fn: (sig: AbortSignal) => Promise<T>): Promise<T> =>
 			this.#runOp(active, label, signal, perOpMs, fn);
@@ -792,6 +893,28 @@ export class WorkerCore {
 					);
 				}),
 			observe: opts => op("tab.observe()", quickOpMs, sig => this.#collectObservation({ ...opts, signal: sig })),
+			ariaSnapshot: (selector, opts) =>
+				op(
+					selector ? `tab.ariaSnapshot(${JSON.stringify(selector)})` : "tab.ariaSnapshot()",
+					quickOpMs,
+					async sig => {
+						let root: ElementHandle | null = null;
+						if (selector) {
+							root = (await untilAborted(sig, () =>
+								page.$(normalizeSelector(selector)),
+							)) as ElementHandle | null;
+							if (!root)
+								throw new ToolError(
+									`tab.ariaSnapshot: selector ${JSON.stringify(selector)} matched no element`,
+								);
+						}
+						try {
+							return await untilAborted(sig, () => captureAriaSnapshot(page, root, opts));
+						} finally {
+							await root?.dispose().catch(() => undefined);
+						}
+					},
+				),
 			screenshot: opts =>
 				op(describeScreenshot(opts), quickOpMs, sig =>
 					this.#captureScreenshot(session, displays, screenshots, sig, opts),
@@ -814,44 +937,88 @@ export class WorkerCore {
 					return content;
 				}),
 			click: selector =>
-				op(`tab.click(${JSON.stringify(selector)})`, INF, async sig => {
+				op(`tab.click(${JSON.stringify(selector)})`, actionOpMs, async sig => {
+					if (parseAriaRefSelector(selector) !== null) {
+						const handle = await this.#resolveAriaRef(selector);
+						try {
+							await untilAborted(sig, () => handle.click());
+						} finally {
+							await handle.dispose().catch(() => undefined);
+						}
+						return;
+					}
 					const resolved = normalizeSelector(selector);
-					if (resolved.startsWith("text/")) await clickQueryHandlerText(page, resolved, timeoutMs, sig);
-					else await untilAborted(sig, () => page.locator(resolved).setTimeout(timeoutMs).click());
+					if (resolved.startsWith("text/")) await clickQueryHandlerText(page, resolved, actionOpMs, sig);
+					else await untilAborted(sig, () => page.locator(resolved).setTimeout(actionOpMs).click({ signal: sig }));
 				}),
 			type: (selector, text) =>
-				op(`tab.type(${JSON.stringify(selector)})`, INF, async sig => {
-					const handle = (await untilAborted(sig, () =>
-						page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle(),
-					)) as ElementHandle;
+				op(`tab.type(${JSON.stringify(selector)})`, actionOpMs, async sig => {
+					const handle = await this.#resolveActionHandle(selector, actionOpMs, sig);
 					try {
 						await untilAborted(sig, () => handle.type(text, { delay: 0 }));
 					} finally {
-						await handle.dispose();
+						await handle.dispose().catch(() => undefined);
 					}
 				}),
 			fill: (selector, value) =>
-				op(`tab.fill(${JSON.stringify(selector)})`, INF, sig =>
-					untilAborted(sig, () => page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).fill(value)),
-				),
+				op(`tab.fill(${JSON.stringify(selector)})`, actionOpMs, async sig => {
+					if (parseAriaRefSelector(selector) !== null) {
+						const handle = await this.#resolveAriaRef(selector);
+						try {
+							await untilAborted(sig, () =>
+								handle.evaluate(el => {
+									const node = el as unknown as { value?: string; focus?: () => void };
+									node.focus?.();
+									if ("value" in node) node.value = "";
+								}),
+							);
+							await untilAborted(sig, () => handle.type(value, { delay: 0 }));
+						} finally {
+							await handle.dispose().catch(() => undefined);
+						}
+						return;
+					}
+					await untilAborted(sig, () =>
+						page.locator(normalizeSelector(selector)).setTimeout(actionOpMs).fill(value, { signal: sig }),
+					);
+				}),
 			press: (key, opts) =>
-				op(`tab.press(${JSON.stringify(key)})`, INF, async sig => {
+				op(`tab.press(${JSON.stringify(key)})`, actionOpMs, async sig => {
 					const selector = opts?.selector;
 					if (selector) await untilAborted(sig, () => page.focus(normalizeSelector(selector)));
 					await untilAborted(sig, () => page.keyboard.press(key));
 				}),
 			scroll: (deltaX, deltaY) =>
-				op("tab.scroll()", INF, sig => untilAborted(sig, () => page.mouse.wheel({ deltaX, deltaY }))),
-			drag: (from, to) => op("tab.drag()", INF, sig => this.#drag(from, to, sig)),
-			waitFor: selector =>
-				op(
-					`tab.waitFor(${JSON.stringify(selector)})`,
-					INF,
-					async sig =>
-						(await untilAborted(sig, () =>
-							page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle(),
-						)) as ElementHandle,
-				),
+				op("tab.scroll()", actionOpMs, sig => untilAborted(sig, () => page.mouse.wheel({ deltaX, deltaY }))),
+			drag: (from, to) => op("tab.drag()", actionOpMs, sig => this.#drag(from, to, sig)),
+			waitFor: (selector, opts) => {
+				const w = waitMs(opts?.timeout);
+				return op(`tab.waitFor(${JSON.stringify(selector)})`, w, sig =>
+					this.#resolveActionHandle(selector, w, sig),
+				);
+			},
+			waitForSelector: (selector, opts) => {
+				const w = waitMs(opts?.timeout);
+				return op(`tab.waitForSelector(${JSON.stringify(selector)})`, w, async sig => {
+					if (parseAriaRefSelector(selector) !== null) return this.#resolveAriaRef(selector);
+					return (await untilAborted(sig, () =>
+						page.waitForSelector(normalizeSelector(selector), {
+							timeout: w,
+							visible: opts?.visible,
+							hidden: opts?.hidden,
+							signal: sig,
+						}),
+					)) as ElementHandle | null;
+				});
+			},
+			waitForNavigation: opts => {
+				const w = waitMs(opts?.timeout);
+				return op("tab.waitForNavigation()", w, sig =>
+					untilAborted(sig, () =>
+						page.waitForNavigation({ waitUntil: opts?.waitUntil ?? "load", timeout: w, signal: sig }),
+					),
+				);
+			},
 			evaluate: (fn, ...args) =>
 				op("tab.evaluate()", INF, sig =>
 					untilAborted(sig, () =>
@@ -861,10 +1028,8 @@ export class WorkerCore {
 					),
 				) as never,
 			scrollIntoView: selector =>
-				op(`tab.scrollIntoView(${JSON.stringify(selector)})`, INF, async sig => {
-					const handle = (await untilAborted(sig, () =>
-						page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle(),
-					)) as ElementHandle;
+				op(`tab.scrollIntoView(${JSON.stringify(selector)})`, actionOpMs, async sig => {
+					const handle = await this.#resolveActionHandle(selector, actionOpMs, sig);
 					try {
 						await untilAborted(sig, () =>
 							handle.evaluate(el => {
@@ -879,16 +1044,23 @@ export class WorkerCore {
 					}
 				}),
 			select: (selector, ...values) =>
-				op(`tab.select(${JSON.stringify(selector)})`, INF, sig => this.#select(selector, values, timeoutMs, sig)),
+				op(`tab.select(${JSON.stringify(selector)})`, actionOpMs, sig =>
+					this.#select(selector, values, actionOpMs, sig),
+				),
 			uploadFile: (selector, ...filePaths) =>
-				op(`tab.uploadFile(${JSON.stringify(selector)})`, INF, sig =>
-					this.#uploadFile(selector, filePaths, timeoutMs, sig, session),
+				op(`tab.uploadFile(${JSON.stringify(selector)})`, actionOpMs, sig =>
+					this.#uploadFile(selector, filePaths, actionOpMs, sig, session),
 				),
-			waitForUrl: (pattern, opts) =>
-				op("tab.waitForUrl()", INF, sig => this.#waitForUrl(pattern, opts?.timeout ?? timeoutMs, sig)),
-			waitForResponse: (pattern, opts) =>
-				op("tab.waitForResponse()", INF, sig => this.#waitForResponse(pattern, opts?.timeout ?? timeoutMs, sig)),
+			waitForUrl: (pattern, opts) => {
+				const w = waitMs(opts?.timeout);
+				return op("tab.waitForUrl()", w, sig => this.#waitForUrl(pattern, w, sig));
+			},
+			waitForResponse: (pattern, opts) => {
+				const w = waitMs(opts?.timeout);
+				return op("tab.waitForResponse()", w, sig => this.#waitForResponse(pattern, w, sig));
+			},
 			id: id => this.#resolveCachedHandle(id),
+			ref: id => this.#resolveAriaRef(id),
 		};
 	}
 
@@ -1073,7 +1245,7 @@ export class WorkerCore {
 	async #select(selector: string, values: string[], timeoutMs: number, signal: AbortSignal): Promise<string[]> {
 		const page = this.#requirePage();
 		const handle = (await untilAborted(signal, () =>
-			page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle(),
+			page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle({ signal }),
 		)) as ElementHandle;
 		try {
 			return (await untilAborted(signal, () =>
@@ -1119,7 +1291,7 @@ export class WorkerCore {
 		if (!filePaths.length) throw new ToolError("tab.uploadFile() requires at least one file path");
 		const page = this.#requirePage();
 		const handle = (await untilAborted(signal, () =>
-			page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle(),
+			page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle({ signal }),
 		)) as ElementHandle;
 		try {
 			const absolute = filePaths.map(filePath => resolveToCwd(filePath, session.cwd));
@@ -1148,7 +1320,7 @@ export class WorkerCore {
 					const url = (globalThis as unknown as { location: { href: string } }).location.href;
 					return isRe ? new RegExp(m, fl).test(url) : url.includes(m);
 				},
-				{ timeout, polling: 200 },
+				{ timeout, polling: 200, signal },
 				matcher,
 				isRegex,
 				flags,
@@ -1169,7 +1341,7 @@ export class WorkerCore {
 				: pattern instanceof RegExp
 					? response => pattern.test(response.url())
 					: response => response.url().includes(pattern);
-		return (await untilAborted(signal, () => page.waitForResponse(predicate, { timeout }))) as HTTPResponse;
+		return (await untilAborted(signal, () => page.waitForResponse(predicate, { timeout, signal }))) as HTTPResponse;
 	}
 
 	async #resolveCachedHandle(id: number): Promise<ElementHandle> {
@@ -1188,6 +1360,29 @@ export class WorkerCore {
 		}
 		return handle;
 	}
+
+	async #resolveAriaRef(id: string): Promise<ElementHandle> {
+		const ref = parseAriaRefSelector(id) ?? id.trim();
+		const handle = await resolveAriaRefHandle(this.#requirePage(), ref);
+		if (!handle) {
+			throw new ToolError(
+				`Unknown ARIA ref ${JSON.stringify(ref)}. Run tab.ariaSnapshot() to refresh refs (they renumber each snapshot).`,
+			);
+		}
+		return handle;
+	}
+
+	/**
+	 * Resolve a selector to an ElementHandle for handle-based actions. An
+	 * `aria-ref=eN` selector resolves against the latest ariaSnapshot's refs
+	 * (main world); anything else goes through the normal locator wait.
+	 */
+	async #resolveActionHandle(selector: string, timeoutMs: number, sig: AbortSignal): Promise<ElementHandle> {
+		if (parseAriaRefSelector(selector) !== null) return this.#resolveAriaRef(selector);
+		return (await untilAborted(sig, () =>
+			this.#requirePage().locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle({ signal: sig }),
+		)) as ElementHandle;
+	}
 	#clearElementCache(): void {
 		if (this.#elementCache.size === 0) {
 			this.#elementCounter = 0;

package/src/tools/browser.ts

@@ -16,6 +16,11 @@ import { ToolAbortError, ToolError, throwIfAborted } from "./tool-errors";
 import { toolResult } from "./tool-result";
 import { clampTimeout } from "./tool-timeouts";
 
+export {
+	type AriaSnapshotOptions,
+	buildAriaSnapshotScript,
+	parseAriaRefSelector,
+} from "./browser/aria/aria-snapshot";
 export { cmuxSnapshotToObservation, mapWaitUntil, resolveCmuxKind, serializeEval } from "./browser/cmux/rpc";
 export { CmuxSocketClient } from "./browser/cmux/socket-client";
 export { extractReadableFromHtml, type ReadableFormat, type ReadableResult } from "./browser/readable";

package/src/tools/find.ts

@@ -101,8 +101,7 @@ interface FindTarget {
 export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 	readonly name = "find";
 	readonly approval = "read" as const;
-	readonly summary = "Find files and directories matching a glob pattern";
-	readonly loadMode = "discoverable";
+	readonly loadMode = "essential";
 	readonly label = "Find";
 	readonly description: string;
 	readonly parameters = findSchema;

package/src/tools/index.ts

@@ -375,7 +375,7 @@ export type ToolFactory = (session: ToolSession) => Tool | null | Promise<Tool |
 export type BuiltinToolLoadMode = "essential" | "discoverable";
 
 /** Default essential tool names when tools.essentialOverride is empty. */
-export const DEFAULT_ESSENTIAL_TOOL_NAMES: readonly string[] = ["read", "bash", "edit"] as const;
+export const DEFAULT_ESSENTIAL_TOOL_NAMES: readonly string[] = ["read", "bash", "edit", "write", "find"] as const;
 
 /**
  * Resolve the active essential built-in tool names from settings.

package/src/tools/write.ts

@@ -27,6 +27,7 @@ import {
 	readArchiveEntries,
 	writeArchive,
 } from "../utils/zip";
+import { routeWriteThroughBridge } from "./acp-bridge";
 import { truncateForPrompt } from "./approval";
 import { assertEditableFile } from "./auto-generated-guard";
 import {
@@ -143,15 +144,6 @@ function maybeWriteSnapshotHeader(session: ToolSession, absolutePath: string, co
 	return formatHashlineHeader(formatPathRelativeToCwd(absolutePath, session.cwd), tag);
 }
 
-function shouldRouteWriteThroughBridge(session: ToolSession, requestedPath: string, absolutePath: string): boolean {
-	if (isInternalUrlPath(requestedPath)) return false;
-
-	const state = session.getPlanModeState?.();
-	if (!state?.enabled || !isInternalUrlPath(state.planFilePath)) return true;
-
-	return absolutePath !== resolvePlanPath(session, state.planFilePath);
-}
-
 /**
  * Append a trailing note line to the first text block of a tool result.
  * Mutates `result` in place (the result object is owned by this call).
@@ -293,8 +285,7 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 	readonly parameters = writeSchema;
 	readonly strict = true;
 	readonly concurrency = "exclusive";
-	readonly loadMode = "discoverable";
-	readonly summary = "Write content to a file (creates or overwrites)";
+	readonly loadMode = "essential";
 
 	/** Stream matchers should see the real file content, not its JSON-escaped argument encoding. */
 	matcherDigest(args: unknown): string | undefined {
@@ -772,11 +763,6 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 		};
 	}
 
-	#routeWriteThroughBridge(absolutePath: string, content: string): Promise<void> | undefined {
-		const bridge = this.session.getClientBridge?.();
-		if (!bridge?.capabilities.writeTextFile || !bridge.writeTextFile) return undefined;
-		return bridge.writeTextFile({ path: absolutePath, content });
-	}
 	async execute(
 		_toolCallId: string,
 		{ path: rawPath, content }: WriteParams,
@@ -883,17 +869,7 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 
 			// Try ACP bridge first for editor-visible filesystem paths. Internal
 			// artifacts such as local:// plans are owned by OMP, not the editor.
-			const bridgePromise = shouldRouteWriteThroughBridge(this.session, path, absolutePath)
-				? this.#routeWriteThroughBridge(absolutePath, cleanContent)
-				: undefined;
-			if (bridgePromise !== undefined) {
-				try {
-					await bridgePromise;
-				} catch (error) {
-					throw new ToolError(error instanceof Error ? error.message : String(error));
-				}
-				invalidateFsScanAfterWrite(absolutePath);
-				this.session.bumpFileMutationVersion?.(absolutePath);
+			if (await routeWriteThroughBridge(this.session, path, absolutePath, cleanContent)) {
 				const madeExecutable = await maybeMarkExecutableForShebang(absolutePath, cleanContent);
 				const displayPath = formatPathRelativeToCwd(absolutePath, this.session.cwd);
 				const header = maybeWriteSnapshotHeader(this.session, absolutePath, cleanContent);

package/src/utils/git.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { $which, hasFsCode, isEnoent, Snowflake } from "@oh-my-pi/pi-utils";
+import { $which, hasFsCode, isEisdir, isEnoent, isEnotdir, Snowflake } from "@oh-my-pi/pi-utils";
 import {
 	parseDiffHunks as parseCommitDiffHunks,
 	parseFileDiffs,
@@ -376,7 +376,8 @@ async function writeTempPatch(content: string): Promise<string> {
 type EntryType = "directory" | "file";
 
 function shouldRetry(err: unknown, n: number) {
-	if (isEnoent(err) || hasFsCode(err, "ENFILE") || hasFsCode(err, "EMFILE")) return false;
+	if (isEnoent(err) || isEisdir(err) || isEnotdir(err) || hasFsCode(err, "ENFILE") || hasFsCode(err, "EMFILE"))
+		return false;
 	if (hasFsCode(err, "EINTR")) return n < EINTR_MAX_RETRIES;
 	if (n > EINTR_MAX_RETRIES) throw err;
 	throw err;