/**
 * quota-window.ts
 *
 * QuotaWindowTracker, tracks provider rate/quota windows from REAL observed
 * signals (429 rate-limit errors and their retry-after, plus explicit
 * limit/remaining/reset when a provider's headers carry them) and answers a
 * pre-fan-out question: "will spawning N agents against this provider likely
 * exhaust its quota window right now?"
 *
 * HONESTY IDIOM: the assessment is grounded in observed evidence and NEVER a
 * fabricated certainty. With no signal for a provider the verdict is `unknown`
 * (with an empty-evidence explanation), not a confident "you're fine". A
 * `likely-exhausts` verdict always carries the evidence it rests on (an active
 * cooldown, or an observed remaining below the requested fan-out), so a caller
 * can see why.
 */
/** One observed rate/quota signal for a provider. */
export interface QuotaSignal {
    readonly provider: string;
    /** Epoch ms the signal was observed. */
    readonly at: number;
    /** Retry-after the provider asked for (ms), when a 429 carried one. Defines the active cooldown window. */
    readonly retryAfterMs?: number | undefined;
    /** Observed window limit (requests or tokens), when headers carried it. */
    readonly limit?: number | undefined;
    /** Observed remaining in the window, when headers carried it. */
    readonly remaining?: number | undefined;
    /** Epoch ms the window resets, when headers carried it. */
    readonly resetAt?: number | undefined;
}
export type FanoutVerdict = 'likely-exhausts' | 'unlikely' | 'unknown';
/** The evidence a fan-out assessment rests on, all observed, never invented. */
export interface FanoutEvidence {
    /** How many rate-limit signals were seen for this provider inside the lookback window. */
    readonly recentRateLimitCount: number;
    /** Remaining cooldown (ms) from the most recent retry-after that has not yet elapsed, when one is active. */
    readonly activeCooldownMs?: number | undefined;
    /** The most recent observed remaining-in-window, when a provider reported it. */
    readonly observedRemaining?: number | undefined;
    /** The most recent observed window limit, when a provider reported it. */
    readonly observedLimit?: number | undefined;
    /** The fan-out size the assessment was made against. */
    readonly requestedAgents: number;
}
export interface FanoutAssessment {
    readonly provider: string;
    readonly verdict: FanoutVerdict;
    /** A plain-language explanation of the verdict and the evidence behind it. */
    readonly reason: string;
    readonly evidence: FanoutEvidence;
}
export interface FanoutQuery {
    readonly provider: string;
    /** How many agents the caller is about to spawn against this provider. */
    readonly agentCount: number;
    /** Optional expected LLM calls each agent will make (defaults to 1), used against an observed `remaining`. */
    readonly callsPerAgent?: number | undefined;
}
/**
 * A point-in-time view of a provider's observed quota window, the most recent
 * limit/remaining/reset a provider's headers reported, plus any active cooldown.
 * `hasSignal:false` (with every observed-* field absent) when no rate-limit
 * signal has been seen for the provider in the lookback window, an honest "no
 * observation", never a fabricated full quota.
 */
export interface QuotaSnapshot {
    readonly provider: string;
    /** Whether any rate-limit/quota signal has been observed within the lookback window. */
    readonly hasSignal: boolean;
    /** Epoch ms of the most recent observed signal, when one exists. */
    readonly observedAt?: number | undefined;
    /** Most recent observed remaining-in-window, when a provider reported it. */
    readonly remaining?: number | undefined;
    /** Most recent observed window limit, when a provider reported it. */
    readonly limit?: number | undefined;
    /** Most recent observed window reset (epoch ms), when a provider reported it. */
    readonly resetAt?: number | undefined;
    /** Remaining cooldown (ms) from the most recent retry-after that has not yet elapsed, when active. */
    readonly activeCooldownMs?: number | undefined;
    /** How many rate-limit (retry-after-carrying) signals were seen in the lookback window. */
    readonly recentRateLimitCount: number;
}
export interface QuotaWindowTrackerOptions {
    /** How far back observed signals stay relevant to an assessment. Default 15 min. */
    readonly lookbackMs?: number | undefined;
    /** Ceiling on retained signals per provider (oldest pruned first). Default 200. */
    readonly maxSignalsPerProvider?: number | undefined;
    readonly now?: (() => number) | undefined;
}
export declare class QuotaWindowTracker {
    private readonly lookbackMs;
    private readonly maxSignalsPerProvider;
    private readonly now;
    private readonly signals;
    constructor(opts?: QuotaWindowTrackerOptions);
    /** Ingest one observed rate/quota signal. */
    record(signal: QuotaSignal): void;
    /**
     * A point-in-time view of the provider's observed quota window: the most
     * recent limit/remaining/reset and any active cooldown, grounded only in what
     * headers actually reported. Honest "no observation" (hasSignal:false) when
     * nothing has been seen in the lookback window.
     */
    snapshot(provider: string): QuotaSnapshot;
    /**
     * Assess whether the requested fan-out likely exhausts the provider's quota
     * window right now, grounded in observed signals.
     */
    assessFanout(query: FanoutQuery): FanoutAssessment;
}
//# sourceMappingURL=quota-window.d.ts.map