Skip to content

Commit e73dadd

Browse files
jay-tauCopilot
andcommitted
feat(adapter/copilot): switch default source to per-session events.jsonl with billing-field-aware dispatch
Closes ccusage#1174. Replaces the opt-in OTel file-export reader (`~/.copilot/otel/*.jsonl`, empty unless the user explicitly enables OpenTelemetry) with the per-session event stream the Copilot CLI now writes by default at `~/.copilot/session-state/<sessionId>/events.jsonl`. After this commit `ccusage copilot daily` works without any extra setup on every Copilot CLI install that ships the session-state schema. Bills correctly across GitHub's June 1, 2026 cutover from premium-request billing to AI Credits billing. The mode dispatch is **billing-field-aware (not date-based)** — the loader keys off `has_aiu` / `has_premium_data` rather than `entry.timestamp`, so backfills and future billing channels route correctly without code changes: | `--mode` | AIU present | AIU absent, premium present | AIU absent, premium absent | | --------------------- | --------------- | --------------------------- | -------------------------- | | `auto` *(default)* | credits × $0.01 | requests.cost × $0.04 | token-priced (LiteLLM) | | `display` | credits × $0.01 | requests.cost × $0.04 | 0 | | `calculate` | token-priced | token-priced | token-priced | Highlights: * **Tolerant deserializers** for `requests.cost` (`Option<f64>`, accept int+float, reject NaN/±Inf/negative). The previous u64 type silently dropped fractional values like Opus 4.7's 7.5×-multiplier rows — recovering ~73M tokens / $6.68 of real local data in this fix alone. * **Content-based dedup keys for credit-only rows** (`credit-shutdown:{session_id}:{model}:{naiu}`, event_id deliberately omitted) so paired AIU snapshots with distinct event_ids collapse rather than double-counting. Token-bearing rows keep the event_id key for the opposite reason — coincidental count-collisions across resumes must not collapse to one row. See adapter README "Resumed sessions and dedup-key design". * **Date filter runs BEFORE the HashMap dedup collapse** to prevent an out-of-range credit-only twin from evicting an in-range row in `HashMap::insert` last-wins. Pinned by `date_filter_runs_before_credit_only_dedup_collapse_to_preserve_in_range_row`. * **Per-file error isolation** so one locked / corrupted / partially-written session-state file does not abort the whole report. Tested with a Unix `chmod 0o000` fixture that genuinely exercises the `File::open` error path. * **Streaming `BufReader::split(b'\n')`** parser with bounded memory on 69MB+ files heavy users accumulate. Substring pre-filter on `SESSION_SHUTDOWN_TYPE` short-circuits non-shutdown lines before serde. * **Non-UTF-8 safe path/env handling** via `var_os` (not `var`), override-is-authoritative semantics (no silent fallback to `~/.copilot` when `COPILOT_CONFIG_DIR` is set). * **Legacy OTel env-var deprecation warning** — users who had `COPILOT_OTEL_FILE_EXPORTER_PATH` / `COPILOT_OTEL_DEDUP` / `COPILOT_PREFER_OTEL` set get a one-shot stderr notice that they're now inert. Process-wide `OnceLock` keeps it to one emission. `LOG_LEVEL=0` silences. The legacy OTel parser is fully removed; the `otel/` directory is intentionally not enumerated even when present on disk (pinned by `ignores_otel_directory_even_when_present`). CLI wiring: adds `copilot_options` block with a Copilot-specific `--mode` description that names the billing fields. Wires `copilot_combined_options` into the `copilot daily|monthly|session` subcommands. Adapter README (`adapter/copilot/README.md`) documents the session-state schema, token mapping, reasoning-token rules, skip rule, dedup-key design, date-filter-before-dedup invariant, cost-mode dispatch table, and env-var deprecation. Co-authored-by: Copilot <[email protected]>
1 parent 31e084a commit e73dadd

8 files changed

Lines changed: 3879 additions & 656 deletions

File tree

