@migor/agentia 0.7.1 → 0.8.0

package/dist/integrations/metrics-otlp.js

@@ -0,0 +1,178 @@
+import { scoreLabels } from './metrics-state.js';
+/**
+ * metricsSink 的 **OTLP/JSON 导出**（E5）：从 `MetricsState` 组装 payload + POST 到
+ * `${endpoint}/v1/metrics`。只读状态、不改账。module 级 export，不进公共面（`src/index.ts`）。
+ */
+/**
+ * OTLP metrics 导出失败（带数值 `status`）。
+ *
+ * 为什么不能抛裸 `Error`：`engine/errors.ts` 的分类是鸭子类型，只看数据属性。
+ * 裸 Error 会被判 `unknown` + `retryable:false` —— 宿主在 `onExportError` 里拿不到
+ * status，也就没法区分「collector 拒收（4xx，改配置）」与「collector 挂了（5xx，等它回来）」。
+ * 形状与 `otlp.ts` 的 `OtlpExportError` 一致（同层两处导出器不该有两种错误形状）。
+ *
+ * 注：本处抛错由 `onExportError` 接住并按「观测失败不得击穿业务」吞掉 —— 带 status 是为了
+ * **可判断**，不是为了让谁重试。
+ */
+export class MetricsExportError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'MetricsExportError';
+        this.status = status;
+    }
+}
+// —— OTLP/JSON 导出（E5）——
+// epoch 毫秒 ×1e6 ≈ 1.7e18 > 2^53，double 直接乘会丢精度 —— 必须先取整再转 BigInt
+const nanos = (ms) => String(BigInt(Math.round(ms)) * 1000000n);
+const strAttr = (key, v) => ({ key, value: { stringValue: v } });
+export function buildOtlpPayload(state, opts) {
+    const p = opts.prefix;
+    const now = nanos(Date.now());
+    const start = nanos(opts.startedAtMs);
+    const s = state.snapshot();
+    const metricTable = new Map();
+    /** 查表取已建 Metric，没有则建；同名只保留首次的 description（冲突描述本身是 semantic error） */
+    const takeMetric = (name, help) => {
+        let m = metricTable.get(name);
+        if (!m) {
+            m = { name, description: help };
+            metricTable.set(name, m);
+        }
+        return m;
+    };
+    const sum = (name, value, help, attrs, monotonic = true) => {
+        const m = takeMetric(name, help);
+        m.sum ??= { aggregationTemporality: 2, isMonotonic: monotonic, dataPoints: [] };
+        m.sum.dataPoints.push({
+            attributes: attrs,
+            startTimeUnixNano: start,
+            timeUnixNano: now,
+            asInt: String(value),
+        });
+    };
+    // 浮点指标（成本）必须走 asDouble —— OTLP 的 asInt 是 string 编码 int64，
+    // 塞浮点（如 0.25）会让 collector 直接拒收整批数据
+    const sumDouble = (name, value, help, attrs) => {
+        const m = takeMetric(name, help);
+        m.sum ??= { aggregationTemporality: 2, isMonotonic: true, dataPoints: [] };
+        m.sum.dataPoints.push({
+            attributes: attrs,
+            startTimeUnixNano: start,
+            timeUnixNano: now,
+            asDouble: value,
+        });
+    };
+    // gauge 没有理由只收 int：评分值是浮点，统一走 asDouble
+    const gauge = (name, value, help, attrs) => {
+        const m = takeMetric(name, help);
+        m.gauge ??= { dataPoints: [] };
+        m.gauge.dataPoints.push({
+            attributes: attrs,
+            startTimeUnixNano: start,
+            timeUnixNano: now,
+            asDouble: value,
+        });
+    };
+    const hist = (name, stat, help, attrs) => {
+        const m = takeMetric(name, help);
+        m.histogram ??= { aggregationTemporality: 2, dataPoints: [] };
+        m.histogram.dataPoints.push({
+            attributes: attrs,
+            startTimeUnixNano: start,
+            timeUnixNano: now,
+            count: stat.count,
+            sum: stat.sumMs,
+            // OTLP 的 bucketCounts 是每桶**非累积**计数（Prometheus 文本才是累积语义）
+            bucketCounts: stat.perBucket(),
+            explicitBounds: [...stat.boundsList],
+        });
+    };
+    sum(`${p}runs_total`, s.runs, 'run 总数', []);
+    sum(`${p}runs_failed_total`, s.failed, '失败的 run 数', []);
+    // tokens_total：四类 kind 分项收进**同一个** Metric；description 与 Prometheus 侧
+    // render() 的 family() 统一成同一句总述（同名 Metric 各带一份描述是 semantic error）
+    const tokensHelp = 'token 累计（kind 分项：input / output / cache_read / cache_creation）';
+    sum(`${p}tokens_total`, state.tokens.input, tokensHelp, [strAttr('kind', 'input')]);
+    sum(`${p}tokens_total`, state.tokens.output, tokensHelp, [strAttr('kind', 'output')]);
+    sum(`${p}tokens_total`, state.tokens.cacheRead, tokensHelp, [strAttr('kind', 'cache_read')]);
+    sum(`${p}tokens_total`, state.tokens.cacheCreation, tokensHelp, [
+        strAttr('kind', 'cache_creation'),
+    ]);
+    sumDouble(`${p}cost_usd_total`, s.costUsd, '累计成本估算（美元）', []);
+    hist(`${p}run_duration_ms`, state.runStat, 'run 时长（毫秒）', []);
+    for (const label of [...state.capabilities.keys()].sort()) {
+        const acc = state.capabilities.get(label);
+        const attrs = [strAttr('capability', label)];
+        sum(`${p}capability_calls_total`, acc.calls, '能力调用次数', attrs);
+        sum(`${p}capability_errors_total`, acc.errors, '能力失败次数', attrs);
+        hist(`${p}capability_duration_ms`, acc.stat, '能力调用耗时（毫秒）', attrs);
+        if (acc.tokens !== null)
+            sum(`${p}capability_tokens_total`, acc.tokens, '子孙 token 合计', attrs);
+        if (acc.costUsd !== null)
+            sumDouble(`${p}capability_cost_usd_total`, acc.costUsd, '估算成本（美元）', attrs);
+    }
+    for (const model of [...state.models.keys()].sort()) {
+        const acc = state.models.get(model);
+        const attrs = [strAttr('model', model)];
+        sum(`${p}model_turns_total`, acc.turns, '模型往返次数', attrs);
+        sum(`${p}model_tokens_total`, acc.tokens, '模型 token 合计', attrs);
+        sumDouble(`${p}model_cost_usd_total`, acc.costUsd, '模型估算成本（美元）', attrs);
+        if (acc.unpricedTurns > 0) {
+            sum(`${p}model_unpriced_turns_total`, acc.unpricedTurns, '未定价 turn 数', attrs);
+        }
+        hist(`${p}model_duration_ms`, acc.stat, '模型往返耗时（毫秒）', attrs);
+    }
+    for (const key of [...state.scores.keys()].sort()) {
+        const acc = state.scores.get(key);
+        const { name, source } = scoreLabels(key);
+        const attrs = [strAttr('name', name), strAttr('source', source)];
+        gauge(`${p}score`, acc.value, '最近一次评分', attrs);
+        sum(`${p}score_total`, acc.count, '评分条数', attrs);
+    }
+    // 基数上限可见性（与 Prometheus 侧 `*_dropped_keys{kind=…}` 同名同义）：
+    // 三个 kind 收进同一个 gauge Metric
+    const droppedHelp = '因基数上限被折叠的不同键数';
+    gauge(`${p}dropped_keys`, state.capBudget.dropped, droppedHelp, [strAttr('kind', 'capability')]);
+    gauge(`${p}dropped_keys`, state.modelBudget.dropped, droppedHelp, [strAttr('kind', 'model')]);
+    gauge(`${p}dropped_keys`, state.scoreBudget.dropped, droppedHelp, [strAttr('kind', 'score')]);
+    const metrics = [...metricTable.values()];
+    const resourceAttrs = [
+        strAttr('service.name', opts.serviceName),
+        ...Object.entries(opts.resourceAttributes ?? {}).map(([k, v]) => strAttr(k, v)),
+    ];
+    return {
+        resourceMetrics: [
+            {
+                resource: { attributes: resourceAttrs },
+                scopeMetrics: [{ scope: { name: 'agentia' }, metrics }],
+            },
+        ],
+    };
+}
+export async function flushOtlpMetrics(state, opts) {
+    let payload;
+    try {
+        payload = buildOtlpPayload(state, opts);
+    }
+    catch (e) {
+        opts.onExportError?.(e);
+        return;
+    }
+    try {
+        const res = await fetch(`${opts.endpoint}/v1/metrics`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(payload),
+            ...(opts.timeoutMs > 0 ? { signal: AbortSignal.timeout(opts.timeoutMs) } : {}),
+        });
+        if (!res.ok) {
+            const text = (await res.text()).slice(0, 200);
+            throw new MetricsExportError(res.status, `OTLP metrics 导出失败: HTTP ${res.status} ${text}`);
+        }
+    }
+    catch (e) {
+        opts.onExportError?.(e); // 观测失败不得击穿业务
+    }
+}
+//# sourceMappingURL=metrics-otlp.js.map

