tokenusage-cli 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (131) hide show
  1. package/CHANGELOG.md +46 -19
  2. package/LICENSE +22 -22
  3. package/README.md +123 -94
  4. package/THIRD_PARTY_NOTICES.md +140 -140
  5. package/bin/tokenusage.js +69 -69
  6. package/package.json +59 -59
  7. package/src/cli.js +146 -134
  8. package/src/commands/device-login.js +205 -205
  9. package/src/commands/diagnostics.js +38 -38
  10. package/src/commands/doctor.js +110 -110
  11. package/src/commands/init.js +2484 -2436
  12. package/src/commands/pause.js +77 -0
  13. package/src/commands/sessions.js +29 -29
  14. package/src/commands/status.js +1758 -1747
  15. package/src/commands/sync.js +8048 -7934
  16. package/src/commands/uninstall.js +322 -312
  17. package/src/lib/account-usage-dedup.js +267 -267
  18. package/src/lib/antigravity-paths.js +48 -48
  19. package/src/lib/ark-agent-plan-limits.js +438 -438
  20. package/src/lib/ark-coding-plan-limits.js +537 -537
  21. package/src/lib/async-queue-reader.js +138 -138
  22. package/src/lib/atomic-json.js +27 -27
  23. package/src/lib/bearer-token.js +11 -11
  24. package/src/lib/categorizer-utils.js +232 -232
  25. package/src/lib/claude-categorizer.js +1343 -1343
  26. package/src/lib/claude-config.js +279 -279
  27. package/src/lib/claude-user-identity.js +56 -56
  28. package/src/lib/cli-ui.js +179 -179
  29. package/src/lib/cloud-account.js +541 -541
  30. package/src/lib/cloud-device-token.js +141 -141
  31. package/src/lib/cloud-sync-prefs.js +14 -14
  32. package/src/lib/cloud-usage-reset.js +115 -115
  33. package/src/lib/codex-config.js +595 -595
  34. package/src/lib/codex-context-breakdown.js +806 -806
  35. package/src/lib/codex-model-attribution.js +128 -128
  36. package/src/lib/codex-rollout-parser.js +1471 -1471
  37. package/src/lib/codex-service-tier.js +49 -49
  38. package/src/lib/codex-token-refresh.js +140 -140
  39. package/src/lib/codex-token-usage.js +195 -195
  40. package/src/lib/codex-usage-record.js +195 -195
  41. package/src/lib/collection-pause.js +77 -0
  42. package/src/lib/command-runner.js +313 -313
  43. package/src/lib/commandcode-limits.js +317 -317
  44. package/src/lib/context-health.js +124 -124
  45. package/src/lib/cursor-config.js +605 -605
  46. package/src/lib/cursor-store.js +1918 -1918
  47. package/src/lib/debug-flags.js +7 -7
  48. package/src/lib/devin-limits.js +249 -249
  49. package/src/lib/devin-usage.js +212 -212
  50. package/src/lib/diagnostics.js +383 -383
  51. package/src/lib/doctor.js +385 -385
  52. package/src/lib/dumate.js +95 -95
  53. package/src/lib/fs.js +455 -455
  54. package/src/lib/function-url.js +14 -14
  55. package/src/lib/gemini-config.js +291 -291
  56. package/src/lib/git-outcomes.js +243 -243
  57. package/src/lib/grok-context-breakdown.js +890 -890
  58. package/src/lib/grok-hook.js +360 -360
  59. package/src/lib/grok-limits.js +865 -865
  60. package/src/lib/grok-usage.js +98 -98
  61. package/src/lib/heatmap-compact.js +114 -114
  62. package/src/lib/ingest-sanitize.js +41 -41
  63. package/src/lib/init-flow.js +42 -42
  64. package/src/lib/install-resolver.js +170 -170
  65. package/src/lib/jsonl-lines.js +134 -134
  66. package/src/lib/kimi-model-repair.js +173 -173
  67. package/src/lib/kimi-profile.js +61 -61
  68. package/src/lib/kimi-session.js +216 -216
  69. package/src/lib/local-api.js +3588 -3588
  70. package/src/lib/machine-id.js +238 -238
  71. package/src/lib/multi-install-parser.js +113 -113
  72. package/src/lib/notify-command.js +38 -38
  73. package/src/lib/omp-hook.js +589 -589
  74. package/src/lib/openclaw-cli.js +104 -104
  75. package/src/lib/openclaw-hook.js +375 -375
  76. package/src/lib/openclaw-session-plugin.js +560 -560
  77. package/src/lib/opencode-config.js +121 -121
  78. package/src/lib/opencode-go-limits.js +807 -807
  79. package/src/lib/outcomes-engine.js +253 -253
  80. package/src/lib/passive-mode.js +219 -219
  81. package/src/lib/pet-packages.js +722 -722
  82. package/src/lib/pricing/curated-overrides.json +822 -822
  83. package/src/lib/pricing/index.js +379 -379
  84. package/src/lib/pricing/litellm-fetcher.js +172 -172
  85. package/src/lib/pricing/matcher.js +456 -456
  86. package/src/lib/pricing/seed-snapshot.json +1 -1
  87. package/src/lib/progress.js +76 -76
  88. package/src/lib/project-usage-purge.js +117 -117
  89. package/src/lib/prompt.js +24 -24
  90. package/src/lib/provider-status.js +104 -104
  91. package/src/lib/proxy-env.js +489 -489
  92. package/src/lib/proxy-settings.js +163 -163
  93. package/src/lib/qoder-cn-cli-limits.js +119 -119
  94. package/src/lib/qoder-limits.js +880 -880
  95. package/src/lib/quiet-warnings.js +26 -26
  96. package/src/lib/rollout.js +26005 -25966
  97. package/src/lib/runtime-config.js +9 -4
  98. package/src/lib/scan-roots.js +277 -277
  99. package/src/lib/scheduled-task.js +145 -0
  100. package/src/lib/sentry.js +231 -231
  101. package/src/lib/session-analytics.js +2972 -2972
  102. package/src/lib/session-performance.js +237 -237
  103. package/src/lib/session-upload.js +379 -379
  104. package/src/lib/skill-usage.js +267 -267
  105. package/src/lib/skills-manager.js +1591 -1591
  106. package/src/lib/source-metadata.js +48 -48
  107. package/src/lib/sqlite-reader.js +215 -215
  108. package/src/lib/star-cta.js +73 -73
  109. package/src/lib/subscription-manager.js +293 -293
  110. package/src/lib/subscriptions.js +508 -508
  111. package/src/lib/sync-report.js +138 -0
  112. package/src/lib/telemetry.js +193 -193
  113. package/src/lib/tracker-paths.js +16 -16
  114. package/src/lib/trae-cn-config.js +548 -548
  115. package/src/lib/trae-db.js +127 -127
  116. package/src/lib/trae-snapshot.js +230 -230
  117. package/src/lib/trae-sqlite.js +143 -143
  118. package/src/lib/trae-usage.js +121 -121
  119. package/src/lib/upload-queue.js +134 -134
  120. package/src/lib/upload-throttle.js +171 -171
  121. package/src/lib/usage-limits.js +4552 -4552
  122. package/src/lib/wrapped-aggregator.js +236 -236
  123. package/src/lib/wsl-probe.js +281 -281
  124. package/src/lib/zcode-limits.js +1172 -1172
  125. package/src/lib/zcode-reset-credits.js +66 -66
  126. package/test/audit-fixes.test.js +200 -0
  127. package/test/cli-smoke.test.js +53 -53
  128. package/test/collection-controls.test.js +210 -0
  129. package/test/ingest-sanitize.test.js +162 -162
  130. package/test/quiet-warnings.test.js +53 -53
  131. package/test/session-upload.test.js +427 -427
