@oh-my-pi/pi-coding-agent 15.7.2 → 15.7.3

package/src/eval/agent-bridge.ts

@@ -0,0 +1,295 @@
+/**
+ * Host-side handler for the eval `agent()` helper.
+ */
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { prompt, Snowflake } from "@oh-my-pi/pi-utils";
+import * as z from "zod/v4";
+import { resolveAgentModelPatterns } from "../config/model-resolver";
+import type { LocalProtocolOptions } from "../internal-urls";
+import { MCPManager } from "../mcp/manager";
+import subagentUserPromptTemplate from "../prompts/system/subagent-user-prompt.md" with { type: "text" };
+import * as taskDiscovery from "../task/discovery";
+import * as taskExecutor from "../task/executor";
+import { AgentOutputManager } from "../task/output-manager";
+import type { AgentDefinition, AgentProgress } from "../task/types";
+import type { ToolSession } from "../tools";
+import { ToolError } from "../tools/tool-errors";
+import type { JsStatusEvent } from "./js/shared/types";
+// Import review tools for side effects (registers subagent tool handlers).
+import "../tools/review";
+
+/** Synthetic bridge name reserved for the `agent()` helper across both runtimes. */
+export const EVAL_AGENT_BRIDGE_NAME = "__agent__";
+
+/** Hard recursion limit for eval-driven subagents. */
+export const EVAL_AGENT_MAX_DEPTH = 3;
+
+const DEFAULT_AGENT_TYPE = "task";
+const DEFAULT_AGENT_LABEL = "EvalAgent";
+
+const agentArgsSchema = z.object({
+	prompt: z.string().min(1, "prompt must be a non-empty string"),
+	agentType: z.string().min(1).optional(),
+	model: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]).optional(),
+	context: z.string().optional(),
+	label: z.string().optional(),
+	schema: z.unknown().optional(),
+});
+
+interface EvalAgentArgs {
+	prompt: string;
+	agentType?: string;
+	model?: string | string[];
+	context?: string;
+	label?: string;
+	schema?: unknown;
+}
+
+export interface EvalAgentBridgeOptions {
+	session: ToolSession;
+	signal?: AbortSignal;
+	emitStatus?: (event: JsStatusEvent) => void;
+}
+
+export interface EvalAgentResult {
+	text: string;
+	details: {
+		agent: string;
+		id: string;
+		model?: string | string[];
+		structured: boolean;
+	};
+}
+
+function parseAgentArgs(args: unknown): EvalAgentArgs {
+	const parsed = agentArgsSchema.safeParse(args);
+	if (!parsed.success) {
+		const issue = parsed.error.issues[0];
+		const where = issue?.path.length ? `${issue.path.join(".")}: ` : "";
+		throw new ToolError(`agent() received invalid arguments: ${where}${issue?.message ?? "bad input"}`);
+	}
+	return parsed.data;
+}
+
+function assertDepthAllowed(session: ToolSession): void {
+	const taskDepth = session.taskDepth ?? 0;
+	if (taskDepth >= EVAL_AGENT_MAX_DEPTH) {
+		throw new ToolError(
+			`agent() cannot spawn another agent at task depth ${taskDepth}; maximum depth is ${EVAL_AGENT_MAX_DEPTH}.`,
+		);
+	}
+}
+
+function assertSpawnAllowed(session: ToolSession, agentName: string): void {
+	const parentSpawns = session.getSessionSpawns() ?? "*";
+	if (parentSpawns === "*") return;
+	if (parentSpawns === "") {
+		throw new ToolError(`Cannot spawn '${agentName}'. Allowed: none (spawns disabled for this agent)`);
+	}
+	const allowedSpawns = parentSpawns.split(",").map(spawn => spawn.trim());
+	if (!allowedSpawns.includes(agentName)) {
+		throw new ToolError(`Cannot spawn '${agentName}'. Allowed: ${parentSpawns}`);
+	}
+}
+
+function assertAgentEnabled(session: ToolSession, agentName: string, agents: AgentDefinition[]): void {
+	const disabledAgents = session.settings.get("task.disabledAgents") as string[];
+	if (!disabledAgents.includes(agentName)) return;
+	const enabled = agents.filter(agent => !disabledAgents.includes(agent.name)).map(agent => agent.name);
+	throw new ToolError(
+		`Agent "${agentName}" is disabled in settings. Enable it via /agents, or use a different agent type.${enabled.length > 0 ? ` Available: ${enabled.join(", ")}` : ""}`,
+	);
+}
+
+function assertNotPlanMode(session: ToolSession): void {
+	if (session.getPlanModeState?.()?.enabled) {
+		throw new ToolError("agent() is unavailable in plan mode.");
+	}
+}
+
+function renderSubagentPrompt(assignment: string): string {
+	return prompt.render(subagentUserPromptTemplate, { assignment: assignment.trim(), independentMode: false });
+}
+
+function trimToUndefined(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	return trimmed ? trimmed : undefined;
+}
+
+function outputIdBase(label: string | undefined, agentName: string): string {
+	const source = trimToUndefined(label) ?? agentName ?? DEFAULT_AGENT_LABEL;
+	const sanitized = source.replace(/[^A-Za-z0-9_-]+/g, "").slice(0, 48);
+	return sanitized || DEFAULT_AGENT_LABEL;
+}
+
+function getOutputManager(session: ToolSession): AgentOutputManager {
+	if (session.agentOutputManager) return session.agentOutputManager;
+	const manager = new AgentOutputManager(session.getArtifactsDir ?? (() => null));
+	session.agentOutputManager = manager;
+	return manager;
+}
+
+async function getArtifacts(session: ToolSession): Promise<{
+	sessionFile: string | null;
+	artifactsDir: string;
+	contextFile?: string;
+}> {
+	const sessionFile = session.getSessionFile();
+	const sessionArtifactsDir = sessionFile ? sessionFile.slice(0, -6) : null;
+	const artifactsDir = sessionArtifactsDir ?? path.join(os.tmpdir(), `omp-eval-agent-${Snowflake.next()}`);
+	await fs.mkdir(artifactsDir, { recursive: true });
+
+	const shouldWriteConversationContext = session.settings.get("irc.enabled") !== true;
+	const compactContext = shouldWriteConversationContext ? session.getCompactContext?.() : undefined;
+	if (!compactContext) return { sessionFile, artifactsDir };
+
+	const contextFile = path.join(artifactsDir, "context.md");
+	await Bun.write(contextFile, compactContext);
+	return { sessionFile, artifactsDir, contextFile };
+}
+
+function emitProgressStatus(emitStatus: ((event: JsStatusEvent) => void) | undefined, progress: AgentProgress): void {
+	if (!emitStatus) return;
+	const preview = (progress.assignment ?? progress.task ?? "").split("\n")[0]?.slice(0, 120);
+	emitStatus({
+		op: "agent",
+		id: progress.id,
+		agent: progress.agent,
+		status: progress.status,
+		lastIntent: progress.lastIntent,
+		currentTool: progress.currentTool,
+		currentToolArgs: progress.currentToolArgs,
+		taskPreview: preview || undefined,
+		toolCount: progress.toolCount,
+		tokens: progress.tokens,
+		contextTokens: progress.contextTokens,
+		contextWindow: progress.contextWindow,
+		cost: progress.cost,
+		durationMs: progress.durationMs,
+		model: progress.resolvedModel,
+	});
+}
+
+/**
+ * Run a single subagent on behalf of an eval cell's `agent()` call.
+ */
+export async function runEvalAgent(args: unknown, options: EvalAgentBridgeOptions): Promise<EvalAgentResult> {
+	const parsed = parseAgentArgs(args);
+	const agentName = parsed.agentType ?? DEFAULT_AGENT_TYPE;
+	const structured = Object.hasOwn(parsed, "schema");
+
+	assertNotPlanMode(options.session);
+	assertDepthAllowed(options.session);
+	assertSpawnAllowed(options.session, agentName);
+
+	const turnBudget = options.session.getTurnBudget?.();
+	if (turnBudget?.hard && turnBudget.total !== null && turnBudget.spent >= turnBudget.total) {
+		throw new ToolError(
+			`agent() blocked: turn token budget exhausted (${turnBudget.spent}/${turnBudget.total} output tokens). Raise or drop the +Nk! ceiling to continue.`,
+		);
+	}
+
+	const { agents } = await taskDiscovery.discoverAgents(options.session.cwd);
+	const agent = taskDiscovery.getAgent(agents, agentName);
+	if (!agent) {
+		const available = agents.map(candidate => candidate.name).join(", ") || "none";
+		throw new ToolError(`Unknown agent "${agentName}". Available: ${available}`);
+	}
+	assertAgentEnabled(options.session, agentName, agents);
+
+	const effectiveAgent = agent;
+	const parentActiveModelPattern = options.session.getActiveModelString?.();
+	const agentModelOverrides = options.session.settings.get("task.agentModelOverrides");
+	const modelOverride = resolveAgentModelPatterns({
+		settingsOverride: parsed.model ?? agentModelOverrides[agentName],
+		agentModel: effectiveAgent.model,
+		settings: options.session.settings,
+		activeModelPattern: parentActiveModelPattern,
+		fallbackModelPattern: options.session.getModelString?.(),
+	});
+	const availableSkills = [...(options.session.skills ?? [])];
+	const resolvedAutoloadSkills =
+		effectiveAgent.autoloadSkills?.length && availableSkills.length > 0
+			? effectiveAgent.autoloadSkills
+					.map(name => availableSkills.find(skill => skill.name === name))
+					.filter((skill): skill is NonNullable<typeof skill> => skill !== undefined)
+			: [];
+	const contextFiles = options.session.contextFiles?.filter(
+		file => path.basename(file.path).toLowerCase() !== "agents.md",
+	);
+	const localProtocolOptions: LocalProtocolOptions = options.session.localProtocolOptions ?? {
+		getArtifactsDir: options.session.getArtifactsDir ?? (() => null),
+		getSessionId: options.session.getSessionId ?? (() => null),
+	};
+	const parentArtifactManager = options.session.getArtifactManager?.() ?? undefined;
+	const parentEvalSessionId = options.session.getEvalSessionId?.() ?? undefined;
+	const mcpManager = options.session.mcpManager ?? MCPManager.instance();
+	const { sessionFile, artifactsDir, contextFile } = await getArtifacts(options.session);
+	const outputManager = getOutputManager(options.session);
+	const id = await outputManager.allocate(outputIdBase(parsed.label, agentName));
+	const assignment = parsed.prompt.trim();
+	const context = trimToUndefined(parsed.context);
+	const result = await taskExecutor.runSubprocess({
+		cwd: options.session.cwd,
+		agent: effectiveAgent,
+		task: renderSubagentPrompt(assignment),
+		assignment,
+		context,
+		description: trimToUndefined(parsed.label),
+		index: 0,
+		id,
+		taskDepth: options.session.taskDepth ?? 0,
+		modelOverride,
+		parentActiveModelPattern,
+		thinkingLevel: effectiveAgent.thinkingLevel,
+		outputSchema: structured ? parsed.schema : undefined,
+		sessionFile,
+		persistArtifacts: Boolean(sessionFile),
+		artifactsDir,
+		contextFile,
+		enableLsp: (options.session.enableLsp ?? true) && options.session.settings.get("task.enableLsp"),
+		signal: options.signal,
+		eventBus: options.session.eventBus,
+		onProgress: progress => emitProgressStatus(options.emitStatus, progress),
+		authStorage: options.session.authStorage,
+		modelRegistry: options.session.modelRegistry,
+		settings: options.session.settings,
+		mcpManager,
+		contextFiles,
+		skills: availableSkills,
+		autoloadSkills: resolvedAutoloadSkills,
+		workspaceTree: options.session.workspaceTree,
+		promptTemplates: options.session.promptTemplates,
+		localProtocolOptions,
+		parentArtifactManager,
+		parentHindsightSessionState: options.session.getHindsightSessionState?.(),
+		parentMnemopiSessionState: options.session.getMnemopiSessionState?.(),
+		parentTelemetry: options.session.getTelemetry?.(),
+		parentEvalSessionId,
+	});
+
+	if (result.exitCode !== 0 || result.error) {
+		const failureMessage =
+			result.error ?? result.stderr ?? result.abortReason ?? `agent() subagent '${agentName}' failed.`;
+		throw new ToolError(failureMessage);
+	}
+
+	options.session.recordEvalSubagentUsage?.(result.usage?.output ?? 0);
+
+	// The final `onProgress` flush from `runSubprocess` already emits a
+	// status:"completed" event carrying full stats (toolCount, cost, context),
+	// so we don't emit a second, sparser completion event here — it would
+	// coalesce over the richer one and drop those stats.
+
+	return {
+		text: result.output,
+		details: {
+			agent: result.agent,
+			id: result.id,
+			model: result.resolvedModel ?? modelOverride,
+			structured,
+		},
+	};
+}

