@code-yeongyu/senpi-codemode 2026.10.5 → 2026.10.7

package/src/config/memory-settings.ts

@@ -3,6 +3,9 @@ import { type Static, Type } from "typebox";
 import type { KernelMemoryThresholds } from "../bridge/memory-protocol.ts";
 import type { CodemodeSettings, Environment } from "./settings.ts";
 
+// The longest delay setTimeout honours (2^31 - 1 ms); a longer one fires after 1 ms.
+export const MAX_IDLE_PARK_MINUTES = 35_791;
+
 export const memorySettingsSchema = Type.Object(
 	{
 		gcWatermarkMb: Type.Optional(Type.Number({ minimum: 0 })),
@@ -10,6 +13,7 @@ export const memorySettingsSchema = Type.Object(
 		ceilingMb: Type.Optional(Type.Number({ minimum: 0 })),
 		retainedResultsMb: Type.Optional(Type.Number({ minimum: 0 })),
 		retainedImagesMb: Type.Optional(Type.Number({ minimum: 0 })),
+		idleParkMinutes: Type.Optional(Type.Number({ minimum: 0, maximum: MAX_IDLE_PARK_MINUTES })),
 	},
 	{ additionalProperties: false },
 );
@@ -27,6 +31,8 @@ export interface CodemodeMemorySettings {
 	readonly retainedResultsMb: number;
 	/** Disk budget (MiB) for settled-cell images spilled under the session artifacts dir; 0 keeps only the count cap. */
 	readonly retainedImagesMb: number;
+	/** Minutes with no cell running or queued before a kernel is closed and restarted on the next cell; absent or 0 never parks. */
+	readonly idleParkMinutes?: number;
 }
 
 export const DEFAULT_MEMORY_GC_WATERMARK_MB = 256;
@@ -67,6 +73,7 @@ export function mergeMemorySettings(input: CodemodeMemorySettingsInput | undefin
 		ceilingMb: input?.ceilingMb ?? defaults.ceilingMb,
 		retainedResultsMb: input?.retainedResultsMb ?? defaults.retainedResultsMb,
 		retainedImagesMb: input?.retainedImagesMb ?? defaults.retainedImagesMb,
+		...(input?.idleParkMinutes === undefined ? {} : { idleParkMinutes: input.idleParkMinutes }),
 	};
 }
 
@@ -91,6 +98,7 @@ export function validatedMemorySettings(input: CodemodeMemorySettingsInput | und
 			...defaults,
 			retainedResultsMb: merged.retainedResultsMb,
 			retainedImagesMb: merged.retainedImagesMb,
+			...(merged.idleParkMinutes === undefined ? {} : { idleParkMinutes: merged.idleParkMinutes }),
 		},
 		warnings: [warning],
 	};

package/src/config/settings-constants.ts

@@ -0,0 +1,7 @@
+export const HARD_LIMIT_ENVIRONMENT_FLAG = "SENPI_CODEMODE_HARD_LIMIT_SECONDS";
+export const FOREGROUND_WINDOW_ENVIRONMENT_FLAG = "SENPI_CODEMODE_FOREGROUND_SECONDS";
+export const RUN_BUDGET_ENVIRONMENT_FLAG = "SENPI_CODEMODE_RUN_BUDGET_SECONDS";
+export const MAX_DETACHED_CELLS_ENVIRONMENT_FLAG = "SENPI_CODEMODE_MAX_DETACHED_CELLS";
+export const DEFAULT_MAX_DETACHED_CELLS = 15;
+
+export type Environment = Readonly<Record<string, string | undefined>>;

package/src/config/settings-overrides.ts

