@narumitw/pi-analytics 0.49.9 → 0.49.11

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/README.md CHANGED
@@ -72,8 +72,9 @@ The dashboard includes finalized cycles and omits active work.
72
72
  A **response cycle** starts when Pi begins agent work and normally ends at `agent_settled`.
73
73
  Retries, overflow-compaction recovery, tool follow-ups, and queued continuations before settlement remain in that cycle.
74
74
 
75
- An **LLM call** is one logical provider generation.
75
+ An **LLM call** is one logical provider generation confirmed by an assistant-message lifecycle.
76
76
  A provider can make several HTTP attempts within it, so `429 → 429 → 200` counts as one LLM call, three observed HTTP responses, two provider errors, and one recovered generation.
77
+ Pi cache-warming requests emit provider hooks without an assistant lifecycle; they are excluded from ordinary LLM-call and reliability counts rather than being reported as interrupted generations.
77
78
 
78
79
  ### Skills
79
80
 
@@ -100,18 +101,9 @@ Raw error messages are classified in memory and discarded.
100
101
 
101
102
  ## 💬 Commands
102
103
 
103
- ```text
104
- /analytics
105
- ```
106
-
107
- The command accepts no arguments.
108
- TUI mode shows the full dashboard, and RPC mode adapts the same screens to dialogs.
109
- Print and JSON modes reject the command before reading analytics data.
110
-
111
- The root menu contains Change time range, Skills, Tools, Provider reliability, Response cycles, Data & privacy, and Close.
112
- Skills and Tools provide searchable details and model breakdowns.
113
- Escape goes back from nested screens and closes the root, while Ctrl+C closes the menu.
114
- Deleting data requires confirmation; Back keeps the dashboard open, Ctrl+C closes it in TUI mode, and cancellation leaves data unchanged.
104
+ Run `/analytics` to inspect local usage, skills, tools, and provider reliability over a chosen time range.
105
+ It accepts no arguments and supports TUI and RPC; print and JSON modes reject it before reading analytics data.
106
+ Deleting analytics data requires confirmation, and cancellation leaves data unchanged.
115
107
 
116
108
  ## 🔒 Security and privacy
117
109
 
@@ -178,35 +170,21 @@ Never copy or remove only the main DB while an old process may still own its WAL
178
170
  - Large all-time histories require scanning the active JSONL generation when the dashboard opens.
179
171
  - Prometheus, JSON/CSV export, cloud sync, browser dashboards, token/cost reporting, and project attribution are not included.
180
172
  - Statistics cover only events visible through Pi's public extension API.
173
+ - Dedicated cache-warming observations require an upstream request-kind and completion signal; persisted warming token and cost totals are not imported into analytics.
181
174
 
182
175
  ## 🗂️ Package layout
183
176
 
184
177
  ```text
185
178
  packages/pi-analytics/
186
- ├── dist/ # Generated TypeScript runtime loaded by Jiti
187
- ├── scripts/
188
- │ └── build-runtime.mjs # Deterministic runtime builder and boundary validator
189
- ├── src/
190
- │ ├── index.ts # Thin Pi entrypoint
191
- │ ├── analytics.ts # Pi lifecycle, command, and session ownership
192
- │ ├── collector.ts # Content-free response-cycle state machine
193
- │ ├── errors.ts # Conservative error classification
194
- │ ├── skills.ts # Explicit and model skill detection
195
- │ ├── menu.ts # TUI/RPC analytics dashboard
196
- │ ├── types.ts # Observation records
197
- │ └── storage/
198
- │ ├── files.ts # Private generations, writes, reads, and Clear
199
- │ ├── format.ts # Versioned JSONL codec and validation
200
- │ ├── queries.ts # Incremental aggregate projections
201
- │ └── store.ts # Lifecycle-safe storage facade
202
- ├── test/
203
- ├── README.md
204
- ├── LICENSE
205
- ├── package.json
206
- └── tsconfig.json
179
+ ├── src/ # Authoritative implementation and helpers
180
+ │ ├── index.ts # Thin Pi entrypoint
181
+ │ └── analytics.ts # Collection lifecycle and dashboard command
182
+ ├── dist/ # Generated Jiti runtime
183
+ ├── scripts/build-runtime.mjs # Runtime builder
184
+ └── test/ # Behavior and lifecycle coverage
207
185
  ```
