@code-yeongyu/senpi-codemode 2026.10.7 → 2026.10.9

package/src/environments/py-environment.ts

@@ -0,0 +1,98 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { assertInstalledInRevision, assertNoEditableInstalls } from "./editable-check.ts";
+import { parsePipRequirements, runPipInstall } from "./py-installer.ts";
+import { publishNextRevision, type Revision } from "./revision-store.ts";
+
+const execFileAsync = promisify(execFile);
+
+export type EnvironmentMode = "managed" | "project";
+
+export interface InstallReceipt {
+	readonly manager: "pip";
+	readonly mode: EnvironmentMode;
+	readonly root: string;
+	readonly revision: number;
+	readonly requested: readonly string[];
+	readonly resolved: readonly string[];
+	readonly changed: boolean;
+}
+
+export function managedEnvironmentBase(artifactsDir: string, language: "py", abiTag: string): string {
+	return join(artifactsDir, "environments", language, abiTag);
+}
+
+export function projectPythonBase(cwd: string): string {
+	return join(cwd, ".senpi", "python-packages");
+}
+
+export async function pythonAbiTag(interpreter: string): Promise<string> {
+	const { stdout } = await execFileAsync(interpreter, [
+		"-c",
+		"import sys, sysconfig; print(sys.implementation.cache_tag, sysconfig.get_platform(), sys.executable)",
+	]);
+	return createHash("sha256").update(stdout.trim()).digest("hex").slice(0, 12);
+}
+
+export async function installPythonPackages(input: {
+	readonly base: string;
+	readonly mode: EnvironmentMode;
+	readonly interpreter: string;
+	readonly requirements: string;
+	readonly cwd: string;
+	readonly signal: AbortSignal;
+	readonly onOutput?: (stream: "stdout" | "stderr", data: string) => void;
+}): Promise<InstallReceipt> {
+	const requested = parsePipRequirements(input.requirements);
+	let stdout = "";
+	const { revision } = await publishNextRevision(
+		input.base,
+		async (staging) => {
+			await runPipInstall({
+				interpreter: input.interpreter,
+				root: staging,
+				args: requested,
+				cwd: input.cwd,
+				signal: input.signal,
+				onOutput: (stream, data) => {
+					if (stream === "stdout") stdout += data;
+					input.onOutput?.(stream, data);
+				},
+			});
+			await assertInstalledInRevision(stdout, staging);
+			await assertNoEditableInstalls(staging);
+		},
+		input.signal,
+		({ holder, waitedMs }) =>
+			input.onOutput?.(
+				"stderr",
+				`[senpi] waiting ${Math.round(waitedMs / 1000)}s for another install into this environment${holder === undefined ? "" : ` (pid ${holder.pid} on ${holder.host})`}\n`,
+			),
+	);
+	const resolved = installedDistributions(stdout);
+	return receipt(input.mode, revision, requested, resolved);
+}
+
+function receipt(
+	mode: EnvironmentMode,
+	revision: Revision,
+	requested: readonly string[],
+	resolved: readonly string[],
+): InstallReceipt {
+	return {
+		manager: "pip",
+		mode,
+		root: revision.dir,
+		revision: revision.number,
+		requested,
+		resolved,
+		changed: resolved.length > 0,
+	};
+}
+
+function installedDistributions(stdout: string): string[] {
+	const line = stdout.split("\n").find((entry) => entry.startsWith("Successfully installed "));
+	return line === undefined ? [] : line.slice("Successfully installed ".length).trim().split(/\s+/);
+}

package/src/environments/py-installer.ts

