import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
/** Per-phase accumulated token totals. */
export interface UsageAccumulator {
    inputTokens: number;
    outputTokens: number;
    cacheReadTokens: number;
    cacheWriteTokens: number;
    /**
     * Peak (high-water) per-turn prompt size = max over turns of
     * (input + cacheRead + cacheWrite). This is the real context-window
     * occupancy — a NON-cumulative size metric. Unlike cacheReadTokens (which
     * sums the whole cached prefix re-read on every turn and balloons to tens of
     * millions), contextTokens stays bounded by the actual context window.
     */
    contextTokens: number;
    estimatedCostUSD: number;
    /** Last model identifier seen in this phase. */
    model: string;
    /** Number of assistant turns accumulated. */
    turnCount: number;
}
/** Options for registerUsageHook. */
export interface UsageHookOptions {
    /**
     * Returns the current phase key. Called on every message_end event.
     * Defaults to reading FORGE_PHASE_KEY env var, falling back to "default".
     */
    getPhaseKey?: () => string;
}
/** Options for flushPhaseUsage. */
export interface FlushOptions {
    /** Sprint ID (e.g. "FORGE-S19"). */
    sprintId: string;
    /** Event ID for the sidecar (e.g. "20260509T080000000Z_FORGE-S19-T03_engineer_plan"). */
    eventId: string;
    /** Phase key to flush from the accumulator. */
    phaseKey: string;
    /** Absolute path to the forge plugin root (for store-cli.cjs location). */
    forgeRoot: string;
    /** The accumulator map returned by registerUsageHook. */
    accumulator: Map<string, UsageAccumulator>;
    /** Called after a successful flush. Optional notification hook. */
    onFlush?: (phaseKey: string, usage: UsageAccumulator) => void;
}
/**
 * Register a message_end listener on `pi` that accumulates per-turn token usage.
 *
 * @returns The accumulator map (keyed by phase key). Pass this to flushPhaseUsage.
 */
export declare function registerUsageHook(pi: ExtensionAPI, options?: UsageHookOptions): Map<string, UsageAccumulator>;
/**
 * Flush accumulated usage for `phaseKey` to store-cli record-usage.
 *
 * Non-blocking: if the subprocess exits non-zero, emits a warn line to
 * stderr and returns normally. Never throws.
 */
export declare function flushPhaseUsage(opts: FlushOptions): void;