@sema-agent/server 1.323.0 → 2.0.0

package/dist/model-select.js

@@ -1,7 +1,34 @@
 import { parseModelMention } from "@sema-agent/core";
+/**
+ * Resolve the model ref for a task spec from the request (CLI `/model` picker + `run --model`).
+ *
+ * Priority (a deliberate selection beats incidental free text):
+ *   1) an explicit, allow-listed `body.model` (the picker / `--model <ref>` flag),
+ *   2) an inline `@name` mention in the objective (core's `parseModelMention`),
+ *   3) the `default` role.
+ *
+ * Security: BOTH the explicit field and the @mention are gated by the SAME catalog (`config.models` keys), so
+ * untrusted body/text can pick WHICH configured model but can never inject a baseUrl/apiKey (parseModelMention
+ * only ever returns an allow-listed catalog name).
+ *
+ * [865]②(clay 生产实锤:onboard 选 kimi 实跑 Qwen):
+ *  - explicit ref 走 name+id 双键索引({@link matchCatalogModel})——壳 boot 回读的 mainLoopModel 是 **id 形**,
+ *    目录键是 **name 形**,单键索引把 id 形请求当「未知」静默落 default = session 中途静默换模型(最恶性的
+ *    上下文污染路径)。
+ *  - 真未知不再无声:FRESH submit 在 HTTP 门 400 fail-loud(带 available 列表,http/server.ts);本函数保持
+ *    不 throw(RESUME 重放持久化 body 不过 400 门——模型可能事后被移出目录,砖死 resume 比降级更糟),但把
+ *    未知 ref 透出给调用方(`unknownExplicit`),resolveSpec 记 warn——降级永远可见,绝不静默。
+ *
+ * Returns the chosen model ref AND the objective with any `@mention` stripped (parseModelMention's cleanedText).
+ *
+ * 🔴 Was a real defect: resolveSpec previously read ONLY the inline @mention, so `body.model` (the picker + the
+ * `--model` flag) was SILENTLY DROPPED — the picker UX was a no-op server-side. This restores it.
+ */
 export function resolveTaskModel(bodyModel, objective, catalog) {
     const mention = parseModelMention(objective, Object.keys(catalog));
     const explicit = typeof bodyModel === "string" ? matchCatalogModel(bodyModel, catalog) : undefined;
+    // 未匹配的「在场」ref 一律透出(codex L1:历史 checkpoint 里的空串/非字符串 model 在 RESUME 重放也不许
+    // 静默降级——非字符串给类型表示,不 stringify 值本体防日志泄内容)。
     const present = bodyModel !== undefined && bodyModel !== null;
     const unknown = present && explicit === undefined;
     const repr = typeof bodyModel !== "string" ? `<non-string:${typeof bodyModel}>` : bodyModel === "" ? "<empty-string>" : bodyModel;
@@ -11,6 +38,13 @@ export function resolveTaskModel(bodyModel, objective, catalog) {
         ...(unknown ? { unknownExplicit: repr } : {}),
     };
 }
+/**
+ * [865]② name+id 双键目录索引:返回 ref 命中的目录 **name 键**(spec.model 的规范形),未知 → undefined。
+ *  - name 命中用 Object.hasOwn(🔴 不用真值索引:Object.prototype 继承键 "constructor"/"__proto__" 等在裸
+ *    索引下是真值,会绕过 allow-list——沿袭原实现的纪律)。
+ *  - id 命中扫目录值(`Model.id`),跳过 "default" 别名键(它与其指向的真身共享 id,解析到别名会让 /model
+ *    面板与实际路由再度撕裂);同 id 多 name 时取目录序第一个(与 /v1/models 列表序一致,确定性)。
+ */
 export function matchCatalogModel(ref, catalog) {
     if (Object.hasOwn(catalog, ref))
         return ref;
@@ -22,9 +56,16 @@ export function matchCatalogModel(ref, catalog) {
     }
     return undefined;
 }
+/**
+ * vision precheck: a catalog model can read images iff its `input` modality list
+ * includes `"image"` (the SAME test as the vision capability on GET /v1/models — `server.ts`). FALSE-SAFE on
+ * missing/unknown modality info: returns `true` (do NOT block) — only an EXPLICIT text-only `input` triggers the
+ * precheck, so a model that never declared its modalities is never wrongly 422'd. Lets a request with images 422
+ * up-front instead of hitting the downstream gateway as an opaque deserialize 400 on a text-only model.
+ */
 export function modelSupportsImages(model) {
     if (!model || !Array.isArray(model.input))
-        return true;
+        return true; // no modality info → fail-open (don't block)
     return model.input.includes("image");
 }
 //# sourceMappingURL=model-select.js.map

package/dist/observability/cost-quota.d.ts