package/dist/integrations/metrics-otlp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-otlp.js","sourceRoot":"","sources":["../../src/integrations/metrics-otlp.ts"],"names":[],"mappings":"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"}

package/dist/integrations/metrics-render.d.ts

@@ -0,0 +1,2 @@
+import type { MetricsState } from './metrics-state.js';
+export declare function renderPrometheus(state: MetricsState, p: string): string;

package/dist/integrations/metrics-render.js

@@ -0,0 +1,145 @@
+import { scoreLabels } from './metrics-state.js';
+/**
+ * metricsSink 的 **Prometheus 文本渲染**（`text/plain; version=0.0.4`，零依赖手写）。
+ * 只读 `MetricsState`，不改账。module 级 export，不进公共面（`src/index.ts`）。
+ */
+/**
+ * 一个指标家族的完整块：HELP/TYPE 各**恰好一行**，后接全部样本行。
+ * expfmt 对同名指标的第二条 HELP/TYPE 是**硬错误**（整次 scrape 失败），
+ * 所以家族头必须集中在这里发一次，绝不能让每条样本自带；同名指标也只能有一种 TYPE
+ * （histogram 与分位 gauge 因此拆成 `*_duration_ms` 与 `*_duration_ms_last` 两个名字）。
+ */
+const family = (name, type, help, samples) => `# HELP ${name} ${help}\n# TYPE ${name} ${type}\n${samples.join('\n')}\n`;
+/** Prometheus label 值转义：\、"、换行必须转义，否则一个含引号的能力名/模型名就损坏整页 exposition */
+const escLabel = (v) => v.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+/** 一个 stat 的 histogram 样本（bucket 累积 + sum + count），labels 形如 `{k="v"}` */
+const histogramSamples = (name, stat, labels = '') => {
+    const inner = labels ? labels.slice(1, -1) + ',' : ''; // 去掉外层 {} 再补逗号
+    const at = (extra) => `{${inner}${extra}}`;
+    const out = [];
+    const cum = stat.cumulative();
+    for (let i = 0; i < stat.boundsList.length; i++) {
+        out.push(`${name}_bucket${at(`le="${stat.boundsList[i]}"`)} ${cum[i]}`);
+    }
+    out.push(`${name}_bucket${at(`le="+Inf"`)} ${stat.count}`);
+    out.push(`${name}_sum${labels} ${stat.sumMs}`);
+    out.push(`${name}_count${labels} ${stat.count}`);
+    return out;
+};
+export function renderPrometheus(state, p) {
+    const out = [];
+    out.push(family(`${p}runs_total`, 'counter', 'run 总数（成功 + 失败）', [
+        `${p}runs_total ${state.runs}`,
+    ]));
+    out.push(family(`${p}runs_failed_total`, 'counter', '失败的 run 数（trace.status=error）', [
+        `${p}runs_failed_total ${state.failed}`,
+    ]));
+    out.push(family(`${p}tokens_total`, 'counter', 'token 累计（kind 分项：input / output / cache_read / cache_creation）', [
+        `${p}tokens_total{kind="input"} ${state.tokens.input}`,
+        `${p}tokens_total{kind="output"} ${state.tokens.output}`,
+        `${p}tokens_total{kind="cache_read"} ${state.tokens.cacheRead}`,
+        `${p}tokens_total{kind="cache_creation"} ${state.tokens.cacheCreation}`,
+    ]));
+    out.push(family(`${p}cost_usd_total`, 'counter', '累计成本估算（美元）', [
+        `${p}cost_usd_total ${state.costUsd}`,
+    ]));
+    // 基数上限的**可见性**：被折叠掉的不同键数。与 `snapshot()` 的同名字段一一对应 ——
+    // 此前只有 snapshot() 有、render() 没有，于是「按文档把 metricsSink 接到 /metrics」的部署
+    // **完全看不见折叠发生**（静默丢失）；而同一份文件对「算不出成本的 turn」专门发了
+    // `model_unpriced_turns_total`，口径不一致。
+    // 与 unpriced 不同：**恒定发三行**（不是 >0 才发）—— 「0 → N」这个变化本身就是要告警的信号。
+    out.push(family(`${p}dropped_keys`, 'gauge', '因基数上限被折叠的不同键数（kind 分项）', [
+        `${p}dropped_keys{kind="capability"} ${state.capBudget.dropped}`,
+        `${p}dropped_keys{kind="model"} ${state.modelBudget.dropped}`,
+        `${p}dropped_keys{kind="score"} ${state.scoreBudget.dropped}`,
+    ]));
+    // 时长：histogram（可跨实例聚合）+ 窗口内精确分位（单实例好读），两种口径并存。
+    // 分位 gauge 必须用另一个名字 `*_last` —— 同名指标只允许一种 TYPE，
+    // 先发 histogram 再发 gauge 会被 expfmt 判硬错误，整次 scrape 失败。
+    out.push(family(`${p}run_duration_ms`, 'histogram', 'run 时长（毫秒）', [
+        ...histogramSamples(`${p}run_duration_ms`, state.runStat),
+    ]));
+    out.push(family(`${p}run_duration_ms_last`, 'gauge', 'run 时长分位（毫秒，滑动窗口内精确值）', [
+        `${p}run_duration_ms_last{quantile="0.5"} ${state.runStat.percentile(0.5)}`,
+        `${p}run_duration_ms_last{quantile="0.95"} ${state.runStat.percentile(0.95)}`,
+    ]));
+    // —— 能力维度（E2）：同一家族的样本跨 label 聚合，家族头只发一次 ——
+    const capLabels = [...state.capabilities.keys()].sort();
+    if (capLabels.length > 0) {
+        const calls = [];
+        const errors = [];
+        const durations = [];
+        const durationQuantiles = [];
+        const capabilityTokens = [];
+        const capabilityCosts = [];
+        for (const label of capLabels) {
+            const acc = state.capabilities.get(label);
+            const lv = escLabel(label);
+            const l = `{capability="${lv}"}`;
+            calls.push(`${p}capability_calls_total${l} ${acc.calls}`);
+            errors.push(`${p}capability_errors_total${l} ${acc.errors}`);
+            durations.push(...histogramSamples(`${p}capability_duration_ms`, acc.stat, l));
+            durationQuantiles.push(`${p}capability_duration_ms_last{capability="${lv}",quantile="0.5"} ${acc.stat.percentile(0.5)}`, `${p}capability_duration_ms_last{capability="${lv}",quantile="0.95"} ${acc.stat.percentile(0.95)}`);
+            if (acc.tokens !== null)
+                capabilityTokens.push(`${p}capability_tokens_total${l} ${acc.tokens}`);
+            if (acc.costUsd !== null)
+                capabilityCosts.push(`${p}capability_cost_usd_total${l} ${acc.costUsd}`);
+        }
+        out.push(family(`${p}capability_calls_total`, 'counter', '能力调用次数', calls));
+        out.push(family(`${p}capability_errors_total`, 'counter', '能力失败次数', errors));
+        out.push(family(`${p}capability_duration_ms`, 'histogram', '能力调用耗时（毫秒）', durations));
+        out.push(family(`${p}capability_duration_ms_last`, 'gauge', '能力调用耗时分位（窗口内精确值）', durationQuantiles));
+        if (capabilityTokens.length > 0) {
+            out.push(family(`${p}capability_tokens_total`, 'counter', 'skill/subagent 的子孙 token 合计', capabilityTokens));
+        }
+        if (capabilityCosts.length > 0) {
+            out.push(family(`${p}capability_cost_usd_total`, 'counter', 'skill/subagent 的估算成本（美元）', capabilityCosts));
+        }
+    }
+    // —— 模型维度（E3）——
+    const modelNames = [...state.models.keys()].sort();
+    if (modelNames.length > 0) {
+        const turns = [];
+        const modelTokens = [];
+        const modelCosts = [];
+        const unpriced = [];
+        const durations = [];
+        const durationQuantiles = [];
+        for (const model of modelNames) {
+            const acc = state.models.get(model);
+            const mv = escLabel(model);
+            const l = `{model="${mv}"}`;
+            turns.push(`${p}model_turns_total${l} ${acc.turns}`);
+            modelTokens.push(`${p}model_tokens_total${l} ${acc.tokens}`);
+            modelCosts.push(`${p}model_cost_usd_total${l} ${acc.costUsd}`);
+            if (acc.unpricedTurns > 0)
+                unpriced.push(`${p}model_unpriced_turns_total${l} ${acc.unpricedTurns}`);
+            durations.push(...histogramSamples(`${p}model_duration_ms`, acc.stat, l));
+            durationQuantiles.push(`${p}model_duration_ms_last{model="${mv}",quantile="0.5"} ${acc.stat.percentile(0.5)}`, `${p}model_duration_ms_last{model="${mv}",quantile="0.95"} ${acc.stat.percentile(0.95)}`);
+        }
+        out.push(family(`${p}model_turns_total`, 'counter', '模型往返次数', turns));
+        out.push(family(`${p}model_tokens_total`, 'counter', '模型 token 合计（四类之和）', modelTokens));
+        out.push(family(`${p}model_cost_usd_total`, 'counter', '模型估算成本（美元，仅已定价部分）', modelCosts));
+        if (unpriced.length > 0) {
+            out.push(family(`${p}model_unpriced_turns_total`, 'counter', '算不出成本的 turn 数（模型不在价格表内）', unpriced));
+        }
+        out.push(family(`${p}model_duration_ms`, 'histogram', '模型往返耗时（毫秒）', durations));
+        out.push(family(`${p}model_duration_ms_last`, 'gauge', '模型往返耗时分位（窗口内精确值）', durationQuantiles));
+    }
+    // —— 评分维度（R7）：gauge 记最近一次值、counter 记条数，label 为 name × source ——
+    if (state.scores.size > 0) {
+        const gaugeSamples = [];
+        const counterSamples = [];
+        for (const key of [...state.scores.keys()].sort()) {
+            const acc = state.scores.get(key);
+            const { name, source } = scoreLabels(key);
+            const l = `{name="${escLabel(name)}",source="${escLabel(source)}"}`;
+            gaugeSamples.push(`${p}score${l} ${acc.value}`);
+            counterSamples.push(`${p}score_total${l} ${acc.count}`);
+        }
+        out.push(family(`${p}score`, 'gauge', '最近一次评分（label 为评分维度与来源）', gaugeSamples));
+        out.push(family(`${p}score_total`, 'counter', '评分条数', counterSamples));
+    }
+    return out.join('');
+}
+//# sourceMappingURL=metrics-render.js.map

