@ponbac/token-ledger 0.8.0 → 0.10.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 +167 -26
  2. package/dist/main.js +1612 -266
  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
 
@@ -101,12 +102,43 @@ node packages/cli/dist/main.js report
101
102
  | Grok Build | `~/.grok/sessions/**/updates.jsonl` | Saved completed turns and their model breakdowns |
102
103
  | 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
104
  | Pi | `~/.pi/agent/sessions` or `PI_CODING_AGENT_SESSION_DIR` | Assistant messages on every branch, plus usage, compaction, and summary entries |
105
+ | OpenCode | `~/.local/share/opencode` | Assistant messages in `opencode*.db` and legacy `storage/message` files |
104
106
 
105
107
  `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `GROK_HOME`, `COPILOT_HOME`, and `PI_CODING_AGENT_DIR`
106
- override the usual homes. Configuration supports additional accounts, machines' exported histories,
108
+ override the usual homes. OpenCode keeps its data under `$XDG_DATA_HOME/opencode` on every
109
+ platform, Windows and macOS included, so an absolute `XDG_DATA_HOME` moves it, and
110
+ `OPENCODE_DB` names a database file in place of `opencode.db`, relative to that directory.
111
+ Configuration supports additional accounts, machines' exported histories,
107
112
  and arbitrary source directories. Histories are opened read-only, including work
108
113
  performed outside T3 Code.
109
114
 
115
+ ### OpenCode
116
+
117
+ Token Ledger reads OpenCode's SQLite database read-only, and every release channel's
118
+ `opencode-<channel>.db` beside it, selecting only accounting fields: message and session
119
+ IDs, timestamps, route, model, token counts, recorded cost, and working directory. Prompts,
120
+ responses, and tool output stay in the database; they are in tables and columns it never
121
+ selects. Under an `opencode` source, wherever it is rooted, every `opencode*.db` is read
122
+ as a database, every `msg_*.json` as a legacy message, and every `ses_*.json` as a legacy
123
+ session, of which only its ID and start time are read. Directories that never hold history
124
+ are skipped: snapshots, logs, cloned repositories, binaries, and the legacy store's parts,
125
+ diffs, shares, and to-do lists. Credentials and other files are never read. A file a source
126
+ names directly, such as an `OPENCODE_DB` override with any extension, is opened as SQLite
127
+ unless it is legacy JSON; one that cannot be opened counts as unreadable history, so `sync`
128
+ keeps the server's stored OpenCode usage. A source directory holding no OpenCode history at
129
+ all is reported as `missing`, which keeps stored usage too. Working directories
130
+ OpenCode stored on Windows with forward slashes are matched as native paths.
131
+
132
+ Models are reported under the ID OpenCode recorded, such as `claude-opus-4.5`. Requests on
133
+ the `github-copilot` route are priced with [Copilot's rate card](#prices-and-exports), and
134
+ other routes' by the public rate table, which prices a dotted Claude version as Anthropic's
135
+ hyphenated ID. OpenCode's own recorded costs are not used for estimates.
136
+
137
+ `sync` names the subscription that paid for a request from the route OpenCode recorded:
138
+ `github-copilot` requests bill to Copilot, and `openai` requests with a recorded cost of
139
+ exactly zero to Codex, because OpenCode's ChatGPT sign-in clears every OpenAI model's
140
+ rates. Other routes, OpenCode Zen and API keys among them, are API-equivalent estimates.
141
+
110
142
  ### Enable Copilot's usage export
111
143
 
112
144
  Copilot writes no usage log until a local OpenTelemetry file export is switched on,
@@ -411,29 +443,82 @@ overlapping files: the first configured source owns their project attribution.
411
443
 
412
444
  ## Prices and exports
413
445
 
414
- The CLI fetches the public LiteLLM model-rate table and caches the decoded snapshot
415
- for 24 hours under `$XDG_CACHE_HOME/token-ledger` (default `~/.cache/token-ledger`).
416
- Histories are processed locally. `report` only uses the network for this public
417
- pricing request; `sync` also uploads aggregated usage, as described below.
418
- `--offline` uses cached prices and config overrides. A failed refresh falls back to
419
- cached prices, with the snapshot timestamp retained in JSON.
420
-
421
- Override exact model IDs in USD per million tokens:
446
+ The CLI fetches the public LiteLLM model-rate table and caches the decoded snapshot, its
447
+ long-context tiers included, for 24 hours as `prices-v2.json` under
448
+ `$XDG_CACHE_HOME/token-ledger` (default `~/.cache/token-ledger`); earlier versions'
449
+ snapshots lack the tiers and are not reused. Histories are processed locally. `report` only
450
+ uses the network for this public pricing request; `sync` also uploads aggregated usage, as
451
+ described below. `--offline` uses cached prices and config overrides. A failed refresh falls
452
+ back to cached prices, with the snapshot timestamp retained in JSON.
453
+
454
+ Each request is priced on its own, before any aggregation:
455
+
456
+ - **Long context.** A request's context is its uncached input, cache reads, and cache
457
+ writes together. The whole request is priced at the highest tier whose threshold its
458
+ context exceeds: against a 272K tier, 272,000 tokens stay at the base rates and 272,001
459
+ are long. OpenAI's GPT-5.6 and GPT-6.x models cost twice as much above 272K (output 1.5
460
+ times); Claude Haiku 5.5 has a tier above 100K, and other Claude models none. A Grok turn
461
+ and Pi's usage for nested tool work can each sum several requests, so their context says
462
+ nothing about one request: they are priced at the base tier.
463
+ - **GitHub Copilot.** Requests Copilot paid for are priced with GitHub's own rate card,
464
+ checked in as [`copilot-rates.json`](packages/core/src/copilot-rates.json): Copilot's
465
+ requests unless a billing hint routes them to a ChatGPT plan, and OpenCode's and Pi's
466
+ `github-copilot` routes. Its rates are dated because GitHub changes them, as when GPT-5.6
467
+ Sol's launch discount ended after 2026-09-03, or Claude Sonnet 5.5's cached rate halved
468
+ from 2026-10-08; a request takes the rate in effect on its UTC day.
469
+ Next edit suggestions (`copilot-nes-*`, `nes-*`) and VS Code's helper model
470
+ (`gpt-4o-mini`, `gpt-4o-mini-*`) are free. A model the card lacks takes LiteLLM's
471
+ `github_copilot/` rates, then the vendor's. Entries marked `provisional` have not yet been
472
+ matched against GitHub's bills or its AI usage report.
473
+ - **Implicit cache writes.** OpenAI's GPT-5.6 and later models write uncached input to their
474
+ cache at a cache-write rate of 1.25 times input, but their clients report no cache writes,
475
+ and GitHub bills Copilot requests the same way. So when a request reports no cache writes
476
+ and its price has OpenAI's cache-write rate, or Copilot's card applies the rule, three of
477
+ its uncached input tokens are priced at the input rate and the rest at the cache-write
478
+ rate, whoever paid. GitHub's bills for GPT-6.1 Sol match this exactly, and its AI usage
479
+ report bills exactly three input tokens per request. It bills Claude via Copilot the same
480
+ way when a client reports no cache writes, so every Copilot price with a cache-write rate
481
+ applies the rule. Claude Code reports its cache writes, so Anthropic's own prices bill
482
+ uncached input at the input rate.
483
+ - **One-hour cache writes.** Claude Code writes one-hour caches, which cost more than
484
+ five-minute ones: $8 instead of $5 per million on Opus 5.5. The one-hour share of a
485
+ request's cache writes is priced at LiteLLM's one-hour rate; token counts do not change.
486
+ - **Model names.** Dotted Claude versions, as Copilot and OpenCode spell them, are priced as
487
+ Anthropic's hyphenated IDs, and a `[1m]` context variant as its base model. Private
488
+ aliases are not guessed: Codex's `codex-auto-review` and `gpt-5.3-codex-spark` have no
489
+ published price and stay unpriced. `report` and `sync` name unpriced models on stderr.
490
+
491
+ `report` loads no billing hints, so it prices a Copilot request routed to a ChatGPT plan
492
+ with Copilot's rate card, as if Copilot had paid; `sync` reads the hints and prices it as
493
+ an OpenAI request.
494
+
495
+ Override exact model IDs in USD per million tokens, optionally with long-context `tiers`, a
496
+ one-hour cache-write rate (`cacheWrite1h`), and implicit cache writes (`uncachedInput`,
497
+ `input` by default):
422
498
 
423
499
  ```json
