@sema-agent/server 7.43.0 → 7.44.0

package/dist/observability/metrics.js

@@ -1,9 +1,5 @@
 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, "\\=")}`)
@@ -39,11 +35,6 @@ 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) {
@@ -87,11 +78,6 @@ export class Metrics {
         s.count += 1;
         h.series.set(k, s);
     }
-    /** [2557] 2-j:dynamic gauge 求值抛错不再折成 0 —— 0 是该 gauge 的合法读数,折 0 让故障态与真实 0
-     *  在 wire 上逐字节不可区分(与上方 inc 静默 no-op 同族:观测面的 fail-silent 正是观测要消灭的东西)。
-     *  披露方向:错帧**不发样本行**(缺席=读数未知,面板显示 no data 而非假 0)+ 计
-     *  `metric_gauge_eval_errors_total{name}`(响亮、可告警)。每次求值(每次刮取/snapshot)错一次计一次;
-     *  仍然绝不 propagate(/metrics 不因单个读数器坏而 500)。 */
     evalDynamic(name, fn) {
         try {
             return fn();
@@ -101,9 +87,7 @@ export class Metrics {
             return undefined;
         }
     }
-    /** Prometheus text exposition (content-type text/plain; version=0.0.4). */
     render() {
-        // dynamic 先求值(2-j):错帧的 inc 要落进**本次**刮取的 counters 段,不能等下一次。
         const dyn = [];
         for (const [name, d] of this.dynamic) {
             const v = this.evalDynamic(name, d.fn);
@@ -136,10 +120,7 @@ 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() {
-        // dynamic 先求值(2-j,同 render):错帧的 inc 要进本次快照的 counters。
         const dynVals = [...this.dynamic].map(([name, d]) => ({ name, help: d.help, v: this.evalDynamic(name, d.fn) }));
         const counters = [...this.counters].map(([name, c]) => ({
             name,
@@ -151,7 +132,6 @@ export class Metrics {
             help: g.help,
             series: [...g.series.values()].map((s) => ({ labels: s.labels, value: s.value })),
         }));
-        // 错帧 series 空:名字/HELP 仍披露(指标存在),但绝不铸 {value:0} 假数据点。
         for (const { name, help, v } of dynVals)
             gauges.push({ name, help, series: v === undefined ? [] : [{ labels: {}, value: v }] });
         const histograms = [...this.histos].map(([name, h]) => ({
@@ -162,9 +142,6 @@ 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) => {
@@ -186,9 +163,6 @@ export class Metrics {
             tokensTotal: ctotal("task_tokens_total"),
             costUsd: ctotal("model_cost_micro_usd_total") / 1e6,
             costUsdByModel: Object.fromEntries(Object.entries(cby("model_cost_micro_usd_total", "model")).map(([k, v]) => [k, v / 1e6])),
-            // D5([2122] 挂账,additive v1):unpriced 部署下 costUsd 恒 0 而消费端读成「零花费」。
-            // costUnknown=true ⇒ costUsd/costUsdByModel 是**下界**(RB-368 缺席=未知语义;显式 0 = declared
-            // free 不计入 unpriced)。计数点在 budget.ts 的 brain.call 臂。
             costUnknown: ctotal("brain_calls_unpriced_total") > 0,
             unpricedCalls: ctotal("brain_calls_unpriced_total"),
             taskDurationAvgSec: havg("task_duration_seconds"),
@@ -215,7 +189,6 @@ export class Metrics {
         };
     }
 }
-/** Register the service's standard metric set. */
 export function createMetrics() {
     const m = new Metrics();
     m.counter("metric_gauge_eval_errors_total", "Dynamic gauge eval errors by gauge name (an erroring gauge emits NO sample that scrape — absence means unknown, not 0)");
@@ -228,20 +201,10 @@ 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. The observed value is
-    // `result.stats.cacheHitRate` — core-computed (core 3.0.0: cachedTokens/totalInputTokens, the normalized
-    // total-including-cache denominator; runs.ts / http/server.ts just forward it), not derived here — this
-    // description names the field, not a formula this file owns (E3: don't restate a formula whose owner
-    // can change it without telling us; core 3.0.0's denominator switched from `promptTokens` to
-    // `totalInputTokens`, which the old "(cachedTokens/promptTokens)" text would have silently mis-described).
     m.histogram("task_cache_hit_rate", "Prefix-cache hit rate per task (core-computed stats.cacheHitRate, 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,
@@ -253,106 +216,50 @@ export function createMetrics() {
     m.counter("budget_exceeded_total", "Tasks failed by a budget/limit ceiling, by errorCode");
     m.counter("cost_quota_rejected_total", "Tasks refused because the principal is over its cumulative cost quota");
     m.counter("degraded_total", "Tasks degraded to a cheaper model (1.40), by reason (budget/rate_limit/breaker_open)");
-    // #233 / A-002.8:名单外的模型选择在 **resume 腿**被放行(fresh 提交是 400)。读法:非零 = 还有存量
-    // 会话跑在 @-mention 名单之外 —— 那是刻意的(砖死 resume 比降级糟),但治理面必须看得见它有多少。
     m.counter("task_model_not_allowlisted_resume_total", "Resumed legs whose model/compactionModel is outside the @-mention allowlist (allowed to keep running by design — the allowlist gates fresh picks only)");
     m.counter("prompt_constitution_total", "Prompt assembly constitution mode per task (core 1.243 提示词主权): steady state = core; provider-assembled/replaced/legacy warrant eyes");
     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");
-    // DESIGN-269 车1:A2A peer 在任务起手不可用(卡取不到 / skill 铸不出)—— 与 mcp 同族的 fail-open 计数。
     m.counter("a2a_peer_unavailable_total", "A2A peers skipped at task start (DESIGN-269 client leg): card unreachable / spec unusable");
-    // DESIGN-269 车2:server-as-peer 的**对外**面。两只计数器刻意分开,它们回答两个不同的问题:
-    //  · `a2a_serve_rpc_total{method,outcome}` = 每个方法各被调了多少次、结果是什么(ok / refused /
-    //    error_<code> / method_not_found / internal_error)。`method_not_found` 那一格是**路线图信号**:
-    //    外部 peer 在真实拓扑里到底在要哪个还没做的方法(message/stream?tasks/cancel?),比我们猜准。
-    //  · `a2a_serve_rejected_total{reason}` = **没能进到方法层**的那些(凭据/形/版本以外的门),
-    //    它是「有人在扫我们 / 有人接错了」的第一手材料。混进上面那只会让「协议用错」与「跑失败了」
-    //    在同一条曲线上不可分。
     m.counter("a2a_serve_rpc_total", "A2A server-as-peer JSON-RPC calls by method and outcome (DESIGN-269 车2)");
     m.counter("a2a_serve_rejected_total", "A2A server-as-peer requests refused before reaching a method handler, by reason (DESIGN-269 车2)");
-    // 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 (sema-internal server/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)");
-    // #96 redesign⑤ (§DESIGN-V2 E): LSP sandbox-bridge lifecycle + session outcomes — previously zero metrics
-    // existed for the whole subsystem (a dead bridge or a stuck restart budget had no fleet-level signal).
     m.counter("lsp_bridge_start_total", "LSP sandbox bridge (re)starts attempted, by provider and generation");
     m.counter("lsp_bridge_dead_total", "LSP sandbox bridge generations that died, by reason (the word IS the model-facing unavailableReason)");
     m.counter("lsp_session_open_total", "LSP session opens, by language and outcome (ok/failed)");
     m.counter("lsp_session_heal_total", "LSP session heals (dead-transport reopen), by outcome (ok/failed)");
-    // 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).
-    // HELP 文案按**唯一活发射点**写(#228 接线后的复扫):stores.ts 的 onFailure 腿打 `{ backend: dialect }`,
-    // 从没有过 `where` 维度(那是退役的 MEMORY_BACKEND/EMBEDDING_* store 面的形)—— 运维照旧文案写
-    // `sum by (where)` 得到的是空序列。USAGE 的 `memory_embed_failed_total{backend}` 才是对的那一份。
     m.counter("memory_embed_failed_total", "Memory embedding calls that failed at runtime (S22), by backend (the memory-engine dialect that owns the embedder)");
     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 (core's PermissionDeniedSource, incl. org governance; 'other' = a word this build does not know; goal B4 always-on deny meter)");
     m.counter("permission_rule_events_total", "Persisted allow-rule seam events by event (persisted_rule_allowed = a rule authorized a call with nobody asked; rule_store_unreadable = the store failed to read so the call was adjudicated with ZERO rules)");
     m.counter("compaction_events_total", "Compaction lifecycle events by outcome (started/completed/failed/skipped) and trigger");
@@ -369,7 +276,6 @@ 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.js

@@ -1,9 +1,7 @@
 import { recordFailOpen } from "./fail-open.js";
-const CUMULATIVE = 2; // OTel AggregationTemporality.CUMULATIVE
-/** uint64 nanos as a string (OTLP/JSON encodes 64-bit ints as strings; ms×1e6 overflows Number). */
+const CUMULATIVE = 2;
 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);
@@ -38,15 +36,13 @@ 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)); // +Inf
+                    bucketCounts.push(String(s.count - prev));
                     return { attributes: attrs(s.labels), startTimeUnixNano: start, timeUnixNano: now, count: String(s.count), sum: s.sum, bucketCounts, explicitBounds: h.buckets };
                 }),
                 aggregationTemporality: CUMULATIVE,
@@ -62,14 +58,10 @@ 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)
@@ -83,8 +75,6 @@ export function startOtlpExporter(metrics, opts) {
                 body: JSON.stringify(payload),
                 signal: AbortSignal.timeout(Math.max(1_000, opts.intervalMs)),
             });
-            // #193 车5(P1-3):两条失败臂都要过 fail-open 计数——onError 只到日志轴,而 Prometheus-only
-            // 部署只看 metrics,此前 collector 持续宕机在 metrics 轴零信号(遥测腿自盲)。
             if (!res.ok) {
                 recordFailOpen("server.otel.export-failed", `http_${res.status}`);
                 opts.onError?.(new Error(`OTLP export HTTP ${res.status}`));
@@ -92,7 +82,7 @@ export function startOtlpExporter(metrics, opts) {
         }
         catch (err) {
             recordFailOpen("server.otel.export-failed", String(err));
-            opts.onError?.(err); // export is best-effort — a collector hiccup must never affect serving
+            opts.onError?.(err);
         }
         finally {
             inFlight = false;

package/dist/observability/principal-context.js

@@ -1,17 +1,8 @@
-/**
- * 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();
 }

package/dist/observability/prompt-manifest.js

@@ -1,9 +1,3 @@
-// design/158 N18: the prompt-manifest / config-assembled observability face moved VERBATIM out of budget.ts
-// (lens4 §4.1 — budget.ts's name says cost/budget, but this half is wire-observability projection of core's
-// `prompt.assembled`/`config.assembled` trace events, unrelated to spend). budget.ts re-exports all four for
-// compat (its own createTracer still consumes promptManifestRecordOf/configAssembledRecordOf/PromptManifestTracker).
-/** Whitelist one `prompt.assembled` trace event into a {@link PromptManifestRecord} (v1 face required,
- *  v2 `sections`/`tools` additive — absent stays absent). */
 export function promptManifestRecordOf(e) {
     return {
         constitution: String(e.constitution),
@@ -14,8 +8,6 @@ export function promptManifestRecordOf(e) {
         ...(Array.isArray(e.tools)
             ? { tools: e.tools.map((t) => ({ wireName: String(t.wireName), aliases: (Array.isArray(t.aliases) ? t.aliases : []).map(String), contractId: String(t.contractId), implementationRevision: String(t.implementationRevision), cardId: String(t.cardId), shapeDigest: String(t.shapeDigest), wireSchemaDigest: String(t.wireSchemaDigest) })) }
             : {}),
-        // toolDisclosure(core 5.15.0 #181,[2872] 提货②):三键逐挑——数值有限、两词字符串非空才铸;
-        // 畸形按缺席(不铸假值,与 sections/tools 的 additive 同规)。
         ...(typeof e.toolDisclosure === "object" && e.toolDisclosure !== null &&
             typeof e.toolDisclosure.deferredTools === "number" && Number.isFinite(e.toolDisclosure.deferredTools) &&
             typeof e.toolDisclosure.strategy === "string" && e.toolDisclosure.strategy.length > 0 &&
@@ -25,23 +17,6 @@ export function promptManifestRecordOf(e) {
         totalChars: e.totalChars,
     };
 }
-/**
- * [998]② per-task prompt-manifest accumulator — the `ModelUsageTracker`(budget.ts)pattern: the
- * `prompt.assembled` tracer hook is SYNC/no-IO, so it cannot persist; it RECORDS here (registered
- * top-level runs only — the same leak fence: sub-task manifests are never registered, never leak), and
- * the durable run lifecycle DRAINS the pending records into `prompt_assembled` events. Two departures
- * from the ModelUsage shape (release-review findings):
- *  - The pending value is an ordered QUEUE, not a single slot: a cascade/verify leg re-prepares under
- *    ONE taskId (core's runCascade passes the same spec taskId to every rung), and each prepare's
- *    manifest must persist — latest-wins would hide the prompt actually used by earlier billed rungs.
- *  - {@link register} returns a per-leg LEASE and {@link clear} requires it: after setSuspended makes
- *    the row claimable, a fast sibling resume can re-register the same taskId before the parked leg's
- *    finally runs (the codebase's documented B-3 window) — an unconditional clear there would silently
- *    delete the NEW leg's registration/pending manifest. Identity-guarded like the sibling
- *    inflight/steerable teardowns.
- */
-/** [1301]③ — `config.assembled` 的白名单投影(core 1.346 trace:catalogVersion/fields[来源标注]/
- *  overrideReasons)。fields 已是 core 精选的观测形(digest-free、有界);32KiB 罩防未来膨胀。 */
 export function configAssembledRecordOf(e) {
     const rec = {
         catalogVersion: e.catalogVersion,
@@ -51,7 +26,7 @@ export function configAssembledRecordOf(e) {
     };
     try {
         if (JSON.stringify(rec).length > 32_768)
-            return undefined; // bounded frame — oversize dropped, never truncated半形
+            return undefined;
     }
     catch {
         return undefined;
@@ -60,14 +35,9 @@ export function configAssembledRecordOf(e) {
 }
 export class PromptManifestTracker {
     byTask = new Map();
-    /** [1301]③:config.assembled 的同生命周期伴随记录(register 同门、drainConfig 同拍)。队列形
-     *  (codex F2):cascade 每 rung 独立解析配置,后到覆盖会把先前已计费 rung 的生效配置抹掉——与
-     *  prompt manifests 同姿势逐条保序。 */
     configByTask = new Map();
     active = new Map();
     leaseCounter = 0;
-    /** Mark a TOP-LEVEL run active (same fence as `ModelUsageTracker.register`, budget.ts). Returns this leg's
-     *  lease — pass it to {@link clear} so only the CURRENT owner can tear the slot down. */
     register(taskId) {
         if (!taskId)
             return 0;
@@ -75,7 +45,6 @@ export class PromptManifestTracker {
         this.active.set(taskId, lease);
         return lease;
     }
-    /** Queue this prepare's manifest — ONLY for a registered top-level run (else a no-op). Sync, never throws. */
     record(taskId, m) {
         if (!taskId || !this.active.has(taskId))
             return;
@@ -85,7 +54,6 @@ export class PromptManifestTracker {
         else
             this.byTask.set(taskId, [m]);
     }
-    /** [1301]③:队一条 config.assembled 投影(同 register 门;逐条保序——cascade 每 rung 各留其形)。 */
     recordConfig(taskId, rec) {
         if (!taskId || !this.active.has(taskId))
             return;
@@ -95,7 +63,6 @@ export class PromptManifestTracker {
         else
             this.configByTask.set(taskId, [rec]);
     }
-    /** Return-and-clear ALL pending config records in emission order; `undefined` when none. */
     drainConfig(taskId) {
         const q = this.configByTask.get(taskId);
         if (!q || q.length === 0)
@@ -103,7 +70,6 @@ export class PromptManifestTracker {
         this.configByTask.delete(taskId);
         return q;
     }
-    /** Return-and-clear ALL pending manifests in emission order; `undefined` when none. */
     drain(taskId) {
         const q = this.byTask.get(taskId);
         if (!q || q.length === 0)
@@ -111,8 +77,6 @@ export class PromptManifestTracker {
         this.byTask.delete(taskId);
         return q;
     }
-    /** Drop pending + unregister (run end / abandoned leg) — but ONLY while `lease` still owns the slot;
-     *  a stale leg's teardown after a fast re-register is a no-op (the new leg owns it now). */
     clear(taskId, lease) {
         if (this.active.get(taskId) !== lease)
             return;

package/dist/observability/rate-limit.js

@@ -1,15 +1,12 @@
 export class RateLimiter {
     windowMs;
     windows = new Map();
-    /** 🔴 不再 `readonly`:限额是**比较参数**,不是窗表状态 —— 换代只动它,窗内已计的数一个不动(§5)。 */
     limit;
     constructor(limit, windowMs = 60_000) {
         this.windowMs = windowMs;
         this.limit = limit;
     }
     check(key) {
-        // 关断哨兵:零比较、零窗表写入。off 期间不攒计数是刻意的——0→N 打开时应该是一个完整的新窗口,
-        // 而不是「上来就超」(那段时间根本没有 ceiling,补记账等于追溯执法)。
         if (this.limit <= 0)
             return { allowed: true, retryAfterSec: 0, remaining: Number.POSITIVE_INFINITY };
         const now = Date.now();
@@ -27,7 +24,6 @@ export class RateLimiter {
     setLimits(next) {
         this.limit = next.rateLimitPerMin;
     }
-    /** Drop expired windows (call periodically). */
     sweep(now = Date.now()) {
         for (const [k, w] of this.windows)
             if (w.resetAt <= now)

package/dist/observability/secret-env-scrub.js

@@ -1,53 +1,18 @@
-/**
- * A-033.3(#256)—— **密钥形 env 剥除的留痕面**(core D1 `scrubSecretEnv` 的可观测半场)。
- *
- * ## 它解决的问题
- * `scrubSecretEnv` 是本仓两条 shell/子进程腿的**安全默认**:模型可驱动的 shell(`inheritEnv:"scrub"`)与
- * git 子进程(钩子/凭证助手)拿到的 env 里,`*_KEY`/`*_TOKEN`/`*_SECRET`/`*_PASSWORD`… 一律先丢掉。
- * 两处都以**单参形**调用,于是「这一次到底丢了哪些 key、按哪条规则(suffix-rule / exact-name)、置信度多少」
- * **零留痕** —— 部署方既证明不了保护生效过,也发现不了它悄悄不生效了(词表漂移 / 一个新的密钥命名法从
- * 规则的缝里穿过去 / 某条腿被改成 `inheritEnv:"all"`)。core 早就把收集口开好了(`findings?:
- * SecretEnvFinding[]`,d.ts 原话:the VALUE is never carried — this record is meant to be loggable),
- * 缺的只是本仓这半场。本模块就是那半场,**不是**一个新的执法面:它一个字节也不改变剥除行为。
- *
- * ## 形(照 `fail-open.ts` 的仓内先例)
- *  1. **计数(逐次)** —— `secret_env_scrubbed_total{site,kind,confidence}`;
- *  2. **结构化披露(每 site×key 一次)** —— 首次在某条腿上丢掉某个 key 时一条 `info`,之后同 key 只走计数。
- *     不是「每 site 一次」:一个**新**的密钥形 key 后来才出现(部署加了一个凭证)时,那才是最该看见的一行。
- * 值永不进任何一件(core 的 finding 本身就不携带值)。
- *
- * ## 为什么是进程级自由函数而不是注入
- * 与 `recordFailOpen` 同因:两个调用点都在**没有 logger/metrics 句柄**的深处
- * (`plugins/remote-env-host.ts` 的 `mergeEnv` 全文零观测通道;`project-memory.ts` 的 `git()` 是个自由函数)。
- * 装配层用 {@link installSecretEnvScrubRecorder} 把句柄接上,装配之前命中的次数不会丢(计数照常累加,
- * install 时一次性补进 metrics),披露行则在下一次命中时补发(未成功披露的 key 不进 `disclosed` 集)。
- */
 import { summarizeRedactions } from "@sema-agent/core";
-/** 登记过的剥除现场。闭集:未登记的 site 传不进 {@link recordSecretEnvScrub}(编译期拒,同 FAIL_OPEN_TAGS 纪律)。 */
 export const SECRET_ENV_SCRUB_SITES = {
     "server.remote-env-host.inherit-scrub": "模型可驱动的 host shell 继承 env(`inheritEnv:\"scrub\"` 默认腿)——这条腿上的一次泄漏等于把编排器的脑钥/仓库令牌交给模型选的命令",
     "server.project-memory.git-subprocess": "project-memory 读仓叙事时的 git 子进程 env —— 仓内的钩子/凭证助手会以本进程身份运行",
 };
