@code-yeongyu/senpi-codemode 2026.9.5 → 2026.9.7

package/src/tool/detached-cell-manager.ts

@@ -1,6 +1,12 @@
 import type { AgentToolResult } from "@code-yeongyu/senpi";
 import { DEFAULT_HARD_LIMIT_SECONDS } from "../config/settings.ts";
-import { SENPI_CODEMODE_WAKE_SOURCE, type WakeSourceState } from "../extension/wake-source-state.ts";
+import type { WakeSourceState } from "../extension/wake-source-state.ts";
+import type {
+	EvalDetachedCellManagerOptions,
+	EvalDetachedCellSnapshot,
+	EvalDetachedCellState,
+	EvalDetachedCellStatusEntry,
+} from "./detached-cell-contract.ts";
 import { detachedNotificationSpillPath } from "./detached-cell-notification.ts";
 import { currentDetachedResult, detachedErrorResult, snapshotDetachedCell } from "./detached-cell-snapshot.ts";
 import {
@@ -8,10 +14,18 @@ import {
 	allowsDetachedCellTransition,
 	detachedCellIsActive,
 } from "./detached-cell-state.ts";
+import { detachedStatusEntries, detachedWakeSourceState } from "./detached-cell-status.ts";
 import { DetachedNotificationQueue } from "./detached-notification-queue.ts";
 import type { EvalKernel, EvalLanguage, EvalToolDetails, EvalToolInput } from "./types.ts";
 
-export type EvalDetachedCellState = "running" | "detached" | "completed" | "failed" | "cancelled";
+export type {
+	EvalDetachedCellManagerOptions,
+	EvalDetachedCellNotification,
+	EvalDetachedCellNotifier,
+	EvalDetachedCellSnapshot,
+	EvalDetachedCellState,
+	EvalDetachedCellStatusEntry,
+} from "./detached-cell-contract.ts";
 
 type LiveResultProvider = () => AgentToolResult<EvalToolDetails>;
 
@@ -26,6 +40,9 @@ type ManagedCell = {
 	wasDetached: boolean;
 	kernel: EvalKernel | undefined;
 	stateRetained: boolean | undefined;
+	interruptNote: string | undefined;
+	/** Holds the completion notification until the interrupt has reported whether kernel state survived. */
+	interruptOutcome: PromiseWithResolvers<void> | undefined;
 	liveResult: LiveResultProvider | undefined;
 	terminalResult: AgentToolResult<EvalToolDetails> | undefined;
 	notificationQueued: boolean;
@@ -35,44 +52,6 @@ type ManagedCell = {
 	onHardLimit: ((error: Error) => void) | undefined;
 };
 
-export interface EvalDetachedCellSnapshot {
-	readonly cellId: string;
-	readonly language: EvalLanguage;
-	readonly state: EvalDetachedCellState;
-	readonly outputTail: string;
-	readonly result: AgentToolResult<EvalToolDetails>;
-	readonly stateRetained: boolean | undefined;
-	/** Set only when the wall-clock kill deadline ended this cell. */
-	readonly hardLimitSeconds?: number;
-}
-
-export interface EvalDetachedCellNotification {
-	readonly cellId: string;
-	readonly content: string;
-}
-
-export interface EvalDetachedCellNotifier {
-	notify(cells: readonly EvalDetachedCellNotification[]): void;
-}
-
-export interface EvalDetachedCellStatusEntry {
-	readonly cellId: string;
-	readonly language: EvalLanguage;
-	readonly summary?: string;
-	readonly startedAtMs: number;
-}
-
-export interface EvalDetachedCellManagerOptions {
-	readonly artifactsDir?: string;
-	readonly notifier?: EvalDetachedCellNotifier;
-	/** Wall-clock kill deadline in seconds; defaults to the bash-parity 1800s. */
-	readonly hardLimitSeconds?: number;
-	readonly onStatusChange?: (entries: readonly EvalDetachedCellStatusEntry[]) => void;
-	/** Receives a full per-source liveness snapshot on every detached-cell transition; used by the goal builtin. */
-	readonly onWakeSourceState?: (state: WakeSourceState) => void;
-	readonly now?: () => number;
-}
-
 export function hardLimitError(cellId: string, hardLimitSeconds: number): Error {
 	const error = new Error(`Eval cell ${cellId} was killed at the ${hardLimitSeconds}s hard limit.`);
 	error.name = "TimeoutError";
@@ -114,6 +93,8 @@ export class EvalDetachedCellManager {
 			wasDetached: false,
 			kernel: undefined,
 			stateRetained: undefined,
+			interruptNote: undefined,
+			interruptOutcome: undefined,
 			liveResult: undefined,
 			terminalResult: undefined,
 			notificationQueued: false,
@@ -162,13 +143,7 @@ export class EvalDetachedCellManager {
 
 	async stop(cellId: string, reason = "Stopped detached eval cell"): Promise<EvalDetachedCellSnapshot> {
 		const cell = this.#get(cellId);
-		if (cell.state === "detached") {
-			const claimed = this.#settle(cell, "cancelled", currentDetachedResult(cell));
-			if (claimed && cell.kernel !== undefined) {
-				const handle = await cell.kernel.interrupt(reason);
-				cell.stateRetained = await handle.stateRetained;
-			}
-		}
+		if (cell.state === "detached") await this.#cancel(cell, reason);
 		return this.#snapshot(cell);
 	}
 
@@ -221,7 +196,10 @@ export class EvalDetachedCellManager {
 			if (!cell.notificationQueued) {
 				cell.notificationQueued = true;
 				this.#notificationQueue.enqueue({
-					snapshot: () => this.#snapshot(cell),
+					snapshot: async () => {
+						await cell.interruptOutcome?.promise;
+						return this.#snapshot(cell);
+					},
 					spillPath: cell.spillPath,
 				});
 			}
@@ -250,40 +228,34 @@ export class EvalDetachedCellManager {
 		const foreground = cell.state === "running" && cell.onHardLimit !== undefined;
 		cell.hardLimited = true;
 		const error = hardLimitError(cell.cellId, cell.hardLimitSeconds);
-		if (!this.#settle(cell, "cancelled", currentDetachedResult(cell))) return;
 		if (foreground) {
-			cell.onHardLimit?.(error);
+			if (this.#settle(cell, "cancelled", currentDetachedResult(cell))) cell.onHardLimit?.(error);
 			return;
 		}
-		if (cell.kernel === undefined) return;
-		const handle = await cell.kernel.interrupt(error.message);
-		cell.stateRetained = await handle.stateRetained;
+		await this.#cancel(cell, error.message);
+	}
+
+	async #cancel(cell: ManagedCell, reason: string): Promise<void> {
+		const outcome = Promise.withResolvers<void>();
+		cell.interruptOutcome = outcome;
+		try {
+			if (!this.#settle(cell, "cancelled", currentDetachedResult(cell)) || cell.kernel === undefined) return;
+			const handle = await cell.kernel.interrupt(reason);
+			cell.interruptNote = handle.note;
+			cell.stateRetained = await handle.stateRetained;
+		} finally {
+			outcome.resolve();
+		}
 	}
 
 	#emitStatus(): void {
 		const liveCells = [...this.#detachedByLanguage.values()];
-		this.#onStatusChange?.(
-			liveCells.map((cell) => ({
-				cellId: cell.cellId,
-				language: cell.input.language,
-				startedAtMs: cell.startedAtMs,
-				...(cell.input.summary === undefined ? {} : { summary: cell.input.summary }),
-			})),
-		);
+		this.#onStatusChange?.(detachedStatusEntries(liveCells));
 		this.#emitWakeSourceState(liveCells);
 	}
 
 	#emitWakeSourceState(liveCells: readonly ManagedCell[]): void {
-		this.#onWakeSourceState?.({
-			source: SENPI_CODEMODE_WAKE_SOURCE,
-			activeCount: liveCells.length,
-			items: liveCells.map((cell) => ({
-				id: cell.cellId,
-				description:
-					cell.input.summary === undefined || cell.input.summary.length === 0 ? cell.cellId : cell.input.summary,
-				startedAtMs: cell.startedAtMs,
-			})),
-		});
+		this.#onWakeSourceState?.(detachedWakeSourceState(liveCells));
 	}
 
 	#snapshot(cell: ManagedCell): EvalDetachedCellSnapshot {

package/src/tool/detached-cell-notification.ts

@@ -1,6 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { EvalDetachedCellNotification, EvalDetachedCellSnapshot } from "./detached-cell-manager.ts";
+import { interruptionStateNote, unknownInterruptionStateNote } from "./interrupt-note.ts";
 
 const NOTIFICATION_TAIL_BYTES = 512;
 
@@ -74,11 +75,9 @@ function outcomeOf(cell: EvalDetachedCellSnapshot): string {
 }
 
 function stateNoteOf(cell: EvalDetachedCellSnapshot): string {
-	if (cell.state === "cancelled" && cell.language === "js")
-		return "JavaScript worker was restarted; VM state was lost.";
-	if (cell.state === "cancelled" && cell.language === "py")
-		return "Python kernel was interrupted; its existing variables are preserved.";
-	return "Kernel state updated - variables are available to the next eval cell.";
+	if (cell.state !== "cancelled") return "Kernel state updated - variables are available to the next eval cell.";
+	const note = interruptionStateNote(cell.language, cell.stateRetained) ?? unknownInterruptionStateNote(cell.language);
+	return cell.interruptNote === undefined ? note : `${note} ${cell.interruptNote.trim()}`;
 }
 
 function safeCellId(cellId: string): string {

package/src/tool/detached-cell-snapshot.ts

@@ -10,6 +10,7 @@ export interface DetachedCellResultSource {
 	state: EvalDetachedCellState;
 	kernel: EvalKernel | undefined;
 	stateRetained: boolean | undefined;
+	interruptNote?: string | undefined;
 	liveResult: (() => AgentToolResult<EvalToolDetails>) | undefined;
 	terminalResult: AgentToolResult<EvalToolDetails> | undefined;
 	hardLimited?: boolean;
@@ -26,6 +27,7 @@ export function snapshotDetachedCell(cell: DetachedCellResultSource, nowMs: numb
 		outputTail: detachedOutputTail(result),
 		result,
 		stateRetained: cell.stateRetained,
+		...(cell.interruptNote === undefined ? {} : { interruptNote: cell.interruptNote }),
 		...(cell.hardLimited === true && cell.hardLimitSeconds !== undefined
 			? { hardLimitSeconds: cell.hardLimitSeconds }
 			: {}),

package/src/tool/detached-cell-status.ts

@@ -0,0 +1,30 @@
+import { SENPI_CODEMODE_WAKE_SOURCE, type WakeSourceState } from "../extension/wake-source-state.ts";
+import type { EvalDetachedCellStatusEntry } from "./detached-cell-manager.ts";
+
+export interface LiveDetachedCell {
+	readonly cellId: string;
+	readonly startedAtMs: number;
+	readonly input: { readonly language: EvalDetachedCellStatusEntry["language"]; readonly summary?: string };
+}
+
+export function detachedStatusEntries(liveCells: readonly LiveDetachedCell[]): EvalDetachedCellStatusEntry[] {
+	return liveCells.map((cell) => ({
+		cellId: cell.cellId,
+		language: cell.input.language,
+		startedAtMs: cell.startedAtMs,
+		...(cell.input.summary === undefined ? {} : { summary: cell.input.summary }),
+	}));
+}
+
+export function detachedWakeSourceState(liveCells: readonly LiveDetachedCell[]): WakeSourceState {
+	return {
+		source: SENPI_CODEMODE_WAKE_SOURCE,
+		activeCount: liveCells.length,
+		items: liveCells.map((cell) => ({
+			id: cell.cellId,
+			description:
+				cell.input.summary === undefined || cell.input.summary.length === 0 ? cell.cellId : cell.input.summary,
+			startedAtMs: cell.startedAtMs,
+		})),
+	};
+}

package/src/tool/detached-eval-result.ts

@@ -40,6 +40,7 @@ export function createDetachedControlResult(snapshot: EvalDetachedCellSnapshot):
 		`Eval cell ${snapshot.cellId} (${snapshot.language}) is ${snapshot.state}.`,
 		output.length === 0 ? "(no buffered output)" : output,
 		...(terminationNote === undefined ? [] : [terminationNote]),
+		...(snapshot.interruptNote === undefined ? [] : [snapshot.interruptNote.trim()]),
 	].join("\n");
 	return {
 		content: [{ type: "text", text }, ...snapshot.result.content.filter((part) => part.type === "image")],

package/src/tool/detached-notification-queue.ts

@@ -2,7 +2,7 @@ import type { EvalDetachedCellNotifier, EvalDetachedCellSnapshot } from "./detac
 import { buildDetachedCellNotification } from "./detached-cell-notification.ts";
 
 export interface PendingDetachedNotification {
-	readonly snapshot: () => EvalDetachedCellSnapshot;
+	readonly snapshot: () => EvalDetachedCellSnapshot | Promise<EvalDetachedCellSnapshot>;
 	readonly spillPath: string | undefined;
 }
 
@@ -30,7 +30,7 @@ export class DetachedNotificationQueue {
 		const flush = Promise.resolve().then(async () => {
 			const pending = this.#pending.splice(0);
 			const notifications = await Promise.all(
-				pending.map(async (item) => await buildDetachedCellNotification(item.snapshot(), item.spillPath)),
+				pending.map(async (item) => await buildDetachedCellNotification(await item.snapshot(), item.spillPath)),
 			);
 			this.#notifier?.notify(notifications);
 		});

package/src/tool/interrupt-note.ts

@@ -1,4 +1,4 @@
-import type { EvalLanguage } from "./types.ts";
+import type { EvalLanguage, KernelInterruptHandle } from "./types.ts";
 
 const TIMEOUT_STATE_GRACE_MS = 5_500;
 
@@ -13,30 +13,40 @@ function fallbackTimeoutMessage(base: string): string {
  */
 export async function describeTimeoutState(
 	error: Error,
-	execution: { readonly interruptStateRetained: Promise<boolean> | undefined },
+	execution: { readonly interruptHandle: Promise<KernelInterruptHandle> | undefined },
 ): Promise<Error> {
-	const outcome = execution.interruptStateRetained;
-	if (outcome === undefined) {
+	const pending = execution.interruptHandle;
+	if (pending === undefined) {
 		error.message = fallbackTimeoutMessage(error.message);
 		return error;
 	}
-	let timer: ReturnType<typeof setTimeout> | undefined;
-	const retained = await Promise.race([
-		outcome,
-		new Promise<boolean | undefined>((resolve) => {
-			timer = setTimeout(() => resolve(undefined), TIMEOUT_STATE_GRACE_MS);
-		}),
-	]).finally(() => {
-		if (timer !== undefined) clearTimeout(timer);
-	});
-	if (retained === undefined) error.message = fallbackTimeoutMessage(error.message);
-	else if (retained)
+	const outcome = await withinGrace(
+		pending.then(async (handle) => ({ retained: await handle.stateRetained, note: handle.note })),
+		TIMEOUT_STATE_GRACE_MS,
+	);
+	if (outcome === undefined) error.message = fallbackTimeoutMessage(error.message);
+	else if (outcome.retained)
 		error.message = `${error.message} The kernel remains running; its existing variables are preserved.`;
 	else
 		error.message = `${error.message} The kernel was unresponsive and restarted; variables from earlier cells are lost.`;
+	if (outcome?.note !== undefined) error.message = `${error.message} ${outcome.note.trim()}`;
 	return error;
 }
 
+async function withinGrace<T>(operation: Promise<T>, graceMs: number): Promise<T | undefined> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		return await Promise.race([
+			operation,
+			new Promise<undefined>((resolve) => {
+				timer = setTimeout(() => resolve(undefined), graceMs);
+			}),
+		]);
+	} finally {
+		if (timer !== undefined) clearTimeout(timer);
+	}
+}
+
 const LANGUAGE_LABEL: Record<EvalLanguage, string> = {
 	py: "Python kernel",
 	js: "JavaScript worker",
@@ -56,3 +66,7 @@ export function interruptionStateNote(language: EvalLanguage, stateRetained: boo
 	if (stateRetained) return `${label} was interrupted and remains running; its existing variables are preserved.`;
 	return `${label} was unresponsive to interrupt and was restarted; variables from earlier cells are lost.`;
 }
+
+export function unknownInterruptionStateNote(language: EvalLanguage): string {
+	return `${LANGUAGE_LABEL[language]} interrupt outcome is unknown; re-establish any variables the next cell needs.`;
+}

package/src/tool/types.ts

@@ -112,6 +112,8 @@ export interface EvalKernelRunInput {
 export interface KernelInterruptHandle {
 	/** Resolves once the kernel knows whether user state survived the interrupt. */
 	readonly stateRetained: Promise<boolean>;
+	/** Extra outcome detail worth showing the model, e.g. that a blocked worker was abandoned. */
+	readonly note?: string;
 }
 
 export interface EvalKernel {