@trazum/core 2.7.0 → 2.7.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.
@@ -0,0 +1,66 @@
1
+ /**
2
+ * A usage-log line with its long strings set aside, for files too large to
3
+ * hold whole.
4
+ *
5
+ * JavaScript cannot hold a string much past 512 MiB, and an agent session can
6
+ * outgrow that: Claude Code writes every tool result into its transcript, so a
7
+ * long session that read large files or ran chatty commands reaches hundreds
8
+ * of megabytes. Reading such a file whole failed with "Invalid string length"
9
+ * and took the rest of the bill down with it.
10
+ *
11
+ * What a converter needs from a line is short: a type, a model id, a request
12
+ * or message id, a timestamp, a session id, a working directory and the token
13
+ * counts. What makes a line long is content: prompts, replies, thinking, tool
14
+ * arguments and tool results, none of which is ever billed by its length here
15
+ * (the counts are the provider's own). So a long line is parsed, every string
16
+ * longer than {@link SLIM_STRING_CHARS} is replaced by a marker that says how
17
+ * long it was, and the line is written back. Numbers, booleans, keys and short
18
+ * strings are untouched, so every converter reads the same fields it would
19
+ * have read from the whole line.
20
+ *
21
+ * **A line that is not JSON is returned unchanged.** A CSV row with a long
22
+ * quoted field is still a row; rewriting what could not be parsed would
23
+ * corrupt it rather than shorten it.
24
+ */
25
+
26
+ /**
27
+ * Strings longer than this are content. PATH_MAX on Linux is 4096, so even
28
+ * the longest working directory a label rule could match survives.
29
+ */
30
+ export const SLIM_STRING_CHARS = 4096;
31
+
32
+ const marker = (length: number): string => `[trazum: ${length} characters not read]`;
33
+
34
+ const slim = (value: unknown, changed: { yes: boolean }): unknown => {
35
+ if (typeof value === 'string') {
36
+ if (value.length <= SLIM_STRING_CHARS) return value;
37
+ changed.yes = true;
38
+ return marker(value.length);
39
+ }
40
+ if (Array.isArray(value)) return value.map((item) => slim(item, changed));
41
+ if (typeof value === 'object' && value !== null) {
42
+ const out: Record<string, unknown> = {};
43
+ for (const [key, item] of Object.entries(value)) out[key] = slim(item, changed);
44
+ return out;
45
+ }
46
+ return value;
47
+ };
48
+
49
+ /**
50
+ * The line with its content strings shortened, or the line itself when it is
51
+ * short, is not JSON, or holds no string long enough to shorten. A line no
52
+ * longer than {@link SLIM_STRING_CHARS} cannot hold such a string, so it is
53
+ * returned without being parsed.
54
+ */
55
+ export function slimUsageLine(line: string): string {
56
+ if (line.length <= SLIM_STRING_CHARS) return line;
57
+ let parsed: unknown;
58
+ try {
59
+ parsed = JSON.parse(line);
60
+ } catch {
61
+ return line;
62
+ }
63
+ const changed = { yes: false };
64
+ const slimmed = slim(parsed, changed);
65
+ return changed.yes ? JSON.stringify(slimmed) : line;
66
+ }
package/src/types.ts CHANGED
@@ -183,7 +183,20 @@ export type TierCondition =
183
183
  * is `[1, 2, 3]` and not `[1, 4]`: an endpoint convention is the kind of
184
184
  * thing two readers disagree about silently.
185
185
  */
186
- | { kind: 'utc-hours'; hours: number[]; weekdaysOnly: boolean };
186
+ | { kind: 'utc-hours'; hours: number[]; weekdaysOnly: boolean }
187
+ /**
188
+ * The call ran at `speed`, as the response's own `usage.speed` records it.
189
+ *
190
+ * Anthropic's fast mode is an opt-in (`speed: "fast"` on the request) billed
191
+ * at a multiple of the standard rates, and the response says which speed ran,
192
+ * `"fast"` or `"standard"`. **Absent means standard and is decided**, unlike a
193
+ * size tier with no token count: fast mode is never on by default, a request
194
+ * for it that cannot run is refused rather than run slowly, and every response
195
+ * names its speed, so a log without the field is one that never asked. Pricing
196
+ * an unrecorded speed at the dearer rate would double every call of a model
197
+ * for the many logs that predate the field.
198
+ */
199
+ | { kind: 'speed'; speed: 'fast' };
187
200
 
