@code-yeongyu/senpi-codemode 2026.10.10 → 2026.10.11

package/src/kernels/sandbox/sandbox-cell.ts

@@ -1,6 +1,6 @@
 import type { ResolvedSandbox } from "../../config/feature-settings.ts";
 import { marshalToolResult } from "../../tool/image.ts";
-import type { ExecuteTool, HostCellExecutor } from "../../tool/types.ts";
+import type { EvalRuntimeInfo, ExecuteTool, HostCellExecutor } from "../../tool/types.ts";
 import type { CodemodeSandbox } from "./vendor/pi-codemode/runtime/host.ts";
 import type { CodemodeError, CodemodeOutputFrame, CodemodeTool } from "./vendor/pi-codemode/types.ts";
 
@@ -13,6 +13,31 @@ export interface SandboxCellOptions {
 	readonly wasmPath?: string;
 }
 
+/**
+ * The runtime an isolated cell's result reports: the QuickJS build it runs on, never the persistent kernel's (senpi#2811).
+ * Read from the installed quickjs-wasi package the wasm loads from, only when an isolated cell runs; when that package
+ * cannot be resolved the cell itself fails with eval_isolate_unavailable, and the version says so.
+ */
+export function sandboxRuntimeInfo(): EvalRuntimeInfo {
+	let version = "unavailable";
+	try {
+		// getBuiltinModule, not a static import: node:module would otherwise load with the extension.
+		const manifest: unknown = process.getBuiltinModule("node:module").createRequire(import.meta.url)(
+			"quickjs-wasi/package.json",
+		);
+		if (
+			typeof manifest === "object" &&
+			manifest !== null &&
+			"version" in manifest &&
+			typeof manifest.version === "string"
+		)
+			version = manifest.version;
+	} catch {
+		// Reported as "unavailable": the same missing package makes the cell fail with eval_isolate_unavailable.
+	}
+	return { name: "quickjs", version, isolation: "sandbox" };
+}
+
 // On the script's first line so reported line numbers still match the cell; globals, so a cell's own
 // `const print` shadows them instead of failing as a redeclaration.
 const OUTPUT_ALIASES =

package/src/kernels/sandbox/vendor/pi-codemode/runtime/host.ts

@@ -115,7 +115,7 @@ class Execution {
 	private finished = false;
 	// senpi-change begin: output streaming
 	private readonly stream: StreamOptions | undefined;
-	private readonly credits: Int32Array | undefined;
+	private readonly credits: Int32Array<SharedArrayBuffer> | undefined;
 	private frameChain: Promise<void> = Promise.resolve();
 	private frames = 0;
 	private inFlightBytes = 0;
@@ -188,7 +188,7 @@ class Execution {
 			// senpi-change begin: output streaming and builtin policy
 			...(this.credits === undefined || this.stream === undefined
 				? {}
-				: { stream: { credits: this.credits.buffer as SharedArrayBuffer, frameBytes: this.stream.frameBytes } }),
+				: { stream: { credits: this.credits.buffer, frameBytes: this.stream.frameBytes } }),
 			storePolicy: options.storePolicy,
 			// senpi-change end
 		};

package/src/kernels/shared/bun-ffi.ts

@@ -0,0 +1,24 @@
+/**
+ * The one read of `bun:ffi` behind a guard: `process.getBuiltinModule` returns the module on Bun and
+ * `undefined` on Node, so this module loads on either runtime, and only a result carrying the callable
+ * surface the CPU readers bind is treated as FFI - the same boundary `display-js.ts` uses for `Bun`.
+ */
+export type BunFfi = {
+	readonly dlopen: <S>(path: string, definitions: Record<string, unknown>) => { readonly symbols: S };
+	readonly FFIType: Record<string, number>;
+	readonly ptr: (buffer: ArrayBufferView) => number;
+};
+
+/** True when `value` carries the `bun:ffi` surface the kernel CPU readers use (`dlopen`, `FFIType`, `ptr`). */
+export function isBunFfi(value: unknown): value is BunFfi {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("dlopen" in value) || typeof value.dlopen !== "function") return false;
+	if (!("ptr" in value) || typeof value.ptr !== "function") return false;
+	return "FFIType" in value && typeof value.FFIType === "object" && value.FFIType !== null;
+}
+
+/** The runtime's `bun:ffi` module, or `undefined` on Node and on any runtime whose builtin is not one. */
+export function loadBunFfi(): BunFfi | undefined {
+	const ffi: unknown = process.getBuiltinModule("bun:ffi");
+	return isBunFfi(ffi) ? ffi : undefined;
+}

