@gajae-code/coding-agent 0.1.1

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

@@ -0,0 +1,301 @@
+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 { logger } from "@gajae-code/utils";
+
+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 `__gjc_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>;
+}
+
+// Strict base64: characters from the standard alphabet plus optional `=` padding, and a
+// length that is a multiple of four. URL-safe base64 and embedded whitespace are not
+// accepted — the Anthropic API only honors strict base64 in image sources.
+const BASE64_STRICT_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+const DECIMAL_CSV_RE = /^\d{1,3}(?:,\d{1,3})*$/;
+
+function isStrictBase64(s: string): boolean {
+	if (s.length === 0 || s.length % 4 !== 0) return false;
+	return BASE64_STRICT_RE.test(s);
+}
+
+/**
+ * Normalize the `data` field of an `{ type: "image", data, mimeType }` display payload
+ * into strict base64. Accepts:
+ *   - already-valid base64 strings (passed through verbatim)
+ *   - `Uint8Array` / `Buffer` / `ArrayBuffer` / typed array views
+ *   - `{ type: "Buffer", data: number[] }` (the shape Node serializes Buffers to via
+ *     `JSON.stringify`)
+ *   - decimal-CSV byte strings (the output of `uint8array.toString("base64")`, which
+ *     silently ignores the encoding argument and returns `Array.prototype.toString` —
+ *     a footgun for callers expecting `Buffer.toString` semantics)
+ * Returns `null` if no recovery is possible.
+ */
+function coerceImageBase64(data: unknown): string | null {
+	if (typeof data === "string") {
+		if (isStrictBase64(data)) return data;
+		if (DECIMAL_CSV_RE.test(data)) {
+			const parts = data.split(",");
+			const bytes = new Uint8Array(parts.length);
+			for (let i = 0; i < parts.length; i++) {
+				const n = Number(parts[i]);
+				if (!Number.isInteger(n) || n < 0 || n > 255) return null;
+				bytes[i] = n;
+			}
+			return Buffer.from(bytes).toString("base64");
+		}
+		return null;
+	}
+	if (data instanceof Uint8Array) return Buffer.from(data).toString("base64");
+	if (data instanceof ArrayBuffer) return Buffer.from(data).toString("base64");
+	if (ArrayBuffer.isView(data)) {
+		const view = data as ArrayBufferView;
+		return Buffer.from(view.buffer, view.byteOffset, view.byteLength).toString("base64");
+	}
+	if (data && typeof data === "object") {
+		const obj = data as { type?: unknown; data?: unknown };
+		if (obj.type === "Buffer" && Array.isArray(obj.data)) {
+			const arr = obj.data as unknown[];
+			const bytes = new Uint8Array(arr.length);
+			for (let i = 0; i < arr.length; i++) {
+				const n = arr[i];
+				if (typeof n !== "number" || !Number.isInteger(n) || n < 0 || n > 255) return null;
+				bytes[i] = n;
+			}
+			return Buffer.from(bytes).toString("base64");
+		}
+	}
+	return null;
+}
+
+function describeDataType(data: unknown): string {
+	if (data === null) return "null";
+	if (data instanceof Uint8Array) return "Uint8Array";
+	if (data instanceof ArrayBuffer) return "ArrayBuffer";
+	if (ArrayBuffer.isView(data)) return data.constructor.name;
+	if (typeof data === "string") return `string(${data.length})`;
+	return typeof data;
+}
+
+/**
+ * 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;
+	#finalExpressionSet = false;
+	#finalExpressionValue: unknown;
+
+	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 { __gjc_session__?: { cwd?: string } }).__gjc_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> {
+		this.#finalExpressionSet = false;
+		this.#finalExpressionValue = undefined;
+		const wrapped = wrapCode(code);
+		const value = indirectEval(wrapped.source, filename);
+		if (wrapped.finalExpressionReturned) {
+			const awaited = await awaitMaybePromise(value);
+			if (this.#finalExpressionSet) {
+				const finalValue = this.#finalExpressionValue;
+				this.#finalExpressionSet = false;
+				this.#finalExpressionValue = undefined;
+				const resolved = await awaitMaybePromise(finalValue);
+				return resolved;
+			}
+			return awaited;
+		}
+		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.mimeType === "string") {
+				const data = coerceImageBase64(record.data);
+				if (data !== null) {
+					hooks.onDisplay({ type: "image", data, mimeType: record.mimeType });
+					return;
+				}
+				logger.warn("js displayValue: dropping image with unrecognized data shape", {
+					mimeType: record.mimeType,
+					dataType: describeDataType(record.data),
+				});
+				hooks.onText(
+					`[display: image dropped — \`data\` must be a base64 string, Uint8Array/Buffer, or ArrayBuffer; got ${describeDataType(record.data)}]\n`,
+				);
+				return;
+			}
+			try {
+				hooks.onDisplay({ type: "json", data: structuredClone(value) });
+			} catch (err) {
+				logger.debug("js displayValue: value is not structured-cloneable, falling back to text", {
+					error: err instanceof Error ? err.message : String(err),
+				});
+				hooks.onText(`${Object.prototype.toString.call(value)}\n`);
+			}
+			return;
+		}
+		hooks.onText(`${String(value)}\n`);
+	}
+
+	#install(extraGlobals: Record<string, unknown> | undefined): void {
+		const injected: Record<string, unknown> = {
+			__gjc_session__: { cwd: this.#cwd, sessionId: this.sessionId },
+			__gjc_helpers__: this.helpers,
+			__gjc_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);
+			},
+			__gjc_import__: async (source: string, options?: ImportCallOptions) => {
+				const target = resolveImportSpecifier(this.#cwd, source);
+				// Always invalidate cached module records for user-owned source files so edits
+				// between cells are picked up. Bun ignores query-string busting on `file:` URLs
+				// but honors `delete require.cache[absPath]`; bare specifiers and URL schemes are
+				// left alone to keep package identity stable across cells.
+				if (isLocalPathSpecifier(source) && path.isAbsolute(target)) {
+					delete require.cache[target];
+				}
+				return options !== undefined ? await import(target, options) : await import(target);
+			},
+			__gjc_emit_status__: (op: string, data: Record<string, unknown> = {}) => {
+				const event: JsStatusEvent = { op, ...data };
+				this.#getHooks()?.onDisplay({ type: "status", event });
+			},
+			__gjc_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`);
+			},
+			__gjc_display__: (value: unknown) => this.displayValue(value),
+			__gjc_set_final_expr__: (value: unknown) => {
+				this.#finalExpressionSet = true;
+				this.#finalExpressionValue = 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 `rewriteImports` 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;
+	}
+}
+
+/**
+ * Returns true when the original specifier is a relative or absolute filesystem path
+ * (i.e. user-owned source the agent is iterating on). Bare specifiers and URL schemes
+ * are excluded — `node:` built-ins cannot be reloaded, and busting bare packages would
+ * defeat module identity for every cell while bringing no editing benefit.
+ */
+function isLocalPathSpecifier(source: string): boolean {
+	return (
+		source.startsWith("./") ||
+		source.startsWith("../") ||
+		source === "." ||
+		source === ".." ||
+		source.startsWith("/") ||
+		source.startsWith("~/") ||
+		/^[a-zA-Z]:[\\/]/.test(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 };

package/src/eval/js/tool-bridge.ts

@@ -0,0 +1,144 @@
+import type { AgentTool, AgentToolResult } from "@gajae-code/agent-core";
+import type { ToolSession } from "../../tools";
+import { ToolError } from "../../tools/tool-errors";
+import type { JsStatusEvent } from "./shared/types";
+
+export type { JsStatusEvent } from "./shared/types";
+
+interface ToolBridgeOptions {
+	session: ToolSession;
+	signal?: AbortSignal;
+	emitStatus?: (event: JsStatusEvent) => void;
+}
+
+type ToolValue =
+	| string
+	| {
+			text: string;
+			details?: unknown;
+			images?: Array<{ mimeType: string; data: string }>;
+			hasError?: boolean;
+	  };
+function toolResultHasError(result: AgentToolResult): boolean {
+	if ((result as { isError?: unknown }).isError === true) {
+		return true;
+	}
+	if (!(result.details && typeof result.details === "object")) {
+		return false;
+	}
+	return (result.details as { isError?: unknown }).isError === true;
+}
+
+function getTool(session: ToolSession, name: string): AgentTool {
+	const tool = session.getToolByName?.(name);
+	if (!tool) {
+		throw new ToolError(`Unknown tool from js runtime: ${name}`);
+	}
+	return tool;
+}
+
+function normalizeArgs(args: unknown): unknown {
+	if (!args || typeof args !== "object" || Array.isArray(args)) {
+		return args;
+	}
+	const record = { ...(args as Record<string, unknown>) };
+	if (record._i === undefined) {
+		record._i = "js prelude";
+	}
+	return record;
+}
+
+function summarizeToolResult(
+	name: string,
+	args: unknown,
+	result: AgentToolResult,
+	text: string,
+	hasError: boolean,
+): JsStatusEvent {
+	const record = (args && typeof args === "object" ? (args as Record<string, unknown>) : {}) as Record<
+		string,
+		unknown
+	>;
+	const details = (
+		result.details && typeof result.details === "object" ? (result.details as Record<string, unknown>) : {}
+	) as Record<string, unknown>;
+	const withError = (event: JsStatusEvent): JsStatusEvent =>
+		hasError ? { ...event, hasError: true, error: text.slice(0, 500) } : event;
+
+	switch (name) {
+		case "read":
+			return withError({ op: "read", path: record.path, chars: text.length, preview: text.slice(0, 500) });
+		case "write":
+			return withError({
+				op: "write",
+				path: record.path,
+				chars: typeof record.content === "string" ? record.content.length : 0,
+			});
+		case "grep":
+			return withError({
+				op: "grep",
+				pattern: record.pattern,
+				path: record.path,
+				count: details.matchCount ?? undefined,
+			});
+		case "find":
+			return withError({
+				op: "find",
+				pattern: record.pattern,
+				count: details.fileCount ?? undefined,
+				matches: Array.isArray(details.files) ? details.files.slice(0, 20) : undefined,
+			});
+		case "bash":
+			return withError({
+				op: "run",
+				cmd: record.command,
+				code: typeof details.exitCode === "number" ? details.exitCode : undefined,
+				output: text.slice(0, 500),
+			});
+		default:
+			return withError({ op: name, chars: text.length });
+	}
+}
+
+export async function callSessionTool(name: string, args: unknown, options: ToolBridgeOptions): Promise<ToolValue> {
+	const tool = getTool(options.session, name);
+	const normalizedArgs = normalizeArgs(args);
+	const toolCallId = `js-${name}-${crypto.randomUUID()}`;
+	try {
+		const result = await tool.execute(toolCallId, normalizedArgs, options.signal);
+		const textBlocks = result.content.filter(
+			(content): content is { type: "text"; text: string } =>
+				content.type === "text" && typeof content.text === "string",
+		);
+		const imageBlocks = result.content.filter(
+			(content): content is { type: "image"; mimeType: string; data: string } =>
+				content.type === "image" && typeof content.mimeType === "string" && typeof content.data === "string",
+		);
+		const text = textBlocks.map(block => block.text).join("");
+		const hasError = toolResultHasError(result);
+		options.emitStatus?.(summarizeToolResult(name, normalizedArgs, result, text, hasError));
+		if (result.details === undefined && imageBlocks.length === 0 && !hasError) {
+			return text;
+		}
+		const value: Exclude<ToolValue, string> = {
+			text,
+			details: result.details,
+		};
+		if (imageBlocks.length > 0) {
+			value.images = imageBlocks.map(block => ({
+				mimeType: block.mimeType,
+				data: block.data,
+			}));
+		}
+		if (hasError) {
+			value.hasError = true;
+		}
+		return value;
+	} catch (error) {
+		options.emitStatus?.({
+			op: name,
+			error: error instanceof Error ? error.message : String(error),
+		});
+		throw error;
+	}
+}

package/src/eval/js/worker-core.ts

@@ -0,0 +1,146 @@
+import { ToolError } from "../../tools/tool-errors";
+import { JsRuntime, type RuntimeHooks } from "./shared/runtime";
+import type { RunErrorPayload, SessionSnapshot, ToolReply, Transport, WorkerInbound } from "./worker-protocol";
+
+interface PendingTool {
+	resolve(value: unknown): void;
+	reject(error: Error): void;
+}
+
+interface ActiveRun {
+	runId: string;
+	pendingTools: Map<string, PendingTool>;
+}
+
+function errorPayload(error: unknown): RunErrorPayload {
+	if (error instanceof Error) {
+		return {
+			name: error.name,
+			message: error.message,
+			stack: error.stack,
+			isAbort: error.name === "AbortError" || error.name === "ToolAbortError",
+			isToolError: error.name === "ToolError" || error instanceof ToolError,
+		};
+	}
+	return { message: String(error) };
+}
+
+function errorFromPayload(payload: RunErrorPayload): Error {
+	const ctor = payload.isToolError ? ToolError : Error;
+	const error = new ctor(payload.message);
+	if (payload.name) error.name = payload.name;
+	if (payload.stack) error.stack = payload.stack;
+	return error;
+}
+
+export class WorkerCore {
+	#transport: Transport;
+	#runtime: JsRuntime | null = null;
+	#queue: Promise<void> = Promise.resolve();
+	#active: ActiveRun | null = null;
+	#unsubscribe: () => void;
+
+	constructor(transport: Transport) {
+		this.#transport = transport;
+		this.#unsubscribe = transport.onMessage(msg => this.#handle(msg));
+		transport.send({ type: "ready" });
+	}
+
+	#handle(msg: WorkerInbound): void {
+		switch (msg.type) {
+			case "init":
+				this.#ensureRuntime(msg.snapshot);
+				return;
+			case "run":
+				this.#enqueueRun(msg.runId, msg.code, msg.filename, msg.snapshot);
+				return;
+			case "tool-reply":
+				this.#deliverToolReply(msg.id, msg.reply);
+				return;
+			case "close":
+				this.#close();
+				return;
+		}
+	}
+
+	#ensureRuntime(snapshot: SessionSnapshot): JsRuntime {
+		if (this.#runtime) {
+			this.#runtime.setCwd(snapshot.cwd);
+			return this.#runtime;
+		}
+		this.#runtime = new JsRuntime({
+			initialCwd: snapshot.cwd,
+			sessionId: snapshot.sessionId,
+			getHooks: () => this.#hooksForCurrentRun(),
+		});
+		return this.#runtime;
+	}
+
+	#hooksForCurrentRun(): RuntimeHooks | null {
+		const active = this.#active;
+		if (!active) return null;
+		const runId = active.runId;
+		return {
+			onText: chunk => this.#transport.send({ type: "text", runId, chunk }),
+			onDisplay: output => this.#transport.send({ type: "display", runId, output }),
+			callTool: (name, args) => this.#callTool(active, name, args),
+		};
+	}
+
+	#enqueueRun(runId: string, code: string, filename: string, snapshot: SessionSnapshot): void {
+		const previous = this.#queue;
+		const next = (async () => {
+			await previous.catch(() => undefined);
+			await this.#runOne(runId, code, filename, snapshot);
+		})();
+		this.#queue = next.catch(() => undefined);
+	}
+
+	async #runOne(runId: string, code: string, filename: string, snapshot: SessionSnapshot): Promise<void> {
+		const runtime = this.#ensureRuntime(snapshot);
+		runtime.setCwd(snapshot.cwd);
+		this.#active = { runId, pendingTools: new Map() };
+		try {
+			const value = await runtime.run(code, filename);
+			runtime.displayValue(value);
+			this.#transport.send({ type: "result", runId, ok: true });
+		} catch (error) {
+			this.#transport.send({ type: "result", runId, ok: false, error: errorPayload(error) });
+		} finally {
+			this.#active = null;
+		}
+	}
+
+	async #callTool(active: ActiveRun, name: string, args: unknown): Promise<unknown> {
+		const id = `tc-${active.runId}-${crypto.randomUUID()}`;
+		const { promise, resolve, reject } = Promise.withResolvers<unknown>();
+		active.pendingTools.set(id, { resolve, reject });
+		this.#transport.send({ type: "tool-call", id, runId: active.runId, name, args });
+		return await promise;
+	}
+
+	#deliverToolReply(id: string, reply: ToolReply): void {
+		const active = this.#active;
+		if (!active) return;
+		const pending = active.pendingTools.get(id);
+		if (!pending) return;
+		active.pendingTools.delete(id);
+		if (reply.ok) pending.resolve(reply.value);
+		else pending.reject(errorFromPayload(reply.error));
+	}
+
+	#close(): void {
+		const active = this.#active;
+		if (active) {
+			for (const pending of active.pendingTools.values()) {
+				pending.reject(new ToolError("JS worker closed"));
+			}
+			active.pendingTools.clear();
+		}
+		this.#active = null;
+		this.#runtime = null;
+		this.#transport.send({ type: "closed" });
+		this.#unsubscribe();
+		this.#transport.close();
+	}
+}

package/src/eval/js/worker-entry.ts

@@ -0,0 +1,24 @@
+import { parentPort } from "node:worker_threads";
+import { WorkerCore } from "./worker-core";
+import type { Transport, WorkerInbound, WorkerOutbound } from "./worker-protocol";
+
+if (!parentPort) throw new Error("js worker-entry: missing parentPort");
+
+const port = parentPort;
+const transport: Transport = {
+	send: (msg: WorkerOutbound) => port.postMessage(msg),
+	onMessage: handler => {
+		const wrap = (data: unknown): void => handler(data as WorkerInbound);
+		port.on("message", wrap);
+		return () => port.off("message", wrap);
+	},
+	close: () => {
+		try {
+			port.close();
+		} catch {
+			// Already closed.
+		}
+	},
+};
+
+new WorkerCore(transport);

package/src/eval/js/worker-protocol.ts

@@ -0,0 +1,41 @@
+import type { JsDisplayOutput } from "./shared/types";
+
+export type { JsDisplayOutput } from "./shared/types";
+
+export interface SessionSnapshot {
+	cwd: string;
+	sessionId: string;
+}
+
+export interface RunErrorPayload {
+	name?: string;
+	message: string;
+	stack?: string;
+	isAbort?: boolean;
+	isToolError?: boolean;
+}
+
+export type ToolReply = { ok: true; value: unknown } | { ok: false; error: RunErrorPayload };
+
+export type WorkerInbound =
+	| { type: "init"; snapshot: SessionSnapshot }
+	| { type: "run"; runId: string; code: string; filename: string; snapshot: SessionSnapshot }
+	| { type: "tool-reply"; id: string; reply: ToolReply }
+	| { type: "close" };
+
+export type WorkerOutbound =
+	| { type: "ready" }
+	| { type: "init-failed"; error: RunErrorPayload }
+	| { type: "text"; runId: string; chunk: string }
+	| { type: "display"; runId: string; output: JsDisplayOutput }
+	| { type: "tool-call"; id: string; runId: string; name: string; args: unknown }
+	| { type: "result"; runId: string; ok: true }
+	| { type: "result"; runId: string; ok: false; error: RunErrorPayload }
+	| { type: "log"; level: "debug" | "warn" | "error"; msg: string; meta?: Record<string, unknown> }
+	| { type: "closed" };
+
+export interface Transport {
+	send(msg: WorkerOutbound): void;
+	onMessage(handler: (msg: WorkerInbound) => void): () => void;
+	close(): void;
+}