@code-yeongyu/senpi-codemode 2026.10.7 → 2026.10.8

package/src/environments/py-installer.ts

@@ -0,0 +1,187 @@
+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;
+
+export function parsePipRequirements(text: string): string[] {
+	const args = text
+		.trim()
+		.split(/\s+/)
+		.filter((arg) => arg !== "");
+	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/revision-store.ts

@@ -0,0 +1,95 @@
+import { randomUUID } from "node:crypto";
+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;
+}
+
+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) };
+	} 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/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/session-manager.ts

@@ -6,6 +6,7 @@ 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 { KernelLifecycle } from "../kernels/shared/kernel-death.ts";
 import type { EvalKernel, EvalLanguage } from "../tool/types.ts";
 import { type BridgeDispatchContext, dispatchBridgeCompletion } from "./bridge-dispatch.ts";
@@ -276,7 +277,20 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 			...lifecycle,
 		};
 		const memory = resolveKernelMemoryThresholds(this.#options.settings.memory);
-		return await startSubprocessKernel({ language, interpreterPath: detected.path, memory, shared });
+		return await startSubprocessKernel({
+			language,
+			interpreterPath: detected.path,
+			memory,
+			shared,
+			peerKernelToolsDescribe: (names) => this.#javaScriptKernelToolsDescribe(names),
+		});
+	}
+
+	/** Only an already running JavaScript kernel can define a colliding name; none is started for this. */
+	#javaScriptKernelToolsDescribe(names: readonly string[]): Promise<KernelToolsDescribeResult> | undefined {
+		const js = this.#kernels.get("js");
+		if (!js || !("describeKernelTools" in js) || typeof js.describeKernelTools !== "function") return undefined;
+		return (js.describeKernelTools as (names: readonly string[]) => Promise<KernelToolsDescribeResult>)(names);
 	}
 
 	#foreignKernelToolNames(): string[] {

package/src/kernels/js/kernel-tools-errors.js

