/**
 * Live spend watcher + cap math (issue #346).
 *
 * This is the provider-agnostic shared surface the loop driver (#332) will
 * reuse for its budget guard. It knows nothing about child processes, agents,
 * or the ledger — it accepts parsed usage events and a caps object, accumulates
 * cost via the canonical pricing module, and fires `onBreach` exactly once when
 * any active cap is crossed.
 *
 * The accumulation is the cross-vendor primitive: feed Claude usage and Codex
 * usage to the same watcher under one `per_project` / `per_run` cap and the
 * spend aggregates across both — no single-vendor control can do that.
 */
import type { AgentId, BudgetConfig } from '../types.js';
/** A parsed usage event from any agent's stream (fields match session/parse). */
export interface UsageEvent {
    agent?: AgentId | string;
    model?: string;
    inputTokens?: number;
    outputTokens?: number;
    cacheReadTokens?: number;
    cacheCreationTokens?: number;
}
/**
 * Caps the watcher enforces. `priorDaySpend` / `priorProjectSpend` seed the
 * accumulators with spend already on the ledger BEFORE this run started, so a
 * per_day cap counts today's earlier runs too — not just this process. Per-cap
 * fields are USD; undefined means "not enforced".
 */
export interface LiveCaps {
    perRun?: number;
    perDay?: number;
    perProject?: number;
    /** Per-agent daily caps. Each agent's running spend is checked against its own cap. */
    perAgent?: Partial<Record<string, number>>;
    /** Day spend already on the ledger before this run (cross-vendor). */
    priorDaySpend?: number;
    /** Project spend already on the ledger before this run (cross-vendor). */
    priorProjectSpend?: number;
    /** Per-agent day spend already on the ledger before this run, keyed by agent. */
    priorAgentDaySpend?: Partial<Record<string, number>>;
}
/** Which cap tripped, and the spend figures at the moment of the breach. */
export interface BreachInfo {
    cap: 'per_run' | 'per_day' | 'per_project' | 'per_agent';
    /** The configured limit that was crossed (USD). */
    limit: number;
    /** The spend that crossed it (USD). */
    spend: number;
    /** Agent attributed to the breach (only meaningful for per_agent). */
    agent?: string;
    /** This run's accumulated spend so far (USD). */
    runSpend: number;
}
/** Public watcher surface. `feedUsage` is idempotent after a breach (no double-fire). */
export interface LiveSpendWatcher {
    /** Feed one parsed usage event; accrues cost and may fire onBreach. */
    feedUsage(event: UsageEvent): void;
    /** Total USD this run has accumulated across all fed events. */
    runSpend(): number;
    /** True once a cap has been breached. */
    breached(): boolean;
    /** Stop accepting events / release references. Idempotent. */
    dispose(): void;
}
/** Convert a resolved BudgetConfig + prior ledger spend into the caps the watcher needs. */
export declare function capsFromConfig(cfg: BudgetConfig, prior?: {
    daySpend?: number;
    projectSpend?: number;
    agentDaySpend?: Partial<Record<string, number>>;
}): LiveCaps;
/**
 * Create a live spend watcher. `onBreach` fires at most once, on the first
 * event that pushes any active cap from at-or-under to over. After it fires the
 * watcher keeps accumulating (so `runSpend()` stays accurate for the final
 * ledger record) but never calls `onBreach` again.
 */
export declare function makeLiveSpendWatcher(args: {
    caps: LiveCaps;
    onBreach: (breach: BreachInfo) => void;
}): LiveSpendWatcher;
/**
 * Incrementally extract usage events from a stream-json chunk. Buffers a partial
 * trailing line across calls (returned in `rest`), parses each complete line,
 * and yields one UsageEvent per line that carries token counts. Provider shapes
 * handled: Claude/`--json` assistant turns (`message.usage` with
 * `input_tokens`/`output_tokens`/`cache_*_input_tokens`) and the flatter
 * `usage.record` shape (`usage.input_tokens`/`output`). Lines that aren't JSON
 * or carry no usage are skipped — this never throws on agent output.
 */
export declare function extractUsageEvents(chunk: string, pending: string, fallbackModel?: string, fallbackAgent?: string): {
    events: UsageEvent[];
    rest: string;
};
