oma-coding-agent 1.1.4

package/src/eval/agent-bridge.ts

@@ -0,0 +1,319 @@
+/**
+ * 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 { type } from "arktype";
+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 { MAIN_AGENT_ID } from "../registry/agent-registry";
+import * as taskDiscovery from "../task/discovery";
+import * as taskExecutor from "../task/executor";
+import { AgentOutputManager } from "../task/output-manager";
+import type { AgentDefinition, AgentProgress, SingleResult } from "../task/types";
+import type { ToolSession } from "../tools";
+import { ToolError } from "../tools/tool-errors";
+import { withBridgeTimeoutPause } from "./bridge-timeout";
+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 = type({
+	prompt: "string>0",
+	"agentType?": "string>0",
+	"model?": "string>0|string>0[]",
+	"label?": "string",
+	"schema?": "unknown",
+});
+
+interface EvalAgentArgs {
+	prompt: string;
+	agentType?: string;
+	model?: string | 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 result = agentArgsSchema(args);
+	if (result instanceof type.errors) {
+		throw new ToolError(`agent() received invalid arguments: ${result.summary}`);
+	}
+	return result;
+}
+
+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() });
+}
+
+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;
+}> {
+	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 });
+	return { sessionFile, artifactsDir };
+}
+
+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,
+	});
+}
+
+/**
+ * Coalesce a subagent failure into a non-empty, human-meaningful error message.
+ *
+ * When the executor aborts a subagent (runtime limit, parent cancellation, …)
+ * the actionable explanation lives on `abortReason`, while `error`/`stderr`
+ * are routinely empty strings. Plain `??` coalescing stops at the empty string
+ * and ships an empty error through the bridge — Python then surfaces only the
+ * generic `bridge call '__agent__' failed`. See #2006.
+ */
+function buildSubagentFailureMessage(agentName: string, result: SingleResult): string {
+	const abortReason = trimToUndefined(result.abortReason);
+	if (result.aborted && abortReason) return abortReason;
+	return (
+		trimToUndefined(result.error) ??
+		trimToUndefined(result.stderr) ??
+		abortReason ??
+		`agent() subagent '${agentName}' failed.`
+	);
+}
+
+/**
+ * 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 mcpManager = options.session.mcpManager ?? MCPManager.instance();
+	const { sessionFile, artifactsDir } = await getArtifacts(options.session);
+	const outputManager = getOutputManager(options.session);
+	const id = await outputManager.allocate(outputIdBase(parsed.label, agentName));
+	const assignment = parsed.prompt.trim();
+	// Suspend eval timeout accounting while the subagent owns control. The
+	// timeout clock restarts once the bridge returns to the cell runtime.
+	const result = await withBridgeTimeoutPause(options.emitStatus, () =>
+		taskExecutor.runSubprocess({
+			cwd: options.session.cwd,
+			agent: effectiveAgent,
+			task: renderSubagentPrompt(assignment),
+			assignment,
+			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,
+			// Eval `agent()` subagents are short-lived programmatic helpers (data
+			// collection, structured output, parallel() fan-out). LSP server
+			// cold-start costs tens of seconds and is pure overhead here, so it is
+			// forced off regardless of the `task.enableLsp` setting — that knob only
+			// governs LSP-aware delegation through the `task` tool.
+			enableLsp: false,
+			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,
+			// Eval `agent()` subagents are never wall-clock capped: the parent
+			// cell's idle watchdog is suspended for the whole bridge call
+			// (withBridgeTimeoutPause), so a long-running phase/recovery workflow
+			// must not be killed by `task.maxRuntimeMs`. Force the limit off
+			// regardless of the inherited session setting.
+			maxRuntimeMs: 0,
+			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?.(),
+			parentAgentId: options.session.getAgentId?.() ?? MAIN_AGENT_ID,
+			// Deliberately omit parentEvalSessionId: the parent's Python kernel is
+			// blocked on this bridge call, so sharing the eval session would deadlock
+			// (subagent queues behind the parent's in-flight execution, parent waits
+			// for subagent → circular). Each bridge-spawned subagent gets its own
+			// eval session with an independent kernel.
+		}),
+	);
+
+	if (result.exitCode !== 0 || result.error || result.aborted) {
+		throw new ToolError(buildSubagentFailureMessage(agentName, result));
+	}
+
+	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

@@ -0,0 +1,71 @@
+import { buildEvalUrlRoots, type LocalProtocolOptions } from "../internal-urls";
+import type { ToolSession } from "../tools";
+import type { EvalDisplayOutput, EvalLanguage, EvalStatusEvent } from "./types";
+
+/** Per-cell execute() options. */
+export interface ExecutorBackendExecOptions {
+	cwd: string;
+	sessionId: string;
+	sessionFile: string | undefined;
+	kernelOwnerId: string | undefined;
+	signal?: AbortSignal;
+	session: ToolSession;
+	/**
+	 * Runtime-work budget in milliseconds (the cell's `timeout`). Cancellation is
+	 * driven entirely by `signal`, which the eval tool arms as a watchdog that
+	 * pauses on bridge timeout-control status events and fires a `TimeoutError`
+	 * reason only while the Python/JS runtime owns control. 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;
+	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(). */
+export interface ExecutorBackendResult {
+	output: string;
+	exitCode: number | undefined;
+	cancelled: boolean;
+	truncated: boolean;
+	artifactId: string | undefined;
+	totalLines: number;
+	totalBytes: number;
+	outputLines: number;
+	outputBytes: number;
+	displayOutputs: EvalDisplayOutput[];
+}
+
+/** Pluggable language backend for the eval tool. */
+export interface ExecutorBackend {
+	readonly id: EvalLanguage;
+	readonly label: string;
+	/** Source language identifier passed to the syntax highlighter (e.g. "python", "javascript"). */
+	readonly highlightLang: string;
+	/** Cheap availability check. Used by fallback resolution. */
+	isAvailable(session: ToolSession): Promise<boolean>;
+	/** Execute one cell. Caller invokes once per cell and aggregates results. */
+	execute(code: string, opts: ExecutorBackendExecOptions): Promise<ExecutorBackendResult>;
+}
+
+/**
+ * Resolve the on-disk roots that the eval helpers substitute for internal-URL
+ * schemes (currently `local://`). Prefers the session's own
+ * {@link LocalProtocolOptions} — the exact mapping `read local://…` uses — so an
+ * eval `write("local://x")` and a later `read local://x` agree on the location.
+ */
+export function resolveEvalUrlRoots(session: ToolSession): Record<string, string> {
+	const options: LocalProtocolOptions = session.localProtocolOptions ?? {
+		getArtifactsDir: () => session.getArtifactsDir?.() ?? null,
+		getSessionId: () => session.getSessionId?.() ?? null,
+	};
+	return buildEvalUrlRoots(options);
+}

package/src/eval/bridge-timeout.ts

@@ -0,0 +1,44 @@
+/**
+ * Timeout suspension for in-flight host-side eval bridge calls.
+ *
+ * The eval watchdog caps a cell's `timeout` as a budget on the cell runtime's
+ * own work. Host-side `agent()` / `parallel()` / `completion()` bridge calls hand
+ * control to the outer TypeScript process, where the Python kernel or JS VM is
+ * only waiting for a result. While that delegated work is in flight, the cell
+ * timeout must be ignored completely; once the bridge returns and the runtime is
+ * back in control, the watchdog starts a fresh timeout window.
+ *
+ * Bridge helpers express that handoff with synthetic pause/resume status events
+ * on the existing `emitStatus → onStatus` path. Consumers MUST treat these as
+ * timeout-control events only: update the watchdog and drop them from rendered
+ * or persisted cell output.
+ */
+import type { JsStatusEvent } from "./js/shared/types";
+
+/** Synthetic status op emitted when a bridge call leaves the cell runtime. */
+export const EVAL_TIMEOUT_PAUSE_OP = "timeout-pause";
+
+/** Synthetic status op emitted when a bridge call returns control to the runtime. */
+export const EVAL_TIMEOUT_RESUME_OP = "timeout-resume";
+
+/** Whether a status event is pure eval-timeout control and should not render. */
+export function isEvalTimeoutControlEvent(event: JsStatusEvent): boolean {
+	return event.op === EVAL_TIMEOUT_PAUSE_OP || event.op === EVAL_TIMEOUT_RESUME_OP;
+}
+
+/**
+ * Run {@link operation} while suspending the eval watchdog through
+ * {@link emitStatus}. A no-op wrapper when no status sink is wired.
+ */
+export async function withBridgeTimeoutPause<T>(
+	emitStatus: ((event: JsStatusEvent) => void) | undefined,
+	operation: () => Promise<T>,
+): Promise<T> {
+	if (!emitStatus) return operation();
+	emitStatus({ op: EVAL_TIMEOUT_PAUSE_OP });
+	try {
+		return await operation();
+	} finally {
+		emitStatus({ op: EVAL_TIMEOUT_RESUME_OP });
+	}
+}

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/completion-bridge.ts

@@ -0,0 +1,211 @@
+/**
+ * Host-side handler for the eval `completion()` helper.
+ *
+ * Both eval runtimes (JS worker + Python kernel) route helper→host calls
+ * through {@link callSessionTool}. Reserving the synthetic tool name
+ * {@link EVAL_COMPLETION_BRIDGE_NAME} lets a single host handler serve both
+ * transports without registering an agent-visible tool: cell code calls
+ * `completion(prompt, opts)`, the prelude forwards `{ prompt, model, system?, schema? }`
+ * through the bridge, and this module performs one stateless completion.
+ *
+ * The call is oneshot and toolless from the model's perspective — pure text
+ * in, text (or, with `schema`, a structured object) out.
+ */
+import { instrumentedCompleteSimple, resolveTelemetry } from "@oh-my-pi/pi-agent-core";
+import { type Api, Effort, type Model, type Tool } from "@oh-my-pi/pi-ai";
+import { getSupportedEfforts } from "@oh-my-pi/pi-catalog/model-thinking";
+import { type } from "arktype";
+import { extractTextContent, extractToolCall, parseJsonPayload } from "../commit/utils";
+
+import {
+	expandRoleAlias,
+	formatModelString,
+	getModelMatchPreferences,
+	resolveModelFromString,
+} from "../config/model-resolver";
+import type { ToolSession } from "../tools";
+import { ToolError } from "../tools/tool-errors";
+import { withBridgeTimeoutPause } from "./bridge-timeout";
+import type { JsStatusEvent } from "./js/shared/types";
+
+/** Synthetic bridge name reserved for the `completion()` helper across both runtimes. */
+export const EVAL_COMPLETION_BRIDGE_NAME = "__completion__";
+
+/** Synthetic tool the model is forced to call when a `schema` is supplied. */
+const STRUCTURED_TOOL_NAME = "respond";
+
+type CompletionTier = "smol" | "default" | "slow";
+
+const TIER_TO_PATTERN: Record<CompletionTier, string> = {
+	smol: "pi/smol",
+	default: "pi/default",
+	slow: "pi/slow",
+};
+
+const completionArgsSchema = type({
+	prompt: "string>0",
+	"model?": "'smol'|'default'|'slow'",
+	"system?": "string",
+	"schema?": "Record<string,unknown>",
+});
+
+export interface EvalCompletionBridgeOptions {
+	session: ToolSession;
+	signal?: AbortSignal;
+	emitStatus?: (event: JsStatusEvent) => void;
+}
+
+export interface EvalCompletionResult {
+	text: string;
+	details: { model: string; tier: CompletionTier; structured: boolean };
+}
+
+/**
+ * Resolve a tier to a concrete {@link Model}. `default` prefers the session's
+ * active model and falls back to the `pi/default` role; `smol`/`slow` resolve
+ * their respective role patterns. Returns `undefined` when nothing matches.
+ */
+function resolveTierModel(tier: CompletionTier, session: ToolSession): Model<Api> | undefined {
+	const modelRegistry = session.modelRegistry;
+	if (!modelRegistry) return undefined;
+	const available = modelRegistry.getAvailable();
+	if (available.length === 0) return undefined;
+
+	const matchPreferences = getModelMatchPreferences(session.settings);
+	const resolve = (pattern: string | undefined): Model<Api> | undefined => {
+		if (!pattern) return undefined;
+		const expanded = expandRoleAlias(pattern, session.settings);
+		return resolveModelFromString(expanded, available, matchPreferences, modelRegistry);
+	};
+
+	if (tier === "default") {
+		const activePattern = session.getActiveModelString?.() ?? session.getModelString?.();
+		return resolve(activePattern) ?? resolve(TIER_TO_PATTERN.default);
+	}
+	return resolve(TIER_TO_PATTERN[tier]);
+}
+
+/**
+ * Choose the reasoning effort for a tier. Only `slow` opts into thinking, and
+ * only on reasoning-capable models — guarding against `requireSupportedEffort`
+ * throwing downstream on models that cannot reason. Clamps to the highest
+ * supported effort so a reasoning model without `high` does not 400.
+ */
+function reasoningForTier(tier: CompletionTier, model: Model<Api>): Effort | undefined {
+	if (tier !== "slow" || !model.reasoning) return undefined;
+	const efforts = getSupportedEfforts(model);
+	if (efforts.length === 0) return undefined;
+	return efforts.includes(Effort.High) ? Effort.High : efforts[efforts.length - 1];
+}
+
+/**
+ * Run a single stateless completion on behalf of an eval cell's `completion()` call.
+ * Returns a `{ text, details }` value shaped like a {@link callSessionTool}
+ * result so the existing bridge transport carries it to either runtime.
+ */
+export async function runEvalCompletion(
+	args: unknown,
+	options: EvalCompletionBridgeOptions,
+): Promise<EvalCompletionResult> {
+	const parsed = completionArgsSchema(args);
+	if (parsed instanceof type.errors) {
+		throw new ToolError(`completion() received invalid arguments: ${parsed.summary}`);
+	}
+	const { prompt, model: modelTier, system, schema } = parsed;
+	// Apply default value for model if not provided
+	const finalTier: CompletionTier = modelTier ?? "default";
+
+	const model = resolveTierModel(finalTier, options.session);
+	if (!model) {
+		throw new ToolError(
+			`completion() could not resolve a model for the "${finalTier}" tier. Configure modelRoles.${finalTier === "default" ? "default" : finalTier} or ensure a provider is available.`,
+		);
+	}
+
+	const registry = options.session.modelRegistry;
+	const apiKey = await registry?.getApiKey(model);
+	if (!registry || !apiKey) {
+		throw new ToolError(
+			`completion() has no API key for ${formatModelString(model)}. Configure credentials for this provider or choose another tier.`,
+		);
+	}
+
+	const tools: Tool[] | undefined = schema
+		? [
+				{
+					name: STRUCTURED_TOOL_NAME,
+					description: "Return your answer by calling this tool with the requested structured fields.",
+					parameters: schema,
+					strict: false,
+				},
+			]
+		: undefined;
+
+	const telemetry = resolveTelemetry(options.session.getTelemetry?.(), options.session.getSessionId?.() ?? undefined);
+
+	// Some providers (notably openai-codex) require a non-empty `instructions`
+	// field on every Responses request and 400 with "Instructions are required"
+	// when it is missing. Fall back to a minimal default so `completion(prompt)` works
+	// without forcing every caller to pass a `system` prompt.
+	const systemPrompt = system ? [system] : ["You are a helpful assistant."];
+
+	// Suspend eval timeout accounting while the model request owns control. The
+	// timeout clock restarts once the bridge returns to the cell runtime.
+	const response = await withBridgeTimeoutPause(options.emitStatus, () =>
+		instrumentedCompleteSimple(
+			model,
+			{
+				systemPrompt,
+				messages: [{ role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() }],
+				tools,
+			},
+			{
+				apiKey: registry.resolver(model, options.session.getSessionId?.() ?? undefined),
+				signal: options.signal,
+				reasoning: reasoningForTier(finalTier, model),
+				toolChoice: schema ? { type: "tool", name: STRUCTURED_TOOL_NAME } : undefined,
+			},
+			{ telemetry, oneshotKind: "eval_completion" },
+		),
+	);
+
+	if (response.stopReason === "error") {
+		throw new ToolError(response.errorMessage ?? "completion() request failed.");
+	}
+	if (response.stopReason === "aborted") {
+		throw new ToolError("completion() request aborted.");
+	}
+
+	let resultText: string;
+	if (schema) {
+		const call = extractToolCall(response, STRUCTURED_TOOL_NAME);
+		let value: unknown;
+		if (call) {
+			value = call.arguments;
+		} else {
+			const text = extractTextContent(response);
+			if (!text) throw new ToolError("completion() returned no structured response.");
+			try {
+				value = parseJsonPayload(text);
+			} catch {
+				throw new ToolError("completion() did not return a structured response matching the schema.");
+			}
+		}
+		resultText = JSON.stringify(value);
+	} else {
+		resultText = extractTextContent(response);
+		if (!resultText) throw new ToolError("completion() returned no text output.");
+	}
+
+	options.emitStatus?.({
+		op: "completion",
+		model: formatModelString(model),
+		tier: finalTier,
+		chars: resultText.length,
+	});
+
+	return {
+		text: resultText,
+		details: { model: formatModelString(model), tier: finalTier, structured: Boolean(schema) },
+	};
+}