@trazum/core 2.7.0 → 2.7.2

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.
@@ -209,6 +222,22 @@ export interface PricingTier {
209
222
  outputPerMTok: number;
210
223
  }
211
224
 
225
+ /**
226
+ * A provider's service tier other than its standard one, as a response names it
227
+ * after normalising: OpenAI's `service_tier` of `"flex"`, `"fast"` or
228
+ * `"priority"` (the same tier, under its name before 2026-07-30), and
229
+ * `"ultrafast"`. See `ModelPricing.serviceTiers`.
230
+ */
231
+ export type ServiceTier = 'flex' | 'fast' | 'ultrafast';
232
+
233
+ /** The rates one service tier charges, with its own conditional bands. */
234
+ export interface ServiceTierRates {
235
+ inputPerMTok: number;
236
+ outputPerMTok: number;
237
+ /** The tier's own long-prompt band, when its table publishes one. */
238
+ tiers?: PricingTier[];
239
+ }
240
+
212
241
  /** One published price this model carried until an instant. See `ModelPricing.history`. */
213
242
  export interface PricePeriod {
214
243
  /** ISO 8601 instant, exclusive: a call at exactly this instant is priced by what came after. */
@@ -344,6 +373,29 @@ export interface ModelPricing {
344
373
  * earliest period stands for it, and the row's note says so.
345
374
  */
346
375
  history?: PricePeriod[];
376
+ /**
377
+ * What the same tokens cost at another of the provider's service tiers.
378
+ *
379
+ * OpenAI sells three besides its standard one, chosen per request with
380
+ * `service_tier` and named again in the response: Flex at about half the
381
+ * price, Fast (called Priority until 2026-07-30) at up to twice, and
382
+ * Ultrafast on two models at six times. Each is a separate table on the
383
+ * pricing page, with its own long-prompt band, and the rates are not one
384
+ * multiple of the standard ones (GPT-4o's Fast is 1.7x, GPT-5.2's 2x), so
385
+ * each is written out per model as the page prints it.
386
+ *
387
+ * Kept apart from `tiers` on purpose. A tier is a condition on the call that
388
+ * may be undecided, so it is never below the base, and Flex is. A service
389
+ * tier is decided by the response that names it, and replaces the base and
390
+ * its tiers whole: Flex on a long prompt is Flex's own long band, never a
391
+ * composite of two tables. The cache and batch ratios stay the row's, which
392
+ * is what the page's own figures show (Flex's cached input is a tenth of
393
+ * Flex's input wherever the standard one is a tenth).
394
+ *
395
+ * A response naming a tier this row has no sheet for is priced at the
396
+ * standard rate: the page publishes nothing else for it.
397
+ */
398
+ serviceTiers?: Partial<Record<ServiceTier, ServiceTierRates>>;
347
399
  /**
348
400
  * Other ids that bill at exactly this rate.
349
401
  *
package/src/usage.ts CHANGED
@@ -176,6 +176,29 @@ 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
+ * The service tier the provider says answered, when the log kept it:
190
+ * OpenAI's top-level `service_tier`, `"flex"`, `"priority"` or `"fast"`,
191
+ * `"ultrafast"`, or `"default"`. Flex bills about half the standard rate
192
+ * and Fast up to twice, from tables of their own (`serviceTiers` in the
193
+ * catalogue). Absent, or `"default"`, is the standard rate.
194
+ */
195
+ serviceTier?: string;
196
+ /**
197
+ * Set when an OpenAI-shaped line split its cache writes by lifetime and the
198
+ * parts did not add up to the total. The lifetime is then unknown even on a
199
+ * model whose unsplit writes are known to be the short kind.
200
+ */
201
+ writeSplitContradicted?: true;
179
202
  }
180
203
 
181
204
  /** What a set of calls cost, split by where the money went. */
@@ -766,6 +789,19 @@ export function parseUsageLine(line: string): UsageRecord | null {
766
789
  typeof detailsRaw === 'object' && detailsRaw !== null ? (detailsRaw as Record<string, unknown>) : null;
767
790
  const openAiCached = details ? readCount(details.cached_tokens) : ({ kind: 'absent' } as Count);
768
791
  const openAiWrite = details ? readCount(details.cache_write_tokens) : ({ kind: 'absent' } as Count);
792
+ /*
793
+ * The same writes split by lifetime, in the Responses API since the
794
+ * 12-hour entry: `ttl_30m_tokens` at 1.25x input and `ttl_12h_tokens` at
795
+ * 2.5x, which "sum to cache_write_tokens" and are "both returned, including
796
+ * when one is zero" (OpenAI's prompt-caching guide). So a write with no
797
+ * split was a 30-minute one: Chat Completions, or a log from before the
798
+ * 12-hour entry existed. Read as one, a 12-hour write cost half its price.
799
+ */
800
+ const openAiSplitRaw = details?.cache_write_tokens_details;
801
+ const openAiSplit =
802
+ typeof openAiSplitRaw === 'object' && openAiSplitRaw !== null ? (openAiSplitRaw as Record<string, unknown>) : null;
803
+ const openAiWrite30m = openAiSplit ? readCount(openAiSplit.ttl_30m_tokens) : ({ kind: 'absent' } as Count);
804
+ const openAiWrite12h = openAiSplit ? readCount(openAiSplit.ttl_12h_tokens) : ({ kind: 'absent' } as Count);
769
805
 
770
806
  /**
771
807
  * Anthropic splits cache writes by time-to-live, and the two cost different
@@ -831,6 +867,8 @@ export function parseUsageLine(line: string): UsageRecord | null {
831
867
  cacheWrite: readCount(usage.cache_creation_input_tokens, usage.cacheWriteTokens),
832
868
  openAiCached,
833
869
  openAiWrite,
870
+ openAiWrite30m,
871
+ openAiWrite12h,
834
872
  geminiCached,
835
873
  geminiThoughts,
836
874
  geminiToolPrompt,
@@ -861,6 +899,12 @@ export function parseUsageLine(line: string): UsageRecord | null {
861
899
  const split5m = valueOf(counts.write5m!);
862
900
  const split1h = valueOf(counts.write1h!);
863
901
  const hasSplit = counts.write5m!.kind === 'ok' || counts.write1h!.kind === 'ok';
902
+ // OpenAI's lifetimes, taken only when they add up to the writes they split.
903
+ const openAiSplitGiven = counts.openAiWrite30m!.kind === 'ok' || counts.openAiWrite12h!.kind === 'ok';
904
+ const openAiSplitAgrees =
905
+ counts.openAiWrite30m!.kind === 'ok' && counts.openAiWrite12h!.kind === 'ok'
906
+ && valueOf(counts.openAiWrite30m!) + valueOf(counts.openAiWrite12h!) === openAiWritten;
907
+ const openAiLong = openAiSplitAgrees ? valueOf(counts.openAiWrite12h!) : 0;
864
908
 
865
909
  return {
866
910
  model,
@@ -871,10 +915,20 @@ export function parseUsageLine(line: string): UsageRecord | null {
871
915
  * `writeTtlKnown` says which, so the report can admit that a rate was assumed
872
916
  * rather than quietly choosing the cheaper one.
873
917
  */
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),
918
+ /*
919
+ * The short and the long write, whatever each provider calls them:
920
+ * Anthropic's 5-minute and 1-hour entries, OpenAI's 30-minute and
921
+ * 12-hour ones. Priced by the model's `cacheWrite5m` and `cacheWrite1h`.
922
+ */
923
+ cacheWrite5mTokens: (hasSplit ? split5m : flatWrite) + openAiWritten - openAiLong,
924
+ cacheWrite1hTokens: (hasSplit ? split1h : 0) + openAiLong,
925
+ /*
926
+ * A split states the lifetime. A `cache_write_tokens` with none does not
927
+ * by itself: Kimi uses the same field and sells two entries at two prices.
928
+ * On OpenAI's own models it does (see above), which `profileUsage` decides
929
+ * by the model, since the line alone cannot say whose API wrote it.
930
+ */
931
+ writeTtlKnown: hasSplit || (flatWrite === 0 && (openAiSplitGiven ? openAiSplitAgrees : openAiWritten === 0)),
878
932
  outputTokens: valueOf(counts.output!) + valueOf(counts.geminiThoughts!),
879
933
  /**
880
934
  * Trimmed and internally normalised: any whitespace run becomes one space.
@@ -914,6 +968,22 @@ export function parseUsageLine(line: string): UsageRecord | null {
914
968
  return reason === 'max_tokens' || reason === 'length' || reason === 'MAX_TOKENS';
915
969
  })(),
916
970
  ...requestsOf(record.requests),
971
+ /*
972
+ * Anthropic's `usage.speed`, "fast" or "standard": fast mode bills the
973
+ * same tokens at a multiple of the standard rates, so a log that kept the
974
+ * field is priced by it. Absent stays absent, which prices as standard.
975
+ */
976
+ ...(typeof usage.speed === 'string' && usage.speed !== '' ? { speed: usage.speed } : {}),
977
+ /*
978
+ * OpenAI's `service_tier`, which a Chat Completions or Responses object
979
+ * carries at the top level beside `usage`, and names the tier that
980
+ * actually ran: a Fast request downgraded under load says "default" and
981
+ * is billed at the standard rate. Priced from that tier's own table.
982
+ */
983
+ ...(typeof record.service_tier === 'string' && record.service_tier !== ''
984
+ ? { serviceTier: record.service_tier }
985
+ : {}),
986
+ ...(openAiSplitGiven && !openAiSplitAgrees ? { writeSplitContradicted: true as const } : {}),
917
987
  };
918
988
  }
919
989
 
@@ -1223,7 +1293,14 @@ export function profileUsage(text: string, options: UsageProfileOptions): UsageP
1223
1293
  if (
1224
1294
  priced !== undefined
1225
1295
  && (cacheTtlOf(priced).longerMs === null
1226
- || multipliersFor(priced).cacheWrite1h === multipliersFor(priced).cacheWrite5m)
1296
+ || multipliersFor(priced).cacheWrite1h === multipliersFor(priced).cacheWrite5m
1297
+ /*
1298
+ * OpenAI returns the 30-minute and 12-hour split whenever a 12-hour
1299
+ * write is possible, "both fields ... including when one is zero",
1300
+ * so on its models an unsplit write is the 30-minute kind. The
1301
+ * guide's rule, not a guess; Kimi's same field gets no such rule.
1302
+ */
1303
+ || (priced.provider === 'openai' && !record.writeSplitContradicted))
1227
1304
  ) {
1228
1305
  record = { ...record, writeTtlKnown: true };
1229
1306
  }