@kr78/pi-coding-agent 17.2.10

package/src/eval/agent-bridge.ts

@@ -0,0 +1,224 @@
+/**
+ * Host-side handler for the eval `agent()` helper.
+ */
+import { type } from "@oh-my-pi/omptype";
+import {
+	buildStructuredSubagentRecoveryHint,
+	runStructuredSubagent,
+	StructuredSubagentError,
+	type StructuredSubagentSchemaMode,
+} from "../task/structured-subagent";
+import type { AgentProgress, SingleResult } from "../task/types";
+import type { NestedRepoPatch } from "../task/worktree";
+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__";
+
+const agentArgsSchema = type({
+	prompt: "string>0",
+	"agent?": "string>0",
+	"label?": "string",
+	"schema?": "unknown",
+	"schemaMode?": "'permissive' | 'strict'",
+	"isolated?": "boolean",
+	"apply?": "boolean",
+	"merge?": "boolean",
+	"handle?": "boolean",
+	"+": "delete",
+});
+
+interface EvalAgentArgs {
+	prompt: string;
+	agent?: string;
+	label?: string;
+	schema?: unknown;
+	schemaMode?: StructuredSubagentSchemaMode;
+	isolated?: boolean;
+	apply?: boolean;
+	merge?: boolean;
+	handle?: boolean;
+}
+
+export interface EvalAgentBridgeOptions {
+	session: ToolSession;
+	signal?: AbortSignal;
+	emitStatus?: (event: JsStatusEvent) => void;
+}
+
+export interface EvalAgentResult {
+	text: string;
+	/** Parsed structured data returned by the child executor. */
+	data?: unknown;
+	details: {
+		agent: string;
+		id: string;
+		model?: string | string[];
+		structured: boolean;
+		schemaSource?: "caller" | "agent" | "session";
+		schemaMode?: StructuredSubagentSchemaMode;
+		schemaStatus?: "valid" | "invalid";
+		isolated?: boolean;
+		patchPath?: string;
+		branchName?: string;
+		nestedPatches?: NestedRepoPatch[];
+		changesApplied?: boolean | null;
+		isolationSummary?: string;
+	};
+}
+
+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 trimToUndefined(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	return trimmed ? trimmed : undefined;
+}
+
+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,
+	});
+}
+
+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 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 isolation =
+		Object.hasOwn(parsed, "isolated") || Object.hasOwn(parsed, "apply") || Object.hasOwn(parsed, "merge")
+			? {
+					...(parsed.isolated !== undefined ? { requested: parsed.isolated } : {}),
+					...(parsed.merge === false ? { merge: "patch" as const } : {}),
+					...(parsed.apply !== undefined ? { apply: parsed.apply } : {}),
+				}
+			: undefined;
+
+	try {
+		const execution = await withBridgeTimeoutPause(
+			options.emitStatus,
+			() =>
+				runStructuredSubagent({
+					session: options.session,
+					invocationKind: "eval",
+					assignment: parsed.prompt,
+					...(parsed.agent !== undefined ? { agent: parsed.agent } : {}),
+					...(Object.hasOwn(parsed, "schema") ? { outputSchema: parsed.schema } : {}),
+					...(parsed.schemaMode !== undefined ? { schemaMode: parsed.schemaMode } : {}),
+					...(parsed.label !== undefined ? { identity: { label: parsed.label } } : {}),
+					...(isolation ? { isolation } : {}),
+					...(parsed.handle ? { retainArtifacts: true } : {}),
+					keepAlive: false,
+					// `maxRuntimeMs` is intentionally omitted: the executor then inherits
+					// `task.maxRuntimeMs`, matching the task tool. Pinning it to 0 here
+					// silently overrode the user's wall-clock cap for eval fan-outs.
+					shareEvalSession: false,
+					...(options.signal !== undefined ? { signal: options.signal } : {}),
+					...(options.emitStatus
+						? { onProgress: (progress: AgentProgress) => emitProgressStatus(options.emitStatus, progress) }
+						: {}),
+				}),
+			{ deferExternalAbort: true },
+		);
+		const { result, policy, mergeSummary, changesApplied, artifactsDir } = execution;
+		if (result.exitCode !== 0 || result.error || result.aborted) {
+			const failureMessage = buildSubagentFailureMessage(policy.agentName, result)
+				.replace(/<\/?system-notification>/g, "")
+				.trim();
+			const recoveryHint = policy.isIsolated ? await buildStructuredSubagentRecoveryHint(result, artifactsDir) : "";
+			throw new ToolError(`${failureMessage}${recoveryHint}`);
+		}
+		if (policy.isIsolated && changesApplied === false) {
+			const summary = mergeSummary.replace(/<\/?system-notification>/g, "").trim();
+			const recoveryHint = await buildStructuredSubagentRecoveryHint(result, artifactsDir);
+			throw new ToolError(
+				`agent() isolated apply failed for ${result.id}${summary ? `: ${summary}` : ""}${recoveryHint}`,
+			);
+		}
+
+		const structuredOutput = result.structuredOutput;
+		const structured = structuredOutput?.source !== undefined && structuredOutput.source !== "none";
+		if (structured && mergeSummary.includes("<system-notification>")) {
+			const recoveryHint = await buildStructuredSubagentRecoveryHint(result, artifactsDir);
+			throw new ToolError(
+				`agent() isolated nested patch apply failed for ${result.id}: ${mergeSummary.replace(/<\/?system-notification>/g, "").trim()}${recoveryHint}`,
+			);
+		}
+
+		const hasData = structured && structuredOutput !== undefined && Object.hasOwn(structuredOutput, "data");
+		const data = structuredOutput?.data;
+		const text = structured ? result.output : result.output + mergeSummary;
+		const schemaSource = structuredOutput?.source === "none" ? undefined : structuredOutput?.source;
+		const schemaMode = structured ? structuredOutput?.mode : undefined;
+		const schemaStatus = structuredOutput?.status === "unavailable" ? undefined : structuredOutput?.status;
+
+		const model = result.resolvedModel ?? policy.modelOverride;
+		const nestedPatches = result.nestedPatches?.length ? result.nestedPatches : undefined;
+		const isolationSummary = mergeSummary ? mergeSummary.trim() : undefined;
+		return {
+			text,
+			...(hasData ? { data } : {}),
+			details: {
+				agent: result.agent,
+				id: result.id,
+				...(model !== undefined ? { model } : {}),
+				structured,
+				...(schemaSource !== undefined ? { schemaSource } : {}),
+				...(schemaMode !== undefined ? { schemaMode } : {}),
+				...(schemaStatus !== undefined ? { schemaStatus } : {}),
+				...(policy.isIsolated ? { isolated: true, changesApplied } : {}),
+				...(result.patchPath !== undefined ? { patchPath: result.patchPath } : {}),
+				...(result.branchName !== undefined ? { branchName: result.branchName } : {}),
+				...(nestedPatches !== undefined ? { nestedPatches } : {}),
+				...(isolationSummary !== undefined ? { isolationSummary } : {}),
+			},
+		};
+	} catch (error) {
+		if (error instanceof StructuredSubagentError) throw new ToolError(error.message);
+		throw error;
+	}
+}

