@oh-my-pi/pi-coding-agent 14.9.3 → 14.9.7

package/src/eval/js/shared/helpers.ts

@@ -0,0 +1,237 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import * as Diff from "diff";
+import { ToolError } from "../../../tools/tool-errors";
+import type { JsStatusEvent } from "./types";
+
+export interface HelperOptions {
+	path?: string;
+	hidden?: boolean;
+	maxDepth?: number;
+	limit?: number;
+	offset?: number;
+	reverse?: boolean;
+	unique?: boolean;
+	count?: boolean;
+}
+
+/**
+ * Inputs the helper factory needs from its host runtime. `cwd` is a getter so the runtime
+ * can update it between cells (e.g. when the agent's session cwd changes) without
+ * recreating helpers.
+ */
+export interface HelperContext {
+	cwd(): string;
+	env: Map<string, string>;
+	emitStatus(event: JsStatusEvent): void;
+}
+
+/**
+ * The set of functions exposed to user code via `globalThis.__omp_helpers__`. The JS
+ * prelude reads from this bag and attaches short aliases (`read`, `write`, `tree`, ...)
+ * onto the global scope.
+ */
+export interface HelperBundle {
+	read(rawPath: string, options?: HelperOptions): Promise<string>;
+	writeFile(rawPath: string, data: unknown): Promise<string>;
+	append(rawPath: string, content: string): Promise<string>;
+	sortText(text: string, options?: HelperOptions): string;
+	uniqText(text: string, options?: HelperOptions): string | Array<[number, string]>;
+	counter(items: string | string[], options?: HelperOptions): Array<[number, string]>;
+	diff(rawA: string, rawB: string): Promise<string>;
+	tree(searchPath?: string, options?: HelperOptions): Promise<string>;
+	env(key?: string, value?: string): string | Record<string, string> | undefined;
+}
+
+const utf8Encoder = new TextEncoder();
+
+export function createHelpers(ctx: HelperContext): HelperBundle {
+	return {
+		read: async (rawPath, options = {}) => {
+			const { filePath, file, size } = await resolveRegularFile(ctx, rawPath);
+			let text = await file.text();
+			const offset = typeof options.offset === "number" ? options.offset : 1;
+			const limit = typeof options.limit === "number" ? options.limit : undefined;
+			if (offset > 1 || limit !== undefined) {
+				const lines = text.split(/\r?\n/);
+				const start = Math.max(0, offset - 1);
+				const end = limit !== undefined ? start + limit : lines.length;
+				text = lines.slice(start, end).join("\n");
+			}
+			ctx.emitStatus({ op: "read", path: filePath, bytes: size, chars: text.length });
+			return text;
+		},
+		writeFile: async (rawPath, data) => {
+			if (!isWriteData(data)) {
+				throw new ToolError("write() expects string, Blob, ArrayBuffer, or TypedArray data");
+			}
+			const filePath = resolvePath(ctx, rawPath);
+			if (typeof data === "string" || data instanceof Blob || data instanceof ArrayBuffer) {
+				await Bun.write(filePath, data);
+			} else {
+				await Bun.write(filePath, new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+			}
+			ctx.emitStatus({ op: "write", path: filePath, bytes: getDataSize(data) });
+			return filePath;
+		},
+		append: async (rawPath, content) => {
+			const target = resolvePath(ctx, rawPath);
+			await Bun.write(
+				target,
+				`${await Bun.file(target)
+					.text()
+					.catch(() => "")}${content}`,
+			);
+			ctx.emitStatus({
+				op: "append",
+				path: target,
+				chars: content.length,
+				bytes: utf8Encoder.encode(content).byteLength,
+			});
+			return target;
+		},
+		sortText: (text, options = {}) => {
+			const lines = String(text).split(/\r?\n/);
+			const deduped = options.unique ? Array.from(new Set(lines)) : lines;
+			const sorted = deduped.sort((a, b) => a.localeCompare(b));
+			if (options.reverse) sorted.reverse();
+			const result = sorted.join("\n");
+			ctx.emitStatus({
+				op: "sort",
+				lines: sorted.length,
+				reverse: options.reverse === true,
+				unique: options.unique === true,
+			});
+			return result;
+		},
+		uniqText: (text, options = {}) => {
+			const lines = String(text)
+				.split(/\r?\n/)
+				.filter(line => line.length > 0);
+			const groups: Array<[number, string]> = [];
+			for (const line of lines) {
+				const last = groups.at(-1);
+				if (last && last[1] === line) {
+					last[0] += 1;
+					continue;
+				}
+				groups.push([1, line]);
+			}
+			ctx.emitStatus({ op: "uniq", groups: groups.length, count_mode: options.count === true });
+			if (options.count) return groups;
+			return groups.map(([, line]) => line).join("\n");
+		},
+		counter: (items, options = {}) => {
+			const values = Array.isArray(items) ? items : String(items).split(/\r?\n/).filter(Boolean);
+			const counts = new Map<string, number>();
+			for (const item of values) counts.set(item, (counts.get(item) ?? 0) + 1);
+			const entries = Array.from(counts.entries())
+				.map(([item, count]) => [count, item] as [number, string])
+				.sort((a, b) => (options.reverse === false ? a[0] - b[0] : b[0] - a[0]) || a[1].localeCompare(b[1]));
+			const limited = entries.slice(0, options.limit ?? entries.length);
+			ctx.emitStatus({ op: "counter", unique: counts.size, total: values.length, top: limited.slice(0, 10) });
+			return limited;
+		},
+		diff: async (rawA, rawB) => {
+			const fileA = resolvePath(ctx, rawA);
+			const fileB = resolvePath(ctx, rawB);
+			const [a, b] = await Promise.all([Bun.file(fileA).text(), Bun.file(fileB).text()]);
+			const result = Diff.createTwoFilesPatch(fileA, fileB, a, b, "", "", { context: 3 });
+			ctx.emitStatus({
+				op: "diff",
+				file_a: fileA,
+				file_b: fileB,
+				identical: a === b,
+				preview: result.slice(0, 500),
+			});
+			return result;
+		},
+		tree: async (searchPath = ".", options = {}) => {
+			const root = resolvePath(ctx, searchPath);
+			const maxDepth = options.maxDepth ?? 3;
+			const showHidden = options.hidden ?? false;
+			const lines: string[] = [`${root}/`];
+			let entryCount = 0;
+			const walk = async (dir: string, prefix: string, depth: number): Promise<void> => {
+				if (depth > maxDepth) return;
+				const entries = (await fs.promises.readdir(dir, { withFileTypes: true }))
+					.filter(entry => showHidden || !entry.name.startsWith("."))
+					.sort((a, b) => a.name.localeCompare(b.name));
+				for (let index = 0; index < entries.length; index++) {
+					const entry = entries[index];
+					const isLast = index === entries.length - 1;
+					const connector = isLast ? "└── " : "├── ";
+					const suffix = entry.isDirectory() ? "/" : "";
+					lines.push(`${prefix}${connector}${entry.name}${suffix}`);
+					entryCount += 1;
+					if (entry.isDirectory()) {
+						await walk(path.join(dir, entry.name), `${prefix}${isLast ? "    " : "│   "}`, depth + 1);
+					}
+				}
+			};
+			await walk(root, "", 1);
+			const result = lines.join("\n");
+			ctx.emitStatus({ op: "tree", path: root, entries: entryCount, preview: result.slice(0, 1000) });
+			return result;
+		},
+		env: (key, value) => {
+			if (!key) {
+				const merged = Object.fromEntries(Object.entries(getMergedEnv(ctx)).sort(([a], [b]) => a.localeCompare(b)));
+				ctx.emitStatus({ op: "env", count: Object.keys(merged).length, keys: Object.keys(merged).slice(0, 20) });
+				return merged;
+			}
+			if (value !== undefined) {
+				ctx.env.set(key, value);
+				ctx.emitStatus({ op: "env", key, value, action: "set" });
+				return value;
+			}
+			const result = ctx.env.get(key) ?? Bun.env[key];
+			ctx.emitStatus({ op: "env", key, value: result, action: "get" });
+			return result;
+		},
+	};
+}
+
+function getMergedEnv(ctx: HelperContext): Record<string, string> {
+	const merged: Record<string, string> = {};
+	for (const [key, value] of Object.entries(Bun.env)) {
+		if (typeof value === "string") merged[key] = value;
+	}
+	for (const [key, value] of ctx.env) merged[key] = value;
+	return merged;
+}
+
+function resolvePath(ctx: HelperContext, value: string): string {
+	if (path.isAbsolute(value)) return path.normalize(value);
+	return path.resolve(ctx.cwd(), value);
+}
+
+async function resolveRegularFile(
+	ctx: HelperContext,
+	rawPath: string,
+): Promise<{ filePath: string; file: Bun.BunFile; size: number }> {
+	if (/^[a-z][a-z0-9+.-]*:\/\//i.test(rawPath)) {
+		throw new ToolError(`Protocol paths are not supported by read(): ${rawPath}`);
+	}
+	const filePath = resolvePath(ctx, rawPath);
+	const file = Bun.file(filePath);
+	const stat = await file.stat();
+	if (stat.isDirectory()) {
+		throw new ToolError(`Directory paths are not supported by read(): ${filePath}`);
+	}
+	return { filePath, file, size: stat.size };
+}
+
+function getDataSize(data: string | Blob | ArrayBuffer | ArrayBufferView): number {
+	if (typeof data === "string") return utf8Encoder.encode(data).byteLength;
+	if (data instanceof Blob) return data.size;
+	if (data instanceof ArrayBuffer) return data.byteLength;
+	return data.byteLength;
+}
+
+function isWriteData(value: unknown): value is string | Blob | ArrayBuffer | ArrayBufferView {
+	return (
+		typeof value === "string" || value instanceof Blob || value instanceof ArrayBuffer || ArrayBuffer.isView(value)
+	);
+}

package/src/eval/js/shared/indirect-eval.ts

@@ -0,0 +1,30 @@
+/**
+ * Indirect eval — runs in the host's global scope, isolating bindings declared with
+ * `const`/`let` from this module's closure. Used by both the JS eval worker and the
+ * browser tab worker to execute user-supplied source without `node:vm`.
+ *
+ * Why not vm.runInContext: Bun crashes the parent process with SIGTRAP when
+ * `Worker.terminate()` fires while a worker is mid-`vm.runInContext` synchronous loop.
+ * Indirect eval does not trip that bug.
+ *
+ * The optional `filename` is appended as a `//# sourceURL=...` pragma so V8 attributes
+ * stack frames to the user cell instead of `<anonymous>`.
+ */
+export function indirectEval(source: string, filename?: string): unknown {
+	const withPragma = filename ? `${source}\n//# sourceURL=${filename}` : source;
+	// Read `eval` via a property access so the call site is *indirect* (global scope),
+	// not direct (this module's lexical scope). The cast erases the DOM lib return type.
+	// We deliberately avoid `node:vm` because Bun crashes the parent with SIGTRAP when
+	// Worker.terminate() fires mid-`vm.runInContext` synchronous loop — indirect eval is
+	// the executor for user code in the worker.
+	// biome-ignore lint/security/noGlobalEval: see comment above — this is the executor.
+	const geval = globalThis.eval as (src: string) => unknown;
+	return geval(withPragma);
+}
+
+export async function awaitMaybePromise<T>(value: T | Promise<T>): Promise<T> {
+	if (!value || typeof value !== "object" || typeof (value as { then?: unknown }).then !== "function") {
+		return value;
+	}
+	return await (value as Promise<T>);
+}

package/src/eval/js/{prelude.txt → shared/prelude.txt}

@@ -12,7 +12,6 @@ if (!globalThis.__omp_js_prelude_loaded__) {
 	const counter = (items, opts = {}) => callHelper("counter", items, toOptions(opts));
 	const diff = (a, b) => callHelper("diff", a, b);
 	const tree = (path = ".", opts = {}) => callHelper("tree", path, toOptions(opts));
-	const run = (cmd, opts = {}) => callHelper("run", cmd, toOptions(opts));
 	const env = (key, value) => callHelper("env", key, value);
 
 	const tool = new Proxy(
@@ -67,6 +66,5 @@ if (!globalThis.__omp_js_prelude_loaded__) {
 	globalThis.counter = counter;
 	globalThis.diff = diff;
 	globalThis.tree = tree;
-	globalThis.run = run;
 	globalThis.env = env;
 }

package/src/eval/js/shared/rewrite-imports.ts

@@ -0,0 +1,211 @@
+import { parse as babelParse } from "@babel/parser";
+
+// Static ESM `import` declarations are not valid inside vm.runInContext (script-mode parsing).
+// We rewrite top-level imports to dynamic-import expressions in the user-supplied source so
+// pasted ESM runs verbatim. A real parser keeps imports embedded in string literals, template
+// literals, or comments intact.
+
+type BabelImportDeclaration = {
+	type: "ImportDeclaration";
+	start: number;
+	end: number;
+	source: { value: string };
+	specifiers: ReadonlyArray<{
+		type: "ImportDefaultSpecifier" | "ImportNamespaceSpecifier" | "ImportSpecifier";
+		local: { name: string };
+		imported?: { type: "Identifier"; name: string } | { type: "StringLiteral"; value: string };
+	}>;
+	attributes?: ReadonlyArray<{
+		key: { type: "Identifier"; name: string } | { type: "StringLiteral"; value: string };
+		value: { value: string };
+	}>;
+};
+
+type BabelLexicalDecl =
+	| { type: "VariableDeclaration"; kind: "const" | "let" | "var"; start: number; end: number }
+	| { type: "ClassDeclaration"; start: number; end: number; id: { start: number; end: number; name: string } | null };
+
+function buildDynamicImportCall(sourceLiteral: string, withClause: string | undefined): string {
+	// Route every static import through the worker-injected `__omp_import__` helper so the
+	// specifier resolves against the session cwd (and `with`-attribute imports keep working).
+	return withClause ? `__omp_import__(${sourceLiteral}, ${withClause})` : `__omp_import__(${sourceLiteral})`;
+}
+
+function buildWithClause(node: BabelImportDeclaration): string | undefined {
+	const attrs = node.attributes;
+	if (!attrs || attrs.length === 0) return undefined;
+	const pairs = attrs.map(attr => {
+		const key = attr.key.type === "Identifier" ? attr.key.name : JSON.stringify(attr.key.value);
+		return `${key}: ${JSON.stringify(attr.value.value)}`;
+	});
+	return `{ ${pairs.join(", ")} }`;
+}
+
+function rewriteImportNode(node: BabelImportDeclaration): string {
+	const sourceLiteral = JSON.stringify(node.source.value);
+	const withClause = buildWithClause(node);
+	const importCall = buildDynamicImportCall(sourceLiteral, withClause);
+
+	let defaultName: string | undefined;
+	let namespaceName: string | undefined;
+	const namedPairs: Array<[string, string]> = [];
+	for (const spec of node.specifiers) {
+		if (spec.type === "ImportDefaultSpecifier") {
+			defaultName = spec.local.name;
+		} else if (spec.type === "ImportNamespaceSpecifier") {
+			namespaceName = spec.local.name;
+		} else if (spec.type === "ImportSpecifier" && spec.imported) {
+			const imported = spec.imported.type === "Identifier" ? spec.imported.name : spec.imported.value;
+			namedPairs.push([imported, spec.local.name]);
+		}
+	}
+
+	if (namedPairs.length > 0) {
+		const inner = namedPairs.map(([imp, loc]) => (imp === loc ? imp : `${imp}: ${loc}`)).join(", ");
+		const props = defaultName ? `default: ${defaultName}, ${inner}` : inner;
+		return `const { ${props} } = await ${importCall};`;
+	}
+	if (namespaceName && defaultName) {
+		return `const ${namespaceName} = await ${importCall}; const ${defaultName} = ${namespaceName}.default;`;
+	}
+	if (namespaceName) return `const ${namespaceName} = await ${importCall};`;
+	if (defaultName) return `const ${defaultName} = (await ${importCall}).default;`;
+	return `await ${importCall};`;
+}
+
+export function rewriteStaticImports(code: string): string {
+	if (!code.includes("import")) return code;
+
+	let ast: { program: { body: ReadonlyArray<{ type: string }> } };
+	try {
+		ast = babelParse(code, {
+			sourceType: "module",
+			allowAwaitOutsideFunction: true,
+			allowReturnOutsideFunction: true,
+			allowImportExportEverywhere: true,
+			allowNewTargetOutsideFunction: true,
+			allowSuperOutsideMethod: true,
+			allowUndeclaredExports: true,
+			errorRecovery: true,
+		}) as unknown as typeof ast;
+	} catch {
+		// Parser bailed entirely — let the VM surface the real syntax error.
+		return code;
+	}
+
+	const imports: BabelImportDeclaration[] = [];
+	for (const node of ast.program.body) {
+		if (node.type === "ImportDeclaration") imports.push(node as unknown as BabelImportDeclaration);
+	}
+	if (imports.length === 0) return code;
+
+	// Splice from the back so earlier offsets stay valid.
+	imports.sort((a, b) => b.start - a.start);
+	let result = code;
+	for (const node of imports) {
+		result = result.slice(0, node.start) + rewriteImportNode(node) + result.slice(node.end);
+	}
+	return result;
+}
+
+/**
+ * Demote top-level `const`/`let`/`class` declarations to `var` so they persist on the
+ * worker's globalThis across indirect `eval` calls. Indirect eval gives each call its own
+ * lexical environment, so `const x = 1` in one cell would be invisible to the next.
+ * `var` and function declarations are stored on the global object and survive across cells.
+ *
+ *   const x = 1;             -> var x = 1;
+ *   let { a, b } = obj;      -> var { a, b } = obj;
+ *   class Foo extends Bar {} -> var Foo = class extends Bar {};
+ *
+ * Nested declarations (inside functions, blocks, classes) are left alone \u2014 they're
+ * scoped to their enclosing function/block regardless of `var` vs `let`/`const`.
+ */
+export function demoteTopLevelLexicals(code: string): string {
+	if (!/\b(?:const|let|class)\b/.test(code)) return code;
+
+	let ast: { program: { body: ReadonlyArray<{ type: string }> } };
+	try {
+		ast = babelParse(code, {
+			sourceType: "module",
+			allowAwaitOutsideFunction: true,
+			allowReturnOutsideFunction: true,
+			allowImportExportEverywhere: true,
+			allowNewTargetOutsideFunction: true,
+			allowSuperOutsideMethod: true,
+			allowUndeclaredExports: true,
+			errorRecovery: true,
+		}) as unknown as typeof ast;
+	} catch {
+		return code;
+	}
+
+	const targets: BabelLexicalDecl[] = [];
+	for (const node of ast.program.body) {
+		if (node.type === "VariableDeclaration") {
+			const decl = node as unknown as BabelLexicalDecl & { kind: string };
+			if (decl.kind === "const" || decl.kind === "let") targets.push(decl as BabelLexicalDecl);
+		} else if (node.type === "ClassDeclaration") {
+			const decl = node as unknown as Extract<BabelLexicalDecl, { type: "ClassDeclaration" }>;
+			if (decl.id) targets.push(decl);
+		}
+	}
+	if (targets.length === 0) return code;
+
+	targets.sort((a, b) => b.start - a.start);
+	let result = code;
+	for (const node of targets) {
+		const segment = result.slice(node.start, node.end);
+		let replacement: string;
+		if (node.type === "VariableDeclaration") {
+			replacement = `var${segment.slice(node.kind.length)}`;
+		} else {
+			const id = node.id;
+			if (!id) continue;
+			const idEndInSegment = id.end - node.start;
+			const tail = segment.slice(idEndInSegment);
+			const hasTrailingSemi = segment.endsWith(";");
+			replacement = `var ${id.name} = class${tail}${hasTrailingSemi ? "" : ";"}`;
+		}
+		result = result.slice(0, node.start) + replacement + result.slice(node.end);
+	}
+	return result;
+}
+
+/**
+ * Strip TypeScript syntax (type annotations, `interface`, `as`, `satisfies`, generics in
+ * call expressions, etc.) before the import/lexical rewriters parse the code. We use Bun's
+ * native transpiler in `ts` loader mode — fast, no JSX transforms, preserves `import`/
+ * `export` declarations so the downstream Babel rewrites keep working.
+ *
+ * Skipped when the code parses as plain JavaScript already (Babel can accept it), so the
+ * common case avoids an extra transpile pass. We detect "looks like TS" with a cheap regex
+ * before invoking the transpiler.
+ */
+export function stripTypeScript(code: string): string {
+	if (!LOOKS_LIKE_TS.test(code)) return code;
+	try {
+		return new Bun.Transpiler({ loader: "ts" }).transformSync(code);
+	} catch {
+		// Transpiler failed (e.g. unrecoverable syntax). Hand the original source back so the
+		// downstream rewriter / VM surfaces the real error to the user.
+		return code;
+	}
+}
+
+// Heuristic: any of the obvious TS-only tokens. Plain JS using `as` only inside strings
+// won't match because we require a leading word boundary plus a colon/keyword neighbor.
+const LOOKS_LIKE_TS =
+	/(?:\binterface\s+\w|\btype\s+\w+\s*=|\b(?:as|satisfies)\s+(?:[A-Z]|\bconst\b)|:\s*(?:string|number|boolean|any|unknown|void|never|object|[A-Z]\w*)\b|<\s*[A-Z]\w*\s*[,>])/;
+
+export function wrapCode(code: string): { source: string; asyncWrapped: boolean } {
+	const rewritten = demoteTopLevelLexicals(rewriteStaticImports(stripTypeScript(code)));
+	const needsAsyncWrapper = /\bawait\b|\breturn\b/.test(rewritten);
+	if (!needsAsyncWrapper) {
+		return { source: rewritten, asyncWrapped: false };
+	}
+	return {
+		source: `(async () => {\n${rewritten}\n})()`,
+		asyncWrapped: true,
+	};
+}

package/src/eval/js/shared/runtime.ts

@@ -0,0 +1,168 @@
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import * as util from "node:util";
+
+import { ToolError } from "../../../tools/tool-errors";
+import { createHelpers, type HelperBundle } from "./helpers";
+import { awaitMaybePromise, indirectEval } from "./indirect-eval";
+import { JAVASCRIPT_PRELUDE_SOURCE } from "./prelude";
+import { wrapCode } from "./rewrite-imports";
+import type { JsDisplayOutput, JsStatusEvent } from "./types";
+
+/**
+ * Per-run callbacks. Returned by `getHooks()` on each helper/tool/display invocation so
+ * the embedding worker can route emissions to the currently active run. Returning `null`
+ * makes status/display/tool calls reject with an error — useful for guarding against
+ * helpers being invoked outside a run window.
+ */
+export interface RuntimeHooks {
+	onText(chunk: string): void;
+	onDisplay(output: JsDisplayOutput): void;
+	callTool(name: string, args: unknown): Promise<unknown>;
+}
+
+export interface RuntimeOptions {
+	initialCwd: string;
+	sessionId: string;
+	/** Resolve hooks for the run currently in flight, or `null` if nothing is active. */
+	getHooks(): RuntimeHooks | null;
+	/**
+	 * Extra globals installed alongside `__omp_helpers__` / prelude. Use for stable, lifetime-
+	 * of-the-worker bindings (e.g. browser's `page`, `browser`). Per-run scope should be set
+	 * via `setRunScope()` instead.
+	 */
+	extraGlobals?: Record<string, unknown>;
+}
+
+/**
+ * Shared JS runtime for the eval worker and the browser tab worker. Owns the prelude,
+ * helper bag, console bridge, and indirect-eval execution. Emits text/display/tool-call
+ * back through `RuntimeHooks` that the embedder supplies — wire format is the embedder's
+ * concern.
+ */
+export class JsRuntime {
+	readonly helpers: HelperBundle;
+	#cwd: string;
+	readonly sessionId: string;
+	#env: Map<string, string>;
+	#getHooks: () => RuntimeHooks | null;
+
+	constructor(opts: RuntimeOptions) {
+		this.#cwd = opts.initialCwd;
+		this.sessionId = opts.sessionId;
+		this.#env = new Map();
+		this.#getHooks = opts.getHooks;
+		this.helpers = createHelpers({
+			cwd: () => this.#cwd,
+			env: this.#env,
+			emitStatus: event => this.#getHooks()?.onDisplay({ type: "status", event }),
+		});
+		this.#install(opts.extraGlobals);
+	}
+
+	get cwd(): string {
+		return this.#cwd;
+	}
+
+	setCwd(cwd: string): void {
+		this.#cwd = cwd;
+		const session = (globalThis as { __omp_session__?: { cwd?: string } }).__omp_session__;
+		if (session) session.cwd = cwd;
+	}
+
+	/**
+	 * Install per-run globals. Intended for run-scoped state (browser's `tab`, `display`
+	 * overrides, etc.). Overwrites previous assignments — caller is responsible for any
+	 * cleanup it wants.
+	 */
+	setRunScope(scope: Record<string, unknown>): void {
+		Object.assign(globalThis, scope);
+	}
+
+	async run(code: string, filename?: string): Promise<unknown> {
+		const wrapped = wrapCode(code);
+		const value = indirectEval(wrapped.source, filename);
+		return await awaitMaybePromise(value);
+	}
+
+	displayValue(value: unknown): void {
+		if (value === undefined) return;
+		const hooks = this.#getHooks();
+		if (!hooks) return;
+		if (value && typeof value === "object") {
+			const record = value as Record<string, unknown>;
+			if (record.type === "image" && typeof record.data === "string" && typeof record.mimeType === "string") {
+				hooks.onDisplay({ type: "image", data: record.data, mimeType: record.mimeType });
+				return;
+			}
+			hooks.onDisplay({ type: "json", data: structuredClone(value) });
+			return;
+		}
+		hooks.onText(`${String(value)}\n`);
+	}
+
+	#install(extraGlobals: Record<string, unknown> | undefined): void {
+		const injected: Record<string, unknown> = {
+			__omp_session__: { cwd: this.#cwd, sessionId: this.sessionId },
+			__omp_helpers__: this.helpers,
+			__omp_call_tool__: async (name: string, args: unknown) => {
+				const hooks = this.#getHooks();
+				if (!hooks) throw new ToolError("Tool calls are only valid inside an active run");
+				return await hooks.callTool(name, args);
+			},
+			__omp_import__: async (source: string, attrs?: Record<string, string>) => {
+				const target = resolveImportSpecifier(this.#cwd, source);
+				return attrs ? await import(target, { with: attrs }) : await import(target);
+			},
+			__omp_emit_status__: (op: string, data: Record<string, unknown> = {}) => {
+				const event: JsStatusEvent = { op, ...data };
+				this.#getHooks()?.onDisplay({ type: "status", event });
+			},
+			__omp_log__: (level: string, ...args: unknown[]) => {
+				const prefix = level === "error" ? "[error] " : level === "warn" ? "[warn] " : "";
+				const text = `${prefix}${formatConsoleArgs(args)}`;
+				this.#getHooks()?.onText(text.endsWith("\n") ? text : `${text}\n`);
+			},
+			__omp_display__: (value: unknown) => this.displayValue(value),
+			webcrypto: crypto,
+			// `process` is intentionally not overridden — user code gets the host worker's real
+			// `process` object. Subsetting it caused segfaults in workers that share state with
+			// puppeteer/worker_threads internals.
+			require: buildRequire(this.#cwd),
+			createRequire,
+			fs,
+		};
+		Object.assign(globalThis, injected, extraGlobals ?? {});
+		// Prelude assigns console bridge + short aliases (`read`, `write`, `tool`, `display`, ...)
+		// onto globalThis. Must run after helpers are in place.
+		indirectEval(JAVASCRIPT_PRELUDE_SOURCE);
+	}
+}
+
+function formatConsoleArgs(args: unknown[]): string {
+	return args
+		.map(arg => (typeof arg === "string" ? arg : util.inspect(arg, { depth: 6, colors: false, breakLength: 120 })))
+		.join(" ");
+}
+
+function buildRequire(cwd: string): NodeJS.Require {
+	return createRequire(pathToFileURL(path.join(cwd, "[eval]")).href);
+}
+
+/**
+ * Resolve an import specifier emitted by `rewriteStaticImports` against the active session
+ * cwd. Relative paths (`./`, `../`, `/`) and bare specifiers (`pkg`, `@scope/pkg`) both go
+ * through `Bun.resolveSync` rooted at the cwd so user-pasted ESM behaves as if it lived in
+ * the project — not next to the worker module. URL-like specifiers (`file://`, `data:`,
+ * `node:`, `http:`) are passed through unchanged.
+ */
+function resolveImportSpecifier(cwd: string, source: string): string {
+	if (/^[a-z][a-z0-9+.-]*:/i.test(source)) return source;
+	try {
+		return Bun.resolveSync(source, cwd);
+	} catch {
+		return source;
+	}
+}

package/src/eval/js/shared/types.ts

@@ -0,0 +1,18 @@
+/**
+ * Structured status payload emitted by helpers (`read`, `write`, `tree`, etc.) and the
+ * tool-call bridge. Surfaces to the model as part of `displays` so it has machine-readable
+ * context about what side effects happened.
+ */
+export interface JsStatusEvent {
+	op: string;
+	[key: string]: unknown;
+}
+
+/**
+ * One unit of structured output from a JS eval cell. `text` chunks flow through a separate
+ * channel.
+ */
+export type JsDisplayOutput =
+	| { type: "json"; data: unknown }
+	| { type: "image"; data: string; mimeType: string }
+	| { type: "status"; event: JsStatusEvent };