@code-yeongyu/senpi 2026.7.10 → 2026.7.13

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/py/kernel.ts

@@ -1,59 +1,24 @@
-import { spawn } from "node:child_process";
-import { dirname, join } from "node:path";
-import type { Readable, Writable } from "node:stream";
-import { fileURLToPath } from "node:url";
-import {
-	type BridgeConnectionConfig,
-	decodeBridgeFrame,
-	encodeBridgeFrame,
-	type HostToKernelMessage,
-	type KernelToHostMessage,
-} from "../../bridge/protocol.ts";
+import type { PendingRun, PythonKernelRunOptions, PythonKernelStartOptions, ResultMessage } from "./kernel-contract.ts";
+import { failedPythonResult, PythonKernelTransport } from "./transport.ts";
 
-export interface KernelChild {
-	readonly stdin: Writable;
-	readonly stdout: Readable;
-	readonly stderr: Readable;
-	readonly pid?: number;
-	readonly killed: boolean;
-	kill(signal?: NodeJS.Signals): boolean;
-	on(event: string, listener: (...args: unknown[]) => void): this;
-	once(event: string, listener: (...args: unknown[]) => void): this;
-	off(event: string, listener: (...args: unknown[]) => void): this;
-}
+export type { PythonKernelRunOptions, PythonKernelStartOptions } from "./kernel-contract.ts";
+export type { KernelChild, KernelSpawnOptions, KernelSpawnProcess } from "./process.ts";
 
-export interface KernelSpawnOptions {
-	readonly command: string;
-	readonly args: readonly string[];
-	readonly cwd: string;
-	readonly env: NodeJS.ProcessEnv;
-}
-export type KernelSpawnProcess = (options: KernelSpawnOptions) => KernelChild;
-export interface PythonKernelStartOptions {
-	readonly interpreterPath: string;
-	readonly sessionId: string;
-	readonly cwd: string;
-	readonly connection: BridgeConnectionConfig;
-	readonly env?: NodeJS.ProcessEnv;
-	readonly startupTimeoutMs?: number;
-	readonly onMessage?: (message: KernelToHostMessage) => void;
-	readonly spawnProcess?: KernelSpawnProcess;
-}
-export interface PythonKernelRunOptions {
-	readonly cellId: string;
-	readonly code: string;
-	readonly timeoutMs?: number;
-}
-type ResultMessage = Extract<KernelToHostMessage, { type: "result" }>;
 const startupTimeoutMs = 5_000;
