@ponbac/token-ledger 0.1.2 → 0.2.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 CHANGED
@@ -24,7 +24,10 @@ These are equivalent alternatives; choose the package manager you already use.
24
24
  The npm package contains a bundled CLI with no runtime dependencies or install
25
25
  scripts. `bunx` uses the Node shebang, so Node 24+ is still required.
26
26
 
27
- The default window is the current calendar month through today, in UTC. Read every
27
+ The default window is the current calendar month through today. `--since` and
28
+ `--until` are inclusive local calendar days in the system time zone; select another
29
+ IANA zone with `--time-zone`, such as `--time-zone Europe/Stockholm`. Days follow
30
+ daylight saving time, so a day can last 23 or 25 hours. Read every
28
31
  supported source by omitting `--provider`. Configure Copilot collection before
29
32
  starting sessions as described below; installing the CLI does not enable telemetry.
30
33
 
@@ -304,7 +307,8 @@ overlapping files: the first configured source owns their project attribution.
304
307
 
305
308
  The CLI fetches the public LiteLLM model-rate table and caches the decoded snapshot
306
309
  for 24 hours under `$XDG_CACHE_HOME/token-ledger` (default `~/.cache/token-ledger`).
307
- Only this public pricing request uses the network; histories are processed locally.
310
+ Histories are processed locally. `report` only uses the network for this public
311
+ pricing request; `sync` also uploads aggregated usage, as described below.
308
312
  `--offline` uses cached prices and config overrides. A failed refresh falls back to
309
313
  cached prices, with the snapshot timestamp retained in JSON.
310
314
 
@@ -323,8 +327,9 @@ applied to the whole selected history; historical price changes, service tiers,
323
327
  tool charges, taxes, negotiated discounts, and subscription allocations are not
324
328
  modeled. Provider-reported credit or dollar figures do not override this estimate.
325
329
 
326
- JSON is a versioned report with pricing provenance, applied unit rates, coverage diagnostics, and rows
327
- grouped by project/day/provider/model. CSV instead matches the terminal summary:
330
+ JSON is a versioned report (version 2; version 1 used UTC days) with pricing provenance, applied unit rates, coverage diagnostics, and rows
331
+ grouped by project/day/provider/model. Its `timeZone` field names the IANA zone of
332
+ `since`, `until`, and each row's `day`. CSV instead matches the terminal summary:
328
333
  one row per project, sorted by known API cost, plus a Total row. It includes token
329
334
  totals, API estimates rounded to two decimals, and cost percentages. Incomplete
330
335
  costs display `+ unknown`, and percentages use only the known subtotal. Neither
@@ -338,20 +343,257 @@ Exit codes: `0` for a generated report, `1` for invalid input or a fatal error,
338
343
  Ordinary mode still produces a partial report when some providers are unavailable.
339
344
  Keep developer identity alongside exported reports when combining them across a team.
340
345
 