@@ -0,0 +1,247 @@
+import { spawn } from "node:child_process";
+import { devNull } from "node:os";
+import { terminateProcessTrees } from "../kernels/js/process-tree-host.ts";
+
+export type EnvironmentErrorCode =
+	| "environment_install_failed"
+	| "environment_install_timeout"
+	| "environment_install_cancelled"
+	| "environment_installer_unavailable"
+	| "environment_resolution_conflict"
+	| "environment_language_mismatch";
+
+export class EnvironmentError extends Error {
+	readonly name = "EnvironmentError";
+	readonly code: EnvironmentErrorCode;
+
+	constructor(code: EnvironmentErrorCode, message: string) {
+		super(`${code}: ${message}`);
+		this.code = code;
+	}
+}
+
+// pip accepts any unambiguous prefix of a long option and grouped short flags, so a denylist of destination
+// options can't be complete. Only these options are accepted, each spelled out in full.
+const ALLOWED_FLAGS = new Set([
+	"--upgrade",
+	"--no-deps",
+	"--pre",
+	"--force-reinstall",
+	"--no-index",
+	"--no-cache-dir",
+	"--only-binary",
+	"--no-binary",
+	"--prefer-binary",
+	"--index-url",
+	"--extra-index-url",
+	"--find-links",
+	"--constraint",
+	"--requirement",
+	"--quiet",
+	"--verbose",
+]);
+const FLAGS_WITH_VALUE = new Set([
+	"--only-binary",
+	"--no-binary",
+	"--index-url",
+	"--extra-index-url",
+	"--find-links",
+	"--constraint",
+	"--requirement",
+]);
+const SHORT_ALIASES: Readonly<Record<string, string>> = {
+	"-U": "--upgrade",
+	"-i": "--index-url",
+	"-f": "--find-links",
+	"-c": "--constraint",
+	"-r": "--requirement",
+	"-q": "--quiet",
+	"-v": "--verbose",
+};
+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 = 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");
+	}
+	if (command.length === 0) throw new EnvironmentError("environment_install_failed", "name at least one requirement");
+	const normalized: string[] = [];
+	for (let index = 0; index < command.length; index++) {
+		const arg = command[index] ?? "";
+		if (!arg.startsWith("-")) {
+			normalized.push(arg);
+			continue;
+		}
+		const [spelled = arg, attached] = arg.split(/=(.*)/su, 2);
+		const flag = SHORT_ALIASES[spelled] ?? spelled;
+		if (!ALLOWED_FLAGS.has(flag)) {
+			throw new EnvironmentError(
+				"environment_install_failed",
+				`${spelled} is not allowed: %pip accepts ${[...ALLOWED_FLAGS].join(", ")} (each spelled out in full); packages always install into the session's environment root`,
+			);
+		}
+		if (!FLAGS_WITH_VALUE.has(flag)) {
+			if (attached !== undefined)
+				throw new EnvironmentError("environment_install_failed", `${spelled} takes no value`);
+			normalized.push(flag);
+			continue;
+		}
+		const value = attached ?? command[++index];
+		if (value === undefined || value === "" || value.startsWith("-")) {
+			throw new EnvironmentError("environment_install_failed", `${spelled} needs a value`);
+		}
+		normalized.push(`${flag}=${value}`);
+	}
+	const named = normalized.some((arg) => !arg.startsWith("-") || arg.startsWith("--requirement="));
+	if (!named) throw new EnvironmentError("environment_install_failed", "name at least one requirement");
+	return normalized;
+}
+
+/**
+ * pip's environment with every PIP_* variable removed and its config file pointed at nothing: `--isolated`
+ * alone still honours PIP_CONFIG_FILE, and a configured target, root or prefix would install outside the revision.
+ */
+export function isolatedPipEnv(): NodeJS.ProcessEnv {
+	const env: NodeJS.ProcessEnv = {};
+	for (const [key, value] of Object.entries(process.env)) {
+		if (!key.toUpperCase().startsWith("PIP_")) env[key] = value;
+	}
+	// pip skips every config file when PIP_CONFIG_FILE equals Python's os.devnull: "nul" on Windows, not Node's "\\\\.\\nul".
+	return { ...env, PIP_CONFIG_FILE: process.platform === "win32" ? "nul" : devNull, PYTHONNOUSERSITE: "1" };
+}
+
+export function runPipInstall(input: {
+	readonly interpreter: string;
+	readonly root: string;
+	readonly args: readonly string[];
+	readonly cwd: string;
+	readonly signal: AbortSignal;
+	readonly onOutput?: (stream: "stdout" | "stderr", data: string) => void;
+}): Promise<void> {
+	const argv = [
+		"-m",
+		"pip",
+		"install",
+		// Ignore pip's config files and PIP_* variables: a configured `root` or `prefix` would write outside the revision.
+		"--isolated",
+		"--disable-pip-version-check",
+		"--no-input",
+		"--target",
+		input.root,
+		...input.args,
+	];
+	return new Promise((resolve, reject) => {
+		if (input.signal.aborted) {
+			reject(new EnvironmentError("environment_install_cancelled", "the install was cancelled before it started"));
+			return;
+		}
+		const child = spawn(input.interpreter, argv, {
+			cwd: input.cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+			env: isolatedPipEnv(),
+		});
+		let stderrTail = "";
+		child.stdout.setEncoding("utf8").on("data", (data: string) => input.onOutput?.("stdout", data));
+		child.stderr.setEncoding("utf8").on("data", (data: string) => {
+			stderrTail = (stderrTail + data).slice(-STDERR_TAIL_BYTES);
+			input.onOutput?.("stderr", data);
+		});
+		// pip's build backends run in their own subprocesses; stopping only pip would leave them writing.
+		const onAbort = () => {
+			const pid = child.pid;
+			if (pid === undefined) child.kill("SIGKILL");
+			else void terminateProcessTrees([pid], { graceMs: PIP_TREE_GRACE_MS }).catch(() => child.kill("SIGKILL"));
+		};
+		input.signal.addEventListener("abort", onAbort, { once: true });
+		child.once("error", (error) => {
+			input.signal.removeEventListener("abort", onAbort);
+			reject(
+				new EnvironmentError("environment_installer_unavailable", `${input.interpreter} -m pip: ${error.message}`),
+			);
+		});
+		child.once("close", (code, signal) => {
+			input.signal.removeEventListener("abort", onAbort);
+			if (input.signal.aborted) {
+				reject(new EnvironmentError("environment_install_cancelled", "the install was cancelled; pip was stopped"));
+			} else if (code === 0) resolve();
+			else if (/No module named pip/.test(stderrTail)) {
+				reject(new EnvironmentError("environment_installer_unavailable", `${input.interpreter} has no pip module`));
+			} else if (/ResolutionImpossible|conflicting dependencies/.test(stderrTail)) {
+				reject(new EnvironmentError("environment_resolution_conflict", stderrTail.trim()));
+			} else {
+				reject(
+					new EnvironmentError(
+						"environment_install_failed",
+						stderrTail.trim() || `pip exited with ${code ?? signal}`,
+					),
+				);
+			}
+		});
+	});
+}

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