208
186
 
209
- The generated runtime is built from the authoritative `src/index.ts` graph and does not import back into `src`.
187
+ The generated runtime is built from `src/index.ts` and does not import back into `src`.
210
188
 
211
189
  ## 🔎 Keywords
212
190
 
package/dist/index.ts CHANGED
@@ -4,9 +4,7 @@
4
4
  // src/analytics.ts
5
5
  import { randomUUID as randomUUID3 } from "node:crypto";
6
6
  import path3 from "node:path";
7
- import {
8
- getAgentDir
9
- } from "@earendil-works/pi-coding-agent";
7
+ import { getAgentDir } from "@earendil-works/pi-coding-agent";
10
8
 
11
9
  // src/collector.ts
12
10
  import { randomUUID } from "node:crypto";
@@ -180,9 +178,7 @@ var ResponseCollector = class {
180
178
  let recoveredHttpErrors = 0;
181
179
  let httpErrors = 0;
182
180
  for (const [generationIndex, generation] of active.generations.entries()) {
183
- const hasLaterSuccess = [...successfulGenerationIndexes].some(
184
- (index) => index > generationIndex
185
- );
181
+ const hasLaterSuccess = [...successfulGenerationIndexes].some((index) => index > generationIndex);
186
182
  for (const [responseIndex, response] of generation.responses.entries()) {
187
183
  if (response.status < 400) continue;
188
184
  httpErrors += 1;
@@ -195,9 +191,7 @@ var ResponseCollector = class {
195
191
  error.recovered = [...successfulGenerationIndexes].some((index) => index > generationIndex);
196
192
  error.terminal = !error.recovered;
197
193
  }
198
- const recoveredGenerationErrors = active.providerErrors.filter(
199
- ({ recovered }) => recovered
200
- ).length;
194
+ const recoveredGenerationErrors = active.providerErrors.filter(({ recovered }) => recovered).length;
201
195
  const providerErrorCount = httpErrors + active.providerErrors.length;
202
196
  const recoveredErrorCount = recoveredHttpErrors + recoveredGenerationErrors;
203
197
  const outcome = forcedOutcome ?? deriveOutcome(active.generations, providerErrorCount);
@@ -289,9 +283,7 @@ async function querySnapshot(runs, range, signal) {
289
283
  const seenRunIds = /* @__PURE__ */ new Set();
290
284
  const skills = /* @__PURE__ */ new Map();
291
285
  const tools = /* @__PURE__ */ new Map();
292
- const categories = Object.fromEntries(
293
- ERROR_CATEGORIES.map((category) => [category, 0])
294
- );
286
+ const categories = Object.fromEntries(ERROR_CATEGORIES.map((category) => [category, 0]));
295
287
  let toolErrors = 0;
296
288
  let providerErrors = 0;
297
289
  let recoveredErrors = 0;
@@ -407,22 +399,17 @@ function responseStatistics(generationCounts) {
407
399
  };
408
400
  }
409
401
  function mergeModelCount(models, next) {
410
- const existing = models.find(
411
- ({ provider, model }) => provider === next.provider && model === next.model
412
- );
402
+ const existing = models.find(({ provider, model }) => provider === next.provider && model === next.model);
413
403
  if (existing) existing.count += next.count;
414
404
  else models.push(next);
415
405
  }
416
406
  function sortModels(models) {
417
407
  return models.sort(
418
- (left, right) => right.count - left.count || `${left.provider ?? ""}/${left.model ?? ""}`.localeCompare(
419
- `${right.provider ?? ""}/${right.model ?? ""}`
420
- )
408
+ (left, right) => right.count - left.count || `${left.provider ?? ""}/${left.model ?? ""}`.localeCompare(`${right.provider ?? ""}/${right.model ?? ""}`)
421
409
  );
422
410
  }
423
411
  function throwIfAborted(signal) {
424
- if (signal?.aborted)
425
- throw signal.reason ?? new DOMException("Analytics query aborted", "AbortError");
412
+ if (signal?.aborted) throw signal.reason ?? new DOMException("Analytics query aborted", "AbortError");
426
413
  }
427
414
  function sum(values) {
428
415
  return values.reduce((total, value) => total + value, 0);
@@ -616,10 +603,7 @@ function overviewLines(result) {
616
603
  return [
617
604
  metric("Response cycles", stats.responseCycles),
618
605
  metric("LLM calls", stats.llmCalls),
619
- metric(
620
- "Calls per response",
621
- `${formatDecimal(stats.callsPerResponse)} \xB7 P95 ${stats.p95CallsPerResponse}`
622
- ),
606
+ metric("Calls per response", `${formatDecimal(stats.callsPerResponse)} \xB7 P95 ${stats.p95CallsPerResponse}`),
623
607
  metric("Tool calls", stats.toolCalls),
624
608
  metric("Tool errors", stats.toolErrors),
625
609
  metric("Skill activations", stats.skillActivations),
@@ -819,9 +803,7 @@ var SkillTracker = class {
819
803
  if (seenNames.has(skill.name)) continue;
820
804
  seenNames.add(skill.name);
821
805
  this.availableNames.add(skill.name);
822
- const canonical = await this.canonicalize(skill.filePath).catch(
823
- () => path.resolve(this.cwd, skill.filePath)
824
- );
806
+ const canonical = await this.canonicalize(skill.filePath).catch(() => path.resolve(this.cwd, skill.filePath));
825
807
  this.skillByPath.set(canonical, skill.name);
826
808
  }
827
809
  }
@@ -842,19 +824,7 @@ function isRecord(value) {
842
824
  // src/storage/files.ts
843
825
  import { randomUUID as randomUUID2 } from "node:crypto";
844
826
  import { createReadStream } from "node:fs";
845
- import {
846
- chmod,
847
- lstat,
848
- mkdir,
849
- open,
850
- readdir,
851
- readFile,
852
- rename,
853
- rm,
854
- rmdir,
855
- unlink,
856
- writeFile
857
- } from "node:fs/promises";
827
+ import { chmod, lstat, mkdir, open, readdir, readFile, rename, rm, rmdir, unlink, writeFile } from "node:fs/promises";
858
828
  import path2 from "node:path";
859
829
 
860
830
  // src/storage/format.ts
@@ -862,23 +832,8 @@ var MAX_STORED_RUN_BYTES = 1024 * 1024;
862
832
  var MAX_STRING_LENGTH = 4096;
863
833
  var MAX_NESTED_RECORDS = 2e4;
864
834
  var TRIGGER_SOURCES = ["interactive", "rpc", "extension", "unknown"];
865
- var RUN_OUTCOMES = [
866
- "success",
867
- "recovered_success",
868
- "error",
869
- "aborted",
870
- "length",
871
- "interrupted"
872
- ];
873
- var GENERATION_OUTCOMES = [
874
- "pending",
875
- "stop",
876
- "tool_use",
877
- "error",
878
- "aborted",
879
- "length",
880
- "interrupted"
881
- ];
835
+ var RUN_OUTCOMES = ["success", "recovered_success", "error", "aborted", "length", "interrupted"];
836
+ var GENERATION_OUTCOMES = ["pending", "stop", "tool_use", "error", "aborted", "length", "interrupted"];
882
837
  var ERROR_CATEGORIES2 = [
883
838
  "dns",
884
839
  "timeout",
@@ -931,10 +886,7 @@ function parseRun(value, budget) {
931
886
  finishedAtMs: timestampValue(run.finishedAtMs, "run.finishedAtMs"),
932
887
  durationMs: durationValue(run.durationMs, "run.durationMs"),
933
888
  triggerSource: enumValue(run.triggerSource, TRIGGER_SOURCES, "run.triggerSource"),
934
- ...optionalProperty(
935
- "initialProvider",
936
- optionalString(run.initialProvider, "run.initialProvider")
937
- ),
889
+ ...optionalProperty("initialProvider", optionalString(run.initialProvider, "run.initialProvider")),
938
890
  ...optionalProperty("initialModel", optionalString(run.initialModel, "run.initialModel")),
939
891
  outcome: enumValue(run.outcome, RUN_OUTCOMES, "run.outcome"),
940
892
  attemptCount: boundedCount(run.attemptCount, "run.attemptCount"),
@@ -943,9 +895,7 @@ function parseRun(value, budget) {
943
895
  ),
944
896
  tools: boundedArray(run.tools, "run.tools", budget).map(parseTool),
945
897
  skills: boundedArray(run.skills, "run.skills", budget).map(parseSkill),
946
- providerErrors: boundedArray(run.providerErrors, "run.providerErrors", budget).map(
947
- parseProviderError
948
- ),
898
+ providerErrors: boundedArray(run.providerErrors, "run.providerErrors", budget).map(parseProviderError),
949
899
  toolErrorCount: boundedCount(run.toolErrorCount, "run.toolErrorCount"),
950
900
  providerErrorCount: boundedCount(run.providerErrorCount, "run.providerErrorCount"),
951
901
  recoveredErrorCount: boundedCount(run.recoveredErrorCount, "run.recoveredErrorCount")
@@ -959,21 +909,13 @@ function parseGeneration(value, index, budget) {
959
909
  ordinal: boundedCount(item.ordinal, `${prefix}.ordinal`),
960
910
  ...optionalProperty("provider", optionalString(item.provider, `${prefix}.provider`)),
961
911
  ...optionalProperty("model", optionalString(item.model, `${prefix}.model`)),
962
- ...optionalProperty(
963
- "thinkingLevel",
964
- optionalString(item.thinkingLevel, `${prefix}.thinkingLevel`)
965
- ),
912
+ ...optionalProperty("thinkingLevel", optionalString(item.thinkingLevel, `${prefix}.thinkingLevel`)),
966
913
  startedAtMs: timestampValue(item.startedAtMs, `${prefix}.startedAtMs`),
967
- ...optionalProperty(
968
- "finishedAtMs",
969
- optionalTimestamp(item.finishedAtMs, `${prefix}.finishedAtMs`)
970
- ),
914
+ ...optionalProperty("finishedAtMs", optionalTimestamp(item.finishedAtMs, `${prefix}.finishedAtMs`)),
971
915
  ...optionalProperty("durationMs", optionalDuration(item.durationMs, `${prefix}.durationMs`)),
972
916
  ...optionalProperty("stopReason", optionalString(item.stopReason, `${prefix}.stopReason`)),
973
917
  outcome: enumValue(item.outcome, GENERATION_OUTCOMES, `${prefix}.outcome`),
974
- responses: boundedArray(item.responses, `${prefix}.responses`, budget).map(
975
- parseProviderResponse
976
- )
918
+ responses: boundedArray(item.responses, `${prefix}.responses`, budget).map(parseProviderResponse)
977
919
  };
978
920
  }
979
921
  function parseProviderResponse(value, index) {
@@ -995,10 +937,7 @@ function parseTool(value, index) {
995
937
  ...optionalProperty("provider", optionalString(item.provider, `${prefix}.provider`)),
996
938
  ...optionalProperty("model", optionalString(item.model, `${prefix}.model`)),
997
939
  startedAtMs: timestampValue(item.startedAtMs, `${prefix}.startedAtMs`),
998
- ...optionalProperty(
999
- "finishedAtMs",
1000
- optionalTimestamp(item.finishedAtMs, `${prefix}.finishedAtMs`)
1001
- ),
940
+ ...optionalProperty("finishedAtMs", optionalTimestamp(item.finishedAtMs, `${prefix}.finishedAtMs`)),
1002
941
  ...optionalProperty("durationMs", optionalDuration(item.durationMs, `${prefix}.durationMs`)),
1003
942
  isError: booleanValue(item.isError, `${prefix}.isError`),
1004
943
  completionState: enumValue(
@@ -1025,18 +964,11 @@ function parseProviderError(value, index) {
1025
964
  const prefix = `run.providerErrors[${index}]`;
1026
965
  return {
1027
966
  id: requiredString(item.id, `${prefix}.id`),
1028
- ...optionalProperty(
1029
- "generationId",
1030
- optionalString(item.generationId, `${prefix}.generationId`)
1031
- ),
967
+ ...optionalProperty("generationId", optionalString(item.generationId, `${prefix}.generationId`)),
1032
968
  occurredAtMs: timestampValue(item.occurredAtMs, `${prefix}.occurredAtMs`),
1033
969
  ...optionalProperty("provider", optionalString(item.provider, `${prefix}.provider`)),
1034
970
  ...optionalProperty("model", optionalString(item.model, `${prefix}.model`)),
1035
- category: enumValue(
1036
- item.category,
1037
- ERROR_CATEGORIES2,
1038
- `${prefix}.category`
1039
- ),
971
+ category: enumValue(item.category, ERROR_CATEGORIES2, `${prefix}.category`),
1040
972
  recovered: booleanValue(item.recovered, `${prefix}.recovered`),
1041
973
  terminal: booleanValue(item.terminal, `${prefix}.terminal`)
1042
974
  };
@@ -1405,9 +1337,7 @@ async function withLinkedSignals(callerSignal, lifecycleSignal, operation) {
1405
1337
  throwIfAborted2(callerSignal);
1406
1338
  throwIfAborted2(lifecycleSignal);
1407
1339
  const controller = new AbortController();
1408
- const abort = (signal) => controller.abort(
1409
- signal.reason ?? new DOMException("Analytics operation aborted", "AbortError")
1410
- );
1340
+ const abort = (signal) => controller.abort(signal.reason ?? new DOMException("Analytics operation aborted", "AbortError"));
1411
1341
  const callerAbort = () => callerSignal && abort(callerSignal);
1412
1342
  const lifecycleAbort = () => abort(lifecycleSignal);
1413
1343
  callerSignal?.addEventListener("abort", callerAbort, { once: true });
@@ -1423,9 +1353,7 @@ async function withDeadline(callerSignal, lifecycleSignal, timeoutMs, operation)
1423
1353
  throwIfAborted2(callerSignal);
1424
1354
  throwIfAborted2(lifecycleSignal);
1425
1355
  const controller = new AbortController();
1426
- const abort = (signal) => controller.abort(
1427
- signal.reason ?? new DOMException("Analytics operation aborted", "AbortError")
1428
- );
1356
+ const abort = (signal) => controller.abort(signal.reason ?? new DOMException("Analytics operation aborted", "AbortError"));
1429
1357
  const callerAbort = () => callerSignal && abort(callerSignal);
1430
1358
  const lifecycleAbort = () => abort(lifecycleSignal);
1431
1359
  callerSignal?.addEventListener("abort", callerAbort, { once: true });
@@ -1518,6 +1446,7 @@ function createAnalyticsExtension(dependencies = {}) {
1518
1446
  let writeFailureActive = false;
1519
1447
  let pendingTriggerSource = "unknown";
1520
1448
  let pendingAttemptWithoutRun = false;
1449
+ let pendingProviderGeneration;
1521
1450
  pi.registerCommand("analytics", {
1522
1451
  description: "Open local Pi usage analytics",
1523
1452
  handler: async (args, ctx) => {
@@ -1553,6 +1482,7 @@ function createAnalyticsExtension(dependencies = {}) {
1553
1482
  writeFailureActive = false;
1554
1483
  pendingTriggerSource = "unknown";
1555
1484
  pendingAttemptWithoutRun = false;
1485
+ pendingProviderGeneration = void 0;
1556
1486
  const storageRoot = path3.join(deps.getAgentDir(), STORAGE_DIRECTORY);
1557
1487
  try {
1558
1488
  store = deps.createStore(storageRoot);
@@ -1577,6 +1507,7 @@ function createAnalyticsExtension(dependencies = {}) {
1577
1507
  });
1578
1508
  });
1579
1509
  pi.on("before_agent_start", async (event, ctx) => {
1510
+ pendingProviderGeneration = void 0;
1580
1511
  const generation = sessionGeneration;
1581
1512
  const tracker = skillTracker;
1582
1513
  const activeCollector = collector;
@@ -1615,18 +1546,22 @@ function createAnalyticsExtension(dependencies = {}) {
1615
1546
  });
1616
1547
  pi.on("turn_start", (_event, ctx) => ensureRun(ctx, "extension"));
1617
1548
  pi.on("before_provider_request", (_event, ctx) => {
1618
- ensureRun(ctx, "extension");
1619
- collector.beginGeneration({
1549
+ pendingProviderGeneration = {
1620
1550
  id: deps.createId(),
1621
- now: deps.now(),
1622
- model: modelIdentity(ctx, pi)
1623
- });
1551
+ startedAtMs: deps.now(),
1552
+ model: modelIdentity(ctx, pi),
1553
+ responses: []
1554
+ };
1624
1555
  });
1625
1556
  pi.on("after_provider_response", (event) => {
1626
- collector.recordProviderResponse({ status: event.status, now: deps.now() });
1557
+ pendingProviderGeneration?.responses.push({ status: event.status, occurredAtMs: deps.now() });
1558
+ });
1559
+ pi.on("message_start", (event, ctx) => {
1560
+ if (event.message.role === "assistant") claimPendingProviderGeneration(ctx);
1627
1561
  });
1628
- pi.on("message_end", (event) => {
1562
+ pi.on("message_end", (event, ctx) => {
1629
1563
  if (event.message.role !== "assistant") return;
1564
+ claimPendingProviderGeneration(ctx);
1630
1565
  collector.finishGeneration({
1631
1566
  now: deps.now(),
1632
1567
  stopReason: event.message.stopReason,
@@ -1672,6 +1607,7 @@ function createAnalyticsExtension(dependencies = {}) {
1672
1607
  const owner = sessionController;
1673
1608
  const run = collector.settle(deps.now());
1674
1609
  pendingAttemptWithoutRun = false;
1610
+ pendingProviderGeneration = void 0;
1675
1611
  pendingTriggerSource = "unknown";
1676
1612
  skillTracker?.clearPending();
1677
1613
  if (run) await persistRun(run, ctx, generation, owner.signal);
@@ -1683,6 +1619,7 @@ function createAnalyticsExtension(dependencies = {}) {
1683
1619
  skillTracker?.clearPending();
1684
1620
  skillTracker = void 0;
1685
1621
  store = void 0;
1622
+ pendingProviderGeneration = void 0;
1686
1623
  collector.interrupt(deps.now());
1687
1624
  const closing = activeStore ? [closeResult(activeStore), ...retiredCloseTasks] : [...retiredCloseTasks];
1688
1625
  const results = await Promise.all(closing);
@@ -1702,6 +1639,20 @@ function createAnalyticsExtension(dependencies = {}) {
1702
1639
  return false;
1703
1640
  }
1704
1641
  }
1642
+ function claimPendingProviderGeneration(ctx) {
1643
+ const pending = pendingProviderGeneration;
1644
+ if (!pending) return;
1645
+ pendingProviderGeneration = void 0;
1646
+ ensureRun(ctx, "extension");
1647
+ collector.beginGeneration({
1648
+ id: pending.id,
1649
+ now: pending.startedAtMs,
1650
+ model: pending.model
1651
+ });
1652
+ for (const response of pending.responses) {
1653
+ collector.recordProviderResponse({ status: response.status, now: response.occurredAtMs });
1654
+ }
1655
+ }
1705
1656
  function ensureRun(ctx, triggerSource) {
1706
1657
  if (collector.hasActiveRun()) return;
1707
1658
  collector.begin({
@@ -1730,11 +1681,7 @@ function createAnalyticsExtension(dependencies = {}) {
1730
1681
  return;
1731
1682
  }
1732
1683
  writeFailureActive = true;
1733
- safeNotify(
1734
- ctx,
1735
- "Analytics could not save this response cycle; its metrics were dropped.",
1736
- "warning"
1737
- );
1684
+ safeNotify(ctx, "Analytics could not save this response cycle; its metrics were dropped.", "warning");
1738
1685
  }
1739
1686
  }
1740
1687
  function menuSource(generation, signal) {