@trazum/core 2.7.6 → 2.7.8

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.
@@ -0,0 +1,145 @@
1
+ /**
2
+ * The shapes a usage file arrives in, told apart from the file's own text.
3
+ *
4
+ * The CLI's `bill` and the web app's Bill tab are the same door, and they
5
+ * used to keep their own copies of this: which shapes exist, and which
6
+ * command explains a shape's left-out rows. Both copies built that command
7
+ * as `from-${shape}`, and both sent people to `trazum from-anthropic-usage`,
8
+ * which answers "Unknown command". One copy here, so a shape added next year
9
+ * is named the same way in both places.
10
+ */
11
+
12
+ import { looksLikeAnthropicCost } from './anthropic-cost.js';
13
+ import { looksLikeAnthropicUsage } from './anthropic-usage.js';
14
+ import { looksLikeBatchResults } from './batch-results.js';
15
+ import { looksLikeClaudeCodeTranscript } from './claude-code.js';
16
+ import { looksLikeCodexTranscript } from './codex.js';
17
+ import { looksLikeGeminiCliSession } from './gemini-cli.js';
18
+ import { looksLikeHelicone } from './helicone.js';
19
+ import { looksLikeLangsmith } from './langsmith.js';
20
+ import { looksLikeLiteLlm } from './litellm.js';
21
+ import { looksLikeOpenaiCost } from './openai-cost.js';
22
+ import { looksLikeOpenaiUsage } from './openai-usage.js';
23
+ import { looksLikeOpenrouterActivity } from './openrouter-activity.js';
24
+ import { looksLikeOtel } from './otel.js';
25
+ import { parseUsageLine } from './usage.js';
26
+
27
+ /** The shapes `bill` can tell apart from a file's own text. */
28
+ export type UsageShape =
29
+ | 'claude-code'
30
+ | 'codex'
31
+ | 'gemini-cli'
32
+ | 'otel'
33
+ | 'litellm'
34
+ | 'helicone'
35
+ | 'langsmith'
36
+ | 'anthropic-usage'
37
+ | 'openai-usage'
38
+ | 'batch-results'
39
+ | 'openrouter'
40
+ | 'usage-log';
41
+
42
+ /**
43
+ * The CLI command that converts each shape on its own, and so says why rows
44
+ * were left out. Null where none exists: batch results only `bill` reads, and
45
+ * a usage log needs no converting. A pointer to a command that does not exist
46
+ * is worse than none, so the CLI's tests run every one of these.
47
+ */
48
+ export const SHAPE_COMMAND: Readonly<Record<UsageShape, string | null>> = {
49
+ 'claude-code': 'from-claude-code',
50
+ codex: 'from-codex',
51
+ 'gemini-cli': 'from-gemini-cli',
52
+ otel: 'from-otel',
53
+ litellm: 'from-litellm',
54
+ helicone: 'from-helicone',
55
+ langsmith: 'from-langsmith',
56
+ 'anthropic-usage': 'from-anthropic',
57
+ 'openai-usage': 'from-openai',
58
+ 'batch-results': null,
59
+ openrouter: 'from-openrouter',
60
+ 'usage-log': null,
61
+ };
62
+
63
+ /**
64
+ * The first line with anything on it, found without splitting a file that
65
+ * may be hundreds of megabytes into an array of every line.
66
+ */
67
+ export function firstLineOf(text: string): string | undefined {
68
+ let start = 0;
69
+ while (start < text.length) {
70
+ const newline = text.indexOf('\n', start);
71
+ const end = newline === -1 ? text.length : newline;
72
+ const line = text.slice(start, end);
73
+ if (line.trim() !== '') return line;
74
+ start = end + 1;
75
+ }
76
+ return undefined;
77
+ }
78
+
79
+ /**
80
+ * Which shapes claim a text. Every detector is asked, not the first that
81
+ * says yes: a file two shapes claim is a file nobody should convert, because
82
+ * whichever one was picked would be a guess wearing a result's clothes.
83
+ *
84
+ * A plain usage log has no signature but its own lines, so it is claimed
85
+ * only when nothing else is and its first line parses as a usage line.
86
+ */
87
+ export function usageShapesOf(text: string): UsageShape[] {
88
+ const claims: UsageShape[] = [];
89
+ if (looksLikeCodexTranscript(text)) claims.push('codex');
90
+ if (looksLikeGeminiCliSession(text)) claims.push('gemini-cli');
91
+ if (looksLikeClaudeCodeTranscript(text)) claims.push('claude-code');
92
+ if (looksLikeOtel(text)) claims.push('otel');
93
+ if (looksLikeAnthropicUsage(text)) claims.push('anthropic-usage');
94
+ if (looksLikeOpenaiUsage(text)) claims.push('openai-usage');
95
+ if (looksLikeBatchResults(text)) claims.push('batch-results');
96
+ if (looksLikeOpenrouterActivity(text)) claims.push('openrouter');
97
+ if (looksLikeHelicone(text)) claims.push('helicone');
98
+ if (looksLikeLangsmith(text)) claims.push('langsmith');
99
+ if (looksLikeLiteLlm(text)) claims.push('litellm');
100
+ if (claims.length > 0) return claims;
101
+ const first = firstLineOf(text);
102
+ if (first !== undefined && parseUsageLine(first) !== null) claims.push('usage-log');
103
+ return claims;
104
+ }
105
+
106
+ /** The coding agents whose sessions convert to a usage log. */
107
+ export const AGENT_SHAPES: readonly UsageShape[] = ['claude-code', 'codex', 'gemini-cli'];
108
+
109
+ /**
110
+ * Why a text handed to something that reads a usage log is not one.
111
+ *
112
+ * - `shape`: one shape claims it; `command` is the CLI converter, or null.
113
+ * - `ambiguous`: more than one claims it, so nobody should convert it.
114
+ * - `cost-report`: a provider's bill, which is not usage at all.
115
+ */
116
+ export type NotAUsageLog =
117
+ | { kind: 'shape'; shape: Exclude<UsageShape, 'usage-log'>; command: string | null }
118
+ | { kind: 'ambiguous'; shapes: UsageShape[] }
119
+ | { kind: 'cost-report' };
120
+
121
+ /**
122
+ * Whether a text meant as a usage log is something else, and what.
123
+ *
124
+ * Every door that reads one usage log (the CLI's `profile` and its kin, the
125
+ * MCP server's tools, the local HTTP API) read a Claude Code session as a
126
+ * log whose every line was unreadable, and answered "no usage records". That
127
+ * reads as a broken file. This names what the text is, so each door can
128
+ * point at what reads it, in its own words.
129
+ *
130
+ * Null when the first line with anything on it is a usage line, so a usage
131
+ * log pays one parsed line for the question, and null when nothing claims
132
+ * the text, whose unreadable lines are then counted where they always were.
133
+ */
134
+ export function notAUsageLog(text: string): NotAUsageLog | null {
135
+ const first = firstLineOf(text);
136
+ if (first === undefined || parseUsageLine(first) !== null) return null;
137
+ const claims = usageShapesOf(text).filter(
138
+ (shape): shape is Exclude<UsageShape, 'usage-log'> => shape !== 'usage-log',
139
+ );
140
+ const [only] = claims;
141
+ if (claims.length === 1 && only !== undefined) return { kind: 'shape', shape: only, command: SHAPE_COMMAND[only] };
142
+ if (claims.length > 1) return { kind: 'ambiguous', shapes: claims };
143
+ if (looksLikeAnthropicCost(text) || looksLikeOpenaiCost(text)) return { kind: 'cost-report' };
144
+ return null;
145
+ }
package/src/usage.ts CHANGED
@@ -139,6 +139,19 @@ export interface UsageRecord {
139
139
  * carries no content, and nothing identifying comes back out of it either.
140
140
  */
141
141
  session: string | null;
142
+ /**
143
+ * A conversation inside the session, when the session ran more than one: a
144
+ * Claude Code subagent, which shares its session's id and keeps a context of
145
+ * its own. Read from `thread`.
146
+ *
147
+ * The findings that follow a conversation turn by turn (how its input grows,
148
+ * whether a turn repeats or retries the last, whether the cache TTL fits the
149
+ * gaps, a write never read back) group by session **and** thread, because a
150
+ * subagent's turns are not the main thread's. What a session costs, and the
151
+ * per-session budget, stay by session: a session costs its subagents too.
152
+ * Like the session key, it is grouped by and never shown.
153
+ */
154
+ thread?: string;
142
155
  /**
143
156
  * When the call happened, as epoch milliseconds, or `null` when the log does
144
157
  * not say.
@@ -1014,6 +1027,7 @@ export function parseUsageLine(line: string): UsageRecord | null {
1014
1027
  * nobody sets measures nothing.
1015
1028
  */
1016
1029
  session: nameOf(record.session) ?? nameOf(record.conversation_id),
1030
+ ...(nameOf(record.thread) === null ? {} : { thread: nameOf(record.thread)! }),
1017
1031
  /**
1018
1032
  * Read from either spelling, for the same reason `session` is: `outcome`
1019
1033
  * in a log somebody wrote for this, `trazum_outcome` in one where a
@@ -1444,13 +1458,22 @@ export function profileUsage(text: string, options: UsageProfileOptions): UsageP
1444
1458
  spanTo = Math.max(spanTo, record.ts);
1445
1459
  spanCalls += 1;
1446
1460
  }
1447
- conversations.add(record);
1461
+ /*
1462
+ A conversation is a session's thread. Every finding that reads one turn
1463
+ after the last reads it per thread; what a session costs stays the
1464
+ whole session's, its subagents included.
1465
+ */
1466
+ const conversation =
1467
+ record.thread === undefined || record.session === null
1468
+ ? record
1469
+ : { ...record, session: `${record.session}\u0000${record.thread}` };
1470
+ conversations.add(conversation);
1448
1471
  output.add(record);
1449
1472
  input.add(record);
1450
- repeats.add(record);
1451
- truncRetries.add(record);
1452
- ttlFit.add(record);
1453
- ledger.add(record);
1473
+ repeats.add(conversation);
1474
+ truncRetries.add(conversation);
1475
+ ttlFit.add(conversation);
1476
+ ledger.add(conversation);
1454
1477
  sessionCosts.add(record);
1455
1478
 
1456
1479
  const usdBefore = total.totalUsd;