@code-yeongyu/senpi-codemode 2026.10.8 → 2026.10.10

package/src/kernels/js/worker-package-resolve.js

@@ -0,0 +1,153 @@
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { isBuiltin } from "node:module";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// A cell's bare import runs `import()` from this worker's own module, so the runtime resolves it from Senpi's install
+// tree, not the session's project or its managed package revision. This resolver walks `node_modules` from each root
+// the cell names, in order, and resolves the package entry the way ESM does (the `exports` field with import
+// conditions), so ESM-only packages load and the first root that has the package wins.
+const RESOLVE_PACKAGE = Symbol.for("senpi.kernel.resolvePackage");
+const CONDITIONS = typeof globalThis.Bun === "object" ? ["bun", "node", "import", "default"] : ["node", "import", "default"];
+
+function isFile(path) {
+	try {
+		return statSync(path).isFile();
+	} catch {
+		return false;
+	}
+}
+
+function isDirectory(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function splitSpecifier(specifier) {
+	const parts = specifier.split("/");
+	const nameParts = specifier.startsWith("@") ? 2 : 1;
+	if (parts.length < nameParts || parts.slice(0, nameParts).some((part) => part === "" || part === "." || part === ".."))
+		return undefined;
+	const rest = parts.slice(nameParts).join("/");
+	return { name: parts.slice(0, nameParts).join("/"), subpath: rest === "" ? "." : `./${rest}` };
+}
+
+function conditionalTarget(target) {
+	if (typeof target === "string") return target;
+	if (Array.isArray(target)) {
+		for (const candidate of target) {
+			const resolved = conditionalTarget(candidate);
+			if (resolved !== undefined) return resolved;
+		}
+		return undefined;
+	}
+	if (target === null || typeof target !== "object") return undefined;
+	for (const [condition, value] of Object.entries(target)) {
+		if (condition !== "default" && !CONDITIONS.includes(condition)) continue;
+		const resolved = conditionalTarget(value);
+		if (resolved !== undefined) return resolved;
+	}
+	return undefined;
+}
+
+function exportsTarget(exportsField, subpath) {
+	const subpathKeyed =
+		exportsField !== null &&
+		typeof exportsField === "object" &&
+		!Array.isArray(exportsField) &&
+		Object.keys(exportsField).some((key) => key.startsWith("."));
+	if (!subpathKeyed) return subpath === "." ? conditionalTarget(exportsField) : undefined;
+	if (Object.hasOwn(exportsField, subpath)) return conditionalTarget(exportsField[subpath]);
+	let best;
+	for (const key of Object.keys(exportsField)) {
+		const star = key.indexOf("*");
+		if (star < 0 || key.includes("*", star + 1)) continue;
+		const prefix = key.slice(0, star);
+		const suffix = key.slice(star + 1);
+		if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix) || subpath.length < prefix.length + suffix.length)
+			continue;
+		if (best === undefined || prefix.length > best.prefix.length) {
+			best = { key, prefix, match: subpath.slice(prefix.length, subpath.length - suffix.length) };
+		}
+	}
+	if (best === undefined || hasInvalidSegment(best.match)) return undefined;
+	const target = conditionalTarget(exportsField[best.key]);
+	return target === undefined ? undefined : target.replaceAll("*", best.match);
+}
+
+// Node refuses a pattern match or target with "." / ".." / "node_modules" segments (ERR_INVALID_MODULE_SPECIFIER).
+function hasInvalidSegment(path) {
+	return path.split(/[\\/]/).some((segment) => segment === "." || segment === ".." || segment === "node_modules");
+}
+
+function legacyFile(path) {
+	for (const candidate of [path, `${path}.js`, `${path}.mjs`, `${path}.cjs`, join(path, "index.js")]) {
+		if (isFile(candidate)) return candidate;
+	}
+	return undefined;
+}
+
+function packageEntry(packageDir, subpath, specifier) {
+	let manifest;
+	try {
+		manifest = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+	} catch {
+		return legacyFile(join(packageDir, subpath === "." ? "index.js" : subpath));
+	}
+	if (manifest.exports !== undefined && manifest.exports !== null) {
+		const target = exportsTarget(manifest.exports, subpath);
+		if (typeof target !== "string" || !target.startsWith("./") || hasInvalidSegment(target.slice(2))) {
+			const error = new Error(`Package subpath '${subpath}' is not exported for import by '${specifier}'`);
+			error.code = "ERR_PACKAGE_PATH_NOT_EXPORTED";
+			throw error;
+		}
+		return join(packageDir, target);
+	}
+	if (subpath !== ".") return legacyFile(join(packageDir, subpath));
+	const moduleEntry = typeof globalThis.Bun === "object" && typeof manifest.module === "string" ? manifest.module : undefined;
+	const main = moduleEntry ?? (typeof manifest.main === "string" ? manifest.main : "index.js");
+	return legacyFile(join(packageDir, main));
+}
+
+function findPackageDir(name, rootUrl) {
+	let directory = fileURLToPath(rootUrl);
+	for (;;) {
+		const candidate = join(directory, "node_modules", name);
+		if (isDirectory(candidate)) return candidate;
+		const parent = dirname(directory);
+		if (parent === directory) return undefined;
+		directory = parent;
+	}
+}
+
+/**
+ * The file URL the bare `specifier` resolves to from the first of `rootUrls` whose `node_modules` chain has its
+ * package, or undefined when it names a builtin or no root has the package (the caller then imports it natively).
+ */
+export function resolvePackage(specifier, rootUrls) {
+	if (specifier.includes(":") || isBuiltin(specifier)) return undefined;
+	const parts = splitSpecifier(specifier);
+	if (parts === undefined) return undefined;
+	for (const rootUrl of rootUrls) {
+		if (typeof rootUrl !== "string") continue;
+		const packageDir = findPackageDir(parts.name, rootUrl);
+		if (packageDir === undefined) continue;
+		const entry = packageEntry(packageDir, parts.subpath, specifier);
+		if (entry === undefined) continue;
+		let real = entry;
+		try {
+			real = realpathSync(entry);
+		} catch {
+			// A missing target fails in the import itself, with the runtime's own error.
+		}
+		return pathToFileURL(real.endsWith(sep) ? real.slice(0, -1) : real).href;
+	}
+	return undefined;
+}
+
+export function installPackageResolver() {
+	globalThis[RESOLVE_PACKAGE] = resolvePackage;
+}