188
201
  /**
189
202
  * A rate that applies when its condition holds.
package/src/usage.ts CHANGED
@@ -176,6 +176,21 @@ export interface UsageRecord {
176
176
  * something of its own should not lose its records to it.
177
177
  */
178
178
  requests?: number | null;
179
+ /**
180
+ * The speed the provider says the call ran at, when the log kept it:
181
+ * Anthropic's `usage.speed`, `"fast"` or `"standard"`. Fast mode bills the
182
+ * same tokens at a multiple of the standard rates (`kind: 'speed'` tiers in
183
+ * the catalogue). Absent on every log that does not record it, and then the
184
+ * call is priced at the standard rate, because fast mode is an explicit
185
+ * opt-in that every response names.
186
+ */
187
+ speed?: string;
188
+ /**
189
+ * Set when an OpenAI-shaped line split its cache writes by lifetime and the
190
+ * parts did not add up to the total. The lifetime is then unknown even on a
191
+ * model whose unsplit writes are known to be the short kind.
192
+ */
193
+ writeSplitContradicted?: true;
179
194
  }
180
195
 
181
196
  /** What a set of calls cost, split by where the money went. */
@@ -766,6 +781,19 @@ export function parseUsageLine(line: string): UsageRecord | null {
766
781
  typeof detailsRaw === 'object' && detailsRaw !== null ? (detailsRaw as Record<string, unknown>) : null;
767
782
  const openAiCached = details ? readCount(details.cached_tokens) : ({ kind: 'absent' } as Count);
768
783
  const openAiWrite = details ? readCount(details.cache_write_tokens) : ({ kind: 'absent' } as Count);
784
+ /*
785
+ * The same writes split by lifetime, in the Responses API since the
786
+ * 12-hour entry: `ttl_30m_tokens` at 1.25x input and `ttl_12h_tokens` at
787
+ * 2.5x, which "sum to cache_write_tokens" and are "both returned, including
788
+ * when one is zero" (OpenAI's prompt-caching guide). So a write with no
789
+ * split was a 30-minute one: Chat Completions, or a log from before the
790
+ * 12-hour entry existed. Read as one, a 12-hour write cost half its price.
791
+ */
792
+ const openAiSplitRaw = details?.cache_write_tokens_details;
793
+ const openAiSplit =
794
+ typeof openAiSplitRaw === 'object' && openAiSplitRaw !== null ? (openAiSplitRaw as Record<string, unknown>) : null;
795
+ const openAiWrite30m = openAiSplit ? readCount(openAiSplit.ttl_30m_tokens) : ({ kind: 'absent' } as Count);
796
+ const openAiWrite12h = openAiSplit ? readCount(openAiSplit.ttl_12h_tokens) : ({ kind: 'absent' } as Count);
769
797
 
770
798
  /**
771
799
  * Anthropic splits cache writes by time-to-live, and the two cost different
@@ -831,6 +859,8 @@ export function parseUsageLine(line: string): UsageRecord | null {
831
859
  cacheWrite: readCount(usage.cache_creation_input_tokens, usage.cacheWriteTokens),
832
860
  openAiCached,
833
861
  openAiWrite,
862
+ openAiWrite30m,
863
+ openAiWrite12h,
834
864
  geminiCached,
835
865
  geminiThoughts,
836
866
  geminiToolPrompt,
@@ -861,6 +891,12 @@ export function parseUsageLine(line: string): UsageRecord | null {
861
891
  const split5m = valueOf(counts.write5m!);
862
892
  const split1h = valueOf(counts.write1h!);
863
893
  const hasSplit = counts.write5m!.kind === 'ok' || counts.write1h!.kind === 'ok';
894
+ // OpenAI's lifetimes, taken only when they add up to the writes they split.
895
+ const openAiSplitGiven = counts.openAiWrite30m!.kind === 'ok' || counts.openAiWrite12h!.kind === 'ok';
896
+ const openAiSplitAgrees =
897
+ counts.openAiWrite30m!.kind === 'ok' && counts.openAiWrite12h!.kind === 'ok'
898
+ && valueOf(counts.openAiWrite30m!) + valueOf(counts.openAiWrite12h!) === openAiWritten;
899
+ const openAiLong = openAiSplitAgrees ? valueOf(counts.openAiWrite12h!) : 0;
864
900
 
865
901
  return {
866
902
  model,
@@ -871,10 +907,20 @@ export function parseUsageLine(line: string): UsageRecord | null {
871
907
  * `writeTtlKnown` says which, so the report can admit that a rate was assumed
872
908
  * rather than quietly choosing the cheaper one.
873
909
  */
874
- cacheWrite5mTokens: (hasSplit ? split5m : flatWrite) + openAiWritten,
875
- cacheWrite1hTokens: hasSplit ? split1h : 0,
876
- // `cache_write_tokens` names no TTL either; see the note in `profileUsage`.
877
- writeTtlKnown: hasSplit || (flatWrite === 0 && openAiWritten === 0),
910
+ /*
911
+ * The short and the long write, whatever each provider calls them:
912
+ * Anthropic's 5-minute and 1-hour entries, OpenAI's 30-minute and
913
+ * 12-hour ones. Priced by the model's `cacheWrite5m` and `cacheWrite1h`.
914
+ */
915
+ cacheWrite5mTokens: (hasSplit ? split5m : flatWrite) + openAiWritten - openAiLong,
916
+ cacheWrite1hTokens: (hasSplit ? split1h : 0) + openAiLong,
917
+ /*
918
+ * A split states the lifetime. A `cache_write_tokens` with none does not
919
+ * by itself: Kimi uses the same field and sells two entries at two prices.
920
+ * On OpenAI's own models it does (see above), which `profileUsage` decides
921
+ * by the model, since the line alone cannot say whose API wrote it.
922
+ */
923
+ writeTtlKnown: hasSplit || (flatWrite === 0 && (openAiSplitGiven ? openAiSplitAgrees : openAiWritten === 0)),
878
924
  outputTokens: valueOf(counts.output!) + valueOf(counts.geminiThoughts!),
879
925
  /**
880
926
  * Trimmed and internally normalised: any whitespace run becomes one space.
@@ -914,6 +960,13 @@ export function parseUsageLine(line: string): UsageRecord | null {
914
960
  return reason === 'max_tokens' || reason === 'length' || reason === 'MAX_TOKENS';
915
961
  })(),
916
962
  ...requestsOf(record.requests),
963
+ /*
964
+ * Anthropic's `usage.speed`, "fast" or "standard": fast mode bills the
965
+ * same tokens at a multiple of the standard rates, so a log that kept the
966
+ * field is priced by it. Absent stays absent, which prices as standard.
967
+ */
968
+ ...(typeof usage.speed === 'string' && usage.speed !== '' ? { speed: usage.speed } : {}),
969
+ ...(openAiSplitGiven && !openAiSplitAgrees ? { writeSplitContradicted: true as const } : {}),
917
970
  };
918
971
  }
919
972
 
@@ -1223,7 +1276,14 @@ export function profileUsage(text: string, options: UsageProfileOptions): UsageP
1223
1276
  if (
1224
1277
  priced !== undefined
1225
1278
  && (cacheTtlOf(priced).longerMs === null
1226
- || multipliersFor(priced).cacheWrite1h === multipliersFor(priced).cacheWrite5m)
1279
+ || multipliersFor(priced).cacheWrite1h === multipliersFor(priced).cacheWrite5m
1280
+ /*
1281
+ * OpenAI returns the 30-minute and 12-hour split whenever a 12-hour
1282
+ * write is possible, "both fields ... including when one is zero",
1283
+ * so on its models an unsplit write is the 30-minute kind. The
1284
+ * guide's rule, not a guess; Kimi's same field gets no such rule.
1285
+ */
1286
+ || (priced.provider === 'openai' && !record.writeSplitContradicted))
1227
1287
  ) {
1228
1288
  record = { ...record, writeTtlKnown: true };
1229
1289
  }