@@ -0,0 +1,72 @@
+import type { CodemodeSettings } from "./settings.ts";
+import {
+	DEFAULT_MAX_DETACHED_CELLS,
+	type Environment,
+	FOREGROUND_WINDOW_ENVIRONMENT_FLAG,
+	HARD_LIMIT_ENVIRONMENT_FLAG,
+	MAX_DETACHED_CELLS_ENVIRONMENT_FLAG,
+	RUN_BUDGET_ENVIRONMENT_FLAG,
+} from "./settings-constants.ts";
+
+const languageEnvironmentFlags = {
+	py: "SENPI_CODEMODE_PY",
+	js: "SENPI_CODEMODE_JS",
+	rb: "SENPI_CODEMODE_RB",
+	jl: "SENPI_CODEMODE_JL",
+} as const;
+
+export function resolveEnabledLanguages(
+	settings: CodemodeSettings,
+	env: Environment = process.env,
+): CodemodeSettings["languages"] {
+	return {
+		py: resolveLanguage(settings.languages.py, env[languageEnvironmentFlags.py]),
+		js: resolveLanguage(settings.languages.js, env[languageEnvironmentFlags.js]),
+		rb: resolveLanguage(settings.languages.rb, env[languageEnvironmentFlags.rb]),
+		jl: resolveLanguage(settings.languages.jl, env[languageEnvironmentFlags.jl]),
+	};
+}
+
+/** Environment override wins over the settings file; a non-positive or malformed value is ignored. */
+export function resolveHardLimitSeconds(settings: CodemodeSettings, env: Environment = process.env): number {
+	return positiveSecondsOverride(env[HARD_LIMIT_ENVIRONMENT_FLAG]) ?? settings.hardLimitSeconds;
+}
+
+/** Environment override wins over the settings file; a non-positive or malformed value is ignored. */
+export function resolveForegroundWindowSeconds(settings: CodemodeSettings, env: Environment = process.env): number {
+	return positiveSecondsOverride(env[FOREGROUND_WINDOW_ENVIRONMENT_FLAG]) ?? settings.foregroundWindowSeconds;
+}
+
+/** Environment override wins over the settings file; a non-positive or malformed value is ignored. */
+export function resolveRunBudgetSeconds(settings: CodemodeSettings, env: Environment = process.env): number {
+	return positiveSecondsOverride(env[RUN_BUDGET_ENVIRONMENT_FLAG]) ?? settings.runBudgetSeconds;
+}
+
+/** Uses the same positive-integer environment parsing as the run budget. */
+export function resolveMaxDetachedCells(settings: CodemodeSettings, env: Environment = process.env): number {
+	return (
+		positiveSecondsOverride(env[MAX_DETACHED_CELLS_ENVIRONMENT_FLAG]) ??
+		settings.maxDetachedCells ??
+		DEFAULT_MAX_DETACHED_CELLS
+	);
+}
+
+function positiveSecondsOverride(value: string | undefined): number | undefined {
+	if (value === undefined) return undefined;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function resolveLanguage(fileSetting: boolean, environmentValue: string | undefined): boolean {
+	if (environmentValue === undefined) return fileSetting;
+	switch (environmentValue.trim().toLowerCase()) {
+		case "0":
+		case "false":
+			return false;
+		case "1":
+		case "true":
+			return true;
+		default:
+			return fileSetting;
+	}
+}

package/src/config/settings.ts

@@ -4,7 +4,10 @@ import { join } from "node:path";
 import type { Static } from "typebox";
 import { Type } from "typebox";
 import { Check } from "typebox/value";
+import { type CodemodeFeatureSettings, featureSettingsProperties, pickFeatureSettings } from "./feature-settings.ts";
 import { type CodemodeMemorySettings, memorySettingsSchema, validatedMemorySettings } from "./memory-settings.ts";
+import { DEFAULT_MAX_DETACHED_CELLS } from "./settings-constants.ts";
+import { withoutUnknownTopLevelKeys } from "./unknown-settings.ts";
 
 export const codemodeSettingsSchema = Type.Object(
 	{
@@ -15,6 +18,7 @@ export const codemodeSettingsSchema = Type.Object(
 					js: Type.Optional(Type.Boolean()),
 					rb: Type.Optional(Type.Boolean()),
 					jl: Type.Optional(Type.Boolean()),
+					pyInterpreter: Type.Optional(Type.String({ minLength: 1 })),
 				},
 				{ additionalProperties: false },
 			),
@@ -45,6 +49,7 @@ export const codemodeSettingsSchema = Type.Object(
 		),
 		statusEvents: Type.Optional(Type.Boolean()),
 		memory: Type.Optional(memorySettingsSchema),
+		...featureSettingsProperties,
 	},
 	{ additionalProperties: false },
 );
