@oh-my-pi/pi-coding-agent 15.10.3 → 15.10.5

package/src/eval/__tests__/js-context-manager.test.ts

@@ -0,0 +1,241 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { TempDir } from "@oh-my-pi/pi-utils";
+import { Settings } from "../../config/settings";
+import type { ToolSession } from "../../tools";
+import { disposeAllVmContexts } from "../js/context-manager";
+import { executeJs } from "../js/executor";
+
+const originalWorker = globalThis.Worker;
+
+interface FakeWorkerStats {
+	closeRequests: number;
+	terminateCalls: number;
+}
+
+interface FakeWorkerBehavior {
+	exitOnClose: boolean;
+	settleRuns: boolean;
+}
+
+function makeSession(cwd: string): ToolSession {
+	return {
+		cwd,
+		hasUI: false,
+		settings: Settings.isolated({
+			"async.enabled": false,
+			"task.isolation.mode": "none",
+			"task.enableLsp": true,
+		}),
+		taskDepth: 0,
+		enableLsp: true,
+		getSessionFile: () => null,
+		getSessionSpawns: () => "*",
+		getActiveModelString: () => "p/active",
+		getModelString: () => "p/fallback",
+		getArtifactsDir: () => null,
+		getSessionId: () => "test-session",
+		getEvalSessionId: () => "test-eval-session",
+	};
+}
+
+async function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+	let timeout: NodeJS.Timeout | undefined;
+	try {
+		return await Promise.race([
+			promise,
+			new Promise<never>((_, reject) => {
+				timeout = setTimeout(() => reject(new Error(`${label} timed out`)), ms);
+			}),
+		]);
+	} finally {
+		if (timeout) clearTimeout(timeout);
+	}
+}
+
+async function waitForRealWorkerExitAfterClose(cwd: string): Promise<void> {
+	const worker = new originalWorker(new URL("../js/worker-entry.ts", import.meta.url).href, { type: "module" });
+	const ready = Promise.withResolvers<void>();
+	const runComplete = Promise.withResolvers<void>();
+	const closedAck = Promise.withResolvers<void>();
+	const workerClosed = Promise.withResolvers<void>();
+	const runId = `keep-alive:${crypto.randomUUID()}`;
+	const snapshot = { cwd, sessionId: `worker-exit:${crypto.randomUUID()}` };
+
+	worker.addEventListener("message", event => {
+		const msg = event.data as { type?: string; runId?: string; ok?: boolean };
+		if (msg.type === "ready") ready.resolve();
+		else if (msg.type === "result" && msg.runId === runId && msg.ok) runComplete.resolve();
+		else if (msg.type === "closed") closedAck.resolve();
+	});
+	worker.addEventListener("close", () => workerClosed.resolve());
+
+	try {
+		await withTimeout(ready.promise, 1_000, "worker ready");
+		worker.postMessage({
+			type: "run",
+			runId,
+			code: "globalThis.__keepAlive = setInterval(() => {}, 1000);\nundefined;",
+			filename: "keep-alive.js",
+			snapshot,
+		});
+		await withTimeout(runComplete.promise, 1_000, "worker run");
+		worker.postMessage({ type: "close" });
+		await withTimeout(closedAck.promise, 1_000, "worker closed ack");
+		await withTimeout(workerClosed.promise, 1_000, "worker close event");
+	} finally {
+		worker.terminate();
+	}
+}
+
+function installFakeWorker(stats: FakeWorkerStats, behavior: FakeWorkerBehavior): void {
+	class FakeWorker {
+		#messageListeners = new Set<(event: MessageEvent) => void>();
+		#closeListeners = new Set<(event: Event) => void>();
+		#readyQueued = false;
+		#exited = false;
+
+		postMessage(message: unknown): void {
+			if (!message || typeof message !== "object") return;
+			const typed = message as { type?: string; runId?: string };
+			if (typed.type === "run" && typed.runId && behavior.settleRuns) {
+				queueMicrotask(() => this.#emitMessage({ type: "result", runId: typed.runId, ok: true }));
+				return;
+			}
+			if (typed.type === "close") {
+				stats.closeRequests++;
+				queueMicrotask(() => {
+					this.#emitMessage({ type: "closed" });
+					if (behavior.exitOnClose) this.#emitClose();
+				});
+			}
+		}
+
+		addEventListener(type: string, listener: (event: MessageEvent | Event) => void): void {
+			if (type === "close") {
+				this.#closeListeners.add(listener as (event: Event) => void);
+				return;
+			}
+			if (type !== "message") return;
+			this.#messageListeners.add(listener as (event: MessageEvent) => void);
+			if (!this.#readyQueued) {
+				this.#readyQueued = true;
+				queueMicrotask(() => this.#emitMessage({ type: "ready" }));
+			}
+		}
+
+		removeEventListener(type: string, listener: (event: MessageEvent | Event) => void): void {
+			if (type === "close") {
+				this.#closeListeners.delete(listener as (event: Event) => void);
+				return;
+			}
+			if (type !== "message") return;
+			this.#messageListeners.delete(listener as (event: MessageEvent) => void);
+		}
+
+		terminate(): void {
+			stats.terminateCalls++;
+			this.#emitClose();
+		}
+
+		#emitMessage(data: unknown): void {
+			const event = new MessageEvent("message", { data });
+			for (const listener of this.#messageListeners) listener(event);
+		}
+
+		#emitClose(): void {
+			if (this.#exited) return;
+			this.#exited = true;
+			const event = new Event("close");
+			for (const listener of this.#closeListeners) listener(event);
+		}
+	}
+
+	Object.defineProperty(globalThis, "Worker", {
+		configurable: true,
+		writable: true,
+		value: FakeWorker as unknown as typeof Worker,
+	});
+}
+
+describe("JavaScript eval worker lifecycle", () => {
+	afterEach(async () => {
+		await disposeAllVmContexts();
+		Object.defineProperty(globalThis, "Worker", {
+			configurable: true,
+			writable: true,
+			value: originalWorker,
+		});
+	});
+
+	it("exits a real worker on graceful close even with ref'ed user handles", async () => {
+		using tempDir = TempDir.createSync("@omp-js-worker-real-close-");
+
+		await waitForRealWorkerExitAfterClose(tempDir.path());
+	});
+
+	it("waits for the worker to close on reset instead of force-terminating it", async () => {
+		using tempDir = TempDir.createSync("@omp-js-worker-close-");
+		const stats: FakeWorkerStats = { closeRequests: 0, terminateCalls: 0 };
+		installFakeWorker(stats, { exitOnClose: true, settleRuns: true });
+
+		const session = makeSession(tempDir.path());
+		const sessionId = `js-close:${crypto.randomUUID()}`;
+
+		const first = await executeJs("globalThis.marker = 1;", { cwd: tempDir.path(), sessionId, session });
+		expect(first.exitCode).toBe(0);
+
+		const second = await executeJs("globalThis.marker = 2;", {
+			cwd: tempDir.path(),
+			sessionId,
+			session,
+			reset: true,
+		});
+		expect(second.exitCode).toBe(0);
+		expect(stats.closeRequests).toBe(1);
+		expect(stats.terminateCalls).toBe(0);
+	});
+
+	it("terminates when close is acknowledged but the worker does not exit", async () => {
+		using tempDir = TempDir.createSync("@omp-js-worker-close-hung-");
+		const stats: FakeWorkerStats = { closeRequests: 0, terminateCalls: 0 };
+		installFakeWorker(stats, { exitOnClose: false, settleRuns: true });
+
+		const session = makeSession(tempDir.path());
+		const sessionId = `js-close-hung:${crypto.randomUUID()}`;
+
+		const first = await executeJs("globalThis.marker = 1;", { cwd: tempDir.path(), sessionId, session });
+		expect(first.exitCode).toBe(0);
+
+		const second = await executeJs("globalThis.marker = 2;", {
+			cwd: tempDir.path(),
+			sessionId,
+			session,
+			reset: true,
+		});
+		expect(second.exitCode).toBe(0);
+		expect(stats.closeRequests).toBe(1);
+		expect(stats.terminateCalls).toBe(1);
+	});
+
+	it("force-terminates instead of closing when an in-flight run is aborted", async () => {
+		using tempDir = TempDir.createSync("@omp-js-worker-abort-");
+		const stats: FakeWorkerStats = { closeRequests: 0, terminateCalls: 0 };
+		installFakeWorker(stats, { exitOnClose: true, settleRuns: false });
+
+		const session = makeSession(tempDir.path());
+		const sessionId = `js-abort:${crypto.randomUUID()}`;
+		const controller = new AbortController();
+		const resultPromise = executeJs("globalThis.neverFinishes = true;", {
+			cwd: tempDir.path(),
+			sessionId,
+			session,
+			signal: controller.signal,
+		});
+		setTimeout(() => controller.abort(new DOMException("Execution aborted", "AbortError")), 0);
+
+		const result = await resultPromise;
+		expect(result.cancelled).toBe(true);
+		expect(stats.closeRequests).toBe(0);
+		expect(stats.terminateCalls).toBe(1);
+	});
+});

package/src/eval/agent-bridge.ts

@@ -272,7 +272,12 @@ export async function runEvalAgent(args: unknown, options: EvalAgentBridgeOption
 			persistArtifacts: Boolean(sessionFile),
 			artifactsDir,
 			contextFile,
-			enableLsp: (options.session.enableLsp ?? true) && options.session.settings.get("task.enableLsp"),
+			// Eval `agent()` subagents are short-lived programmatic helpers (data
+			// collection, structured output, parallel() fan-out). LSP server
+			// cold-start costs tens of seconds and is pure overhead here, so it is
+			// forced off regardless of the `task.enableLsp` setting — that knob only
+			// governs LSP-aware delegation through the `task` tool.
+			enableLsp: false,
 			signal: options.signal,
 			eventBus: options.session.eventBus,
 			onProgress: progress => emitProgressStatus(options.emitStatus, progress),

package/src/eval/backend.ts

@@ -1,3 +1,4 @@
+import { buildEvalUrlRoots, type LocalProtocolOptions } from "../internal-urls";
 import type { ToolSession } from "../tools";
 import type { EvalDisplayOutput, EvalLanguage, EvalStatusEvent } from "./types";
 
@@ -56,3 +57,17 @@ export interface ExecutorBackend {
 	/** Execute one cell. Caller invokes once per cell and aggregates results. */
 	execute(code: string, opts: ExecutorBackendExecOptions): Promise<ExecutorBackendResult>;
 }
+
+/**
+ * Resolve the on-disk roots that the eval helpers substitute for internal-URL
+ * schemes (currently `local://`). Prefers the session's own
+ * {@link LocalProtocolOptions} — the exact mapping `read local://…` uses — so an
+ * eval `write("local://x")` and a later `read local://x` agree on the location.
+ */
+export function resolveEvalUrlRoots(session: ToolSession): Record<string, string> {
+	const options: LocalProtocolOptions = session.localProtocolOptions ?? {
+		getArtifactsDir: () => session.getArtifactsDir?.() ?? null,
+		getSessionId: () => session.getSessionId?.() ?? null,
+	};
+	return buildEvalUrlRoots(options);
+}

package/src/eval/bridge-timeout.ts

@@ -2,7 +2,7 @@
  * Timeout suspension for in-flight host-side eval bridge calls.
  *
  * The eval watchdog caps a cell's `timeout` as a budget on the cell runtime's
- * own work. Host-side `agent()` / `parallel()` / `llm()` bridge calls hand
+ * own work. Host-side `agent()` / `parallel()` / `completion()` bridge calls hand
  * control to the outer TypeScript process, where the Python kernel or JS VM is
  * only waiting for a result. While that delegated work is in flight, the cell
  * timeout must be ignored completely; once the bridge returns and the runtime is

package/src/eval/{llm-bridge.ts → completion-bridge.ts}

@@ -1,11 +1,11 @@
 /**
- * Host-side handler for the eval `llm()` helper.
+ * Host-side handler for the eval `completion()` helper.
  *
  * Both eval runtimes (JS worker + Python kernel) route helper→host calls
  * through {@link callSessionTool}. Reserving the synthetic tool name
- * {@link EVAL_LLM_BRIDGE_NAME} lets a single host handler serve both
+ * {@link EVAL_COMPLETION_BRIDGE_NAME} lets a single host handler serve both
  * transports without registering an agent-visible tool: cell code calls
- * `llm(prompt, opts)`, the prelude forwards `{ prompt, model, system?, schema? }`
+ * `completion(prompt, opts)`, the prelude forwards `{ prompt, model, system?, schema? }`
  * through the bridge, and this module performs one stateless completion.
  *
  * The call is oneshot and toolless from the model's perspective — pure text
@@ -27,36 +27,36 @@ import { ToolError } from "../tools/tool-errors";
 import { withBridgeTimeoutPause } from "./bridge-timeout";
 import type { JsStatusEvent } from "./js/shared/types";
 
-/** Synthetic bridge name reserved for the `llm()` helper across both runtimes. */
-export const EVAL_LLM_BRIDGE_NAME = "__llm__";
+/** Synthetic bridge name reserved for the `completion()` helper across both runtimes. */
+export const EVAL_COMPLETION_BRIDGE_NAME = "__completion__";
 
 /** Synthetic tool the model is forced to call when a `schema` is supplied. */
 const STRUCTURED_TOOL_NAME = "respond";
 
-type LlmTier = "smol" | "default" | "slow";
+type CompletionTier = "smol" | "default" | "slow";
 
-const TIER_TO_PATTERN: Record<LlmTier, string> = {
+const TIER_TO_PATTERN: Record<CompletionTier, string> = {
 	smol: "pi/smol",
 	default: "pi/default",
 	slow: "pi/slow",
 };
 
-const llmArgsSchema = z.object({
+const completionArgsSchema = z.object({
 	prompt: z.string().min(1, "prompt must be a non-empty string"),
 	model: z.enum(["smol", "default", "slow"]).default("default"),
 	system: z.string().optional(),
 	schema: z.record(z.string(), z.unknown()).optional(),
 });
 
-export interface EvalLlmBridgeOptions {
+export interface EvalCompletionBridgeOptions {
 	session: ToolSession;
 	signal?: AbortSignal;
 	emitStatus?: (event: JsStatusEvent) => void;
 }
 
-export interface EvalLlmResult {
+export interface EvalCompletionResult {
 	text: string;
-	details: { model: string; tier: LlmTier; structured: boolean };
+	details: { model: string; tier: CompletionTier; structured: boolean };
 }
 
 /**
@@ -64,7 +64,7 @@ export interface EvalLlmResult {
  * active model and falls back to the `pi/default` role; `smol`/`slow` resolve
  * their respective role patterns. Returns `undefined` when nothing matches.
  */
-function resolveTierModel(tier: LlmTier, session: ToolSession): Model<Api> | undefined {
+function resolveTierModel(tier: CompletionTier, session: ToolSession): Model<Api> | undefined {
 	const modelRegistry = session.modelRegistry;
 	if (!modelRegistry) return undefined;
 	const available = modelRegistry.getAvailable();
@@ -90,7 +90,7 @@ function resolveTierModel(tier: LlmTier, session: ToolSession): Model<Api> | und
  * throwing downstream on models that cannot reason. Clamps to the highest
  * supported effort so a reasoning model without `high` does not 400.
  */
-function reasoningForTier(tier: LlmTier, model: Model<Api>): Effort | undefined {
+function reasoningForTier(tier: CompletionTier, model: Model<Api>): Effort | undefined {
 	if (tier !== "slow" || !model.reasoning) return undefined;
 	const efforts = getSupportedEfforts(model);
 	if (efforts.length === 0) return undefined;
@@ -98,23 +98,26 @@ function reasoningForTier(tier: LlmTier, model: Model<Api>): Effort | undefined
 }
 
 /**
- * Run a single stateless completion on behalf of an eval cell's `llm()` call.
+ * Run a single stateless completion on behalf of an eval cell's `completion()` call.
  * Returns a `{ text, details }` value shaped like a {@link callSessionTool}
  * result so the existing bridge transport carries it to either runtime.
  */
-export async function runEvalLlm(args: unknown, options: EvalLlmBridgeOptions): Promise<EvalLlmResult> {
-	const parsed = llmArgsSchema.safeParse(args);
+export async function runEvalCompletion(
+	args: unknown,
+	options: EvalCompletionBridgeOptions,
+): Promise<EvalCompletionResult> {
+	const parsed = completionArgsSchema.safeParse(args);
 	if (!parsed.success) {
 		const issue = parsed.error.issues[0];
 		const where = issue?.path.length ? `${issue.path.join(".")}: ` : "";
-		throw new ToolError(`llm() received invalid arguments: ${where}${issue?.message ?? "bad input"}`);
+		throw new ToolError(`completion() received invalid arguments: ${where}${issue?.message ?? "bad input"}`);
 	}
 	const { prompt, model: tier, system, schema } = parsed.data;
 
 	const model = resolveTierModel(tier, options.session);
 	if (!model) {
 		throw new ToolError(
-			`llm() could not resolve a model for the "${tier}" tier. Configure modelRoles.${tier === "default" ? "default" : tier} or ensure a provider is available.`,
+			`completion() could not resolve a model for the "${tier}" tier. Configure modelRoles.${tier === "default" ? "default" : tier} or ensure a provider is available.`,
 		);
 	}
 
@@ -122,7 +125,7 @@ export async function runEvalLlm(args: unknown, options: EvalLlmBridgeOptions):
 	const apiKey = await registry?.getApiKey(model);
 	if (!registry || !apiKey) {
 		throw new ToolError(
-			`llm() has no API key for ${formatModelString(model)}. Configure credentials for this provider or choose another tier.`,
+			`completion() has no API key for ${formatModelString(model)}. Configure credentials for this provider or choose another tier.`,
 		);
 	}
 
@@ -141,7 +144,7 @@ export async function runEvalLlm(args: unknown, options: EvalLlmBridgeOptions):
 
 	// Some providers (notably openai-codex) require a non-empty `instructions`
 	// field on every Responses request and 400 with "Instructions are required"
-	// when it is missing. Fall back to a minimal default so `llm(prompt)` works
+	// when it is missing. Fall back to a minimal default so `completion(prompt)` works
 	// without forcing every caller to pass a `system` prompt.
 	const systemPrompt = system ? [system] : ["You are a helpful assistant."];
 
@@ -164,15 +167,15 @@ export async function runEvalLlm(args: unknown, options: EvalLlmBridgeOptions):
 				reasoning: reasoningForTier(tier, model),
 				toolChoice: schema ? { type: "tool", name: STRUCTURED_TOOL_NAME } : undefined,
 			},
-			{ telemetry, oneshotKind: "eval_llm" },
+			{ telemetry, oneshotKind: "eval_completion" },
 		),
 	);
 
 	if (response.stopReason === "error") {
-		throw new ToolError(response.errorMessage ?? "llm() request failed.");
+		throw new ToolError(response.errorMessage ?? "completion() request failed.");
 	}
 	if (response.stopReason === "aborted") {
-		throw new ToolError("llm() request aborted.");
+		throw new ToolError("completion() request aborted.");
 	}
 
 	let resultText: string;
@@ -183,20 +186,20 @@ export async function runEvalLlm(args: unknown, options: EvalLlmBridgeOptions):
 			value = call.arguments;
 		} else {
 			const text = extractTextContent(response);
-			if (!text) throw new ToolError("llm() returned no structured response.");
+			if (!text) throw new ToolError("completion() returned no structured response.");
 			try {
 				value = parseJsonPayload(text);
 			} catch {
-				throw new ToolError("llm() did not return a structured response matching the schema.");
+				throw new ToolError("completion() did not return a structured response matching the schema.");
 			}
 		}
 		resultText = JSON.stringify(value);
 	} else {
 		resultText = extractTextContent(response);
-		if (!resultText) throw new ToolError("llm() returned no text output.");
+		if (!resultText) throw new ToolError("completion() returned no text output.");
 	}
 
-	options.emitStatus?.({ op: "llm", model: formatModelString(model), tier, chars: resultText.length });
+	options.emitStatus?.({ op: "completion", model: formatModelString(model), tier, chars: resultText.length });
 
 	return { text: resultText, details: { model: formatModelString(model), tier, structured: Boolean(schema) } };
 }

package/src/eval/idle-timeout.ts

@@ -3,7 +3,7 @@
  *
  * A cell's `timeout` bounds time while the Python kernel or JS VM is in control.
  * Host-side bridge calls can {@link pause} the watchdog so delegated
- * `agent()`/`parallel()`/`llm()` work is ignored completely, then {@link resume}
+ * `agent()`/`parallel()`/`completion()` work is ignored completely, then {@link resume}
  * starts a fresh timeout window once the runtime gets control back.
  *
  * The active timer self-reschedules instead of being torn down on every

package/src/eval/js/context-manager.ts

@@ -30,6 +30,7 @@ interface WorkerHandle {
 	mode: "worker" | "inline";
 	send(msg: WorkerInbound): void;
 	onMessage(handler: (msg: WorkerOutbound) => void): () => void;
+	close(): Promise<boolean>;
 	terminate(): Promise<void>;
 }
 
@@ -60,12 +61,14 @@ const resettingSessions = new Map<string, Promise<void>>();
 // avoiding `vm.runInContext` (see shared/indirect-eval.ts), here surfacing as a
 // SIGILL/SIGSEGV. Callers that pass a larger per-cell budget still dominate.
 const WORKER_INIT_TIMEOUT_MS = 15_000;
+const WORKER_CLOSE_TIMEOUT_MS = 1_000;
 
 export async function executeInVmContext(options: {
 	sessionKey: string;
 	sessionId: string;
 	cwd: string;
 	session: ToolSession;
+	localRoots?: Record<string, string>;
 	reset?: boolean;
 	code: string;
 	filename: string;
@@ -98,7 +101,7 @@ export async function executeInVmContext(options: {
 	}
 	const session = await acquireSession(
 		options.sessionKey,
-		{ cwd: options.cwd, sessionId: options.sessionId },
+		{ cwd: options.cwd, sessionId: options.sessionId, localRoots: options.localRoots },
 		options.timeoutMs,
 	);
 	return await runOnce(session, options);
@@ -108,7 +111,7 @@ export async function resetVmContext(sessionKey: string): Promise<void> {
 	const session = sessions.get(sessionKey) ?? (await startingSessions.get(sessionKey)?.catch(() => undefined));
 	if (!session) return;
 	sessions.delete(sessionKey);
-	await killSession(session, new ToolError("JS context reset"));
+	await killSession(session, new ToolError("JS context reset"), { force: false });
 }
 
 export async function disposeAllVmContexts(): Promise<void> {
@@ -121,7 +124,7 @@ export async function disposeAllVmContexts(): Promise<void> {
 		if (!all.includes(result.value)) all.push(result.value);
 	}
 	sessions.clear();
-	await Promise.all(all.map(session => killSession(session, new ToolError("JS context disposed"))));
+	await Promise.all(all.map(session => killSession(session, new ToolError("JS context disposed"), { force: false })));
 }
 
 async function runOnce(
@@ -130,6 +133,7 @@ async function runOnce(
 		sessionId: string;
 		cwd: string;
 		session: ToolSession;
+		localRoots?: Record<string, string>;
 		code: string;
 		filename: string;
 		runState: VmRunState;
@@ -154,7 +158,7 @@ async function runOnce(
 		// Cancel any in-flight tool calls first.
 		for (const ctrl of pending.toolCalls.values()) ctrl.abort(abortError);
 		// Hard-kill the worker — only way to interrupt synchronous user code.
-		void killSessionFor(session, abortError);
+		void killSessionFor(session, abortError, { force: true });
 	};
 
 	if (options.runState.signal?.aborted) {
@@ -169,7 +173,7 @@ async function runOnce(
 			runId,
 			code: options.code,
 			filename: options.filename,
-			snapshot: { cwd: options.cwd, sessionId: options.sessionId },
+			snapshot: { cwd: options.cwd, sessionId: options.sessionId, localRoots: options.localRoots },
 		});
 		return await promise;
 	} finally {
@@ -294,14 +298,14 @@ function settlePending(session: JsSession, msg: Extract<WorkerOutbound, { type:
 	pending.reject(errorFromPayload(msg.error));
 }
 
-async function killSessionFor(session: JsSession, error: Error): Promise<void> {
+async function killSessionFor(session: JsSession, error: Error, options: { force: boolean }): Promise<void> {
 	if (sessions.get(session.sessionKey) === session) {
 		sessions.delete(session.sessionKey);
 	}
-	await killSession(session, error);
+	await killSession(session, error, options);
 }
 
-async function killSession(session: JsSession, error: Error): Promise<void> {
+async function killSession(session: JsSession, error: Error, options: { force: boolean }): Promise<void> {
 	if (session.state === "dead") return;
 	session.state = "dead";
 	for (const pending of session.pending.values()) {
@@ -311,6 +315,11 @@ async function killSession(session: JsSession, error: Error): Promise<void> {
 		pending.reject(error);
 	}
 	session.pending.clear();
+	if (options.force) {
+		await session.worker.terminate().catch(() => undefined);
+		return;
+	}
+	if (await session.worker.close().catch(() => false)) return;
 	await session.worker.terminate().catch(() => undefined);
 }
 
@@ -398,6 +407,38 @@ function wrapBunWorker(worker: Worker): WorkerHandle {
 			worker.addEventListener("message", wrap);
 			return () => worker.removeEventListener("message", wrap);
 		},
+		async close() {
+			const { promise: closed, resolve } = Promise.withResolvers<boolean>();
+			let settled = false;
+			let sawClosedAck = false;
+			let sawWorkerExit = false;
+			let timeout: NodeJS.Timeout | undefined;
+			let unsubscribe = (): void => {};
+			const finish = (value: boolean): void => {
+				if (settled) return;
+				settled = true;
+				if (timeout) clearTimeout(timeout);
+				unsubscribe();
+				worker.removeEventListener("close", onClose);
+				resolve(value);
+			};
+			const finishIfClosed = (): void => {
+				if (sawClosedAck && sawWorkerExit) finish(true);
+			};
+			const onClose = (): void => {
+				sawWorkerExit = true;
+				finishIfClosed();
+			};
+			unsubscribe = this.onMessage(msg => {
+				if (msg.type !== "closed") return;
+				sawClosedAck = true;
+				finishIfClosed();
+			});
+			worker.addEventListener("close", onClose);
+			timeout = setTimeout(() => finish(false), WORKER_CLOSE_TIMEOUT_MS);
+			worker.postMessage({ type: "close" } satisfies WorkerInbound);
+			return await closed;
+		},
 		async terminate() {
 			worker.terminate();
 		},
@@ -434,6 +475,27 @@ function spawnInlineWorker(): WorkerHandle {
 			hostListeners.add(handler);
 			return () => hostListeners.delete(handler);
 		},
+		async close() {
+			const { promise: closed, resolve } = Promise.withResolvers<boolean>();
+			let settled = false;
+			let timeout: NodeJS.Timeout | undefined;
+			let unsubscribe = (): void => {};
+			const finish = (value: boolean): void => {
+				if (settled) return;
+				settled = true;
+				if (timeout) clearTimeout(timeout);
+				unsubscribe();
+				hostListeners.clear();
+				workerListeners.clear();
+				resolve(value);
+			};
+			unsubscribe = this.onMessage(msg => {
+				if (msg.type === "closed") finish(true);
+			});
+			this.send({ type: "close" });
+			timeout = setTimeout(() => finish(false), WORKER_CLOSE_TIMEOUT_MS);
+			return await closed;
+		},
 		async terminate() {
 			hostListeners.clear();
 			workerListeners.clear();

package/src/eval/js/executor.ts

@@ -24,6 +24,8 @@ export interface JsExecutorOptions {
 	artifactPath?: string;
 	artifactId?: string;
 	session: ToolSession;
+	/** On-disk roots the helpers substitute for internal-URL schemes (e.g. `local://`). */
+	localRoots?: Record<string, string>;
 }
 
 export interface JsResult {
@@ -96,6 +98,7 @@ export async function executeJs(code: string, options: JsExecutorOptions): Promi
 			sessionId: options.sessionId,
 			cwd: options.cwd ?? options.session.cwd,
 			session: options.session,
+			localRoots: options.localRoots,
 			reset: options.reset,
 			code,
 			filename: `js-cell-${crypto.randomUUID()}.js`,

package/src/eval/js/index.ts

@@ -1,5 +1,10 @@
 import type { ToolSession } from "../../tools";
-import type { ExecutorBackend, ExecutorBackendExecOptions, ExecutorBackendResult } from "../backend";
+import {
+	type ExecutorBackend,
+	type ExecutorBackendExecOptions,
+	type ExecutorBackendResult,
+	resolveEvalUrlRoots,
+} from "../backend";
 import { executeJs } from "./executor";
 
 const JS_SESSION_PREFIX = "js:";
@@ -30,6 +35,7 @@ export default {
 			onChunk: opts.onChunk,
 			onStatus: opts.onStatus,
 			session: opts.session,
+			localRoots: resolveEvalUrlRoots(opts.session),
 		});
 		return {
 			output: result.output,