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

package/src/tool/detached-cell-notification.ts

@@ -1,61 +1,21 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
 import type { EvalDetachedCellNotification, EvalDetachedCellSnapshot } from "./detached-cell-manager.ts";
 import { interruptionStateNote, unknownInterruptionStateNote } from "./interrupt-note.ts";
 import type { EvalKernelState, EvalMemoryDetails } from "./types.ts";
 
-const NOTIFICATION_TAIL_BYTES = 512;
-
-export function detachedNotificationSpillPath(artifactsDir: string | undefined, cellId: string): string | undefined {
-	if (artifactsDir === undefined) return undefined;
-	return join(artifactsDir, "local", `detached-eval-${safeCellId(cellId)}.log`);
-}
-
-export async function buildDetachedCellNotification(
-	snapshot: EvalDetachedCellSnapshot,
-	spillPath: string | undefined,
-): Promise<EvalDetachedCellNotification> {
-	const body = notificationBody(snapshot);
-	const overflow = Buffer.byteLength(body, "utf8") > NOTIFICATION_TAIL_BYTES;
-	let spillNotice = "";
-	if (overflow && spillPath !== undefined) {
-		try {
-			await mkdir(dirname(spillPath), { recursive: true });
-			await writeFile(spillPath, body, "utf8");
-			// The agent read tool resolves plain paths only, so the notice must carry
-			// the absolute spill path, never the kernel-helper local:// scheme.
-			spillNotice = `\nBuffered output overflowed; full output: ${spillPath}`;
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			spillNotice = `\nBuffered output overflow could not be spilled: ${message}`;
-		}
-	}
-	return {
-		cellId: snapshot.cellId,
-		content: `${overflow ? notificationPreview(snapshot) : body}${overflow ? "\n[…notification tail capped…]" : ""}${spillNotice}`,
-	};
-}
-
-function notificationBody(cell: EvalDetachedCellSnapshot): string {
-	const outcome = outcomeOf(cell);
-	const resultText = textContent(cell);
-	const stateNote = stateNoteOf(cell);
-	return [
-		`<system-reminder>Detached eval cell ${cell.cellId} (${cell.language}) ${outcome}.`,
-		resultText.length === 0 ? "(no output)" : resultText,
-		`${stateNote}</system-reminder>`,
-	].join("\n");
+/**
+ * A detached cell's completion carries the same text its result would have shown in the foreground: the output sink
+ * already bounded it (the configured head, the tail, the middle marker and the artifact notice), plus its images.
+ */
+export function buildDetachedCellNotification(snapshot: EvalDetachedCellSnapshot): EvalDetachedCellNotification {
+	const images = snapshot.result.content.filter((part) => part.type === "image");
+	return { cellId: snapshot.cellId, content: notificationText(snapshot, textContent(snapshot)), images };
 }
 
-function notificationPreview(cell: EvalDetachedCellSnapshot): string {
-	const outcome = outcomeOf(cell);
-	const resultText = textContent(cell);
-	const stateNote = stateNoteOf(cell);
+function notificationText(cell: EvalDetachedCellSnapshot, output: string): string {
 	return [
-		`<system-reminder>Detached eval cell ${cell.cellId} (${cell.language}) ${outcome}.`,
-		"Buffered output tail:",
-		truncateTailUtf8(resultText, NOTIFICATION_TAIL_BYTES),
-		`${stateNote}</system-reminder>`,
+		`<system-reminder>Detached eval cell ${cell.cellId} (${cell.language}) ${outcomeOf(cell)}.`,
+		output.length === 0 ? "(no output)" : output,
+		`${stateNoteOf(cell)}</system-reminder>`,
 	].join("\n");
 }
 
@@ -101,15 +61,3 @@ export function memoryStateNote(memory: EvalMemoryDetails | undefined): string {
 		return "The kernel was restarted before this cell ran - globals from earlier cells are gone; this cell's variables are available to the next eval cell.";
 	return "Kernel state updated - variables are available to the next eval cell.";
 }
-
-function safeCellId(cellId: string): string {
-	return cellId.replace(/[^a-zA-Z0-9_-]/gu, "_");
-}
-
-function truncateTailUtf8(text: string, maxBytes: number): string {
-	if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
-	const bytes = Buffer.from(text, "utf8");
-	let start = bytes.length - maxBytes;
-	while (start < bytes.length && (bytes[start] & 0xc0) === 0x80) start++;
-	return bytes.subarray(start).toString("utf8");
-}

package/src/tool/detached-cell-snapshot.ts

@@ -63,6 +63,23 @@ export function currentDetachedResult(cell: DetachedCellResultSource): AgentTool
 	return cell.terminalResult ?? cell.liveResult?.() ?? fallbackResult(cell.input);
 }
 
+/**
+ * The result a cell cancelled before its handler finished settles with: its buffered output, not the live progress
+ * frame ("1/1 cells running"), so a stopped cell never reads as still running.
+ */
+export function cancelledDetachedResult(cell: DetachedCellResultSource): AgentToolResult<EvalToolDetails> {
+	if (cell.terminalResult !== undefined) return cell.terminalResult;
+	const current = currentDetachedResult(cell);
+	const output = detachedOutputTail(current);
+	return {
+		content: [
+			{ type: "text", text: output.length > 0 ? output : "(no output)" },
+			...current.content.filter((part) => part.type === "image"),
+		],
+		details: current.details,
+	};
+}
+
 export function detachedErrorResult(cell: DetachedCellResultSource, error: Error): AgentToolResult<EvalToolDetails> {
 	const current = currentDetachedResult(cell);
 	const output = detachedOutputTail(current);

package/src/tool/detached-eval-result.ts

@@ -46,9 +46,7 @@ function createEvalListResult(cellManager: EvalDetachedCellManager): AgentToolRe
 			language: snapshot.language,
 			state: snapshot.state,
 			startedAtMs: snapshot.startedAtMs,
-			...(snapshot.queuedBehind === undefined || snapshot.queuedBehind.length === 0
-				? {}
-				: { queuedBehind: [...snapshot.queuedBehind] }),
+			...(snapshot.queuedBehind === undefined ? {} : { queuedBehind: [...snapshot.queuedBehind] }),
 			...(summary ? { summary } : {}),
 		};
 	});
