tokenstats 1.0.0__py3-none-any.whl

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.
tokenstats.py ADDED
@@ -0,0 +1,2049 @@
1
+ #!/usr/bin/env python3
2
+ """tokenstats — permanent local record of AI token usage on this machine.
3
+
4
+ Snapshots OpenCode's per-session totals (read-only) into our own SQLite store
5
+ and reports them filtered by model, date, and token thresholds. Reporting
6
+ views carry a TOK/S column: each session row is the mean of its per-turn
7
+ decode rates (matching OpenCode's per-prompt number), and aggregate rows are
8
+ token-weighted by generated tokens. Opt-in --cost[=<slug>] overlays a
9
+ reference dollar estimate priced at one chosen model (family names resolve to
10
+ the provider's mid-tier); opt-in --real-cost shows the stored real USD OpenCode
11
+ reported. See README.md.
12
+ """
13
+ import argparse
14
+ import colorsys
15
+ import datetime
16
+ import json
17
+ import os
18
+ import pathlib
19
+ import re
20
+ import sqlite3
21
+ import sys
22
+ import time
23
+ from collections import Counter
24
+
25
+
26
+ def state_dir(home=None):
27
+ """The one directory tokenstats owns: <home>/.tokenstats (pure path math)."""
28
+ if home is None:
29
+ home = os.path.expanduser("~")
30
+ return os.path.join(home, ".tokenstats")
31
+
32
+
33
+ def default_db(home=None):
34
+ """Our store: <home>/.tokenstats/usage.db."""
35
+ return os.path.join(state_dir(home), "usage.db")
36
+
37
+
38
+ def themes_dir(home=None):
39
+ """User theme files and the saved default: <home>/.tokenstats/themes."""
40
+ return os.path.join(state_dir(home), "themes")
41
+
42
+
43
+ def theme_config(home=None):
44
+ """The saved default theme file: <home>/.tokenstats/themes/config.json."""
45
+ return os.path.join(themes_dir(home), "config.json")
46
+
47
+
48
+ def default_src(home=None):
49
+ """OpenCode's database, resolved the way it can be found on each OS. Every
50
+ candidate is tried in order and the first that exists wins; with nothing on
51
+ disk the XDG-style default is returned so the caller still has a real path
52
+ to report. Order: $OPENCODE_DB (absolute) → $XDG_DATA_HOME/opencode/
53
+ opencode.db (absolute) → <home>/.local/share → macOS ~/Library/Application
54
+ Support → Windows %APPDATA% → legacy <home>/.opencode."""
55
+ if home is None:
56
+ home = os.path.expanduser("~")
57
+ local_default = os.path.join(home, ".local", "share", "opencode",
58
+ "opencode.db")
59
+ candidates = []
60
+ env_db = os.environ.get("OPENCODE_DB", "")
61
+ if os.path.isabs(env_db):
62
+ candidates.append(env_db)
63
+ xdg = os.environ.get("XDG_DATA_HOME", "")
64
+ if os.path.isabs(xdg):
65
+ candidates.append(os.path.join(xdg, "opencode", "opencode.db"))
66
+ candidates.append(local_default)
67
+ if sys.platform == "darwin":
68
+ candidates.append(os.path.join(home, "Library", "Application Support",
69
+ "opencode", "opencode.db"))
70
+ if sys.platform == "win32":
71
+ appdata = os.environ.get("APPDATA", "")
72
+ if os.path.isabs(appdata):
73
+ candidates.append(os.path.join(appdata, "opencode", "opencode.db"))
74
+ candidates.append(os.path.join(home, ".opencode", "opencode.db"))
75
+ for path in candidates:
76
+ if os.path.exists(path):
77
+ return path
78
+ return local_default
79
+
80
+
81
+ STATE_DIR = state_dir()
82
+ LEGACY_DIR = os.path.dirname(os.path.abspath(__file__))
83
+ DEFAULT_DB = default_db()
84
+ DEFAULT_SRC = default_src()
85
+ THEMES_DIR = themes_dir()
86
+ THEME_CONFIG = theme_config()
87
+
88
+
89
+ def default_store(state=None, legacy=None):
90
+ """The store path main() opens when --db was not given: <state>/usage.db,
91
+ after moving any state still sitting beside the script into <state>.
92
+
93
+ The path it returns always holds the history: a move that fails keeps using
94
+ the legacy file rather than trading it for an empty report, and a move lost
95
+ to a rival run lands on the store that run migrated.
96
+
97
+ The only function here that creates directories or moves files on its own
98
+ (`write_default_theme` also writes, but only because `--theme-default`
99
+ asked it to), and main() is its only caller: importing tokenstats stays
100
+ side-effect-free, and so is every run that names its own --db. `state` and
101
+ `legacy` take their defaults from the module globals at CALL time (the
102
+ same reason main() reads THEMES_DIR there) so a caller that repoints the
103
+ globals steers the migration.
104
+ """
105
+ state = STATE_DIR if state is None else state
106
+ legacy = LEGACY_DIR if legacy is None else legacy
107
+ old_db = os.path.join(legacy, "usage.db")
108
+ new_db = os.path.join(state, "usage.db")
109
+ try:
110
+ os.makedirs(state, exist_ok=True)
111
+ except OSError as exc:
112
+ print(f"warning: could not create {state}: {exc}; using {old_db}"
113
+ " instead", file=sys.stderr)
114
+ return old_db
115
+
116
+ # The siblings travel first and the store itself LAST: history is the one
117
+ # thing a migration may not lose, so the file that decides where the store
118
+ # lives is the last one to move. Anything that fails before it (a second
119
+ # filesystem, a permission, a live connection on the -wal, a rival run that
120
+ # won the race) leaves the store exactly where it was, and the files that
121
+ # did move are pulled back. A half-moved store is the failure this avoids:
122
+ # main() would open an empty database at the path it is handed and report
123
+ # nothing while the real history sat at the other one, and the next run —
124
+ # seeing both paths occupied — would never try again.
125
+ used = new_db
126
+ if os.path.exists(old_db) and not os.path.exists(new_db):
127
+ moved = []
128
+ try:
129
+ for suffix in ("-wal", "-shm", ""):
130
+ if os.path.exists(old_db + suffix):
131
+ os.replace(old_db + suffix, new_db + suffix)
132
+ moved.append(suffix)
133
+ except OSError as exc:
134
+ # Pull the siblings back only while the legacy store is still
135
+ # there. If it is gone, a rival run moved it: our files belong
136
+ # with it at the state dir, and moving them back would orphan them
137
+ # beside a path that holds nothing — permanently, because the next
138
+ # run sees both paths occupied and never retries. This is also
139
+ # what a double fault (the forward move failed AND the reverse one
140
+ # does) leaves behind, so one gate closes both.
141
+ if os.path.exists(old_db):
142
+ for suffix in reversed(moved):
143
+ try:
144
+ os.replace(new_db + suffix, old_db + suffix)
145
+ except OSError:
146
+ pass
147
+ # Decide by what is on disk, not by what was attempted: a failed
148
+ # move leaves the legacy store in place, and a lost race leaves it
149
+ # gone — moved by the winner, whose store is the one to open.
150
+ used = old_db if os.path.exists(old_db) else new_db
151
+ if used == old_db:
152
+ print(f"warning: could not migrate {old_db}: {exc}; using it"
153
+ " in place", file=sys.stderr)
154
+ else:
155
+ print(f"migrated store: {old_db} -> {new_db}", file=sys.stderr)
156
+
157
+ # Themes travel with it, but only as long as the state dir has none of its
158
+ # own: a theme is cosmetic, so a file that will not move is a warning and a
159
+ # skipped file, never a lost report. Only top-level *.json files move —
160
+ # README.md and examples/ are shipped documentation, not personal state.
161
+ old_themes = os.path.join(legacy, "themes")
162
+ new_themes = os.path.join(state, "themes")
163
+ if os.path.isdir(old_themes) and not os.path.isdir(new_themes):
164
+ try:
165
+ os.makedirs(new_themes)
166
+ names = sorted(os.listdir(old_themes))
167
+ except OSError as exc:
168
+ print(f"warning: could not migrate {old_themes}: {exc}; leaving"
169
+ " theme files in place", file=sys.stderr)
170
+ names = []
171
+ for name in names:
172
+ if not name.endswith(".json"):
173
+ continue
174
+ old_file = os.path.join(old_themes, name)
175
+ new_file = os.path.join(new_themes, name)
176
+ if not os.path.isfile(old_file):
177
+ continue
178
+ try:
179
+ os.replace(old_file, new_file)
180
+ except OSError as exc:
181
+ print(f"warning: could not migrate {old_file}: {exc}; using"
182
+ " it in place", file=sys.stderr)
183
+ continue
184
+ print(f"migrated theme file: {old_file} -> {new_file}",
185
+ file=sys.stderr)
186
+ return used
187
+
188
+
189
+ MODEL_ANY = object() # --model with no value (valid only with --total)
190
+ SESSIONS_BARE = object() # --sessions with no value; argparse skips type on
191
+ # a non-str const, so the sentinel distinguishes the valueless flag from
192
+ # --sessions=0 (a plain string const would be run through type=int).
193
+ THEME_LIST = object() # --theme with no value: list the themes and exit
194
+ THEME_SAVE = object() # --theme-default with no value: save this run's theme
195
+
196
+ TOKEN_COLUMNS = (
197
+ "tokens_input", "tokens_output", "tokens_reasoning",
198
+ "tokens_cache_read", "tokens_cache_write", "cost",
199
+ )
200
+
201
+
202
+ def ensure_schema(dest: sqlite3.Connection) -> None:
203
+ dest.execute(
204
+ """CREATE TABLE IF NOT EXISTS usage (
205
+ session_id TEXT PRIMARY KEY,
206
+ provider TEXT NOT NULL DEFAULT '',
207
+ model_id TEXT NOT NULL DEFAULT '',
208
+ tokens_input INTEGER NOT NULL DEFAULT 0,
209
+ tokens_output INTEGER NOT NULL DEFAULT 0,
210
+ tokens_reasoning INTEGER NOT NULL DEFAULT 0,
211
+ tokens_cache_read INTEGER NOT NULL DEFAULT 0,
212
+ tokens_cache_write INTEGER NOT NULL DEFAULT 0,
213
+ cost REAL NOT NULL DEFAULT 0,
214
+ title TEXT,
215
+ directory TEXT,
216
+ agent TEXT,
217
+ time_created INTEGER NOT NULL,
218
+ time_updated INTEGER,
219
+ first_seen INTEGER NOT NULL,
220
+ last_seen INTEGER NOT NULL)"""
221
+ )
222
+ dest.execute(
223
+ """CREATE TABLE IF NOT EXISTS opencode_steps (
224
+ message_id TEXT PRIMARY KEY,
225
+ session_id TEXT NOT NULL,
226
+ turn INTEGER NOT NULL DEFAULT 0,
227
+ step_ms INTEGER,
228
+ tokens_generated INTEGER NOT NULL DEFAULT 0,
229
+ time_created INTEGER NOT NULL)"""
230
+ )
231
+ # Hot filter columns: date-windowed queries scan these first.
232
+ dest.execute(
233
+ """CREATE INDEX IF NOT EXISTS idx_usage_time_created
234
+ ON usage(time_created)"""
235
+ )
236
+ dest.execute(
237
+ """CREATE INDEX IF NOT EXISTS idx_opencode_steps_session_turn
238
+ ON opencode_steps(session_id, turn)"""
239
+ )
240
+
241
+
242
+ def parse_model(raw):
243
+ """Source `model` JSON -> (provider, model_id); ("", "") for NULL/invalid."""
244
+ try:
245
+ data = json.loads(raw)
246
+ except (TypeError, ValueError):
247
+ return ("", "")
248
+ if not isinstance(data, dict):
249
+ return ("", "")
250
+ return (str(data.get("providerID", "")), str(data.get("id", "")))
251
+
252
+
253
+ def _turn_index(types: list[str], end: int, legacy: bool) -> int:
254
+ """Index of the input message opening the turn ending at `end` (exclusive).
255
+
256
+ Port of OpenCode's inputIndex: walk back from `end`, remembering the last
257
+ user/synthetic message, and stop at the first `idle` — so a mid-turn
258
+ `synthetic` never splits a turn. legacy (a session with no `idle` rows at
259
+ all) returns the nearest input instead of walking past one. -1 when the
260
+ session has no input message before `end`."""
261
+ found = -1
262
+ for i in range(end - 1, -1, -1):
263
+ kind = types[i]
264
+ if kind == "idle":
265
+ return found
266
+ if kind not in ("user", "synthetic"):
267
+ continue
268
+ if legacy:
269
+ return i
270
+ found = i
271
+ return found
272
+
273
+
274
+ def _upsert(dest, table, pk, rows, numeric, overwrite=(), insert_only=()):
275
+ """Fold `rows` into `table` with one monotonic-max upsert per row.
276
+
277
+ `rows` is a list of dicts carrying every column to write, `pk` among them;
278
+ the column order is the first row's key order. Each column belongs to one
279
+ class, and the classes are what keeps the ingest invariants:
280
+
281
+ numeric — stored as max(old, new), never an increment: a source that
282
+ repeats or shrinks can neither double count nor erase
283
+ history (invariant 1).
284
+ overwrite — takes the new value unconditionally, even NULL, so a run
285
+ that finished stops looking unfinished.
286
+ insert_only — written on insert and never touched again (our own
287
+ provenance columns, e.g. first_seen, and source
288
+ timestamps that are immutable upstream).
289
+ everything else — a label: `new or old`, so a source that nulls a
290
+ provider/model/title keeps the best we already have
291
+ (invariant 3).
292
+
293
+ A row counts `updated` when its NUMERIC merge moved and `unchanged`
294
+ otherwise: a label-only change is not a number moving, which is what these
295
+ counters have always meant. One malformed row fails inside its own
296
+ statement and bumps `skipped` without aborting (or rolling back) the rest.
297
+ The caller owns the commit, so a family's rows land in one transaction.
298
+
299
+ Every name in `numeric`, `overwrite` and `insert_only` must be a real
300
+ column of `table` and none of them may be `pk`; a name that is not raises
301
+ `ValueError` before any row is written, because the alternative is silent:
302
+ an unknown `numeric` name leaves that column in the label class, where
303
+ invariant 1 is not protected. A payload key that is not a column is a
304
+ different kind of mistake and lands as `skipped`, one row at a time.
305
+ """
306
+ # The column classes are a contract with the table, and every way to break
307
+ # it is silent: an unknown name in `numeric` demotes a real token column to
308
+ # the label class, where `new or old` can shrink it (invariant 1), and a
309
+ # column in two classes resolves in `numeric`'s favor. Checked once, up
310
+ # front, before the first row: inside the per-row try a ValueError would
311
+ # only count as `skipped` and the whole family would vanish one row at a
312
+ # time. `table` is interpolated into the PRAGMA because it is a literal from
313
+ # this module, like every other fragment this engine interpolates.
314
+ known = {row[1] for row in dest.execute(f"PRAGMA table_info({table})")}
315
+ if pk not in known:
316
+ raise ValueError(f"{table} has no column {pk!r}")
317
+ by_class = {}
318
+ for cls, names in (("numeric", numeric), ("overwrite", overwrite),
319
+ ("insert_only", insert_only)):
320
+ for name in names:
321
+ if name not in known:
322
+ raise ValueError(f"{table} has no column {name!r} "
323
+ f"(named in the {cls} class)")
324
+ if name == pk or name in by_class:
325
+ raise ValueError(f"{table}: {name!r} is in both the "
326
+ f"{by_class.get(name, 'primary-key')} and "
327
+ f"{cls} classes")
328
+ by_class[name] = cls
329
+ counts = Counter(inserted=0, updated=0, unchanged=0)
330
+ if not rows:
331
+ return counts
332
+ cols = list(rows[0])
333
+ labels = [c for c in cols if c != pk and c not in numeric
334
+ and c not in overwrite and c not in insert_only]
335
+ # Only the numeric and label columns need the stored row: an overwrite
336
+ # column comes from the source alone, an insert_only one is never read.
337
+ probe = [c for c in cols if c != pk and c not in overwrite
338
+ and c not in insert_only]
339
+ updates = [c for c in cols if c != pk and c not in insert_only]
340
+ select = f"SELECT {', '.join(probe)} FROM {table} WHERE {pk} = ?"
341
+ insert = (f"INSERT INTO {table} ({', '.join(cols)})"
342
+ f" VALUES ({', '.join('?' * len(cols))})")
343
+ update = (f"UPDATE {table} SET "
344
+ f"{', '.join(f'{c} = ?' for c in updates)} WHERE {pk} = ?")
345
+ for row in rows:
346
+ try:
347
+ existing = dest.execute(select, (row[pk],)).fetchone()
348
+ if existing is None:
349
+ dest.execute(insert, [row[c] for c in cols])
350
+ counts["inserted"] += 1
351
+ continue
352
+ old = dict(zip(probe, existing))
353
+ merged = {c: max(old[c], row[c]) for c in numeric}
354
+ changed = merged != {c: old[c] for c in numeric}
355
+ values = {**{c: row[c] for c in overwrite}, **merged,
356
+ **{c: row[c] or old[c] for c in labels}}
357
+ dest.execute(update, [values[c] for c in updates] + [row[pk]])
358
+ counts["updated" if changed else "unchanged"] += 1
359
+ except (sqlite3.Error, TypeError, ValueError):
360
+ # One malformed source row must not abort (or roll back) the rest:
361
+ # sqlite3 refuses a value it cannot bind, and a text-typed numeric
362
+ # column makes the max() merge compare str to int. Same width as
363
+ # import_opencode_steps' per-row guard, for the same reason. The
364
+ # column-class check above runs before this loop precisely so a
365
+ # ValueError from a programming mistake is never counted here.
366
+ counts["skipped"] += 1
367
+ return counts
368
+
369
+
370
+ def record(src: sqlite3.Connection, dest: sqlite3.Connection, now_ms: int) -> dict:
371
+ """Upsert every session_v2 row into our usage table.
372
+
373
+ One row per OpenCode session id; token/cost columns store the latest
374
+ observed total (max of stored and source), so re-recording can never
375
+ double count and a pruned/rewritten source can never shrink history.
376
+ time_updated and last_seen follow the source (last_seen is the one field
377
+ that moves on an unchanged session), first_seen and the source's own
378
+ time_created are written once — a creation stamp is immutable, so a
379
+ source that ever rewrote one must not move the stored value — and the
380
+ labels — provider, model_id, title, directory and agent — keep the best
381
+ we already have (invariant 3). Numeric fields are coerced per row before
382
+ the upsert: a source value that cannot be a number is a malformed row and
383
+ bumps `skipped`, never a poisoned store row that crashes every later
384
+ report.
385
+ """
386
+ rows = src.execute(
387
+ "SELECT id, model, tokens_input, tokens_output, tokens_reasoning,"
388
+ " tokens_cache_read, tokens_cache_write, cost, title, directory,"
389
+ " agent, time_created, time_updated FROM session_v2"
390
+ ).fetchall()
391
+ payload = []
392
+ bad = 0
393
+ for (sid, model_raw, tin, tout, treas, tcr, tcw, cost, title, directory,
394
+ agent, created, updated) in rows:
395
+ try:
396
+ # Coerce every numeric field HERE, not in the store: SQLite's
397
+ # column affinity happily files text like 'oops' into an INTEGER
398
+ # column, and a text time_created or cost that gets stored never
399
+ # leaves (invariant 1: the store never shrinks) — it would then
400
+ # crash every later report (fromtimestamp(str), f"{str:.2f}").
401
+ # Isolation belongs at ingest, where the skipped counter lives.
402
+ provider, model_id = parse_model(model_raw)
403
+ payload.append({
404
+ "session_id": sid, "provider": provider, "model_id": model_id,
405
+ "tokens_input": int(tin or 0), "tokens_output": int(tout or 0),
406
+ "tokens_reasoning": int(treas or 0),
407
+ "tokens_cache_read": int(tcr or 0),
408
+ "tokens_cache_write": int(tcw or 0), "cost": float(cost or 0),
409
+ "title": title, "directory": directory, "agent": agent,
410
+ "time_created": int(created),
411
+ "time_updated": None if updated is None else int(updated),
412
+ "first_seen": now_ms, "last_seen": now_ms,
413
+ })
414
+ except (TypeError, ValueError):
415
+ bad += 1
416
+ counts = _upsert(dest, "usage", "session_id", payload,
417
+ numeric=TOKEN_COLUMNS,
418
+ overwrite=("time_updated", "last_seen"),
419
+ insert_only=("first_seen", "time_created"))
420
+ if bad: # only when nonzero: a clean run carries no `skipped` key at all
421
+ counts["skipped"] = counts.get("skipped", 0) + bad
422
+ counts.update(import_opencode_steps(src, dest))
423
+ dest.commit()
424
+ return counts
425
+
426
+
427
+ def import_opencode_steps(src: sqlite3.Connection,
428
+ dest: sqlite3.Connection) -> dict:
429
+ """Snapshot OpenCode assistant steps into our opencode_steps table.
430
+
431
+ One row per session_message.id; step_ms and tokens_generated are monotonic
432
+ max, so re-recording can never double count and a pruned source can never
433
+ shrink history. A source without session_message imports as zero steps.
434
+
435
+ This family keeps its own loop instead of folding into `_upsert`: the dense
436
+ turn ordinals and the rule that a NULL step_ms never maxes against a real
437
+ duration are semantics, not duplication.
438
+
439
+ `step_ms` is a duration, not a running total: NULL means "no information"
440
+ (the step never streamed), so it is deliberately NOT folded into max() as
441
+ a zero — unlike the other numeric columns. Keep the stored value when the
442
+ new reading is NULL, take the new value when none was stored. The spec's
443
+ turn rule requires this: a never-streamed step contributes no duration.
444
+
445
+ Turn numbers are dense 0-based ORDINALS, not raw message indices. The
446
+ boundary walk (_turn_index) returns the index of the input message opening
447
+ the turn; distinct boundary indices are numbered in first-appearance order
448
+ so the first turn's steps get 0, the next turn's get 1, and so on. This
449
+ keeps _turn_index's raw-index contract intact (Task 1 pins it) while the
450
+ stored turn stays a small, stable label. A skipped row never claims an
451
+ ordinal, so stored turns still start at 0.
452
+
453
+ Turns are recomputed for every LIVE session, so growth and the legacy ->
454
+ idle flip still regroup turns. A session is frozen ONLY when the source has
455
+ lost a step we already stored (a stored message_id missing from the current
456
+ assistant messages): pruning would otherwise move boundaries and silently
457
+ rewrite historical rates. Frozen rows keep their stored turn; new rows in a
458
+ pruned session take dense ordinals continuing from that session's stored
459
+ maximum, so they cannot collide with a frozen one.
460
+
461
+ Per-row isolation covers the whole body — ordinal lookup, blob parse,
462
+ arithmetic and upsert — against sqlite3.Error, TypeError and ValueError.
463
+ A well-formed blob with non-numeric timing/token fields raises TypeError
464
+ in the arithmetic; per the spec's error-isolation constraint it bumps
465
+ `skipped` instead of aborting the snapshot.
466
+ """
467
+ counts = Counter(inserted=0, updated=0, unchanged=0)
468
+ has_table = src.execute(
469
+ "SELECT name FROM sqlite_master WHERE type='table'"
470
+ " AND name='session_message'").fetchone()
471
+ if not has_table:
472
+ return counts
473
+ rows = src.execute(
474
+ "SELECT id, session_id, type, time_created, data FROM session_message"
475
+ " ORDER BY session_id, time_created").fetchall()
476
+ # One pass over our own store: {session_id: {message_id: stored turn}}.
477
+ # This detects pruning (a stored step gone from the source) and supplies
478
+ # the high-water mark for new rows in a pruned session, without an N+1
479
+ # SELECT per session or per row beyond the existing per-row upsert probe.
480
+ stored_by_session = {}
481
+ for sid, mid, turn in dest.execute(
482
+ "SELECT session_id, message_id, turn FROM opencode_steps"):
483
+ stored_by_session.setdefault(sid, {})[mid] = turn
484
+ # ORDER BY keeps each session's messages contiguous and in time order.
485
+ sessions = {}
486
+ for row in rows:
487
+ sessions.setdefault(row[1], []).append(row)
488
+ for sid, msgs in sessions.items():
489
+ stored = stored_by_session.get(sid, {})
490
+ present_ids = {m[0] for m in msgs if m[2] == "assistant"}
491
+ pruned = bool(stored.keys() - present_ids)
492
+ stored_max = max(stored.values(), default=-1)
493
+ types = [m[2] for m in msgs]
494
+ legacy = not any(kind == "idle" for kind in types)
495
+ turn_ordinals = {} # live session: recomputed dense ordinals
496
+ new_turn_ordinals = {} # pruned session: dense ordinals for NEW rows
497
+ for i, (mid, sid, kind, created, data) in enumerate(msgs):
498
+ if kind != "assistant":
499
+ continue
500
+ try:
501
+ boundary = _turn_index(types, i + 1, legacy)
502
+ data_obj = json.loads(data)
503
+ # Non-dict JSON is an extraction failure, not a row error
504
+ # (mirrors parse_model): the step still inserts, with no
505
+ # duration and no generated tokens.
506
+ if not isinstance(data_obj, dict):
507
+ data_obj = {}
508
+ timing = data_obj.get("time")
509
+ tokens = data_obj.get("tokens")
510
+ timing = timing if isinstance(timing, dict) else {}
511
+ tokens = tokens if isinstance(tokens, dict) else {}
512
+ streamed = timing.get("streamed")
513
+ if streamed is None:
514
+ step_ms = None
515
+ else:
516
+ first = timing.get("firstToken")
517
+ start = first if first is not None else created
518
+ step_ms = max(0, streamed - start)
519
+ tokens_generated = ((tokens.get("output") or 0)
520
+ + (tokens.get("reasoning") or 0))
521
+ existing = dest.execute(
522
+ "SELECT step_ms, tokens_generated FROM opencode_steps"
523
+ " WHERE message_id = ?", (mid,)).fetchone()
524
+ is_new = existing is None
525
+ # Peek at the ordinal without claiming it: a row that fails
526
+ # anywhere below must not consume a turn number. In a pruned
527
+ # session existing rows keep their stored turn (the UPDATE
528
+ # below omits `turn`); new rows continue the stored sequence
529
+ # so they cannot collide with a frozen ordinal.
530
+ if not pruned:
531
+ turn = turn_ordinals.get(boundary)
532
+ if turn is None:
533
+ turn = len(turn_ordinals)
534
+ elif is_new:
535
+ turn = new_turn_ordinals.get(boundary)
536
+ if turn is None:
537
+ turn = stored_max + 1 + len(new_turn_ordinals)
538
+ else:
539
+ turn = None # frozen row: leave its stored turn alone
540
+ if is_new:
541
+ dest.execute(
542
+ "INSERT INTO opencode_steps (message_id, session_id,"
543
+ " turn, step_ms, tokens_generated, time_created)"
544
+ " VALUES (?,?,?,?,?,?)",
545
+ [mid, sid, turn, step_ms, tokens_generated, created])
546
+ outcome = "inserted"
547
+ else:
548
+ old_step, old_tokens = existing
549
+ # NULL is "no information", never a zero to max against.
550
+ if step_ms is None:
551
+ merged_step = old_step
552
+ elif old_step is None:
553
+ merged_step = step_ms
554
+ else:
555
+ merged_step = max(old_step, step_ms)
556
+ merged = [merged_step, max(old_tokens, tokens_generated)]
557
+ changed = merged != list(existing)
558
+ if pruned:
559
+ dest.execute(
560
+ "UPDATE opencode_steps SET step_ms = ?,"
561
+ " tokens_generated = ?, time_created = ?"
562
+ " WHERE message_id = ?",
563
+ [*merged, created, mid])
564
+ else:
565
+ dest.execute(
566
+ "UPDATE opencode_steps SET turn = ?, step_ms = ?,"
567
+ " tokens_generated = ?, time_created = ?"
568
+ " WHERE message_id = ?",
569
+ [turn, *merged, created, mid])
570
+ outcome = "updated" if changed else "unchanged"
571
+ # The upsert succeeded — now the ordinal is official.
572
+ if not pruned:
573
+ turn_ordinals[boundary] = turn
574
+ elif is_new:
575
+ new_turn_ordinals[boundary] = turn
576
+ counts[outcome] += 1
577
+ except (sqlite3.Error, TypeError, ValueError):
578
+ # One malformed source row must not abort (or roll back) the
579
+ # rest, and must not consume a turn ordinal.
580
+ counts["skipped"] += 1
581
+ dest.commit()
582
+ return counts
583
+
584
+
585
+ def _like_pattern(model):
586
+ """Lowered substring LIKE pattern for `model`, with the LIKE metacharacters
587
+ `%` and `_` escaped so user text always matches literally (pairs with
588
+ ESCAPE '\\')."""
589
+ return "%" + model.lower().replace("%", "\\%").replace("_", "\\_") + "%"
590
+
591
+
592
+ def _date_clauses(column, since_ms, until_ms):
593
+ """(where, params) for an inclusive date window over `column`: since is a
594
+ lower bound, until is exclusive at the end of the until-day (via
595
+ _day_end_ms, local-time and DST-safe). Empty lists when unbounded."""
596
+ where, params = [], []
597
+ if since_ms is not None:
598
+ where.append(column + " >= ?")
599
+ params.append(since_ms)
600
+ if until_ms is not None:
601
+ where.append(column + " < ?")
602
+ params.append(_day_end_ms(until_ms)) # until-day inclusive
603
+ return where, params
604
+
605
+
606
+ def _weighted_mean_rate_and_weight(pairs):
607
+ """(token-weighted mean rate, Σ weight of the rows that averaged into it).
608
+
609
+ Rows with no rate or no weight drop out of BOTH sides; `den` is exactly the
610
+ denominator the mean divided by, exposed so an aggregate row can carry the
611
+ weight it actually used rather than a sum over rows it ignored."""
612
+ num = den = 0
613
+ for rate, weight in pairs:
614
+ if rate is not None and weight:
615
+ num += rate * weight
616
+ den += weight
617
+ return (round(num / den, 1) if den else None), den
618
+
619
+
620
+ def _weighted_mean_rate(pairs):
621
+ """Token-weighted mean of `pairs`, a group's (rate, tokens moved) pairs,
622
+ rounded to one decimal like every other rate; None when nothing is left.
623
+
624
+ Each row's rate counts in proportion to the tokens it moved, so a session
625
+ that carried 200k tokens speaks 200x one that carried 1k. Rows with no
626
+ rate (session with no valid turn, unfinished or failed run) and rows with
627
+ no tokens are dropped from BOTH sides: they cannot be averaged and they
628
+ carry no weight. The alternative — dividing the group's token sum by its
629
+ calendar span — counted every idle second between and inside sessions, so
630
+ one session left open overnight sank a model's average below every row
631
+ above it."""
632
+ return _weighted_mean_rate_and_weight(pairs)[0]
633
+
634
+
635
+ def _session_rate_groups(dest, key_sql, where, params):
636
+ """{group key: [(per-session turn-mean rate, generated tokens)]} for
637
+ sessions matching `where`, using query_sessions' own turn-derived rate and
638
+ generated-token weight so an aggregate stays reproducible from the rates
639
+ the sessions view displays. A rate is None when the session has no valid
640
+ turn. `key_sql` is the SQL expression to group on."""
641
+ sql = ("SELECT " + key_sql + ", " + _TURN_RATE_SQL + ", " + _GENERATED_SQL
642
+ + " FROM usage")
643
+ if where:
644
+ sql += " WHERE " + " AND ".join(where)
645
+ groups = {}
646
+ for key, rate, generated in dest.execute(sql, params):
647
+ groups.setdefault(key, []).append((rate, generated or 0))
648
+ return groups
649
+
650
+
651
+ def _grouped_aggregates(dest, table, key_sql, sums, where, params, groups,
652
+ row_builder):
653
+ """One engine for every grouped aggregate view: SELECT key + `sums`,
654
+ GROUP BY key ORDER BY key ASC, one row dict per group from
655
+ row_builder(key, counts, rate, weight).
656
+
657
+ `counts` is the aggregate tuple (the `sums` columns of the row). `groups`
658
+ maps a key to the (rate, weight) pairs to average for that row; None
659
+ means the family has no per-row rate to weight, and rate/weight arrive
660
+ None. Rows come back in query order.
661
+
662
+ `table`, `key_sql` and `sums` are SQL fragments, interpolated into the
663
+ statement rather than bound into it, so they are trusted internal values
664
+ only: every caller passes a literal from this module (or a builder built
665
+ from one). User input reaches a query through `where` and `params`, which
666
+ are parameterized — nothing derived from a command line may be passed
667
+ here. Same contract for `_run_rate_groups` and `_session_rate_groups`."""
668
+ sql = "SELECT " + key_sql + " AS key," + sums + " FROM " + table
669
+ if where:
670
+ sql += " WHERE " + " AND ".join(where)
671
+ sql += " GROUP BY key ORDER BY key ASC"
672
+ rows = []
673
+ for row in dest.execute(sql, params):
674
+ key, counts = row[0], tuple(row[1:])
675
+ if groups is None:
676
+ rate = weight = None
677
+ else:
678
+ rate, weight = _weighted_mean_rate_and_weight(groups.get(key, []))
679
+ rows.append(row_builder(key, counts, rate, weight))
680
+ return rows
681
+
682
+
683
+ def _total_aggregates(dest, table, sums, where, params, groups, row_builder,
684
+ group_key_sql=None):
685
+ """All-time aggregates: with `group_key_sql`, the same grouped rows
686
+ _grouped_aggregates would build; without it, one grand-total row keyed
687
+ "(all)" (empty when nothing matches — COUNT(*) is 0), whose rate group is
688
+ groups.get("(all)", []).
689
+
690
+ `table`, `sums` and `group_key_sql` are the same trusted internal SQL
691
+ fragments _grouped_aggregates documents, and the same rule applies."""
692
+ if group_key_sql is not None:
693
+ return _grouped_aggregates(dest, table, group_key_sql, sums, where,
694
+ params, groups, row_builder)
695
+ sql = "SELECT" + sums + " FROM " + table
696
+ if where:
697
+ sql += " WHERE " + " AND ".join(where)
698
+ found = dest.execute(sql, params).fetchone()
699
+ if not found[0]:
700
+ return []
701
+ if groups is None:
702
+ rate = weight = None
703
+ else:
704
+ rate, weight = _weighted_mean_rate_and_weight(groups.get("(all)", []))
705
+ return [row_builder("(all)", tuple(found), rate, weight)]
706
+
707
+
708
+ DAY_MS = 86_400_000
709
+
710
+
711
+ def _day_end_ms(until_ms):
712
+ """Exclusive upper bound for an inclusive until-day: local midnight of
713
+ the next calendar day (DST-safe, unlike until_ms + DAY_MS)."""
714
+ start = datetime.datetime.fromtimestamp(until_ms / 1000)
715
+ return int((start + datetime.timedelta(days=1)).timestamp() * 1000)
716
+
717
+
718
+ def parse_date(s: str) -> int:
719
+ """YYYY-MM-DD -> epoch ms at local midnight."""
720
+ try:
721
+ dt = datetime.datetime.strptime(s, "%Y-%m-%d")
722
+ except ValueError:
723
+ raise argparse.ArgumentTypeError(
724
+ f"invalid date {s!r}, expected YYYY-MM-DD") from None
725
+ return int(dt.timestamp() * 1000)
726
+
727
+
728
+ def _session_filters(model, since_ms, until_ms, min_in, min_out, limit=None):
729
+ where, params = [], []
730
+ if model:
731
+ where.append("lower(provider || '/' || model_id) LIKE ? ESCAPE '\\'")
732
+ params.append(_like_pattern(model))
733
+ date_where, date_params = _date_clauses("time_created", since_ms, until_ms)
734
+ where.extend(date_where)
735
+ params.extend(date_params)
736
+ if min_in is not None:
737
+ where.append("tokens_input >= ?")
738
+ params.append(min_in)
739
+ if min_out is not None:
740
+ where.append("tokens_output >= ?")
741
+ params.append(min_out)
742
+ if limit: # None and 0 both mean "no cap"
743
+ inner = list(params)
744
+ where.append("session_id IN (SELECT session_id FROM usage"
745
+ + (" WHERE " + " AND ".join(where) if where else "")
746
+ + " ORDER BY time_created DESC, session_id LIMIT ?)")
747
+ params = inner + inner + [int(limit)]
748
+ return where, params
749
+
750
+
751
+ # Scalar subqueries correlated on usage.session_id, reused by the aggregate
752
+ # views (Task 4). _TURN_RATE_SQL is the unweighted mean of the session's turn
753
+ # rates; a turn is excluded when ANY step never streamed (COUNT(step_ms) <>
754
+ # COUNT(*)), when it moved no tokens, or when its pooled span is sub-second.
755
+ # _GENERATED_SQL is the session's total generated tokens (output+reasoning).
756
+ _TURN_RATE_SQL = (
757
+ "(SELECT AVG(rate) FROM (SELECT SUM(tokens_generated) * 1000.0"
758
+ " / SUM(step_ms) AS rate FROM opencode_steps"
759
+ " WHERE opencode_steps.session_id = usage.session_id GROUP BY turn"
760
+ " HAVING COUNT(step_ms) = COUNT(*) AND SUM(step_ms) >= 1000"
761
+ " AND SUM(tokens_generated) > 0))")
762
+ _GENERATED_SQL = (
763
+ "(SELECT SUM(tokens_generated) FROM opencode_steps"
764
+ " WHERE opencode_steps.session_id = usage.session_id)")
765
+
766
+
767
+ def query_sessions(dest, model=None, since_ms=None, until_ms=None,
768
+ min_in=None, min_out=None, limit=None):
769
+ """Session rows matching all given filters, oldest first.
770
+
771
+ tok_s is the unweighted mean of the session's per-turn rates — the number
772
+ OpenCode shows per prompt: Σ(output+reasoning) / Σ(streamed - firstToken)
773
+ per turn, then averaged across turns. None when the session has no valid
774
+ turn. rate_weight is the session's total generated tokens. There is
775
+ deliberately no wall-clock fallback: mixing the two bases is the bug this
776
+ replaces. limit=N keeps only the N most recent matching sessions
777
+ (None/0 = uncapped)."""
778
+ sql = ("SELECT time_created, provider, model_id, tokens_input,"
779
+ " tokens_output, cost, title, tokens_cache_read,"
780
+ " tokens_cache_write, " + _TURN_RATE_SQL + ", " + _GENERATED_SQL
781
+ + " FROM usage")
782
+ where, params = _session_filters(model, since_ms, until_ms, min_in,
783
+ min_out, limit)
784
+ if where:
785
+ sql += " WHERE " + " AND ".join(where)
786
+ sql += " ORDER BY time_created ASC"
787
+ rows = []
788
+ for (created, provider, model_id, tin, tout, cost, title, tcr, tcw,
789
+ rate, generated) in dest.execute(sql, params):
790
+ date = datetime.datetime.fromtimestamp(created / 1000).strftime(
791
+ "%Y-%m-%d")
792
+ rows.append({"date": date, "model": f"{provider}/{model_id}",
793
+ "tokens_input": tin, "tokens_output": tout,
794
+ "total": tin + tout, "cost": cost, "title": title or "",
795
+ "tokens_cache_read": tcr, "tokens_cache_write": tcw,
796
+ "tok_s": round(rate, 1) if rate is not None else None,
797
+ "rate_weight": generated or 0})
798
+ return rows
799
+
800
+
801
+ def most_recent(rows, n):
802
+ """`rows` oldest-first in, newest-first out, truncated to `n`;
803
+ n <= 0 keeps all. The one recency step shared by the default
804
+ dashboard's session panel and the --sessions list view."""
805
+ rev = list(reversed(rows))
806
+ return rev[:n] if n > 0 else rev
807
+
808
+
809
+ def _sessions_limit(value, daily, total):
810
+ """Resolve --sessions into the `limit=` the query functions take
811
+ (None = flag absent, 0 = uncapped, N = N most recent).
812
+
813
+ A valueless --sessions lists the 20 most recent sessions, but means ALL
814
+ sessions in the aggregate views: with --daily/--total the view is about
815
+ coverage, not recency. `total` is the EFFECTIVE total flag — bare
816
+ --model is the --total shortcut and counts, so a valueless --sessions
817
+ with `--sessions --model` also means all sessions."""
818
+ if value is None:
819
+ return None
820
+ if value is SESSIONS_BARE:
821
+ return 0 if (daily or total) else 20
822
+ return value
823
+
824
+
825
+ SESSION_COLUMNS = [
826
+ ("DATE", "date", "text"), ("MODEL", "model", "text"),
827
+ ("TOTAL", "total", "int"), ("TOK/S", "tok_s", "rate"),
828
+ ("IN", "tokens_input", "int"), ("OUT", "tokens_output", "int"),
829
+ ("SESSION", "title", "title"),
830
+ ]
831
+ DAILY_COLUMNS = [
832
+ ("DATE", "date", "text"),
833
+ ("TOTAL", "total", "int"), ("TOK/S", "tok_s", "rate"),
834
+ ("SESSIONS", "sessions", "int"),
835
+ ("IN", "tokens_input", "int"), ("OUT", "tokens_output", "int"),
836
+ ]
837
+ TOTAL_COLUMNS = [
838
+ ("MODEL", "model", "text"),
839
+ ("TOTAL", "total", "int"), ("TOK/S", "tok_s", "rate"),
840
+ ("SESSIONS", "sessions", "int"),
841
+ ("IN", "tokens_input", "int"), ("OUT", "tokens_output", "int"),
842
+ ]
843
+ SHARE_COLUMNS = TOTAL_COLUMNS + [
844
+ # share pair (human decision): the percent column is "SHARE %", the bar
845
+ # column "SHARE" — labeled so the visual reads at a glance.
846
+ ("SHARE %", "share_str", "text"), ("SHARE", "bar", "text"),
847
+ ]
848
+
849
+
850
+ def cost_column(tier):
851
+ """(header, key, kind) for the opt-in --cost overlay; the header names the
852
+ model the pricing is pinned to, so a stale price table is visible.
853
+ SINGLE line (human decision): "COST · <model> Prices" — compactness wins
854
+ over column width; the whole head stays one line tall."""
855
+ return (f"COST \u00b7 {PRICES[tier]['name']} Prices", "cost_est", "cost")
856
+
857
+
858
+ # --real-cost overlay: the stored real cost (real OpenCode data); every
859
+ # session-family row and aggregate already carries `cost`, display-only.
860
+ REAL_COST_COLUMN = ("REAL COST", "cost", "cost")
861
+ CACHE_COLUMN = ("CACHE", "cache", "int") # opt-in --cache display overlay
862
+
863
+
864
+ def annotate_cache(rows):
865
+ """Copy of `rows` with the two cache classes combined into int `cache`.
866
+ Display-only overlay: inputs untouched, nothing stored, TOTAL unchanged."""
867
+ return [{**r, "cache": r.get("tokens_cache_read", 0)
868
+ + r.get("tokens_cache_write", 0)} for r in rows]
869
+
870
+
871
+ def with_cache(columns):
872
+ """Copy of `columns` with CACHE_COLUMN inserted after the OUT entry
873
+ (IN OUT CACHE reads as the token classes, CACHE outside the total)."""
874
+ out = list(columns)
875
+ i = next(i for i, (header, _, _) in enumerate(out) if header == "OUT")
876
+ out.insert(i + 1, CACHE_COLUMN)
877
+ return out
878
+
879
+
880
+ # Reference list prices, USD per million tokens, verified 2026-11-17.
881
+ # Anthropic bills cache reads at 0.1x and cache writes at 1.25x input;
882
+ # the other vendors bill no cache-write premium (cache_write = in).
883
+ PRICES = {
884
+ "haiku-4.5": {"name": "Claude Haiku 4.5", "in": 1.00, "out": 5.00, "cache_read": 0.10, "cache_write": 1.25},
885
+ "sonnet-5": {"name": "Claude Sonnet 5", "in": 2.00, "out": 10.00, "cache_read": 0.20, "cache_write": 2.50},
886
+ "opus-5": {"name": "Claude Opus 5", "in": 5.00, "out": 25.00, "cache_read": 0.50, "cache_write": 6.25},
887
+ "gpt-5.1-codex-mini": {"name": "GPT-5.1-Codex-Mini", "in": 0.25, "out": 2.00, "cache_read": 0.025, "cache_write": 0.25},
888
+ "gpt-5.1-codex": {"name": "GPT-5.1-Codex", "in": 1.25, "out": 10.00, "cache_read": 0.125, "cache_write": 1.25},
889
+ "deepseek-v3.2": {"name": "DeepSeek V3.2", "in": 0.28, "out": 0.40, "cache_read": 0.028, "cache_write": 0.28},
890
+ "qwen-turbo": {"name": "Qwen-Turbo", "in": 0.05, "out": 0.20, "cache_read": 0.05, "cache_write": 0.05},
891
+ "qwen-plus": {"name": "Qwen-Plus", "in": 0.40, "out": 1.20, "cache_read": 0.40, "cache_write": 0.40},
892
+ "qwen-max": {"name": "Qwen-Max", "in": 1.60, "out": 6.40, "cache_read": 1.60, "cache_write": 1.60},
893
+ }
894
+
895
+ # Family name -> the mid-tier model the provider offers (two-model lineups:
896
+ # the standard model is the mid, not the light one).
897
+ FAMILY_ALIASES = {"claude": "sonnet-5", "openai": "gpt-5.1-codex",
898
+ "codex": "gpt-5.1-codex", "deepseek": "deepseek-v3.2",
899
+ "qwen": "qwen-plus"}
900
+
901
+
902
+ def resolve_cost_tier(slug):
903
+ """Family alias -> mid-tier model slug; model slugs pass through."""
904
+ return FAMILY_ALIASES.get(slug, slug)
905
+
906
+
907
+ def annotate_cost(rows, tier="sonnet-5"):
908
+ """Copy of `rows` with a reference estimate added as float `cost_est`
909
+ (USD), priced at `tier`'s entry in PRICES. Display/JSON overlay only:
910
+ inputs untouched, nothing stored. Row shape picks the math: run rows
911
+ (progress_tokens) price as output-only; session-family rows add the
912
+ cache classes; event rows use input+output."""
913
+ p = PRICES[tier]
914
+ out = []
915
+ for r in rows:
916
+ if "progress_tokens" in r:
917
+ est = r["progress_tokens"] * p["out"] / 1e6
918
+ elif "tokens_cache_read" in r:
919
+ est = (r["tokens_input"] * p["in"] + r["tokens_output"] * p["out"]
920
+ + r["tokens_cache_read"] * p["cache_read"]
921
+ + r["tokens_cache_write"] * p["cache_write"]) / 1e6
922
+ else:
923
+ est = (r["tokens_input"] * p["in"]
924
+ + r["tokens_output"] * p["out"]) / 1e6
925
+ out.append({**r, "cost_est": est})
926
+ return out
927
+
928
+
929
+ BAR_FULL = "█" # U+2588; fractions use the full-cell shades ░▒▓ (U+2591..2593).
930
+ # Eighth-block glyphs (U+2581..2587) match fill height better but sit on a
931
+ # different vertical metric than U+2588 in many fonts, which rags the bar's
932
+ # bottom edge — full-cell shades avoid that entirely.
933
+ BAR_SHADES = ("░", "▒", "▓") # light / medium / dark shade
934
+
935
+
936
+ def _bar(value, biggest, width):
937
+ """Smooth text bar: full blocks plus at most one shade block for the
938
+ fraction, length proportional to value/biggest; nonzero never renders
939
+ empty."""
940
+ if value <= 0 or biggest <= 0:
941
+ return ""
942
+ exact = width * value / biggest
943
+ full = int(exact)
944
+ eighths = round((exact - full) * 8)
945
+ if eighths == 8: # fraction rounded up to a whole block
946
+ full, eighths = full + 1, 0
947
+ shade = ""
948
+ if eighths:
949
+ shade = BAR_SHADES[0 if eighths <= 2 else 1 if eighths <= 4 else 2]
950
+ bar = BAR_FULL * full + shade
951
+ return bar or BAR_SHADES[0] # nonzero never renders empty
952
+
953
+
954
+ def add_shares(rows, bar_width=30):
955
+ """Copy of `rows` with per-row share of the overall (summed) total plus a
956
+ smooth Unicode bar scaled to the largest row. Pure display enrichment;
957
+ inputs untouched."""
958
+ overall = sum(r["total"] for r in rows)
959
+ biggest = max((r["total"] for r in rows), default=0)
960
+ out = []
961
+ for r in rows:
962
+ share = 100.0 * r["total"] / overall if overall else 0.0
963
+ out.append({**r, "share": share, "share_str": f"{share:.1f}%",
964
+ "bar": _bar(r["total"], biggest, bar_width)})
965
+ return out
966
+
967
+
968
+ # Neon Midnight palette for the display layer: near-black indigo chrome,
969
+ # a mirrored input-blue / output-pink pair for the token columns, lime for
970
+ # cache reads, violet totals (the gradient midpoint), teal derived stats.
971
+ # Every value is a true-color (r, g, b) triple.
972
+ NEON = {
973
+ "border": (76, 58, 120), "accent": (232, 121, 249),
974
+ "label": (169, 156, 201), "num": (244, 240, 255),
975
+ "tin": (96, 165, 250), "tout": (244, 114, 182),
976
+ "tcach": (163, 230, 53), "track": (30, 23, 48),
977
+ "ttotal": (167, 139, 250), "tshare": (94, 234, 212),
978
+ }
979
+
980
+ # Nine roles shared by every palette; `track` is legacy and lives in NEON only.
981
+ THEME_ROLES = ("border", "accent", "label", "num", "tin", "tout",
982
+ "tcach", "ttotal", "tshare")
983
+
984
+
985
+ def _hex(h):
986
+ """#RRGGBB -> (r, g, b) triple, so the palette hexes read as written."""
987
+ return tuple(int(h[i:i + 2], 16) for i in (1, 3, 5))
988
+
989
+
990
+ # dracula/nord/monokai `label` values are lifted from each scheme's comment color so the hero's date span stays readable.
991
+ TOKYO_NIGHT = {
992
+ "border": _hex("#414868"), "accent": _hex("#F7768E"),
993
+ "label": _hex("#7982A9"), "num": _hex("#C0CAF5"),
994
+ "tin": _hex("#7AA2F7"), "tout": _hex("#FF9E64"),
995
+ "tcach": _hex("#9ECE6A"), "ttotal": _hex("#BB9AF7"),
996
+ "tshare": _hex("#2ACBCF"),
997
+ }
998
+ DRACULA = {
999
+ "border": _hex("#6272A4"), "accent": _hex("#FF79C6"),
1000
+ "label": _hex("#8A94C0"), "num": _hex("#F8F8F2"),
1001
+ "tin": _hex("#8BE9FD"), "tout": _hex("#FFB86C"),
1002
+ "tcach": _hex("#50FA7B"), "ttotal": _hex("#BD93F9"),
1003
+ "tshare": _hex("#F1FA8C"),
1004
+ }
1005
+ NORD = {
1006
+ "border": _hex("#4C566A"), "accent": _hex("#BF616A"),
1007
+ "label": _hex("#7B88A1"), "num": _hex("#ECEFF4"),
1008
+ "tin": _hex("#88C0D0"), "tout": _hex("#D08770"),
1009
+ "tcach": _hex("#A3BE8C"), "ttotal": _hex("#B48EAD"),
1010
+ "tshare": _hex("#EBCB8B"),
1011
+ }
1012
+ GRUVBOX_DARK = {
1013
+ "border": _hex("#665C54"), "accent": _hex("#FE8019"),
1014
+ "label": _hex("#A89984"), "num": _hex("#EBDBB2"),
1015
+ "tin": _hex("#83A598"), "tout": _hex("#FB4934"),
1016
+ "tcach": _hex("#B8BB26"), "ttotal": _hex("#D38696"),
1017
+ "tshare": _hex("#8EC07C"),
1018
+ }
1019
+ SOLARIZED_DARK = {
1020
+ "border": _hex("#073642"), "accent": _hex("#D33682"),
1021
+ "label": _hex("#839496"), "num": _hex("#EEE8D5"),
1022
+ "tin": _hex("#268BD2"), "tout": _hex("#CB4B16"),
1023
+ "tcach": _hex("#859900"), "ttotal": _hex("#6C71C4"),
1024
+ "tshare": _hex("#2AA198"),
1025
+ }
1026
+ MONOKAI = {
1027
+ "border": _hex("#75715E"), "accent": _hex("#F92672"),
1028
+ "label": _hex("#9B9277"), "num": _hex("#F8F8F2"),
1029
+ "tin": _hex("#66D9EF"), "tout": _hex("#FD971F"),
1030
+ "tcach": _hex("#A6E22E"), "ttotal": _hex("#AE81FF"),
1031
+ "tshare": _hex("#F4BF75"),
1032
+ }
1033
+ ONE_DARK = {
1034
+ "border": _hex("#4B5263"), "accent": _hex("#C678DD"),
1035
+ "label": _hex("#7F8695"), "num": _hex("#ABB2BF"),
1036
+ "tin": _hex("#61AFEF"), "tout": _hex("#E06C75"),
1037
+ "tcach": _hex("#98C379"), "ttotal": _hex("#E5C07B"),
1038
+ "tshare": _hex("#56B6C2"),
1039
+ }
1040
+ SOLARIZED_LIGHT = {
1041
+ "border": _hex("#93A1A1"), "accent": _hex("#D33682"),
1042
+ "label": _hex("#657B83"), "num": _hex("#073642"),
1043
+ "tin": _hex("#268BD2"), "tout": _hex("#CB4B16"),
1044
+ "tcach": _hex("#859900"), "ttotal": _hex("#6C71C4"),
1045
+ "tshare": _hex("#2AA198"),
1046
+ }
1047
+ PAPER = {
1048
+ "border": _hex("#B0B7C3"), "accent": _hex("#BE185D"),
1049
+ "label": _hex("#6B7280"), "num": _hex("#1F2328"),
1050
+ "tin": _hex("#1D4ED8"), "tout": _hex("#C2410C"),
1051
+ "tcach": _hex("#15803D"), "ttotal": _hex("#6D28D9"),
1052
+ "tshare": _hex("#0E7490"),
1053
+ }
1054
+ THEMES = {
1055
+ "neon-midnight": ("Neon Midnight", {role: NEON[role] for role in THEME_ROLES}),
1056
+ "tokyo-night": ("Tokyo Night", TOKYO_NIGHT),
1057
+ "dracula": ("Dracula", DRACULA),
1058
+ "nord": ("Nord", NORD),
1059
+ "gruvbox-dark": ("Gruvbox Dark", GRUVBOX_DARK),
1060
+ "solarized-dark": ("Solarized Dark", SOLARIZED_DARK),
1061
+ "monokai": ("Monokai", MONOKAI),
1062
+ "one-dark": ("One Dark", ONE_DARK),
1063
+ "solarized-light": ("Solarized Light", SOLARIZED_LIGHT),
1064
+ "paper": ("Paper", PAPER),
1065
+ }
1066
+
1067
+ # Strict hex for user-supplied files: exactly '#rrggbb', digits or a-f, any
1068
+ # case. (The _hex() helper above is deliberately NOT reused — it is permissive
1069
+ # and only for the built-in palettes.)
1070
+ _THEME_HEX_RE = re.compile(r"#[0-9a-fA-F]{6}\Z")
1071
+
1072
+
1073
+ class ThemeError(Exception):
1074
+ """A theme file or slug could not be used."""
1075
+
1076
+
1077
+ def _theme_from_obj(obj, origin):
1078
+ """Validate one parsed theme object: a str `name` and a `colors` dict
1079
+ holding every THEME_ROLES key (extra keys ignored), each value a 7-char
1080
+ '#rrggbb' string. Returns (display name, colors) with (r, g, b) triples;
1081
+ `origin` names the file in the user-facing messages."""
1082
+ if not isinstance(obj, dict):
1083
+ raise ThemeError(f"{origin}: theme must be a JSON object with "
1084
+ f"'name' and 'colors'")
1085
+ name = obj.get("name")
1086
+ if not isinstance(name, str) or not name.strip():
1087
+ raise ThemeError(f"{origin}: theme 'name' must be a non-empty string")
1088
+ raw = obj.get("colors")
1089
+ if not isinstance(raw, dict):
1090
+ raise ThemeError(f"{origin}: theme 'colors' must be a JSON object")
1091
+ missing = [role for role in THEME_ROLES if role not in raw]
1092
+ if missing:
1093
+ raise ThemeError(f"{origin}: theme colors missing {', '.join(missing)}")
1094
+ colors = {}
1095
+ for role in THEME_ROLES:
1096
+ hexstr = raw[role]
1097
+ if not isinstance(hexstr, str) or not _THEME_HEX_RE.match(hexstr):
1098
+ raise ThemeError(f"{origin}: role '{role}' is not a #rrggbb "
1099
+ f"color: {hexstr!r}")
1100
+ colors[role] = (int(hexstr[1:3], 16), int(hexstr[3:5], 16),
1101
+ int(hexstr[5:7], 16))
1102
+ return name, colors
1103
+
1104
+
1105
+ def load_theme_file(path):
1106
+ """Read + validate one theme JSON file; returns (display name, colors)."""
1107
+ try:
1108
+ # encoding pinned so a theme file parses identically in every locale;
1109
+ # undecodable bytes (UTF-16-authored, binary misnamed .json) are a
1110
+ # ThemeError like any other parse failure, never a traceback.
1111
+ with open(path, encoding="utf-8") as fh:
1112
+ obj = json.load(fh)
1113
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
1114
+ raise ThemeError(f"{path}: {exc}") from exc
1115
+ return _theme_from_obj(obj, path)
1116
+
1117
+
1118
+ def scan_themes(dir=THEMES_DIR, warn=None):
1119
+ """Built-in THEMES merged with every *.json in `dir` (folder wins on slug
1120
+ collision), except the saved-default file `config.json` (see THEME_CONFIG):
1121
+ it shares this folder but is not a theme, so a scan never reads it, warns
1122
+ about it, or lists "config" as a slug. A file that raises ThemeError is
1123
+ skipped, reported through warn(f"warning: ...") when given; a missing dir
1124
+ is a no-op."""
1125
+ found = dict(THEMES)
1126
+ if os.path.isdir(dir):
1127
+ for fname in sorted(os.listdir(dir)):
1128
+ if not fname.endswith(".json"):
1129
+ continue
1130
+ # config.json is the saved-default file that lives in this same
1131
+ # folder (see THEME_CONFIG), not a theme: skip it so a scan neither
1132
+ # warns about it nor lists "config" as an available slug.
1133
+ if fname == "config.json":
1134
+ continue
1135
+ try:
1136
+ found[os.path.splitext(fname)[0]] = \
1137
+ load_theme_file(os.path.join(dir, fname))
1138
+ except ThemeError as exc:
1139
+ if warn is not None:
1140
+ warn(f"warning: {exc}")
1141
+ return found
1142
+
1143
+
1144
+ # The saved default theme lives in THEME_CONFIG (see the globals block at the
1145
+ # top) as {"default": "<slug>"}.
1146
+ # It is read whenever a run resolves a theme without an explicit --theme=SLUG
1147
+ # (and by the bare --theme list) and written by --theme-default; a missing or
1148
+ # unusable file is not an error, it simply means "no default saved".
1149
+
1150
+
1151
+ def read_default_theme(path=THEME_CONFIG, warn=None):
1152
+ """The saved default theme slug from `path`, or None. A missing file is a
1153
+ silent None; a file that exists but cannot be read, decoded, or parsed, is
1154
+ not a JSON object, or has no usable string "default" is reported through
1155
+ warn(f"warning: ...") and yields None — an unusable config must not let a
1156
+ saved theme silently stop applying with no clue why."""
1157
+ try:
1158
+ with open(path, encoding="utf-8") as fh:
1159
+ obj = json.load(fh)
1160
+ except FileNotFoundError:
1161
+ return None
1162
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
1163
+ if warn is not None:
1164
+ warn(f"warning: {path}: {exc}")
1165
+ return None
1166
+ if not isinstance(obj, dict):
1167
+ if warn is not None:
1168
+ warn(f"warning: {path}: config must be a JSON object")
1169
+ return None
1170
+ slug = obj.get("default")
1171
+ if not isinstance(slug, str) or not slug:
1172
+ if warn is not None:
1173
+ warn(f"warning: {path}: no usable 'default' theme slug found")
1174
+ return None
1175
+ return slug
1176
+
1177
+
1178
+ def write_default_theme(path, slug):
1179
+ """Persist {"default": slug} to `path`, creating the parent folder if needed."""
1180
+ parent = os.path.dirname(path)
1181
+ if parent:
1182
+ os.makedirs(parent, exist_ok=True)
1183
+ with open(path, "w", encoding="utf-8") as fh:
1184
+ fh.write(json.dumps({"default": slug}) + "\n")
1185
+
1186
+
1187
+ def resolve_theme(slug, dir=THEMES_DIR, warn=None):
1188
+ """The role -> (r, g, b) colors for `slug`: None means the Neon Midnight
1189
+ default; a slug is looked up in scan_themes(dir) so folder themes resolve by
1190
+ slug too; an unknown slug raises ThemeError naming it and listing the
1191
+ available slugs. `warn`, when given, goes to that scan, so a theme file that
1192
+ is present but invalid reports its real reason instead of only reading as an
1193
+ unknown slug."""
1194
+ if slug is None:
1195
+ return NEON
1196
+ found = scan_themes(dir, warn=warn)
1197
+ if slug in found:
1198
+ return found[slug][1]
1199
+ raise ThemeError(f"unknown theme '{slug}'; available: "
1200
+ f"{', '.join(sorted(found))}")
1201
+
1202
+
1203
+ # Bars are a left-to-right color gradient: input tokens blue fading into
1204
+ # output-token pink, with the transition centered where the input share of
1205
+ # the row's total ends. Interpolated in HSL sweeping UP from blue through
1206
+ # violet (never through gray); hue, lightness AND saturation are lerped
1207
+ # between the endpoints so both ends reproduce them exactly. Those endpoints
1208
+ # now come from the resolved theme paint_bars is handed (its `tin`/`tout`
1209
+ # roles), not from import-time globals; the two constants below are the default
1210
+ # theme's (NEON) endpoints and no production caller reads them any more — they
1211
+ # are kept as the public pin on that palette (NeonThemeTests pins them to
1212
+ # NEON["tin"]/NEON["tout"]).
1213
+ TOKEN_IN_RGB = NEON["tin"]
1214
+ TOKEN_OUT_RGB = NEON["tout"]
1215
+
1216
+
1217
+ def gradient_stops(theme):
1218
+ """The seven precomputed HLS values a theme's gradient runs on:
1219
+ (hue_in, lum_in, sat_in, hue_out, lum_out, sat_out, hue_span)."""
1220
+ hue_in, lum_in, sat_in = colorsys.rgb_to_hls(*(v / 255 for v in theme["tin"]))
1221
+ hue_out, lum_out, sat_out = colorsys.rgb_to_hls(*(v / 255 for v in theme["tout"]))
1222
+ # sweep UP (blue -> violet -> pink), wrapping past 1.0 when needed; for
1223
+ # the default pair it is the short arc
1224
+ return (hue_in, lum_in, sat_in, hue_out, lum_out, sat_out,
1225
+ (hue_out - hue_in) % 1.0)
1226
+
1227
+
1228
+ def _token_rgb(t, stops):
1229
+ """Blend from the theme's tin (t=0) to its tout (t=1), lerping hue
1230
+ (UP sweep), lightness, and saturation; endpoints round-trip exactly."""
1231
+ hue_in, lum_in, sat_in, hue_out, lum_out, sat_out, hue_span = stops
1232
+ r, g, b = colorsys.hls_to_rgb((hue_in + t * hue_span) % 1.0,
1233
+ lum_in + (lum_out - lum_in) * t,
1234
+ sat_in + (sat_out - sat_in) * t)
1235
+ return (round(r * 255), round(g * 255), round(b * 255))
1236
+
1237
+
1238
+ def _paint_gradient(bar, frac_in, stops):
1239
+ """Per-glyph true-color sweep; the IN->OUT midpoint lands at frac_in."""
1240
+ n = len(bar)
1241
+ parts = []
1242
+ for i, ch in enumerate(bar):
1243
+ if frac_in <= 0:
1244
+ t = 1.0
1245
+ elif frac_in >= 1:
1246
+ t = 0.0
1247
+ else:
1248
+ p = i / (n - 1) if n > 1 else 0.5
1249
+ t = 0.5 * p / frac_in if p <= frac_in \
1250
+ else 0.5 + 0.5 * (p - frac_in) / (1 - frac_in)
1251
+ r, g, b = _token_rgb(t, stops)
1252
+ parts.append(f"\x1b[38;2;{r};{g};{b}m{ch}")
1253
+ return "".join(parts) + "\x1b[0m"
1254
+
1255
+
1256
+ def _color_enabled(out, environ):
1257
+ """True-color output only on a terminal, and never under NO_COLOR. A
1258
+ stream that cannot answer isatty (None, as under pythonw) is not a
1259
+ terminal: plain output, no crash."""
1260
+ isatty = getattr(out, "isatty", None)
1261
+ return bool(isatty is not None and isatty()) and "NO_COLOR" not in environ
1262
+
1263
+
1264
+ def paint_bars(rows, color, theme=NEON):
1265
+ """Copy of `rows` with BAR cells padded by one space either side; when
1266
+ color is true, nonzero bars get a per-glyph gradient from `theme`'s tin to
1267
+ its tout whose transition marks the row's input/output split. Defaults to
1268
+ the Neon Midnight palette, so callers that pass no theme are unchanged.
1269
+ Table-only."""
1270
+ stops = gradient_stops(theme) if color else None
1271
+ out = []
1272
+ for r in rows:
1273
+ bar = r["bar"]
1274
+ if color and r["total"]:
1275
+ bar = _paint_gradient(bar, r["tokens_input"] / r["total"], stops)
1276
+ out.append({**r, "bar": f" {bar} "})
1277
+ return out
1278
+
1279
+
1280
+ def compact(n):
1281
+ """Token count in report form: 7.77M, 12.3k, 999."""
1282
+ if n >= 1_000_000:
1283
+ return f"{n / 1e6:.2f}M"
1284
+ if n >= 1_000:
1285
+ k = f"{n / 1e3:.1f}"
1286
+ # 999_950..999_999 would round the k-form to "1000.0k"; one step down
1287
+ # reads truer than promoting to M below the M threshold.
1288
+ return ("999.9" if k == "1000.0" else k) + "k"
1289
+ return str(n)
1290
+
1291
+
1292
+ # per painted key: (cell kind as in render_table.fmt, color role, bold)
1293
+ _PAINT_CELLS = {
1294
+ "tokens_input": ("int", "tin", False),
1295
+ "tokens_output": ("int", "tout", False),
1296
+ "cache": ("int", "tcach", False),
1297
+ "cost_est": ("cost", "num", False),
1298
+ "cost": ("cost", "num", False), # --real-cost's stored value
1299
+ "total": ("int", "ttotal", True),
1300
+ "share_str": ("text", "tshare", False),
1301
+ "sessions": ("int", "tshare", False), # row count: the hero's other stat
1302
+ "tok_s": ("rate", "accent", False), # same hue as the hero's TOK/S stat
1303
+ }
1304
+
1305
+
1306
+ def paint_cells(rows, theme=NEON):
1307
+ """Copy of `rows` whose token/cost/rate cells are wrapped in their class
1308
+ color. Values arrive raw (ints) or already rendered (strings); numbers are
1309
+ formatted exactly as `render_table.fmt` would, so painting never changes
1310
+ a cell's visible width. The input rows are left untouched."""
1311
+ def render(value, kind):
1312
+ if isinstance(value, str):
1313
+ return value # already a rendered cell
1314
+ if kind == "int":
1315
+ return f"{value:,}"
1316
+ if kind == "rate":
1317
+ return f"{value:.1f}"
1318
+ return f"${value:.2f}" # cost_est / cost
1319
+
1320
+ out = []
1321
+ for row in rows:
1322
+ painted = dict(row) # shallow copy: never mutate input
1323
+ for key, (kind, role, bold) in _PAINT_CELLS.items():
1324
+ value = painted.get(key)
1325
+ if value is None or value == "":
1326
+ continue
1327
+ r, g, b = theme[role]
1328
+ painted[key] = (f"\x1b[{'1;' if bold else ''}38;2;{r};{g};{b}m"
1329
+ f"{render(value, kind)}\x1b[0m")
1330
+ out.append(painted)
1331
+ return out
1332
+
1333
+
1334
+ _ANSI_RE = re.compile(r"\x1b\[[0-9;]*m") # SGR color sequences (painted bars)
1335
+
1336
+
1337
+ def _visible(cell):
1338
+ """Display length of a cell: len() ignoring escape-sequence bytes, so
1339
+ colored cells neither inflate column widths nor shift padded output."""
1340
+ return len(_ANSI_RE.sub("", cell))
1341
+
1342
+
1343
+ def panel(title, lines, theme=NEON, color=True):
1344
+ """Rounded frame around `lines`, headed by a ` tokenstats · {title} ` strip;
1345
+ an empty title renders the plain ` tokenstats ` strip (no separator).
1346
+ `color=False` emits the same frame characters with no escape bytes.
1347
+ Every returned line shares one visible width: the widest content line or
1348
+ the title strip, whichever is longer, plus the two border cells."""
1349
+ def paint(text, role, bold=False):
1350
+ if not text:
1351
+ return ""
1352
+ if not color:
1353
+ return text
1354
+ r, g, b = theme[role]
1355
+ return f"\x1b[{'1;' if bold else ''}38;2;{r};{g};{b}m{text}\x1b[0m"
1356
+
1357
+ if title:
1358
+ head = " tokenstats · "
1359
+ strip = f"{head}{title} "
1360
+ else:
1361
+ head = strip = " tokenstats "
1362
+ widest = max((_visible(ln) for ln in lines), default=0)
1363
+ # one space inset either side, but never narrower than the title strip
1364
+ inner = max(len(strip), widest + 2)
1365
+ top = ("╭" + paint(head, "accent", bold=True)
1366
+ + (paint(title + " ", "label") if title else "")
1367
+ + paint("─" * (inner - len(strip)), "border") + paint("╮", "border"))
1368
+ body = [paint("│", "border") + " " + ln + " " * (inner - 1 - _visible(ln))
1369
+ + paint("│", "border") for ln in lines]
1370
+ bottom = "╰" + paint("─" * inner, "border") + paint("╯", "border")
1371
+ return [top] + body + [bottom]
1372
+
1373
+
1374
+ def report_header(title, rows, theme=NEON, cost_est=None, real_cost=None,
1375
+ unit="rows", color=True, cache_total=None):
1376
+ """Hero panel for a report: one grand-total line over a dim date span.
1377
+ Safe for rows that carry no tokens_input/tokens_output keys and for rows
1378
+ whose date is missing or None (the span is omitted when none is dated).
1379
+ Segment order (human decision 2026-11-18): grand total, TOK/S, row
1380
+ count, in, out, then the opt-in tails — `cache_total` (int tokens,
1381
+ precomputed by the caller) appends a `· X cache` stat after out;
1382
+ `cost_est` (float USD) appends a `~$X.XX` reference-estimate tail;
1383
+ `real_cost` (float USD) appends a `· $X.XX` tail after it — no tilde,
1384
+ it is the stored real cost. Each omitted input drops its segment whole.
1385
+ `unit` names what one row means in this view (the dashboard passes
1386
+ "sessions").
1387
+ Rows carrying a `tok_s` add a token-weighted TOK/S stat; when none of
1388
+ them has a rate the segment is omitted entirely.
1389
+ `color=False` renders the same text with no escape bytes."""
1390
+ def sum_of(key):
1391
+ return sum(r.get(key) or 0 for r in rows)
1392
+
1393
+ def paint(text, rgb, bold=False):
1394
+ if not color:
1395
+ return text
1396
+ r, g, b = rgb
1397
+ return (f"\x1b[{'1;' if bold else ''}38;2;{r};{g};{b}m"
1398
+ f"{text}\x1b[0m")
1399
+
1400
+ # "1 sessions" would read wrong: singularize a count of one.
1401
+ n_rows = len(rows)
1402
+ unit1 = unit[:-1] if n_rows == 1 and unit.endswith("s") else unit
1403
+ # Same token-weighted mean the aggregate tables use, over exactly the rows
1404
+ # this hero summarizes, so the hero and the table under it never disagree.
1405
+ # A view whose rows carry no rate gets no TOK/S segment at all.
1406
+ rate = _weighted_mean_rate([(r.get("tok_s"),
1407
+ r.get("rate_weight", r.get("total") or 0))
1408
+ for r in rows])
1409
+ # IN/OUT tinted like the table columns; the grand total glows at the
1410
+ # gradient midpoint (bold); the row-count is a derived stat like SHARE,
1411
+ # so it wears the same teal; TOK/S takes the accent hue, the token-column
1412
+ # hues being claimed by the tables. Only the NUMBERS are painted — every
1413
+ # unit word ("tokens", "in", "out", " tok/s", the row-count unit) stays in
1414
+ # the terminal's own color. panel() measures visible width, so the escape
1415
+ # bytes never rag the frame.
1416
+ hero = (paint(compact(sum_of('total')), theme["ttotal"], bold=True)
1417
+ + " tokens"
1418
+ + (" · " + paint(f"{rate:.1f}", theme["accent"]) + " tok/s"
1419
+ if rate is not None else "")
1420
+ + " · " + paint(str(n_rows), theme["tshare"]) + " " + unit1
1421
+ + " · " + paint(compact(sum_of('tokens_input')), theme["tin"]) + " in"
1422
+ + " · " + paint(compact(sum_of('tokens_output')), theme["tout"]) + " out"
1423
+ + (" · " + paint(compact(cache_total), theme["tcach"]) + " cache"
1424
+ if cache_total is not None else "")
1425
+ + (" · " + paint(f"~${cost_est:,.2f}", theme["num"])
1426
+ if cost_est is not None else "")
1427
+ + (" · " + paint(f"${real_cost:,.2f}", theme["num"])
1428
+ if real_cost is not None else ""))
1429
+ lines = [hero]
1430
+ dates = sorted(d for d in (r.get("date") for r in rows) if d)
1431
+ if dates:
1432
+ span = dates[0] if dates[0] == dates[-1] else f"{dates[0]} → {dates[-1]}"
1433
+ lines.append(paint(span, theme["label"]))
1434
+ return panel(title, lines, theme, color=color)
1435
+
1436
+
1437
+ def _table_panel(title, rows, columns, share_view, color, theme=NEON):
1438
+ """Panel of the rendered table; share views get padded (and colored)
1439
+ bars first; the header block and its rule dim to their roles in color.
1440
+ Every painter below gets `theme`, so one theme owns the whole panel."""
1441
+ if share_view:
1442
+ rows = paint_bars(rows, color=color, theme=theme)
1443
+ table = render_table(paint_cells(rows, theme) if color else rows, columns)
1444
+ lines = table.splitlines()
1445
+ if color and table != "no sessions match\n":
1446
+ paint_header_block(lines, columns, theme=theme)
1447
+ return panel(title, lines, theme, color=color)
1448
+
1449
+
1450
+ def header_height(columns):
1451
+ """Lines the header block occupies: 1, plus one per "\\n" wrap in a name."""
1452
+ return max(name.count("\n") for name, _, _ in columns) + 1
1453
+
1454
+
1455
+ def paint_header_block(lines, columns, theme=NEON):
1456
+ """In place: header lines wear the label role (column names recede behind
1457
+ the painted numbers below them) and the rule under them the border hue.
1458
+ Color mode only; `lines` are render_table output for `columns`."""
1459
+ h_h = header_height(columns)
1460
+ r, g, b = theme["label"]
1461
+ for i in range(h_h):
1462
+ lines[i] = f"\x1b[38;2;{r};{g};{b}m{lines[i]}\x1b[0m"
1463
+ r, g, b = theme["border"]
1464
+ lines[h_h] = f"\x1b[38;2;{r};{g};{b}m{lines[h_h]}\x1b[0m"
1465
+
1466
+
1467
+ def render_table(rows, columns=None):
1468
+ """Aligned report. `columns` is a list of (header, key, kind). A header
1469
+ may contain "\\n" to wrap; header text bottom-left aligns and a rule
1470
+ separates the header block from the data."""
1471
+ if columns is None:
1472
+ columns = SESSION_COLUMNS
1473
+ if not rows:
1474
+ return "no sessions match\n"
1475
+
1476
+ def fmt(value, kind):
1477
+ if value is None:
1478
+ return ""
1479
+ if isinstance(value, str) and kind in ("int", "cost", "rate"):
1480
+ return value # already numeric-formatted (paint_cells)
1481
+ if kind == "rate":
1482
+ return f"{value:.1f}"
1483
+ if kind == "cost":
1484
+ return f"${value:.2f}"
1485
+ if kind == "int":
1486
+ return f"{value:,}"
1487
+ if kind == "title":
1488
+ return str(value)[:40]
1489
+ return str(value)
1490
+
1491
+ header = [name.split("\n") for name, _, _ in columns]
1492
+ h_h = max(len(h) for h in header)
1493
+ body = [[fmt(r.get(key), kind) for _, key, kind in columns] for r in rows]
1494
+ widths = []
1495
+ for i, (name, _, kind) in enumerate(columns):
1496
+ if i == len(columns) - 1:
1497
+ widths.append(None) # last column needs no padding
1498
+ else:
1499
+ widths.append(max([max(_visible(l) for l in header[i])]
1500
+ + [_visible(row[i]) for row in body]))
1501
+
1502
+ def line_out(cells):
1503
+ parts = []
1504
+ for i, cell in enumerate(cells):
1505
+ if widths[i] is None:
1506
+ parts.append(cell)
1507
+ else:
1508
+ # pad by visible length (ljust would count escape bytes)
1509
+ parts.append(cell + " " * (widths[i] - _visible(cell)))
1510
+ return " ".join(parts).rstrip()
1511
+
1512
+ # Header text BOTTOM-aligns (human decision): a wrapped column (the
1513
+ # --cost header) floats its first lines above, and every column's last
1514
+ # line sits on the rule that separates the head from the data.
1515
+ out = []
1516
+ for j in range(h_h):
1517
+ out.append(line_out([h[j - h_h] if len(h) + j >= h_h else ""
1518
+ for h in header]))
1519
+ for row in body:
1520
+ out.append(line_out(row))
1521
+ out.insert(h_h, "\u2500" * max(_visible(ln) for ln in out))
1522
+ return "\n".join(out) + "\n"
1523
+
1524
+
1525
+ def daily_totals(dest, model=None, since_ms=None, until_ms=None,
1526
+ min_in=None, min_out=None, limit=None):
1527
+ """Per-day aggregates matching the filters, oldest day first. TOK/S is the
1528
+ token-weighted mean of the day's per-session rates. limit=N aggregates
1529
+ only the N most recent matching sessions (None/0 = uncapped)."""
1530
+ where, params = _session_filters(model, since_ms, until_ms, min_in,
1531
+ min_out, limit)
1532
+ day_sql = "date(time_created/1000, 'unixepoch', 'localtime')"
1533
+ return _grouped_aggregates(
1534
+ dest, "usage", day_sql,
1535
+ " COUNT(*), SUM(tokens_input), SUM(tokens_output), SUM(cost),"
1536
+ " SUM(tokens_cache_read), SUM(tokens_cache_write)",
1537
+ where, params, _session_rate_groups(dest, day_sql, where, params),
1538
+ lambda day, counts, rate, weight: {
1539
+ "date": day, "sessions": counts[0], "tokens_input": counts[1] or 0,
1540
+ "tokens_output": counts[2] or 0,
1541
+ "total": (counts[1] or 0) + (counts[2] or 0),
1542
+ "cost": counts[3] or 0.0, "tokens_cache_read": counts[4] or 0,
1543
+ "tokens_cache_write": counts[5] or 0,
1544
+ "tok_s": rate, "rate_weight": weight})
1545
+
1546
+
1547
+ def total_totals(dest, model=None, since_ms=None, until_ms=None,
1548
+ min_in=None, min_out=None, by_model=False, limit=None):
1549
+ """All-time aggregates: one grand-total row; per-provider/model_id rows
1550
+ (ordered by that string) with a model filter or by_model=True. Empty
1551
+ when no rows match. TOK/S is the token-weighted mean of the group's
1552
+ per-session rates. limit=N aggregates only the N most recent matching
1553
+ sessions, in both the grand-total and per-model branches
1554
+ (None/0 = uncapped)."""
1555
+ where, params = _session_filters(model, since_ms, until_ms, min_in,
1556
+ min_out, limit)
1557
+ sums = (" COUNT(*), SUM(tokens_input), SUM(tokens_output), SUM(cost),"
1558
+ " SUM(tokens_cache_read), SUM(tokens_cache_write)")
1559
+ builder = lambda m, counts, rate, weight: _total_row(
1560
+ m, *counts, rate, weight)
1561
+ if not model and not by_model:
1562
+ return _total_aggregates(
1563
+ dest, "usage", sums, where, params,
1564
+ _session_rate_groups(dest, "'(all)'", where, params), builder)
1565
+ return _total_aggregates(
1566
+ dest, "usage", sums, where, params,
1567
+ _session_rate_groups(dest, "provider || '/' || model_id", where,
1568
+ params), builder,
1569
+ group_key_sql="provider || '/' || model_id")
1570
+
1571
+
1572
+ def _total_row(model, n, tin, tout, cost, tcr, tcw, rate, weight):
1573
+ """Row dict for total_totals: totals plus cache components, the
1574
+ token-weighted mean of the group's per-session rates (None if none of them
1575
+ carries weight), and the Σ weight that produced it."""
1576
+ tin, tout = tin or 0, tout or 0
1577
+ return {"model": model, "sessions": n, "tokens_input": tin,
1578
+ "tokens_output": tout, "total": tin + tout, "cost": cost or 0.0,
1579
+ "tokens_cache_read": tcr or 0, "tokens_cache_write": tcw or 0,
1580
+ "tok_s": rate, "rate_weight": weight}
1581
+
1582
+
1583
+ def _connect_src(path):
1584
+ """Open the source read-only via a proper file URI. The path is resolved
1585
+ and percent-encoded (`pathlib.Path.as_uri`), because a raw `#` truncates
1586
+ the URI filename and a raw `?` starts the query — either one silently
1587
+ drops `mode=ro` and points SQLite at the wrong file, where it would
1588
+ CREATE one (invariant 4: the source is never written). A path that cannot
1589
+ be a URI at all (a Windows UNC share) falls back to the naive form."""
1590
+ try:
1591
+ uri = pathlib.Path(path).resolve().as_uri() + "?mode=ro"
1592
+ except ValueError:
1593
+ uri = f"file:{path}?mode=ro"
1594
+ return sqlite3.connect(uri, uri=True)
1595
+
1596
+
1597
+ def _view_rows(dest, args, model, model_any, want_total, limit):
1598
+ """(rows, columns) for the view the flags ask for.
1599
+
1600
+ The total family ends with SHARE and the share-descending sort (ties keep
1601
+ SQL's alphabetical-by-model order, because the sort is stable); the session
1602
+ list renders newest first when a --sessions cap is in force. main has
1603
+ already rejected --total x --daily by the time this runs."""
1604
+ if want_total:
1605
+ rows = total_totals(dest, model=model, since_ms=args.since,
1606
+ until_ms=args.until, min_in=args.min_in,
1607
+ min_out=args.min_out, by_model=model_any,
1608
+ limit=limit)
1609
+ rows = add_shares(rows)
1610
+ rows.sort(key=lambda r: -r["share"]) # biggest share first
1611
+ return rows, SHARE_COLUMNS
1612
+ rows = (daily_totals(dest, model=model, since_ms=args.since,
1613
+ until_ms=args.until, min_in=args.min_in,
1614
+ min_out=args.min_out, limit=limit)
1615
+ if args.daily else
1616
+ query_sessions(dest, model=model, since_ms=args.since,
1617
+ until_ms=args.until, min_in=args.min_in,
1618
+ min_out=args.min_out, limit=limit))
1619
+ if not args.daily and args.sessions is not None:
1620
+ # The list view renders newest first; --json serialises the same rows,
1621
+ # so the reversal happens on the row list itself.
1622
+ rows = most_recent(rows, limit)
1623
+ return rows, (DAILY_COLUMNS if args.daily else SESSION_COLUMNS)
1624
+
1625
+
1626
+ def _view_title(args, share_view, limit):
1627
+ """(panel title, hero row-unit) for the view those flags picked.
1628
+
1629
+ A positive --sessions cap on an aggregate says so in the title
1630
+ (` · last N sessions`); the list view names its scope instead
1631
+ (`sessions · N most recent`, `sessions · all`), and a 0 cap leaves every
1632
+ title byte-identical to the uncapped view."""
1633
+ if share_view:
1634
+ # Rows here are per-model totals, or the single grand total.
1635
+ title = ("usage by model · sorted by share"
1636
+ if args.model is not None else "totals")
1637
+ hero_unit = "models" if args.model is not None else "totals"
1638
+ elif args.daily:
1639
+ title, hero_unit = "daily", "days"
1640
+ else:
1641
+ title, hero_unit = "sessions", "sessions"
1642
+ if args.sessions is not None:
1643
+ title = (f"sessions · {limit} most recent" if limit
1644
+ else "sessions · all")
1645
+ # Aggregate views fold sessions up, so a positive cap must say so in the
1646
+ # title: ` · last N sessions` on --daily and the totals/share views
1647
+ # (bare --model counts — it is the --total shortcut). The list view's title
1648
+ # already names its scope, and a limit of 0 (all) leaves every title
1649
+ # byte-identical to the uncapped view.
1650
+ if limit and (share_view or args.daily):
1651
+ title = (f"{title} · last {limit} session"
1652
+ f"{'s' if limit != 1 else ''}")
1653
+ return title, hero_unit
1654
+
1655
+
1656
+ def render_report(title, rows, columns, share_view, color, theme, head=()):
1657
+ """The exact text main() prints for a table view.
1658
+
1659
+ A terminal with rows gets `head` — the hero lines, empty for the views
1660
+ that get no hero — above the framed table, and the frame comes from
1661
+ _table_panel, so one path paints the table, the bars and the header block.
1662
+ Everything else (piped, NO_COLOR, or the empty view) is the bare
1663
+ render_table text: byte-plain, unframed, and printed with no extra newline
1664
+ — the golden piped cases compare these bytes exactly. A share view gets its
1665
+ bars padded there too: paint_bars' one space either side is layout, not
1666
+ color, and the plain table has always had it."""
1667
+ if color and rows:
1668
+ return "\n".join(list(head) + _table_panel(title, rows, columns,
1669
+ share_view, color,
1670
+ theme)) + "\n"
1671
+ if share_view:
1672
+ rows = paint_bars(rows, color=False, theme=theme)
1673
+ return render_table(rows, columns)
1674
+
1675
+
1676
+ def _ensure_utf8_streams(out=None, err=None):
1677
+ """Best-effort UTF-8 so box-drawing/Unicode never crashes a Windows cp1252
1678
+ console. No-op on streams without reconfigure (StringIO in tests, already
1679
+ UTF-8 POSIX consoles)."""
1680
+ for stream in (sys.stdout if out is None else out,
1681
+ sys.stderr if err is None else err):
1682
+ reconfigure = getattr(stream, "reconfigure", None)
1683
+ if reconfigure is not None:
1684
+ try:
1685
+ reconfigure(encoding="utf-8")
1686
+ except (ValueError, OSError):
1687
+ pass
1688
+
1689
+
1690
+ def main(argv):
1691
+ _ensure_utf8_streams()
1692
+ parser = argparse.ArgumentParser(
1693
+ prog="tokenstats",
1694
+ description="Record and report AI token usage from OpenCode into a "
1695
+ "permanent local store.")
1696
+ parser.add_argument("command", nargs="?",
1697
+ choices=["record"],
1698
+ help="record = snapshot OpenCode now"
1699
+ " (default: report)")
1700
+ parser.add_argument("--model", nargs="?", const=MODEL_ANY,
1701
+ help="substring match on provider/model — literal,"
1702
+ " %% and _ are not wildcards (omit the value:"
1703
+ " totals for every model)")
1704
+ parser.add_argument("--since", type=parse_date, metavar="YYYY-MM-DD",
1705
+ help="first day of usage (inclusive)")
1706
+ parser.add_argument("--until", type=parse_date, metavar="YYYY-MM-DD",
1707
+ help="last day of usage (inclusive)")
1708
+ parser.add_argument("--min-in", type=int, dest="min_in",
1709
+ help=argparse.SUPPRESS)
1710
+ parser.add_argument("--min-out", type=int, dest="min_out",
1711
+ help=argparse.SUPPRESS)
1712
+ parser.add_argument("--daily", action="store_true",
1713
+ help="totals per day instead of per session")
1714
+ parser.add_argument("--total", action="store_true",
1715
+ help="grand total (with --model: per-model totals) "
1716
+ "instead of per-session rows")
1717
+ parser.add_argument("--sessions", nargs="?", const=SESSIONS_BARE,
1718
+ type=int, default=None, metavar="N",
1719
+ help="scope to the N most recent sessions "
1720
+ "(default 20 when listing, all when aggregating)")
1721
+ parser.add_argument("--json", action="store_true", dest="as_json",
1722
+ help="emit JSON instead of a table (rows carry"
1723
+ " tok_s; --cost adds cost_est)")
1724
+ # No default to print: the store is created on first run, so --help would
1725
+ # otherwise advertise a path that does not exist yet. default=None means
1726
+ # "ask default_store()", below. The rest of the plumbing below is hidden
1727
+ # for the same reason: fully usable, never advertised.
1728
+ parser.add_argument("--db", default=None, help=argparse.SUPPRESS)
1729
+ parser.add_argument("--src", default=DEFAULT_SRC,
1730
+ help=argparse.SUPPRESS)
1731
+ parser.add_argument("--cost", nargs="?", const="sonnet-5", default=None,
1732
+ metavar="TIER", dest="cost",
1733
+ choices=sorted(PRICES) + sorted(FAMILY_ALIASES),
1734
+ help="add a reference cost estimate column priced at"
1735
+ " TIER (model slug or family name; default:"
1736
+ " sonnet-5); display-only overlay. Prefer"
1737
+ " --cost=TIER: the space form"
1738
+ " can swallow a following command")
1739
+ parser.add_argument("--real-cost", action="store_true", dest="real_cost",
1740
+ help="add a REAL COST column with the stored real USD"
1741
+ " OpenCode reported")
1742
+ # --cost-tier was removed with the --cost rework; kept as a suppressed
1743
+ # shim so stale shell-history invocations get a migration message
1744
+ # instead of argparse blaming the word it swallowed as the command.
1745
+ parser.add_argument("--cost-tier", nargs="?", const="<removed>",
1746
+ default=None, dest="_cost_tier", metavar="TIER",
1747
+ help=argparse.SUPPRESS)
1748
+ parser.add_argument("--cache", action="store_true", dest="cache",
1749
+ help="add a CACHE column (cache read + write) between"
1750
+ " OUT and TOTAL in session views; informational,"
1751
+ " TOTAL unchanged")
1752
+ parser.add_argument("--theme", nargs="?", const=THEME_LIST, default=None,
1753
+ metavar="SLUG",
1754
+ help="bare --theme lists all themes and exits; with"
1755
+ " SLUG, paints this run with that theme"
1756
+ " (display-only overlay like --cost, so the"
1757
+ " dashboard still renders). Prefer --theme=SLUG:"
1758
+ " the space form can swallow a following command")
1759
+ parser.add_argument("--theme-default", nargs="?", const=THEME_SAVE,
1760
+ default=None, dest="theme_default", metavar="SLUG",
1761
+ help="save SLUG as the default theme in"
1762
+ " ~/.tokenstats/themes/config.json (bare"
1763
+ " --theme-default saves this run's theme). Prefer"
1764
+ " --theme-default=SLUG: the space form can"
1765
+ " swallow a following command")
1766
+ args = parser.parse_args(argv)
1767
+ # `--theme=` and `--theme-default=` (an explicit empty value) mean "no
1768
+ # value", not a slug named '': normalize each to what its bare form means,
1769
+ # so an empty --theme leaves the saved default in charge and an empty
1770
+ # --theme-default hits the same "name a --theme=SLUG" error as the bare
1771
+ # flag instead of failing on the empty slug.
1772
+ if args.theme == "":
1773
+ args.theme = None
1774
+ if args.theme_default == "":
1775
+ args.theme_default = THEME_SAVE
1776
+ # `--model=` (an explicit empty pattern, e.g. an expanded empty shell
1777
+ # variable) is indistinguishable from no pattern in the filter layer, so
1778
+ # normalize it to absent here — the panel title then matches the filter.
1779
+ if args.model == "":
1780
+ args.model = None
1781
+ # Windows cmd does not expand `~`; do it for any user-typed path.
1782
+ args.src = os.path.expanduser(args.src)
1783
+ if args.db is not None:
1784
+ args.db = os.path.expanduser(args.db)
1785
+ if args._cost_tier is not None:
1786
+ parser.error("--cost-tier was removed; use --cost=<slug>"
1787
+ " (e.g. --cost=opus-5); see --help")
1788
+ cost_tier = resolve_cost_tier(args.cost) if args.cost else None
1789
+
1790
+ # Theme: resolved here, before the store opens, and passed explicitly to
1791
+ # every paint call below. Both actions short-circuit here too — listing or
1792
+ # saving touches themes/ only, never SQLite. THEMES_DIR and THEME_CONFIG
1793
+ # are read now (not as resolve_theme's def-time default arguments) so a
1794
+ # caller that repoints the module globals steers this run.
1795
+ def theme_warn(msg):
1796
+ print(msg, file=sys.stderr)
1797
+
1798
+ if args.theme_default is not None:
1799
+ # bare --theme-default saves the --theme=SLUG of the same invocation.
1800
+ slug = (args.theme_default if isinstance(args.theme_default, str)
1801
+ else args.theme if isinstance(args.theme, str) else None)
1802
+ if slug is None:
1803
+ parser.error("--theme-default with no value saves the theme given"
1804
+ " by --theme=SLUG in the same invocation; none was"
1805
+ " given — add --theme=SLUG, or save directly as"
1806
+ " --theme-default=SLUG")
1807
+ # write_default_theme does not validate: resolve first, so a typo in
1808
+ # the slug never lands in ~/.tokenstats/themes/config.json.
1809
+ try:
1810
+ resolve_theme(slug, THEMES_DIR)
1811
+ except ThemeError as exc:
1812
+ parser.error(str(exc))
1813
+ name = scan_themes(THEMES_DIR)[slug][0] # safe: it just resolved
1814
+ try:
1815
+ write_default_theme(THEME_CONFIG, slug)
1816
+ except OSError as exc:
1817
+ # a read-only (or otherwise unwritable) themes/ is a CLI failure
1818
+ # like every other one here: tokenstats: error: ..., never a
1819
+ # traceback.
1820
+ parser.error(f"could not write {THEME_CONFIG}: {exc}")
1821
+ print(f"default theme: {slug} ({name})")
1822
+ return 0
1823
+ if args.theme is THEME_LIST:
1824
+ # The list is where a user looks for the theme they just wrote, so a
1825
+ # file that failed validation says why here: scan_themes warns.
1826
+ found = scan_themes(THEMES_DIR, warn=theme_warn)
1827
+ default = read_default_theme(THEME_CONFIG, warn=theme_warn) \
1828
+ or "neon-midnight"
1829
+ for slug in sorted(found):
1830
+ print(f"{slug} \u2014 {found[slug][0]}"
1831
+ + (" (default)" if slug == default else ""))
1832
+ if default not in found:
1833
+ # A saved default that is not in this list marks nothing on stdout,
1834
+ # which reads as a silent bug from the one place the user came to
1835
+ # diagnose it: say where the dead slug came from. stdout stays the
1836
+ # plain list.
1837
+ theme_warn(f"warning: {THEME_CONFIG}: saved default theme"
1838
+ f" '{default}' is not available; runs render in Neon"
1839
+ f" Midnight until --theme-default=SLUG saves another")
1840
+ return 0
1841
+ # Precedence: --theme=SLUG > ~/.tokenstats/themes/config.json > Neon
1842
+ # Midnight. The two sources fail differently on purpose: a slug typed for
1843
+ # this run is the user's own request, so an unknown one is a hard exit 2; a
1844
+ # *saved* default that cannot be resolved is a config that cannot be used —
1845
+ # warn naming the file and render with Neon Midnight, because a cosmetic
1846
+ # default must not cost the user a report whose data is fine. Only this
1847
+ # saved-default path passes warn= down: a file that is present but invalid
1848
+ # then reports its real reason from the scan, above the config line,
1849
+ # instead of reading as a plain "unknown theme" for a file the user can see
1850
+ # on disk.
1851
+ if args.theme:
1852
+ try:
1853
+ theme = resolve_theme(args.theme, THEMES_DIR)
1854
+ except ThemeError as exc:
1855
+ parser.error(str(exc))
1856
+ else:
1857
+ try:
1858
+ theme = resolve_theme(read_default_theme(THEME_CONFIG,
1859
+ warn=theme_warn),
1860
+ THEMES_DIR, warn=theme_warn)
1861
+ except ThemeError as exc:
1862
+ theme_warn(f"warning: {THEME_CONFIG}: {exc}; using Neon Midnight")
1863
+ theme = NEON
1864
+
1865
+ dest = None
1866
+ try:
1867
+ try:
1868
+ # Only a run that was not told where the store lives has a state
1869
+ # dir to create (and possibly a store to migrate): this is the
1870
+ # module's only call to default_store(), so every run that passes
1871
+ # --db — and every test — never touches $HOME.
1872
+ if args.db is None:
1873
+ args.db = default_store()
1874
+ dest = sqlite3.connect(args.db)
1875
+ # WAL + busy_timeout so a scheduled `record` and an interactive
1876
+ # query can overlap without either failing. busy_timeout FIRST:
1877
+ # the rollback-journal -> WAL conversion on a store's first run
1878
+ # needs a brief lock, and this is the one moment a concurrent
1879
+ # writer could otherwise bounce us out with "database is locked".
1880
+ dest.execute("PRAGMA busy_timeout=5000")
1881
+ dest.execute("PRAGMA journal_mode=WAL")
1882
+ ensure_schema(dest)
1883
+ except sqlite3.Error as exc:
1884
+ print(f"warning: could not open our store {args.db}: {exc}",
1885
+ file=sys.stderr)
1886
+ return 1
1887
+ now_ms = int(time.time() * 1000)
1888
+
1889
+ def _ingest(path, fn, verbose):
1890
+ """Open `path` read-only, run one ingestion step on it, and always
1891
+ close the source; warn-and-continue on sqlite errors."""
1892
+ try:
1893
+ src = _connect_src(path)
1894
+ except sqlite3.Error as exc:
1895
+ print(f"warning: could not read {path}: {exc}", file=sys.stderr)
1896
+ return False
1897
+ try:
1898
+ counts = fn(src)
1899
+ if verbose:
1900
+ line = (f"inserted={counts['inserted']}"
1901
+ f" updated={counts['updated']}"
1902
+ f" unchanged={counts['unchanged']}")
1903
+ if counts.get("skipped"):
1904
+ line += f" skipped={counts['skipped']}"
1905
+ print(line)
1906
+ return True
1907
+ except sqlite3.Error as exc:
1908
+ print(f"warning: could not read {path}: {exc}", file=sys.stderr)
1909
+ return False
1910
+ finally:
1911
+ src.close()
1912
+
1913
+ if args.command == "record":
1914
+ ok = _ingest(args.src, lambda src: record(src, dest, now_ms),
1915
+ verbose=True)
1916
+ return 0 if ok else 1
1917
+
1918
+ # Report mode: snapshot OpenCode first, degrade gracefully if the
1919
+ # source is missing or locked.
1920
+ _ingest(args.src, lambda src: record(src, dest, now_ms), verbose=False)
1921
+
1922
+ # Compact default dashboard (design 2026-11-15): a truly bare run —
1923
+ # no command, no view/filter flags (--cost/--cache are overlays, not
1924
+ # views) — renders hero + top-5 models + 5 most recent sessions.
1925
+ # --json keeps the full flat array (display-only limits).
1926
+ compact_dash = (args.command is None and args.model is None
1927
+ and not args.daily and not args.total
1928
+ and args.sessions is None
1929
+ and args.since is None and args.until is None
1930
+ and args.min_in is None and args.min_out is None)
1931
+ if compact_dash and not args.as_json:
1932
+ all_rows = query_sessions(dest)
1933
+ if not all_rows:
1934
+ print("no sessions match")
1935
+ return 0
1936
+ model_rows = add_shares(total_totals(dest, by_model=True))
1937
+ model_rows.sort(key=lambda r: -r["share"]) # stable: ties keep
1938
+ # SQL's alphabetical-by-model order (mirrors the share view).
1939
+ sess_rows = most_recent(all_rows, 5)
1940
+ model_rows = model_rows[:5]
1941
+ color = _color_enabled(sys.stdout, os.environ)
1942
+ m_cols, s_cols = SHARE_COLUMNS, SESSION_COLUMNS
1943
+ hero_cost = None
1944
+ if args.cost:
1945
+ model_rows = annotate_cost(model_rows, cost_tier)
1946
+ sess_rows = annotate_cost(sess_rows, cost_tier)
1947
+ cc = cost_column(cost_tier)
1948
+ m_cols, s_cols = m_cols + [cc], s_cols + [cc]
1949
+ # Hero total spans ALL sessions — the model table truncates
1950
+ # to five rows, so its COST column can't sum to the truth.
1951
+ hero_cost = sum(r["cost_est"]
1952
+ for r in annotate_cost(all_rows, cost_tier))
1953
+ hero_real = None
1954
+ if args.real_cost:
1955
+ hero_real = sum(r["cost"] for r in all_rows)
1956
+ m_cols = m_cols + [REAL_COST_COLUMN]
1957
+ s_cols = s_cols + [REAL_COST_COLUMN]
1958
+ hero_cache = None
1959
+ if args.cache:
1960
+ model_rows = annotate_cache(model_rows)
1961
+ sess_rows = annotate_cache(sess_rows)
1962
+ m_cols, s_cols = with_cache(m_cols), with_cache(s_cols)
1963
+ # Hero cache spans ALL sessions, like the hero cost totals.
1964
+ hero_cache = sum(r["cache"] for r in annotate_cache(all_rows))
1965
+ lines = report_header("", all_rows, theme, cost_est=hero_cost,
1966
+ real_cost=hero_real, unit="sessions",
1967
+ color=color, cache_total=hero_cache)
1968
+ lines += _table_panel("usage by model \u00b7 top 5 by share",
1969
+ model_rows, m_cols, True, color, theme)
1970
+ lines += _table_panel("sessions \u00b7 5 most recent",
1971
+ sess_rows, s_cols, False, color, theme)
1972
+ print("\n".join(lines))
1973
+ return 0
1974
+
1975
+ model_any = args.model is MODEL_ANY
1976
+ # Bare --model is a shortcut for `--total --model`: totals per model.
1977
+ # (With --daily it just means "all models", as before.)
1978
+ want_total = args.total or (model_any and not args.daily)
1979
+ model = None if model_any else args.model
1980
+
1981
+ # The SQL layer can't guard this: a negative LIMIT silently
1982
+ # degenerates to no cap, so the CLI is the only rejection point.
1983
+ limit = _sessions_limit(args.sessions, args.daily, want_total)
1984
+ if limit is not None and limit < 0:
1985
+ parser.error("--sessions must be a non-negative number of"
1986
+ " sessions (0 = all)")
1987
+ if want_total and args.daily:
1988
+ parser.error("--total cannot be combined with --daily")
1989
+ rows, columns = _view_rows(dest, args, model, model_any, want_total,
1990
+ limit)
1991
+ # Opt-in --cost overlay: reference pricing on row copies, never stored
1992
+ # data. The share-view flag is captured BEFORE appending cost_column —
1993
+ # the append creates a new list, and render_report must still recognize
1994
+ # the share view.
1995
+ share_view = columns is SHARE_COLUMNS
1996
+ # Panel title, derived from the same flags that picked `columns`
1997
+ # (a daily share view cannot occur: --total rejects --daily).
1998
+ title, hero_unit = _view_title(args, share_view, limit)
1999
+ # Hero cost tails mirror the dashboard: the estimate tail sums the
2000
+ # reference estimate over the displayed rows, the real tail their
2001
+ # stored cost. A single-row total view renders no hero at all.
2002
+ hero_cost = None
2003
+ if args.cost:
2004
+ rows = annotate_cost(rows, cost_tier)
2005
+ columns = columns + [cost_column(cost_tier)]
2006
+ hero_cost = sum(r["cost_est"] for r in rows)
2007
+ hero_real = None
2008
+ if args.real_cost:
2009
+ columns = columns + [REAL_COST_COLUMN]
2010
+ hero_real = sum(r["cost"] for r in rows)
2011
+ # Opt-in --cache overlay: combined cache classes as one informational
2012
+ # column after OUT; TOTAL stays IN + OUT. The hero gets the same
2013
+ # combined number as its own segment.
2014
+ hero_cache = None
2015
+ if args.cache:
2016
+ rows = annotate_cache(rows)
2017
+ columns = with_cache(columns)
2018
+ hero_cache = sum(r["cache"] for r in rows)
2019
+ if args.as_json:
2020
+ # share travels in JSON; the painted bar is table-only decoration;
2021
+ # `cache` is a render-time join of fields JSON already carries
2022
+ print(json.dumps([{k: v for k, v in r.items()
2023
+ if k not in ("bar", "share_str", "cache")}
2024
+ for r in rows], indent=2))
2025
+ else:
2026
+ color = _color_enabled(sys.stdout, os.environ)
2027
+ # A total view narrowed to a single aggregate row already shows the
2028
+ # grand total in-table — the hero would be a pure echo. Piped
2029
+ # output never renders the hero at all, so do not build it.
2030
+ head = ([] if not color or (want_total and len(rows) == 1)
2031
+ else report_header(title, rows, theme, unit=hero_unit,
2032
+ cache_total=hero_cache,
2033
+ cost_est=hero_cost,
2034
+ real_cost=hero_real))
2035
+ print(render_report(title, rows, columns, share_view, color, theme,
2036
+ head=head), end="")
2037
+ return 0
2038
+ finally:
2039
+ if dest is not None:
2040
+ dest.close()
2041
+
2042
+
2043
+ def cli_main():
2044
+ """Console-script entry point: argv from sys.argv, exit code from main()."""
2045
+ return main(sys.argv[1:])
2046
+
2047
+
2048
+ if __name__ == "__main__":
2049
+ sys.exit(main(sys.argv[1:]))