import type { TurnCompletion } from "./run-contracts.js";
/**
 * A turn the site started. The sequence borrows it to cancel it on a timeout; it
 * releases nothing. The engine's `eventRelay` step reads the events and the
 * terminal result.
 */
export interface StartedTurn {
    cancel(reason: string): Promise<void>;
}
/**
 * The input the sequence hands to the one `turnFinalize` step. A `terminal`
 * input carries the turn's terminal result; an `error` input carries the step
 * error and the phase it failed in. Both carry the wall-clock timeout flag.
 */
export type TurnFinalizeInput<TTerminal> = {
    readonly kind: "terminal";
    readonly terminal: TTerminal;
    readonly timedOut: boolean;
} | {
    readonly kind: "error";
    readonly error: unknown;
    readonly phase: "prepare_turn" | "turn";
    readonly timedOut: boolean;
};
/**
 * The five steps the sequence runs, plus the timer inputs. The engine implements
 * each step over its own run state. `turnFinalize` maps a terminal result or a
 * step error to a `TurnCompletion`; it must not reject, so the sequence never
 * rejects.
 */
export interface TurnSteps<TTerminal> {
    readonly signal?: AbortSignal;
    /** The wall-clock timeout, in milliseconds, or undefined for no timeout. */
    readonly timeoutMs: number | undefined;
    /** The message the timeout cancel carries. */
    readonly timeoutMessage: string;
    /** Build the prompt and emit the run metadata. A failure here is `prepare_turn`. */
    promptBuild(signal: AbortSignal): Promise<void>;
    /** Snapshot the pre-turn usage, so this run's cost excludes earlier runs. */
    preTurnUsage(): Promise<void>;
    /** Start the turn with the run's six inputs. The sequence adds the signal and the timeout. */
    turnStart(signal: AbortSignal, timeoutMs: number | undefined): StartedTurn;
    /** Relay the turn events and return the terminal result. */
    eventRelay(turn: StartedTurn): Promise<TTerminal>;
    /** Map a terminal result or a step error to a `TurnCompletion`. Must not reject. */
    turnFinalize(input: TurnFinalizeInput<TTerminal>): Promise<TurnCompletion>;
}
/**
 * Run the turn sequence. It returns a `TurnCompletion` on every path and never
 * rejects. A failure before `turnStart` returns is a `prepare_turn` failure; a
 * failure after it is a `turn` failure. Only the reported phase differs.
 */
export declare function runTurn<TTerminal>(steps: TurnSteps<TTerminal>): Promise<TurnCompletion>;
//# sourceMappingURL=turn-sequence.d.ts.map