package/src/kernels/js/worker-runtime.js

@@ -65,13 +65,15 @@ export class JsWorkerRuntime {
 		try {
 			let prelude = "";
 			let cellCode = code;
+			let sourceName = cellId;
 			if (code.startsWith(PREPARED_CELL_PREFIX)) {
 				const prepared = JSON.parse(code.slice(PREPARED_CELL_PREFIX.length));
 				if (!isPlainObject(prepared) || typeof prepared.prelude !== "string" || typeof prepared.code !== "string") throw new Error("Invalid prepared JavaScript cell payload");
 				({ prelude, code: cellCode } = prepared);
+				if (typeof prepared.sourceFile === "string") sourceName = prepared.sourceFile;
 			}
 			if (prelude) indirectEval(prelude, PRELUDE_SOURCE_URL);
-			const value = await awaitMaybePromise(indirectEval(bindKernelBun(wrapUserCode(cellCode)), cellId));
+			const value = await awaitMaybePromise(indirectEval(bindKernelBun(wrapUserCode(cellCode)), sourceName));
 			await this.#drainPendingDisplays();
 			return value;
 		} finally {

package/src/kernels/js/workpool.js

@@ -4,8 +4,11 @@ import { kernelToolError } from "./kernel-tools-errors.js";
 // Only host-tool sugar: no admission, worker, or queue state belongs to the kernel.
 export async function createWorkpool(callTool, agent, name, options = {}) {
 	if (inKernelToolInvoke()) throw kernelToolError("kernel_tool_recursion", "kernel tools may not invoke workpool()");
-	if (options === null || typeof options !== "object" || Array.isArray(options) || Object.keys(options).some(key => key !== "mode")) {
-		throw new TypeError("workpool() options only accept mode");
+	if (options === null || typeof options !== "object" || Array.isArray(options) || Object.keys(options).some(key => key !== "mode" && key !== "tools")) {
+		throw new TypeError("workpool() options only accept mode and tools");
+	}
+	if (options.tools !== undefined && (!Array.isArray(options.tools) || !options.tools.every(name => typeof name === "string"))) {
+		throw workpoolError("invalid_tools", `workpool() tools takes an array of tool names; got ${Array.isArray(options.tools) ? "an array with a non-string" : typeof options.tools}`);
 	}
 	const call = async args => {
 		try {

package/src/kernels/py/host-cell.ts

@@ -1,42 +1,19 @@
 import type { KernelToHostMessage } from "../../bridge/protocol.ts";
 import type { HostCellExecutor } from "../../tool/types.ts";
-
-type HostCellOutcome = Awaited<ReturnType<HostCellExecutor>>;
-
+import { runHostCell as runSharedHostCell } from "../shared/host-cell.ts";
 import type { PendingRun, ResultMessage } from "./kernel-contract.ts";
-import { failedPythonResult } from "./transport.ts";
 
 export function runHostCell(
 	pending: PendingRun,
 	host: HostCellExecutor,
 	io: { readonly emit: (message: KernelToHostMessage) => void; readonly settle: (result: ResultMessage) => void },
 ): void {
-	const abort = new AbortController();
-	pending.hostAbort = abort;
-	const cellId = pending.input.cellId;
-	let finished = false;
-	// Output from an executor that was aborted, or after its outcome, belongs to no cell.
-	const emit = (message: KernelToHostMessage): void => {
-		if (!finished && !abort.signal.aborted) io.emit(message);
-	};
-	// Calling the executor inside a promise keeps a synchronous throw in this cell instead of failing the queue.
-	const done = new Promise<HostCellOutcome>((resolve) => resolve(host({ signal: abort.signal, emit }))).then(
-		(outcome): ResultMessage =>
-			outcome.ok
-				? {
-						type: "result",
-						cellId,
-						ok: true,
-						durationMs: 0,
-						...(outcome.valueRepr === undefined ? {} : { valueRepr: outcome.valueRepr }),
-					}
-				: { type: "result", cellId, ok: false, error: outcome.error, durationMs: 0 },
-		(error: unknown): ResultMessage =>
-			failedPythonResult(cellId, error instanceof Error ? error.message : String(error)),
-	);
-	pending.hostDone = done;
-	void done.then((result) => {
-		finished = true;
-		if (!abort.signal.aborted) io.settle(result);
+	const run = runSharedHostCell(pending.input.cellId, host, {
+		emit: io.emit,
+		settle: io.settle,
+		durationMs: () => 0,
+		settleAfterAbort: false,
 	});
+	pending.hostAbort = run.abort;
+	pending.hostDone = run.done;
 }

package/src/kernels/py/kernel.ts

@@ -5,6 +5,7 @@ import type {
 	KernelToolsInvokeOptions,
 	KernelToolsInvokeRequest,
 } from "../js/kernel-tools-types.ts";
+import { inputAtStart } from "../shared/cell-source-at-start.ts";
 import { describeExit } from "../shared/kernel-death.ts";
 import { KernelMemoryHost } from "../shared/kernel-memory-host.ts";
 import { KernelPreludeTracker } from "../shared/kernel-prelude-plan.ts";
@@ -243,10 +244,15 @@ export class PythonKernel {
 			});
 			return;
 		}
+		const input = inputAtStart(pending.input);
+		if ("refused" in input) {
+			this.#settleRun(pending, failedPythonResult(pending.input.cellId, input.refused));
+			return;
+		}
 		try {
 			this.#transport?.run({
-				...pending.input,
-				preludePlan: this.#preludes.plan(pending.input.kernelPreludes ?? []),
+				...input,
+				preludePlan: this.#preludes.plan(input.kernelPreludes ?? []),
 			});
 		} catch (error) {
 			const failure = error instanceof Error ? error : new Error(String(error));

package/src/kernels/py/prelude.py

@@ -13,6 +13,7 @@ import asyncio  # noqa: ANYIO_OK — stdlib-only embedded kernel runner.
 import base64
 import codecs
 import contextlib
+import importlib
 import gc
 import inspect
 import io
@@ -374,7 +375,15 @@ _BRIDGE_SOCKET_TIMEOUT_SECONDS = 60
 _WAIT_SOCKET_GRACE_SECONDS = 30
 
 
+# The host's secret for the run in this context. Every host call carries it, so the host gives the call that run's
+# kernel tools; copied contexts (parallel workers) keep it, plain threads do not, and the host forgets it at settle.
+CURRENT_CELL_TOKEN: contextvars.ContextVar[str | None] = contextvars.ContextVar("senpi_cell_token", default=None)
+
+
 def bridge_post(path: str, payload: dict[str, Any], *, socket_timeout: float | None = _BRIDGE_SOCKET_TIMEOUT_SECONDS) -> Any:
+    cell_token = CURRENT_CELL_TOKEN.get()
+    if path == "/call" and cell_token is not None and "cellToken" not in payload:
+        payload = {**payload, "cellToken": cell_token}
     port = CONNECTION.get("port")
     token = CONNECTION.get("token")
     if not isinstance(port, int) or not isinstance(token, str):
@@ -1088,10 +1097,18 @@ class Workpool:
         return _workpool_call({"op": "cancel", "pool_id": self.pool_id})
 
 
-def workpool(agent: dict[str, JsonValue], name: str, *, mode: str | None = None) -> Workpool:
+def workpool(
+    agent: dict[str, JsonValue], name: str, *, mode: str | None = None, tools: list[str] | None = None
+) -> Workpool:
     args: dict[str, JsonValue] = {"op": "create", "agent": agent, "name": name}
     if mode is not None:
         args["mode"] = mode
+    if tools is not None:
+        if not isinstance(tools, (list, tuple)) or not all(isinstance(name, str) for name in tools):
+            raise PreludeRuntimeError(
+                f"workpool(tools=...) takes a list of tool names; got {type(tools).__name__}", "invalid_tools"
+            )
+        args["tools"] = list(tools)
     result = _workpool_call(args)
     details = result.get("details")
     if isinstance(details, dict):
@@ -1169,9 +1186,12 @@ def agent(
     apply: bool | None = None,
     merge: bool | str | None = None,
     handle: bool = False,
+    tools: list[str] | None = None,
 ) -> Any:
     """Delegate work; isolated/apply/merge need a host that supports isolation, otherwise a warning.
 
+    tools grants the child this kernel's @tool functions by name, as JavaScript's agent(prompt, { tools }) does.
+
     merge accepts "patch"/"branch" or False/True respectively. Unapplied foreground
     changes raise an error with recovery instructions. A handle returns immediately;
     await the completion notification or read task_output for the isolation result.
@@ -1193,6 +1213,10 @@ def agent(
         args["merge"] = merge
     if handle:
         args["handle"] = True
+    if tools is not None:
+        if not isinstance(tools, (list, tuple)) or not all(isinstance(name, str) for name in tools):
+            raise PreludeRuntimeError(f"agent(tools=...) takes a list of tool names; got {type(tools).__name__}", "invalid_tools")
+        args["tools"] = list(tools)
 
     response = bridge_post(
         "/call",
@@ -1577,8 +1601,14 @@ _LINE_MAGICS: dict[str, Callable[[str], Any]] = {
 }
 
 
+_HOST_MAGICS = frozenset({"pip", "environment"})
+
+
 def _magic(name: str, args: str) -> Any:
     handler = _LINE_MAGICS.get(name)
+    if handler is None and name in _HOST_MAGICS:
+        # The host runs these only as a cell's first code line; anywhere else they reach here.
+        raise PreludeRuntimeError(f"put %{name} on its own cell, then run the code that uses it in the next cell")
     if handler is None:
         raise PreludeRuntimeError(f"Unsupported line magic: %{name}")
     return handler(args)
@@ -2069,8 +2099,8 @@ KERNEL_MEMORY = _KernelMemory()
 TLA_FLAG = getattr(ast, "PyCF_ALLOW_TOP_LEVEL_AWAIT", 0x2000)
 
 
-def compile_cell(source: str) -> tuple[Any | None, Any | None]:
-    module = ast.parse(transform_cell(source), mode="exec")
+def compile_cell(source: str, filename: str = "<cell>") -> tuple[Any | None, Any | None]:
+    module = ast.parse(transform_cell(source), filename=filename, mode="exec")
     if not module.body:
         return None, None
     last = module.body[-1]
@@ -2078,13 +2108,13 @@ def compile_cell(source: str) -> tuple[Any | None, Any | None]:
         body = ast.Module(body=module.body[:-1], type_ignores=[])
         expression = ast.Expression(body=last.value)
         ast.copy_location(expression, last)
-        return compile(body, "<cell>", "exec", flags=TLA_FLAG), compile(
+        return compile(body, filename, "exec", flags=TLA_FLAG), compile(
             expression,
-            "<cell>",
+            filename,
             "eval",
             flags=TLA_FLAG,
         )
-    return compile(module, "<cell>", "exec", flags=TLA_FLAG), None
+    return compile(module, filename, "exec", flags=TLA_FLAG), None
 
 
 async def run_code(code: Any, want_value: bool) -> Any:
@@ -2111,7 +2141,41 @@ def apply_preludes(preludes: Any) -> None:
             exec(compile(contribution.get("python", ""), "<kernel-prelude>", "exec"), USER_NS)
 
 
-def run_cell(cell_id: str, code: str, preludes: Any = None) -> None:
+def _enter_source_file(source_file: str | None) -> Callable[[], None]:
+    # A %load cell runs as its file: __file__ names it and its directory comes first on the import path,
+    # so `from sibling import x` resolves next to the file the way it does when the file runs as a script.
+    # The returned step undoes both when the cell ends, so a later cell never imports from that directory
+    # ahead of the session environment; the file's own sys.path edits stay.
+    if source_file is None:
+        return lambda: None
+    missing = object()
+    previous_file = USER_NS.get("__file__", missing)
+    directory = os.path.dirname(source_file)
+    previous_index = sys.path.index(directory) if directory in sys.path else None
+    with contextlib.suppress(ValueError):
+        sys.path.remove(directory)
+    sys.path.insert(0, directory)
+    importlib.invalidate_caches()
+    USER_NS["__file__"] = source_file
+
+    def restore() -> None:
+        with contextlib.suppress(ValueError):
+            sys.path.remove(directory)
+        if previous_index is not None:
+            sys.path.insert(min(previous_index, len(sys.path)), directory)
+        if previous_file is missing:
+            USER_NS.pop("__file__", None)
+        else:
+            USER_NS["__file__"] = previous_file
+        # Last: it calls every sys.meta_path finder, and user code may have installed one that raises.
+        importlib.invalidate_caches()
+
+    return restore
+
+
+def run_cell(
+    cell_id: str, code: str, preludes: Any = None, source_file: str | None = None, cell_token: str | None = None
+) -> None:
     start = time.monotonic()
     stdout = io.StringIO()
     stderr = io.StringIO()
@@ -2119,12 +2183,15 @@ def run_cell(cell_id: str, code: str, preludes: Any = None) -> None:
     # cells) ignores it so a late signal cannot kill the stdin-read loop.
     signal.signal(signal.SIGINT, signal.default_int_handler)
     result: dict[str, Any]
+    leave_source_file: Callable[[], None] = lambda: None
+    cell_scope = CURRENT_CELL_TOKEN.set(cell_token)
     try:
         KERNEL_TOOL_TOKEN.acquire()
         cell_stdout, cell_stderr = KERNEL_TOOL_STREAMS
         with cell_stdout.capture(stdout, cell=True), cell_stderr.capture(stderr, cell=True):
             apply_preludes(preludes)
-            body, expression = compile_cell(code)
+            leave_source_file = _enter_source_file(source_file)
+            body, expression = compile_cell(code, source_file or "<cell>")
             LOOP.run_until_complete(run_code(body, False))
             value = LOOP.run_until_complete(run_code(expression, True))
         text("stdout", stdout.getvalue())
@@ -2148,7 +2215,13 @@ def run_cell(cell_id: str, code: str, preludes: Any = None) -> None:
             "durationMs": elapsed(start),
         }
     finally:
+        # Liveness and revocation first: nothing the cell installed (an import finder, a path hook) can skip them.
         KERNEL_TOOL_TOKEN.release()
+        CURRENT_CELL_TOKEN.reset(cell_scope)
+        try:
+            leave_source_file()
+        except BaseException as exc:  # noqa: BROAD_EXCEPT_OK — user code can break the restore; it must not wedge the kernel.
+            text("stderr", f"[senpi] %load could not fully restore the import path: {exc}\n")
         signal.signal(signal.SIGINT, signal.SIG_IGN)
     try:
         memory = KERNEL_MEMORY.after_cell()
@@ -2180,7 +2253,18 @@ def _handle_message(message: dict[str, Any]) -> bool:
         emit({"type": "ready"})
         return True
     if message_type == "run":
-        run_cell(str(message.get("cellId", "")), str(message.get("code", "")), message.get("preludes"))
+        env_root = message.get("envRoot")
+        if isinstance(env_root, str):
+            _activate_env_root(env_root)
+        source_file = message.get("sourceFile")
+        token = message.get("bridgeCellToken")
+        run_cell(
+            str(message.get("cellId", "")),
+            str(message.get("code", "")),
+            message.get("preludes"),
+            source_file if isinstance(source_file, str) and source_file else None,
+            token if isinstance(token, str) else None,
+        )
         return True
     if message_type == "close":
         KERNEL_TOOL_RUNNER.close()
@@ -2189,6 +2273,25 @@ def _handle_message(message: dict[str, Any]) -> bool:
     return True
 
 
+_ACTIVE_ENV_ROOT: list[str] = []
+
+
+def _activate_env_root(root: str) -> None:
+    # One environment revision is on the import path at a time: a newer revision already holds every
+    # package of the previous one, so it replaces that entry instead of stacking another.
+    # An empty root means the session's current mode has nothing installed: the previous revision leaves too.
+    wanted = [root] if root else []
+    if _ACTIVE_ENV_ROOT == wanted:
+        return
+    for previous in _ACTIVE_ENV_ROOT:
+        with contextlib.suppress(ValueError):
+            sys.path.remove(previous)
+    _ACTIVE_ENV_ROOT[:] = wanted
+    if root:
+        sys.path.insert(0, root)
+    importlib.invalidate_caches()
+
+
 def _terminate_process_group() -> None:
     # The kernel is spawned into its own session (setsid), so its pid is its process
     # group id and a cell's subprocesses inherit that group. Killing the group takes

package/src/kernels/py/transport.ts

@@ -35,6 +35,9 @@ export interface PythonTransportRunInput {
 	readonly code: string;
 	readonly timeoutMs?: number;
 	readonly preludePlan?: KernelPreludePlan;
+	readonly envRoot?: () => string;
+	readonly sourceFile?: string;
+	readonly bridgeCellToken?: string;
 }
 
 export interface PythonTransportOptions {
@@ -157,7 +160,16 @@ export class PythonKernelTransport {
 			install: input.preludePlan.install.map(({ exports, python }) => ({ exports: [...exports], python })),
 			remove: [...input.preludePlan.remove],
 		};
-		this.#write({ type: "run", cellId: input.cellId, code: input.code, timeoutMs: input.timeoutMs, preludes });
+		this.#write({
+			type: "run",
+			cellId: input.cellId,
+			code: input.code,
+			timeoutMs: input.timeoutMs,
+			preludes,
+			...(input.envRoot === undefined ? {} : { envRoot: input.envRoot() }),
+			...(input.sourceFile === undefined ? {} : { sourceFile: input.sourceFile }),
+			...(input.bridgeCellToken === undefined ? {} : { bridgeCellToken: input.bridgeCellToken }),
+		});
 	}
 
 	interrupt(reason: string): void {

package/src/kernels/rb/workpool.rb

@@ -23,9 +23,15 @@ class SenpiWorkpool
   end
 end
 
-def workpool(agent, name, mode: nil)
+def workpool(agent, name, mode: nil, tools: nil)
   args = { "op" => "create", "agent" => agent, "name" => name }
   args["mode"] = mode unless mode.nil?
+  unless tools.nil?
+    unless tools.is_a?(Array) && tools.all? { |name| name.is_a?(String) }
+      raise SenpiBridgeError.new("workpool(tools: ...) takes an array of tool names; got #{tools.class}", "invalid_tools")
+    end
+    args["tools"] = tools.dup
+  end
   result = __senpi_workpool_call(args)
   details = result["details"]
   if details.is_a?(Hash)

package/src/kernels/sandbox/sandbox-cell.ts

@@ -0,0 +1,116 @@
+import type { ResolvedSandbox } from "../../config/feature-settings.ts";
+import { marshalToolResult } from "../../tool/image.ts";
+import type { ExecuteTool, HostCellExecutor } from "../../tool/types.ts";
+import type { CodemodeSandbox } from "./vendor/pi-codemode/runtime/host.ts";
+import type { CodemodeError, CodemodeOutputFrame, CodemodeTool } from "./vendor/pi-codemode/types.ts";
+
+export interface SandboxCellOptions {
+	readonly sandbox: ResolvedSandbox;
+	readonly executeTool: ExecuteTool;
+	readonly toolNames: () => readonly string[];
+	readonly describeTool?: (name: string) => string | undefined;
+	/** Where the QuickJS wasm lives; by default the installed `quickjs-wasi` package's file. */
+	readonly wasmPath?: string;
+}
+
+// On the script's first line so reported line numbers still match the cell; globals, so a cell's own
+// `const print` shadows them instead of failing as a redeclaration.
+const OUTPUT_ALIASES =
+	'globalThis.print = (...values) => text(values.map((value) => (typeof value === "string" ? value : JSON.stringify(value))).join(" ")); globalThis.display = (value) => ((typeof value === "string" && value.startsWith("data:image/")) || (value !== null && typeof value === "object" && ("image_url" in value || value.type === "image")) ? image(value) : text(typeof value === "string" ? value : JSON.stringify(value))); globalThis.tool = tools; ';
+
+const ERROR_CODES: Partial<Record<CodemodeError["kind"], string>> = {
+	timeout: "eval_isolate_timeout",
+	aborted: "eval_isolate_aborted",
+	sandbox: "eval_isolate_unavailable",
+};
+
+function codeFor(error: CodemodeError): string | undefined {
+	if (error.kind === "script" && error.reason === "memory") return "eval_isolate_memory_limit";
+	if (error.kind === "script" && error.name === "CodemodeStoreDisabledError") return "eval_isolate_no_state";
+	if (error.kind === "script" && error.reason === "unresolved") return "eval_isolate_unresolved_promise";
+	return ERROR_CODES[error.kind];
+}
+
+/** The persistent kernel never sees an isolated cell; its tools go through executeTool so permission hooks still apply. */
+export function sandboxCellExecutor(code: string, options: SandboxCellOptions): HostCellExecutor {
+	return async ({ signal, emit }) => {
+		let sandbox: CodemodeSandbox;
+		try {
+			// Lazy: the vendored QuickJS runtime loads only when a session runs its first isolated cell. The wasm is loaded
+			// here, before any of the cell runs, so a missing runtime is reported as unavailable instead of failing inside
+			// the script.
+			const runtime = await import("./vendor/pi-codemode/runtime/host.ts");
+			const { loadQuickJSWasm } = await import("./vendor/pi-codemode/wasm.ts");
+			const wasm = await loadQuickJSWasm(options.wasmPath);
+			const items = new Map<number, string[]>();
+			const tools: CodemodeTool[] = options
+				.toolNames()
+				.filter((name) => name !== "eval")
+				.map((name) => ({
+					name,
+					description: options.describeTool?.(name) ?? "",
+					execute: async (args: unknown, context: { signal: AbortSignal }) =>
+						marshalToolResult(await options.executeTool(name, args, { signal: context.signal })),
+				}));
+			sandbox = new runtime.CodemodeSandbox({
+				wasm,
+				tools,
+				timeoutMs: options.sandbox.timeoutSeconds * 1_000,
+				memoryLimitBytes: options.sandbox.memoryMb * 1024 * 1024,
+				output: "stream",
+				builtins: { store: "reject" },
+				onOutputFrame: (frame: CodemodeOutputFrame) => {
+					const parts = items.get(frame.itemId) ?? [];
+					parts.push(frame.chunk);
+					if (!frame.final) {
+						items.set(frame.itemId, parts);
+						return;
+					}
+					items.delete(frame.itemId);
+					const payload = parts.join("");
+					if (frame.type === "image") {
+						emit({ type: "display", mimeType: frame.mimeType ?? "image/png", dataBase64: payload });
+					} else {
+						emit({ type: "text", stream: "stdout", data: payload.endsWith("\n") ? payload : `${payload}\n` });
+					}
+				},
+			});
+		} catch (error) {
+			// The full error, paths included, goes to the host's own log so a maintainer can diagnose it; the cell gets
+			// only what failed and the error's code. This covers every setup step: the runtime import, the tool list,
+			// the wasm load and the sandbox itself.
+			console.error("[senpi-codemode] isolated cell setup failed:", error);
+			const code =
+				error instanceof Error && "code" in error && typeof error.code === "string" ? ` (${error.code})` : "";
+			return {
+				ok: false,
+				error: {
+					name: "SandboxUnavailableError",
+					message: `eval_isolate_unavailable: the QuickJS runtime for isolated cells could not be loaded${code}; nothing in the cell ran`,
+				},
+			};
+		}
+		try {
+			const result = await sandbox.execute(OUTPUT_ALIASES + code, { signal });
+			if (result.ok) {
+				return result.value === undefined
+					? { ok: true }
+					: {
+							ok: true,
+							valueRepr: typeof result.value === "string" ? result.value : JSON.stringify(result.value),
+						};
+			}
+			const errorCode = codeFor(result.error);
+			return {
+				ok: false,
+				error: {
+					...(result.error.name === undefined ? {} : { name: result.error.name }),
+					message: errorCode === undefined ? result.error.message : `${errorCode}: ${result.error.message}`,
+					...(result.error.stack === undefined ? {} : { stack: result.error.stack }),
+				},
+			};
+		} finally {
+			await sandbox.close();
+		}
+	};
+}

package/src/kernels/sandbox/vendor/pi-codemode/VENDORED.md

@@ -40,3 +40,4 @@ A sync must re-apply both kinds: dropping a marked line (for example `"output-fr
    - A normal finish settles only after every frame is consumed. An abort or timeout settles at once and drops frames still queued. The timer and the abort signal stay armed while a finished run's last frames drain, so a late abort, timeout or `close()` abandons them too (the run settles with that error): a consumer that never returns cannot keep a run alive.
    - `frameBytes` and `windowBytes` must be at least 4, so a frame can always hold a whole surrogate pair.
 2. **Builtin store policy** (`builtins: { store: "collect" | "reject" }`; `types.ts`, `runtime/protocol.ts`, `runtime/worker.ts`, `runtime/host.ts`, `runtime/prelude-source.ts`). With `"reject"`, `load()` returns `undefined` and `store()` throws `CodemodeStoreDisabledError`. The names stay defined, so scripts written for upstream fail with a clear message instead of a ReferenceError.
+3. **Runtime-set error reasons** (`types.ts` `CodemodeError.reason`, `runtime/prelude-source.ts`, `runtime/worker.ts`). The prelude captures the engine's own `InternalError` before user code runs and tags a failure `reason: "memory"` only for an instance of it whose message is exactly "out of memory"; its stalled-promise failure is tagged `reason: "unresolved"`; the worker tags an engine out-of-memory from `evalCode` the same way; and `text()` rethrows the engine's own error instead of replacing it with a `TypeError`. The host maps the isolate error codes from `reason` only, never from message text. Upstream has no `reason`, so its behaviour is unchanged.