jeopi-cli 16.4.2 → 16.4.3

package/src/task/executor.ts

@@ -2038,14 +2038,22 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				thinkingLevel: resolvedThinkingLevel,
 				explicitThinkingLevel,
 				authFallbackUsed,
+				warning: modelResolutionWarning,
 			} = await awaitAbortable(
 				resolveModelOverrideWithAuthFallback(
 					modelPatterns,
 					options.parentActiveModelPattern,
 					modelRegistry,
 					settings,
+					id,
 				),
 			);
+			if (modelResolutionWarning) {
+				logger.warn("Subagent model resolution warning", {
+					warning: modelResolutionWarning,
+					requested: modelPatterns,
+				});
+			}
 			if (authFallbackUsed && model) {
 				logger.warn("Subagent model has no working credentials; falling back to parent session model", {
 					requested: modelPatterns,

package/src/tools/bash-skill-urls.ts

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import type { Skill } from "../extensibility/skills";
 import { type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
 import { validateRelativePath } from "../internal-urls/skill-protocol";
-import type { InternalResource } from "../internal-urls/types";
+import type { InternalResource, ResolveContext } from "../internal-urls/types";
 import { normalizeLocalScheme } from "./path-utils";
 import { ToolError } from "./tool-errors";
 
@@ -19,7 +19,7 @@ type SupportedInternalScheme = (typeof SUPPORTED_INTERNAL_SCHEMES)[number];
 
 interface InternalUrlResolver {
 	canHandle(input: string): boolean;
-	resolve(input: string): Promise<InternalResource>;
+	resolve(input: string, context?: ResolveContext): Promise<InternalResource>;
 }
 
 export interface InternalUrlExpansionOptions {
@@ -27,6 +27,7 @@ export interface InternalUrlExpansionOptions {
 	noEscape?: boolean;
 	internalRouter?: InternalUrlResolver;
 	localOptions?: LocalProtocolOptions;
+	cwd?: string;
 	ensureLocalParentDirs?: boolean;
 }
 
@@ -66,7 +67,7 @@ export function resolveSkillUrlToPath(url: string, skills: readonly Skill[]): st
 	const hasRelativePath = rawPath !== "" && rawPath !== "/";
 
 	if (!hasRelativePath) {
-		return path.resolve(skill.filePath);
+		return path.resolve(skill.baseDir);
 	}
 
 	let relativePath: string;
@@ -151,6 +152,7 @@ async function resolveInternalUrlToPath(
 	internalRouter?: InternalUrlResolver,
 	localOptions?: LocalProtocolOptions,
 	ensureLocalParentDirs?: boolean,
+	cwd?: string,
 ): Promise<string> {
 	const url = normalizeLocalScheme(rawUrl);
 	const scheme = extractScheme(url);
@@ -184,7 +186,7 @@ async function resolveInternalUrlToPath(
 
 	let resource: InternalResource;
 	try {
-		resource = await internalRouter.resolve(url);
+		resource = await internalRouter.resolve(url, { cwd });
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		throw new ToolError(`Failed to resolve ${scheme}:// URL in bash command: ${url}\n${message}`);
@@ -239,6 +241,7 @@ export async function expandInternalUrls(command: string, options: InternalUrlEx
 			options.internalRouter,
 			options.localOptions,
 			options.ensureLocalParentDirs,
+			options.cwd,
 		);
 		const replacement = options.noEscape ? resolvedPath : shellEscape(resolvedPath);
 		expanded = `${expanded.slice(0, index)}${replacement}${expanded.slice(index + token.length)}`;

package/src/tools/bash.ts

@@ -163,10 +163,9 @@ type ManagedBashJobCompletion =
 
 interface ManagedBashJobHandle {
 	jobId: string;
-	label: string;
 	completion: Promise<ManagedBashJobCompletion>;
 	getLatestText: () => string;
-	setBackgrounded: (backgrounded: boolean) => void;
+	stopUpdates: () => void;
 }
 
 function normalizeResultOutput(result: BashResult | BashInteractiveResult): string {
@@ -297,6 +296,10 @@ function formatExitCodeNotice(exitCode: number): string {
 	return `Command exited with code ${exitCode}`;
 }
 
+function formatBackgroundNotice(jobId: string): string {
+	return `Backgrounded as job ${jobId}; result will be delivered automatically.`;
+}
+
 /**
  * Strip the trailing occurrence of `notice` (plus a single surrounding newline
  * on each side) so the TUI can echo the value via a styled footer label
@@ -325,6 +328,11 @@ function stripExitCodeNotice(text: string, exitCode: number | undefined): string
 	return stripTrailingNotice(text, formatExitCodeNotice(exitCode));
 }
 
+function stripBackgroundNotice(text: string, async: BashToolDetails["async"] | undefined): string {
+	if (async?.state !== "running") return text;
+	return stripTrailingNotice(text, formatBackgroundNotice(async.jobId));
+}
+
 /**
  * Bash tool implementation.
  *
@@ -473,7 +481,6 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 
 	#buildBackgroundStartResult(
 		jobId: string,
-		label: string,
 		previewText: string,
 		timeoutSec: number,
 		options: { requestedTimeoutSec?: number; notices?: readonly string[] } = {},
@@ -493,11 +500,7 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		if (options.notices?.length) {
 			lines.push(...options.notices, "");
 		}
-		lines.push(`Background job ${jobId} started: ${label}`);
-		lines.push("Result will be delivered automatically when complete.");
-		lines.push(
-			`You can use \`job\` to poll until complete, but prefer to continue with another task in the meanwhile if it's not blocking.`,
-		);
+		lines.push(formatBackgroundNotice(jobId));
 		return {
 			content: [{ type: "text", text: lines.join("\n") }],
 			details,
@@ -518,7 +521,7 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 
 		resolvedEnv?: Record<string, string>;
 		onUpdate?: AgentToolUpdateCallback<BashToolDetails>;
-		startBackgrounded: boolean;
+		forwardUpdates: boolean;
 	}): ManagedBashJobHandle {
 		const manager = this.session.asyncJobManager;
 		if (!manager) {
@@ -527,7 +530,7 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 
 		const label = options.command.length > 120 ? `${options.command.slice(0, 117)}...` : options.command;
 		let latestText = "";
-		let backgrounded = options.startBackgrounded;
+		let forwardUpdates = options.forwardUpdates;
 		const completion = Promise.withResolvers<ManagedBashJobCompletion>();
 
 		const jobId = manager.register(
@@ -583,11 +586,12 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 			},
 			{
 				ownerId: this.session.getAgentId?.() ?? undefined,
-				onProgress: async (text, details) => {
+				onProgress: async text => {
 					latestText = text;
+					if (!forwardUpdates) return;
 					await options.onUpdate?.({
 						content: [{ type: "text", text }],
-						details: backgrounded ? ((details ?? {}) as BashToolDetails) : {},
+						details: {},
 					});
 				},
 			},
@@ -595,11 +599,10 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 
 		return {
 			jobId,
-			label,
 			completion: completion.promise,
 			getLatestText: () => latestText,
-			setBackgrounded: (nextBackgrounded: boolean) => {
-				backgrounded = nextBackgrounded;
+			stopUpdates: () => {
+				forwardUpdates = false;
 			},
 		};
 	}
@@ -701,6 +704,7 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		const internalUrlOptions: InternalUrlExpansionOptions = {
 			skills: this.session.skills ?? [],
 			internalRouter: InternalUrlRouter.instance(),
+			cwd: this.session.cwd,
 			localOptions: {
 				getArtifactsDir: this.session.getArtifactsDir,
 				getSessionId: this.session.getSessionId,
@@ -769,9 +773,9 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 
 				resolvedEnv,
 				onUpdate,
-				startBackgrounded: true,
+				forwardUpdates: false,
 			});
-			return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec, {
+			return this.#buildBackgroundStartResult(job.jobId, "", timeoutSec, {
 				requestedTimeoutSec,
 				notices: pendingNotices,
 			});
@@ -807,10 +811,10 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 
 				resolvedEnv,
 				onUpdate,
-				startBackgrounded,
+				forwardUpdates: !startBackgrounded,
 			});
 			if (startBackgrounded) {
-				return this.#buildBackgroundStartResult(job.jobId, job.label, "", timeoutSec, {
+				return this.#buildBackgroundStartResult(job.jobId, "", timeoutSec, {
 					requestedTimeoutSec,
 					notices: pendingNotices,
 				});
@@ -830,9 +834,9 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 				autoBgManager.cancel(job.jobId);
 				throw new ToolAbortError(job.getLatestText() || "Command aborted");
 			}
-			job.setBackgrounded(true);
+			job.stopUpdates();
 			autoBgManager.resumeDeliveries([job.jobId]);
-			return this.#buildBackgroundStartResult(job.jobId, job.label, job.getLatestText(), timeoutSec, {
+			return this.#buildBackgroundStartResult(job.jobId, job.getLatestText(), timeoutSec, {
 				requestedTimeoutSec,
 				notices: pendingNotices,
 			});
@@ -1249,7 +1253,8 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 					) {
 						return cachedLines;
 					}
-					const strippedOutput = stripOutputNotice(rawOutput, details?.meta);
+					const withoutBackground = stripBackgroundNotice(rawOutput, details?.async);
+					const strippedOutput = stripOutputNotice(withoutBackground, details?.meta);
 					const withoutExit = stripExitCodeNotice(strippedOutput, details?.exitCode);
 					const withoutWall = stripWallTimeNotice(withoutExit, details?.wallTimeMs);
 					const rawOutputArtifact = stripRawOutputArtifactNotice(withoutWall);
@@ -1262,6 +1267,9 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 					const requestedTimeoutSeconds = details?.requestedTimeoutSeconds;
 					const wallTimeMs = details?.wallTimeMs;
 					const statsParts: string[] = [];
+					if (details?.async?.state === "running") {
+						statsParts.push(`Backgrounded: ${details.async.jobId}`);
+					}
 					if (wallTimeMs !== undefined) {
 						statsParts.push(`Wall: ${formatWallTimeSeconds(wallTimeMs)}s`);
 					}

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

@@ -3,7 +3,6 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { logger, Snowflake, untilAborted } from "jeopi-utils";
 import { JsRuntime, type RuntimeHooks } from "../../../eval/js/shared/runtime";
-import type { JsDisplayOutput } from "../../../eval/js/shared/types";
 import { callSessionTool } from "../../../eval/js/tool-bridge";
 import { resizeImage } from "../../../utils/image-resize";
 import type { ToolSession } from "../../index";
@@ -13,7 +12,8 @@ import { ToolAbortError, ToolError, throwIfAborted } from "../../tool-errors";
 import { type AriaSnapshotOptions, buildAriaSnapshotScript } from "../aria/aria-snapshot";
 import { DEFAULT_VIEWPORT } from "../launch";
 import { extractReadableFromHtml, type ReadableFormat } from "../readable";
-import { bindBrowserRunFacade, waitForBrowserRun } from "../run-cancellation";
+import { bindBrowserRunFacade, type WaitPredicateOptions, waitForBrowserRun } from "../run-cancellation";
+import { cloneSafe, RunOutput } from "../run-output";
 import type { Observation, ReadyInfo, RunResultOk, ScreenshotResult, SessionSnapshot } from "../tab-protocol";
 import {
 	type CmuxEvalResult,
@@ -24,7 +24,8 @@ import {
 	cmuxSnapshotToObservation,
 	GEOMETRY_SCRIPT,
 	mapWaitUntil,
-	serializeEval,
+	serializeEvalWithEnvelope,
+	unwrapEvalEnvelope,
 } from "./rpc";
 import type { CmuxSocketClient } from "./socket-client";
 
@@ -43,7 +44,7 @@ interface ObserveOptions {
 
 interface RunContext {
 	session: SessionSnapshot;
-	displays: RunResultOk["displays"];
+	output: RunOutput;
 	screenshots: ScreenshotResult[];
 	signal: AbortSignal;
 	timeoutMs: number;
@@ -445,10 +446,14 @@ export class CmuxTab {
 		fn: string | ((...args: TArgs) => TResult | Promise<TResult>),
 		...args: TArgs
 	): Promise<TResult> {
-		const result = (await this.#request("browser.eval", {
-			script: serializeEval(fn as string | ((...args: unknown[]) => unknown), args),
-		})) as CmuxEvalResult;
-		return result.value as TResult;
+		// A script that throws inside the daemon comes back as a bare
+		// `js_error: A JavaScript exception occurred` with no message or stack.
+		// Catch page-side instead so the exception is diagnosable, and turn the
+		// daemon's other blind spot — Promise return values it cannot
+		// serialize — into an actionable error instead of "unsupported type".
+		const script = serializeEvalWithEnvelope(fn as string | ((...args: unknown[]) => unknown), args);
+		const result = (await this.#request("browser.eval", { script })) as CmuxEvalResult;
+		return unwrapEvalEnvelope<TResult>(result.value, "tab.evaluate()");
 	}
 
 	async scrollIntoView(selector: string): Promise<void> {
@@ -479,10 +484,22 @@ export class CmuxTab {
 
 	async screenshot(opts: ScreenshotOptions = {}): Promise<ScreenshotResult> {
 		const context = this.#requireRunContext("tab.screenshot()");
+		// The cmux daemon's `browser.screenshot` captures the surface viewport
+		// only — it has no element-clip or full-page mode, and Bun.Image cannot
+		// crop locally. Degrade transparently instead of silently mislabeling
+		// the capture: scroll the element into view, then TELL the model the
+		// image is the full viewport (reports showed selector captures being
+		// consumed as element crops).
+		const captureNotes: string[] = [];
 		if (opts.selector) {
 			await this.scrollIntoView(opts.selector);
+			captureNotes.push(
+				`selector ${JSON.stringify(opts.selector)} was scrolled into view, but this surface cannot clip to an element — the image is the full viewport`,
+			);
+		}
+		if (opts.fullPage) {
+			captureNotes.push("fullPage is unavailable on this surface — the image is the viewport only");
 		}
-		void opts.fullPage;
 		const result = await this.#captureScreenshotPng(context.timeoutMs);
 		const buffer = Buffer.from(result.png_base64, "base64");
 		const captureMime = "image/png";
@@ -528,8 +545,11 @@ export class CmuxTab {
 				dest,
 				resized,
 			});
-			context.displays.push({ type: "text", text: lines.join("\n") });
-			context.displays.push({ type: "image", data: resized.data, mimeType: resized.mimeType });
+			if (captureNotes.length > 0) {
+				lines.push(`[cmux surface: ${captureNotes.join("; ")}]`);
+			}
+			context.output.push({ type: "text", text: lines.join("\n") });
+			context.output.push({ type: "image", data: resized.data, mimeType: resized.mimeType });
 		}
 		return info;
 	}
@@ -724,7 +744,12 @@ export class CmuxTab {
 			const callable = (0, eval)("(" + source + ")");
 			return callable(element, ...args);
 		})()`;
-		return await this.#evalScript<TResult>(script);
+		// Envelope so a stale selector or a throwing callback reports its actual
+		// error instead of the daemon's generic js_error (see tab.evaluate()).
+		const result = (await this.#request("browser.eval", {
+			script: serializeEvalWithEnvelope(script, []),
+		})) as CmuxEvalResult;
+		return unwrapEvalEnvelope<TResult>(result.value, "elementHandle.evaluate()");
 	}
 
 	async pageContent(): Promise<string> {
@@ -1097,6 +1122,10 @@ class CmuxElementHandle {
 		await this.#tab.fill(this.#selector, value);
 	}
 
+	async press(key: string): Promise<void> {
+		await this.#tab.press(key, { selector: this.#selector });
+	}
+
 	async focus(): Promise<void> {
 		await this.#tab.focus(this.#selector);
 	}
@@ -1284,10 +1313,10 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 	const signal = AbortSignal.any(
 		opts.signal ? [timeoutSignal, opts.signal, runAc.signal] : [timeoutSignal, runAc.signal],
 	);
-	const displays: RunResultOk["displays"] = [];
+	const output = new RunOutput();
 	const screenshots: ScreenshotResult[] = [];
 	const runId = crypto.randomUUID();
-	tab.setRunContext({ session: opts.snapshot, displays, screenshots, signal, timeoutMs: opts.timeoutMs });
+	tab.setRunContext({ session: opts.snapshot, output, screenshots, signal, timeoutMs: opts.timeoutMs });
 	const runtime = tab.ensureRuntime(opts.snapshot);
 	runtime.setCwd(opts.snapshot.cwd);
 	const runTab = bindBrowserRunFacade(tab, signal);
@@ -1298,7 +1327,8 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 		assert: (cond: unknown, text?: string): void => {
 			if (!cond) throw new ToolError(text ?? "Assertion failed");
 		},
-		wait: (ms: number): Promise<void> => waitForBrowserRun(ms, signal),
+		wait: (msOrPredicate: number | (() => unknown), opts?: WaitPredicateOptions): Promise<unknown> =>
+			waitForBrowserRun(msOrPredicate, signal, opts),
 	});
 
 	const { promise: cancelRejection, reject } = Promise.withResolvers<never>();
@@ -1316,11 +1346,12 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 		const hooks: RuntimeHooks = {
 			onText: chunk => {
 				throwIfAborted(signal);
+				output.pushText(chunk);
 				logger.debug(chunk.replace(/\n$/, ""));
 			},
-			onDisplay: output => {
+			onDisplay: displayed => {
 				throwIfAborted(signal);
-				pushDisplay(displays, output);
+				output.pushDisplay(displayed);
 			},
 			callTool: (name, args) => {
 				throwIfAborted(signal);
@@ -1333,7 +1364,7 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 			runtime.run(opts.code, `cmux-run-${runId}.js`, hooks, { runId, cwd: opts.snapshot.cwd }),
 			cancelRejection,
 		]);
-		return { displays, returnValue: cloneSafe(returnValue), screenshots };
+		return { displays: output.finish(), returnValue: cloneSafe(returnValue), screenshots };
 	} finally {
 		signal.removeEventListener("abort", onAbort);
 		runAc.abort(new ToolAbortError("Browser run ended"));
@@ -1341,38 +1372,6 @@ export async function runCmuxCode(tab: CmuxTab, opts: RunCmuxCodeOptions): Promi
 	}
 }
 
-function pushDisplay(displays: RunResultOk["displays"], output: JsDisplayOutput): void {
-	if (output.type === "image") {
-		displays.push({ type: "image", data: output.data, mimeType: output.mimeType });
-		return;
-	}
-	if (output.type === "json") {
-		displays.push({ type: "text", text: safeJsonStringify(output.data) });
-		return;
-	}
-	displays.push({ type: "text", text: safeJsonStringify(output.event) });
-}
-
-function safeJsonStringify(value: unknown): string {
-	try {
-		return JSON.stringify(value, null, 2);
-	} catch {
-		return String(value);
-	}
-}
-
-function cloneSafe(value: unknown): unknown {
-	if (value === undefined) return undefined;
-	try {
-		structuredClone(value);
-		return value;
-	} catch {}
-	try {
-		return JSON.parse(JSON.stringify(value)) as unknown;
-	} catch {}
-	return String(value);
-}
-
 function numberFrom(value: unknown, fallback: number): number {
 	return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }

package/src/tools/browser/cmux/rpc.ts

@@ -1,3 +1,4 @@
+import { ToolError } from "../../tool-errors";
 import type { Observation, ObservationEntry } from "../tab-protocol";
 
 export interface CmuxKind {
@@ -120,6 +121,55 @@ export function serializeEval(fn: string | ((...args: unknown[]) => unknown), ar
 	return `(${fn.toString()})(${args.map(arg => JSON.stringify(arg)).join(",")})`;
 }
 
+/**
+ * Like {@link serializeEval}, but wraps the expression in a page-side
+ * try/catch envelope so a throwing script surfaces its message + stack
+ * instead of the daemon's opaque `js_error: A JavaScript exception occurred`,
+ * and a Promise return (which the daemon cannot serialize) is flagged
+ * explicitly rather than failing as "unsupported type".
+ *
+ * String scripts run through indirect eval to keep global-scope semantics;
+ * function sources are already expressions and are invoked directly.
+ * `undefined` results come back as `null` (JSON cannot carry `undefined`).
+ * Decode with {@link unwrapEvalEnvelope}.
+ */
+export function serializeEvalWithEnvelope(fn: string | ((...args: unknown[]) => unknown), args: unknown[]): string {
+	const inner = serializeEval(fn, args);
+	const expr = typeof fn === "string" ? `(0, eval)(${JSON.stringify(inner)})` : inner;
+	return `(() => {
+		try {
+			const __v = (${expr});
+			if (__v && typeof __v.then === "function") return { __jeopiPromise: true };
+			return { __jeopiOk: __v === undefined ? null : __v };
+		} catch (e) {
+			return { __jeopiErr: (e && (e.stack || e.message)) || String(e) };
+		}
+	})()`;
+}
+
+/**
+ * Decode a {@link serializeEvalWithEnvelope} result: rethrow page-side
+ * exceptions as rich {@link ToolError}s, reject unserializable Promise
+ * returns with an actionable message, and pass through values from daemons
+ * that did not run the wrapper.
+ */
+export function unwrapEvalEnvelope<TResult>(value: unknown, label: string): TResult {
+	if (value && typeof value === "object") {
+		if ("__jeopiErr" in value && typeof value.__jeopiErr === "string") {
+			throw new ToolError(`${label} threw a JavaScript exception:\n${value.__jeopiErr}`);
+		}
+		if ("__jeopiPromise" in value && value.__jeopiPromise === true) {
+			throw new ToolError(
+				`${label} returned a Promise, but this surface evaluates synchronously and cannot await it — return a plain value (poll with waitForFunction for async state instead)`,
+			);
+		}
+		if ("__jeopiOk" in value) {
+			return value.__jeopiOk as TResult;
+		}
+	}
+	return value as TResult;
+}
+
 export function mapWaitUntil(waitUntil: string | undefined): "interactive" | "complete" {
 	return waitUntil === "domcontentloaded" ? "interactive" : "complete";
 }

package/src/tools/browser/launch.ts

@@ -99,12 +99,16 @@ async function loadBrowsers(): Promise<typeof BrowsersNs> {
 }
 
 /**
- * Lazily download Chromium on first browser launch via @puppeteer/browsers.
- * Skipped when a system Chromium (NixOS) or PUPPETEER_EXECUTABLE_PATH is set.
- * The browser is cached under ~/.jeopi/puppeteer (getPuppeteerDir).
+ * Resolve the Chromium executable puppeteer will launch, lazily downloading it
+ * on first use via @puppeteer/browsers. Skipped when a system Chromium (NixOS)
+ * or PUPPETEER_EXECUTABLE_PATH is set. The browser is cached under
+ * ~/.jeopi/puppeteer (getPuppeteerDir). Returns undefined when platform
+ * detection fails (puppeteer default resolution takes over). Exported so
+ * real-browser tests can probe launchability and skip on hosts missing
+ * Chrome's system libraries.
  */
 let chromiumExecutablePromise: Promise<string | undefined> | undefined;
-async function ensureChromiumExecutable(): Promise<string | undefined> {
+export async function ensureChromiumExecutable(): Promise<string | undefined> {
 	const sysChrome = resolveSystemChromium();
 	if (sysChrome) return sysChrome;
 	const envPath = process.env.PUPPETEER_EXECUTABLE_PATH;

package/src/tools/browser/run-cancellation.ts

@@ -1,11 +1,50 @@
 import { untilAborted } from "jeopi-utils";
-import { throwIfAborted } from "../tool-errors";
+import { ToolError, throwIfAborted } from "../tool-errors";
 
-/** Sleeps inside evaluated browser code while honoring the owning run's cancellation signal. */
-export async function waitForBrowserRun(ms: number, signal: AbortSignal): Promise<void> {
-	throwIfAborted(signal);
-	await untilAborted(signal, () => Bun.sleep(ms));
+/** Options for the predicate form of the run-scoped `wait()` helper. */
+export interface WaitPredicateOptions {
+	/** Max time to poll before failing, in ms (default 30_000). */
+	timeout?: number;
+	/** Poll interval in ms (default 100, floor 10). */
+	interval?: number;
+}
+
+/**
+ * Run-scoped `wait()` helper for evaluated browser code, honoring the owning run's
+ * cancellation signal.
+ *
+ * - `wait(ms)` sleeps for `ms` milliseconds.
+ * - `wait(fn, { timeout?, interval? })` polls `fn` (sync or async) until it returns a
+ *   truthy value and resolves with that value; throws a named `ToolError` on timeout
+ *   instead of stalling into the whole-cell deadline. Predicate errors propagate.
+ */
+export async function waitForBrowserRun(
+	msOrPredicate: number | (() => unknown),
+	signal: AbortSignal,
+	opts?: WaitPredicateOptions,
+): Promise<unknown> {
 	throwIfAborted(signal);
+	if (typeof msOrPredicate === "number") {
+		await untilAborted(signal, async () => await Bun.sleep(msOrPredicate));
+		throwIfAborted(signal);
+		return undefined;
+	}
+	if (typeof msOrPredicate !== "function") {
+		throw new ToolError("wait(...) expects milliseconds (number) or a predicate function to poll");
+	}
+	const timeout =
+		opts?.timeout !== undefined && Number.isFinite(opts.timeout) && opts.timeout > 0 ? opts.timeout : 30_000;
+	const interval = Math.max(opts?.interval ?? 100, 10);
+	const deadline = Date.now() + timeout;
+	for (;;) {
+		const value = await untilAborted(signal, async () => await msOrPredicate());
+		throwIfAborted(signal);
+		if (value) return value;
+		if (Date.now() + interval > deadline) {
+			throw new ToolError(`wait(predicate) timed out after ${timeout}ms — predicate never returned truthy`);
+		}
+		await untilAborted(signal, async () => await Bun.sleep(interval));
+	}
 }
 
 /** Binds a long-lived browser facade to one evaluated run's abort signal. */

package/src/tools/browser/run-output.ts

@@ -0,0 +1,76 @@
+import type { ImageContent, TextContent } from "jeopi-ai";
+import type { JsDisplayOutput } from "../../eval/js/shared/types";
+
+/**
+ * Accumulates a browser run's result entries: explicit `display()` payloads,
+ * screenshot captions/images, and buffered stream text (`console.*`, `print`,
+ * `display()` of strings/primitives — `JsRuntime.displayValue` emits those via
+ * `onText`). Stream text is buffered and flushed as one entry before the next
+ * display/screenshot (and on `finish()`) so it reaches the tool result in
+ * order instead of vanishing into the debug log.
+ */
+export class RunOutput {
+	readonly #displays: Array<TextContent | ImageContent> = [];
+	#textBuffer = "";
+
+	/** Buffer a stream-text chunk; it joins the entries at the next push or on finish(). */
+	pushText(chunk: string): void {
+		this.#textBuffer += chunk;
+	}
+
+	/** Append a `display()` payload (image/json/status), flushing buffered text first. */
+	pushDisplay(output: JsDisplayOutput): void {
+		if (output.type === "image") {
+			this.push({ type: "image", data: output.data, mimeType: output.mimeType });
+			return;
+		}
+		if (output.type === "json") {
+			this.push({ type: "text", text: safeJsonStringify(output.data) });
+			return;
+		}
+		// status — surface as compact JSON so helper side effects (read/write/env) appear in
+		// the cell result alongside explicit display() output.
+		this.push({ type: "text", text: safeJsonStringify(output.event) });
+	}
+
+	/** Append a pre-built entry (e.g. a screenshot caption/image), flushing buffered text first. */
+	push(entry: TextContent | ImageContent): void {
+		this.#flush();
+		this.#displays.push(entry);
+	}
+
+	/** Flush any remaining stream text and return the ordered entries. */
+	finish(): Array<TextContent | ImageContent> {
+		this.#flush();
+		return this.#displays;
+	}
+
+	#flush(): void {
+		if (!this.#textBuffer) return;
+		// Entries are newline-joined at render; drop the stream's trailing newline.
+		this.#displays.push({ type: "text", text: this.#textBuffer.replace(/\n$/, "") });
+		this.#textBuffer = "";
+	}
+}
+
+/** JSON.stringify that never throws (cycles/BigInt → String(value)). */
+export function safeJsonStringify(value: unknown): string {
+	try {
+		return JSON.stringify(value, null, 2);
+	} catch {
+		return String(value);
+	}
+}
+
+/** Pass a return value across the run boundary: structured-cloneable as-is, else JSON round-trip, else String. */
+export function cloneSafe(value: unknown): unknown {
+	if (value === undefined) return undefined;
+	try {
+		structuredClone(value);
+		return value;
+	} catch {}
+	try {
+		return JSON.parse(JSON.stringify(value)) as unknown;
+	} catch {}
+	return String(value);
+}