@sema-agent/server 3.5.1 → 3.5.3

package/dist/budget.js

@@ -131,6 +131,31 @@ export function createTracer(metrics, costQuota, modelUsage, fleetUsage, fleetLe
                 if (principal)
                     costQuota?.add(principal, e.costMicroUsd);
             }
+            // ┌─ #59 裁定([2052]① cli 报案 → 黑板 [2073] 立案;本块是该工单的落点,勿删) ─────────────────┐
+            // 病灶报案:下面三处 `e.costMicroUsd ?? 0`(本行 + fleetUsage + fleetLease)把「成本未知」记成
+            // 「免费」,与 `pricingConfigured=false` 的部署组合 ⇒ 全部账目假 0。
+            //
+            // 亲读上游后的**事实纠偏**:core 在 brain.call 帧上**恒发数字、从不缺席**——
+            //   runtask.ts `usageCostMicroUsd(...)` 返回 `number`(内部 `computeCostMicroUsd` 恒返回 number),
+            //   帧上 `costMicroUsd: turnCostMicroUsd` 是**无条件**键;无价目表时 `modelCostToPricing(undefined)`
+            //   产出全零单价 ⇒ 每次调用如实算出 **0**。
+            // 所以「0 = 免费」与「0 = 没配价目表」的歧义**产生在 core**,server 收到的信息里根本不含这个区分:
+            // 把这三处改成透传缺席**治不了根**(缺席永不到达),只会在 wire/SDK 面开一个今天零 producer 的可缺键。
+            // `?? 0` 因此定性为**类型面守卫**(core 契约把该键声明为 optional),不是语义折零点。
+            //
+            // 三问:
+            //  · 谁需要 —— 消费端要区分真零/未知(cli 在 CC 对照里正是靠「诚实缺席不编造」赢的那一点)。
+            //  · 谁受伤 —— (a) 聚合面遇缺席:usage-analytics 与 aggregateModelUsage 此前把 DB JSON 当全必填做裸
+            //    算术,一行缺键就 NaN/字符串毒掉整窗(#59 同批已修,红先复现在
+            //    test/usage-analytics.test.ts + test/model-usage.test.ts);(b) 历史行:已按 0 记账的行无法回溯
+            //    区分,只能靠部署位读回。
+            //  · 补偿 —— 第一级 = `capabilities.pricingConfigured`(main.ts:801,已在):false ⇒ 消费端把任何 0
+            //    渲染成「未知」而非「免费」;SDK `ModelUsageDelta.costMicroUsd` 的文档逐字同源。第二级(行级缺席)
+            //    需要 core 先在源头消歧 —— **工单挂 core**:无价目表时别为该调用编 0(缺席该键,或带一位
+            //    priced=false),到货后本处三行同批改透传,聚合面已经接得住。
+            // 现状语义(本批测试钉死,勿静默改):core 发 0 ⇒ server **如实透传 0**,消歧走部署位;
+            // 缺席(今日无 producer)⇒ 记 0,不抛不 NaN。
+            // └──────────────────────────────────────────────────────────────────────────────────────────────┘
             // 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

package/dist/trace/project.d.ts

