@code-yeongyu/senpi-codemode 2026.10.5 → 2026.10.7

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/removed-tool-hints.ts

@@ -0,0 +1,15 @@
+/** Migration guidance for the tools eval replaced; the host returns it when a model calls them. */
+export interface RemovedToolHintRegistrar {
+	registerRemovedToolHint(name: string, hint: string): void;
+}
+
+export const WAIT_REMOVED_TOOL_HINT =
+	"wait is not a tool; inside a cell use the wait(handles) helper (tool_schema('eval:wait')), or let detached cells notify.";
+
+export function registerRemovedToolHints(pi: RemovedToolHintRegistrar): void {
+	pi.registerRemovedToolHint(
+		"exec",
+		'exec was removed; use eval({ language: "js", code }) instead. Long eval cells detach on their own and notify when complete.',
+	);
+	pi.registerRemovedToolHint("wait", WAIT_REMOVED_TOOL_HINT);
+}

package/src/extension/runtime-factory.ts

@@ -8,6 +8,7 @@ import {
 	type ResolvedCodemodeSettings,
 	resolveEnabledLanguages,
 } from "../config/settings.ts";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
 import {
 	createInterpreterDetector,
 	getInterpreterAvailability,
@@ -54,6 +55,7 @@ export async function createRuntime(
 	event: unknown,
 	complete: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>,
 	options: RuntimeFactoryOptions,
+	handles?: HandleRegistry,
 ): Promise<SessionRuntime> {
 	const loaded = await loadCodemodeSettings({ cwd: ctx.cwd });
 	const settings: ResolvedCodemodeSettings = {
@@ -81,6 +83,7 @@ export async function createRuntime(
 		executeTool,
 		listTools: () => pi.getAllTools(),
 		complete,
+		...(handles === undefined ? {} : { handles }),
 	});
 	return {
 		sessionId,

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

@@ -2,6 +2,7 @@ import type { ExtensionContext } from "@code-yeongyu/senpi";
 import type { EvalSchemaToolInfo } from "../bridges/schema-bridge.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import type { CodemodeSettings } from "../config/settings.ts";
+import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { InterpreterAvailability } from "../interpreters/detect.ts";
 import type { SessionEnvironment } from "../kernels/session-env.ts";
 import type { EvalKernelManager, ExecuteTool } from "../tool/types.ts";
@@ -39,4 +40,6 @@ export interface CreateCodemodeSessionManagerOptions {
 	readonly executeTool: ExecuteTool;
 	readonly listTools?: () => readonly EvalSchemaToolInfo[];
 	readonly complete: (request: CompletionRequest, ctx: ExtensionContext) => Promise<CompletionResult>;
+	/** The session generation's handle registry; subprocess kernels reach `wait()`/`handle()` through the bridge. */
+	readonly handles?: HandleRegistry;
 }

package/src/extension/session-manager.ts

@@ -2,22 +2,22 @@ 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 BridgeDispatchContext, dispatchBridgeCompletion } from "./bridge-dispatch.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 +61,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,40 +70,27 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 
 	constructor(options: CreateCodemodeSessionManagerOptions) {
 		this.#options = options;
+		this.#registrations = new SessionKernelRegistrations(options.ownerSessionId ?? options.sessionId);
 	}
 
 	async start(): Promise<void> {
+		const manager = this;
+		const dispatch: BridgeDispatchContext = {
+			get context() {
+				return manager.#context;
+			},
+			contextFor: (signal) => this.#contextFor(signal),
+			requireContext: () => this.#requireContext(),
+		};
 		this.#bridge = await startBridgeServer({
 			onCall: async (request) => await this.#call(request),
 			onEmit: async () => undefined,
-			onCompletion: async (request) =>
-				this.#options.complete({ prompt: request.prompt, opts: request.opts }, this.#contextFor(request.signal)),
+			onCompletion: async (request) => await dispatchBridgeCompletion(this.#options, request, dispatch),
 		});
 	}
 
-	// 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, this.#context?.evalHandleHost);
 	}
 
 	async getKernel(language: EvalLanguage, onMessage: (message: KernelToHostMessage) => void): Promise<EvalKernel> {
@@ -170,7 +157,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 +180,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 +211,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,
@@ -293,9 +288,14 @@ class DefaultCodemodeSessionManager implements CodemodeSessionManager {
 		return names;
 	}
 
-	#contextFor(signal: AbortSignal): ExtensionContext {
+	#requireContext(): ExtensionContext {
 		const ctx = this.#context;
 		if (!ctx) throw new CodemodeContextUnavailableError();
+		return ctx;
+	}
+
+	#contextFor(signal: AbortSignal): ExtensionContext {
+		const ctx = this.#requireContext();
 		return { ...ctx, signal: ctx.signal ? AbortSignal.any([ctx.signal, signal]) : signal };
 	}
 }

