@code-yeongyu/senpi-codemode 2026.10.8 → 2026.10.9

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/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/shared/cell-source-at-start.ts

@@ -0,0 +1,18 @@
+import type { CellSourceAtStart, EvalKernelRunInput } from "../../tool/types.ts";
+
+/** The run input with its turn-time source applied, or the refusal to settle the cell with. */
+export function inputAtStart<T extends EvalKernelRunInput>(input: T): T | { readonly refused: string } {
+	if (input.resolveAtStart === undefined) return input;
+	let source: CellSourceAtStart;
+	try {
+		source = input.resolveAtStart();
+	} catch (error) {
+		return { refused: error instanceof Error ? error.message : String(error) };
+	}
+	if (!source.ok) return { refused: source.message };
+	return {
+		...input,
+		code: source.code,
+		...(source.sourceFile === undefined ? {} : { sourceFile: source.sourceFile }),
+	};
+}

package/src/tool/cell-handler.ts

@@ -48,7 +48,7 @@ export interface CellBridgeRuntime {
 	readonly ctx: ExtensionContext;
 	readonly artifactPath?: string;
 	readonly imageResizer?: EvalImageResizer;
-	/** This cell's live kernel-tool capability; only a JS kernel has one (#1754). */
+	/** This cell's live kernel-tool capability; JS and Python kernels have one (#1754, #2731). */
 	readonly kernelTools?: KernelToolsCapability;
 	/** The session generation's handle registry behind `wait()` / `handle()` / completion handles. */
 	readonly handles?: HandleRegistry;

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 { PythonEnvironments } from "../environments/python-environments.ts";
 import type { EvalExecutionTracker } from "../extension/session-manager.ts";
 import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { EvalTimeoutFactory } from "./cell-execution.ts";
@@ -69,6 +70,8 @@ export interface CreateEvalToolOptions {
 	readonly bunSkillPath?: string;
 	/** Kernel globals of the tools active when a cell is submitted; read once per cell. */
 	readonly kernelPreludes?: () => readonly KernelPreludeContribution[];
+	/** The session's Python environments: `%pip` / `%environment` cells and the import root of every Python cell. */
+	readonly pythonEnvironments?: PythonEnvironments;
 	/** Contributions whose documentation lines the description lists; snapshot taken when the tool is (re)registered. */
 	readonly promptKernelPreludes?: readonly KernelPreludeContribution[];
 }

package/src/tool/load-cell.ts

@@ -0,0 +1,73 @@
+import { closeSync, constants, fstatSync, openSync, readFileSync } 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.
+ */
+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}` };
+		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 };
+	} 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,65 @@
+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,
+): 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 (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 () => {
+				const root = await environments.setMode(mode);
+				return { ok: true, valueRepr: `environment: ${mode} (${root})` };
+			},
+		};
+	}
+	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 } });
+			}
+		},
+	};
+}

package/src/tool/magic-cells.ts

@@ -0,0 +1,65 @@
+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 };
+
+const HOST_MAGICS = ["pip", "environment", "load"] 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;
+	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 === "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/run-eval-cell.ts

@@ -23,6 +23,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(
@@ -205,11 +207,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];
@@ -249,10 +261,26 @@ 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);
+			// 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"
+					? () => loadCell(magic.target, loadOptions)
+					: magic.kind === "refused"
+						? () => ({ ok: false as const, message: magic.message })
+						: undefined;
+			const environments = invocation.input.language === "py" ? options.pythonEnvironments : undefined;
+			const envRoot = environments === undefined ? undefined : () => environments.activeRoot ?? "";
 			const result = await execution.wait(
 				kernel.run({
 					cellId: invocation.cellId,
 					code: invocation.input.code,
+					...(resolveAtStart === undefined ? {} : { resolveAtStart }),
+					...(magic.kind === "host" ? { host: magic.executor } : {}),
+					...(envRoot === undefined ? {} : { envRoot }),
+					...(bridgeCellToken === undefined ? {} : { bridgeCellToken }),
 					kernelPreludes: options.kernelPreludes?.(),
 					onMessage,
 					onStarted: () => {
@@ -285,6 +313,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();