-/** 计数器名。 */
 const SCRUB_COUNTER = "secret_env_scrubbed_total";
-/** 已披露集的上限。key 集在一个进程里实际上是常量(恒扫同一份 `process.env`),这个帽只是防病态输入
- *  把集合撑爆;越帽之后只停止**新增披露**,计数照常(缺席的是行,不是账)。 */
 const DISCLOSED_CAP = 512;
-/** 桶键与披露键的分隔符。用 `=` 是有据的:POSIX 环境变量名里唯二不可能出现的字节就是 `=` 与 NUL
- *  (NUL 不写进源码 —— 裸控制字节会让 grep 对整个文件失明,本仓有机械门盯它)。用空格/冒号分隔则会让
- *  `A B`+`C` 与 `A`+`B C` 撞成同一个键 —— 标签串台 = 遥测说谎。 */
 const SEP = "=";
 let sink = {};
-/** `site=kind=confidence` → 累计次数(逐次,进程级)。 */
 let counts = new Map();
-/** 已经推进 metrics 的部分 —— 差额即欠账,install 时一次性补。 */
 let pushed = new Map();
-/** `site=key` —— 已经出过披露行的现场×键。 */
 let disclosed = new Set();
 function bucketKey(site, f) {
     return `${site}${SEP}${f.kind}${SEP}${f.confidence}`;
 }
