@code-yeongyu/senpi-codemode 2026.10.10 → 2026.10.11

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

@@ -1,61 +1,21 @@
-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";
 import type { EvalKernelState, EvalMemoryDetails } from "./types.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,
-): 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");
-			// The agent read tool resolves plain paths only, so the notice must carry
-			// the absolute spill path, never the kernel-helper local:// scheme.
-			spillNotice = `\nBuffered output overflowed; full output: ${spillPath}`;
-		} 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");
+/**
+ * A detached cell's completion carries the same text its result would have shown in the foreground: the output sink
+ * already bounded it (the configured head, the tail, the middle marker and the artifact notice), plus its images.
+ */
+export function buildDetachedCellNotification(snapshot: EvalDetachedCellSnapshot): EvalDetachedCellNotification {
+	const images = snapshot.result.content.filter((part) => part.type === "image");
+	return { cellId: snapshot.cellId, content: notificationText(snapshot, textContent(snapshot)), images };
 }
 
-function notificationPreview(cell: EvalDetachedCellSnapshot): string {
-	const outcome = outcomeOf(cell);
-	const resultText = textContent(cell);
-	const stateNote = stateNoteOf(cell);
+function notificationText(cell: EvalDetachedCellSnapshot, output: string): string {
 	return [
-		`<system-reminder>Detached eval cell ${cell.cellId} (${cell.language}) ${outcome}.`,
-		"Buffered output tail:",
-		truncateTailUtf8(resultText, NOTIFICATION_TAIL_BYTES),
-		`${stateNote}</system-reminder>`,
+		`<system-reminder>Detached eval cell ${cell.cellId} (${cell.language}) ${outcomeOf(cell)}.`,
+		output.length === 0 ? "(no output)" : output,
+		`${stateNoteOf(cell)}</system-reminder>`,
 	].join("\n");
 }
 
@@ -101,15 +61,3 @@ export function memoryStateNote(memory: EvalMemoryDetails | undefined): string {
 		return "The kernel was restarted before this cell ran - globals from earlier cells are gone; this cell's variables are available to the next eval cell.";
 	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 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-snapshot.ts

@@ -63,6 +63,23 @@ export function currentDetachedResult(cell: DetachedCellResultSource): AgentTool
 	return cell.terminalResult ?? cell.liveResult?.() ?? fallbackResult(cell.input);
 }
 
+/**
+ * The result a cell cancelled before its handler finished settles with: its buffered output, not the live progress
+ * frame ("1/1 cells running"), so a stopped cell never reads as still running.
+ */
+export function cancelledDetachedResult(cell: DetachedCellResultSource): AgentToolResult<EvalToolDetails> {
+	if (cell.terminalResult !== undefined) return cell.terminalResult;
+	const current = currentDetachedResult(cell);
+	const output = detachedOutputTail(current);
+	return {
+		content: [
+			{ type: "text", text: output.length > 0 ? output : "(no output)" },
+			...current.content.filter((part) => part.type === "image"),
+		],
+		details: current.details,
+	};
+}
+
 export function detachedErrorResult(cell: DetachedCellResultSource, error: Error): AgentToolResult<EvalToolDetails> {
 	const current = currentDetachedResult(cell);
 	const output = detachedOutputTail(current);

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

@@ -46,9 +46,7 @@ function createEvalListResult(cellManager: EvalDetachedCellManager): AgentToolRe
 			language: snapshot.language,
 			state: snapshot.state,
 			startedAtMs: snapshot.startedAtMs,
-			...(snapshot.queuedBehind === undefined || snapshot.queuedBehind.length === 0
-				? {}
-				: { queuedBehind: [...snapshot.queuedBehind] }),
+			...(snapshot.queuedBehind === undefined ? {} : { queuedBehind: [...snapshot.queuedBehind] }),
 			...(summary ? { summary } : {}),
 		};
 	});
@@ -60,7 +58,7 @@ function createEvalListResult(cellManager: EvalDetachedCellManager): AgentToolRe
 				" ",
 			);
 			const elapsed = Math.floor(snapshot.result.details.durationMs / 1000);
-			const queued = cell.queuedBehind === undefined ? "" : ` queued behind ${cell.queuedBehind.join(", ")}`;
+			const queued = cell.queuedBehind === undefined ? "" : ` ${queuedPhrase(cell.queuedBehind, cell.language)}`;
 			return `${cell.cellId} ${cell.language} ${cell.state} ${elapsed}s${queued} - ${preview}`;
 		})
 		.join("\n");
