@sema-agent/server 1.322.0 → 2.0.0

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>;

package/dist/capabilities/center-plugins.js

@@ -1,16 +1,41 @@
+/**
+ * plugins 域 worker 消费半场(契约冻结 board [1361]②/[1362] 四收紧/[1366]①;2026-07-28 开工车)。
+ *
+ * center 只存"插件从哪来"(PluginSpec 引用,永不承载可执行字节);worker 半场 = 把引用物化成本地
+ * 目录并把其中的 **skills** 装进 baseline(v1 装载面;commands 由 cli 壳消费——board [1363] 即 cli
+ * 答的命令契约稿,worker 侧本无命令面,这是分工不是降级)。挂 applyCenterSkills 同 reconcile 周期
+ * (boot 期,buildScenarios 之前)。
+ *
+ * 契约条款落点(与 test/center-plugins.test.ts 逐条对应):
+ *  - https-only + `PLUGINS_ALLOW_HOSTS`(缺省 github.com):{@link validatePluginDecl}。registry-core
+ *    0.10.23 已在 schema 层单真源拒非 https,worker 侧**仍复验**——纵深:wire 可能来自旧 center。
+ *  - sha 全 40hex + checkout 强制:{@link gitClonePlan}(有 sha = init+fetch-by-sha+checkout,不信
+ *    分支名也不拉全史;无 sha = `--depth 1` HEAD)。
+ *  - clone 姿势隔离:GIT_CONFIG_GLOBAL/SYSTEM=/dev/null + GIT_TERMINAL_PROMPT=0(无凭据仓 fail 而非
+ *    挂交互 prompt)。私仓凭据走各机自己的 credential helper,永不入声明。
+ *  - manifest 路径逃逸(../ /绝对路径/symlink 出根)= 整条拒装:{@link resolvePluginSkillsRoot}
+ *    (realpath 后前缀判定)。
+ *  - 撞名让位(收紧④):plugin 的 skill 与 baseline(builtin/center 直发)同名 ⇒ **plugin 让位**
+ *    (跳过+letGo 留痕)。⚠️ 方向与 applyCenterSkills 的 center-wins 相反——center 直发 skills 过了
+ *    publisher RBAC+发布审批,plugin 内容只是 git 仓字节,信任级不同,让位方向因此相反。
+ *  - fail-loud 单条不连坐 + LKG(上次成功物化留盘,拉取失败沿用):{@link applyCenterPlugins}。
+ */
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { promises as fsp, realpathSync, existsSync, readFileSync } from "node:fs";
 import { join, resolve, isAbsolute, sep } from "node:path";
 import { loadSkills } from "./skills.js";
 const execFileP = promisify(execFile);
+/** 缺省 clone host 白名单(契约条款 1;国内镜像走本名单加 https 镜像域,不开 http 口)。 */
 export const DEFAULT_PLUGIN_ALLOW_HOSTS = ["github.com"];
