@code-yeongyu/senpi-codemode 2026.7.31 → 2026.8.3

package/src/tool/cell-runtime.ts

@@ -0,0 +1,157 @@
+import type { AgentToolResult, AgentToolUpdateCallback, ExtensionContext } from "@code-yeongyu/senpi";
+import type { KernelToHostMessage } from "../bridge/protocol.ts";
+import { type EvalImageResizer, EvalOutputCollector, type EvalOutputResult } from "./image.ts";
+import type { EvalStatusEvent, EvalToolDetails, EvalToolInput } from "./types.ts";
+
+type KernelResult = Extract<KernelToHostMessage, { type: "result" }>;
+type DisplayMessage = Extract<KernelToHostMessage, { type: "display" }>;
+type ToolCall = EvalToolDetails["toolCalls"] extends readonly (infer Item)[] ? Item : never;
+
+export interface CellState {
+	readonly input: EvalToolInput;
+	readonly signal: AbortSignal;
+	readonly onUpdate: AgentToolUpdateCallback<EvalToolDetails> | undefined;
+	readonly toolCalls: ToolCall[];
+	readonly pendingBridgeCalls: Promise<void>[];
+	readonly statusEvents: EvalStatusEvent[];
+	active: boolean;
+	output: string;
+	phase: string | undefined;
+	durationMs: number;
+	status: "pending" | "running" | "complete" | "error";
+}
+
+export interface CellResultBuilderOptions {
+	readonly artifactPath?: string;
+	readonly headBytes: number;
+	readonly imageResizer?: EvalImageResizer;
+	readonly maxColumns: number;
+	readonly model: ExtensionContext["model"];
+	readonly state: CellState;
+}
+
+export class CellResultBuilder {
+	readonly #output: EvalOutputCollector;
+	readonly #state: CellState;
+
+	constructor(options: CellResultBuilderOptions) {
+		this.#state = options.state;
+		this.#output = new EvalOutputCollector({
+			headBytes: options.headBytes,
+			maxColumns: options.maxColumns,
+			model: options.model,
+			...(options.artifactPath === undefined ? {} : { artifactPath: options.artifactPath }),
+			...(options.imageResizer === undefined ? {} : { imageResizer: options.imageResizer }),
+			onChunk: (_aggregate, cell) => {
+				options.state.output = cell;
+				this.emitUpdate(false);
+			},
+		});
+		options.state.status = "running";
+		this.emitUpdate(false);
+	}
+
+	push(text: string): void {
+		this.#output.push(text);
+	}
+
+	display(message: DisplayMessage): void {
+		this.#output.display(message);
+	}
+
+	setPhase(title: string): void {
+		this.#state.phase = title;
+		this.emitUpdate(false);
+	}
+
+	async finalize(result: KernelResult): Promise<AgentToolResult<EvalToolDetails>> {
+		this.#state.durationMs = result.durationMs;
+		if (result.ok) {
+			if (result.valueRepr) this.#output.push(`${result.valueRepr}\n`);
+			this.#state.status = "complete";
+		} else {
+			this.#output.push(`${result.error.message}\n`);
+			this.#state.status = "error";
+		}
+		return await this.#finish(!result.ok);
+	}
+
+	async finalizeCancellation(error: Error): Promise<AgentToolResult<EvalToolDetails>> {
+		this.#output.push(`${error.message}\n`);
+		this.#state.status = "error";
+		return await this.#finish(true);
+	}
+
+	async flushOutput(): Promise<void> {
+		await this.#output.flush();
+	}
+
+	liveResult(): AgentToolResult<EvalToolDetails> {
+		return {
+			content: [{ type: "text", text: this.#liveUpdateText() }],
+			details: this.#details(undefined, this.#state.status === "error"),
+		};
+	}
+
+	emitUpdate(isError: boolean): void {
+		if (!this.#state.active) return;
+		this.#state.onUpdate?.({
+			content: [{ type: "text", text: this.#liveUpdateText() }],
+			details: this.#details(undefined, isError),
+		});
+	}
+
+	async #finish(isError: boolean): Promise<AgentToolResult<EvalToolDetails>> {
+		const output = await this.#output.finish();
+		this.#state.output = output.output;
+		const details = this.#details(output, isError);
+		this.emitUpdate(isError);
+		const text =
+			output.output ||
+			(output.images.length > 0
+				? `(displayed ${output.images.length} image${output.images.length === 1 ? "" : "s"}; no text output)`
+				: "(no output)");
+		return { content: [{ type: "text", text }, ...output.images], details };
+	}
+
+	#details(output: EvalOutputResult | undefined, isError: boolean): EvalToolDetails {
+		const statusEvents = this.#state.statusEvents.length > 0 ? [...this.#state.statusEvents] : undefined;
+		return {
+			language: this.#state.input.language,
+			languages: [this.#state.input.language],
+			...(this.#state.input.title === undefined ? {} : { title: this.#state.input.title }),
+			durationMs: this.#state.durationMs,
+			toolCalls: [...this.#state.toolCalls],
+			truncated: output?.truncated ?? false,
+			...(isError ? { isError: true } : {}),
+			...(this.#state.phase === undefined ? {} : { phase: this.#state.phase }),
+			cells: [
+				{
+					index: 0,
+					...(this.#state.input.title === undefined ? {} : { title: this.#state.input.title }),
+					code: this.#state.input.code,
+					language: this.#state.input.language,
+					output: this.#state.output,
+					status: this.#state.status,
+					durationMs: this.#state.durationMs,
+					...(statusEvents === undefined ? {} : { statusEvents }),
+					...(output?.hasMarkdown ? { hasMarkdown: true } : {}),
+				},
+			],
+			...(statusEvents === undefined ? {} : { statusEvents }),
+			...(output === undefined || output.jsonOutputs.length === 0 ? {} : { jsonOutputs: output.jsonOutputs }),
+			...(output?.notice === undefined ? {} : { notice: output.notice }),
+			...(output?.meta === undefined ? {} : { meta: output.meta }),
+		};
+	}
+
+	#liveUpdateText(): string {
+		const title = this.#state.input.title === undefined ? "" : ` ${this.#state.input.title}`;
+		const aggregateOutput = this.#output.aggregateText();
+		const outputLines = aggregateOutput.split("\n");
+		const hasTrailingNewline = aggregateOutput.endsWith("\n");
+		if (hasTrailingNewline) outputLines.pop();
+		const output = `${outputLines.slice(-8).join("\n")}${hasTrailingNewline ? "\n" : ""}`;
+		return `1/1 cells ${this.#state.status}\n[1] ${this.#state.input.language}${title} ${this.#state.status}${output.length === 0 ? "" : `\n${output}`}`;
+	}
+}

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

@@ -1,26 +1,32 @@
-import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
 import type { AgentToolResult } from "@code-yeongyu/senpi";
+import { detachedNotificationSpillPath } from "./detached-cell-notification.ts";
+import { currentDetachedResult, detachedErrorResult, snapshotDetachedCell } from "./detached-cell-snapshot.ts";
+import {
+	activeDetachedCellReuseError,
+	allowsDetachedCellTransition,
+	detachedCellIsActive,
+} from "./detached-cell-state.ts";
+import { DetachedNotificationQueue } from "./detached-notification-queue.ts";
 import type { EvalKernel, EvalLanguage, EvalToolDetails, EvalToolInput } from "./types.ts";
 
-const NOTIFICATION_TAIL_BYTES = 512;
-
 export type EvalDetachedCellState = "running" | "detached" | "completed" | "failed" | "cancelled";
 
+type LiveResultProvider = () => AgentToolResult<EvalToolDetails>;
+
 type ManagedCell = {
 	readonly cellId: string;
 	readonly input: EvalToolInput;
 	readonly spillPath: string | undefined;
+	readonly startedAtMs: number;
+	readonly terminal: PromiseWithResolvers<EvalDetachedCellSnapshot>;
 	state: EvalDetachedCellState;
 	canDetach: boolean;
 	wasDetached: boolean;
 	kernel: EvalKernel | undefined;
-	/** Set after an interrupt-driven stop; undefined until the kernel reports its fate. */
 	stateRetained: boolean | undefined;
-	outputTail: (() => string) | undefined;
-	result: AgentToolResult<EvalToolDetails> | undefined;
+	liveResult: LiveResultProvider | undefined;
+	terminalResult: AgentToolResult<EvalToolDetails> | undefined;
 	notificationQueued: boolean;
-	readonly terminal: PromiseWithResolvers<EvalDetachedCellSnapshot>;
 };
 
 export interface EvalDetachedCellSnapshot {
@@ -28,7 +34,7 @@ export interface EvalDetachedCellSnapshot {
 	readonly language: EvalLanguage;
 	readonly state: EvalDetachedCellState;
 	readonly outputTail: string;
-	readonly result: AgentToolResult<EvalToolDetails> | undefined;
+	readonly result: AgentToolResult<EvalToolDetails>;
 	readonly stateRetained: boolean | undefined;
 }
 
@@ -41,63 +47,53 @@ export interface EvalDetachedCellNotifier {
 	notify(cells: readonly EvalDetachedCellNotification[]): void;
 }
 
-/** One live detached cell, as shown in the footer status line. */
 export interface EvalDetachedCellStatusEntry {
 	readonly cellId: string;
 	readonly language: EvalLanguage;
 	readonly title?: string;
+	readonly startedAtMs: number;
 }
 
 export interface EvalDetachedCellManagerOptions {
 	readonly artifactsDir?: string;
 	readonly notifier?: EvalDetachedCellNotifier;
-	/** Called with every detached cell whenever that set changes; empty clears the status. */
 	readonly onStatusChange?: (entries: readonly EvalDetachedCellStatusEntry[]) => void;
+	readonly now?: () => number;
 }
 
-/**
- * Session-owned lifecycle owner for eval cells that outlive their tool call.
- *
- * All state changes are synchronous and funnel through #transition. That is the
- * atomic boundary for timeout, kernel completion, explicit stop, and session
- * disposal races; exactly one path can release a language's detached busy mark.
- */
 export class EvalDetachedCellManager {
 	readonly #artifactsDir: string | undefined;
-	readonly #notifier: EvalDetachedCellNotifier | undefined;
 	readonly #onStatusChange: ((entries: readonly EvalDetachedCellStatusEntry[]) => void) | undefined;
 	readonly #cells = new Map<string, ManagedCell>();
 	readonly #detachedByLanguage = new Map<EvalLanguage, ManagedCell>();
-	#notificationQueue: ManagedCell[] = [];
-	#notificationFlush: Promise<void> | undefined;
+	readonly #notificationQueue: DetachedNotificationQueue;
+	readonly #now: () => number;
 
 	constructor(options: EvalDetachedCellManagerOptions = {}) {
 		this.#artifactsDir = options.artifactsDir;
-		this.#notifier = options.notifier;
 		this.#onStatusChange = options.onStatusChange;
+		this.#notificationQueue = new DetachedNotificationQueue(options.notifier, options.artifactsDir);
+		this.#now = options.now ?? Date.now;
 	}
 
 	create(cellId: string, input: EvalToolInput): ManagedCell {
 		const existing = this.#cells.get(cellId);
 		if (existing !== undefined) {
-			if (existing.state === "running" || existing.state === "detached") throw activeCellReuseError(existing);
+			if (detachedCellIsActive(existing.state)) throw activeDetachedCellReuseError(existing);
 			this.#cells.delete(cellId);
 		}
-		const spillPath =
-			this.#artifactsDir === undefined
-				? undefined
-				: join(this.#artifactsDir, "local", `detached-eval-${safeCellId(cellId)}.log`);
 		const cell: ManagedCell = {
 			cellId,
 			input,
-			spillPath,
+			spillPath: detachedNotificationSpillPath(this.#artifactsDir, cellId),
+			startedAtMs: this.#now(),
 			state: "running",
 			canDetach: false,
 			wasDetached: false,
 			kernel: undefined,
 			stateRetained: undefined,
-			outputTail: undefined,
-			result: undefined,
+			liveResult: undefined,
+			terminalResult: undefined,
 			notificationQueued: false,
 			terminal: Promise.withResolvers<EvalDetachedCellSnapshot>(),
 		};
@@ -105,15 +101,16 @@ export class EvalDetachedCellManager {
 		return cell;
 	}
 
-	markRunning(cell: ManagedCell, kernel: EvalKernel, outputTail: () => string): void {
+	markRunning(cell: ManagedCell, kernel: EvalKernel, liveResult: LiveResultProvider): void {
 		if (cell.state !== "running") return;
 		cell.kernel = kernel;
-		cell.outputTail = outputTail;
+		cell.liveResult = liveResult;
 		cell.canDetach = true;
 	}
 
 	detach(cell: ManagedCell): boolean {
-		if (!cell.canDetach || !this.#transition(cell, "detached")) return false;
+		if (!cell.canDetach || !allowsDetachedCellTransition(cell.state, "detached")) return false;
+		cell.state = "detached";
 		cell.wasDetached = true;
 		this.#detachedByLanguage.set(cell.input.language, cell);
 		this.#emitStatus();
@@ -121,22 +118,19 @@ export class EvalDetachedCellManager {
 	}
 
 	complete(cell: ManagedCell, result: AgentToolResult<EvalToolDetails>): boolean {
-		cell.result = result;
-		return this.#transition(cell, result.details.isError === true ? "failed" : "completed");
+		return this.#settle(cell, result.details.isError === true ? "failed" : "completed", result);
 	}
 
 	fail(cell: ManagedCell, error: Error): boolean {
-		const result = errorResult(cell, error);
-		cell.result = result;
-		return this.#transition(cell, "failed");
+		return this.#settle(cell, "failed", detachedErrorResult(cell, error));
 	}
 
 	async stop(cellId: string, reason = "Stopped detached eval cell"): Promise<EvalDetachedCellSnapshot> {
 		const cell = this.#get(cellId);
-		if (cell.state === "detached" && this.#transition(cell, "cancelled")) {
-			const kernel = cell.kernel;
-			if (kernel !== undefined) {
-				const handle = await kernel.interrupt(reason);
+		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;
 			}
 		}
@@ -161,85 +155,51 @@ export class EvalDetachedCellManager {
 		await Promise.allSettled(
 			detached.map(async (cell) => await this.stop(cell.cellId, "Session ended; detached eval cell cancelled")),
 		);
-		await this.flushNotifications();
+		await this.#notificationQueue.flush();
 	}
 
 	async flushNotifications(): Promise<void> {
-		const flush = this.#notificationFlush;
-		if (flush !== undefined) await flush;
-	}
-
-	#transition(cell: ManagedCell, next: EvalDetachedCellState): boolean {
-		if (!allowsTransition(cell.state, next)) return false;
-		cell.state = next;
-		if (next !== "running" && next !== "detached") cell.terminal.resolve(this.#snapshot(cell));
-		if (cell.wasDetached && next !== "detached") {
+		await this.#notificationQueue.flush();
+	}
+
+	#settle(
+		cell: ManagedCell,
+		state: "completed" | "failed" | "cancelled",
+		result: AgentToolResult<EvalToolDetails>,
+	): boolean {
+		if (!allowsDetachedCellTransition(cell.state, state)) return false;
+		cell.state = state;
+		cell.terminalResult = result;
+		cell.liveResult = undefined;
+		cell.terminal.resolve(this.#snapshot(cell));
+		if (cell.wasDetached) {
 			if (this.#detachedByLanguage.get(cell.input.language) === cell)
 				this.#detachedByLanguage.delete(cell.input.language);
 			this.#emitStatus();
-			this.#queueNotification(cell);
+			if (!cell.notificationQueued) {
+				cell.notificationQueued = true;
+				this.#notificationQueue.enqueue({
+					snapshot: () => this.#snapshot(cell),
+					spillPath: cell.spillPath,
+				});
+			}
 		}
 		return true;
 	}
 
 	#emitStatus(): void {
-		const emit = this.#onStatusChange;
-		if (emit === undefined) return;
-		emit(
+		this.#onStatusChange?.(
 			[...this.#detachedByLanguage.values()].map((cell) => ({
 				cellId: cell.cellId,
 				language: cell.input.language,
+				startedAtMs: cell.startedAtMs,
 				...(cell.input.title === undefined ? {} : { title: cell.input.title }),
 			})),
 		);
 	}
 
-	#queueNotification(cell: ManagedCell): void {
-		if (cell.notificationQueued) return;
-		cell.notificationQueued = true;
-		this.#notificationQueue.push(cell);
-		this.#scheduleNotificationFlush();
-	}
-
-	#scheduleNotificationFlush(): void {
-		if (this.#notificationFlush !== undefined) return;
-		const flush = Promise.resolve().then(async () => {
-			const cells = this.#notificationQueue.splice(0);
-			const notifications = await Promise.all(cells.map(async (candidate) => await this.#notification(candidate)));
-			this.#notifier?.notify(notifications);
-		});
-		this.#notificationFlush = flush;
-		void flush.then(
-			() => this.#finishNotificationFlush(flush),
-			() => this.#finishNotificationFlush(flush),
-		);
-	}
-
-	#finishNotificationFlush(flush: Promise<void>): void {
-		if (this.#notificationFlush !== flush) return;
-		this.#notificationFlush = undefined;
-		if (this.#notificationQueue.length > 0) this.#scheduleNotificationFlush();
-	}
-
-	async #notification(cell: ManagedCell): Promise<EvalDetachedCellNotification> {
-		const snapshot = this.#snapshot(cell);
-		const body = notificationBody(snapshot);
-		const overflow = Buffer.byteLength(body, "utf8") > NOTIFICATION_TAIL_BYTES;
-		let spillNotice = "";
-		if (overflow && cell.spillPath !== undefined) {
-			try {
-				await mkdir(dirname(cell.spillPath), { recursive: true });
-				await writeFile(cell.spillPath, body, "utf8");
-				spillNotice = `\nBuffered output overflowed; full output: ${localUri(cell.spillPath, this.#artifactsDir)}`;
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
-				spillNotice = `\nBuffered output overflow could not be spilled: ${message}`;
-			}
-		}
-		return {
-			cellId: cell.cellId,
-			content: `${overflow ? notificationPreview(snapshot) : body}${overflow ? "\n[…notification tail capped…]" : ""}${spillNotice}`,
-		};
+	#snapshot(cell: ManagedCell): EvalDetachedCellSnapshot {
+		return snapshotDetachedCell(cell, this.#now());
 	}
 
 	#get(cellId: string): ManagedCell {
@@ -247,110 +207,4 @@ export class EvalDetachedCellManager {
 		if (cell === undefined) throw new Error(`Unknown detached eval cell "${cellId}"`);
 		return cell;
 	}
-
-	#snapshot(cell: ManagedCell): EvalDetachedCellSnapshot {
-		return {
-			cellId: cell.cellId,
-			language: cell.input.language,
-			state: cell.state,
-			outputTail: cell.outputTail?.() ?? "",
-			result: cell.result,
-			stateRetained: cell.stateRetained,
-		};
-	}
-}
-
-function activeCellReuseError(cell: ManagedCell): Error {
-	return new Error(
-		`Eval cell ${cell.cellId} from a previous call is still ${cell.state} in the ${cell.input.language} kernel. Use eval({ action: "peek", cell_id: "${cell.cellId}" }) to read it or eval({ action: "stop", cell_id: "${cell.cellId}" }) to end it before its id can be reused.`,
-	);
-}
-
-function allowsTransition(from: EvalDetachedCellState, to: EvalDetachedCellState): boolean {
-	if (from === "running") return to === "detached" || to === "completed" || to === "failed" || to === "cancelled";
-	if (from === "detached") return to === "completed" || to === "failed" || to === "cancelled";
-	return false;
-}
-
-function errorResult(cell: ManagedCell, error: Error): AgentToolResult<EvalToolDetails> {
-	const output = cell.outputTail?.() ?? "";
-	return {
-		content: [{ type: "text", text: output.length > 0 ? `${output}\n${error.message}` : error.message }],
-		details: {
-			language: cell.input.language,
-			languages: [cell.input.language],
-			durationMs: 0,
-			toolCalls: [],
-			truncated: false,
-			isError: true,
-			cells: [
-				{
-					index: 0,
-					code: cell.input.code,
-					language: cell.input.language,
-					output,
-					status: "error",
-				},
-			],
-		},
-	};
-}
-
-function notificationBody(cell: EvalDetachedCellSnapshot): string {
-	const outcome = cell.state === "completed" ? "completed" : cell.state === "cancelled" ? "cancelled" : "failed";
-	const resultText =
-		cell.result?.content
-			.filter((part) => part.type === "text")
-			.map((part) => part.text)
-			.join("\n") ?? cell.outputTail;
-	const stateNote =
-		cell.state === "cancelled" && cell.language === "js"
-			? "JavaScript worker was restarted; VM state was lost."
-			: cell.state === "cancelled" && cell.language === "py"
-				? "Python kernel was interrupted; its existing variables are preserved."
-				: "Kernel state updated - variables are available to the next eval cell.";
-	return [
-		`<system-reminder>Detached eval cell ${cell.cellId} (${cell.language}) ${outcome}.`,
-		resultText.length === 0 ? "(no output)" : resultText,
-		`${stateNote}</system-reminder>`,
-	].join("\n");
-}
-
-function notificationPreview(cell: EvalDetachedCellSnapshot): string {
-	const outcome = cell.state === "completed" ? "completed" : cell.state === "cancelled" ? "cancelled" : "failed";
-	const resultText =
-		cell.result?.content
-			.filter((part) => part.type === "text")
-			.map((part) => part.text)
-			.join("\n") ?? cell.outputTail;
-	const stateNote =
-		cell.state === "cancelled" && cell.language === "js"
-			? "JavaScript worker was restarted; VM state was lost."
-			: cell.state === "cancelled" && cell.language === "py"
-				? "Python kernel was interrupted; its existing variables are preserved."
-				: "Kernel state updated - variables are available to the next eval cell.";
-	return [
-		`<system-reminder>Detached eval cell ${cell.cellId} (${cell.language}) ${outcome}.`,
-		"Buffered output tail:",
-		truncateTailUtf8(resultText, NOTIFICATION_TAIL_BYTES),
-		`${stateNote}</system-reminder>`,
-	].join("\n");
-}
-
-function safeCellId(cellId: string): string {
-	return cellId.replace(/[^a-zA-Z0-9_-]/gu, "_");
-}
-
-function localUri(path: string, artifactsDir: string | undefined): string {
-	if (artifactsDir === undefined) return `local://${path}`;
-	const root = join(artifactsDir, "local");
-	return path.startsWith(`${root}/`) ? `local://${path.slice(root.length + 1)}` : `local://${path}`;
-}
-
-function truncateTailUtf8(text: string, maxBytes: number): string {
-	if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
-	const bytes = Buffer.from(text, "utf8");
-	let start = bytes.length - maxBytes;
-	while (start < bytes.length && (bytes[start] & 0xc0) === 0x80) start++;
-	return bytes.subarray(start).toString("utf8");
 }

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

@@ -0,0 +1,98 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { EvalDetachedCellNotification, EvalDetachedCellSnapshot } from "./detached-cell-manager.ts";
+
+const NOTIFICATION_TAIL_BYTES = 512;
+
+export function detachedNotificationSpillPath(artifactsDir: string | undefined, cellId: string): string | undefined {
+	if (artifactsDir === undefined) return undefined;
+	return join(artifactsDir, "local", `detached-eval-${safeCellId(cellId)}.log`);
+}
+
+export async function buildDetachedCellNotification(
+	snapshot: EvalDetachedCellSnapshot,
+	spillPath: string | undefined,
+	artifactsDir: string | undefined,
+): Promise<EvalDetachedCellNotification> {
+	const body = notificationBody(snapshot);
+	const overflow = Buffer.byteLength(body, "utf8") > NOTIFICATION_TAIL_BYTES;
+	let spillNotice = "";
+	if (overflow && spillPath !== undefined) {
+		try {
+			await mkdir(dirname(spillPath), { recursive: true });
+			await writeFile(spillPath, body, "utf8");
+			spillNotice = `\nBuffered output overflowed; full output: ${localUri(spillPath, artifactsDir)}`;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			spillNotice = `\nBuffered output overflow could not be spilled: ${message}`;
+		}
+	}
+	return {
+		cellId: snapshot.cellId,
+		content: `${overflow ? notificationPreview(snapshot) : body}${overflow ? "\n[…notification tail capped…]" : ""}${spillNotice}`,
+	};
+}
+
+function notificationBody(cell: EvalDetachedCellSnapshot): string {
+	const outcome = outcomeOf(cell);
+	const resultText = textContent(cell);
+	const stateNote = stateNoteOf(cell);
+	return [
+		`<system-reminder>Detached eval cell ${cell.cellId} (${cell.language}) ${outcome}.`,
+		resultText.length === 0 ? "(no output)" : resultText,
+		`${stateNote}</system-reminder>`,
+	].join("\n");
+}
+
+function notificationPreview(cell: EvalDetachedCellSnapshot): string {
+	const outcome = outcomeOf(cell);
+	const resultText = textContent(cell);
+	const stateNote = stateNoteOf(cell);
+	return [
+		`<system-reminder>Detached eval cell ${cell.cellId} (${cell.language}) ${outcome}.`,
+		"Buffered output tail:",
+		truncateTailUtf8(resultText, NOTIFICATION_TAIL_BYTES),
+		`${stateNote}</system-reminder>`,
+	].join("\n");
+}
+
+function textContent(cell: EvalDetachedCellSnapshot): string {
+	return (
+		cell.result.content
+			.filter((part) => part.type === "text")
+			.map((part) => part.text)
+			.join("\n") || cell.outputTail
+	);
+}
+
+function outcomeOf(cell: EvalDetachedCellSnapshot): string {
+	if (cell.state === "completed") return "completed";
+	if (cell.state === "cancelled") return "cancelled";
+	return "failed";
+}
+
+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.";
+}
+
+function safeCellId(cellId: string): string {
+	return cellId.replace(/[^a-zA-Z0-9_-]/gu, "_");
+}
+
+function localUri(path: string, artifactsDir: string | undefined): string {
+	if (artifactsDir === undefined) return `local://${path}`;
+	const root = join(artifactsDir, "local");
+	return path.startsWith(`${root}/`) ? `local://${path.slice(root.length + 1)}` : `local://${path}`;
+}
+
+function truncateTailUtf8(text: string, maxBytes: number): string {
+	if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
+	const bytes = Buffer.from(text, "utf8");
+	let start = bytes.length - maxBytes;
+	while (start < bytes.length && (bytes[start] & 0xc0) === 0x80) start++;
+	return bytes.subarray(start).toString("utf8");
+}