@sema-agent/server 3.24.0 → 4.0.0

package/dist/bench/s1/run-firm.js

@@ -285,7 +285,7 @@ function dryRunMockFactory() {
             runWithVerification: async () => vr,
             runWithVerificationSup: async () => vr,
             resumeWithVerification: async () => vr,
-            runRepairLoop: async () => ({ ...vr, terminal: "candidate_only", bundle: { failureTrace: "", diagnostics: [], rejectedHypotheses: [], attemptCount: 1, oracleTier: "trusted_hidden" } }),
+            runRepairLoop: async () => ({ ...vr, terminal: "candidate_only", oracleCostMicroUsd: 0, bundle: { failureTrace: "", diagnostics: [], rejectedHypotheses: [], attemptCount: 1, oracleTier: "trusted_hidden" } }),
             getCheckpoint: async () => null,
             runLeaderTask: async () => ({ ok: true, reports: [], merge: undefined, workerBudgetsUsd: [0.5, 0.5] }),
             runOracle: async () => oracle,

package/dist/budget.d.ts

@@ -46,6 +46,12 @@ export interface ModelUsageDelta {
      *  = 运营者声明免费 ⇒ 键在场且为 0。两者可区分,这正是 #59 折零案的源头修复。
      *  与 SDK `ModelUsageDelta`(五键全可选)/ `usage-analytics.UsageModelEntry` 同轨。 */
     costMicroUsd?: number;
+    /** core 3.0.0([2296] 装车单 S10,§DESIGN-V2 V2-⑤)可选口径标记:标出这一行的 token 分量是在哪套记账
+     *  基准下写的(当前唯一值 = `"uncached-components-v1"`:`inputTokens` = cache-MISS 分量,`cacheRead`/
+     *  `cacheWrite` 分列)。**写点在 `trace/project.ts` 的 durable 行构造处**(`appendModelUsageDelta`),
+     *  不在这里 —— {@link ModelUsageTracker.record} 的累加逻辑本身零改动,永远不设置这个键(它只在 drain
+     *  之后、落盘之前被打上)。缺席 = 落盘更早、口径未知的存量行(usage-analytics 读端据此诚实标注)。 */
+    usageBasis?: string;
 }
 /**
  * E8 (shell-host contract): per-task × per-model usage accumulator, fed (synchronously) by the `brain.call`

package/dist/budget.js

@@ -206,16 +206,29 @@ export function createTracer(metrics, costQuota, modelUsage, fleetUsage, fleetLe
             // 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.
+            // core 3.0.0([2296] S1):this lane's `inputTokens` stays `e.promptTokens` — DELIBERATELY zero-changed.
+            // The E8 ledger's semantics are COMPONENT-wise (MISS + cacheRead/cacheWrite listed separately;
+            // usage-analytics' read side SUMS them back into a total), unlike the weightedTokens/fleetUsage lane just
+            // below (which wants the pre-summed normalized total and migrates to `e.totalInputTokens`). Pre-3.0.0 the
+            // gateway family's `promptTokens` already included cache, so this same read-side sum double-counted for
+            // that family — an existing accounting gap in historical rows that this version does not retroactively fix
+            // (declared, not silently carried forward): see CHANGELOG's "存量口径断层" note.
             modelUsage?.record(e.taskId, e.model, { inputTokens: e.promptTokens, outputTokens: e.completionTokens, cacheReadTokens: e.cacheRead, cacheWriteTokens: e.cacheWrite, ...(e.costMicroUsd !== undefined ? { costMicroUsd: e.costMicroUsd } : {}) }); // RB-368 透传缺席
             // weight-at-burn:加权 tokens = (prompt+completion)×模型配额倍率,在记账点固化(此后改倍率
             // 不回算历史,registry ModelEntry.quotaWeight 同句契约)。weight 源=config.modelQuotaWeights(registry
             // hot-apply;env lane 空表 ⇒ 1 兜底);非法回调值防御性归 1(tracer 契约 never-throws,不让坏表毒记账)。
+            // core 3.0.0([2296] S1):`e.promptTokens` → `e.totalInputTokens`. This axis's contract (line ~365 below)
+            // has always been "normalized total input INCLUDING cache" — pre-3.0.0 that's what `promptTokens` meant for
+            // the gateway family; 3.0.0 flips `promptTokens` to mean cache-MISS-only, so staying on it here would
+            // massively under-count the quota/lease axis for any cache-heavy load (a lease could be walked through by
+            // cache-heavy traffic — the exact same failure class as the side-query R4 finding below).
             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);
+            const weightedTokens = Math.round((e.totalInputTokens + 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, ...(e.costMicroUsd !== undefined ? { costMicroUsd: e.costMicroUsd } : {}), weightedTokens, quotaWeightAtUse: qw }); // RB-368 透传缺席
+            // core 3.0.0:同上迁移理由,inputTokens=归一化总输入含 cache(totalInputTokens),与 weightedTokens 同轴。
+            fleetUsage?.record(currentPrincipal(), e.model, e.taskId, { inputTokens: e.totalInputTokens, outputTokens: e.completionTokens, ...(e.costMicroUsd !== undefined ? { costMicroUsd: e.costMicroUsd } : {}), weightedTokens, quotaWeightAtUse: qw }); // RB-368 透传缺席
             // lease 消费(D4 AP):同一 ALS 归因点做 lease 本地扣减 —— 只对当前持 lease 的 principal
             // 生效(FleetLeaseManager 内部判),sync + never throws。双轴=weightedTokens(配额轴)+costMicroUsd($ 轴)。
             fleetLease?.recordSpend(currentPrincipal(), { weightedTokens, ...(e.costMicroUsd !== undefined ? { costMicroUsd: e.costMicroUsd } : {}) }); // RB-368 透传缺席
@@ -332,6 +345,9 @@ fleetUsage, fleetLease, quotaWeightFor) {
         // (input-excludes-cached)的 cache 命中几乎全部在 input 之外,不加 cacheRead/cacheWrite 就是配额轴
         // 大幅少收(lease 可被 cache-heavy side query 绕穿)。family 未知(catalog 查不到)走**保守臂**
         // (含 cache——OpenAI 族此臂多收,方向与 cost 残差一致:宁多勿少,记档同一条)。
+        // core 3.0.0 核实(S1 提货站):此段的输入源是 `SideQueryResult.usage`(llm 层生料 `Usage`,
+        // engine/llm/types.d.ts)——不是 3.0.0 翻新过的 `brain.call`/`turn_end` trace 事件面,3.0.0 未动这个类型,
+        // 本折算继续承重(零改动)。
         const promptTokens = r.family === "input-includes-cached" ? input : input + cacheRead + cacheWrite;
         // RB-368/#59 同判据(createTracer 上方注释同款纪律):`usage.cost.total` 整键缺席 = 未知(unpriced 部署的
         // side query 真形),不是「花了 $0」——折 0 就是把「不知道」编造成「免费」。已知(哪怕显式 0)才带键。

package/dist/config.js

@@ -514,8 +514,10 @@ function parseModelDomain() {
     }
     // Model.api must reflect the brain that actually serves it (routing is by provider): an "anthropic"
     // provider runs the Anthropic brain, whose usage reports `input` EXCLUDING cached tokens. core ≥1.22
-    // normalizes the cache-hit-rate denominator per api family — a wrong api makes promptTokens too small
-    // and cacheHitRate exceed 100%. (Brains select by provider, not api, so this only fixes accounting.)
+    // normalizes the cache-hit-rate denominator per api family (`cacheFamilyOf` picks the fold formula from
+    // `Model.api`) — a wrong api picks the wrong family, so the normalized total (core 3.0.0: `totalInputTokens`,
+    // core's own cacheHitRate = cachedTokens/totalInputTokens) comes out too small and cacheHitRate exceeds
+    // 100%. (Brains select by provider, not api, so this only fixes accounting.)
     //
     // Default inference ([792]④, core ruling 2026-07-14): an EXPLICIT MODEL_PROVIDER always wins (unchanged).
     // When it is unset but the operator explicitly configured an Anthropic-protocol base URL AND a matching

package/dist/fleet/fleet-bus.js

@@ -222,13 +222,16 @@ export function fleetRunPublisher(bus, run) {
             return 0;
         if (typeof u.totalTokens === "number")
             return u.totalTokens;
-        // #9 (workflow 2nd-pass re-review): a turn_end.usage has NO totalTokens → this field-sum. core's turn_end.inputTokens
-        // is the NORMALIZED TOTAL INPUT *INCLUDING CACHE* (usage-accounting promptTokensOf — input + cacheRead + cacheWrite
-        // for the Anthropic family; OpenAI already folds cacheRead into input). So inputTokens + outputTokens ALREADY is the
-        // turn total — the old code ALSO added cacheRead/cacheWrite, double-counting them (~2x with prompt caching, the
-        // normal case). Display-only (the leader fleet-row token number); billing (costMicroUsd) + context/compaction use
-        // totalTokens and were never affected; child rows use task_progress.usage.totalTokens (the early-return) — correct.
-        return (u.inputTokens ?? 0) + (u.outputTokens ?? 0);
+        // core 3.0.0([2296] 装车单 S2, [2298] R#9 二次复审并入):`turn_end.usage.inputTokens` 的语义在 3.0.0
+        // **翻转**——此前(core ≤2.x)它是 NORMALIZED TOTAL INPUT *INCLUDING CACHE*(usage-accounting
+        // promptTokensOf:Anthropic 族 = input+cacheRead+cacheWrite,OpenAI 族已把 cache 折进 input),本函数当时
+        // 直接 `inputTokens + outputTokens` 就是整轮总量;3.0.0 起 `inputTokens` 恒为 cache-MISS 分量,新必填的
+        // `totalInputTokens` 才是那个「含 cache 的归一化总量」(旧 inputTokens 语义的正统继承者)。继续只加
+        // `inputTokens` 会在有 cache 命中时**漏计**(leader 行的展示 token 数偏低)——故总量优先取
+        // `totalInputTokens`,旧核帧(尚未升级到 3.0.0、该键缺席)回落 `inputTokens`(防御性:本引擎恒 ≥3.0.0
+        // 时两键并存;异常帧宁少算不 NaN)。Display-only(leader fleet 行的 token 数);billing(costMicroUsd)+
+        // context/compaction 走 totalTokens,不受影响;child 行走 task_progress.usage.totalTokens(上面的早退臂)。
+        return (u.totalInputTokens ?? u.inputTokens ?? 0) + (u.outputTokens ?? 0);
     };
     return {
         onStart() {

package/dist/fleet-client.d.ts

@@ -31,6 +31,10 @@ export declare class FleetUsageAccumulator {
      * 同款=**传染**(同为单 producer 累加器:已知+未知=未知);center 聚合面的「下界 + costUnknown
      * 标记」语义在 registry-core aggregateUsage(跨 worker 审计总账层,两层判据见 [2103])。
      * 配额轴(weightedTokens)不受影响,仍逐笔精确。
+     *
+     * core 3.0.0([2296] 装车单 S4c)语义注:`d.inputTokens` 在唯一调用点(budget.ts 的
+     * `fleetUsage.record(...)`,S1 已迁)传的是 `e.totalInputTokens`(归一化总输入含 cache),不是
+     * `e.promptTokens`(3.0.0 起恒 cache-MISS)——上游已切换口径,本函数只是照收不重算,值域/签名零改动。
      */
     record(principal: string | undefined, model: string, taskId: string, d: {
         inputTokens: number;

package/dist/fleet-client.js

@@ -31,6 +31,10 @@ export class FleetUsageAccumulator {
      * 同款=**传染**(同为单 producer 累加器:已知+未知=未知);center 聚合面的「下界 + costUnknown
      * 标记」语义在 registry-core aggregateUsage(跨 worker 审计总账层,两层判据见 [2103])。
      * 配额轴(weightedTokens)不受影响,仍逐笔精确。
+     *
+     * core 3.0.0([2296] 装车单 S4c)语义注:`d.inputTokens` 在唯一调用点(budget.ts 的
+     * `fleetUsage.record(...)`,S1 已迁)传的是 `e.totalInputTokens`(归一化总输入含 cache),不是
+     * `e.promptTokens`(3.0.0 起恒 cache-MISS)——上游已切换口径,本函数只是照收不重算,值域/签名零改动。
      */
     record(principal, model, taskId, d) {
         const p = principal ?? "__anonymous__"; // single-user turnkey: no principal — still meter, under a stable bucket

package/dist/observability/metrics.js

@@ -213,8 +213,13 @@ export function createMetrics() {
     m.counter("council_runs_total", "Code-review council runs (L1+L3)");
     m.histogram("council_tokens", "Total model tokens per council review (lenses + arbiter)");
     // Prefix-cache effectiveness (core 1.22): per-task hit rate (cost-critical) + a count of tasks the
-    // Runner flagged as low-hit (unstable/poisoned prefix) so it can be alerted on.
-    m.histogram("task_cache_hit_rate", "Prefix-cache hit rate per task (cachedTokens/promptTokens, 0..1)", [
+    // 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");

package/dist/plugins/remote-env-host.js

@@ -867,7 +867,8 @@ export class RemoteHostExecutionEnv {
             }
             catch (e) {
                 // 同步 spawn throw(如 cwd=文件的 ENOTDIR)——与管道旧形字节级对齐:executor 内 re-throw=Promise
-                // reject(消费方契约:core pruneWorktrees 等 await 抛才算失败;吞成 Result err 会让 reap 静默)。
+                // reject(消费方按 await 抛感知传输层失败;吞成 Result err 会让上层静默。⚠️ 引例更新:core 3.0.0
+                // 起 pruneWorktrees 改回执形 {ok},其消费点已双臂消费——worktree-isolation.ts;本处 spawn 层契约不变)。
                 closeSpoolFds();
                 cleanupSpool();
                 throw e;

package/dist/plugins/worktree-isolation.js

@@ -227,7 +227,12 @@ export async function reapOrphanWorktrees(baseEnvForGit, repoRoot, logger) {
     try {
         // #62:prune 动的是与 add/remove 同一张 `.git/worktrees` 注册表 ⇒ 必须过同一把 per-repoRoot 锁
         // (曾绕锁直跑;恶劣臂见 serializeGitAdmin 注)。
-        await serializeGitAdmin(repoRoot, () => pruneWorktrees(baseEnvForGit, norm(repoRoot)));
+        // core 3.0.0(#94 提货):pruneWorktrees 从「失败 throw」改为回执 `{ok:true}|{ok:false,detail}`——
+        // 只靠下面的 catch 发警在 3.0.0 下= prune 失败**静默化**(CI svc3 钉抓出)。回执臂与 throw 臂
+        // (serializeGitAdmin/env 传输层仍可抛)两路都进同一条 warn,判据不变:失败必须留痕。
+        const r = await serializeGitAdmin(repoRoot, () => pruneWorktrees(baseEnvForGit, norm(repoRoot)));
+        if (r.ok === false)
+            logger?.warn?.("worktree_prune_failed", { repoRoot: norm(repoRoot), error: r.detail });
     }
     catch (e) {
         logger?.warn?.("worktree_prune_failed", { repoRoot: norm(repoRoot), error: e instanceof Error ? e.message : String(e) });

package/dist/trace/project.d.ts

@@ -19,7 +19,13 @@ type AppendFn = (type: string, data: unknown) => Promise<void>;
 type GetEventsFn = (taskId: string, afterSeq: number) => Promise<RunEvent[]>;
 /** E8 (shell-host): drain the per-task model-usage accumulator into an append-only `model_usage` DELTA event.
  *  Shared by BOTH durable-write legs (runInBackground + the resume leg) so the persisted shape never drifts; the
- *  append-only deltas make a suspended/resumed run's total resume-safe (each leg appends its own, the echo sums). */
+ *  append-only deltas make a suspended/resumed run's total resume-safe (each leg appends its own, the echo sums).
+ *
+ *  core 3.0.0([2296] 装车单 S10,§DESIGN-V2 V2-⑤): every drained row is tagged with `usageBasis:
+ *  "uncached-components-v1"` — the write point for this label (the tracker itself, {@link ModelUsageTracker},
+ *  never sets it; it stays a pure token/cost accumulator). This is what lets {@link aggregateModelUsage} tell
+ *  apart rows written under the current component semantics from older rows (pre-dating this label) when it
+ *  sums across a run's whole event log. */
 export declare function appendModelUsageDelta(append: AppendFn, modelUsage: ModelUsageTracker | undefined, taskId: string): Promise<void>;
 /** [998]② drain the pending prompt-manifest records (whitelisted at RECORD time, budget.ts — ids/digests/
  *  counts only, no prompt bodies by core's manifest contract) into durable `prompt_assembled` events, one per
@@ -287,9 +293,15 @@ export interface TraceTurn {
     ts: string;
     role: "system" | "user" | "assistant" | "tool";
     blocks: TraceBlock[];
+    /** core 3.0.0([2296] 装车单 S3,§DESIGN-V2 V2-②):这是**本服务自有的投影契约**,不是 core wire 帧的
+     *  verbatim 转发——`in` 刻意保持它历史上的「总量」语义不变(旧帧/新帧读端零伤),不随 core 的
+     *  `promptTokens`/`turn_end.usage.inputTokens` 翻转为 cache-MISS。新增 `uncachedIn` 承接 core 3.0.0 才有的
+     *  cache-MISS 分量(命名取自 core `uncachedInputTokensOf`),只在能确认自己踩在新契约帧上时才发
+     *  (见 {@link toContractTokens})。 */
     tokens?: {
         in: number;
         out: number;
+        uncachedIn?: number;
         cacheRead?: number;
         cacheWrite?: number;
     };
@@ -326,7 +338,14 @@ export declare function turnEndEventData(ev: {
     stopReason?: string;
 }): Record<string, unknown>;
 /** Map core's `turn_end.usage` (1.76 / core [R59]: inputTokens/outputTokens/cacheReadTokens/cacheWriteTokens/
- *  costMicroUsd) → the contract's `TraceTurn.tokens {in,out,cacheRead?,cacheWrite?}`. Absent/empty → undefined. */
+ *  costMicroUsd; core 3.0.0 adds required `totalInputTokens`) → the contract's `TraceTurn.tokens`.
+ *  Absent/empty → undefined.
+ *
+ *  core 3.0.0([2296] 装车单 S3,§DESIGN-V2 V2-②,codex 复审「异议」采纳):`TraceTurn.tokens` 是本服务自有
+ *  的投影契约,不是 wire verbatim——`in` 保持它一直以来的**总量**语义,3.0.0 起改取 `totalInputTokens`
+ *  (归一化总输入含 cache)优先,`inputTokens` 回落(旧帧/尚未升级的 core 下 `totalInputTokens` 缺席时,
+ *  `in` 落回旧值,读端零伤)。`uncachedIn` 只在**能确认自己踩在新契约帧上**(`totalInputTokens` 在场)时
+ *  才发——旧帧的 `inputTokens` 是族依赖的旧语义,标成「uncachedIn(cache-MISS)」会是谎言。 */
 export declare function toContractTokens(usage: unknown): TraceTurn["tokens"] | undefined;
 export interface ProjectOpts {
     /** Prepend the user turn (the objective is not in the event log; the endpoint supplies it). */

package/dist/trace/project.js

@@ -1,11 +1,21 @@
 import { redactSecrets, redactDeep } from "./redact.js";
 /** E8 (shell-host): drain the per-task model-usage accumulator into an append-only `model_usage` DELTA event.
  *  Shared by BOTH durable-write legs (runInBackground + the resume leg) so the persisted shape never drifts; the
- *  append-only deltas make a suspended/resumed run's total resume-safe (each leg appends its own, the echo sums). */
+ *  append-only deltas make a suspended/resumed run's total resume-safe (each leg appends its own, the echo sums).
+ *
+ *  core 3.0.0([2296] 装车单 S10,§DESIGN-V2 V2-⑤): every drained row is tagged with `usageBasis:
+ *  "uncached-components-v1"` — the write point for this label (the tracker itself, {@link ModelUsageTracker},
+ *  never sets it; it stays a pure token/cost accumulator). This is what lets {@link aggregateModelUsage} tell
+ *  apart rows written under the current component semantics from older rows (pre-dating this label) when it
+ *  sums across a run's whole event log. */
 export async function appendModelUsageDelta(append, modelUsage, taskId) {
     const delta = modelUsage?.drain(taskId);
-    if (delta)
-        await append("model_usage", { usage: delta });
+    if (delta) {
+        const tagged = {};
+        for (const [model, d] of Object.entries(delta))
+            tagged[model] = { ...d, usageBasis: "uncached-components-v1" };
+        await append("model_usage", { usage: tagged });
+    }
 }
 /** [998]② drain the pending prompt-manifest records (whitelisted at RECORD time, budget.ts — ids/digests/
  *  counts only, no prompt bodies by core's manifest contract) into durable `prompt_assembled` events, one per
@@ -61,6 +71,11 @@ export function aggregateModelUsage(events) {
     const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
     const total = {};
     const costUnknown = new Set(); // RB-368:该模型至少有一行没带 costMicroUsd 键 ⇒ 总量不可知
+    // S10([2296] 装车单,§DESIGN-V2 V2-⑤):usageBasis 只在**这个模型贡献的每一行**都带同一个值时才透传到
+    // 回声行——混窗(升级前落盘的旧行 / 坏行 / 未来换了别的 basis 字符串)一律诚实省略,不猜、不传染出一个
+    // 假的一致标记。Map 记「目前为止这个模型见过的一致值」:第一行定值;之后任何一行不同(含缺席,记作
+    // undefined)⇒ 永久锁定为 undefined(一旦分歧就回不去)。
+    const basisSeen = new Map();
     let any = false;
     for (const ev of events) {
         if (ev.type !== "model_usage")
@@ -74,6 +89,7 @@ export function aggregateModelUsage(events) {
             // 之后,对唯一能判别的形(null)先抛,守卫不可达;坏行按整行 0 折(#59 同口径),cost 记未知。
             if (d === null || typeof d !== "object") {
                 costUnknown.add(model);
+                basisSeen.set(model, undefined); // 坏行 = 不可知,视同分歧,不透传 basis
                 continue;
             }
             const cur = total[model] ?? { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, costMicroUsd: 0 };
@@ -87,11 +103,19 @@ export function aggregateModelUsage(events) {
                 cur.costMicroUsd = num(cur.costMicroUsd) + num(d.costMicroUsd);
             else
                 costUnknown.add(model);
+            const rowBasis = typeof d.usageBasis === "string" ? d.usageBasis : undefined;
+            if (!basisSeen.has(model))
+                basisSeen.set(model, rowBasis);
+            else if (basisSeen.get(model) !== rowBasis)
+                basisSeen.set(model, undefined);
             total[model] = cur;
         }
     }
     for (const model of costUnknown)
         delete total[model]?.costMicroUsd;
+    for (const [model, basis] of basisSeen)
+        if (basis !== undefined && total[model])
+            total[model].usageBasis = basis;
     return any ? total : undefined;
 }
 /** Identity fields core stamps on each content event (1.121.0 `TaskEventIdentity`, shell-host contract E2):
@@ -396,16 +420,24 @@ export function turnEndEventData(ev) {
     };
 }
 /** Map core's `turn_end.usage` (1.76 / core [R59]: inputTokens/outputTokens/cacheReadTokens/cacheWriteTokens/
- *  costMicroUsd) → the contract's `TraceTurn.tokens {in,out,cacheRead?,cacheWrite?}`. Absent/empty → undefined. */
+ *  costMicroUsd; core 3.0.0 adds required `totalInputTokens`) → the contract's `TraceTurn.tokens`.
+ *  Absent/empty → undefined.
+ *
+ *  core 3.0.0([2296] 装车单 S3,§DESIGN-V2 V2-②,codex 复审「异议」采纳):`TraceTurn.tokens` 是本服务自有
+ *  的投影契约,不是 wire verbatim——`in` 保持它一直以来的**总量**语义,3.0.0 起改取 `totalInputTokens`
+ *  (归一化总输入含 cache)优先,`inputTokens` 回落(旧帧/尚未升级的 core 下 `totalInputTokens` 缺席时,
+ *  `in` 落回旧值,读端零伤)。`uncachedIn` 只在**能确认自己踩在新契约帧上**(`totalInputTokens` 在场)时
+ *  才发——旧帧的 `inputTokens` 是族依赖的旧语义,标成「uncachedIn(cache-MISS)」会是谎言。 */
 export function toContractTokens(usage) {
     if (!usage || typeof usage !== "object")
         return undefined;
     const u = usage;
-    if (u.inputTokens == null && u.outputTokens == null)
+    if (u.inputTokens == null && u.totalInputTokens == null && u.outputTokens == null)
         return undefined;
     return {
-        in: u.inputTokens ?? 0,
+        in: u.totalInputTokens ?? u.inputTokens ?? 0,
         out: u.outputTokens ?? 0,
+        ...(u.totalInputTokens != null && u.inputTokens != null ? { uncachedIn: u.inputTokens } : {}),
         ...(u.cacheReadTokens != null ? { cacheRead: u.cacheReadTokens } : {}),
         ...(u.cacheWriteTokens != null ? { cacheWrite: u.cacheWriteTokens } : {}),
     };

package/dist/usage-analytics.d.ts

@@ -40,6 +40,10 @@ export interface UsageModelEntry {
     outputTokens?: number;
     cacheReadTokens?: number;
     cacheWriteTokens?: number;
+    /** S10(core 3.0 计量语义统一,§DESIGN-V2 V2-⑤)口径标记:`"uncached-components-v1"` = 三个输入键是
+     *  分量制(互不重叠,本文件的 tokensIn 求和公式正确)。缺席/别的值 = 口径不可分辨(存量行可能把
+     *  cache 计入 inputTokens,求和会双算)⇒ fold 侧标 {@link UsageTotals.estimated}。 */
+    usageBasis?: string;
     /** 整数 micro-USD。**缺席 = 未知**,不是 0(SDK `ModelUsageDelta` 同款单轨契约)。注意在场的 `0` 仍有
      *  歧义(引擎无价目表时恒发 0),那层消歧在部署面 `capabilities.pricingConfigured`——裁定见 budget.ts。 */
     costMicroUsd?: number;
@@ -49,9 +53,11 @@ export interface UsageTotals {
     tokensIn: number;
     tokensOut: number;
     costUsd: number;
-    /** 本聚合的口径**不完整**——两种来源:①有行走了 stats.tokens fallback(无 per-model echo,token 数为估算);
-     *  ②有 per-model echo 行**缺数值键**(该键按 0 计入,总量偏低;成本键缺席时尤其:少算 ≠ 免费)。
-     *  两者都只表达「别把这个总数当精确值」,消费端一视同仁。 */
+    /** 本聚合的口径**不完整**——三种来源:①有行走了 stats.tokens fallback(无 per-model echo,token 数为估算);
+     *  ②有 per-model echo 行**缺数值键**(该键按 0 计入,总量偏低;成本键缺席时尤其:少算 ≠ 免费);
+     *  ③(S10/V2-⑤)有行的 {@link UsageModelEntry.usageBasis} 缺席或非本读端认识的分量制——存量行某族
+     *  历史上把 cache 计入 inputTokens,tokensIn 求和会**双算**,口径不可分辨。
+     *  三者都只表达「别把这个总数当精确值」,消费端一视同仁。 */
     estimated: boolean;
 }
 /** GET /v1/usage/summary — 窗内总量。 */

package/dist/usage-analytics.js

@@ -36,6 +36,10 @@ function foldModelEntry(t, d) {
     t.costUsd += (cost ?? 0) / 1e6;
     if (input === undefined || output === undefined || cacheRead === undefined || cacheWrite === undefined || cost === undefined)
         t.estimated = true;
+    // S10/V2-⑤:上面这条 tokensIn 求和公式只在「分量制」行上正确。缺标记(存量行,某族历史上 inputTokens
+    // 含 cache ⇒ 双算)或本读端不认识的标记值(将来别的口径)⇒ 走既有不精确通道,不显示为精确值。
+    if (d.usageBasis !== "uncached-components-v1")
+        t.estimated = true;
 }
 function foldRow(t, row) {
     t.tasks += 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "3.24.0",
+  "version": "4.0.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -54,7 +54,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "^2.13.0",
+    "@sema-agent/core": "^3.0.0",
     "@sema-agent/registry-core": "^0.12.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",