@sema-agent/server 1.323.0 → 2.0.0

package/dist/usage-analytics.js

@@ -1,3 +1,20 @@
+/**
+ * 用量统计查询面(registry AnalyticsSource id="service-usage" 槽位的数据源)。
+ *
+ * 数据源 = task_run 账本的 result JSON(E8 `stats.modelUsage` per-model echo:inputTokens/outputTokens/
+ * cacheReadTokens/cacheWriteTokens/costMicroUsd——costMicroUsd 是 authoritative micro-USD 记账非估算)。
+ * 架构 = store 侧薄扫窗(usageScan:SQL 只按时间窗过滤取四列,行内 JSON 提取在 store 完成)+ 本文件的
+ * 【纯函数】聚合(三后端同代码,零方言分叉;test 直接喂行)。
+ *
+ * 口径(回帖契约,2026-07-09):
+ *  - tokensIn = Σ(inputTokens + cacheReadTokens + cacheWriteTokens)(即"进模型的上下文 token 总量",
+ *    cache 命中也计——计费口径;cache 明细在 breakdown 的 cacheReadTokens 单列可见);
+ *  - tokensOut = Σ outputTokens;
+ *  - costUsd = Σ costMicroUsd / 1e6(authoritative);
+ *  - 旧行/无 modelUsage echo 的行(1.x 早期或非终态)fallback `stats.tokens` 整数计入 tokensOut 并置
+ *    `estimated:true` 于该聚合(诚实标注,契约要求"token 数标注估算与否");
+ *  - 扫窗有行数上限(store 侧 LIMIT)——触顶时结果携带 `truncated:true`(诚实截断,绝不静默)。
+ */
 const emptyTotals = () => ({ tasks: 0, tokensIn: 0, tokensOut: 0, costUsd: 0, estimated: false });
 function foldRow(t, row) {
     t.tasks += 1;
@@ -10,18 +27,20 @@ function foldRow(t, row) {
         }
     }
     else if (row.stats?.tokens) {
-        t.tokensOut += row.stats.tokens;
+        t.tokensOut += row.stats.tokens; // 旧行 fallback:总数无 in/out 拆分,归 out 侧并标 estimated
         t.estimated = true;
     }
 }
 const round6 = (n) => Math.round(n * 1e6) / 1e6;
 const finish = (t) => ({ ...t, costUsd: round6(t.costUsd) });
+/** GET /v1/usage/summary — 窗内总量。 */
 export function usageSummary(rows) {
     const t = emptyTotals();
     for (const r of rows)
         foldRow(t, r);
     return finish(t);
 }
+/** GET /v1/usage/series — 时间序列(UTC 桶;空桶不发行,消费方按需补零)。 */
 export function usageSeries(rows, metric, granularity) {
     const bucketMs = granularity === "hour" ? 3_600_000 : 86_400_000;
     const buckets = new Map();
@@ -36,6 +55,8 @@ export function usageSeries(rows, metric, granularity) {
         .sort((a, b) => a[0] - b[0])
         .map(([b, t]) => ({ t: new Date(b).toISOString(), v: metric === "costUsd" ? round6(t.costUsd) : t[metric] }));
 }
+/** GET /v1/usage/breakdown — 按维度分桶。dimension=model 时按 per-model echo 展开(一行可贡献多个 model 桶;
+ *  fallback 行归 "(unattributed)");dimension=principal 时 owner NULL 归 "(anonymous)"。 */
 export function usageBreakdown(rows, dimension) {
     const buckets = new Map();
     const bucket = (key) => {
@@ -53,7 +74,7 @@ export function usageBreakdown(rows, dimension) {
         if (mu && Object.keys(mu).length > 0) {
             for (const [model, d] of Object.entries(mu)) {
                 const t = bucket(model);
-                t.tasks += 1;
+                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;
@@ -67,6 +88,7 @@ export function usageBreakdown(rows, dimension) {
         .sort((a, b) => b[1].costUsd - a[1].costUsd || b[1].tokensOut - a[1].tokensOut || a[0].localeCompare(b[0]))
         .map(([key, t]) => ({ key, ...finish(t) }));
 }
+/** store 行投影 helper:result JSON(已 parse 或原始字符串)→ UsageRow.stats。所有后端复用(方言只在 SQL)。 */
 export function projectUsageStats(result) {
     try {
         const parsed = typeof result === "string" ? JSON.parse(result) : result;
@@ -82,8 +104,9 @@ export function projectUsageStats(result) {
         return out;
     }
     catch {
-        return undefined;
+        return undefined; // 坏 JSON:计 tasks 不计 token(诚实降级)
     }
 }
+/** usageScan 的统一行数上限(触顶=结果 truncated:true;试点规模远在限内)。 */
 export const USAGE_SCAN_LIMIT = 50_000;
 //# sourceMappingURL=usage-analytics.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "1.323.0",
+  "version": "2.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",