@@ -1,267 +1,267 @@
1
- "use strict";
2
-
3
- /**
4
- * Account-level cross-device truth - JS reference implementation.
5
- *
6
- * Account-level sources (ACCOUNT_LEVEL_SOURCES in src/lib/source-metadata.js)
7
- * come from a per-ACCOUNT cloud API, so every device that syncs them stores
8
- * its own copy of the SAME account data. How to dedup depends on the source:
9
- *
10
- * - 'cursor' has NO stable session identity: its rows are identical across
11
- * devices, so the legacy whole-row MAX pick per (hour, source, model)
12
- * dedups them (dedupeAccountLevelRows below).
13
- * - 'trae-cn' is a CORRECTABLE snapshot: totals can be revised down, a
14
- * session can move to another model or another half-hour. Hour-level
15
- * dedup CANNOT express that (a fresh device's first data bucket cannot
16
- * safely displace earlier hours - that would need an unproven "absent =
17
- * deleted" contract - and a 10:00 -> 10:30 bucket migration strands the
18
- * old hour). Canonical truth for trae-cn therefore lives at the SESSION
19
- * level (token_account_session_states; migrations/
20
- * 20260817120000_account-session-states.sql): identity is
21
- * (user_id, source, session_id) - device_id is NOT identity (the usage
22
- * API request carries no device discriminator). Session-id evidence
23
- * (2026-08-17): repeated-fetch stability VERIFIED, cross-window
24
- * stability VERIFIED; cross-device same-account stability NOT DIRECTLY
25
- * VERIFIED (no second independent device/auth experiment). Every
26
- * observation of one
27
- * session whole-row-replaces the previous state under a strict LWW
28
- * guard, so the three correction classes collapse into ONE operation:
29
- *
30
- * downward S tokens 100 -> 60 replaced, total 60
31
- * model S model A -> B replaced, only B remains
32
- * bucket S bucket 10:00 -> 10:30 replaced, only 10:30 remains
33
- *
34
- * ABSENCE is NOT PROVEN to mean deletion, so nothing ever deletes a session
35
- * row: a session missing from a non-empty snapshot asserts nothing, and an
36
- * empty snapshot asserts nothing at all.
37
- *
38
- * Freshness: the TRAE API exposes no provider-side ordering signal (probed
39
- * 2026-08-17: headers carry only CDN trace ids, rows carry no revision), so
40
- * snapshot_verified_at is the CLIENT logical fetch stamp (best-effort
41
- * cross-device ordering under clock skew - documented residual risk, NOT
42
- * strict correctness). It is stamped once per real fetch and replayed
43
- * verbatim by the append-only queue; the LWW guard applies strictly newer
44
- * (>) stamps only, so retries are idempotent and a re-delivered older
45
- * observation cannot displace a newer one. Equal stamps keep the
46
- * first-applied row (stable under retries).
47
- *
48
- * This module is the executable specification of that semantics; the
49
- * deployed SQL (migrations/20260817120000_account-session-states.sql upsert,
50
- * scripts/ops/account-usage-grouped-rpc.sql + leaderboard_hourly_dedup_v2
51
- * aggregation branches) implements the same algorithm and MUST stay in sync
52
- * - test/account-usage-dedup.test.js pins both.
53
- */
54
-
55
- // Queue record kind the TRAE CN parser emits for one changed session's
56
- // canonical observation (src/lib/rollout.js appendTraeCnSessionStates).
57
- const SESSION_STATE_KIND = "account_session_state";
58
-
59
- function parseMs(value) {
60
- const ms = Date.parse(value);
61
- return Number.isFinite(ms) ? ms : null;
62
- }
63
-
64
- // Token columns that make up a canonical session state row (the SQL table's
65
- // non-key, non-metadata columns).
66
- const TOKEN_COLUMNS = [
67
- "input_tokens",
68
- "output_tokens",
69
- "cached_input_tokens",
70
- "cache_creation_input_tokens",
71
- "reasoning_output_tokens",
72
- "total_tokens",
73
- ];
74
-
75
- function normalizeStateRow(observation) {
76
- const source = String(observation?.source ?? "").trim().toLowerCase();
77
- const sessionId = String(observation?.session_id ?? "").trim();
78
- if (!source || !sessionId) return null;
79
- const verifiedMs = parseMs(observation?.snapshot_verified_at);
80
- if (verifiedMs === null) return null;
81
- const bucketStart = String(observation?.bucket_start ?? "");
82
- if (parseMs(bucketStart) === null) return null;
83
- const model = String(observation?.model ?? "");
84
- if (!model) return null;
85
- const row = {
86
- source,
87
- session_id: sessionId,
88
- model,
89
- bucket_start: bucketStart,
90
- snapshot_verified_at: observation.snapshot_verified_at,
91
- };
92
- for (const column of TOKEN_COLUMNS) {
93
- const value = Number(observation?.[column]);
94
- row[column] = Number.isFinite(value) ? value : 0;
95
- }
96
- return row;
97
- }
98
-
99
- /**
100
- * Whole-row LWW replace of canonical session states - mirrors
101
- * token_upsert_account_session_states() (migrations/
102
- * 20260817120000_account-session-states.sql): a row applies only when its
103
- * snapshot_verified_at is STRICTLY newer (>) than the stored one. Replays of
104
- * the same observation are no-ops; equal stamps keep the first-applied row.
105
- *
106
- * @param {Map<string, object>} states - canonical table keyed by
107
- * `${source}|${session_id}` (mirrors the (user_id, source, session_id) PK
108
- * for one account; mutated in place).
109
- * @param {Array<object>} observations - ingest batch (already deduped to one
110
- * row per session by the edge, like the SQL batch upsert requires).
111
- * @returns {number} applied row count (mirrors the SQL ROW_COUNT return).
112
- */
113
- function upsertAccountSessionStates(states, observations) {
114
- const table = states instanceof Map ? states : new Map();
115
- const batch = Array.isArray(observations) ? observations : [];
116
- let applied = 0;
117
- for (const observation of batch) {
118
- const row = normalizeStateRow(observation);
119
- if (!row) continue;
120
- const key = `${row.source}|${row.session_id}`;
121
- const stored = table.get(key);
122
- if (!stored) {
123
- table.set(key, row);
124
- applied += 1;
125
- continue;
126
- }
127
- const storedMs = parseMs(stored.snapshot_verified_at) ?? -Infinity;
128
- const rowMs = parseMs(row.snapshot_verified_at) ?? -Infinity;
129
- if (rowMs > storedMs) {
130
- table.set(key, row);
131
- applied += 1;
132
- }
133
- }
134
- return applied;
135
- }
136
-
137
- /**
138
- * Aggregate canonical session states into hourly rows - mirrors the trae-cn
139
- * branch of account_usage_grouped (scripts/ops/account-usage-grouped-rpc.sql)
140
- * and leaderboard_hourly_dedup_v2: SUM per (bucket_start, source, model),
141
- * conversations = session count.
142
- *
143
- * @param {Map<string, object>|Array<object>} states
144
- * @param {{from?: string, to?: string}} [opts] - optional [from, to) window.
145
- * @returns {Array<object>} rows shaped like token_usage_hourly aggregates.
146
- */
147
- function aggregateSessionStates(states, opts = {}) {
148
- const values = states instanceof Map ? [...states.values()] : Array.isArray(states) ? states : [];
149
- const fromMs = parseMs(opts.from ?? "");
150
- const toMs = parseMs(opts.to ?? "");
151
- const grouped = new Map();
152
- for (const state of values) {
153
- const row = normalizeStateRow(state);
154
- if (!row) continue;
155
- const bucketMs = parseMs(row.bucket_start);
156
- if (bucketMs === null) continue;
157
- if (fromMs !== null && bucketMs < fromMs) continue;
158
- if (toMs !== null && bucketMs >= toMs) continue;
159
- const key = `${row.bucket_start}||${row.source}||${row.model}`;
160
- const acc = grouped.get(key) || {
161
- hour_start: row.bucket_start,
162
- source: row.source,
163
- model: row.model,
164
- input_tokens: 0,
165
- output_tokens: 0,
166
- cached_input_tokens: 0,
167
- cache_creation_input_tokens: 0,
168
- reasoning_output_tokens: 0,
169
- total_tokens: 0,
170
- conversations: 0,
171
- };
172
- for (const column of TOKEN_COLUMNS) acc[column] += row[column];
173
- acc.conversations += 1;
174
- grouped.set(key, acc);
175
- }
176
- return [...grouped.values()].sort(
177
- (a, b) =>
178
- String(a.hour_start).localeCompare(String(b.hour_start)) ||
179
- String(a.source).localeCompare(String(b.source)) ||
180
- String(a.model).localeCompare(String(b.model)),
181
- );
182
- }
183
-
184
- // Mirrors the legacy SQL DISTINCT ON (hour, source, model)
185
- // ORDER BY total_tokens DESC, updated_at DESC (device_id asc as the final
186
- // deterministic tiebreak). Used ONLY for account-level sources without a
187
- // stable session identity ('cursor') and watermark-less history.
188
- function pickLegacyRow(rows) {
189
- let best = null;
190
- for (const row of rows) {
191
- if (!best) {
192
- best = row;
193
- continue;
194
- }
195
- const rowTotal = Number(row.total_tokens) || 0;
196
- const bestTotal = Number(best.total_tokens) || 0;
197
- if (rowTotal !== bestTotal) {
198
- if (rowTotal > bestTotal) best = row;
199
- continue;
200
- }
201
- const rowUpdated = parseMs(row.updated_at ?? "") ?? -Infinity;
202
- const bestUpdated = parseMs(best.updated_at ?? "") ?? -Infinity;
203
- if (rowUpdated !== bestUpdated) {
204
- if (rowUpdated > bestUpdated) best = row;
205
- continue;
206
- }
207
- if (String(row.device_id) < String(best.device_id)) best = row;
208
- }
209
- return best;
210
- }
211
-
212
- /**
213
- * Legacy whole-row MAX dedup for account-level hourly rows WITHOUT a stable
214
- * session identity ('cursor'): rows are identical across devices, so one
215
- * canonical row per (hour, source, model) suffices. Sources with a session
216
- * identity ('trae-cn') must instead aggregate from canonical session states
217
- * (aggregateSessionStates) - never from per-device hourly rows.
218
- *
219
- * @param {Array<{device_id: string, hour_start: string, source: string,
220
- * model: string, updated_at?: string, total_tokens: number}>} rows -
221
- * every device's token_usage_hourly-shaped rows.
222
- * @returns {Array} canonical rows - one consistent row per (hour, model).
223
- */
224
- function dedupeAccountLevelRows(rows) {
225
- if (!Array.isArray(rows)) return [];
226
- // Group rows by (source, hour_start); keep original row objects untouched.
227
- const byHour = new Map();
228
- for (const row of rows) {
229
- if (!row || typeof row.hour_start !== "string" || !row.hour_start) continue;
230
- const key = `${row.source}||${row.hour_start}`;
231
- const list = byHour.get(key) || [];
232
- list.push(row);
233
- byHour.set(key, list);
234
- }
235
-
236
- const out = [];
237
- for (const [, hourRows] of byHour) {
238
- const byModel = new Map();
239
- for (const row of hourRows) {
240
- const modelKey = row.model || "unknown";
241
- const list = byModel.get(modelKey) || [];
242
- list.push(row);
243
- byModel.set(modelKey, list);
244
- }
245
- for (const list of byModel.values()) {
246
- out.push(pickLegacyRow(list));
247
- }
248
- }
249
- return out;
250
- }
251
-
252
- /** Total tokens of a deduped row set - convenience for tests/diagnostics. */
253
- function sumTotalTokens(rows) {
254
- return (Array.isArray(rows) ? rows : []).reduce(
255
- (acc, row) => acc + (Number(row?.total_tokens) || 0),
256
- 0,
257
- );
258
- }
259
-
260
- module.exports = {
261
- SESSION_STATE_KIND,
262
- TOKEN_COLUMNS,
263
- upsertAccountSessionStates,
264
- aggregateSessionStates,
265
- dedupeAccountLevelRows,
266
- sumTotalTokens,
267
- };
1
+ "use strict";
2
+
3
+ /**
4
+ * Account-level cross-device truth - JS reference implementation.
5
+ *
6
+ * Account-level sources (ACCOUNT_LEVEL_SOURCES in src/lib/source-metadata.js)
7
+ * come from a per-ACCOUNT cloud API, so every device that syncs them stores
8
+ * its own copy of the SAME account data. How to dedup depends on the source:
9
+ *
10
+ * - 'cursor' has NO stable session identity: its rows are identical across
11
+ * devices, so the legacy whole-row MAX pick per (hour, source, model)
12
+ * dedups them (dedupeAccountLevelRows below).
13
+ * - 'trae-cn' is a CORRECTABLE snapshot: totals can be revised down, a
14
+ * session can move to another model or another half-hour. Hour-level
15
+ * dedup CANNOT express that (a fresh device's first data bucket cannot
16
+ * safely displace earlier hours - that would need an unproven "absent =
17
+ * deleted" contract - and a 10:00 -> 10:30 bucket migration strands the
18
+ * old hour). Canonical truth for trae-cn therefore lives at the SESSION
19
+ * level (token_account_session_states; migrations/
20
+ * 20260817120000_account-session-states.sql): identity is
21
+ * (user_id, source, session_id) - device_id is NOT identity (the usage
22
+ * API request carries no device discriminator). Session-id evidence
23
+ * (2026-08-17): repeated-fetch stability VERIFIED, cross-window
24
+ * stability VERIFIED; cross-device same-account stability NOT DIRECTLY
25
+ * VERIFIED (no second independent device/auth experiment). Every
26
+ * observation of one
27
+ * session whole-row-replaces the previous state under a strict LWW
28
+ * guard, so the three correction classes collapse into ONE operation:
29
+ *
30
+ * downward S tokens 100 -> 60 replaced, total 60
31
+ * model S model A -> B replaced, only B remains
32
+ * bucket S bucket 10:00 -> 10:30 replaced, only 10:30 remains
33
+ *
34
+ * ABSENCE is NOT PROVEN to mean deletion, so nothing ever deletes a session
35
+ * row: a session missing from a non-empty snapshot asserts nothing, and an
36
+ * empty snapshot asserts nothing at all.
37
+ *
38
+ * Freshness: the TRAE API exposes no provider-side ordering signal (probed
39
+ * 2026-08-17: headers carry only CDN trace ids, rows carry no revision), so
40
+ * snapshot_verified_at is the CLIENT logical fetch stamp (best-effort
41
+ * cross-device ordering under clock skew - documented residual risk, NOT
42
+ * strict correctness). It is stamped once per real fetch and replayed
43
+ * verbatim by the append-only queue; the LWW guard applies strictly newer
44
+ * (>) stamps only, so retries are idempotent and a re-delivered older
45
+ * observation cannot displace a newer one. Equal stamps keep the
46
+ * first-applied row (stable under retries).
47
+ *
48
+ * This module is the executable specification of that semantics; the
49
+ * deployed SQL (migrations/20260817120000_account-session-states.sql upsert,
50
+ * scripts/ops/account-usage-grouped-rpc.sql + leaderboard_hourly_dedup_v2
51
+ * aggregation branches) implements the same algorithm and MUST stay in sync
52
+ * - test/account-usage-dedup.test.js pins both.
53
+ */
54
+
55
+ // Queue record kind the TRAE CN parser emits for one changed session's
56
+ // canonical observation (src/lib/rollout.js appendTraeCnSessionStates).
57
+ const SESSION_STATE_KIND = "account_session_state";
58
+
59
+ function parseMs(value) {
60
+ const ms = Date.parse(value);
61
+ return Number.isFinite(ms) ? ms : null;
62
+ }
63
+
64
+ // Token columns that make up a canonical session state row (the SQL table's
65
+ // non-key, non-metadata columns).
66
+ const TOKEN_COLUMNS = [
67
+ "input_tokens",
68
+ "output_tokens",
69
+ "cached_input_tokens",
70
+ "cache_creation_input_tokens",
71
+ "reasoning_output_tokens",
72
+ "total_tokens",
73
+ ];
74
+
75
+ function normalizeStateRow(observation) {
76
+ const source = String(observation?.source ?? "").trim().toLowerCase();
77
+ const sessionId = String(observation?.session_id ?? "").trim();
78
+ if (!source || !sessionId) return null;
79
+ const verifiedMs = parseMs(observation?.snapshot_verified_at);
80
+ if (verifiedMs === null) return null;
81
+ const bucketStart = String(observation?.bucket_start ?? "");
82
+ if (parseMs(bucketStart) === null) return null;
83
+ const model = String(observation?.model ?? "");
84
+ if (!model) return null;
85
+ const row = {
86
+ source,
87
+ session_id: sessionId,
88
+ model,
89
+ bucket_start: bucketStart,
90
+ snapshot_verified_at: observation.snapshot_verified_at,
91
+ };
92
+ for (const column of TOKEN_COLUMNS) {
93
+ const value = Number(observation?.[column]);
94
+ row[column] = Number.isFinite(value) ? value : 0;
95
+ }
96
+ return row;
97
+ }
98
+
99
+ /**
100
+ * Whole-row LWW replace of canonical session states - mirrors
101
+ * token_upsert_account_session_states() (migrations/
102
+ * 20260817120000_account-session-states.sql): a row applies only when its
103
+ * snapshot_verified_at is STRICTLY newer (>) than the stored one. Replays of
104
+ * the same observation are no-ops; equal stamps keep the first-applied row.
105
+ *
106
+ * @param {Map<string, object>} states - canonical table keyed by
107
+ * `${source}|${session_id}` (mirrors the (user_id, source, session_id) PK
108
+ * for one account; mutated in place).
109
+ * @param {Array<object>} observations - ingest batch (already deduped to one
110
+ * row per session by the edge, like the SQL batch upsert requires).
111
+ * @returns {number} applied row count (mirrors the SQL ROW_COUNT return).
112
+ */
113
+ function upsertAccountSessionStates(states, observations) {
114
+ const table = states instanceof Map ? states : new Map();
115
+ const batch = Array.isArray(observations) ? observations : [];
116
+ let applied = 0;
117
+ for (const observation of batch) {
118
+ const row = normalizeStateRow(observation);
119
+ if (!row) continue;
120
+ const key = `${row.source}|${row.session_id}`;
121
+ const stored = table.get(key);
122
+ if (!stored) {
123
+ table.set(key, row);
124
+ applied += 1;
125
+ continue;
126
+ }
127
+ const storedMs = parseMs(stored.snapshot_verified_at) ?? -Infinity;
128
+ const rowMs = parseMs(row.snapshot_verified_at) ?? -Infinity;
129
+ if (rowMs > storedMs) {
130
+ table.set(key, row);
131
+ applied += 1;
132
+ }
133
+ }
134
+ return applied;
135
+ }
136
+
137
+ /**
138
+ * Aggregate canonical session states into hourly rows - mirrors the trae-cn
139
+ * branch of account_usage_grouped (scripts/ops/account-usage-grouped-rpc.sql)
140
+ * and leaderboard_hourly_dedup_v2: SUM per (bucket_start, source, model),
141
+ * conversations = session count.
142
+ *
143
+ * @param {Map<string, object>|Array<object>} states
144
+ * @param {{from?: string, to?: string}} [opts] - optional [from, to) window.
145
+ * @returns {Array<object>} rows shaped like token_usage_hourly aggregates.
146
+ */
147
+ function aggregateSessionStates(states, opts = {}) {
148
+ const values = states instanceof Map ? [...states.values()] : Array.isArray(states) ? states : [];
149
+ const fromMs = parseMs(opts.from ?? "");
150
+ const toMs = parseMs(opts.to ?? "");
151
+ const grouped = new Map();
152
+ for (const state of values) {
153
+ const row = normalizeStateRow(state);
154
+ if (!row) continue;
155
+ const bucketMs = parseMs(row.bucket_start);
156
+ if (bucketMs === null) continue;
157
+ if (fromMs !== null && bucketMs < fromMs) continue;
158
+ if (toMs !== null && bucketMs >= toMs) continue;
159
+ const key = `${row.bucket_start}||${row.source}||${row.model}`;
160
+ const acc = grouped.get(key) || {
161
+ hour_start: row.bucket_start,
162
+ source: row.source,
163
+ model: row.model,
164
+ input_tokens: 0,
165
+ output_tokens: 0,
166
+ cached_input_tokens: 0,
167
+ cache_creation_input_tokens: 0,
168
+ reasoning_output_tokens: 0,
169
+ total_tokens: 0,
170
+ conversations: 0,
171
+ };
172
+ for (const column of TOKEN_COLUMNS) acc[column] += row[column];
173
+ acc.conversations += 1;
174
+ grouped.set(key, acc);
175
+ }
176
+ return [...grouped.values()].sort(
177
+ (a, b) =>
178
+ String(a.hour_start).localeCompare(String(b.hour_start)) ||
179
+ String(a.source).localeCompare(String(b.source)) ||
180
+ String(a.model).localeCompare(String(b.model)),
181
+ );
182
+ }
183
+
184
+ // Mirrors the legacy SQL DISTINCT ON (hour, source, model)
185
+ // ORDER BY total_tokens DESC, updated_at DESC (device_id asc as the final
186
+ // deterministic tiebreak). Used ONLY for account-level sources without a
187
+ // stable session identity ('cursor') and watermark-less history.
188
+ function pickLegacyRow(rows) {
189
+ let best = null;
190
+ for (const row of rows) {
191
+ if (!best) {
192
+ best = row;
193
+ continue;
194
+ }
195
+ const rowTotal = Number(row.total_tokens) || 0;
196
+ const bestTotal = Number(best.total_tokens) || 0;
197
+ if (rowTotal !== bestTotal) {
198
+ if (rowTotal > bestTotal) best = row;
199
+ continue;
200
+ }
201
+ const rowUpdated = parseMs(row.updated_at ?? "") ?? -Infinity;
202
+ const bestUpdated = parseMs(best.updated_at ?? "") ?? -Infinity;
203
+ if (rowUpdated !== bestUpdated) {
204
+ if (rowUpdated > bestUpdated) best = row;
205
+ continue;
206
+ }
207
+ if (String(row.device_id) < String(best.device_id)) best = row;
208
+ }
209
+ return best;
210
+ }
211
+
212
+ /**
213
+ * Legacy whole-row MAX dedup for account-level hourly rows WITHOUT a stable
214
+ * session identity ('cursor'): rows are identical across devices, so one
215
+ * canonical row per (hour, source, model) suffices. Sources with a session
216
+ * identity ('trae-cn') must instead aggregate from canonical session states
217
+ * (aggregateSessionStates) - never from per-device hourly rows.
218
+ *
219
+ * @param {Array<{device_id: string, hour_start: string, source: string,
220
+ * model: string, updated_at?: string, total_tokens: number}>} rows -
221
+ * every device's token_usage_hourly-shaped rows.
222
+ * @returns {Array} canonical rows - one consistent row per (hour, model).
223
+ */
224
+ function dedupeAccountLevelRows(rows) {
225
+ if (!Array.isArray(rows)) return [];
226
+ // Group rows by (source, hour_start); keep original row objects untouched.
227
+ const byHour = new Map();
228
+ for (const row of rows) {
229
+ if (!row || typeof row.hour_start !== "string" || !row.hour_start) continue;
230
+ const key = `${row.source}||${row.hour_start}`;
231
+ const list = byHour.get(key) || [];
232
+ list.push(row);
233
+ byHour.set(key, list);
234
+ }
235
+
236
+ const out = [];
237
+ for (const [, hourRows] of byHour) {
238
+ const byModel = new Map();
239
+ for (const row of hourRows) {
240
+ const modelKey = row.model || "unknown";
241
+ const list = byModel.get(modelKey) || [];
242
+ list.push(row);
243
+ byModel.set(modelKey, list);
244
+ }
245
+ for (const list of byModel.values()) {
246
+ out.push(pickLegacyRow(list));
247
+ }
248
+ }
249
+ return out;
250
+ }
251
+
252
+ /** Total tokens of a deduped row set - convenience for tests/diagnostics. */
253
+ function sumTotalTokens(rows) {
254
+ return (Array.isArray(rows) ? rows : []).reduce(
255
+ (acc, row) => acc + (Number(row?.total_tokens) || 0),
256
+ 0,
257
+ );
258
+ }
259
+
260
+ module.exports = {
261
+ SESSION_STATE_KIND,
262
+ TOKEN_COLUMNS,
263
+ upsertAccountSessionStates,
264
+ aggregateSessionStates,
265
+ dedupeAccountLevelRows,
266
+ sumTotalTokens,
267
+ };
@@ -1,48 +1,48 @@
1
- const fs = require("node:fs");
2
- const os = require("node:os");
3
- const path = require("node:path");
4
-
5
- const MAIN_APP_SUBDIR = "antigravity";
6
- const IDE_SUBDIR = "antigravity-ide";
7
-
8
- function geminiHome(env) {
9
- return path.join(env.HOME || env.USERPROFILE || os.homedir(), ".gemini");
10
- }
11
-
12
- function trimmed(value) {
13
- return typeof value === "string" ? value.trim() : "";
14
- }
15
-
16
- function existsDir(dirPath) {
17
- try {
18
- return fs.statSync(dirPath).isDirectory();
19
- } catch (_e) {
20
- return false;
21
- }
22
- }
23
-
24
- function resolveAntigravitySkillDirs(env = process.env) {
25
- const override = trimmed(env.TOKENUSAGE_ANTIGRAVITY_HOME);
26
- if (override) return [path.join(override, "skills")];
27
-
28
- const home = geminiHome(env);
29
- const mainSkills = path.join(home, MAIN_APP_SUBDIR, "skills");
30
- const ideSkills = path.join(home, IDE_SUBDIR, "skills");
31
- const mainParent = path.join(home, MAIN_APP_SUBDIR);
32
- const ideParent = path.join(home, IDE_SUBDIR);
33
-
34
- const dirs = [];
35
- if (existsDir(mainParent)) dirs.push(mainSkills);
36
- if (existsDir(ideParent)) dirs.push(ideSkills);
37
-
38
- // Neither Antigravity install present: fall back to the main-app path so
39
- // targetList still surfaces a stable path string and the user can install
40
- // skills now and run Antigravity later. The empty parent will be created on
41
- // demand by ensureDir; cleanup happens naturally via uninstallSkill.
42
- if (dirs.length > 0) return dirs;
43
- return [mainSkills];
44
- }
45
-
46
- module.exports = {
47
- resolveAntigravitySkillDirs,
48
- };
1
+ const fs = require("node:fs");
2
+ const os = require("node:os");
3
+ const path = require("node:path");
4
+
5
+ const MAIN_APP_SUBDIR = "antigravity";
6
+ const IDE_SUBDIR = "antigravity-ide";
7
+
8
+ function geminiHome(env) {
9
+ return path.join(env.HOME || env.USERPROFILE || os.homedir(), ".gemini");
10
+ }
11
+
12
+ function trimmed(value) {
13
+ return typeof value === "string" ? value.trim() : "";
14
+ }
15
+
16
+ function existsDir(dirPath) {
17
+ try {
18
+ return fs.statSync(dirPath).isDirectory();
19
+ } catch (_e) {
20
+ return false;
21
+ }
22
+ }
23
+
24
+ function resolveAntigravitySkillDirs(env = process.env) {
25
+ const override = trimmed(env.TOKENUSAGE_ANTIGRAVITY_HOME);
26
+ if (override) return [path.join(override, "skills")];
27
+
28
+ const home = geminiHome(env);
29
+ const mainSkills = path.join(home, MAIN_APP_SUBDIR, "skills");
30
+ const ideSkills = path.join(home, IDE_SUBDIR, "skills");
31
+ const mainParent = path.join(home, MAIN_APP_SUBDIR);
32
+ const ideParent = path.join(home, IDE_SUBDIR);
33
+
34
+ const dirs = [];
35
+ if (existsDir(mainParent)) dirs.push(mainSkills);
36
+ if (existsDir(ideParent)) dirs.push(ideSkills);
37
+
38
+ // Neither Antigravity install present: fall back to the main-app path so
39
+ // targetList still surfaces a stable path string and the user can install
40
+ // skills now and run Antigravity later. The empty parent will be created on
41
+ // demand by ensureDir; cleanup happens naturally via uninstallSkill.
42
+ if (dirs.length > 0) return dirs;
43
+ return [mainSkills];
44
+ }
45
+
46
+ module.exports = {
47
+ resolveAntigravitySkillDirs,
48
+ };