@@ -41,7 +41,13 @@ export declare function attachModelUsage<T extends TaskResult>(result: T, ctx: {
 /** E8 (shell-host contract): SUM the per-turn `model_usage` delta events in a run's durable event log into the
  *  cumulative per-model total for `TaskStats.modelUsage`. The tracer drains deltas at each turn boundary
  *  (append-only) → this is resume-safe: it sums across ALL process legs of a suspended/resumed run. Returns
- *  undefined when the run logged no model usage (→ the shell soft-degrades to aggregate cost only). */
+ *  undefined when the run logged no model usage (→ the shell soft-degrades to aggregate cost only).
+ *
+ *  #59([2052]①):事件体是 **DB 里的 JSON**(旧版本 / 别的 producer 都可能写),此前的 `?? 0` 只接住
+ *  null/undefined——NaN 与字符串会原样进 `+`,一个坏键就把该模型的整 run 总量变成 NaN 或字符串拼接,
+ *  再顺着 `TaskStats.modelUsage` 回声流进 usage-analytics 的整窗聚合。守卫改「非有限数 = 缺席、按 0 计」,
+ *  与 usage-analytics 读侧同口径。注意本折叠对「costMicroUsd 缺席」与「costMicroUsd=0」的输出相同(都是 0):
+ *  行级 0-vs-未知的消歧不在这里,也不在 server —— 裁定见 budget.ts 的「#59 裁定」块。 */
 export declare function aggregateModelUsage(events: RunEvent[]): Record<string, ModelUsageDelta> | undefined;
 export type TraceBlock = {
     type: "thinking";

package/dist/trace/project.js

@@ -39,8 +39,15 @@ export async function attachModelUsage(result, ctx) {
 /** E8 (shell-host contract): SUM the per-turn `model_usage` delta events in a run's durable event log into the
  *  cumulative per-model total for `TaskStats.modelUsage`. The tracer drains deltas at each turn boundary
  *  (append-only) → this is resume-safe: it sums across ALL process legs of a suspended/resumed run. Returns
- *  undefined when the run logged no model usage (→ the shell soft-degrades to aggregate cost only). */
+ *  undefined when the run logged no model usage (→ the shell soft-degrades to aggregate cost only).
+ *
+ *  #59([2052]①):事件体是 **DB 里的 JSON**(旧版本 / 别的 producer 都可能写),此前的 `?? 0` 只接住
+ *  null/undefined——NaN 与字符串会原样进 `+`,一个坏键就把该模型的整 run 总量变成 NaN 或字符串拼接,
+ *  再顺着 `TaskStats.modelUsage` 回声流进 usage-analytics 的整窗聚合。守卫改「非有限数 = 缺席、按 0 计」,
+ *  与 usage-analytics 读侧同口径。注意本折叠对「costMicroUsd 缺席」与「costMicroUsd=0」的输出相同(都是 0):
+ *  行级 0-vs-未知的消歧不在这里,也不在 server —— 裁定见 budget.ts 的「#59 裁定」块。 */
 export function aggregateModelUsage(events) {
+    const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
     const total = {};
     let any = false;
     for (const ev of events) {
@@ -52,11 +59,11 @@ export function aggregateModelUsage(events) {
         for (const [model, d] of Object.entries(usage)) {
             any = true;
             const cur = total[model] ?? { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, costMicroUsd: 0 };
-            cur.inputTokens += d.inputTokens ?? 0;
-            cur.outputTokens += d.outputTokens ?? 0;
-            cur.cacheReadTokens += d.cacheReadTokens ?? 0;
-            cur.cacheWriteTokens += d.cacheWriteTokens ?? 0;
-            cur.costMicroUsd += d.costMicroUsd ?? 0;
+            cur.inputTokens += num(d.inputTokens);
+            cur.outputTokens += num(d.outputTokens);
+            cur.cacheReadTokens += num(d.cacheReadTokens);
+            cur.cacheWriteTokens += num(d.cacheWriteTokens);
+            cur.costMicroUsd += num(d.costMicroUsd);
             total[model] = cur;
         }
     }

package/dist/usage-analytics.d.ts

@@ -12,7 +12,9 @@
  *  - tokensOut = Σ outputTokens;
  *  - costUsd = Σ costMicroUsd / 1e6(authoritative);
  *  - 旧行/无 modelUsage echo 的行(1.x 早期或非终态)fallback `stats.tokens` 整数计入 tokensOut 并置
- *    `estimated:true` 于该聚合(诚实标注,契约要求"token 数标注估算与否");
+ *    `estimated:true` 于该聚合(诚实标注,契约要求"token 数标注估算与否");#59 起 `estimated` 还覆盖
+ *    第二种口径不完整:**有 echo 行但缺数值键**(该键按 0 计入 ⇒ 总量偏低)——两臂同义:别把总数当精确值;
+ *  - 行内数值键一律走 {@link numOf} 守卫:数据源是 DB 里的 JSON,裸算术遇缺席/非数会 NaN 毒掉整窗(#59);
  *  - 扫窗有行数上限(store 侧 LIMIT)——触顶时结果携带 `truncated:true`(诚实截断,绝不静默)。
  */
 /** store 侧 usageScan 的行投影(所有后端同形状;createdAtMs=epoch ms)。 */
@@ -23,21 +25,33 @@ export interface UsageRow {
     /** result.stats 摘要;result NULL/不可解析 ⇒ undefined(不计 token/cost,仍计 tasks)。 */
     stats?: {
         tokens?: number;
-        modelUsage?: Record<string, {
-            inputTokens: number;
-            outputTokens: number;
-            cacheReadTokens: number;
-            cacheWriteTokens: number;
-            costMicroUsd: number;
-        }>;
+        modelUsage?: Record<string, UsageModelEntry>;
     };
 }
+/**
+ * 一行 per-model echo。**五键逐个可选**——本类型描述的不是本进程铸的对象,而是 **DB 里 result JSON 的一段**:
+ * 旧版本写的行、别的 producer 写的行、以及 wire 契约本身(SDK `ModelUsageDelta` 五键全可选 + `[k]:unknown`
+ * 开放)都可能少键。#59([2052]①):此处原先声明成「全必填」,`projectUsageStats` 又对任意 JSON 做裸 cast,
+ * 于是 fold 侧的裸算术遇缺席就产出 NaN,**一行毒一整窗**(NaN 沿 Σ 传染,JSON.stringify(NaN)==="null",
+ * 消费端读到的是「没有数」而不是「少了一行」)。声明改诚实 + fold 侧 {@link numOf} 数值守卫。
+ */
+export interface UsageModelEntry {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    /** 整数 micro-USD。**缺席 = 未知**,不是 0(SDK `ModelUsageDelta` 同款单轨契约)。注意在场的 `0` 仍有
+     *  歧义(引擎无价目表时恒发 0),那层消歧在部署面 `capabilities.pricingConfigured`——裁定见 budget.ts。 */
+    costMicroUsd?: number;
+}
 export interface UsageTotals {
     tasks: number;
     tokensIn: number;
     tokensOut: number;
     costUsd: number;
-    /** 有行走了 stats.tokens fallback(无 per-model echo)——token 口径部分为估算。 */
+    /** 本聚合的口径**不完整**——两种来源:①有行走了 stats.tokens fallback(无 per-model echo,token 数为估算);
+     *  ②有 per-model echo 行**缺数值键**(该键按 0 计入,总量偏低;成本键缺席时尤其:少算 ≠ 免费)。
+     *  两者都只表达「别把这个总数当精确值」,消费端一视同仁。 */
     estimated: boolean;
 }
 /** GET /v1/usage/summary — 窗内总量。 */

package/dist/usage-analytics.js

@@ -12,19 +12,37 @@
  *  - tokensOut = Σ outputTokens;
  *  - costUsd = Σ costMicroUsd / 1e6(authoritative);
  *  - 旧行/无 modelUsage echo 的行(1.x 早期或非终态)fallback `stats.tokens` 整数计入 tokensOut 并置
- *    `estimated:true` 于该聚合(诚实标注,契约要求"token 数标注估算与否");
+ *    `estimated:true` 于该聚合(诚实标注,契约要求"token 数标注估算与否");#59 起 `estimated` 还覆盖
+ *    第二种口径不完整:**有 echo 行但缺数值键**(该键按 0 计入 ⇒ 总量偏低)——两臂同义:别把总数当精确值;
+ *  - 行内数值键一律走 {@link numOf} 守卫:数据源是 DB 里的 JSON,裸算术遇缺席/非数会 NaN 毒掉整窗(#59);
  *  - 扫窗有行数上限(store 侧 LIMIT)——触顶时结果携带 `truncated:true`(诚实截断,绝不静默)。
  */
+/** JSON 来源的数值键:非 number / 非有限 ⇒ undefined(缺席),**绝不返回 NaN**,也绝不让字符串滑进 `+`。 */
+function numOf(d, key) {
+    const v = d[key];
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
 const emptyTotals = () => ({ tasks: 0, tokensIn: 0, tokensOut: 0, costUsd: 0, estimated: false });
+/** 折入一行 per-model echo(summary/series 的 foldRow 与 breakdown 的 model 维共用——两处写两遍必漂移)。
+ *  缺席/非数键按 0 计入并置 `estimated`(诚实标注偏低,绝不静默,也绝不 NaN 毒窗)。 */
+function foldModelEntry(t, d) {
+    const input = numOf(d, "inputTokens");
+    const output = numOf(d, "outputTokens");
+    const cacheRead = numOf(d, "cacheReadTokens");
+    const cacheWrite = numOf(d, "cacheWriteTokens");
+    const cost = numOf(d, "costMicroUsd");
+    t.tokensIn += (input ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0);
+    t.tokensOut += output ?? 0;
+    t.costUsd += (cost ?? 0) / 1e6;
+    if (input === undefined || output === undefined || cacheRead === undefined || cacheWrite === undefined || cost === undefined)
+        t.estimated = true;
+}
 function foldRow(t, row) {
     t.tasks += 1;
     const mu = row.stats?.modelUsage;
     if (mu && Object.keys(mu).length > 0) {
-        for (const d of Object.values(mu)) {
-            t.tokensIn += d.inputTokens + d.cacheReadTokens + d.cacheWriteTokens;
-            t.tokensOut += d.outputTokens;
-            t.costUsd += d.costMicroUsd / 1e6;
-        }
+        for (const d of Object.values(mu))
+            foldModelEntry(t, d);
     }
     else if (row.stats?.tokens) {
         t.tokensOut += row.stats.tokens; // 旧行 fallback:总数无 in/out 拆分,归 out 侧并标 estimated
@@ -75,9 +93,7 @@ export function usageBreakdown(rows, dimension) {
             for (const [model, d] of Object.entries(mu)) {
                 const t = bucket(model);
                 t.tasks += 1; // 每 (run, model) 计一次 —— 一个 run 用两个模型在两桶各计 1(桶内 tasks=touched-run 数)
-                t.tokensIn += d.inputTokens + d.cacheReadTokens + d.cacheWriteTokens;
-                t.tokensOut += d.outputTokens;
-                t.costUsd += d.costMicroUsd / 1e6;
+                foldModelEntry(t, d); // #59:与 summary/series 同一守卫(缺席键不毒桶,只标 estimated;桶间不传染)
             }
         }
         else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "3.5.1",
+  "version": "3.5.3",
   "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",
@@ -67,7 +67,7 @@
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@sema-agent/sdk": "^2.1.1",
+    "@sema-agent/sdk": "^2.1.2",
     "@types/libsodium-wrappers": "^0.7.14",
     "@types/node": "22.10.2",
     "@types/pg": "^8.20.0",