@sns-myagent/cli 0.2.0

package/src/eval/kernel-base.ts

@@ -0,0 +1,569 @@
+import { logger, Snowflake } from "@oh-my-pi/pi-utils";
+import type { Subprocess } from "bun";
+import { type KernelDisplayOutput, renderKernelDisplay } from "./py/display";
+
+export type KernelRuntimeEnv = Record<string, string | null>;
+
+export interface KernelExecuteOptions {
+	id?: string;
+	/** Runtime working directory applied immediately before this request executes. */
+	cwd?: string;
+	/** Managed runtime environment variables applied immediately before this request executes. */
+	env?: Record<string, string | undefined> | Record<string, string | null>;
+	signal?: AbortSignal;
+	onChunk?: (text: string) => Promise<void> | void;
+	onDisplay?: (output: KernelDisplayOutput) => Promise<void> | void;
+	timeoutMs?: number;
+	silent?: boolean;
+	storeHistory?: boolean;
+	allowStdin?: boolean;
+}
+
+export interface KernelExecuteResult {
+	status: "ok" | "error";
+	executionCount?: number;
+	error?: { name: string; value: string; traceback: string[] };
+	cancelled: boolean;
+	timedOut: boolean;
+	stdinRequested: boolean;
+	/**
+	 * True when the kernel subprocess was killed as part of settling this
+	 * execution (e.g. SIGINT was ignored and we escalated to shutdown, or the
+	 * kernel died unexpectedly). When false, the kernel remains reusable.
+	 */
+	kernelKilled?: boolean;
+}
+
+export interface KernelShutdownResult {
+	confirmed: boolean;
+}
+
+export interface KernelShutdownOptions {
+	signal?: AbortSignal;
+	timeoutMs?: number;
+}
+
+/** Per-language lifecycle configuration consumed by each kernel's `start()`. */
+export interface KernelStartOptions {
+	cwd: string;
+	env?: Record<string, string | undefined>;
+	/** Explicit interpreter path; skips discovery when set. */
+	interpreter?: string;
+	signal?: AbortSignal;
+	deadlineMs?: number;
+}
+
+/** Per-language configuration handed to {@link BaseKernel} by each subclass. */
+export interface BaseKernelOptions<TExecuteOptions extends KernelExecuteOptions = KernelExecuteOptions> {
+	/** Human-readable language label used in log messages and errors. */
+	languageName: string;
+	/** When true, every IPC frame is logged at debug level. */
+	traceIpc: boolean;
+	/** Wire payload asking the runner to exit cleanly. */
+	exitPayload: string;
+	/** How long to wait after SIGINT before escalating to subprocess termination. */
+	interruptEscalationMs: number;
+	/** Default grace period applied by {@link BaseKernel.shutdown}. */
+	shutdownGraceMs: number;
+	/** Serializes an execution request into the runner's wire protocol. */
+	buildPayload: (code: string, msgId: string, options?: TExecuteOptions) => string;
+}
+
+export type FrameType = "started" | "stdout" | "stderr" | "display" | "result" | "error" | "done";
+
+export interface Frame {
+	type: FrameType;
+	id?: string;
+	data?: string;
+	bundle?: Record<string, unknown>;
+	ename?: string;
+	evalue?: string;
+	traceback?: string[];
+	status?: "ok" | "error";
+	executionCount?: number;
+	cancelled?: boolean;
+}
+
+interface PendingExecution {
+	resolve: (result: KernelExecuteResult) => void;
+	options?: KernelExecuteOptions;
+	status: "ok" | "error";
+	executionCount?: number;
+	error?: { name: string; value: string; traceback: string[] };
+	cancelled: boolean;
+	timedOut: boolean;
+	stdinRequested: boolean;
+	kernelKilled: boolean;
+	settled: boolean;
+	escalationTimer?: NodeJS.Timeout;
+	finalize?: () => void;
+}
+
+export function getRemainingTimeMs(deadlineMs?: number): number | undefined {
+	if (deadlineMs === undefined) return undefined;
+	return Math.max(0, deadlineMs - Date.now());
+}
+
+export function createAbortError(name: "AbortError" | "TimeoutError", message: string): Error {
+	const err = new Error(message);
+	err.name = name;
+	return err;
+}
+
+export function throwIfAborted(signal: AbortSignal | undefined, fallbackReason: string): void {
+	if (!signal?.aborted) return;
+	const reason = signal.reason;
+	if (reason instanceof Error) throw reason;
+	throw createAbortError("AbortError", typeof reason === "string" ? reason : fallbackReason);
+}
+
+export function isTimeoutReason(reason: unknown): boolean {
+	if (reason instanceof DOMException) return reason.name === "TimeoutError";
+	if (reason instanceof Error) return reason.name === "TimeoutError";
+	return false;
+}
+
+/**
+ * Shared subprocess-backed kernel machinery for the language runners. Each
+ * language subclasses this, supplying its binary/runner via a static `start()`
+ * and its wire protocol via {@link BaseKernelOptions.buildPayload}. The IPC loop
+ * speaks NDJSON: the runner emits one JSON {@link Frame} per line; outbound
+ * requests are serialized by `buildPayload` (which may itself be NDJSON or any
+ * other line-delimited encoding).
+ *
+ * `TExecuteOptions` is the language's own execute-options type so each runner's
+ * `buildPayload` sees its precise option shape (e.g. environment-map variants).
+ */
+export abstract class BaseKernel<TExecuteOptions extends KernelExecuteOptions = KernelExecuteOptions> {
+	readonly id: string;
+	#proc: Subprocess | null = null;
+	#stdin: Bun.FileSink | null = null;
+	#alive = true;
+	#disposed = false;
+	#shutdownConfirmed = false;
+	#exitedPromise: Promise<number> | null = null;
+	#pending = new Map<string, PendingExecution>();
+	#readBuffer = "";
+	readonly #options: BaseKernelOptions<TExecuteOptions>;
+
+	constructor(id: string, options: BaseKernelOptions<TExecuteOptions>) {
+		this.id = id;
+		this.#options = options;
+	}
+
+	setProcess(proc: Subprocess<"pipe", "pipe", "pipe">) {
+		this.#proc = proc;
+		this.#stdin = proc.stdin;
+		this.#exitedPromise = proc.exited;
+		void this.#exitedPromise.then(code => {
+			this.#alive = false;
+			this.#abortPendingExecutions(`${this.#options.languageName} kernel exited with code ${code}`, {
+				kernelKilled: true,
+			});
+		});
+
+		this.#startReader(proc.stdout as ReadableStream<Uint8Array>);
+		this.#startStderrDrain(proc.stderr as ReadableStream<Uint8Array>);
+	}
+
+	isAlive(): boolean {
+		return this.#alive && !this.#disposed;
+	}
+
+	async execute(code: string, options?: TExecuteOptions): Promise<KernelExecuteResult> {
+		if (!this.isAlive()) {
+			throw new Error(`${this.#options.languageName} kernel is not running`);
+		}
+
+		const msgId = options?.id ?? Snowflake.next();
+		const { promise, resolve } = Promise.withResolvers<KernelExecuteResult>();
+		const pending: PendingExecution = {
+			resolve,
+			options,
+			status: "ok",
+			cancelled: false,
+			timedOut: false,
+			stdinRequested: false,
+			settled: false,
+			kernelKilled: false,
+		};
+		this.#pending.set(msgId, pending);
+
+		const finalize = () => {
+			if (pending.settled) return;
+			pending.settled = true;
+			this.#pending.delete(msgId);
+			cleanup();
+			resolve({
+				status: pending.status,
+				executionCount: pending.executionCount,
+				error: pending.error,
+				cancelled: pending.cancelled,
+				timedOut: pending.timedOut,
+				stdinRequested: pending.stdinRequested,
+				kernelKilled: pending.kernelKilled,
+			});
+		};
+
+		let requestWritten = false;
+		const requestCancel = () => {
+			if (pending.settled || pending.escalationTimer) return;
+			if (!requestWritten) {
+				finalize();
+				return;
+			}
+			void this.interrupt();
+			const escalation = setTimeout(() => {
+				if (pending.settled) return;
+				logger.warn(`${this.#options.languageName} runner did not respond to SIGINT; terminating subprocess`, {
+					kernelId: this.id,
+				});
+				pending.kernelKilled = true;
+				void this.shutdown();
+			}, this.#options.interruptEscalationMs);
+			escalation.unref?.();
+			pending.escalationTimer = escalation;
+		};
+
+		const onAbort = () => {
+			pending.cancelled = true;
+			pending.timedOut = pending.timedOut || isTimeoutReason(options?.signal?.reason);
+			requestCancel();
+		};
+		const timeoutId =
+			typeof options?.timeoutMs === "number" && options.timeoutMs > 0
+				? setTimeout(() => {
+						pending.timedOut = true;
+						pending.cancelled = true;
+						requestCancel();
+					}, options.timeoutMs)
+				: undefined;
+
+		const cleanup = () => {
+			clearTimeout(timeoutId);
+			clearTimeout(pending.escalationTimer);
+			pending.escalationTimer = undefined;
+			options?.signal?.removeEventListener("abort", onAbort);
+		};
+
+		if (options?.signal) {
+			if (options.signal.aborted) {
+				onAbort();
+			} else {
+				options.signal.addEventListener("abort", onAbort, { once: true });
+				if (options.signal.aborted) {
+					options.signal.removeEventListener("abort", onAbort);
+					onAbort();
+				}
+			}
+		}
+
+		pending.finalize = finalize;
+
+		const payload = this.#options.buildPayload(code, msgId, options);
+
+		if (pending.settled) {
+			return promise;
+		}
+
+		requestWritten = true;
+		try {
+			await this.#writeLine(payload);
+		} catch (err) {
+			pending.cancelled = true;
+			pending.error = {
+				name: "TransportError",
+				value: err instanceof Error ? err.message : String(err),
+				traceback: [],
+			};
+			finalize();
+		}
+
+		return promise;
+	}
+
+	async interrupt(): Promise<void> {
+		if (!this.#proc || this.#disposed) return;
+		try {
+			this.#proc.kill("SIGINT");
+		} catch (err) {
+			logger.warn(`Failed to interrupt ${this.#options.languageName.toLowerCase()} runner`, {
+				error: err instanceof Error ? err.message : String(err),
+			});
+		}
+	}
+
+	async shutdown(options?: KernelShutdownOptions): Promise<KernelShutdownResult> {
+		if (this.#shutdownConfirmed) return { confirmed: true };
+
+		this.#alive = false;
+		this.#abortPendingExecutions(`${this.#options.languageName} kernel shutdown`, { kernelKilled: true });
+
+		const timeoutMs = options?.timeoutMs ?? this.#options.shutdownGraceMs;
+		const proc = this.#proc;
+		if (!proc) {
+			this.#shutdownConfirmed = true;
+			this.#disposed = true;
+			return { confirmed: true };
+		}
+
+		try {
+			await this.#writeLine(this.#options.exitPayload).catch(() => {});
+		} catch {
+			/* writer may already be closed */
+		}
+
+		try {
+			this.#stdin?.end();
+		} catch {
+			/* ignore */
+		}
+
+		const exited = this.#waitForExitWithTimeout(timeoutMs);
+		let result = await exited;
+		if (!result) {
+			try {
+				proc.kill("SIGTERM");
+			} catch {
+				/* ignore */
+			}
+			result = await this.#waitForExitWithTimeout(timeoutMs);
+		}
+		if (!result) {
+			try {
+				proc.kill("SIGKILL");
+			} catch {
+				/* ignore */
+			}
+			result = await this.#waitForExitWithTimeout(timeoutMs);
+		}
+
+		const confirmed = !!result;
+		this.#shutdownConfirmed = confirmed;
+		this.#disposed = true;
+		return { confirmed };
+	}
+
+	#abortPendingExecutions(reason: string, options?: { kernelKilled?: boolean }): void {
+		if (this.#pending.size === 0) return;
+		const pending = Array.from(this.#pending.values());
+		this.#pending.clear();
+		const kernelKilledDefault = options?.kernelKilled ?? false;
+		for (const entry of pending) {
+			if (entry.settled) continue;
+			entry.settled = true;
+			void entry.options?.onChunk?.(`[kernel] ${reason}\n`);
+			entry.resolve({
+				status: "error",
+				cancelled: true,
+				timedOut: entry.timedOut,
+				stdinRequested: entry.stdinRequested,
+				executionCount: entry.executionCount,
+				error: entry.error,
+				kernelKilled: entry.kernelKilled || kernelKilledDefault,
+			});
+		}
+	}
+
+	async #writeLine(line: string): Promise<void> {
+		if (!this.#stdin) {
+			throw new Error(`${this.#options.languageName} kernel stdin is not open`);
+		}
+		if (this.#options.traceIpc) {
+			logger.debug(`${this.#options.languageName}Kernel send`, { preview: line.slice(0, 120) });
+		}
+		this.#stdin.write(`${line}\n`);
+		this.#stdin.flush();
+	}
+
+	#startReader(stream: ReadableStream<Uint8Array>): void {
+		const reader = stream.getReader();
+		const decoder = new TextDecoder();
+		const loop = async () => {
+			try {
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					this.#readBuffer += decoder.decode(value, { stream: true });
+					await this.#flushFrames();
+				}
+				this.#readBuffer += decoder.decode();
+				await this.#flushFrames();
+			} catch (err) {
+				logger.warn(`${this.#options.languageName} kernel reader failed`, {
+					error: err instanceof Error ? err.message : String(err),
+				});
+			} finally {
+				try {
+					reader.releaseLock();
+				} catch {
+					/* ignore */
+				}
+			}
+		};
+		void loop();
+	}
+
+	#startStderrDrain(stream: ReadableStream<Uint8Array>): void {
+		const reader = stream.getReader();
+		const decoder = new TextDecoder();
+		const loop = async () => {
+			try {
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					const text = decoder.decode(value);
+					if (text.trim()) {
+						logger.warn(`${this.#options.languageName} runner stderr`, { text });
+					}
+				}
+			} catch {
+				/* ignore */
+			} finally {
+				try {
+					reader.releaseLock();
+				} catch {
+					/* ignore */
+				}
+			}
+		};
+		void loop();
+	}
+
+	async #flushFrames(): Promise<void> {
+		while (true) {
+			const nl = this.#readBuffer.indexOf("\n");
+			if (nl < 0) return;
+			const line = this.#readBuffer.slice(0, nl);
+			this.#readBuffer = this.#readBuffer.slice(nl + 1);
+			if (!line.trim()) continue;
+			let frame: Frame;
+			try {
+				frame = JSON.parse(line) as Frame;
+			} catch (err) {
+				logger.warn(`${this.#options.languageName} runner emitted invalid JSON`, {
+					line: line.slice(0, 200),
+					error: err instanceof Error ? err.message : String(err),
+				});
+				continue;
+			}
+			if (this.#options.traceIpc) {
+				logger.debug(`${this.#options.languageName}Kernel recv`, { type: frame.type, id: frame.id });
+			}
+			await this.#handleFrame(frame);
+		}
+	}
+
+	async #handleFrame(frame: Frame): Promise<void> {
+		const rid = frame.id;
+		if (!rid) return;
+		const pending = this.#pending.get(rid);
+		if (!pending) return;
+
+		switch (frame.type) {
+			case "started":
+				return;
+			case "stdout":
+			case "stderr": {
+				const text = frame.data ?? "";
+				if (text && pending.options?.onChunk) {
+					await pending.options.onChunk(text);
+				}
+				return;
+			}
+			case "display":
+			case "result": {
+				const bundle = frame.bundle ?? {};
+				const { text, outputs } = await renderKernelDisplay(bundle);
+				if (text && pending.options?.onChunk) {
+					await pending.options.onChunk(text);
+				}
+				if (outputs.length > 0 && pending.options?.onDisplay) {
+					for (const output of outputs) {
+						await pending.options.onDisplay(output);
+					}
+				}
+				return;
+			}
+			case "error": {
+				const traceback = Array.isArray(frame.traceback) ? frame.traceback.map(String) : [];
+				pending.status = "error";
+				pending.error = {
+					name: String(frame.ename ?? "Error"),
+					value: String(frame.evalue ?? ""),
+					traceback,
+				};
+				const message =
+					traceback.length > 0 ? `${traceback.join("\n")}\n` : `${pending.error.name}: ${pending.error.value}\n`;
+				if (pending.options?.onChunk) {
+					await pending.options.onChunk(message);
+				}
+				return;
+			}
+			case "done": {
+				if (typeof frame.executionCount === "number") {
+					pending.executionCount = frame.executionCount;
+				}
+				if (frame.status === "error" && pending.status === "ok") {
+					pending.status = "error";
+				}
+				if (frame.cancelled) {
+					pending.cancelled = true;
+				}
+				pending.finalize?.();
+				return;
+			}
+		}
+	}
+
+	async executeWithBudget(
+		code: string,
+		signal: AbortSignal | undefined,
+		timeoutMs: number,
+		label: string,
+	): Promise<void> {
+		const controller = new AbortController();
+		const cleanups: Array<() => void> = [];
+		if (signal) {
+			if (signal.aborted) {
+				controller.abort(signal.reason);
+			} else {
+				const onAbort = () => controller.abort(signal.reason);
+				signal.addEventListener("abort", onAbort, { once: true });
+				cleanups.push(() => signal.removeEventListener("abort", onAbort));
+			}
+		}
+		const timer =
+			timeoutMs > 0
+				? setTimeout(() => controller.abort(createAbortError("TimeoutError", `${label} timed out`)), timeoutMs)
+				: undefined;
+		if (timer) cleanups.push(() => clearTimeout(timer));
+		try {
+			throwIfAborted(controller.signal, label);
+			const result = await this.execute(code, {
+				signal: controller.signal,
+				silent: true,
+				storeHistory: false,
+			} as TExecuteOptions);
+			if (result.cancelled) {
+				throw createAbortError(result.timedOut ? "TimeoutError" : "AbortError", `${label} cancelled`);
+			}
+			if (result.status === "error") {
+				const reason = result.error?.value ?? `${this.#options.languageName} kernel init failed`;
+				throw new Error(`${label} failed: ${reason}`);
+			}
+		} finally {
+			for (const cleanup of cleanups) cleanup();
+		}
+	}
+
+	#waitForExitWithTimeout(timeoutMs: number): Promise<number | null> {
+		if (!this.#exitedPromise) return Promise.resolve(0);
+		const exitedPromise = this.#exitedPromise;
+		const timeout = new Promise<null>(resolve => {
+			const timer = setTimeout(() => resolve(null), Math.max(0, timeoutMs));
+			timer.unref?.();
+		});
+		return Promise.race([exitedPromise.then(code => code as number | null), timeout]);
+	}
+}

