@code-yeongyu/senpi-codemode 2026.10.6 → 2026.10.8

package/src/kernels/js/kernel-tools-registry.js

@@ -6,7 +6,8 @@ import { orderedArgs, resolveToolMetadata, validateInvokeArgs } from "./kernel-t
 
 export { createToolNamespace };
 
-const DEFAULT_RESERVED = Object.freeze(["__agent__", "__output__", "__schema__"]);
+// "defined" and "undefine" are the tool namespace's own members, so a kernel tool by those names could never be reached.
+const DEFAULT_RESERVED = Object.freeze(["__agent__", "__output__", "__schema__", "defined", "undefine"]);
 
 function currentNames(source) {
 	return typeof source === "function" ? source() : (source ?? []);
@@ -47,21 +48,22 @@ export function createKernelToolRegistry(options = {}) {
 			assertJs();
 			const parsed = parseToolFunction(fn);
 			const resolved = resolveToolMetadata(metadata, parsed.params);
-			if (sanitizeNamePart(parsed.name) !== parsed.name || parsed.name.length > MCP_TOOL_NAME_MAX_LENGTH) {
+			const name = resolved.name ?? parsed.name;
+			if (sanitizeNamePart(name) !== name || name.length > MCP_TOOL_NAME_MAX_LENGTH) {
 				throw kernelToolError("invalid_tool_definition", "Kernel tool name must match MCP name grammar");
 			}
-			const normalizedName = parsed.name;
-			const key = kernelToolKey(parsed.name);
-			if (reservedKeys.has(key)) throw kernelToolError("reserved_tool_name", `Kernel tool name is reserved: ${parsed.name}`);
+			const normalizedName = name;
+			const key = kernelToolKey(name);
+			if (reservedKeys.has(key)) throw kernelToolError("reserved_tool_name", `Kernel tool name is reserved: ${name}`);
 			if (hasNameKey(hostSource, key) || hasNameKey(foreignSource, key)) {
-				throw kernelToolError("tool_name_collision", `Kernel tool name collides: ${parsed.name}`);
+				throw kernelToolError("tool_name_collision", `Kernel tool name collides: ${name}`);
 			}
 			const existing = entries.get(key);
-			if (existing && existing.originalName !== parsed.name) {
-				throw kernelToolError("tool_name_collision", `Kernel tool name collides: ${parsed.name}`);
+			if (existing && existing.originalName !== name) {
+				throw kernelToolError("tool_name_collision", `Kernel tool name collides: ${name}`);
 			}
 			const entry = {
-				originalName: parsed.name,
+				originalName: name,
 				normalizedName,
 				fn,
 				params: parsed.params,
@@ -114,6 +116,13 @@ export function createKernelToolRegistry(options = {}) {
 				throw kernelToolError("kernel_tool_failed", error instanceof Error ? error.message : String(error));
 			}
 		},
+		defined() {
+			return [...entries.values()].map((entry) => entry.normalizedName).sort();
+		},
+		undefine(name) {
+			if (typeof name !== "string") return false;
+			return entries.delete(kernelToolKey(name));
+		},
 		bumpGeneration() {
 			generation += 1;
 			entries.clear();

package/src/kernels/js/kernel-tools-schema.js

@@ -18,7 +18,11 @@ export function resolveToolMetadata(metadata, params) {
 	if (typeof description !== "string") {
 		throw kernelToolError("invalid_tool_definition", "tool() description must be a string");
 	}
-	if (metadata.schema === undefined) return { description, input_schema: defaultInputSchema(params) };
+	if (metadata.name !== undefined && typeof metadata.name !== "string") {
+		throw kernelToolError("invalid_tool_definition", "tool() name must be a string");
+	}
+	const named = metadata.name === undefined ? {} : { name: metadata.name };
+	if (metadata.schema === undefined) return { ...named, description, input_schema: defaultInputSchema(params) };
 	const schema = metadata.schema;
 	if (!isPlainJsonObject(schema) || schema.type !== "object" || !isPlainJsonObject(schema.properties)) {
 		throw kernelToolError("invalid_tool_definition", "tool() metadata schema must be a JSON object schema");
@@ -27,7 +31,7 @@ export function resolveToolMetadata(metadata, params) {
 	if (propertyKeys.length !== params.length || params.some((name) => !Object.hasOwn(schema.properties, name))) {
 		throw kernelToolError("invalid_tool_definition", "tool() metadata schema properties must match parameters");
 	}
-	return { description, input_schema: schema };
+	return { ...named, description, input_schema: schema };
 }
 
 export function validateInvokeArgs(schema, args) {

package/src/kernels/js/worker-runtime.js

@@ -8,6 +8,7 @@ import { awaitMaybePromise, indirectEval, wrapUserCode } from "./worker-indirect
 import { installShellCapture } from "./worker-shell-capture.js";
 import { bindKernelBun } from "./worker-webview.js";
 import { createWorkpool } from "./workpool.js";
+import { createHandleHelpers } from "./handles.js";
 import { inKernelToolInvoke } from "./kernel-tools-context.js";
 import { kernelToolError } from "./kernel-tools-errors.js";
 import { createKernelToolRegistry, createToolNamespace } from "./kernel-tools-registry.js";
@@ -137,10 +138,18 @@ export class JsWorkerRuntime {
 		globalThis.workpool = (agent, name, options) => createWorkpool((toolName, args) => this.#callTool(toolName, args), agent, name, options);
 		globalThis.parallel = async thunks => await this.#parallel(thunks);
 		globalThis.pipeline = async (items, ...stages) => await this.#pipeline(items, stages);
-		globalThis.completion = async (prompt, opts) => await this.#callTool("completion", { prompt, opts });
+		const handles = createHandleHelpers(async (toolName, args) => await this.#callTool(toolName, args));
+		globalThis.completion = async (prompt, opts) => {
+			const value = await this.#callTool("completion", { prompt, opts });
+			// The host answers a {handle: true} request with a saved reference; the cell gets the control view.
+			return isPlainObject(opts) && opts.handle === true ? handles.handle(value) : value;
+		};
+		globalThis.wait = async (list, options) => await handles.wait(list, options);
+		globalThis.handle = value => handles.handle(value);
 		globalThis.tool = createToolNamespace(
 			(fn, metadata) => this.#tools.define(fn, metadata),
 			async (name, args) => await this.#callTool(name, args),
+			{ defined: () => this.#tools.defined(), undefine: (name) => this.#tools.undefine(name) },
 		);
 		globalThis.tools = globalThis.tool;
 		const originalLog = console.log.bind(console);

package/src/kernels/py/host-cell.ts

@@ -0,0 +1,42 @@
+import type { KernelToHostMessage } from "../../bridge/protocol.ts";
+import type { HostCellExecutor } from "../../tool/types.ts";
+
+type HostCellOutcome = Awaited<ReturnType<HostCellExecutor>>;
+
+import type { PendingRun, ResultMessage } from "./kernel-contract.ts";
+import { failedPythonResult } from "./transport.ts";
+
+export function runHostCell(
+	pending: PendingRun,
+	host: HostCellExecutor,
+	io: { readonly emit: (message: KernelToHostMessage) => void; readonly settle: (result: ResultMessage) => void },
+): void {
+	const abort = new AbortController();
+	pending.hostAbort = abort;
+	const cellId = pending.input.cellId;
+	let finished = false;
+	// Output from an executor that was aborted, or after its outcome, belongs to no cell.
+	const emit = (message: KernelToHostMessage): void => {
+		if (!finished && !abort.signal.aborted) io.emit(message);
+	};
+	// Calling the executor inside a promise keeps a synchronous throw in this cell instead of failing the queue.
+	const done = new Promise<HostCellOutcome>((resolve) => resolve(host({ signal: abort.signal, emit }))).then(
+		(outcome): ResultMessage =>
+			outcome.ok
+				? {
+						type: "result",
+						cellId,
+						ok: true,
+						durationMs: 0,
+						...(outcome.valueRepr === undefined ? {} : { valueRepr: outcome.valueRepr }),
+					}
+				: { type: "result", cellId, ok: false, error: outcome.error, durationMs: 0 },
+		(error: unknown): ResultMessage =>
+			failedPythonResult(cellId, error instanceof Error ? error.message : String(error)),
+	);
+	pending.hostDone = done;
+	void done.then((result) => {
+		finished = true;
+		if (!abort.signal.aborted) io.settle(result);
+	});
+}

package/src/kernels/py/kernel-contract.ts

@@ -3,7 +3,8 @@ import type { BridgeConnectionConfig, KernelToHostMessage } from "../../bridge/p
 import type { EvalKernelRunInput } from "../../tool/types.ts";
 import type { SessionEnvironment } from "../session-env.ts";
 import type { KernelLifecycle } from "../shared/kernel-death.ts";
-import type { KernelSpawnProcess } from "./process.ts";
+import type { PeerKernelToolsDescribe } from "./kernel-tools-host.ts";
+import type { KernelSpawnProcess, KillProcessGroup } from "./process.ts";
 import type { PythonStartupStage } from "./startup.ts";
 import type { PythonTransportResult } from "./transport.ts";
 
@@ -15,14 +16,22 @@ export interface PythonKernelStartOptions extends KernelLifecycle {
 	readonly env?: NodeJS.ProcessEnv;
 	/** Per-session PI_* values merged into the interpreter environment at spawn. */
 	readonly sessionEnv?: SessionEnvironment;
-	/** Python bootstrap inactivity guard per advancing stage, not a total readiness deadline. */
+	/** How long a starting interpreter may show no stage change, output or CPU use before startup fails. */
 	readonly startupTimeoutMs?: number;
+	/** Total startup backstop for an interpreter that stays busy but never becomes ready. */
+	readonly startupCeilingMs?: number;
+	/** Reads the interpreter's CPU time; the default reads the process group (Unix) or the process (Windows). */
+	readonly readCpuTime?: (pid: number | undefined) => bigint | undefined;
+	/** Signals the interpreter's process group when it is retired; the default is `process.kill(-pid, signal)`. */
+	readonly killProcessGroup?: KillProcessGroup;
 	/** Observes bootstrap control events without mixing them into cell output callbacks. */
 	readonly onStartupProgress?: (stage: PythonStartupStage) => void;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
 	readonly spawnProcess?: KernelSpawnProcess;
 	/** Post-cell collection, notice, and ceiling thresholds sent on `init`; absent leaves memory unmanaged. */
 	readonly memory?: KernelMemoryThresholds;
+	/** The JavaScript kernel's describe, so a name defined in both languages is a describe-time collision. */
+	readonly peerKernelToolsDescribe?: PeerKernelToolsDescribe;
 }
 
 export type PythonKernelRunOptions = EvalKernelRunInput;
@@ -39,4 +48,6 @@ export interface PendingRun {
 	interruptReason?: string;
 	/** Set while an interrupt outcome is pending; resolved once the kernel knows whether state survived. */
 	resolveStateRetained?: (retained: boolean) => void;
+	hostAbort?: AbortController;
+	hostDone?: Promise<ResultMessage>;
 }

package/src/kernels/py/kernel-tools-host.ts

@@ -0,0 +1,97 @@
+import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
+import { kernelToolError } from "../js/kernel-tools-errors.ts";
+import type {
+	KernelToolsDescribeResult,
+	KernelToolsInvokeOptions,
+	KernelToolsInvokeRequest,
+} from "../js/kernel-tools-types.ts";
+import { KernelToolHostPump } from "../shared/kernel-tools-pump.ts";
+
+export type KernelToolReplyEvent = {
+	readonly requestId: string;
+	readonly ok: boolean;
+	readonly code?: string;
+	readonly message?: string;
+	readonly output?: string;
+};
+
+function replyEvent(message: Extract<KernelToHostMessage, { type: "kernel-tool-invoke-reply" }>): KernelToolReplyEvent {
+	return {
+		requestId: message.requestId,
+		ok: message.ok,
+		...(message.ok ? {} : { message: message.error.message }),
+		...(!message.ok && message.error.code !== undefined ? { code: message.error.code } : {}),
+		...(message.output === undefined ? {} : { output: message.output }),
+	};
+}
+
+export type PeerKernelToolsDescribe = (names: readonly string[]) => Promise<KernelToolsDescribeResult> | undefined;
+
+/** The host half of Python kernel tools: frames over the live transport, names, and generation fencing. */
+export class PythonKernelTools {
+	readonly #pump: KernelToolHostPump;
+	readonly #peerDescribe: PeerKernelToolsDescribe | undefined;
+	#names: readonly string[] = [];
+
+	constructor(options: {
+		readonly post: (message: HostToKernelMessage) => void;
+		readonly isOpen: () => boolean;
+		readonly peerDescribe?: PeerKernelToolsDescribe;
+	}) {
+		this.#pump = new KernelToolHostPump(options.post, options.isOpen);
+		this.#peerDescribe = options.peerDescribe;
+	}
+
+	get events(): EventTarget {
+		return this.#pump.events;
+	}
+
+	listNames(): readonly string[] {
+		return this.#names;
+	}
+
+	consume(message: KernelToHostMessage): boolean {
+		if (message.type === "kernel-tools-defined") {
+			this.#names = [...message.names];
+			return true;
+		}
+		if (message.type === "kernel-tool-invoke-reply") {
+			// Published even when the waiter is gone (a cancelled call), so its explicit outcome stays observable.
+			this.#pump.events.dispatchEvent(
+				new CustomEvent<KernelToolReplyEvent>("kernelToolReply", { detail: replyEvent(message) }),
+			);
+		}
+		return this.#pump.consume(message);
+	}
+
+	/** The interpreter is gone (restart, reset, close, death): its definitions and in-flight calls are too. */
+	retire(reason: "kernel_tool_stale" | "tools_unavailable", message: string): void {
+		this.#names = [];
+		this.#pump.rejectAll(kernelToolError(reason, message));
+	}
+
+	async describe(names: readonly string[]): Promise<KernelToolsDescribeResult> {
+		const own = await this.#pump.describe(names);
+		const peer = await this.#peerDescribe?.(names)?.catch(() => undefined);
+		if (!peer) return own;
+		const definedInJs = new Set(peer.results.filter((entry) => entry.ok).map((entry) => entry.name));
+		return {
+			results: own.results.map((entry) =>
+				entry.ok && definedInJs.has(entry.name)
+					? {
+							name: entry.name,
+							ok: false,
+							error: {
+								code: "tool_name_collision",
+								message: `Kernel tool ${entry.name} is defined in both js and py`,
+							},
+						}
+					: entry,
+			),
+		};
+	}
+
+	async invoke(request: KernelToolsInvokeRequest, options?: AbortSignal | KernelToolsInvokeOptions): Promise<unknown> {
+		return await this.#pump.invoke(request, options);
+	}
+}

package/src/kernels/py/kernel.ts

@@ -1,12 +1,17 @@
 // allow: SIZE_OK — one persistent Python lifecycle state machine owns queue, generation, and retirement.
 import type { KernelInterruptHandle, PendingCell } from "../../tool/types.ts";
-import type { KernelToolsInvokeOptions } from "../js/kernel-tools-types.ts";
-import { rejectKernelToolsUnavailable } from "../kernel-tools-unavailable.ts";
+import type {
+	KernelToolsDescribeResult,
+	KernelToolsInvokeOptions,
+	KernelToolsInvokeRequest,
+} from "../js/kernel-tools-types.ts";
 import { describeExit } from "../shared/kernel-death.ts";
 import { KernelMemoryHost } from "../shared/kernel-memory-host.ts";
 import { KernelPreludeTracker } from "../shared/kernel-prelude-plan.ts";
+import { runHostCell } from "./host-cell.ts";
 import type { PendingRun, PythonKernelRunOptions, PythonKernelStartOptions, ResultMessage } from "./kernel-contract.ts";
-import { pythonStartupHangGuardMs } from "./startup.ts";
+import { PythonKernelTools } from "./kernel-tools-host.ts";
+import { pythonStartupCeilingMs, pythonStartupHangGuardMs } from "./startup.ts";
 import { failedPythonResult, PythonKernelTransport } from "./transport.ts";
 
 export type { PythonKernelRunOptions, PythonKernelStartOptions } from "./kernel-contract.ts";
@@ -14,6 +19,15 @@ export type { KernelChild, KernelSpawnOptions, KernelSpawnProcess } from "./proc
 
 const interruptEscalationMs = 5_000;
 
+// Every interpreter this process starts gets its own generation, so a kernel tool descriptor taken from one
+// never resolves in another, whether it was replaced by reset, by a lazy restart after a crash, or by a new
+// kernel instance an owner created.
+let lastInterpreterGeneration = 0;
+function nextInterpreterGeneration(): number {
+	lastInterpreterGeneration += 1;
+	return lastInterpreterGeneration;
+}
+
 export class PythonKernel {
 	readonly #options: PythonKernelStartOptions;
 	#transport: PythonKernelTransport | null = null;
@@ -28,11 +42,17 @@ export class PythonKernel {
 	readonly #memory: KernelMemoryHost | null;
 	#generation = 0;
 	#closed = false;
+	readonly #tools: PythonKernelTools;
 	#dead = false;
 
 	private constructor(options: PythonKernelStartOptions) {
 		this.#options = options;
 		this.#memory = options.memory === undefined ? null : new KernelMemoryHost("py", options.memory);
+		this.#tools = new PythonKernelTools({
+			post: (message) => this.#transport?.post(message),
+			isOpen: () => this.#transport !== null && !this.#closed,
+			...(options.peerKernelToolsDescribe === undefined ? {} : { peerDescribe: options.peerKernelToolsDescribe }),
+		});
 	}
 
 	static async start(options: PythonKernelStartOptions): Promise<PythonKernel> {
@@ -42,7 +62,11 @@ export class PythonKernel {
 	}
 
 	listKernelToolNames(): readonly string[] {
-		return [];
+		return this.#tools.listNames();
+	}
+
+	get kernelToolEvents(): EventTarget {
+		return this.#tools.events;
 	}
 
 	isAlive(): boolean {
@@ -57,12 +81,15 @@ export class PythonKernel {
 		});
 	}
 
-	describeKernelTools(_names: readonly string[]): Promise<never> {
-		return rejectKernelToolsUnavailable();
+	describeKernelTools(names: readonly string[]): Promise<KernelToolsDescribeResult> {
+		return this.#tools.describe(names);
 	}
 
-	invokeKernelTool(_request: unknown, _options?: AbortSignal | KernelToolsInvokeOptions): Promise<never> {
-		return rejectKernelToolsUnavailable();
+	invokeKernelTool(
+		request: KernelToolsInvokeRequest,
+		options?: AbortSignal | KernelToolsInvokeOptions,
+	): Promise<unknown> {
+		return this.#tools.invoke(request, options);
 	}
 
 	run(input: PythonKernelRunOptions): Promise<ResultMessage> {
@@ -104,6 +131,11 @@ export class PythonKernel {
 			}
 		}
 		const active = this.#active;
+		if (active?.hostAbort && active.interruptReason === undefined) {
+			active.interruptReason = reason;
+			void this.#stopHostEntry(active, failedPythonResult(active.input.cellId, "Eval interrupted"));
+			return { stateRetained: Promise.resolve(true) };
+		}
 		const transport = this.#transport;
 		if (!active || !transport || active.interruptReason !== undefined)
 			return { stateRetained: Promise.resolve(true) };
@@ -125,6 +157,7 @@ export class PythonKernel {
 		if (this.#failure) throw this.#failure;
 		if (this.#closed) throw new Error("Python kernel is closed");
 		const generation = ++this.#generation;
+		this.#tools.retire("kernel_tool_stale", "Python kernel was reset; its kernel tools are gone");
 		const prior = this.#starting;
 		const operation = (async () => {
 			await prior?.catch(() => undefined);
@@ -150,6 +183,7 @@ export class PythonKernel {
 		if (this.#closePromise) return await this.#closePromise;
 		this.#closed = true;
 		this.#generation += 1;
+		this.#tools.retire("tools_unavailable", "Python kernel is closed");
 		this.#settleAllPending("Python kernel closed");
 		const starting = this.#starting;
 		this.#closePromise = (async () => {
@@ -201,6 +235,14 @@ export class PythonKernel {
 		const timeoutMs = pending.input.timeoutMs;
 		if (timeoutMs !== undefined)
 			pending.timeoutTimer = setTimeout(() => this.#timeoutRun(pending, timeoutMs), timeoutMs);
+		const host = pending.input.host;
+		if (host !== undefined) {
+			runHostCell(pending, host, {
+				emit: (message) => (pending.input.onMessage ?? this.#options.onMessage)?.(message),
+				settle: (result) => this.#settleRun(pending, result),
+			});
+			return;
+		}
 		try {
 			this.#transport?.run({
 				...pending.input,
@@ -219,11 +261,40 @@ export class PythonKernel {
 
 	#timeoutRun(pending: PendingRun, timeoutMs: number): void {
 		if (this.#active !== pending) return;
+		const timedOut = failedPythonResult(pending.input.cellId, `Python kernel timed out after ${timeoutMs}ms`);
+		if (pending.hostAbort) {
+			void this.#stopHostEntry(pending, timedOut);
+			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`),
-		);
+		this.#settleRun(pending, timedOut);
+	}
+
+	/**
+	 * Aborts a running host entry and settles it only once its executor has stopped (or after the same bound the
+	 * interpreter gets before escalation), so the next queue entry never overlaps the aborted host work. An
+	 * executor that finished successfully despite the abort reports that outcome: its work did commit.
+	 */
+	async #stopHostEntry(pending: PendingRun, stopped: ResultMessage): Promise<void> {
+		pending.hostAbort?.abort();
+		const done = pending.hostDone;
+		let bound: ReturnType<typeof setTimeout> | undefined;
+		const outcome =
+			done === undefined
+				? undefined
+				: await Promise.race([
+						done,
+						new Promise<undefined>((resolve) => {
+							bound = setTimeout(() => resolve(undefined), interruptEscalationMs);
+						}),
+					]);
+		if (bound !== undefined) clearTimeout(bound);
+		if (outcome?.ok === true) {
+			pending.interruptReason = undefined;
+			this.#settleRun(pending, outcome);
+			return;
+		}
+		this.#settleRun(pending, stopped);
 	}
 
 	async #ensureStarted(): Promise<void> {
@@ -240,6 +311,7 @@ export class PythonKernel {
 			...this.#options,
 			onMessage: (message) => {
 				if (message.type === "result") return;
+				if (generation === this.#generation && this.#tools.consume(message)) return;
 				const callback =
 					message.type === "ready" || message.type === "init-failed" || message.type === "closed"
 						? this.#options.onMessage
@@ -247,6 +319,8 @@ export class PythonKernel {
 				callback?.(message);
 			},
 			startupTimeoutMs: this.#options.startupTimeoutMs ?? pythonStartupHangGuardMs,
+			startupCeilingMs: this.#options.startupCeilingMs ?? pythonStartupCeilingMs,
+			kernelGeneration: nextInterpreterGeneration(),
 			isOwned: () => !this.#closed && generation === this.#generation,
 			onRetirementFailure: (transport, error) => {
 				if (!this.#transport) this.#transport = transport;
@@ -281,6 +355,7 @@ export class PythonKernel {
 	#onExit(transport: PythonKernelTransport, error: Error, reason: string): void {
 		if (this.#transport !== transport) return;
 		this.#transport = null;
+		this.#tools.retire("kernel_tool_stale", "Python kernel died; its kernel tools are gone");
 		// With an owner listening, a death is final for this instance: the cells that never started stay
 		// queued for `drainPending` and the owner replaces it. Without one it respawns lazily, as before.
 		const onDeath = this.#options.onDeath;
@@ -354,6 +429,7 @@ export class PythonKernel {
 	}
 
 	#removePending(pending: PendingRun): void {
+		pending.hostAbort?.abort();
 		if (pending.timeoutTimer) clearTimeout(pending.timeoutTimer);
 		if (pending.escalationTimer) clearTimeout(pending.escalationTimer);
 		pending.timeoutTimer = null;