@code-yeongyu/senpi-codemode 2026.10.7 → 2026.10.9

package/src/kernels/sandbox/vendor/pi-codemode/runtime/worker.ts

@@ -0,0 +1,231 @@
+// Vendored from https://github.com/earendil-works/pi (packages/codemode/src) at v1.0.1, commit a7229ddc21810d6245105978033b7df645ecc2f7.
+// MIT license; see LICENSE beside this file. Local changes are listed in VENDORED.md.
+/**
+ * Worker thread entry. One worker runs one script inside a fresh QuickJS VM
+ * (a separate wasm instance), relays tool calls and output to the host, and
+ * reports the result. The host terminates the worker when the script settles,
+ * times out, or is aborted; the worker exists so that a spinning script never
+ * blocks the host thread.
+ *
+ * Importing this module starts the worker. Hosts that bundle their code (for
+ * example a Bun compiled executable) add a file that imports
+ * `@earendil-works/pi-codemode/worker` as a separate entrypoint and pass its URL
+ * or embedded-module string specifier as `workerUrl`.
+ */
+import { parentPort, workerData } from "node:worker_threads";
+import { JSException, type JSValueHandle, MAX_STACK_SIZE, QuickJS } from "quickjs-wasi";
+import { PRELUDE_SOURCE } from "./prelude-source.ts";
+import { isHostToWorkerMessage, type WorkerData, type WorkerToHostMessage } from "./protocol.ts";
+
+function post(message: WorkerToHostMessage): void {
+	parentPort?.postMessage(message);
+}
+
+function crash(error: unknown): void {
+	post({ type: "crash", message: error instanceof Error ? `${error.name}: ${error.message}` : String(error) });
+}
+
+/**
+ * QuickJS writes engine diagnostics to fd 1 and 2, which the default shim
+ * forwards to the host's stdout and stderr. That output belongs to the host
+ * application (for example a TUI), so it is discarded. Reporting every byte as
+ * written keeps libc from retrying.
+ */
+function discardOutput(memory: { readonly buffer: ArrayBufferLike }) {
+	return {
+		fd_write(_fd: number, iovsPtr: number, iovsLen: number, nwrittenPtr: number): number {
+			const view = new DataView(memory.buffer);
+			let written = 0;
+			for (let i = 0; i < iovsLen; i++) {
+				written += view.getUint32(iovsPtr + i * 8 + 4, true);
+			}
+			view.setUint32(nwrittenPtr, written, true);
+			return 0;
+		},
+	};
+}
+
+function describeException(error: JSException): string {
+	const head = error.message ? `${error.name}: ${error.message}` : error.name;
+	const stack = error.stack?.trimEnd();
+	return JSON.stringify({ name: error.name, message: error.message, stack: stack ? `${head}\n${stack}` : head });
+}
+// senpi-change begin: output streaming
+/**
+ * Sends one output item as frames of at most `frameBytes` UTF-16 bytes, each only after taking that many bytes
+ * of credit. With no credit left the worker sleeps until the host consumes a frame or interrupts the run, so
+ * neither side ever holds more than the window. Returns false when the run was interrupted while waiting.
+ */
+function streamItem(
+	stream: { credits: Int32Array; frameBytes: number },
+	interrupt: Int32Array,
+	itemId: number,
+	type: "text" | "image",
+	payload: string,
+	mimeType: string | undefined,
+): boolean {
+	const frameUnits = Math.max(1, Math.floor(stream.frameBytes / 2));
+	let offset = 0;
+	let seq = 0;
+	do {
+		let end = Math.min(payload.length, offset + frameUnits);
+		// Never split a surrogate pair across frames.
+		if (end < payload.length && end - offset > 1) {
+			const last = payload.charCodeAt(end - 1);
+			if (last >= 0xd800 && last <= 0xdbff) end--;
+		}
+		const chunk = payload.slice(offset, end);
+		const bytes = Math.max(2, chunk.length * 2);
+		for (;;) {
+			if (Atomics.load(interrupt, 0) !== 0) return false;
+			const available = Atomics.load(stream.credits, 0);
+			if (available >= bytes) {
+				if (Atomics.compareExchange(stream.credits, 0, available, available - bytes) === available) break;
+				continue;
+			}
+			Atomics.wait(stream.credits, 0, available);
+		}
+		post({
+			type: "output-frame",
+			bytes,
+			frame: {
+				itemId,
+				seq,
+				final: end >= payload.length,
+				type,
+				chunk,
+				...(mimeType === undefined ? {} : { mimeType }),
+			},
+		});
+		offset = end;
+		seq++;
+	} while (offset < payload.length);
+	return true;
+}
+// senpi-change end
+
+async function main(data: WorkerData): Promise<void> {
+	const interrupt = new Int32Array(data.interrupt);
+	// senpi-change begin: output streaming
+	const stream =
+		data.stream === undefined
+			? undefined
+			: { credits: new Int32Array(data.stream.credits), frameBytes: data.stream.frameBytes };
+	let nextItemId = 0;
+	// senpi-change end
+	const vm = await QuickJS.create({
+		wasm: data.wasm,
+		memoryLimit: data.memoryLimitBytes,
+		// Without a guard, deep recursion overflows the wasm stack and traps instead of throwing a
+		// catchable RangeError.
+		maxStackSize: MAX_STACK_SIZE,
+		interruptHandler: () => Atomics.load(interrupt, 0) !== 0,
+		wasi: discardOutput,
+	});
+
+	// Called from the prelude with primitives only.
+	const bridge = vm.newFunction("bridge", (kind, a, b, c) => {
+		switch (kind.toString()) {
+			case "call":
+			case "global":
+				post({
+					type: "call",
+					id: a.toNumber(),
+					target: kind.toString() === "call" ? "tool" : "global",
+					name: b.toString(),
+					args: c === undefined || c.isUndefined ? undefined : c.toString(),
+				});
+				break;
+			case "output":
+				// senpi-change begin: output streaming
+				if (stream !== undefined) {
+					const image = a.toString() === "image";
+					streamItem(stream, interrupt, nextItemId++, image ? "image" : "text", b.toString(), image ? c.toString() : undefined);
+					break;
+				}
+				// senpi-change end
+				post({
+					type: "output",
+					item:
+						a.toString() === "image"
+							? { type: "image", data: b.toString(), mimeType: c.toString() }
+							: { type: "text", text: b.toString() },
+				});
+				break;
+			case "done":
+				if (a.toBoolean()) {
+					post({
+						type: "done",
+						ok: true,
+						value: b === undefined || b.isUndefined ? undefined : b.toString(),
+						writes: c.toString(),
+					});
+				} else {
+					post({ type: "done", ok: false, error: b.toString() });
+				}
+				break;
+		}
+		return vm.undefined;
+	});
+
+	// The VM lives until the host terminates the worker, so these handles are never disposed.
+	const api = vm.withScope((scope) =>
+		scope.escape(
+			vm.callFunction(
+				vm.evalCode(PRELUDE_SOURCE, "codemode-prelude.js"),
+				vm.undefined,
+				bridge,
+				vm.newString(JSON.stringify(data.tools)),
+				vm.newString(JSON.stringify(data.globals)),
+				vm.newString(JSON.stringify(data.store)),
+				// senpi-change begin: output streaming and builtin policy
+				vm.newString(JSON.stringify({ streamOutput: stream !== undefined, store: data.storePolicy ?? "collect" })),
+				// senpi-change end
+			),
+		),
+	);
+	const settle = api.getProp("settle");
+	const run = api.getProp("run");
+	const stalled = api.getProp("stalled");
+	/** Run queued jobs, then fail a script that waits on nothing that can ever resume it. */
+	const drain = () => {
+		vm.executePendingJobs();
+		vm.callFunction(stalled, api).dispose();
+	};
+
+	parentPort?.on("message", (message: unknown) => {
+		if (!isHostToWorkerMessage(message)) return;
+		try {
+			vm.withScope(() => {
+				vm.callFunction(
+					settle,
+					api,
+					vm.newNumber(message.id),
+					message.ok ? vm.true : vm.false,
+					message.payload === undefined ? vm.undefined : vm.newString(message.payload),
+				);
+			});
+			drain();
+		} catch (error) {
+			crash(error);
+		}
+	});
+
+	// The prefix shares the first line with the script so reported line numbers
+	// match the script as written.
+	let fn: JSValueHandle;
+	try {
+		fn = vm.evalCode(`(async (tools, console) => {${data.code}\n})`, "codemode.js");
+	} catch (error) {
+		if (!(error instanceof JSException)) throw error;
+		post({ type: "done", ok: false, error: describeException(error) });
+		return;
+	}
+	vm.callFunction(run, api, fn).dispose();
+	fn.dispose();
+	drain();
+}
+
+if (parentPort) {
+	main(workerData as WorkerData).catch(crash);
+}

