@code-yeongyu/senpi 2026.7.10 → 2026.7.13

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/context-manager.ts

@@ -1,45 +1,40 @@
-import { Worker } from "node:worker_threads";
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
 import { createInlineWorker, type WorkerLike } from "./inline-worker.ts";
+import {
+	assertJavaScriptKernelOpen,
+	type JavaScriptKernelMode,
+	type JavaScriptRunInput,
+	type LifecycleState,
+	type ResultMessage,
+	type ToolCallMessage,
+} from "./kernel-contract.ts";
+import { type JavaScriptKernelOptions, LocalModuleLoader, localBridgeConnection } from "./local-module-loader.ts";
+import { JavaScriptRunQueue, type PendingJavaScriptRun, stoppedResult } from "./run-queue.ts";
+import { bridgeError, spawnNodeWorker, WorkerStartupCancelledError, waitForReady } from "./worker-host.ts";
 
-export type JavaScriptKernelMode = "worker" | "inline";
-
-export interface JavaScriptKernelOptions {
-	readonly sessionId: string;
-	readonly cwd: string;
-	readonly parallelPoolWidth: number;
-	readonly onMessage?: (message: KernelToHostMessage) => void;
-	readonly workerEntryUrl?: URL;
-}
-
-export interface JavaScriptRunInput {
-	readonly cellId: string;
-	readonly code: string;
-	readonly timeoutMs?: number;
-	readonly onMessage?: (message: KernelToHostMessage) => void;
-}
-
-type ResultMessage = Extract<KernelToHostMessage, { type: "result" }>;
-type ToolCallMessage = Extract<KernelToHostMessage, { type: "tool-call" }>;
-
-interface QueuedRun {
-	readonly input: JavaScriptRunInput;
-	resolve(message: ResultMessage): void;
-}
+export { JavaScriptKernelClosedError, type JavaScriptKernelMode, type JavaScriptRunInput } from "./kernel-contract.ts";
+export type { JavaScriptKernelOptions } from "./local-module-loader.ts";
 
 export class JavaScriptKernel {
 	readonly #options: JavaScriptKernelOptions;
+	readonly #moduleLoader: LocalModuleLoader;
 	#worker: WorkerLike | null = null;
 	#mode: JavaScriptKernelMode = "worker";
+	#lifecycle: LifecycleState = "open";
 	#ready: Promise<void> | null = null;
-	#queue: QueuedRun[] = [];
-	#active: QueuedRun | null = null;
+	#startupAbort: AbortController | null = null;
+	#generation = 0;
+	#activation: Promise<void> | null = null;
+	#recovery: Promise<void> | null = null;
+	#closePromise: Promise<void> | null = null;
+	readonly #runs = new JavaScriptRunQueue();
 	#timeout: NodeJS.Timeout | null = null;
 	#toolWaiters: Array<(message: ToolCallMessage) => void> = [];
 	#pendingToolCalls: ToolCallMessage[] = [];
 
 	constructor(options: JavaScriptKernelOptions) {
 		this.#options = options;
+		this.#moduleLoader = new LocalModuleLoader(options);
 	}
 
 	get mode(): JavaScriptKernelMode {
@@ -47,22 +42,32 @@ export class JavaScriptKernel {
 	}
 
 	async run(input: JavaScriptRunInput): Promise<ResultMessage> {
-		await this.#ensureReady();
-		const promise = new Promise<ResultMessage>((resolve) => {
-			this.#queue.push({ input, resolve });
-		});
-		this.#startNext();
+		assertJavaScriptKernelOpen(this.#lifecycle, "run");
+		const promise = this.#runs.enqueue(input);
+		this.#activate();
 		return await promise;
 	}
 
+	async interrupt(reason = "interrupted"): Promise<void> {
+		assertJavaScriptKernelOpen(this.#lifecycle, "interrupt");
+		const active = this.#runs.active;
+		const target = this.#runs.takeInterruptTarget();
+		if (!target) return;
+		if (target === active) this.#clearTimeout();
+		this.#runs.settle(target, stoppedResult(target.input.cellId, `JS cell interrupted: ${reason}`));
+		await this.#restartAfterStop();
+	}
+
 	async reset(): Promise<void> {
+		assertJavaScriptKernelOpen(this.#lifecycle, "reset");
 		await this.#terminate();
-		this.#ready = null;
+		assertJavaScriptKernelOpen(this.#lifecycle, "reset");
 		await this.#ensureReady();
+		this.#startNext();
 	}
 
 	deliverToolReply(message: Extract<HostToKernelMessage, { type: "tool-reply" }>): void {
-		this.#worker?.postMessage(message);
+		if (this.#lifecycle === "open") this.#worker?.postMessage(message);
 	}
 
 	async nextToolCall(): Promise<ToolCallMessage> {
@@ -72,92 +77,175 @@ export class JavaScriptKernel {
 	}
 
 	async close(): Promise<void> {
+		if (this.#closePromise) return await this.#closePromise;
 		this.#worker?.postMessage({ type: "close" });
-		await this.#terminate();
+		this.#lifecycle = "closing";
+		this.#runs.settleAll("JS kernel closed");
+		const recovery = this.#recovery;
+		const closePromise = (async () => {
+			if (recovery) await recovery;
+			await this.#terminate();
+		})().finally(() => {
+			this.#lifecycle = "closed";
+		});
+		this.#closePromise = closePromise;
+		return await closePromise;
+	}
+
+	#activate(): void {
+		if (this.#activation || this.#lifecycle !== "open" || this.#runs.active || !this.#runs.hasWaiting) return;
+		const activation = this.#activateWhenReady();
+		this.#activation = activation;
+		void activation.then(() => {
+			if (this.#activation === activation) this.#activation = null;
+			if (this.#lifecycle === "open" && !this.#runs.active && this.#runs.hasWaiting) this.#activate();
+		});
+	}
+
+	async #activateWhenReady(): Promise<void> {
+		try {
+			await this.#ensureReady();
+			if (this.#lifecycle === "open") this.#startNext();
+		} catch (error) {
+			if (error instanceof WorkerStartupCancelledError) return;
+			this.#runs.rejectWaiting(error instanceof Error ? error : new Error(String(error)));
+		}
 	}
 
 	async #ensureReady(): Promise<void> {
-		if (!this.#ready) this.#ready = this.#startWorker();
+		assertJavaScriptKernelOpen(this.#lifecycle, "run");
+		if (!this.#ready) {
+			const generation = ++this.#generation;
+			const controller = new AbortController();
+			this.#startupAbort = controller;
+			const ready = this.#startWorker(generation, controller.signal);
+			this.#ready = ready;
+			void ready.then(
+				() => {
+					if (this.#ready === ready) this.#startupAbort = null;
+				},
+				() => {
+					if (this.#ready === ready) {
+						this.#ready = null;
+						this.#startupAbort = null;
+					}
+				},
+			);
+		}
 		return await this.#ready;
 	}
 
-	async #startWorker(): Promise<void> {
-		const worker = this.#spawnWorker();
-		this.#worker = worker;
-		this.#mode = worker.mode;
-		const ready = waitForReady(worker);
-		worker.onMessage((message) => this.#handleMessage(message));
-		worker.onError((error) => this.#handleCrash(error));
-		worker.postMessage({ type: "init", sessionId: this.#options.sessionId, connection: { port: 1, token: "local" } });
+	async #startWorker(generation: number, signal: AbortSignal): Promise<void> {
+		let worker = this.#spawnWorker();
+		this.#publishWorker(worker, generation);
 		try {
-			await ready;
+			await this.#initializeWorker(worker, signal);
+			return;
 		} catch (error) {
+			if (!this.#isCurrent(worker, generation) || error instanceof WorkerStartupCancelledError) {
+				await worker.terminate();
+				throw new WorkerStartupCancelledError();
+			}
 			if (worker.mode === "inline") throw error;
-			await worker.terminate().catch(() => undefined);
-			const inline = createInlineWorker(this.#options.parallelPoolWidth);
-			this.#worker = inline;
-			this.#mode = "inline";
-			const inlineReady = waitForReady(inline);
-			inline.onMessage((message) => this.#handleMessage(message));
-			inline.onError((crash) => this.#handleCrash(crash));
-			inline.postMessage({
-				type: "init",
-				sessionId: this.#options.sessionId,
-				connection: { port: 1, token: "local" },
-			});
-			await inlineReady;
+			this.#worker = null;
+			await worker.terminate();
 		}
+		if (this.#lifecycle !== "open" || generation !== this.#generation) throw new WorkerStartupCancelledError();
+		worker = createInlineWorker(this.#options.cwd, this.#options.parallelPoolWidth);
+		this.#publishWorker(worker, generation);
+		await this.#initializeWorker(worker, signal);
 	}
 
 	#spawnWorker(): WorkerLike {
 		try {
 			const url = this.#options.workerEntryUrl ?? new URL("./worker-entry.js", import.meta.url);
-			const worker = new Worker(url, {
-				workerData: { cwd: this.#options.cwd, parallelPoolWidth: this.#options.parallelPoolWidth },
-			});
-			return wrapNodeWorker(worker);
-		} catch {
-			return createInlineWorker(this.#options.parallelPoolWidth);
+			return spawnNodeWorker(url, this.#options.cwd, this.#options.parallelPoolWidth);
+		} catch (error) {
+			if (!(error instanceof Error)) throw error;
+			return createInlineWorker(this.#options.cwd, this.#options.parallelPoolWidth);
 		}
 	}
 
+	#publishWorker(worker: WorkerLike, generation: number): void {
+		if (this.#lifecycle !== "open" || generation !== this.#generation) throw new WorkerStartupCancelledError();
+		this.#worker = worker;
+		this.#mode = worker.mode;
+		worker.onMessage((message) => {
+			if (this.#isCurrent(worker, generation)) this.#handleMessage(message);
+		});
+		worker.onError((error) => {
+			if (this.#isCurrent(worker, generation)) this.#handleCrash(error);
+		});
+	}
+
+	async #initializeWorker(worker: WorkerLike, signal: AbortSignal): Promise<void> {
+		const ready = waitForReady(worker, signal);
+		worker.postMessage({
+			type: "init",
+			sessionId: this.#options.sessionId,
+			connection: localBridgeConnection(this.#options),
+		});
+		await ready;
+	}
+
+	#isCurrent(worker: WorkerLike, generation: number): boolean {
+		return this.#lifecycle === "open" && this.#worker === worker && this.#generation === generation;
+	}
+
 	#startNext(): void {
-		if (this.#active || !this.#worker) return;
-		const next = this.#queue.shift();
+		if (this.#lifecycle !== "open" || this.#runs.active || !this.#worker) return;
+		const next = this.#runs.startNext(performance.now());
 		if (!next) return;
-		this.#active = next;
 		if (next.input.timeoutMs) {
-			this.#timeout = setTimeout(() => void this.#timeoutActive(next.input.cellId), next.input.timeoutMs);
+			this.#timeout = setTimeout(() => void this.#timeoutActive(next), next.input.timeoutMs);
 		}
 		this.#worker.postMessage({
 			type: "run",
 			cellId: next.input.cellId,
-			code: next.input.code,
+			code: this.#moduleLoader.prepareCell(next.input.code),
 			timeoutMs: next.input.timeoutMs,
 		});
 	}
 
-	async #timeoutActive(cellId: string): Promise<void> {
-		const active = this.#active;
-		if (!active || active.input.cellId !== cellId) return;
-		const durationMs = active.input.timeoutMs ?? 0;
-		active.resolve({
+	async #timeoutActive(run: PendingJavaScriptRun): Promise<void> {
+		if (!this.#runs.releaseActive(run)) return;
+		const durationMs = run.input.timeoutMs ?? 0;
+		this.#runs.settle(run, {
 			type: "result",
-			cellId,
+			cellId: run.input.cellId,
 			ok: false,
 			error: { message: `JS cell timed out after ${durationMs}ms` },
 			durationMs,
 		});
-		this.#active = null;
-		await this.#terminate();
-		this.#ready = null;
-		await this.#ensureReady();
-		this.#startNext();
+		await this.#restartAfterStop();
+	}
+
+	async #restartAfterStop(): Promise<void> {
+		if (this.#recovery) return await this.#recovery;
+		const recovery = this.#performRestartAfterStop();
+		this.#recovery = recovery;
+		try {
+			await recovery;
+		} finally {
+			if (this.#recovery === recovery) this.#recovery = null;
+		}
+	}
+
+	async #performRestartAfterStop(): Promise<void> {
+		try {
+			await this.#terminate();
+			if (this.#lifecycle !== "open") return;
+			await this.#ensureReady();
+			if (this.#lifecycle === "open") this.#startNext();
+		} catch (error) {
+			if (error instanceof WorkerStartupCancelledError) return;
+			this.#runs.rejectWaiting(error instanceof Error ? error : new Error(String(error)));
+		}
 	}
 
 	#handleMessage(message: KernelToHostMessage): void {
 		this.#options.onMessage?.(message);
-		this.#active?.input.onMessage?.(message);
+		this.#runs.active?.input.onMessage?.(message);
 		if (message.type === "tool-call") {
 			const waiter = this.#toolWaiters.shift();
 			if (waiter) waiter(message);
@@ -165,83 +253,44 @@ export class JavaScriptKernel {
 			return;
 		}
 		if (message.type !== "result") return;
-		if (this.#timeout) clearTimeout(this.#timeout);
-		this.#timeout = null;
-		const active = this.#active;
-		this.#active = null;
-		active?.resolve(message);
+		const active = this.#runs.active;
+		if (!active || active.input.cellId !== message.cellId) return;
+		this.#clearTimeout();
+		this.#runs.releaseActive(active);
+		this.#runs.settle(active, message);
 		this.#startNext();
 	}
 
 	#handleCrash(error: Error): void {
-		const active = this.#active;
-		if (!active) return;
-		this.#active = null;
-		active.resolve({
-			type: "result",
-			cellId: active.input.cellId,
-			ok: false,
-			error: bridgeError(error),
-			durationMs: 0,
-		});
+		const active = this.#runs.active;
+		if (!active && this.#startupAbort) return;
+		this.#clearTimeout();
+		if (active) {
+			this.#runs.releaseActive(active);
+			this.#runs.settle(active, {
+				type: "result",
+				cellId: active.input.cellId,
+				ok: false,
+				error: bridgeError(error),
+				durationMs: this.#runs.durationMs(active, performance.now()),
+			});
+		}
+		void this.#restartAfterStop();
 	}
 
-	async #terminate(): Promise<void> {
+	#clearTimeout(): void {
 		if (this.#timeout) clearTimeout(this.#timeout);
 		this.#timeout = null;
+	}
+
+	async #terminate(): Promise<void> {
+		this.#clearTimeout();
+		this.#generation += 1;
+		this.#startupAbort?.abort();
+		this.#startupAbort = null;
+		this.#ready = null;
 		const worker = this.#worker;
 		this.#worker = null;
-		await worker?.terminate().catch(() => undefined);
+		if (worker) await worker.terminate();
 	}
 }
-
-function waitForReady(worker: WorkerLike): Promise<void> {
-	return new Promise((resolve, reject) => {
-		const offMessage = worker.onMessage((message) => {
-			if (message.type === "ready") {
-				offMessage();
-				offError();
-				resolve();
-			} else if (message.type === "init-failed") {
-				offMessage();
-				offError();
-				reject(errorFromBridge(message.error));
-			}
-		});
-		const offError = worker.onError((error) => {
-			offMessage();
-			offError();
-			reject(error);
-		});
-	});
-}
-
-function wrapNodeWorker(worker: Worker): WorkerLike {
-	return {
-		mode: "worker",
-		postMessage: (message) => worker.postMessage(message),
-		onMessage(handler) {
-			const listener = (message: KernelToHostMessage): void => handler(message);
-			worker.on("message", listener);
-			return () => worker.off("message", listener);
-		},
-		onError(handler) {
-			worker.on("error", handler);
-			return () => worker.off("error", handler);
-		},
-		async terminate() {
-			await worker.terminate();
-		},
-	};
-}
-
-function errorFromBridge(error: { message: string; name?: string; stack?: string }): Error {
-	const result = new Error(error.message);
-	if (error.name) result.name = error.name;
-	if (error.stack) result.stack = error.stack;
-	return result;
-}
-
-function bridgeError(error: Error): { message: string; name?: string; stack?: string } {
-	return { message: error.message, name: error.name, stack: error.stack };
-}

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/inline-worker-entry.js

@@ -0,0 +1,23 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { createWorkerCore } from "./worker-core.js";
+
+if (!parentPort) throw new Error("JS kernel inline fallback worker missing parentPort");
+
+const transport = {
+	send(message) {
+		parentPort.postMessage(message);
+	},
+	onMessage(handler) {
+		parentPort.on("message", handler);
+		return () => parentPort.off("message", handler);
+	},
+	close() {
+		parentPort.close();
+		setTimeout(() => process.exit(0), 0);
+	},
+};
+
+createWorkerCore(transport, {
+	cwd: workerData.cwd,
+	parallelPoolWidth: workerData.parallelPoolWidth,
+});

package/node_modules/@code-yeongyu/senpi-codemode/src/kernels/js/inline-worker.ts

@@ -1,11 +1,6 @@
-import { inspect } from "node:util";
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
-import type { JavaScriptKernelMode } from "./context-manager.ts";
-
-type AsyncFunctionType = new (...args: string[]) => (...values: unknown[]) => Promise<unknown>;
-const AsyncFunction = async function inlineAsyncFunction() {
-	return undefined;
-}.constructor as AsyncFunctionType;
+import type { JavaScriptKernelMode } from "./kernel-contract.ts";
+import { spawnNodeWorker } from "./worker-host.ts";
 
 export interface WorkerLike {
 	readonly mode: JavaScriptKernelMode;
@@ -15,172 +10,6 @@ export interface WorkerLike {
 	terminate(): Promise<void>;
 }
 
-export function createInlineWorker(parallelPoolWidth: number): WorkerLike {
-	return new InlineWorker(parallelPoolWidth);
-}
-
-class InlineWorker implements WorkerLike {
-	readonly mode = "inline";
-	readonly #parallelPoolWidth: number;
-	readonly #state: Record<string, unknown> = {};
-	#handlers: Array<(message: KernelToHostMessage) => void> = [];
-	#errorHandlers: Array<(error: Error) => void> = [];
-	#pendingTools = new Map<string, { resolve(value: unknown): void; reject(error: Error): void }>();
-
-	constructor(parallelPoolWidth: number) {
-		this.#parallelPoolWidth = parallelPoolWidth;
-	}
-
-	postMessage(message: HostToKernelMessage): void {
-		if (message.type === "init") this.#emit({ type: "ready" });
-		else if (message.type === "run") void this.#run(message.cellId, message.code);
-		else if (message.type === "tool-reply") this.#deliverToolReply(message);
-		else if (message.type === "close") this.#emit({ type: "closed" });
-	}
-
-	onMessage(handler: (message: KernelToHostMessage) => void): () => void {
-		this.#handlers.push(handler);
-		return () => {
-			this.#handlers = this.#handlers.filter((existing) => existing !== handler);
-		};
-	}
-
-	onError(handler: (error: Error) => void): () => void {
-		this.#errorHandlers.push(handler);
-		return () => {
-			this.#errorHandlers = this.#errorHandlers.filter((existing) => existing !== handler);
-		};
-	}
-
-	async terminate(): Promise<void> {
-		this.#handlers = [];
-		this.#errorHandlers = [];
-		this.#pendingTools.clear();
-	}
-
-	async #run(cellId: string, code: string): Promise<void> {
-		const started = Date.now();
-		try {
-			const value = await this.#execute(code);
-			this.#emit({
-				type: "result",
-				cellId,
-				ok: true,
-				valueRepr: valueRepr(value),
-				durationMs: Date.now() - started,
-			});
-		} catch (error) {
-			this.#emit({ type: "result", cellId, ok: false, error: bridgeError(error), durationMs: Date.now() - started });
-		}
-	}
-
-	async #execute(code: string): Promise<unknown> {
-		const transformed = code.replace(/(^|\n)\s*(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/gu, "$1state.$2 =");
-		const body = /\breturn\b/u.test(transformed) ? transformed : `return await (${transformed})`;
-		const fn = new AsyncFunction(
-			"state",
-			"tool",
-			"parallel",
-			"print",
-			"display",
-			"log",
-			"phase",
-			`with (state) { ${body} }`,
-		);
-		return await fn(
-			this.#state,
-			this.#toolProxy(),
-			this.#parallel.bind(this),
-			this.#print.bind(this),
-			this.#display.bind(this),
-			this.#log.bind(this),
-			this.#phase.bind(this),
-		);
-	}
-
-	#toolProxy(): unknown {
-		return new Proxy(
-			{},
-			{
-				get: (_target, prop) => {
-					if (typeof prop !== "string") return undefined;
-					return async (args: unknown) => await this.#callTool(prop, args);
-				},
-			},
-		);
-	}
-
-	async #callTool(toolName: string, args: unknown): Promise<unknown> {
-		const callId = `js-${crypto.randomUUID()}`;
-		const promise = new Promise<unknown>((resolve, reject) => this.#pendingTools.set(callId, { resolve, reject }));
-		this.#emit({ type: "tool-call", callId, toolName, args });
-		return await promise;
-	}
-
-	#deliverToolReply(message: Extract<HostToKernelMessage, { type: "tool-reply" }>): void {
-		const pending = this.#pendingTools.get(message.callId);
-		if (!pending) return;
-		this.#pendingTools.delete(message.callId);
-		if (message.ok) pending.resolve(message.value);
-		else pending.reject(errorFromBridge(message.error));
-	}
-
-	async #parallel(thunks: Array<() => Promise<unknown>>): Promise<unknown[]> {
-		const results = new Array<unknown>(thunks.length);
-		let next = 0;
-		await Promise.all(
-			Array.from({ length: Math.min(this.#parallelPoolWidth, thunks.length) }, async () => {
-				while (next < thunks.length) {
-					const index = next;
-					next += 1;
-					results[index] = await thunks[index]();
-				}
-			}),
-		);
-		return results;
-	}
-
-	#print(...values: unknown[]): void {
-		this.#emit({ type: "text", stream: "stdout", data: `${values.map(formatValue).join(" ")}\n` });
-	}
-
-	#display(value: unknown): void {
-		this.#emit({
-			type: "display",
-			mimeType: "application/json",
-			dataBase64: Buffer.from(JSON.stringify(value), "utf8").toString("base64"),
-		});
-	}
-
-	#log(message: unknown): void {
-		this.#emit({ type: "log", message: String(message) });
-	}
-
-	#phase(title: unknown): void {
-		this.#emit({ type: "phase", title: String(title) });
-	}
-
-	#emit(message: KernelToHostMessage): void {
-		for (const handler of this.#handlers) handler(message);
-	}
-}
-
-function valueRepr(value: unknown): string | undefined {
-	return value === undefined ? undefined : JSON.stringify(value);
-}
-
-function formatValue(value: unknown): string {
-	return typeof value === "string" ? value : inspect(value, { colors: false, depth: 5 });
-}
-
-function errorFromBridge(error: { message: string; name?: string; stack?: string }): Error {
-	const result = new Error(error.message);
-	if (error.name) result.name = error.name;
-	if (error.stack) result.stack = error.stack;
-	return result;
-}
-
-function bridgeError(error: unknown): { message: string; name?: string; stack?: string } {
-	if (error instanceof Error) return { message: error.message, name: error.name, stack: error.stack };
-	return { message: String(error) };
+export function createInlineWorker(cwd: string, parallelPoolWidth: number): WorkerLike {
+	return spawnNodeWorker(new URL("./inline-worker-entry.js", import.meta.url), cwd, parallelPoolWidth, "inline");
 }

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

@@ -0,0 +1,38 @@
+import type { KernelToHostMessage } from "../../bridge/protocol.ts";
+
+export type ResultMessage = Extract<KernelToHostMessage, { type: "result" }>;
+export type ToolCallMessage = Extract<KernelToHostMessage, { type: "tool-call" }>;
+
+export type JavaScriptKernelMode = "worker" | "inline";
+
+export interface JavaScriptKernelOptions {
+	readonly sessionId: string;
+	readonly cwd: string;
+	readonly parallelPoolWidth: number;
+	readonly onMessage?: (message: KernelToHostMessage) => void;
+	readonly workerEntryUrl?: URL;
+}
+
+export interface JavaScriptRunInput {
+	readonly cellId: string;
+	readonly code: string;
+	readonly timeoutMs?: number;
+	readonly onMessage?: (message: KernelToHostMessage) => void;
+}
+
+export type KernelOperation = "run" | "reset" | "interrupt";
+export type LifecycleState = "open" | "closing" | "closed";
+
+export class JavaScriptKernelClosedError extends Error {
+	readonly name = "JavaScriptKernelClosedError";
+	readonly operation: KernelOperation;
+
+	constructor(operation: KernelOperation) {
+		super(`Cannot ${operation}: JavaScript kernel is closed`);
+		this.operation = operation;
+	}
+}
+
+export function assertJavaScriptKernelOpen(lifecycle: LifecycleState, operation: KernelOperation): void {
+	if (lifecycle !== "open") throw new JavaScriptKernelClosedError(operation);
+}