@trazum/core 2.5.1 → 2.5.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.
package/src/codex.ts ADDED
@@ -0,0 +1,136 @@
1
+ /**
2
+ * Codex rollout JSONL, from explicit caller-supplied text. No prompt, path,
3
+ * instruction, tool output or credential is copied. See docs/codex.md for the
4
+ * pinned upstream protocol and the conservative snapshot reconciliation rules.
5
+ */
6
+ export interface CodexRecord {
7
+ model: string;
8
+ ts?: string;
9
+ session?: string;
10
+ label?: string;
11
+ usage: { input_tokens: number; output_tokens: number; cache_read_input_tokens: number };
12
+ }
13
+
14
+ export interface CodexConversion {
15
+ records: CodexRecord[];
16
+ duplicates: number;
17
+ unparseable: number;
18
+ missingModel: number;
19
+ /** Incomplete, synthetic, reset or uncorroborated usage snapshots; never zero-cost calls. */
20
+ unsupported: number;
21
+ otherLines: number;
22
+ }
23
+
24
+ const object = (value: unknown): value is Record<string, unknown> =>
25
+ typeof value === 'object' && value !== null && !Array.isArray(value);
26
+ const FIELDS = ['input_tokens', 'cached_input_tokens', 'output_tokens', 'reasoning_output_tokens', 'total_tokens', 'cache_write_input_tokens'] as const;
27
+ type Counts = Record<typeof FIELDS[number], number>;
28
+
29
+ function counts(value: unknown): Counts | null {
30
+ if (!object(value)) return null;
31
+ const result = {} as Counts;
32
+ for (const field of FIELDS) {
33
+ // Upstream marks only cache_write_input_tokens with serde(default).
34
+ const amount = field === 'cache_write_input_tokens' && value[field] === undefined ? 0 : value[field];
35
+ if (typeof amount !== 'number' || !Number.isSafeInteger(amount) || amount < 0) return null;
36
+ result[field] = amount;
37
+ }
38
+ if (result.cached_input_tokens > result.input_tokens ||
39
+ result.reasoning_output_tokens > result.output_tokens ||
40
+ result.total_tokens !== result.input_tokens + result.output_tokens) return null;
41
+ return result;
42
+ }
43
+
44
+ /** A signature, not a filename or a guess based on prose inside the session. */
45
+ export function looksLikeCodexTranscript(text: string): boolean {
46
+ for (const line of text.split('\n').slice(0, 100)) {
47
+ if (line.trim() === '') continue;
48
+ try {
49
+ const row: unknown = JSON.parse(line);
50
+ if (!object(row) || !object(row.payload)) continue;
51
+ if (row.type === 'session_meta' && typeof row.payload.id === 'string') return true;
52
+ if (row.type === 'turn_context' && typeof row.payload.model === 'string') return true;
53
+ if (row.type === 'event_msg' && row.payload.type === 'token_count') return true;
54
+ } catch { /* Malformed lines are reported by conversion, never executed. */ }
55
+ }
56
+ return false;
57
+ }
58
+
59
+ /**
60
+ * Emit one usage record only when a cumulative increment corroborates the
61
+ * last response's counters. Rate-limit refreshes repeat totals and contribute
62
+ * nothing. A restored first snapshot cannot establish historical model/call
63
+ * attribution, so it establishes a baseline and is explicitly left out.
64
+ */
65
+ export function codexRecords(text: string, options: { label?: string } = {}): CodexConversion {
66
+ const result: CodexConversion = { records: [], duplicates: 0, unparseable: 0, missingModel: 0, unsupported: 0, otherLines: 0 };
67
+ type SessionState = { previous: Counts | null; highWater: Counts | null; seenUsage: boolean };
68
+ const states = new Map<string | null, SessionState>();
69
+ let state: SessionState = { previous: null, highWater: null, seenUsage: false };
70
+ states.set(null, state);
71
+ let model: string | null = null;
72
+ let session: string | null = null;
73
+ for (const line of text.split('\n')) {
74
+ if (line.trim() === '') continue;
75
+ let row: unknown;
76
+ try { row = JSON.parse(line); } catch { result.unparseable++; continue; }
77
+ if (!object(row) || !object(row.payload)) { result.otherLines++; continue; }
78
+ const payload = row.payload;
79
+ if (row.type === 'session_meta') {
80
+ const next = typeof payload.id === 'string' && payload.id !== '' ? payload.id : null;
81
+ if (next === null) { model = null; result.unsupported++; continue; }
82
+ if (next !== session) {
83
+ model = null;
84
+ state = states.get(next) ?? { previous: null, highWater: null, seenUsage: false };
85
+ states.set(next, state);
86
+ }
87
+ session = next;
88
+ continue;
89
+ }
90
+ if (row.type === 'turn_context') {
91
+ model = typeof payload.model === 'string' && payload.model.trim() !== '' ? payload.model : null;
92
+ continue;
93
+ }
94
+ if (row.type !== 'event_msg' || payload.type !== 'token_count') { result.otherLines++; continue; }
95
+ // Rate-limit-only notifications can have no token usage at all.
96
+ if (payload.info === null) { result.otherLines++; continue; }
97
+ if (!object(payload.info)) { result.unsupported++; state.previous = null; state.seenUsage = true; continue; }
98
+ const total = counts(payload.info.total_token_usage);
99
+ const last = counts(payload.info.last_token_usage);
100
+ const first = !state.seenUsage;
101
+ state.seenUsage = true;
102
+ if (total === null) { result.unsupported++; state.previous = null; continue; }
103
+ // A reset or replay cannot lower the baseline and bill the same totals again.
104
+ if (state.highWater !== null && FIELDS.every((field) => total[field] === state.highWater![field])) {
105
+ result.duplicates++;
106
+ continue;
107
+ }
108
+ if (state.highWater !== null && FIELDS.some((field) => total[field] < state.highWater![field])) {
109
+ result.unsupported++;
110
+ continue;
111
+ }
112
+ state.highWater = total;
113
+ const corroborated = last !== null && FIELDS.every((field) =>
114
+ total[field] - (state.previous?.[field] ?? 0) === last[field]);
115
+ const canAttribute = state.previous !== null || first;
116
+ state.previous = total;
117
+ if (!canAttribute || !corroborated || last === null || last.total_tokens === 0 || last.cache_write_input_tokens > 0) {
118
+ result.unsupported++;
119
+ continue;
120
+ }
121
+ if (model === null) { result.missingModel++; continue; }
122
+ result.records.push({
123
+ model,
124
+ ...(typeof row.timestamp === 'string' && Number.isFinite(Date.parse(row.timestamp)) ? { ts: row.timestamp } : {}),
125
+ ...(session === null ? {} : { session }),
126
+ ...(options.label === undefined ? {} : { label: options.label }),
127
+ usage: {
128
+ // Both cached input and reasoning output are subsets, not extra tokens.
129
+ input_tokens: last.input_tokens - last.cached_input_tokens,
130
+ output_tokens: last.output_tokens,
131
+ cache_read_input_tokens: last.cached_input_tokens,
132
+ },
133
+ });
134
+ }
135
+ return result;
136
+ }
package/src/gateway.ts CHANGED
@@ -115,6 +115,7 @@ export type CannotTellCause =
115
115
  | 'no-budget'
