/**
 * Runner — owns per-run state and the single agent loop.
 *
 * Design invariant (product differentiator): the full turn algorithm lives in
 * private `loop()` in this file so a developer can read one method end-to-end.
 * Helpers below only remove duplication; they do not split control flow.
 */
import { Agent } from "./agent";
import { Tracer, type TraceSpan } from "../tracing";
import type { ClearloopEvent, ApprovalDecision, ApprovalRequest, PendingApproval, RunCheckpoint, StorageAdapter } from "../types";
export interface TokenBudget {
    maxPromptTokens?: number;
    maxCompletionTokens?: number;
    maxTotalTokens?: number;
}
export interface RunnerConfig {
    maxTurns?: number;
    storage?: StorageAdapter;
    maxOutputRepairAttempts?: number;
    tokenBudget?: TokenBudget;
    timeoutMs?: number;
    modelTimeoutMs?: number;
    /** Retries for transient model failures (recorded as retry spans in the trace). */
    maxRetries?: number;
    retryBaseDelayMs?: number;
    /**
     * Run independent tool calls in a turn concurrently (stable message order).
     * Default: true.
     */
    parallelTools?: boolean;
    onEvent?: (event: ClearloopEvent) => void;
    onSpan?: (span: TraceSpan) => void;
    /**
     * Sync shortcut for tools with `requiresApproval: true`.
     * If omitted, the run pauses with a checkpoint instead (use Runner.resume).
     */
    onApprovalRequired?: (request: ApprovalRequest) => boolean | Promise<boolean>;
}
export interface RunOptions<TContext = Record<string, unknown>> {
    sessionId?: string;
    dryRun?: boolean;
    /** App context passed into tools and tool guardrails (userId, tenant, etc.). */
    context?: TContext;
}
export interface RunResult<TOutput = string, TContext = Record<string, unknown>> {
    status: "completed" | "paused" | "failed";
    /** Present when status is "completed". */
    output: TOutput;
    runId: string;
    finalAgentName: string;
    trace: Tracer;
    turnsUsed: number;
    dryRun: boolean;
    pendingApproval?: PendingApproval;
    checkpoint?: RunCheckpoint<TContext>;
}
export declare class Runner {
    private readonly maxTurns;
    private readonly sessions;
    private readonly maxOutputRepairAttempts;
    private readonly tokenBudget?;
    private readonly timeoutMs?;
    private readonly modelTimeoutMs?;
    private readonly maxRetries;
    private readonly retryBaseDelayMs;
    private readonly parallelTools;
    private onEvent?;
    private readonly onSpan?;
    private readonly onApprovalRequired?;
    constructor(config?: RunnerConfig);
    private emit;
    /** Non-streaming entrypoint. */
    run<TOutput = string, TContext = Record<string, unknown>>(agent: Agent<TOutput, TContext>, userInput: string, options?: RunOptions<TContext>): Promise<RunResult<TOutput, TContext>>;
    /**
     * Resume a paused run after a human approval decision.
     * Pass the same root agent (handoff graph) used for the original run.
     */
    resume<TOutput = string, TContext = Record<string, unknown>>(checkpoint: RunCheckpoint<TContext>, decision: ApprovalDecision, options: {
        agent: Agent<TOutput, TContext>;
    }): Promise<RunResult<TOutput, TContext>>;
    /**
     * Streaming entrypoint — yields the same ClearloopEvent stream the loop emits.
     * Uses chatStream on the provider when available; loop logic is shared with run().
     */
    runStream<TOutput = string, TContext = Record<string, unknown>>(agent: Agent<TOutput, TContext>, userInput: string, options?: RunOptions<TContext>): AsyncGenerator<ClearloopEvent, RunResult<TOutput, TContext>>;
    /** Re-emit a stored trace as events (no model calls). */
    replayFromTrace(traceJSON: {
        runId: string;
        agentName: string;
        spans: Array<{
            type: string;
            name: string;
            durationMs?: number;
            metadata?: Record<string, unknown>;
        }>;
        finalOutput?: unknown;
        error?: string;
    }): ClearloopEvent[];
    private tripGuardrail;
    private buildPausedResult;
    private execute;
    /** Virtual handoff tools exposed to the model for this turn. */
    private handoffTools;
    private resolveHandoffTarget;
    /** First tool in the batch that needs HITL pause (no sync approval handler). */
    private findPauseCall;
    private emitPause;
    /**
     * The entire agent loop — readable end-to-end in one method.
     * Stream vs non-stream is a flag on model calls, not a second framework.
     */
    private loop;
    /**
     * Execute a tool batch. When parallelTools is on and there are multiple calls,
     * runs them concurrently but appends tool messages in original call order.
     */
    private executeToolBatch;
    /**
     * Guardrails → approval → dry-run or execute → emit events.
     * Returns tool message content (caller appends in stable order).
     */
    private executeOneTool;
    /**
     * Invoke the model with optional retries. Each retry is recorded on the trace
     * and emitted as a `retry` event so graders/debuggers can see it.
     */
    private callModel;
    private checkBudget;
    private finalize;
}
//# sourceMappingURL=runner.d.ts.map