@sema-agent/server 1.323.0 → 2.0.1

package/dist/brain.d.ts

@@ -1,8 +1,33 @@
 import { type Brain, type BreakerState } from "@sema-agent/core";
 import type { ServiceConfig } from "./config-types.js";
+/**
+ * Build the external "Brain" (LLM) from config.
+ *
+ * Composition (A1 + the 1.38 resilience stack, ordered timeout-innermost → breaker → failover-outermost):
+ *   - **Tiered timeouts** (1.38, `connectTimeoutMs`/`firstTokenTimeoutMs`) are passed into each
+ *     openai-compatible brain at creation — they bound "gateway never accepts the connection" and
+ *     "stream opened but hangs without a token" as retryable `[network]` failures. Default ON
+ *     (30s/120s, [880] fleet audit; env =0 disables).
+ *   - **Circuit breaker** (`createCircuitBreakerBrain`) wraps the *primary* gateway route(s) when
+ *     `MODEL_CIRCUIT_BREAKER=true`: after N transient failures it opens and fast-fails, so failover
+ *     switches to the bare backup immediately instead of waiting out each timeout. The last gateway
+ *     route stays bare (last-resort) — matching core design/20. State is core's in-process Map (each
+ *     replica trips independently; cross-replica shared state via a TiDB adapter is a follow-up).
+ *   - **Failover** (`createFailoverBrain`) stacks the primary gateway with optional
+ *     `MODEL_GATEWAY_FALLBACK_URLS` — same protocol, same model id, tried in order.
+ *   - **Routing** (`createRoutingBrain`, by `model.provider`) selects the cloud Anthropic Messages
+ *     route for `provider:"anthropic"`, and the gateway/failover stack for everything else. (Anthropic
+ *     ↔ vLLM is a *routing* choice, not failover.)
+ *
+ * When no fallback URL, no Anthropic key, and no resilience thresholds are configured, this returns the
+ * bare openai brain (carrying the default-on watchdog timeouts — set the three env knobs to 0 for the
+ * pre-[880] fully-bare shape). The Model itself (id / contextWindow / maxTokens / provider) flows
+ * per-request through `Runner({ models })`.
+ */
 export declare function createBrain(config: ServiceConfig, deps?: {
     fetchImpl?: typeof fetch;
     breakerState?: BreakerState;
 }): Brain;
+/** One-line summary of the active brain composition, for the startup log. */
 export declare function brainSummary(config: ServiceConfig): Record<string, unknown>;
 //# sourceMappingURL=brain.d.ts.map

package/dist/brain.js