116
116
  | 'nothing-measured'
117
117
  | 'model-unpriced'
118
+ | 'output-unbounded'
118
119
  /** A ceiling in the `limits` policy could not be judged — see `policy`. */
119
120
  | 'limit-unjudged';
120
121
 
@@ -215,10 +216,11 @@ function priceCall(
215
216
  call: GatewayCall,
216
217
  on: Date,
217
218
  ): number | null {
218
- if (model === undefined || call.inputTokens === null) return null;
219
+ if (model === undefined || call.inputTokens === null || !Number.isFinite(call.inputTokens) || call.inputTokens < 0 ||
220
+ call.maxOutputTokens === null || !Number.isFinite(call.maxOutputTokens) || call.maxOutputTokens < 0) return null;
219
221
  // The call's own prompt decides a model priced by prompt length.
220
222
  const rates = effectivePricing(model, on, { inputTokens: call.inputTokens });
221
- const output = call.maxOutputTokens ?? 0;
223
+ const output = call.maxOutputTokens;
222
224
  return (call.inputTokens / 1_000_000) * rates.inputPerMTok + (output / 1_000_000) * rates.outputPerMTok;
223
225
  }
224
226
 
@@ -273,9 +275,11 @@ function alternativesFor(
273
275
  function whyCannotTell(
274
276
  standing: GatewayStanding | null,
275
277
  priced: number | null,
278
+ call: GatewayCall,
276
279
  ): CannotTellCause | null {
277
280
  if (standing === null) return 'no-budget';
278
281
  if (standing.consumedUsd === 0 && standing.provenance !== 'measured') return 'nothing-measured';
282
+ if (call.maxOutputTokens === null || !Number.isFinite(call.maxOutputTokens) || call.maxOutputTokens < 0) return 'output-unbounded';
279
283
  return priced === null ? 'model-unpriced' : null;
280
284
  }
281
285
 
@@ -352,7 +356,7 @@ export function gatewayDecision(
352
356
  };
353
357
  }
