@code-yeongyu/senpi-codemode 2026.10.8 → 2026.10.10

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

@@ -46,6 +46,10 @@ export const PRELUDE_SOURCE: string = `(function (bridge, toolsJson, globalsJson
 	const options = optionsJson === undefined ? {} : JSON.parse(optionsJson);
 	const streamOutput = options.streamOutput === true;
 	const rejectStore = options.store === "reject";
+	// The engine's own InternalError, captured before user code runs: a failure is tagged by identity, never by its
+	// text, so a cell's own error that merely mentions memory keeps its own code. A script can still construct this
+	// constructor itself and so label its own failure as the memory limit; that mislabels only its own cell.
+	const EngineInternalError = typeof InternalError === "function" ? InternalError : undefined;
 	// senpi-change end
 	"use strict";
 	const stringify = JSON.stringify;
@@ -94,7 +98,13 @@ export const PRELUDE_SOURCE: string = `(function (bridge, toolsJson, globalsJson
 
 	function describeError(error) {
 		if (error instanceof ErrorCtor) {
-			return stringify({ name: error.name, message: error.message, stack: errorText(error) });
+			// senpi-change begin: the engine's out-of-memory error is reported by identity, not by matching its message
+			const reason =
+				EngineInternalError !== undefined && error instanceof EngineInternalError && error.message === "out of memory"
+					? "memory"
+					: undefined;
+			return stringify({ name: error.name, message: error.message, stack: errorText(error), reason });
+			// senpi-change end
 		}
 		return stringify({ message: format(error) });
 	}
@@ -285,6 +295,8 @@ export const PRELUDE_SOURCE: string = `(function (bridge, toolsJson, globalsJson
 		try {
 			rendered = outputText(value);
 		} catch (error) {
+			// The engine's own out-of-memory error keeps its identity, so it is still reported as the memory limit.
+			if (EngineInternalError !== undefined && error instanceof EngineInternalError) throw error; // senpi-change
 			throw new TypeErrorCtor(error instanceof ErrorCtor ? error.message : String(error));
 		}
 		output("text", rendered);
@@ -423,6 +435,7 @@ export const PRELUDE_SOURCE: string = `(function (bridge, toolsJson, globalsJson
 					name: "Error",
 					message:
 						"The script is waiting on a promise that can never settle: no tool call is pending, and timers do not exist here.",
+					reason: "unresolved", // senpi-change: tagged by the runtime, so a script's own error text never matches it
 				}),
 			);
 			return true;

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

@@ -48,7 +48,10 @@ function discardOutput(memory: { readonly buffer: ArrayBufferLike }) {
 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: evalCode fails before any script runs, so an InternalError here is the engine's own
+	const reason = error.name === "InternalError" && error.message === "out of memory" ? "memory" : undefined;
+	return JSON.stringify({ name: error.name, message: error.message, stack: stack ? `${head}\n${stack}` : head, reason });
+	// senpi-change end
 }
 // senpi-change begin: output streaming
 /**

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

@@ -71,6 +71,8 @@ export interface CodemodeError {
 	name?: string;
 	message: string;
 	stack?: string;
+	/** senpi-change: set by the runtime itself (never from script text) for its own memory-limit and stalled failures. */
+	reason?: "memory" | "unresolved";
 }
 
 /** Keys the script changed with `store()`. Only successful executions report writes. */

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/host-cell.ts

