@code-yeongyu/senpi-codemode 2026.10.8 → 2026.10.9

package/CHANGELOG.md

@@ -12,6 +12,26 @@
 
 ### Removed
 
+## [2026.10.9] - 2026-10-04
+
+### Breaking Changes
+
+### Added
+
+- Python `agent(prompt, tools=[...])` grants the child the cell's `@tool` functions by name, like JavaScript's `agent(prompt, { tools })`; anything other than a list of names is refused with `invalid_tools` ([#2731](https://github.com/code-yeongyu/senpi/issues/2731)).
+- `workpool(agent, name, {mode, tools})` forwards `tools`, a list of kernel-tool names the cell defined, to the host workpool unchanged in all four languages, so pool workers can call them; anything other than a list of names is refused with `invalid_tools` before reaching the host. Which kernels' tools a host accepts is the host's call: JavaScript `tool(fn)` tools work on omo today, while Python `@tool` tools need omo#9529 ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- A Python or JavaScript cell that is only `%load <path>` runs that local file as the cell: its definitions persist, Python tracebacks name the file and its sibling modules import, and JavaScript resolves the file's relative imports from its directory; remote URLs are refused ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+- A Python cell that is only `%pip install <requirements>` installs packages without restarting the kernel; the next cell imports them. Packages go into the session's own environment (or `<cwd>/.senpi/python-packages` after `%environment project`), never the interpreter's site-packages or the user site, and a failed or cancelled install leaves the previous packages active ([#2452](https://github.com/code-yeongyu/senpi/issues/2452)).
+
+### Changed
+
+### Fixed
+
+- A Python cell can now grant its `@tool` functions to a child ([#2731](https://github.com/code-yeongyu/senpi/issues/2731)). Host calls from Python cells (`tool.task(..., tools=[...])`, `agent(..., tools=[...])`, `workpool(..., tools=[...])`) reached the host with no kernel-tools capability, so every such grant was refused as unavailable. Each call now carries its cell, and the host gives it that cell's capability while the cell runs; a call from another, unknown or finished cell gets none.
+- `%pip` parsing follow-ups ([#2689](https://github.com/code-yeongyu/senpi/pull/2689)): a `%pip` or `%environment` line after code now says to put it on its own cell instead of "Unsupported line magic"; a comment line ending in a backslash no longer swallows the `%pip` line after it; inside double quotes a backslash is kept unless it escapes a quote, backslash, `$` or a backtick, as a POSIX shell does.
+
+### Removed
+
 ## [2026.10.8] - 2026-10-04
 
 ### Breaking Changes

package/README.md

@@ -100,6 +100,51 @@ getter and may name a file that does not exist yet. It honors session-directory
 and in-memory sessions; it cannot be derived reliably from `PI_SESSION_FILE`. If the host
 omits the getter, the variable is unset rather than inherited from the launching process.
 
+### Loading a file
+
+A Python or JavaScript cell whose only line is `%load <path>` reads that file and
+runs it as the cell, so its definitions persist like any cell. The path is relative
+to the session directory, or a `local://` or `file://` URL; other URL schemes are
+refused and nothing is fetched. The cell runs as its file: Python compiles it under
+the file's name, so tracebacks name the file and line, and sets `__file__` and puts
+the file's directory first on the import path, so `from sibling import g` resolves
+next to it. JavaScript evaluates it under the file's name and resolves its relative
+imports from the file's directory. The file is read when the cell's turn comes in
+the kernel's queue, so a `%load` queued behind the cell that writes the file runs
+what that cell wrote. When the cell ends, Python takes the file's directory back off
+the import path and restores `__file__`, so later cells import as before. A file that
+cannot be read fails the cell with a message naming the path as written
+(`file not found: <path>`, `permission denied: <path>`); files over 8 MiB, and
+anything that is not a regular file, are refused.
+
+### Python packages
+
+A Python cell whose only line is `%pip install <requirements>` installs packages
+without restarting the kernel: variables, the process and its working directory
+stay as they were. The cell runs in the kernel's queue like any other cell (it waits
+for the cell ahead of it, can be cancelled while queued, and detaches past the
+foreground window), but the install runs on the host, so its time does not count
+against the run budget. The next cell imports the new packages; modules a cell
+already imported stay cached until `reset`.
+
+Packages go into the session's own environment, never into the interpreter's
+site-packages or the user site: pip always runs as
+`<kernel interpreter> -m pip install --target <environment>`, and flags that pick
+another destination (`--target`, `--user`, `--prefix`, `--root`, `--home`,
+`-e`) are refused. Each install builds a new revision of the environment and
+publishes it only when pip succeeds, so a failed or cancelled install leaves the
+previous packages active and importable. A cell that mixes `%pip` with code is
+refused; put `%pip` on its own cell.
+
+`%environment managed` (the default) keeps the environment under the session's
+artifacts directory, or `environments.managedRoot` when set; `%environment project`
+installs into `<cwd>/.senpi/python-packages` instead, shared by every session in
+that project, with concurrent installs serialised by a lock. Setting
+`environments.autoProvision` to `false` turns installs off
+(`environment_installer_unavailable`). Failures carry pip's error output and one
+of `environment_install_failed`, `environment_install_cancelled`,
+`environment_installer_unavailable` or `environment_resolution_conflict`.
+
 ## Settings
 
 Configuration is loaded in this order:
@@ -207,7 +252,7 @@ options object and asynchronous helpers are `await`-able.
 | `agent(prompt, ...)` | Delegates to the configured active `taskTools.task` tool. Supports background handles and structured JSON results. |
 | `wait(handles, timeout?, mode?)` | Blocks the cell until the given handles settle (agent handle records, `handle()` views, completion handles, closed workpools, or saved `{kind, id, run_epoch}` references). `mode` is `all` (values in input order; the first failed, cancelled, or lost handle raises), `any` (`{index, ref, value}` of the first success), or `settled` (one outcome per input slot). `timeout` is wall-clock seconds from entry; on expiry `eval_wait_timeout` is raised and nothing is cancelled. Rides the bridge-call path, so the run budget pauses while parked. Agent and workpool handles need the host's `EvalHandleHost` capability (`eval_wait_unavailable` without it); completion handles always work. Julia extends `Base.wait` for handle views (`wait(handle(node))`). Details: `tool_schema("eval:wait")`. |
 | `handle(node \| ref \| {pool_id})` | Returns a rich view: the legacy record's fields plus a non-enumerable `control` (Python: attribute on a `dict` subclass; Ruby: singleton method) with `status()`, `output(format?, offset?, limit?)`, `send(message)` (agent handles only), `cancel()` (idempotent for that run epoch; never touches a successor run), and `wait(timeout?)`. Every control call is fenced by owner, id, and `run_epoch` inside the task owner (`eval_handle_stale`, `eval_handle_forbidden`). `completion(prompt, handle: true)` returns such a view for a host completion. The `agent(..., handle: true)` record itself is unchanged. Details: `tool_schema("eval:helpers")`. |
-| `workpool(agent, name, mode?)` | Creates a thin adapter over the normal host `workpool` tool; exposes `pool_id`, `push(items)`, `close()`, `inspect()`, and `cancel()`. JS awaits creation and operations. |
+| `workpool(agent, name, mode?, tools?)` | Creates a thin adapter over the normal host `workpool` tool; exposes `pool_id`, `push(items)`, `close()`, `inspect()`, and `cancel()`. JS awaits creation and operations. `tools` is a list of kernel-tool names this cell defined; the pool's workers may call exactly those, the host refuses any name the caller doesn't hold, and a value that isn't a list of names raises `invalid_tools`. Ruby and Julia define no kernel tools, so they have nothing to grant. |
 | `output(ids, format?, offset?, limit?)` | Delegates transcript retrieval to the configured active `taskTools.output` tool. |
 | `parallel(thunks)` | Runs thunks through the configured bounded pool while preserving input order. |
 | `pipeline(items, ...stages)` | Applies stages left to right with a barrier between stages. |
@@ -256,8 +301,11 @@ Any isolation metadata supplied by the host on a handle is preserved as
 `{subagent_type, prompt, model?}` as its plain-data agent spec. Mode is `fresh`
 or `keep_alive`: pass `{mode: "fresh"}` in JS, `mode="fresh"` in Python/Julia,
 or `mode: "fresh"` in Ruby. Omission is forwarded unchanged to the engine;
-hosts without an approved default still require an explicit mode. Custom tool
-names are not enabled by this adapter.
+hosts without an approved default still require an explicit mode. `tools`
+(kernel-tool names, for example from Python `@tool` or JavaScript `tool(fn)`) is
+forwarded unchanged to the host's `create`, which validates it: `{tools: ["add"]}`
+in JS, `tools=["add"]` in Python/Julia, `tools: ["add"]` in Ruby. There is no
+`pool.wait()`; the host delivers the aggregate.
 
 `push` forwards `[{key, input}]` and returns the host receipt without waiting
 for admission. Operations return the same `{text, details, images?, hasError?}`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@code-yeongyu/senpi-codemode",
-	"version": "2026.10.8",
+	"version": "2026.10.9",
 	"description": "Source-only senpi extension package for codemode evaluation tools",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -32,15 +32,15 @@
 	},
 	"dependencies": {
 		"@babel/parser": "8.0.4",
-		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.8",
+		"@earendil-works/pi-ai": "npm:@code-yeongyu/senpi-ai@2026.10.9",
 		"quickjs-wasi": "3.6.2",
 		"typebox": "1.3.34"
 	},
 	"peerDependencies": {
-		"@code-yeongyu/senpi": "2026.10.8"
+		"@code-yeongyu/senpi": "2026.10.9"
 	},
 	"devDependencies": {
-		"@code-yeongyu/senpi": "2026.10.8"
+		"@code-yeongyu/senpi": "2026.10.9"
 	},
 	"keywords": [
 		"senpi",

package/src/bridge/http-server.ts

@@ -8,6 +8,8 @@ const LOOPBACK_HOST = "127.0.0.1";
 
 export interface BridgeHttpCallRequest {
 	callId: string;
+	/** The calling run's secret; the host resolves that run's kernel-tools capability from it. */
+	cellToken?: string;
 	toolName: string;
 	args: unknown;
 	signal: AbortSignal;
@@ -132,7 +134,13 @@ async function dispatchCall(body: unknown, options: BridgeServerOptions, signal:
 	try {
 		return {
 			ok: true,
-			value: await options.onCall({ callId: body.callId, toolName: body.toolName, args: body.args, signal }),
+			value: await options.onCall({
+				callId: body.callId,
+				...(typeof body.cellToken === "string" ? { cellToken: body.cellToken } : {}),
+				toolName: body.toolName,
+				args: body.args,
+				signal,
+			}),
 		};
 	} catch (error) {
 		return { ok: false, error: bridgeError(error) };

package/src/bridge/protocol.ts

@@ -44,6 +44,10 @@ const hostToKernelMessageSchema = Type.Union([
 		cellId: Type.String({ minLength: 1 }),
 		code: Type.String(),
 		timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
+		/** Python only: the published environment revision to import from, applied before the cell runs; empty removes the previous one. */
+		envRoot: Type.Optional(Type.String()),
+		/** The file a `%load` cell runs; the runner compiles under its name and imports beside it. */
+		sourceFile: Type.Optional(Type.String({ minLength: 1 })),
 		/** Python only: active tool globals to install before the cell and deactivated ones to remove. */
 		preludes: Type.Optional(
 			Type.Object({

package/src/bridges/eval-virtual-schemas.ts

@@ -52,6 +52,7 @@ const helpersEntry: EvalSchemaResult = {
 		"control.status() goes through the host subscription; control.send/cancel/output are fenced by owner, id and run_epoch inside the task owner (stale -> eval_handle_stale, foreign -> eval_handle_forbidden); control.output() returns only that epoch's transcript. The plain output() helper and task tools are unchanged.",
 		"The legacy agent(..., {handle: true}) record is unchanged: .output stays a string and no enumerable key is added. A saved {kind, id, run_epoch} (or the record itself) can be rebound with handle(ref) in a later cell or after a kernel reset while the owner and run epoch are valid.",
 		"completion(prompt, {handle: true}) (py: handle=True) returns a control handle after preflight validation; provider failures surface in its outcome; its deadline derives from the creating cell's hard deadline. Completion handles are codemode-owned and need no host capability; once the session generation is dropped they fail with eval_handle_stale.",
+		"workpool(agent, name, {mode?, tools?}) (py/jl: mode=, tools=; rb: mode:, tools:) forwards tools (kernel-tool names, e.g. from @tool or tool(fn)) unchanged to the host workpool tool's create; the host checks them. There is no pool.wait(): the host delivers the aggregate and the kernel stays free to serve kernel tools.",
 		"See tool_schema('eval:wait') for the barrier semantics.",
 	].join("\n"),
 	parameters: {

package/src/environments/py-installer.ts

@@ -61,11 +61,71 @@ const SHORT_ALIASES: Readonly<Record<string, string>> = {
 const STDERR_TAIL_BYTES = 4_096;
 const PIP_TREE_GRACE_MS = 2_000;
 
+/**
+ * Splits a %pip argument line the way the platform's shell would for these inputs: single and double quotes
+ * group (`"pkg[extra]>=1.0"`) and `#` at the start of a word begins a comment. A backslash escapes the next
+ * character only in POSIX mode; on Windows it is a path separator and stays as written. An unclosed quote is
+ * refused rather than guessed.
+ */
+const DOUBLE_QUOTE_ESCAPES: ReadonlySet<string> = new Set(['"', "\\", "$", "`"]);
+
+export function splitShellWords(text: string, posix = process.platform !== "win32"): string[] {
+	const words: string[] = [];
+	let word = "";
+	let inWord = false;
+	let quote: "'" | '"' | undefined;
+	for (let index = 0; index < text.length; index++) {
+		const char = text[index] ?? "";
+		if (quote === "'") {
+			if (char === "'") quote = undefined;
+			else word += char;
+			continue;
+		}
+		if (posix && char === "\\" && index + 1 < text.length) {
+			const next = text[index + 1] ?? "";
+			// A backslash-newline is a line continuation in a shell, inside double quotes or not: both characters go.
+			if (next === "\n") {
+				index += 1;
+				continue;
+			}
+			// Inside double quotes a shell only escapes these; any other backslash stays as written.
+			if (quote === '"' && !DOUBLE_QUOTE_ESCAPES.has(next)) {
+				word += char;
+				continue;
+			}
+			index += 1;
+			word += next;
+			inWord = true;
+			continue;
+		}
+		if (quote === '"') {
+			if (char === '"') quote = undefined;
+			else word += char;
+			continue;
+		}
+		if (char === "'" || char === '"') {
+			quote = char;
+			inWord = true;
+			continue;
+		}
+		if (/\s/u.test(char)) {
+			if (inWord) words.push(word);
+			word = "";
+			inWord = false;
+			continue;
+		}
+		if (char === "#" && !inWord) break;
+		word += char;
+		inWord = true;
+	}
+	if (quote !== undefined)
+		throw new EnvironmentError("environment_install_failed", `unclosed ${quote} quote in %pip arguments`);
+	if (inWord) words.push(word);
+	return words;
+}
+
 export function parsePipRequirements(text: string): string[] {
-	const args = text
-		.trim()
-		.split(/\s+/)
-		.filter((arg) => arg !== "");
+	const args = splitShellWords(text);
 	const command = args[0] === "install" ? args.slice(1) : undefined;
 	if (command === undefined) {
 		throw new EnvironmentError("environment_install_failed", "only `%pip install <requirements>` is supported");

package/src/environments/python-environments.ts

@@ -0,0 +1,85 @@
+import type { ResolvedCodemodeSettings } from "../config/settings.ts";
+import {
+	type EnvironmentMode,
+	type InstallReceipt,
+	installPythonPackages,
+	managedEnvironmentBase,
+	projectPythonBase,
+	pythonAbiTag,
+} from "./py-environment.ts";
+import { EnvironmentError } from "./py-installer.ts";
+import { readActiveRevisionSync } from "./revision-store.ts";
+
+export interface PythonEnvironmentsOptions {
+	readonly artifactsDir: string;
+	readonly cwd: string;
+	readonly interpreter: string;
+	readonly settings: Pick<ResolvedCodemodeSettings, "environments">;
+}
+
+export class PythonEnvironments {
+	readonly #options: PythonEnvironmentsOptions;
+	#mode: EnvironmentMode = "managed";
+	#currentBase: string | undefined;
+	#managedBase: Promise<string> | undefined;
+
+	constructor(options: PythonEnvironmentsOptions) {
+		this.#options = options;
+	}
+
+	get mode(): EnvironmentMode {
+		return this.#mode;
+	}
+
+	/**
+	 * The revision a Python cell imports from, read from the current mode's root each time a cell starts, so an
+	 * install by another session sharing the project root is seen. Undefined while nothing is installed there.
+	 */
+	get activeRoot(): string | undefined {
+		return this.#currentBase === undefined ? undefined : readActiveRevisionSync(this.#currentBase)?.dir;
+	}
+
+	async setMode(mode: EnvironmentMode): Promise<string> {
+		const base = await this.#base(mode);
+		this.#mode = mode;
+		this.#currentBase = base;
+		return base;
+	}
+
+	async install(
+		requirements: string,
+		signal: AbortSignal,
+		onOutput?: (stream: "stdout" | "stderr", data: string) => void,
+	): Promise<InstallReceipt> {
+		if (this.#options.settings.environments?.autoProvision === false) {
+			throw new EnvironmentError(
+				"environment_installer_unavailable",
+				"installs are turned off for this project (environments.autoProvision is false)",
+			);
+		}
+		const mode = this.#mode;
+		const base = await this.#base(mode);
+		const receipt = await installPythonPackages({
+			base,
+			mode,
+			interpreter: this.#options.interpreter,
+			requirements,
+			cwd: this.#options.cwd,
+			signal,
+			...(onOutput === undefined ? {} : { onOutput }),
+		});
+		if (this.#mode === mode) this.#currentBase = base;
+		return receipt;
+	}
+
+	#base(mode: EnvironmentMode): Promise<string> {
+		if (mode === "project") return Promise.resolve(projectPythonBase(this.#options.cwd));
+		const configured = this.#options.settings.environments?.managedRoot;
+		this.#managedBase ??= pythonAbiTag(this.#options.interpreter).then((abi) =>
+			configured === undefined
+				? managedEnvironmentBase(this.#options.artifactsDir, "py", abi)
+				: managedEnvironmentBase(configured, "py", abi),
+		);
+		return this.#managedBase;
+	}
+}

package/src/environments/revision-store.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { type LockWaitNotice, withRootLock } from "./install-lock.ts";
@@ -12,11 +13,25 @@ export interface Revision {
 	readonly dir: string;
 }
 
+/** The same read, synchronous: the pointer is one short file, read when a Python cell starts running. */
+export function readActiveRevisionSync(base: string): Revision | undefined {
+	try {
+		return parsePointer(base, readFileSync(join(base, POINTER), "utf8"));
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+function parsePointer(base: string, text: string): Revision | undefined {
+	const name = text.trim();
+	const match = REVISION.exec(name);
+	return match?.[1] === undefined ? undefined : { number: Number(match[1]), dir: join(base, name) };
+}
+
 export async function readActiveRevision(base: string): Promise<Revision | undefined> {
 	try {
-		const name = (await readFile(join(base, POINTER), "utf8")).trim();
-		const match = REVISION.exec(name);
-		return match?.[1] === undefined ? undefined : { number: Number(match[1]), dir: join(base, name) };
+		return parsePointer(base, await readFile(join(base, POINTER), "utf8"));
 	} catch (error) {
 		if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
 		throw error;

package/src/extension/bridge-tool-call.ts

@@ -8,6 +8,8 @@ export interface BridgeToolCallRequest {
 	readonly toolName: string;
 	readonly args: unknown;
 	readonly callId: string;
+	/** The calling run's secret; absent for a call made outside any run (a plain thread), which gets no kernel tools. */
+	readonly cellToken?: string;
 	readonly signal: AbortSignal;
 }
 

package/src/extension/cell-kernel-tools.ts

@@ -0,0 +1,28 @@
+import { kernelToolsStorage } from "@code-yeongyu/senpi";
+import type { KernelToolsCapability } from "../kernels/js/kernel-tools-types.ts";
+
+/**
+ * Kernel-tools capabilities of the subprocess-kernel cells running right now, keyed by a secret minted per run and
+ * sent only to the kernel running that cell. Those kernels (py/rb/jl) reach the host over the bridge, outside the
+ * submitting cell's async context, so a bridge call carries its run's secret and runs inside that run's capability:
+ * the same `kernelToolsStorage` scope the JS worker path enters per host call (#1754).
+ */
+export class CellKernelTools {
+	readonly #byToken = new Map<string, KernelToolsCapability>();
+
+	/** Makes `capability` the kernel tools of calls carrying `token` until the returned release runs. */
+	bind(token: string, capability: KernelToolsCapability): () => void {
+		this.#byToken.set(token, capability);
+		return () => {
+			if (this.#byToken.get(token) === capability) this.#byToken.delete(token);
+		};
+	}
+
+	/** Runs `call` with the capability bound to `token`; an absent, unknown or released token gets none. */
+	async run<T>(token: string | undefined, call: () => Promise<T>): Promise<T> {
+		const capability = token === undefined ? undefined : this.#byToken.get(token);
+		return capability === undefined
+			? await kernelToolsStorage.exit(call)
+			: await kernelToolsStorage.run(capability, call);
+	}
+}

package/src/extension/kernel-replacement.ts

@@ -13,6 +13,7 @@ import type {
 	KernelInterruptHandle,
 	PendingCell,
 } from "../tool/types.ts";
+import { hasKernelTools, type KernelToolsMethods } from "./kernel-tools-probe.ts";
 
 export type StartKernel = (lifecycle: Required<KernelLifecycle>) => Promise<EvalKernel>;
 
@@ -50,10 +51,29 @@ export class ReplaceableKernel implements EvalKernel {
 	#closed = false;
 	#closeFailure: unknown;
 
+	// Present only when the instance has kernel tools, so a probe sees what it would see on the instance itself.
+	declare readonly describeKernelTools?: KernelToolsMethods["describeKernelTools"];
+	declare readonly invokeKernelTool?: KernelToolsMethods["invokeKernelTool"];
+
 	private constructor(language: EvalLanguage, start: StartKernel, first: EvalKernel) {
 		this.#language = language;
 		this.#start = start;
 		this.#kernel = first;
+		// Python is the one subprocess kernel with kernel tools; rb and jl only carry tools_unavailable stubs to hide.
+		if (language === "py" && hasKernelTools(first)) {
+			// Always the CURRENT instance: after a replacement the old definitions are gone with the old interpreter.
+			const tools: KernelToolsMethods = {
+				describeKernelTools: (names) => this.#currentTools().describeKernelTools(names),
+				invokeKernelTool: (request, options) => this.#currentTools().invokeKernelTool(request, options),
+			};
+			Object.assign(this, tools);
+		}
+	}
+
+	#currentTools(): KernelToolsMethods {
+		const current = this.#kernel;
+		if (!hasKernelTools(current)) throw new Error(`The ${this.#language} kernel has no kernel tools`);
+		return current;
 	}
 
 	/** Starts the first instance; one that cannot hand back its queue is returned as it is. */

package/src/extension/runtime-factory.ts

@@ -8,6 +8,7 @@ import {
 	type ResolvedCodemodeSettings,
 	resolveEnabledLanguages,
 } from "../config/settings.ts";
+import { PythonEnvironments } from "../environments/python-environments.ts";
 import type { HandleRegistry } from "../handles/handle-registry.ts";
 import {
 	createInterpreterDetector,
@@ -47,6 +48,7 @@ export type SessionRuntime = {
 	readonly artifactsDir: string;
 	readonly executeTool: AgentExecuteTool;
 	readonly spawns: boolean;
+	readonly pythonEnvironments?: PythonEnvironments;
 };
 
 export async function createRuntime(
@@ -96,6 +98,16 @@ export async function createRuntime(
 		artifactsDir: artifacts.dir,
 		executeTool,
 		spawns: activeTools.has(settings.taskTools.task),
+		...(availability.py.detected.ok && enabledLanguages.py
+			? {
+					pythonEnvironments: new PythonEnvironments({
+						artifactsDir: artifacts.dir,
+						cwd: ctx.cwd,
+						interpreter: availability.py.detected.path,
+						settings,
+					}),
+				}
+			: {}),
 	};
 }
 

package/src/extension/session-manager-proxy.ts

@@ -1,6 +1,7 @@
 import type { ExtensionContext } from "@code-yeongyu/senpi";
 import type { KernelToHostMessage } from "../bridge/protocol.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
+import type { KernelToolsCapability } from "../kernels/js/kernel-tools-types.ts";
 import type { EvalKernel, EvalLanguage } from "../tool/types.ts";
 import {
 	CodemodeSessionDisposedError,
@@ -106,6 +107,11 @@ export class SessionManagerProxy implements CodemodeSessionManager, EvalExecutio
 		this.#current?.releaseKernelListener?.(language, onMessage);
 	}
 
+	bindCellKernelTools(token: string, capability: KernelToolsCapability): () => void {
+		// Bound to the generation that runs the cell: a later generation never serves that cell's host calls.
+		return this.#current?.bindCellKernelTools?.(token, capability) ?? (() => undefined);
+	}
+
 	async complete(request: CompletionRequest, ctx: ExtensionContext): Promise<CompletionResult> {
 		this.assertEvalExecutionAllowed();
 		const current = this.#current;

package/src/extension/session-manager.ts

@@ -6,11 +6,12 @@ import type { CompletionRequest, CompletionResult } from "../completion/handler.
 import { resolveKernelMemoryThresholds } from "../config/memory-settings.ts";
 import { collectOrphanedChildren } from "../host-sdk.ts";
 import { JavaScriptKernel } from "../kernels/js/context-manager.ts";
-import type { KernelToolsDescribeResult } from "../kernels/js/kernel-tools-types.ts";
+import type { KernelToolsCapability, KernelToolsDescribeResult } from "../kernels/js/kernel-tools-types.ts";
 import type { KernelLifecycle } from "../kernels/shared/kernel-death.ts";
 import type { EvalKernel, EvalLanguage } from "../tool/types.ts";
 import { type BridgeDispatchContext, dispatchBridgeCompletion } from "./bridge-dispatch.ts";
 import { type BridgeToolCallRequest, routeBridgeToolCall } from "./bridge-tool-call.ts";
+import { CellKernelTools } from "./cell-kernel-tools.ts";
 import { parkWhenIdle } from "./idle-parking-kernel.ts";
 import {
 	javaScriptKernelMemory,
@@ -65,6 +66,7 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 	readonly #registrations: SessionKernelRegistrations;
 	#kernelCreations = new Map<EvalLanguage, Promise<EvalKernel>>();
 	#onMessageRefs = new Map<EvalLanguage, (message: KernelToHostMessage) => void>();
+	readonly #cellKernelTools = new CellKernelTools();
 	#context: ExtensionContext | undefined;
 	#generation = 0;
 	#disposePromise: Promise<void> | undefined;
@@ -91,7 +93,13 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 	}
 
 	async #call(request: BridgeToolCallRequest): Promise<unknown> {
-		return await routeBridgeToolCall(this.#options, request, this.#context?.evalHandleHost);
+		return await this.#cellKernelTools.run(request.cellToken, () =>
+			routeBridgeToolCall(this.#options, request, this.#context?.evalHandleHost),
+		);
+	}
+
+	bindCellKernelTools(token: string, capability: KernelToolsCapability): () => void {
+		return this.#cellKernelTools.bind(token, capability);
 	}
 
 	async getKernel(language: EvalLanguage, onMessage: (message: KernelToHostMessage) => void): Promise<EvalKernel> {

package/src/index.ts

@@ -157,6 +157,7 @@ export default function senpiCodemode(pi: CodemodeExtensionAPI, options: SenpiCo
 					complete,
 					settings: runtime.settings,
 					artifactsDir: runtime.artifactsDir,
+					...(runtime.pythonEnvironments === undefined ? {} : { pythonEnvironments: runtime.pythonEnvironments }),
 					cellManager,
 					handles,
 					executionTracker: manager,

package/src/kernels/jl/prelude.jl

@@ -210,9 +210,14 @@ function Base.getproperty(pool::SenpiWorkpool, name::Symbol)
     getfield(pool, name)
 end
 
-function workpool(agent::AbstractDict, name::AbstractString; mode=nothing)
+function workpool(agent::AbstractDict, name::AbstractString; mode=nothing, tools=nothing)
     args = Dict{String, Any}("op" => "create", "agent" => agent, "name" => name)
     mode !== nothing && (args["mode"] = mode)
+    if tools !== nothing
+        (tools isa AbstractVector && all(name -> name isa AbstractString, tools)) ||
+            throw(SenpiBridgeError("workpool(tools=...) takes a vector of tool names; got $(typeof(tools))", "invalid_tools"))
+        args["tools"] = collect(String, tools)
+    end
     result = senpi_workpool_call(args)
     details = get(result, "details", nothing)
     if details isa AbstractDict

package/src/kernels/js/context-manager.ts

@@ -1,6 +1,7 @@
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
 import { CHILD_LIFECYCLE_OP, INTERRUPT_ACK_OP } from "../../bridge/reserved.ts";
 import type { KernelInterruptHandle } from "../../tool/types.ts";
+import { inputAtStart } from "../shared/cell-source-at-start.ts";
 import { KernelToolHostPump } from "../shared/kernel-tools-pump.ts";
 import { ActiveCellControl } from "./active-cell-control.ts";
 import { DEFAULT_INTERRUPT_BOUNDS, type WorkerRetirement } from "./interrupt-bounds.ts";
@@ -195,6 +196,19 @@ export class JavaScriptKernel {
 		if (this.#lifecycle !== "open" || this.#runs.active || !this.#slot.present) return;
 		const next = this.#runs.startNext(performance.now());
 		if (!next) return;
+		const input = inputAtStart(next.input);
+		if ("refused" in input) {
+			this.#runs.releaseActive(next);
+			this.#runs.settle(next, {
+				type: "result",
+				cellId: next.input.cellId,
+				ok: false,
+				error: { message: input.refused },
+				durationMs: 0,
+			});
+			this.#startNext();
+			return;
+		}
 		this.#activeCell.arm(next);
 		this.#slot.postMessage({
 			type: "kernel-tools-names",
@@ -204,7 +218,7 @@ export class JavaScriptKernel {
 		this.#slot.postMessage({
 			type: "run",
 			cellId: next.input.cellId,
-			code: this.#moduleLoader.prepareCell(next.input.code, next.input.kernelPreludes),
+			code: this.#moduleLoader.prepareCell(input.code, input.kernelPreludes, input.sourceFile),
 			timeoutMs: next.input.timeoutMs,
 		});
 	}

package/src/kernels/js/local-module-loader.ts

@@ -1,4 +1,4 @@
-import { join, resolve, sep } from "node:path";
+import { dirname, join, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import type { KernelPreludeContribution } from "@code-yeongyu/senpi";
 import type { BridgeConnectionConfig } from "../../bridge/protocol.ts";
@@ -121,8 +121,13 @@ export class LocalModuleLoader {
 		this.#prelude = loaderPrelude(runtimeContext(options));
 	}
 
-	prepareCell(code: string, contributions: readonly KernelPreludeContribution[] = []): string {
-		const prelude = `${this.#prelude}\n${contributionPrelude(this.#contributions.plan(contributions))}`;
-		return `${PREPARED_CELL_PREFIX}${JSON.stringify({ prelude, code: rewriteImports(code) })}`;
+	prepareCell(code: string, contributions: readonly KernelPreludeContribution[] = [], sourceFile?: string): string {
+		// A %load cell resolves its relative imports from its own file's directory for that cell only.
+		const base =
+			sourceFile === undefined
+				? ""
+				: `\nglobalThis.__senpi_module_context__ = { ...globalThis.__senpi_module_context__, cwdUrl: ${JSON.stringify(directoryUrl(dirname(sourceFile)))} };`;
+		const prelude = `${this.#prelude}${base}\n${contributionPrelude(this.#contributions.plan(contributions))}`;
+		return `${PREPARED_CELL_PREFIX}${JSON.stringify({ prelude, code: rewriteImports(code), ...(sourceFile === undefined ? {} : { sourceFile }) })}`;
 	}
 }

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

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