346
+ ## Sync to toki2
347
+
348
+ `sync` uploads this machine's usage to a [toki2](https://github.com/ponbac/toki2)
349
+ server, which combines every developer's machines for team reporting and billing.
350
+ Run it on **every machine** where you use a coding agent, and schedule it daily.
351
+
352
+ ### Set up
353
+
354
+ 1. **Create an API token.** In toki2, open **Account** in the side navigation, then
355
+ **API tokens**, and create a token such as `token-ledger work-laptop`. The secret is
356
+ shown only once. A token per machine lets you revoke one machine alone.
357
+ 2. **Save the server and token:**
358
+
359
+ ```sh
360
+ npx @ponbac/token-ledger@latest login
361
+ ```
362
+
363
+ `login` asks for the server URL and the token, then writes them to `sync.json` in
364
+ your settings directory with mode 600. Windows ignores the mode; there the file is
365
+ as private as the directory, and `%APPDATA%` is yours alone:
366
+
367
+ | Platform | Settings directory |
368
+ | -------- | ------------------------------------------------------------- |
369
+ | Linux | `~/.config/token-ledger` (or `$XDG_CONFIG_HOME/token-ledger`) |
370
+ | macOS | `~/Library/Application Support/token-ledger` |
371
+ | Windows | `%APPDATA%\token-ledger` |
372
+
373
+ A set `XDG_CONFIG_HOME` takes precedence on every platform. Without a terminal,
374
+ pass `--server` and set `TOKI_API_TOKEN`; `login` saves those. `sync` also accepts
375
+ `TOKEN_LEDGER_SERVER` and `TOKI_API_TOKEN`, or `--server` and `--token`, without
376
+ saving them; flags win over environment variables, which win over `sync.json`.
377
+ The token is sent only over HTTPS, or plain HTTP to localhost, and never printed.
378
+
379
+ 3. **Check, then sync:**
380
+
381
+ ```sh
382
+ npx @ponbac/token-ledger@latest sync --dry-run # print the payload; upload nothing
383
+ npx @ponbac/token-ledger@latest sync
384
+ ```
385
+
386
+ The first run creates `machine.json` in the settings directory with a random
387
+ machine ID and a label taken from the host name. Edit the label freely, but keep
388
+ the ID: a new ID makes the same history count again as another machine.
389
+
390
+ If you map projects in a `token-ledger.json`, pass it with `--config`; scheduled jobs
391
+ do not run in your project directory. Days follow the system time zone; add
392
+ `--time-zone Europe/Stockholm` when a scheduler's environment may lack one.
393
+
394
+ ### Schedule a daily sync
395
+
396
+ Schedule a daily sync to upload history before providers prune it:
397
+
398
+ ```sh
399
+ npx @ponbac/token-ledger@latest schedule install
400
+ ```
401
+
402
+ This registers a daily job with the operating system's own scheduler; token-ledger
403
+ does not keep a process running. Run it again to change the job.
404
+
405
+ | Flag | Effect |
406
+ | ----------------------- | ------------------------------------------------------- |
407
+ | `--at 07:30` | Daily local time; the default is `12:30` |
408
+ | `--config <file>` | Project mappings for the job, saved as an absolute path |
409
+ | `--time-zone <zone>` | Pass a time zone when the scheduler may not have one |
410
+ | `--provider <provider>` | Sync one provider only |
411
+ | `--dry-run` | Print the files and commands, and change nothing |
412
+
413
+ `schedule status` shows the scheduler's own report, including the last run, and
414
+ `schedule uninstall` removes the job and keeps your settings. A run's output is in
415
+ `journalctl --user -u token-ledger-sync` on Linux and in
416
+ `~/Library/Logs/token-ledger-sync.log` on macOS.
417
+
418
+ | Platform | Scheduler | A missed run |
419
+ | -------- | ------------------- | ------------------------------------------------------ |
420
+ | Linux | systemd user timer | Runs within ten minutes of your next login |
421
+ | macOS | launchd agent | Runs on wake; also syncs each time you log in |
422
+ | Windows | Task Scheduler task | Runs at the next opportunity, on battery power as well |
423
+
424
+ The job needs the server and token saved by `login`: it cannot read `--token` or
425
+ variables set only in your shell, such as `TOKI_API_TOKEN` or `CLAUDE_CONFIG_DIR`.
426
+ The exception is `XDG_CONFIG_HOME`, which `schedule install` copies into the job so
427
+ that it reads the same settings directory.
428
+ It runs `npx --yes @ponbac/token-ledger@latest sync`, so it stays up to date. It
429
+ looks for `npx` beside the Node that ran `schedule install` and then on the
430
+ scheduler's `PATH`, so it survives removing that Node version when another is on the
431
+ `PATH`.
432
+
433
+ Linux needs a systemd user session, which Arch, Ubuntu, Debian, and Fedora provide.
434
+ Without one, as on Alpine or in WSL with systemd disabled, use the cron entry below.
435
+
436
+ <details>
437
+ <summary>Scheduling by hand</summary>
438
+
439
+ `schedule install --dry-run` prints the exact files and commands for your machine.
440
+ The examples below do the same with a login shell finding `npx`; if it is not on the
441
+ scheduler's `PATH`, use its absolute path or install the CLI globally with
442
+ `npm install -g @ponbac/token-ledger` and run `token-ledger sync`.
443
+
444
+ **Linux (systemd user timer).** Create `~/.config/systemd/user/token-ledger-sync.service`:
445
+
446
+ ```ini
447
+ [Unit]
448
+ Description=Upload AI usage to toki2
449
+
450
+ [Service]
451
+ Type=oneshot
452
+ ExecStart=/bin/sh -lc 'npx --yes @ponbac/token-ledger@latest sync'
453
+ ```
454
+
455
+ and `~/.config/systemd/user/token-ledger-sync.timer`:
456
+
457
+ ```ini
458
+ [Unit]
459
+ Description=Daily AI usage sync
460
+
461
+ [Timer]
462
+ OnCalendar=daily
463
+ Persistent=true
464
+ RandomizedDelaySec=1h
465
+
466
+ [Install]
467
+ WantedBy=timers.target
468
+ ```
469
+
470
+ Then run `systemctl --user enable --now token-ledger-sync.timer`. Check results with
471
+ `journalctl --user -u token-ledger-sync`. `Persistent=true` catches missed runs when
472
+ the user timer is next active.
473
+
474
+ **cron.** Create the log directory with `mkdir -p "$HOME/.cache"`, then run
475
+ `crontab -e` and add:
476
+
477
+ ```cron
478
+ 30 12 * * * /bin/sh -lc 'npx --yes @ponbac/token-ledger@latest sync' >> "$HOME/.cache/token-ledger-sync.log" 2>&1
479
+ ```
480
+
481
+ cron skips runs while the machine is asleep or off; prefer the systemd timer where
482
+ available.
483
+
484
+ **macOS (launchd).** Create `~/Library/LaunchAgents/com.github.ponbac.token-ledger.sync.plist`:
485
+
486
+ ```xml
487
+ <?xml version="1.0" encoding="UTF-8"?>
488
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
489
+ <plist version="1.0">
490
+ <dict>
491
+ <key>Label</key>
492
+ <string>com.github.ponbac.token-ledger.sync</string>
493
+ <key>ProgramArguments</key>
494
+ <array>
495
+ <string>/bin/zsh</string>
496
+ <string>-lc</string>
497
+ <string>npx --yes @ponbac/token-ledger@latest sync</string>
498
+ </array>
499
+ <key>RunAtLoad</key>
500
+ <true/>
501
+ <key>StartCalendarInterval</key>
502
+ <dict>
503
+ <key>Hour</key>
504
+ <integer>12</integer>
505
+ <key>Minute</key>
506
+ <integer>30</integer>
507
+ </dict>
508
+ <key>StandardOutPath</key>
509
+ <string>/tmp/token-ledger-sync.log</string>
510
+ <key>StandardErrorPath</key>
511
+ <string>/tmp/token-ledger-sync.log</string>
512
+ </dict>
513
+ </plist>
514
+ ```
515
+
516
+ Then run `launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.github.ponbac.token-ledger.sync.plist`.
517
+ `RunAtLoad` also syncs when the agent loads at login. `StartCalendarInterval`
518
+ [catches missed intervals after sleep](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/ScheduledJobs.html),
519
+ but does not replay intervals missed while powered off.
520
+
521
+ **Windows (Task Scheduler).** In PowerShell:
522
+
523
+ ```powershell
524
+ $action = New-ScheduledTaskAction -Execute "cmd.exe" -Argument "/c npx --yes @ponbac/token-ledger@latest sync"
525
+ $trigger = New-ScheduledTaskTrigger -Daily -At 12:30
526
+ $settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries
527
+ Register-ScheduledTask -TaskName "token-ledger sync" -Action $action -Trigger $trigger -Settings $settings
528
+ ```
529
+
530
+ `-StartWhenAvailable` runs a missed sync at the next opportunity. The battery
531
+ switches allow starts on battery and keep a running sync from being stopped when
532
+ AC power disconnects. See [Task Scheduler settings](https://learn.microsoft.com/en-us/powershell/module/scheduledtasks/new-scheduledtasksettingsset).
533
+
534
+ </details>
535
+
536
+ ### What leaves the machine
537
+
538
+ Provider histories stay on the machine. `sync` uploads only aggregates, and only when
539
+ you run it:
540
+
541
+ - **Uploaded:** hourly totals per session, project, provider, and model: input,
542
+ cache, and output tokens, request counts, and API-equivalent cost. Also the window,
543
+ your time zone name, the machine ID and label, the CLI version, per-provider
544
+ coverage counts, pricing provenance, and billing plans Codex reports.
545
+ - **Hashed:** session identities. Some providers use a transcript's file path as its
546
+ session, so no raw session ID is sent.
547
+ - **Never uploaded:** prompts, responses, individual requests, source code, file or
548
+ directory paths, and credentials. Usage attributed only to a local directory or a
549
+ local-path Git remote is sent as `unattributed`; configured project names and
550
+ network Git remotes (`host/owner/repo`) are sent as they are.
551
+
552
+ See [the payload contract](docs/sync-v1.md) for every field.
553
+
554
+ ### Windows and re-syncing
555
+
556
+ The default window is the last 14 local days. For each provider whose history was
557
+ fully read, the server replaces what this machine previously sent for that provider
558
+ in the window, so repeated syncs never double count, and machines add up. Fully read
559
+ means every file that could hold usage in the window: older transcripts are
560
+ [counted without being opened](#accuracy-and-limitations). A provider
561
+ with no history found, or with history that could not be read, keeps its stored data,
562
+ as do providers left out with `--provider`: missing data is never treated as zero.
563
+
564
+ Replacement also means an old window is risky: if a provider has since pruned its
565
+ history, syncing that window again replaces good server data with smaller totals.
566
+ Claude Code deletes transcripts after 30 days by default, so keep `--since` within
567
+ the last 30 days; `sync` warns when it is not. Once uploaded, the server keeps the
568
+ long-term record.
569
+
570
+ Exit codes: `0` synced, `1` invalid input or settings, `2` refused by `--strict`,
571
+ `3` server unreachable or temporarily failing (retry later), `4` token or machine
572
+ refused, `5` unsupported payload version (upgrade token-ledger), `6` payload rejected.
573
+
341
574
  ## Accuracy and limitations
342
575
 
343
576
  - Reports reflect saved, readable local history, not an authoritative provider invoice.
344
577
  - JSONL files are streamed, while Copilot buffers accounting records and span links
345
578
  per source for attribution; SQLite imports read the selected accounting rows. Each
346
579
  run rescans its sources, and memory grows with observed usage records.
580
+ - Transcripts are append-only, so a Codex, Claude Code, or Grok file last modified more
581
+ than 36 hours before the window starts is not opened; coverage counts these as
582
+ `filesBeforeWindow`. This trusts modification times: a history restored with times
583
+ earlier than its last events is missed, so name such a file as the source itself,
584
+ which is always read. Copilot exports are always read too, because requests are
585
+ correlated across files and a live SQLite database's modification time lags its rows.
347
586
  - Copied files, overlapping source paths, and stable provider record IDs are deduplicated.
348
587
  Missing stable IDs are called out where the provider cannot support that guarantee.
349
- - Codex fork histories use T3 Code's timing heuristic to exclude the leading copied
350
- burst. The report explicitly marks affected coverage as partial.
588
+ - Codex fork and subagent histories begin with a copy of their parent's history, which
589
+ the parent's own rollout already counts. T3 Code's timing heuristic excludes that
590
+ leading burst; it is not lost usage, so coverage stays `ok`. `partial` means real loss:
591
+ malformed lines, usage events that could not be normalized, or, in a report, paths
592
+ that could not be read.
351
593
  - A truncated or malformed JSONL line is skipped and counted. No prompts are printed
352
594
  in diagnostics. An active session can change during a scan; this is not a transactional snapshot.
353
- - Coverage diagnostics describe all scanned files, including events outside the selected
354
- date window. Codex updates with no usage payload are ignored, not counted as lost usage.
595
+ - Coverage diagnostics describe every opened file, including its events outside the
596
+ selected date window. Codex updates with no usage payload are ignored, not counted as lost usage.
355
597
  - Default project inference uses the current local Git metadata when the transcript
356
598
  lacks a remote. Explicit mappings make attribution more stable across machines.
357
599
  - A session that works across projects still needs an explicit allocation policy;
@@ -369,7 +611,7 @@ For manual publication:
369
611
  1. Log in with `npm login` using an account with publish access to `@ponbac/token-ledger`.
370
612
  2. Run `bun run check`. The CLI test packs the package, installs it offline outside
371
613
  the repository with lifecycle scripts disabled, and exercises the installed CLI.
372
- 3. Run `bun run pack` to create `dist/ponbac-token-ledger-0.1.2.tgz` (filename follows version).
614
+ 3. Run `bun run pack` to create `dist/ponbac-token-ledger-0.2.0.tgz` (filename follows version).
373
615
  4. Inspect `npm publish ./dist/npm --dry-run`.
374
616
  5. Publish with `npm publish ./dist/npm --access public`; complete npm's authentication
375
617
  prompt if requested.
@@ -395,7 +637,7 @@ bun run lint:fix
395
637
  `Ledger.report` returns data and typed failures, with no terminal rendering.
396
638
  - `packages/cli`: Effect CLI and process wiring. A later UI can run the same core
397
639
  through a local backend.
398
- - Effect and platform packages are pinned to `4.0.0-rc.117`.
640
+ - Effect and platform packages are pinned to stable `4.0.0`.
399
641
  - Oxlint `1.80.0` with type-aware checks, Oxfmt `0.66.0`, and all 18 generic plus
400
642
  five Effect anti-slop policies gate CI, including test code, without exemptions.
401
643
  TypeScript owns duplicate declaration checking for schema/type pairs.
@@ -412,14 +654,32 @@ application checks and editor indexing, and marked vendored for GitHub statistic
412
654
 
413
655
  ```sh
414
656
  # Start with a clean working tree. Change the version deliberately when upgrading.
415
- bun run reference:update effect 'effect@4.0.0-rc.117'
657
+ bun run reference:update effect 'effect@4.0.0'
416
658
  bun run reference:update t3code main
659
+ # Refresh only the Effect-source overlay within the T3 Code reference:
660
+ bun run reference:update effect-t3code 'effect@4.0.0'
417
661
  ```
418
662
 
419
- Update Effect dependencies together with their reference. Git subtree commit
663
+ Refresh the Effect reference after upgrading dependencies, in a separate PR stacked
664
+ above the dependency upgrade. The Effect reference is pinned to `effect@4.0.0`
665
+ (`67ba4e46a11ccda0b6761578bfd22c04ae00167d`) from
666
+ [`Effect-TS/effect`](https://github.com/Effect-TS/effect). Git subtree commit
420
667
  messages record the imported revisions. The initial T3 reference is upstream
421
668
  `aff9318bf46beaf05cc7155b428d3f0b8711efd2`.
422
669
 
670
+ The nested `.reference/t3code/.repos/effect` snapshot has a deliberate overlay
671
+ of the same stable Effect source. Related T3 Code docs and updater paths use this
672
+ canonical name; unrelated T3 Code reference files keep their imported revision.
673
+ Its nested subtree history was omitted by the outer squash, so the updater
674
+ replaces that snapshot and records its upstream URL, release tag, and commit in Git
675
+ commit trailers. Refreshing either outer reference reapplies this Effect overlay;
676
+ refreshing T3 Code uses the root manifest's installed Effect version.
677
+ The updater also removes a legacy nested snapshot reintroduced by upstream and
678
+ reapplies the canonical paths in T3 Code's reference docs and updater files.
679
+ Its own reference-sync command pins Effect to `effect@4.0.0`, independently of
680
+ the vendored T3 runtime catalog; `--latest` still explicitly selects `main`.
681
+ The parent updater reapplies this small source patch after outer T3 refreshes.
682
+
423
683
  ## License
424
684
 
425
685
  MIT. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and the licenses retained
@@ -30,7 +30,7 @@ THE SOFTWARE.
30
30
 
31
31
  ---
32
32
 
33
- @effect/platform-node-shared@4.0.0-rc.117
33
+ @effect/platform-node-shared@4.0.0
34
34
 
35
35
  MIT License
36
36
 
@@ -57,7 +57,7 @@ SOFTWARE.
57
57
 
58
58
  ---
59
59
 
60
- @effect/platform-node@4.0.0-rc.117
60
+ @effect/platform-node@4.0.0
61
61
 
62
62
  MIT License
63
63
 
@@ -156,7 +156,7 @@ SOFTWARE.
156
156
 
157
157
  ---
158
158
 
159
- effect@4.0.0-rc.117
159
+ effect@4.0.0
160
160
 
161
161
  MIT License
162
162