package/dist/integrations/metrics-render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-render.js","sourceRoot":"","sources":["../../src/integrations/metrics-render.ts"],"names":[],"mappings":"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"}

package/dist/integrations/metrics-state.d.ts

@@ -0,0 +1,191 @@
+import type { Trace } from '../core/trace.js';
+/**
+ * metricsSink 的**状态层**：进程内累加器 + 快照（本文件）与渲染/导出（`metrics-render.ts` /
+ * `metrics-otlp.ts`）分离。本文件只管「账」，不管「怎么给人看 / 怎么发出去」。
+ * module 级 export，不进公共面（`src/index.ts`）。
+ */
+/** 能力维度指标（`snapshot().capabilities[label]`） */
+export interface CapabilityMetrics {
+    /** 该能力的调用次数 */
+    calls: number;
+    /** 其中失败次数（工具 `ok:false`；skill/subagent 的 capability span `status:'error'`） */
+    errors: number;
+    /** 单次调用耗时（毫秒）的窗口内精确分位；无样本时 0 */
+    latencyP50: number;
+    latencyP95: number;
+    /** 仅 skill/subagent：子孙 llm.turn 的 token 聚合（四类之和）；工具为 null */
+    tokens: number | null;
+    /** 仅 skill/subagent：估算成本（美元）；未定价或工具为 null */
+    costUsd: number | null;
+}
+/** 模型维度指标（`snapshot().models[model]`） */
+export interface ModelMetrics {
+    /** 该模型的 llm.turn 次数 */
+    turns: number;
+    /** 四类 token 之和 */
+    tokens: number;
+    /** 已定价部分的成本（美元）；全未定价时为 0 */
+    costUsd: number;
+    /** 成本估不出来的 turn 数（模型不在价格表内，且未用 priceOverrides 覆盖）*/
+    unpricedTurns: number;
+    latencyP50: number;
+    latencyP95: number;
+}
+/** 评分维度指标（`snapshot().scores[key]`，key 为 `name@source`，source 缺省时裸 name） */
+export interface ScoreMetrics {
+    /** 最近一次评分值（gauge 语义 —— 分数不是累加量） */
+    value: number;
+    /** 评分条数 */
+    count: number;
+    /** 评分值合计（平均 = sum / count） */
+    sum: number;
+}
+/** 进程内累计快照（`snapshot()` 返回） */
+export interface MetricsSnapshot {
+    /** 投递过 trace 的 run 总数（= `export` 被调用次数） */
+    runs: number;
+    /** 其中 `trace.status === 'error'` 的条数（含 budget_exceeded / aborted / error） */
+    failed: number;
+    /** run 时长（根 span `endedAt - startedAt`）分位，毫秒；窗口内无样本时 0 */
+    latencyP50: number;
+    latencyP95: number;
+    /**
+     * 累计 token —— 口径 = **四类之和**（input + output + cacheRead + cacheCreation），
+     * 与 `BudgetGuard` 的 token 口径一致。分项在 `render()` 里以 label 给出，不会丢。
+     */
+    tokens: number;
+    /** 累计成本估算（美元）；模型不在价格表内时该 run 不计入（见 usage.ts） */
+    costUsd: number;
+    /**
+     * 能力维度（`labelMode:'none'` 时为空对象）。超 `maxCapabilities` 的键折叠在
+     * `'__other__'` —— 该桶照常累加，所以这里的**总量**不受上限影响。
+     */
+    capabilities: Record<string, CapabilityMetrics>;
+    /** 模型维度；超 `maxModels` 的键折叠在 `'__other__'`（同上：总量不丢） */
+    models: Record<string, ModelMetrics>;
+    /**
+     * 评分维度（key 为 `name@source`，source 缺省时裸 name；无评分时为空对象）；
+     * 超 `maxScores` 的键折叠在 `'__other__'`。
+     */
+    scores: Record<string, ScoreMetrics>;
+    /** 因 `maxCapabilities` 上限被归入 `__other__` 的不同能力数 */
+    droppedCapabilities: number;
+    /** 因 `maxModels` 上限被归入 `__other__` 的不同模型数 */
+    droppedModels: number;
+    /** 因 `maxScores` 上限被归入 `__other__` 的不同评分维度数 */
+    droppedScores: number;
+}
+/**
+ * 标签基数配额：三个维度共用的「有界键空间」。
+ *
+ * 键第一次出现且在额度内 → 分到自己的标签（**永远认自己**，不会时而被折叠时而不折叠）；
+ * 超限 → 归入 `OTHER_LABEL`。
+ *
+ * 被折叠的键记进 `over`，只为回答「多少个**不同**的键被折叠了」；这本账自身也有界
+ * （`MAX_DROPPED_TRACKING`），满了以后 `dropped` 是下界。
+ */
+export declare class KeyBudget {
+    private readonly max;
+    private readonly assigned;
+    private readonly over;
+    constructor(max: number);
+    /** 取键的标签：额度内原样返回，超限返回 `OTHER_LABEL` */
+    take(key: string): string;
+    /** 被折叠的**不同**键数（记满 `MAX_DROPPED_TRACKING` 后为下界） */
+    get dropped(): number;
+    /** 清空配额（`reset()` 用）—— 与 `capabilities` / `models` / `scores` 三张表同步清 */
+    reset(): void;
+}
+/**
+ * 时长统计：环形窗口（算窗口内精确分位）+ 累积直方图（算可聚合的 bucket）。
+ * run / 能力 / 模型共用同一个实现，保证三种粒度的口径与取整完全一致。
+ */
+export declare class DurationStat {
+    private readonly windowSize;
+    private readonly bounds;
+    private readonly ring;
+    private cursor;
+    /** 每桶非累积计数：counts[i] 对应 le = bounds[i]；末位是 +Inf 桶 */
+    private readonly counts;
+    private total;
+    private sum;
+    constructor(windowSize: number, bounds: readonly number[]);
+    add(ms: number): void;
+    get count(): number;
+    get sumMs(): number;
+    get windowSamples(): number;
+    /**
+     * 窗口内精确分位（Prometheus 的 quantile 语义：取第 ceil(q·n) 个样本）。
+     * 算法单源在 `core/stats.ts` —— 与 `report.ts` 的时长 p50/p95 必须同口径，
+     * 否则同一条 trace 在看板与报告里会有两个 p95。
+     */
+    percentile(q: number): number;
+    /** 累积 bucket 计数（长度 = bounds+1，末位为 +Inf = count）—— Prometheus 文本语义 */
+    cumulative(): number[];
+    /** 每桶**非累积**计数 —— OTLP histogram 的 bucketCounts 语义（与 cumulative() 千万别混用） */
+    perBucket(): number[];
+    get boundsList(): readonly number[];
+    reset(): void;
+}
+/** 能力累加器：调用数 / 失败数 / 时长；skill·subagent 还带 token 与成本 */
+export interface CapabilityAcc {
+    calls: number;
+    errors: number;
+    stat: DurationStat;
+    tokens: number | null;
+    costUsd: number | null;
+}
+export interface ModelAcc {
+    turns: number;
+    tokens: number;
+    costUsd: number;
+    unpricedTurns: number;
+    stat: DurationStat;
+}
+/**
+ * 评分键 → 指标标签。键有两种形态：**折叠桶**（`__other__`，整个键就是标签，不含 `\t`）
+ * 与正常的 `name\tsource`（source 缺省为 ''）。两个出口（Prometheus 文本 / OTLP）共用一处
+ * 解码 —— 各切各的必然有一处把折叠桶切成乱码。
+ */
+export declare function scoreLabels(key: string): {
+    name: string;
+    source: string;
+};
+/**
+ * 进程内累加器：`metricsSink` 的全部可变状态（run / 能力 / 模型 / 评分四个维度 +
+ * 三个基数配额）。渲染（`metrics-render.ts`）与 OTLP 导出（`metrics-otlp.ts`）只读它。
+ */
+export declare class MetricsState {
+    private readonly opts;
+    runs: number;
+    failed: number;
+    costUsd: number;
+    readonly tokens: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheCreation: number;
+    };
+    readonly runStat: DurationStat;
+    readonly capabilities: Map<string, CapabilityAcc>;
+    readonly models: Map<string, ModelAcc>;
+    /** 评分累加器：key = `${name}\t${source}`（source 缺省 ''；\t 不会出现在正常评分名里，做天然分隔符） */
+    readonly scores: Map<string, ScoreMetrics>;
+    readonly capBudget: KeyBudget;
+    readonly modelBudget: KeyBudget;
+    readonly scoreBudget: KeyBudget;
+    constructor(opts: {
+        windowSize: number;
+        maxCapabilities: number;
+        maxModels: number;
+        maxScores: number;
+        labelMode: 'capability' | 'kind' | 'none';
+        buckets: readonly number[];
+    });
+    private newCapability;
+    /** 能力标签分配：labelMode 决定粒度，capBudget 决定基数上限 */
+    private labelFor;
+    accumulate(trace: Trace): void;
+    snapshot(): MetricsSnapshot;
+    reset(): void;
+}