@@ -0,0 +1,57 @@
+import type { KernelToHostMessage } from "../../bridge/protocol.ts";
+import type { HostCellExecutor } from "../../tool/types.ts";
+
+type HostCellOutcome = Awaited<ReturnType<HostCellExecutor>>;
+type HostResult = Extract<KernelToHostMessage, { type: "result" }>;
+
+export interface HostCellRun {
+	readonly cellId: string;
+	readonly abort: AbortController;
+	readonly done: Promise<HostResult>;
+}
+
+/**
+ * Runs a host entry (a cell the host executes, such as an install) for one queue slot: output after the outcome or after
+ * an abort belongs to no cell, a synchronous throw stays in this cell, and `settle` receives the cell's result.
+ * `settleAfterAbort` says whether an aborted entry still settles here or whoever aborted it settles the cell.
+ */
+export function runHostCell(
+	cellId: string,
+	host: HostCellExecutor,
+	io: {
+		readonly emit: (message: KernelToHostMessage) => void;
+		readonly settle: (result: HostResult) => void;
+		readonly durationMs: () => number;
+		readonly settleAfterAbort: boolean;
+	},
+): HostCellRun {
+	const abort = new AbortController();
+	let finished = false;
+	const emit = (message: KernelToHostMessage): void => {
+		if (!finished && !abort.signal.aborted) io.emit(message);
+	};
+	const done = new Promise<HostCellOutcome>((resolve) => resolve(host({ signal: abort.signal, emit }))).then(
+		(outcome): HostResult =>
+			outcome.ok
+				? {
+						type: "result",
+						cellId,
+						ok: true,
+						durationMs: io.durationMs(),
+						...(outcome.valueRepr === undefined ? {} : { valueRepr: outcome.valueRepr }),
+					}
+				: { type: "result", cellId, ok: false, error: outcome.error, durationMs: 0 },
+		(error: unknown): HostResult => ({
+			type: "result",
+			cellId,
+			ok: false,
+			error: { message: error instanceof Error ? error.message : String(error) },
+			durationMs: 0,
+		}),
+	);
+	void done.then((result) => {
+		finished = true;
+		if (io.settleAfterAbort || !abort.signal.aborted) io.settle(result);
+	});
+	return { cellId, abort, done };
+}

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;
@@ -235,22 +235,20 @@ export class CellHandler {
 			this.#kernel.deliverToolReply({ type: "tool-reply", callId: message.callId, ok: true, value: reply.value });
 		} catch (error) {
 			if (!this.#state.active) return;
-			const text = appendSchemaHint(
-				error instanceof Error ? error.message : String(error),
-				message.toolName,
-				this.#toolParameters(message.toolName),
-			);
+			const code =
+				error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : undefined;
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			// A blocked call (a permission denial or another hook's veto) is not an argument problem.
+			const text =
+				code === "blocked"
+					? errorMessage
+					: appendSchemaHint(errorMessage, message.toolName, this.#toolParameters(message.toolName));
 			recordToolCall(this.#state.toolCalls, false, capture, undefined, text);
 			this.#kernel.deliverToolReply({
 				type: "tool-reply",
 				callId: message.callId,
 				ok: false,
-				error: {
-					message: text,
-					...(error instanceof Error && "code" in error && typeof error.code === "string"
-						? { code: error.code }
-						: {}),
-				},
+				error: { message: text, ...(code === undefined ? {} : { code }) },
 			});
 		}
 		this.#resultBuilder.emitUpdate(false);

package/src/tool/eval-request.ts

@@ -17,9 +17,19 @@ export function normalizeEvalSummary(value: unknown): string | undefined {
 	return normalized.length === 0 ? undefined : normalized;
 }
 
+export class EvalIsolateInvalidError extends TypeError {
+	readonly name = "EvalIsolateInvalidError";
+	readonly code = "eval_isolate_invalid";
+
+	constructor(reason: string) {
+		super(`eval_isolate_invalid: ${reason}`);
+	}
+}
+
 export function parseEvalRequest(
 	params: unknown,
 	enabledLanguages: readonly EvalLanguage[] = evalLanguageOrder,
+	options: { readonly sandbox?: boolean } = {},
 ): EvalToolRequest {
 	if (!isRecord(params)) throw new TypeError("eval parameters must be an object");
 	if (params.action === "list") return { action: "list" };
@@ -30,7 +40,9 @@ export function parseEvalRequest(
 	}
 	if (params.action !== undefined && params.action !== "run")
 		throw new TypeError(`Unknown eval action "${String(params.action)}"`);
-	if (!isEvalLanguage(params.language)) throw new TypeError(evalRunRequiresLanguageMessage(enabledLanguages));
+	if (params.language === undefined) throw new TypeError(evalRunRequiresLanguageMessage(enabledLanguages));
+	if (!isEvalLanguage(params.language))
+		throw new TypeError(`eval run language must be one of: ${enabledLanguages.join(", ")}`);
 	if (typeof params.code !== "string")
 		throw new TypeError("eval run requires code — the cell body to execute, verbatim");
 	const summary = normalizeEvalSummary(params.summary);
@@ -40,6 +52,15 @@ export function parseEvalRequest(
 		);
 	if (params.on_timeout !== undefined && params.on_timeout !== "detach" && params.on_timeout !== "error")
 		throw new TypeError(`Unknown eval on_timeout value "${String(params.on_timeout)}"`);
+	if (params.isolate !== undefined && params.isolate !== false) {
+		if (params.isolate !== true) throw new EvalIsolateInvalidError("isolate must be true or false");
+		if (options.sandbox !== true) {
+			throw new EvalIsolateInvalidError("sandbox cells are turned off (set sandbox.enabled in codemode settings)");
+		}
+		if (params.language !== "js")
+			throw new EvalIsolateInvalidError('sandbox cells run JavaScript only (language: "js")');
+		if (params.reset === true) throw new EvalIsolateInvalidError("a sandbox cell starts fresh; reset does not apply");
+	}
 	return {
 		language: params.language,
 		code: params.code,
@@ -48,6 +69,7 @@ export function parseEvalRequest(
 		...(typeof params.timeout === "number" ? { timeout: params.timeout } : {}),
 		...(params.on_timeout === "detach" || params.on_timeout === "error" ? { on_timeout: params.on_timeout } : {}),
 		...(typeof params.reset === "boolean" ? { reset: params.reset } : {}),
+		...(params.isolate === true ? { isolate: true } : {}),
 	};
 }
 

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

@@ -8,6 +8,8 @@ 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 { JsEnvironments } from "../environments/js-environments.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 +71,10 @@ 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;
+	/** The session's managed JavaScript packages: `%bun add` / `%npm add` cells and the bare-import fallback root. */
+	readonly jsEnvironments?: JsEnvironments;
 	/** Contributions whose documentation lines the description lists; snapshot taken when the tool is (re)registered. */
 	readonly promptKernelPreludes?: readonly KernelPreludeContribution[];
 }

package/src/tool/eval-tool.ts

@@ -1,5 +1,6 @@
 import type { AgentToolResult, ToolDefinition } from "@code-yeongyu/senpi";
 import type { TUnsafe } from "typebox";
+import { resolveSandbox } from "../config/feature-settings.ts";
 import {
 	DEFAULT_FOREGROUND_WINDOW_SECONDS,
 	defaultCodemodeSettings,
@@ -8,7 +9,12 @@ import {
 import { buildEvalPrompt } from "../prompt/eval-prompt.ts";
 import { EvalDetachedCellManager } from "./detached-cell-manager.ts";
 import { executeEvalControl } from "./detached-eval-result.ts";
-import { isEvalControlRequest, normalizeEvalSummary, parseEvalRequest } from "./eval-request.ts";
+import {
+	EvalIsolateInvalidError,
+	isEvalControlRequest,
+	normalizeEvalSummary,
+	parseEvalRequest,
+} from "./eval-request.ts";
 import type { CreateEvalToolOptions } from "./eval-tool-options.ts";
 import { runEvalCell } from "./run-eval-cell.ts";
 import {
@@ -43,7 +49,8 @@ export function createEvalTool(options: CreateEvalToolOptions) {
 		foregroundWindowSeconds,
 		hardLimitSeconds: options.hardLimitSeconds ?? defaultEvalDeadlineSeconds.hardLimitSeconds,
 	};
-	const parameters = createEvalInputSchema(options.enabledLanguages, deadlines);
+	const sandbox = resolveSandbox(options.settings ?? defaultCodemodeSettings).enabled;
+	const parameters = createEvalInputSchema(options.enabledLanguages, deadlines, { sandbox });
 	const prompt = buildEvalPrompt(options.enabledLanguages, {
 		spawns: options.spawns ?? false,
 		monitor: options.monitor,
@@ -74,9 +81,14 @@ export function createEvalTool(options: CreateEvalToolOptions) {
 	async function execute(
 		...[toolCallId, params, signal, onUpdate, ctx]: EvalExecuteArgs<EvalToolRequest>
 	): Promise<AgentToolResult<EvalResultDetails>> {
-		const request = parseEvalRequest(params, languages);
+		const request = parseEvalRequest(params, languages, { sandbox });
 		if (isEvalControlRequest(request)) return await executeEvalControl(cellManager, request);
-		if (options.proxyExecutor) return await options.proxyExecutor(request, signal);
+		if (options.proxyExecutor) {
+			// A proxy runs cells elsewhere and knows nothing of sandbox cells: an isolated cell must never run unisolated.
+			if ("isolate" in request && request.isolate === true)
+				throw new EvalIsolateInvalidError("isolate: true is not available through this eval proxy");
+			return await options.proxyExecutor(request, signal);
+		}
 		if (!languages.includes(request.language))
 			throw new RangeError(
 				`Unsupported eval language "${request.language}". Enabled languages: ${languages.join(", ")}`,

package/src/tool/load-cell.ts

@@ -0,0 +1,88 @@
+import { closeSync, constants, fstatSync, openSync, readSync } 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.
+ */
+/** Reads from `fd` until EOF or `limit` bytes, whichever comes first; a file still growing cannot exceed it. */
+export function readAtMost(fd: number, limit: number): Buffer {
+	const buffer = Buffer.alloc(limit);
+	let filled = 0;
+	while (filled < limit) {
+		const read = readSync(fd, buffer, filled, limit - filled, null);
+		if (read === 0) break;
+		filled += read;
+	}
+	return buffer.subarray(0, filled);
+}
+
+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}` };
+		const tooLarge = { ok: false as const, message: `%load reads files up to 8 MiB: ${target}` };
+		if (info.size > MAX_LOAD_BYTES) return tooLarge;
+		const bytes = readAtMost(fd, MAX_LOAD_BYTES + 1);
+		if (bytes.length > MAX_LOAD_BYTES) return tooLarge;
+		return { ok: true, code: bytes.toString("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);
+	}
+}

package/src/tool/magic-cell-host.ts

@@ -0,0 +1,123 @@
+import type { JsEnvironments } from "../environments/js-environments.ts";
+import type { PythonEnvironments } from "../environments/python-environments.ts";
+import { TIMEOUT_PAUSE_OP, TIMEOUT_RESUME_OP } from "../timeouts/bridge-timeout.ts";
+import { MagicCellError, parseMagicCell } from "./magic-cells.ts";
+import type { EvalLanguage, HostCellExecutor } from "./types.ts";
+
+export type MagicCellPlan =
+	| { readonly kind: "ordinary" }
+	| { readonly kind: "host"; readonly executor: HostCellExecutor }
+	| { readonly kind: "refused"; readonly message: string }
+	| { readonly kind: "load"; readonly target: string };
+
+export function planMagicCell(
+	language: EvalLanguage,
+	code: string,
+	environments: PythonEnvironments | undefined,
+	jsEnvironments?: JsEnvironments,
+): MagicCellPlan {
+	let magic: ReturnType<typeof parseMagicCell>;
+	try {
+		magic = parseMagicCell(language, code);
+	} catch (error) {
+		if (error instanceof MagicCellError) return { kind: "refused", message: error.message };
+		throw error;
+	}
+	if (magic === undefined) return { kind: "ordinary" };
+	if (magic.kind === "load") return { kind: "load", target: magic.target };
+	if (language === "js") return planJsMagic(magic, jsEnvironments);
+	if (environments === undefined) {
+		return {
+			kind: "refused",
+			message: "environment_installer_unavailable: this session has no Python interpreter to install packages for",
+		};
+	}
+	if (magic.kind === "environment") {
+		const mode = magic.mode;
+		return {
+			kind: "host",
+			executor: async () => {
+				await environments.setMode(mode);
+				const where = mode === "project" ? "the session directory" : "this session's managed revisions";
+				return { ok: true, valueRepr: `environment: ${mode} (${where})` };
+			},
+		};
+	}
+	const requirements = magic.args;
+	return {
+		kind: "host",
+		// Install time is parked time for the run budget, the same accounting as a bridge call.
+		executor: async ({ signal, emit }) => {
+			emit({ type: "status", event: { op: TIMEOUT_PAUSE_OP } });
+			try {
+				const receipt = await environments.install(requirements, signal, (stream, data) =>
+					emit({ type: "text", stream, data }),
+				);
+				const packages = receipt.resolved.length > 0 ? receipt.resolved.join(", ") : "nothing new";
+				return {
+					ok: true,
+					valueRepr: `installed ${packages} into ${receipt.mode} (revision ${receipt.revision}); already-imported modules stay cached until reset`,
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return { ok: false, error: { message } };
+			} finally {
+				emit({ type: "status", event: { op: TIMEOUT_RESUME_OP } });
+			}
+		},
+	};
+}
+
+function planJsMagic(
+	magic: Exclude<NonNullable<ReturnType<typeof parseMagicCell>>, { kind: "load" }>,
+	environments: JsEnvironments | undefined,
+): MagicCellPlan {
+	if (environments === undefined) {
+		return {
+			kind: "refused",
+			message: "environment_installer_unavailable: this session has no JavaScript package environment",
+		};
+	}
+	if (magic.kind === "environment") {
+		const mode = magic.mode;
+		return {
+			kind: "host",
+			executor: async () => {
+				await environments.setMode(mode);
+				const where = mode === "project" ? "the session directory" : "this session's managed revisions";
+				return { ok: true, valueRepr: `environment: ${mode} (${where})` };
+			},
+		};
+	}
+	if (magic.kind !== "js-add") return { kind: "refused", message: "this magic is not available in JavaScript" };
+	const requested = magic.args;
+	return {
+		kind: "host",
+		executor: async ({ signal, emit }) => {
+			emit({ type: "status", event: { op: TIMEOUT_PAUSE_OP } });
+			try {
+				const receipt = await environments.install(
+					requested,
+					signal,
+					(stream, data) => emit({ type: "text", stream, data }),
+					magic.installer,
+				);
+				const added = receipt.added.length > 0 ? receipt.added.join(", ") : "nothing new";
+				const where =
+					receipt.revision === undefined ? receipt.mode : `${receipt.mode} (revision ${receipt.revision})`;
+				const shadow =
+					receipt.shadowed.length > 0
+						? `; environment_resolution_conflict: ${receipt.shadowed.join(", ")} still ${receipt.shadowed.length === 1 ? "resolves" : "resolve"} from the project's node_modules first`
+						: "";
+				return {
+					ok: true,
+					valueRepr: `added ${added} with ${receipt.installer} into ${where}${shadow}; already-imported modules stay cached until reset`,
+				};
+			} catch (error) {
+				return { ok: false, error: { message: error instanceof Error ? error.message : String(error) } };
+			} finally {
+				emit({ type: "status", event: { op: TIMEOUT_RESUME_OP } });
+			}
+		},
+	};
+}

package/src/tool/magic-cells.ts

@@ -0,0 +1,75 @@
+import type { EvalLanguage } from "./types.ts";
+
+export type MagicCell =
+	| { readonly kind: "pip"; readonly args: string }
+	| { readonly kind: "environment"; readonly mode: "managed" | "project" }
+	| { readonly kind: "load"; readonly target: string }
+	| { readonly kind: "js-add"; readonly installer: "bun" | "npm"; readonly args: string };
+
+const HOST_MAGICS = ["pip", "environment", "load", "bun", "npm"] as const;
+const LOAD_LANGUAGES: ReadonlySet<EvalLanguage> = new Set(["py", "js"]);
+const COMMENT_PREFIX: Partial<Record<EvalLanguage, string>> = { py: "#", js: "//" };
+type HostMagic = (typeof HOST_MAGICS)[number];
+
+export class MagicCellError extends Error {
+	readonly name = "MagicCellError";
+}
+
+function joinContinuations(lines: readonly string[]): string[] {
+	const joined: string[] = [];
+	let pending: string | undefined;
+	for (const line of lines) {
+		const current = pending === undefined ? line : `${pending} ${line.trim()}`;
+		if (current.trimEnd().endsWith("\\")) pending = current.trimEnd().slice(0, -1).trimEnd();
+		else {
+			joined.push(current);
+			pending = undefined;
+		}
+	}
+	if (pending !== undefined) joined.push(pending);
+	return joined;
+}
+
+function hostMagicOf(language: EvalLanguage, line: string): HostMagic | undefined {
+	const match = /^%([A-Za-z]+)(?:\s|$)/.exec(line.trim());
+	const name = match?.[1];
+	const magic = HOST_MAGICS.find((candidate) => candidate === name);
+	if (magic === "load") return LOAD_LANGUAGES.has(language) ? magic : undefined;
+	if (magic === "bun" || magic === "npm") return language === "js" ? magic : undefined;
+	if (magic === "environment") return language === "py" || language === "js" ? magic : undefined;
+	return language === "py" ? magic : undefined;
+}
+
+/**
+ * A cell whose first code line (blank and comment lines skipped) is a host magic runs on the host instead of
+ * the interpreter: `%pip` and `%environment` in Python, `%load` in Python and JavaScript. In Python a trailing
+ * backslash continues the line. Any other cell is ordinary code, so a magic-looking line later in the cell
+ * (say, inside a string) is left alone. A magic followed by more code is refused, because the host step must
+ * finish before the code that depends on it runs.
+ */
+export function parseMagicCell(language: EvalLanguage, code: string): MagicCell | undefined {
+	const comment = COMMENT_PREFIX[language];
+	// Comment lines go before Python's backslash continuations are joined: Python never continues a comment line.
+	const raw = code.split("\n").filter((line) => comment === undefined || !line.trim().startsWith(comment));
+	const lines = (language === "py" ? joinContinuations(raw) : raw).filter((line) => line.trim() !== "");
+	const first = lines[0] ?? "";
+	const magic = hostMagicOf(language, first);
+	if (magic === undefined) return undefined;
+	if (lines.length > 1)
+		throw new MagicCellError(`put %${magic} on its own cell, then run the code that uses it in the next cell`);
+	const args = first.trim().slice(`%${magic}`.length).trim();
+	if (magic === "pip") return { kind: "pip", args };
+	if (magic === "bun" || magic === "npm") {
+		const [verb, ...rest] = args.split(/\s+/);
+		if (verb !== "add" && verb !== "install") {
+			throw new MagicCellError(`%${magic} supports only add: %${magic} add <package ...>`);
+		}
+		return { kind: "js-add", installer: magic, args: rest.join(" ") };
+	}
+	if (magic === "load") {
+		if (args === "") throw new MagicCellError("%load takes one argument: the path of the file to run");
+		return { kind: "load", target: args };
+	}
+	if (args === "managed" || args === "project") return { kind: "environment", mode: args };
+	throw new MagicCellError("%environment takes one argument: managed or project");
+}