/**
 * Pre-flight cost estimate + gate (issue #346).
 *
 * Before a run spawns we estimate its cost and decide whether to allow it. The
 * estimate's token basis comes from recent ledger averages for the same agent
 * (the most accurate signal we have), falling back to a prompt-character
 * heuristic when there's no history. Cost is computed via the canonical pricing
 * module — never reimplemented here.
 *
 * `enforcePreflight` is the decision: with `on_exceed: block`, if launching
 * this run would push any cap (per_run / per_day / per_agent / per_project)
 * over the line, it denies. With `on_exceed: warn` it always allows but reports
 * the projected overrun.
 */
import type { BudgetConfig } from '../types.js';
import type { SpendEntry } from './ledger.js';
/** A pre-flight cost estimate for one run. */
export interface RunEstimate {
    /** Estimated USD for this run. 0 when the model is unpriced. */
    estUsd: number;
    /** How the token count was derived. */
    basis: 'ledger-average' | 'prompt-heuristic' | 'none';
    /** True when the model resolved to a priced entry. */
    priced: boolean;
    estInputTokens: number;
    estOutputTokens: number;
}
/**
 * Estimate the cost of a run. When the ledger has prior runs for this agent we
 * use their average input/output tokens; otherwise we fall back to a
 * prompt-character heuristic. `recentAvgTokens` lets callers inject a
 * precomputed average (e.g. from a scoped ledger) for testability.
 */
export declare function estimateRunCost(args: {
    agent: string;
    model: string;
    mode?: string;
    promptChars?: number;
    recentAvgTokens?: {
        input: number;
        output: number;
    };
    ledger?: SpendEntry[];
}): RunEstimate;
/** Average input/output tokens per RUN for an agent, from the ledger. Null when no history. */
export declare function ledgerAverageTokens(agent: string, ledger: SpendEntry[]): {
    input: number;
    output: number;
} | null;
/** Decision returned by the pre-flight gate. */
export interface PreflightDecision {
    /** Whether the run may proceed. */
    allow: boolean;
    /** Whether the caller must interactively confirm (estimate >= require_confirm_over). */
    needsConfirm: boolean;
    /** Human reason when blocked or confirming. */
    reason?: string;
    /** Which cap blocked, if any. */
    blockedCap?: 'per_run' | 'per_day' | 'per_agent' | 'per_project';
    /** Projected day spend if this run lands at its estimate. */
    projectedDaySpend: number;
    /** Projected project spend if this run lands at its estimate. */
    projectedProjectSpend: number;
}
/** Current spend snapshot the gate compares the estimate against. */
export interface LedgerState {
    /** Agent this snapshot is for (used to pick the matching per_agent cap). */
    agent: string;
    daySpend: number;
    projectSpend: number;
    agentDaySpend: number;
}
/** Read the ledger snapshot the gate needs for `agent` / `project` / today. */
export declare function ledgerStateFor(agent: string, project: string, ledger?: SpendEntry[]): LedgerState;
/**
 * The pre-flight gate. Projects this run's estimate on top of current spend and
 * decides allow/deny. `on_exceed: warn` never blocks (allow:true) but still
 * reports the projected overrun via `reason`. A hard block sets allow:false —
 * `--yes` MUST NOT override it (the caller enforces that; this function only
 * reports the truth).
 */
export declare function enforcePreflight(cfg: BudgetConfig, state: LedgerState, est: RunEstimate): PreflightDecision;
/** Build a one-line human estimate banner for `agents run` preamble. */
export declare function formatEstimateBanner(agent: string, model: string, est: RunEstimate): string;
/** Result of the high-level run gate consumed by `agents run` / teams / cloud. */
export interface PreflightGateResult {
    /** True when no caps are configured — budget feature dormant, nothing to do. */
    dormant: boolean;
    cfg: BudgetConfig;
    estimate: RunEstimate;
    decision: PreflightDecision;
    banner: string;
}
/**
 * High-level pre-flight gate: resolve the effective budget for `cwd`, estimate
 * the run, and evaluate every cap. Returns `dormant:true` (and skips all work)
 * when no caps are set, so the gate is zero-cost for users who never configure
 * a budget. The CLI layer decides how to act on `decision` (print banner,
 * confirm, or block + exit non-zero).
 */
export declare function runPreflightGate(args: {
    agent: string;
    model: string;
    mode?: string;
    prompt?: string;
    project: string;
    cwd?: string;
    ledger?: SpendEntry[];
}): PreflightGateResult;
export type { SpendEntry };