package/src/kernels/sandbox/vendor/pi-codemode/types.ts

@@ -0,0 +1,185 @@
+// Vendored from https://github.com/earendil-works/pi (packages/codemode/src) at v1.0.1, commit a7229ddc21810d6245105978033b7df645ecc2f7.
+// MIT license; see LICENSE beside this file. Local changes are listed in VENDORED.md.
+import type { CodemodeWasmModule } from "./wasm.ts";
+
+export interface CodemodeToolContext {
+	/**
+	 * Aborted when the script finishes (including unawaited calls), the
+	 * execution times out, the caller aborts, or the sandbox is closed.
+	 */
+	signal: AbortSignal;
+}
+
+/** A JSON Schema document. Only used to render declarations; values are not validated against it. */
+export type CodemodeJsonSchema = { [key: string]: unknown } | boolean;
+
+export interface CodemodeTool {
+	/**
+	 * The script calls tools as `tools.<id>(args)`, where `<id>` is the name with characters that
+	 * are not valid in identifiers replaced by `_` (see `toCodemodeIdentifier`), and also as
+	 * `tools["<name>"](args)`. Globals are called as `<name>(args)` and must be identifiers, or
+	 * `<namespace>.<member>`, which groups them into a frozen namespace object.
+	 */
+	name: string;
+	/** Shown as a doc comment in {@link renderDeclarations}, and listed in `ALL_TOOLS` for tools. */
+	description?: string;
+	/** Schema of the single argument. Rendered as the parameter type; `unknown` when omitted. */
+	inputSchema?: CodemodeJsonSchema;
+	/** Schema of the resolved value. Rendered as the promise type; `unknown` when omitted. */
+	outputSchema?: CodemodeJsonSchema;
+	/** Globals only: `execute` receives all call arguments as an array instead of the first one. */
+	spread?: boolean;
+	/**
+	 * Globals only: TypeScript parameter list and return type for {@link renderDeclarations}, for
+	 * example `(type: string, id?: string): Promise<Model[]>`. Replaces the rendering from the schemas.
+	 */
+	signature?: string;
+	/**
+	 * `args` is whatever the script passed, after a JSON round trip. The return
+	 * value must be JSON-serializable; a thrown error surfaces in the script as
+	 * an `Error` with the same message.
+	 */
+	execute(args: unknown, context: CodemodeToolContext): Promise<unknown> | unknown;
+}
+
+/**
+ * One item of the script's output, in the order the script produced it: `text()` and `console.*`
+ * produce text items, `image()` image items. `data` is base64.
+ */
+export type CodemodeOutputItem = { type: "text"; text: string } | { type: "image"; data: string; mimeType: string };
+
+export type CodemodeCallStatus = "ok" | "error" | "cancelled";
+
+export interface CodemodeCall {
+	name: string;
+	status: CodemodeCallStatus;
+	durationMs: number;
+}
+
+export type CodemodeErrorKind =
+	/** The script threw or failed to parse. `name` and `stack` come from the script's error. */
+	| "script"
+	/** The overall deadline expired. The worker was terminated. */
+	| "timeout"
+	/** The caller's signal fired or the sandbox was closed. The worker was terminated. */
+	| "aborted"
+	/** The worker or VM failed outside the script's control (for example a wasm trap or a missing worker file). */
+	| "sandbox";
+
+export interface CodemodeError {
+	kind: CodemodeErrorKind;
+	name?: string;
+	message: string;
+	stack?: string;
+}
+
+/** Keys the script changed with `store()`. Only successful executions report writes. */
+export interface CodemodeStoreWrites {
+	set: Record<string, unknown>;
+	/** Keys stored as `undefined`. */
+	delete: string[];
+}
+// senpi-change begin: output streaming
+/**
+ * One transport frame of an output item in `output: "stream"` mode. An item is split into frames of at most
+ * `frameBytes` (UTF-16 bytes of `chunk`); frames of one item share `itemId`, arrive in `seq` order, and the
+ * last one has `final: true`. Image frames carry base64 text and repeat the item's `mimeType`.
+ */
+export interface CodemodeOutputFrame {
+	itemId: number;
+	seq: number;
+	final: boolean;
+	type: "text" | "image";
+	chunk: string;
+	mimeType?: string;
+}
+
+/** Bounds observed in `output: "stream"` mode: frames delivered and the most bytes ever in flight. */
+export interface CodemodeStreamStats {
+	frames: number;
+	maxInFlightBytes: number;
+	windowBytes: number;
+}
+// senpi-change end
+
+// senpi-change begin: output streaming (replaces upstream's CodemodeResult union to add `streamed`)
+/** `output` is kept for failed executions too, up to the failure. `exit()` completes with `value: undefined`. */
+export type CodemodeResult = (
+	| {
+			ok: true;
+			value: unknown;
+			output: CodemodeOutputItem[];
+			calls: CodemodeCall[];
+			storeWrites: CodemodeStoreWrites;
+	  }
+	| { ok: false; error: CodemodeError; output: CodemodeOutputItem[]; calls: CodemodeCall[] }
+) & {
+	/** Set in `output: "stream"` mode, where `output` stays empty because every item went to `onOutputFrame`. */
+	streamed?: CodemodeStreamStats;
+};
+// senpi-change end
+
+export interface CodemodeSandboxOptions {
+	tools?: CodemodeTool[];
+	/**
+	 * Functions exposed as top-level identifiers instead of on `tools`, for host helpers such as
+	 * attaching an image to the result. They behave like tools (JSON round trip, promise result)
+	 * but are not recorded in `result.calls`. Names must be identifiers and may not shadow the
+	 * built-in globals (`tools`, `ALL_TOOLS`, `console`, `text`, `image`, `exit`, `store`, `load`).
+	 */
+	globals?: CodemodeTool[];
+	/**
+	 * Overall deadline per execution, including time spent in tools. `Infinity` disables the
+	 * deadline; the execution then only ends when the script settles or is aborted.
+	 * Default: 300000.
+	 */
+	timeoutMs?: number;
+	/**
+	 * Maximum memory the QuickJS VM may allocate. Allocations beyond it fail inside the script as
+	 * `InternalError: out of memory`. Default: no limit beyond wasm32's 4 GiB address space.
+	 */
+	memoryLimitBytes?: number;
+	/**
+	 * Compiled `quickjs-wasi/quickjs.wasm`, usually from {@link loadQuickJSWasm}. Default:
+	 * `loadQuickJSWasm()`, the file in the installed `quickjs-wasi` package. Pass it when that file
+	 * is not on disk, for example in a Bun compiled executable.
+	 */
+	wasm?: CodemodeWasmModule | Promise<CodemodeWasmModule>;
+	/**
+	 * Worker entry that imports `@earendil-works/pi-codemode/worker`. Default: this package's own
+	 * worker file. Pass it when this package is bundled, since the default is resolved relative to
+	 * the module that creates the sandbox. Bun compiled executables require the relative string
+	 * specifier of an embedded build entrypoint; other hosts usually use a URL.
+	 */
+	workerUrl?: string | URL;
+	// senpi-change begin: output streaming and builtin policy
+	/**
+	 * `"collect"` (default) keeps output items until the script settles and returns them in `result.output`.
+	 * `"stream"` keeps nothing: each item is split into frames handed to `onOutputFrame` as they arrive, the
+	 * worker blocks once `windowBytes` of frames are unconsumed, and the per-script output limits do not apply.
+	 */
+	output?: "collect" | "stream";
+	/** Receives frames in order in `"stream"` mode; the next frame is handed over only after this settles. */
+	onOutputFrame?: (frame: CodemodeOutputFrame) => void | Promise<void>;
+	/** Bytes of frames that may be unconsumed at once in `"stream"` mode. Default: 262144. */
+	windowBytes?: number;
+	/** Largest frame in `"stream"` mode, at most `windowBytes`. Default: 65536. */
+	frameBytes?: number;
+	/**
+	 * `store: "collect"` (default) is upstream's `store()`/`load()`. `"reject"` keeps the names but holds no state:
+	 * `load()` returns `undefined` and `store()` throws an error named `CodemodeStoreDisabledError`.
+	 */
+	builtins?: { store?: "collect" | "reject" };
+	// senpi-change end
+}
+
+export interface CodemodeExecuteOptions {
+	signal?: AbortSignal;
+	/** Overrides the sandbox default for this execution. */
+	timeoutMs?: number;
+	/**
+	 * Values the script reads with `load(key)`. Must be JSON-serializable. The script's own
+	 * `store()` calls come back as `result.storeWrites`; persisting them is up to the caller.
+	 */
+	store?: Readonly<Record<string, unknown>>;
+}