package/src/eval/backend.ts

@@ -1,5 +1,5 @@
 import type { ToolSession } from "../tools";
-import type { EvalDisplayOutput, EvalLanguage } from "./types";
+import type { EvalDisplayOutput, EvalLanguage, EvalStatusEvent } from "./types";
 
 /** Per-cell execute() options. */
 export interface ExecutorBackendExecOptions {
@@ -9,11 +9,26 @@ export interface ExecutorBackendExecOptions {
 	kernelOwnerId: string | undefined;
 	signal?: AbortSignal;
 	session: ToolSession;
-	deadlineMs: number;
+	/**
+	 * Inactivity budget in milliseconds (the cell's `timeout`). Cancellation is
+	 * driven entirely by `signal`, which the eval tool arms as an idle watchdog
+	 * that fires a `TimeoutError` reason after this much time with no progress
+	 * (status) events. Backends use this value only for timeout-annotation text
+	 * and as cold-start headroom; they MUST NOT derive a competing wall-clock
+	 * timer from it.
+	 */
+	idleTimeoutMs: number;
 	reset: boolean;
 	artifactPath: string | undefined;
 	artifactId: string | undefined;
 	onChunk: (chunk: string) => void;
+	/**
+	 * Live status events (read/write/agent/…) delivered as they are emitted,
+	 * before the cell finishes. The same events are also returned in
+	 * `displayOutputs`; this channel exists so callers can stream long-running
+	 * progress (e.g. `agent()` subagents) into the UI mid-execution.
+	 */
+	onStatus?: (event: EvalStatusEvent) => void;
 }
 
 /** Result returned by a backend's execute(). */

package/src/eval/budget-bridge.ts

@@ -0,0 +1,48 @@
+/**
+ * Host-side handler for the eval `budget` helper.
+ *
+ * Reports the active token ceiling and amount spent so kernel helpers can
+ * compute remaining budget. Precedence: a `+Nk`/`+Nk!` per-turn directive (the
+ * user's immediate intent) wins; otherwise an active Goal Mode budget; otherwise
+ * no ceiling, with `spent` still reflecting this turn's output where available.
+ */
+import type { ToolSession } from "../tools";
+import type { JsStatusEvent } from "./js/shared/types";
+
+/** Synthetic bridge name reserved for the `budget` helper across both runtimes. */
+export const EVAL_BUDGET_BRIDGE_NAME = "__budget__";
+
+export interface EvalBudgetBridgeOptions {
+	session: ToolSession;
+	signal?: AbortSignal;
+	emitStatus?: (event: JsStatusEvent) => void;
+}
+
+export interface EvalBudgetResult {
+	total: number | null;
+	spent: number;
+	/** Whether the ceiling is enforced (eval `agent()` throws past it) vs advisory. */
+	hard: boolean;
+}
+
+/**
+ * Resolve the current token budget snapshot for an eval cell's `budget` helper.
+ * The returned object is JSON-passed verbatim by the bridge transport; kernel
+ * helpers read `.total`/`.spent`/`.hard` directly.
+ */
+export async function runEvalBudget(_args: unknown, options: EvalBudgetBridgeOptions): Promise<EvalBudgetResult> {
+	const turn = options.session.getTurnBudget?.();
+	if (turn && turn.total !== null) {
+		return { total: turn.total, spent: turn.spent, hard: turn.hard };
+	}
+	const goal = options.session.getGoalModeState?.();
+	if (goal?.enabled && goal.goal) {
+		return {
+			total: goal.goal.tokenBudget ?? null,
+			spent: goal.goal.tokensUsed ?? 0,
+			hard: goal.goal.tokenBudget != null,
+		};
+	}
+	const spent = turn?.spent ?? options.session.getUsageStatistics?.()?.output ?? 0;
+	return { total: null, spent, hard: false };
+}

package/src/eval/idle-timeout.ts

@@ -0,0 +1,80 @@
+/**
+ * Inactivity watchdog for eval cells.
+ *
+ * A cell's `timeout` is treated as an *idle* budget rather than a hard
+ * wall-clock deadline: the watchdog aborts {@link signal} (with a
+ * `TimeoutError` reason, matching `AbortSignal.timeout`) only once `idleMs`
+ * elapses with no {@link bump}. Every progress signal re-arms it, so a
+ * long-running fanout that keeps reporting progress (e.g. `agent()` status
+ * updates, `log()`/`phase()`) never trips the timeout, while a genuinely
+ * stalled cell still gets interrupted.
+ *
+ * The timer self-reschedules instead of being torn down and recreated on every
+ * bump, so a high-frequency stream of bumps (sub-second agent progress) costs
+ * one timestamp write per event rather than churning a timer each time.
+ */
+export class IdleTimeout {
+	readonly #controller = new AbortController();
+	readonly #idleMs: number;
+	/** Absolute time (epoch ms) at which inactivity is considered to have expired. */
+	#deadlineMs: number;
+	#timer: NodeJS.Timeout | undefined;
+	#settled = false;
+
+	constructor(idleMs: number) {
+		this.#idleMs = Math.max(1, Math.floor(idleMs));
+		this.#deadlineMs = Date.now() + this.#idleMs;
+		this.#arm(this.#idleMs);
+	}
+
+	/** Aborts with a `TimeoutError` reason once the inactivity budget is exhausted. */
+	get signal(): AbortSignal {
+		return this.#controller.signal;
+	}
+
+	/** Configured inactivity budget in milliseconds. */
+	get idleMs(): number {
+		return this.#idleMs;
+	}
+
+	/** Record activity, pushing the inactivity deadline forward by `idleMs`. */
+	bump(): void {
+		if (this.#settled) return;
+		this.#deadlineMs = Date.now() + this.#idleMs;
+	}
+
+	/** Stop the watchdog. Safe to call multiple times. */
+	dispose(): void {
+		if (this.#settled) return;
+		this.#settled = true;
+		if (this.#timer) {
+			clearTimeout(this.#timer);
+			this.#timer = undefined;
+		}
+	}
+
+	[Symbol.dispose](): void {
+		this.dispose();
+	}
+
+	#arm(delayMs: number): void {
+		const timer = setTimeout(() => this.#onExpire(), Math.max(0, delayMs));
+		// Never keep the event loop alive for the watchdog itself.
+		timer.unref?.();
+		this.#timer = timer;
+	}
+
+	#onExpire(): void {
+		if (this.#settled) return;
+		const remainingMs = this.#deadlineMs - Date.now();
+		if (remainingMs > 0) {
+			// A bump moved the deadline forward after this timer was armed; wait
+			// out the remaining window instead of firing early.
+			this.#arm(remainingMs);
+			return;
+		}
+		this.#settled = true;
+		this.#timer = undefined;
+		this.#controller.abort(new DOMException(`Idle for ${Math.round(this.#idleMs / 1000)}s`, "TimeoutError"));
+	}
+}

package/src/eval/js/executor.ts

@@ -2,12 +2,20 @@ import { DEFAULT_MAX_BYTES, OutputSink } from "../../session/streaming-output";
 import type { ToolSession } from "../../tools";
 import { resolveOutputMaxColumns, resolveOutputSinkHeadBytes } from "../../tools/output-meta";
 import { executeInVmContext, type JsDisplayOutput } from "./context-manager";
+import type { JsStatusEvent } from "./shared/types";
 
 export interface JsExecutorOptions {
 	cwd?: string;
 	timeoutMs?: number;
 	deadlineMs?: number;
+	/**
+	 * Inactivity budget (ms). Used for worker cold-start headroom and
+	 * timeout-annotation text when the caller drives cancellation via an
+	 * idle-aware `signal` instead of `deadlineMs`/`timeoutMs`. Never arms a timer.
+	 */
+	idleTimeoutMs?: number;
 	onChunk?: (chunk: string) => Promise<void> | void;
+	onStatus?: (event: JsStatusEvent) => void;
 	signal?: AbortSignal;
 	sessionId: string;
 	reset?: boolean;
@@ -44,6 +52,20 @@ function isAbortError(error: unknown): boolean {
 	);
 }
 
+function isTimeoutReason(reason: unknown): boolean {
+	return (
+		(reason instanceof DOMException && reason.name === "TimeoutError") ||
+		(reason instanceof Error && reason.name === "TimeoutError")
+	);
+}
+
+function formatJsTimeoutAnnotation(timeoutMs: number | undefined, idle: boolean): string {
+	const suffix = idle ? " of inactivity" : "";
+	if (timeoutMs === undefined) return "Command timed out";
+	const secs = Math.max(1, Math.round(timeoutMs / 1000));
+	return `Command timed out after ${secs} seconds${suffix}`;
+}
+
 export async function executeJs(code: string, options: JsExecutorOptions): Promise<JsResult> {
 	const displayOutputs: JsDisplayOutput[] = [];
 	const outputSink = new OutputSink({
@@ -54,15 +76,20 @@ export async function executeJs(code: string, options: JsExecutorOptions): Promi
 		maxColumns: resolveOutputMaxColumns(options.session.settings),
 		onChunk: chunk => options.onChunk?.(chunk),
 	});
-	const timeoutMs = getExecutionTimeoutMs(options);
+	const legacyTimeoutMs = getExecutionTimeoutMs(options);
 	const timeoutSignal =
-		typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0
-			? AbortSignal.timeout(timeoutMs)
+		typeof legacyTimeoutMs === "number" && Number.isFinite(legacyTimeoutMs) && legacyTimeoutMs > 0
+			? AbortSignal.timeout(legacyTimeoutMs)
 			: undefined;
 	const signal =
 		options.signal && timeoutSignal
 			? AbortSignal.any([options.signal, timeoutSignal])
 			: (options.signal ?? timeoutSignal);
+	// Idle mode: the eval tool drives cancellation via an idle-aware `signal` and
+	// passes only an inactivity budget. Use it for worker cold-start headroom and
+	// timeout-annotation text; never derive a competing fixed timer from it.
+	const idleMode = legacyTimeoutMs === undefined && options.idleTimeoutMs !== undefined;
+	const acquireBudgetMs = legacyTimeoutMs ?? options.idleTimeoutMs;
 
 	try {
 		await executeInVmContext({
@@ -73,12 +100,13 @@ export async function executeJs(code: string, options: JsExecutorOptions): Promi
 			reset: options.reset,
 			code,
 			filename: `js-cell-${crypto.randomUUID()}.js`,
-			timeoutMs,
+			timeoutMs: acquireBudgetMs,
 			runState: {
 				signal,
 				onText: chunk => outputSink.push(chunk),
 				onDisplay: output => {
 					displayOutputs.push(output);
+					if (output.type === "status") options.onStatus?.(output.event);
 				},
 			},
 		});
@@ -97,9 +125,9 @@ export async function executeJs(code: string, options: JsExecutorOptions): Promi
 		};
 	} catch (error) {
 		if (signal?.aborted || isAbortError(error)) {
-			const timeoutReason = timeoutSignal?.aborted ? "Command timed out" : "";
-			if (timeoutReason) {
-				outputSink.push(timeoutReason);
+			const timedOut = Boolean(timeoutSignal?.aborted) || isTimeoutReason(options.signal?.reason);
+			if (timedOut) {
+				outputSink.push(formatJsTimeoutAnnotation(legacyTimeoutMs ?? options.idleTimeoutMs, idleMode));
 			}
 			const summary = await outputSink.dump();
 			return {

package/src/eval/js/index.ts

@@ -20,7 +20,7 @@ export default {
 	async execute(code: string, opts: ExecutorBackendExecOptions): Promise<ExecutorBackendResult> {
 		const result = await executeJs(code, {
 			cwd: opts.cwd,
-			deadlineMs: opts.deadlineMs,
+			idleTimeoutMs: opts.idleTimeoutMs,
 			signal: opts.signal,
 			sessionId: namespaceSessionId(opts.sessionId),
 			sessionFile: opts.sessionFile,
@@ -28,6 +28,7 @@ export default {
 			artifactPath: opts.artifactPath,
 			artifactId: opts.artifactId,
 			onChunk: opts.onChunk,
+			onStatus: opts.onStatus,
 			session: opts.session,
 		});
 		return {

package/src/eval/js/shared/prelude.txt

@@ -39,11 +39,88 @@ if (!globalThis.__omp_js_prelude_loaded__) {
 		return values.length === 1 ? values[0] : values;
 	};
 
+	const hasOwn = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
+
 	const llm = async (prompt, opts = {}) => {
 		const o = toOptions(opts);
 		const res = await globalThis.__omp_call_tool__("__llm__", { prompt, ...o });
 		const text = res && typeof res === "object" ? res.text : res;
-		return o.schema ? JSON.parse(text) : text;
+		return hasOwn(o, "schema") ? JSON.parse(text) : text;
+	};
+
+	const agent = async (prompt, opts = {}) => {
+		const o = toOptions(opts);
+		const res = await globalThis.__omp_call_tool__("__agent__", { prompt, ...o });
+		const text = res && typeof res === "object" ? res.text : res;
+		return hasOwn(o, "schema") ? JSON.parse(text) : text;
+	};
+
+	const normalizeConcurrency = value => {
+		const number = Number(value ?? 4);
+		if (!Number.isFinite(number)) return 4;
+		return Math.max(1, Math.min(16, Math.trunc(number)));
+	};
+
+	const __pool = async (items, limit, fn) => {
+		const list = Array.from(items ?? []);
+		const concurrency = Math.min(normalizeConcurrency(limit), list.length);
+		const results = new Array(list.length);
+		let next = 0;
+		const worker = async () => {
+			while (true) {
+				const index = next++;
+				if (index >= list.length) return;
+				results[index] = await fn(list[index], index);
+			}
+		};
+		await Promise.all(Array.from({ length: concurrency }, () => worker()));
+		return results;
+	};
+
+	const parallel = async (thunks, opts = {}) =>
+		__pool(thunks, toOptions(opts).concurrency, (thunk, index) => {
+			if (typeof thunk !== "function") throw new TypeError("parallel() expects an iterable of functions");
+			return thunk(index);
+		});
+
+	const pipeline = async (items, ...stagesAndOptions) => {
+		let opts = {};
+		const last = stagesAndOptions.at(-1);
+		if (last && typeof last === "object" && !Array.isArray(last)) {
+			opts = last;
+			stagesAndOptions = stagesAndOptions.slice(0, -1);
+		}
+		let current = Array.from(items ?? []);
+		for (const stage of stagesAndOptions) {
+			if (typeof stage !== "function") throw new TypeError("pipeline() stages must be functions");
+			current = await __pool(current, toOptions(opts).concurrency, stage);
+		}
+		return current;
+	};
+
+	const log = message => globalThis.__omp_emit_status__("log", { message: String(message) });
+
+	const phase = title => {
+		globalThis.__omp_phase__ = String(title);
+		globalThis.__omp_emit_status__("phase", { title: String(title) });
+	};
+
+	const __budgetSnap = async () => {
+		const r = await globalThis.__omp_call_tool__("__budget__", {});
+		return r && typeof r === "object" ? r : {};
+	};
+
+	const budget = {
+		total: async () => {
+			const s = await __budgetSnap();
+			return s.total ?? null;
+		},
+		spent: async () => Number((await __budgetSnap()).spent ?? 0),
+		remaining: async () => {
+			const s = await __budgetSnap();
+			return s.total == null ? Infinity : Math.max(0, Number(s.total) - Number(s.spent ?? 0));
+		},
+		hard: async () => Boolean((await __budgetSnap()).hard),
 	};
 
 	const display = value => {
@@ -70,6 +147,13 @@ if (!globalThis.__omp_js_prelude_loaded__) {
 	globalThis.tool = tool;
 	globalThis.llm = llm;
 	globalThis.output = output;
+	globalThis.agent = agent;
+	globalThis.parallel = parallel;
+	globalThis.pipeline = pipeline;
+	globalThis.log = log;
+	globalThis.phase = phase;
+	globalThis.budget = budget;
+	globalThis.__pool = __pool;
 	globalThis.read = read;
 	globalThis.write = write;
 	globalThis.append = append;