@trazum/core 2.7.7 → 2.7.9

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.
package/src/pricing.ts CHANGED
@@ -47,8 +47,15 @@ export const PROVIDER_REVIEWED: Readonly<Record<string, string>> = Object.freeze
47
47
  * are gone, and the context-windows page gives each the 200k window every
48
48
  * Claude model outside its 1M list has. Claude Sonnet 3.7 and Haiku 3 are
49
49
  * retired and absent from the pricing page, so they stay unpriced.
50
+ *
51
+ * Re-read 2026-11-16 (pricing, the models overview, deprecations,
52
+ * prompt-caching, fast-mode and the Fable and Mythos model pages), after
53
+ * `scripts/price-drift.mjs` failed the weekly run of 2026-11-09. Every
54
+ * existing price matched. New: Claude Fable 5.2 and Claude Mythos 5.2,
55
+ * released 2026-11-09 at $8/$40 with fast mode at $16/$80, both unpriced
56
+ * for a week. Fable 5.1's page now opens "Legacy"; its prices are the same.
50
57
  */
51
- anthropic: '2026-11-05',
58
+ anthropic: '2026-11-16',
52
59
  /*
53
60
  * developers.openai.com/api/docs/pricing, read 2026-08-31.
54
61
  *
@@ -77,8 +84,21 @@ export const PROVIDER_REVIEWED: Readonly<Record<string, string>> = Object.freeze
77
84
  * priced as one, at half its cost; and sixteen earlier models that are still
78
85
  * billed and still in logs (GPT-5.5, 5.4, 5.2, 5.1 and their mini, nano and
79
86
  * pro siblings, GPT-5 pro, GPT-4.1, GPT-4o and o3), none of which was priced.
87
+ *
88
+ * Re-read 2026-11-16: pricing.md and the model pages of every row, after
89
+ * the same weekly run. Every existing price matched, and no row was added.
90
+ * What changed is the "Specialized models" table, which now prints a model
91
+ * priced by prompt length as two rows, "(short context)" and "(long
92
+ * context)", so `price-drift.mjs` read `gpt-5.6-cyber` as gone and nine
93
+ * rows as new. Six ids are on the page and unpriced on purpose, each with
94
+ * its reason in `DELIBERATELY_UNPRICED`: five have no model page, so no
95
+ * context window (`gpt-5.5-cyber-preview`, `gpt-6-rosalind`, the two
96
+ * `gpt-rosalind` models, `gpt-6-astra-law`), and `gpt-6-cyber` has one, but
97
+ * no published cache-write price over 272K input tokens. The long-context
98
+ * cache writes the page prints for every other model were compared for the
99
+ * first time, and each is the long input rate times the row's multiplier.
80
100
  */
81
- openai: '2026-11-05',
101
+ openai: '2026-11-16',
82
102
  /*
83
103
  * ai.google.dev/gemini-api/docs/pricing, docs/caching and the model pages,
84
104
  * read 2026-10-10. Every price matched; what changed is how caching starts
@@ -297,6 +317,12 @@ const OPENAI_EARLIER_LONG_NOTE =
297
317
  const OPENAI_EARLIER_NO_CACHE_NOTE = 'OpenAI publishes no cached-input price for this model, so caching is not priced.';
298
318
  const OPENAI_DEPRECATED_SUFFIX = ' Deprecated by OpenAI: priced for the logs that hold it, never recommended.';
299
319
  const OPENAI_SHUT_DOWN_SUFFIX = ' Shut down by OpenAI: priced for the logs that hold it, never recommended.';
320
+ /** What the three Gemini 4 rows share, from Google's pricing page and docs/caching, read 2026-11-16. */
321
+ const GEMINI_4_NOTE =
322
+ 'Implicit caching is automatic above 4,096 tokens and is the only kind: Google does not support explicit caching'
323
+ + ' on Gemini 4. In a multi-turn conversation the previous request is cached only when the new one adds at least'
324
+ + ' 2,050 tokens. Google also sells a Flex tier at half this price and a Priority tier at 1.8 times it; a call on'
325
+ + ' either is priced here at the standard rate.';
300
326
  const OPENAI_CODEX_NOTE =
