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.
@@ -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: read.records.length,
119
- records: read.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
- * @param records - validated records from the backup.
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
- seen.add(key);
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 };
@@ -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;
@@ -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
@@ -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.37";
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.37';
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
- if (!dryRun && outcome.records.length > 0) {
363
- const appended = await store.appendRecords(outcome.records);
364
- if (appended.written !== outcome.records.length) {
365
- throw new OperationError(500, 'write-failed', 'could not append backfilled records');
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
@@ -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). */
@@ -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);