@ponbac/token-ledger 0.9.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +146 -29
  2. package/dist/main.js +1488 -229
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -6,9 +6,10 @@ An Effect v4 core reads provider histories and produces structured reports. An E
6
6
  CLI handles discovery, configuration, and terminal/CSV/JSON output. You do not need
7
7
  T3 Code, provider API keys, or a company dashboard to use it.
8
8
 
9
- **Dollar figures are API-equivalent estimates, not subscription expenses.** Reports
10
- keep input, cache-read, cache-write, and output tokens separate. Unknown model or
11
- cache prices stay unknown; the known subtotal remains available.
9
+ **Dollar figures are API-equivalent estimates, not subscription expenses.** Requests
10
+ GitHub Copilot paid for are priced at Copilot's own AI credit rates. Reports keep input,
11
+ cache-read, cache-write, and output tokens separate. Unknown model or cache prices stay
12
+ unknown; the known subtotal remains available.
12
13
 
13
14
  ## Quick start
14
15
 
@@ -28,9 +29,11 @@ The default window is the current calendar month through today. `--since` and
28
29
  `--until` are inclusive local calendar days in the system time zone; select another
29
30
  IANA zone with `--time-zone`, such as `--time-zone Europe/Stockholm`. Days follow
30
31
  daylight saving time, so a day can last 23 or 25 hours. Read every
