@code-yeongyu/senpi-codemode 2026.10.5 → 2026.10.6

package/src/extension/idle-parking-kernel.ts

@@ -0,0 +1,272 @@
+import type { HostToKernelMessage } from "../bridge/protocol.ts";
+import { kernelToolError } from "../kernels/js/kernel-tools-errors.ts";
+import { restartNotice, unstartedResult } from "../kernels/shared/kernel-death.ts";
+import type {
+	EvalKernel,
+	EvalKernelResult,
+	EvalKernelRunInput,
+	EvalLanguage,
+	KernelInterruptHandle,
+} from "../tool/types.ts";
+import { hasKernelTools, type KernelToolsMethods } from "./kernel-tools-probe.ts";
+
+export type RestartParkedKernel = () => Promise<EvalKernel>;
+
+class IdleParkingKernelClosedError extends Error {
+	readonly name = "IdleParkingKernelClosedError";
+
+	constructor() {
+		super("Kernel closed");
+	}
+}
+
+interface WaitingCell {
+	readonly cancel: (reason: string) => void;
+}
+
+/**
+ * Opt-in (`memory.idleParkMinutes` > 0): once no cell has been running or queued on the session's kernel for
+ * the configured time, closes it to give its memory back, and starts a fresh one when the next cell arrives.
+ * That cell's result says the kernel was restarted and every global is gone. A cell submitted while the
+ * kernel is being parked or restarted waits for the fresh kernel; a restart that fails settles that cell
+ * with the reason, and the next cell tries again.
+ */
+export class IdleParkingKernel implements EvalKernel {
+	readonly #language: EvalLanguage;
+	readonly #idleMs: number;
+	readonly #restart: RestartParkedKernel;
+	readonly #onParked: () => void;
+	#kernel: EvalKernel | null;
+	#inFlight = 0;
+	#timer: ReturnType<typeof setTimeout> | undefined;
+	#parking: Promise<void> | null = null;
+	#parkFailure: string | null = null;
+	#starting: Promise<EvalKernel> | null = null;
+	#announce: string | null = null;
+	readonly #waiting = new Map<string, WaitingCell>();
+	#closed = false;
+	// Present only when the wrapped kernel has kernel tools, so a probe for them sees what it saw before.
+	declare readonly describeKernelTools?: KernelToolsMethods["describeKernelTools"];
+	declare readonly invokeKernelTool?: KernelToolsMethods["invokeKernelTool"];
+
+	constructor(
+		language: EvalLanguage,
+		idleMinutes: number,
+		first: EvalKernel,
+		restart: RestartParkedKernel,
+		onParked: () => void = () => {},
+	) {
+		this.#language = language;
+		this.#idleMs = idleMinutes * 60_000;
+		this.#restart = restart;
+		this.#onParked = onParked;
+		this.#kernel = first;
+		if (hasKernelTools(first)) {
+			const tools: KernelToolsMethods = {
+				describeKernelTools: (names) => this.#withTools((kernel) => kernel.describeKernelTools(names)),
+				invokeKernelTool: (request, options) =>
+					this.#withTools((kernel) => kernel.invokeKernelTool(request, options)),
+			};
+			Object.assign(this, tools);
+		}
+		this.#arm();
+	}
+
+	run(input: EvalKernelRunInput): Promise<EvalKernelResult> {
+		if (this.#closed) return Promise.reject(new IdleParkingKernelClosedError());
+		this.#disarm();
+		this.#inFlight++;
+		return this.#runOnCurrent(input).finally(() => {
+			this.#inFlight--;
+			this.#arm();
+		});
+	}
+
+	cancelQueued(cellId: string, reason: string): boolean {
+		if (this.#cancelWaiting(cellId, reason)) return true;
+		return this.#kernel?.cancelQueued(cellId, reason) ?? false;
+	}
+
+	async interrupt(reason = "interrupted", cellId?: string): Promise<KernelInterruptHandle> {
+		if (cellId !== undefined && this.#cancelWaiting(cellId, reason)) return { stateRetained: Promise.resolve(true) };
+		if (cellId === undefined) for (const id of [...this.#waiting.keys()]) this.#cancelWaiting(id, reason);
+		const kernel = this.#kernel;
+		if (kernel === null) return { stateRetained: Promise.resolve(true) };
+		return await kernel.interrupt(reason, cellId);
+	}
+
+	queueSnapshot(): { activeCellId: string | null; queuedCellIds: readonly string[] } {
+		const current = this.#kernel?.queueSnapshot() ?? { activeCellId: null, queuedCellIds: [] };
+		return { activeCellId: current.activeCellId, queuedCellIds: [...current.queuedCellIds, ...this.#waiting.keys()] };
+	}
+
+	deliverToolReply(message: Extract<HostToKernelMessage, { type: "tool-reply" }>): void {
+		this.#kernel?.deliverToolReply(message);
+	}
+
+	async reset(): Promise<void> {
+		this.#announce = null;
+		const kernel = this.#kernel;
+		if (kernel !== null) await kernel.reset();
+	}
+
+	async close(): Promise<void> {
+		this.#closed = true;
+		this.#disarm();
+		for (const id of [...this.#waiting.keys()]) this.#cancelWaiting(id, new IdleParkingKernelClosedError().message);
+		if (this.#parking !== null) await this.#parking;
+		if (this.#starting !== null) await this.#starting.catch(() => undefined);
+		const kernel = this.#kernel;
+		this.#kernel = null;
+		if (kernel !== null) await kernel.close();
+	}
+
+	listKernelToolNames(): readonly string[] {
+		return this.#kernel?.listKernelToolNames?.() ?? [];
+	}
+
+	/** A tool call is work on the kernel: it keeps the kernel from being parked under it. */
+	async #withTools<T>(use: (kernel: KernelToolsMethods) => Promise<T>): Promise<T> {
+		const kernel = this.#parking === null ? this.#kernel : null;
+		if (this.#closed || kernel === null || !hasKernelTools(kernel)) {
+			throw kernelToolError(
+				"tools_unavailable",
+				`the ${this.#language} kernel was parked after idling, so the tools it defined are gone; run a cell to start a fresh kernel`,
+			);
+		}
+		this.#disarm();
+		this.#inFlight++;
+		try {
+			return await use(kernel);
+		} finally {
+			this.#inFlight--;
+			this.#arm();
+		}
+	}
+
+	#runOnCurrent(input: EvalKernelRunInput): Promise<EvalKernelResult> {
+		const kernel = this.#kernel;
+		if (kernel !== null && this.#parking === null) return kernel.run(input).then((result) => this.#announced(result));
+		return new Promise((settle, reject) => {
+			let cancelled = false;
+			this.#waiting.set(input.cellId, {
+				cancel: (reason) => {
+					cancelled = true;
+					settle(unstartedResult(input.cellId, reason));
+				},
+			});
+			this.#current().then(
+				(current) => {
+					this.#waiting.delete(input.cellId);
+					if (cancelled) return;
+					current.run(input).then((result) => settle(this.#announced(result)), reject);
+				},
+				(error: unknown) => {
+					this.#waiting.delete(input.cellId);
+					if (!cancelled) settle(unstartedResult(input.cellId, this.#restartFailure(error)));
+				},
+			);
+		});
+	}
+
+	async #current(): Promise<EvalKernel> {
+		if (this.#parking !== null) await this.#parking;
+		const failure = this.#parkFailure;
+		if (failure !== null) {
+			this.#parkFailure = null;
+			throw new Error(failure);
+		}
+		if (this.#kernel !== null) return this.#kernel;
+		if (this.#closed) throw new IdleParkingKernelClosedError();
+		this.#starting ??= this.#restart()
+			.then((kernel) => {
+				this.#kernel = kernel;
+				this.#announce = restartNotice(this.#language, this.#parkReason());
+				return kernel;
+			})
+			.finally(() => {
+				this.#starting = null;
+			});
+		return await this.#starting;
+	}
+
+	#announced(result: EvalKernelResult): EvalKernelResult {
+		const notice = this.#announce;
+		if (notice === null) return result;
+		this.#announce = null;
+		return {
+			...result,
+			notice: result.notice === undefined ? notice : `${notice}\n${result.notice}`,
+			kernelState: "restarted",
+		};
+	}
+
+	#arm(): void {
+		if (this.#closed || this.#inFlight > 0 || this.#kernel === null || this.#timer !== undefined) return;
+		this.#timer = setTimeout(() => {
+			this.#timer = undefined;
+			this.#park();
+		}, this.#idleMs);
+		this.#timer.unref?.();
+	}
+
+	#disarm(): void {
+		if (this.#timer === undefined) return;
+		clearTimeout(this.#timer);
+		this.#timer = undefined;
+	}
+
+	#park(): void {
+		const kernel = this.#kernel;
+		if (this.#closed || this.#inFlight > 0 || kernel === null) return;
+		const snapshot = kernel.queueSnapshot();
+		// Tools a cell defined stay callable by child tasks between cells, so their kernel is never parked.
+		const hasTools = (kernel.listKernelToolNames?.() ?? []).length > 0;
+		if (snapshot.activeCellId !== null || snapshot.queuedCellIds.length > 0 || hasTools) {
+			this.#arm();
+			return;
+		}
+		this.#kernel = null;
+		this.#onParked();
+		const parking = kernel
+			.close()
+			.catch((error: unknown) => {
+				this.#parkFailure = `the idle ${this.#language} kernel could not be stopped: ${errorText(error)}; run the cell again to start a fresh kernel`;
+			})
+			.finally(() => {
+				if (this.#parking === parking) this.#parking = null;
+			});
+		this.#parking = parking;
+	}
+
+	#cancelWaiting(cellId: string, reason: string): boolean {
+		const waiting = this.#waiting.get(cellId);
+		if (waiting === undefined) return false;
+		this.#waiting.delete(cellId);
+		waiting.cancel(reason);
+		return true;
+	}
+
+	#parkReason(): string {
+		const minutes = this.#idleMs / 60_000;
+		return `idling for ${minutes} minute${minutes === 1 ? "" : "s"} (memory.idleParkMinutes)`;
+	}
+
+	#restartFailure(error: unknown): string {
+		return `the ${this.#language} kernel parked after idling did not restart: ${errorText(error)}; run the cell again to retry`;
+	}
+}
+
+export function parkWhenIdle(
+	language: EvalLanguage,
+	idleMinutes: number,
+	kernel: EvalKernel,
+	restart: RestartParkedKernel,
+	onParked?: () => void,
+): EvalKernel {
+	return idleMinutes > 0 ? new IdleParkingKernel(language, idleMinutes, kernel, restart, onParked) : kernel;
+}
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/extension/kernel-registration.ts

@@ -35,6 +35,31 @@ export function registerKernel(sessionId: string, language: EvalLanguage, memory
 	return id;
 }
 
+/** One registry entry per language for a session; replacing a language's kernel replaces its entry. */
+export class SessionKernelRegistrations {
+	readonly #owner: string;
+	readonly #ids = new Map<EvalLanguage, string>();
+
+	constructor(owner: string) {
+		this.#owner = owner;
+	}
+
+	register(language: EvalLanguage, memory: RegisteredKernelSource | undefined): void {
+		this.unregister(language);
+		if (memory !== undefined) this.#ids.set(language, registerKernel(this.#owner, language, memory));
+	}
+
+	unregister(language: EvalLanguage): void {
+		const id = this.#ids.get(language);
+		if (id !== undefined) kernelRegistry.unregister(id);
+		this.#ids.delete(language);
+	}
+
+	clear(): void {
+		for (const language of [...this.#ids.keys()]) this.unregister(language);
+	}
+}
+
 export function javaScriptKernelMemory(kernel: JavaScriptKernel): RegisteredKernelSource {
 	return {
 		measure: "heap",

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

@@ -0,0 +1,24 @@
+import type {
+	KernelToolsDescribeResult,
+	KernelToolsInvokeOptions,
+	KernelToolsInvokeRequest,
+} from "../kernels/js/kernel-tools-types.ts";
+import type { EvalKernel } from "../tool/types.ts";
+
+/** The kernel-tools surface a JavaScript kernel exposes; `run-eval-cell` finds it by probing for these methods. */
+export interface KernelToolsMethods {
+	describeKernelTools(names: readonly string[]): Promise<KernelToolsDescribeResult>;
+	invokeKernelTool(
+		request: KernelToolsInvokeRequest,
+		options?: AbortSignal | KernelToolsInvokeOptions,
+	): Promise<unknown>;
+}
+
+export function hasKernelTools(kernel: EvalKernel): kernel is EvalKernel & KernelToolsMethods {
+	return (
+		"describeKernelTools" in kernel &&
+		typeof kernel.describeKernelTools === "function" &&
+		"invokeKernelTool" in kernel &&
+		typeof kernel.invokeKernelTool === "function"
+	);
+}

package/src/extension/session-manager.ts

@@ -2,22 +2,21 @@ import { join } from "node:path";
 import type { ExtensionContext } from "@code-yeongyu/senpi";
 import { type BridgeServerHandle, startBridgeServer } from "../bridge/http-server.ts";
 import type { KernelToHostMessage } from "../bridge/protocol.ts";
-import { isReservedToolName, runReservedTool } from "../bridges/reserved-dispatch.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import { resolveKernelMemoryThresholds } from "../config/memory-settings.ts";
-import { defaultCodemodeSettings } from "../config/settings.ts";
 import { collectOrphanedChildren } from "../host-sdk.ts";
 import { JavaScriptKernel } from "../kernels/js/context-manager.ts";
 import type { KernelLifecycle } from "../kernels/shared/kernel-death.ts";
-import { marshalToolResult } from "../tool/image.ts";
 import type { EvalKernel, EvalLanguage } from "../tool/types.ts";
+import { type BridgeToolCallRequest, routeBridgeToolCall } from "./bridge-tool-call.ts";
+import { parkWhenIdle } from "./idle-parking-kernel.ts";
 import {
 	javaScriptKernelMemory,
-	registerKernel,
+	SessionKernelRegistrations,
 	type StartedKernel,
 	startSubprocessKernel,
 } from "./kernel-registration.ts";
-import { kernelRegistry, type RegisteredKernelSource } from "./kernel-registry.ts";
+import type { RegisteredKernelSource } from "./kernel-registry.ts";
 import { ReplaceableKernel } from "./kernel-replacement.ts";
 import { assertSessionCwdAvailable } from "./session-cwd.ts";
 import type {
@@ -61,7 +60,7 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 	readonly #options: CreateCodemodeSessionManagerOptions;
 	#bridge: BridgeServerHandle | undefined;
 	#kernels = new Map<EvalLanguage, EvalKernel>();
-	readonly #registrations = new Map<EvalLanguage, string>();
+	readonly #registrations: SessionKernelRegistrations;
 	#kernelCreations = new Map<EvalLanguage, Promise<EvalKernel>>();
 	#onMessageRefs = new Map<EvalLanguage, (message: KernelToHostMessage) => void>();
 	#context: ExtensionContext | undefined;
@@ -70,6 +69,7 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 
 	constructor(options: CreateCodemodeSessionManagerOptions) {
 		this.#options = options;
+		this.#registrations = new SessionKernelRegistrations(options.ownerSessionId ?? options.sessionId);
 	}
 
 	async start(): Promise<void> {
@@ -81,29 +81,8 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 		});
 	}
 
-	// Subprocess kernels (py/rb/jl) reach the host only through this route, so every reply
-	// must match the in-process JS path in tool/cell-handler.ts: reserved helper names dispatch
-	// through runReservedTool (forwarding them made agent() fail with "Unknown tool __agent__"),
-	// and ordinary tool results are marshalled to { text, images, details, hasError } — the raw
-	// { content } shape left python cells unable to reach tool.read image blocks.
-	async #call(request: { toolName: string; args: unknown; callId: string; signal: AbortSignal }): Promise<unknown> {
-		if (!isReservedToolName(request.toolName)) {
-			return marshalToolResult(
-				await this.#options.executeTool(request.toolName, request.args, { signal: request.signal }),
-			);
-		}
-		const taskTools = this.#options.settings.taskTools ?? defaultCodemodeSettings.taskTools;
-		return await runReservedTool(request.toolName, {
-			callId: request.callId,
-			args: request.args,
-			executeTool: this.#options.executeTool,
-			taskToolName: taskTools.task,
-			taskOutputToolName: taskTools.output,
-			listTools: this.#options.listTools,
-			signal: request.signal,
-			emitStatus: () => {},
-			marshalToolResult,
-		});
+	async #call(request: BridgeToolCallRequest): Promise<unknown> {
+		return await routeBridgeToolCall(this.#options, request);
 	}
 
 	async getKernel(language: EvalLanguage, onMessage: (message: KernelToHostMessage) => void): Promise<EvalKernel> {
@@ -170,7 +149,6 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 		const kernels = [...this.#kernels.values()];
 		const bridge = this.#bridge;
 		this.#kernels.clear();
-		for (const id of this.#registrations.values()) kernelRegistry.unregister(id);
 		this.#registrations.clear();
 		this.#onMessageRefs.clear();
 		this.#bridge = undefined;
@@ -194,36 +172,29 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 		generation: number,
 	): Promise<EvalKernel> {
 		await assertSessionCwdAvailable(this.#options.cwd);
-		// py/rb/jl instances can die; the session holds one replaceable kernel per language so every
-		// cell that kept a reference to it survives the death (JS heals its own worker).
-		let memory: RegisteredKernelSource | undefined;
-		const kernel =
-			language === "js"
-				? (() => {
-						return this.#createKernel(language, onMessage).then((created) => {
-							memory = created.memory;
-							return created.kernel;
-						});
-					})()
-				: ReplaceableKernel.create(language, async (lifecycle) => {
-						const created = await this.#createKernel(language, onMessage, lifecycle);
-						memory ??= created.memory;
-						return created.kernel;
-					});
-		const resolvedKernel = await kernel;
+		const started = await this.#startLanguageKernel(language, onMessage);
+		const idleParkMinutes = this.#options.settings.memory?.idleParkMinutes ?? 0;
+		const resolvedKernel = parkWhenIdle(
+			language,
+			idleParkMinutes,
+			started.kernel,
+			async () => {
+				const restarted = await this.#startLanguageKernel(language, onMessage);
+				if (generation !== this.#generation) {
+					await restarted.kernel.close();
+					throw new CodemodeSessionDisposedError();
+				}
+				this.#registrations.register(language, restarted.memory);
+				return restarted.kernel;
+			},
+			() => this.#registrations.unregister(language),
+		);
 		if (generation !== this.#generation) {
 			await resolvedKernel.close();
 			throw new CodemodeSessionDisposedError();
 		}
 		this.#kernels.set(language, resolvedKernel);
-		this.#registrations.set(
-			language,
-			registerKernel(
-				this.#options.ownerSessionId ?? this.#options.sessionId,
-				language,
-				memory as RegisteredKernelSource,
-			),
-		);
+		this.#registrations.register(language, started.memory);
 		// The directory can vanish while the interpreter starts; every caller sharing this creation
 		// must see that, not only the next one. The kernel stays stored and dispose still closes it.
 		await assertSessionCwdAvailable(this.#options.cwd);
@@ -232,6 +203,22 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 		return resolvedKernel;
 	}
 
+	// py/rb/jl instances can die; the session holds one replaceable kernel per language so every
+	// cell that kept a reference to it survives the death (JS heals its own worker).
+	async #startLanguageKernel(
+		language: EvalLanguage,
+		onMessage: (message: KernelToHostMessage) => void,
+	): Promise<{ readonly kernel: EvalKernel; readonly memory: RegisteredKernelSource | undefined }> {
+		if (language === "js") return await this.#createKernel(language, onMessage);
+		let memory: RegisteredKernelSource | undefined;
+		const kernel = await ReplaceableKernel.create(language, async (lifecycle) => {
+			const created = await this.#createKernel(language, onMessage, lifecycle);
+			memory ??= created.memory;
+			return created.kernel;
+		});
+		return { kernel, memory };
+	}
+
 	async #createKernel(
 		language: EvalLanguage,
 		onMessage: (message: KernelToHostMessage) => void,

package/src/kernels/jl/kernel.ts

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import type { BridgeConnectionConfig, KernelToHostMessage } from "../../bridge/protocol.ts";
 import type { SessionEnvironment } from "../session-env.ts";
 import type { KernelLifecycle } from "../shared/kernel-death.ts";
+import { readProcessGroupCpuTime } from "../shared/process-group-cpu.ts";
 import { type CodemodeRuntimeAssetEnvironment, requireCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
 import { SubprocessKernel, type SubprocessKernelMemory, type SubprocessSpawn } from "../shared/subprocess-kernel.ts";
 
@@ -14,7 +15,7 @@ export interface JuliaKernelStartOptions extends KernelLifecycle {
 	readonly command?: string;
 	readonly spawn?: SubprocessSpawn;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
-	/** Ceiling-only memory management (no notice or globals list: the runner reports no memory). */
+	/** Memory management: the runner reports its largest globals and the host reads the interpreter footprint for the ceiling. */
 	readonly memory?: SubprocessKernelMemory;
 }
 
@@ -54,6 +55,7 @@ export class JuliaKernel extends SubprocessKernel {
 			onMessage: options.onMessage,
 			memory: options.memory && { language: "jl", ...options.memory },
 			onDeath: options.onDeath,
+			startup: { label: "Julia", readGroupCpuTime: readProcessGroupCpuTime },
 		});
 	}
 }