tokenusage-cli 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (125) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/LICENSE +22 -0
  3. package/README.md +94 -0
  4. package/THIRD_PARTY_NOTICES.md +140 -0
  5. package/bin/tokenusage.js +69 -0
  6. package/package.json +59 -0
  7. package/src/cli.js +134 -0
  8. package/src/commands/device-login.js +205 -0
  9. package/src/commands/diagnostics.js +38 -0
  10. package/src/commands/doctor.js +110 -0
  11. package/src/commands/init.js +2436 -0
  12. package/src/commands/sessions.js +29 -0
  13. package/src/commands/status.js +1747 -0
  14. package/src/commands/sync.js +7934 -0
  15. package/src/commands/uninstall.js +312 -0
  16. package/src/lib/account-usage-dedup.js +267 -0
  17. package/src/lib/antigravity-paths.js +48 -0
  18. package/src/lib/ark-agent-plan-limits.js +438 -0
  19. package/src/lib/ark-coding-plan-limits.js +537 -0
  20. package/src/lib/async-queue-reader.js +138 -0
  21. package/src/lib/atomic-json.js +27 -0
  22. package/src/lib/bearer-token.js +11 -0
  23. package/src/lib/categorizer-utils.js +232 -0
  24. package/src/lib/claude-categorizer.js +1343 -0
  25. package/src/lib/claude-config.js +279 -0
  26. package/src/lib/claude-user-identity.js +56 -0
  27. package/src/lib/cli-ui.js +179 -0
  28. package/src/lib/cloud-account.js +541 -0
  29. package/src/lib/cloud-device-token.js +141 -0
  30. package/src/lib/cloud-sync-prefs.js +14 -0
  31. package/src/lib/cloud-usage-reset.js +115 -0
  32. package/src/lib/codex-config.js +595 -0
  33. package/src/lib/codex-context-breakdown.js +806 -0
  34. package/src/lib/codex-model-attribution.js +128 -0
  35. package/src/lib/codex-rollout-parser.js +1471 -0
  36. package/src/lib/codex-service-tier.js +49 -0
  37. package/src/lib/codex-token-refresh.js +140 -0
  38. package/src/lib/codex-token-usage.js +195 -0
  39. package/src/lib/codex-usage-record.js +195 -0
  40. package/src/lib/command-runner.js +313 -0
  41. package/src/lib/commandcode-limits.js +317 -0
  42. package/src/lib/context-health.js +124 -0
  43. package/src/lib/cursor-config.js +605 -0
  44. package/src/lib/cursor-store.js +1918 -0
  45. package/src/lib/debug-flags.js +7 -0
  46. package/src/lib/devin-limits.js +249 -0
  47. package/src/lib/devin-usage.js +212 -0
  48. package/src/lib/diagnostics.js +383 -0
  49. package/src/lib/doctor.js +385 -0
  50. package/src/lib/dumate.js +95 -0
  51. package/src/lib/fs.js +455 -0
  52. package/src/lib/function-url.js +14 -0
  53. package/src/lib/gemini-config.js +291 -0
  54. package/src/lib/git-outcomes.js +243 -0
  55. package/src/lib/grok-context-breakdown.js +890 -0
  56. package/src/lib/grok-hook.js +360 -0
  57. package/src/lib/grok-limits.js +865 -0
  58. package/src/lib/grok-usage.js +98 -0
  59. package/src/lib/heatmap-compact.js +114 -0
  60. package/src/lib/ingest-sanitize.js +41 -0
  61. package/src/lib/init-flow.js +42 -0
  62. package/src/lib/install-resolver.js +170 -0
  63. package/src/lib/jsonl-lines.js +134 -0
  64. package/src/lib/kimi-model-repair.js +173 -0
  65. package/src/lib/kimi-profile.js +61 -0
  66. package/src/lib/kimi-session.js +216 -0
  67. package/src/lib/local-api.js +3588 -0
  68. package/src/lib/machine-id.js +238 -0
  69. package/src/lib/multi-install-parser.js +113 -0
  70. package/src/lib/notify-command.js +38 -0
  71. package/src/lib/omp-hook.js +589 -0
  72. package/src/lib/openclaw-cli.js +104 -0
  73. package/src/lib/openclaw-hook.js +375 -0
  74. package/src/lib/openclaw-session-plugin.js +560 -0
  75. package/src/lib/opencode-config.js +121 -0
  76. package/src/lib/opencode-go-limits.js +807 -0
  77. package/src/lib/outcomes-engine.js +253 -0
  78. package/src/lib/passive-mode.js +219 -0
  79. package/src/lib/pet-packages.js +722 -0
  80. package/src/lib/pricing/curated-overrides.json +822 -0
  81. package/src/lib/pricing/index.js +379 -0
  82. package/src/lib/pricing/litellm-fetcher.js +172 -0
  83. package/src/lib/pricing/matcher.js +456 -0
  84. package/src/lib/pricing/seed-snapshot.json +1 -0
  85. package/src/lib/progress.js +76 -0
  86. package/src/lib/project-usage-purge.js +117 -0
  87. package/src/lib/prompt.js +24 -0
  88. package/src/lib/provider-status.js +104 -0
  89. package/src/lib/proxy-env.js +489 -0
  90. package/src/lib/proxy-settings.js +163 -0
  91. package/src/lib/qoder-cn-cli-limits.js +119 -0
  92. package/src/lib/qoder-limits.js +880 -0
  93. package/src/lib/quiet-warnings.js +26 -0
  94. package/src/lib/rollout.js +25966 -0
  95. package/src/lib/runtime-config.js +259 -0
  96. package/src/lib/scan-roots.js +277 -0
  97. package/src/lib/sentry.js +231 -0
  98. package/src/lib/session-analytics.js +2972 -0
  99. package/src/lib/session-performance.js +237 -0
  100. package/src/lib/session-upload.js +379 -0
  101. package/src/lib/skill-usage.js +267 -0
  102. package/src/lib/skills-manager.js +1591 -0
  103. package/src/lib/source-metadata.js +48 -0
  104. package/src/lib/sqlite-reader.js +215 -0
  105. package/src/lib/star-cta.js +73 -0
  106. package/src/lib/subscription-manager.js +293 -0
  107. package/src/lib/subscriptions.js +508 -0
  108. package/src/lib/telemetry.js +193 -0
  109. package/src/lib/tracker-paths.js +16 -0
  110. package/src/lib/trae-cn-config.js +548 -0
  111. package/src/lib/trae-db.js +127 -0
  112. package/src/lib/trae-snapshot.js +230 -0
  113. package/src/lib/trae-sqlite.js +143 -0
  114. package/src/lib/trae-usage.js +121 -0
  115. package/src/lib/upload-queue.js +134 -0
  116. package/src/lib/upload-throttle.js +171 -0
  117. package/src/lib/usage-limits.js +4552 -0
  118. package/src/lib/wrapped-aggregator.js +236 -0
  119. package/src/lib/wsl-probe.js +281 -0
  120. package/src/lib/zcode-limits.js +1172 -0
  121. package/src/lib/zcode-reset-credits.js +66 -0
  122. package/test/cli-smoke.test.js +53 -0
  123. package/test/ingest-sanitize.test.js +162 -0
  124. package/test/quiet-warnings.test.js +53 -0
  125. package/test/session-upload.test.js +427 -0
