/**
 * Agent loop metrics tracking.
 *
 * The {@link Meter} accumulates local metrics during agent invocation and
 * provides them as a read-only {@link AgentMetrics} snapshot via the
 * {@link Meter.metrics} getter for inclusion in {@link AgentResult}.
 *
 * When an OTEL MeterProvider is registered (via {@link setupMeter} or
 * directly), the Meter also emits counters and histograms through the
 * global OTEL metrics API, enabling export to OTLP backends.
 */
import type { Usage, Metrics, ModelMetadataEventData } from '../models/streaming.js';
import type { ToolUse } from '../tools/types.js';
import type { JSONSerializable } from '../types/json.js';
/**
 * Per-tool execution metrics.
 */
export interface ToolMetricsData {
    /**
     * Total number of calls to this tool.
     */
    callCount: number;
    /**
     * Number of successful calls.
     */
    successCount: number;
    /**
     * Number of failed calls.
     */
    errorCount: number;
    /**
     * Total execution time in milliseconds.
     */
    totalTime: number;
}
/**
 * Per-cycle usage tracking.
 */
export interface AgentLoopMetricsData {
    /**
     * Unique identifier for this cycle.
     */
    cycleId: string;
    /**
     * Duration of this cycle in milliseconds.
     */
    duration: number;
    /**
     * Token usage for this cycle.
     */
    usage: Usage;
}
/**
 * Per-invocation metrics tracking.
 */
export interface InvocationMetricsData {
    /**
     * Cycle metrics for this invocation.
     */
    cycles: AgentLoopMetricsData[];
    /**
     * Accumulated token usage for this invocation.
     */
    usage: Usage;
}
/**
 * JSON-serializable representation of AgentMetrics.
 */
export interface AgentMetricsData {
    /**
     * Total number of agent loop cycles executed across all invocations.
     */
    cycleCount: number;
    /**
     * Accumulated token usage across all model invocations.
     */
    accumulatedUsage: Usage;
    /**
     * Accumulated performance metrics across all model invocations.
     */
    accumulatedMetrics: Metrics;
    /**
     * Per-invocation metrics for recent invocations.
     * Only the most recent 50 entries are retained.
     */
    agentInvocations: InvocationMetricsData[];
    /**
     * Per-tool execution metrics keyed by tool name.
     */
    toolMetrics: Record<string, ToolMetricsData>;
    /**
     * The most recent input token count from the last model invocation.
     * Represents the current context window utilization.
     */
    latestContextSize?: number;
    /**
     * Projected context size for the next model call (inputTokens + outputTokens from the last call).
     * Represents the baseline token count the next invocation will start with.
     */
    projectedContextSize?: number;
    /**
     * Total duration of all cycles across all invocations in milliseconds.
     */
    totalDuration?: number;
}
/**
 * Options for recording tool usage.
 */
interface ToolUsageOptions {
    /**
     * The tool that was used.
     */
    tool: ToolUse;
    /**
     * Execution duration in milliseconds.
     */
    duration: number;
    /**
     * Whether the tool call succeeded.
     */
    success: boolean;
}
/**
 * Read-only snapshot of aggregated agent metrics.
 *
 * Returned by {@link Meter.metrics} and stored on {@link AgentResult}.
 * Provides access to cycle counts, tool usage, token consumption,
 * and per-invocation breakdowns. Supports serialization via {@link toJSON}.
 *
 * @example
 * ```typescript
 * const result = await agent.invoke('Hello')
 * console.log(result.metrics?.cycleCount)
 * console.log(result.metrics?.totalDuration)
 * console.log(result.metrics?.accumulatedData)
 * console.log(result.metrics?.toolMetrics)
 * console.log(JSON.stringify(result.metrics))
 * ```
 */