package/src/eval/backend-helpers.ts

@@ -0,0 +1,48 @@
+/**
+ * Helpers shared by the per-language eval backend definitions (jl/js/py/rb
+ * index modules): session-id namespacing, settings access, and projection of
+ * executor results into the ExecutorBackend result shape.
+ */
+import type { ToolSession } from "../tools";
+import type { ExecutorBackendResult } from "./backend";
+import type { EvalDisplayOutput } from "./types";
+
+export function namespaceSessionId(sessionId: string, prefix: string): string {
+	return sessionId.startsWith(prefix) ? sessionId : `${prefix}${sessionId}`;
+}
+
+export function readSetting<T>(session: ToolSession, key: string): T | undefined {
+	const settings = session.settings as { get?: (key: string) => T | undefined } | undefined;
+	return settings?.get?.(key);
+}
+
+export function readInterpreterSetting(session: ToolSession, key: string): string | undefined {
+	const value = readSetting<unknown>(session, key);
+	return typeof value === "string" ? value.trim() || undefined : undefined;
+}
+
+export function toExecutorBackendResult(result: {
+	output: string;
+	exitCode: number | undefined;
+	cancelled: boolean;
+	truncated: boolean;
+	artifactId?: string | undefined;
+	totalLines: number;
+	totalBytes: number;
+	outputLines: number;
+	outputBytes: number;
+	displayOutputs: EvalDisplayOutput[];
+}): ExecutorBackendResult {
+	return {
+		output: result.output,
+		exitCode: result.exitCode,
+		cancelled: result.cancelled,
+		truncated: result.truncated,
+		artifactId: result.artifactId,
+		totalLines: result.totalLines,
+		totalBytes: result.totalBytes,
+		outputLines: result.outputLines,
+		outputBytes: result.outputBytes,
+		displayOutputs: result.displayOutputs,
+	};
+}

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; undefined
+	 * disables the cell timeout. Backends 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,65 @@
+/**
+ * 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;
+}
+
+/** Optional behavior for a timeout pause around a host bridge call. */
+export interface BridgeTimeoutPauseOptions {
+	/**
+	 * Holds an external eval abort back from the *kernel* until this bridge call
+	 * settles, so the runtime is never torn down mid-phase (`agent()` isolation
+	 * worktree setup and merge/cherry-pick). It does not shield the delegated
+	 * work itself: the bridge hands subagents the caller's real signal, so a
+	 * turn cancel still stops them immediately.
+	 */
+	deferExternalAbort?: boolean;
+}
+
+/**
+ * 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>,
+	options?: BridgeTimeoutPauseOptions,
+): Promise<T> {
+	if (!emitStatus) return operation();
+	emitStatus(
+		options?.deferExternalAbort
+			? { op: EVAL_TIMEOUT_PAUSE_OP, deferExternalAbort: true }
+			: { op: EVAL_TIMEOUT_PAUSE_OP },
+	);
+	try {
+		return await operation();
+	} finally {
+		emitStatus(
+			options?.deferExternalAbort
+				? { op: EVAL_TIMEOUT_RESUME_OP, deferExternalAbort: true }
+				: { 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,212 @@
+/**
+ * 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 { type } from "@oh-my-pi/omptype";
+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 { 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: "@smol",
+	default: "@default",
+	slow: "@slow",
+};
+
+const completionArgsSchema = type({
+	prompt: "string>0",
+	"model?": "'smol'|'default'|'slow'",
+	"system?": "string",
+	"schema?": { "[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 `@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);
+	};
+
+	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) },
+	};
+}