354
358
 
355
- const cause = whyCannotTell(standing, estimatedUsd);
359
+ const cause = whyCannotTell(standing, estimatedUsd, call);
356
360
  if (cause !== null) {
357
361
  /**
358
362
  * Cannot judge. The operator decided this in advance, and a substitution
@@ -429,6 +433,7 @@ export function gatewayDecision(
429
433
 
430
434
 
431
435
  function becauseCannotTell(cause: CannotTellCause): string {
436
+ if (cause === 'output-unbounded') return 'The request has no valid output-token bound, so its cost cannot be bounded, and this gateway is configured to fail closed.';
432
437
  return cause === 'no-budget'
433
438
  ? 'No budget is configured, so there is nothing to judge this against, and this gateway is configured to fail closed.'
434
439
  : cause === 'nothing-measured'
@@ -482,6 +487,20 @@ export interface GatewayUsage {
482
487
  outputTokens: number;
483
488
  cacheReadTokens: number;
484
489
  cacheWriteTokens: number;
490
+ /** Present only when the provider reports the cache-write TTL split. */
491
+ cacheWrite5mTokens?: number;
492
+ cacheWrite1hTokens?: number;
493
+ }
494
+
495
+ function cacheWriteBreakdown(usage: Record<string, unknown>): Partial<GatewayUsage> {
496
+ const creation = usage.cache_creation;
497
+ if (typeof creation !== 'object' || creation === null) return {};
498
+ const values = creation as Record<string, unknown>;
499
+ const short = values.ephemeral_5m_input_tokens;
500
+ const long = values.ephemeral_1h_input_tokens;
501
+ if (typeof short !== 'number' || typeof long !== 'number' ||
502
+ !Number.isFinite(short) || !Number.isFinite(long) || short < 0 || long < 0) return {};
503
+ return { cacheWrite5mTokens: short, cacheWrite1hTokens: long };
485
504
  }
486
505
 
487
506
  /**
@@ -520,7 +539,39 @@ export interface StreamingUsageReader {
520
539
  */
521
540
  const MAX_SSE_LINE_BYTES = 1024 * 1024;
522
541
 
