@code-yeongyu/senpi-codemode 2026.10.9 → 2026.10.10-3

package/src/tool/eval-tool.ts

@@ -1,5 +1,6 @@
 import type { AgentToolResult, ToolDefinition } from "@code-yeongyu/senpi";
 import type { TUnsafe } from "typebox";
+import { resolveAdvertiseHelpers, 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,9 +49,11 @@ 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,
+		...(resolveAdvertiseHelpers(options.settings ?? defaultCodemodeSettings) ? { advertiseHelpers: true } : {}),
 		monitor: options.monitor,
 		maxDetachedCells,
 		runBudgetSeconds: deadlines.runBudgetSeconds,
@@ -74,9 +82,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

@@ -1,4 +1,4 @@
-import { closeSync, constants, fstatSync, openSync, readFileSync } from "node:fs";
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -50,6 +50,18 @@ function resolveTarget(target: string, options: LoadCellOptions): { path: string
  * 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 };
@@ -60,8 +72,11 @@ export function loadCell(target: string, options: LoadCellOptions): LoadedCell {
 		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 };
+		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}` };

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

@@ -1,3 +1,4 @@
+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";
@@ -13,6 +14,7 @@ export function planMagicCell(
 	language: EvalLanguage,
 	code: string,
 	environments: PythonEnvironments | undefined,
+	jsEnvironments?: JsEnvironments,
 ): MagicCellPlan {
 	let magic: ReturnType<typeof parseMagicCell>;
 	try {
@@ -23,6 +25,7 @@ export function planMagicCell(
 	}
 	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",
@@ -34,8 +37,9 @@ export function planMagicCell(
 		return {
 			kind: "host",
 			executor: async () => {
-				const root = await environments.setMode(mode);
-				return { ok: true, valueRepr: `environment: ${mode} (${root})` };
+				await environments.setMode(mode);
+				const where = mode === "project" ? "the session directory" : "this session's managed revisions";
+				return { ok: true, valueRepr: `environment: ${mode} (${where})` };
 			},
 		};
 	}
@@ -63,3 +67,57 @@ export function planMagicCell(
 		},
 	};
 }
+
+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

@@ -3,9 +3,10 @@ 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: "load"; readonly target: string }
+	| { readonly kind: "js-add"; readonly installer: "bun" | "npm"; readonly args: string };
 
-const HOST_MAGICS = ["pip", "environment", "load"] as const;
+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];
@@ -34,6 +35,8 @@ function hostMagicOf(language: EvalLanguage, line: string): HostMagic | undefine
 	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;
 }
 
@@ -56,6 +59,13 @@ export function parseMagicCell(language: EvalLanguage, code: string): MagicCell
 		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 };

package/src/tool/run-eval-cell.ts

@@ -7,12 +7,14 @@ import {
 	kernelToolsStorage,
 } from "@code-yeongyu/senpi";
 import type { KernelToHostMessage } from "../bridge/protocol.ts";
+import { resolveSandbox } from "../config/feature-settings.ts";
 import { DEFAULT_FOREGROUND_WINDOW_SECONDS, defaultCodemodeSettings } from "../config/settings.ts";
 import {
 	KERNEL_TOOLS_CAPABILITIES,
 	type KernelToolsCapability,
 	type KernelToolsDescribeResult,
 } from "../kernels/js/kernel-tools-types.ts";
+import { sandboxCellExecutor } from "../kernels/sandbox/sandbox-cell.ts";
 import { TIMEOUT_PAUSE_OP, TIMEOUT_RESUME_OP } from "../timeouts/bridge-timeout.ts";
 import { abortError, CellExecution, defaultTimeoutFactory } from "./cell-execution.ts";
 import { CellHandler, type CellState } from "./cell-handler.ts";
@@ -261,25 +263,50 @@ async function executeCell(
 			}
 			if (invocation.input.reset) await execution.wait(kernel.reset());
 			execution.setKernel(kernel);
-			const magic = planMagicCell(invocation.input.language, invocation.input.code, options.pythonEnvironments);
+			const magic = planMagicCell(
+				invocation.input.language,
+				invocation.input.code,
+				options.pythonEnvironments,
+				options.jsEnvironments,
+			);
 			// Resolved when the cell's turn comes in the kernel's queue: a %load reads the file the cells ahead of it
 			// wrote, and a refusal settles in queue order like any cell.
 			const loadOptions = { cwd: invocation.ctx.cwd, artifactsDir: options.artifactsDir };
-			const resolveAtStart =
-				magic.kind === "load"
+			// An isolated cell never runs a file outside its sandbox: %load there is refused.
+			const isolatedLoad = invocation.input.isolate === true && magic.kind === "load";
+			const resolveAtStart = isolatedLoad
+				? () => ({
+						ok: false as const,
+						message:
+							"isolate: true cannot run a %load cell: an isolated cell sees no host files, and loading one would break that isolation. Run %load in a normal cell, or paste the code into the isolated cell.",
+					})
+				: magic.kind === "load"
 					? () => loadCell(magic.target, loadOptions)
 					: magic.kind === "refused"
 						? () => ({ ok: false as const, message: magic.message })
 						: undefined;
+			const isolated =
+				invocation.input.isolate === true && resolveAtStart === undefined
+					? sandboxCellExecutor(invocation.input.code, {
+							sandbox: resolveSandbox(options.settings ?? {}),
+							executeTool: options.executeTool,
+							toolNames: () => (options.listTools?.() ?? []).map((tool) => tool.name),
+							describeTool: (name) => options.listTools?.().find((tool) => tool.name === name)?.description,
+						})
+					: undefined;
 			const environments = invocation.input.language === "py" ? options.pythonEnvironments : undefined;
 			const envRoot = environments === undefined ? undefined : () => environments.activeRoot ?? "";
+			const jsEnvironments = invocation.input.language === "js" ? options.jsEnvironments : undefined;
+			const packageRoot = jsEnvironments === undefined ? undefined : () => jsEnvironments.packageRoot;
 			const result = await execution.wait(
 				kernel.run({
 					cellId: invocation.cellId,
 					code: invocation.input.code,
 					...(resolveAtStart === undefined ? {} : { resolveAtStart }),
 					...(magic.kind === "host" ? { host: magic.executor } : {}),
+					...(isolated === undefined ? {} : { host: isolated }),
 					...(envRoot === undefined ? {} : { envRoot }),
+					...(packageRoot === undefined ? {} : { packageRoot }),
 					...(bridgeCellToken === undefined ? {} : { bridgeCellToken }),
 					kernelPreludes: options.kernelPreludes?.(),
 					onMessage,

package/src/tool/runtime-label.ts

@@ -10,7 +10,8 @@ const ELLIPSIS = "\u2026";
  * runtime name because node and bun are otherwise indistinguishable.
  */
 export function formatRuntimeBadge(language: EvalLanguage, runtime: EvalRuntimeInfo, home: string = homedir()): string {
-	const label = language === "js" ? `${runtime.name} ${runtime.version}` : runtime.version;
+	const base = language === "js" ? `${runtime.name} ${runtime.version}` : runtime.version;
+	const label = runtime.isolation === "process" ? `${base}, process` : base;
 	if (runtime.path === undefined || runtime.path.length === 0) return label;
 	return `${label}, ${minifyPath(runtime.path, home)}`;
 }

package/src/tool/types.ts

@@ -52,6 +52,8 @@ export interface EvalToolInput {
 	readonly timeout?: number;
 	readonly on_timeout?: "detach" | "error";
 	readonly reset?: boolean;
+	/** Run in a fresh sandbox VM instead of the persistent kernel; accepted only while `sandbox.enabled` is on. */
+	readonly isolate?: boolean;
 }
 
 export interface EvalListInput {
@@ -117,14 +119,26 @@ const fullEvalInputSchema = Type.Object(
 /** Runtime accepts a discriminated run/control union. */
 export type EvalInputSchema = TUnsafe<EvalToolRequest> & Pick<typeof fullEvalInputSchema, "properties">;
 
+const ISOLATE_FIELD_DESCRIPTION =
+	"js only. Fresh sandbox per call: no persistence, no fs/net/process/timers; only tool.* plus print/display.";
+
 export function createEvalInputSchema(
 	enabled: EnabledEvalLanguages,
 	deadlines: EvalDeadlineSeconds = defaultEvalDeadlineSeconds,
+	options: { readonly sandbox?: boolean } = {},
 ): EvalInputSchema {
 	const languages = enabledLanguageList(enabled);
 	if (languages.length === 0) throw new Error("eval requires at least one enabled language");
 	const languageSchema = evalLanguageUnion(languages);
-	const properties = evalInputProperties(languageSchema, deadlines);
+	// The sandbox field exists in the schema only while sandbox cells are turned on, so the default schema
+	// (and the prompt built from it) stays exactly what it was.
+	const properties =
+		options.sandbox === true && languages.includes("js")
+			? {
+					...evalInputProperties(languageSchema, deadlines),
+					isolate: Type.Optional(Type.Boolean({ description: ISOLATE_FIELD_DESCRIPTION })),
+				}
+			: evalInputProperties(languageSchema, deadlines);
 	return Type.Unsafe<EvalToolRequest>(
 		Type.Object(properties, {
 			// Keep branches self-contained for Mistral-hosted GLM (#2240).
@@ -175,6 +189,12 @@ export interface EvalKernelRunInput {
 	readonly envRoot?: () => string;
 	/** The file a `%load` cell runs: tracebacks name it and its relative imports resolve from its directory. */
 	readonly sourceFile?: string;
+	/**
+	 * JavaScript only: the session's managed package revision; bare imports that do not resolve from cwd fall back to
+	 * it. Read when the cell starts running (not when it was queued), so a cell queued behind `%bun add` resolves the
+	 * revision that install published.
+	 */
+	readonly packageRoot?: () => string | undefined;
 	/**
 	 * Called when the cell's turn comes in the kernel's queue, never earlier: what to run instead of `code` (a `%load`
 	 * cell's file), or a refusal that settles the cell as failed in queue order.
@@ -259,6 +279,8 @@ export interface EvalRuntimeInfo {
 	readonly name: string;
 	readonly version: string;
 	readonly path?: string;
+	/** JS only: the kernel runs in a child process instead of a worker thread. */
+	readonly isolation?: "process";
 }
 
 export type EvalRuntimes = Readonly<Partial<Record<EvalLanguage, EvalRuntimeInfo>>>;