package/src/kernels/sandbox/vendor/pi-codemode/wasm.ts

@@ -0,0 +1,37 @@
+// Vendored from https://github.com/earendil-works/pi (packages/codemode/src) at v1.0.1, commit a7229ddc21810d6245105978033b7df645ecc2f7.
+// MIT license; see LICENSE beside this file. Local changes are listed in VENDORED.md.
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+
+/**
+ * A compiled `WebAssembly.Module` of `quickjs-wasi/quickjs.wasm`. Typed opaquely because the Node
+ * type definitions do not declare the WebAssembly globals (they live in the DOM lib).
+ */
+export type CodemodeWasmModule = object;
+
+interface WebAssemblyGlobal {
+	compile(bytes: Uint8Array): Promise<CodemodeWasmModule>;
+}
+
+const modules = new Map<string, Promise<CodemodeWasmModule>>();
+
+/**
+ * Read and compile the QuickJS wasm once per path. `path` defaults to the file in the installed
+ * `quickjs-wasi` package; pass it when that file lives elsewhere, for example embedded in a Bun
+ * compiled executable. A failed load is retried on the next call.
+ */
+export function loadQuickJSWasm(path?: string): Promise<CodemodeWasmModule> {
+	const resolved = path ?? createRequire(import.meta.url).resolve("quickjs-wasi/quickjs.wasm");
+	let module = modules.get(resolved);
+	if (!module) {
+		const { WebAssembly } = globalThis as unknown as { WebAssembly: WebAssemblyGlobal };
+		module = readFile(resolved)
+			.then((bytes) => WebAssembly.compile(bytes))
+			.catch((error: unknown) => {
+				modules.delete(resolved);
+				throw error;
+			});
+		modules.set(resolved, module);
+	}
+	return module;
+}

