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,253 +1,253 @@
1
- "use strict";
2
-
3
- // ---------------------------------------------------------------------------
4
- // Quality-per-dollar / Effective-Tokens engine (opt-in, sidecar)
5
- //
6
- // Token Usage answers "what did the tokens COST?". This optional layer adds
7
- // "what did they BUY?" by joining an opt-in, vendor-neutral `outcomes.jsonl`
8
- // sidecar to the existing token/$ rows by model + time.
9
- //
10
- // Design invariants (see GitHub #229):
11
- // 1. SIDECAR, never the hot path. This module only ever READS its own file
12
- // and the already-parsed queue rows. It never touches queue.jsonl, its
13
- // schema, or the sync path. A bug here cannot corrupt token/$ data.
14
- // 2. DEGRADES TO COST-ONLY. No outcomes file -> readOutcomesData returns []
15
- // and every join yields empty, so callers render exactly as today.
16
- // 3. METADATA-ONLY. sanitizeOutcome whitelists a tiny set of scalar fields
17
- // and drops everything else, so a mis-populated sidecar can NEVER surface
18
- // PR bodies, diffs, or message text into the dashboard.
19
- // ---------------------------------------------------------------------------
20
-
21
- const fs = require("node:fs");
22
- const os = require("node:os");
23
- const path = require("node:path");
24
- const { computeRowCost } = require("./pricing");
25
-
26
- function resolveOutcomesPath() {
27
- return path.join(os.homedir(), ".tokenusage", "tracker", "outcomes.jsonl");
28
- }
29
-
30
- function resolveAutoOutcomesPath() {
31
- return path.join(os.homedir(), ".tokenusage", "tracker", "auto-outcomes.jsonl");
32
- }
33
-
34
- // The ONLY fields ever lifted off an outcome record. Anything not on this list
35
- // — bodies, diffs, messages, arbitrary blobs — is dropped at read time. This is
36
- // the enforcement point for the metadata-only privacy invariant.
37
- function sanitizeOutcome(raw) {
38
- if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
39
- const timestamp = typeof raw.timestamp === "string" ? raw.timestamp.trim() : "";
40
- if (!timestamp) return null; // an outcome with no time can't be joined to $ rows
41
-
42
- // `accepted` is the gate signal: a merged PR / passed task. Strictly boolean
43
- // — anything other than literal true counts as not-accepted (rework).
44
- const accepted = raw.accepted === true;
45
-
46
- const model =
47
- typeof raw.model === "string" && raw.model.trim() ? raw.model.trim() : "unknown";
48
- // `tool` mirrors the queue row's `source` (claude, codex, cursor, …). Accept
49
- // either key so writers can use whichever they have on hand.
50
- const toolRaw =
51
- (typeof raw.tool === "string" && raw.tool.trim() && raw.tool) ||
52
- (typeof raw.source === "string" && raw.source.trim() && raw.source) ||
53
- "";
54
- const tool = toolRaw ? String(toolRaw).trim() : "unknown";
55
-
56
- const out = { timestamp, model, tool, accepted };
57
- // task_type is an optional, low-cardinality label (e.g. "feature", "bugfix").
58
- if (typeof raw.task_type === "string" && raw.task_type.trim()) {
59
- out.task_type = raw.task_type.trim();
60
- }
61
- for (const key of ["status", "session_hash", "commit_hash", "confidence", "methodology"]) {
62
- if (typeof raw[key] === "string" && raw[key].trim()) out[key] = raw[key].trim();
63
- }
64
- if (Number.isFinite(Number(raw.parent_count))) out.parent_count = Number(raw.parent_count);
65
- return out;
66
- }
67
-
68
- function readOutcomesData(outcomesPath) {
69
- let raw;
70
- try {
71
- raw = fs.readFileSync(outcomesPath, "utf8");
72
- } catch (e) {
73
- // ENOENT is the normal "user hasn't opted in" case — silent. Anything else
74
- // is surfaced once so a genuinely unreadable file isn't hidden forever.
75
- if (e && e.code !== "ENOENT") {
76
- console.error("[outcomes] read failed:", (e && e.message) || e);
77
- }
78
- return [];
79
- }
80
- const out = [];
81
- let malformed = 0;
82
- for (const line of raw.split("\n")) {
83
- const trimmed = line.trim();
84
- if (!trimmed) continue;
85
- let parsed;
86
- try {
87
- parsed = JSON.parse(trimmed);
88
- } catch {
89
- malformed += 1;
90
- continue;
91
- }
92
- const rec = sanitizeOutcome(parsed);
93
- if (rec) out.push(rec);
94
- else malformed += 1;
95
- }
96
- if (malformed > 0) {
97
- console.error(`[outcomes] skipped ${malformed} malformed/invalid line(s) in ${outcomesPath}`);
98
- }
99
- return out;
100
- }
101
-
102
- function readAllOutcomesData(paths = [resolveOutcomesPath(), resolveAutoOutcomesPath()]) {
103
- const dedup = new Map();
104
- for (const outcomePath of paths) {
105
- for (const row of readOutcomesData(outcomePath)) {
106
- const key = row.commit_hash
107
- ? `commit:${row.commit_hash}`
108
- : `${row.timestamp}|${row.model}|${row.tool}|${row.task_type || ""}`;
109
- dedup.set(key, row);
110
- }
111
- }
112
- return [...dedup.values()];
113
- }
114
-
115
- function dayOf(value) {
116
- return typeof value === "string" ? value.slice(0, 10) : "";
117
- }
118
-
119
- function inWindow(dayStr, from, to) {
120
- if (from && dayStr && dayStr < from) return false;
121
- if (to && dayStr && dayStr > to) return false;
122
- return true;
123
- }
124
-
125
- function bumpCost(map, key, cost, tokens) {
126
- let agg = map.get(key);
127
- if (!agg) {
128
- agg = { cost_usd: 0, total_tokens: 0 };
129
- map.set(key, agg);
130
- }
131
- agg.cost_usd += cost;
132
- agg.total_tokens += tokens;
133
- }
134
-
135
- function bumpOutcome(map, key, accepted) {
136
- let agg = map.get(key);
137
- if (!agg) {
138
- agg = { accepted: 0, outcomes: 0 };
139
- map.set(key, agg);
140
- }
141
- agg.outcomes += 1;
142
- if (accepted) agg.accepted += 1;
143
- }
144
-
145
- function combineRow(key, cost, out) {
146
- const cost_usd = cost ? cost.cost_usd : 0;
147
- const total_tokens = cost ? cost.total_tokens : 0;
148
- const accepted = out ? out.accepted : 0;
149
- const outcomes = out ? out.outcomes : 0;
150
- const acceptance_rate = outcomes > 0 ? accepted / outcomes : null;
151
- // quality per dollar = accepted, gate-passing outcomes ÷ dollars spent.
152
- // Null (not zero) when we can't form the ratio — no spend or no outcomes —
153
- // so the UI can distinguish "0 quality" from "not enough data".
154
- const quality_per_dollar = cost_usd > 0 && outcomes > 0 ? accepted / cost_usd : null;
155
- // Effective Tokens: the share of tokens that produced accepted work.
156
- const effective_tokens = acceptance_rate === null ? null : total_tokens * acceptance_rate;
157
- const effective_cost_usd = acceptance_rate === null ? null : cost_usd * acceptance_rate;
158
- return {
159
- key,
160
- cost_usd,
161
- total_tokens,
162
- accepted,
163
- outcomes,
164
- acceptance_rate,
165
- quality_per_dollar,
166
- effective_tokens,
167
- effective_cost_usd,
168
- };
169
- }
170
-
171
- function combine(costMap, outMap) {
172
- const keys = new Set([...costMap.keys(), ...outMap.keys()]);
173
- const rows = [];
174
- for (const key of keys) {
175
- rows.push(combineRow(key, costMap.get(key), outMap.get(key)));
176
- }
177
- // Highest quality-per-dollar first; rows without a ratio sink to the bottom.
178
- rows.sort((a, b) => {
179
- const av = a.quality_per_dollar;
180
- const bv = b.quality_per_dollar;
181
- if (av === null && bv === null) return b.outcomes - a.outcomes;
182
- if (av === null) return 1;
183
- if (bv === null) return -1;
184
- return bv - av;
185
- });
186
- return rows;
187
- }
188
-
189
- /**
190
- * Join outcomes to token/$ rows by model + tool, within an optional [from,to]
191
- * day window. Returns per-model and per-tool quality-per-dollar / ET, plus
192
- * totals. Pure: no I/O, no mutation of inputs.
193
- *
194
- * @param {Array} queueRows already-parsed queue rows ({ source, model, hour_start, …token fields })
195
- * @param {Array} outcomes sanitized outcome records (from readOutcomesData)
196
- * @param {{from?:string,to?:string}} [window]
197
- */
198
- function computeQualityPerDollar(queueRows, outcomes, { from = "", to = "" } = {}) {
199
- const modelCost = new Map();
200
- const toolCost = new Map();
201
- for (const row of queueRows || []) {
202
- if (!row || typeof row !== "object") continue; // tolerate a stray null/garbage line
203
- const day = dayOf(row.hour_start);
204
- if ((from || to) && !inWindow(day, from, to)) continue;
205
- const model = (row && row.model) || "unknown";
206
- const tool = (row && row.source) || "unknown";
207
- const cost = computeRowCost(row) || 0;
208
- const tokens = Number((row && row.total_tokens) || 0);
209
- bumpCost(modelCost, model, cost, tokens);
210
- bumpCost(toolCost, tool, cost, tokens);
211
- }
212
-
213
- const modelOut = new Map();
214
- const toolOut = new Map();
215
- for (const o of outcomes || []) {
216
- const day = dayOf(o && o.timestamp);
217
- if ((from || to) && !inWindow(day, from, to)) continue;
218
- bumpOutcome(modelOut, (o && o.model) || "unknown", !!(o && o.accepted));
219
- bumpOutcome(toolOut, (o && o.tool) || "unknown", !!(o && o.accepted));
220
- }
221
-
222
- const by_model = combine(modelCost, modelOut);
223
- const by_tool = combine(toolCost, toolOut);
224
-
225
- let totalCost = 0;
226
- let totalTokens = 0;
227
- for (const v of modelCost.values()) {
228
- totalCost += v.cost_usd;
229
- totalTokens += v.total_tokens;
230
- }
231
- let totalAccepted = 0;
232
- let totalOutcomes = 0;
233
- for (const v of modelOut.values()) {
234
- totalAccepted += v.accepted;
235
- totalOutcomes += v.outcomes;
236
- }
237
- const totals = combineRow(
238
- "__all__",
239
- { cost_usd: totalCost, total_tokens: totalTokens },
240
- { accepted: totalAccepted, outcomes: totalOutcomes },
241
- );
242
-
243
- return { available: outcomes && outcomes.length > 0, by_model, by_tool, totals };
244
- }
245
-
246
- module.exports = {
247
- resolveOutcomesPath,
248
- resolveAutoOutcomesPath,
249
- sanitizeOutcome,
250
- readOutcomesData,
251
- readAllOutcomesData,
252
- computeQualityPerDollar,
253
- };
1
+ "use strict";
2
+
3
+ // ---------------------------------------------------------------------------
4
+ // Quality-per-dollar / Effective-Tokens engine (opt-in, sidecar)
5
+ //
6
+ // Token Usage answers "what did the tokens COST?". This optional layer adds
7
+ // "what did they BUY?" by joining an opt-in, vendor-neutral `outcomes.jsonl`
8
+ // sidecar to the existing token/$ rows by model + time.
9
+ //
10
+ // Design invariants (see GitHub #229):
11
+ // 1. SIDECAR, never the hot path. This module only ever READS its own file
12
+ // and the already-parsed queue rows. It never touches queue.jsonl, its
13
+ // schema, or the sync path. A bug here cannot corrupt token/$ data.
14
+ // 2. DEGRADES TO COST-ONLY. No outcomes file -> readOutcomesData returns []
15
+ // and every join yields empty, so callers render exactly as today.
16
+ // 3. METADATA-ONLY. sanitizeOutcome whitelists a tiny set of scalar fields
17
+ // and drops everything else, so a mis-populated sidecar can NEVER surface
18
+ // PR bodies, diffs, or message text into the dashboard.
19
+ // ---------------------------------------------------------------------------
20
+
21
+ const fs = require("node:fs");
22
+ const os = require("node:os");
23
+ const path = require("node:path");
24
+ const { computeRowCost } = require("./pricing");
25
+
26
+ function resolveOutcomesPath() {
27
+ return path.join(os.homedir(), ".tokenusage", "tracker", "outcomes.jsonl");
28
+ }
29
+
30
+ function resolveAutoOutcomesPath() {
31
+ return path.join(os.homedir(), ".tokenusage", "tracker", "auto-outcomes.jsonl");
32
+ }
33
+
34
+ // The ONLY fields ever lifted off an outcome record. Anything not on this list
35
+ // — bodies, diffs, messages, arbitrary blobs — is dropped at read time. This is
36
+ // the enforcement point for the metadata-only privacy invariant.
37
+ function sanitizeOutcome(raw) {
38
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
39
+ const timestamp = typeof raw.timestamp === "string" ? raw.timestamp.trim() : "";
40
+ if (!timestamp) return null; // an outcome with no time can't be joined to $ rows
41
+
42
+ // `accepted` is the gate signal: a merged PR / passed task. Strictly boolean
43
+ // — anything other than literal true counts as not-accepted (rework).
44
+ const accepted = raw.accepted === true;
45
+
46
+ const model =
47
+ typeof raw.model === "string" && raw.model.trim() ? raw.model.trim() : "unknown";
48
+ // `tool` mirrors the queue row's `source` (claude, codex, cursor, …). Accept
49
+ // either key so writers can use whichever they have on hand.
50
+ const toolRaw =
51
+ (typeof raw.tool === "string" && raw.tool.trim() && raw.tool) ||
52
+ (typeof raw.source === "string" && raw.source.trim() && raw.source) ||
53
+ "";
54
+ const tool = toolRaw ? String(toolRaw).trim() : "unknown";
55
+
56
+ const out = { timestamp, model, tool, accepted };
57
+ // task_type is an optional, low-cardinality label (e.g. "feature", "bugfix").
58
+ if (typeof raw.task_type === "string" && raw.task_type.trim()) {
59
+ out.task_type = raw.task_type.trim();
60
+ }
61
+ for (const key of ["status", "session_hash", "commit_hash", "confidence", "methodology"]) {
62
+ if (typeof raw[key] === "string" && raw[key].trim()) out[key] = raw[key].trim();
63
+ }
64
+ if (Number.isFinite(Number(raw.parent_count))) out.parent_count = Number(raw.parent_count);
65
+ return out;
66
+ }
67
+
68
+ function readOutcomesData(outcomesPath) {
69
+ let raw;
70
+ try {
71
+ raw = fs.readFileSync(outcomesPath, "utf8");
72
+ } catch (e) {
73
+ // ENOENT is the normal "user hasn't opted in" case — silent. Anything else
74
+ // is surfaced once so a genuinely unreadable file isn't hidden forever.
75
+ if (e && e.code !== "ENOENT") {
76
+ console.error("[outcomes] read failed:", (e && e.message) || e);
77
+ }
78
+ return [];
79
+ }
80
+ const out = [];
81
+ let malformed = 0;
82
+ for (const line of raw.split("\n")) {
83
+ const trimmed = line.trim();
84
+ if (!trimmed) continue;
85
+ let parsed;
86
+ try {
87
+ parsed = JSON.parse(trimmed);
88
+ } catch {
89
+ malformed += 1;
90
+ continue;
91
+ }
92
+ const rec = sanitizeOutcome(parsed);
93
+ if (rec) out.push(rec);
94
+ else malformed += 1;
95
+ }
96
+ if (malformed > 0) {
97
+ console.error(`[outcomes] skipped ${malformed} malformed/invalid line(s) in ${outcomesPath}`);
98
+ }
99
+ return out;
100
+ }
101
+
102
+ function readAllOutcomesData(paths = [resolveOutcomesPath(), resolveAutoOutcomesPath()]) {
103
+ const dedup = new Map();
104
+ for (const outcomePath of paths) {
105
+ for (const row of readOutcomesData(outcomePath)) {
106
+ const key = row.commit_hash
107
+ ? `commit:${row.commit_hash}`
108
+ : `${row.timestamp}|${row.model}|${row.tool}|${row.task_type || ""}`;
109
+ dedup.set(key, row);
110
+ }
111
+ }
112
+ return [...dedup.values()];
113
+ }
114
+
115
+ function dayOf(value) {
116
+ return typeof value === "string" ? value.slice(0, 10) : "";
117
+ }
118
+
119
+ function inWindow(dayStr, from, to) {
120
+ if (from && dayStr && dayStr < from) return false;
121
+ if (to && dayStr && dayStr > to) return false;
122
+ return true;
123
+ }
124
+
125
+ function bumpCost(map, key, cost, tokens) {
126
+ let agg = map.get(key);
127
+ if (!agg) {
128
+ agg = { cost_usd: 0, total_tokens: 0 };
129
+ map.set(key, agg);
130
+ }
131
+ agg.cost_usd += cost;
132
+ agg.total_tokens += tokens;
133
+ }
134
+
135
+ function bumpOutcome(map, key, accepted) {
136
+ let agg = map.get(key);
137
+ if (!agg) {
138
+ agg = { accepted: 0, outcomes: 0 };
139
+ map.set(key, agg);
140
+ }
141
+ agg.outcomes += 1;
142
+ if (accepted) agg.accepted += 1;
143
+ }
144
+
145
+ function combineRow(key, cost, out) {
146
+ const cost_usd = cost ? cost.cost_usd : 0;
147
+ const total_tokens = cost ? cost.total_tokens : 0;
148
+ const accepted = out ? out.accepted : 0;
149
+ const outcomes = out ? out.outcomes : 0;
150
+ const acceptance_rate = outcomes > 0 ? accepted / outcomes : null;
151
+ // quality per dollar = accepted, gate-passing outcomes ÷ dollars spent.
152
+ // Null (not zero) when we can't form the ratio — no spend or no outcomes —
153
+ // so the UI can distinguish "0 quality" from "not enough data".
154
+ const quality_per_dollar = cost_usd > 0 && outcomes > 0 ? accepted / cost_usd : null;
155
+ // Effective Tokens: the share of tokens that produced accepted work.
156
+ const effective_tokens = acceptance_rate === null ? null : total_tokens * acceptance_rate;
157
+ const effective_cost_usd = acceptance_rate === null ? null : cost_usd * acceptance_rate;
158
+ return {
159
+ key,
160
+ cost_usd,
161
+ total_tokens,
162
+ accepted,
163
+ outcomes,
164
+ acceptance_rate,
165
+ quality_per_dollar,
166
+ effective_tokens,
167
+ effective_cost_usd,
168
+ };
169
+ }
170
+
171
+ function combine(costMap, outMap) {
172
+ const keys = new Set([...costMap.keys(), ...outMap.keys()]);
173
+ const rows = [];
174
+ for (const key of keys) {
175
+ rows.push(combineRow(key, costMap.get(key), outMap.get(key)));
176
+ }
177
+ // Highest quality-per-dollar first; rows without a ratio sink to the bottom.
178
+ rows.sort((a, b) => {
179
+ const av = a.quality_per_dollar;
180
+ const bv = b.quality_per_dollar;
181
+ if (av === null && bv === null) return b.outcomes - a.outcomes;
182
+ if (av === null) return 1;
183
+ if (bv === null) return -1;
184
+ return bv - av;
185
+ });
186
+ return rows;
187
+ }
188
+
189
+ /**
190
+ * Join outcomes to token/$ rows by model + tool, within an optional [from,to]
191
+ * day window. Returns per-model and per-tool quality-per-dollar / ET, plus
192
+ * totals. Pure: no I/O, no mutation of inputs.
193
+ *
194
+ * @param {Array} queueRows already-parsed queue rows ({ source, model, hour_start, …token fields })
195
+ * @param {Array} outcomes sanitized outcome records (from readOutcomesData)
196
+ * @param {{from?:string,to?:string}} [window]
197
+ */
198
+ function computeQualityPerDollar(queueRows, outcomes, { from = "", to = "" } = {}) {
199
+ const modelCost = new Map();
200
+ const toolCost = new Map();
201
+ for (const row of queueRows || []) {
202
+ if (!row || typeof row !== "object") continue; // tolerate a stray null/garbage line
203
+ const day = dayOf(row.hour_start);
204
+ if ((from || to) && !inWindow(day, from, to)) continue;
205
+ const model = (row && row.model) || "unknown";
206
+ const tool = (row && row.source) || "unknown";
207
+ const cost = computeRowCost(row) || 0;
208
+ const tokens = Number((row && row.total_tokens) || 0);
209
+ bumpCost(modelCost, model, cost, tokens);
210
+ bumpCost(toolCost, tool, cost, tokens);
211
+ }
212
+
213
+ const modelOut = new Map();
214
+ const toolOut = new Map();
215
+ for (const o of outcomes || []) {
216
+ const day = dayOf(o && o.timestamp);
217
+ if ((from || to) && !inWindow(day, from, to)) continue;
218
+ bumpOutcome(modelOut, (o && o.model) || "unknown", !!(o && o.accepted));
219
+ bumpOutcome(toolOut, (o && o.tool) || "unknown", !!(o && o.accepted));
220
+ }
221
+
222
+ const by_model = combine(modelCost, modelOut);
223
+ const by_tool = combine(toolCost, toolOut);
224
+
225
+ let totalCost = 0;
226
+ let totalTokens = 0;
227
+ for (const v of modelCost.values()) {
228
+ totalCost += v.cost_usd;
229
+ totalTokens += v.total_tokens;
230
+ }
231
+ let totalAccepted = 0;
232
+ let totalOutcomes = 0;
233
+ for (const v of modelOut.values()) {
234
+ totalAccepted += v.accepted;
235
+ totalOutcomes += v.outcomes;
236
+ }
237
+ const totals = combineRow(
238
+ "__all__",
239
+ { cost_usd: totalCost, total_tokens: totalTokens },
240
+ { accepted: totalAccepted, outcomes: totalOutcomes },
241
+ );
242
+
243
+ return { available: outcomes && outcomes.length > 0, by_model, by_tool, totals };
244
+ }
245
+
246
+ module.exports = {
247
+ resolveOutcomesPath,
248
+ resolveAutoOutcomesPath,
249
+ sanitizeOutcome,
250
+ readOutcomesData,
251
+ readAllOutcomesData,
252
+ computeQualityPerDollar,
253
+ };