agent-orchestrator-kit 0.14.1 → 0.15.0

package/CHANGELOG.md

@@ -4,7 +4,13 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-09-08
+
+### Added
+- **`costUsdTotal` — one USD figure per change, phase, platform, model, and session.** Each session contributes its billed `costUsd` when present, otherwise its `costUsdEstimated`; sums are rounded to 4 decimals. A change that ran on Amp (billed `$14.48`) plus Claude (`~$5.16`) and Cursor (`~$1.43`) now carries `spend.costUsdTotal: 21.0779` instead of forcing a dashboard to pick `costUsd` and drop the estimated platforms. `costUsd` and `costUsdEstimated` stay separate fields and Amp credits stay out of every USD field. `metrics --summary-json` carries the field; the human `cost:` line prints `$21.08 ($14.48 billed + ~$6.60 est.)`.
+
 ### Fixed
+- **Billed sums are rounded like estimates.** `spendByModel[].costUsd`, `spendByPlatform.*.costUsd`, `phases.*.costUsd`, and `spend.costUsd` stored raw float sums such as `4.4399999999999995` and `0.009000000000000001`; they are now `Math.round(x * 10000) / 10000`, the same rule `costUsdEstimated` already had.
 - **Cache-split cost estimates survive the session recompute.** `applyCollectedSessionFields` recomputed `byModel[].costUsdEstimated` from `inputTokens` + `outputTokens` alone and overwrote the value the adapters had already produced. Since `inputTokens` includes `cache_read_*` / `cache_creation_*`, every cached token was billed at the full input rate: a real Claude change with 3.5M tokens estimated `$30.11` instead of `$5.16`, and Cursor rows lost their own rate table to the Claude `$3/$15` fallback. The recompute now only fills rows that have no adapter estimate, so ESTIMATE-ALL still covers Amp rows without `Cost:` while `claude-opus-5` with 100k input + 900k cache read + 10k output stays at `$1.20`.
 
 ## [0.14.1] - 2026-09-08

package/README.md