@@ -8,6 +8,8 @@ export const KERNEL_TOOL_ERROR_CODES = Object.freeze([
 	"kernel_tool_failed",
 	"kernel_tool_recursion",
 	"kernel_tool_host_denied",
+	"kernel_tool_cancelled",
+	"kernel_tool_loop_mismatch",
 ]);
 
 export class KernelToolError extends Error {

package/src/kernels/js/kernel-tools-errors.ts

@@ -8,6 +8,8 @@ export const KERNEL_TOOL_ERROR_CODES = [
 	"kernel_tool_failed",
 	"kernel_tool_recursion",
 	"kernel_tool_host_denied",
+	"kernel_tool_cancelled",
+	"kernel_tool_loop_mismatch",
 ] as const;
 
 export type KernelToolErrorCode = (typeof KERNEL_TOOL_ERROR_CODES)[number];

package/src/kernels/py/kernel-contract.ts

@@ -3,7 +3,8 @@ import type { BridgeConnectionConfig, KernelToHostMessage } from "../../bridge/p
 import type { EvalKernelRunInput } from "../../tool/types.ts";
 import type { SessionEnvironment } from "../session-env.ts";
 import type { KernelLifecycle } from "../shared/kernel-death.ts";
-import type { KernelSpawnProcess } from "./process.ts";
+import type { PeerKernelToolsDescribe } from "./kernel-tools-host.ts";
+import type { KernelSpawnProcess, KillProcessGroup } from "./process.ts";
 import type { PythonStartupStage } from "./startup.ts";
 import type { PythonTransportResult } from "./transport.ts";
 
@@ -15,14 +16,22 @@ export interface PythonKernelStartOptions extends KernelLifecycle {
 	readonly env?: NodeJS.ProcessEnv;
 	/** Per-session PI_* values merged into the interpreter environment at spawn. */
 	readonly sessionEnv?: SessionEnvironment;
-	/** Python bootstrap inactivity guard per advancing stage, not a total readiness deadline. */
+	/** How long a starting interpreter may show no stage change, output or CPU use before startup fails. */
 	readonly startupTimeoutMs?: number;
+	/** Total startup backstop for an interpreter that stays busy but never becomes ready. */
+	readonly startupCeilingMs?: number;
+	/** Reads the interpreter's CPU time; the default reads the process group (Unix) or the process (Windows). */
+	readonly readCpuTime?: (pid: number | undefined) => bigint | undefined;
+	/** Signals the interpreter's process group when it is retired; the default is `process.kill(-pid, signal)`. */
+	readonly killProcessGroup?: KillProcessGroup;
 	/** Observes bootstrap control events without mixing them into cell output callbacks. */
 	readonly onStartupProgress?: (stage: PythonStartupStage) => void;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
 	readonly spawnProcess?: KernelSpawnProcess;
 	/** Post-cell collection, notice, and ceiling thresholds sent on `init`; absent leaves memory unmanaged. */
 	readonly memory?: KernelMemoryThresholds;
+	/** The JavaScript kernel's describe, so a name defined in both languages is a describe-time collision. */
+	readonly peerKernelToolsDescribe?: PeerKernelToolsDescribe;
 }
 
 export type PythonKernelRunOptions = EvalKernelRunInput;

package/src/kernels/py/kernel-tools-host.ts

@@ -0,0 +1,97 @@
+import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
+import { kernelToolError } from "../js/kernel-tools-errors.ts";
+import type {
+	KernelToolsDescribeResult,
+	KernelToolsInvokeOptions,
+	KernelToolsInvokeRequest,
+} from "../js/kernel-tools-types.ts";
+import { KernelToolHostPump } from "../shared/kernel-tools-pump.ts";
+
+export type KernelToolReplyEvent = {
+	readonly requestId: string;
+	readonly ok: boolean;
+	readonly code?: string;
+	readonly message?: string;
+	readonly output?: string;
+};
+
+function replyEvent(message: Extract<KernelToHostMessage, { type: "kernel-tool-invoke-reply" }>): KernelToolReplyEvent {
+	return {
+		requestId: message.requestId,
+		ok: message.ok,
+		...(message.ok ? {} : { message: message.error.message }),
+		...(!message.ok && message.error.code !== undefined ? { code: message.error.code } : {}),
+		...(message.output === undefined ? {} : { output: message.output }),
+	};
+}
+
+export type PeerKernelToolsDescribe = (names: readonly string[]) => Promise<KernelToolsDescribeResult> | undefined;
+
+/** The host half of Python kernel tools: frames over the live transport, names, and generation fencing. */
+export class PythonKernelTools {
+	readonly #pump: KernelToolHostPump;
+	readonly #peerDescribe: PeerKernelToolsDescribe | undefined;
+	#names: readonly string[] = [];
+
+	constructor(options: {
+		readonly post: (message: HostToKernelMessage) => void;
+		readonly isOpen: () => boolean;
+		readonly peerDescribe?: PeerKernelToolsDescribe;
+	}) {
+		this.#pump = new KernelToolHostPump(options.post, options.isOpen);
+		this.#peerDescribe = options.peerDescribe;
+	}
+
+	get events(): EventTarget {
+		return this.#pump.events;
+	}
+
+	listNames(): readonly string[] {
+		return this.#names;
+	}
+
+	consume(message: KernelToHostMessage): boolean {
+		if (message.type === "kernel-tools-defined") {
+			this.#names = [...message.names];
+			return true;
+		}
+		if (message.type === "kernel-tool-invoke-reply") {
+			// Published even when the waiter is gone (a cancelled call), so its explicit outcome stays observable.
+			this.#pump.events.dispatchEvent(
+				new CustomEvent<KernelToolReplyEvent>("kernelToolReply", { detail: replyEvent(message) }),
+			);
+		}
+		return this.#pump.consume(message);
+	}
+
+	/** The interpreter is gone (restart, reset, close, death): its definitions and in-flight calls are too. */
+	retire(reason: "kernel_tool_stale" | "tools_unavailable", message: string): void {
+		this.#names = [];
+		this.#pump.rejectAll(kernelToolError(reason, message));
+	}
+
+	async describe(names: readonly string[]): Promise<KernelToolsDescribeResult> {
+		const own = await this.#pump.describe(names);
+		const peer = await this.#peerDescribe?.(names)?.catch(() => undefined);
+		if (!peer) return own;
+		const definedInJs = new Set(peer.results.filter((entry) => entry.ok).map((entry) => entry.name));
+		return {
+			results: own.results.map((entry) =>
+				entry.ok && definedInJs.has(entry.name)
+					? {
+							name: entry.name,
+							ok: false,
+							error: {
+								code: "tool_name_collision",
+								message: `Kernel tool ${entry.name} is defined in both js and py`,
+							},
+						}
+					: entry,
+			),
+		};
+	}
+
+	async invoke(request: KernelToolsInvokeRequest, options?: AbortSignal | KernelToolsInvokeOptions): Promise<unknown> {
+		return await this.#pump.invoke(request, options);
+	}
+}

package/src/kernels/py/kernel.ts

@@ -1,13 +1,17 @@
 // allow: SIZE_OK — one persistent Python lifecycle state machine owns queue, generation, and retirement.
 import type { KernelInterruptHandle, PendingCell } from "../../tool/types.ts";
-import type { KernelToolsInvokeOptions } from "../js/kernel-tools-types.ts";
-import { rejectKernelToolsUnavailable } from "../kernel-tools-unavailable.ts";
+import type {
+	KernelToolsDescribeResult,
+	KernelToolsInvokeOptions,
+	KernelToolsInvokeRequest,
+} from "../js/kernel-tools-types.ts";
 import { describeExit } from "../shared/kernel-death.ts";
 import { KernelMemoryHost } from "../shared/kernel-memory-host.ts";
 import { KernelPreludeTracker } from "../shared/kernel-prelude-plan.ts";
 import { runHostCell } from "./host-cell.ts";
 import type { PendingRun, PythonKernelRunOptions, PythonKernelStartOptions, ResultMessage } from "./kernel-contract.ts";
-import { pythonStartupHangGuardMs } from "./startup.ts";
+import { PythonKernelTools } from "./kernel-tools-host.ts";
+import { pythonStartupCeilingMs, pythonStartupHangGuardMs } from "./startup.ts";
 import { failedPythonResult, PythonKernelTransport } from "./transport.ts";
 
 export type { PythonKernelRunOptions, PythonKernelStartOptions } from "./kernel-contract.ts";