@@ -0,0 +1,110 @@
+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";
+import { EnvironmentError } from "./py-installer.ts";
+
+const POINTER = "active";
+const REVISION = /^rev-(\d+)$/;
+
+export interface Revision {
+	readonly number: number;
+	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 {
+		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;
+	}
+}
+
+/**
+ * Builds the next revision under the root's lock: a staging copy of the active revision (so packages
+ * accumulate) is handed to `build`, renamed to `rev-<n>` only after `build` succeeds, and published by an
+ * atomic replace of the `active` pointer. A failed, cancelled or interrupted build is deleted; the
+ * previous revision stays active and is never modified, so a running kernel never sees a partial install.
+ */
+export async function publishNextRevision(
+	base: string,
+	build: (staging: string, previous: Revision | undefined) => Promise<void>,
+	signal?: AbortSignal,
+	onLockWait?: (notice: LockWaitNotice) => void,
+): Promise<{ readonly revision: Revision; readonly previous: Revision | undefined }> {
+	await mkdir(base, { recursive: true });
+	return withRootLock(
+		base,
+		async () => {
+			const previous = await readActiveRevision(base);
+			const number = Math.max(previous?.number ?? 0, await highestRevision(base)) + 1;
+			const staging = join(base, `.staging-rev-${number}-${process.pid}-${randomUUID()}`);
+			const dir = join(base, `rev-${number}`);
+			try {
+				if (previous === undefined) await mkdir(staging, { recursive: true });
+				else await cp(previous.dir, staging, { recursive: true, verbatimSymlinks: true });
+				await build(staging, previous);
+				signal?.throwIfAborted();
+				await renameRetrying(staging, dir);
+				const pointer = join(base, `.${POINTER}-${process.pid}-${randomUUID()}`);
+				await writeFile(pointer, `rev-${number}\n`);
+				await renameRetrying(pointer, join(base, POINTER));
+			} catch (error) {
+				await rm(staging, { recursive: true, force: true });
+				throw error;
+			}
+			return { revision: { number, dir }, previous };
+		},
+		signal,
+		onLockWait,
+	);
+}
+
+const RENAME_RETRY_DELAYS_MS = [20, 50, 100, 200, 400, 800];
+
+// On Windows a rename fails with EPERM/EBUSY/EACCES while another process (an indexer, antivirus) holds a
+// handle on the source or the replaced file; those holds are brief, so the rename is retried before failing.
+async function renameRetrying(from: string, to: string): Promise<void> {
+	for (let attempt = 0; ; attempt++) {
+		try {
+			await rename(from, to);
+			return;
+		} catch (error) {
+			const code = error instanceof Error && "code" in error ? error.code : undefined;
+			const transient = code === "EPERM" || code === "EBUSY" || code === "EACCES";
+			const delay = RENAME_RETRY_DELAYS_MS[attempt];
+			if (!transient || delay === undefined) {
+				const reason = error instanceof Error ? error.message : String(error);
+				throw new EnvironmentError("environment_install_failed", `could not publish the new revision: ${reason}`);
+			}
+			await new Promise((resolve) => setTimeout(resolve, delay));
+		}
+	}
+}
+
+async function highestRevision(base: string): Promise<number> {
+	let highest = 0;
+	for (const entry of await readdir(base)) {
+		const match = REVISION.exec(entry);
+		if (match?.[1] !== undefined) highest = Math.max(highest, Number(match[1]));
+	}
+	return highest;
+}

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-registration.ts