@@ -0,0 +1,312 @@
1
+ const os = require("node:os");
2
+ const path = require("node:path");
3
+ const fs = require("node:fs/promises");
4
+ const { expandHome } = require("../lib/scan-roots");
5
+
6
+ const {
7
+ restoreCodexNotify,
8
+ restoreAcodeNotify,
9
+ restoreEveryCodeNotify,
10
+ buildCodexNotifyCmd,
11
+ buildAcodeNotifyCmd,
12
+ buildEveryCodeNotifyCmd,
13
+ } = require("../lib/codex-config");
14
+ const {
15
+ removeClaudeHook,
16
+ removeClaudeUsageHooks,
17
+ buildClaudeHookCommand,
18
+ buildHookCommand,
19
+ } = require("../lib/claude-config");
20
+ const {
21
+ resolveGeminiConfigDir,
22
+ resolveGeminiSettingsPath,
23
+ buildGeminiHookCommand,
24
+ removeGeminiHook,
25
+ } = require("../lib/gemini-config");
26
+ const { resolveOpencodeConfigDir, removeOpencodePlugin } = require("../lib/opencode-config");
27
+ const { removeOpenclawHookConfig } = require("../lib/openclaw-hook");
28
+ const { removeOpenclawSessionPluginConfig } = require("../lib/openclaw-session-plugin");
29
+ const { removeGrokHook } = require("../lib/grok-hook");
30
+ const { removeOmpHook } = require("../lib/omp-hook");
31
+ const { resolveTrackerPaths } = require("../lib/tracker-paths");
32
+
33
+ async function cmdUninstall(argv) {
34
+ const opts = parseArgs(argv);
35
+ const home = os.homedir();
36
+ const { trackerDir, binDir } = await resolveTrackerPaths({ home });
37
+ const codexHome = process.env.CODEX_HOME || path.join(home, ".codex");
38
+ const codexConfigPath = path.join(codexHome, "config.toml");
39
+ const acodeHome = process.env.TOKENUSAGE_ACODE_HOME || path.join(home, ".acode");
40
+ const acodeConfigPath = path.join(acodeHome, "config.toml");
41
+ const codeHome = process.env.CODE_HOME || path.join(home, ".code");
42
+ const codeConfigPath = path.join(codeHome, "config.toml");
43
+ const claudeSettingsPath = path.join(home, ".claude", "settings.json");
44
+ const codebuddyDir = process.env.CODEBUDDY_HOME || path.join(home, ".codebuddy");
45
+ const codebuddySettingsPath = path.join(codebuddyDir, "settings.json");
46
+ const workbuddyDir = process.env.WORKBUDDY_HOME || path.join(home, ".workbuddy");
47
+ const workbuddySettingsPath = path.join(workbuddyDir, "settings.json");
48
+ // WorkBuddy AI — international build, sibling home (~/.workbuddy-ai).
49
+ const workbuddyAiDir = expandHome(process.env.WORKBUDDY_AI_HOME, home) || path.join(home, ".workbuddy-ai");
50
+ const workbuddyAiSettingsPath = path.join(workbuddyAiDir, "settings.json");
51
+ const geminiConfigDir = resolveGeminiConfigDir({ home, env: process.env });
52
+ const geminiSettingsPath = resolveGeminiSettingsPath({ configDir: geminiConfigDir });
53
+ const opencodeConfigDir = resolveOpencodeConfigDir({ home, env: process.env });
54
+ const notifyPath = path.join(binDir, "notify.cjs");
55
+ const notifyOriginalPath = path.join(trackerDir, "codex_notify_original.json");
56
+ const acodeNotifyOriginalPath = path.join(trackerDir, "acode_notify_original.json");
57
+ const codeNotifyOriginalPath = path.join(trackerDir, "code_notify_original.json");
58
+ const codexNotifyCmd = buildCodexNotifyCmd(notifyPath);
59
+ const acodeNotifyCmd = buildAcodeNotifyCmd(notifyPath);
60
+ const codeNotifyCmd = buildEveryCodeNotifyCmd(notifyPath);
61
+ const claudeHookCommand = buildClaudeHookCommand(notifyPath);
62
+ const codebuddyHookCommand = buildHookCommand(notifyPath, "codebuddy");
63
+ const workbuddyHookCommand = buildHookCommand(notifyPath, "workbuddy");
64
+ const workbuddyAiHookCommand = buildHookCommand(notifyPath, "workbuddy-ai");
65
+ const geminiHookCommand = buildGeminiHookCommand(notifyPath);
66
+
67
+ const codexConfigExists = await isFile(codexConfigPath);
68
+ const acodeConfigExists = await isFile(acodeConfigPath);
69
+ const codeConfigExists = await isFile(codeConfigPath);
70
+ const claudeConfigExists = await isFile(claudeSettingsPath);
71
+ const codebuddyConfigExists = await isFile(codebuddySettingsPath);
72
+ const workbuddyConfigExists = await isFile(workbuddySettingsPath);
73
+ const workbuddyAiConfigExists = await isFile(workbuddyAiSettingsPath);
74
+ const geminiConfigExists = await isDir(geminiConfigDir);
75
+ const opencodeConfigExists = await isDir(opencodeConfigDir);
76
+ const codexRestore = codexConfigExists
77
+ ? await restoreCodexNotify({
78
+ codexConfigPath,
79
+ notifyOriginalPath,
80
+ notifyCmd: codexNotifyCmd,
81
+ })
82
+ : { restored: false, skippedReason: "config-missing" };
83
+ const acodeRestore = acodeConfigExists
84
+ ? await restoreAcodeNotify({
85
+ acodeConfigPath,
86
+ notifyOriginalPath: acodeNotifyOriginalPath,
87
+ notifyCmd: acodeNotifyCmd,
88
+ })
89
+ : { restored: false, skippedReason: "config-missing" };
90
+ const codeRestore = codeConfigExists
91
+ ? await restoreEveryCodeNotify({
92
+ codeConfigPath,
93
+ notifyOriginalPath: codeNotifyOriginalPath,
94
+ notifyCmd: codeNotifyCmd,
95
+ })
96
+ : { restored: false, skippedReason: "config-missing" };
97
+ const claudeRemove = claudeConfigExists
98
+ ? await removeClaudeUsageHooks({
99
+ settingsPath: claudeSettingsPath,
100
+ hookCommand: claudeHookCommand,
101
+ })
102
+ : { removed: false, skippedReason: "config-missing" };
103
+ const codebuddyRemove = codebuddyConfigExists
104
+ ? await removeClaudeHook({
105
+ settingsPath: codebuddySettingsPath,
106
+ hookCommand: codebuddyHookCommand,
107
+ })
108
+ : { removed: false, skippedReason: "config-missing" };
109
+ const workbuddyRemove = workbuddyConfigExists
110
+ ? await removeClaudeHook({
111
+ settingsPath: workbuddySettingsPath,
112
+ hookCommand: workbuddyHookCommand,
113
+ })
114
+ : { removed: false, skippedReason: "config-missing" };
115
+ const workbuddyAiRemove = workbuddyAiConfigExists
116
+ ? await removeClaudeHook({
117
+ settingsPath: workbuddyAiSettingsPath,
118
+ hookCommand: workbuddyAiHookCommand,
119
+ })
120
+ : { removed: false, skippedReason: "config-missing" };
121
+ const geminiRemove = geminiConfigExists
122
+ ? await removeGeminiHook({ settingsPath: geminiSettingsPath, hookCommand: geminiHookCommand })
123
+ : { removed: false, skippedReason: "config-missing" };
124
+ const opencodeRemove = opencodeConfigExists
125
+ ? await removeOpencodePlugin({ configDir: opencodeConfigDir })
126
+ : { removed: false, skippedReason: "config-missing" };
127
+ const openclawSessionPluginRemove = await removeOpenclawSessionPluginConfig({
128
+ home,
129
+ trackerDir,
130
+ env: process.env,
131
+ });
132
+ const openclawHookRemove = await removeOpenclawHookConfig({ home, trackerDir, env: process.env });
133
+ const grokHookRemove = await removeGrokHook({ home, trackerDir, env: process.env });
134
+ const ompHookRemove = await removeOmpHook({ home, trackerDir, env: process.env });
135
+
136
+ // Remove installed notify handler.
137
+ await fs.unlink(notifyPath).catch(() => {});
138
+
139
+ // Remove local app runtime (installed by init for notify-driven sync).
140
+ await fs.rm(path.join(trackerDir, "app"), { recursive: true, force: true }).catch(() => {});
141
+
142
+ // Deliberately NOT removed by --purge: the machine-identity seed lets a
143
+ // reinstall reuse the same cloud device row instead of double-counting the
144
+ // replayed history under a new device (issue #176).
145
+ const machineIdSeedPath = path.join(home, ".config", "tokenusage", "machine-id");
146
+ let machineIdSeedKept = false;
147
+ if (opts.purge) {
148
+ await fs.rm(path.join(home, ".tokenusage"), { recursive: true, force: true }).catch(() => {});
149
+ machineIdSeedKept = await fs.access(machineIdSeedPath).then(
150
+ () => true,
151
+ () => false,
152
+ );
153
+ }
154
+
155
+ process.stdout.write(
156
+ [
157
+ "Uninstalled:",
158
+ codexConfigExists
159
+ ? codexRestore?.restored
160
+ ? `- Codex notify restored: ${codexConfigPath}`
161
+ : codexRestore?.skippedReason === "no-backup-not-installed"
162
+ ? "- Codex notify: skipped (no backup; not installed)"
163
+ : codexRestore?.skippedReason === "current-not-managed"
164
+ ? "- Codex notify: skipped (current notify is not managed by tokenusage)"
165
+ : "- Codex notify: no change"
166
+ : "- Codex notify: skipped (config.toml not found)",
167
+ acodeConfigExists
168
+ ? acodeRestore?.restored
169
+ ? `- AStudio notify restored: ${acodeConfigPath}`
170
+ : acodeRestore?.skippedReason === "no-backup-not-installed"
171
+ ? "- AStudio notify: skipped (no backup; not installed)"
172
+ : acodeRestore?.skippedReason === "current-not-managed"
173
+ ? "- AStudio notify: skipped (current notify is not managed by tokenusage)"
174
+ : "- AStudio notify: no change"
175
+ : "- AStudio notify: skipped (config.toml not found)",
176
+ codeConfigExists
177
+ ? codeRestore?.restored
178
+ ? `- Every Code notify restored: ${codeConfigPath}`
179
+ : codeRestore?.skippedReason === "no-backup-not-installed"
180
+ ? "- Every Code notify: skipped (no backup; not installed)"
181
+ : codeRestore?.skippedReason === "current-not-managed"
182
+ ? "- Every Code notify: skipped (current notify is not managed by tokenusage)"
183
+ : "- Every Code notify: no change"
184
+ : "- Every Code notify: skipped (config.toml not found)",
185
+ claudeConfigExists
186
+ ? claudeRemove?.removed
187
+ ? `- Claude hooks removed: ${claudeSettingsPath}`
188
+ : claudeRemove?.skippedReason === "hook-missing"
189
+ ? "- Claude hooks: no change"
190
+ : "- Claude hooks: skipped"
191
+ : "- Claude hooks: skipped (settings.json not found)",
192
+ codebuddyConfigExists
193
+ ? codebuddyRemove?.removed
194
+ ? `- CodeBuddy hooks removed: ${codebuddySettingsPath}`
195
+ : codebuddyRemove?.skippedReason === "hook-missing"
196
+ ? "- CodeBuddy hooks: no change"
197
+ : "- CodeBuddy hooks: skipped"
198
+ : "- CodeBuddy hooks: skipped (settings.json not found)",
199
+ workbuddyConfigExists
200
+ ? workbuddyRemove?.removed
201
+ ? `- WorkBuddy hooks removed: ${workbuddySettingsPath}`
202
+ : workbuddyRemove?.skippedReason === "hook-missing"
203
+ ? "- WorkBuddy hooks: no change"
204
+ : "- WorkBuddy hooks: skipped"
205
+ : "- WorkBuddy hooks: skipped (settings.json not found)",
206
+ workbuddyAiConfigExists
207
+ ? workbuddyAiRemove?.removed
208
+ ? `- WorkBuddy AI hooks removed: ${workbuddyAiSettingsPath}`
209
+ : workbuddyAiRemove?.skippedReason === "hook-missing"
210
+ ? "- WorkBuddy AI hooks: no change"
211
+ : "- WorkBuddy AI hooks: skipped"
212
+ : "- WorkBuddy AI hooks: skipped (settings.json not found)",
213
+ geminiConfigExists
214
+ ? geminiRemove?.removed
215
+ ? `- Gemini hooks removed: ${geminiSettingsPath}`
216
+ : geminiRemove?.skippedReason === "hook-missing"
217
+ ? "- Gemini hooks: no change"
218
+ : "- Gemini hooks: skipped"
219
+ : `- Gemini hooks: skipped (${geminiConfigDir} not found)`,
220
+ opencodeConfigExists
221
+ ? opencodeRemove?.removed
222
+ ? `- Opencode plugin removed: ${opencodeConfigDir}`
223
+ : opencodeRemove?.skippedReason === "plugin-missing"
224
+ ? "- Opencode plugin: no change"
225
+ : opencodeRemove?.skippedReason === "unexpected-content"
226
+ ? "- Opencode plugin: skipped (unexpected content)"
227
+ : "- Opencode plugin: skipped"
228
+ : `- Opencode plugin: skipped (${opencodeConfigDir} not found)`,
229
+ openclawSessionPluginRemove?.removed
230
+ ? `- OpenClaw session plugin removed: ${openclawSessionPluginRemove.openclawConfigPath}`
231
+ : openclawSessionPluginRemove?.skippedReason === "openclaw-config-missing"
232
+ ? "- OpenClaw session plugin: skipped (openclaw config not found)"
233
+ : "- OpenClaw session plugin: no change",
234
+ openclawHookRemove?.removed
235
+ ? `- OpenClaw hook (legacy) removed: ${openclawHookRemove.openclawConfigPath}`
236
+ : openclawHookRemove?.skippedReason === "openclaw-config-missing"
237
+ ? "- OpenClaw hook (legacy): skipped (openclaw config not found)"
238
+ : "- OpenClaw hook (legacy): no change",
239
+ grokHookRemove?.removed
240
+ ? `- Grok Build hook removed: ${grokHookRemove.hookPath}`
241
+ : "- Grok Build hook: no change",
242
+ formatOmpHookRemoveLine(ompHookRemove),
243
+ opts.purge ? `- Purged: ${path.join(home, ".tokenusage")}` : "- Purge: skipped (use --purge)",
244
+ ...(machineIdSeedKept
245
+ ? [`- Kept: ${machineIdSeedPath} (cloud device identity — a reinstall reuses the same device; delete it to fully reset)`]
246
+ : []),
247
+ "",
248
+ ].join("\n"),
249
+ );
250
+ }
251
+
252
+ function formatOmpHookRemoveLine(ompHookRemove) {
253
+ if (ompHookRemove?.removed) {
254
+ return `- oh-my-pi notify extension removed: ${ompHookRemove.extensionPath}`;
255
+ }
256
+ const reason = ompHookRemove?.skippedReason;
257
+ const residualPath = ompHookRemove?.stagedPath || ompHookRemove?.extensionPath;
258
+ const residual = residualPath
259
+ ? ` (left in place: ${residualPath})`
260
+ : "";
261
+ if (reason === "unmanaged") {
262
+ return `- oh-my-pi notify extension: skipped (unmanaged file)${residual}`;
263
+ }
264
+ if (reason === "unlink-failed") {
265
+ const detail = ompHookRemove?.error ? `: ${ompHookRemove.error}` : "";
266
+ return `- oh-my-pi notify extension: failed to remove${detail}${residual}`;
267
+ }
268
+ if (reason === "extension-read-failed") {
269
+ const detail = ompHookRemove?.error ? `: ${ompHookRemove.error}` : "";
270
+ return `- oh-my-pi notify extension: failed to read${detail}${residual}`;
271
+ }
272
+ if (reason === "identity-changed") {
273
+ return `- oh-my-pi notify extension: skipped (file changed during uninstall)${residual}`;
274
+ }
275
+ if (reason === "omp-agent-dir-unresolved") {
276
+ return "- oh-my-pi notify extension: skipped (omp agent dir unresolved)";
277
+ }
278
+ if (reason === "missing") {
279
+ return "- oh-my-pi notify extension: no change";
280
+ }
281
+ return "- oh-my-pi notify extension: no change";
282
+ }
283
+
284
+ function parseArgs(argv) {
285
+ const out = { purge: false };
286
+ for (let i = 0; i < argv.length; i++) {
287
+ const a = argv[i];
288
+ if (a === "--purge") out.purge = true;
289
+ else throw new Error(`Unknown option: ${a}`);
290
+ }
291
+ return out;
292
+ }
293
+
294
+ module.exports = { cmdUninstall, formatOmpHookRemoveLine };
295
+
296
+ async function isFile(p) {
297
+ try {
298
+ const st = await fs.stat(p);
299
+ return st.isFile();
300
+ } catch (_e) {
301
+ return false;
302
+ }
303
+ }
304
+
305
+ async function isDir(p) {
306
+ try {
307
+ const st = await fs.stat(p);
308
+ return st.isDirectory();
309
+ } catch (_e) {
310
+ return false;
311
+ }
312
+ }
@@ -0,0 +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
+ };
@@ -0,0 +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
+ };