523
- export function streamingUsageReader(provider: string): StreamingUsageReader {
542
+ /** Strict accounting cannot turn missing or malformed token counts into zero. */
543
+ function completeUsage(shape: WireShape, usage: Record<string, unknown>): boolean {
544
+ const count = (value: unknown): boolean => typeof value === 'number' && Number.isFinite(value) && value >= 0;
545
+ const required = shape === 'anthropic' ? ['input_tokens', 'output_tokens']
546
+ : shape === 'openai' ? ['prompt_tokens', 'completion_tokens']
547
+ : ['promptTokenCount', 'candidatesTokenCount'];
548
+ if (!required.every((key) => count(usage[key]))) return false;
549
+ const optional = shape === 'anthropic' ? ['cache_read_input_tokens', 'cache_creation_input_tokens']
550
+ : shape === 'google' ? ['cachedContentTokenCount', 'thoughtsTokenCount'] : [];
551
+ if (optional.some((key) => usage[key] !== undefined && !count(usage[key]))) return false;
552
+ if (shape === 'anthropic' && usage.cache_creation !== undefined) {
553
+ const breakdown = cacheWriteBreakdown(usage);
554
+ if (breakdown.cacheWrite5mTokens === undefined || breakdown.cacheWrite1hTokens === undefined ||
555
+ breakdown.cacheWrite5mTokens + breakdown.cacheWrite1hTokens !== (usage.cache_creation_input_tokens ?? 0)) return false;
556
+ }
557
+ if (shape === 'openai' && usage.prompt_tokens_details !== undefined) {
558
+ const details = usage.prompt_tokens_details;
559
+ if (typeof details !== 'object' || details === null || Array.isArray(details)) return false;
560
+ const cached = (details as Record<string, unknown>).cached_tokens;
561
+ if (cached !== undefined && (!count(cached) || (cached as number) > (usage.prompt_tokens as number))) return false;
562
+ }
563
+ if (shape === 'google') {
564
+ if ((usage.cachedContentTokenCount as number | undefined ?? 0) > (usage.promptTokenCount as number)) return false;
565
+ // The current price path has no separate reasoning-token treatment.
566
+ if ((usage.thoughtsTokenCount as number | undefined ?? 0) > 0) return false;
567
+ }
568
+ return true;
569
+ }
570
+
571
+ export function streamingUsageReader(
572
+ provider: string,
573
+ options: { requireComplete?: boolean } = {},
574
+ ): StreamingUsageReader {
524
575
  /**
525
576
  * `google` is deliberately not among the shapes this reads.
526
577
  *
@@ -535,6 +586,10 @@ export function streamingUsageReader(provider: string): StreamingUsageReader {
535
586
  let pending = '';
536
587
  let seen = false;
537
588
  let overlong = false;
589
+ let invalid = false;
590
+ let completeStart = false;
591
+ let completeDelta = false;
592
+ let stopped = false;
538
593
  const usage: GatewayUsage = {
539
594
  inputTokens: 0,
540
595
  outputTokens: 0,
@@ -556,14 +611,20 @@ export function streamingUsageReader(provider: string): StreamingUsageReader {
556
611
  const doc = parsed as Record<string, unknown>;
557
612
 
558
613
  if (shape === 'anthropic') {
614
+ if (doc.type === 'message_stop') stopped = true;
559
615
  const message = doc.message;
560
616
  if (typeof message === 'object' && message !== null) {
561
617
  const u = (message as Record<string, unknown>).usage;
562
618
  if (typeof u === 'object' && u !== null) {
563
619
  const start = u as Record<string, unknown>;
620
+ if (options.requireComplete) {
621
+ completeStart = completeUsage('anthropic', start);
622
+ if (!completeStart) invalid = true;
623
+ }
564
624
  usage.inputTokens = num(start.input_tokens);
565
625
  usage.cacheReadTokens = num(start.cache_read_input_tokens);
566
626
  usage.cacheWriteTokens = num(start.cache_creation_input_tokens);
627
+ Object.assign(usage, cacheWriteBreakdown(start));
567
628
  // `message_start` also carries an output count, which is the tokens
568
629
  // emitted so far and therefore near zero. Taken anyway so a stream
569
630
  // that ends before any delta still reports what it reported.
@@ -574,6 +635,13 @@ export function streamingUsageReader(provider: string): StreamingUsageReader {
574
635
  const delta = doc.usage;
575
636
  if (typeof delta === 'object' && delta !== null) {
576
637
  const d = delta as Record<string, unknown>;
638
+ if (options.requireComplete) {
639
+ const complete = completeUsage('anthropic', {
640
+ input_tokens: usage.inputTokens, output_tokens: usage.outputTokens, ...d,
641
+ });
642
+ if (!complete || typeof d.output_tokens !== 'number') invalid = true;
643
+ if (doc.type === 'message_delta' && complete && typeof d.output_tokens === 'number') completeDelta = true;
644
+ }
577
645
  // Cumulative, so the last one wins rather than accumulating.
578
646
  if (typeof d.output_tokens === 'number') usage.outputTokens = num(d.output_tokens);
579
647
  if (typeof d.input_tokens === 'number') usage.inputTokens = num(d.input_tokens);
@@ -586,6 +654,7 @@ export function streamingUsageReader(provider: string): StreamingUsageReader {
586
654
  const u = doc.usage;
587
655
  if (typeof u !== 'object' || u === null) return;
588
656
  const o = u as Record<string, unknown>;
657
+ if (options.requireComplete && !completeUsage('openai', o)) { invalid = true; return; }
589
658
  if (typeof o.prompt_tokens !== 'number' && typeof o.completion_tokens !== 'number') return;
590
659
  const details = o.prompt_tokens_details;
591
660
  const cached =
@@ -621,6 +690,8 @@ export function streamingUsageReader(provider: string): StreamingUsageReader {
621
690
  }
622
691
  },
623
692
  done(): GatewayUsage | null {
693
+ if (options.requireComplete && (invalid || overlong ||
694
+ (shape === 'anthropic' && (!completeStart || !completeDelta || !stopped)))) return null;
624
695
  if (overlong && !seen) return null;
625
696
  return seen ? usage : null;
626
697
  },
@@ -640,7 +711,8 @@ export function streamingUsageReader(provider: string): StreamingUsageReader {
640
711
  export function usageFromResponse(
641
712
  provider: string,
642
713
  body: unknown,
643
- ): { inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number } | null {
714
+ options: { requireComplete?: boolean } = {},
715
+ ): GatewayUsage | null {
644
716
  if (typeof body !== 'object' || body === null || Array.isArray(body)) return null;
645
717
  const num = (value: unknown): number => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
646
718
 
@@ -660,6 +732,7 @@ export function usageFromResponse(
660
732
  : (body as { usage?: unknown }).usage;
661
733
  if (typeof carrier !== 'object' || carrier === null || Array.isArray(carrier)) return null;
662
734
  const u = carrier as Record<string, unknown>;
735
+ if (options.requireComplete && !completeUsage(shape, u)) return null;
663
736
 
664
737
  if (shape === 'anthropic') {
665
738
  if (typeof u.input_tokens !== 'number' && typeof u.output_tokens !== 'number') return null;
@@ -668,6 +741,7 @@ export function usageFromResponse(
668
741
  outputTokens: num(u.output_tokens),
669
742
  cacheReadTokens: num(u.cache_read_input_tokens),
670
743
  cacheWriteTokens: num(u.cache_creation_input_tokens),
744
+ ...cacheWriteBreakdown(u),
671
745
  };
672
746
  }
673
747
  if (shape === 'openai') {
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Static integration discovery, safe to import in a browser.
3
+ *
4
+ * A harness identifies where work runs, not who billed for it. An importer
5
+ * describes a supported local format; it does not discover installed tools,
6
+ * inspect sessions, or intercept their model calls.
7
+ */
8
+ export interface HarnessCapability {
9
+ readonly id: string;
10
+ readonly name: string;
11
+ readonly nativeImport: {
12
+ readonly command: 'from-claude-code' | 'from-codex';
13
+ readonly format: 'claude-code-transcript-jsonl' | 'codex-session-jsonl';
14
+ } | null;
15
+ readonly normalizedUsage: { readonly command: 'bill'; readonly format: 'trazum-usage-jsonl' };
16
+ readonly billingMode: 'unknown';
17
+ readonly automaticInterception: false;
18
+ }
19
+
20
+ export interface HarnessCapabilities {
21
+ readonly schemaVersion: 1;
22
+ /** Trazum entry points, not automatically installed integrations for each harness. */
23
+ readonly accessChannels: readonly ('cli' | 'mcp' | 'http')[];
24
+ readonly taskQuality: 'not-measured';
25
+ readonly harnesses: readonly HarnessCapability[];
26
+ }
27
+
28
+ const normalizedUsage = Object.freeze({ command: 'bill', format: 'trazum-usage-jsonl' } as const);
29
+ const harness = (
30
+ id: string,
31
+ name: string,
32
+ nativeImport: HarnessCapability['nativeImport'],
33
+ ): HarnessCapability => Object.freeze({
34
+ id, name, nativeImport: nativeImport === null ? null : Object.freeze(nativeImport),
35
+ normalizedUsage, billingMode: 'unknown', automaticInterception: false,
36
+ });
37
+
38
+ export const HARNESS_CAPABILITIES: HarnessCapabilities = Object.freeze({
39
+ schemaVersion: 1,
40
+ accessChannels: Object.freeze(['cli', 'mcp', 'http'] as const),
41
+ taskQuality: 'not-measured',
42
+ harnesses: Object.freeze([
43
+ harness('claude-code', 'Claude Code', { command: 'from-claude-code', format: 'claude-code-transcript-jsonl' }),
44
+ harness('codex', 'Codex', { command: 'from-codex', format: 'codex-session-jsonl' }),
45
+ harness('cursor', 'Cursor', null),
46
+ harness('mcp-client', 'Generic MCP client', null),
47
+ ]),
48
+ });
49
+
50
+ /** Exact stable IDs only; unknown clients never inherit another harness's importer. */
51
+ export function getHarnessCapability(id: string): HarnessCapability | null {
52
+ return HARNESS_CAPABILITIES.harnesses.find((entry) => entry.id === id) ?? null;
53
+ }
package/src/host.ts CHANGED
@@ -6,17 +6,16 @@
6
6
  * the same prompt optimises the same way everywhere, as it must, and that is a
7
7
  * standing constraint rather than a coincidence.
8
8
  *
9
- * What the answer earns is the right to stop quoting a monthly dollar saving to
10
- * somebody on a flat-rate plan. Inside Cursor or a Claude Code subscription the
11
- * per-call saving is real arithmetic about tokens and **not money anybody gets
12
- * back**, and "$184/month" is wrong in the direction that matters most.
9
+ * Environment markers identify the execution host, not its payment mode. The
10
+ * same host can use a subscription, API credentials, credits or a local model.
11
+ * Never infer invoice savings from the terminal running the command.
13
12
  */
14
13
 
15
14
  export interface HostEnvironment {
16
15
  id: string;
17
16
  displayName: string;
18
17
  /**
19
- * How the host bills.
18
+ * Verified payment mode, if known. Host identity alone cannot establish it.
20
19
  *
21
20
  * `unknown` is honest rather than lazy: a VS Code terminal says nothing about
22
21
  * whether the prompts written in it go to a metered API or a subscription, and
@@ -42,38 +41,32 @@ export interface HostEnvironment {
42
41
  const HOSTS: Array<{
43
42
  id: string;
44
43
  displayName: string;
45
- billing: HostEnvironment['billing'];
46
44
  test: (env: NodeJS.ProcessEnv) => string | null;
47
45
  }> = [
48
46
  {
49
47
  id: 'claude-code',
50
48
  displayName: 'Claude Code',
51
- billing: 'subscription',
52
49
  test: (e) => (e.CLAUDECODE ? 'CLAUDECODE' : null),
53
50
  },
54
51
  {
55
52
  id: 'codex',
56
53
  displayName: 'Codex',
57
- billing: 'subscription',
58
54
  test: (e) => (e.CODEX_SANDBOX ? 'CODEX_SANDBOX' : e.CODEX_HOME ? 'CODEX_HOME' : null),
59
55
  },
60
56
  {
61
57
  id: 'cursor',
62
58
  displayName: 'Cursor',
63
- billing: 'subscription',
64
59
  test: (e) => (e.CURSOR_TRACE_ID ? 'CURSOR_TRACE_ID' : null),
65
60
  },
66
61
  {
67
62
  id: 'github-actions',
68
63
  displayName: 'GitHub Actions',
69
- billing: 'per-token',
70
64
  test: (e) => (e.GITHUB_ACTIONS ? 'GITHUB_ACTIONS' : null),
71
65
  },
72
- { id: 'ci', displayName: 'CI', billing: 'per-token', test: (e) => (e.CI ? 'CI' : null) },
66
+ { id: 'ci', displayName: 'CI', test: (e) => (e.CI ? 'CI' : null) },
73
67
  {
74
68
  id: 'vscode',
75
69
  displayName: 'VS Code',
76
- billing: 'unknown',
77
70
  test: (e) => (e.TERM_PROGRAM === 'vscode' ? 'TERM_PROGRAM' : null),
78
71
  },
79
72
  ];
@@ -83,7 +76,7 @@ export function detectHost(env: NodeJS.ProcessEnv = process.env): HostEnvironmen
83
76
  for (const host of HOSTS) {
84
77
  const evidence = host.test(env);
85
78
  if (evidence !== null) {
86
- return { id: host.id, displayName: host.displayName, billing: host.billing, evidence };
79
+ return { id: host.id, displayName: host.displayName, billing: 'unknown', evidence };
87
80
  }
88
81
  }
89
82
  return { id: 'terminal', displayName: 'terminal', billing: 'unknown', evidence: null };
package/src/index.ts CHANGED
@@ -14,10 +14,13 @@ export {
14
14
  parseUsageLine,
15
15
  profileUsage,
16
16
  sharesOf,
17
+ spendByMonth,
17
18
  } from './usage.js';
18
19
  export type {
19
20
  CacheEconomics,
20
21
  CacheVerdict,
22
+ MonthSpend,
23
+ SpendByMonth,
21
24
  UsageProfileOptions,
22
25
  UsageBreakdown,
23
26
  FieldCoverage,
@@ -660,3 +663,12 @@ export type {
660
663
  Section,
661
664
  Slot,
662
665
  } from './write.js';
666
+
667
+ export { codexRecords, looksLikeCodexTranscript } from './codex.js';
668
+ export type { CodexRecord, CodexConversion } from './codex.js';
669
+
670
+ export { HARNESS_CAPABILITIES, getHarnessCapability } from './harnesses.js';
671
+ export type { HarnessCapability, HarnessCapabilities } from './harnesses.js';
672
+
673
+ export { compactToolOutput, EFFICIENT_OUTPUT_INSTRUCTIONS } from './tool-output.js';
674
+ export type { ToolOutputView } from './tool-output.js';
@@ -0,0 +1,69 @@
1
+ import { estimateTokens } from './tokenizer.js';
2
+ import { MAX_INPUT_CHARS } from './limits.js';
3
+
4
+ /** A display view of a log, never a replacement for machine-readable output. */
5
+ export interface ToolOutputView {
6
+ text: string;
7
+ applied: boolean;
8
+ reason: 'compacted' | 'unchanged' | 'unsupported' | 'too-large' | 'not-worthwhile';
9
+ estimatedTokensBefore: number | null;
10
+ estimatedTokensAfter: number | null;
11
+ repeatedLines: number;
12
+ }
13
+
14
+ export const EFFICIENT_OUTPUT_INSTRUCTIONS =
15
+ 'Answer the requested task directly. Avoid repeating the request, unchanged code, ' +
16
+ 'and redundant explanations. Use only the detail needed for correctness. ' +
17
+ 'Preserve errors, evidence, constraints and required checks. Expand compacted tool ' +
18
+ 'output when exact lines are needed. Follow the user’s requested format and depth. ' +
19
+ 'Never claim token reductions increase a provider’s quota.';
20
+
21
+ const HEADER = '[Trazum compacted log;';
22
+ // Diagnostic repetition may be evidence of frequency and must remain visible.
23
+ const DIAGNOSTIC = /error|warn|fail|fatal|exception|traceback|panic|assert|stderr/i;
24
+
25
+ /**
26
+ * Collapse only consecutive, identical, complete log lines. No semantic rewrite,
27
+ * source-code compression, tail truncation or deduplication across intervening
28
+ * lines. The caller must store the original before emitting an applied view.
29
+ * Counts are heuristic estimates, not provider usage or subscription capacity.
30
+ */
31
+ export function compactToolOutput(input: string, recoveryCommand: string): ToolOutputView {
32
+ const unchanged = (reason: ToolOutputView['reason'], before: number | null): ToolOutputView => ({
33
+ text: input, applied: false, reason, estimatedTokensBefore: before,
34
+ estimatedTokensAfter: before, repeatedLines: 0,
35
+ });
36
+ if (input.length > MAX_INPUT_CHARS) return unchanged('too-large', null);
37
+ const before = estimateTokens(input);
38
+ if (!recoveryCommand || /[\r\n]/.test(recoveryCommand)) return unchanged('unsupported', before);
39
+ // Do not reinterpret terminal controls, fenced source or our own output.
40
+ if (/[\x00-\x08\x0b-\x1f\x7f]/.test(input) || /```|~~~/.test(input) || input.startsWith(HEADER)) {
41
+ return unchanged('unsupported', before);
42
+ }
43
+ const lines = input.split('\n');
44
+ const out: string[] = [];
45
+ let removed = 0;
46
+ for (let i = 0; i < lines.length;) {
47
+ const line = lines[i]!;
48
+ let end = i + 1;
49
+ // Leave the final unterminated line untouched.
50
+ while (end < lines.length - 1 && lines[end] === line) end++;
51
+ const count = end - i;
52
+ if (count >= 3 && line.trim() !== '' && !DIAGNOSTIC.test(line)) {
53
+ out.push(line, `[Trazum: previous line repeated ${count - 1} additional times]`);
54
+ removed += count - 1;
55
+ } else {
56
+ for (let j = i; j < end; j++) out.push(lines[j]!);
57
+ }
58
+ i = end;
59
+ }
60
+ if (!removed) return unchanged('unchanged', before);
61
+ const text = `${HEADER} consecutive repetitions only; token counts are estimates]\n` +
62
+ `Recover original: ${recoveryCommand}\n\n` + out.join('\n');
63
+ const after = estimateTokens(text);
64
+ // Include recovery instructions in the comparison; tiny reductions do not
65
+ // justify changing the display. This is a heuristic, not a token guarantee.
66
+ if (before - after < 128 || after > before * 0.8) return unchanged('not-worthwhile', before);
67
+ return { text, applied: true, reason: 'compacted', estimatedTokensBefore: before,
68
+ estimatedTokensAfter: after, repeatedLines: removed };
69
+ }
package/src/usage.ts CHANGED
@@ -1530,6 +1530,69 @@ export function sharesOf(breakdown: UsageBreakdown): UsageShares {
1530
1530
  };
1531
1531
  }
1532
1532
 
1533
+ /** One calendar month of a bill, UTC. */
1534
+ export interface MonthSpend {
1535
+ /** `YYYY-MM`, UTC. */
1536
+ month: string;
1537
+ /** The first and last UTC day of the month, the `--since`/`--until` that bill it alone. */
1538
+ firstDay: string;
1539
+ lastDay: string;
1540
+ calls: number;
1541
+ usd: number;
1542
+ }
1543
+
1544
+ /** A bill by calendar month, and the part of it that sits in no month. */
1545
+ export interface SpendByMonth {
1546
+ /** Oldest first. Only months with priced, dated calls appear. */
1547
+ months: MonthSpend[];
1548
+ /**
1549
+ * Priced calls with no clock: in the total and in no month. Zero calls when
1550
+ * every priced call carried a timestamp. Without it the month rows add up
1551
+ * short of the total, and the reader goes looking for an error that is not
1552
+ * one.
1553
+ */
1554
+ undated: { calls: number; usd: number };
1555
+ }
1556
+
1557
+ /**
1558
+ * A bill by calendar month, summed from the report's own days.
1559
+ *
1560
+ * A year of Claude Code sessions in one total says what it all cost and not
1561
+ * which month cost what, which is the next question. One function, so that
1562
+ * the statement, the bill's documents and the browser cannot disagree about
1563
+ * which month a call belongs to: a month is UTC, like the days it is summed
1564
+ * from, and the days hold only priced calls that carry a clock.
1565
+ */
1566
+ export function spendByMonth(report: Pick<UsageProfileReport, 'spendByDay' | 'total'>): SpendByMonth {
1567
+ const byMonth = new Map<string, { calls: number; usd: number }>();
1568
+ for (const day of report.spendByDay) {
1569
+ const key = day.day.slice(0, 7);
1570
+ const month = byMonth.get(key) ?? { calls: 0, usd: 0 };
1571
+ month.calls += day.calls;
1572
+ month.usd += day.usd;
1573
+ byMonth.set(key, month);
1574
+ }
1575
+ const months = [...byMonth.entries()]
1576
+ .sort(([a], [b]) => a.localeCompare(b))
1577
+ .map(([month, { calls, usd }]) => {
1578
+ const [year, monthNumber] = month.split('-').map(Number);
1579
+ const lastDay = new Date(Date.UTC(year ?? 1970, monthNumber ?? 1, 0)).toISOString().slice(0, 10);
1580
+ return { month, firstDay: `${month}-01`, lastDay, calls, usd };
1581
+ });
1582
+ const dated = months.reduce((sum, month) => ({ calls: sum.calls + month.calls, usd: sum.usd + month.usd }), {
1583
+ calls: 0,
1584
+ usd: 0,
1585
+ });
1586
+ const undatedCalls = report.total.calls - dated.calls;
1587
+ return {
1588
+ months,
1589
+ undated:
1590
+ undatedCalls > 0
1591
+ ? { calls: undatedCalls, usd: Math.max(0, report.total.totalUsd - dated.usd) }
1592
+ : { calls: 0, usd: 0 },
1593
+ };
1594
+ }
1595
+
1533
1596
  /**
1534
1597
  * How much of the input that could have been cached was.
1535
1598
  *