jeopi-cli 16.4.1 → 16.4.3

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);
+}