@code-yeongyu/senpi-codemode 2026.10.7 → 2026.10.9

package/src/kernels/py/process.ts

@@ -22,6 +22,13 @@ export interface KernelSpawnOptions {
 
 export type KernelSpawnProcess = (options: KernelSpawnOptions) => KernelChild;
 
+/** Signals a kernel's whole process group (addressed by its leader pid); throws like `process.kill`. */
+export type KillProcessGroup = (pid: number, signal: NodeJS.Signals) => void;
+
+export const killProcessGroup: KillProcessGroup = (pid, signal) => {
+	process.kill(-pid, signal);
+};
+
 export class PythonKernelRetirementError extends Error {
 	constructor(pid: number | undefined) {
 		super(`Python kernel process${pid === undefined ? "" : ` ${pid}`} did not exit after SIGKILL`);
@@ -95,10 +102,10 @@ export async function waitForExit(child: KernelChild, timeoutMs: number): Promis
 // A cell's own subprocess is spawned into the detached kernel's process group. When the
 // leader exits gracefully on close, kill the group so a Popen the cell left running does
 // not outlive the kernel; the group is addressed by the leader pid (== pgid) while members live.
-export function sweepProcessGroup(child: KernelChild): void {
+export function sweepProcessGroup(child: KernelChild, killGroup: KillProcessGroup = killProcessGroup): void {
 	if (child.pid === undefined || process.platform === "win32") return;
 	try {
-		process.kill(-child.pid, "SIGKILL");
+		killGroup(child.pid, "SIGKILL");
 	} catch (error) {
 		// ESRCH means the group is already gone (the success case). Any other error
 		// (for example EPERM on a member we cannot signal) must not fail a graceful close.
@@ -106,7 +113,11 @@ export function sweepProcessGroup(child: KernelChild): void {
 	}
 }
 
-export async function hardKill(child: KernelChild, timeoutMs: number): Promise<void> {
+export async function hardKill(
+	child: KernelChild,
+	timeoutMs: number,
+	killGroup: KillProcessGroup = killProcessGroup,
+): Promise<void> {
 	await new Promise<void>((resolve, reject) => {
 		let timer: NodeJS.Timeout | undefined;
 		let settled = false;
@@ -123,7 +134,7 @@ export async function hardKill(child: KernelChild, timeoutMs: number): Promise<v
 		let signalDelivered = true;
 		if (child.pid !== undefined && process.platform !== "win32") {
 			try {
-				process.kill(-child.pid, "SIGKILL");
+				killGroup(child.pid, "SIGKILL");
 			} catch (error) {
 				if (!(error instanceof Error)) {
 					settle(new Error(String(error)));

package/src/kernels/py/startup.ts

@@ -1,10 +1,20 @@
 import type { KernelToHostMessage } from "../../bridge/protocol.ts";
 
-// Fresh-cache Windows bootstrap: p99 5,220 ms across 30 samples in Actions run
-// 36882163342. Twice that observation, rounded up to a second, is a hang guard,
-// not a total startup budget: only an advancing kernel stage rearms it.
+/**
+ * How long a starting interpreter may stay completely still before startup fails: no new stage, no output
+ * line, and no CPU used. A cold, contended interpreter importing the stdlib emits nothing for seconds but
+ * keeps the CPU busy, so it never trips; only one that is silent AND idle does. Fresh-cache Windows
+ * bootstraps measured p99 5,220 ms of mostly import time (Actions run 36882163342), so 11 s of complete
+ * stillness is a stall, not a slow start.
+ */
 export const pythonStartupHangGuardMs = 11_000;
 
+/**
+ * Total startup budget, a backstop for an interpreter that keeps burning CPU without ever reaching
+ * `ready` (a livelock). Over twenty times the slowest measured cold start; never reached by a real one.
+ */
+export const pythonStartupCeilingMs = 120_000;
+
 const stages = ["interpreter-launch", "stdlib-imports", "runtime-init", "host-init"] as const;
 export type PythonStartupStage = (typeof stages)[number];
 
@@ -18,19 +28,30 @@ export class PythonKernelStartupError extends Error {
 	}
 }
 
-/** Owns the ready event and a per-stage inactivity watchdog, never a total deadline. */
+export interface PythonStartupOptions {
+	readonly noProgressMs: number;
+	readonly ceilingMs: number;
+	readonly failureDetail: () => string;
+	/** CPU used so far by the interpreter (any unit that only grows); `undefined` when unreadable. */
+	readonly readCpuTime: () => bigint | undefined;
+}
+
 export class PythonStartup {
-	readonly #timeoutMs: number;
-	readonly #failureDetail: () => string;
+	readonly #options: PythonStartupOptions;
 	readonly #ready = Promise.withResolvers<void>();
 	readonly ready = this.#ready.promise;
+	readonly #ceiling: NodeJS.Timeout;
 	#timer: NodeJS.Timeout | undefined;
 	#stageIndex = 0;
+	#lastCpu: bigint | undefined;
 	#settled = false;
 
-	constructor(timeoutMs: number, failureDetail: () => string) {
-		this.#timeoutMs = timeoutMs;
-		this.#failureDetail = failureDetail;
+	constructor(options: PythonStartupOptions) {
+		this.#options = options;
+		this.#ceiling = setTimeout(
+			() => this.#fail(`not ready after ${Math.round(options.ceilingMs / 1000)} s`),
+			options.ceilingMs,
+		);
 		this.#arm();
 	}
 
@@ -45,31 +66,48 @@ export class PythonStartup {
 		return stage;
 	}
 
+	activity(): void {
+		if (!this.#settled) this.#arm();
+	}
+
 	settle(error?: Error): boolean {
 		if (this.#settled) return false;
 		this.#settled = true;
 		clearTimeout(this.#timer);
+		clearTimeout(this.#ceiling);
 		if (error) {
-			const stage = stages[this.#stageIndex] ?? "interpreter-launch";
 			this.#ready.reject(
 				error instanceof PythonKernelStartupError
 					? error
-					: new PythonKernelStartupError(stage, error.message, error),
+					: new PythonKernelStartupError(this.#stage(), error.message, error),
 			);
 		} else this.#ready.resolve();
 		return true;
 	}
 
 	#arm(): void {
+		this.#lastCpu = this.#options.readCpuTime();
 		clearTimeout(this.#timer);
-		this.#timer = setTimeout(() => {
-			const detail = this.#failureDetail().trim();
-			this.settle(
-				new PythonKernelStartupError(
-					stages[this.#stageIndex] ?? "interpreter-launch",
-					`no progress for ${this.#timeoutMs}ms${detail ? `; ${detail}` : ""}`,
-				),
-			);
-		}, this.#timeoutMs);
+		this.#timer = setTimeout(() => this.#expire(), this.#options.noProgressMs);
+	}
+
+	#expire(): void {
+		if (this.#settled) return;
+		const cpu = this.#options.readCpuTime();
+		// Where CPU can't be read, stage and output are the only signs of life, as before.
+		if (cpu !== undefined && cpu !== this.#lastCpu) {
+			this.#arm();
+			return;
+		}
+		this.#fail(`no output, stage change or CPU use for ${this.#options.noProgressMs}ms`);
+	}
+
+	#fail(reason: string): void {
+		const detail = this.#options.failureDetail().trim();
+		this.settle(new PythonKernelStartupError(this.#stage(), `${reason}${detail ? `; ${detail}` : ""}`));
+	}
+
+	#stage(): PythonStartupStage {
+		return stages[this.#stageIndex] ?? "interpreter-launch";
 	}
 }

package/src/kernels/py/transport.ts

@@ -11,6 +11,7 @@ import {
 } from "../../bridge/protocol.ts";
 import { applySessionEnvironment, type SessionEnvironment } from "../session-env.ts";
 import type { KernelPreludePlan } from "../shared/kernel-prelude-plan.ts";
+import { readKernelCpuTime } from "../shared/process-cpu.ts";
 import { type CodemodeRuntimeAssetEnvironment, requireCodemodeRuntimeAsset } from "../shared/runtime-asset.ts";
 import {
 	defaultSpawn,
@@ -18,6 +19,7 @@ import {
 	type KernelChild,
 	type KernelSpawnOptions,
 	type KernelSpawnProcess,
+	type KillProcessGroup,
 	numberOrNull,
 	signalOrNull,
 	splitCommand,
@@ -33,6 +35,9 @@ export interface PythonTransportRunInput {
 	readonly code: string;
 	readonly timeoutMs?: number;
 	readonly preludePlan?: KernelPreludePlan;
+	readonly envRoot?: () => string;
+	readonly sourceFile?: string;
+	readonly bridgeCellToken?: string;
 }
 
 export interface PythonTransportOptions {
@@ -44,8 +49,13 @@ export interface PythonTransportOptions {
 	/** Per-session PI_* values merged into the interpreter environment at spawn. */
 	readonly sessionEnv?: SessionEnvironment;
 	readonly startupTimeoutMs: number;
+	readonly startupCeilingMs: number;
+	readonly readCpuTime?: (pid: number | undefined) => bigint | undefined;
+	readonly killProcessGroup?: KillProcessGroup;
 	readonly onStartupProgress?: (stage: PythonStartupStage) => void;
 	readonly memory?: KernelMemoryThresholds;
+	/** Kernel-tool descriptors carry this; a restarted interpreter gets a new one, so old descriptors go stale. */
+	readonly kernelGeneration?: number;
 	readonly onMessage?: (message: KernelToHostMessage) => void;
 	readonly spawnProcess?: KernelSpawnProcess;
 	readonly isOwned: () => boolean;
@@ -140,12 +150,26 @@ export class PythonKernelTransport {
 		return transport;
 	}
 
+	/** Kernel-tool frames for the runner's control reader (served even while a cell runs). */
+	post(message: HostToKernelMessage): void {
+		if (this.#active && !this.#exited) this.#write(message);
+	}
+
 	run(input: PythonTransportRunInput): void {
 		const preludes = input.preludePlan && {
 			install: input.preludePlan.install.map(({ exports, python }) => ({ exports: [...exports], python })),
 			remove: [...input.preludePlan.remove],
 		};
-		this.#write({ type: "run", cellId: input.cellId, code: input.code, timeoutMs: input.timeoutMs, preludes });
+		this.#write({
+			type: "run",
+			cellId: input.cellId,
+			code: input.code,
+			timeoutMs: input.timeoutMs,
+			preludes,
+			...(input.envRoot === undefined ? {} : { envRoot: input.envRoot() }),
+			...(input.sourceFile === undefined ? {} : { sourceFile: input.sourceFile }),
+			...(input.bridgeCellToken === undefined ? {} : { bridgeCellToken: input.bridgeCellToken }),
+		});
 	}
 
 	interrupt(reason: string): void {
@@ -166,7 +190,7 @@ export class PythonKernelTransport {
 			return;
 		}
 		if (!this.#active) {
-			await hardKill(this.#child, hardKillWaitMs);
+			await hardKill(this.#child, hardKillWaitMs, this.#options.killProcessGroup);
 			return;
 		}
 		this.#active = false;
@@ -178,15 +202,15 @@ export class PythonKernelTransport {
 		}
 		// hardKill kills the whole group; a graceful leader exit does not, so sweep it
 		// to retire any subprocess the cell left running in the kernel's process group.
-		if (await exited) sweepProcessGroup(this.#child);
-		else await hardKill(this.#child, hardKillWaitMs);
+		if (await exited) sweepProcessGroup(this.#child, this.#options.killProcessGroup);
+		else await hardKill(this.#child, hardKillWaitMs, this.#options.killProcessGroup);
 	}
 
 	retire(): Promise<void> {
 		if (this.#exited || this.#isGone) return Promise.resolve();
 		if (this.#retirement) return this.#retirement;
 		this.#active = false;
-		const retirement = hardKill(this.#child, hardKillWaitMs).finally(() => {
+		const retirement = hardKill(this.#child, hardKillWaitMs, this.#options.killProcessGroup).finally(() => {
 			this.#detachListeners();
 			if (this.#retirement === retirement) this.#retirement = null;
 		});
@@ -195,7 +219,16 @@ export class PythonKernelTransport {
 	}
 
 	async #initialize(): Promise<void> {
-		const startup = new PythonStartup(this.#options.startupTimeoutMs, () => this.#stderrTail);
+		const pid = this.#child.pid;
+		const startup = new PythonStartup({
+			noProgressMs: this.#options.startupTimeoutMs,
+			ceilingMs: this.#options.startupCeilingMs,
+			failureDetail: () => this.#stderrTail,
+			readCpuTime: () => {
+				if (this.#options.readCpuTime) return this.#options.readCpuTime(pid);
+				return pid === undefined ? undefined : readKernelCpuTime(pid);
+			},
+		});
 		this.#startup = startup;
 		const onStdout = (chunk: unknown) => this.#onStdout(String(chunk));
 		const onStderr = (chunk: unknown) => this.#onStderr(String(chunk));
@@ -211,8 +244,14 @@ export class PythonKernelTransport {
 		this.#child.stderr.on("data", onStderr);
 		this.#child.on("error", onError);
 		this.#child.on("exit", onExit);
-		const { sessionId, connection, memory } = this.#options;
-		this.#write({ type: "init", sessionId, connection, ...(memory === undefined ? {} : { memory }) });
+		const { sessionId, connection, memory, kernelGeneration } = this.#options;
+		this.#write({
+			type: "init",
+			sessionId,
+			connection,
+			...(memory === undefined ? {} : { memory }),
+			...(kernelGeneration === undefined ? {} : { kernelGeneration }),
+		});
 		await startup.ready;
 	}
 
@@ -234,6 +273,7 @@ export class PythonKernelTransport {
 
 	#onStderr(chunk: string): void {
 		if (!this.#active) return;
+		this.#startup?.activity();
 		this.#stderrTail = `${this.#stderrTail}${chunk}`.slice(-4_000);
 		this.#options.onMessage?.({ type: "text", stream: "stderr", data: chunk });
 	}
@@ -251,6 +291,7 @@ export class PythonKernelTransport {
 			if (stage !== undefined) this.#options.onStartupProgress?.(stage);
 			return;
 		}
+		if (message.type === "text") this.#startup?.activity();
 		if (message.type === "ready") this.#settleStartup();
 		else if (message.type === "init-failed") this.#settleStartup(new Error(message.error.message));
 		else if (message.type === "result") this.#options.onResult(this, message);

package/src/kernels/rb/workpool.rb

@@ -23,9 +23,15 @@ class SenpiWorkpool
   end
 end
 
-def workpool(agent, name, mode: nil)
+def workpool(agent, name, mode: nil, tools: nil)
   args = { "op" => "create", "agent" => agent, "name" => name }
   args["mode"] = mode unless mode.nil?
+  unless tools.nil?
+    unless tools.is_a?(Array) && tools.all? { |name| name.is_a?(String) }
+      raise SenpiBridgeError.new("workpool(tools: ...) takes an array of tool names; got #{tools.class}", "invalid_tools")
+    end
+    args["tools"] = tools.dup
+  end
   result = __senpi_workpool_call(args)
   details = result["details"]
   if details.is_a?(Hash)

package/src/kernels/sandbox/vendor/pi-codemode/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/kernels/sandbox/vendor/pi-codemode/VENDORED.md

@@ -0,0 +1,42 @@
+# Vendored: @earendil-works/pi-codemode 1.0.1
+
+- Upstream: https://github.com/earendil-works/pi, directory `packages/codemode/src`
+- Tag `v1.0.1`, commit `a7229ddc21810d6245105978033b7df645ecc2f7` (`packages/codemode/package.json` version 1.0.1)
+- License: MIT, upstream `LICENSE` copied unchanged beside this file.
+- Why vendored: the published package ships compiled `dist` only, and senpi needs three host changes that are not in any release (listed below once they land). Vendoring the source keeps them in this repository, so a registry consumer receives them.
+
+## Provenance
+
+Building `packages/codemode` at that commit with its pinned compiler (`typescript` 7.0.2, `tsc -p tsconfig.build.json`) reproduces all 40 files of the published npm `@earendil-works/pi-codemode@1.0.1` `dist` byte for byte, so this source is the released code.
+
+Each file below starts with a two-line attribution header. `wasm.ts` and `identifier.ts` are otherwise the upstream file unchanged. The other five carry the local changes listed below, and nothing else: outside the `senpi-change` blocks and the lines marked `// senpi-change`, every line is upstream's, in upstream's order. The SHA-256 is of the upstream file.
+
+| file | upstream SHA-256 |
+| --- | --- |
+| `runtime/host.ts` | `b81e1bb07f3cd7e612c5ed03b6d23929acf3738be764c0741b85306d8221c522` |
+| `runtime/worker.ts` | `f2e4854de6c9713390148a7d02b35e753065aca42c759ca14676f90f937f0a8a` |
+| `runtime/prelude-source.ts` | `bd544106d5bd36543be4e5fc21128c9cd46b26856fb0b17931250b955f93c24a` |
+| `runtime/protocol.ts` | `b5150df8e6c743f99a94f13cf6f4ae7515768bb9e6305e1a7e4dacd20e4dc6ff` |
+| `types.ts` | `a54fd8d97468bedd16cc1aae6d89648581da90bd55f65bb0b116c947893b5920` |
+| `wasm.ts` | `0785024745568c86611b00a82f2bc8f70fc1559eff7200e64a449ebbeeeebb94` |
+| `identifier.ts` | `c920a297e79186edc61348906950b639e8d67602122f165fb98012fd32be2f11` |
+
+Only these seven files are vendored: the closure of `runtime/host.ts` (the sandbox host). `index.ts`, `source.ts` and `declarations.ts` are not used.
+
+## Local changes
+
+Every change is marked, in one of two ways, so a sync can find each one:
+
+- a block between `// senpi-change begin: <topic>` and `// senpi-change end`, which adds code or replaces the upstream lines it stands in place of (for example `types.ts`'s `CodemodeResult`, and the end of `finish()` in `runtime/host.ts`);
+- a single upstream line edited in place, ending in `// senpi-change` (an extra import name, the `"output-frame"` message type in `isWorkerToHostMessage`, the prelude's `optionsJson` parameter and its stream-mode output-cap condition).
+
+A sync must re-apply both kinds: dropping a marked line (for example `"output-frame"` in the protocol guard) would make the host ignore every frame. Each one is an option whose default is upstream's behaviour: with the defaults, the ported upstream suite (`test/sandbox/vendor/upstream-sandbox.test.ts`, 47 cases, only its imports changed) passes unchanged.
+
+1. **Output streaming** (`output: "stream"`, `onOutputFrame`, `windowBytes`, `frameBytes`; `types.ts`, `runtime/protocol.ts`, `runtime/worker.ts`, `runtime/host.ts`, `runtime/prelude-source.ts`). Upstream keeps every output item until the script settles, which is why it caps output at 16 Mi characters. In stream mode:
+   - The host keeps nothing; `result.output` stays empty and `result.streamed` reports frames and the peak bytes in flight.
+   - The worker splits each item into frames of at most `frameBytes` (default 64 KiB), never splitting a surrogate pair, tagged with item id, sequence and a final flag.
+   - It sends a frame only after taking that many bytes from a shared credit counter (default window 256 KiB). It sleeps on the counter with `Atomics.wait` while the window is full, and re-checks the interrupt flag each time it wakes.
+   - The host hands frames to the consumer one at a time, in order, and returns their credit only once the consumer has finished. The output cap does not apply, because memory is bounded by the window.
+   - A normal finish settles only after every frame is consumed. An abort or timeout settles at once and drops frames still queued. The timer and the abort signal stay armed while a finished run's last frames drain, so a late abort, timeout or `close()` abandons them too (the run settles with that error): a consumer that never returns cannot keep a run alive.
+   - `frameBytes` and `windowBytes` must be at least 4, so a frame can always hold a whole surrogate pair.
+2. **Builtin store policy** (`builtins: { store: "collect" | "reject" }`; `types.ts`, `runtime/protocol.ts`, `runtime/worker.ts`, `runtime/host.ts`, `runtime/prelude-source.ts`). With `"reject"`, `load()` returns `undefined` and `store()` throws `CodemodeStoreDisabledError`. The names stay defined, so scripts written for upstream fail with a clear message instead of a ReferenceError.

package/src/kernels/sandbox/vendor/pi-codemode/identifier.ts

@@ -0,0 +1,14 @@
+// Vendored from https://github.com/earendil-works/pi (packages/codemode/src) at v1.0.1, commit a7229ddc21810d6245105978033b7df645ecc2f7.
+// MIT license; see LICENSE beside this file. Local changes are listed in VENDORED.md.
+/**
+ * The identifier a script uses for a tool: characters that are not valid in a JavaScript
+ * identifier become `_`. `mcp__docs__search` stays as is, `my-tool` becomes `my_tool`.
+ */
+export function toCodemodeIdentifier(name: string): string {
+	let identifier = "";
+	for (const char of name) {
+		const valid = identifier === "" ? /^[A-Za-z_$]$/.test(char) : /^[A-Za-z0-9_$]$/.test(char);
+		identifier += valid ? char : "_";
+	}
+	return identifier === "" ? "_" : identifier;
+}