fix(cost): Opus-accurate context ring + cost ledger + stop button

[stansalvatec]

Summary

Five related fixes stacked on the token-cost-meter branch, now merged together:

1. Stop button stuck active after model done (96768f1) — client optimistically reconciles session.status in thread.message-sent and guards onInterrupt when the latest turn is in a terminal state.
2. Bot-review cleanups (76a3495) — dead useInvalidateCostSummary removed, duplicate formatUsd re-exported from @t3tools/shared/pricing, no-op ternaries in sanitizePersistedFile simplified.
3. Cost ledger over-counting (b027c89) — ProviderRuntimeIngestion now gates recordUsage on the presence of any lastXxxTokens field (the canonical "turn-final" signal). Mid-turn Claude snapshots only flow to the context-window activity, not the ledger. Also normalises the model slug before ledger writes so the byModel breakdown stays stable.
4. Context-window ring over-reporting (step 1) (b027c89) — both adapters redefined usedTokens as input-side only (input + cache-read + cache-creation for Claude, last.inputTokens + last.cachedInputTokens for Codex). totalProcessedTokens keeps its billing-side semantic. ContextWindowSnapshot now carries cacheCreationInputTokens / lastCacheCreationInputTokens.
5. Opus-accurate context ring (step 2) (d46b444) — the step-1 fix still over-reported on Opus because we fell back to result.usage (which is session-cumulative across every API call, not per-turn), and the task_progress.usage SDK field only exposes an opaque total_tokens. Now we capture input + cache_read + cache_creation from every SDKAssistantMessage.message.usage (Anthropic-native per-call breakdown) and use it as the top-priority usedTokens source, emit mid-turn ring updates on each assistant frame, and drop the session-cumulative fallback entirely.

Migration: existing ledger files are polluted and can't be repaired in-place. CostTrackerLive writes a .schema-v2 sentinel in the usage dir on boot; when absent it wipes the known ledger files (session_*.json, YYYY-MM.json, alltime.json) and writes the sentinel. Stray non-ledger files are left alone. Bumping LEDGER_SCHEMA_VERSION is the single line needed for future reducer-incompatible changes.

Existing threads: context-window.updated activities sit in the orchestration event log per-thread. The ring reads the latest such activity, so existing threads keep their pre-fix (inflated) values until a new turn lands. New chats → correct immediately. Old threads → self-heal on next turn.

Files

• apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts — turn-final filter + model slug normalisation.
• apps/server/src/provider/Layers/ClaudeAdapter.ts — usedTokens = input-side; per-call capture from SDKAssistantMessage.message.usage; priority for lastApiCallInputSide.
• apps/server/src/provider/Layers/CodexAdapter.ts — usedTokens = last.inputTokens + last.cachedInputTokens.
• apps/server/src/cost/Layers/CostTracker.ts — schema sentinel + first-boot wipe.
• apps/web/src/lib/contextWindow.ts — carry through cacheCreationInputTokens / lastCacheCreationInputTokens.
• packages/contracts/src/providerRuntime.ts — JSDoc for ThreadTokenUsageSnapshot (two dimensions, turn-final signal).
• apps/web/src/store.ts + apps/web/src/components/ChatView.tsx — stop-button reconciliation.
• apps/web/src/lib/costQuery.ts + apps/server/src/cost/Reducer.ts — bot-review cleanups.

Test plan

• apps/server cost + adapter + ingestion tests — 206/206 pass (+3 new for Opus fix)
• apps/web — 908/908 pass
• packages/shared — 126/126 pass
• Typecheck clean
• oxlint clean on changed files
• Manual: send a message, wait for model done, confirm stop button disappears immediately
• Manual: Opus multi-call turn — confirm context ring tracks real prompt size, not a number that grows with each turn
• Manual: long-output Claude turn — confirm ring stays within reasonable bounds (excludes output)
• Manual: send several turns with Claude — confirm turnCount matches user-visible turn count (not 3-10× higher)
• Manual: confirm first boot writes .schema-v2 sentinel in <T3CODE_HOME>/<state>/usage/ and wipes existing ledger files; second boot leaves them intact

Migration note for users

On first server boot after merging, the usage ledger at <T3CODE_HOME>/<state>/usage/ is wiped (session + month + all-time files) to clear totals polluted by the pre-fix reducer. A .schema-v2 sentinel is written to prevent re-wipes. Month + all-time totals rebuild from subsequent turns; per-thread session files show $0/0 until a new turn lands.

Existing thread rings may keep their old wrong values until the next turn generates a new activity.

🤖 Generated with Claude Code

Note

Add per-turn cost ledger, accurate context-window ring, and stop-button guard for Claude/Codex

• Adds a CostTrackerLive service that atomically persists per-session, per-month (local timezone), and all-time cost ledgers as JSON files under usageDir, exposed via GET /api/cost/summary.
• Adds a pricing.ts module in packages/shared with model pricing for Claude and Codex models, computeTurnCost, and formatUsd for UI display.
• Reworks ClaudeAdapter and CodexAdapter to report usedTokens as input-side tokens only (not including output), emit mid-turn thread.token-usage.updated events from assistant frames, and include per-class deltas (last* fields) on turn completion.
• Adds a CostMeter ring in the chat composer footer showing session and month-to-date spend with a per-model breakdown popover, invalidating on each context-window.updated activity.
• ProviderRuntimeIngestion now records costs to CostTracker only for turn-final token-usage events (those with last* fields); mid-turn snapshots are ignored.
• Fixes ChatView.onInterrupt to skip dispatching a stop command when the latest turn is already in a terminal state (completed, interrupted, or error).
• Behavioral Change: usedTokens in token-usage snapshots now reflects input-side tokens only and is no longer capped to maxTokens; totalProcessedTokens carries the full cumulative billing total.

