@wahack/pi-coding-agent 15.11.0

package/src/eval/py/runtime.ts

@@ -0,0 +1,276 @@
+/**
+ * Python runtime resolution utilities.
+ *
+ * Centralizes environment filtering, venv detection, and Python executable resolution
+ * for both the shared gateway and local kernel spawning.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { $env, $which, getPythonEnvDir } from "@oh-my-pi/pi-utils";
+
+const DEFAULT_ENV_ALLOWLIST = new Set([
+	"PATH",
+	"HOME",
+	"USER",
+	"LOGNAME",
+	"SHELL",
+	"LANG",
+	"LC_ALL",
+	"LC_CTYPE",
+	"LC_MESSAGES",
+	"TERM",
+	"TERM_PROGRAM",
+	"TERM_PROGRAM_VERSION",
+	"TMPDIR",
+	"TEMP",
+	"TMP",
+	"XDG_CACHE_HOME",
+	"XDG_CONFIG_HOME",
+	"XDG_DATA_HOME",
+	"XDG_RUNTIME_DIR",
+	"SSH_AUTH_SOCK",
+	"SSH_AGENT_PID",
+	"CONDA_PREFIX",
+	"CONDA_DEFAULT_ENV",
+	"VIRTUAL_ENV",
+	"PYTHONPATH",
+	"LD_LIBRARY_PATH",
+]);
+
+const WINDOWS_ENV_ALLOWLIST = new Set([
+	"APPDATA",
+	"COMPUTERNAME",
+	"COMSPEC",
+	"HOMEDRIVE",
+	"HOMEPATH",
+	"LOCALAPPDATA",
+	"NUMBER_OF_PROCESSORS",
+	"OS",
+	"PATH",
+	"PATHEXT",
+	"PROCESSOR_ARCHITECTURE",
+	"PROCESSOR_IDENTIFIER",
+	"PROGRAMDATA",
+	"PROGRAMFILES",
+	"PROGRAMFILES(X86)",
+	"PROGRAMW6432",
+	"SESSIONNAME",
+	"SYSTEMDRIVE",
+	"SYSTEMROOT",
+	"TEMP",
+	"TMP",
+	"USERDOMAIN",
+	"USERDOMAIN_ROAMINGPROFILE",
+	"USERPROFILE",
+	"USERNAME",
+	"WINDIR",
+]);
+
+const DEFAULT_ENV_DENYLIST = new Set([
+	"OPENAI_API_KEY",
+	"ANTHROPIC_API_KEY",
+	"GOOGLE_API_KEY",
+	"GEMINI_API_KEY",
+	"OPENROUTER_API_KEY",
+	"PERPLEXITY_API_KEY",
+	"PERPLEXITY_COOKIES",
+	"EXA_API_KEY",
+	"AZURE_OPENAI_API_KEY",
+	"MISTRAL_API_KEY",
+]);
+
+const DEFAULT_ENV_ALLOW_PREFIXES = ["LC_", "XDG_", "PI_"];
+
+const CASE_INSENSITIVE_ENV = process.platform === "win32";
+const BASE_ENV_ALLOWLIST = new Set([...DEFAULT_ENV_ALLOWLIST, ...WINDOWS_ENV_ALLOWLIST]);
+
+const NORMALIZED_ALLOWLIST = new Set(
+	Array.from(BASE_ENV_ALLOWLIST, key => (CASE_INSENSITIVE_ENV ? key.toUpperCase() : key)),
+);
+const NORMALIZED_DENYLIST = new Set(
+	Array.from(DEFAULT_ENV_DENYLIST, key => (CASE_INSENSITIVE_ENV ? key.toUpperCase() : key)),
+);
+const NORMALIZED_ALLOW_PREFIXES = CASE_INSENSITIVE_ENV
+	? DEFAULT_ENV_ALLOW_PREFIXES.map(prefix => prefix.toUpperCase())
+	: DEFAULT_ENV_ALLOW_PREFIXES;
+
+function normalizeEnvKey(key: string): string {
+	return CASE_INSENSITIVE_ENV ? key.toUpperCase() : key;
+}
+
+function resolvePathKey(env: Record<string, string | undefined>): string {
+	if (!CASE_INSENSITIVE_ENV) return "PATH";
+	const match = Object.keys(env).find(candidate => candidate.toLowerCase() === "path");
+	return match ?? "PATH";
+}
+
+function resolveManagedPythonEnv(): string {
+	return getPythonEnvDir();
+}
+
+function resolveManagedPythonCandidate(): { venvPath: string; pythonPath: string } {
+	const venvPath = resolveManagedPythonEnv();
+	const binDir = process.platform === "win32" ? path.join(venvPath, "Scripts") : path.join(venvPath, "bin");
+	const pythonPath = path.join(binDir, process.platform === "win32" ? "python.exe" : "python");
+	return { venvPath, pythonPath };
+}
+
+export interface PythonRuntime {
+	/** Path to python executable */
+	pythonPath: string;
+	/** Filtered environment variables */
+	env: Record<string, string | undefined>;
+	/** Path to virtual environment, if detected */
+	venvPath?: string;
+}
+
+/**
+ * Filter environment variables to a safe allowlist for Python subprocesses.
+ * Removes sensitive API keys and limits to known-safe variables.
+ */
+export function filterEnv(env: Record<string, string | undefined>): Record<string, string | undefined> {
+	const filtered: Record<string, string | undefined> = {};
+	for (const [key, value] of Object.entries(env)) {
+		if (value === undefined) continue;
+		const normalizedKey = normalizeEnvKey(key);
+		if (NORMALIZED_DENYLIST.has(normalizedKey)) continue;
+		if (NORMALIZED_ALLOWLIST.has(normalizedKey)) {
+			const destKey = normalizedKey === "PATH" ? "PATH" : key;
+			filtered[destKey] = value;
+			continue;
+		}
+		if (NORMALIZED_ALLOW_PREFIXES.some(prefix => normalizedKey.startsWith(prefix))) {
+			filtered[key] = value;
+		}
+	}
+	return filtered;
+}
+
+/**
+ * Detect virtual environment path from VIRTUAL_ENV or common locations.
+ */
+export function resolveVenvPath(cwd: string): string | undefined {
+	if ($env.VIRTUAL_ENV) return $env.VIRTUAL_ENV;
+	if ($env.CONDA_PREFIX) return $env.CONDA_PREFIX;
+	const candidates = [path.join(cwd, ".venv"), path.join(cwd, "venv")];
+	for (const candidate of candidates) {
+		if (fs.existsSync(candidate)) {
+			return candidate;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Apply a venv-style PATH/VIRTUAL_ENV layout onto a fresh copy of `baseEnv` for
+ * the interpreter living in `binDir`.
+ */
+function applyVenvEnv(
+	baseEnv: Record<string, string | undefined>,
+	venvPath: string,
+	binDir: string,
+): Record<string, string | undefined> {
+	const env = { ...baseEnv };
+	env.VIRTUAL_ENV = venvPath;
+	const pathKey = resolvePathKey(env);
+	const currentPath = env[pathKey];
+	env[pathKey] = currentPath ? `${binDir}${path.delimiter}${currentPath}` : binDir;
+	return env;
+}
+
+function venvBinDir(venvPath: string): string {
+	return process.platform === "win32" ? path.join(venvPath, "Scripts") : path.join(venvPath, "bin");
+}
+
+function detectExplicitVenv(pythonPath: string): { venvPath: string; binDir: string } | undefined {
+	const binDir = path.dirname(pythonPath);
+	const venvPath = path.dirname(binDir);
+	if (fs.existsSync(path.join(venvPath, "pyvenv.cfg"))) {
+		return { venvPath, binDir };
+	}
+	return undefined;
+}
+
+/**
+ * Resolve an explicitly configured interpreter (`python.interpreter`) into a
+ * runtime, bypassing discovery. Does not probe or validate the executable —
+ * callers must check it actually runs. `~` expands to the home directory and
+ * relative paths resolve against `cwd`. When the interpreter sits inside a
+ * virtualenv (a `pyvenv.cfg` above its bin dir), the venv activation env is
+ * applied so subprocesses and `pip` resolve consistently.
+ */
+export function resolveExplicitPythonRuntime(
+	interpreter: string,
+	cwd: string,
+	baseEnv: Record<string, string | undefined>,
+): PythonRuntime {
+	const expanded =
+		interpreter === "~"
+			? os.homedir()
+			: interpreter.startsWith("~/")
+				? path.join(os.homedir(), interpreter.slice(2))
+				: interpreter;
+	const pythonPath = path.isAbsolute(expanded) ? expanded : path.resolve(cwd, expanded);
+	const venv = detectExplicitVenv(pythonPath);
+	if (venv) {
+		return { pythonPath, env: applyVenvEnv(baseEnv, venv.venvPath, venv.binDir), venvPath: venv.venvPath };
+	}
+	return { pythonPath, env: { ...baseEnv } };
+}
+
+/**
+ * Enumerate candidate Python runtimes in priority order: an active/project venv,
+ * the managed `~/.omp/python-env`, then the system interpreter on PATH. Every
+ * candidate that physically exists is returned so callers can probe each in turn
+ * rather than committing to the first — a managed env left behind by a removed
+ * `uv` install no longer shadows a working system Python.
+ */
+export function enumeratePythonRuntimes(cwd: string, baseEnv: Record<string, string | undefined>): PythonRuntime[] {
+	const runtimes: PythonRuntime[] = [];
+	const seen = new Set<string>();
+	const push = (runtime: PythonRuntime): void => {
+		if (seen.has(runtime.pythonPath)) return;
+		seen.add(runtime.pythonPath);
+		runtimes.push(runtime);
+	};
+
+	const venvPath = baseEnv.VIRTUAL_ENV ?? resolveVenvPath(cwd);
+	if (venvPath) {
+		const binDir = venvBinDir(venvPath);
+		const pythonCandidate = path.join(binDir, process.platform === "win32" ? "python.exe" : "python");
+		if (fs.existsSync(pythonCandidate)) {
+			push({ pythonPath: pythonCandidate, env: applyVenvEnv(baseEnv, venvPath, binDir), venvPath });
+		}
+	}
+
+	const managed = resolveManagedPythonCandidate();
+	if (fs.existsSync(managed.pythonPath)) {
+		const managedBin = path.dirname(managed.pythonPath);
+		push({
+			pythonPath: managed.pythonPath,
+			env: applyVenvEnv(baseEnv, managed.venvPath, managedBin),
+			venvPath: managed.venvPath,
+		});
+	}
+
+	const systemPath = $which("python") ?? $which("python3");
+	if (systemPath) {
+		push({ pythonPath: systemPath, env: { ...baseEnv } });
+	}
+
+	return runtimes;
+}
+
+/**
+ * Resolve the highest-priority Python runtime. Prefer {@link enumeratePythonRuntimes}
+ * when you can probe candidates; this returns only the first one and throws when
+ * no interpreter exists.
+ */
+export function resolvePythonRuntime(cwd: string, baseEnv: Record<string, string | undefined>): PythonRuntime {
+	const [runtime] = enumeratePythonRuntimes(cwd, baseEnv);
+	if (!runtime) {
+		throw new Error("Python executable not found on PATH");
+	}
+	return runtime;
+}

package/src/eval/py/spawn-options.ts

@@ -0,0 +1,126 @@
+/**
+ * Subprocess spawn-option helpers for the Python kernel.
+ *
+ * Pure helpers (`shouldHideKernelWindow`, `consoleAttachedViaTTY`) live here
+ * so they can be unit-tested without dragging in the kernel's runtime
+ * dependencies. The effectful `hostHasInheritableConsole` wraps a Win32 FFI
+ * probe with a TTY fallback and is the function `kernel.ts` actually calls.
+ */
+import { dlopen, FFIType } from "bun:ffi";
+
+/**
+ * Decide whether the long-lived Python kernel subprocess should be spawned
+ * with `windowsHide: true`.
+ *
+ * On Windows, Bun maps `windowsHide: true` to the `CREATE_NO_WINDOW` flag,
+ * which detaches the child from any inherited console. The Python kernel
+ * runs user code that imports NumPy/pandas; those native extensions
+ * (`numpy/_core/_multiarray_umath.pyd` + bundled OpenBLAS/SLEEF thread-pool
+ * init) can deadlock inside `LoadLibraryExW` when no console is attached,
+ * and a console-less child cannot receive SIGINT via
+ * `GenerateConsoleCtrlEvent` (the recovery path the host relies on). See
+ * issue #1960.
+ *
+ * So on Windows we hide only when the host itself has no console to share.
+ * In any launch where a console is attached — even one with every stdio
+ * stream redirected — the kernel inherits the parent's console, matching
+ * `python.exe` invoked from `cmd.exe`, which keeps native imports and
+ * SIGINT recovery working.
+ *
+ * Short-lived helper subprocesses elsewhere in the codebase (LSP probes,
+ * git, plugin installs) keep `windowsHide: true` because they don't load
+ * complex native modules and the brief console flash would be user-visible
+ * noise.
+ */
+export function shouldHideKernelWindow(opts: {
+	platform: NodeJS.Platform;
+	hostHasInheritableConsole: boolean;
+}): boolean {
+	if (opts.platform !== "win32") return false;
+	return !opts.hostHasInheritableConsole;
+}
+
+/**
+ * TTY-based fallback used when the Win32 console probe is unavailable.
+ *
+ * Returns `true` if any of stdin/stdout/stderr is currently a TTY. This
+ * correctly detects the common interactive launches and the partial-
+ * redirection cases (`omp -p > out.txt`, `< in.txt`, `2> err.log`) where at
+ * least one stream stays bound to the terminal. The all-stdio-redirected
+ * case (`< in > out 2> err` from a console) is the reason we prefer the
+ * Win32 probe over this fallback whenever possible.
+ */
+export function consoleAttachedViaTTY(opts: {
+	stdinIsTTY: boolean;
+	stdoutIsTTY: boolean;
+	stderrIsTTY: boolean;
+}): boolean {
+	return opts.stdinIsTTY || opts.stdoutIsTTY || opts.stderrIsTTY;
+}
+
+/**
+ * Probe `kernel32.dll!GetConsoleWindow()` to detect whether the current
+ * Windows process owns a console window.
+ *
+ * Returns `true` for a non-NULL HWND, `false` when NULL (no console — true
+ * service / `DETACHED_PROCESS` / GUI parent), and `null` when the probe
+ * itself fails (off-Windows, FFI disabled, or unexpected kernel32 layout).
+ * A `null` return means "don't trust me, use the TTY fallback".
+ *
+ * Cached on first call because in practice the console attachment of a
+ * long-lived OMP host never changes for the lifetime of the process, and
+ * we don't want to re-dlopen kernel32 on every kernel spawn.
+ */
+type ConsoleProbeResult = boolean | null;
+let cachedWindowsConsoleProbe: { value: ConsoleProbeResult } | undefined;
+
+function probeWindowsConsoleWindow(): ConsoleProbeResult {
+	if (cachedWindowsConsoleProbe) return cachedWindowsConsoleProbe.value;
+	let value: ConsoleProbeResult = null;
+	try {
+		const lib = dlopen("kernel32.dll", {
+			GetConsoleWindow: { args: [], returns: FFIType.ptr },
+		});
+		try {
+			const hwnd = lib.symbols.GetConsoleWindow();
+			// FFIType.ptr returns `Pointer | null`; a 0 pointer should also be
+			// treated as NULL defensively in case Bun ever returns 0n / 0.
+			value = hwnd !== null && hwnd !== 0;
+		} finally {
+			lib.close();
+		}
+	} catch {
+		value = null;
+	}
+	cachedWindowsConsoleProbe = { value };
+	return value;
+}
+
+/** Reset the cached Win32 probe result. Test-only; not part of the public surface. */
+export function __resetWindowsConsoleProbeCache(): void {
+	cachedWindowsConsoleProbe = undefined;
+}
+
+/**
+ * Whether the host process owns a console its children can inherit.
+ *
+ * - On Windows, the authoritative signal is `GetConsoleWindow()`. It returns
+ *   a non-NULL HWND whenever the process has a console attached, regardless
+ *   of how the standard streams are redirected — so an `omp -p ... < in.txt
+ *   > out.txt 2> err.log` launched from a real Windows Terminal session is
+ *   correctly classified as console-attached and the kernel keeps its
+ *   inheritable console.
+ * - On any other platform, or if the FFI probe fails, fall back to the
+ *   TTY-OR heuristic. That still catches the common interactive cases.
+ */
+export function hostHasInheritableConsole(): boolean {
+	if (process.platform === "win32") {
+		const native = probeWindowsConsoleWindow();
+		if (native !== null) return native;
+	}
+	return consoleAttachedViaTTY({
+		stdinIsTTY: !!process.stdin.isTTY,
+		stdoutIsTTY: !!process.stdout.isTTY,
+		stderrIsTTY: !!process.stderr.isTTY,
+	});
+}

package/src/eval/py/tool-bridge.ts

@@ -0,0 +1,182 @@
+/**
+ * HTTP loopback bridge that lets the Python kernel synchronously invoke
+ * host-side tools by name, mirroring the JS worker's `tool.<name>(args)` proxy.
+ *
+ * The Python prelude builds a `tool` proxy that POSTs to `/v1/tool` over a
+ * 127.0.0.1 loopback socket; the host resolves the request against the
+ * `ToolSession` registered for the current execution and forwards to the same
+ * `callSessionTool` implementation the JS bridge uses.
+ */
+import { logger } from "@oh-my-pi/pi-utils";
+import type { ToolSession } from "../../tools";
+import { callSessionTool, type JsStatusEvent } from "../js/tool-bridge";
+
+export interface PyToolBridgeEntry {
+	toolSession: ToolSession;
+	signal?: AbortSignal;
+	emitStatus?: (event: JsStatusEvent) => void;
+}
+
+export interface PyToolBridgeInfo {
+	url: string;
+	token: string;
+}
+
+interface BridgeServer {
+	info: PyToolBridgeInfo;
+	stop: () => Promise<void>;
+}
+
+const registrations = new Map<string, PyToolBridgeEntry>();
+let serverPromise: Promise<BridgeServer> | null = null;
+
+/**
+ * Forward a bridge call to {@link callSessionTool}, but resolve the HTTP request
+ * the instant the cell's signal aborts instead of waiting for the tool/subagent
+ * to fully tear down.
+ *
+ * The kernel invokes this bridge with a *blocking* `urllib` request from a
+ * worker thread (each `agent()` / `tool.*` call). When the cell is interrupted,
+ * `parallel()`'s `ThreadPoolExecutor.__exit__` joins those worker threads
+ * (`shutdown(wait=True)`), so they cannot unwind until their `urllib` call
+ * returns — i.e. until this handler responds. A host-side `agent()` teardown
+ * (aborting nested LLM streams + tools across a wide fan-out) routinely exceeds
+ * the kernel's SIGINT escalation window, so the kernel was hard-killed and its
+ * persistent state lost while the subagents were still winding down. Responding
+ * immediately on abort lets the kernel raise through the blocked call and settle
+ * cleanly (preserving state); the already-signaled call keeps tearing down in
+ * the background, its eventual result/rejection swallowed.
+ */
+async function callSessionToolPromptOnAbort(name: string, args: unknown, entry: PyToolBridgeEntry): Promise<unknown> {
+	const call = callSessionTool(name, args, {
+		session: entry.toolSession,
+		signal: entry.signal,
+		emitStatus: entry.emitStatus,
+	});
+	const signal = entry.signal;
+	if (!signal) return await call;
+	if (signal.aborted) {
+		void call.catch(() => {});
+		throw new Error(`bridge call ${JSON.stringify(name)} aborted: eval cell was interrupted`);
+	}
+	const { promise: aborted, reject } = Promise.withResolvers<never>();
+	const onAbort = () => reject(new Error(`bridge call ${JSON.stringify(name)} aborted: eval cell was interrupted`));
+	signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		return await Promise.race([call, aborted]);
+	} finally {
+		signal.removeEventListener("abort", onAbort);
+		// `call` may still be settling (subagent teardown after its own abort);
+		// swallow its outcome so an abort-won race can't surface as unhandled.
+		void call.catch(() => {});
+	}
+}
+
+async function startServer(): Promise<BridgeServer> {
+	const token = crypto.randomUUID();
+	const server = Bun.serve({
+		hostname: "127.0.0.1",
+		port: 0,
+		async fetch(req) {
+			const url = new URL(req.url);
+			if (req.method !== "POST" || url.pathname !== "/v1/tool") {
+				return new Response("Not Found", { status: 404 });
+			}
+			if (req.headers.get("authorization") !== `Bearer ${token}`) {
+				return new Response("Forbidden", { status: 403 });
+			}
+
+			let body: { session?: unknown; run?: unknown; name?: unknown; args?: unknown };
+			try {
+				body = (await req.json()) as { session?: unknown; run?: unknown; name?: unknown; args?: unknown };
+			} catch {
+				return Response.json({ ok: false, error: "Invalid JSON body" }, { status: 400 });
+			}
+			const sessionId = typeof body.session === "string" ? body.session : "";
+			const runId = typeof body.run === "string" ? body.run : "";
+			const name = typeof body.name === "string" ? body.name : "";
+			if (!sessionId || !runId || !name) {
+				return Response.json({ ok: false, error: "Missing session/run/name" }, { status: 400 });
+			}
+			const registrationKey = bridgeRegistrationKey(sessionId, runId);
+			const entry = registrations.get(registrationKey) ?? registrations.get(sessionId);
+			if (!entry) {
+				return Response.json(
+					{ ok: false, error: `No active Python tool bridge session: ${registrationKey}` },
+					{ status: 200 },
+				);
+			}
+
+			try {
+				const value = await callSessionToolPromptOnAbort(name, body.args, entry);
+				return Response.json({ ok: true, value });
+			} catch (err) {
+				return Response.json({
+					ok: false,
+					error: err instanceof Error ? err.message : String(err),
+				});
+			}
+		},
+	});
+
+	const info: PyToolBridgeInfo = {
+		url: `http://${server.hostname}:${server.port}`,
+		token,
+	};
+	logger.debug("Python tool bridge listening", { url: info.url });
+
+	return {
+		info,
+		stop: async () => {
+			await server.stop(true);
+		},
+	};
+}
+
+/** Starts the bridge server lazily and returns its connection info. */
+export async function ensurePyToolBridge(): Promise<PyToolBridgeInfo> {
+	if (!serverPromise) {
+		serverPromise = startServer();
+	}
+	try {
+		const server = await serverPromise;
+		return server.info;
+	} catch (err) {
+		serverPromise = null;
+		throw err;
+	}
+}
+
+/**
+ * Register a tool session for the duration of one execution. The returned
+ * function MUST be called to remove the entry once execution finishes.
+ */
+function bridgeRegistrationKey(sessionId: string, runId: string): string {
+	return `${sessionId}:${runId}`;
+}
+
+export function registerPyToolBridge(sessionId: string, runId: string, entry: PyToolBridgeEntry): () => void {
+	const key = bridgeRegistrationKey(sessionId, runId);
+	registrations.set(key, entry);
+	return () => {
+		if (registrations.get(key) === entry) {
+			registrations.delete(key);
+		}
+	};
+}
+
+/** Stop the bridge and clear registrations. Test-only / shutdown helper. */
+export async function disposePyToolBridge(): Promise<void> {
+	registrations.clear();
+	const pending = serverPromise;
+	serverPromise = null;
+	if (!pending) return;
+	try {
+		const server = await pending;
+		await server.stop();
+	} catch (err) {
+		logger.debug("Failed to stop Python tool bridge", {
+			error: err instanceof Error ? err.message : String(err),
+		});
+	}
+}

package/src/eval/session-id.ts

@@ -0,0 +1,8 @@
+import type { ToolSession } from "../tools";
+
+export type EvalSessionSource = Pick<ToolSession, "cwd" | "getSessionFile">;
+
+export function defaultEvalSessionId(session: EvalSessionSource): string {
+	const sessionFile = session.getSessionFile?.() ?? undefined;
+	return sessionFile ? `session:${sessionFile}:cwd:${session.cwd}` : `cwd:${session.cwd}`;
+}

package/src/eval/types.ts

@@ -0,0 +1,48 @@
+/** Runtime backend that an eval cell dispatches to. */
+export type EvalLanguage = "python" | "js";
+
+import type { ImageContent } from "@oh-my-pi/pi-ai";
+import type { OutputMeta } from "../tools/output-meta";
+
+/** Status event emitted by prelude helpers (python or js) for TUI rendering. */
+export interface EvalStatusEvent {
+	op: string;
+	[key: string]: unknown;
+}
+
+/** Display output captured during eval execution. Union of python and js shapes. */
+export type EvalDisplayOutput =
+	| { type: "json"; data: unknown }
+	| { type: "image"; data: string; mimeType: string }
+	| { type: "markdown"; text?: string }
+	| { type: "status"; event: EvalStatusEvent };
+
+/** Per-cell execution result for transcript rendering. */
+export interface EvalCellResult {
+	index: number;
+	title?: string;
+	code: string;
+	language?: EvalLanguage;
+	output: string;
+	status: "pending" | "running" | "complete" | "error";
+	durationMs?: number;
+	exitCode?: number;
+	statusEvents?: EvalStatusEvent[];
+	hasMarkdown?: boolean;
+}
+
+/** Tool result detail object surfaced to the UI/transcript. */
+export interface EvalToolDetails {
+	cells?: EvalCellResult[];
+	jsonOutputs?: unknown[];
+	images?: ImageContent[];
+	statusEvents?: EvalStatusEvent[];
+	isError?: boolean;
+	meta?: OutputMeta;
+	/** First backend that produced cells. Kept for transcript compatibility. */
+	language?: EvalLanguage;
+	/** Backends that produced cells in this call, in first-use order. */
+	languages?: EvalLanguage[];
+	/** Optional human-readable notice (e.g. fallback explanation). */
+	notice?: string;
+}

package/src/exa/index.ts

@@ -0,0 +1,2 @@
+export * from "./mcp-client";
+export type { ExaSearchResponse, MCPCallResponse, MCPTool, MCPToolsResponse, MCPToolWrapperConfig } from "./types";