package/src/kernels/shared/kernel-memory-host.ts

@@ -1,4 +1,4 @@
-import type { KernelMemoryThresholds } from "../../bridge/memory-protocol.ts";
+import type { KernelMemoryReport, KernelMemoryThresholds } from "../../bridge/memory-protocol.ts";
 import type { KernelToHostMessage } from "../../bridge/protocol.ts";
 import type { EvalLanguage } from "../../tool/types.ts";
 import { KernelMemoryPolicy } from "./kernel-memory.ts";
@@ -11,7 +11,7 @@ export type FootprintReader = (pid: number) => { readonly bytes: number } | unde
 export interface KernelMemoryHostOptions {
 	/**
 	 * Host-measured kernel (rb, jl): the host reads the interpreter's footprint after each result and
-	 * replaces the runner's live reading with it; the runner still names its largest globals, so the
+	 * replaces the runner's live reading with it; the runner names its largest globals on demand, so the
 	 * notice and the ceiling both apply, with every reading counting (no collection precedes it).
 	 */
 	readonly readFootprint?: FootprintReader;
@@ -36,12 +36,35 @@ export class KernelMemoryHost {
 	}
 
 	annotate(result: ResultMessage, pid?: number): ResultMessage {
+		return this.annotateReport(result, this.readReport(result, pid));
+	}
+
+	readReport(result: ResultMessage, pid?: number): KernelMemoryReport | undefined {
 		const runnerReport = result.memory;
-		const report =
-			this.#readFootprint === undefined
-				? runnerReport
-				: this.#footprintReport(this.#readFootprint, pid, runnerReport);
-		return report === undefined ? result : { ...result, memory: this.#policy.annotate(report) };
+		return this.#readFootprint === undefined
+			? runnerReport
+			: this.#footprintReport(this.#readFootprint, pid, runnerReport);
+	}
+
+	needsGlobals(report: KernelMemoryReport): boolean {
+		const { noticeBytes, ceilingBytes } = this.#policy.thresholds;
+		// Collect at or above the host-read notice threshold or ceiling, regardless of notice hysteresis;
+		// never collect below both thresholds. Zero disables a threshold, not the lazy diagnostic gate.
+		return (
+			(noticeBytes > 0 && report.liveBytes >= noticeBytes) || (ceilingBytes > 0 && report.liveBytes >= ceilingBytes)
+		);
+	}
+
+	annotateReport(result: ResultMessage, report: KernelMemoryReport | undefined): ResultMessage {
+		if (report === undefined) return result;
+		const memory = this.#policy.annotate(report);
+		// Safety accounting still observes every cell, but ordinary host-measured results carry no payload.
+		// A recycle announcement remains visible even when the replacement process is below threshold.
+		if (this.#readFootprint !== undefined && !this.needsGlobals(report) && memory.notice === undefined) {
+			const { memory: _memory, ...ordinary } = result;
+			return ordinary;
+		}
+		return { ...result, memory };
 	}
 
 	/**

package/src/kernels/shared/process-cpu.ts

@@ -8,9 +8,9 @@
  *   Windows has no process groups; this is the interpreter itself when it is launched directly.
  * - anything else, or Windows under Node: `undefined`, and the caller treats the CPU as unknown.
  */
+import { type BunFfi, loadBunFfi } from "./bun-ffi.ts";
 import { readProcessGroupCpuTime } from "./process-group-cpu.ts";
 
-type BunFfi = typeof import("bun:ffi");
 type CpuReader = (pid: number) => bigint | undefined;
 
 const PROCESS_QUERY_LIMITED_INFORMATION = 0x1000;
@@ -26,7 +26,7 @@ export function readKernelCpuTime(pid: number): bigint | undefined {
 }
 
 function createWindowsReader(): CpuReader | undefined {
-	const ffi = process.getBuiltinModule("bun:ffi") as BunFfi | undefined;
+	const ffi = loadBunFfi();
 	if (ffi === undefined) return undefined;
 	try {
 		return bindGetProcessTimes(ffi);
@@ -37,7 +37,11 @@ function createWindowsReader(): CpuReader | undefined {
 }
 
 function bindGetProcessTimes({ dlopen, FFIType, ptr }: BunFfi): CpuReader {
-	const library = dlopen("kernel32.dll", {
+	const library = dlopen<{
+		OpenProcess: (access: number, inheritHandle: number, pid: number) => number | null;
+		GetProcessTimes: (handle: number, create: number, exit: number, kernel: number, user: number) => number;
+		CloseHandle: (handle: number) => number;
+	}>("kernel32.dll", {
 		OpenProcess: { args: [FFIType.u32, FFIType.i32, FFIType.u32], returns: FFIType.ptr },
 		GetProcessTimes: {
 			args: [FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr, FFIType.ptr],

package/src/kernels/shared/process-group-cpu.ts

@@ -15,8 +15,8 @@
  */
 import { execFileSync } from "node:child_process";
 import { readdirSync, readFileSync } from "node:fs";
+import { type BunFfi, loadBunFfi } from "./bun-ffi.ts";
 
-type BunFfi = typeof import("bun:ffi");
 type GroupCpuReader = (pgid: number) => bigint | undefined;
 
 const RUSAGE_INFO_V2 = 2;
@@ -59,7 +59,7 @@ export function parsePsCpuTime(text: string): bigint | undefined {
 function createGroupReader(): GroupCpuReader | undefined {
 	if (process.platform === "linux") return linuxGroupReader;
 	if (process.platform !== "darwin") return undefined;
-	const ffi = process.getBuiltinModule("bun:ffi") as BunFfi | undefined;
+	const ffi = loadBunFfi();
 	if (ffi === undefined) return darwinPsGroupReader;
 	try {
 		return darwinGroupReader(ffi);
@@ -116,7 +116,10 @@ function linuxGroupReader(pgid: number): bigint | undefined {
 }
 
 function darwinGroupReader({ dlopen, FFIType, ptr }: BunFfi): GroupCpuReader {
-	const library = dlopen("libSystem.B.dylib", {
+	const library = dlopen<{
+		proc_listpgrppids: (pgid: number, buffer: number, byteLength: number) => number;
+		proc_pid_rusage: (pid: number, flavor: number, buffer: number) => number;
+	}>("libSystem.B.dylib", {
 		proc_listpgrppids: { args: [FFIType.i32, FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
 		proc_pid_rusage: { args: [FFIType.i32, FFIType.i32, FFIType.ptr], returns: FFIType.i32 },
 	});

package/src/kernels/shared/subprocess-kernel.ts

@@ -1,3 +1,4 @@
+// allow: SIZE_OK — subprocess protocol, FIFO ownership, retirement, and replacement form one serialized state machine.
 import type { HostToKernelMessage, KernelToHostMessage } from "../../bridge/protocol.ts";
 import { decodeBridgeFrame, encodeBridgeFrame, isKernelToHostMessage } from "../../bridge/protocol.ts";
 import type { KernelInterruptHandle, PendingCell } from "../../tool/types.ts";
@@ -7,6 +8,7 @@ import { applySessionEnvironment } from "../session-env.ts";
 import { describeExit } from "./kernel-death.ts";
 import { KernelMemoryHost } from "./kernel-memory-host.ts";
 import type { KernelResult, KernelRunInput, SubprocessKernelOptions, ToolCallMessage } from "./subprocess-contract.ts";
+import { SubprocessMemoryGlobals } from "./subprocess-memory-globals.ts";
 import { type SubprocessLike, SubprocessProcess, type SubprocessSpawn, spawnSubprocess } from "./subprocess-process.ts";
 import { SubprocessRunQueue } from "./subprocess-queue.ts";
 import {
@@ -39,6 +41,7 @@ export class SubprocessKernel {
 	private readonly onMessage?: (message: KernelToHostMessage) => void;
 	private readonly runs = new SubprocessRunQueue();
 	private readonly memory: KernelMemoryHost | null;
+	private readonly globals = new SubprocessMemoryGlobals();
 	private process: SubprocessProcess | null = null;
 	private processReady = false;
 	private startup: SubprocessStartupWatchdog | null = null;
@@ -90,8 +93,10 @@ export class SubprocessKernel {
 			this.runs.settleAll(new CellInterruptedError(reason));
 			return { stateRetained: Promise.resolve(true) };
 		}
+		if (this.globals.completeWithoutGlobals()) return { stateRetained: Promise.resolve(true) };
 		const process = this.process;
 		process?.retire();
+		this.globals.reset();
 		this.runs.clearToolCalls();
 		const run = this.runs.active;
 		if (!run) return { stateRetained: Promise.resolve(true) };
@@ -126,6 +131,7 @@ export class SubprocessKernel {
 
 	async reset(): Promise<void> {
 		if (this.closed) throw new KernelClosedError();
+		this.globals.reset();
 		this.settleAll(new KernelResetError());
 		this.runs.clearToolCalls();
 		await this.restartProcess(this.process);
@@ -135,6 +141,7 @@ export class SubprocessKernel {
 	async close(): Promise<void> {
 		const wasClosed = this.closed;
 		this.closed = true;
+		this.globals.reset();
 		this.startup?.stop();
 		if (!wasClosed) {
 			this.settleAll(new KernelClosingError());
@@ -175,6 +182,7 @@ export class SubprocessKernel {
 		if (this.runs.active !== run || run.settled) return;
 		const process = this.process;
 		process?.retire();
+		this.globals.reset();
 		this.runs.clearToolCalls();
 		this.runs.releaseActive(run);
 		this.runs.settle(run, timeoutResult(run, timeoutMs));
@@ -199,6 +207,7 @@ export class SubprocessKernel {
 			},
 		});
 		this.process = process;
+		this.globals.reset();
 		this.processReady = false;
 		this.startup?.stop();
 		const startup = this.options.startup;
@@ -237,6 +246,7 @@ export class SubprocessKernel {
 		if (!this.accepts(process)) return;
 		if (!this.processReady) this.startup?.observe(message);
 		if (message.type === "ready") {
+			this.globals.reset(message.memoryGlobals === true);
 			this.startup?.stop();
 			this.processReady = true;
 			this.runs.handleMessage(message, this.onMessage);
@@ -248,9 +258,23 @@ export class SubprocessKernel {
 			this.failClosed(new KernelStartupError(message.error.message));
 			return;
 		}
-		const ownResult = message.type === "result" && this.runs.active?.input.cellId === message.cellId;
-		const settled = ownResult && this.memory ? this.memory.annotate(message, process.child.pid) : message;
-		if (!this.runs.handleMessage(settled, this.onMessage)) return;
+		const run = this.runs.active;
+		if (message.type === "memory-globals-result") {
+			if (this.memory) this.globals.reply({ process, run }, message, this.memory);
+			return;
+		}
+		if (message.type === "result" && run?.input.cellId === message.cellId && this.memory) {
+			this.globals.request({ process, run, result: message }, this.memory, (result) => {
+				if (!this.accepts(process) || this.runs.active !== run || run.settled) return;
+				this.settleMessage(result);
+			});
+			return;
+		}
+		this.settleMessage(message);
+	}
+
+	private settleMessage(message: KernelToHostMessage): void {
+		if (!this.runs.handleMessage(message, this.onMessage)) return;
 		this.pumpRuns();
 		this.recycleOverCeilingWhenIdle();
 	}
@@ -270,6 +294,7 @@ export class SubprocessKernel {
 			return;
 		}
 		this.process = null;
+		this.globals.reset();
 		this.processReady = false;
 		const error = new KernelExitedError(signal ?? code ?? "unknown");
 		if (this.options.onDeath) this.die(error, describeExit(code, signal), this.options.onDeath);
@@ -362,6 +387,7 @@ export class SubprocessKernel {
 
 	private failClosed(error: Error): void {
 		this.startup?.stop();
+		this.globals.reset();
 		const process = this.process;
 		this.failure = error;
 		this.closed = true;

package/src/kernels/shared/subprocess-memory-globals.ts

@@ -0,0 +1,101 @@
+import type { KernelMemoryReport } from "../../bridge/memory-protocol.ts";
+import { encodeBridgeFrame, type KernelToHostMessage } from "../../bridge/protocol.ts";
+import type { KernelMemoryHost } from "./kernel-memory-host.ts";
+import type { KernelResult } from "./subprocess-contract.ts";
+import type { SubprocessProcess } from "./subprocess-process.ts";
+import type { PendingRun } from "./subprocess-run.ts";
+
+const GLOBALS_TIMEOUT_MS = 5_000;
+type GlobalsProcess = Pick<SubprocessProcess, "send"> & {
+	readonly child: { readonly pid?: number };
+};
+
+interface PendingGlobals {
+	readonly process: GlobalsProcess;
+	readonly run: PendingRun;
+	readonly result: KernelResult;
+	readonly report: KernelMemoryReport;
+	readonly memory: KernelMemoryHost;
+	readonly finish: (result: KernelResult) => void;
+	readonly timer: ReturnType<typeof setTimeout>;
+}
+
+/** Holds FIFO cell ownership until its bounded diagnostic is returned or its deadline expires. */
+export class SubprocessMemoryGlobals {
+	#pending: PendingGlobals | null = null;
+	#available = false;
+
+	reset(available = false): void {
+		if (this.#pending !== null) clearTimeout(this.#pending.timer);
+		this.#pending = null;
+		this.#available = available;
+	}
+
+	request(
+		owner: {
+			readonly process: GlobalsProcess;
+			readonly run: PendingRun;
+			readonly result: KernelResult;
+		},
+		memory: KernelMemoryHost,
+		finish: (result: KernelResult) => void,
+	): void {
+		if (this.#pending !== null) return;
+		const report = memory.readReport(owner.result, owner.process.child.pid);
+		if (!this.#available || report === undefined || !memory.needsGlobals(report)) {
+			finish(memory.annotateReport(owner.result, report));
+			return;
+		}
+		const pending: PendingGlobals = {
+			...owner,
+			report,
+			memory,
+			finish,
+			timer: setTimeout(() => {
+				if (this.#pending !== pending) return;
+				this.#pending = null;
+				pending.finish(memory.annotateReport(pending.result, report));
+			}, GLOBALS_TIMEOUT_MS),
+		};
+		this.#pending = pending;
+		owner.process.send(
+			encodeBridgeFrame({
+				type: "memory-globals",
+				cellId: owner.result.cellId,
+			}),
+		);
+	}
+
+	/** Settles an already-finished cell immediately when stop arrives during its optional diagnostic. */
+	completeWithoutGlobals(): boolean {
+		const pending = this.#pending;
+		if (pending === null) return false;
+		clearTimeout(pending.timer);
+		this.#pending = null;
+		pending.finish(pending.memory.annotateReport(pending.result, pending.report));
+		return true;
+	}
+
+	reply(
+		owner: {
+			readonly process: GlobalsProcess;
+			readonly run: PendingRun | null;
+		},
+		message: Extract<KernelToHostMessage, { type: "memory-globals-result" }>,
+		memory: KernelMemoryHost,
+	): void {
+		const pending = this.#pending;
+		if (
+			pending === null ||
+			pending.process !== owner.process ||
+			pending.run !== owner.run ||
+			pending.result.cellId !== message.cellId
+		)
+			return;
+		clearTimeout(pending.timer);
+		this.#pending = null;
+		const report = message.globals.length === 0 ? pending.report : { ...pending.report, globals: message.globals };
+		const result = memory.annotateReport(pending.result, report);
+		pending.finish(result);
+	}
+}

package/src/kernels/shared/subprocess-process.ts

@@ -1,9 +1,13 @@
 import { spawn as nodeSpawn } from "node:child_process";
 import { createInterface, type Interface as ReadlineInterface } from "node:readline";
+import { killWindowsTree } from "../js/windows-tree-kill-host.ts";
 
 export interface SubprocessLike {
 	readonly pid?: number;
-	readonly stdin: { write(chunk: string): unknown };
+	readonly stdin: {
+		write(chunk: string): unknown;
+		on?(event: "error", listener: (error: Error) => void): unknown;
+	};
 	readonly stdout: NodeJS.ReadableStream;
 	readonly stderr: NodeJS.ReadableStream;
 	on(event: "error", listener: (error: Error) => void): this;
@@ -46,11 +50,13 @@ export class SubprocessProcess {
 	private readonly stdoutReader: ReadlineInterface;
 	private readonly stderrListener: (chunk: string | Buffer) => void;
 	private readonly errorListener: (error: Error) => void;
+	private readonly stdinErrorListener: (error: Error) => void;
 	private exited = false;
 	private retiring = false;
 	private outputDetached = false;
 	private errorReported = false;
 	private terminationPromise: Promise<boolean> | null = null;
+	private windowsTreeKill: Promise<void> | undefined;
 
 	constructor(child: SubprocessLike, handlers: SubprocessProcessHandlers) {
 		this.child = child;
@@ -67,8 +73,16 @@ export class SubprocessProcess {
 		this.stdoutReader.on("line", (line) => {
 			if (!this.retiring) this.handlers.onLine(this, `${line}\n`);
 		});
+		// senpi#3016: a frame written while the child is dying fails on the stdin stream (EPIPE), which emits there
+		// and not on the ChildProcess. Unhandled, it is a process-level error that can end the host; once the child is
+		// gone or being retired the write failure carries no news, otherwise it is this process's error.
+		this.stdinErrorListener = (error) => {
+			if (this.exited || this.retiring) return;
+			this.errorListener(error);
+		};
 		child.stderr.on("data", this.stderrListener);
 		child.on("error", this.errorListener);
+		child.stdin.on?.("error", this.stdinErrorListener);
 		child.once("exit", (code, signal) => {
 			this.exited = true;
 			this.detachOutput();
@@ -83,7 +97,7 @@ export class SubprocessProcess {
 	}
 
 	send(frame: string): boolean {
-		if (this.retiring) return false;
+		if (this.retiring || this.exited) return false;
 		this.child.stdin.write(frame);
 		return true;
 	}
@@ -125,6 +139,8 @@ export class SubprocessProcess {
 		this.retire();
 		if (this.exited) return true;
 		this.kill(initialSignal);
+		// On Windows the kill first lists processes (up to 5 s); the exit wait starts once taskkill has run.
+		if (this.windowsTreeKill) await this.windowsTreeKill;
 		if (await this.waitForExit(escalationMs)) return true;
 		this.kill("SIGKILL");
 		return await this.waitForExit(forcedExitWaitMs);
@@ -151,6 +167,12 @@ export class SubprocessProcess {
 	}
 
 	private kill(signal: NodeJS.Signals): void {
+		if (globalThis.process.platform === "win32") {
+			// taskkill /F is already forced, so escalation reuses the first kill instead of listing again.
+			if (this.child.pid !== undefined) this.windowsTreeKill ??= killWindowsTree(this.child.pid);
+			else this.child.kill(signal);
+			return;
+		}
 		if (this.child.pid !== undefined) {
 			try {
 				globalThis.process.kill(-this.child.pid, signal);

package/src/kernels/shared/subprocess-queue.ts

@@ -120,6 +120,7 @@ export class SubprocessRunQueue {
 				return false;
 			case "webview-connect":
 			case "memory-query-result":
+			case "memory-globals-result":
 			case "kernel-tools-defined":
 				return false;
 			default: {

package/src/prompt/eval-prompt.ts

@@ -18,6 +18,8 @@ export interface EvalPromptParts {
 
 export interface EvalPromptOptions {
 	readonly spawns: boolean;
+	/** `prompt.advertiseHelpers`: true appends one pointer line to the helper documentation entry. */
+	readonly advertiseHelpers?: boolean;
 	/** Whether the session registry exposes the monitor tool through eval. */
 	readonly monitor?: boolean;
 	readonly spawnDefaultAgent?: string;
@@ -74,6 +76,10 @@ export function evalEmphasisStyle(modelId: string | undefined): EvalEmphasisStyl
 type ContextValue = string | boolean;
 type Context = Readonly<Record<string, ContextValue>>;
 
+/** The single line `prompt.advertiseHelpers: true` adds; off by default, so the default description is unchanged. */
+export const ADVERTISED_HELPERS_LINE =
+	"Advanced cell helpers (handle controls, wait(), kernel tools in workpools) are documented on demand: tool_schema('eval:helpers').";
+
 export function buildEvalPrompt(
 	enabled: EnabledLanguages,
 	options: EvalPromptOptions = { spawns: false },
@@ -104,9 +110,10 @@ export function buildEvalPrompt(
 		maxDetachedCells: String(options.maxDetachedCells ?? DEFAULT_MAX_DETACHED_CELLS),
 		kernelPreludeDocs: (options.kernelPreludes ?? []).map((prelude) => prelude.documentation).join("\n"),
 	};
-	const description = renderTemplate(EVAL_PROMPT_TEMPLATE, context)
+	const rendered = renderTemplate(EVAL_PROMPT_TEMPLATE, context)
 		.replace(/\n{3,}/g, "\n\n")
 		.trim();
+	const description = options.advertiseHelpers === true ? `${rendered}\n\n${ADVERTISED_HELPERS_LINE}` : rendered;
 	return {
 		description,
 		promptSnippet: "Run one incremental code cell in a persistent language kernel.",

package/src/tool/AGENTS.md

@@ -17,6 +17,7 @@ anchor most suites).
 | Code preview layout | `code-preview.ts` -> `display-code.ts` (JS: `display-js*.ts` Bun-only masked `Bun.Transpiler`; Python: `display-python*.ts` user interpreter, background + repaint) |
 | Status events, execution events | `status-events.ts`, `eval-execution-event.ts` |
 | Interrupt, capture | `interrupt-note.ts`, `call-capture.ts` |
+| Magic cells | `magic-cells.ts` (parsing), `magic-cell-host.ts` (`%pip`, `%bun`/`%npm`, `%environment`), `load-cell.ts` (`%load`); installs live in `../environments/` |
 
 ## CONVENTIONS
 

package/src/tool/cell-handler.ts

@@ -14,6 +14,7 @@ import { appendSchemaHint } from "../bridges/schema-hint.ts";
 import type { CompletionRequest, CompletionResult } from "../completion/handler.ts";
 import { handleCompletionToolCall } from "../completion/tool-bridge.ts";
 import type { ResolvedCodemodeSettings } from "../config/settings.ts";
+import type { PackagesInstallEnvironments } from "../environments/packages-install.ts";
 import type { HandleRegistry } from "../handles/handle-registry.ts";
 import type { KernelToolsCapability } from "../kernels/js/kernel-tools-types.ts";
 import {
@@ -54,6 +55,8 @@ export interface CellBridgeRuntime {
 	readonly handles?: HandleRegistry;
 	/** Absolute wall-clock deadline of this cell; a completion handle it creates is bounded by it. */
 	readonly hardDeadlineMs?: number;
+	/** A JS cell's session environment for `packages.install()`; Python cells reach theirs over the bridge. */
+	readonly environments?: PackagesInstallEnvironments;
 }
 
 export class CellHandler {

package/src/tool/cell-reserved-dispatch.ts

@@ -29,6 +29,7 @@ export function reservedDispatchContext(
 		marshalToolResult,
 		...(runtime.handles === undefined ? {} : { handles: runtime.handles }),
 		...(host === undefined ? {} : { evalHandleHost: host }),
+		...(runtime.environments === undefined ? {} : { environments: runtime.environments }),
 	};
 }
 

package/src/tool/cell-runtime.ts

@@ -219,8 +219,10 @@ export class CellResultBuilder {
 	}
 
 	#liveUpdateText(): string {
-		if (this.#state.status === "queued" && this.#state.queuedBehind?.length) {
-			return `queued behind ${this.#state.queuedBehind.join(", ")} in the ${this.#state.input.language} kernel`;
+		if (this.#state.status === "queued" && this.#state.queuedBehind !== undefined) {
+			return this.#state.queuedBehind.length === 0
+				? `waiting for the ${this.#state.input.language} kernel to be ready`
+				: `queued behind ${this.#state.queuedBehind.join(", ")} in the ${this.#state.input.language} kernel`;
 		}
 		const summary = this.#state.input.summary === undefined ? "" : ` ${this.#state.input.summary}`;
 		const output = this.#liveLines.text();

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

@@ -1,5 +1,6 @@
 import type { AgentToolResult } from "@code-yeongyu/senpi";
 import type { WakeSourceState } from "../extension/wake-source-state.ts";
+import type { EvalImageContent } from "./image-resize.ts";
 import type { EvalLanguage, EvalToolDetails } from "./types.ts";
 
 export type EvalDetachedCellState = "queued" | "running" | "detached" | "completed" | "failed" | "cancelled";
@@ -24,6 +25,8 @@ export interface EvalDetachedCellSnapshot {
 export interface EvalDetachedCellNotification {
 	readonly cellId: string;
 	readonly content: string;
+	/** Images the cell displayed, delivered with the notification the way a foreground result delivers them. */
+	readonly images?: readonly EvalImageContent[];
 }
 
 export interface EvalDetachedCellNotifier {

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

@@ -13,7 +13,7 @@ import type {
 	EvalDetachedCellSnapshot,
 	EvalDetachedCellStatusEntry,
 } from "./detached-cell-contract.ts";
-import { currentDetachedResult, detachedErrorResult, snapshotDetachedCell } from "./detached-cell-snapshot.ts";
+import { cancelledDetachedResult, detachedErrorResult, snapshotDetachedCell } from "./detached-cell-snapshot.ts";
 import {
 	activeDetachedCellReuseError,
 	allowsDetachedCellTransition,
@@ -36,7 +36,6 @@ export type {
 } from "./detached-cell-contract.ts";
 
 export class EvalDetachedCellManager {
-	readonly #artifactsDir: string | undefined;
 	readonly #onStatusChange: ((entries: readonly EvalDetachedCellStatusEntry[]) => void) | undefined;
 	readonly #onWakeSourceState: ((state: WakeSourceState) => void) | undefined;
 	readonly #cells = new Map<string, ManagedCell>();
@@ -49,7 +48,6 @@ export class EvalDetachedCellManager {
 	readonly #maxDetachedCells: number;
 
 	constructor(options: EvalDetachedCellManagerOptions = {}) {
-		this.#artifactsDir = options.artifactsDir;
 		this.#onStatusChange = options.onStatusChange;
 		this.#onWakeSourceState = options.onWakeSourceState;
 		this.#notificationQueue = new DetachedNotificationQueue(options.notifier);
@@ -85,7 +83,6 @@ export class EvalDetachedCellManager {
 		const cell = createManagedCell({
 			cellId,
 			input,
-			artifactsDir: this.#artifactsDir,
 			now: this.#now,
 			defaultHardLimitSeconds: this.#hardLimitSeconds,
 			defaultRunBudgetSeconds: this.#runBudgetSeconds,
@@ -239,7 +236,6 @@ export class EvalDetachedCellManager {
 						await cell.interruptOutcome?.promise;
 						return this.#snapshot(cell);
 					},
-					spillPath: cell.spillPath,
 				});
 			}
 		}
@@ -260,7 +256,7 @@ export class EvalDetachedCellManager {
 			return;
 		}
 		if (foreground) {
-			if (this.#settle(cell, "cancelled", currentDetachedResult(cell))) cell.onKill?.(expiry.error);
+			if (this.#settle(cell, "cancelled", cancelledDetachedResult(cell))) cell.onKill?.(expiry.error);
 			return;
 		}
 		await this.#cancel(cell, expiry.error.message);
@@ -269,7 +265,7 @@ export class EvalDetachedCellManager {
 	#cancelQueued(cell: ManagedCell, reason: string, error = new Error(reason)): void {
 		const dequeued = cell.kernel?.cancelQueued(cell.cellId, reason) ?? false;
 		cell.stateRetained = true;
-		this.#settle(cell, "cancelled", currentDetachedResult(cell));
+		this.#settle(cell, "cancelled", cancelledDetachedResult(cell));
 		// Acquisition/reset has no queue promise yet; its execution has no interrupt target either.
 		if (!dequeued) cell.onKill?.(error);
 	}
@@ -278,7 +274,7 @@ export class EvalDetachedCellManager {
 		const outcome = Promise.withResolvers<void>();
 		cell.interruptOutcome = outcome;
 		try {
-			if (!this.#settle(cell, "cancelled", currentDetachedResult(cell)) || cell.kernel === undefined) return;
+			if (!this.#settle(cell, "cancelled", cancelledDetachedResult(cell)) || cell.kernel === undefined) return;
 			const handle = await cell.kernel.interrupt(reason, cell.cellId);
 			cell.interruptNote = handle.note;
 			cell.stateRetained = await handle.stateRetained;