@code-yeongyu/senpi-codemode 2026.10.4 → 2026.10.6

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

@@ -0,0 +1,37 @@
+import { isReservedToolName, runReservedTool } from "../bridges/reserved-dispatch.ts";
+import { defaultCodemodeSettings } from "../config/settings.ts";
+import { marshalToolResult } from "../tool/image.ts";
+import type { CreateCodemodeSessionManagerOptions } from "./session-manager-contract.ts";
+
+export interface BridgeToolCallRequest {
+	readonly toolName: string;
+	readonly args: unknown;
+	readonly callId: string;
+	readonly signal: AbortSignal;
+}
+
+// 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.
+export async function routeBridgeToolCall(
+	options: Pick<CreateCodemodeSessionManagerOptions, "executeTool" | "listTools" | "settings">,
+	request: BridgeToolCallRequest,
+): Promise<unknown> {
+	if (!isReservedToolName(request.toolName)) {
+		return marshalToolResult(await options.executeTool(request.toolName, request.args, { signal: request.signal }));
+	}
+	const taskTools = options.settings.taskTools ?? defaultCodemodeSettings.taskTools;
+	return await runReservedTool(request.toolName, {
+		callId: request.callId,
+		args: request.args,
+		executeTool: options.executeTool,
+		taskToolName: taskTools.task,
+		taskOutputToolName: taskTools.output,
+		listTools: options.listTools,
+		signal: request.signal,
+		emitStatus: () => {},
+		marshalToolResult,
+	});
+}

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

