feat(hub): usage fact ledger for run-scoped cost attribution (ADR-0026) (#4)

Co-authored-by: Hong Jiarong <me@jrhim.com>
Co-committed-by: Hong Jiarong <me@jrhim.com>

hub/src/feishu/slashCommands.ts

@@ -92,7 +92,18 @@ export function createSlashCommandRegistry(
           finishedAt: { not: null },
         },
         orderBy: { finishedAt: "asc" },
-        select: { model: true, provider: true, inputTokens: true, outputTokens: true, costUsd: true },
+        select: {
+          usageFacts: {
+            select: {
+              provider: true,
+              model: true,
+              inputTokens: true,
+              outputTokens: true,
+              costUsd: true,
+            },
+            orderBy: { occurredAt: "asc" },
+          },
+        },
       });
       await sendText(rt, chatId, formatUsageReport(runs, scope), sendOptions);
     },
@@ -118,18 +129,24 @@ async function currentRoleSessionIds(
   return sessions.map((session) => session.id);
 }
 
-interface UsageRun {
-  readonly model: string;
-  readonly provider: string;
-  readonly inputTokens: number | null;
-  readonly outputTokens: number | null;
-  readonly costUsd: unknown;
+interface UsageRunWithFacts {
+  readonly usageFacts: readonly {
+    readonly provider: string;
+    readonly model: string | null;
+    readonly inputTokens: number | null;
+    readonly outputTokens: number | null;
+    readonly costUsd: unknown;
+  }[];
 }
 
-function formatUsageReport(runs: readonly UsageRun[], scope: "current" | "project"): string {
+function formatUsageReport(runs: readonly UsageRunWithFacts[], scope: "current" | "project"): string {
   if (runs.length === 0) return `${scope === "current" ? "当前角色会话" : "当前项目"}还没有已结束的 Agent run。`;
+  // Bucket by (fact.provider, fact.model) — ADR-0026: external capabilities
+  // carry their own provider/model and contribute their own meter, so a run
+  // with a main loop + an external call lands in two buckets. A run with no
+  // cost-bearing fact is "unrecorded" (ADR-0022: missing cost ≠ zero).
   const buckets = new Map<string, {
-    provider: string; model: string; runs: number; inputTokens: number; outputTokens: number; costUsd: number;
+    provider: string; model: string; facts: number; inputTokens: number; outputTokens: number; costUsd: number;
   }>();
   let recordedRuns = 0;
   let unrecordedRuns = 0;
@@ -137,21 +154,34 @@ function formatUsageReport(runs: readonly UsageRun[], scope: "current" | "projec
   let totalOutputTokens = 0;
   let totalCostUsd = 0;
   for (const run of runs) {
-    const costUsd = decimalToNumberOrNull(run.costUsd);
-    if (costUsd === null) { unrecordedRuns++; continue; }
+    const facts = run.usageFacts;
+    if (facts.length === 0 || !facts.some((f) => f.costUsd !== null && f.costUsd !== undefined)) {
+      unrecordedRuns++;
+      // Tokens from unrecorded runs still count toward totals (matches pre-0026).
+      for (const f of facts) {
+        totalInputTokens += f.inputTokens ?? 0;
+        totalOutputTokens += f.outputTokens ?? 0;
+      }
+      continue;
+    }
     recordedRuns++;
-    const key = `${run.provider}\u0000${run.model}`;
-    const bucket = buckets.get(key) ?? {
-      provider: run.provider, model: run.model, runs: 0, inputTokens: 0, outputTokens: 0, costUsd: 0,
-    };
-    bucket.runs++;
-    bucket.inputTokens += run.inputTokens ?? 0;
-    bucket.outputTokens += run.outputTokens ?? 0;
-    bucket.costUsd += costUsd;
-    buckets.set(key, bucket);
-    totalInputTokens += run.inputTokens ?? 0;
-    totalOutputTokens += run.outputTokens ?? 0;
-    totalCostUsd += costUsd;
+    for (const f of facts) {
+      const costUsd = decimalToNumberOrNull(f.costUsd);
+      if (costUsd === null) continue;
+      const model = f.model ?? "(unknown model)";
+      const key = `${f.provider}\u0000${model}`;
+      const bucket = buckets.get(key) ?? {
+        provider: f.provider, model, facts: 0, inputTokens: 0, outputTokens: 0, costUsd: 0,
+      };
+      bucket.facts += 1;
+      bucket.inputTokens += f.inputTokens ?? 0;
+      bucket.outputTokens += f.outputTokens ?? 0;
+      bucket.costUsd += costUsd;
+      buckets.set(key, bucket);
+      totalInputTokens += f.inputTokens ?? 0;
+      totalOutputTokens += f.outputTokens ?? 0;
+      totalCostUsd += costUsd;
+    }
   }
   const lines = [
     `${scope === "current" ? "当前角色会话" : "当前项目"}用量`,
@@ -160,7 +190,7 @@ function formatUsageReport(runs: readonly UsageRun[], scope: "current" | "projec
   ];
   if (unrecordedRuns > 0) lines.push(`另有 ${formatInteger(unrecordedRuns)} 个 run 未记录成本。`);
   for (const bucket of buckets.values()) {
-    lines.push(`- ${bucket.provider} / ${bucket.model}: ${formatInteger(bucket.runs)} runs, ${formatUsd(bucket.costUsd)}`);
+    lines.push(`- ${bucket.provider} / ${bucket.model}: ${formatInteger(bucket.facts)} 次, ${formatUsd(bucket.costUsd)}`);
   }
   return lines.join("\n");
 }

hub/src/feishu/trigger.ts

@@ -604,6 +604,32 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
             data: { metadata: mergeSessionMetadata(session.metadata, metadataPatch) },
           });
         }
+        // ADR-0026: the UsageFact ledger is the truth; AgentRun.costUsd /
+        // inputTokens / outputTokens are a derived rollup cache for existing
+        // readers. We write the fact first, then mirror it onto the run.
+        // They are separate statements (not one transaction) so the AgentRun
+        // row lock is held for the shortest possible window and concurrent
+        // workspace teardown cannot deadlock on the FK ShareLock. A crash
+        // between the two leaves the cache stale, but the cache is derived
+        // (the usage service re-reads facts), so staleness is recoverable;
+        // the reverse order would lose the truth and is unrecoverable.
+        const finishedAt = new Date();
+        const reportedCost = result.costUsd;
+        const costSource = reportedCost !== undefined ? "provider_reported" : "unknown";
+        await deps.prisma.usageFact.create({
+          data: {
+            runId: run.id,
+            occurredAt: finishedAt,
+            kind: "model_completion",
+            provider: providerId,
+            model,
+            inputTokens: result.usage.inputTokens,
+            outputTokens: result.usage.outputTokens,
+            costUsd: reportedCost ?? null,
+            costSource,
+            metadata: {},
+          },
+        });
         await deps.prisma.agentRun.update({
           where: { id: run.id },
           data: {
@@ -618,9 +644,10 @@ export function makeTriggerHandler(deps: TriggerDeps): TriggerHandler {
                     : "FAILED",
             inputTokens: result.usage.inputTokens,
             outputTokens: result.usage.outputTokens,
-            ...(result.costUsd !== undefined ? { costUsd: result.costUsd, costSource: "provider_reported" } : {}),
+            costUsd: reportedCost ?? null,
+            costSource,
             error: result.error ?? null,
-            finishedAt: new Date(),
+            finishedAt,
           },
         });
         await writeAudit(deps.prisma, {