@@ -74,7 +74,7 @@ npx agent-orchestrator-kit@latest init --profile generic --ci gitlab --spec-veri
 
 See [Installation](#installation) for profile/CI options.
 
-**🔄 Already have the kit installed? Upgrade to latest (v0.14.1 fixes a `handoff` persist that wiped the Memory graph, syncs the `/opsx:*` commands into Cursor and Claude Code, and stops `status` / `gate-check` from reporting a gate as met when it is not):**
+**🔄 Already have the kit installed? Upgrade to latest (v0.15.0 adds `costUsdTotal`, one USD figure per change / phase / platform / model that sums billed Amp with estimated Cursor and Claude, rounds billed sums like estimates, and keeps cache-split Claude estimates from being re-billed at the full input rate):**
 
 ```bash
 npx agent-orchestrator-kit@latest update
@@ -816,7 +816,7 @@ Schema v2 stores compact `sourceIds`, `sourceTotals`, and `byModel` per session
 - **Locked client** — `--restore` records `pending.platform` and Amp `pending.threadId` before phase work. Persist follows that client’s flow even if persist runs in another shell (no `AMP_*` / `CURSOR_*`). Amp: `amp threads export` plus `amp threads usage --details` (`AOK_AMP_BIN`) and local `threads/*.json`. Export supplies `model` / tokens / `agentMode`; usage supplies billed `$`. If Amp runs tools over a pipe (`/dev/null`), thread id comes from `amp threads list`, not stale `session.json` `lastThreadId`. When env and Amp parent do not win, restore locks a fresh `session.json` `lastThreadId` as `amp-session-last`. Cursor: spend hook file. Claude: `~/.claude/projects`. `--collect` still runs all three adapters.
 - **Cursor spend hook (optional)** — Cursor never writes token usage to disk, so the kit can install `scripts/cursor-spend-hook.cjs` plus `.cursor/hooks.json` entries (`stop` / `subagentStop` / `afterAgentResponse`) in `init` / `update` / `sync` / `mcp-setup`: the hook appends each turn's tokens to gitignored `.agents/spend/cursor-usage.jsonl`. After a successful `stop` / `afterAgentResponse` append the hook runs leftover (fail-open, no stdout). Hook and collect resolve the consumer in a multi-root window (not the first cwd with `.agents` or `openspec`). Persist auto-reads that file when the locked client is Cursor. Persist and restore do not self-heal the hook. `sessionEnd` still runs `scripts/cursor-spend-collect.cjs`. Restart Cursor once after the first install. `status` shows a `Spend capture` section. Claude JSONL remains a fallback. Amp web/CLI spend is taken from `amp threads export` (tokens, model, `agentMode`) and `amp threads usage` (billed USD).
 
-Aggregates are recomputed on every write: per-phase totals (`startedAt`, `endedAt`, `leadTimeMs` from that phase’s sessions, `durationMs` = sum of session work time — not `totals.leadTimeMs` and not `endedAt − startedAt`, tokens, `costUsd`, `costUsdEstimated` to 4 decimals, `sessions`, `roles`, `models`) plus overall `totals` (`sessions`, `cloudSessions`, `durationMs` = sum of session work time, `leadTimeMs` = wall clock from first session start to last session end), `spend` (USD only), and separate **by platform** / **by model** tables. Numbers are null-honest: a metric nobody reported stays `null`, never a fake `0`. No single total that adds Amp credits to USD.
+Aggregates are recomputed on every write: per-phase totals (`startedAt`, `endedAt`, `leadTimeMs` from that phase’s sessions, `durationMs` = sum of session work time — not `totals.leadTimeMs` and not `endedAt − startedAt`, tokens, `costUsd`, `costUsdEstimated`, `costUsdTotal` to 4 decimals, `sessions`, `roles`, `models`) plus overall `totals` (`sessions`, `cloudSessions`, `durationMs` = sum of session work time, `leadTimeMs` = wall clock from first session start to last session end), `spend` (USD only), and separate **by platform** / **by model** tables. Numbers are null-honest: a metric nobody reported stays `null`, never a fake `0`. No single total that adds Amp credits to USD. `costUsdTotal` is the one USD figure per change, phase, platform, model, and session: each session contributes its billed `costUsd` when present, otherwise its `costUsdEstimated`, so a change that ran on Amp (billed) plus Cursor and Claude (estimated) sums all three platforms instead of showing only the billed part. Amp credits never enter it. The human `cost:` line prints it as `$21.08 ($14.48 billed + ~$6.60 est.)`.
 
 Fill `## Metrics` in `handoff.md` **before** persist (unknown is fine; do not invent `0`):
 
@@ -843,7 +843,7 @@ npx agent-orchestrator-kit archive add-thing --sync      # finalize + the same t
 
 #### Для дашбордів
 
-Use only `phases.<phase>.startedAt`, `endedAt`, and `durationMs` for phase boundaries and duration. Use `totals.leadTimeMs` only for the whole change. Git log MUST NOT be used for phase boundaries; the kit does not provide per-phase commit counts. `metrics <name> --summary-json` returns only aggregate `totals`, `phases`, and spend maps, without sessions or commits.
+Use only `phases.<phase>.startedAt`, `endedAt`, and `durationMs` for phase boundaries and duration. Use `totals.leadTimeMs` only for the whole change. Git log MUST NOT be used for phase boundaries; the kit does not provide per-phase commit counts. `metrics <name> --summary-json` returns only aggregate `totals`, `phases`, and spend maps, without sessions or commits. For the headline cost use `spend.costUsdTotal` (and `phases.<phase>.costUsdTotal`, `spendByPlatform.<platform>.costUsdTotal`, `spendByModel[].costUsdTotal`): `costUsd` alone is only the billed part and `costUsdEstimated` alone is only the estimated part, so picking one of them drops every platform that reported the other.
 
 Recording is on by default and never a persist/archive/`gate-check` gate; opt out per persist with `--no-metrics`. Persist and archive collect the locked client without `--collect`; `--collect` runs every adapter. Flags (`--model`, `--platform`, `--input-tokens`, …) override session totals in `metrics.json` and do not rewrite the `## Metrics` section.
 
@@ -1017,6 +1017,11 @@ Phase bounds and non-goals: [`openspec/specs/agentic-factory-roadmap/spec.md`](o
 
 ## Changelog
 
+### 0.15.0
+- **`costUsdTotal`** on `spend`, `phases.*`, `spendByPlatform.*`, `spendByModel[]`, and sessions — billed `costUsd` when present, otherwise `costUsdEstimated`, per session; a change that ran on Amp (billed) plus Cursor and Claude (estimated) now sums all three platforms instead of showing only the billed part; the human `cost:` line prints `$21.08 ($14.48 billed + ~$6.60 est.)` and `--summary-json` carries the field
+- Billed `costUsd` aggregates are rounded to 4 decimals like estimates (no more `4.4399999999999995` in `spendByModel`)
+- Cache-split Claude cost estimates survive the session recompute instead of being re-billed at the full input rate (`$30.11` → `$5.16` on a 3.5M-token change)
+
 ### 0.14.1
 - **Memory graph survives `handoff` persist** — JSONL graphs were misread as an aggregate document and returned empty, so each persist overwrote the file with only the current change; all `Decision:*`, other changes, and relations were lost
 - `/opsx:*` commands now sync to `.cursor/commands/` (flat) and `.claude/commands/opsx/` (namespaced), so the documented slash commands exist in both IDEs

package/bin/agent-orchestrator.js

@@ -1710,12 +1710,18 @@ function roundUsd4(x) {
   return Math.round(Number(x) * 10000) / 10000;
 }
 
+function costUsdTotalOf(obj) {
+  const billed = numOrNull(obj && obj.costUsd);
+  if (billed != null) return billed;
+  return numOrNull(obj && obj.costUsdEstimated);
+}
+
 function metricsFilePath(projectDir, changeName) {
   return join(projectDir, 'openspec', 'changes', changeName, 'metrics.json');
 }
 
 function emptySpendTotals() {
-  return { inputTokens: null, outputTokens: null, totalTokens: null, costUsd: null, costUsdEstimated: null };
+  return { inputTokens: null, outputTokens: null, totalTokens: null, costUsd: null, costUsdEstimated: null, costUsdTotal: null };
 }
 
 function emptyPlatformSpend(source = 'none') {
@@ -1726,6 +1732,7 @@ function emptyPlatformSpend(source = 'none') {
     costUsd: null,
     ampCredits: null,
     costUsdEstimated: null,
+    costUsdTotal: null,
     source,
   };
 }
@@ -2549,6 +2556,7 @@ function spendTuple(obj) {
     costUsd: numOrNull(obj && obj.costUsd),
     ampCredits: numOrNull(obj && obj.ampCredits),
     costUsdEstimated: numOrNull(obj && obj.costUsdEstimated),
+    costUsdTotal: numOrNull(obj && obj.costUsdTotal) ?? costUsdTotalOf(obj),
   };
 }
 
@@ -2568,6 +2576,7 @@ function addSpendNums(target, nums) {
   target.costUsd = addNullable(target.costUsd, nums.costUsd);
   target.ampCredits = addNullable(target.ampCredits, nums.ampCredits);
   target.costUsdEstimated = addNullable(target.costUsdEstimated, nums.costUsdEstimated);
+  target.costUsdTotal = addNullable(target.costUsdTotal, nums.costUsdTotal);
 }
 
 function recomputeSpendMaps(metrics) {
@@ -2586,6 +2595,7 @@ function recomputeSpendMaps(metrics) {
       costUsd: null,
       ampCredits: null,
       costUsdEstimated: null,
+      costUsdTotal: null,
     };
     addSpendNums(row, nums);
     byModel.set(key, row);
@@ -2606,10 +2616,14 @@ function recomputeSpendMaps(metrics) {
     }
   }
   for (const key of Object.keys(byPlatform)) {
+    byPlatform[key].costUsd = roundUsd4(byPlatform[key].costUsd);
     byPlatform[key].costUsdEstimated = roundUsd4(byPlatform[key].costUsdEstimated);
+    byPlatform[key].costUsdTotal = roundUsd4(byPlatform[key].costUsdTotal);
   }
   for (const row of byModel.values()) {
+    row.costUsd = roundUsd4(row.costUsd);
     row.costUsdEstimated = roundUsd4(row.costUsdEstimated);
+    row.costUsdTotal = roundUsd4(row.costUsdTotal);
   }
   metrics.spendByPlatform = byPlatform;
   metrics.spendByModel = [...byModel.values()];
@@ -2661,6 +2675,13 @@ function recomputeMetricsAggregates(metrics) {
       phase[spendKey] = addNullable(phase[spendKey], value);
       spend[spendKey] = addNullable(spend[spendKey], value);
     }
+    const sessionCostUsdTotal = costUsdTotalOf({
+      costUsd: sessionFieldOrSources(session, 'costUsd'),
+      costUsdEstimated: sessionFieldOrSources(session, 'costUsdEstimated'),
+    });
+    session.costUsdTotal = roundUsd4(sessionCostUsdTotal);
+    phase.costUsdTotal = addNullable(phase.costUsdTotal, sessionCostUsdTotal);
+    spend.costUsdTotal = addNullable(spend.costUsdTotal, sessionCostUsdTotal);
     if (session.role && !phase.agents.includes(session.role)) phase.agents.push(session.role);
     if (session.model && !phase.models.includes(session.model)) phase.models.push(session.model);
     if (Array.isArray(session.models)) {
@@ -2679,9 +2700,13 @@ function recomputeMetricsAggregates(metrics) {
     phase.leadTimeMs = Number.isFinite(startMs) && Number.isFinite(endMs)
       ? Math.max(0, endMs - startMs)
       : null;
+    phase.costUsd = roundUsd4(phase.costUsd);
     phase.costUsdEstimated = roundUsd4(phase.costUsdEstimated);
+    phase.costUsdTotal = roundUsd4(phase.costUsdTotal);
   }
+  spend.costUsd = roundUsd4(spend.costUsd);
   spend.costUsdEstimated = roundUsd4(spend.costUsdEstimated);
+  spend.costUsdTotal = roundUsd4(spend.costUsdTotal);
   metrics.phases = phases;
   metrics.totals = totals;
   metrics.spend = spend;
@@ -2908,7 +2933,8 @@ function formatMetricsCostLine(spend) {
   const estimated = spend && spend.costUsdEstimated;
   if (billed == null && estimated == null) return '—';
   if (billed != null && estimated != null) {
-    return `${formatMetricsCost(billed)} billed + ~${formatMetricsCost(estimated)} est.`;
+    const total = spend.costUsdTotal != null ? spend.costUsdTotal : billed + estimated;
+    return `${formatMetricsCost(total)} (${formatMetricsCost(billed)} billed + ~${formatMetricsCost(estimated)} est.)`;
   }
   if (billed != null) return formatMetricsCost(billed);
   return `~${formatMetricsCost(estimated)} est.`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-kit",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Universal AI agent orchestration kit for Cursor, Claude Code, and Amp Code — spec-driven OpenSpec pipeline, conductor subagents, durable session handoff, factory gates and MCP setup, cloud-agent handoff, and optional local Figma PAT setup",
   "keywords": [
     "ai-agent",

package/templates/scripts/cursor-spend-collect.cjs

@@ -23,6 +23,12 @@ function roundUsd4(x) {
   return Math.round(Number(x) * 10000) / 10000;
 }
 
+function costUsdTotalOf(obj) {
+  const billed = numOrNull(obj && obj.costUsd);
+  if (billed != null) return billed;
+  return numOrNull(obj && obj.costUsdEstimated);
+}
+
 function timestampMs(value) {
   if (value == null || value === '') return NaN;
   const ms = Date.parse(value);
@@ -435,6 +441,7 @@ function emptyPlatform(source = 'none') {
     costUsd: null,
     ampCredits: null,
     costUsdEstimated: null,
+    costUsdTotal: null,
     source,
   };
 }
@@ -442,7 +449,7 @@ function emptyPlatform(source = 'none') {
 function recompute(metrics) {
   const phases = {};
   const totals = { sessions: 0, durationMs: null, leadTimeMs: null, cloudSessions: 0 };
-  const spend = { inputTokens: null, outputTokens: null, totalTokens: null, costUsd: null, costUsdEstimated: null };
+  const spend = { inputTokens: null, outputTokens: null, totalTokens: null, costUsd: null, costUsdEstimated: null, costUsdTotal: null };
   const byPlatform = {
     cursor: emptyPlatform(),
     claude: emptyPlatform(),
@@ -477,6 +484,7 @@ function recompute(metrics) {
       totalTokens: null,
       costUsd: null,
       costUsdEstimated: null,
+      costUsdTotal: null,
       agents: [],
       models: [],
     };
@@ -493,6 +501,10 @@ function recompute(metrics) {
       phase[spendKey] = addNullable(phase[spendKey], value);
       spend[spendKey] = addNullable(spend[spendKey], value);
     }
+    const sessionCostUsdTotal = costUsdTotalOf(session);
+    session.costUsdTotal = roundUsd4(sessionCostUsdTotal);
+    phase.costUsdTotal = addNullable(phase.costUsdTotal, sessionCostUsdTotal);
+    spend.costUsdTotal = addNullable(spend.costUsdTotal, sessionCostUsdTotal);
     if (session.role && !phase.agents.includes(session.role)) phase.agents.push(session.role);
     if (session.model && !phase.models.includes(session.model)) phase.models.push(session.model);
     if (Array.isArray(session.models)) {
@@ -508,6 +520,7 @@ function recompute(metrics) {
       for (const key of ['inputTokens', 'outputTokens', 'totalTokens', 'costUsd', 'ampCredits', 'costUsdEstimated']) {
         bucket[key] = addNullable(bucket[key], numOrNull(session[key]));
       }
+      bucket.costUsdTotal = addNullable(bucket.costUsdTotal, sessionCostUsdTotal);
       if ((session.sourceIds || []).length) bucket.source = platform === 'cursor' ? 'cursor-hook' : `${platform}-jsonl`;
     }
     const modelRows = (session.byModel || []).length ? session.byModel : [session];
@@ -523,6 +536,7 @@ function recompute(metrics) {
           costUsd: null,
           ampCredits: null,
           costUsdEstimated: null,
+          costUsdTotal: null,
         };
         row.inputTokens = addNullable(row.inputTokens, numOrNull(src.inputTokens));
         row.outputTokens = addNullable(row.outputTokens, numOrNull(src.outputTokens));
@@ -530,6 +544,7 @@ function recompute(metrics) {
         row.costUsd = addNullable(row.costUsd, numOrNull(src.costUsd));
         row.ampCredits = addNullable(row.ampCredits, numOrNull(src.ampCredits));
         row.costUsdEstimated = addNullable(row.costUsdEstimated, numOrNull(src.costUsdEstimated));
+        row.costUsdTotal = addNullable(row.costUsdTotal, costUsdTotalOf(src));
         byModel.set(modelKey, row);
       }
     }
@@ -544,14 +559,22 @@ function recompute(metrics) {
     phase.leadTimeMs = Number.isFinite(startMs) && Number.isFinite(endMs)
       ? Math.max(0, endMs - startMs)
       : null;
+    phase.costUsd = roundUsd4(phase.costUsd);
     phase.costUsdEstimated = roundUsd4(phase.costUsdEstimated);
+    phase.costUsdTotal = roundUsd4(phase.costUsdTotal);
   }
+  spend.costUsd = roundUsd4(spend.costUsd);
   spend.costUsdEstimated = roundUsd4(spend.costUsdEstimated);
+  spend.costUsdTotal = roundUsd4(spend.costUsdTotal);
   for (const bucket of Object.values(byPlatform)) {
+    bucket.costUsd = roundUsd4(bucket.costUsd);
     bucket.costUsdEstimated = roundUsd4(bucket.costUsdEstimated);
+    bucket.costUsdTotal = roundUsd4(bucket.costUsdTotal);
   }
   for (const row of byModel.values()) {
+    row.costUsd = roundUsd4(row.costUsd);
     row.costUsdEstimated = roundUsd4(row.costUsdEstimated);
+    row.costUsdTotal = roundUsd4(row.costUsdTotal);
   }
   metrics.phases = phases;
   metrics.totals = totals;