@@ -60,7 +58,7 @@ function createEvalListResult(cellManager: EvalDetachedCellManager): AgentToolRe
 				" ",
 			);
 			const elapsed = Math.floor(snapshot.result.details.durationMs / 1000);
-			const queued = cell.queuedBehind === undefined ? "" : ` queued behind ${cell.queuedBehind.join(", ")}`;
+			const queued = cell.queuedBehind === undefined ? "" : ` ${queuedPhrase(cell.queuedBehind, cell.language)}`;
 			return `${cell.cellId} ${cell.language} ${cell.state} ${elapsed}s${queued} - ${preview}`;
 		})
 		.join("\n");
@@ -76,11 +74,13 @@ export function resultAfterDetach(
 	otherLiveCells: number,
 ): AgentToolResult<EvalToolDetails> {
 	if (snapshot.state !== "detached" && snapshot.state !== "running") return createDetachedControlResult(snapshot);
-	const predecessors = snapshot.queuedBehind?.join(", ");
+	const queuedBehind = snapshot.queuedBehind;
 	const text =
-		predecessors === undefined
+		queuedBehind === undefined
 			? `Eval cell ${snapshot.cellId} detached and is running in the ${input.language} kernel (${otherLiveCells} other live cells). Completion arrives as a notification; do not re-run it. eval({ action: "peek" | "stop", cell_id }) or eval({ action: "list" }).`
-			: `Eval cell ${snapshot.cellId} is queued behind ${predecessors} in the ${input.language} kernel and detached; it runs after ${predecessors} and completes as one notification. peek/stop/list with eval({ action, cell_id })`;
+			: queuedBehind.length === 0
+				? `Eval cell ${snapshot.cellId} is detached and waiting for the ${input.language} kernel to be ready; it runs first once the kernel is ready and completes as one notification. peek/stop/list with eval({ action, cell_id })`
+				: `Eval cell ${snapshot.cellId} is queued behind ${queuedBehind.join(", ")} in the ${input.language} kernel and detached; it runs after ${queuedBehind.join(", ")} and completes as one notification. peek/stop/list with eval({ action, cell_id })`;
 	return {
 		content: [
 			{
@@ -164,6 +164,12 @@ export function resultForDetachedState(
 	};
 }
 
+function queuedPhrase(queuedBehind: readonly string[], language: string): string {
+	return queuedBehind.length === 0
+		? `waiting for the ${language} kernel to be ready`
+		: `queued behind ${queuedBehind.join(", ")}`;
+}
+
 function textContent(result: AgentToolResult<EvalToolDetails>): string {
 	return result.content
 		.filter((part) => part.type === "text")

package/src/tool/detached-notification-queue.ts

@@ -3,7 +3,6 @@ import { buildDetachedCellNotification } from "./detached-cell-notification.ts";
 
 export interface PendingDetachedNotification {
 	readonly snapshot: () => EvalDetachedCellSnapshot | Promise<EvalDetachedCellSnapshot>;
-	readonly spillPath: string | undefined;
 }
 
 export class DetachedNotificationQueue {
@@ -30,7 +29,7 @@ export class DetachedNotificationQueue {
 		const flush = Promise.resolve().then(async () => {
 			const pending = this.#pending.splice(0);
 			const notifications = await Promise.all(
-				pending.map(async (item) => await buildDetachedCellNotification(await item.snapshot(), item.spillPath)),
+				pending.map(async (item) => buildDetachedCellNotification(await item.snapshot())),
 			);
 			this.#notifier?.notify(notifications);
 		});

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,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 { 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";
@@ -72,6 +73,8 @@ export interface CreateEvalToolOptions {
 	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 { 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/interrupt-note.ts

@@ -26,9 +26,8 @@ export async function describeTimeoutState(
 	);
 	if (outcome === undefined) error.message = fallbackTimeoutMessage(error.message);
 	else if (outcome.retained)
-		error.message = `${error.message} The kernel remains running; its existing variables are preserved.`;
-	else
-		error.message = `${error.message} The kernel was unresponsive and restarted; variables from earlier cells are lost.`;
+		error.message = `${error.message} The kernel was not restarted; variables from earlier cells are kept.`;
+	else error.message = `${error.message} The kernel was restarted; variables from earlier cells are lost.`;
 	if (outcome?.note !== undefined) error.message = `${error.message} ${outcome.note.trim()}`;
 	return error;
 }
@@ -63,8 +62,8 @@ const LANGUAGE_LABEL: Record<EvalLanguage, string> = {
 export function interruptionStateNote(language: EvalLanguage, stateRetained: boolean | undefined): string | undefined {
 	if (stateRetained === undefined) return undefined;
 	const label = LANGUAGE_LABEL[language];
-	if (stateRetained) return `${label} was interrupted and remains running; its existing variables are preserved.`;
-	return `${label} was unresponsive to interrupt and was restarted; variables from earlier cells are lost.`;
+	if (stateRetained) return `The ${label} was not restarted; variables from earlier cells are kept.`;
+	return `The ${label} was restarted; variables from earlier cells are lost.`;
 }
 
 export function unknownInterruptionStateNote(language: EvalLanguage): string {

package/src/tool/live-headline.ts

@@ -0,0 +1,60 @@
+import { sanitizeTerminalLabel, visibleWidth } from "@code-yeongyu/senpi";
+import { type EvalCellResult, type EvalLanguage, evalLanguageOrder } from "./types.ts";
+
+const HEADLINED_STATUSES: ReadonlySet<EvalCellResult["status"]> = new Set(["pending", "queued", "running", "detached"]);
+
+/**
+ * A collapsed headline never wraps the frame: it gets what the language, state and timing leave on the line. This
+ * floor (in screen cells) only keeps a word or two visible in very narrow terminals.
+ */
+const MIN_HEADLINE_CELLS = 8;
+
+export function leadsWithHeadline(status: EvalCellResult["status"]): boolean {
+	return HEADLINED_STATUSES.has(status);
+}
+
+/**
+ * What an in-progress cell is doing, in one line: its summary, or else the first line of its code that has content once sanitized (the
+ * oh-my-pi fallback), or an ellipsis while the arguments are still streaming in. Collapsed rows cut it to
+ * `maxCells` screen cells (a wide character takes two), so the headline stays one line. Whichever is chosen is
+ * sanitized before it is measured, so escape and control characters never reach the row (senpi#2831, senpi#2839).
+ */
+export function liveHeadline(
+	summary: string | undefined,
+	code: string | undefined,
+	maxCells: number | undefined,
+): string {
+	const text = (summary === undefined ? "" : sanitizeTerminalLabel(summary)) || firstCodeLine(code) || "…";
+	const limit = maxCells === undefined ? undefined : Math.max(MIN_HEADLINE_CELLS, maxCells);
+	if (limit === undefined || visibleWidth(text) <= limit) return text;
+	return `${cellPrefix(text, limit - 1)}…`;
+}
+
+// A plain cut by screen cells: the headline is styled by the caller, so no reset codes may be inserted here.
+function cellPrefix(text: string, cells: number): string {
+	let kept = "";
+	let used = 0;
+	for (const { segment } of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(text)) {
+		const width = visibleWidth(segment);
+		if (used + width > cells) break;
+		kept += segment;
+		used += width;
+	}
+	return kept;
+}
+
+export function knownLanguage(language: unknown): EvalLanguage | undefined {
+	return evalLanguageOrder.find((known) => known === language);
+}
+
+// The first line with something to show once it is sanitized: a line of only escape or control characters is skipped
+// (senpi#2850), and the later lines never reach the row.
+function firstCodeLine(code: string | undefined): string | undefined {
+	if (code === undefined) return undefined;
+	// Stops at the first line with content, so a long cell is not sanitized line by line on every frame.
+	for (const line of code.split("\n")) {
+		const clean = sanitizeTerminalLabel(line);
+		if (clean.length > 0) return clean;
+	}
+	return undefined;
+}

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

@@ -1,7 +1,6 @@
 import type { AgentToolResult } from "@code-yeongyu/senpi";
 import { type CellDeadlineExpiry, CellDeadlines } from "./cell-deadlines.ts";
 import type { EvalDetachedCellSnapshot, EvalDetachedCellState } from "./detached-cell-contract.ts";
-import { detachedNotificationSpillPath } from "./detached-cell-notification.ts";
 import type { EvalKernel, EvalToolDetails, EvalToolInput } from "./types.ts";
 
 export type LiveResultProvider = () => AgentToolResult<EvalToolDetails>;
@@ -9,7 +8,6 @@ export type LiveResultProvider = () => AgentToolResult<EvalToolDetails>;
 export type ManagedCell = {
 	readonly cellId: string;
 	readonly input: EvalToolInput;
-	readonly spillPath: string | undefined;
 	readonly startedAtMs: number;
 	readonly terminal: PromiseWithResolvers<EvalDetachedCellSnapshot>;
 	state: Exclude<EvalDetachedCellState, "detached">;
@@ -37,7 +35,6 @@ export type ManagedCell = {
 export interface ManagedCellInit {
 	readonly cellId: string;
 	readonly input: EvalToolInput;
-	readonly artifactsDir: string | undefined;
 	readonly now: () => number;
 	readonly defaultHardLimitSeconds: number;
 	readonly defaultRunBudgetSeconds: number;
@@ -60,7 +57,6 @@ export function createManagedCell(init: ManagedCellInit): ManagedCell {
 	return {
 		cellId: init.cellId,
 		input: init.input,
-		spillPath: detachedNotificationSpillPath(init.artifactsDir, init.cellId),
 		startedAtMs: init.now(),
 		state: "queued",
 		runStartedAtMs: undefined,