/**
 * In-memory aggregator for agent-pushed metrics.
 *
 * Agents push their OTel metrics snapshots via the WS `agent.metrics` message.
 * This aggregator stores the latest snapshot per agent and produces a
 * cardinality-bounded view by **collapsing all agents within the same
 * scaler pool into one series per (metric, labels, scaler)**. The
 * `agent_id` label is intentionally NOT emitted — including it would
 * make Mimir cardinality grow with the number of agents that have ever
 * existed (every ephemeral firecracker microVM minted a fresh ID), which
 * is unbounded. The caller-side dashboard filters by `scaler` instead,
 * which has a fixed enum of values (`stateful` / `container` /
 * `firecracker` / `bare-metal`).
 *
 * Aggregation rules per metric kind:
 *   - counter / upDownCounter / gauge → SUM across agents in the pool
 *   - histogram → bucket-by-bucket SUM, plus summed `_count` / `_sum`
 *
 * Trade-off: counter rates are approximate during agent churn. If
 * agent A reports `100` at t1 and disconnects, then agent B starts
 * fresh at `0` for t2, the combined series steps 100 → 0 — which
 * Prometheus interprets as a reset and `rate()` handles correctly.
 * Over a longer window though (e.g. a day with many ephemeral agents
 * appearing + disappearing), the integrated count can under-count.
 * The orchestrator-side counters (`kici_orch_*`) are the canonical
 * source for absolute totals; the agent counters here are for live
 * "what's happening right now" panels.
 *
 * Cleanup: after an agent disconnects, its snapshot is retained for one
 * configurable retention period (default 30s, ~2x scrape interval) so
 * Prometheus can scrape it at least once before it disappears.
 */
/** Shape of a single metric data point pushed by the agent. */
export interface MetricSnapshot {
    name: string;
    type: 'counter' | 'histogram' | 'gauge' | 'upDownCounter';
    value?: number;
    labels?: Record<string, string>;
    buckets?: Array<{
        le: number;
        count: number;
    }>;
    count?: number;
    sum?: number;
}
export declare class AgentMetricsAggregator {
    private store;
    private defaultRetentionMs;
    /**
     * Optional lookup: agentId → scaler backend name (e.g. `container`,
     * `firecracker`, `bare-metal`). Returning null marks the agent as
     * static / stateful — we then stamp the `scaler` label as `'stateful'`.
     * Wired from ScalerManager.getBackendName in production. Tests can
     * leave it undefined; in that case the `scaler` label is omitted.
     */
    private readonly getScalerForAgent?;
    constructor(opts?: {
        retentionMs?: number;
        getScalerForAgent?: (agentId: string) => string | null;
    });
    /**
     * Resolve the `scaler` label for one agentId. Centralized so both the
     * structured snapshot (Mimir push) and the Prometheus text
     * exporter (HTTP /metrics) stamp identical values.
     */
    private resolveScalerLabel;
    /** Store or replace metrics for an agent. */
    update(agentId: string, metrics: MetricSnapshot[]): void;
    /** Mark an agent as disconnected (start the retention countdown). */
    markDisconnected(agentId: string): void;
    /** Remove entries where disconnectedAt + retentionMs < now. */
    cleanup(retentionMs?: number): void;
    /**
     * Build a stable string key for grouping metrics across agents. The
     * key encodes the metric name plus every label except `agent_id`
     * (which is dropped) and including the resolved `scaler`. Sorted so
     * insertion order can't sneak into the key.
     */
    private groupKey;
    /**
     * Walk every stored snapshot and bucket points into per-(metric, labels)
     * groups, summing counter / gauge values and merging histogram buckets
     * across all agents in each bucket. The bucketing key includes the
     * `scaler` label and excludes `agent_id`, so the output is one series
     * per (metric, labels-except-agent_id, scaler) combination.
     *
     * Returns one MetricSnapshot per group so both `getStructuredSnapshot`
     * and `getPrometheusText` can iterate the same shape.
     */
    private aggregateAcrossAgents;
    /**
     * Produce a structured snapshot of all stored agent metrics in the
     * `OrchMetrics['metrics']` wire shape — same format the orchestrator's
     * own `MetricsReporter` produces from its OTel exporter. Used by the
     * Platform-bound Mimir push pipeline so agent metrics land in Mimir
     * per-org alongside `kici_orch_*` .
     *
     * Output is **already aggregated across agents per scaler** — see the
     * class docstring for the cardinality rationale and counter trade-off.
     *
     * Runs `cleanup()` first so disconnected agents past their retention
     * window stop being emitted.
     */
    getStructuredSnapshot(): MetricSnapshot[];
    /**
     * Produce Prometheus exposition text for all stored agent metrics,
     * aggregated across agents per scaler. See `getStructuredSnapshot` for
     * the aggregation rules. Runs auto-cleanup before generating output.
     *
     * Groups metrics by name and emits `# TYPE` directives so Prometheus
     * correctly interprets histograms, counters, and gauges.
     */
    getPrometheusText(): string;
    private formatHistogram;
}
//# sourceMappingURL=agent-metrics-aggregator.d.ts.map