pi-exchange-stats 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Copyright (c) 2026 ezoushen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE.

package/README.md

@@ -0,0 +1,46 @@
+# pi-exchange-stats
+
+Show timing, token, cache, cost, and tool-use statistics for each Pi exchange.
+
+An **exchange** is one uninterrupted work span from a submitted prompt until Pi has
+nothing left to do automatically. A **turn** is one model response plus the tools it
+invokes, so an exchange can contain several turns. The status line shows the current
+or most recent exchange, and a transcript card records the settled breakdown.
+
+Tool time is the union of tool spans, not their sum, so parallel calls are not counted
+twice. Model time is estimated as turn wall time minus tool time. Output throughput is
+calculated per turn, while cumulative cost and token fields use Pi's reported usage.
+Run `/exstats` to append a cumulative session card.
+
+## External contract
+
+Pi must emit its documented session, agent, turn, tool, and UI-prompt lifecycle events.
+Assistant messages should include usage and cost fields when the provider supports
+them. No network service or machine-local file is required.
+
+## If the contract is unmet
+
+Missing usage fields are reported as zero; the extension does not invent token or cost
+data. Missing lifecycle events produce an incomplete or absent span. When UI status is
+unavailable, status updates are skipped. If custom-entry persistence is unavailable,
+the live status can still update and the agent turn continues.
+
+The measurements are process-local. They do not claim provider-side queue time,
+exclusive model compute time, or billing beyond the usage object Pi received.
+
+## Settings
+
+There are no settings and no environment variables. The package operates entirely
+from Pi-provided events and context.
+
+## Install and verify
+
+```sh
+pi install npm:pi-exchange-stats
+```
+
+Submit a prompt that makes at least one tool call and wait for Pi to settle. Expand the
+exchange card and verify that its turn count, output tokens, tool names, and wall-time
+breakdown match the transcript. Run `/exstats` and confirm that the session card equals
+the sum of completed exchanges. To check parallel-tool accounting, run two overlapping
+tools and confirm their union is not larger than the exchange wall time.

package/exchange-stats.js