31
- supported source by omitting `--provider`. Copilot records nothing until its export
32
- is switched on: run [`copilot enable`](#enable-copilots-usage-export) before starting
33
- sessions; installing the CLI does not enable telemetry.
32
+ supported source by omitting `--provider`. Copilot CLI and VS Code's Copilot harness
33
+ keep their own session logs, which are read without setup. VS Code's Local harness and
34
+ inline chat record nothing until Copilot's export is switched on: run
35
+ [`copilot enable`](#enable-copilots-usage-export) before starting sessions; installing
36
+ the CLI does not enable telemetry.
34
37
 
35
38
  ```sh
36
39
  npx @ponbac/token-ledger@latest report --since 2026-09-01 --until 2026-09-30 --format csv > usage.csv
@@ -99,6 +102,7 @@ node packages/cli/dist/main.js report
99
102
  | Codex | `~/.codex/sessions` and `archived_sessions` | Rollout token events, model switches, session and working-directory metadata |
100
103
  | Claude Code | `~/.claude/projects` | Assistant usage records; repeated message blocks counted once |
101
104
  | Grok Build | `~/.grok/sessions/**/updates.jsonl` | Saved completed turns and their model breakdowns |
105
+ | Copilot sessions | `~/.copilot/session-state/*/events.jsonl` | Request usage and the workspace of Copilot CLI and VS Code Copilot harness runs |
102
106
  | Copilot CLI / VS Code Chat | `~/.copilot/otel` or `COPILOT_OTEL_FILE_EXPORTER_PATH` | JSONL request spans, VS Code inference events, and SQLite span exports |
103
107
  | Pi | `~/.pi/agent/sessions` or `PI_CODING_AGENT_SESSION_DIR` | Assistant messages on every branch, plus usage, compaction, and summary entries |
104
108
  | OpenCode | `~/.local/share/opencode` | Assistant messages in `opencode*.db` and legacy `storage/message` files |
@@ -128,20 +132,41 @@ keeps the server's stored OpenCode usage. A source directory holding no OpenCode
128
132
  all is reported as `missing`, which keeps stored usage too. Working directories
129
133
  OpenCode stored on Windows with forward slashes are matched as native paths.
130
134
 
131
- Models are reported under the ID OpenCode recorded, such as `claude-opus-4.5`, and priced
132
- by the public rate table; GitHub Copilot's dotted Claude IDs are not in it and stay unpriced
133
- unless configured under `prices`. OpenCode's own recorded costs are not used for estimates.
135
+ Models are reported under the ID OpenCode recorded, such as `claude-opus-4.5`. Requests on
136
+ the `github-copilot` route are priced with [Copilot's rate card](#prices-and-exports), and
137
+ other routes' by the public rate table, which prices a dotted Claude version as Anthropic's
138
+ hyphenated ID. OpenCode's own recorded costs are not used for estimates.
134
139
 
135
140
  `sync` names the subscription that paid for a request from the route OpenCode recorded:
136
141
  `github-copilot` requests bill to Copilot, and `openai` requests with a recorded cost of
137
142
  exactly zero to Codex, because OpenCode's ChatGPT sign-in clears every OpenAI model's
138
143
  rates. Other routes, OpenCode Zen and API keys among them, are API-equivalent estimates.
139
144
 
145
+ ### Copilot session logs
146
+
147
+ The Copilot runtime behind Copilot CLI and VS Code's Copilot harness, the default for new
148
+ VS Code chats since 1.143, keeps an event log per session in
149
+ `~/.copilot/session-state/<session>/events.jsonl` (`$COPILOT_HOME/session-state`). It
150
+ records each request's model and tokens whether or not an export is on, and the session's
151
+ working directory and GitHub repository, which name the project. Those logs also hold the
152
+ session's prompts, responses, and tool output: Token Ledger decodes only the session start
153
+ and usage events, and never reads the rest. Requests on your own key (BYOK) are not
154
+ Copilot's to bill and are left out of syncs, unless the local proxy routed them to a ChatGPT
155
+ plan; a report, which reads no proxy hints, counts them. A request also found in Copilot's export below is
156
+ counted once.
157
+
158
+ The Copilot harness runs in VS Code's Agent Host, which ignores the Chat export settings
159
+ below, so before session logs were read its requests went unrecorded. VS Code can also
160
+ export them through a device-wide `managed-settings.json`
161
+ ([`telemetry.filePath`](https://code.visualstudio.com/docs/agents/guides/monitoring-agents));
162
+ that file needs admin rights, turns off VS Code's Claude harness, and is not needed here.
163
+ Its export is read like the others when it is in the export folder.
164
+
140
165
  ### Enable Copilot's usage export
141
166
 
142
- Copilot writes no usage log until a local OpenTelemetry file export is switched on,
143
- and nothing is backfilled: sessions from before that are lost. One command switches
144
- it on for Copilot CLI and VS Code Copilot Chat:
167
+ VS Code's Local harness and inline chat write no usage log until a local OpenTelemetry
168
+ file export is switched on, and nothing is backfilled: sessions from before that are lost.
169
+ One command switches it on for Copilot CLI and VS Code Copilot Chat:
145
170
 
146
171
  ```sh
147
172
  npx @ponbac/token-ledger@latest copilot enable
@@ -441,29 +466,82 @@ overlapping files: the first configured source owns their project attribution.
441
466
 
442
467
  ## Prices and exports
443
468
 
444
- The CLI fetches the public LiteLLM model-rate table and caches the decoded snapshot
445
- for 24 hours under `$XDG_CACHE_HOME/token-ledger` (default `~/.cache/token-ledger`).
446
- Histories are processed locally. `report` only uses the network for this public
447
- pricing request; `sync` also uploads aggregated usage, as described below.
448
- `--offline` uses cached prices and config overrides. A failed refresh falls back to
449
- cached prices, with the snapshot timestamp retained in JSON.
450
-
451
- Override exact model IDs in USD per million tokens:
469
+ The CLI fetches the public LiteLLM model-rate table and caches the decoded snapshot, its
470
+ long-context tiers included, for 24 hours as `prices-v2.json` under
471
+ `$XDG_CACHE_HOME/token-ledger` (default `~/.cache/token-ledger`); earlier versions'
472
+ snapshots lack the tiers and are not reused. Histories are processed locally. `report` only
473
+ uses the network for this public pricing request; `sync` also uploads aggregated usage, as
474
+ described below. `--offline` uses cached prices and config overrides. A failed refresh falls
475
+ back to cached prices, with the snapshot timestamp retained in JSON.
476
+
477
+ Each request is priced on its own, before any aggregation:
478
+
479
+ - **Long context.** A request's context is its uncached input, cache reads, and cache
480
+ writes together. The whole request is priced at the highest tier whose threshold its
481
+ context exceeds: against a 272K tier, 272,000 tokens stay at the base rates and 272,001
482
+ are long. OpenAI's GPT-5.6 and GPT-6.x models cost twice as much above 272K (output 1.5
483
+ times); Claude Haiku 5.5 has a tier above 100K, and other Claude models none. A Grok turn
484
+ and Pi's usage for nested tool work can each sum several requests, so their context says
485
+ nothing about one request: they are priced at the base tier.
486
+ - **GitHub Copilot.** Requests Copilot paid for are priced with GitHub's own rate card,
487
+ checked in as [`copilot-rates.json`](packages/core/src/copilot-rates.json): Copilot's
488
+ requests unless a billing hint routes them to a ChatGPT plan, and OpenCode's and Pi's
489
+ `github-copilot` routes. Its rates are dated because GitHub changes them, as when GPT-5.6
490
+ Sol's launch discount ended after 2026-09-03, or Claude Sonnet 5.5's cached rate halved
491
+ from 2026-10-08; a request takes the rate in effect on its UTC day.
492
+ Next edit suggestions (`copilot-nes-*`, `nes-*`) and VS Code's helper model
493
+ (`gpt-4o-mini`, `gpt-4o-mini-*`) are free. A model the card lacks takes LiteLLM's
494
+ `github_copilot/` rates, then the vendor's. Entries marked `provisional` have not yet been
495
+ matched against GitHub's bills or its AI usage report.
496
+ - **Implicit cache writes.** OpenAI's GPT-5.6 and later models write uncached input to their
497
+ cache at a cache-write rate of 1.25 times input, but their clients report no cache writes,
498
+ and GitHub bills Copilot requests the same way. So when a request reports no cache writes
499
+ and its price has OpenAI's cache-write rate, or Copilot's card applies the rule, three of
500
+ its uncached input tokens are priced at the input rate and the rest at the cache-write
501
+ rate, whoever paid. GitHub's bills for GPT-6.1 Sol match this exactly, and its AI usage
502
+ report bills exactly three input tokens per request. It bills Claude via Copilot the same
503
+ way when a client reports no cache writes, so every Copilot price with a cache-write rate
504
+ applies the rule. Claude Code reports its cache writes, so Anthropic's own prices bill
505
+ uncached input at the input rate.
506
+ - **One-hour cache writes.** Claude Code writes one-hour caches, which cost more than
507
+ five-minute ones: $8 instead of $5 per million on Opus 5.5. The one-hour share of a
508
+ request's cache writes is priced at LiteLLM's one-hour rate; token counts do not change.
509
+ - **Model names.** Dotted Claude versions, as Copilot and OpenCode spell them, are priced as
510
+ Anthropic's hyphenated IDs, and a `[1m]` context variant as its base model. Private
511
+ aliases are not guessed: Codex's `codex-auto-review` and `gpt-5.3-codex-spark` have no
512
+ published price and stay unpriced. `report` and `sync` name unpriced models on stderr.
513
+
514
+ `report` loads no billing hints, so it prices a Copilot request routed to a ChatGPT plan
515
+ with Copilot's rate card, as if Copilot had paid; `sync` reads the hints and prices it as
516
+ an OpenAI request.
517
+
518
+ Override exact model IDs in USD per million tokens, optionally with long-context `tiers`, a
519
+ one-hour cache-write rate (`cacheWrite1h`), and implicit cache writes (`uncachedInput`,
520
+ `input` by default):
452
521
 
453
522
  ```json
454
523
  {
455
524
  "prices": {
456
- "my-model": { "input": 2, "output": 10, "cacheRead": 0.2, "cacheWrite": null }
525
+ "my-model": { "input": 2, "output": 10, "cacheRead": 0.2, "cacheWrite": null },
526
+ "my-tiered-model": {
527
+ "input": 2,
528
+ "output": 10,
529
+ "cacheRead": 0.1,
530
+ "cacheWrite": 2.5,
531
+ "uncachedInput": "cacheWrite",
532
+ "tiers": [{ "above": 272000, "input": 4, "output": 15, "cacheRead": 0.2, "cacheWrite": 5 }]
533
+ }
457
534
  }
458
535
  }
459
536
  ```
460
537
 
461
- `null` means unknown, while `0` explicitly means free. Rates are base-tier estimates
462
- applied to the whole selected history; historical price changes, service tiers,
463
- tool charges, taxes, negotiated discounts, and subscription allocations are not
464
- modeled. Provider-reported credit or dollar figures do not override this estimate.
538
+ `null` means unknown, while `0` explicitly means free. Overrides replace vendor rates, not
539
+ the rates Copilot's card gives the requests Copilot paid for. Vendor rates apply to the whole
540
+ selected history: their historical changes, service tiers, tool charges, taxes, negotiated
541
+ discounts, Copilot's discount for automatic model selection, and subscription allocations
542
+ are not modeled. Provider-reported credit or dollar figures do not override this estimate.
465
543
 
466
- JSON is a versioned report (version 2; version 1 used UTC days) with pricing provenance, applied unit rates, coverage diagnostics, and rows
544
+ JSON is a versioned report (version 2; version 1 used UTC days) with pricing provenance, applied base-tier unit rates, coverage diagnostics, and rows
467
545
  grouped by project/day/provider/model. Its `timeZone` field names the IANA zone of
468
546
  `since`, `until`, and each row's `day`. CSV instead matches the terminal summary:
469
547
  one row per project, sorted by known API cost, plus a Total row. It includes token
@@ -563,6 +641,12 @@ npx @ponbac/token-ledger@latest schedule install --every 24h --at 07:30 # once
563
641
  | `--provider <provider>` | Sync one provider only |
564
642
  | `--dry-run` | Print the files and commands, and change nothing |
565
643
 
644
+ Before `--every`, `schedule install` synced once a day. The first sync by 0.10.0 or
645
+ later moves such a job to every two hours from the same time of day, keeping what it
646
+ runs, and says so in its output. It does this once per installation and never after a
647
+ `schedule install` of its own, so `schedule install --every 24h` keeps a daily sync.
648
+ On macOS the agent reloads after that sync exits and syncs once more as it loads.
649
+
566
650
  `schedule status` shows the scheduler's own report, including the last run, and
567
651
  `schedule uninstall` removes the job and keeps your settings. A run's output is in
568
652
  `journalctl --user -u token-ledger-sync` on Linux and in
@@ -710,7 +794,10 @@ you run it:
710
794
  cache, and output tokens, request counts, and API-equivalent cost, with the
711
795
  subscription that paid when a request's route or a billing hint shows it. Also the
712
796
  window, your time zone name, the machine ID and label, the CLI version, per-provider
713
- coverage counts, pricing provenance, and billing plans Codex reports.
797
+ coverage counts, pricing provenance, and billing plans Codex reports. Provenance includes
798
+ a pricing basis naming the pricing method, the Copilot rate card's version, and a hash of
799
+ any configured price overrides. [Repricing](#repricing-older-usage) sends the same hourly
800
+ totals again for older hours, with new costs.
714
801
  - **Hashed:** session identities. Some providers use a transcript's file path as its
715
802
  session, so no raw session ID is sent.
716
803
  - **Never uploaded:** prompts, responses, individual requests, source code, file or
@@ -766,6 +853,35 @@ Exit codes: `0` synced, `1` invalid input or settings, `2` refused by `--strict`
766
853
  refused, `5` unsupported payload version (upgrade token-ledger), `6` payload rejected,
767
854
  `7` superseded twice by newer syncs from this machine (run it again).
768
855
 
856
+ ### Repricing older usage
857
+
858
+ Prices change: a token-ledger release can price requests differently, GitHub changes
859
+ Copilot's rates, and you can change configured `prices`. Each upload names the pricing basis
860
+ behind its costs, and a sync replaces only its own window, so hours before it keep the costs
861
+ an older basis gave them. After each successful sync whose upload names a basis, `sync` asks
862
+ the server which of this machine's stored usage another basis priced, rebuilds each such
863
+ tool's hourly buckets from the first stale hour up to the window, exactly as an upload builds
864
+ them, and sends them as a reprice-only upload. The server takes a new cost only for a stored
865
+ bucket that matches exactly. It never adds or removes usage, so history a tool has since
866
+ pruned, such as Claude Code's transcripts after 30 days, keeps its stored cost instead of
867
+ disappearing. [The repricing protocol](docs/sync-v1.md#repricing) has the matching rules,
868
+ batching, and retries.
869
+
870
+ `sync` prints, per tool, how many stored buckets took the new cost and how many of the
871
+ buckets it sent matched none:
872
+
873
+ ```text
874
+ Repriced copilot from 2026-10-03 14:00 UTC · 12 buckets stored on an older pricing basis · sent 290 · 288 updated · 2 unmatched
875
+ ```
876
+
877
+ A reprice that does not finish, because the server is unreachable or refuses it or a tool's
878
+ history cannot be read or found, is reported and tried again on the next sync; it never
879
+ changes the sync's exit code. Finished reprices are remembered in `repricing.json` in the
880
+ settings directory, so stale buckets this machine can no longer reproduce are reported as
881
+ skipped rather than sent on every run; delete the file to send them again. A run that priced
882
+ without vendor rates claims no basis and reprices nothing. `--provider` limits repricing to
883
+ that tool, and `--dry-run` neither asks nor sends.
884
+
769
885
  ## Accuracy and limitations
770
886
 
771
887
  - Reports reflect saved, readable local history, not an authoritative provider invoice.
@@ -789,7 +905,8 @@ refused, `5` unsupported payload version (upgrade token-ledger), `6` payload rej
789
905
  request is counted once, for the session that made it; when that session's file is not
790
906
  among the files read, it is counted for the fork. Pi names no model for nested tool
791
907
  work or for compaction and branch summaries; those tokens are reported under the model
792
- `unknown` and stay unpriced. Pi's own recorded costs are not used.
908
+ `unknown` and stay unpriced. Pi's own recorded costs are not used. Requests on Pi's
909
+ `github-copilot` route bill to Copilot.
793
910
  - A Pi `sessionDir` setting is not read; when sessions live outside the default
794
911
  directory, set `PI_CODING_AGENT_SESSION_DIR` or configure a `pi` source.
795
912
  - OpenCode keeps each request's usage on its assistant message. Its newer store repeats
@@ -829,7 +946,7 @@ For manual publication:
829
946
  1. Log in with `npm login` using an account with publish access to `@ponbac/token-ledger`.
830
947
  2. Run `bun run check`. The CLI test packs the package, installs it offline outside
831
948
  the repository with lifecycle scripts disabled, and exercises the installed CLI.
832
- 3. Run `bun run pack` to create `dist/ponbac-token-ledger-0.9.0.tgz` (filename follows version).
949
+ 3. Run `bun run pack` to create `dist/ponbac-token-ledger-0.11.0.tgz` (filename follows version).
833
950
  4. Inspect `npm publish ./dist/npm --dry-run`.
834
951
  5. Publish with `npm publish ./dist/npm --access public`; complete npm's authentication
835
952
  prompt if requested.