@@ -0,0 +1,230 @@
+import type { HostToKernelMessage } from "../bridge/protocol.ts";
+import {
+	type KernelLifecycle,
+	KernelUnavailableError,
+	restartNotice,
+	unstartedResult,
+} from "../kernels/shared/kernel-death.ts";
+import type {
+	EvalKernel,
+	EvalKernelResult,
+	EvalKernelRunInput,
+	EvalLanguage,
+	KernelInterruptHandle,
+	PendingCell,
+} from "../tool/types.ts";
+
+export type StartKernel = (lifecycle: Required<KernelLifecycle>) => Promise<EvalKernel>;
+
+class ReplaceableKernelClosedError extends Error {
+	readonly name = "ReplaceableKernelClosedError";
+
+	constructor() {
+		super("Kernel closed");
+	}
+}
+
+/**
+ * The one kernel a session holds for a language whose instances can die (py, rb, jl). Every caller keeps
+ * this object for the life of a cell - its handler, its execution, its detached record - so a death never
+ * strands them: on the instance's own death event this evicts it, takes back the cells that never started,
+ * starts ONE replacement and runs them there in their original order, with their own callbacks. The first
+ * result of the replacement says the kernel was restarted. A replacement that dies before it finished a
+ * cell is not replaced again for the same cells: they fail with `eval_kernel_unavailable`, and the next
+ * cell submitted starts a fresh one. The cell that was running when the interpreter died is never re-run.
+ */
+export class ReplaceableKernel implements EvalKernel {
+	readonly #language: EvalLanguage;
+	readonly #start: StartKernel;
+	#kernel: EvalKernel;
+	#generation = 0;
+	#nextGeneration = 0;
+	#held: PendingCell[] = [];
+	#replacing: Promise<void> | null = null;
+	/** The death the current instance replaced, until that instance settled a cell of its own. */
+	#recovering: string | null = null;
+	/** A death whose cells were failed instead of replaced: the next cell's fresh instance announces it. */
+	#unannounced: string | null = null;
+	/** Carried by the first result the current replacement produces. */
+	#announce: string | null = null;
+	#closed = false;
+	#closeFailure: unknown;
+
+	private constructor(language: EvalLanguage, start: StartKernel, first: EvalKernel) {
+		this.#language = language;
+		this.#start = start;
+		this.#kernel = first;
+	}
+
+	/** Starts the first instance; one that cannot hand back its queue is returned as it is. */
+	static async create(language: EvalLanguage, start: StartKernel): Promise<EvalKernel> {
+		let owner: ReplaceableKernel | undefined;
+		const first = await start({
+			onDeath: (reason) => {
+				if (owner !== undefined) owner.#died(0, reason);
+			},
+		});
+		if (first.drainPending === undefined) return first;
+		owner = new ReplaceableKernel(language, start, first);
+		return owner;
+	}
+
+	run(input: EvalKernelRunInput): Promise<EvalKernelResult> {
+		if (this.#closed) return Promise.reject(new ReplaceableKernelClosedError());
+		if (this.#replacing === null && this.#kernel.isAlive?.() !== false) {
+			return this.#submit(this.#generation, this.#kernel, input);
+		}
+		return new Promise((settle) => {
+			this.#held.push({ input, settle });
+			this.#ensureReplacement();
+		});
+	}
+
+	cancelQueued(cellId: string, reason: string): boolean {
+		return this.#cancelHeld(cellId, reason) || this.#kernel.cancelQueued(cellId, reason);
+	}
+
+	async interrupt(reason = "interrupted", cellId?: string): Promise<KernelInterruptHandle> {
+		if (cellId !== undefined && this.#cancelHeld(cellId, reason)) return { stateRetained: Promise.resolve(true) };
+		if (cellId === undefined) this.#failHeld(reason === "Eval interrupted" ? reason : `Eval interrupted: ${reason}`);
+		return await this.#kernel.interrupt(reason, cellId);
+	}
+
+	queueSnapshot(): { activeCellId: string | null; queuedCellIds: readonly string[] } {
+		const current = this.#kernel.queueSnapshot();
+		return {
+			activeCellId: current.activeCellId,
+			queuedCellIds: [...current.queuedCellIds, ...this.#held.map((cell) => cell.input.cellId)],
+		};
+	}
+
+	deliverToolReply(message: Extract<HostToKernelMessage, { type: "tool-reply" }>): void {
+		this.#kernel.deliverToolReply(message);
+	}
+
+	async reset(): Promise<void> {
+		if (this.#replacing !== null) await this.#replacing;
+		if (this.#kernel.isAlive?.() === false) {
+			// A reset discards every global anyway, so the fresh instance announces nothing.
+			this.#unannounced = null;
+			const replacing = this.#replace(null);
+			this.#replacing = replacing;
+			await replacing;
+			if (this.#replacing === replacing) this.#replacing = null;
+			return;
+		}
+		await this.#kernel.reset();
+	}
+
+	async close(): Promise<void> {
+		this.#closed = true;
+		const held = this.#held.splice(0);
+		for (const cell of held)
+			cell.settle(unstartedResult(cell.input.cellId, new ReplaceableKernelClosedError().message));
+		if (this.#replacing !== null) await this.#replacing;
+		if (this.#closeFailure !== undefined) throw this.#closeFailure;
+		await this.#kernel.close();
+	}
+
+	listKernelToolNames(): readonly string[] {
+		return this.#kernel.listKernelToolNames?.() ?? [];
+	}
+
+	#submit(generation: number, kernel: EvalKernel, input: EvalKernelRunInput): Promise<EvalKernelResult> {
+		return kernel.run(input).then((result) => {
+			if (generation !== this.#generation) return result;
+			// The result the kernel settled for the cell its death interrupted proves nothing about the
+			// replacement; a result from a still-live current instance proves it works.
+			// A drained cell settles through this same promise already tagged; only the interrupted one is `lost`.
+			if (kernel.isAlive?.() === false)
+				return result.kernelState === undefined ? { ...result, kernelState: "lost" } : result;
+			this.#recovering = null;
+			const notice = this.#announce;
+			if (notice === null) return result;
+			this.#announce = null;
+			return { ...result, notice, kernelState: "restarted" };
+		});
+	}
+
+	#died(generation: number, reason: string): void {
+		if (generation !== this.#generation || this.#closed) return;
+		this.#held = [...(this.#kernel.drainPending?.() ?? []), ...this.#held];
+		if (this.#recovering !== null) {
+			this.#recovering = null;
+			this.#unannounced = reason;
+			const error = new KernelUnavailableError(this.#language, reason);
+			for (const cell of this.#held.splice(0)) cell.settle(unstartedResult(cell.input.cellId, error.message));
+			return;
+		}
+		this.#recovering = reason;
+		this.#ensureReplacement();
+	}
+
+	#ensureReplacement(): void {
+		if (this.#replacing !== null) return;
+		const reason = this.#recovering ?? this.#unannounced;
+		this.#recovering = reason;
+		this.#unannounced = null;
+		const replacing = this.#replace(reason).finally(() => {
+			if (this.#replacing === replacing) this.#replacing = null;
+		});
+		this.#replacing = replacing;
+	}
+
+	/** Never rejects: every failure settles the held cells with what went wrong. */
+	async #replace(reason: string | null): Promise<void> {
+		const dead = this.#kernel;
+		try {
+			await dead.close();
+		} catch (error) {
+			// The old interpreter may still be running: report that rather than start a second one.
+			this.#failUnavailable(reason, `its interpreter could not be retired: ${errorText(error)}`);
+			return;
+		}
+		if (this.#closed) return;
+		const generation = ++this.#nextGeneration;
+		let next: EvalKernel;
+		try {
+			next = await this.#start({ onDeath: (died) => this.#died(generation, died) });
+		} catch (error) {
+			this.#failUnavailable(reason, `its replacement did not start: ${errorText(error)}`);
+			return;
+		}
+		if (this.#closed) {
+			await next.close().catch((error: unknown) => {
+				this.#closeFailure = error;
+			});
+			return;
+		}
+		this.#kernel = next;
+		this.#generation = generation;
+		this.#announce = reason === null ? null : restartNotice(this.#language, reason);
+		for (const cell of this.#held.splice(0)) {
+			void this.#submit(generation, next, cell.input).then(cell.settle, (error: unknown) =>
+				cell.settle(unstartedResult(cell.input.cellId, errorText(error))),
+			);
+		}
+	}
+
+	#failUnavailable(reason: string | null, detail: string): void {
+		this.#recovering = null;
+		this.#unannounced = reason;
+		const error = new KernelUnavailableError(this.#language, reason === null ? detail : `${reason}; ${detail}`);
+		for (const cell of this.#held.splice(0)) cell.settle(unstartedResult(cell.input.cellId, error.message));
+	}
+
+	#cancelHeld(cellId: string, reason: string): boolean {
+		const index = this.#held.findIndex((cell) => cell.input.cellId === cellId);
+		const [cell] = index < 0 ? [] : this.#held.splice(index, 1);
+		cell?.settle(unstartedResult(cellId, reason));
+		return cell !== undefined;
+	}
+
+	#failHeld(message: string): void {
+		for (const cell of this.#held.splice(0)) cell.settle(unstartedResult(cell.input.cellId, message));
+	}
+}
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}

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"
+	);
+}