@@ -61,12 +66,14 @@ export interface CodemodeOutputSink {
 	readonly maxColumns: number;
 }
 
-export interface CodemodeSettings {
+export interface CodemodeSettings extends CodemodeFeatureSettings {
 	readonly languages: {
 		readonly py: boolean;
 		readonly js: boolean;
 		readonly rb: boolean;
 		readonly jl: boolean;
+		/** Explicit Python interpreter; unset keeps today's PATH detection. */
+		readonly pyInterpreter?: string;
 	};
 	/** Idle time an interactive call blocks the turn before the cell detaches; capped by the foreground window. */
 	readonly cellTimeoutSeconds: number;
@@ -118,8 +125,6 @@ export interface LoadedCodemodeSettings {
  */
 export const DEFAULT_HARD_LIMIT_SECONDS = 1800;
 
-export const HARD_LIMIT_ENVIRONMENT_FLAG = "SENPI_CODEMODE_HARD_LIMIT_SECONDS";
-
 /**
  * Bash parity: `terminal/tools/foreground-window.ts` auto-detaches a still-running bash command to a
  * background session at 60s regardless of its `timeout` kill deadline. An eval cell gets the same
@@ -128,8 +133,6 @@ export const HARD_LIMIT_ENVIRONMENT_FLAG = "SENPI_CODEMODE_HARD_LIMIT_SECONDS";
  */
 export const DEFAULT_FOREGROUND_WINDOW_SECONDS = 60;
 
-export const FOREGROUND_WINDOW_ENVIRONMENT_FLAG = "SENPI_CODEMODE_FOREGROUND_SECONDS";
-
 /**
  * One language kernel runs one cell at a time and a killed JavaScript cell that cannot settle
  * cooperatively restarts its worker, so a runaway cell costs far more than a runaway bash command:
@@ -137,11 +140,6 @@ export const FOREGROUND_WINDOW_ENVIRONMENT_FLAG = "SENPI_CODEMODE_FOREGROUND_SEC
  */
 export const DEFAULT_RUN_BUDGET_SECONDS = 300;
 
-export const DEFAULT_MAX_DETACHED_CELLS = 15;
-
-export const RUN_BUDGET_ENVIRONMENT_FLAG = "SENPI_CODEMODE_RUN_BUDGET_SECONDS";
-export const MAX_DETACHED_CELLS_ENVIRONMENT_FLAG = "SENPI_CODEMODE_MAX_DETACHED_CELLS";
-
 // OMP settings-schema.ts:3211-3299 has language/path settings only; eval.ts:427
 // defaults timeout to 30s, and codemode pins concurrency-bridge.ts:30 width to 4.
 export const defaultCodemodeSettings: ResolvedCodemodeSettings = {
@@ -169,15 +167,6 @@ export const defaultCodemodeSettings: ResolvedCodemodeSettings = {
 	memory: validatedMemorySettings(undefined).settings,
 };
 
-const languageEnvironmentFlags = {
-	py: "SENPI_CODEMODE_PY",
-	js: "SENPI_CODEMODE_JS",
-	rb: "SENPI_CODEMODE_RB",
-	jl: "SENPI_CODEMODE_JL",
-} as const;
-
-export type Environment = Readonly<Record<string, string | undefined>>;
-
 export async function loadCodemodeSettings(options: LoadCodemodeSettingsOptions = {}): Promise<LoadedCodemodeSettings> {
 	const cwd = options.cwd ?? process.cwd();
 	const homeDir = options.homeDir ?? homedir();
@@ -193,48 +182,6 @@ export async function loadCodemodeSettings(options: LoadCodemodeSettingsOptions
 	return { settings: defaultCodemodeSettings, source: null, warnings: [] };
 }
 
-export function resolveEnabledLanguages(
-	settings: CodemodeSettings,
-	env: Environment = process.env,
-): CodemodeSettings["languages"] {
-	return {
-		py: resolveLanguage(settings.languages.py, env[languageEnvironmentFlags.py]),
-		js: resolveLanguage(settings.languages.js, env[languageEnvironmentFlags.js]),
-		rb: resolveLanguage(settings.languages.rb, env[languageEnvironmentFlags.rb]),
-		jl: resolveLanguage(settings.languages.jl, env[languageEnvironmentFlags.jl]),
-	};
-}
-
-/** Environment override wins over the settings file; a non-positive or malformed value is ignored. */
-export function resolveHardLimitSeconds(settings: CodemodeSettings, env: Environment = process.env): number {
-	return positiveSecondsOverride(env[HARD_LIMIT_ENVIRONMENT_FLAG]) ?? settings.hardLimitSeconds;
-}
-
-/** Environment override wins over the settings file; a non-positive or malformed value is ignored. */
-export function resolveForegroundWindowSeconds(settings: CodemodeSettings, env: Environment = process.env): number {
-	return positiveSecondsOverride(env[FOREGROUND_WINDOW_ENVIRONMENT_FLAG]) ?? settings.foregroundWindowSeconds;
-}
-
-/** Environment override wins over the settings file; a non-positive or malformed value is ignored. */
-export function resolveRunBudgetSeconds(settings: CodemodeSettings, env: Environment = process.env): number {
-	return positiveSecondsOverride(env[RUN_BUDGET_ENVIRONMENT_FLAG]) ?? settings.runBudgetSeconds;
-}
-
-/** Uses the same positive-integer environment parsing as the run budget. */
-export function resolveMaxDetachedCells(settings: CodemodeSettings, env: Environment = process.env): number {
-	return (
-		positiveSecondsOverride(env[MAX_DETACHED_CELLS_ENVIRONMENT_FLAG]) ??
-		settings.maxDetachedCells ??
-		DEFAULT_MAX_DETACHED_CELLS
-	);
-}
-
-function positiveSecondsOverride(value: string | undefined): number | undefined {
-	if (value === undefined) return undefined;
-	const parsed = Number.parseInt(value, 10);
-	return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
-}
-
 async function loadSettingsFile(path: string): Promise<LoadedCodemodeSettings> {
 	const raw = await readFile(path, "utf8");
 	let parsed: unknown;
@@ -249,15 +196,21 @@ async function loadSettingsFile(path: string): Promise<LoadedCodemodeSettings> {
 		};
 	}
 
-	if (!Check(codemodeSettingsSchema, parsed)) {
+	const known = withoutUnknownTopLevelKeys(parsed, new Set(Object.keys(codemodeSettingsSchema.properties)), path);
+	const candidate = known.value;
+	if (!Check(codemodeSettingsSchema, candidate)) {
 		return {
 			settings: defaultCodemodeSettings,
 			source: path,
-			warnings: [`Invalid codemode settings in ${path}. Falling back to codemode defaults.`],
+			warnings: [...known.warnings, `Invalid codemode settings in ${path}. Falling back to codemode defaults.`],
 		};
 	}
 
-	return { settings: mergeSettings(parsed), source: path, warnings: validatedMemorySettings(parsed.memory).warnings };
+	return {
+		settings: mergeSettings(candidate),
+		source: path,
+		warnings: [...known.warnings, ...validatedMemorySettings(candidate.memory).warnings],
+	};
 }
 
 function mergeSettings(input: CodemodeSettingsInput): ResolvedCodemodeSettings {
@@ -267,6 +220,7 @@ function mergeSettings(input: CodemodeSettingsInput): ResolvedCodemodeSettings {
 			js: input.languages?.js ?? defaultCodemodeSettings.languages.js,
 			rb: input.languages?.rb ?? defaultCodemodeSettings.languages.rb,
 			jl: input.languages?.jl ?? defaultCodemodeSettings.languages.jl,
+			...(input.languages?.pyInterpreter === undefined ? {} : { pyInterpreter: input.languages.pyInterpreter }),
 		},
 		cellTimeoutSeconds: input.cellTimeoutSeconds ?? defaultCodemodeSettings.cellTimeoutSeconds,
 		foregroundWindowSeconds: input.foregroundWindowSeconds ?? defaultCodemodeSettings.foregroundWindowSeconds,
@@ -284,23 +238,10 @@ function mergeSettings(input: CodemodeSettingsInput): ResolvedCodemodeSettings {
 		},
 		statusEvents: input.statusEvents ?? defaultCodemodeSettings.statusEvents,
 		memory: validatedMemorySettings(input.memory).settings,
+		...pickFeatureSettings(input),
 	};
 }
 
-function resolveLanguage(fileSetting: boolean, environmentValue: string | undefined): boolean {
-	if (environmentValue === undefined) return fileSetting;
-	switch (environmentValue.trim().toLowerCase()) {
-		case "0":
-		case "false":
-			return false;
-		case "1":
-		case "true":
-			return true;
-		default:
-			return fileSetting;
-	}
-}
-
 async function fileExists(path: string): Promise<boolean> {
 	try {
 		await access(path);
@@ -309,3 +250,19 @@ async function fileExists(path: string): Promise<boolean> {
 		return false;
 	}
 }
+
+export {
+	DEFAULT_MAX_DETACHED_CELLS,
+	type Environment,
+	FOREGROUND_WINDOW_ENVIRONMENT_FLAG,
+	HARD_LIMIT_ENVIRONMENT_FLAG,
+	MAX_DETACHED_CELLS_ENVIRONMENT_FLAG,
+	RUN_BUDGET_ENVIRONMENT_FLAG,
+} from "./settings-constants.ts";
+export {
+	resolveEnabledLanguages,
+	resolveForegroundWindowSeconds,
+	resolveHardLimitSeconds,
+	resolveMaxDetachedCells,
+	resolveRunBudgetSeconds,
+} from "./settings-overrides.ts";

package/src/config/unknown-settings.ts

@@ -0,0 +1,19 @@
+/**
+ * A settings file written for a newer senpi may name keys this version does not know: they are dropped with
+ * one warning each instead of failing the whole file, so the user's other settings still apply. Only the
+ * top level is lenient; the known nested objects keep their strict schemas.
+ */
+export function withoutUnknownTopLevelKeys(
+	parsed: unknown,
+	known: ReadonlySet<string>,
+	path: string,
+): { readonly value: unknown; readonly warnings: string[] } {
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return { value: parsed, warnings: [] };
+	const kept: Record<string, unknown> = {};
+	const warnings: string[] = [];
+	for (const [key, value] of Object.entries(parsed)) {
+		if (known.has(key)) kept[key] = value;
+		else warnings.push(`Unknown codemode setting "${key}" in ${path} is ignored; the other settings still apply.`);
+	}
+	return { value: kept, warnings };
+}

package/src/extension/bridge-dispatch.ts

@@ -0,0 +1,41 @@
+import type { ExtensionContext } from "@code-yeongyu/senpi";
+import type { BridgeHttpCompletionRequest } from "../bridge/http-server.ts";
+import { startCompletionHandle, wantsCompletionHandle } from "../completion/handle.ts";
+import type { CompletionRequest } from "../completion/handler.ts";
+import { resolveHardLimitSeconds } from "../config/settings.ts";
+import type { CreateCodemodeSessionManagerOptions } from "./session-manager-contract.ts";
+
+export interface BridgeDispatchContext {
+	/** The context of the cell that last reached the manager; the handle host and completion owner are read from it. */
+	readonly context: ExtensionContext | undefined;
+	readonly contextFor: (signal: AbortSignal) => ExtensionContext;
+	readonly requireContext: () => ExtensionContext;
+}
+
+/**
+ * `completion(prompt, handle=True)` from a subprocess kernel: the handle lives in the session registry and is
+ * bounded by the hard limit measured from this request, the tightest bound the bridge knows for its cell.
+ */
+export async function dispatchBridgeCompletion(
+	options: CreateCodemodeSessionManagerOptions,
+	request: BridgeHttpCompletionRequest,
+	dispatch: BridgeDispatchContext,
+): Promise<unknown> {
+	const completion: CompletionRequest = { prompt: request.prompt, opts: request.opts };
+	if (!wantsCompletionHandle(request.opts)) {
+		return await options.complete(completion, dispatch.contextFor(request.signal));
+	}
+	const registry = options.handles;
+	if (registry === undefined) {
+		throw Object.assign(new Error("eval_wait_unavailable: completion handles are not available in this session"), {
+			code: "eval_wait_unavailable",
+		});
+	}
+	return startCompletionHandle({
+		registry,
+		request: completion,
+		complete: options.complete,
+		ctx: dispatch.requireContext(),
+		deadlineMs: Date.now() + resolveHardLimitSeconds(options.settings) * 1_000,
+	});
+}

package/src/extension/bridge-tool-call.ts

@@ -0,0 +1,41 @@
+import type { EvalHandleHost } from "@code-yeongyu/senpi";
+import { isReservedToolName, runReservedTool } from "../bridges/reserved-dispatch.ts";
+import { defaultCodemodeSettings } from "../config/settings.ts";
+import { marshalToolResult } from "../tool/image.ts";
+import type { CreateCodemodeSessionManagerOptions } from "./session-manager-contract.ts";
+
+export interface BridgeToolCallRequest {
+	readonly toolName: string;
+	readonly args: unknown;
+	readonly callId: string;
+	readonly signal: AbortSignal;
+}
+
+// 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.
+export async function routeBridgeToolCall(
+	options: Pick<CreateCodemodeSessionManagerOptions, "executeTool" | "listTools" | "settings" | "handles">,
+	request: BridgeToolCallRequest,
+	evalHandleHost?: EvalHandleHost,
+): Promise<unknown> {
+	if (!isReservedToolName(request.toolName)) {
+		return marshalToolResult(await options.executeTool(request.toolName, request.args, { signal: request.signal }));
+	}
+	const taskTools = options.settings.taskTools ?? defaultCodemodeSettings.taskTools;
+	return await runReservedTool(request.toolName, {
+		callId: request.callId,
+		args: request.args,
+		executeTool: options.executeTool,
+		taskToolName: taskTools.task,
+		taskOutputToolName: taskTools.output,
+		listTools: options.listTools,
+		signal: request.signal,
+		emitStatus: () => {},
+		marshalToolResult,
+		...(options.handles === undefined ? {} : { handles: options.handles }),
+		...(evalHandleHost === undefined ? {} : { evalHandleHost }),
+	});
+}

package/src/extension/host-facts.ts

@@ -0,0 +1,18 @@
+import * as os from "node:os";
+import { jsRuntimeLabel } from "./runtime-info.ts";
+
+/** The one-line host description the eval prompt shows (platform, CPU, cores, JS runtime). */
+export function hostLine(): string {
+	const cpu = os.cpus()[0]?.model?.trim();
+	return [`${os.platform()} ${os.arch()}`, cpu, `${os.availableParallelism()} cores`, jsRuntimeLabel()]
+		.filter((part): part is string => !!part)
+		.join(" \u00b7 ");
+}
+
+/** The model id carried by a `model_select` event, when it has one. */
+export function modelIdFrom(event: unknown): string | undefined {
+	if (typeof event !== "object" || event === null || !("model" in event)) return undefined;
+	const model = event.model;
+	if (typeof model !== "object" || model === null || !("id" in model)) return undefined;
+	return typeof model.id === "string" ? model.id : undefined;
+}