@prometheus-ai/agent 0.5.4 → 0.5.8

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

@@ -8,7 +8,9 @@ import type {
 	Browser,
 	Dialog,
 	ElementHandle,
+	ElementScreenshotOptions,
 	HTTPResponse,
+	ImageFormat,
 	KeyInput,
 	Page,
 	SerializedAXNode,
@@ -27,7 +29,7 @@ import {
 	DEFAULT_VIEWPORT,
 	loadPuppeteerInWorker,
 } from "./launch";
-import { extractReadableFromHtml, type ReadableFormat, type ReadableResult } from "./readable";
+import { extractReadableFromHtml, type ReadableFormat } from "./readable";
 import type {
 	Observation,
 	ObservationEntry,
@@ -78,6 +80,14 @@ 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)`.
+ */
+const QUICK_OP_TIMEOUT_MS = 20_000;
+
 interface ScreenshotOptions {
 	selector?: string;
 	fullPage?: boolean;
@@ -97,7 +107,7 @@ interface TabApi {
 	): Promise<void>;
 	observe(opts?: { includeAll?: boolean; viewportOnly?: boolean }): Promise<Observation>;
 	screenshot(opts?: ScreenshotOptions): Promise<ScreenshotResult>;
-	extract(format?: ReadableFormat): Promise<ReadableResult | null>;
+	extract(format?: ReadableFormat): Promise<string>;
 	click(selector: string): Promise<void>;
 	type(selector: string, text: string): Promise<void>;
 	fill(selector: string, value: string): Promise<void>;
@@ -167,6 +177,25 @@ function cloneSafe(value: unknown): unknown {
 	return String(value);
 }
 
+/**
+ * Strip `user:pass@` from a URL before surfacing it in tool outputs / details
+ * so Basic Auth credentials don't leak into transcripts. Returns the original
+ * string verbatim when it doesn't parse as a URL or when there are no
+ * credentials to redact.
+ */
+function redactUrlCredentials(url: string): string {
+	if (!url || (!url.includes("@") && !url.includes("//"))) return url;
+	try {
+		const parsed = new URL(url);
+		if (!parsed.username && !parsed.password) return url;
+		parsed.username = "";
+		parsed.password = "";
+		return parsed.toString();
+	} catch {
+		return url;
+	}
+}
+
 function errorPayload(error: unknown): RunErrorPayload {
 	if (error instanceof ToolAbortError) {
 		return { name: error.name, message: error.message, stack: error.stack, isToolError: false, isAbort: true };
@@ -385,12 +414,49 @@ async function clickQueryHandlerText(
 	);
 }
 
+export interface InflightOp {
+	label: string;
+	startedAt: number;
+}
+
 interface ActiveRun {
 	id: string;
 	ac: AbortController;
 	displays: RunResultOk["displays"];
 	screenshots: ScreenshotResult[];
 	pendingTools: Map<string, { resolve(value: unknown): void; reject(error: Error): void }>;
+	/** Helper invocations currently awaiting the page/network, keyed by op id. */
+	inflight: Map<number, InflightOp>;
+	opCounter: number;
+}
+
+/** Human-readable label for a screenshot op, used in op tracking + timeout errors. */
+export function describeScreenshot(opts?: ScreenshotOptions): string {
+	if (opts?.selector) return `tab.screenshot({ selector: ${JSON.stringify(opts.selector)} })`;
+	if (opts?.fullPage) return "tab.screenshot({ fullPage: true })";
+	return "tab.screenshot()";
+}
+
+/** Map an explicit save path's extension to a puppeteer capture format (default png). */
+export function imageFormatForPath(filePath: string): ImageFormat {
+	switch (path.extname(filePath).toLowerCase()) {
+		case ".webp":
+			return "webp";
+		case ".jpg":
+		case ".jpeg":
+			return "jpeg";
+		default:
+			return "png";
+	}
+}
+
+/** Summarize still-running helpers (oldest first) so a cell timeout names what stalled. */
+export function describeInflight(inflight: Map<number, InflightOp>): string {
+	const now = Date.now();
+	return [...inflight.values()]
+		.sort((a, b) => a.startedAt - b.startedAt)
+		.map(op => `${op.label} (${((now - op.startedAt) / 1000).toFixed(1)}s)`)
+		.join(", ");
 }
 
 export class WorkerCore {
@@ -491,7 +557,7 @@ export class WorkerCore {
 		const targetId = this.#targetId ?? (await targetIdForPage(page));
 		this.#targetId = targetId;
 		return {
-			url: page.url(),
+			url: redactUrlCredentials(page.url()),
 			title: await page.title().catch(() => undefined),
 			viewport: page.viewport() ?? DEFAULT_VIEWPORT,
 			targetId,
@@ -541,13 +607,21 @@ export class WorkerCore {
 		const signal = AbortSignal.any([timeoutSignal, ac.signal]);
 		const displays: RunResultOk["displays"] = [];
 		const screenshots: ScreenshotResult[] = [];
-		const active: ActiveRun = { id: msg.id, ac, displays, screenshots, pendingTools: new Map() };
+		const active: ActiveRun = {
+			id: msg.id,
+			ac,
+			displays,
+			screenshots,
+			pendingTools: new Map(),
+			inflight: new Map(),
+			opCounter: 0,
+		};
 		this.#active = active;
 		try {
 			throwIfAborted(signal);
 			const page = this.#requirePage();
 			const browser = this.#requireBrowser();
-			const tabApi = this.#createTabApi(msg.name, msg.timeoutMs, signal, msg.session, displays, screenshots);
+			const tabApi = this.#createTabApi(msg.name, msg.timeoutMs, signal, msg.session, displays, screenshots, active);
 			const runtime = this.#ensureRuntime(msg.session);
 			runtime.setCwd(msg.session.cwd);
 			runtime.setRunScope({
@@ -561,11 +635,16 @@ export class WorkerCore {
 			});
 			const { promise: cancelRejection, reject: rejectCancel } = Promise.withResolvers<never>();
 			const onCancel = (): void => {
-				rejectCancel(
-					timeoutSignal.aborted
-						? new ToolError(`Browser code execution timed out after ${msg.timeoutMs}ms`)
-						: new ToolAbortError(),
-				);
+				if (timeoutSignal.aborted) {
+					const stalled = describeInflight(active.inflight);
+					rejectCancel(
+						new ToolError(
+							`Browser code execution timed out after ${msg.timeoutMs}ms${stalled ? ` (stalled on ${stalled})` : ""}`,
+						),
+					);
+				} else {
+					rejectCancel(new ToolAbortError());
+				}
 				// Cancel in-flight tool calls so user code's awaited proxies reject promptly.
 				for (const pending of active.pendingTools.values()) {
 					pending.reject(new ToolAbortError());
@@ -651,6 +730,39 @@ export class WorkerCore {
 		else pending.reject(replyError(reply.error));
 	}
 
+	/**
+	 * Wrap a tab helper so it (a) registers in the active run's in-flight map for
+	 * timeout diagnostics and (b) honors an optional per-op deadline that fails fast
+	 * with a named error instead of silently consuming the whole cell budget. Pass
+	 * `Number.POSITIVE_INFINITY` for `perOpTimeoutMs` to bound the op only by the cell
+	 * budget (used for `evaluate` running user code and for locator helpers that already
+	 * carry puppeteer's own `.setTimeout(timeoutMs)`).
+	 */
+	async #runOp<T>(
+		active: ActiveRun,
+		label: string,
+		cellSignal: AbortSignal,
+		perOpTimeoutMs: number,
+		fn: (signal: AbortSignal) => Promise<T>,
+	): Promise<T> {
+		const opId = active.opCounter++;
+		active.inflight.set(opId, { label, startedAt: Date.now() });
+		const capped = Number.isFinite(perOpTimeoutMs) && perOpTimeoutMs > 0;
+		const opTimeout = capped ? AbortSignal.timeout(perOpTimeoutMs) : undefined;
+		const opSignal = opTimeout ? AbortSignal.any([cellSignal, opTimeout]) : cellSignal;
+		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) {
+				throw new ToolError(`${label} timed out after ${perOpTimeoutMs}ms`);
+			}
+			throw err;
+		} finally {
+			active.inflight.delete(opId);
+		}
+	}
+
 	#createTabApi(
 		name: string,
 		timeoutMs: number,
@@ -658,88 +770,125 @@ export class WorkerCore {
 		session: SessionSnapshot,
 		displays: RunResultOk["displays"],
 		screenshots: ScreenshotResult[],
+		active: ActiveRun,
 	): TabApi {
 		const page = this.#requirePage();
+		const quickOpMs = Math.min(timeoutMs, QUICK_OP_TIMEOUT_MS);
+		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);
 		return {
 			name,
 			page,
 			signal,
 			url: () => page.url(),
-			title: () => page.title(),
-			goto: async (url, opts) => {
-				this.#clearElementCache();
-				await untilAborted(signal, () =>
+			title: () => op("tab.title()", INF, sig => untilAborted(sig, () => page.title())),
+			goto: (url, opts) =>
+				op(`tab.goto(${JSON.stringify(url)})`, INF, async sig => {
+					this.#clearElementCache();
 					// Default to "load" because dev servers with HMR/WS never reach networkidle.
-					page.goto(url, { waitUntil: opts?.waitUntil ?? "load", timeout: timeoutMs }),
-				);
-			},
-			observe: opts => this.#collectObservation({ ...opts, signal }),
-			screenshot: async opts => await this.#captureScreenshot(session, displays, screenshots, signal, opts),
-			extract: async (format = "markdown") => {
-				const html = (await untilAborted(signal, () => page.content())) as string;
-				return extractReadableFromHtml(html, page.url(), format);
-			},
-			click: async selector => {
-				const resolved = normalizeSelector(selector);
-				if (resolved.startsWith("text/")) await clickQueryHandlerText(page, resolved, timeoutMs, signal);
-				else await untilAborted(signal, () => page.locator(resolved).setTimeout(timeoutMs).click());
-			},
-			type: async (selector, text) => {
-				const handle = (await untilAborted(signal, () =>
-					page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle(),
-				)) as ElementHandle;
-				try {
-					await untilAborted(signal, () => handle.type(text, { delay: 0 }));
-				} finally {
-					await handle.dispose();
-				}
-			},
-			fill: async (selector, value) => {
-				await untilAborted(signal, () =>
-					page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).fill(value),
-				);
-			},
-			press: async (key, opts) => {
-				const selector = opts?.selector;
-				if (selector) await untilAborted(signal, () => page.focus(normalizeSelector(selector)));
-				await untilAborted(signal, () => page.keyboard.press(key));
-			},
-			scroll: async (deltaX, deltaY) => {
-				await untilAborted(signal, () => page.mouse.wheel({ deltaX, deltaY }));
-			},
-			drag: async (from, to) => await this.#drag(from, to, signal),
-			waitFor: async selector =>
-				(await untilAborted(signal, () =>
-					page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle(),
-				)) as ElementHandle,
-			evaluate: async (fn, ...args) =>
-				(await untilAborted(signal, () =>
-					typeof fn === "string" ? page.evaluate(fn) : page.evaluate(fn as (...a: unknown[]) => unknown, ...args),
-				)) as never,
-			scrollIntoView: async selector => {
-				const handle = (await untilAborted(signal, () =>
-					page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).waitHandle(),
-				)) as ElementHandle;
-				try {
-					await untilAborted(signal, () =>
-						handle.evaluate(el => {
-							const target = el as unknown as {
-								scrollIntoView: (opts: { behavior: string; block: string; inline: string }) => void;
-							};
-							target.scrollIntoView({ behavior: "instant", block: "center", inline: "center" });
-						}),
+					await untilAborted(sig, () =>
+						page.goto(url, { waitUntil: opts?.waitUntil ?? "load", timeout: timeoutMs }),
 					);
-				} finally {
-					await handle.dispose().catch(() => undefined);
-				}
-			},
-			select: async (selector, ...values) => await this.#select(selector, values, timeoutMs, signal),
-			uploadFile: async (selector, ...filePaths) =>
-				await this.#uploadFile(selector, filePaths, timeoutMs, signal, session),
-			waitForUrl: async (pattern, opts) => await this.#waitForUrl(pattern, opts?.timeout ?? timeoutMs, signal),
-			waitForResponse: async (pattern, opts) =>
-				await this.#waitForResponse(pattern, opts?.timeout ?? timeoutMs, signal),
-			id: async id => await this.#resolveCachedHandle(id),
+				}),
+			observe: opts => op("tab.observe()", quickOpMs, sig => this.#collectObservation({ ...opts, signal: sig })),
+			screenshot: opts =>
+				op(describeScreenshot(opts), quickOpMs, sig =>
+					this.#captureScreenshot(session, displays, screenshots, sig, opts),
+				),
+			extract: (format = "markdown") =>
+				op(`tab.extract(${JSON.stringify(format)})`, quickOpMs, async sig => {
+					const html = (await untilAborted(sig, () => page.content())) as string;
+					const result = await extractReadableFromHtml(html, page.url(), format);
+					if (!result) {
+						throw new ToolError(
+							`tab.extract(${JSON.stringify(format)}) found no readable content on ${page.url()}`,
+						);
+					}
+					const content = format === "markdown" ? result.markdown : result.text;
+					if (!content) {
+						throw new ToolError(
+							`tab.extract(${JSON.stringify(format)}) produced empty ${format} content for ${page.url()}`,
+						);
+					}
+					return content;
+				}),
+			click: selector =>
+				op(`tab.click(${JSON.stringify(selector)})`, INF, async sig => {
+					const resolved = normalizeSelector(selector);
+					if (resolved.startsWith("text/")) await clickQueryHandlerText(page, resolved, timeoutMs, sig);
+					else await untilAborted(sig, () => page.locator(resolved).setTimeout(timeoutMs).click());
+				}),
+			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;
+					try {
+						await untilAborted(sig, () => handle.type(text, { delay: 0 }));
+					} finally {
+						await handle.dispose();
+					}
+				}),
+			fill: (selector, value) =>
+				op(`tab.fill(${JSON.stringify(selector)})`, INF, sig =>
+					untilAborted(sig, () => page.locator(normalizeSelector(selector)).setTimeout(timeoutMs).fill(value)),
+				),
+			press: (key, opts) =>
+				op(`tab.press(${JSON.stringify(key)})`, INF, 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,
+				),
+			evaluate: (fn, ...args) =>
+				op("tab.evaluate()", INF, sig =>
+					untilAborted(sig, () =>
+						typeof fn === "string"
+							? page.evaluate(fn)
+							: page.evaluate(fn as (...a: unknown[]) => unknown, ...args),
+					),
+				) 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;
+					try {
+						await untilAborted(sig, () =>
+							handle.evaluate(el => {
+								const target = el as unknown as {
+									scrollIntoView: (opts: { behavior: string; block: string; inline: string }) => void;
+								};
+								target.scrollIntoView({ behavior: "instant", block: "center", inline: "center" });
+							}),
+						);
+					} finally {
+						await handle.dispose().catch(() => undefined);
+					}
+				}),
+			select: (selector, ...values) =>
+				op(`tab.select(${JSON.stringify(selector)})`, INF, sig => this.#select(selector, values, timeoutMs, sig)),
+			uploadFile: (selector, ...filePaths) =>
+				op(`tab.uploadFile(${JSON.stringify(selector)})`, INF, sig =>
+					this.#uploadFile(selector, filePaths, timeoutMs, 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)),
+			id: id => this.#resolveCachedHandle(id),
 		};
 	}
 
@@ -796,6 +945,12 @@ export class WorkerCore {
 	): Promise<ScreenshotResult> {
 		const page = this.#requirePage();
 		const fullPage = opts.selector ? false : (opts.fullPage ?? false);
+		// An explicit save path picks the full-res capture format: puppeteer encodes
+		// png/jpeg/webp natively, so `save: "shot.webp"` gets real WebP bytes instead
+		// of PNG bytes hiding behind a .webp name. Unknown/missing extensions stay PNG.
+		const explicitPath = opts.save ? resolveToCwd(opts.save, session.cwd) : undefined;
+		const captureType = explicitPath ? imageFormatForPath(explicitPath) : "png";
+		const captureMime = `image/${captureType}` as const;
 		let buffer: Buffer;
 		if (opts.selector) {
 			const handle = (await untilAborted(signal, () =>
@@ -803,23 +958,36 @@ export class WorkerCore {
 			)) as ElementHandle | null;
 			if (!handle) throw new ToolError("Screenshot selector did not resolve to an element");
 			try {
-				buffer = (await untilAborted(signal, () => handle.screenshot({ type: "png" }))) as Buffer;
+				// Bring the element into view with a single instant scroll instead of puppeteer's
+				// scrollIntoViewIfNeeded(), whose IntersectionObserver promise can stall indefinitely
+				// on continuously-animating pages (WebGL / backdrop-filter "glass" effects). Best-effort.
+				await untilAborted(signal, () =>
+					handle.evaluate(el => {
+						const target = el as unknown as {
+							scrollIntoView: (opts: { behavior: string; block: string; inline: string }) => void;
+						};
+						target.scrollIntoView({ behavior: "instant", block: "center", inline: "center" });
+					}),
+				).catch(() => undefined);
+				// scrollIntoView:false skips the same IntersectionObserver check inside screenshot();
+				// captureBeyondViewport (puppeteer's default) still renders the clipped region.
+				const shotOpts: ElementScreenshotOptions = { type: captureType, scrollIntoView: false };
+				buffer = (await untilAborted(signal, () => handle.screenshot(shotOpts))) as Buffer;
 			} finally {
 				await handle.dispose().catch(() => undefined);
 			}
 		} else {
-			buffer = (await untilAborted(signal, () => page.screenshot({ type: "png", fullPage }))) as Buffer;
+			buffer = (await untilAborted(signal, () => page.screenshot({ type: captureType, fullPage }))) as Buffer;
 		}
 		const resized = await resizeImage(
-			{ type: "image", data: buffer.toBase64(), mimeType: "image/png" },
-			{ maxWidth: 1024, maxHeight: 1024, maxBytes: 150 * 1024, jpegQuality: 70 },
+			{ type: "image", data: buffer.toBase64(), mimeType: captureMime },
+			{ maxWidth: 1024, maxHeight: 1024, maxBytes: 150 * 1024, jpegQuality: 70, excludeWebP: session.excludeWebP },
 		);
-		const explicitPath = opts.save ? resolveToCwd(opts.save, session.cwd) : undefined;
 		const saveFullRes = !!(explicitPath || session.browserScreenshotDir);
 		const savedBuffer = saveFullRes ? buffer : resized.buffer;
-		const savedMimeType = saveFullRes ? "image/png" : resized.mimeType;
-		// Auto-generated names must match the bytes we actually write: full-res is always
-		// PNG, but the resized buffer is whichever of PNG/JPEG/WebP encoded smallest.
+		const savedMimeType = saveFullRes ? captureMime : resized.mimeType;
+		// Names must match the bytes we actually write: full-res follows the capture
+		// format, the resized buffer is whichever of PNG/JPEG/WebP encoded smallest.
 		const ext = savedMimeType === "image/webp" ? "webp" : savedMimeType === "image/jpeg" ? "jpg" : "png";
 		const dest =
 			explicitPath ??

package/src/tools/browser.ts

@@ -1,9 +1,11 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@prometheus-ai/agent-core";
 import { prompt, untilAborted } from "@prometheus-ai/utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import browserDescription from "../prompts/tools/browser.md" with { type: "text" };
 import type { ToolSession } from "../sdk";
+import { enforceInlineByteCap } from "../session/streaming-output";
 import { truncateForPrompt } from "./approval";
+import { resolveCmuxKind } from "./browser/cmux/rpc";
 import { acquireBrowser, type BrowserHandle, type BrowserKind, type BrowserKindTag } from "./browser/registry";
 import type { Observation, ScreenshotResult } from "./browser/tab-protocol";
 import { acquireTab, dropHeadlessTabs, getTab, releaseAllTabs, releaseTab, runInTab } from "./browser/tab-supervisor";
@@ -13,6 +15,8 @@ import { ToolAbortError, ToolError, throwIfAborted } from "./tool-errors";
 import { toolResult } from "./tool-result";
 import { clampTimeout } from "./tool-timeouts";
 
+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";
 export type { Observation, ObservationEntry } from "./browser/tab-protocol";
 
@@ -76,6 +80,12 @@ function resolveBrowserKind(params: BrowserParams, session: ToolSession): Browse
 		const exe = resolveToCwd(app.path, session.cwd);
 		return { kind: "spawned", path: exe };
 	}
+	const cmuxKind = resolveCmuxKind({
+		settingEnabled: session.settings.get("browser.cmux") as boolean | undefined,
+	});
+	if (cmuxKind) {
+		return cmuxKind;
+	}
 	const headless = session.settings.get("browser.headless") as boolean;
 	return { kind: "headless", headless };
 }
@@ -271,12 +281,41 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 			.filter((c): c is { type: "text"; text: string } => c.type === "text")
 			.map(c => c.text)
 			.join("\n");
-		details.result = textOnly;
+		// Final defense at the tool-result boundary: a single run can display
+		// tens of KB (large JSON returns, dumped observations). Cap the combined
+		// text inline; the full text stays recoverable via the artifact footer
+		// when allocation succeeds.
+		const cappedText = await enforceInlineByteCap(textOnly, {
+			label: "browser output",
+			saveArtifact: full => saveBrowserOutputArtifact(this.session, full),
+		});
+		details.result = cappedText;
+		if (cappedText !== textOnly) {
+			const nonText = content.filter(c => c.type !== "text");
+			return toolResult(details)
+				.content([...nonText, { type: "text", text: cappedText }])
+				.done();
+		}
 		return toolResult(details).content(content).done();
 	}
 }
 
+/** Persist over-cap browser run output as a session artifact; mirrors the bash minimizer's save path. */
+async function saveBrowserOutputArtifact(session: ToolSession, fullText: string): Promise<string | undefined> {
+	try {
+		const alloc = await session.allocateOutputArtifact?.("browser-original");
+		if (!alloc?.path || !alloc.id) return undefined;
+		await Bun.write(alloc.path, fullText);
+		return alloc.id;
+	} catch {
+		return undefined;
+	}
+}
+
 function describeBrowser(handle: BrowserHandle): string {
+	if (!("browser" in handle)) {
+		return `cmux browser (${handle.kind.surface ?? "split"})`;
+	}
 	switch (handle.kind.kind) {
 		case "headless":
 			return `headless browser (${handle.kind.headless ? "hidden" : "visible"})`;
@@ -295,6 +334,8 @@ function describeKind(kind: BrowserKind): string {
 			return `spawned:${kind.path}`;
 		case "connected":
 			return `connected:${kind.cdpUrl}`;
+		case "cmux":
+			return `cmux:${kind.surface ?? "split"}`;
 	}
 }
 
@@ -303,6 +344,7 @@ function sameBrowserKind(a: BrowserKind, b: BrowserKind): boolean {
 	if (a.kind === "headless" && b.kind === "headless") return a.headless === b.headless;
 	if (a.kind === "spawned" && b.kind === "spawned") return a.path === b.path;
 	if (a.kind === "connected" && b.kind === "connected") return a.cdpUrl === b.cdpUrl;
+	if (a.kind === "cmux" && b.kind === "cmux") return a.socketPath === b.socketPath;
 	return false;
 }
 

package/src/tools/checkpoint.ts

@@ -1,6 +1,6 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@prometheus-ai/agent-core";
 import { prompt } from "@prometheus-ai/utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import checkpointDescription from "../prompts/tools/checkpoint.md" with { type: "text" };
 import rewindDescription from "../prompts/tools/rewind.md" with { type: "text" };
 import type { ToolSession } from ".";

package/src/tools/conflict-detect.ts

@@ -68,7 +68,9 @@ export function scanConflictLines(lines: readonly string[], firstLineNumber: num
 	} | null = null;
 
 	for (let i = 0; i < lines.length; i++) {
-		const line = lines[i];
+		// Strip a trailing \r so CRLF checkouts match the same markers; stored
+		// section lines are LF-normalized (splice re-applies \r on write).
+		const line = stripTrailingCr(lines[i]);
 		const ln = firstLineNumber + i;
 
 		const oursLabel = matchMarker(line, OURS_PREFIX);
@@ -338,13 +340,22 @@ export function spliceConflict(originalText: string, entry: ConflictEntry, repla
 	}
 
 	const trimmed = normalizeTrailingNewline(replacement);
-	const replacementLines = trimmed.split("\n");
+	let replacementLines = trimmed.split("\n").map(stripTrailingCr);
+	// Round-trip fidelity for CRLF files: recorded sections are LF-normalized,
+	// so re-apply \r to spliced lines when the matched region used CRLF. The
+	// final replacement line only carries \r when another line follows it.
+	if (lines[match.startIdx]!.endsWith("\r")) {
+		const hasFollowingLine = match.endIdx + 1 < lines.length;
+		replacementLines = replacementLines.map((l, i) =>
+			i < replacementLines.length - 1 || hasFollowingLine ? `${l}\r` : l,
+		);
+	}
 	const next = [...lines.slice(0, match.startIdx), ...replacementLines, ...lines.slice(match.endIdx + 1)];
 	return next.join("\n");
 }
 
 /** Reconstruct the recorded marker block as it should appear in the file. */
-function buildRecordedRegion(entry: ConflictEntry): string[] {
+function buildRecordedRegion(entry: ConflictBlock): string[] {
 	const out: string[] = [];
 	out.push(entry.oursLabel ? `${OURS_PREFIX} ${entry.oursLabel}` : OURS_PREFIX);
 	out.push(...entry.oursLines);
@@ -358,6 +369,36 @@ function buildRecordedRegion(entry: ConflictEntry): string[] {
 	return out;
 }
 
+/**
+ * True when two registered blocks record the same marker-block content
+ * (labels and all sides). Out-of-band edits can shift a block's line
+ * numbers between reads, registering a fresh id while the stale one
+ * persists; callers use content identity to treat a locate-miss for the
+ * stale twin as "already resolved" instead of a hard failure.
+ */
+export function conflictRegionsEqual(a: ConflictBlock, b: ConflictBlock): boolean {
+	const ra = buildRecordedRegion(a);
+	const rb = buildRecordedRegion(b);
+	if (ra.length !== rb.length) return false;
+	for (let i = 0; i < ra.length; i++) {
+		if (ra[i] !== rb[i]) return false;
+	}
+	return true;
+}
+
+/**
+ * True when the entry's recorded marker block still occurs in `content`
+ * (LF-normalized — recorded sections are stored LF). Distinguishes a stale
+ * re-registration of a just-resolved region (no longer present) from a
+ * DISTINCT conflict block that happens to be byte-identical (still present
+ * elsewhere in the file and must stay addressable).
+ */
+export function conflictRegionPresent(content: string, entry: ConflictBlock): boolean {
+	const region = buildRecordedRegion(entry).join("\n");
+	const normalized = content.includes("\r") ? content.replace(/\r\n/g, "\n") : content;
+	return normalized.includes(region);
+}
+
 /**
  * Find a contiguous match of `expected` inside `lines`, preferring the
  * occurrence closest to `preferredIdx` to disambiguate when an identical
@@ -391,11 +432,16 @@ function locateRegion(
 function matchesAt(lines: readonly string[], startIdx: number, expected: readonly string[]): boolean {
 	if (startIdx < 0 || startIdx + expected.length > lines.length) return false;
 	for (let i = 0; i < expected.length; i++) {
-		if (lines[startIdx + i] !== expected[i]) return false;
+		// Recorded lines are LF-normalized; tolerate CRLF on-disk lines.
+		if (stripTrailingCr(lines[startIdx + i]!) !== expected[i]) return false;
 	}
 	return true;
 }
 
+function stripTrailingCr(line: string): string {
+	return line.endsWith("\r") ? line.slice(0, -1) : line;
+}
+
 function normalizeTrailingNewline(replacement: string): string {
 	if (replacement.endsWith("\r\n")) return replacement.slice(0, -2);
 	if (replacement.endsWith("\n")) return replacement.slice(0, -1);