@ponbac/token-ledger 0.9.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.
- package/README.md +117 -23
- package/dist/main.js +1289 -212
- 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.**
|
|
10
|
-
|
|
11
|
-
cache
|
|
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
|
|
|
@@ -128,9 +129,10 @@ keeps the server's stored OpenCode usage. A source directory holding no OpenCode
|
|
|
128
129
|
all is reported as `missing`, which keeps stored usage too. Working directories
|
|
129
130
|
OpenCode stored on Windows with forward slashes are matched as native paths.
|
|
130
131
|
|
|
131
|
-
Models are reported under the ID OpenCode recorded, such as `claude-opus-4.5
|
|
132
|
-
|
|
133
|
-
|
|
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.
|
|
134
136
|
|
|
135
137
|
`sync` names the subscription that paid for a request from the route OpenCode recorded:
|
|
136
138
|
`github-copilot` requests bill to Copilot, and `openai` requests with a recorded cost of
|
|
@@ -441,29 +443,82 @@ overlapping files: the first configured source owns their project attribution.
|
|
|
441
443
|
|
|
442
444
|
## Prices and exports
|
|
443
445
|
|
|
444
|
-
The CLI fetches the public LiteLLM model-rate table and caches the decoded snapshot
|
|
445
|
-
for 24 hours
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
cached prices
|
|
450
|
-
|
|
451
|
-
|
|
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):
|
|
452
498
|
|
|
453
499
|
```json
|
|
454
500
|
{
|
|
455
501
|
"prices": {
|
|
456
|
-
"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
|
+
}
|
|
457
511
|
}
|
|
458
512
|
}
|
|
459
513
|
```
|
|
460
514
|
|
|
461
|
-
`null` means unknown, while `0` explicitly means free.
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
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.
|
|
465
520
|
|
|
466
|
-
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
|
|
467
522
|
grouped by project/day/provider/model. Its `timeZone` field names the IANA zone of
|
|
468
523
|
`since`, `until`, and each row's `day`. CSV instead matches the terminal summary:
|
|
469
524
|
one row per project, sorted by known API cost, plus a Total row. It includes token
|
|
@@ -563,6 +618,12 @@ npx @ponbac/token-ledger@latest schedule install --every 24h --at 07:30 # once
|
|
|
563
618
|
| `--provider <provider>` | Sync one provider only |
|
|
564
619
|
| `--dry-run` | Print the files and commands, and change nothing |
|
|
565
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
|
+
|
|
566
627
|
`schedule status` shows the scheduler's own report, including the last run, and
|
|
567
628
|
`schedule uninstall` removes the job and keeps your settings. A run's output is in
|
|
568
629
|
`journalctl --user -u token-ledger-sync` on Linux and in
|
|
@@ -710,7 +771,10 @@ you run it:
|
|
|
710
771
|
cache, and output tokens, request counts, and API-equivalent cost, with the
|
|
711
772
|
subscription that paid when a request's route or a billing hint shows it. Also the
|
|
712
773
|
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.
|
|
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.
|
|
714
778
|
- **Hashed:** session identities. Some providers use a transcript's file path as its
|
|
715
779
|
session, so no raw session ID is sent.
|
|
716
780
|
- **Never uploaded:** prompts, responses, individual requests, source code, file or
|
|
@@ -766,6 +830,35 @@ Exit codes: `0` synced, `1` invalid input or settings, `2` refused by `--strict`
|
|
|
766
830
|
refused, `5` unsupported payload version (upgrade token-ledger), `6` payload rejected,
|
|
767
831
|
`7` superseded twice by newer syncs from this machine (run it again).
|
|
768
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
|
+
|
|
769
862
|
## Accuracy and limitations
|
|
770
863
|
|
|
771
864
|
- Reports reflect saved, readable local history, not an authoritative provider invoice.
|
|
@@ -789,7 +882,8 @@ refused, `5` unsupported payload version (upgrade token-ledger), `6` payload rej
|
|
|
789
882
|
request is counted once, for the session that made it; when that session's file is not
|
|
790
883
|
among the files read, it is counted for the fork. Pi names no model for nested tool
|
|
791
884
|
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.
|
|
885
|
+
`unknown` and stay unpriced. Pi's own recorded costs are not used. Requests on Pi's
|
|
886
|
+
`github-copilot` route bill to Copilot.
|
|
793
887
|
- A Pi `sessionDir` setting is not read; when sessions live outside the default
|
|
794
888
|
directory, set `PI_CODING_AGENT_SESSION_DIR` or configure a `pi` source.
|
|
795
889
|
- OpenCode keeps each request's usage on its assistant message. Its newer store repeats
|
|
@@ -829,7 +923,7 @@ For manual publication:
|
|
|
829
923
|
1. Log in with `npm login` using an account with publish access to `@ponbac/token-ledger`.
|
|
830
924
|
2. Run `bun run check`. The CLI test packs the package, installs it offline outside
|
|
831
925
|
the repository with lifecycle scripts disabled, and exercises the installed CLI.
|
|
832
|
-
3. Run `bun run pack` to create `dist/ponbac-token-ledger-0.
|
|
926
|
+
3. Run `bun run pack` to create `dist/ponbac-token-ledger-0.10.0.tgz` (filename follows version).
|
|
833
927
|
4. Inspect `npm publish ./dist/npm --dry-run`.
|
|
834
928
|
5. Publish with `npm publish ./dist/npm --access public`; complete npm's authentication
|
|
835
929
|
prompt if requested.
|