^{Macroscope summarized bd0fc3b.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: cca1ac92-e77a-4f6b-8156-6c4070c32b09

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a significant new cost tracking feature with server-side ledger, pricing calculations, HTTP endpoints, and UI components. Unresolved HIGH severity review comments identify potential bugs in the Codex adapter token calculation (NaN from undefined addition) that could cause incorrect cost reporting. The billing/cost tracking nature of these changes combined with the identified bugs warrant careful human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[Olympicx]

updated the PR

[cursor]

Missing undefined guard in Codex token usage fallback

Medium Severity

The old code guarded against usage.last.totalTokens being undefined with an explicit usedTokens === undefined || usedTokens <= 0 check. The new code removed the undefined check. When inputSideTokens is 0, usedTokens falls back to usage.last.totalTokens. If that value is undefined, the guard usedTokens <= 0 evaluates to false (because undefined coerces to NaN, and NaN <= 0 is false), so the function proceeds to return a snapshot with usedTokens: undefined instead of returning undefined to signal no valid usage data.

 

^{Reviewed by Cursor Bugbot for commit b027c89. Configure here.}

[cursor]

NaN from undefined addition defeats input-side-only fix

High Severity

In normalizeCodexTokenUsage, inputTokens and cachedInputTokens can be undefined (the code itself checks !== undefined when conditionally spreading them into the snapshot a few lines later). Adding undefined + undefined or number + undefined produces NaN, and NaN > 0 is false, so the fallback to usage.last.totalTokens (which includes output + reasoning tokens) silently kicks in — exactly the over-reporting this PR is meant to fix. The values need a nullish coalesce to zero before addition.

 

^{Reviewed by Cursor Bugbot for commit 1790ec5. Configure here.}

[cursor]

Unused emptyBucketFile function is dead code

Low Severity

The emptyBucketFile helper is defined inside the make generator but never called anywhere. The loadFile function already handles missing files via sanitizePersistedFile, which returns an empty bucket when the raw input is undefined. This is dead code that can be removed.

 

^{Reviewed by Cursor Bugbot for commit 1790ec5. Configure here.}

[macroscopeapp]

🟢 Low Layers/ClaudeAdapter.ts:517

Line 520 uses ?? so when input.taskSnapshot.usedTokens is 0, the code keeps that 0 instead of falling through to deltaUsedFallback. The comment on lines 521–524 states the intent is to "never emit 0 for a turn that clearly had activity", but ?? only falls back on undefined/null, not on 0. If the SDK reports usedTokens: 0 while cumulative indicates activity, usedTokens becomes 0, violating the stated intent. Consider using a ternary that checks > 0 instead of ??.

-  const usedTokens =
-    input.lastApiCallInputSide !== undefined && input.lastApiCallInputSide > 0
-      ? input.lastApiCallInputSide
-      : (input.taskSnapshot?.usedTokens ?? deltaUsedFallback);
+  const usedTokens =
+    input.lastApiCallInputSide !== undefined && input.lastApiCallInputSide > 0
+      ? input.lastApiCallInputSide
+      : (input.taskSnapshot?.usedTokens ?? deltaUsedFallback) || deltaUsedFallback;

🤖 Copy this AI Prompt to have your agent fix this:

In file apps/server/src/provider/Layers/ClaudeAdapter.ts around lines 517-520:

Line 520 uses `??` so when `input.taskSnapshot.usedTokens` is `0`, the code keeps that `0` instead of falling through to `deltaUsedFallback`. The comment on lines 521–524 states the intent is to "never emit 0 for a turn that clearly had activity", but `??` only falls back on `undefined`/`null`, not on `0`. If the SDK reports `usedTokens: 0` while `cumulative` indicates activity, `usedTokens` becomes `0`, violating the stated intent. Consider using a ternary that checks `> 0` instead of `??`.

Evidence trail:
apps/server/src/provider/Layers/ClaudeAdapter.ts lines 505-525 at REVIEWED_COMMIT. Line 520 shows `(input.taskSnapshot?.usedTokens ?? deltaUsedFallback)` using nullish coalescing. Lines 521-524 contain the comment stating "so we never emit 0 for a turn that clearly had activity". Line 505-506 shows `deltaUsedFallback = lastInputSideTokens > 0 ? lastInputSideTokens : cumulative.totalTokens` which would provide a non-zero fallback when cumulative indicates activity.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

There are 5 total unresolved issues (including 3 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit bd0fc3b. Configure here.}

[cursor]

Duplicate identical functions in same file

Low Severity

sanitizeNumber and finiteNonNeg are identical functions defined in the same file — both accept unknown, check for a finite non-negative number, and return 0 otherwise. One of them can be removed and all call sites pointed at the surviving function.

Additional Locations (1)

• apps/server/src/cost/Reducer.ts#L21-L24

 

^{Reviewed by Cursor Bugbot for commit bd0fc3b. Configure here.}

[cursor]

Stale monthKey in shared singleton constant

Low Severity

EMPTY_COST_SUMMARY computes monthKey via monthKeyNow() once at module-load time and reuses it as a frozen constant. If the browser tab stays open across a month boundary, the placeholder and fallback monthKey becomes stale (e.g., shows "2026-03" in April). Converting EMPTY_COST_SUMMARY to a function or computing monthKey lazily would avoid the stale value.

 

^{Reviewed by Cursor Bugbot for commit bd0fc3b. Configure here.}