dsh-token-usage-ledger 0.0.37 → 0.0.44
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/CHANGELOG.md +88 -0
- package/README.md +16 -10
- package/lib/client.js +1731 -568
- package/lib/host/aggregate.js +566 -0
- package/lib/host/backfill.d.ts +14 -0
- package/lib/host/backfill.js +30 -2
- package/lib/host/collector.d.ts +54 -3
- package/lib/host/collector.js +289 -10
- package/lib/host/ledger-io.d.ts +28 -1
- package/lib/host/ledger-io.js +54 -4
- package/lib/host/records.d.ts +18 -0
- package/lib/host/records.js +143 -1
- package/lib/host/schema.js +167 -2
- package/lib/index.d.ts +1 -1
- package/lib/index.js +12 -7
- package/lib/shared/format.d.ts +19 -1
- package/lib/shared/format.js +70 -1
- package/lib/shared/protocol.d.ts +277 -3
- package/lib/shared/protocol.js +9 -2
- package/package.json +1 -1
package/lib/host/ledger-io.js
CHANGED
|
@@ -13,6 +13,34 @@ import { readFile } from 'node:fs/promises';
|
|
|
13
13
|
import { BACKUP_FORMAT, BACKUP_FORMAT_VERSION, BACKUP_LIMITS, RECORD_SCHEMA_VERSION, } from '../shared/protocol.js';
|
|
14
14
|
import { OperationError } from './operation-error.js';
|
|
15
15
|
import { parseRecordLine, readRecordValue } from './schema.js';
|
|
16
|
+
/**
|
|
17
|
+
* Collapse repeated `(sessionId, turn)` lines, keeping the newest one.
|
|
18
|
+
*
|
|
19
|
+
* The ledger is append-only, so an enriched v1 record is followed by its v2
|
|
20
|
+
* upgrade. The dashboard reader already applies newest-wins; a backup must use
|
|
21
|
+
* the same rule, otherwise a restore would keep the older line and silently
|
|
22
|
+
* drop the v2 fields. The position of the first occurrence is preserved so the
|
|
23
|
+
* exported order still reads chronologically.
|
|
24
|
+
*
|
|
25
|
+
* @param records - records in file order (oldest first).
|
|
26
|
+
* @returns unique records, newest content per key.
|
|
27
|
+
*/
|
|
28
|
+
export function dedupeRecordsNewest(records) {
|
|
29
|
+
const byKey = new Map();
|
|
30
|
+
const unique = [];
|
|
31
|
+
for (const record of records) {
|
|
32
|
+
const key = recordKey(record);
|
|
33
|
+
const index = byKey.get(key);
|
|
34
|
+
if (index === undefined) {
|
|
35
|
+
byKey.set(key, unique.length);
|
|
36
|
+
unique.push(record);
|
|
37
|
+
}
|
|
38
|
+
else {
|
|
39
|
+
unique[index] = record;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
return unique;
|
|
43
|
+
}
|
|
16
44
|
/**
|
|
17
45
|
* Stable idempotency key for one turn.
|
|
18
46
|
* @param record - ledger record.
|
|
@@ -94,9 +122,13 @@ export async function readLedgerFile(path) {
|
|
|
94
122
|
*/
|
|
95
123
|
export async function readLedgerKeys(path) {
|
|
96
124
|
const read = await readLedgerFile(path);
|
|
125
|
+
const recordsByKey = new Map();
|
|
126
|
+
for (const record of read.records)
|
|
127
|
+
recordsByKey.set(recordKey(record), record);
|
|
97
128
|
return {
|
|
98
129
|
keys: new Set(read.records.map(recordKey)),
|
|
99
130
|
fingerprints: new Set(read.records.map(fingerprintOf)),
|
|
131
|
+
recordsByKey,
|
|
100
132
|
malformedLines: read.malformedLines,
|
|
101
133
|
unsupportedRecords: read.unsupportedRecords,
|
|
102
134
|
};
|
|
@@ -109,14 +141,18 @@ export async function readLedgerKeys(path) {
|
|
|
109
141
|
*/
|
|
110
142
|
export async function createBackup(path, pluginVersion) {
|
|
111
143
|
const read = await readLedgerFile(path);
|
|
144
|
+
// Enrichment appends a v2 line with the same key as its v1 source. A backup
|
|
145
|
+
// is a RESTORE artifact, so it must carry one record per Turn — the newest —
|
|
146
|
+
// or restoring into an empty ledger would silently lose the v2 fields.
|
|
147
|
+
const records = dedupeRecordsNewest(read.records);
|
|
112
148
|
return {
|
|
113
149
|
format: BACKUP_FORMAT,
|
|
114
150
|
formatVersion: BACKUP_FORMAT_VERSION,
|
|
115
151
|
exportedAt: Date.now(),
|
|
116
152
|
pluginVersion,
|
|
117
153
|
recordSchemaVersion: RECORD_SCHEMA_VERSION,
|
|
118
|
-
recordCount:
|
|
119
|
-
records
|
|
154
|
+
recordCount: records.length,
|
|
155
|
+
records,
|
|
120
156
|
malformedLines: read.malformedLines,
|
|
121
157
|
unsupportedRecords: read.unsupportedRecords,
|
|
122
158
|
};
|
|
@@ -171,13 +207,21 @@ export function parseBackup(value) {
|
|
|
171
207
|
}
|
|
172
208
|
/**
|
|
173
209
|
* Select records that are not already present (and de-duplicate the file itself).
|
|
174
|
-
*
|
|
210
|
+
*
|
|
211
|
+
* A backup produced by an older build (or a hand-edited file) may still contain
|
|
212
|
+
* two lines for one Turn. The import keeps the LAST one, mirroring the ledger
|
|
213
|
+
* reader's newest-wins rule, so a v2 upgrade is never displaced by its older v1
|
|
214
|
+
* source. Internal duplicates are counted in `duplicates`, like duplicates
|
|
215
|
+
* already present in the target ledger.
|
|
216
|
+
*
|
|
217
|
+
* @param records - validated records from the backup, in file order.
|
|
175
218
|
* @param existing - duplicate-tracking view of the current ledger.
|
|
176
219
|
* @returns new records and the duplicate count.
|
|
177
220
|
*/
|
|
178
221
|
export function selectNewRecords(records, existing) {
|
|
179
222
|
const seen = new Set(existing.keys);
|
|
180
223
|
const fresh = [];
|
|
224
|
+
const freshIndex = new Map();
|
|
181
225
|
let duplicates = 0;
|
|
182
226
|
for (const record of records) {
|
|
183
227
|
const key = recordKey(record);
|
|
@@ -185,7 +229,13 @@ export function selectNewRecords(records, existing) {
|
|
|
185
229
|
duplicates += 1;
|
|
186
230
|
continue;
|
|
187
231
|
}
|
|
188
|
-
|
|
232
|
+
const earlier = freshIndex.get(key);
|
|
233
|
+
if (earlier !== undefined) {
|
|
234
|
+
fresh[earlier] = record;
|
|
235
|
+
duplicates += 1;
|
|
236
|
+
continue;
|
|
237
|
+
}
|
|
238
|
+
freshIndex.set(key, fresh.length);
|
|
189
239
|
fresh.push(record);
|
|
190
240
|
}
|
|
191
241
|
return { records: fresh, duplicates };
|
package/lib/host/records.d.ts
CHANGED
|
@@ -45,3 +45,21 @@ export declare function workspaceLabelOf(workspace: string): string;
|
|
|
45
45
|
* @returns the immutable record to append.
|
|
46
46
|
*/
|
|
47
47
|
export declare function buildRecord(outcome: TurnOutcome, context: RecordContext, rule: PricingRule): UsageRecord;
|
|
48
|
+
/**
|
|
49
|
+
* Fill v2 timing/activity fields into an existing record from a replayed Turn.
|
|
50
|
+
*
|
|
51
|
+
* This is the ONLY path that may touch an already-written record, and it is
|
|
52
|
+
* deliberately additive: token counts, prices, identity, timestamps, reason and
|
|
53
|
+
* routes are never read from the replay. It is used by the backfill scanner to
|
|
54
|
+
* upgrade v1 history when the original session log still exists.
|
|
55
|
+
*
|
|
56
|
+
* Alignment is strict: the old and replayed attempts must have the same length
|
|
57
|
+
* and the same `(at, total, provider, model)` tuple at every index. If anything
|
|
58
|
+
* disagrees, the whole Turn is skipped — a partial merge could mis-attribute a
|
|
59
|
+
* latency to the wrong call.
|
|
60
|
+
*
|
|
61
|
+
* @param existing - canonical record already in the ledger (v1 or v2).
|
|
62
|
+
* @param outcome - the same Turn replayed from its durable log.
|
|
63
|
+
* @returns an upgraded record, or undefined when there is nothing safe to add.
|
|
64
|
+
*/
|
|
65
|
+
export declare function mergeRecordExtras(existing: UsageRecord, outcome: TurnOutcome): UsageRecord | undefined;
|
package/lib/host/records.js
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
* @module dsh-token-usage-ledger/host/records
|
|
10
10
|
*/
|
|
11
11
|
import { basename } from 'node:path';
|
|
12
|
-
import { RECORD_SCHEMA_VERSION } from '../shared/protocol.js';
|
|
12
|
+
import { RECORD_SCHEMA_VERSION, } from '../shared/protocol.js';
|
|
13
13
|
import { priceAttempt } from './pricing.js';
|
|
14
14
|
/**
|
|
15
15
|
* Derive a short, stable display label for a workspace path.
|
|
@@ -28,6 +28,33 @@ export function workspaceLabelOf(workspace) {
|
|
|
28
28
|
return workspace;
|
|
29
29
|
return basename(trimmed) || trimmed;
|
|
30
30
|
}
|
|
31
|
+
/**
|
|
32
|
+
* Copy the optional v2 timing facts from one collected attempt.
|
|
33
|
+
*
|
|
34
|
+
* Kept as a spread helper so a missing field is genuinely absent from the JSON
|
|
35
|
+
* (not `undefined`, not 0): v1 clients/readers must see "unknown".
|
|
36
|
+
*
|
|
37
|
+
* @param attempt - collected attempt.
|
|
38
|
+
* @returns the optional fields to merge into a ledger attempt.
|
|
39
|
+
*/
|
|
40
|
+
function timingFieldsOf(attempt) {
|
|
41
|
+
return {
|
|
42
|
+
step: attempt.step,
|
|
43
|
+
startedAt: attempt.startedAt,
|
|
44
|
+
settledBy: attempt.settledBy,
|
|
45
|
+
reportedCacheRead: attempt.reportedCacheRead,
|
|
46
|
+
reportedCacheWrite: attempt.reportedCacheWrite,
|
|
47
|
+
reportedReasoning: attempt.reportedReasoning,
|
|
48
|
+
...(attempt.firstTokenAt === undefined ? {} : { firstTokenAt: attempt.firstTokenAt }),
|
|
49
|
+
...(attempt.ttftMs === undefined ? {} : { ttftMs: attempt.ttftMs }),
|
|
50
|
+
...(attempt.decodeMs === undefined ? {} : { decodeMs: attempt.decodeMs }),
|
|
51
|
+
...(attempt.durationMs === undefined ? {} : { durationMs: attempt.durationMs }),
|
|
52
|
+
...(attempt.tokensPerSecond === undefined
|
|
53
|
+
? {}
|
|
54
|
+
: { tokensPerSecond: attempt.tokensPerSecond }),
|
|
55
|
+
...(attempt.interrupted === true ? { interrupted: true } : {}),
|
|
56
|
+
};
|
|
57
|
+
}
|
|
31
58
|
/**
|
|
32
59
|
* Build the ledger line for one completed Turn.
|
|
33
60
|
*
|
|
@@ -78,6 +105,7 @@ export function buildRecord(outcome, context, rule) {
|
|
|
78
105
|
? {}
|
|
79
106
|
: { pricedBy: priced.effectiveFrom }),
|
|
80
107
|
window: priced?.window ?? 'unknown',
|
|
108
|
+
...timingFieldsOf(attempt),
|
|
81
109
|
});
|
|
82
110
|
estimatedReason ??= attemptEstimated
|
|
83
111
|
? (priced?.estimatedReason ?? 'no-price-row')
|
|
@@ -111,6 +139,120 @@ export function buildRecord(outcome, context, rule) {
|
|
|
111
139
|
estimated,
|
|
112
140
|
...(estimatedReason === undefined ? {} : { estimatedReason }),
|
|
113
141
|
},
|
|
142
|
+
...(outcome.tools.length === 0 ? {} : { tools: outcome.tools.map((tool) => ({ ...tool })) }),
|
|
143
|
+
...(outcome.retries === 0 ? {} : { retries: outcome.retries }),
|
|
144
|
+
...(outcome.retryCodes.length === 0 ? {} : { retryCodes: [...outcome.retryCodes] }),
|
|
145
|
+
...(outcome.interrupted ? { interrupted: true } : {}),
|
|
146
|
+
};
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Fill v2 timing/activity fields into an existing record from a replayed Turn.
|
|
150
|
+
*
|
|
151
|
+
* This is the ONLY path that may touch an already-written record, and it is
|
|
152
|
+
* deliberately additive: token counts, prices, identity, timestamps, reason and
|
|
153
|
+
* routes are never read from the replay. It is used by the backfill scanner to
|
|
154
|
+
* upgrade v1 history when the original session log still exists.
|
|
155
|
+
*
|
|
156
|
+
* Alignment is strict: the old and replayed attempts must have the same length
|
|
157
|
+
* and the same `(at, total, provider, model)` tuple at every index. If anything
|
|
158
|
+
* disagrees, the whole Turn is skipped — a partial merge could mis-attribute a
|
|
159
|
+
* latency to the wrong call.
|
|
160
|
+
*
|
|
161
|
+
* @param existing - canonical record already in the ledger (v1 or v2).
|
|
162
|
+
* @param outcome - the same Turn replayed from its durable log.
|
|
163
|
+
* @returns an upgraded record, or undefined when there is nothing safe to add.
|
|
164
|
+
*/
|
|
165
|
+
export function mergeRecordExtras(existing, outcome) {
|
|
166
|
+
if (existing.attempts.length !== outcome.attempts.length)
|
|
167
|
+
return undefined;
|
|
168
|
+
let changed = false;
|
|
169
|
+
const attempts = existing.attempts.map((attempt, index) => {
|
|
170
|
+
const collected = outcome.attempts[index];
|
|
171
|
+
if (collected === undefined)
|
|
172
|
+
return attempt;
|
|
173
|
+
if (attempt.at !== collected.at ||
|
|
174
|
+
attempt.total !== collected.total ||
|
|
175
|
+
attempt.provider !== collected.provider ||
|
|
176
|
+
attempt.model !== collected.model) {
|
|
177
|
+
return attempt;
|
|
178
|
+
}
|
|
179
|
+
const next = { ...attempt };
|
|
180
|
+
if (next.step === undefined && collected.step !== undefined) {
|
|
181
|
+
next.step = collected.step;
|
|
182
|
+
changed = true;
|
|
183
|
+
}
|
|
184
|
+
if (next.startedAt === undefined) {
|
|
185
|
+
next.startedAt = collected.startedAt;
|
|
186
|
+
changed = true;
|
|
187
|
+
}
|
|
188
|
+
if (next.firstTokenAt === undefined && collected.firstTokenAt !== undefined) {
|
|
189
|
+
next.firstTokenAt = collected.firstTokenAt;
|
|
190
|
+
changed = true;
|
|
191
|
+
}
|
|
192
|
+
if (next.ttftMs === undefined && collected.ttftMs !== undefined) {
|
|
193
|
+
next.ttftMs = collected.ttftMs;
|
|
194
|
+
changed = true;
|
|
195
|
+
}
|
|
196
|
+
if (next.decodeMs === undefined && collected.decodeMs !== undefined) {
|
|
197
|
+
next.decodeMs = collected.decodeMs;
|
|
198
|
+
changed = true;
|
|
199
|
+
}
|
|
200
|
+
if (next.durationMs === undefined && collected.durationMs !== undefined) {
|
|
201
|
+
next.durationMs = collected.durationMs;
|
|
202
|
+
changed = true;
|
|
203
|
+
}
|
|
204
|
+
if (next.tokensPerSecond === undefined && collected.tokensPerSecond !== undefined) {
|
|
205
|
+
next.tokensPerSecond = collected.tokensPerSecond;
|
|
206
|
+
changed = true;
|
|
207
|
+
}
|
|
208
|
+
if (next.settledBy === undefined) {
|
|
209
|
+
next.settledBy = collected.settledBy;
|
|
210
|
+
changed = true;
|
|
211
|
+
}
|
|
212
|
+
if (next.interrupted === undefined && collected.interrupted === true) {
|
|
213
|
+
next.interrupted = true;
|
|
214
|
+
changed = true;
|
|
215
|
+
}
|
|
216
|
+
if (next.reportedCacheRead === undefined) {
|
|
217
|
+
next.reportedCacheRead = collected.reportedCacheRead;
|
|
218
|
+
changed = true;
|
|
219
|
+
}
|
|
220
|
+
if (next.reportedCacheWrite === undefined) {
|
|
221
|
+
next.reportedCacheWrite = collected.reportedCacheWrite;
|
|
222
|
+
changed = true;
|
|
223
|
+
}
|
|
224
|
+
if (next.reportedReasoning === undefined) {
|
|
225
|
+
next.reportedReasoning = collected.reportedReasoning;
|
|
226
|
+
changed = true;
|
|
227
|
+
}
|
|
228
|
+
return next;
|
|
229
|
+
});
|
|
230
|
+
// A mismatch in one attempt does not make the whole record unmergeable: the
|
|
231
|
+
// record-level fields (tools/retries) are still safe and useful. Attempt
|
|
232
|
+
// fields are only upgraded for the indices that matched.
|
|
233
|
+
const nextRecord = {
|
|
234
|
+
...existing,
|
|
235
|
+
v: RECORD_SCHEMA_VERSION,
|
|
236
|
+
attempts,
|
|
237
|
+
...(existing.tools !== undefined || outcome.tools.length === 0
|
|
238
|
+
? {}
|
|
239
|
+
: { tools: outcome.tools.map((tool) => ({ ...tool })) }),
|
|
240
|
+
...(existing.retries !== undefined || outcome.retries === 0
|
|
241
|
+
? {}
|
|
242
|
+
: { retries: outcome.retries }),
|
|
243
|
+
...(existing.retryCodes !== undefined || outcome.retryCodes.length === 0
|
|
244
|
+
? {}
|
|
245
|
+
: { retryCodes: [...outcome.retryCodes] }),
|
|
246
|
+
...(existing.interrupted !== undefined || !outcome.interrupted ? {} : { interrupted: true }),
|
|
114
247
|
};
|
|
248
|
+
if (nextRecord.tools !== undefined && existing.tools === undefined)
|
|
249
|
+
changed = true;
|
|
250
|
+
if (nextRecord.retries !== undefined && existing.retries === undefined)
|
|
251
|
+
changed = true;
|
|
252
|
+
if (nextRecord.retryCodes !== undefined && existing.retryCodes === undefined)
|
|
253
|
+
changed = true;
|
|
254
|
+
if (nextRecord.interrupted === true && existing.interrupted === undefined)
|
|
255
|
+
changed = true;
|
|
256
|
+
return changed ? nextRecord : undefined;
|
|
115
257
|
}
|
|
116
258
|
//# sourceMappingURL=records.js.map
|
package/lib/host/schema.js
CHANGED
|
@@ -28,7 +28,7 @@ import { isCurrency, RECORD_SCHEMA_VERSION } from '../shared/protocol.js';
|
|
|
28
28
|
*
|
|
29
29
|
* Ordered oldest-first. `RECORD_SCHEMA_VERSION` must always appear here.
|
|
30
30
|
*/
|
|
31
|
-
export const READABLE_RECORD_VERSIONS = [1];
|
|
31
|
+
export const READABLE_RECORD_VERSIONS = [1, 2];
|
|
32
32
|
/**
|
|
33
33
|
* Parse one ledger line.
|
|
34
34
|
*
|
|
@@ -72,6 +72,7 @@ export function readRecordValue(value) {
|
|
|
72
72
|
/** Reader table, keyed by the version the LINE declares. */
|
|
73
73
|
const READERS = {
|
|
74
74
|
1: readVersion1,
|
|
75
|
+
2: readVersion2,
|
|
75
76
|
};
|
|
76
77
|
/**
|
|
77
78
|
* Reader for schema version 1.
|
|
@@ -112,7 +113,171 @@ function readVersion1(raw) {
|
|
|
112
113
|
return undefined;
|
|
113
114
|
const label = typeof raw['workspaceLabel'] === 'string' ? raw['workspaceLabel'] : raw['workspace'];
|
|
114
115
|
const record = { ...raw, workspaceLabel: label };
|
|
115
|
-
return record;
|
|
116
|
+
return sanitizeOptionalRecord(record);
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Reader for schema version 2.
|
|
120
|
+
*
|
|
121
|
+
* v2 adds only optional fields. The core shape is exactly v1's, so this reader
|
|
122
|
+
* reuses that validation and then CLEANS the optional fields: a malformed
|
|
123
|
+
* timing value is dropped instead of rejecting the whole Turn. That asymmetry is
|
|
124
|
+
* deliberate — the token/cost facts are still exact and useful even when one
|
|
125
|
+
* optional timing probe is unusable.
|
|
126
|
+
*
|
|
127
|
+
* @param raw - the parsed line.
|
|
128
|
+
* @returns the canonical record, or undefined when the core shape is unusable.
|
|
129
|
+
*/
|
|
130
|
+
function readVersion2(raw) {
|
|
131
|
+
return readVersion1(raw);
|
|
132
|
+
}
|
|
133
|
+
/** Read a finite, non-negative number, or undefined. */
|
|
134
|
+
function optionalCount(value) {
|
|
135
|
+
if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
|
|
136
|
+
return undefined;
|
|
137
|
+
return value;
|
|
138
|
+
}
|
|
139
|
+
/** Read a non-negative safe integer, or undefined. */
|
|
140
|
+
function optionalInteger(value) {
|
|
141
|
+
if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
|
|
142
|
+
return undefined;
|
|
143
|
+
return value;
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* Drop unusable v2 fields from one attempt without touching the v1 core.
|
|
147
|
+
* @param attempt - validated attempt.
|
|
148
|
+
* @returns a shallow copy with bad optional fields removed.
|
|
149
|
+
*/
|
|
150
|
+
function sanitizeAttempt(attempt) {
|
|
151
|
+
const next = { ...attempt };
|
|
152
|
+
const step = optionalInteger(next.step);
|
|
153
|
+
if (step === undefined)
|
|
154
|
+
delete next.step;
|
|
155
|
+
else
|
|
156
|
+
next.step = step;
|
|
157
|
+
const startedAt = optionalCount(next.startedAt);
|
|
158
|
+
if (startedAt === undefined)
|
|
159
|
+
delete next.startedAt;
|
|
160
|
+
else
|
|
161
|
+
next.startedAt = startedAt;
|
|
162
|
+
const firstTokenAt = optionalCount(next.firstTokenAt);
|
|
163
|
+
if (firstTokenAt === undefined)
|
|
164
|
+
delete next.firstTokenAt;
|
|
165
|
+
else
|
|
166
|
+
next.firstTokenAt = firstTokenAt;
|
|
167
|
+
const ttftMs = optionalCount(next.ttftMs);
|
|
168
|
+
if (ttftMs === undefined)
|
|
169
|
+
delete next.ttftMs;
|
|
170
|
+
else
|
|
171
|
+
next.ttftMs = ttftMs;
|
|
172
|
+
const decodeMs = optionalCount(next.decodeMs);
|
|
173
|
+
if (decodeMs === undefined)
|
|
174
|
+
delete next.decodeMs;
|
|
175
|
+
else
|
|
176
|
+
next.decodeMs = decodeMs;
|
|
177
|
+
const durationMs = optionalCount(next.durationMs);
|
|
178
|
+
if (durationMs === undefined)
|
|
179
|
+
delete next.durationMs;
|
|
180
|
+
else
|
|
181
|
+
next.durationMs = durationMs;
|
|
182
|
+
const rate = optionalCount(next.tokensPerSecond);
|
|
183
|
+
if (rate === undefined)
|
|
184
|
+
delete next.tokensPerSecond;
|
|
185
|
+
else
|
|
186
|
+
next.tokensPerSecond = rate;
|
|
187
|
+
if (next.settledBy !== 'message' &&
|
|
188
|
+
next.settledBy !== 'attempt' &&
|
|
189
|
+
next.settledBy !== 'retry' &&
|
|
190
|
+
next.settledBy !== 'step-end') {
|
|
191
|
+
delete next.settledBy;
|
|
192
|
+
}
|
|
193
|
+
if (next.interrupted !== undefined && typeof next.interrupted !== 'boolean')
|
|
194
|
+
delete next.interrupted;
|
|
195
|
+
if (next.reportedCacheRead !== undefined &&
|
|
196
|
+
typeof next.reportedCacheRead !== 'boolean') {
|
|
197
|
+
delete next.reportedCacheRead;
|
|
198
|
+
}
|
|
199
|
+
if (next.reportedCacheWrite !== undefined &&
|
|
200
|
+
typeof next.reportedCacheWrite !== 'boolean') {
|
|
201
|
+
delete next.reportedCacheWrite;
|
|
202
|
+
}
|
|
203
|
+
if (next.reportedReasoning !== undefined &&
|
|
204
|
+
typeof next.reportedReasoning !== 'boolean') {
|
|
205
|
+
delete next.reportedReasoning;
|
|
206
|
+
}
|
|
207
|
+
return next;
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* Sanitize one tool row.
|
|
211
|
+
* @param value - raw row.
|
|
212
|
+
* @returns the row, or undefined when there is no usable name/count.
|
|
213
|
+
*/
|
|
214
|
+
function sanitizeTool(value) {
|
|
215
|
+
if (typeof value !== 'object' || value === null || Array.isArray(value))
|
|
216
|
+
return undefined;
|
|
217
|
+
const raw = value;
|
|
218
|
+
const name = typeof raw['name'] === 'string' ? raw['name'].trim().slice(0, 100) : '';
|
|
219
|
+
if (name.length === 0)
|
|
220
|
+
return undefined;
|
|
221
|
+
const calls = optionalInteger(raw['calls']);
|
|
222
|
+
const results = optionalInteger(raw['results']);
|
|
223
|
+
const errors = optionalInteger(raw['errors']);
|
|
224
|
+
const durationMs = optionalCount(raw['durationMs']);
|
|
225
|
+
if (calls === undefined || results === undefined || errors === undefined || durationMs === undefined) {
|
|
226
|
+
return undefined;
|
|
227
|
+
}
|
|
228
|
+
return { name, calls, results, errors, durationMs };
|
|
229
|
+
}
|
|
230
|
+
/**
|
|
231
|
+
* Clean the optional v2 fields on a canonical record.
|
|
232
|
+
*
|
|
233
|
+
* Unknown extra properties from a hand-edited line are ignored rather than
|
|
234
|
+
* copied, so a typo can never become a rendered number.
|
|
235
|
+
*
|
|
236
|
+
* @param record - canonical record.
|
|
237
|
+
* @returns the same record with sanitized optional fields.
|
|
238
|
+
*/
|
|
239
|
+
function sanitizeOptionalRecord(record) {
|
|
240
|
+
const next = { ...record };
|
|
241
|
+
next.attempts = next.attempts.map(sanitizeAttempt);
|
|
242
|
+
if (Array.isArray(next.tools)) {
|
|
243
|
+
const tools = next.tools.map(sanitizeTool).filter((tool) => tool !== undefined);
|
|
244
|
+
if (tools.length > 0)
|
|
245
|
+
next.tools = tools.slice(0, 200);
|
|
246
|
+
else
|
|
247
|
+
delete next.tools;
|
|
248
|
+
}
|
|
249
|
+
else {
|
|
250
|
+
delete next.tools;
|
|
251
|
+
}
|
|
252
|
+
if (next.retries !== undefined) {
|
|
253
|
+
const retries = optionalInteger(next.retries);
|
|
254
|
+
if (retries === undefined)
|
|
255
|
+
delete next.retries;
|
|
256
|
+
else
|
|
257
|
+
next.retries = retries;
|
|
258
|
+
}
|
|
259
|
+
if (Array.isArray(next.retryCodes)) {
|
|
260
|
+
const codes = [];
|
|
261
|
+
for (const value of next.retryCodes) {
|
|
262
|
+
if (typeof value !== 'string')
|
|
263
|
+
continue;
|
|
264
|
+
const code = value.trim().slice(0, 40);
|
|
265
|
+
if (code.length > 0 && !codes.includes(code))
|
|
266
|
+
codes.push(code);
|
|
267
|
+
if (codes.length >= 20)
|
|
268
|
+
break;
|
|
269
|
+
}
|
|
270
|
+
if (codes.length > 0)
|
|
271
|
+
next.retryCodes = codes;
|
|
272
|
+
else
|
|
273
|
+
delete next.retryCodes;
|
|
274
|
+
}
|
|
275
|
+
else {
|
|
276
|
+
delete next.retryCodes;
|
|
277
|
+
}
|
|
278
|
+
if (next.interrupted !== undefined && typeof next.interrupted !== 'boolean')
|
|
279
|
+
delete next.interrupted;
|
|
280
|
+
return next;
|
|
116
281
|
}
|
|
117
282
|
/**
|
|
118
283
|
* Report whether a value is a token bucket set with numeric buckets.
|
package/lib/index.d.ts
CHANGED
|
@@ -29,7 +29,7 @@ export declare const name = "token-usage";
|
|
|
29
29
|
* Plugin version, kept in sync with `package.json` by
|
|
30
30
|
* `tests/manifest.test.mjs`.
|
|
31
31
|
*/
|
|
32
|
-
export declare const PLUGIN_VERSION = "0.0.
|
|
32
|
+
export declare const PLUGIN_VERSION = "0.0.44";
|
|
33
33
|
/** Settings after normalization; every field has a usable default. */
|
|
34
34
|
export interface PluginSettings {
|
|
35
35
|
/** Ledger directory; `undefined` means `<dsh home>/token-usage`. */
|
package/lib/index.js
CHANGED
|
@@ -38,7 +38,7 @@ export const name = 'token-usage';
|
|
|
38
38
|
* Plugin version, kept in sync with `package.json` by
|
|
39
39
|
* `tests/manifest.test.mjs`.
|
|
40
40
|
*/
|
|
41
|
-
export const PLUGIN_VERSION = '0.0.
|
|
41
|
+
export const PLUGIN_VERSION = '0.0.44';
|
|
42
42
|
/** Default route prefix for the browser-facing JSON endpoint. */
|
|
43
43
|
const DEFAULT_API_PATH = '/dsh-token-usage';
|
|
44
44
|
/**
|
|
@@ -359,14 +359,19 @@ export function apply(ctx, rawConfig) {
|
|
|
359
359
|
},
|
|
360
360
|
});
|
|
361
361
|
let written = 0;
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
362
|
+
let enriched = 0;
|
|
363
|
+
if (!dryRun) {
|
|
364
|
+
const append = [...outcome.records, ...outcome.upgrades];
|
|
365
|
+
if (append.length > 0) {
|
|
366
|
+
const appended = await store.appendRecords(append);
|
|
367
|
+
if (appended.written !== append.length) {
|
|
368
|
+
throw new OperationError(500, 'write-failed', 'could not append backfilled records');
|
|
369
|
+
}
|
|
370
|
+
written = outcome.records.length;
|
|
371
|
+
enriched = outcome.upgrades.length;
|
|
366
372
|
}
|
|
367
|
-
written = appended.written;
|
|
368
373
|
}
|
|
369
|
-
return { dryRun, written, report: outcome.report };
|
|
374
|
+
return { dryRun, written, enriched, report: outcome.report };
|
|
370
375
|
});
|
|
371
376
|
// The dashboard route is registered through `ctx.inject` rather than read
|
|
372
377
|
// eagerly with `ctx.get`: the web server is contributed by another row, and
|
package/lib/shared/format.d.ts
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
*
|
|
8
8
|
* @module dsh-token-usage-ledger/client/format
|
|
9
9
|
*/
|
|
10
|
-
import { type Currency, type DailyPoint, type TokenBuckets } from './protocol.js';
|
|
10
|
+
import { type Currency, type DailyPoint, type TimingTotals, type TokenBuckets } from './protocol.js';
|
|
11
11
|
/** Granularity the bar charts can be grouped at. */
|
|
12
12
|
export type Granularity = 'day' | 'week' | 'month';
|
|
13
13
|
/** One aggregated bar. */
|
|
@@ -34,6 +34,8 @@ export interface BucketPoint {
|
|
|
34
34
|
estimated: boolean;
|
|
35
35
|
/** Why, when every contributing day agrees; `undefined` otherwise. */
|
|
36
36
|
estimatedReason?: string;
|
|
37
|
+
/** Timing/tool counters for the bucket, absent when no day carried v2 data. */
|
|
38
|
+
perf?: TimingTotals;
|
|
37
39
|
}
|
|
38
40
|
/**
|
|
39
41
|
* Compact token count for axes and cards: `1234` → `1.23K`.
|
|
@@ -63,6 +65,22 @@ export declare function formatTokensExact(value: number): string;
|
|
|
63
65
|
* @returns a short display string (`—` for unusable input).
|
|
64
66
|
*/
|
|
65
67
|
export declare function formatDuration(milliseconds: number): string;
|
|
68
|
+
/**
|
|
69
|
+
* Format an output speed for cards and tables.
|
|
70
|
+
*
|
|
71
|
+
* Rounded to one decimal below 100 tok/s and to an integer above it; a
|
|
72
|
+
* missing/zero sample renders as `—` so it can never be read as "0 tok/s".
|
|
73
|
+
*
|
|
74
|
+
* @param tokensPerSecond - output speed.
|
|
75
|
+
* @returns `12.3 tok/s`, `123 tok/s`, or `—`.
|
|
76
|
+
*/
|
|
77
|
+
export declare function formatSpeed(tokensPerSecond: number): string;
|
|
78
|
+
/**
|
|
79
|
+
* Format a 0..1 ratio as a percentage with one decimal.
|
|
80
|
+
* @param ratio - ratio in 0..1.
|
|
81
|
+
* @returns `12.3%`, or `—` when unusable.
|
|
82
|
+
*/
|
|
83
|
+
export declare function formatShare(ratio: number): string;
|
|
66
84
|
/** One adaptive cache-hit-rate axis. */
|
|
67
85
|
export interface CacheRateAxis {
|
|
68
86
|
/** Lower bound (0..1). */
|
package/lib/shared/format.js
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
*
|
|
8
8
|
* @module dsh-token-usage-ledger/client/format
|
|
9
9
|
*/
|
|
10
|
-
import { API_LIMITS } from './protocol.js';
|
|
10
|
+
import { API_LIMITS, } from './protocol.js';
|
|
11
11
|
/** Token amount suffixes. Decimal steps, matching how the models are billed. */
|
|
12
12
|
const TOKEN_UNITS = [
|
|
13
13
|
[1e12, 'T'],
|
|
@@ -76,6 +76,69 @@ export function formatDuration(milliseconds) {
|
|
|
76
76
|
const minutes = wholeMinutes % 60;
|
|
77
77
|
return minutes === 0 ? `${String(hours)}小时` : `${String(hours)}小时${String(minutes)}分`;
|
|
78
78
|
}
|
|
79
|
+
/**
|
|
80
|
+
* Format an output speed for cards and tables.
|
|
81
|
+
*
|
|
82
|
+
* Rounded to one decimal below 100 tok/s and to an integer above it; a
|
|
83
|
+
* missing/zero sample renders as `—` so it can never be read as "0 tok/s".
|
|
84
|
+
*
|
|
85
|
+
* @param tokensPerSecond - output speed.
|
|
86
|
+
* @returns `12.3 tok/s`, `123 tok/s`, or `—`.
|
|
87
|
+
*/
|
|
88
|
+
export function formatSpeed(tokensPerSecond) {
|
|
89
|
+
if (!Number.isFinite(tokensPerSecond) || tokensPerSecond <= 0)
|
|
90
|
+
return '—';
|
|
91
|
+
return `${tokensPerSecond >= 100 ? String(Math.round(tokensPerSecond)) : tokensPerSecond.toFixed(1)} tok/s`;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Format a 0..1 ratio as a percentage with one decimal.
|
|
95
|
+
* @param ratio - ratio in 0..1.
|
|
96
|
+
* @returns `12.3%`, or `—` when unusable.
|
|
97
|
+
*/
|
|
98
|
+
export function formatShare(ratio) {
|
|
99
|
+
if (!Number.isFinite(ratio) || ratio < 0)
|
|
100
|
+
return '—';
|
|
101
|
+
return `${(ratio * 100).toFixed(1)}%`;
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* A fresh timing accumulator for client-side week/month bucketing.
|
|
105
|
+
* @returns zeroed counters.
|
|
106
|
+
*/
|
|
107
|
+
function zeroTimingTotals() {
|
|
108
|
+
return {
|
|
109
|
+
ttftMs: 0,
|
|
110
|
+
ttftSamples: 0,
|
|
111
|
+
decodeMs: 0,
|
|
112
|
+
decodeTokens: 0,
|
|
113
|
+
modelMs: 0,
|
|
114
|
+
modelSamples: 0,
|
|
115
|
+
toolMs: 0,
|
|
116
|
+
toolCalls: 0,
|
|
117
|
+
steps: 0,
|
|
118
|
+
stepSamples: 0,
|
|
119
|
+
calls: 0,
|
|
120
|
+
callsWithTiming: 0,
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* Add one day's timing counters into a bucket.
|
|
125
|
+
* @param target - bucket accumulator.
|
|
126
|
+
* @param add - day counters.
|
|
127
|
+
*/
|
|
128
|
+
function addTimingTotals(target, add) {
|
|
129
|
+
target.ttftMs += add.ttftMs;
|
|
130
|
+
target.ttftSamples += add.ttftSamples;
|
|
131
|
+
target.decodeMs += add.decodeMs;
|
|
132
|
+
target.decodeTokens += add.decodeTokens;
|
|
133
|
+
target.modelMs += add.modelMs;
|
|
134
|
+
target.modelSamples += add.modelSamples;
|
|
135
|
+
target.toolMs += add.toolMs;
|
|
136
|
+
target.toolCalls += add.toolCalls;
|
|
137
|
+
target.steps += add.steps;
|
|
138
|
+
target.stepSamples += add.stepSamples;
|
|
139
|
+
target.calls += add.calls;
|
|
140
|
+
target.callsWithTiming += add.callsWithTiming;
|
|
141
|
+
}
|
|
79
142
|
/**
|
|
80
143
|
* Choose a cache-hit-rate y-axis that keeps tiny differences visible.
|
|
81
144
|
*
|
|
@@ -325,6 +388,7 @@ export function bucketDaily(points, granularity) {
|
|
|
325
388
|
cost: point.cost,
|
|
326
389
|
estimated: point.estimated,
|
|
327
390
|
...(point.estimatedReason === undefined ? {} : { estimatedReason: point.estimatedReason }),
|
|
391
|
+
...(point.perf === undefined ? {} : { perf: { ...point.perf } }),
|
|
328
392
|
}));
|
|
329
393
|
}
|
|
330
394
|
const buckets = [];
|
|
@@ -368,6 +432,11 @@ export function bucketDaily(points, granularity) {
|
|
|
368
432
|
}
|
|
369
433
|
current.estimated = current.estimated || point.estimated;
|
|
370
434
|
current.endDay = point.date;
|
|
435
|
+
if (point.perf !== undefined) {
|
|
436
|
+
const perf = current.perf ?? zeroTimingTotals();
|
|
437
|
+
addTimingTotals(perf, point.perf);
|
|
438
|
+
current.perf = perf;
|
|
439
|
+
}
|
|
371
440
|
}
|
|
372
441
|
for (const bucket of buckets) {
|
|
373
442
|
bucket.longLabel = longLabelForBucket(bucket.key, granularity, bucket.endDay);
|