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

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");
+}

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,

package/src/tool/render.ts

@@ -7,6 +7,7 @@ import {
 	type ToolDefinition,
 	type ToolRenderResultOptions,
 	truncateToVisualLines,
+	visibleWidth,
 } from "@code-yeongyu/senpi";
 import type { TruncationMeta } from "../output/output-meta.ts";
 import { highlightedCode } from "./code-preview.ts";
@@ -21,6 +22,7 @@ import {
 	JSON_TREE_SCALAR_LEN_EXPANDED,
 	renderJsonTreeLines,
 } from "./json-tree.ts";
+import { knownLanguage, leadsWithHeadline, liveHeadline } from "./live-headline.ts";
 import { formatRuntimeBadge } from "./runtime-label.ts";
 import { codePointPrefix, formatDuration, renderToolCallWidget } from "./tool-widgets.ts";
 import type {
@@ -341,18 +343,37 @@ function cellHeader(cell: EvalCellResult, environment: RenderEnvironment, badges
 		environment.spinnerFrame ?? Math.floor((cellElapsedMs(cell, environment) ?? 0) / LIVE_RENDER_TICK_MS),
 	);
 	const runtimeBadge = cell.runtime === undefined ? "" : ` (${formatRuntimeBadge(cell.language, cell.runtime)})`;
-	let header = `eval ${cell.language}${runtimeBadge} ${presentation.label} ${presentation.icon}`;
+	let header = leadsWithHeadline(cell.status)
+		? `eval ${cell.language}${runtimeBadge} ${presentation.label}`
+		: `eval ${cell.language}${runtimeBadge} ${presentation.label} ${presentation.icon}`;
 	if (cell.queuedBehind !== undefined && cell.queuedBehind.length > 0)
 		header += ` · queued behind ${cell.queuedBehind.map(sanitizeTerminalLabel).join(", ")}`;
+	else if (cell.queuedBehind !== undefined && cell.status === "queued")
+		header += ` · waiting for the ${cell.language} kernel to be ready`;
 	const throughputBadge = badges.throughput === undefined ? undefined : formatThroughputBadge(badges.throughput);
 	if (throughputBadge !== undefined) header += ` · ${throughputBadge}`;
 	const elapsedMs = badges.throughput?.wallDurationMs ?? cellElapsedMs(cell, environment);
 	if (elapsedMs !== undefined) header += ` · ${formatDuration(elapsedMs)}`;
 	if (badges.reset) header += " · reset";
 	if (badges.timeout !== undefined) header += ` · timeout ${badges.timeout}s`;
+	if (leadsWithHeadline(cell.status))
+		header = headlined(presentation.icon, cell.summary, cell.code, header, environment);
 	return style(environment.theme, presentation.color, header);
 }
 