+/** 条款 1/2/4:https-only、host 全等白名单、sha 40hex。纯函数,worker 侧纵深复验(不信任 wire 已验过)。 */
 export function validatePluginDecl(decl, allowHosts) {
     const name = typeof decl.name === "string" && decl.name !== "" ? decl.name : "(unnamed)";
     if (decl.enabled === false)
         return { ok: false, skip: true, name, reason: "enabled:false" };
     const kind = decl.source?.kind;
     if (kind === "marketplace") {
+        // v1 暂缓:marketplace 物化(add-by-url + install-by-name)是 v2 面;skip 不连坐,warn 留痕。
         return { ok: false, skip: true, name, reason: "marketplace source: not materialized in v1 (skills lane ships git-form first)" };
     }
     if (kind !== "git")
@@ -26,6 +51,7 @@ export function validatePluginDecl(decl, allowHosts) {
     catch {
         return { ok: false, name, reason: "https url does not parse" };
     }
+    // host 全等匹配——evil-github.com / github.com.evil.io 都不隐含放行。
     if (!allowHosts.some((h) => h.toLowerCase() === host)) {
         return { ok: false, name, reason: `host ${host} not in PLUGINS_ALLOW_HOSTS (default github.com; extend with a comma-separated https mirror domain list)` };
     }
@@ -37,15 +63,17 @@ export function validatePluginDecl(decl, allowHosts) {
     }
     return { ok: true, name, url };
 }
+/** 条款 3/5:clone 计划(argv 序列 + 隔离 env)。纯数据,让"姿势"可被钉死。 */
 export function gitClonePlan(o) {
     const env = {
-        GIT_CONFIG_GLOBAL: "/dev/null",
+        GIT_CONFIG_GLOBAL: "/dev/null", // 收紧③:宿主 git 配置(insteadOf/credential/hooks)一概不继承
         GIT_CONFIG_SYSTEM: "/dev/null",
-        GIT_TERMINAL_PROMPT: "0",
+        GIT_TERMINAL_PROMPT: "0", // 无凭据仓 ⇒ fail-loud,绝不挂在交互 prompt 上
     };
     if (o.sha === undefined) {
         return { steps: [["clone", "--depth", "1", "--quiet", o.url, o.dest]], env };
     }
+    // 有 sha:init + fetch-by-sha + checkout —— 不信分支名、不拉全史;fetch 不到该 sha = 该条失败。
     return {
         steps: [
             ["init", "--quiet", o.dest],
@@ -55,6 +83,9 @@ export function gitClonePlan(o) {
         env,
     };
 }
+/** 条款 5 的 manifest 半场:`.claude-plugin/plugin.json` 的 `skillsPath`(缺省 `skills/`;cli plugin
+ *  布局同族)。返回 ok:true+dir:undefined = 插件没有 skills 目录(可以只有 commands——那是 cli 壳的
+ *  半场,worker 装 0 个 skill 不算失败);ok:false = 路径逃逸,整条拒装。 */
 export function resolvePluginSkillsRoot(cloneRoot) {
     let skillsPath = "skills";
     try {
@@ -63,22 +94,27 @@ export function resolvePluginSkillsRoot(cloneRoot) {
             skillsPath = manifest.skillsPath;
     }
     catch {
+        /* 无 manifest / 坏 JSON ⇒ 缺省 skills/(manifest 是可选面) */
     }
     if (isAbsolute(skillsPath))
         return { ok: false, reason: `skillsPath must be relative (got ${skillsPath})` };
     const rootReal = realpathSync(cloneRoot);
     const candidate = resolve(rootReal, skillsPath);
+    // 先做词法前缀判定(../ 逃逸在 realpath 之前就拒——目标可能不存在)
     if (candidate !== rootReal && !candidate.startsWith(rootReal + sep)) {
         return { ok: false, reason: `skillsPath escapes the plugin root (${skillsPath})` };
     }
     if (!existsSync(candidate))
         return { ok: true };
+    // symlink 出根:对存在的目标 realpath 再判一次
     const real = realpathSync(candidate);
     if (real !== rootReal && !real.startsWith(rootReal + sep)) {
         return { ok: false, reason: `skillsPath resolves outside the plugin root via symlink (${skillsPath})` };
     }
     return { ok: true, dir: candidate };
 }
+/** 总入口(条款 3/7/8):逐条物化 + 装载 + 让位合并。materialize 盘位 = `<cacheRoot>/<name>/live`
+ *  (成功后原子 rename 替换,失败保留旧盘位 = LKG)。 */
 export async function applyCenterPlugins(baseline, eff, opts) {
     const declared = Array.isArray(eff.plugins)
         ? (eff.plugins)
@@ -91,7 +127,7 @@ export async function applyCenterPlugins(baseline, eff, opts) {
     const runGit = opts.runGit ?? (async (args, env) => {
         await execFileP("git", args, { env: { ...process.env, ...env }, timeout: 120_000, maxBuffer: 4 * 1024 * 1024 });
     });
-    const taken = new Set(baseline.map((s) => s.spec.name));
+    const taken = new Set(baseline.map((s) => s.spec.name)); // 让位判据:baseline(builtin+center 直发)恒赢
     for (const decl of declared) {
         const v = opts.skipValidate
             ? { ok: true, name: String(decl.name), url: String(decl.source?.url), ...(typeof decl.sha === "string" ? { sha: decl.sha } : {}) }
@@ -106,12 +142,14 @@ export async function applyCenterPlugins(baseline, eff, opts) {
             continue;
         }
         const liveDir = join(opts.cacheRoot, v.name, "live");
+        // ── 物化:clone 到 staging,成功后原子替换 live;失败保留旧 live = LKG ──
         const staging = join(opts.cacheRoot, v.name, `staging-${process.pid}`);
         let materialized = false;
         try {
             await fsp.rm(staging, { recursive: true, force: true });
             await fsp.mkdir(staging, { recursive: true });
             const plan = gitClonePlan({ url: v.url, dest: staging, sha: v.sha });
+            // clone 目标目录已建:单步 clone 允许空目录;init 形对空目录同样成立。
             for (const step of plan.steps)
                 await runGit(step, plan.env);
             await fsp.rm(liveDir, { recursive: true, force: true });
@@ -122,6 +160,7 @@ export async function applyCenterPlugins(baseline, eff, opts) {
         catch (err) {
             await fsp.rm(staging, { recursive: true, force: true }).catch(() => undefined);
             if (existsSync(liveDir)) {
+                // LKG:拉取失败沿用上次成功物化(applyCenterSkills 同款语义)。
                 opts.logger?.warn("center_plugin_fetch_failed_lkg", { plugin: v.name, error: err instanceof Error ? err.message : String(err) });
                 out.lkgUsed.push(v.name);
             }
@@ -131,6 +170,7 @@ export async function applyCenterPlugins(baseline, eff, opts) {
                 continue;
             }
         }
+        // ── 装载:skills 目录(路径逃逸=整条拒装;fail-loud 单条不连坐)──
         try {
             const rootCheck = resolvePluginSkillsRoot(liveDir);
             if (!rootCheck.ok) {
@@ -139,10 +179,11 @@ export async function applyCenterPlugins(baseline, eff, opts) {
                 continue;
             }
             if (!rootCheck.dir)
-                continue;
+                continue; // 无 skills 目录:合法(commands-only 插件,cli 壳的半场)
             const loaded = loadSkills(rootCheck.dir);
             for (const skill of loaded) {
                 if (taken.has(skill.spec.name)) {
+                    // 收紧④:plugin 让位(方向与 center-wins 相反,理由见模块顶注)。
                     out.letGo.push({ plugin: v.name, skill: skill.spec.name });
                     opts.logger?.warn("center_plugin_skill_shadowed", { plugin: v.name, skill: skill.spec.name, note: "name taken by builtin/center skill — plugin yields (contract tightening-4)" });
                     continue;