‎rust/crates/ccusage-cli/src/cli-commands.json‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"claude_daily_options": ["shared_claude_options", "daily_options"],
66
"claude_session_options": ["shared_claude_options", "session_options"],
77
"claude_weekly_options": ["shared_claude_options", "weekly_options"],
8+
"copilot_combined_options": ["agent_options", "copilot_options"],
89
"openclaw_combined_options": ["agent_options", "openclaw_options"],
910
"pi_combined_options": ["agent_options", "pi_options"]
1011
},
@@ -567,19 +568,19 @@
567568
"path": ["copilot", "daily"],
568569
"description": "Show GitHub Copilot CLI usage grouped by date",
569570
"usage": "ccusage copilot daily <OPTIONS>",
570-
"options": "agent_options"
571+
"options": "copilot_combined_options"
571572
},
572573
{
573574
"path": ["copilot", "monthly"],
574575
"description": "Show GitHub Copilot CLI usage grouped by month",
575576
"usage": "ccusage copilot monthly <OPTIONS>",
576-
"options": "agent_options"
577+
"options": "copilot_combined_options"
577578
},
578579
{
579580
"path": ["copilot", "session"],
580581
"description": "Show GitHub Copilot CLI usage grouped by session",
581582
"usage": "ccusage copilot session <OPTIONS>",
582-
"options": "agent_options"
583+
"options": "copilot_combined_options"
583584
},
584585
{
585586
"path": ["gemini"],

‎rust/crates/ccusage-cli/src/cli-help.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -238,6 +238,14 @@
238238
"description": "Comma-separated project aliases (e.g., 'ccusage=Usage Tracker,myproject=My Project')"
239239
}
240240
],
241+
"copilot_options": [
242+
{
243+
"flags": "-m, --mode [mode]",
244+
"description": "Cost calculation mode (auto = billing-field-aware true bill; display = source precomputed only; calculate = LiteLLM token pricing)",
245+
"default": "auto",
246+
"choices": ["auto", "calculate", "display"]
247+
}
248+
],
241249
"pi_options": [
242250
{
243251
"flags": "--pi-path <pi-path>",

‎rust/crates/ccusage-test-support/src/lib.rs‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -17,18 +17,26 @@ fn env_lock() -> MutexGuard<'static, ()> {
1717
}
1818

1919
pub struct EnvVarGuard {
20-
key: &'static str,
21-
previous: Option<OsString>,
20+
previous: Vec<(&'static str, Option<OsString>)>,
2221
_guard: MutexGuard<'static, ()>,
2322
}
2423

2524
impl EnvVarGuard {
2625
pub fn set(key: &'static str, value: impl AsRef<OsStr>) -> Self {
26+
Self::set_many(&[(key, Some(value.as_ref()))])
27+
}
28+
29+
pub fn set_many(overrides: &[(&'static str, Option<&OsStr>)]) -> Self {
2730
let guard = env_lock();
28-
let previous = std::env::var_os(key);
29-
unsafe { std::env::set_var(key, value) };
31+
let mut previous = Vec::with_capacity(overrides.len());
32+
for (key, value) in overrides {
33+
previous.push((*key, std::env::var_os(key)));
34+
match value {
35+
Some(value) => unsafe { std::env::set_var(key, value) },
36+
None => unsafe { std::env::remove_var(key) },
37+
}
38+
}
3039
Self {
31-
key,
3240
previous,
3341
_guard: guard,
3442
}
@@ -37,9 +45,11 @@ impl EnvVarGuard {
3745

3846
impl Drop for EnvVarGuard {
3947
fn drop(&mut self) {
40-
match self.previous.take() {
41-
Some(value) => unsafe { std::env::set_var(self.key, value) },
42-
None => unsafe { std::env::remove_var(self.key) },
48+
for (key, value) in self.previous.drain(..).rev() {
49+
match value {
50+
Some(value) => unsafe { std::env::set_var(key, value) },
51+
None => unsafe { std::env::remove_var(key) },
52+
}
4353
}
4454
}
4555
}
Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
# GitHub Copilot CLI Source
2+
3+
Data source:
4+
5+
```text
6+
${COPILOT_CONFIG_DIR:-~/.copilot}/session-state/<sessionId>/events.jsonl
7+
```
8+
9+
The Copilot CLI writes `session-state/<uuid>/events.jsonl` automatically during each CLI session, appending a `session.shutdown` event on graceful exit.
10+
11+
## session-state schema
12+
13+
Relevant JSONL event:
14+
15+
- `type === "session.shutdown"` (other event types — `tool.execution_start`,
16+
`assistant.message`, etc. — may contain the literal string
17+
`"session.shutdown"` inside `arguments.command` or `content`; the parser
18+
requires the top-level `type` field after JSON parsing, never trusts the
19+
substring alone).
20+
- `id` — per-event UUID, used as part of the dedup key
21+
(`shutdown:{session_id}:{event.id}:{model}` for token-bearing rows;
22+
`session_id` is prefixed as defense-in-depth against a future Copilot
23+
CLI that might scope event ids per-session).
24+
- `timestamp` — RFC3339 with ms (`"2026-05-02T15:27:09.013Z"`).
25+
- `data.modelMetrics` — map keyed by Copilot model id; each value carries
26+
`usage.{inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens,
27+
reasoningTokens}` and `requests.{count, cost}`.
28+
29+
### Token mapping (session-state)
30+
31+
`usage.inputTokens` in this schema is inclusive of **both** `cacheReadTokens`
32+
and `cacheWriteTokens`.
33+
34+
| Field on `LoadedEntry` | Source |
35+
| -------------------------------- | --------------------------------------------------------------------------- |
36+
| `input_tokens` | `usage.inputTokens − usage.cacheReadTokens − usage.cacheWriteTokens` (saturating) |
37+
| `output_tokens` | `usage.outputTokens` |
38+
| `cache_read_tokens` | `usage.cacheReadTokens` |
39+
| `cache_creation_input_tokens` | `usage.cacheWriteTokens` |
40+
| `reasoning_output_tokens` | provider-dependent — see below |
41+
42+
`data.tokenDetails` exists in the schema but is **intentionally not used as a
43+
source**: empirical verification showed `usage.*` and `tokenDetails.*` are
44+
independent snapshots that diverge in ~31% of resumed-session rows. We use
45+
`usage.*` consistently across all four token fields.
46+
47+
### Reasoning tokens
48+
49+
Provider conventions differ. Verified locally across the full session-state
50+
corpus:
51+
52+
| Provider | Convention | Rule |
53+
| ------------------------- | ------------------------------------------------------- | --------------------------------- |
54+
| `claude-*` (Anthropic) | Extended-thinking tokens included in `outputTokens` | `reasoning_output_tokens = 0` |
55+
| `gpt-*` (OpenAI) | `reasoning_tokens` is a subset of `output_tokens` | `reasoning_output_tokens = 0` |
56+
| `gemini-*` (Google) | `thoughtsTokenCount` is a separate field from output | `reasoning_output_tokens = usage.reasoningTokens` |
57+
| Anything else (default) | Treated like Claude/GPT — the subset rule cannot over-count | `reasoning_output_tokens = 0` |
58+
59+
### Skip rule
60+
61+
A `modelMetrics` row is skipped when **all** of the following are true:
62+
63+
1. All non-reasoning token fields are zero (`input`, `output`, `cache_read`,
64+
`cache_write`), AND for Gemini models `reasoning_tokens` is also zero.
65+
2. `requests.count` is zero.
66+
3. `metrics.totalNanoAiu` is absent or zero.
67+
68+
Matches PR #957's `data-loader.ts` inline skip-row predicate, extended with the AIU
69+
carve-out so that real-data credit-only rows (zero tokens, zero requests,
70+
non-zero `totalNanoAiu`) survive. The reasoning-token clause is
71+
provider-gated to stay symmetric with `build_session_state_entry`: for
72+
Gemini the builder preserves `reasoning_tokens` verbatim (separate field
73+
from output), so the skip rule counts it as usage; for OpenAI/Anthropic
74+
the builder discards it (already subsumed into `output_tokens`), so the
75+
skip rule ignores it to avoid surfacing all-zero phantom rows. See
76+
`keeps_zero_token_row_when_per_model_total_nano_aiu_is_present`,
77+
`keeps_gemini_row_with_only_reasoning_tokens`, and
78+
`skips_non_gemini_row_with_only_reasoning_tokens` for the matching
79+
regressions.
80+
81+
### Resumed sessions and dedup-key design
82+
83+
A single `events.jsonl` may contain multiple `session.shutdown` events (the user
84+
re-opened the same session UUID multiple times). Each shutdown is a
85+
**per-process snapshot** — token counts are NOT cumulative across resumes. The
86+
parser emits one entry per `(session_id, event.id, model)` triple so the
87+
resumed-session totals are summed correctly at report time.
88+
89+
The dedup-key selector chooses between two key shapes for each surviving row,
90+
and the two shapes deliberately encode **opposite beliefs about what a duplicate
91+
shutdown means** — because real-data shapes differ between the two paths:
92+
93+
- **Token-bearing / priced rows** key on `shutdown:{session_id}:{event_id}:{model}`.
94+
Two shutdowns with distinct event ids are treated as distinct charges (sum at
95+
report time), even if their token counts happen to coincide. This is correct
96+
because per-process snapshots commonly produce near-identical counts when a
97+
user resumes a similar workload, and treating them as duplicates would
98+
silently under-count usage. The `session_id` prefix is defense-in-depth:
99+
today every observed `event.id` is a globally-unique UUID, but prefixing
100+
with `session_id` guards against a hypothetical future Copilot CLI that
101+
scopes event ids per-session, which would otherwise silently collapse
102+
distinct sessions' rows in the loader's final `HashMap`-keyed dedup. Pinned
103+
by `token_bearing_rows_keep_event_id_dedup_key_not_content_based` and
104+
`treats_resumed_session_shutdowns_as_distinct_entries`.
105+
- **Credit-only zero-token rows** key on
106+
`credit-shutdown:{session_id}:{model}:{naiu}` — **deliberately omitting
107+
`event_id`**. The loader's `HashMap::insert` collapse is last-wins, so
108+
duplicate AIU snapshots with identical `totalNanoAiu` collapse instead of
109+
double-counting. Pinned by
110+
`auto_mode_dedupes_duplicate_credit_only_rows_within_same_session` and
111+
`credit_only_rows_with_identical_naiu_but_distinct_event_ids_are_treated_as_duplicates`.
112+
113+
**The asymmetry is intentional.** Token rows trust event ids because their
114+
data shape (per-process snapshots) makes coincidence-collision a far more
115+
likely failure mode than missed-duplicate. Credit-only rows distrust event
116+
ids because paired snapshots make the opposite true.
117+
118+
The aggregate-credit synthetic entry (emitted only when no per-model row
119+
carries a priced billing signal — see `parse_session_state_file`'s
120+
suppression guard) uses the same content-based key family
121+
(`credit-aggregate:{session_id}:{nano_aiu}`) to mirror the credit-only
122+
"paired snapshot" semantics.
123+
124+
### Date filter must run before dedup
125+
126+
The credit-only key shape above (which deliberately omits `event_id`) makes
127+
the loader's `HashMap`-based dedup collapse **last-wins by parse order**:
128+
two credit-only rows in the same session with the same `(model, naiu)` but
129+
distinct timestamps collapse into whichever was inserted last. That's the
130+
intended behaviour for paired snapshots inside an active date range — but
131+
if the two rows straddle a `--since` / `--until` boundary, applying the
132+
date filter **after** the dedup HashMap could keep the out-of-range row,
133+
drop it on the filter, and silently lose the in-range row's credits
134+
entirely.
135+
136+
The loader therefore applies the `--since` / `--until` filter to the
137+
`CopilotUsageEntry` vector **before** the dedup `HashMap::insert` collapse.
138+
Each surviving entry already satisfies the date range, so the collapse can
139+
never pick an out-of-range winner. Token-bearing rows (event-id keyed) are
140+
immune to this ordering bug, but the filter applies uniformly to keep the
141+
loader-layer surface symmetric across both key families. The downstream
142+
`filter_loaded_entries_by_date` calls in `copilot::run` and the cross-source
143+
aggregator (`adapter::all::loader`) remain in place as defense-in-depth
144+
no-ops once the loader has filtered, and to keep the user-facing
145+
`LoadedEntry` surface uniform with the other adapters. Pinned by
146+
`date_filter_runs_before_credit_only_dedup_collapse_to_preserve_in_range_row`.
147+
148+
## Model normalization
149+
150+
The adapter ships `normalize_copilot_model()` for pricing-lookup callers. The
151+
function is applied **only inside `loader.rs::usage_entry_to_loaded`** for both
152+
`calculate_cost_for_usage` and `missing_pricing_model_for_usage` call sites —
153+
the entry itself keeps the raw model name so reports, JSON and `modelsUsed`
154+
preserve source fidelity.
155+
156+
Rules:
157+
158+
1. Strip Copilot routing suffixes in this order: `-1m-internal`, `-internal`,
159+
`-xhigh`, `-high`, `-1m`. Required because
160+
`pricing::suffix_starts_with_numeric_model_version` rejects suffixes that
161+
begin with another digit, so without stripping the `-1m` family of variants
162+
no pricing entry resolves.
163+
2. For `claude-*` names, convert version-number dots to dashes (e.g.
164+
`claude-opus-4.7` → `claude-opus-4-7`). Matches the canonical LiteLLM keys.
165+
3. GPT names pass through unchanged — LiteLLM keeps them dotted.
166+
4. Unknown prefixes pass through unchanged.
167+
168+
## Cost modes
169+
170+
| `--mode` | Behavior for Copilot |
171+
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
172+
| `auto` | True bill, billing-field-aware: AIU when present (typically post-cutover) → premium-requests × $0.04 when present (typically pre-cutover) → token-priced via LiteLLM (neither billing field). The default. Free-tier rows (`requests.cost == 0`) bill as $0. |
173+
| `display`| Source-precomputed only: AIU → premium-requests → $0. No token-priced fallback. |
174+
| `calculate` / `api` | Always token-priced via LiteLLM (`normalize_copilot_model()` applied at both `calculate_cost_for_usage` and `missing_pricing_model_for_usage` call sites). |
175+
176+
The billing-field-aware default reflects that GitHub Copilot switched billing
177+
models on June 1, 2026: pre-cutover sessions were billed in "premium requests"
178+
with per-model multipliers at $0.04/overage-request, and post-cutover sessions
179+
bill in AI Units (1 AIU = 1 credit = $0.01). The Copilot CLI records each
180+
session's own billing data, so `auto` surfaces what GitHub actually charged
181+
you for that session.
182+
183+
**The dispatch keys off field presence, not the cutover date.** The
184+
loader never compares `entry.timestamp` to June 1, 2026 — it just asks
185+
"did this row ship `totalNanoAiu`?" and picks AIU billing if so. The cutover
186+
date is the *why* behind the two billing columns existing in the wire
187+
schema; it is not a branching condition in the code. This shape is more
188+
robust than a date check: it correctly handles a pre-cutover session that
189+
happens to ship AIU (rare but possible if GitHub ever backfills) and
190+
generalises to a hypothetical future third billing channel without a
191+
schema-version migration.
192+
193+
`PREMIUM_REQUEST_COST_USD = $0.04` and `AI_CREDIT_COST_USD = $0.01` are
194+
GitHub's published external pricing rates, not contracts encoded in the
195+
CLI's wire format. If GitHub adjusts either rate, `auto`/`display` will
196+
mis-bill until the constants are updated. The mitigation users have today
197+
is `--mode api` (alias of `calculate`): that path bills from token counts
198+
via LiteLLM and does not depend on either constant.
199+
200+
`LoadedEntry.credits` is populated independently of `--mode` whenever the
201+
source carried `totalNanoAiu`, so JSON consumers see the raw credit count
202+
regardless of mode selection.
203+
204+
The `missing_pricing_model` warning never fires for the AIU and premium-request
205+
branches of `auto`/`display` because they don't consult LiteLLM — those
206+
branches return `None` directly. The shared
207+
`cost.rs::missing_pricing_model_for_usage` early-return remains intact so other
208+
adapters still see legitimate missing-pricing warnings when their token-pricing
209+
fallback can't resolve a model.
210+
211+
## Environment variables
212+
213+
| Variable | Effect |
214+
| -------------------- | --------------------------------------------------------------- |
215+
| `COPILOT_CONFIG_DIR` | Override the base Copilot directory (defaults to `~/.copilot`). |
216+
217+
## Legacy OpenTelemetry environment variables
218+
219+
ccusage no longer reads OpenTelemetry exports — the production loader uses
220+
the session-state source described above directly. The legacy OTel
221+
environment variables (`COPILOT_OTEL_FILE_EXPORTER_PATH`, `COPILOT_OTEL_DEDUP`,
222+
`COPILOT_PREFER_OTEL`) are inert; if any of them are set when `ccusage copilot`
223+
runs, a one-shot stderr warning explains they are ignored. Unset them, or set
224+
`LOG_LEVEL=0`, to silence the warning.

0 commit comments

Comments
 (0)