/**
 * Token / context usage helpers.
 *
 * Prefer provider-reported counts (OpenAI `usage`, Anthropic `usage`, Gemini
 * `usageMetadata`, Ollama eval counts). Fall back to the same estimator used
 * by auto-compact when a provider omits usage.
 */
import type { ProviderId } from "../types.js";
import type { ChatMessage } from "../types.js";
/** Authoritative or estimated token counts for one completion. */
export interface TokenUsage {
    /** Input / prompt / context tokens for this request. */
    readonly promptTokens: number;
    /**
     * Present only when the provider omitted an input measurement while still
     * reporting another counter. Absence preserves the historic API contract:
     * a supplied promptTokens value is known, including an explicit zero.
     */
    readonly promptTokensKnown?: false | undefined;
    /** Output / completion tokens for this response. */
    readonly completionTokens: number;
    /** Total when provided; otherwise prompt + completion. */
    readonly totalTokens: number;
    /** true when values came from the provider API (exact). */
    readonly exact: boolean;
    /** Prompt tokens served from a provider cache, when reported. */
    readonly cachedPromptTokens?: number | undefined;
    /** Prompt tokens written into the provider cache, when reported. */
    readonly cacheCreationTokens?: number | undefined;
    /** Prompt tokens that were explicitly not served from the provider cache. */
    readonly uncachedPromptTokens?: number | undefined;
    /** Reasoning tokens included in completion usage, when reported. */
    readonly reasoningTokens?: number | undefined;
    readonly reasoningObserved?: true | undefined;
}
/**
 * Optional response-field paths for a user-configured OpenAI-compatible route.
 * Paths are relative to that route's `usage` object. They are telemetry input
 * only: they never affect request construction or cache eligibility.
 */
export interface CompatibleUsageAliases {
    readonly promptTokens?: string | undefined;
    readonly completionTokens?: string | undefined;
    readonly totalTokens?: string | undefined;
    readonly cachedPromptTokens?: string | undefined;
    readonly cacheCreationTokens?: string | undefined;
    readonly uncachedPromptTokens?: string | undefined;
    readonly reasoningTokens?: string | undefined;
}
export interface ContextUsageSnapshot {
    /** Tokens currently filling the context window (last prompt or estimate). */
    readonly contextTokens: number;
    /** Explicit session model-window limit, or 0 when no override is set. */
    readonly contextLimit: number;
    /** Last completion output tokens (0 if unknown). */
    readonly lastCompletionTokens: number;
    /** Session cumulative prompt tokens (API only when exact). */
    readonly sessionPromptTokens: number;
    /** Session cumulative completion tokens. */
    readonly sessionCompletionTokens: number;
    /** Whether contextTokens is provider-exact. */
    readonly exact: boolean;
}
/** Normalize sparse provider payloads into TokenUsage. */
export declare function normalizeTokenUsage(input: {
    promptTokens?: number | undefined;
    completionTokens?: number | undefined;
    totalTokens?: number | undefined;
    exact?: boolean | undefined;
    cachedPromptTokens?: number | undefined;
    cacheCreationTokens?: number | undefined;
    uncachedPromptTokens?: number | undefined;
    reasoningTokens?: number | undefined;
    reasoningObserved?: boolean | undefined;
}): TokenUsage | undefined;
export declare function withReasoningObservation(usage: TokenUsage | undefined, observed: boolean): TokenUsage | undefined;
/**
 * Parse OpenAI-compatible `usage` object (stream final chunk or complete body).
 * Handles standard counters, documented DeepSeek cache hit/miss fields, and
 * optional configured aliases for a user-defined compatible endpoint.
 */
export declare function parseOpenAiUsage(raw: unknown, aliases?: CompatibleUsageAliases | undefined): TokenUsage | undefined;
/**
 * Fireworks emits normal compatible usage plus optional performance metrics.
 * The latter are available in response headers for complete calls and in the
 * final body frame when `perf_metrics_in_response` is requested for streams.
 */
export declare function parseFireworksUsage(rawUsage: unknown, performanceMetrics?: unknown, headers?: Headers | undefined): TokenUsage | undefined;
/** Anthropic message usage: input_tokens / output_tokens. */
export declare function parseAnthropicUsage(raw: unknown): TokenUsage | undefined;
/**
 * Merge Anthropic streaming usage without losing cache telemetry.
 * `message_start` carries input/cache counts while `message_delta` normally
 * carries only output tokens; replacing the former with the latter made real
 * cache hits appear as zero in the UI and audit log.
 */
export declare function mergeAnthropicStreamUsage(previous: TokenUsage | undefined, current: TokenUsage): TokenUsage;
/** Gemini usageMetadata. */
export declare function parseGeminiUsage(raw: unknown): TokenUsage | undefined;
/** Ollama generate/chat counts. */
export declare function parseOllamaUsage(raw: {
    prompt_eval_count?: number | undefined;
    eval_count?: number | undefined;
}): TokenUsage | undefined;
/** Estimated usage from message list (not billing-accurate). */
export declare function estimateUsageFromMessages(messages: readonly ChatMessage[]): TokenUsage;
export { modelContextWindow, providerContextOverrideTokens, } from "./context-windows.js";
/** Compact integer: 128450 → "128,450"; large → "128.5k" when compact. */
export declare function formatTokenCount(n: number, compact?: boolean): string;
/**
 * Footer chip: current session context fill (not cumulative session billing).
 * An optional denominator is an explicit session model window, never a guessed
 * model limit or auto-compaction trigger.
 */
export declare function formatContextChip(snapshot: ContextUsageSnapshot, opts?: {
    compact?: boolean;
}): string;
/** Merge a new usage into session totals; prefer latest known prompt as context fill. */
export declare function applyUsageToSnapshot(prev: ContextUsageSnapshot | undefined, usage: TokenUsage, contextLimit: number): ContextUsageSnapshot;
export declare function snapshotFromEstimate(messages: readonly ChatMessage[], model: string | undefined, provider?: ProviderId | undefined, prev?: ContextUsageSnapshot | undefined): ContextUsageSnapshot;