-/** 把 counts 与 pushed 的差额推进 metrics。metrics 缺席时什么也不做(差额留着,下次补)。 */
 function drainToMetrics() {
     const m = sink.metrics;
     if (m === undefined)
@@ -59,17 +24,12 @@ function drainToMetrics() {
         const [site, kind, confidence] = k.split(SEP);
         try {
             m.inc(SCRUB_COUNTER, { site: site, kind: kind, confidence: confidence }, n - already);
-            pushed.set(k, n); // 真进了汇才销账(投递失败 ⇒ 差额留着重放)
+            pushed.set(k, n);
         }
         catch {
-            /* 下一次命中/下一次装配再补 */
         }
     }
 }
-/**
- * 记一次剥除。**总不抛** —— 观测本身绝不能变成故障(同 `recordFailOpen` / reapers 的判据)。
- * `findings` 为空(这一次没丢任何 key)时什么也不做:那不是事件,是常态。
- */
 export function recordSecretEnvScrub(site, findings) {
     if (findings.length === 0)
         return;
@@ -81,13 +41,7 @@ export function recordSecretEnvScrub(site, findings) {
         drainToMetrics();
         const logger = sink.logger;
         if (logger === undefined)
-            return; // 披露行留到有 logger 的下一次命中(未进 disclosed ⇒ 会补发)
-        // 🔴 帽是**对这一次的批也生效**的(codex 复审 round2 medium 真修):先按剩余容量截断,再用截断后的
-        // 那一批去发行与登记。两条都靠它:
-        //   ① 帽满 ⇒ 停止披露,而不是「喊了但记不下」—— 后者会把「每 site×key 一次」在 key 最多的时候
-        //      反转成「每次调用一行」(mergeEnv 是逐命令调用的,那是刷屏);
-        //   ② 单批越界 ⇒ 也得截断 —— 只在批**之前**判帽,一次 513 条的病态 env 会一次性把 513 条全发出去
-        //      (一行超大日志)并全部留驻,帽等于没有。计数不受截断影响:账永远是全的,缺席的只是行。
+            return;
         const room = DISCLOSED_CAP - disclosed.size;
         if (room <= 0)
             return;
@@ -97,34 +51,26 @@ export function recordSecretEnvScrub(site, findings) {
         logger.info("secret_env_scrubbed", {
             site,
             note: SECRET_ENV_SCRUB_SITES[site],
-            // 只报**本次新见**的 key(值永不携带 —— core 的 finding 按契约只带键名/规则/置信度/来源)。
             keys: fresh.map((f) => f.key),
-            // 一行人读摘要走 core 的 `summarizeRedactions`(SecretEnvFinding 满足 SummarizableFinding),
-            // 不在本仓另写一份分组渲染 —— 那正是本票要消灭的那种孪生。
             summary: summarizeRedactions(fresh),
         });
         for (const f of fresh)
             disclosed.add(`${site}${SEP}${f.key}`);
     }
     catch {
-        /* 观测绝不抛 */
     }
 }
-/** 装配层把 logger/metrics 接上(main.ts,与 `installFailOpenRecorder` 同一处)。装配前累计的次数在此补进 metrics。 */
 export function installSecretEnvScrubRecorder(deps) {
     sink = { ...deps };
     deps.metrics?.counter(SCRUB_COUNTER, "secret-pattern env entries dropped before spawning a child process, by site/rule/confidence (core scrubSecretEnv findings)");
     drainToMetrics();
 }
-/** 已留驻的「现场×键」条数(测试/诊断读面)。恒 ≤ {@link DISCLOSED_CAP}。 */
 export function secretEnvScrubDisclosedSize() {
     return disclosed.size;
 }
-/** 本进程各桶的累计次数(测试/诊断读面)。 */
 export function secretEnvScrubCounts() {
     return new Map(counts);
 }
-/** 测试用重置(进程级状态在同一个 vitest worker 里跨用例存活)。 */
 export function resetSecretEnvScrubRecorderForTest(deps = {}) {
     counts = new Map();
     pushed = new Map();