package/src/extension/start-recovery.ts

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+import type { ExtensionContext } from "@code-yeongyu/senpi";
+import type { createEvalTool } from "../tool/eval-tool.ts";
+import { CodemodeSessionDisposedError } from "./session-manager.ts";
+import { CodemodeSessionNotStartedError } from "./session-manager-proxy.ts";
+
+export class CodemodeRuntimeRecreationError extends Error {
+	readonly name = "CodemodeRuntimeRecreationError";
+
+	constructor(reason: string) {
+		super(`codemode runtime could not be re-created: ${reason}. Start a new session or reload to bring eval back.`);
+	}
+}
+
+type StartSession = (event: unknown, ctx: ExtensionContext) => Promise<void>;
+
+/**
+ * A session_start whose runtime could not be created leaves the session running with no usable manager. The
+ * next eval re-creates the runtime once for that failed start (concurrent evals share the attempt) and runs; a
+ * failed re-creation is reported to every later eval until the next session_start. One stderr line names the
+ * failed start with a hashed session id so a recurrence stays visible. A session that ended is never recovered.
+ */
+export class StartRecovery {
+	readonly #startSession: StartSession;
+	readonly #report: (line: string) => void;
+	#failedStartEvent: { readonly event: unknown } | undefined;
+	#recreation: Promise<void> | undefined;
+	#recreationFailure: CodemodeRuntimeRecreationError | undefined;
+
+	constructor(
+		startSession: StartSession,
+		report: (line: string) => void = (line) => globalThis.process.stderr.write(`${line}\n`),
+	) {
+		this.#startSession = startSession;
+		this.#report = report;
+	}
+
+	async runStart(event: unknown, ctx: ExtensionContext): Promise<void> {
+		try {
+			await this.#startSession(event, ctx);
+			this.#reset();
+		} catch (error) {
+			this.#reset();
+			this.#failedStartEvent = { event };
+			throw error;
+		}
+	}
+
+	sessionEnded(): void {
+		this.#reset();
+	}
+
+	wrapExecute<Args extends unknown[], Result>(
+		execute: (...args: Args) => Promise<Result>,
+		contextOf: (args: Args) => ExtensionContext,
+	): (...args: Args) => Promise<Result> {
+		return async (...args) => {
+			try {
+				return await execute(...args);
+			} catch (error) {
+				if (!(error instanceof CodemodeSessionDisposedError || error instanceof CodemodeSessionNotStartedError)) {
+					throw error;
+				}
+				if (this.#recreationFailure !== undefined) throw this.#recreationFailure;
+				const recreation = this.#recreation ?? this.#beginRecreation(contextOf(args));
+				if (recreation === undefined) throw error;
+				await recreation;
+				return await execute(...args);
+			}
+		};
+	}
+
+	#beginRecreation(ctx: ExtensionContext): Promise<void> | undefined {
+		const failed = this.#failedStartEvent;
+		if (failed === undefined) return undefined;
+		this.#report(
+			`[senpi-codemode] eval re-created a runtime left disposed by a failed session_start (session ${sessionHash(ctx)})`,
+		);
+		const recreation = this.#startSession(failed.event, ctx).then(
+			() => {
+				this.#recreation = undefined;
+				this.#reset();
+			},
+			(error: unknown) => {
+				this.#recreation = undefined;
+				this.#recreationFailure = new CodemodeRuntimeRecreationError(
+					error instanceof Error ? error.message : String(error),
+				);
+				throw this.#recreationFailure;
+			},
+		);
+		this.#recreation = recreation;
+		return recreation;
+	}
+
+	#reset(): void {
+		this.#failedStartEvent = undefined;
+		this.#recreationFailure = undefined;
+	}
+}
+
+export function withStartRecovery<Tool extends ReturnType<typeof createEvalTool>>(
+	recovery: StartRecovery,
+	tool: Tool,
+): Tool {
+	return { ...tool, execute: recovery.wrapExecute(tool.execute, (args) => args[4]) };
+}
+
+function sessionHash(ctx: ExtensionContext): string {
+	return createHash("sha256").update(ctx.sessionManager.getSessionId()).digest("hex").slice(0, 12);
+}