+const interruptEscalationMs = 5_000;
 
 export class PythonKernel {
 	readonly #options: PythonKernelStartOptions;
-	#child: KernelChild | null = null;
-	#stdoutBuffer = "";
-	#stderrTail = "";
-	#settleReady: ((error?: Error) => void) | null = null;
-	#pending = new Map<string, (result: ResultMessage) => void>();
+	#transport: PythonKernelTransport | null = null;
+	#pending = new Map<string, PendingRun>();
+	#queue: PendingRun[] = [];
+	#active: PendingRun | null = null;
+	#starting: Promise<void> | null = null;
+	#retirement: Promise<void> | null = null;
+	#closePromise: Promise<void> | null = null;
+	#failure: Error | null = null;
+	#generation = 0;
+	#closed = false;
 
 	private constructor(options: PythonKernelStartOptions) {
 		this.#options = options;
@@ -61,197 +26,265 @@ export class PythonKernel {
 
 	static async start(options: PythonKernelStartOptions): Promise<PythonKernel> {
 		const kernel = new PythonKernel(options);
-		await kernel.#spawn();
+		await kernel.#spawn(kernel.#generation);
 		return kernel;
 	}
 
-	async run(options: PythonKernelRunOptions): Promise<ResultMessage> {
-		await this.#ensureStarted();
-		return await new Promise<ResultMessage>((resolve) => {
-			const timer = setTimeout(() => {
-				this.#pending.delete(options.cellId);
-				void this.#kill();
-				resolve({
-					type: "result",
-					cellId: options.cellId,
-					ok: false,
-					error: { message: `Python kernel timed out after ${options.timeoutMs ?? 0}ms` },
-					durationMs: options.timeoutMs ?? 0,
-				});
-			}, options.timeoutMs ?? 30_000);
-			this.#pending.set(options.cellId, (result) => {
-				clearTimeout(timer);
-				resolve(result);
-			});
-			this.#write({ type: "run", cellId: options.cellId, code: options.code, timeoutMs: options.timeoutMs });
+	run(input: PythonKernelRunOptions): Promise<ResultMessage> {
+		if (this.#failure) return Promise.reject(this.#failure);
+		if (this.#closed) return Promise.reject(new Error("Python kernel is closed"));
+		return new Promise<ResultMessage>((resolve, reject) => {
+			const pending: PendingRun = { input, resolve, reject, startedAt: null, timeoutTimer: null };
+			this.#pending.set(input.cellId, pending);
+			this.#queue.push(pending);
+			this.#startNext();
 		});
 	}
 
 	async interrupt(reason = "interrupted"): Promise<void> {
-		if (!this.#child) return;
-		this.#write({ type: "interrupt", reason });
-		if (process.platform === "win32") this.#child.kill();
-		else this.#child.kill("SIGINT");
+		if (this.#failure) throw this.#failure;
+		for (const pending of [...this.#queue]) {
+			pending.interruptReason = reason;
+			this.#settleRun(pending, failedPythonResult(pending.input.cellId, "Eval interrupted"));
+		}
+		const active = this.#active;
+		const transport = this.#transport;
+		if (!active || !transport || active.interruptReason !== undefined) return;
+		active.interruptReason = reason;
+		if (active.timeoutTimer) clearTimeout(active.timeoutTimer);
+		active.timeoutTimer = null;
+		active.escalationTimer = setTimeout(
+			() => void this.#escalateInterruptedRun(active).catch(() => undefined),
+			interruptEscalationMs,
+		);
+		transport.interrupt(reason);
 	}
 
 	async reset(): Promise<void> {
-		await this.#kill();
-		await this.#spawn();
+		if (this.#failure) throw this.#failure;
+		if (this.#closed) throw new Error("Python kernel is closed");
+		const generation = ++this.#generation;
+		const prior = this.#starting;
+		const operation = (async () => {
+			await prior?.catch(() => undefined);
+			if (this.#failure) throw this.#failure;
+			if (this.#closed || generation !== this.#generation) throw new Error("Python kernel reset was superseded");
+			const transport = this.#transport;
+			if (transport) await this.#beginRetirement(transport);
+			if (this.#closed || generation !== this.#generation) throw new Error("Python kernel reset was superseded");
+			await this.#spawn(generation);
+		})();
+		this.#starting = operation;
+		this.#settleAllPending("Python kernel reset");
+		try {
+			await operation;
+		} finally {
+			this.#finishStarting(operation);
+		}
 	}
 
 	deliverToolReply(): void {}
 
 	async close(): Promise<void> {
-		const child = this.#child;
-		if (!child) return;
-		this.#write({ type: "close" });
-		await Promise.race([onceExit(child), delay(500)]);
-		if (!child.killed) await this.#kill();
-		this.#child = null;
+		if (this.#closePromise) return await this.#closePromise;
+		this.#closed = true;
+		this.#generation += 1;
+		this.#settleAllPending("Python kernel closed");
+		const starting = this.#starting;
+		this.#closePromise = (async () => {
+			await starting?.catch(() => undefined);
+			await this.#retirement?.catch(() => undefined);
+			const transport = this.#transport;
+			if (!transport) return;
+			try {
+				await transport.close();
+			} catch (error) {
+				if (error instanceof Error) throw this.#recordFailure(error);
+				throw error;
+			}
+			if (this.#transport === transport) this.#transport = null;
+		})();
+		return await this.#closePromise;
 	}
 
-	async #ensureStarted(): Promise<void> {
-		if (this.#child && !this.#child.killed) return;
-		await this.#spawn();
+	#startNext(): void {
+		if (
+			this.#closed ||
+			this.#failure ||
+			this.#active ||
+			this.#starting ||
+			this.#retirement ||
+			this.#queue.length === 0
+		)
+			return;
+		const starting = this.#activateNext();
+		this.#starting = starting;
+		void starting.then(
+			() => this.#finishStarting(starting),
+			(error: unknown) => {
+				this.#rejectAllPending(error);
+				this.#finishStarting(starting);
+			},
+		);
 	}
 
-	async #spawn(): Promise<void> {
-		const scriptPath = join(dirname(fileURLToPath(import.meta.url)), "prelude.py");
-		const invocation = splitCommand(this.#options.interpreterPath);
-		const spawnOptions: KernelSpawnOptions = {
-			command: invocation.command,
-			args: [...invocation.args, "-u", scriptPath],
-			cwd: this.#options.cwd,
-			env: { ...process.env, ...this.#options.env, PYTHONUNBUFFERED: "1", PYTHONIOENCODING: "utf-8" },
-		};
-		const child = (this.#options.spawnProcess ?? defaultSpawn)(spawnOptions);
-		this.#child = child;
-		this.#stdoutBuffer = "";
-		this.#stderrTail = "";
-		const ready = new Promise<void>((resolve, reject) => {
-			this.#settleReady = (error) => (error ? reject(error) : resolve());
-		});
-		child.stdout.on("data", (chunk) => this.#onStdout(String(chunk)));
-		child.stderr.on("data", (chunk) => this.#onStderr(String(chunk)));
-		child.once("exit", (code, signal) => this.#onExit(numberOrNull(code), signalOrNull(signal)));
-		this.#write({ type: "init", sessionId: this.#options.sessionId, connection: this.#options.connection });
-		await withTimeout(
-			ready,
-			this.#options.startupTimeoutMs ?? startupTimeoutMs,
-			"Python kernel did not become ready",
-		);
+	async #activateNext(): Promise<void> {
+		await this.#ensureStarted();
+		if (this.#closed || this.#active || this.#retirement) return;
+		const pending = this.#queue.shift();
+		if (!pending || !this.#pending.has(pending.input.cellId)) return;
+		this.#active = pending;
+		pending.startedAt = performance.now();
+		const timeoutMs = pending.input.timeoutMs;
+		if (timeoutMs !== undefined)
+			pending.timeoutTimer = setTimeout(() => this.#timeoutRun(pending, timeoutMs), timeoutMs);
+		try {
+			this.#transport?.run(pending.input);
+		} catch (error) {
+			const failure = error instanceof Error ? error : new Error(String(error));
+			this.#rejectRun(pending, failure);
+		}
 	}
 
-	#write(message: HostToKernelMessage): void {
-		this.#child?.stdin.write(encodeBridgeFrame(message));
+	#finishStarting(starting: Promise<void>): void {
+		if (this.#starting === starting) this.#starting = null;
+		this.#startNext();
 	}
 
-	#onStdout(chunk: string): void {
-		this.#stdoutBuffer += chunk;
-		let newline = this.#stdoutBuffer.indexOf("\n");
-		while (newline >= 0) {
-			const line = this.#stdoutBuffer.slice(0, newline + 1);
-			this.#stdoutBuffer = this.#stdoutBuffer.slice(newline + 1);
-			this.#handleLine(line);
-			newline = this.#stdoutBuffer.indexOf("\n");
-		}
+	#timeoutRun(pending: PendingRun, timeoutMs: number): void {
+		if (this.#active !== pending) return;
+		if (this.#transport) void this.#beginRetirement(this.#transport).catch(() => undefined);
+		this.#settleRun(
+			pending,
+			failedPythonResult(pending.input.cellId, `Python kernel timed out after ${timeoutMs}ms`),
+		);
 	}
 
-	#onStderr(chunk: string): void {
-		this.#stderrTail = `${this.#stderrTail}${chunk}`.slice(-4_000);
-		this.#emit({ type: "text", stream: "stderr", data: chunk });
+	async #ensureStarted(): Promise<void> {
+		await this.#retirement;
+		if (this.#failure) throw this.#failure;
+		if (this.#transport) return;
+		await this.#spawn(this.#generation);
 	}
 
-	#handleLine(line: string): void {
-		const decoded = decodeBridgeFrame(line);
-		if (!decoded.ok) {
-			this.#emit({ type: "text", stream: "stderr", data: `${decoded.error.message}\n` });
-			return;
-		}
-		const message = decoded.message as KernelToHostMessage;
-		if (message.type === "ready") this.#settleReady?.();
-		else if (message.type === "init-failed") this.#settleReady?.(new Error(message.error.message));
-		else if (message.type === "result") this.#pending.get(message.cellId)?.(message);
-		this.#emit(message);
+	async #spawn(generation: number): Promise<void> {
+		if (this.#closed || generation !== this.#generation) throw new Error("Python kernel startup was superseded");
+		this.#transport = await PythonKernelTransport.start({
+			...this.#options,
+			startupTimeoutMs: this.#options.startupTimeoutMs ?? startupTimeoutMs,
+			isOwned: () => !this.#closed && generation === this.#generation,
+			onRetirementFailure: (transport, error) => {
+				if (!this.#transport) this.#transport = transport;
+				this.#recordFailure(error);
+			},
+			onResult: (transport, result) => this.#onResult(transport, result),
+			onError: (transport, error) => this.#onError(transport, error),
+			onExit: (transport, error) => this.#onExit(transport, error),
+		});
 	}
 
-	#onExit(code: number | null, signal: NodeJS.Signals | null): void {
-		const error = new Error(this.#stderrTail.trim() || `Python kernel exited (${code ?? signal ?? "unknown"})`);
-		this.#settleReady?.(error);
-		for (const [cellId, settle] of this.#pending) {
-			settle({
-				type: "result",
-				cellId,
-				ok: false,
-				error: { message: "Python kernel died", stack: error.message },
-				durationMs: 0,
-			});
-		}
-		this.#pending.clear();
-		this.#child = null;
+	#onResult(transport: PythonKernelTransport, result: ResultMessage): void {
+		if (this.#transport !== transport) return;
+		const pending = this.#pending.get(result.cellId);
+		if (pending) this.#settleRun(pending, result);
 	}
 
-	#emit(message: KernelToHostMessage): void {
-		this.#options.onMessage?.(message);
+	#onExit(transport: PythonKernelTransport, error: Error): void {
+		if (this.#transport !== transport) return;
+		this.#transport = null;
+		const active = this.#active;
+		if (active) this.#settleRun(active, failedPythonResult(active.input.cellId, "Python kernel died", error.message));
+		this.#startNext();
 	}
 
-	async #kill(): Promise<void> {
-		const child = this.#child;
-		if (!child) return;
-		if (child.pid !== undefined && process.platform !== "win32") {
-			try {
-				process.kill(-child.pid, "SIGKILL");
-			} catch {
-				child.kill("SIGKILL");
-			}
+	#onError(transport: PythonKernelTransport, error: Error): void {
+		if (this.#transport !== transport) return;
+		const retirement = this.#beginRetirement(transport);
+		void retirement.then(
+			() => undefined,
+			(retirementError: unknown) => {
+				this.#recordFailure(
+					retirementError instanceof Error ? retirementError : new Error(String(retirementError)),
+				);
+			},
+		);
+		const active = this.#active;
+		if (active) this.#settleRun(active, failedPythonResult(active.input.cellId, "Python kernel died", error.message));
+	}
+
+	#settleRun(pending: PendingRun, result: ResultMessage): void {
+		if (!this.#pending.delete(pending.input.cellId)) return;
+		this.#removePending(pending);
+		const durationMs = pending.startedAt === null ? 0 : Math.max(0, performance.now() - pending.startedAt);
+		if (pending.interruptReason !== undefined) {
+			const message =
+				pending.interruptReason === "Eval interrupted"
+					? "Eval interrupted"
+					: `Eval interrupted: ${pending.interruptReason}`;
+			const error = result.ok ? { message } : { ...result.error, message };
+			pending.resolve({ type: "result", cellId: pending.input.cellId, ok: false, error, durationMs });
 		} else {
-			child.kill("SIGKILL");
+			pending.resolve(result.durationMs === 0 ? { ...result, durationMs } : result);
 		}
-		await Promise.race([onceExit(child), delay(500)]);
-		this.#child = null;
+		this.#startNext();
 	}
-}
 
-function defaultSpawn(options: KernelSpawnOptions): KernelChild {
-	return spawn(options.command, [...options.args], {
-		cwd: options.cwd,
-		env: options.env,
-		stdio: "pipe",
-		detached: process.platform !== "win32",
-		windowsHide: true,
-	});
-}
+	#rejectRun(pending: PendingRun, error: unknown): void {
+		if (!this.#pending.delete(pending.input.cellId)) return;
+		this.#removePending(pending);
+		pending.reject(error);
+		this.#startNext();
+	}
 
-function splitCommand(commandLine: string): { readonly command: string; readonly args: readonly string[] } {
-	const [command, ...args] = commandLine.split(" ").filter(Boolean);
-	if (!command) throw new Error("Python interpreter path is empty");
-	return { command, args };
-}
+	#removePending(pending: PendingRun): void {
+		if (pending.timeoutTimer) clearTimeout(pending.timeoutTimer);
+		if (pending.escalationTimer) clearTimeout(pending.escalationTimer);
+		pending.timeoutTimer = null;
+		pending.escalationTimer = undefined;
+		if (this.#active === pending) this.#active = null;
+		const queuedIndex = this.#queue.indexOf(pending);
+		if (queuedIndex >= 0) this.#queue.splice(queuedIndex, 1);
+	}
 
-function numberOrNull(value: unknown): number | null {
-	return typeof value === "number" ? value : null;
-}
+	#settleAllPending(message: string): void {
+		for (const pending of [...this.#pending.values()])
+			this.#settleRun(pending, failedPythonResult(pending.input.cellId, message));
+	}
 
-function signalOrNull(value: unknown): NodeJS.Signals | null {
-	return typeof value === "string" ? (value as NodeJS.Signals) : null;
-}
+	#rejectAllPending(error: unknown): void {
+		for (const pending of [...this.#pending.values()]) this.#rejectRun(pending, error);
+	}
 
-async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T> {
-	let timer: NodeJS.Timeout | undefined;
-	const timeout = new Promise<never>((_, reject) => {
-		timer = setTimeout(() => reject(new Error(message)), timeoutMs);
-	});
-	try {
-		return await Promise.race([promise, timeout]);
-	} finally {
-		if (timer) clearTimeout(timer);
+	async #escalateInterruptedRun(pending: PendingRun): Promise<void> {
+		if (this.#active !== pending || pending.interruptReason === undefined) return;
+		const transport = this.#transport;
+		if (transport) await this.#beginRetirement(transport);
+		if (this.#pending.has(pending.input.cellId))
+			this.#settleRun(pending, failedPythonResult(pending.input.cellId, "Eval interrupted"));
 	}
-}
 
-async function delay(ms: number): Promise<void> {
-	await new Promise((resolve) => setTimeout(resolve, ms));
-}
+	#beginRetirement(transport: PythonKernelTransport): Promise<void> {
+		if (this.#retirement) return this.#retirement;
+		const operation = (async () => {
+			try {
+				await transport.retire();
+			} catch (error) {
+				if (error instanceof Error) throw this.#recordFailure(error);
+				throw error;
+			}
+			if (this.#transport === transport) this.#transport = null;
+		})();
+		const retirement = operation.finally(() => {
+			if (this.#retirement === retirement) this.#retirement = null;
+			this.#startNext();
+		});
+		this.#retirement = retirement;
+		return retirement;
+	}
 
-async function onceExit(child: KernelChild): Promise<void> {
-	await new Promise<void>((resolve) => child.once("exit", () => resolve()));
+	#recordFailure(error: Error): Error {
+		this.#failure = error;
+		this.#rejectAllPending(error);
+		return error;
+	}
 }