import { TokenUsage } from '../types.js';
/** 单条用量记录 */
export interface UsageRecord {
    /** 记录时间戳（毫秒） */
    timestamp: number;
    /** 会话 ID */
    sessionId: string;
    /** Agent Profile ID（可选） */
    agentProfileId?: string;
    /** LLM Provider 标识 */
    provider: string;
    /** 模型名称 */
    model: string;
    /** Token 用量 */
    usage: TokenUsage;
    /** 估算成本（美元） */
    cost: number;
    /** 迭代轮次 */
    iterations?: number;
}
/** 用量统计查询过滤条件 */
export interface UsageStatsFilter {
    /** 起始时间（毫秒时间戳） */
    startTime?: number;
    /** 结束时间（毫秒时间戳） */
    endTime?: number;
    /** 按 Agent 过滤 */
    agentProfileId?: string;
    /** 按 Provider 过滤 */
    provider?: string;
    /** 按模型过滤 */
    model?: string;
}
/** 用量统计结果 */
export interface UsageStats {
    /** 总 token 数 */
    totalTokens: number;
    /** 总输入 token 数 */
    totalPromptTokens: number;
    /** 总输出 token 数 */
    totalCompletionTokens: number;
    /** 总成本（美元） */
    totalCost: number;
    /** 记录数 */
    recordCount: number;
    /** 按 Provider 分组统计 */
    byProvider: Record<string, {
        tokens: number;
        cost: number;
        count: number;
    }>;
    /** 按模型分组统计 */
    byModel: Record<string, {
        tokens: number;
        cost: number;
        count: number;
    }>;
}
/** Token 预算配置 */
export interface TokenBudget {
    /** 最大 token 数（undefined = 不限制） */
    maxTokens?: number;
    /** 超出预算时的行为 */
    onExceed?: 'warn' | 'abort';
}
/** 预算检查结果 */
export interface BudgetCheckResult {
    /** 是否超出预算 */
    exceeded: boolean;
    /** 当前累计 token 数 */
    currentTokens: number;
    /** 预算上限 */
    maxTokens?: number;
    /** 超出比例（0-1） */
    ratio: number;
}
/**
 * UsageTracker — Token 用量追踪接口
 *
 * 使用方实现此接口即可将用量数据持久化到任意存储后端。
 * Core 提供默认实现 `InMemoryUsageTracker`（内存存储，重启丢失）。
 *
 * @example
 * const tracker = new InMemoryUsageTracker();
 * const engine = new AgentEngine({ ..., usageTracker: tracker });
 */
export interface UsageTracker {
    /** 记录一次 LLM 调用的用量 */
    record(record: Omit<UsageRecord, 'cost' | 'timestamp'>): void;
    /** 查询用量统计 */
    stats(filter?: UsageStatsFilter): UsageStats;
    /** 查询原始记录列表 */
    list(filter?: UsageStatsFilter): UsageRecord[];
    /** 检查会话是否超出 token 预算 */
    checkBudget(sessionId: string, budget: TokenBudget): BudgetCheckResult;
    /** 获取会话累计 token 数 */
    getSessionUsage(sessionId: string): number;
    /** 清空所有记录 */
    clear(): void;
}
/**
 * InMemoryUsageTracker — 内存版用量追踪器
 *
 * 开发/测试用，重启后数据丢失。
 * 上层可替换为持久化实现（如 JsonUsageTracker）。
 */
export declare class InMemoryUsageTracker implements UsageTracker {
    private records;
    /** sessionId → 累计 token 数 */
    private sessionUsageMap;
    record(record: Omit<UsageRecord, 'cost' | 'timestamp'>): void;
    stats(filter?: UsageStatsFilter): UsageStats;
    list(filter?: UsageStatsFilter): UsageRecord[];
    checkBudget(sessionId: string, budget: TokenBudget): BudgetCheckResult;
    getSessionUsage(sessionId: string): number;
    clear(): void;
    private filterRecords;
}
//# sourceMappingURL=usage-tracker.d.ts.map