@juanbenjumea/pi-agy 0.7.13 → 0.7.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,115 @@
1
+ /**
2
+ * Native token usage validation, session-cumulative differencing, and
3
+ * Pi `Usage` normalization for Antigravity provider turns.
4
+ *
5
+ * Verified against live `agy --output-format stream-json`:
6
+ * - `input_tokens` excludes `cache_read_tokens`.
7
+ * - `output_tokens` includes `thinking_tokens` (matching Pi's `reasoning` subset).
8
+ * - In persistent `--input-format stream-json` mode, `result.usage` is
9
+ * cumulative across turns in the process session, so consecutive turns
10
+ * subtract the previous committed baseline to avoid double-counting.
11
+ */
12
+
13
+ export interface ValidatedAgyUsage {
14
+ input: number;
15
+ output: number;
16
+ cacheRead: number;
17
+ thinking?: number;
18
+ }
19
+
20
+ export interface NormalizedProviderUsage {
21
+ input: number;
22
+ output: number;
23
+ cacheRead: number;
24
+ cacheWrite: number;
25
+ reasoning?: number;
26
+ totalTokens: number;
27
+ }
28
+
29
+ export const ZERO_USAGE_BASELINE: Readonly<ValidatedAgyUsage> = Object.freeze({
30
+ input: 0,
31
+ output: 0,
32
+ cacheRead: 0,
33
+ thinking: 0,
34
+ });
35
+
36
+ function parseNonNegSafeInt(value: unknown): number | undefined {
37
+ if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
38
+ return undefined;
39
+ }
40
+ return value === 0 ? 0 : value;
41
+ }
42
+
43
+ /**
44
+ * Validate a raw `agy` usage object without coercion, rounding, or clamping.
45
+ * Returns `undefined` when absent or when any recognized own field is invalid.
46
+ */
47
+ export function validateAgyUsage(raw: unknown): ValidatedAgyUsage | undefined {
48
+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return undefined;
49
+ const record = raw as Record<string, unknown>;
50
+
51
+ if (!Object.hasOwn(record, "input_tokens") || !Object.hasOwn(record, "output_tokens")) {
52
+ return undefined;
53
+ }
54
+ const input = parseNonNegSafeInt(record.input_tokens);
55
+ const output = parseNonNegSafeInt(record.output_tokens);
56
+ if (input === undefined || output === undefined) return undefined;
57
+
58
+ let cacheRead = 0;
59
+ if (Object.hasOwn(record, "cache_read_tokens") && record.cache_read_tokens !== undefined) {
60
+ const parsed = parseNonNegSafeInt(record.cache_read_tokens);
61
+ if (parsed === undefined) return undefined;
62
+ cacheRead = parsed;
63
+ }
64
+
65
+ let thinking: number | undefined;
66
+ if (Object.hasOwn(record, "thinking_tokens") && record.thinking_tokens !== undefined) {
67
+ const parsed = parseNonNegSafeInt(record.thinking_tokens);
68
+ if (parsed === undefined) return undefined;
69
+ thinking = parsed;
70
+ }
71
+
72
+ if (Object.hasOwn(record, "total_tokens") && record.total_tokens !== undefined) {
73
+ if (parseNonNegSafeInt(record.total_tokens) === undefined) return undefined;
74
+ }
75
+
76
+ return thinking !== undefined
77
+ ? { input, output, cacheRead, thinking }
78
+ : { input, output, cacheRead };
79
+ }
80
+
81
+ /**
82
+ * Difference a cumulative session usage snapshot against a known same-generation
83
+ * baseline. Returns `undefined` on counter regression or safe-integer overflow.
84
+ */
85
+ export function diffAgyUsage(
86
+ current: ValidatedAgyUsage,
87
+ baseline: ValidatedAgyUsage,
88
+ ): NormalizedProviderUsage | undefined {
89
+ const input = current.input - baseline.input;
90
+ const output = current.output - baseline.output;
91
+ const cacheRead = current.cacheRead - baseline.cacheRead;
92
+ if (input < 0 || output < 0 || cacheRead < 0) return undefined;
93
+
94
+ let reasoning: number | undefined;
95
+ if (current.thinking !== undefined) {
96
+ const baseThinking = baseline.thinking ?? 0;
97
+ const deltaThinking = current.thinking - baseThinking;
98
+ if (deltaThinking < 0) return undefined;
99
+ if (deltaThinking <= output) {
100
+ reasoning = deltaThinking === 0 ? 0 : deltaThinking;
101
+ }
102
+ }
103
+
104
+ const totalTokens = input + output + cacheRead;
105
+ if (!Number.isSafeInteger(totalTokens)) return undefined;
106
+
107
+ return {
108
+ input: input === 0 ? 0 : input,
109
+ output: output === 0 ? 0 : output,
110
+ cacheRead: cacheRead === 0 ? 0 : cacheRead,
111
+ cacheWrite: 0,
112
+ ...(reasoning !== undefined ? { reasoning } : {}),
113
+ totalTokens: totalTokens === 0 ? 0 : totalTokens,
114
+ };
115
+ }