@@ -76,11 +74,13 @@ export function resultAfterDetach(
 	otherLiveCells: number,
 ): AgentToolResult<EvalToolDetails> {
 	if (snapshot.state !== "detached" && snapshot.state !== "running") return createDetachedControlResult(snapshot);
-	const predecessors = snapshot.queuedBehind?.join(", ");
+	const queuedBehind = snapshot.queuedBehind;
 	const text =
-		predecessors === undefined
+		queuedBehind === undefined
 			? `Eval cell ${snapshot.cellId} detached and is running in the ${input.language} kernel (${otherLiveCells} other live cells). Completion arrives as a notification; do not re-run it. eval({ action: "peek" | "stop", cell_id }) or eval({ action: "list" }).`
-			: `Eval cell ${snapshot.cellId} is queued behind ${predecessors} in the ${input.language} kernel and detached; it runs after ${predecessors} and completes as one notification. peek/stop/list with eval({ action, cell_id })`;
+			: queuedBehind.length === 0
+				? `Eval cell ${snapshot.cellId} is detached and waiting for the ${input.language} kernel to be ready; it runs first once the kernel is ready and completes as one notification. peek/stop/list with eval({ action, cell_id })`
+				: `Eval cell ${snapshot.cellId} is queued behind ${queuedBehind.join(", ")} in the ${input.language} kernel and detached; it runs after ${queuedBehind.join(", ")} and completes as one notification. peek/stop/list with eval({ action, cell_id })`;
 	return {
 		content: [
 			{
@@ -164,6 +164,12 @@ export function resultForDetachedState(
 	};
 }
 
+function queuedPhrase(queuedBehind: readonly string[], language: string): string {
+	return queuedBehind.length === 0
+		? `waiting for the ${language} kernel to be ready`
+		: `queued behind ${queuedBehind.join(", ")}`;
+}
+
 function textContent(result: AgentToolResult<EvalToolDetails>): string {
 	return result.content
 		.filter((part) => part.type === "text")

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

@@ -3,7 +3,6 @@ import { buildDetachedCellNotification } from "./detached-cell-notification.ts";
 
 export interface PendingDetachedNotification {
 	readonly snapshot: () => EvalDetachedCellSnapshot | Promise<EvalDetachedCellSnapshot>;
-	readonly spillPath: string | undefined;
 }
 
 export class DetachedNotificationQueue {
@@ -30,7 +29,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(await item.snapshot(), item.spillPath)),
+				pending.map(async (item) => buildDetachedCellNotification(await item.snapshot())),
 			);
 			this.#notifier?.notify(notifications);
 		});

package/src/tool/eval-tool.ts

@@ -1,6 +1,6 @@
 import type { AgentToolResult, ToolDefinition } from "@code-yeongyu/senpi";
 import type { TUnsafe } from "typebox";
-import { resolveSandbox } from "../config/feature-settings.ts";
+import { resolveAdvertiseHelpers, resolveSandbox } from "../config/feature-settings.ts";
 import {
 	DEFAULT_FOREGROUND_WINDOW_SECONDS,
 	defaultCodemodeSettings,
@@ -25,6 +25,7 @@ import {
 	type EvalListInput,
 	type EvalResultDetails,
 	type EvalToolDetails,
+	type EvalToolInput,
 	type EvalToolRequest,
 	enabledLanguageList,
 } from "./types.ts";
@@ -34,7 +35,7 @@ export type { CreateEvalToolOptions } from "./eval-tool-options.ts";
 export type { EnabledEvalLanguages, EvalKernel, EvalKernelManager } from "./types.ts";
 
 type EvalExecuteArgs<Request extends EvalToolRequest> = Parameters<
-	ToolDefinition<TUnsafe<Request>, EvalToolDetails>["execute"]
+	ToolDefinition<TUnsafe<Request | Partial<EvalToolInput>>, EvalToolDetails>["execute"]
 >;
 
 export function createEvalTool(options: CreateEvalToolOptions) {
@@ -53,6 +54,7 @@ export function createEvalTool(options: CreateEvalToolOptions) {
 	const parameters = createEvalInputSchema(options.enabledLanguages, deadlines, { sandbox });
 	const prompt = buildEvalPrompt(options.enabledLanguages, {
 		spawns: options.spawns ?? false,
+		...(resolveAdvertiseHelpers(options.settings ?? defaultCodemodeSettings) ? { advertiseHelpers: true } : {}),
 		monitor: options.monitor,
 		maxDetachedCells,
 		runBudgetSeconds: deadlines.runBudgetSeconds,

package/src/tool/interrupt-note.ts

@@ -26,9 +26,8 @@ export async function describeTimeoutState(
 	);
 	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.`;
+		error.message = `${error.message} The kernel was not restarted; variables from earlier cells are kept.`;
+	else error.message = `${error.message} The kernel was restarted; variables from earlier cells are lost.`;
 	if (outcome?.note !== undefined) error.message = `${error.message} ${outcome.note.trim()}`;
 	return error;
 }
@@ -63,8 +62,8 @@ const LANGUAGE_LABEL: Record<EvalLanguage, string> = {
 export function interruptionStateNote(language: EvalLanguage, stateRetained: boolean | undefined): string | undefined {
 	if (stateRetained === undefined) return undefined;
 	const label = LANGUAGE_LABEL[language];
-	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.`;
+	if (stateRetained) return `The ${label} was not restarted; variables from earlier cells are kept.`;
+	return `The ${label} was restarted; variables from earlier cells are lost.`;
 }
 
 export function unknownInterruptionStateNote(language: EvalLanguage): string {

package/src/tool/live-headline.ts

@@ -0,0 +1,60 @@
+import { sanitizeTerminalLabel, visibleWidth } from "@code-yeongyu/senpi";
+import { type EvalCellResult, type EvalLanguage, evalLanguageOrder } from "./types.ts";
+
+const HEADLINED_STATUSES: ReadonlySet<EvalCellResult["status"]> = new Set(["pending", "queued", "running", "detached"]);
+
+/**
+ * A collapsed headline never wraps the frame: it gets what the language, state and timing leave on the line. This
+ * floor (in screen cells) only keeps a word or two visible in very narrow terminals.
+ */
+const MIN_HEADLINE_CELLS = 8;
+
+export function leadsWithHeadline(status: EvalCellResult["status"]): boolean {
+	return HEADLINED_STATUSES.has(status);
+}
+
+/**
+ * What an in-progress cell is doing, in one line: its summary, or else the first line of its code that has content once sanitized (the
+ * oh-my-pi fallback), or an ellipsis while the arguments are still streaming in. Collapsed rows cut it to
+ * `maxCells` screen cells (a wide character takes two), so the headline stays one line. Whichever is chosen is
+ * sanitized before it is measured, so escape and control characters never reach the row (senpi#2831, senpi#2839).
+ */
+export function liveHeadline(
+	summary: string | undefined,
+	code: string | undefined,
+	maxCells: number | undefined,
+): string {
+	const text = (summary === undefined ? "" : sanitizeTerminalLabel(summary)) || firstCodeLine(code) || "…";
+	const limit = maxCells === undefined ? undefined : Math.max(MIN_HEADLINE_CELLS, maxCells);
+	if (limit === undefined || visibleWidth(text) <= limit) return text;
+	return `${cellPrefix(text, limit - 1)}…`;
+}
+
+// A plain cut by screen cells: the headline is styled by the caller, so no reset codes may be inserted here.
+function cellPrefix(text: string, cells: number): string {
+	let kept = "";
+	let used = 0;
+	for (const { segment } of new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(text)) {
+		const width = visibleWidth(segment);
+		if (used + width > cells) break;
+		kept += segment;
+		used += width;
+	}
+	return kept;
+}
+
+export function knownLanguage(language: unknown): EvalLanguage | undefined {
+	return evalLanguageOrder.find((known) => known === language);
+}
+
+// The first line with something to show once it is sanitized: a line of only escape or control characters is skipped
+// (senpi#2850), and the later lines never reach the row.
+function firstCodeLine(code: string | undefined): string | undefined {
+	if (code === undefined) return undefined;
+	// Stops at the first line with content, so a long cell is not sanitized line by line on every frame.
+	for (const line of code.split("\n")) {
+		const clean = sanitizeTerminalLabel(line);
+		if (clean.length > 0) return clean;
+	}
+	return undefined;
+}

package/src/tool/managed-cell.ts

@@ -1,7 +1,6 @@
 import type { AgentToolResult } from "@code-yeongyu/senpi";
 import { type CellDeadlineExpiry, CellDeadlines } from "./cell-deadlines.ts";
 import type { EvalDetachedCellSnapshot, EvalDetachedCellState } from "./detached-cell-contract.ts";
-import { detachedNotificationSpillPath } from "./detached-cell-notification.ts";
 import type { EvalKernel, EvalToolDetails, EvalToolInput } from "./types.ts";
 
 export type LiveResultProvider = () => AgentToolResult<EvalToolDetails>;
@@ -9,7 +8,6 @@ export type LiveResultProvider = () => AgentToolResult<EvalToolDetails>;
 export type ManagedCell = {
 	readonly cellId: string;
 	readonly input: EvalToolInput;
-	readonly spillPath: string | undefined;
 	readonly startedAtMs: number;
 	readonly terminal: PromiseWithResolvers<EvalDetachedCellSnapshot>;
 	state: Exclude<EvalDetachedCellState, "detached">;
@@ -37,7 +35,6 @@ export type ManagedCell = {
 export interface ManagedCellInit {
 	readonly cellId: string;
 	readonly input: EvalToolInput;
-	readonly artifactsDir: string | undefined;
 	readonly now: () => number;
 	readonly defaultHardLimitSeconds: number;
 	readonly defaultRunBudgetSeconds: number;
@@ -60,7 +57,6 @@ export function createManagedCell(init: ManagedCellInit): ManagedCell {
 	return {
 		cellId: init.cellId,
 		input: init.input,
-		spillPath: detachedNotificationSpillPath(init.artifactsDir, init.cellId),
 		startedAtMs: init.now(),
 		state: "queued",
 		runStartedAtMs: undefined,

package/src/tool/render-agent.ts

@@ -0,0 +1,110 @@
+import {
+	appendLines,
+	assertNever,
+	type RenderEnvironment,
+	renderPrefixed,
+	type StatusPresentation,
+	spinner,
+	style,
+} from "./render-blocks.ts";
+import { eventString } from "./render-status.ts";
+import { formatDuration } from "./tool-widgets.ts";
+import type { EvalStatusEvent } from "./types.ts";
+
+type AgentStatus = "pending" | "running" | "completed" | "failed" | "aborted";
+
+function eventNumber(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function agentStatus(value: unknown): AgentStatus {
+	switch (value) {
+		case "pending":
+		case "running":
+		case "completed":
+		case "failed":
+		case "aborted":
+			return value;
+		default:
+			return "running";
+	}
+}
+
+function coalesceAgentEvents(events: readonly EvalStatusEvent[]): EvalStatusEvent[] {
+	const rows: EvalStatusEvent[] = [];
+	const indexes = new Map<string, number>();
+	for (const event of events) {
+		const id = eventString(event.id);
+		if (id === undefined) {
+			rows.push(event);
+			continue;
+		}
+		const index = indexes.get(id);
+		if (index === undefined) {
+			indexes.set(id, rows.length);
+			rows.push(event);
+		} else rows[index] = event;
+	}
+	return rows;
+}
+
+function agentPresentation(status: AgentStatus, spinnerFrame: number | undefined): StatusPresentation {
+	switch (status) {
+		case "pending":
+			return { label: "pending", icon: "○", color: "muted" };
+		case "running":
+			return { label: "running", icon: spinner(spinnerFrame), color: "warning" };
+		case "completed":
+			return { label: "done", icon: "✓", color: "success" };
+		case "failed":
+			return { label: "failed", icon: "✗", color: "error" };
+		case "aborted":
+			return { label: "aborted", icon: "×", color: "error" };
+		default:
+			return assertNever(status);
+	}
+}
+
+export function renderAgentProgressEvents(
+	events: readonly EvalStatusEvent[],
+	environment: RenderEnvironment,
+): string[] {
+	const rows = coalesceAgentEvents(events);
+	const lines: string[] = [];
+	// Senpi Theme has no tree-token API; fixed ├/└/│ glyphs intentionally mirror omp.
+	for (const [index, event] of rows.entries()) {
+		const isLast = index === rows.length - 1;
+		const status = agentStatus(event.status);
+		const presentation = agentPresentation(status, environment.spinnerFrame);
+		const id = eventString(event.id) ?? "agent";
+		const styledId = environment.theme === undefined ? id : environment.theme.bold(id);
+		let body = `${style(environment.theme, presentation.color, presentation.icon)} ${styledId} ${presentation.label}`;
+		if (status === "completed" || status === "failed" || status === "aborted") {
+			const duration = eventNumber(event.durationMs);
+			if (duration > 0) body += ` · ${style(environment.theme, "dim", formatDuration(duration))}`;
+		}
+		const branch = isLast ? "└ " : "├ ";
+		const continuation = isLast ? "  " : "│ ";
+		appendLines(
+			lines,
+			renderPrefixed(body, environment, { prefix: branch, continuation: continuation, color: "dim" }),
+		);
+		if (status !== "running") continue;
+		const currentTool = eventString(event.currentTool);
+		const lastIntent = eventString(event.lastIntent);
+		if (currentTool === undefined && lastIntent === undefined) continue;
+		const detail =
+			currentTool === undefined
+				? (lastIntent ?? "")
+				: `${currentTool}${lastIntent === undefined ? "" : `: ${lastIntent}`}`;
+		appendLines(
+			lines,
+			renderPrefixed(detail, environment, {
+				prefix: `${continuation}└ `,
+				continuation: `${continuation}  `,
+				color: "dim",
+			}),
+		);
+	}
+	return lines;
+}