package/src/eval/py/__tests__/prelude.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "bun:test";
+import { PYTHON_PRELUDE } from "../prelude";
+
+describe("python prelude", () => {
+	it("exposes read(path, offset?, limit?) with positional optional args", () => {
+		// The eval docs advertise `read(path, offset?=1, limit?=None)`. A
+		// keyword-only signature (`def read(path, *, offset=1, limit=None)`)
+		// makes `read("file", 10)` raise `TypeError: read() takes 1 positional
+		// argument but 2 were given`, which agents in the wild repeatedly hit.
+		// Lock the contract so the helper accepts both positional and keyword
+		// forms.
+		const match = PYTHON_PRELUDE.match(/def\s+read\(([^)]+)\)/);
+		expect(match).not.toBeNull();
+		const signature = match?.[1] ?? "";
+		expect(signature).not.toContain("*,");
+		expect(signature).toContain("offset");
+		expect(signature).toContain("limit");
+	});
+});

package/src/eval/py/display.ts

@@ -0,0 +1,71 @@
+/**
+ * Display bundle rendering shared between the Python runner output and the
+ * legacy Jupyter MIME conventions. Pure function, no kernel coupling.
+ */
+import { htmlToBasicMarkdown } from "../../web/scrapers/types";
+
+/** Status event emitted by prelude helpers for TUI rendering. */
+export interface PythonStatusEvent {
+	/** Operation name (e.g., "find", "read", "write") */
+	op: string;
+	/** Additional data fields (count, path, pattern, etc.) */
+	[key: string]: unknown;
+}
+
+export type KernelDisplayOutput =
+	| { type: "json"; data: unknown }
+	| { type: "image"; data: string; mimeType: string }
+	| { type: "markdown" }
+	| { type: "status"; event: PythonStatusEvent };
+
+function normalizeDisplayText(text: string): string {
+	return text.endsWith("\n") ? text : `${text}\n`;
+}
+
+/** Render a MIME bundle into text + structured outputs. */
+export async function renderKernelDisplay(content: Record<string, unknown>): Promise<{
+	text: string;
+	outputs: KernelDisplayOutput[];
+}> {
+	// Accept both raw bundles ({"text/plain": ...}) and Jupyter-style
+	// content envelopes ({ data: {...} }) so callers don't need to unwrap.
+	const data =
+		(content.data as Record<string, unknown> | undefined) ?? (content as Record<string, unknown> | undefined);
+	if (!data) return { text: "", outputs: [] };
+
+	const outputs: KernelDisplayOutput[] = [];
+
+	// Status events bypass the text path entirely — they exist only for TUI hooks.
+	if (data["application/x-omp-status"] !== undefined) {
+		const statusData = data["application/x-omp-status"];
+		if (statusData && typeof statusData === "object" && "op" in statusData) {
+			outputs.push({ type: "status", event: statusData as PythonStatusEvent });
+		}
+		return { text: "", outputs };
+	}
+
+	if (typeof data["image/png"] === "string") {
+		outputs.push({ type: "image", data: data["image/png"] as string, mimeType: "image/png" });
+	}
+	if (typeof data["image/jpeg"] === "string") {
+		outputs.push({ type: "image", data: data["image/jpeg"] as string, mimeType: "image/jpeg" });
+	}
+	if (data["application/json"] !== undefined) {
+		outputs.push({ type: "json", data: data["application/json"] });
+	}
+
+	// text/markdown takes precedence over text/plain (Markdown objects expose both
+	// where text/plain is just the repr).
+	if (typeof data["text/markdown"] === "string") {
+		outputs.push({ type: "markdown" });
+		return { text: normalizeDisplayText(String(data["text/markdown"])), outputs };
+	}
+	if (typeof data["text/plain"] === "string") {
+		return { text: normalizeDisplayText(String(data["text/plain"])), outputs };
+	}
+	if (data["text/html"] !== undefined) {
+		const markdown = (await htmlToBasicMarkdown(String(data["text/html"]))) || "";
+		return { text: markdown ? normalizeDisplayText(markdown) : "", outputs };
+	}
+	return { text: "", outputs };
+}