refactor(usage): transcript readers come from their drivers

[juliusmarminge]

UsageService hard-coded every provider: it decoded Claude and Codex settings itself, resolved each transcript home, and the JSONL engine branched on provider === "codex" | "grok". Adding a provider meant editing the aggregator.

• ProviderDriver gains an optional usage reader, a discriminated union (transcripts | scan) defined in provider-core/server/usage, with its own environment (UsageR) so UsageService doesn't require every driver's creation environment.
• The JSONL engine takes a TranscriptUsageFormat (field selection, line prefilter, parsers, optional resumable state with a schema).
• Grok's format and GROK_HOME resolution move into provider-grok. Claude's and Codex's sit next to their drivers until those become packages.
• Codex shared-session dedupe is a format flag (sharedSessionsAcrossFiles).
• The scan cache's cs field stores the format's schema-encoded state. It is byte-identical to the previous Codex state, so existing caches still resume.
• Driver order for usage lives in BUILT_IN_USAGE_DRIVERS to keep today's result order (Claude, Codex, Grok, …).

No behavior change: UsageService.test.ts changed only in wiring and imports.

🤖 Generated with Claude Code (Claude Opus 5.5, Claude Code harness)

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	20.9 KiB	20.9 KiB	0 B (0.0%)	29.3 KiB	✅
Codex	Live turn messages	2	2	0 (0.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	−24 B (−0.5%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Claude	Live turn WebSocket wire	1.2 KiB	1.2 KiB	−24 B (−2.0%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.2 KiB	21.2 KiB	−41 B (−0.2%)	29.3 KiB	✅
Claude	Live turn messages	2	1	−1 (−50.0%)	8	✅

Baseline: 454b94a · PR result: 6c36724 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This is a broad production usage-pipeline refactor that introduces a new provider-core reader contract, moves three transcript implementations, generalizes resumable parsing and cache state, and rewires UsageService dispatch. The tests support the intended behavior, but the shared infrastructure and persisted-cache boundary make the change too substantial for automatic approval.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Team
• Run ID: f3654a44-46bd-4d09-9cd1-4a6133683d44

---

📥 Commits

Reviewing files that changed from the base of the PR and between 9291a7b and 6c36724.

---

📒 Files selected for processing (5)

• apps/server/src/provider/Drivers/claudeUsage.ts
• apps/server/src/provider/Drivers/codexUsage.ts
• apps/server/src/usage/UsageService.test.ts
• apps/server/src/usage/UsageService.ts
• packages/provider-core/src/server/usage.ts

---

🚧 Files skipped from review as they are similar to previous changes (1)

• apps/server/src/usage/UsageService.test.ts

---

Limit details: You’ve used all 10 included reviews currently available.

---

---

📝 Walkthrough

Walkthrough

Provider-core adds shared provider usage-reader contracts. Claude, Codex, and Grok add transcript readers. The server discovers readers through built-in drivers and uses their formats for transcript parsing, resumable state, cache decoding, and shared-session deduplication.

Changes

Provider usage reader integration

Layer / File(s)	Summary
Usage contracts and shared types packages/provider-core/src/server/usage.ts, packages/provider-core/src/server/driver.ts, packages/provider-core/package.json, apps/server/src/usage/*	Provider-core adds usage records, transcript formats, scan contracts, and reader environment types. Existing usage consumers import shared usage types from provider-core.
Provider transcript readers apps/server/src/provider/Drivers/*Usage*, apps/server/src/provider/Drivers/{ClaudeDriver,CodexDriver}.ts, packages/provider-grok/src/server/*, packages/provider-grok/package.json	Claude, Codex, and Grok add transcript parsers and directory readers. Their drivers expose those readers, and tests cover provider-specific parsing and token or cost handling.
Generic transcript parsing and cache apps/server/src/usage/usageTranscriptReader*, apps/server/src/usage/usageScanCache*, apps/server/src/usage/usageTestFormats.ts, apps/server/src/usage/usageTranscripts*	The transcript reader and cache accept provider-supplied formats and generic persisted state. Tests use format objects; the previous shared transcript parser and its tests are removed.
Usage service integration and deduplication apps/server/src/provider/builtInDrivers.ts, apps/server/src/usage/UsageService*	UsageService resolves registered readers and passes their formats to scanning and cache decoding. Cross-file deduplication uses reader-declared shared sessions.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Refactor

Sequence Diagram(s)

sequenceDiagram
  participant UsageService
  participant BUILT_IN_USAGE_DRIVERS
  participant ProviderUsageReader
  participant readTranscriptRecords
  UsageService->>BUILT_IN_USAGE_DRIVERS: enumerate usage readers
  UsageService->>ProviderUsageReader: resolve transcript directories
  UsageService->>readTranscriptRecords: parse files using reader formats

Loading

---

Merge Risk: ⚪ Minimal · up to 6c367

No identified issue blocks merging this change after normal checks.

Pre-merge checks | 3 | 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check		The description explains the problem and the main implementation changes, but it does not provide the required Scope and approval information or focused verification results. It also omits the templat…	Add the required Problem, Change, Scope and approval, and Verification sections. Link the triaged issue or maintainer approval, explain any approval exemption if applicable, and list focused tests or manual checks with observed results and …

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check		The title clearly summarizes the primary change: transcript readers now come from provider drivers.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

---

Full details: Description check

Explanation

The description explains the problem and the main implementation changes, but it does not provide the required Scope and approval information or focused verification results. It also omits the template section headings.

Resolution

Add the required Problem, Change, Scope and approval, and Verification sections. Link the triaged issue or maintainer approval, explain any approval exemption if applicable, and list focused tests or manual checks with observed results and any checks not run.

---

---

• Fix all pre-merge checks with AI

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

---

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Usage-based review receipt

• Mode: Continue automatically
• Reviewed files: 4
• Charged: $1.00
• View usage details

Note

This review was completed with usage-based billing: files reviewed beyond your plan's included limits are billed at $0.25/file. View usage-based billing.

---

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

[juliusmarminge]

Adversarial review (3 reviewers, one per layer group) found no blockers. Two behavior changes against main are fixed in this push:

• refactor(usage): transcript readers come from their drivers #17576: the generic instance builder dropped instances whose config doesn't decode. On main only Claude and Codex did that. Grok and Antigravity read history by home or profile alone, so a malformed config hid their usage. Instances now reach every reader with config: undefined. Claude and Codex skip them as before, while Grok and Antigravity read them. A regression case in UsageService.test.ts fails without the fix (46 vs 59 tokens).
• refactor(usage): Cursor account usage comes from provider-cursor #17578: the Cursor scan re-read settings instead of using the snapshot the rest of the read (and the in-flight dedupe key) used, and a failed re-read looked like "usage is off". Scan readers now get the read's settings snapshot.

Also verified: the parsers, prefilters and field selection match main. The Codex cs cache is byte-identical. Cursor TTL, refresh dedupe, persistence and messages are unchanged, and CursorKeychain is built once (proven by test). OpenCode and Antigravity roots, ordering and aliased-dir dedupe are unchanged.