@@ -1,9 +1,25 @@
+/**
+ * Per-principal CUMULATIVE cost quota (design/21/27 follow-up). The per-task `maxCostUsd` gate caps a
+ * SINGLE task; this caps a principal's spend ACROSS tasks within a rolling fixed window. Spend is the
+ * authoritative integer `costMicroUsd` accumulated by the tracer (so it includes council/team
+ * sub-tasks, via the principal ALS context). A new task is REFUSED once the window's accumulated cost
+ * has crossed the ceiling — the in-flight task that crossed it still finishes (the per-task gate is the
+ * single-task guard); the quota blocks the NEXT one until the window rolls over.
+ *
+ * In-memory, per-replica — same trade as the request rate limiter. A multi-replica deployment under-
+ * counts across replicas (each tracks its own slice); a shared (TiDB) quota is the hardening step,
+ * mirroring TiDBBreakerState. Documented, not silently wrong.
+ */
 export interface QuotaDecision {
     allowed: boolean;
     usedMicroUsd: number;
     limitMicroUsd: number;
+    /** Seconds until the current window rolls over (only meaningful when !allowed). */
     retryAfterSec: number;
 }
+/** The hot-path surface shared by the in-memory {@link CostQuota} (single replica) and the cross-replica
+ *  {@link import("../plugins/tidb-cost-quota.js").TiDBCostQuota}. `key` is opaque (principal today;
+ *  principal/team/feature later — design/30 N3), so both stores are key-based. */
 export interface QuotaTracker {
     check(key: string): QuotaDecision;
     add(key: string, micro: number): void;
@@ -13,9 +29,13 @@ export declare class CostQuota implements QuotaTracker {
     private readonly windowMs;
     private readonly now;
     private windows;
+    /** @param limitMicroUsd ceiling per window (integer micro-USD). @param windowMs rolling window. */
     constructor(limitMicroUsd: number, windowMs: number, now?: () => number);
+    /** Is this principal under quota right now? (Reads only — does not consume.) */
     check(key: string): QuotaDecision;
+    /** Add spend for a principal, starting a fresh window if the prior one expired. */
     add(key: string, micro: number): void;
+    /** Drop expired windows (called from the background reaper) to bound memory. */
     reap(): number;
 }
 //# sourceMappingURL=cost-quota.d.ts.map

package/dist/observability/cost-quota.js

@@ -3,11 +3,13 @@ export class CostQuota {
     windowMs;
     now;
     windows = new Map();
+    /** @param limitMicroUsd ceiling per window (integer micro-USD). @param windowMs rolling window. */
     constructor(limitMicroUsd, windowMs, now = () => Date.now()) {
         this.limitMicroUsd = limitMicroUsd;
         this.windowMs = windowMs;
         this.now = now;
     }
+    /** Is this principal under quota right now? (Reads only — does not consume.) */
     check(key) {
         const t = this.now();
         const w = this.windows.get(key);
@@ -17,6 +19,7 @@ export class CostQuota {
         const retryAfterSec = !allowed && live ? Math.ceil((w.start + this.windowMs - t) / 1000) : 0;
         return { allowed, usedMicroUsd: used, limitMicroUsd: this.limitMicroUsd, retryAfterSec };
     }
+    /** Add spend for a principal, starting a fresh window if the prior one expired. */
     add(key, micro) {
         if (micro <= 0)
             return;
@@ -27,6 +30,7 @@ export class CostQuota {
         else
             w.micro += micro;
     }
+    /** Drop expired windows (called from the background reaper) to bound memory. */
     reap() {
         const t = this.now();
         let dropped = 0;

package/dist/observability/cost-taxonomy.d.ts

@@ -1,33 +1,78 @@
+/**
+ * design/80 b (item 3) — the INFRA cost axes the SERVICE owns, composed with core's LLM-family `costBreakdown`
+ * for the supervisor cost surface.
+ *
+ * (design/158 N24: moved here from the single-file `src/finance/` directory — lens4 §4.4 flagged the "cost"
+ * concept as split across `finance/cost-taxonomy.ts` + `observability/cost-quota.ts` + `budget.ts`. Chose
+ * "dissolve finance/, fold into observability/" over "collect all three into finance/": this module + the
+ * quota tracker are both cost REPORT/GUARD layers that feed metrics/decisions (observability's existing
+ * job), and budget.ts stays put — it has ~19 import sites and was already the N18 move target this same
+ * batch; stacking a second wide-fanout move on it in one session was the higher-risk option for no added
+ * clarity.)
+ *
+ * The engine prices ONLY LLM tokens (core's `Stats.costBreakdown` = llmRoot / nestedSubagent / memoryConsolidation
+ * / compaction). It has NO $ for tool calls, sandbox wall-clock, or network egress — those are INFRA/service costs
+ * the service owns the data + rates for. This module is the thin report layer: it turns a
+ * per-run infra USAGE + the deployment's RATES into an infra breakdown, then composes it with the core LLM
+ * breakdown into one supervisor-facing total. Pure + rate-driven (rates default 0 ⇒ infra reads $0, exactly like
+ * MODEL_COST_* — opt-in pricing). The per-run usage extraction (sandbox wall-clock from the run's remote-env
+ * spans, tool-call count from the trace) is the data-source wiring fed in by the caller; this layer is the math.
+ */
+/** Deployment infra pricing (config; default 0 = not priced, mirrors MODEL_COST_*). */
 export interface InfraCostRates {
+    /** $ (micro-USD) per tool invocation. */
     toolCallMicroUsd: number;
+    /** $ (micro-USD) per sandbox wall-clock SECOND (the run's remote-env connected lifetime). */
     sandboxSecMicroUsd: number;
+    /** $ (micro-USD) per GB of network egress. */
     egressGbMicroUsd: number;
 }
+/** Per-run infra USAGE (fed by the caller from the run's trace / remote-env spans). */
 export interface InfraUsage {
     toolCalls: number;
     sandboxWalltimeMs: number;
     egressBytes: number;
 }
+/** The service's infra cost axes (micro-USD), the complement to core's LLM-family breakdown. */
 export interface InfraCostBreakdown {
     toolCallMicroUsd: number;
     sandboxWalltimeMicroUsd: number;
     egressMicroUsd: number;
     totalMicroUsd: number;
 }
+/** Core's LLM-family breakdown (mirror of core `Stats.costBreakdown`), accepted read-only for composition. */
 export interface LlmCostBreakdown {
     llmRootMicroUsd: number;
     nestedSubagentMicroUsd: number;
     memoryConsolidationMicroUsd: number;
     compactionMicroUsd: number;
 }
+/** The combined supervisor cost surface: core's LLM axes + the service's infra axes + a reconciled grand total. */
 export interface SupervisorCostBreakdown {
     llm: LlmCostBreakdown | null;
     infra: InfraCostBreakdown;
+    /** llm.total (the engine's priced LLM $) + infra.total. `llmTotalMicroUsd` is supplied explicitly (core's
+     *  authoritative `stats.costMicroUsd`) rather than re-summed from the breakdown, so a category drift in the
+     *  breakdown can never silently inflate/deflate the grand total. */
     totalMicroUsd: number;
 }
+/** Price a run's infra usage. Every term clamps negatives to 0 (a bad usage/rate never produces a negative cost). */
 export declare function infraCost(usage: InfraUsage, rates: InfraCostRates): InfraCostBreakdown;
+/**
+ * Compose the supervisor cost surface from core's LLM breakdown + total and the service's infra breakdown.
+ * `llmTotalMicroUsd` is core's authoritative priced-LLM total (`stats.costMicroUsd`) — the grand total is that +
+ * infra, NOT a re-sum of the LLM sub-categories (so a breakdown category bug can't move the grand total).
+ */
 export declare function composeSupervisorCost(llm: LlmCostBreakdown | null, llmTotalMicroUsd: number, infra: InfraCostBreakdown): SupervisorCostBreakdown;
+/** True iff ANY infra axis is priced — the gate for surfacing the composed supervisor cost (when all rates are 0
+ *  the infra contribution is always $0, so the client just reads core's `stats.costBreakdown` directly). */
 export declare function hasInfraPricing(r: InfraCostRates): boolean;
+/**
+ * Extract a run's infra USAGE from its event log + wall-clock span. `toolCalls` = the `tool_start` events (one per
+ * tool invocation). `sandboxWalltimeMs` ≈ the run's wall-clock duration (the remote-env is connected for ~the
+ * run's active life; the precise per-span sum lives in logs, not the event trace — the run duration is the
+ * faithful per-run proxy). `egressBytes` = 0 (not yet metered per run).
+ */
 export declare function infraUsageFromEvents(events: ReadonlyArray<{
     type?: string;
 }>, runDurationMs: number): InfraUsage;

package/dist/observability/cost-taxonomy.js

@@ -1,4 +1,25 @@
+/**
+ * design/80 b (item 3) — the INFRA cost axes the SERVICE owns, composed with core's LLM-family `costBreakdown`
+ * for the supervisor cost surface.
+ *
+ * (design/158 N24: moved here from the single-file `src/finance/` directory — lens4 §4.4 flagged the "cost"
+ * concept as split across `finance/cost-taxonomy.ts` + `observability/cost-quota.ts` + `budget.ts`. Chose
+ * "dissolve finance/, fold into observability/" over "collect all three into finance/": this module + the
+ * quota tracker are both cost REPORT/GUARD layers that feed metrics/decisions (observability's existing
+ * job), and budget.ts stays put — it has ~19 import sites and was already the N18 move target this same
+ * batch; stacking a second wide-fanout move on it in one session was the higher-risk option for no added
+ * clarity.)
+ *
+ * The engine prices ONLY LLM tokens (core's `Stats.costBreakdown` = llmRoot / nestedSubagent / memoryConsolidation
+ * / compaction). It has NO $ for tool calls, sandbox wall-clock, or network egress — those are INFRA/service costs
+ * the service owns the data + rates for. This module is the thin report layer: it turns a
+ * per-run infra USAGE + the deployment's RATES into an infra breakdown, then composes it with the core LLM
+ * breakdown into one supervisor-facing total. Pure + rate-driven (rates default 0 ⇒ infra reads $0, exactly like
+ * MODEL_COST_* — opt-in pricing). The per-run usage extraction (sandbox wall-clock from the run's remote-env
+ * spans, tool-call count from the trace) is the data-source wiring fed in by the caller; this layer is the math.
+ */
 const nonNeg = (n) => (Number.isFinite(n) && n > 0 ? n : 0);
+/** Price a run's infra usage. Every term clamps negatives to 0 (a bad usage/rate never produces a negative cost). */
 export function infraCost(usage, rates) {
     const toolCallMicroUsd = nonNeg(usage.toolCalls) * nonNeg(rates.toolCallMicroUsd);
     const sandboxWalltimeMicroUsd = (nonNeg(usage.sandboxWalltimeMs) / 1000) * nonNeg(rates.sandboxSecMicroUsd);
@@ -10,12 +31,25 @@ export function infraCost(usage, rates) {
         totalMicroUsd: toolCallMicroUsd + sandboxWalltimeMicroUsd + egressMicroUsd,
     };
 }
+/**
+ * Compose the supervisor cost surface from core's LLM breakdown + total and the service's infra breakdown.
+ * `llmTotalMicroUsd` is core's authoritative priced-LLM total (`stats.costMicroUsd`) — the grand total is that +
+ * infra, NOT a re-sum of the LLM sub-categories (so a breakdown category bug can't move the grand total).
+ */
 export function composeSupervisorCost(llm, llmTotalMicroUsd, infra) {
     return { llm, infra, totalMicroUsd: nonNeg(llmTotalMicroUsd) + infra.totalMicroUsd };
 }
+/** True iff ANY infra axis is priced — the gate for surfacing the composed supervisor cost (when all rates are 0
+ *  the infra contribution is always $0, so the client just reads core's `stats.costBreakdown` directly). */
 export function hasInfraPricing(r) {
     return r.toolCallMicroUsd > 0 || r.sandboxSecMicroUsd > 0 || r.egressGbMicroUsd > 0;
 }
+/**
+ * Extract a run's infra USAGE from its event log + wall-clock span. `toolCalls` = the `tool_start` events (one per
+ * tool invocation). `sandboxWalltimeMs` ≈ the run's wall-clock duration (the remote-env is connected for ~the
+ * run's active life; the precise per-span sum lives in logs, not the event trace — the run duration is the
+ * faithful per-run proxy). `egressBytes` = 0 (not yet metered per run).
+ */
 export function infraUsageFromEvents(events, runDurationMs) {
     return {
         toolCalls: events.reduce((n, e) => (e.type === "tool_start" ? n + 1 : n), 0),

package/dist/observability/logger.d.ts

@@ -1,3 +1,4 @@
+/** Minimal structured (JSON-line) logger. One line per event → stdout/stderr, scraper-friendly. */
 export type LogLevel = "debug" | "info" | "warn" | "error";
 export interface Logger {
     debug(msg: string, fields?: Record<string, unknown>): void;

package/dist/observability/logger.js

@@ -1,4 +1,9 @@
 const ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
+// EPIPE hardening (live catch): a host that feeds this engine's stdout through a
+// PIPE and exits first leaves the fd broken — the NEXT log write raises EPIPE. Without a listener
+// that async 'error' event on process.stdout is fatal, which killed drainThenShutdown ON ITS FIRST
+// LOG LINE (the SIGHUP reap never ran). Logs are droppable; the process is not — swallow both the
+// sync throw (try/catch below) and the async 'error' event (no-op listener, attached once).
 let stdioErrorsSwallowed = false;
 function swallowStdioErrors() {
     if (stdioErrorsSwallowed)
@@ -23,6 +28,7 @@ export function createLogger(minLevel = "info") {
             (level === "error" || level === "warn" ? process.stderr : process.stdout).write(line + "\n");
         }
         catch {
+            // Broken/destroyed stream (EPIPE family): drop the line, never the process.
         }
     };
     return {

package/dist/observability/metrics.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Tiny in-process metrics registry with Prometheus text exposition — no dependency.
+ *
+ * Per-instance (each container exposes its own counters); aggregate across instances at the scraper.
+ * Supports labeled counters, gauges (static + dynamic), and duration histograms.
+ */
 export type Labels = Record<string, string>;
 export declare class Metrics {
     private counters;
@@ -12,8 +18,14 @@ export declare class Metrics {
     setGauge(name: string, value: number, labels?: Labels): void;
     addGauge(name: string, delta: number, labels?: Labels): void;
     observe(name: string, value: number, labels?: Labels): void;
+    /** Prometheus text exposition (content-type text/plain; version=0.0.4). */
     render(): string;
+    /** Structured snapshot of the whole registry — the OTLP exporter maps this to OTel data points
+     *  (counters→Sum monotonic, gauges/dynamic→Gauge, histograms→Histogram). Read-only copy. */
     snapshot(): MetricSnapshot;
+    /** Curated health summary (friendly JSON) for a lightweight fleet dashboard — the sema-registry's
+     *  fleet page fetches this per worker and renders cards + computes rates over polls (no Prometheus
+     *  needed). Counters are cumulative totals; histograms are reported as averages (sum/count). */
     summarize(): MetricsSummary;
 }
 export interface MetricsSummary {
@@ -72,5 +84,6 @@ export interface MetricSnapshot {
         }>;
     }>;
 }
+/** Register the service's standard metric set. */
 export declare function createMetrics(): Metrics;
 //# sourceMappingURL=metrics.d.ts.map

package/dist/observability/metrics.js

@@ -1,5 +1,9 @@
 const DEFAULT_BUCKETS = [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60];
 function labelKey(labels) {
+    // Escape the delimiters (`\` `,` `=`) IN THE VALUE so distinct label sets can't collide onto one series:
+    // without this, {a:"1,b=2"} and {a:"1",b:"2"} both key to "a=1,b=2" and silently merge (tool names come from
+    // MCP, model ids from config — not strongly constrained). This key is internal series identity only;
+    // Prometheus rendering escapes separately via renderLabels/esc.
     return Object.keys(labels)
         .sort()
         .map((k) => `${k}=${String(labels[k]).replace(/\\/g, "\\\\").replace(/,/g, "\\,").replace(/=/g, "\\=")}`)
@@ -35,6 +39,11 @@ export class Metrics {
         if (!this.histos.has(name))
             this.histos.set(name, { help, buckets, series: new Map() });
     }
+    // 根因升类:inc 对未注册名曾是静默 no-op — 15 个只 inc 未 counter() 的计数器
+    // (permission_denied_total / compaction_events_total / hook_llm_calls_total / fleet_lease_* /
+    // metric_label_overflow_total[溢出护栏自己的计数器!]等)整批从未出现在 /metrics。观测面的
+    // fail-silent 正是观测要消灭的东西 → inc/setGauge/addGauge 改为首用自动注册(help 标注
+    // auto-registered,提醒补显式注册拿正经 HELP 文案);已知 15 名已在 createMetrics 补显式注册。
     inc(name, labels = {}, n = 1) {
         let c = this.counters.get(name);
         if (!c) {
@@ -78,6 +87,7 @@ export class Metrics {
         s.count += 1;
         h.series.set(k, s);
     }
+    /** Prometheus text exposition (content-type text/plain; version=0.0.4). */
     render() {
         const out = [];
         for (const [name, c] of this.counters) {
@@ -106,6 +116,8 @@ export class Metrics {
         }
         return out.join("\n") + "\n";
     }
+    /** Structured snapshot of the whole registry — the OTLP exporter maps this to OTel data points
+     *  (counters→Sum monotonic, gauges/dynamic→Gauge, histograms→Histogram). Read-only copy. */
     snapshot() {
         const counters = [...this.counters].map(([name, c]) => ({
             name,
@@ -127,6 +139,9 @@ export class Metrics {
         }));
         return { counters, gauges, histograms };
     }
+    /** Curated health summary (friendly JSON) for a lightweight fleet dashboard — the sema-registry's
+     *  fleet page fetches this per worker and renders cards + computes rates over polls (no Prometheus
+     *  needed). Counters are cumulative totals; histograms are reported as averages (sum/count). */
     summarize() {
         const ctotal = (name) => [...(this.counters.get(name)?.series.values() ?? [])].reduce((a, s) => a + s.value, 0);
         const cby = (name, label) => {
@@ -180,6 +195,7 @@ function safe(fn) {
         return 0;
     }
 }
+/** Register the service's standard metric set. */
 export function createMetrics() {
     const m = new Metrics();
     m.counter("http_requests_total", "HTTP requests by route/method/status");
@@ -191,10 +207,15 @@ export function createMetrics() {
     m.gauge("runs_active", "Async runs currently executing");
     m.counter("council_runs_total", "Code-review council runs (L1+L3)");
     m.histogram("council_tokens", "Total model tokens per council review (lenses + arbiter)");
+    // Prefix-cache effectiveness (core 1.22): per-task hit rate (cost-critical) + a count of tasks the
+    // Runner flagged as low-hit (unstable/poisoned prefix) so it can be alerted on.
     m.histogram("task_cache_hit_rate", "Prefix-cache hit rate per task (cachedTokens/promptTokens, 0..1)", [
         0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95, 1,
     ]);
     m.counter("prompt_cache_low_hit_total", "Tasks the Runner flagged with a low prefix-cache hit rate");
+    // Cost & trace observability (core 1.37). Spend = the integer micro-USD `costMicroUsd` summed over
+    // ALL brain calls (top-level + async + council sub-tasks) via the tracer — the authoritative billing
+    // counter. firstTokenMs is the gateway-hang early signal; tool calls + budget cutoffs round it out.
     m.counter("model_cost_micro_usd_total", "Authoritative model spend (integer micro-USD) over all brain calls, by model");
     m.histogram("brain_first_token_ms", "Time to first content token per brain call (gateway-hang signal)", [
         50, 100, 250, 500, 1000, 2000, 5000, 10000, 30000,
@@ -210,38 +231,79 @@ export function createMetrics() {
     m.counter("rewind_snapshot_failed_total", "Per-turn rewind file snapshots that failed, by code (too_large = big working tree, expected/benign; other codes warrant eyes)");
     m.counter("verifications_total", "Tasks run through the verification gate (1.44), by final verdict");
     m.counter("cascade_total", "Tasks run through the model cascade (1.45), by outcome (passed/exhausted)");
+    // Degenerate-repetition salvage classifier (core 1.59): on errorCode=output.degenerate, where was the
+    // useful answer? a=in the degenerate turn itself, b=in an earlier turn, unknown=nowhere. Frequencies
+    // feed back to core's decision on whether the "last-substantive-turn" salvage (②) is worth building.
     m.counter("degenerate_total", "Degenerate-output failures (1.59), by salvage class (a/b/unknown)");
+    // Plan-cache recurrence probe (INSTRUMENT-FIRST, core design/42): does a tenant re-pose near-duplicate
+    // task objectives? Fleet-level totals; per-scope detail is at GET /metrics/plan-cache (not a label, to
+    // avoid high tenant cardinality). Decides whether core builds the plan-caching producer hook.
     m.counter("plan_cache_recurrence_total", "Finished tasks whose objective recurs vs scope history, by hit (true/false)");
     m.histogram("plan_cache_qsig", "Significant-token count of task objectives (qSig length)", [1, 2, 3, 5, 10, 20]);
+    // Memory consolidation (1.62 B-full): the reconcile-LLM store writes, by op. A spike in update/delete is
+    // the prod signal for over-merging / a mis-calibrated band. Recorded by the store on each call, so it does
+    // NOT need the fire-and-forget consolidation() to be awaited.
     m.counter("memory_consolidation_ops_total", "Memory consolidation store ops (1.62 B-full), by op (update/delete)");
     m.counter("mcp_server_unavailable_total", "MCP servers skipped fail-open at task start (1.68), unreachable/misconfigured");
+    // Remote execution env (design/48 E2B adapter): lifecycle outcomes by provider/result.
     m.counter("remote_env_connect_total", "E2B remote-env connect outcomes (provider/result)");
     m.counter("remote_env_destroy_total", "E2B remote-env destroy outcomes (provider/result)");
     m.counter("remote_env_suspend_total", "E2B remote-env suspendVM outcomes (v1.5, provider/result)");
     m.counter("remote_env_resume_total", "E2B remote-env resumeVM outcomes (v1.5, provider/result)");
     m.counter("remote_env_exec_stream_read_timeout_total", "E2B execStream idle read-timeouts (#1128, provider)");
+    // E18 resume-at: a per-turn anchor capture (getLeafId→put) failed (e.g. an un-migrated DB missing resume_anchor) —
+    // best-effort, never fails the run; this surfaces a SYSTEMATIC capture outage instead of a silent feature stoppage.
     m.counter("resume_anchor_capture_failed", "E18 resume-at per-turn anchor captures that failed (best-effort, run unaffected)");
+    // Silent-fallback telemetry P0 batch (docs/design/SILENT-FALLBACK-TELEMETRY.md, service half):
+    // S4 — brain-layer liveness phases (rate_limited/retrying/reconnecting/circuit_open) were previously visible
+    // only on the live SSE stream; count them so upstream throttling/outage is graphable per phase.
     m.counter("brain_retry_total", "Brain-layer status events (S4), by phase (rate_limited/retrying/reconnecting/circuit_open)");
+    // S5 — the auto store-backend probe degraded this replica to in-memory at boot (configured DB unreachable).
+    // 1 = degraded (this replica is NOT persisting); scrape-level alert target. /health carries the twin flag.
     m.gauge("store_backend_degraded", "1 when the auto DB probe failed at boot and this replica degraded to in-memory (S5)");
+    // S6 — images submitted to a model whose declared input has no "image": core degrades them to text
+    // placeholders (1.233.1). Counted at submit so the silent modality drop is visible per model.
     m.counter("images_omitted_total", "Tasks whose images will be degraded to text placeholders (no-vision model), by model (S6)");
+    // S7 — background reapers: how many rows each sweep actually flipped (previously discarded), by kind.
+    // A spike = an instance died and its orphans were batch-failed (distinguishable from organic failures).
     m.counter("runs_reaped_total", "Run rows flipped by the background reapers (S7), by kind (stale/suspended/expired_checkpoint)");
     m.counter("checkpoints_reaped_total", "Durable checkpoints expired by the backstop reaper (S7)");
     m.counter("bakes_reaped_total", "Image bakes failed by the stale-lease reaper (S7)");
+    // S9 — cross-replica write-behind counters (rate limit / cost quota): flush/refresh failures previously
+    // vanished in a bare catch → the fleet silently degrades to per-replica counting. Streak gauge = current
+    // consecutive failures (0 = healthy); the total counts every failed attempt.
     m.counter("counter_flush_failed_total", "Write-behind counter flush/refresh failures (S9), by table and kind");
     m.gauge("counter_flush_fail_streak", "Current consecutive write-behind flush/refresh failures (S9), by table and kind");
+    // S14 — near-budget degrade was configured but DROPPED for this task (e.g. image task + text-only degrade
+    // target): the task keeps its main model and will hard-fail on cost instead. Previously undetectable.
     m.counter("degrade_dropped_total", "Tasks whose near-budget degrade was dropped at submit (S14), by reason");
+    // Silent-fallback P1 batch (second sweep, same doc §P1):
+    // S18 — every brain call by provider+model; provider="unknown" = the routing layer fell through to the
+    // gateway default without a recognized provider (previously invisible).
     m.counter("brain_calls_total", "Brain calls by provider/model (S18); provider=unknown = unrecognized routing fallthrough");
+    // S10 — DB wall-clock minus local wall-clock (ms, can be negative). The write-behind counters bucket on
+    // LOCAL floor(now/windowMs); replica clock skew splits a fleet window into disjoint buckets (soft-limit leak).
     m.gauge("fleet_counter_bucket_skew_ms", "DB clock minus local clock in ms (S10) — skew splits cross-replica counter windows");
     m.gauge("fleet_clock_probe_ok", "1 = last DB clock probe succeeded, 0 = failing (skew gauge is stale while 0)");
+    // S21 — which backend snapshot blobs actually land on (minio|sql). Partial MINIO_* config silently falls to sql.
     m.gauge("snapshot_blob_backend", "1 on the active snapshot-blob backend series (S21), by backend (minio|sql)");
+    // S22 — memory embed/KNN runtime failures (boot said vector; runtime silently degrades to lexical).
     m.counter("memory_embed_failed_total", "Memory embedding calls that failed at runtime (S22), by where (add/recall/consolidation)");
     m.counter("memory_knn_query_failed_total", "Memory KNN searchScored queries that failed at runtime (S22)");
+    // LOW — dedup fold vs new insert (a fold UPDATEs the existing row; previously indistinguishable), and the
+    // dedup probe failing over to a plain INSERT.
     m.counter("memory_dedup_folded_total", "Memory writes folded into an existing near-duplicate row (LOW)");
     m.counter("memory_dedup_probe_failed_total", "Memory dedup KNN probes that failed and fell through to INSERT (LOW)");
+    // S24 — redaction rewrites by pattern (over/under-redaction previously had zero fingerprint).
     m.counter("redactions_applied_total", "redactSecrets rewrites (S24), by pattern label");
+    // S25 — warm session-cache entries evicted by a cross-instance write (import/replace) while still cached.
     m.counter("stale_cache_conflict_total", "Warm session-cache entries evicted by a cross-instance write while cached (S25)");
+    // LOW — cross-replica breaker write-through failures (advisory swallow previously silent).
     m.counter("breaker_writethrough_failed_total", "Circuit-breaker cross-replica write-through failures (LOW), by backend");
+    // LOW — web-search provider returned a non-array payload (model silently gets zero results).
     m.counter("web_search_bad_payload_total", "Web-search provider responses whose results field was not an array (LOW), by provider");
+    // 收账批(2026-07-08):这 15 个计数器一直只有 inc 没注册 — 在 auto-register 落地前
+    // 整批从未上过 /metrics(inc 曾对未注册名静默 no-op)。补显式注册拿正经 HELP 文案。
     m.counter("permission_denied_total", "Tool-gate denials by source (policy/hook/plan-mode; goal B4 always-on deny meter)");
     m.counter("compaction_events_total", "Compaction lifecycle events by outcome (started/completed/failed/skipped) and trigger");
     m.counter("hook_llm_calls_total", "prompt/agent hook entries that completed a model call (hooks 3b), by type");
@@ -257,6 +319,7 @@ export function createMetrics() {
     m.counter("remote_env_rpc_timeout_total", "Remote-env RPC timeouts, by provider");
     m.counter("task_outcomes_total", "Task outcome-ledger rows recorded, by status and oracle green flag");
     m.counter("workflow_runs_total", "Self-orchestration workflow runs, by status");
+    // 鉴权桥 verify 延迟:热路径(kid 命中)亚毫秒;冷路径(JWKS 拉取)带网络 RTT——首请求/轮换尾延迟可见。
     m.histogram("auth_bridge_verify_seconds", "Registry SSO JWT verify latency (hot path sub-ms; cold path includes a JWKS fetch)", [0.001, 0.005, 0.02, 0.1, 0.5, 2, 10]);
     return m;
 }

package/dist/observability/otel-exporter.d.ts

@@ -1,4 +1,12 @@
+/**
+ * OTLP/HTTP metrics exporter (core 1.37 observability seam) — DEPENDENCY-FREE. core stays SDK-free and
+ * the deployment owns export; rather than pull in the OpenTelemetry SDK (a concern for the intranet
+ * mirror + the bun-compiled binary), we periodically snapshot the in-process registry and POST it to an
+ * OTLP collector as OTLP/JSON `ExportMetricsServiceRequest`. Enabled only when `OTEL_EXPORTER_OTLP_ENDPOINT`
+ * is set; otherwise zero overhead. Prometheus /metrics is unaffected — both can run side by side.
+ */
 import type { MetricSnapshot } from "./metrics.js";
+/** Build the OTLP/JSON metrics payload from a registry snapshot. Pure → unit-testable. */
 export declare function buildOtlpPayload(snap: MetricSnapshot, opts: {
     serviceName: string;
     startMs: number;
@@ -29,6 +37,7 @@ export interface OtlpExporterOptions {
     fetchImpl?: typeof fetch;
     onError?: (err: unknown) => void;
 }
+/** Start the periodic push loop (unref'd so it never holds the process open). Returns a stop handle. */
 export declare function startOtlpExporter(metrics: {
     snapshot(): MetricSnapshot;
 }, opts: OtlpExporterOptions): {

package/dist/observability/otel-exporter.js

@@ -1,6 +1,8 @@
-const CUMULATIVE = 2;
+const CUMULATIVE = 2; // OTel AggregationTemporality.CUMULATIVE
+/** uint64 nanos as a string (OTLP/JSON encodes 64-bit ints as strings; ms×1e6 overflows Number). */
 const nano = (ms) => (BigInt(ms) * 1000000n).toString();
 const attrs = (labels) => Object.entries(labels).map(([key, v]) => ({ key, value: { stringValue: String(v) } }));
+/** Build the OTLP/JSON metrics payload from a registry snapshot. Pure → unit-testable. */
 export function buildOtlpPayload(snap, opts) {
     const start = nano(opts.startMs);
     const now = nano(opts.nowMs);
@@ -35,13 +37,15 @@ export function buildOtlpPayload(snap, opts) {
             description: h.help,
             histogram: {
                 dataPoints: h.series.map((s) => {
+                    // our buckets are CUMULATIVE (Prometheus-style: counts[i] = #obs ≤ bounds[i]); OTLP wants
+                    // PER-bucket counts with a trailing +Inf overflow bucket (length = bounds.length + 1).
                     const bucketCounts = [];
                     let prev = 0;
                     for (let i = 0; i < h.buckets.length; i++) {
                         bucketCounts.push(String(s.counts[i] - prev));
                         prev = s.counts[i];
                     }
-                    bucketCounts.push(String(s.count - prev));
+                    bucketCounts.push(String(s.count - prev)); // +Inf
                     return { attributes: attrs(s.labels), startTimeUnixNano: start, timeUnixNano: now, count: String(s.count), sum: s.sum, bucketCounts, explicitBounds: h.buckets };
                 }),
                 aggregationTemporality: CUMULATIVE,
@@ -57,10 +61,14 @@ export function buildOtlpPayload(snap, opts) {
         ],
     };
 }
+/** Start the periodic push loop (unref'd so it never holds the process open). Returns a stop handle. */
 export function startOtlpExporter(metrics, opts) {
     const startMs = Date.now();
     const url = `${opts.endpoint}/v1/metrics`;
     const fetchImpl = opts.fetchImpl ?? fetch;
+    // A collector that accepts the connection but never responds would otherwise let one fetch per tick pile
+    // up (each holding a full snapshot payload + socket) — bound each request and skip a tick while one is
+    // still in flight, so a half-dead collector can never accumulate back-pressure inside the process.
     let inFlight = false;
     const exportOnce = async () => {
         if (inFlight)
@@ -78,7 +86,7 @@ export function startOtlpExporter(metrics, opts) {
                 opts.onError?.(new Error(`OTLP export HTTP ${res.status}`));
         }
         catch (err) {
-            opts.onError?.(err);
+            opts.onError?.(err); // export is best-effort — a collector hiccup must never affect serving
         }
         finally {
             inFlight = false;

package/dist/observability/principal-context.d.ts

@@ -1,5 +1,14 @@
+/**
+ * Per-principal execution context (AsyncLocalStorage). The brain-call tracer fires for EVERY model
+ * call — including council/team sub-tasks that run on the shared `subRunner` (a per-task tracer can't
+ * reach those). To attribute spend to the right principal we wrap a task's execution in this ALS:
+ * `node:async_hooks` propagates the store through every `await`, so a sub-task spawned inside a tool
+ * call still reads the originating principal. Absent store = unattributed (dev / no principal).
+ */
 import { AsyncLocalStorage } from "node:async_hooks";
 export declare const principalContext: AsyncLocalStorage<string>;
+/** Run `fn` with `principal` as the ambient context (no-op wrapper when principal is undefined). */
 export declare function withPrincipal<T>(principal: string | undefined, fn: () => T): T;
+/** The principal attributed to the current async execution, if any. */
 export declare function currentPrincipal(): string | undefined;
 //# sourceMappingURL=principal-context.d.ts.map

package/dist/observability/principal-context.js

@@ -1,8 +1,17 @@
+/**
+ * Per-principal execution context (AsyncLocalStorage). The brain-call tracer fires for EVERY model
+ * call — including council/team sub-tasks that run on the shared `subRunner` (a per-task tracer can't
+ * reach those). To attribute spend to the right principal we wrap a task's execution in this ALS:
+ * `node:async_hooks` propagates the store through every `await`, so a sub-task spawned inside a tool
+ * call still reads the originating principal. Absent store = unattributed (dev / no principal).
+ */
 import { AsyncLocalStorage } from "node:async_hooks";
 export const principalContext = new AsyncLocalStorage();
+/** Run `fn` with `principal` as the ambient context (no-op wrapper when principal is undefined). */
 export function withPrincipal(principal, fn) {
     return principal ? principalContext.run(principal, fn) : fn();
 }
+/** The principal attributed to the current async execution, if any. */
 export function currentPrincipal() {
     return principalContext.getStore();
 }