dsh-token-usage-ledger 0.0.36 → 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.
@@ -8,8 +8,15 @@
8
8
  *
9
9
  * @module dsh-token-usage-ledger/shared/protocol
10
10
  */
11
- /** Bumped whenever the persisted record shape changes incompatibly. */
12
- export declare const RECORD_SCHEMA_VERSION = 1;
11
+ /**
12
+ * Bumped whenever the persisted record shape changes incompatibly.
13
+ *
14
+ * v2 adds only OPTIONAL fields (per-attempt timing and per-turn tool/retry
15
+ * activity) on top of v1, so every v1 line stays readable — see
16
+ * `host/schema.ts`. The line's own `v` decides which reader upgrades it, and
17
+ * readers never invent values for fields the older line did not record.
18
+ */
19
+ export declare const RECORD_SCHEMA_VERSION = 2;
13
20
  /** Bumped whenever the wire summary shape changes incompatibly. */
14
21
  export declare const SUMMARY_SCHEMA_VERSION = 1;
15
22
  /** Currency of the pricing table. The official pages publish both sets independently. */
@@ -71,6 +78,67 @@ export interface UsageAttempt {
71
78
  * row matched at all — claiming a window there would be a fabrication.
72
79
  */
73
80
  window: 'peak' | 'off-peak' | 'unknown';
81
+ /**
82
+ * Step number this attempt belongs to (v2+, optional).
83
+ *
84
+ * One step is one model call plus the tool executions it requested; a retry
85
+ * keeps the same step number while producing a new attempt.
86
+ */
87
+ step?: number;
88
+ /**
89
+ * Local epoch ms when this attempt started waiting for the model (v2+).
90
+ *
91
+ * The first attempt of a step starts at `step/start`; a retried attempt starts
92
+ * at `llm/retry-started`, so the retry wait is not charged to the call.
93
+ */
94
+ startedAt?: number;
95
+ /**
96
+ * Local epoch ms of this attempt's first output token (v2+).
97
+ *
98
+ * Derived from the durable compact stream timestamps; absent when the stream
99
+ * carries no token delta (e.g. a legacy log that stored only the usage chunk).
100
+ */
101
+ firstTokenAt?: number;
102
+ /** `firstTokenAt - startedAt` clamped to `>= 0` (v2+). */
103
+ ttftMs?: number;
104
+ /** `at - firstTokenAt` clamped to `>= 0` (v2+). */
105
+ decodeMs?: number;
106
+ /** `at - startedAt` clamped to `>= 0` (v2+). */
107
+ durationMs?: number;
108
+ /** `tokens.output / decodeMs * 1000`, only when `decodeMs > 0` (v2+). */
109
+ tokensPerSecond?: number;
110
+ /**
111
+ * How this attempt was closed (v2+).
112
+ *
113
+ * `step-end`/`retry` attempts are usually failed calls; only `message`
114
+ * attempts are a step's final reply.
115
+ */
116
+ settledBy?: 'message' | 'attempt' | 'retry' | 'step-end';
117
+ /** True when the settling `assistant/message` was interrupted (v2+). */
118
+ interrupted?: boolean;
119
+ /**
120
+ * Whether the provider explicitly reported the optional cache bucket (v2+).
121
+ *
122
+ * Absent on v1 lines means "unknown", never "not reported".
123
+ */
124
+ reportedCacheRead?: boolean;
125
+ /** Whether the provider explicitly reported the cache-write bucket (v2+). */
126
+ reportedCacheWrite?: boolean;
127
+ /** Whether the provider explicitly reported the reasoning bucket (v2+). */
128
+ reportedReasoning?: boolean;
129
+ }
130
+ /** One tool name aggregated over a Turn (v2+). */
131
+ export interface ToolUsage {
132
+ /** Tool id as reported by the harness (arguments/results are never stored). */
133
+ name: string;
134
+ /** Number of `tool/call` events. */
135
+ calls: number;
136
+ /** Number of matched `tool/result` events. */
137
+ results: number;
138
+ /** Results whose message carried `isError: true`. */
139
+ errors: number;
140
+ /** Sum of `result.time - call.time` over matched results, in ms. */
141
+ durationMs: number;
74
142
  }
75
143
  /** Cost decomposition of one record, frozen at write time so history stays auditable. */