424
500
  {
425
501
  "prices": {
426
- "my-model": { "input": 2, "output": 10, "cacheRead": 0.2, "cacheWrite": null }
502
+ "my-model": { "input": 2, "output": 10, "cacheRead": 0.2, "cacheWrite": null },
503
+ "my-tiered-model": {
504
+ "input": 2,
505
+ "output": 10,
506
+ "cacheRead": 0.1,
507
+ "cacheWrite": 2.5,
508
+ "uncachedInput": "cacheWrite",
509
+ "tiers": [{ "above": 272000, "input": 4, "output": 15, "cacheRead": 0.2, "cacheWrite": 5 }]
510
+ }
427
511
  }
428
512
  }
429
513
  ```
430
514
 
431
- `null` means unknown, while `0` explicitly means free. Rates are base-tier estimates
432
- applied to the whole selected history; historical price changes, service tiers,
433
- tool charges, taxes, negotiated discounts, and subscription allocations are not
434
- modeled. Provider-reported credit or dollar figures do not override this estimate.
515
+ `null` means unknown, while `0` explicitly means free. Overrides replace vendor rates, not
516
+ the rates Copilot's card gives the requests Copilot paid for. Vendor rates apply to the whole
517
+ selected history: their historical changes, service tiers, tool charges, taxes, negotiated
518
+ discounts, Copilot's discount for automatic model selection, and subscription allocations
519
+ are not modeled. Provider-reported credit or dollar figures do not override this estimate.
435
520
 
436
- JSON is a versioned report (version 2; version 1 used UTC days) with pricing provenance, applied unit rates, coverage diagnostics, and rows
521
+ JSON is a versioned report (version 2; version 1 used UTC days) with pricing provenance, applied base-tier unit rates, coverage diagnostics, and rows
437
522
  grouped by project/day/provider/model. Its `timeZone` field names the IANA zone of
438
523
  `since`, `until`, and each row's `day`. CSV instead matches the terminal summary:
439
524
  one row per project, sorted by known API cost, plus a Total row. It includes token
@@ -533,6 +618,12 @@ npx @ponbac/token-ledger@latest schedule install --every 24h --at 07:30 # once
533
618
  | `--provider <provider>` | Sync one provider only |
534
619
  | `--dry-run` | Print the files and commands, and change nothing |
535
620
 
621
+ Before `--every`, `schedule install` synced once a day. The first sync by 0.10.0 or
622
+ later moves such a job to every two hours from the same time of day, keeping what it
623
+ runs, and says so in its output. It does this once per installation and never after a
624
+ `schedule install` of its own, so `schedule install --every 24h` keeps a daily sync.
625
+ On macOS the agent reloads after that sync exits and syncs once more as it loads.
626
+
536
627
  `schedule status` shows the scheduler's own report, including the last run, and
537
628
  `schedule uninstall` removes the job and keeps your settings. A run's output is in
538
629
  `journalctl --user -u token-ledger-sync` on Linux and in
@@ -677,9 +768,13 @@ Provider histories stay on the machine. `sync` uploads only aggregates, and only
677
768
  you run it:
678
769
 
679
770
  - **Uploaded:** hourly totals per session, project, provider, and model: input,
680
- cache, and output tokens, request counts, and API-equivalent cost. Also the window,
681
- your time zone name, the machine ID and label, the CLI version, per-provider
682
- coverage counts, pricing provenance, and billing plans Codex reports.
771
+ cache, and output tokens, request counts, and API-equivalent cost, with the
772
+ subscription that paid when a request's route or a billing hint shows it. Also the
773
+ window, your time zone name, the machine ID and label, the CLI version, per-provider
774
+ coverage counts, pricing provenance, and billing plans Codex reports. Provenance includes
775
+ a pricing basis naming the pricing method, the Copilot rate card's version, and a hash of
776
+ any configured price overrides. [Repricing](#repricing-older-usage) sends the same hourly
777
+ totals again for older hours, with new costs.
683
778
  - **Hashed:** session identities. Some providers use a transcript's file path as its
684
779
  session, so no raw session ID is sent.
685
780
  - **Never uploaded:** prompts, responses, individual requests, source code, file or
@@ -735,15 +830,44 @@ Exit codes: `0` synced, `1` invalid input or settings, `2` refused by `--strict`
735
830
  refused, `5` unsupported payload version (upgrade token-ledger), `6` payload rejected,
736
831
  `7` superseded twice by newer syncs from this machine (run it again).
737
832
 
833
+ ### Repricing older usage
834
+
835
+ Prices change: a token-ledger release can price requests differently, GitHub changes
836
+ Copilot's rates, and you can change configured `prices`. Each upload names the pricing basis
837
+ behind its costs, and a sync replaces only its own window, so hours before it keep the costs
838
+ an older basis gave them. After each successful sync whose upload names a basis, `sync` asks
839
+ the server which of this machine's stored usage another basis priced, rebuilds each such
840
+ tool's hourly buckets from the first stale hour up to the window, exactly as an upload builds
841
+ them, and sends them as a reprice-only upload. The server takes a new cost only for a stored
842
+ bucket that matches exactly. It never adds or removes usage, so history a tool has since
843
+ pruned, such as Claude Code's transcripts after 30 days, keeps its stored cost instead of
844
+ disappearing. [The repricing protocol](docs/sync-v1.md#repricing) has the matching rules,
845
+ batching, and retries.
846
+
847
+ `sync` prints, per tool, how many stored buckets took the new cost and how many of the
848
+ buckets it sent matched none:
849
+
850
+ ```text
851
+ Repriced copilot from 2026-10-03 14:00 UTC · 12 buckets stored on an older pricing basis · sent 290 · 288 updated · 2 unmatched
852
+ ```
853
+
854
+ A reprice that does not finish, because the server is unreachable or refuses it or a tool's
855
+ history cannot be read or found, is reported and tried again on the next sync; it never
856
+ changes the sync's exit code. Finished reprices are remembered in `repricing.json` in the
857
+ settings directory, so stale buckets this machine can no longer reproduce are reported as
858
+ skipped rather than sent on every run; delete the file to send them again. A run that priced
859
+ without vendor rates claims no basis and reprices nothing. `--provider` limits repricing to
860
+ that tool, and `--dry-run` neither asks nor sends.
861
+
738
862
  ## Accuracy and limitations
739
863
 
740
864
  - Reports reflect saved, readable local history, not an authoritative provider invoice.
741
865
  - JSONL files are streamed, while Copilot buffers accounting records and span links
742
866
  per source for attribution; SQLite imports read the selected accounting rows. Each
743
867
  run rescans its sources, and memory grows with observed usage records.
744
- - Transcripts are append-only, so a Codex, Claude Code, Grok, or Pi file last modified more
745
- than 36 hours before the window starts is not opened; coverage counts these as
746
- `filesBeforeWindow`. This trusts modification times: a history restored with times
868
+ - Transcripts are append-only, so a Codex, Claude Code, Grok, Pi, or legacy OpenCode file
869
+ last modified more than 36 hours before the window starts is not opened; coverage counts
870
+ these as `filesBeforeWindow`. This trusts modification times: a history restored with times
747
871
  earlier than its last events is missed, so name such a file as the source itself,
748
872
  which is always read. Copilot exports are always read too, because requests are
749
873
  correlated across files and a live SQLite database's modification time lags its rows.
@@ -758,9 +882,26 @@ refused, `5` unsupported payload version (upgrade token-ledger), `6` payload rej
758
882
  request is counted once, for the session that made it; when that session's file is not
759
883
  among the files read, it is counted for the fork. Pi names no model for nested tool
760
884
  work or for compaction and branch summaries; those tokens are reported under the model
761
- `unknown` and stay unpriced. Pi's own recorded costs are not used.
885
+ `unknown` and stay unpriced. Pi's own recorded costs are not used. Requests on Pi's
886
+ `github-copilot` route bill to Copilot.
762
887
  - A Pi `sessionDir` setting is not read; when sessions live outside the default
763
888
  directory, set `PI_CODING_AGENT_SESSION_DIR` or configure a `pi` source.
889
+ - OpenCode keeps each request's usage on its assistant message. Its newer store repeats
890
+ those messages under the same IDs, and legacy files repeat them too; each request is
891
+ counted once. A fork copies its parent's messages under new IDs with their timestamps
892
+ and usage, so a copy, a message older than its session, is matched to its original by
893
+ timestamp, route, model, and tokens in any OpenCode database or legacy file read, and
894
+ counted for the fork only when no original is read. Legacy copies are recognised only
895
+ when their session's file in `storage/session` is read too, by any source. Reverting a session deletes the reverted messages, and their usage with them, as
896
+ in OpenCode's own totals. A summary's usage is counted from its compaction message; a
897
+ failed one names no model and is reported under `unknown`, unpriced. Title generation,
898
+ which OpenCode's newest runtime records only in session totals, is not counted.
899
+ - An OpenCode database is always read, because its modification time lags rows in its
900
+ write-ahead log; only its messages created in the window are selected, so its rows
901
+ outside the window are not diagnosed. Legacy session files are always read, and legacy
902
+ message files follow the modification-time rule above.
903
+ - An `openai` request made with an API key for a model whose listed rates are zero would
904
+ also be billed to Codex: a recorded cost of zero is the only sign of the ChatGPT sign-in.
764
905
  - A truncated or malformed JSONL line is skipped and counted. No prompts are printed
765
906
  in diagnostics. An active session can change during a scan; this is not a transactional snapshot.
766
907
  - Coverage diagnostics describe every opened file, including its events outside the
@@ -782,7 +923,7 @@ For manual publication:
782
923
  1. Log in with `npm login` using an account with publish access to `@ponbac/token-ledger`.
783
924
  2. Run `bun run check`. The CLI test packs the package, installs it offline outside
784
925
  the repository with lifecycle scripts disabled, and exercises the installed CLI.
785
- 3. Run `bun run pack` to create `dist/ponbac-token-ledger-0.8.0.tgz` (filename follows version).
926
+ 3. Run `bun run pack` to create `dist/ponbac-token-ledger-0.10.0.tgz` (filename follows version).
786
927
  4. Inspect `npm publish ./dist/npm --dry-run`.
787
928
  5. Publish with `npm publish ./dist/npm --access public`; complete npm's authentication
788
929
  prompt if requested.