+// An in-progress row leads with what the cell is doing (senpi#2802); collapsed, the headline is cut so the whole
+// header stays on one line, and the code moves behind expand.
+function headlined(
+	icon: string,
+	summary: string | undefined,
+	code: string | undefined,
+	rest: string,
+	environment: RenderEnvironment,
+): string {
+	const budget = environment.expanded ? undefined : environment.width - 3 - visibleWidth(`${icon}  · ${rest}`);
+	return `${icon} ${liveHeadline(summary, code, budget)} · ${rest}`;
+}
+
 function previewText(
 	text: string,
 	maxLines: number,
@@ -612,12 +633,23 @@ function renderAgentProgressEvents(events: readonly EvalStatusEvent[], environme
 }
 
 function renderCell(cell: EvalCellResult, environment: RenderEnvironment, badges: CellBadges): string[] {
+	if (leadsWithHeadline(cell.status) && !environment.expanded && cell.output.trim().length === 0) {
+		const statusEvents = (cell.statusEvents ?? []).filter((event) => event.op !== "agent");
+		if (statusEvents.length === 0) {
+			// Nothing to frame yet: the collapsed live row is its headline alone, one line, no empty box.
+			const lines = renderPrefixed(cellHeader(cell, environment, badges), environment, LIVE_LINE_PREFIX);
+			const agentEvents = (cell.statusEvents ?? []).filter((event) => event.op === "agent");
+			if (agentEvents.length > 0) appendLines(lines, renderAgentProgressEvents(agentEvents, environment));
+			return lines;
+		}
+	}
 	const lines = renderPrefixed(cellHeader(cell, environment, badges), environment, {
 		prefix: "╭─ ",
 		continuation: "│  ",
 		color: "borderAccent",
 	});
-	if (cell.summary !== undefined) {
+	const headlined = leadsWithHeadline(cell.status);
+	if (cell.summary !== undefined && !headlined) {
 		appendLines(
 			lines,
 			summaryVisualLines(cell.summary, Math.max(1, environment.width - 2), environment.expanded).map(
@@ -626,11 +658,14 @@ function renderCell(cell: EvalCellResult, environment: RenderEnvironment, badges
 		);
 	}
 	const innerWidth = Math.max(1, environment.width - 2);
-	const codePreview = previewText(
-		highlightedCode(cell.code, cell.language, environment.theme, environment.repaint),
-		environment.expanded ? Number.POSITIVE_INFINITY : CODE_PREVIEW_LINES,
-		innerWidth,
-	);
+	const codePreview =
+		headlined && !environment.expanded
+			? { lines: [], skipped: 0 }
+			: previewText(
+					highlightedCode(cell.code, cell.language, environment.theme, environment.repaint),
+					environment.expanded ? Number.POSITIVE_INFINITY : CODE_PREVIEW_LINES,
+					innerWidth,
+				);
 	if (codePreview.skipped > 0) {
 		appendLines(
 			lines,
@@ -879,6 +914,10 @@ function displaySummary(summary: string | undefined): string | undefined {
 	return normalizeEvalSummary(summary);
 }
 
+function cellIdSuffix(cellId: unknown): string {
+	return typeof cellId === "string" && cellId !== "" ? ` ${sanitizeTerminalLabel(cellId)}` : "";
+}
+
 export function renderEvalCall(
 	args: EvalToolRequest,
 	theme: Theme | undefined,
@@ -892,15 +931,23 @@ export function renderEvalCall(
 		return component;
 	}
 	if (!isEvalRunInput(args)) {
-		const title = args.action === "list" ? "eval list" : `eval ${args.action} ${args.cell_id}`;
+		// While a peek/stop call streams in, `cell_id` can still be missing; the title is the action alone until it arrives.
+		const title = args.action === "list" ? "eval list" : `eval ${args.action}${cellIdSuffix(args.cell_id)}`;
 		component.setBlocks([{ kind: "text", text: style(theme, "toolTitle", title) }]);
 		return component;
 	}
+	// While the model streams the call, `code` usually arrives before `language` and `summary`; a partial call still
+	// renders (the host would otherwise fall back to a raw key=value row).
+	const code = typeof args.code === "string" ? args.code : "";
+	const language = knownLanguage(args.language);
 	if (theme === undefined && context.spinnerFrame === undefined) {
 		const reset = args.reset === true ? " reset" : "";
 		const timeout = args.timeout === undefined ? "" : ` timeout ${args.timeout}s`;
 		component.setBlocks([
-			{ kind: "text", text: style(theme, "toolTitle", `eval ${args.language}${reset}${timeout}`) },
+			{
+				kind: "text",
+				text: style(theme, "toolTitle", `eval${language === undefined ? "" : ` ${language}`}${reset}${timeout}`),
+			},
 			...(displaySummary(args.summary) === undefined
 				? []
 				: [summaryBlock(displaySummary(args.summary) ?? "", theme, context.expanded)]),
@@ -909,9 +956,11 @@ export function renderEvalCall(
 				text: style(
 					theme,
 					"mdCodeBlock",
-					args.code.trim().length > 0
-						? displayCode(args.code, args.language, context.argsComplete ? context.invalidate : undefined)
-						: "...",
+					code.trim().length === 0
+						? "..."
+						: language === undefined
+							? code
+							: displayCode(code, language, context.argsComplete ? context.invalidate : undefined),
 				),
 				maxVisualLines: context.expanded ? undefined : CODE_PREVIEW_LINES,
 				collapseKind: "code",
@@ -933,11 +982,13 @@ export function renderEvalCall(
 					now: renderNow(context),
 					...(context.argsComplete ? { repaint: context.invalidate } : {}),
 				};
+				const summary = displaySummary(args.summary);
+				if (language === undefined) return streamingCallLines(summary, code, environment);
 				const cell: EvalCellResult = {
 					index: 0,
-					...(displaySummary(args.summary) === undefined ? {} : { summary: displaySummary(args.summary) ?? "" }),
-					code: args.code,
-					language: args.language,
+					...(summary === undefined ? {} : { summary }),
+					code,
+					language,
 					output: "",
 					status: context.spinnerFrame === undefined ? "pending" : "running",
 				};
@@ -952,6 +1003,14 @@ export function renderEvalCall(
 	return component;
 }
 
+/** A call whose language has not streamed in yet: the headline row alone, until the full frame can render. */
+function streamingCallLines(summary: string | undefined, code: string, environment: RenderEnvironment): string[] {
+	const icon = environment.spinnerFrame === undefined ? "○" : spinner(environment.spinnerFrame);
+	return renderPrefixed(headlined(icon, summary, code, "eval", environment), environment, LIVE_LINE_PREFIX);
+}
+
+const LIVE_LINE_PREFIX: PrefixStyle = { prefix: "╶─ ", continuation: "   ", color: "borderAccent" };
+
 export function renderEvalResult(
 	result: AgentToolResult<EvalResultDetails>,
 	options: ToolRenderResultOptions,

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

@@ -7,12 +7,16 @@ 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 type { JsEnvironments } from "../environments/js-environments.ts";
+import type { PackagesInstallEnvironments } from "../environments/packages-install.ts";
 import {
 	KERNEL_TOOLS_CAPABILITIES,
 	type KernelToolsCapability,
 	type KernelToolsDescribeResult,
 } from "../kernels/js/kernel-tools-types.ts";
+import { sandboxCellExecutor, sandboxRuntimeInfo } 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";
@@ -23,6 +27,8 @@ import { EvalKernelResetRefusedError } from "./eval-kernel-reset-refused-error.t
 import { evalTimeoutBehavior } from "./eval-request.ts";
 import type { CreateEvalToolOptions, EvalCellInvocation } from "./eval-tool-options.ts";
 import { describeTimeoutState } from "./interrupt-note.ts";
+import { loadCell } from "./load-cell.ts";
+import { planMagicCell } from "./magic-cell-host.ts";
 import type { EvalKernel, EvalToolDetails } from "./types.ts";
 
 export async function runEvalCell(
@@ -40,7 +46,8 @@ export async function runEvalCell(
 	const bridgeAbortController = new AbortController();
 	const cellSignal = AbortSignal.any([invocation.signal, bridgeAbortController.signal]);
 	const bridgeContext: ExtensionContext = { ...invocation.ctx, signal: cellSignal };
-	const runtime = options.runtimes?.[invocation.input.language];
+	const runtime =
+		invocation.input.isolate === true ? sandboxRuntimeInfo() : options.runtimes?.[invocation.input.language];
 	const state: CellState = {
 		input: invocation.input,
 		...(runtime === undefined ? {} : { runtime }),
@@ -205,11 +212,21 @@ async function executeCell(
 		const pending = handler.handle(message);
 		void pending.catch((error: unknown) => execution.cancel(error));
 	};
+	let releaseCellKernelTools: (() => void) | undefined;
 	try {
 		const kernel = await execution.wait(options.kernelManager.getKernel(invocation.input.language, onMessage));
 		// Computed before the handler so its construction-time snapshot captures this cell's capability.
 		// Worker messages later restore that snapshot before calling host tools (#1754, #2512).
 		const kernelTools = kernelToolsFor(kernel);
+		// Subprocess kernels call the host over the bridge, outside this async context. Their calls carry a fresh secret
+		// minted for this run and sent only to this cell's kernel, never the model-visible cell id, so code in another
+		// kernel cannot name this cell into its tools. JS calls already run inside this cell's scope (#1754).
+		const bridgeCellToken =
+			kernelTools === undefined || invocation.input.language === "js" ? undefined : randomUUID();
+		releaseCellKernelTools =
+			kernelTools === undefined || bridgeCellToken === undefined
+				? undefined
+				: options.kernelManager.bindCellKernelTools?.(bridgeCellToken, kernelTools);
 		const runBound = async (): Promise<AgentToolResult<EvalToolDetails>> => {
 			const queue = kernel.queueSnapshot();
 			state.queuedBehind = [...(queue.activeCellId === null ? [] : [queue.activeCellId]), ...queue.queuedCellIds];
@@ -226,6 +243,7 @@ async function executeCell(
 				...(kernelTools === undefined ? {} : { kernelTools }),
 				...(options.handles === undefined ? {} : { handles: options.handles }),
 				hardDeadlineMs: cell.startedAtMs + cell.hardLimitSeconds * 1_000,
+				...cellEnvironments(invocation.input.language, options),
 			});
 			handler = activeHandler;
 			cellManager.bindKernel(
@@ -249,10 +267,51 @@ 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,
+				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 };
+			// 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,
 					onStarted: () => {
@@ -285,6 +344,8 @@ async function executeCell(
 		if (error instanceof Error && error.name === "TimeoutError") throw await describeTimeoutState(error, execution);
 		throw error;
 	} finally {
+		// First, so nothing below can skip it: from here on a host call carrying this run's secret gets no kernel tools.
+		releaseCellKernelTools?.();
 		state.active = false;
 		bridgeAbortController.abort();
 		execution.finish();
@@ -306,3 +367,14 @@ function kernelToolsFor(kernel: EvalKernel): KernelToolsCapability | undefined {
 		invoke: (request, options) => withTools.invokeKernelTool(request, options),
 	} satisfies ExtensionKernelTools;
 }
+
+// Only JS cells call tools in-process; a Python cell reaches packages.install() over the bridge, whose session manager
+// holds the same Python environment its magics use.
+function cellEnvironments(
+	language: string,
+	options: { readonly jsEnvironments?: JsEnvironments },
+): { readonly environments?: PackagesInstallEnvironments } {
+	if (language === "js" && options.jsEnvironments !== undefined)
+		return { environments: { js: options.jsEnvironments } };
+	return {};
+}

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 === undefined ? base : `${base}, ${runtime.isolation}`;
 	if (runtime.path === undefined || runtime.path.length === 0) return label;
 	return `${label}, ${minifyPath(runtime.path, home)}`;
 }