76
144
  export interface CostBreakdown {
@@ -134,6 +202,19 @@ export interface UsageRecord {
134
202
  total: number;
135
203
  /** Priced cost, frozen at write time. */
136
204
  cost: CostBreakdown;
205
+ /**
206
+ * Per-tool-name activity in this Turn (v2+, optional).
207
+ *
208
+ * Only names/counts/durations/statuses are stored; tool arguments and results
209
+ * never reach the ledger.
210
+ */
211
+ tools?: ToolUsage[];
212
+ /** Number of provider-routed retries scheduled in this Turn (v2+). */
213
+ retries?: number;
214
+ /** Stable provider-neutral failure codes observed for those retries (v2+). */
215
+ retryCodes?: string[];
216
+ /** True when any settled assistant message was interrupted (v2+). */
217
+ interrupted?: boolean;
137
218
  }
138
219
  /** One selectable value in a filter control. */
139
220
  export interface Facet {
@@ -189,6 +270,33 @@ export interface WorkspaceFacet extends Facet {
189
270
  /** Number of distinct raw paths in this group (`paths.length`); 1 when unknown. */
190
271
  mergedCount?: number | undefined;
191
272
  }
273
+ /** Timing and tool-activity counters, per day or per chart bucket (v2+). */
274
+ export interface TimingTotals {
275
+ /** Sum of step TTFT values (ms). */
276
+ ttftMs: number;
277
+ /** Steps contributing to {@link ttftMs}. */
278
+ ttftSamples: number;
279
+ /** Sum of step decode durations (ms). */
280
+ decodeMs: number;
281
+ /** Output tokens of the steps contributing to {@link decodeMs}. */
282
+ decodeTokens: number;
283
+ /** Sum of step model durations (`completedAt - startedAt`, ms). */
284
+ modelMs: number;
285
+ /** Steps contributing to {@link modelMs}. */
286
+ modelSamples: number;
287
+ /** Sum of tool-call durations (ms). */
288
+ toolMs: number;
289
+ /** Tool calls counted. */
290
+ toolCalls: number;
291
+ /** Distinct steps counted. */
292
+ steps: number;
293
+ /** Turns contributing step data. */
294
+ stepSamples: number;
295
+ /** Model calls selected by the active filter. */
296
+ calls: number;
297
+ /** Model calls carrying a usable start/first-token pair. */
298
+ callsWithTiming: number;
299
+ }
192
300
  /** Per-day aggregate powering the bar charts and the calendar heatmap. */
193
301
  export interface DailyPoint {
194
302
  /** Local calendar day, `YYYY-MM-DD`. */
@@ -205,6 +313,13 @@ export interface DailyPoint {
205
313
  estimated: boolean;
206
314
  /** Why, when every contributing record agrees; `undefined` otherwise. */
207
315
  estimatedReason?: string;
316
+ /**
317
+ * Timing/tool counters for this day, absent when no v2 timing data exists.
318
+ *
319
+ * Absence is "not recorded", never "zero": a legacy day must not draw a
320
+ * 0 ms TTFT or 0 tok/s point.
321
+ */
322
+ perf?: TimingTotals;
208
323
  }
209
324
  /** Cumulative figures for the active filter, or all-time when unfiltered. */
210
325
  export interface Totals {
@@ -320,6 +435,141 @@ export interface SessionStats {
320
435
  /** Median cost per session. */
321
436
  medianCost: number;
322
437
  }
438
+ /** How much of the current selection actually carries v2 timing data. */
439
+ export interface TimingCoverage {
440
+ /** Selected Turns with at least one attempt carrying timing fields. */
441
+ recordsWithTiming: number;
442
+ /** Selected Turns. */
443
+ records: number;
444
+ /** Selected attempts carrying a usable start/first-token pair. */
445
+ attemptsWithTiming: number;
446
+ /** Selected attempts. */
447
+ attempts: number;
448
+ }
449
+ /**
450
+ * Response-speed and agent-loop activity for the current filter (v2+).
451
+ *
452
+ * Mirrors the harness's own session statistics: TTFT/model time come from the
453
+ * step's first token and completion timestamps, tool time from call/result
454
+ * pairs. Medians are per step/call; averages are token-weighted where marked.
455
+ */
456
+ export interface PerformanceStats {
457
+ /** Median step TTFT in ms. */
458
+ ttftMedian: number;
459
+ /** 90th-percentile step TTFT in ms. */
460
+ ttftP90: number;
461
+ /** Mean step TTFT in ms. */
462
+ ttftAverage: number;
463
+ /** Steps contributing to the TTFT figures. */
464
+ ttftSamples: number;
465
+ /** Median per-step output speed, tok/s. */
466
+ tpsMedian: number;
467
+ /** Arithmetic mean of trusted per-step output speeds, tok/s. */
468
+ tpsAverage: number;
469
+ /** Steps contributing to the output-speed figures. */
470
+ tpsSamples: number;
471
+ /** Sum of step model durations, ms. */
472
+ modelMs: number;
473
+ /** Steps contributing to {@link modelMs}. */
474
+ modelSamples: number;
475
+ /** Sum of tool-call durations, ms. */
476
+ toolMs: number;
477
+ /** Tool calls counted. */
478
+ toolCalls: number;
479
+ /** Tool results that failed. */
480
+ toolErrors: number;
481
+ /** Failures / results, 0..1. */
482
+ toolErrorRate: number;
483
+ /** Distinct steps across the selected Turns. */
484
+ stepsTotal: number;
485
+ /** Turns with at least one step counted. */
486
+ stepSamples: number;
487
+ /** Mean steps per **sampled** Turn (whole-turn activity, not per call). */
488
+ stepsPerTurn: number;
489
+ /** Selected model calls. */
490
+ calls: number;
491
+ /** Model calls carrying timing data. */
492
+ callsWithTiming: number;
493
+ /** Retries scheduled in the selected Turns. */
494
+ retries: number;
495
+ /** Retries / model calls, 0..1. */
496
+ retryRate: number;
497
+ /** Turns whose assistant message was interrupted. */
498
+ interrupted: number;
499
+ /** Coverage caveat: old records have no timing fields. */
500
+ coverage: TimingCoverage;
501
+ }
502
+ /** One provider/model route's response-performance row (v2+). */
503
+ export interface RoutePerformance {
504
+ /** `provider/model` key, the same key the model facet uses. */
505
+ key: string;
506
+ /** Provider id. */
507
+ provider: string;
508
+ /** Model id. */
509
+ model: string;
510
+ /** Calls on this route. */
511
+ calls: number;
512
+ /** Calls with a usable first-token timestamp. */
513
+ timedCalls: number;
514
+ /** Provider-reported output tokens. */
515
+ outputTokens: number;
516
+ /** Median per-call TTFT in ms, 0 when no sample. */
517
+ ttftMedian: number;
518
+ /** Median per-call output speed, tok/s, 0 when no sample. */
519
+ tpsMedian: number;
520
+ /** 10th-percentile per-call output speed, tok/s, 0 when no sample. */
521
+ tpsP10?: number;
522
+ /** 25th-percentile per-call output speed, tok/s, 0 when no sample. */
523
+ tpsP25?: number;
524
+ /** 75th-percentile per-call output speed, tok/s, 0 when no sample. */
525
+ tpsP75?: number;
526
+ /** 90th-percentile per-call output speed, tok/s, 0 when no sample. */
527
+ tpsP90?: number;
528
+ /** Sum of per-call durations, ms. */
529
+ modelMs: number;
530
+ }
531
+ /** Activity in one local weekday/hour cell (v2+); Monday is weekday 0. */
532
+ export interface WeekdayHourUsage {
533
+ /** Monday-first weekday, 0–6. */
534
+ weekday: number;
535
+ /** Local hour, 0–23. */
536
+ hour: number;
537
+ /** Turns started in this cell. */
538
+ turns: number;
539
+ /** Model calls settled in this cell. */
540
+ calls: number;
541
+ /** Provider-reported tokens for those calls. */
542
+ tokens: number;
543
+ /** Priced cost for those calls. */
544
+ cost: number;
545
+ }
546
+ /** One of the most expensive Turns under the active filter (v2+). */
547
+ export interface TurnHighlight {
548
+ /** Stable UI key; contains a short session fingerprint, never the full id. */
549
+ key: string;
550
+ /** Short non-reversible fingerprint of the session id (8 hex chars). */
551
+ sessionKey: string;
552
+ /** Turn number inside that session. */
553
+ turn: number;
554
+ /** Local epoch ms of `turn/end`. */
555
+ ts: number;
556
+ /** Why the Turn ended. */
557
+ reason: string;
558
+ /** Distinct `provider/model` labels separated by `,`. */
559
+ models: string;
560
+ /** Tokens selected by the active filter. */
561
+ tokens: number;
562
+ /** Cost selected by the active filter. */
563
+ cost: number;
564
+ /** Wall-clock duration of the Turn, ms. */
565
+ durationMs: number;
566
+ /** Distinct steps (when v2 data exists). */
567
+ steps?: number;
568
+ /** First step's TTFT, ms (when v2 data exists). */
569
+ ttftMs?: number;
570
+ /** Token-weighted output speed across the Turn's steps, tok/s. */
571
+ tokensPerSecond?: number;
572
+ }
323
573
  /**
324
574
  * Additional statistics derived only from fields already present in the ledger.
325
575
  *
@@ -349,6 +599,22 @@ export interface Analytics {
349
599
  windows: WindowUsage[];
350
600
  /** Local hour-of-day activity (always 24 entries, 0–23). */
351
601
  hours: HourUsage[];
602
+ /** Response speed / model vs tool time (v2+; absent on older Hosts). */
603
+ performance?: PerformanceStats;
604
+ /** Output-speed histogram in tok/s (v2+). */
605
+ speedBins?: CountBin[];
606
+ /** Steps-per-turn histogram (v2+). */
607
+ stepBins?: CountBin[];
608
+ /** Tool-calls-per-turn histogram (v2+). */
609
+ toolBins?: CountBin[];
610
+ /** Per-tool activity, most-called first (v2+). */
611
+ tools?: ToolUsage[];
612
+ /** Per-route response performance, most-called first (v2+). */
613
+ routes?: RoutePerformance[];
614
+ /** Monday-first 7×24 activity grid (v2+). */
615
+ weekHours?: WeekdayHourUsage[];
616
+ /** Most expensive Turns under the active filter (v2+). */
617
+ highlights?: TurnHighlight[];
352
618
  }
353
619
  /** Pricing provenance the dashboard displays so a figure can be traced to its source. */
354
620
  export interface PricingProvenance {
@@ -620,6 +886,12 @@ export interface BackfillReport {
620
886
  turnsFilteredOut: number;
621
887
  /** Turns that can be appended. */
622
888
  turnsBackfillable: number;
889
+ /** Existing Turns whose v2 timing/tool fields can be filled from logs. */
890
+ turnsEnrichable: number;
891
+ /** Existing Turns actually upgraded with new fields. */
892
+ turnsEnriched: number;
893
+ /** Existing Turns that had a log but no new field to add. */
894
+ turnsEnrichSkipped: number;
623
895
  /** First backfillable turn end, ISO string or `''`. */
624
896
  firstTurn: string;
625
897
  /** Last backfillable turn end, ISO string or `''`. */
@@ -629,8 +901,10 @@ export interface BackfillReport {
629
901
  export interface BackfillResult {
630
902
  /** True when nothing was written (preview). */
631
903
  dryRun: boolean;
632
- /** Records actually appended. */
904
+ /** Records actually appended (new Turns only). */
633
905
  written: number;
906
+ /** Existing Turns upgraded with v2 fields (also appended, still one per key). */
907
+ enriched?: number;
634
908
  /** Scan counters. */
635
909
  report: BackfillReport;
636
910
  }
@@ -8,8 +8,15 @@
8
8
  *
9
9
  * @module dsh-token-usage-ledger/shared/protocol
10
10
  */
11
- /** Bumped whenever the persisted record shape changes incompatibly. */
12
- export const RECORD_SCHEMA_VERSION = 1;
11
+ /**
12
+ * Bumped whenever the persisted record shape changes incompatibly.
13
+ *
14
+ * v2 adds only OPTIONAL fields (per-attempt timing and per-turn tool/retry
15
+ * activity) on top of v1, so every v1 line stays readable — see
16
+ * `host/schema.ts`. The line's own `v` decides which reader upgrades it, and
17
+ * readers never invent values for fields the older line did not record.
18
+ */
19
+ export const RECORD_SCHEMA_VERSION = 2;
13
20
  /** Bumped whenever the wire summary shape changes incompatibly. */
14
21
  export const SUMMARY_SCHEMA_VERSION = 1;
15
22
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-token-usage-ledger",
3
- "version": "0.0.36",
3
+ "version": "0.0.44",
4
4
  "description": "Token usage and cost ledger with a dashboard for DeepSeek Harness: per-turn ledger, 365-day heatmap, charts, filters, export/import and backfill.",
5
5
  "type": "module",
6
6
  "main": "lib/index.js",
@@ -21,7 +21,9 @@
21
21
  "cordis.patch.yml",
22
22
  "README.md",
23
23
  "CHANGELOG.md",
24
- "LICENSE"
24
+ "LICENSE",
25
+ "docs/token-usage-image01.png",
26
+ "docs/token-usage-image02.png"
25
27
  ],
26
28
  "dsh": {
27
29
  "bundle": {