@@ -1,5 +1,9 @@
 import { createAnthropicBrain, createCircuitBreakerBrain, createDegradingBrain, createFailoverBrain, createOpenAIBrain, createRoutingBrain, } from "@sema-agent/core";
 const DEFAULT_RESILIENCE = {
+    // Watchdog defaults ON — mirrors config.ts env defaults so a config object without a
+    // resilience block gets the same posture. connect/firstToken per the [880] fleet audit
+    // (core's idle timer only arms after the first token, so firstToken is the sole guard for a
+    // stream that opens and never emits); idle = CC 196 parity. 0 restores off.
     connectTimeoutMs: 30_000,
     firstTokenTimeoutMs: 120_000,
     idleTimeoutMs: 300_000,
@@ -7,30 +11,70 @@ const DEFAULT_RESILIENCE = {
     failureThreshold: 5,
     cooldownMs: 30_000,
 };
+/**
+ * Build the external "Brain" (LLM) from config.
+ *
+ * Composition (A1 + the 1.38 resilience stack, ordered timeout-innermost → breaker → failover-outermost):
+ *   - **Tiered timeouts** (1.38, `connectTimeoutMs`/`firstTokenTimeoutMs`) are passed into each
+ *     openai-compatible brain at creation — they bound "gateway never accepts the connection" and
+ *     "stream opened but hangs without a token" as retryable `[network]` failures. Default ON
+ *     (30s/120s, [880] fleet audit; env =0 disables).
+ *   - **Circuit breaker** (`createCircuitBreakerBrain`) wraps the *primary* gateway route(s) when
+ *     `MODEL_CIRCUIT_BREAKER=true`: after N transient failures it opens and fast-fails, so failover
+ *     switches to the bare backup immediately instead of waiting out each timeout. The last gateway
+ *     route stays bare (last-resort) — matching core design/20. State is core's in-process Map (each
+ *     replica trips independently; cross-replica shared state via a TiDB adapter is a follow-up).
+ *   - **Failover** (`createFailoverBrain`) stacks the primary gateway with optional
+ *     `MODEL_GATEWAY_FALLBACK_URLS` — same protocol, same model id, tried in order.
+ *   - **Routing** (`createRoutingBrain`, by `model.provider`) selects the cloud Anthropic Messages
+ *     route for `provider:"anthropic"`, and the gateway/failover stack for everything else. (Anthropic
+ *     ↔ vLLM is a *routing* choice, not failover.)
+ *
+ * When no fallback URL, no Anthropic key, and no resilience thresholds are configured, this returns the
+ * bare openai brain (carrying the default-on watchdog timeouts — set the three env knobs to 0 for the
+ * pre-[880] fully-bare shape). The Model itself (id / contextWindow / maxTokens / provider) flows
+ * per-request through `Runner({ models })`.
+ */
 export function createBrain(config, deps = {}) {
     const { fetchImpl, breakerState } = deps;
     const r = config.resilience ?? DEFAULT_RESILIENCE;
+    // [1.207 codex H4] pass 0 THROUGH (never map to undefined): core 1.296's wall-clock lane supplies per-call
+    // stall suggestions merged `configValue ?? suggested` — an undefined field silently re-arms the watchdog a
+    // task-timeout run (idle would come back at 90s). An explicit 0 is core's documented "constructor-explicit
+    // disable, wins over suggestions"; 0 also disarms the timer on pre-1.296 arming code (`value > 0` guards).
     const timeouts = {
         connectTimeoutMs: r.connectTimeoutMs,
         firstTokenTimeoutMs: r.firstTokenTimeoutMs,
         idleTimeoutMs: r.idleTimeoutMs,
     };
+    // Local openai-compatible gateway stack: primary + optional same-protocol fallbacks (failover).
     const routes = [config.gatewayBaseUrl, ...config.gatewayFallbackUrls];
     const openaiBrains = routes.map((baseUrl, i) => {
         const brain = createOpenAIBrain({ baseUrl, apiKey: config.gatewayApiKey, maxRetries: 2, fetchImpl, ...timeouts });
+        // Breaker on every route EXCEPT the last (the bare last-resort backup), and only with ≥2 routes —
+        // a breaker without a failover alternative would just hard-fail the only gateway during cooldown.
         const isLast = i === routes.length - 1;
         return r.circuitBreaker && !isLast
             ? createCircuitBreakerBrain(brain, {
                 failureThreshold: r.failureThreshold,
                 cooldownMs: r.cooldownMs,
-                state: breakerState,
+                state: breakerState, // shared cross-replica state when provided; else core's in-process Map
+                // L14(接入审计):core 默认 key=`<provider>:<id>`(与 baseUrl 无关)——≥3 路由时 routes[0..n-2]
+                // 命中同一 breaker 条目,一条网关的故障计入另一条的阈值(失 per-route 隔离)。key 掺入本路由
+                // baseUrl 恢复隔离;1-2 路由行为不变(只有一个带 breaker 的路由)。
                 key: (m) => `${m.provider ?? "openai"}:${m.id}@${baseUrl}`,
             })
             : brain;
     });
     const gatewayBrain = openaiBrains.length > 1 ? createFailoverBrain(openaiBrains) : openaiBrains[0];
+    // Route by model.provider: "anthropic" → cloud Messages API (prompt caching + thinking replay),
+    // everything else → the local gateway stack (also the fallback for an unrecognized provider).
     const anthropicBrain = config.anthropic
         ? createAnthropicBrain({
+            // Anthropic-compatible Bearer auth: `ANTHROPIC_AUTH_TOKEN` → `Authorization: Bearer`
+            // via core's extra-`headers` seam, and apiKey is then NOT passed (x-api-key only emits when set) —
+            // 二选一, AUTH_TOKEN priority. Bearer-first providers in this ecosystem commonly accept only
+            // the Bearer form.
             ...(config.anthropic.authToken
                 ? { headers: { Authorization: `Bearer ${config.anthropic.authToken}` } }
                 : { apiKey: config.anthropic.apiKey }),
@@ -42,12 +86,24 @@ export function createBrain(config, deps = {}) {
             ...timeouts,
         })
         : undefined;
+    // No cloud route + single gateway → bare brain (unchanged); else route by provider.
     let brain = anthropicBrain
         ? createRoutingBrain({ anthropic: anthropicBrain }, { fallback: gatewayBrain })
         : gatewayBrain;
+    // Reactive degradation (1.39) — wrapped OUTERMOST (core council #8): on rate_limit / breaker-open from
+    // the primary, serve a cheaper catalog model instead of failing. The fallback brain carries its own
+    // credentials (the decorator clears the primary's per-call apiKey so it can't leak to a different
+    // provider). fallbackModel resolved from the catalog.
     if (config.degrade?.reactive) {
         const fallbackModel = config.models[config.degrade.to];
         if (fallbackModel) {
+            // Cross-gateway degrade (audit B, brain.ts): the degrading decorator clears the per-call apiKey
+            // (so the primary's key can't leak to another provider), which left the fallback authenticating
+            // with the PRIMARY gateway key even when the catalog points the target at a different gateway.
+            // Resolve the target's own key at construction via the existing per-model apiKeyEnv mechanism
+            // (sema-registry catalog); `model.baseUrl` already wins inside the openai brain — pass it
+            // explicitly so the route is visible here. Unset catalog baseUrl/apiKeyEnv = same-gateway degrade
+            // (unchanged), which stays meaningful for per-model limits (e.g. deepseek pro→flash).
             const fbKeyEnv = config.modelApiKeyEnv?.[fallbackModel.name] ?? config.modelApiKeyEnv?.[config.degrade.to];
             const fbApiKey = (fbKeyEnv ? process.env[fbKeyEnv] : undefined) || config.gatewayApiKey;
             const fallback = fallbackModel.provider === "anthropic" && anthropicBrain
@@ -58,9 +114,11 @@ export function createBrain(config, deps = {}) {
     }
     return brain;
 }
+/** One-line summary of the active brain composition, for the startup log. */
 export function brainSummary(config) {
     const r = config.resilience ?? DEFAULT_RESILIENCE;
     const hasFailover = config.gatewayFallbackUrls.length > 0;
+    // The breaker only does anything with ≥2 gateway routes (it pairs with failover); flag a no-op config.
     const breakerActive = r.circuitBreaker && hasFailover;
     return {
         gateway: config.gatewayBaseUrl,
@@ -74,7 +132,9 @@ export function brainSummary(config) {
         circuitBreaker: breakerActive,
         circuitBreakerRequested: r.circuitBreaker,
         circuitBreakerNoop: r.circuitBreaker && !hasFailover ? "needs ≥2 gateway routes" : null,
+        // reactive degrade is active only if a valid catalog target resolves
         reactiveDegradeTo: config.degrade?.reactive && config.models?.[config.degrade.to] ? config.degrade.to : null,
+        // cross-gateway degrade visibility: the fallback's effective route (null = degrade off)
         reactiveDegradeBaseUrl: config.degrade?.reactive && config.models?.[config.degrade.to]
             ? config.models[config.degrade.to].baseUrl || config.gatewayBaseUrl
             : null,

package/dist/budget.d.ts

@@ -1,11 +1,29 @@
+/**
+ * Cost / budget / trace wiring for the Runner (core 1.37) — pure, testable helpers kept out of the
+ * auto-running main.ts:
+ *   ③ buildPricing   — Model.cost catalog → injected ModelPricing (authoritative costMicroUsd).
+ *   ④ createTracer    — core's content-free TraceEvents → /metrics (spend, first-token, tool calls).
+ *   ⑤ cappedCeiling  — clamp a caller's requested per-task budget DOWN to the operator ceiling.
+ */
 import { type Model, type ModelPricing, type TracerHook } from "@sema-agent/core";
 import type { Metrics } from "./observability/metrics.js";
 import type { QuotaTracker } from "./observability/cost-quota.js";
 import type { FleetUsageAccumulator } from "./fleet-client.js";
 import type { FleetLeaseManager } from "./fleet-lease.js";
 import { type PromptManifestTracker } from "./observability/prompt-manifest.js";
+/** ③ Per-model pricing keyed by model id (core falls back to each Model.cost when a model is absent). */
 export declare function buildPricing(models: Record<string, Model>): Record<string, ModelPricing>;
+/**
+ * Bound the cardinality of a free-form metric label value (BL-11/BL-21). A label fed by untrusted/unbounded
+ * input — MCP tool names (a misconfigured/malicious server can emit thousands of dynamic names) or center
+ * model ids (a malformed roster) — would otherwise mint an unbounded number of metric series: a slow memory
+ * leak in the registry + a /metrics scrape blow-up. We track the DISTINCT values seen; once the cap is hit,
+ * further NEW values collapse into one `__other__` bucket (already-seen values still report exactly). The
+ * cap is made observable (no silent truncation) via `onOverflow`, fired once when the cap is first crossed.
+ */
 export declare function cardinalityGuard(cap: number, onOverflow: () => void): (value: string) => string;
+/** Per-model usage accumulated for one task (shell-host contract E8). Token names mirror `turn_end.usage` /
+ *  the contract's per-model entry; `costMicroUsd` is micro-USD (÷1e6 for USD). */
 export interface ModelUsageDelta {
     inputTokens: number;
     outputTokens: number;
@@ -13,16 +31,59 @@ export interface ModelUsageDelta {
     cacheWriteTokens: number;
     costMicroUsd: number;
 }
+/**
+ * E8 (shell-host contract): per-task × per-model usage accumulator, fed (synchronously) by the `brain.call`
+ * tracer. The `TracerHook` contract is SYNC / no-IO, so we cannot persist from the hook; instead we accumulate
+ * here in memory and the run lifecycle DRAINS us at each turn boundary, appending the delta to the durable run
+ * event log. The **append-only delta** model is what makes it resume-safe: a task that suspends and resumes in a
+ * different process appends only its own post-resume deltas; the result echo SUMS all `model_usage` events across
+ * the whole (possibly multi-process) run. Memory is bounded — a task's entry is dropped on {@link drain}/{@link clear}.
+ */
 export declare class ModelUsageTracker {
     private readonly byTask;
     private readonly active;
+    /** Mark a TOP-LEVEL run active so its `brain.call` usage is tracked. **Required** — `record` ignores any taskId
+     *  that isn't registered. This is the leak fence: delegated SUB-TASKS (team members,
+     *  adversarial verifiers) run on throwaway core-minted sessionIds that the run lifecycle never registers/drains,
+     *  so without this gate their usage would accumulate under ids nothing ever clears → an unbounded process-lifetime
+     *  leak. Sub-task spend is intentionally NOT in the per-run `modelUsage` echo (it lands in `TaskStats.nested`);
+     *  `modelUsage` is the TOP-LEVEL run's own per-model usage. Call at run start; {@link clear} unregisters. */
     register(taskId: string): void;
+    /** Accumulate one `brain.call`'s usage — ONLY for a registered top-level run (else a no-op; see {@link register}).
+     *  Sync, never throws (TracerHook contract). */
     record(taskId: string, model: string, d: ModelUsageDelta): void;
+    /** Return the usage accumulated for this task SINCE the last drain (per neutral model id), and RESET it.
+     *  `undefined` when nothing accrued — callers skip the durable append then. */
     drain(taskId: string): Record<string, ModelUsageDelta> | undefined;
+    /** Drop a task's pending accumulation AND unregister it (cleanup at run end / on an abandoned/errored leg). After
+     *  this, further `record(taskId,…)` no-ops until a fresh {@link register}. `drain` deliberately does NOT unregister
+     *  (the run continues across turns); only `clear` ends the run's tracking. */
     clear(taskId: string): void;
 }
 export { type PromptManifestRecord, promptManifestRecordOf, configAssembledRecordOf, PromptManifestTracker, } from "./observability/prompt-manifest.js";
+/**
+ * ④ Bridge core's fire-and-forget trace events to /metrics (+ the E8 per-task model-usage accumulator). The hook
+ * is void / never throws / does no sync IO (in-memory counters only), per the TracerHook contract. `brain.call`
+ * fires for EVERY call (top-level + async + council sub-tasks) → `model_cost_micro_usd_total` is the authoritative
+ * spend, and (when a {@link ModelUsageTracker} is supplied) the per-task `modelUsage` echo's source.
+ */
 export declare function createTracer(metrics: Pick<Metrics, "inc" | "observe">, costQuota?: QuotaTracker, modelUsage?: ModelUsageTracker, fleetUsage?: FleetUsageAccumulator, fleetLease?: FleetLeaseManager, quotaWeightFor?: (model: string) => number, promptManifests?: PromptManifestTracker): TracerHook;
+/**
+ * [1469] side-query 记账 seam(codex R3 high:sideQuery 不走 core tracer——brain.stream 直调不发
+ * brain.call——createTracer 的四路 sink(costQuota/model_cost 指标/fleetUsage 批报/fleetLease 本地扣减)
+ * 全部旁路)。本 seam 与 createTracer 的 brain.call 臂**同语义**喂同一组 sink:weightedTokens 同式
+ * (tokens×quotaWeight,weight-at-burn 固化)、micro-USD 同轴。装配点与 createTracer 同一处(main.ts),
+ * 传同一组实例——两臂永不分家。
+ *
+ * 已知残差(codex R3 medium,记档):cost 源=core SideQueryResult.usage.cost.total(brain 层计价),
+ * OpenAI cache-heavy 输入按全价入账(tracer 的 e.costMicroUsd 是 cache-family-aware 价)——方向=多收
+ * (保守,绝不少收);根修=core 在 SideQueryResult 上回权威 costMicroUsd(已提货 core)。model 标签/
+ * weight 键用**路由身份 r.model**(池配置有界)非 servedModel(provider 上报,无界)。
+ */
+/** core `usage-accounting.cacheFamilyOf` 的私拷镜像(core exports map 只开 barrel,该函数未导出——
+ *  已提货 core barrel 导出,到货即换,normalizeAgentName 同款纪律)。逐字对拍源:
+ *  dist/core/runner/usage-accounting.js(override 别名 anthropic/openai + api 判 anthropic-messages/
+ *  bedrock-converse-stream)。undefined 入参(catalog 查不到)→ undefined,调用方走保守臂。 */
 export declare function cacheFamilyOfMirror(model: {
     api?: string;
     params?: {
@@ -42,5 +103,10 @@ export declare function createSideQueryAccountant(metrics: Pick<Metrics, "inc">,
         };
     };
 }) => void;
+/**
+ * ⑤ Resolve a per-task budget: honor the caller's requested value but never let it EXCEED the operator
+ * ceiling. `0`/unset ceiling = no limit (returns the caller's value, or undefined). A non-positive /
+ * non-numeric request is ignored (falls back to the ceiling). Returns undefined = "no budget gate".
+ */
 export declare function cappedCeiling(requested: unknown, ceiling: number): number | undefined;
 //# sourceMappingURL=budget.d.ts.map

package/dist/budget.js

@@ -1,6 +1,14 @@
+/**
+ * Cost / budget / trace wiring for the Runner (core 1.37) — pure, testable helpers kept out of the
+ * auto-running main.ts:
+ *   ③ buildPricing   — Model.cost catalog → injected ModelPricing (authoritative costMicroUsd).
+ *   ④ createTracer    — core's content-free TraceEvents → /metrics (spend, first-token, tool calls).
+ *   ⑤ cappedCeiling  — clamp a caller's requested per-task budget DOWN to the operator ceiling.
+ */
 import { modelCostToPricing } from "@sema-agent/core";
 import { currentPrincipal } from "./observability/principal-context.js";
-import { promptManifestRecordOf, configAssembledRecordOf } from "./observability/prompt-manifest.js";
+import { promptManifestRecordOf, configAssembledRecordOf } from "./observability/prompt-manifest.js"; // design/158 N18: see re-export block below (moved to ./observability/prompt-manifest.js)
+/** ③ Per-model pricing keyed by model id (core falls back to each Model.cost when a model is absent). */
 export function buildPricing(models) {
     const pricing = {};
     for (const m of Object.values(models))
@@ -8,6 +16,14 @@ export function buildPricing(models) {
             pricing[m.id] = modelCostToPricing(m.cost);
     return pricing;
 }
+/**
+ * Bound the cardinality of a free-form metric label value (BL-11/BL-21). A label fed by untrusted/unbounded
+ * input — MCP tool names (a misconfigured/malicious server can emit thousands of dynamic names) or center
+ * model ids (a malformed roster) — would otherwise mint an unbounded number of metric series: a slow memory
+ * leak in the registry + a /metrics scrape blow-up. We track the DISTINCT values seen; once the cap is hit,
+ * further NEW values collapse into one `__other__` bucket (already-seen values still report exactly). The
+ * cap is made observable (no silent truncation) via `onOverflow`, fired once when the cap is first crossed.
+ */
 export function cardinalityGuard(cap, onOverflow) {
     const seen = new Set();
     let overflowed = false;
@@ -25,11 +41,27 @@ export function cardinalityGuard(cap, onOverflow) {
         return value;
     };
 }
+/**
+ * E8 (shell-host contract): per-task × per-model usage accumulator, fed (synchronously) by the `brain.call`
+ * tracer. The `TracerHook` contract is SYNC / no-IO, so we cannot persist from the hook; instead we accumulate
+ * here in memory and the run lifecycle DRAINS us at each turn boundary, appending the delta to the durable run
+ * event log. The **append-only delta** model is what makes it resume-safe: a task that suspends and resumes in a
+ * different process appends only its own post-resume deltas; the result echo SUMS all `model_usage` events across
+ * the whole (possibly multi-process) run. Memory is bounded — a task's entry is dropped on {@link drain}/{@link clear}.
+ */
 export class ModelUsageTracker {
     byTask = new Map();
     active = new Set();
+    /** Mark a TOP-LEVEL run active so its `brain.call` usage is tracked. **Required** — `record` ignores any taskId
+     *  that isn't registered. This is the leak fence: delegated SUB-TASKS (team members,
+     *  adversarial verifiers) run on throwaway core-minted sessionIds that the run lifecycle never registers/drains,
+     *  so without this gate their usage would accumulate under ids nothing ever clears → an unbounded process-lifetime
+     *  leak. Sub-task spend is intentionally NOT in the per-run `modelUsage` echo (it lands in `TaskStats.nested`);
+     *  `modelUsage` is the TOP-LEVEL run's own per-model usage. Call at run start; {@link clear} unregisters. */
     register(taskId) { if (taskId)
         this.active.add(taskId); }
+    /** Accumulate one `brain.call`'s usage — ONLY for a registered top-level run (else a no-op; see {@link register}).
+     *  Sync, never throws (TracerHook contract). */
     record(taskId, model, d) {
         if (!taskId || !model || !this.active.has(taskId))
             return;
@@ -50,6 +82,8 @@ export class ModelUsageTracker {
             perModel.set(model, { ...d });
         }
     }
+    /** Return the usage accumulated for this task SINCE the last drain (per neutral model id), and RESET it.
+     *  `undefined` when nothing accrued — callers skip the durable append then. */
     drain(taskId) {
         const perModel = this.byTask.get(taskId);
         if (!perModel || perModel.size === 0)
@@ -60,27 +94,60 @@ export class ModelUsageTracker {
         this.byTask.delete(taskId);
         return out;
     }
+    /** Drop a task's pending accumulation AND unregister it (cleanup at run end / on an abandoned/errored leg). After
+     *  this, further `record(taskId,…)` no-ops until a fresh {@link register}. `drain` deliberately does NOT unregister
+     *  (the run continues across turns); only `clear` ends the run's tracking. */
     clear(taskId) { this.byTask.delete(taskId); this.active.delete(taskId); }
 }
+// design/158 N18: PromptManifestRecord / promptManifestRecordOf / configAssembledRecordOf / PromptManifestTracker
+// moved VERBATIM to ./observability/prompt-manifest.js (budget.ts's name says cost/budget; this face is
+// wire-observability projection of prompt.assembled/config.assembled, unrelated). Re-exported here so existing
+// importers (main.ts, runs.ts, http/server.ts, trace/project.ts, tests) keep working untouched — createTracer
+// below still consumes promptManifestRecordOf/configAssembledRecordOf/PromptManifestTracker.
 export { promptManifestRecordOf, configAssembledRecordOf, PromptManifestTracker, } from "./observability/prompt-manifest.js";
+/**
+ * ④ Bridge core's fire-and-forget trace events to /metrics (+ the E8 per-task model-usage accumulator). The hook
+ * is void / never throws / does no sync IO (in-memory counters only), per the TracerHook contract. `brain.call`
+ * fires for EVERY call (top-level + async + council sub-tasks) → `model_cost_micro_usd_total` is the authoritative
+ * spend, and (when a {@link ModelUsageTracker} is supplied) the per-task `modelUsage` echo's source.
+ */
 export function createTracer(metrics, costQuota, modelUsage, fleetUsage, fleetLease, quotaWeightFor, promptManifests) {
+    // Per-process cardinality guards for the two unbounded-input labels (BL-11/BL-21). 256 is generous for any
+    // real tool/model catalog; overflow bumps a counter so an over-cap deploy is observable, not silent.
     const toolName = cardinalityGuard(256, () => metrics.inc("metric_label_overflow_total", { label: "tool_name" }));
     const modelId = cardinalityGuard(256, () => metrics.inc("metric_label_overflow_total", { label: "model" }));
+    // provider flows from env/registry config (not a bounded enum) — guard it like modelId (1.127.0):
+    // a misconfigured registry entry must not explode Prometheus label cardinality. 64 is generous for real providers.
     const providerName = cardinalityGuard(64, () => metrics.inc("metric_label_overflow_total", { label: "provider" }));
     return (e) => {
         if (e.kind === "brain.call") {
+            // S18 (SILENT-FALLBACK P1): count every call by provider+model. provider is optional on the trace event —
+            // "unknown" = the routing layer fell through without a recognized provider (previously unobservable).
             metrics.inc("brain_calls_total", { provider: providerName(e.provider ?? "unknown"), model: modelId(e.model) });
             if (e.costMicroUsd) {
                 metrics.inc("model_cost_micro_usd_total", { model: modelId(e.model) }, e.costMicroUsd);
+                // ⑤b attribute spend to the originating principal (ALS) — reaches council/team sub-tasks too.
                 const principal = currentPrincipal();
                 if (principal)
                     costQuota?.add(principal, e.costMicroUsd);
             }
+            // E8 (shell-host): per-task × per-model usage for the `TaskStats.modelUsage` echo. `record` is a NO-OP unless
+            // e.taskId is a REGISTERED top-level run (the leak fence — sub-task/throwaway taskIds are never registered, so
+            // they neither leak nor enter the echo; their spend is in TaskStats.nested). Drained at turn boundaries into the
+            // durable log (resume-safe); the registered entry is dropped at run end (clear). NOT cardinality-guarded by
+            // model: bounded by a run's model set, and by the active-run set.
             modelUsage?.record(e.taskId, e.model, { inputTokens: e.promptTokens, outputTokens: e.completionTokens, cacheReadTokens: e.cacheRead, cacheWriteTokens: e.cacheWrite, costMicroUsd: e.costMicroUsd ?? 0 });
+            // weight-at-burn:加权 tokens = (prompt+completion)×模型配额倍率,在记账点固化(此后改倍率
+            // 不回算历史,registry ModelEntry.quotaWeight 同句契约)。weight 源=config.modelQuotaWeights(registry
+            // hot-apply;env lane 空表 ⇒ 1 兜底);非法回调值防御性归 1(tracer 契约 never-throws,不让坏表毒记账)。
             const qwRaw = quotaWeightFor?.(e.model);
             const qw = typeof qwRaw === "number" && Number.isFinite(qwRaw) && qwRaw > 0 ? qwRaw : 1;
             const weightedTokens = Math.round((e.promptTokens + e.completionTokens) * qw);
+            // P2 用量批报:principal×model 窗口累计(同 ⑤b 的 ALS 归因点 — 子任务花费也归到发起 principal),
+            // fleet-client 每窗口 drain→POST /api/fleet/usage。未配 fleet(accumulator 缺席)= 零行为。
             fleetUsage?.record(currentPrincipal(), e.model, e.taskId, { inputTokens: e.promptTokens, outputTokens: e.completionTokens, costMicroUsd: e.costMicroUsd ?? 0, weightedTokens, quotaWeightAtUse: qw });
+            // lease 消费(D4 AP):同一 ALS 归因点做 lease 本地扣减 —— 只对当前持 lease 的 principal
+            // 生效(FleetLeaseManager 内部判),sync + never throws。双轴=weightedTokens(配额轴)+costMicroUsd($ 轴)。
             fleetLease?.recordSpend(currentPrincipal(), { weightedTokens, costMicroUsd: e.costMicroUsd ?? 0 });
             if (e.firstTokenMs !== undefined)
                 metrics.observe("brain_first_token_ms", e.firstTokenMs);
@@ -90,27 +157,75 @@ export function createTracer(metrics, costQuota, modelUsage, fleetUsage, fleetLe
             metrics.inc("tool_calls_total", { name: toolName(e.name), ok: String(e.ok) });
         }
         else if (e.kind === "task.degraded") {
+            // 1.40: a task was switched to a cheaper model (near-budget / rate_limit / breaker-open). Quality
+            // dropped → alert-worthy operational signal, by reason.
             metrics.inc("degraded_total", { reason: e.reason });
         }
         else if (e.kind === "prompt.assembled") {
+            // core 1.243(提示词主权批): who owned the constitution layer, per task. The
+            // steady state for EVERY service scenario is "core" (structural constitution — our providers all
+            // return role bases only). Anything else is worth eyes: "provider-assembled" = a pre-1.243-shaped
+            // provider tripped the migration guard (upgrade it); "replaced" = an explicit replaceAll opt-out
+            // (none exist in this repo today); "legacy" = a deprecated free-form `system` provider. Alert on
+            // `prompt_constitution_total{mode!="core"} > 0` — the "TOC lost its safety blocks and called it a
+            // config issue" failure class becomes a one-glance dashboard check.
             metrics.inc("prompt_constitution_total", { mode: e.constitution });
+            // [998]② durable half: record the whitelisted manifest for the run lifecycle to drain into a
+            // `prompt_assembled` event (turns/stream). register-gated (top-level runs only), sync, never persists here.
             promptManifests?.record(e.taskId, promptManifestRecordOf(e));
         }
         else if (e.kind === "config.assembled") {
+            // [1301]③:config catalog 观测半场——生效配置逐字段来源(default/spec/derived/host-declared+
+            // overrideReasons)随任务进 durable 事件日志(config_assembled),「谁设的 80」读帧不考古。
             const rec = configAssembledRecordOf(e);
             if (rec)
                 promptManifests?.recordConfig(e.taskId, rec);
         }
         else if (e.kind === "compaction.phase_timings") {
+            // codex F6: core 1.289's `compaction.phase_timings` fires on SUCCESS (per-phase timing telemetry) — it is
+            // NOT an outcome, so counting it into compaction_events_total would add a fake "phase_timings" failure
+            // outcome for every successful compaction (poisoning the "non-success outcomes" dashboard semantics
+            // documented below). Record the total duration on the existing observe face instead (the
+            // brain_call_latency_ms precedent); non-finite values are dropped (tracer never throws, never poisons).
+            // 三路复审修5 核查(workflow W5 报「histogram never」):duration 观测出口就在下一行(F6 起已在),
+            // event 契约(core trace.d.ts)带 `durationMs: number`,budget.test.ts 咬合断言 observe 只进
+            // compaction_duration_ms 不进失败计数器 —— W5 判 STALE,零改。per-phase 明细走 compacted 事件的
+            // phaseDurations(trace/project.ts compactedEventData)上 wire,不在 /metrics 重复开面(有界纪律)。
             const d = e.durationMs;
             if (typeof d === "number" && Number.isFinite(d))
                 metrics.observe("compaction_duration_ms", d);
         }
         else if (e.kind.startsWith("compaction.")) {
+            // core 1.257(压缩健康面): every NON-SUCCESS compaction outcome
+            // now emits a `compaction.*` trace frame (failed / mooted / blocked / noop / disabled / suppressed +
+            // the input_truncated disclosure and announce_dropped). Before these frames the only evidence of a
+            // failing compactor was `onError(phase:"compaction")` log lines — no aggregate, so "3 silent auto
+            // failures opened the breaker and manual verbs drain mooted" (the exact failure fingerprint)
+            // was invisible on a dashboard. Count by outcome+trigger: `compaction_events_total{outcome="failed"}`
+            // rising = the summarizer is failing; sustained `mooted`/`blocked` explains "202 → no compacted
+            // event" without log spelunking. Labels are bounded: 8 kinds × 3 triggers (frames without a trigger
+            // — noop/disabled/mooted/input_truncated/announce_dropped — label "none"). SUCCESS is deliberately
+            // not counted here: `compacted` is a TaskEvent riding the run stream, not a trace frame.
             metrics.inc("compaction_events_total", { outcome: e.kind.slice("compaction.".length), trigger: e.trigger ?? "none" });
         }
     };
 }
+/**
+ * [1469] side-query 记账 seam(codex R3 high:sideQuery 不走 core tracer——brain.stream 直调不发
+ * brain.call——createTracer 的四路 sink(costQuota/model_cost 指标/fleetUsage 批报/fleetLease 本地扣减)
+ * 全部旁路)。本 seam 与 createTracer 的 brain.call 臂**同语义**喂同一组 sink:weightedTokens 同式
+ * (tokens×quotaWeight,weight-at-burn 固化)、micro-USD 同轴。装配点与 createTracer 同一处(main.ts),
+ * 传同一组实例——两臂永不分家。
+ *
+ * 已知残差(codex R3 medium,记档):cost 源=core SideQueryResult.usage.cost.total(brain 层计价),
+ * OpenAI cache-heavy 输入按全价入账(tracer 的 e.costMicroUsd 是 cache-family-aware 价)——方向=多收
+ * (保守,绝不少收);根修=core 在 SideQueryResult 上回权威 costMicroUsd(已提货 core)。model 标签/
+ * weight 键用**路由身份 r.model**(池配置有界)非 servedModel(provider 上报,无界)。
+ */
+/** core `usage-accounting.cacheFamilyOf` 的私拷镜像(core exports map 只开 barrel,该函数未导出——
+ *  已提货 core barrel 导出,到货即换,normalizeAgentName 同款纪律)。逐字对拍源:
+ *  dist/core/runner/usage-accounting.js(override 别名 anthropic/openai + api 判 anthropic-messages/
+ *  bedrock-converse-stream)。undefined 入参(catalog 查不到)→ undefined,调用方走保守臂。 */
 export function cacheFamilyOfMirror(model) {
     if (!model)
         return undefined;
@@ -127,6 +242,10 @@ export function createSideQueryAccountant(metrics, costQuota, fleetUsage, fleetL
         const output = typeof r.usage?.output === "number" ? r.usage.output : 0;
         const cacheRead = typeof r.usage?.cacheRead === "number" ? r.usage.cacheRead : 0;
         const cacheWrite = typeof r.usage?.cacheWrite === "number" ? r.usage.cacheWrite : 0;
+        // codex R4 high:prompt tokens 必须按 cache family 折算(core promptTokensOf 同式)——Anthropic 族
+        // (input-excludes-cached)的 cache 命中几乎全部在 input 之外,不加 cacheRead/cacheWrite 就是配额轴
+        // 大幅少收(lease 可被 cache-heavy side query 绕穿)。family 未知(catalog 查不到)走**保守臂**
+        // (含 cache——OpenAI 族此臂多收,方向与 cost 残差一致:宁多勿少,记档同一条)。
         const promptTokens = r.family === "input-includes-cached" ? input : input + cacheRead + cacheWrite;
         const micro = Math.round((typeof r.usage?.cost?.total === "number" ? r.usage.cost.total : 0) * 1_000_000);
         if (micro > 0) {
@@ -138,15 +257,20 @@ export function createSideQueryAccountant(metrics, costQuota, fleetUsage, fleetL
         const qw = typeof qwRaw === "number" && Number.isFinite(qwRaw) && qwRaw > 0 ? qwRaw : 1;
         const weightedTokens = Math.round((promptTokens + output) * qw);
         if (weightedTokens > 0 || micro > 0) {
-            fleetUsage?.record(principal, r.model, "", { inputTokens: promptTokens, outputTokens: output, costMicroUsd: micro, weightedTokens, quotaWeightAtUse: qw });
+            fleetUsage?.record(principal, r.model, "", { inputTokens: promptTokens, outputTokens: output, costMicroUsd: micro, weightedTokens, quotaWeightAtUse: qw }); // taskId ""(无 run 语义;accumulator 对 "" 不计 runsSeen);inputTokens=归一化总输入含 cache(fleet-bus 同口径)
             fleetLease?.recordSpend(principal, { weightedTokens, costMicroUsd: micro });
         }
     };
 }
+/**
+ * ⑤ Resolve a per-task budget: honor the caller's requested value but never let it EXCEED the operator
+ * ceiling. `0`/unset ceiling = no limit (returns the caller's value, or undefined). A non-positive /
+ * non-numeric request is ignored (falls back to the ceiling). Returns undefined = "no budget gate".
+ */
 export function cappedCeiling(requested, ceiling) {
     const req = typeof requested === "number" && requested > 0 ? requested : undefined;
     if (!ceiling || ceiling <= 0)
-        return req;
-    return req === undefined ? ceiling : Math.min(req, ceiling);
+        return req; // no operator ceiling → honor caller (or none)
+    return req === undefined ? ceiling : Math.min(req, ceiling); // cap caller down to the ceiling
 }
 //# sourceMappingURL=budget.js.map

package/dist/capabilities/builtin-tools.d.ts

@@ -1,3 +1,6 @@
 import type { ToolSpec } from "@sema-agent/core";
+/** Current time — the model has no clock; OA/most tasks need it. No side effects. CC-parity tool name `Now`
+ *  (PascalCase, core 1.176 first-party rename wrap-up — the SERVICE owns this one; `nowTool` is not a core tool).
+ *  effect:"read" so it never suspends → no durable-resume rename strand (no pending-tool checkpoint to canonicalize). */
 export declare function nowTool(): ToolSpec;
 //# sourceMappingURL=builtin-tools.d.ts.map

package/dist/capabilities/builtin-tools.js

@@ -1,4 +1,7 @@
 import { Type } from "typebox";
+/** Current time — the model has no clock; OA/most tasks need it. No side effects. CC-parity tool name `Now`
+ *  (PascalCase, core 1.176 first-party rename wrap-up — the SERVICE owns this one; `nowTool` is not a core tool).
+ *  effect:"read" so it never suspends → no durable-resume rename strand (no pending-tool checkpoint to canonicalize). */
 export function nowTool() {
     return {
         name: "Now",

package/dist/capabilities/center-plugins.d.ts

@@ -1,6 +1,8 @@
 import type { Logger } from "../observability/logger.js";
 import { type LoadedSkill } from "./skills.js";
+/** 缺省 clone host 白名单(契约条款 1;国内镜像走本名单加 https 镜像域,不开 http 口)。 */
 export declare const DEFAULT_PLUGIN_ALLOW_HOSTS: readonly string[];
+/** wire 上的插件声明(registry-core PluginSpec 的宽读形——本模块只消费不裁决,未知键忽略)。 */
 export interface PluginDeclWire {
     name?: unknown;
     source?: {
@@ -17,13 +19,17 @@ export type PluginValidation = {
     name: string;
     url: string;
     sha?: string;
-} | {
+}
+/** skip=true:不装但不算失败(enabled:false / marketplace 形 v1 暂缓);skip 缺席 = 真失败(计入 failures)。 */
+ | {
     ok: false;
     skip?: true;
     name: string;
     reason: string;
 };
+/** 条款 1/2/4:https-only、host 全等白名单、sha 40hex。纯函数,worker 侧纵深复验(不信任 wire 已验过)。 */
 export declare function validatePluginDecl(decl: PluginDeclWire, allowHosts: readonly string[]): PluginValidation;
+/** 条款 3/5:clone 计划(argv 序列 + 隔离 env)。纯数据,让"姿势"可被钉死。 */
 export declare function gitClonePlan(o: {
     url: string;
     dest: string;
@@ -32,6 +38,9 @@ export declare function gitClonePlan(o: {
     steps: string[][];
     env: Record<string, string>;
 };
+/** 条款 5 的 manifest 半场:`.claude-plugin/plugin.json` 的 `skillsPath`(缺省 `skills/`;cli plugin
+ *  布局同族)。返回 ok:true+dir:undefined = 插件没有 skills 目录(可以只有 commands——那是 cli 壳的
+ *  半场,worker 装 0 个 skill 不算失败);ok:false = 路径逃逸,整条拒装。 */
 export declare function resolvePluginSkillsRoot(cloneRoot: string): {
     ok: true;
     dir?: string;
@@ -41,22 +50,29 @@ export declare function resolvePluginSkillsRoot(cloneRoot: string): {
 };
 export interface ApplyPluginsResult {
     skills: LoadedSkill[];
+    /** 真失败(validate 拒/clone 失败且无 LKG/装载抛):单条不连坐,逐条留痕。 */
     failures: Array<{
         plugin: string;
         reason: string;
     }>;
+    /** 撞名让位名单(收紧④)。 */
     letGo: Array<{
         plugin: string;
         skill: string;
     }>;
+    /** 本轮拉取失败、沿用上次成功物化的插件名。 */
     lkgUsed: string[];
 }
+/** 总入口(条款 3/7/8):逐条物化 + 装载 + 让位合并。materialize 盘位 = `<cacheRoot>/<name>/live`
+ *  (成功后原子 rename 替换,失败保留旧盘位 = LKG)。 */
 export declare function applyCenterPlugins(baseline: LoadedSkill[], eff: {
     plugins?: unknown;
 }, opts: {
     cacheRoot: string;
     allowHosts: readonly string[];
     logger?: Logger;
+    /** 测试口:跳过 validate(materialize 只接受已验声明;真 git 腿用本地 bare repo,validate 层的
+     *  https-only 单独测——两层分开,谁也不掩护谁)。生产恒 false/缺席。 */
     skipValidate?: boolean;
     runGit?: (args: string[], env: Record<string, string>) => Promise<void>;
 }): Promise<ApplyPluginsResult>;