@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/README.md +10 -0
- package/dist/codex.d.ts +37 -0
- package/dist/codex.d.ts.map +1 -0
- package/dist/codex.js +148 -0
- package/dist/codex.js.map +1 -0
- package/dist/gateway.d.ts +10 -8
- package/dist/gateway.d.ts.map +1 -1
- package/dist/gateway.js +89 -6
- package/dist/gateway.js.map +1 -1
- package/dist/harnesses.d.ts +32 -0
- package/dist/harnesses.d.ts.map +1 -0
- package/dist/harnesses.js +21 -0
- package/dist/harnesses.js.map +1 -0
- package/dist/host.d.ts +4 -5
- package/dist/host.d.ts.map +1 -1
- package/dist/host.js +5 -11
- package/dist/host.js.map +1 -1
- package/dist/index.d.ts +8 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -1
- package/dist/index.js.map +1 -1
- package/dist/tool-output.d.ts +18 -0
- package/dist/tool-output.d.ts.map +1 -0
- package/dist/tool-output.js +63 -0
- package/dist/tool-output.js.map +1 -0
- package/dist/usage.d.ts +35 -0
- package/dist/usage.d.ts.map +1 -1
- package/dist/usage.js +37 -0
- package/dist/usage.js.map +1 -1
- package/package.json +1 -1
- package/src/codex.ts +136 -0
- package/src/gateway.ts +79 -5
- package/src/harnesses.ts +53 -0
- package/src/host.ts +6 -13
- package/src/index.ts +12 -0
- package/src/tool-output.ts +69 -0
- package/src/usage.ts +63 -0
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)
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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') {
|
package/src/harnesses.ts
ADDED
|
@@ -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
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
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
|
-
*
|
|
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',
|
|
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:
|
|
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
|
*
|