package/src/kernels/shared/cell-source-at-start.ts

@@ -0,0 +1,18 @@
+import type { CellSourceAtStart, EvalKernelRunInput } from "../../tool/types.ts";
+
+/** The run input with its turn-time source applied, or the refusal to settle the cell with. */
+export function inputAtStart<T extends EvalKernelRunInput>(input: T): T | { readonly refused: string } {
+	if (input.resolveAtStart === undefined) return input;
+	let source: CellSourceAtStart;
+	try {
+		source = input.resolveAtStart();
+	} catch (error) {
+		return { refused: error instanceof Error ? error.message : String(error) };
+	}
+	if (!source.ok) return { refused: source.message };
+	return {
+		...input,
+		code: source.code,
+		...(source.sourceFile === undefined ? {} : { sourceFile: source.sourceFile }),
+	};
+}

package/src/kernels/shared/kernel-tools-pump.ts

@@ -159,6 +159,9 @@ function codeOf(
 	| "kernel_tool_missing"
 	| "kernel_tool_recursion"
 	| "kernel_tool_host_denied"
+	| "kernel_tool_cancelled"
+	| "kernel_tool_loop_mismatch"
+	| "tool_name_collision"
 	| "tools_unavailable"
 	| "invalid_tool_definition" {
 	if (
@@ -166,6 +169,9 @@ function codeOf(
 		code === "kernel_tool_missing" ||
 		code === "kernel_tool_recursion" ||
 		code === "kernel_tool_host_denied" ||
+		code === "kernel_tool_cancelled" ||
+		code === "kernel_tool_loop_mismatch" ||
+		code === "tool_name_collision" ||
 		code === "tools_unavailable" ||
 		code === "invalid_tool_definition"
 	) {

package/src/kernels/shared/process-cpu.ts

@@ -0,0 +1,69 @@
+/**
+ * CPU time a kernel child has used so far, in platform units that only ever grow; a watchdog compares
+ * two readings and never converts.
+ *
+ * - linux and darwin: the child's whole process group (`readProcessGroupCpuTime`), so a helper process
+ *   the runner forks counts as activity. The kernel child is spawned detached, so its pid is its pgid.
+ * - win32 under Bun: the child's own kernel + user time from `GetProcessTimes` (kernel32, via `bun:ffi`).
+ *   Windows has no process groups; this is the interpreter itself when it is launched directly.
+ * - anything else, or Windows under Node: `undefined`, and the caller treats the CPU as unknown.
+ */
+import { readProcessGroupCpuTime } from "./process-group-cpu.ts";
+
+type BunFfi = typeof import("bun:ffi");
+type CpuReader = (pid: number) => bigint | undefined;
+
+const PROCESS_QUERY_LIMITED_INFORMATION = 0x1000;
+const FILETIME_BYTES = 8;
+
+let windowsReader: CpuReader | null | undefined;
+
+export function readKernelCpuTime(pid: number): bigint | undefined {
+	if (!Number.isInteger(pid) || pid <= 0) return undefined;
+	if (process.platform !== "win32") return readProcessGroupCpuTime(pid);
+	if (windowsReader === undefined) windowsReader = createWindowsReader() ?? null;
+	return windowsReader?.(pid);
+}
+
+function createWindowsReader(): CpuReader | undefined {
+	const ffi = process.getBuiltinModule("bun:ffi") as BunFfi | undefined;
+	if (ffi === undefined) return undefined;
+	try {
+		return bindGetProcessTimes(ffi);
+	} catch {
+		// kernel32 always exports these; a binding failure means this runtime cannot call it at all.
+		return undefined;
+	}
+}
+
+function bindGetProcessTimes({ dlopen, FFIType, ptr }: BunFfi): CpuReader {
+	const library = dlopen("kernel32.dll", {
+		OpenProcess: { args: [FFIType.u32, FFIType.i32, FFIType.u32], returns: FFIType.ptr },
+		GetProcessTimes: {
+			args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],
+			returns: FFIType.i32,
+		},
+		CloseHandle: { args: [FFIType.ptr], returns: FFIType.i32 },
+	});
+	const times = new Uint8Array(FILETIME_BYTES * 4);
+	const view = new DataView(times.buffer);
+	return (pid) => {
+		const handle = library.symbols.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, pid);
+		if (!handle) return undefined;
+		try {
+			times.fill(0);
+			const base = ptr(times);
+			const ok = library.symbols.GetProcessTimes(
+				handle,
+				base,
+				base + FILETIME_BYTES,
+				base + FILETIME_BYTES * 2,
+				base + FILETIME_BYTES * 3,
+			);
+			if (ok === 0) return undefined;
+			return view.getBigUint64(FILETIME_BYTES * 2, true) + view.getBigUint64(FILETIME_BYTES * 3, true);
+		} finally {
+			library.symbols.CloseHandle(handle);
+		}
+	};
+}

package/src/kernels/shared/subprocess-queue.ts

@@ -120,6 +120,7 @@ export class SubprocessRunQueue {
 				return false;
 			case "webview-connect":
 			case "memory-query-result":
+			case "kernel-tools-defined":
 				return false;
 			default: {
 				const exhaustive: never = message;

package/src/tool/cell-handler.ts

@@ -48,7 +48,7 @@ export interface CellBridgeRuntime {
 	readonly ctx: ExtensionContext;
 	readonly artifactPath?: string;
 	readonly imageResizer?: EvalImageResizer;
-	/** This cell's live kernel-tool capability; only a JS kernel has one (#1754). */
+	/** This cell's live kernel-tool capability; JS and Python kernels have one (#1754, #2731). */
 	readonly kernelTools?: KernelToolsCapability;
 	/** The session generation's handle registry behind `wait()` / `handle()` / completion handles. */
 	readonly handles?: HandleRegistry;

package/src/tool/eval-tool-options.ts

@@ -8,6 +8,7 @@ import type {
 import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import type { ResolvedCodemodeSettings } from "../config/settings.ts";
+import type { PythonEnvironments } from "../environments/python-environments.ts";
 import type { EvalExecutionTracker } from "../extension/session-manager.ts";
 import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { EvalTimeoutFactory } from "./cell-execution.ts";
@@ -69,6 +70,8 @@ export interface CreateEvalToolOptions {
 	readonly bunSkillPath?: string;
 	/** Kernel globals of the tools active when a cell is submitted; read once per cell. */
 	readonly kernelPreludes?: () => readonly KernelPreludeContribution[];
+	/** The session's Python environments: `%pip` / `%environment` cells and the import root of every Python cell. */
+	readonly pythonEnvironments?: PythonEnvironments;
 	/** Contributions whose documentation lines the description lists; snapshot taken when the tool is (re)registered. */
 	readonly promptKernelPreludes?: readonly KernelPreludeContribution[];
 }

package/src/tool/load-cell.ts

@@ -0,0 +1,73 @@
+import { closeSync, constants, fstatSync, openSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type LoadedCell =
+	| { readonly ok: true; readonly code: string; readonly sourceFile: string }
+	| { readonly ok: false; readonly message: string };
+
+export interface LoadCellOptions {
+	readonly cwd: string;
+	readonly artifactsDir: string | undefined;
+}
+
+const MAX_LOAD_BYTES = 8 * 1024 * 1024;
+const URL_SCHEME = /^([a-z][a-z0-9+.-]*):\/\//i;
+
+function errorCode(error: unknown): string | undefined {
+	return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
+		? error.code
+		: undefined;
+}
+
+function resolveTarget(target: string, options: LoadCellOptions): { path: string } | { message: string } {
+	const scheme = URL_SCHEME.exec(target)?.[1]?.toLowerCase();
+	try {
+		if (scheme === "file") return { path: fileURLToPath(target) };
+		if (scheme === "local") {
+			if (options.artifactsDir === undefined)
+				return { message: "%load local:// needs a session artifacts directory" };
+			const root = join(options.artifactsDir, "local");
+			const path = resolve(root, decodeURIComponent(target.slice("local://".length)));
+			const inside = relative(root, path);
+			if (inside.startsWith("..") || isAbsolute(inside))
+				return { message: `%load path escapes local://: ${target}` };
+			return { path };
+		}
+	} catch {
+		// fileURLToPath and decodeURIComponent throw on a malformed URL; the message names the user's own text.
+		return { message: `%load could not read the path in ${target}` };
+	}
+	if (scheme !== undefined) {
+		return {
+			message: `%load reads local files only (a path, local:// or file://); it does not fetch ${scheme}:// URLs`,
+		};
+	}
+	return { path: resolve(options.cwd, target) };
+}
+
+/**
+ * Reads a `%load` target when its cell's turn comes in the kernel's queue, so a file the previous cell wrote is
+ * there. Every failure is a refusal that names the target as the user wrote it, never an absolute path.
+ */
+export function loadCell(target: string, options: LoadCellOptions): LoadedCell {
+	const resolved = resolveTarget(target, options);
+	if ("message" in resolved) return { ok: false, message: resolved.message };
+	let fd: number | undefined;
+	try {
+		// One non-blocking open, then checks on that same handle: a FIFO or device swapped in after a check can
+		// neither block the host nor be read, and the size cap keeps a huge file from stalling the event loop.
+		fd = openSync(resolved.path, constants.O_RDONLY | constants.O_NONBLOCK);
+		const info = fstatSync(fd);
+		if (!info.isFile()) return { ok: false, message: `not a file: ${target}` };
+		if (info.size > MAX_LOAD_BYTES) return { ok: false, message: `%load reads files up to 8 MiB: ${target}` };
+		return { ok: true, code: readFileSync(fd, "utf8"), sourceFile: resolved.path };
+	} catch (error) {
+		const code = errorCode(error);
+		if (code === "ENOENT" || code === "ENOTDIR") return { ok: false, message: `file not found: ${target}` };
+		if (code === "EACCES" || code === "EPERM") return { ok: false, message: `permission denied: ${target}` };
+		return { ok: false, message: `%load could not read ${target}${code === undefined ? "" : ` (${code})`}` };
+	} finally {
+		if (fd !== undefined) closeSync(fd);
+	}
+}