/**
 * Usage extraction utilities for converting AI SDK usage to Mastra UsageStats
 */
import type { UsageStats } from '@mastra/core/observability';
import type { LanguageModelUsage, ProviderMetadata } from '@mastra/core/stream';
/**
 * Extracts and normalizes token usage from AI SDK response, including
 * provider-specific cache tokens from providerMetadata.
 *
 * Cache token extraction priority (highest to lowest):
 * 1. AI SDK aggregated inputTokenDetails (properly summed across all steps in multi-step runs)
 * 2. Mastra-aggregated top-level usage fields (usage.cachedInputTokens, usage.cacheCreationInputTokens) -
 *    summed across steps by RunOutput, so they are correct for multi-step runs.
 * 3. Provider-specific providerMetadata (accurate for single-step, LAST STEP ONLY in multi-step).
 *
 * Handles:
 * - OpenAI: cachedInputTokens in usage object
 * - Anthropic: cacheCreationInputTokens, cacheReadInputTokens in providerMetadata.anthropic
 * - Google/Gemini: cachedContentTokenCount, thoughtsTokenCount in providerMetadata.google.usageMetadata
 * - OpenRouter: Uses OpenAI-compatible structure (cache tokens in usage)
 *
 * @param usage - The LanguageModelV2Usage from AI SDK response
 * @param providerMetadata - Optional provider-specific metadata
 * @returns UsageStats with inputDetails and outputDetails
 */
export declare function extractUsageMetrics(usage?: LanguageModelUsage, providerMetadata?: ProviderMetadata): UsageStats;
/**
 * Sum two UsageStats into a new one. Treats undefined fields as zero when
 * the other side has a value, and preserves undefined when both are absent.
 * Used to roll up internal model-generation usage onto a visible ancestor
 * span so cost / token attribution survives internal-span filtering.
 */
export declare function addUsageStats(a: UsageStats | undefined, b: UsageStats): UsageStats;
//# sourceMappingURL=usage.d.ts.map