301
327
  'Caching is automatic; a write costs what input costs. Responses API only, and no batch. OpenAI says the minimum for'
302
328
  + ' models before GPT-5.6 varies by request settings, so 1,024 here is the nearest published floor.';
@@ -343,6 +369,70 @@ const US_ONLY_INFERENCE = Object.freeze({ us: 1.1 });
343
369
  const ANTHROPIC_WEB_SEARCH_USD_PER_1K = 10;
344
370
 
345
371
  export const MODELS: ModelPricing[] = [
372
+ {
373
+ /*
374
+ * platform.claude.com/docs/en/about-claude/pricing and the Fable 5.2 model
375
+ * page (models/fable-5-2/overview), read 2026-11-16: "Latest. Released
376
+ * November 9, 2026". Cheaper than Fable 5.1 at both ends, $8/$40. The
377
+ * cache read is $0.20, the same 0.025x ("priced at 0.025x the base input
378
+ * price"); writes are $10 and $16, 1.25x and 2x; the Batch API table has
379
+ * $4/$20. A 1M context window, and the prompt-caching page lists it among
380
+ * the models with a 512-token minimum.
381
+ *
382
+ * Found by `scripts/price-drift.mjs` on the weekly run of 2026-11-09, the
383
+ * day it was released, as a model on the pricing page that read as
384
+ * unpriced. That included this repository's own Claude Code sessions.
385
+ */
386
+ id: 'claude-fable-5-2',
387
+ provider: 'anthropic',
388
+ webSearchPerThousandUsd: ANTHROPIC_WEB_SEARCH_USD_PER_1K,
389
+ inferenceGeoMultipliers: US_ONLY_INFERENCE,
390
+ displayName: 'Claude Fable 5.2',
391
+ inputPerMTok: 8,
392
+ outputPerMTok: 40,
393
+ contextWindow: 1_000_000,
394
+ cacheMinTokens: 512,
395
+ multipliers: { cacheRead: 0.025, cacheWrite5m: 1.25, cacheWrite1h: 2, batch: 0.5 },
396
+ /*
397
+ * Fast mode, read 2026-11-16 from the pricing page's "Fast mode pricing"
398
+ * table and build-with-claude/fast-mode: $16/$80, "a multiplier on
399
+ * standard rates across the full context window", with the caching
400
+ * multipliers "on top". The response's `usage.speed` says which speed ran.
401
+ */
402
+ tiers: [{ id: 'fast', when: { kind: 'speed', speed: 'fast' }, inputPerMTok: 16, outputPerMTok: 80 }],
403
+ capability: 'frontier',
404
+ tier: 'frontier',
405
+ notes: 'Cache hits cost 2.5% of the input price ($0.20). Fast mode (usage.speed "fast") bills $16/$80.'
406
+ + ' Requires 30-day data retention.',
407
+ },
408
+ {
409
+ /*
410
+ * The same pages, read 2026-11-16. Its own page (models/mythos-5-2/
411
+ * overview): "the same model as Claude Fable 5.2, available only to
412
+ * organizations verified through Anthropic's verification programs", with
413
+ * "the same specifications and pricing". The pricing page prints its row
414
+ * beside Fable 5.2's in the model, batch and fast-mode tables, each figure
415
+ * the same. Priced for the logs that carry it and never offered as
416
+ * somebody's cheaper alternative.
417
+ */
418
+ id: 'claude-mythos-5-2',
419
+ provider: 'anthropic',
420
+ webSearchPerThousandUsd: ANTHROPIC_WEB_SEARCH_USD_PER_1K,
421
+ inferenceGeoMultipliers: US_ONLY_INFERENCE,
422
+ displayName: 'Claude Mythos 5.2',
423
+ recommendable: false,
424
+ inputPerMTok: 8,
425
+ outputPerMTok: 40,
426
+ contextWindow: 1_000_000,
427
+ cacheMinTokens: 512,
428
+ multipliers: { cacheRead: 0.025, cacheWrite5m: 1.25, cacheWrite1h: 2, batch: 0.5 },
429
+ tiers: [{ id: 'fast', when: { kind: 'speed', speed: 'fast' }, inputPerMTok: 16, outputPerMTok: 80 }],
430
+ capability: 'frontier',
431
+ tier: 'frontier',
432
+ notes:
433
+ 'Available only to organizations verified through Anthropic\'s verification programs.'
434
+ + ' Fast mode (usage.speed "fast") bills $16/$80. Requires 30-day data retention.',
435
+ },
346
436
  {
347
437
  /*
348
438
  * platform.claude.com/docs/en/about-claude/pricing and the Fable 5.1 model
@@ -350,6 +440,10 @@ export const MODELS: ModelPricing[] = [
350
440
  * cache read, $0.25 against $10 of input, a quarter of the 0.1x every
351
441
  * earlier Claude model pays. Writes stay at 1.25x and 2x ($12.50, $20),
352
442
  * and the Batch API halves both sides ($5/$25).
443
+ *
444
+ * Its page, re-read 2026-11-16, opens "Legacy. Released September 1,
445
+ * 2026" and says "Claude Fable 5.2 is the current Fable model". Still
446
+ * served ("Active (legacy)") at the same prices.
353
447
  */
354
448
  id: 'claude-fable-5-1',
355
449
  provider: 'anthropic',
@@ -363,7 +457,8 @@ export const MODELS: ModelPricing[] = [
363
457
  multipliers: { cacheRead: 0.025, cacheWrite5m: 1.25, cacheWrite1h: 2, batch: 0.5 },
364
458
  capability: 'frontier',
365
459
  tier: 'frontier',
366
- notes: 'Cache hits cost 2.5% of the input price ($0.25). Requires 30-day data retention.',
460
+ notes: 'Legacy: superseded by Claude Fable 5.2, which costs less ($8/$40). Cache hits cost 2.5% of the input'
461
+ + ' price ($0.25). Requires 30-day data retention.',
367
462
  },
368
463
  {
369
464
  /*
@@ -1681,13 +1776,18 @@ export const MODELS: ModelPricing[] = [
1681
1776
  * which is exactly what `promo` is for and is the shape the catalogue nearly
1682
1777
  * shipped Sonnet 5 wrong on: on 2027-01-01 every figure here doubles with no
1683
1778
  * code change, and `pricing-review.test.js` fails before that arrives.
1779
+ *
1780
+ * It failed on 2026-11-16, 45 days before the end, and the page was read
1781
+ * again that day: "$0.75 through December 31, 2026. $1.50 starting January
1782
+ * 1, 2027", "$3.75 ... $7.50" for output and "$0.075 ... $0.15" for the
1783
+ * cache, word for word what it said in October. The rise stands.
1684
1784
  */
1685
1785
  id: 'gemini-3.6-flash',
1686
1786
  provider: 'google',
1687
1787
  displayName: 'Gemini 3.6 Flash',
1688
1788
  inputPerMTok: 1.5,
1689
1789
  outputPerMTok: 7.5,
1690
- promo: { inputPerMTok: 0.75, outputPerMTok: 3.75, until: '2026-12-31' },
1790
+ promo: { inputPerMTok: 0.75, outputPerMTok: 3.75, until: '2026-12-31', confirmedOn: '2026-11-16' },
1691
1791
  contextWindow: 1_048_576,
1692
1792
  cacheMinTokens: 4096,
1693
1793
  caching: 'automatic',
@@ -1710,14 +1810,16 @@ export const MODELS: ModelPricing[] = [
1710
1810
  * page and docs/caching, read 2026-10-10. The same rates and the same
1711
1811
  * introductory window as 3.6 Flash, published as one table each: $0.75
1712
1812
  * and $3.75 through 2026-12-31, $1.50 and $7.50 from 2027-01-01, and the
1713
- * cache price scales with them ($0.075, then $0.15).
1813
+ * cache price scales with them ($0.075, then $0.15). Read again on
1814
+ * 2026-11-16, inside the promotion's last 45 days: the same six figures
1815
+ * and the same two dates.
1714
1816
  */
1715
1817
  id: 'gemini-3.8-flash',
1716
1818
  provider: 'google',
1717
1819
  displayName: 'Gemini 3.8 Flash',
1718
1820
  inputPerMTok: 1.5,
1719
1821
  outputPerMTok: 7.5,
1720
- promo: { inputPerMTok: 0.75, outputPerMTok: 3.75, until: '2026-12-31' },
1822
+ promo: { inputPerMTok: 0.75, outputPerMTok: 3.75, until: '2026-12-31', confirmedOn: '2026-11-16' },
1721
1823
  contextWindow: 1_048_576,
1722
1824
  cacheMinTokens: 4096,
1723
1825
  caching: 'automatic',
@@ -1767,6 +1869,105 @@ export const MODELS: ModelPricing[] = [
1767
1869
  + ' Implicit caching is automatic above 4,096 tokens; explicit caching is also billed for storage,'
1768
1870
  + ' $4.50 per 1M tokens per hour.',
1769
1871
  },
1872
+ /*
1873
+ * The Gemini 4 family, from ai.google.dev/gemini-api/docs/pricing, the three
1874
+ * model pages and docs/caching, read 2026-11-16.
1875
+ *
1876
+ * Carbon ("our most capable reasoning model") and Argon ("our efficient
1877
+ * Gemini 4 frontier reasoning model") carry one table: "$2.00 through
1878
+ * November 30, 2026. $4.00 starting December 1, 2026" in, "$10.00 ...
1879
+ * $20.00" out, and the cache at "$0.10 ... $0.20", which is 5% of input on
1880
+ * both sides of the date, so one ratio serves. Batch is half of each
1881
+ * ($1.00/$5.00, then $2.00/$10.00). Hydrogen has no introductory price:
1882
+ * $1.50/$7.50, the cache at $0.075 (5% again), batch $0.75/$3.75.
1883
+ *
1884
+ * All three: a 1,048,576-token window that input and output share,
1885
+ * implicit caching from 4,096 tokens, and "implicit caching only (explicit
1886
+ * caching is not supported)", so there is no storage price to name.
1887
+ *
1888
+ * The introductory window was fourteen days from its end when these rows
1889
+ * were written, inside the 45 days `pricing-review.test.js` asks about, so
1890
+ * each records the day the page was read. On 2026-12-01 that test fails
1891
+ * until $2/$10 is moved into `history` and the promotion removed.
1892
+ *
1893
+ * Not here, and on the page: the Flex tier (the batch figures) and the
1894
+ * Priority tier (1.8 times standard, $3.60/$18.00 then $7.20/$36.00 on
1895
+ * Carbon and Argon, $2.70/$13.50 on Hydrogen). No Google row in this table
1896
+ * carries a service tier yet, and a tier whose price also changes on a date
1897
+ * needs a shape `serviceTiers` does not have. A call on either is priced at
1898
+ * the standard rate, and the note says so.
1899
+ */
1900
+ {
1901
+ id: 'gemini-4-carbon',
1902
+ provider: 'google',
1903
+ displayName: 'Gemini 4 Carbon',
1904
+ inputPerMTok: 4,
1905
+ outputPerMTok: 20,
1906
+ promo: { inputPerMTok: 2, outputPerMTok: 10, until: '2026-11-30', confirmedOn: '2026-11-16' },
1907
+ contextWindow: 1_048_576,
1908
+ cacheMinTokens: 4096,
1909
+ caching: 'automatic',
1910
+ multipliers: { cacheRead: 0.05, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
1911
+ capability: 'frontier',
1912
+ tier: 'frontier',
1913
+ notes: GEMINI_4_NOTE,
1914
+ },
1915
+ {
1916
+ id: 'gemini-4-argon',
1917
+ provider: 'google',
1918
+ displayName: 'Gemini 4 Argon',
1919
+ inputPerMTok: 4,
1920
+ outputPerMTok: 20,
1921
+ promo: { inputPerMTok: 2, outputPerMTok: 10, until: '2026-11-30', confirmedOn: '2026-11-16' },
1922
+ contextWindow: 1_048_576,
1923
+ cacheMinTokens: 4096,
1924
+ caching: 'automatic',
1925
+ multipliers: { cacheRead: 0.05, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
1926
+ capability: 'frontier',
1927
+ tier: 'frontier',
1928
+ notes: GEMINI_4_NOTE,
1929
+ },
1930
+ {
1931
+ id: 'gemini-4-hydrogen',
1932
+ provider: 'google',
1933
+ displayName: 'Gemini 4 Hydrogen',
1934
+ inputPerMTok: 1.5,
1935
+ outputPerMTok: 7.5,
1936
+ contextWindow: 1_048_576,
1937
+ cacheMinTokens: 4096,
1938
+ caching: 'automatic',
1939
+ multipliers: { cacheRead: 0.05, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
1940
+ capability: 'mid',
1941
+ tier: 'sonnet',
1942
+ notes: GEMINI_4_NOTE,
1943
+ },
1944
+ {
1945
+ /*
1946
+ * The pricing page and the model page, read 2026-11-16: $0.30 in for
1947
+ * text, image, video and audio alike, $2.50 out, the cache at $0.03 (10%),
1948
+ * batch $0.15/$1.25. 1,048,576 tokens in, 65,536 out. Added because
1949
+ * Google's deprecation page names it as where every request to
1950
+ * `gemini-2.5-flash` goes from 2026-12-01.
1951
+ *
1952
+ * No cache minimum: docs/caching says implicit caching is on "for all
1953
+ * Gemini 2.5 and newer models" and its table of minimums has no row for
1954
+ * this one, so none is written.
1955
+ */
1956
+ id: 'gemini-3.5-flash-lite',
1957
+ provider: 'google',
1958
+ displayName: 'Gemini 3.5 Flash-Lite',
1959
+ inputPerMTok: 0.3,
1960
+ outputPerMTok: 2.5,
1961
+ contextWindow: 1_048_576,
1962
+ cacheMinTokens: null,
1963
+ caching: 'automatic',
1964
+ multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
1965
+ capability: 'small',
1966
+ tier: 'haiku',
1967
+ notes:
1968
+ 'Implicit caching is automatic, and no minimum prefix length is published for this model. Explicit caching is'
1969
+ + ' also billed for storage, $1.00 per 1M tokens per hour.',
1970
+ },
1770
1971
 
1771
1972
  // ------------------------------------------------------------------------
1772
1973
  // Moonshot
package/src/types.ts CHANGED
@@ -336,6 +336,18 @@ export interface ModelPricing {
336
336
  outputPerMTok: number;
337
337
  /** ISO date (inclusive) the promotional price applies until. */
338
338
  until: string;
339
+ /**
340
+ * ISO date the provider's page was last read still stating this end date
341
+ * and the price after it.
342
+ *
343
+ * A promotion is the one price change this table can see coming, and the
344
+ * one a provider can cancel: Anthropic did, with Sonnet 5. So inside the
345
+ * last `STALE_PRICING_DAYS` of a promotion somebody has to read the page
346
+ * again, and this is where they write down that they did.
347
+ * `pricing-review.test.js` fails a promotion that close to its end without
348
+ * a confirmation that recent. It changes no price.
349
+ */
350
+ confirmedOn?: string;
339
351
  };
340
352
  /**
341
353
  * Rates that apply only under a stated condition.
@@ -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
+ }