/**
 * Agent Exec engine — one-shot exposure of the AgentRunner surface over the
 * public subprocess protocol in doc/agent-exec-protocol.md (§3).
 *
 * Process model: the CALLER (e.g. monoagentcli) spawns `monomind agent exec`;
 * monomind resolves the requested runtime's AgentRunner and drives ONE agent
 * turn, adapting the `--prompt` string into the single-message async stream
 * the runner interface expects (`AgentRunArgs.prompt`). With
 * `--tools stdio` (+ `--tools-file` / `--tool-names`), tool handler
 * invocations are bridged to the caller as `tool_call` frames on stdout and
 * satisfied by `tool_result` frames on stdin — identically for native
 * runners (ClaudeAgentRunner registers them as real SDK tools) and fence
 * runners (subprocess CLIs render + parse the fence protocol in-process).
 *
 * stdout purity (§3): the ONLY thing this engine writes to stdout is NDJSON
 * events via the injected `emit` sink. Everything else goes to stderr.
 *
 * Cancellation semantics: `--timeout`, budget breach, and caller `cancel`
 * frames all funnel through `terminate()` — a fire-and-forget
 * `stream.return()` (the runner's finally-blocks SIGTERM/SIGKILL its child)
 * raced against a grace window, after which the engine resolves regardless.
 * A runner wedged mid-await cannot have its return() propagate until it
 * reaches a yield; the grace bound keeps the exec from hanging forever, and
 * the runner's own 2h/45s ladders remain the backstop for orphaned children.
 */
import type { Readable } from 'node:stream';
import type { AgentRunner } from './agent-runner.js';
import { z } from 'zod';
export type ExecErrorCode = 'auth' | 'quota' | 'missing-binary' | 'no-runner' | 'budget' | 'runner-error' | 'timeout' | 'cancelled' | 'bad-frame';
/** Tool definition from `--tools-file` (JSON Schema) or `--tool-names`. */
export interface ToolSpec {
    name: string;
    description: string;
    /** JSON Schema `{type:'object', properties, required}` (optional for --tool-names). */
    schema?: Record<string, unknown>;
}
export interface AgentExecOptions {
    runtime: string;
    prompt: string;
    systemPrompt?: string;
    model?: string;
    cwd?: string;
    resume?: string;
    maxTurns: number;
    /** Overall wall-clock cap (ms); undefined = none. */
    timeoutMs?: number;
    /** Max wait per caller tool_result frame (ms). */
    toolTimeoutMs: number;
    /** Optional spend cap (USD) checked at result granularity (see §3.1 note). */
    budgetUsd?: number;
    env?: Record<string, string>;
    /** null/[] = no caller-side tools. Non-empty enables the stdio bridge. */
    toolSpecs?: ToolSpec[] | null;
    /** Injectable runner for tests; production resolves via resolveExecRunner. */
    runnerOverride?: AgentRunner;
    /** Event sink — the command layer writes each object as one NDJSON line. */
    emit: (ev: Record<string, unknown>) => void;
    /** Frame source for the tool bridge (default: process.stdin at command layer). */
    stdin?: Readable;
    /** Grace window for stream.return() propagation before resolving (ms). */
    returnGraceMs?: number;
}
/** Convert `{type:'object', properties, required}` JSON Schema to a zod shape. */
export declare function jsonSchemaToZodShape(schema?: Record<string, unknown>): Record<string, z.ZodType<any>>;
/**
 * Run one agent exec turn. Emits protocol events via opts.emit and returns
 * the process exit code (§3.2): 0 success · 1 error · 124 timeout ·
 * 130 cancelled. `done` is emitted exactly once before returning.
 */
export declare function runAgentExec(opts: AgentExecOptions): Promise<number>;
//# sourceMappingURL=agent-exec.d.ts.map