@@ -15,6 +19,15 @@ export type { KernelChild, KernelSpawnOptions, KernelSpawnProcess } from "./proc
 
 const interruptEscalationMs = 5_000;
 
+// Every interpreter this process starts gets its own generation, so a kernel tool descriptor taken from one
+// never resolves in another, whether it was replaced by reset, by a lazy restart after a crash, or by a new
+// kernel instance an owner created.
+let lastInterpreterGeneration = 0;
+function nextInterpreterGeneration(): number {
+	lastInterpreterGeneration += 1;
+	return lastInterpreterGeneration;
+}
+
 export class PythonKernel {
 	readonly #options: PythonKernelStartOptions;
 	#transport: PythonKernelTransport | null = null;
@@ -29,11 +42,17 @@ export class PythonKernel {
 	readonly #memory: KernelMemoryHost | null;
 	#generation = 0;
 	#closed = false;
+	readonly #tools: PythonKernelTools;
 	#dead = false;
 
 	private constructor(options: PythonKernelStartOptions) {
 		this.#options = options;
 		this.#memory = options.memory === undefined ? null : new KernelMemoryHost("py", options.memory);
+		this.#tools = new PythonKernelTools({
+			post: (message) => this.#transport?.post(message),
+			isOpen: () => this.#transport !== null && !this.#closed,
+			...(options.peerKernelToolsDescribe === undefined ? {} : { peerDescribe: options.peerKernelToolsDescribe }),
+		});
 	}
 
 	static async start(options: PythonKernelStartOptions): Promise<PythonKernel> {
@@ -43,7 +62,11 @@ export class PythonKernel {
 	}
 
 	listKernelToolNames(): readonly string[] {
-		return [];
+		return this.#tools.listNames();
+	}
+
+	get kernelToolEvents(): EventTarget {
+		return this.#tools.events;
 	}
 
 	isAlive(): boolean {
@@ -58,12 +81,15 @@ export class PythonKernel {
 		});
 	}
 
-	describeKernelTools(_names: readonly string[]): Promise<never> {
-		return rejectKernelToolsUnavailable();
+	describeKernelTools(names: readonly string[]): Promise<KernelToolsDescribeResult> {
+		return this.#tools.describe(names);
 	}
 
-	invokeKernelTool(_request: unknown, _options?: AbortSignal | KernelToolsInvokeOptions): Promise<never> {
-		return rejectKernelToolsUnavailable();
+	invokeKernelTool(
+		request: KernelToolsInvokeRequest,
+		options?: AbortSignal | KernelToolsInvokeOptions,
+	): Promise<unknown> {
+		return this.#tools.invoke(request, options);
 	}
 
 	run(input: PythonKernelRunOptions): Promise<ResultMessage> {
@@ -131,6 +157,7 @@ export class PythonKernel {
 		if (this.#failure) throw this.#failure;
 		if (this.#closed) throw new Error("Python kernel is closed");
 		const generation = ++this.#generation;
+		this.#tools.retire("kernel_tool_stale", "Python kernel was reset; its kernel tools are gone");
 		const prior = this.#starting;
 		const operation = (async () => {
 			await prior?.catch(() => undefined);
@@ -156,6 +183,7 @@ export class PythonKernel {
 		if (this.#closePromise) return await this.#closePromise;
 		this.#closed = true;
 		this.#generation += 1;
+		this.#tools.retire("tools_unavailable", "Python kernel is closed");
 		this.#settleAllPending("Python kernel closed");
 		const starting = this.#starting;
 		this.#closePromise = (async () => {
@@ -283,6 +311,7 @@ export class PythonKernel {
 			...this.#options,
 			onMessage: (message) => {
 				if (message.type === "result") return;
+				if (generation === this.#generation && this.#tools.consume(message)) return;
 				const callback =
 					message.type === "ready" || message.type === "init-failed" || message.type === "closed"
 						? this.#options.onMessage
@@ -290,6 +319,8 @@ export class PythonKernel {
 				callback?.(message);
 			},
 			startupTimeoutMs: this.#options.startupTimeoutMs ?? pythonStartupHangGuardMs,
+			startupCeilingMs: this.#options.startupCeilingMs ?? pythonStartupCeilingMs,
+			kernelGeneration: nextInterpreterGeneration(),
 			isOwned: () => !this.#closed && generation === this.#generation,
 			onRetirementFailure: (transport, error) => {
 				if (!this.#transport) this.#transport = transport;
@@ -324,6 +355,7 @@ export class PythonKernel {
 	#onExit(transport: PythonKernelTransport, error: Error, reason: string): void {
 		if (this.#transport !== transport) return;
 		this.#transport = null;
+		this.#tools.retire("kernel_tool_stale", "Python kernel died; its kernel tools are gone");
 		// With an owner listening, a death is final for this instance: the cells that never started stay
 		// queued for `drainPending` and the owner replaces it. Without one it respawns lazily, as before.
 		const onDeath = this.#options.onDeath;