@@ -0,0 +1,382 @@
+// extensions/exchange-stats/exchange-stats.ts
+import { keyHint } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+var ENTRY_TYPE = "exchange-stats";
+var STATUS_KEY = "exchange";
+var TICK_MS = 1e3;
+var TOOL_SHARE_NOTE = 0.25;
+var emptyTotals = () => ({
+  input: 0,
+  output: 0,
+  reasoning: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  totalTokens: 0,
+  cost: 0
+});
+function fmtDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return "\u2014";
+  if (ms < 1e3) return `${Math.round(ms)}ms`;
+  const s = ms / 1e3;
+  if (s < 60) return `${s.toFixed(1)}s`;
+  const m = Math.floor(s / 60);
+  const rem = Math.round(s % 60);
+  return rem > 0 ? `${m}m${rem}s` : `${m}m`;
+}
+function fmtTokens(n) {
+  if (!Number.isFinite(n) || n <= 0) return "0";
+  if (n < 1e3) return `${Math.round(n)}`;
+  if (n < 1e6) return `${(n / 1e3).toFixed(1)}k`;
+  return `${(n / 1e6).toFixed(2)}M`;
+}
+function fmtCost(cost) {
+  if (!Number.isFinite(cost) || cost <= 0) return "$0";
+  return cost < 0.01 ? `$${cost.toFixed(5)}` : `$${cost.toFixed(4)}`;
+}
+function fmtRate(tokensPerSec) {
+  if (!Number.isFinite(tokensPerSec) || tokensPerSec <= 0) return "\u2014";
+  return tokensPerSec < 1e3 ? `${Math.round(tokensPerSec)} tok/s` : `${(tokensPerSec / 1e3).toFixed(1)}k tok/s`;
+}
+function plural(n, one, many = `${one}s`) {
+  return n === 1 ? `${n} ${one}` : `${n} ${many}`;
+}
+function openToolText(spans, now) {
+  let longest;
+  for (const span of spans.values()) {
+    if (!longest || now - span.start > now - longest.start) longest = span;
+  }
+  if (!longest) return void 0;
+  const extra = spans.size > 1 ? ` (+${spans.size - 1})` : "";
+  return `${longest.name} ${fmtDuration(now - longest.start)}${extra}`;
+}
+function expandHint() {
+  try {
+    return ` (${keyHint("app.tools.expand", "to expand")})`;
+  } catch {
+    return " (expand for per-turn detail)";
+  }
+}
+function toolBreakdown(turn) {
+  return turn.tools.map((tool) => `${tool.name} ${fmtDuration(tool.ms)}${tool.isError ? " (failed)" : ""}`).join(", ");
+}
+function unionMs(runs) {
+  if (runs.length === 0) return 0;
+  const sorted = [...runs].sort((a, b) => a.start - b.start);
+  let total = 0;
+  let start = sorted[0].start;
+  let end = sorted[0].end;
+  for (const run of sorted.slice(1)) {
+    if (run.start > end) {
+      total += end - start;
+      start = run.start;
+      end = run.end;
+    } else if (run.end > end) {
+      end = run.end;
+    }
+  }
+  return total + (end - start);
+}
+function exchange_stats_default(pi) {
+  const sessionTotals = {
+    ...emptyTotals(),
+    exchanges: 0,
+    turnCount: 0,
+    durationMs: 0,
+    toolMs: 0,
+    waitingMs: 0
+  };
+  let sessionStartedAt = 0;
+  let running = false;
+  let startedAt = 0;
+  let promptCount = 0;
+  let exchangeIndex = 0;
+  let model = "unknown";
+  let stopReason = "stop";
+  let turns = [];
+  let totals = emptyTotals();
+  let waitingMs = 0;
+  let waitingStart;
+  let liveTimer;
+  let liveRefresh;
+  let activeTurn;
+  let activeToolRuns = [];
+  function setStatus(text, ctx) {
+    if (!ctx.hasUI) return;
+    ctx.ui.setStatus(STATUS_KEY, text);
+  }
+  function liveStatusText() {
+    const now = Date.now();
+    const parts = [`\u23F1 ${fmtDuration(now - startedAt)}`];
+    if (turns.length > 0) parts.push(`${plural(turns.length, "turn")} done`);
+    const toolText = activeTurn ? openToolText(activeTurn.spans, now) : void 0;
+    if (toolText) parts.push(toolText);
+    else if (activeTurn) parts.push(`turn ${activeTurn.index}`);
+    return parts.join(" \xB7 ");
+  }
+  function stopLiveTimer() {
+    if (liveTimer) clearInterval(liveTimer);
+    liveTimer = void 0;
+    liveRefresh = void 0;
+  }
+  function resetExchangeState() {
+    running = false;
+    startedAt = 0;
+    promptCount = 0;
+    turns = [];
+    totals = emptyTotals();
+    waitingMs = 0;
+    waitingStart = void 0;
+    activeTurn = void 0;
+    activeToolRuns = [];
+    stopLiveTimer();
+  }
+  pi.registerEntryRenderer(ENTRY_TYPE, (entry, { expanded }, theme) => {
+    const data = entry.data;
+    const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+    if (!data) {
+      box.addChild(new Text(theme.fg("dim", "(no stats)"), 0, 0));
+      return box;
+    }
+    const isSession = data.kind === "session";
+    const headline = isSession ? `\u{1F4CA} Session \xB7 ${plural(data.turnCount, "turn")} across ${plural(data.index, "exchange")}` : `\u23F1 Exchange ${data.index} \xB7 ${fmtDuration(data.durationMs)}`;
+    box.addChild(
+      new Text(
+        theme.fg("accent", theme.bold(headline)) + theme.fg("dim", `  ${data.model}`) + (!expanded && !isSession ? theme.fg("dim", expandHint()) : ""),
+        0,
+        0
+      )
+    );
+    const summary = [];
+    if (isSession) {
+      summary.push(`active ${fmtDuration(data.durationMs)}`);
+    } else {
+      summary.push(plural(data.turnCount, "turn"), plural(data.promptCount, "prompt"));
+    }
+    if (data.toolMs > 0) summary.push(`tools ${fmtDuration(data.toolMs)}`);
+    summary.push(`out ${fmtTokens(data.output)}`, fmtCost(data.cost));
+    if (data.waitingMs > 0) summary.push(`waiting ${fmtDuration(data.waitingMs)}`);
+    box.addChild(new Text(theme.fg("dim", summary.join(" \xB7 ")), 0, 0));
+    if (expanded) {
+      for (const turn of data.turns) {
+        const detail = [`model ${fmtDuration(turn.modelMs)}`];
+        if (turn.toolMs > 0) detail.push(`tools ${fmtDuration(turn.toolMs)} (${toolBreakdown(turn)})`);
+        detail.push(`out ${fmtTokens(turn.output)}`, fmtRate(turn.outputPerSec));
+        box.addChild(
+          new Text(
+            `  ${theme.fg("dim", `#${String(turn.index).padStart(2, " ")}`)}  ` + theme.fg("text", fmtDuration(turn.durationMs).padStart(8, " ")) + theme.fg("dim", `  ${detail.join(" \xB7 ")}`),
+            0,
+            0
+          )
+        );
+      }
+      if (isSession && data.turnCount > 0) {
+        box.addChild(
+          new Text(
+            theme.fg("dim", `avg ${fmtDuration(data.durationMs / data.turnCount)} per turn`),
+            0,
+            0
+          )
+        );
+      }
+      const tokenParts = [
+        `in ${fmtTokens(data.input)}`,
+        `out ${fmtTokens(data.output)}`,
+        `cache r ${fmtTokens(data.cacheRead)} / w ${fmtTokens(data.cacheWrite)}`,
+        `total ${fmtTokens(data.totalTokens)}`,
+        fmtCost(data.cost)
+      ];
+      if (data.reasoning > 0) tokenParts.splice(2, 0, `thinking ${fmtTokens(data.reasoning)}`);
+      box.addChild(new Text(theme.fg("dim", tokenParts.join(" \xB7 ")), 0, 0));
+      if (data.startedAt > 0) {
+        const from = new Date(data.startedAt).toLocaleTimeString();
+        const to = new Date(data.endedAt).toLocaleTimeString();
+        box.addChild(new Text(theme.fg("dim", `${from} \u2192 ${to}  stop: ${data.stopReason}`), 0, 0));
+      }
+    }
+    return box;
+  });
+  pi.on("session_start", (_event, ctx) => {
+    resetExchangeState();
+    sessionStartedAt = Date.now();
+    setStatus("\u23F1 ready", ctx);
+  });
+  pi.on("session_shutdown", () => {
+    resetExchangeState();
+  });
+  pi.on("before_agent_start", (_event, ctx) => {
+    if (running) {
+      promptCount++;
+      return;
+    }
+    running = true;
+    startedAt = Date.now();
+    promptCount = 1;
+    exchangeIndex++;
+    turns = [];
+    totals = emptyTotals();
+    waitingMs = 0;
+    waitingStart = void 0;
+    activeTurn = void 0;
+    activeToolRuns = [];
+    model = ctx.model?.id ?? "unknown";
+    stopReason = "stop";
+    stopLiveTimer();
+    setStatus(liveStatusText(), ctx);
+    liveRefresh = () => setStatus(liveStatusText(), ctx);
+    liveTimer = setInterval(() => {
+      try {
+        liveRefresh?.();
+      } catch {
+        stopLiveTimer();
+      }
+    }, TICK_MS);
+  });
+  pi.on("turn_start", (event, _ctx) => {
+    if (!running) return;
+    activeTurn = { index: event.turnIndex ?? turns.length + 1, startedAt: Date.now(), spans: /* @__PURE__ */ new Map() };
+    activeToolRuns = [];
+  });
+  pi.on("tool_execution_start", (event, _ctx) => {
+    if (!running || !activeTurn) return;
+    activeTurn.spans.set(event.toolCallId, { name: event.toolName, start: Date.now() });
+  });
+  pi.on("tool_execution_end", (event, _ctx) => {
+    if (!running || !activeTurn) return;
+    const open = activeTurn.spans.get(event.toolCallId);
+    if (open) {
+      activeTurn.spans.delete(event.toolCallId);
+      activeToolRuns.push({
+        name: event.toolName ?? open.name,
+        start: open.start,
+        end: Date.now(),
+        isError: Boolean(event.isError)
+      });
+      return;
+    }
+    const at = Date.now();
+    activeToolRuns.push({ name: event.toolName, start: at, end: at, isError: Boolean(event.isError) });
+  });
+  pi.on("turn_end", (event, _ctx) => {
+    if (!running || !activeTurn) return;
+    const endedAt = Date.now();
+    for (const [id, open] of activeTurn.spans) {
+      activeToolRuns.push({ name: open.name, start: open.start, end: endedAt, isError: false });
+      activeTurn.spans.delete(id);
+    }
+    const usage = event.message?.role === "assistant" ? event.message.usage : void 0;
+    const durationMs = endedAt - activeTurn.startedAt;
+    const toolMs = unionMs(activeToolRuns);
+    const output = usage?.output ?? 0;
+    turns.push({
+      index: activeTurn.index,
+      durationMs,
+      toolMs,
+      modelMs: Math.max(0, durationMs - toolMs),
+      outputPerSec: durationMs > 0 ? output / (durationMs / 1e3) : 0,
+      tools: activeToolRuns.map((run) => ({ name: run.name, ms: run.end - run.start, isError: run.isError })),
+      input: usage?.input ?? 0,
+      output,
+      reasoning: usage?.reasoning ?? 0,
+      cacheRead: usage?.cacheRead ?? 0,
+      cacheWrite: usage?.cacheWrite ?? 0,
+      totalTokens: usage?.totalTokens ?? 0,
+      cost: usage?.cost?.total ?? 0
+    });
+    totals.input += usage?.input ?? 0;
+    totals.output += output;
+    totals.reasoning += usage?.reasoning ?? 0;
+    totals.cacheRead += usage?.cacheRead ?? 0;
+    totals.cacheWrite += usage?.cacheWrite ?? 0;
+    totals.totalTokens += usage?.totalTokens ?? 0;
+    totals.cost += usage?.cost?.total ?? 0;
+    if (event.message?.stopReason) stopReason = event.message.stopReason;
+    activeTurn = void 0;
+    activeToolRuns = [];
+  });
+  pi.on("ui_prompt_start", (_event, _ctx) => {
+    if (!running || waitingStart !== void 0) return;
+    waitingStart = Date.now();
+  });
+  pi.on("ui_prompt_end", (_event, _ctx) => {
+    if (waitingStart === void 0) return;
+    waitingMs += Date.now() - waitingStart;
+    waitingStart = void 0;
+  });
+  pi.on("agent_settled", (_event, ctx) => {
+    if (!running) return;
+    const endedAt = Date.now();
+    if (waitingStart !== void 0) {
+      waitingMs += endedAt - waitingStart;
+      waitingStart = void 0;
+    }
+    const durationMs = endedAt - startedAt;
+    const toolMs = turns.reduce((sum, turn) => sum + turn.toolMs, 0);
+    const record = {
+      ...totals,
+      kind: "exchange",
+      index: exchangeIndex,
+      promptCount,
+      turnCount: turns.length,
+      turns,
+      startedAt,
+      endedAt,
+      durationMs,
+      waitingMs,
+      toolMs,
+      model,
+      stopReason
+    };
+    stopLiveTimer();
+    sessionTotals.input += totals.input;
+    sessionTotals.output += totals.output;
+    sessionTotals.reasoning += totals.reasoning;
+    sessionTotals.cacheRead += totals.cacheRead;
+    sessionTotals.cacheWrite += totals.cacheWrite;
+    sessionTotals.totalTokens += totals.totalTokens;
+    sessionTotals.cost += totals.cost;
+    sessionTotals.exchanges++;
+    sessionTotals.turnCount += turns.length;
+    sessionTotals.durationMs += durationMs;
+    sessionTotals.toolMs += toolMs;
+    sessionTotals.waitingMs += waitingMs;
+    try {
+      pi.appendEntry(ENTRY_TYPE, record);
+    } catch {
+    }
+    const parts = [`\u23F1 ${fmtDuration(durationMs)}`, plural(turns.length, "turn")];
+    if (toolMs > 0 && durationMs > 0 && toolMs / durationMs >= TOOL_SHARE_NOTE) {
+      parts.push(`tools ${fmtDuration(toolMs)}`);
+    }
+    parts.push(`out ${fmtTokens(totals.output)}`, fmtCost(totals.cost));
+    if (waitingMs > 0) parts.push(`waiting ${fmtDuration(waitingMs)}`);
+    setStatus(parts.join(" \xB7 "), ctx);
+    resetExchangeState();
+  });
+  pi.registerCommand("exstats", {
+    description: "Append a cumulative session timing card",
+    handler: () => {
+      const record = {
+        ...sessionTotals,
+        kind: "session",
+        index: sessionTotals.exchanges,
+        promptCount: sessionTotals.exchanges,
+        turnCount: sessionTotals.turnCount,
+        turns: [],
+        startedAt: sessionStartedAt,
+        endedAt: Date.now(),
+        durationMs: sessionTotals.durationMs,
+        waitingMs: sessionTotals.waitingMs,
+        toolMs: sessionTotals.toolMs,
+        model: `${plural(sessionTotals.turnCount, "turn")} tracked`,
+        stopReason: "session"
+      };
+      try {
+        pi.appendEntry(ENTRY_TYPE, record);
+      } catch {
+      }
+    }
+  });
+}
+export {
+  exchange_stats_default as default
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "pi-exchange-stats",
+  "version": "0.1.0",
+  "description": "Show timing and cost for each Pi exchange.",
+  "type": "module",
+  "main": "./exchange-stats.js",
+  "exports": "./exchange-stats.js",
+  "files": [
+    "exchange-stats.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ezoushen/pi-extensions.git",
+    "directory": "extensions/exchange-stats"
+  },
+  "homepage": "https://github.com/ezoushen/pi-extensions/tree/main/extensions/exchange-stats#readme",
+  "bugs": {
+    "url": "https://github.com/ezoushen/pi-extensions/issues"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./exchange-stats.js"
+    ]
+  }
+}