@@ -4,6 +4,7 @@ import type { BridgeConnectionConfig, KernelToHostMessage } from "../bridge/prot
 import { JuliaKernel } from "../kernels/jl/kernel.ts";
 import type { JavaScriptKernel } from "../kernels/js/context-manager.ts";
 import { PythonKernel } from "../kernels/py/kernel.ts";
+import type { PeerKernelToolsDescribe } from "../kernels/py/kernel-tools-host.ts";
 import { defaultSpawn } from "../kernels/py/process.ts";
 import { RubyKernel } from "../kernels/rb/kernel.ts";
 import type { SessionEnvironment } from "../kernels/session-env.ts";
@@ -27,6 +28,7 @@ export interface SubprocessKernelStart {
 		readonly connection: BridgeConnectionConfig;
 		readonly onMessage: (message: KernelToHostMessage) => void;
 	};
+	readonly peerKernelToolsDescribe?: PeerKernelToolsDescribe;
 }
 
 export function registerKernel(sessionId: string, language: EvalLanguage, memory: RegisteredKernelSource): string {
@@ -82,6 +84,9 @@ export async function startSubprocessKernel(start: SubprocessKernelStart): Promi
 			...shared,
 			interpreterPath: start.interpreterPath,
 			memory,
+			...(start.peerKernelToolsDescribe === undefined
+				? {}
+				: { peerKernelToolsDescribe: start.peerKernelToolsDescribe }),
 			spawnProcess: (options) => {
 				const child = defaultSpawn(options);
 				pid = child.pid;

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,
+					}),
+				}
+			: {}),
 	};
 }