export declare class AgentMetrics implements JSONSerializable<AgentMetricsData> {
    /**
     * Total number of agent loop cycles executed across all invocations.
     */
    readonly cycleCount: number;
    /**
     * Accumulated token usage across all model invocations.
     */
    readonly accumulatedUsage: Usage;
    /**
     * Accumulated performance metrics across all model invocations.
     */
    readonly accumulatedMetrics: Metrics;
    /**
     * Per-invocation metrics for recent invocations.
     * Only the most recent 50 entries are retained to prevent unbounded memory growth.
     * For full history, collect {@link latestAgentInvocation} from each {@link AgentResult}.
     */
    readonly agentInvocations: InvocationMetricsData[];
    /**
     * Per-tool execution metrics keyed by tool name.
     */
    readonly toolMetrics: Record<string, ToolMetricsData>;
    /**
     * The most recent input token count from the last model invocation.
     * Represents the current context window utilization.
     * Returns `undefined` when no invocations have occurred.
     */
    readonly latestContextSize: number | undefined;
    /**
     * Projected context size for the next model call (inputTokens + outputTokens from the last call).
     * Represents the baseline token count the next invocation will start with.
     * Returns `undefined` when no invocations have occurred.
     */
    readonly projectedContextSize: number | undefined;
    /**
     * Total duration of all cycles across all invocations in milliseconds.
     */
    readonly totalDuration: number;
    constructor(data?: Partial<AgentMetricsData>);
    /**
     * The most recent agent invocation, or undefined if none exist.
     */
    get latestAgentInvocation(): InvocationMetricsData | undefined;
    /**
     * Accumulated usage and performance metrics across all model invocations.
     */
    get accumulatedData(): {
        usage: Usage;
        metrics: Metrics;
    };
    /**
     * Average cycle duration in milliseconds, or 0 if no cycles exist.
     */
    get averageCycleTime(): number;
    /**
     * Per-tool execution statistics with computed averages and rates.
     */
    get toolUsage(): Record<string, ToolMetricsData & {
        averageTime: number;
        successRate: number;
    }>;
    /**
     * Returns a JSON-serializable representation of all collected metrics.
     * Called automatically by JSON.stringify().
     *
     * @returns A plain object suitable for round-trip serialization
     */
    toJSON(): AgentMetricsData;
}
/**
 * Accumulates local metrics during agent invocation.
 *
 * Tracks cycle counts, token usage, tool execution stats, and model latency.
 * Use the {@link metrics} getter to obtain a read-only {@link AgentMetrics}
 * snapshot for inclusion in {@link AgentResult}.
 *
 * When an OTEL MeterProvider is registered, the same data is also emitted
 * as OTEL counters and histograms via the global metrics API. If no
 * provider is registered the OTEL meter is a no-op and adds no overhead.
 */
export declare class Meter {
    /**
     * Number of agent loop cycles executed.
     */
    private _cycleCount;
    /**
     * Accumulated token usage across all model invocations.
     */
    private readonly _accumulatedUsage;
    /**
     * Accumulated performance metrics across all model invocations.
     */
    private readonly _accumulatedMetrics;
    /**
     * Per-invocation metrics.
     */
    private readonly _agentInvocations;
    /**
     * Per-tool execution metrics keyed by tool name.
     */
    private readonly _toolMetrics;
    /**
     * The most recent input token count from the last model invocation.
     */
    private _latestContextSize;
    /**
     * Projected context size for the next model call (inputTokens + outputTokens).
     */
    private _projectedContextSize;
    /**
     * Running total of all cycle durations in milliseconds.
     */
    private _totalDuration;
    private readonly _otelMeter;
    private readonly _otelCycleCounter;
    private readonly _otelInvocationCounter;
    private readonly _otelCycleDuration;
    private readonly _otelToolCallCounter;
    private readonly _otelToolErrorCounter;
    private readonly _otelToolDuration;
    private readonly _otelInputTokens;
    private readonly _otelOutputTokens;
    private readonly _otelModelLatency;
    private readonly _otelTimeToFirstToken;
    constructor();
    /**
     * Begin tracking a new agent invocation.
     * Creates a new InvocationMetricsData entry for per-invocation metrics.
     * Evicts the oldest entry when the history exceeds MAX_INVOCATION_HISTORY.
     */
    startNewInvocation(): void;
    /**
     * Start a new agent loop cycle.
     *
     * @returns The cycle id and start time
     */
    startCycle(): {
        cycleId: string;
        startTime: number;
    };
    /**
     * End the current agent loop cycle and record its duration.
     *
     * @param startTime - The timestamp when the cycle started (milliseconds since epoch)
     */
    endCycle(startTime: number): void;
    /**
     * Record metrics for a completed tool invocation.
     *
     * @param options - Tool usage recording options
     */
    endToolCall(options: ToolUsageOptions): void;
    /**
     * Update loop-level metrics from a model response.
     *
     * Call this after each model invocation within a cycle to
     * accumulate usage and latency.
     *
     * @param metadata - The metadata event from a model invocation, or undefined if unavailable
     */
    updateCycle(metadata?: ModelMetadataEventData): void;
    /**
     * Read-only snapshot of the accumulated metrics.
     * Returns an AgentMetrics instance suitable for inclusion in AgentResult.
     */
    get metrics(): AgentMetrics;
    /**
     * The most recent agent invocation, or undefined if none exist.
     */
    private get _latestAgentInvocation();
    /**
     * Update accumulated usage and metrics from a model metadata event.
     *
     * @param metadata - The metadata event from a model invocation
     */
    private _updateFromMetadata;
    /**
     * Update the accumulated token usage with new usage data.
     *
     * @param usage - The usage data to accumulate
     */
    private _updateUsage;
}
export {};
//# sourceMappingURL=meter.d.ts.map