@trazum/core 2.5.2 → 2.7.0

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/task.ts ADDED
@@ -0,0 +1,172 @@
1
+ import { analyzeTask, taskError, taskId, taskKeys, taskText } from './task-analysis.js';
2
+ import { MAX_INPUT_CHARS } from './limits.js';
3
+ import { BUNDLED_CATALOGUE } from './pricing.js';
4
+ import { TASK_GAPS, TASK_LIMITATIONS } from './task-types.js';
5
+ import type { TaskComparison, TaskReport } from './task-types.js';
6
+
7
+ export { analyzeTask };
8
+ export type { TaskCategory, TaskComparison, TaskFinding, TaskFormat, TaskInput, TaskOutcome, TaskPolicyId, TaskReport } from './task-types.js';
9
+
10
+ export interface TaskPolicy { id: 'repeat-review-v1'; instructions: string }
11
+
12
+ export const TASK_POLICY_INSTRUCTIONS = [
13
+ 'Before repeating a read or search with identical arguments, check whether the earlier result is still available and relevant.',
14
+ 'Reuse an earlier result only when you can establish that the underlying state has not changed. Otherwise read or search again.',
15
+ 'Before retrying an identical failed shell command, inspect the recorded failure and change the cause or explain why retrying is justified.',
16
+ 'Keep deliberate verification, fresh-state checks, required tests and safety checks. Never suppress failures or claim an outcome without evidence.',
17
+ 'This policy does not authorize running commands, changing permissions or omitting required work.',
18
+ ].join('\n');
19
+
20
+ const count = (value: unknown): value is number => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
21
+ const checksum = (value: unknown): value is string => typeof value === 'string' && /^[a-f0-9]{16}$/u.test(value);
22
+ function exact(value: unknown, fields: readonly string[]): asserts value is Record<string, unknown> {
23
+ taskKeys(value, fields);
24
+ if (Object.keys(value).length !== fields.length) taskError();
25
+ }
26
+ function stringList(value: unknown, max: number): value is string[] {
27
+ return Array.isArray(value) && value.length <= max && value.every((item) => typeof item === 'string') && new Set(value).size === value.length;
28
+ }
29
+
30
+ /** Validate every persisted field; reports remain caller-supplied observations, not signed evidence. */
31
+ function validateReport(value: unknown): TaskReport {
32
+ exact(value, ['version', 'kind', 'task', 'usage', 'sources', 'coverage', 'tools', 'limitations']);
33
+ if (value.version !== 1 || value.kind !== 'trazum-task') taskError();
34
+ const task = value.task;
35
+ exact(task, ['id', 'type', 'criterion', 'policyId', 'outcome', 'assessor']);
36
+ if (!taskId(task.id) || !taskId(task.type) || !taskText(task.criterion, 500) ||
37
+ typeof task.policyId !== 'string' || !['baseline', 'repeat-review-v1'].includes(task.policyId) ||
38
+ typeof task.outcome !== 'string' || !['accepted', 'rejected', 'unknown'].includes(task.outcome) ||
39
+ (task.assessor !== null && !taskText(task.assessor, 100)) ||
40
+ (task.outcome !== 'unknown' && task.assessor === null)) taskError();
41
+ const usage = value.usage;
42
+ exact(usage, ['records', 'inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'totalTokens', 'apiEquivalentUsd', 'unpricedRecords', 'pricing']);
43
+ exact(usage.pricing, ['source', 'lastReviewed', 'basis']);
44
+ if (usage.pricing.source !== 'bundled' || usage.pricing.basis !== 'api-equivalent' ||
45
+ typeof usage.pricing.lastReviewed !== 'string' || !/^\d{4}-\d{2}-\d{2}$/u.test(usage.pricing.lastReviewed) ||
46
+ !Number.isFinite(Date.parse(usage.pricing.lastReviewed)) ||
47
+ new Date(usage.pricing.lastReviewed).toISOString().slice(0, 10) !== usage.pricing.lastReviewed) taskError();
48
+ for (const key of ['records', 'inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'totalTokens', 'unpricedRecords']) if (!count(usage[key])) taskError();
49
+ if (usage.totalTokens !== (usage.inputTokens as number) + (usage.outputTokens as number) + (usage.cacheReadTokens as number) + (usage.cacheWriteTokens as number) ||
50
+ (usage.unpricedRecords as number) > (usage.records as number) ||
51
+ (usage.apiEquivalentUsd !== null && (typeof usage.apiEquivalentUsd !== 'number' || !Number.isFinite(usage.apiEquivalentUsd) || usage.apiEquivalentUsd < 0)) ||
52
+ ((usage.records === 0 || usage.unpricedRecords !== 0) && usage.apiEquivalentUsd !== null) ||
53
+ (usage.records === 0 && usage.totalTokens !== 0)) taskError();
54
+ if (!Array.isArray(value.sources) || value.sources.length < 1 || value.sources.length > 16) taskError();
55
+ const fingerprints = new Set<string>();
56
+ const sessions = new Set<string>();
57
+ const formats = new Set<string>();
58
+ const requiredGaps = new Set<string>();
59
+ let sourceIndex = 0;
60
+ for (const source of value.sources) {
61
+ exact(source, ['index', 'format', 'fingerprint', 'sessionKeys', 'sessionCount', 'diagnostics', 'completeness']);
62
+ if (source.index !== ++sourceIndex || typeof source.format !== 'string' || !['claude-code', 'codex'].includes(source.format) || !checksum(source.fingerprint) ||
63
+ !count(source.sessionCount) || !stringList(source.sessionKeys, 10_000) || !source.sessionKeys.every(checksum) || source.sessionKeys.length !== source.sessionCount ||
64
+ source.completeness !== 'not-established' || fingerprints.has(source.fingerprint)) taskError();
65
+ fingerprints.add(source.fingerprint);
66
+ formats.add(source.format as string);
67
+ for (const key of source.sessionKeys) { if (sessions.has(key)) taskError(); sessions.add(key); }
68
+ if (source.sessionCount === 0) requiredGaps.add('missing-session');
69
+ const diagnostics = source.diagnostics;
70
+ const names = source.format === 'claude-code'
71
+ ? ['collapsed', 'noRequestId', 'otherLines', 'unparseable', 'assistantWithoutUsage', 'streamed', 'disagreements', 'synthetic', 'resume']
72
+ : ['duplicates', 'unparseable', 'missingModel', 'unsupported', 'otherLines'];
73
+ exact(diagnostics, names);
74
+ for (const key of names) {
75
+ if (key === 'resume') {
76
+ exact(diagnostics.resume, ['line', 'records']);
77
+ if (!count(diagnostics.resume.line) || !count(diagnostics.resume.records)) taskError();
78
+ } else if (!count(diagnostics[key])) taskError();
79
+ }
80
+ if (diagnostics.unparseable) requiredGaps.add('malformed-lines');
81
+ if (diagnostics.assistantWithoutUsage || diagnostics.unsupported || diagnostics.missingModel) requiredGaps.add('incomplete-usage');
82
+ if (diagnostics.disagreements) requiredGaps.add('usage-disagreement');
83
+ if (diagnostics.noRequestId) requiredGaps.add('missing-request-id');
84
+ }
85
+ const coverage = value.coverage;
86
+ exact(coverage, ['harnesses', 'models', 'gaps']);
87
+ if (!stringList(coverage.harnesses, 2) || !stringList(coverage.models, BUNDLED_CATALOGUE.models.length) ||
88
+ !coverage.models.every((id) => BUNDLED_CATALOGUE.models.some((model) => model.id === id)) ||
89
+ !stringList(coverage.gaps, TASK_GAPS.length) || !coverage.gaps.every((gap) => (TASK_GAPS as readonly string[]).includes(gap)) ||
90
+ coverage.harnesses.slice().sort().join(',') !== [...formats].sort().join(',')) taskError();
91
+ if (usage.records === 0) requiredGaps.add('missing-usage');
92
+ if (usage.unpricedRecords !== 0) { requiredGaps.add('unpriced-model'); requiredGaps.add('unrecognized-model'); }
93
+ if ((usage.records as number) > (usage.unpricedRecords as number) && coverage.models.length === 0) taskError();
94
+ const tools = value.tools;
95
+ exact(tools, ['calls', 'duplicateCalls', 'missingResults', 'unsupported', 'findings']);
96
+ for (const key of ['calls', 'duplicateCalls', 'missingResults', 'unsupported']) if (!count(tools[key])) taskError();
97
+ if ((tools.missingResults as number) > (tools.calls as number) || !Array.isArray(tools.findings) || tools.findings.length > 100) taskError();
98
+ if (tools.missingResults || tools.unsupported) requiredGaps.add('incomplete-tools');
99
+ let findingsCalls = 0;
100
+ for (const finding of tools.findings) {
101
+ exact(finding, ['kind', 'category', 'count', 'occurrences']);
102
+ if (typeof finding.kind !== 'string' || !['repeated-result', 'repeated-failure'].includes(finding.kind) ||
103
+ typeof finding.category !== 'string' || !['read', 'search', 'shell'].includes(finding.category) ||
104
+ !count(finding.count) || finding.count < 2 || !Array.isArray(finding.occurrences) || finding.occurrences.length < 2 ||
105
+ finding.occurrences.length !== Math.min(finding.count, 20)) taskError();
106
+ findingsCalls += finding.count;
107
+ if (finding.count > 20) requiredGaps.add('findings-truncated');
108
+ let previousLine = 0;
109
+ let sourceIndexForFinding: number | null = null;
110
+ for (const occurrence of finding.occurrences) {
111
+ exact(occurrence, ['source', 'line', 'resultLine']);
112
+ if (!count(occurrence.source) || occurrence.source < 1 || occurrence.source > value.sources.length ||
113
+ !count(occurrence.line) || occurrence.line < 1 || occurrence.line < previousLine || !count(occurrence.resultLine) || occurrence.resultLine <= occurrence.line) taskError();
114
+ if (sourceIndexForFinding !== null && sourceIndexForFinding !== occurrence.source) taskError();
115
+ sourceIndexForFinding = occurrence.source;
116
+ previousLine = occurrence.line;
117
+ }
118
+ }
119
+ if (findingsCalls > (tools.calls as number) - (tools.missingResults as number)) taskError();
120
+ const gaps = coverage.gaps as string[];
121
+ if ([...requiredGaps].some((gap) => !gaps.includes(gap))) taskError();
122
+ if (!Array.isArray(value.limitations) || JSON.stringify(value.limitations) !== JSON.stringify(TASK_LIMITATIONS)) taskError();
123
+ return value as unknown as TaskReport;
124
+ }
125
+
126
+ export function parseTaskReport(text: string): TaskReport {
127
+ if (typeof text !== 'string' || text.length > MAX_INPUT_CHARS) taskError();
128
+ let value: unknown;
129
+ try { value = JSON.parse(text); } catch { taskError(); }
130
+ return validateReport(value);
131
+ }
132
+
133
+ function validated(value: TaskReport): TaskReport {
134
+ let text: string;
135
+ try { text = JSON.stringify(value); } catch { taskError(); }
136
+ return parseTaskReport(text);
137
+ }
138
+
139
+ export function taskPolicy(report: TaskReport): TaskPolicy {
140
+ const checked = validated(report);
141
+ if (!checked.tools.findings.some((finding) => finding.category === 'read' || finding.category === 'search' || finding.kind === 'repeated-failure')) {
142
+ throw new Error('No actionable repeated read, search or explicit failure evidence was found.');
143
+ }
144
+ return { id: 'repeat-review-v1', instructions: TASK_POLICY_INSTRUCTIONS };
145
+ }
146
+
147
+ /** Compare declared matched tasks; never infer causality, quality or monetary savings. */
148
+ export function compareTasks(before: TaskReport, after: TaskReport): TaskComparison {
149
+ const a = validated(before);
150
+ const b = validated(after);
151
+ const result: TaskComparison = { version: 1, kind: 'trazum-task-comparison', verdict: 'inconclusive', reasons: [], tokenChange: null, limitations: [...TASK_LIMITATIONS] };
152
+ if (a.task.type !== b.task.type) result.reasons.push('task-type-mismatch');
153
+ if (a.task.criterion !== b.task.criterion) result.reasons.push('criterion-mismatch');
154
+ if (a.task.policyId !== 'baseline' || b.task.policyId !== 'repeat-review-v1') result.reasons.push('policy-pair-mismatch');
155
+ if (a.coverage.harnesses.slice().sort().join(',') !== b.coverage.harnesses.slice().sort().join(',')) result.reasons.push('harness-coverage-mismatch');
156
+ if (a.coverage.models.slice().sort().join(',') !== b.coverage.models.slice().sort().join(',')) result.reasons.push('model-coverage-mismatch');
157
+ const fingerprints = new Set(a.sources.map((source) => source.fingerprint));
158
+ const sessions = new Set(a.sources.flatMap((source) => source.sessionKeys));
159
+ if (b.sources.some((source) => fingerprints.has(source.fingerprint) || source.sessionKeys.some((key) => sessions.has(key)))) result.reasons.push('source-reuse');
160
+ if (a.coverage.gaps.length || b.coverage.gaps.length) result.reasons.push('incomplete-evidence');
161
+ if (result.reasons.length) return result;
162
+ if (a.task.outcome === 'accepted' && b.task.outcome === 'rejected') {
163
+ result.verdict = 'quality-regressed'; result.reasons.push('declared-acceptance-regressed'); return result;
164
+ }
165
+ if (a.task.outcome !== 'accepted' || b.task.outcome !== 'accepted') { result.reasons.push('accepted-outcomes-required'); return result; }
166
+ if (a.usage.records === 0 || b.usage.records === 0 || a.usage.totalTokens === 0) { result.reasons.push('nonzero-baseline-required'); return result; }
167
+ const delta = b.usage.totalTokens - a.usage.totalTokens;
168
+ result.tokenChange = { before: a.usage.totalTokens, after: b.usage.totalTokens, delta, percent: delta / a.usage.totalTokens * 100 };
169
+ result.verdict = delta < 0 ? 'lower-usage' : delta > 0 ? 'higher-usage' : 'similar-usage';
170
+ result.reasons.push('paired-observation-not-causal');
171
+ return result;
172
+ }
package/src/usage.ts CHANGED
@@ -799,6 +799,20 @@ export function parseUsageLine(line: string): UsageRecord | null {
799
799
  const geminiCached = geminiMeta
800
800
  ? readCount(geminiMeta.cachedContentTokenCount)
801
801
  : ({ kind: 'absent' } as Count);
802
+ /**
803
+ * The two Gemini counts that sit outside `promptTokenCount` and
804
+ * `candidatesTokenCount` and are still billed. The SDK's own definitions
805
+ * (`@google/genai`, `UsageMetadata`): `thoughtsTokenCount` is "the model's
806
+ * generated 'thoughts' output", priced as output, and
807
+ * `toolUsePromptTokenCount` is "the results from tool executions, which are
808
+ * provided back to the model as input", priced as input; and
809
+ * `totalTokenCount` "is the sum of prompt, candidates, tool-use prompt and
810
+ * thoughts". Reading only the first two priced every thinking model's
811
+ * reasoning at zero: on Gemini 2.5 Pro and 3.1 Pro that is often most of the
812
+ * output, and it was the flattering direction.
813
+ */
814
+ const geminiThoughts = geminiMeta ? readCount(geminiMeta.thoughtsTokenCount) : ({ kind: 'absent' } as Count);
815
+ const geminiToolPrompt = geminiMeta ? readCount(geminiMeta.toolUsePromptTokenCount) : ({ kind: 'absent' } as Count);
802
816
 
803
817
  const counts: Record<string, Count> = {
804
818
  input: readCount(
@@ -818,6 +832,8 @@ export function parseUsageLine(line: string): UsageRecord | null {
818
832
  openAiCached,
819
833
  openAiWrite,
820
834
  geminiCached,
835
+ geminiThoughts,
836
+ geminiToolPrompt,
821
837
  write5m,
822
838
  write1h,
823
839
  };
@@ -848,7 +864,7 @@ export function parseUsageLine(line: string): UsageRecord | null {
848
864
 
849
865
  return {
850
866
  model,
851
- inputTokens: Math.max(0, valueOf(counts.input!) - cached - openAiWritten),
867
+ inputTokens: Math.max(0, valueOf(counts.input!) - cached - openAiWritten) + valueOf(counts.geminiToolPrompt!),
852
868
  cacheReadTokens: counts.cacheRead!.kind === 'ok' ? counts.cacheRead!.value : cached,
853
869
  /**
854
870
  * The split when the log carries it, the flat number otherwise — and
@@ -859,7 +875,7 @@ export function parseUsageLine(line: string): UsageRecord | null {
859
875
  cacheWrite1hTokens: hasSplit ? split1h : 0,
860
876
  // `cache_write_tokens` names no TTL either; see the note in `profileUsage`.
861
877
  writeTtlKnown: hasSplit || (flatWrite === 0 && openAiWritten === 0),
862
- outputTokens: valueOf(counts.output!),
878
+ outputTokens: valueOf(counts.output!) + valueOf(counts.geminiThoughts!),
863
879
  /**
864
880
  * Trimmed and internally normalised: any whitespace run becomes one space.
865
881
  * A label is a workload name, and it is also used as half of structured keys
@@ -1593,6 +1609,97 @@ export function spendByMonth(report: Pick<UsageProfileReport, 'spendByDay' | 'to
1593
1609
  };
1594
1610
  }
1595
1611
 
1612
+ /** The calendar unit a bill is split by. Weeks are ISO weeks: Monday to Sunday, UTC. */
1613
+ export type BillPeriodUnit = 'day' | 'week' | 'month';
1614
+
1615
+ /** One period of a bill, UTC. */
1616
+ export interface PeriodSpend {
1617
+ /** `YYYY-MM-DD` for a day, `YYYY-Www` (ISO) for a week, `YYYY-MM` for a month. */
1618
+ period: string;
1619
+ /** The first and last UTC day of the period, the `--since`/`--until` that bill it alone. */
1620
+ firstDay: string;
1621
+ lastDay: string;
1622
+ calls: number;
1623
+ usd: number;
1624
+ }
1625
+
1626
+ /** A bill by day, week or month, and the part of it that sits in no period. */
1627
+ export interface SpendByPeriod {
1628
+ unit: BillPeriodUnit;
1629
+ /** Oldest first. Only periods with priced, dated calls appear. */
1630
+ periods: PeriodSpend[];
1631
+ /** Priced calls with no clock: in the total and in no period. */
1632
+ undated: { calls: number; usd: number };
1633
+ }
1634
+
1635
+ const isoDay = (ms: number): string => new Date(ms).toISOString().slice(0, 10);
1636
+
1637
+ /** ISO 8601 week of a UTC day: the week belongs to the year of its Thursday. */
1638
+ function isoWeekOf(day: string): { key: string; monday: string; sunday: string } {
1639
+ const ms = Date.parse(`${day}T00:00:00Z`);
1640
+ const weekday = (new Date(ms).getUTCDay() + 6) % 7; // Monday = 0
1641
+ const monday = ms - weekday * 86_400_000;
1642
+ const thursday = new Date(monday + 3 * 86_400_000);
1643
+ const year = thursday.getUTCFullYear();
1644
+ const firstThursday = Date.UTC(year, 0, 4);
1645
+ const firstMonday = firstThursday - ((new Date(firstThursday).getUTCDay() + 6) % 7) * 86_400_000;
1646
+ const week = Math.round((monday - firstMonday) / (7 * 86_400_000)) + 1;
1647
+ return { key: `${year}-W${String(week).padStart(2, '0')}`, monday: isoDay(monday), sunday: isoDay(monday + 6 * 86_400_000) };
1648
+ }
1649
+
1650
+ /**
1651
+ * A bill by calendar day, ISO week or month, summed from the report's own days.
1652
+ *
1653
+ * The same rules as `spendByMonth`, which is this with `month`: UTC, priced
1654
+ * calls with a clock only, and the undated remainder returned beside the
1655
+ * periods so they reconcile to the total. A week is ISO 8601's, Monday to
1656
+ * Sunday, numbered by the year its Thursday falls in, so the last days of
1657
+ * December can belong to week 1 of the next year, as every ISO calendar says.
1658
+ */
1659
+ export function spendByPeriod(
1660
+ report: Pick<UsageProfileReport, 'spendByDay' | 'total'>,
1661
+ unit: BillPeriodUnit,
1662
+ ): SpendByPeriod {
1663
+ const byPeriod = new Map<string, { firstDay: string; lastDay: string; calls: number; usd: number }>();
1664
+ for (const day of report.spendByDay) {
1665
+ let key: string;
1666
+ let firstDay: string;
1667
+ let lastDay: string;
1668
+ if (unit === 'day') {
1669
+ key = day.day;
1670
+ firstDay = day.day;
1671
+ lastDay = day.day;
1672
+ } else if (unit === 'week') {
1673
+ const week = isoWeekOf(day.day);
1674
+ key = week.key;
1675
+ firstDay = week.monday;
1676
+ lastDay = week.sunday;
1677
+ } else {
1678
+ key = day.day.slice(0, 7);
1679
+ const [year, monthNumber] = key.split('-').map(Number);
1680
+ firstDay = `${key}-01`;
1681
+ lastDay = new Date(Date.UTC(year ?? 1970, monthNumber ?? 1, 0)).toISOString().slice(0, 10);
1682
+ }
1683
+ const entry = byPeriod.get(key) ?? { firstDay, lastDay, calls: 0, usd: 0 };
1684
+ entry.calls += day.calls;
1685
+ entry.usd += day.usd;
1686
+ byPeriod.set(key, entry);
1687
+ }
1688
+ const periods = [...byPeriod.entries()]
1689
+ .sort(([, a], [, b]) => a.firstDay.localeCompare(b.firstDay))
1690
+ .map(([period, { firstDay, lastDay, calls, usd }]) => ({ period, firstDay, lastDay, calls, usd }));
1691
+ const dated = periods.reduce((sum, p) => ({ calls: sum.calls + p.calls, usd: sum.usd + p.usd }), { calls: 0, usd: 0 });
1692
+ const undatedCalls = report.total.calls - dated.calls;
1693
+ return {
1694
+ unit,
1695
+ periods,
1696
+ undated:
1697
+ undatedCalls > 0
1698
+ ? { calls: undatedCalls, usd: Math.max(0, report.total.totalUsd - dated.usd) }
1699
+ : { calls: 0, usd: 0 },
1700
+ };
1701
+ }
1702
+
1596
1703
  /**
1597
1704
  * How much of the input that could have been cached was.
1598
1705
  *