@sebastianandreasson/pi-autonomous-agents 0.12.1 → 0.13.1

package/README.md

@@ -269,10 +269,16 @@ Useful files during a run:
   Main run log.
 - `pi_telemetry.jsonl`
 - `pi_telemetry.csv`
+- `pi-output/token-usage/events.jsonl`
+  Normalized token-attribution event stream for downstream tools. Each row includes phase, role, kind, session/model, attribution bucket, tool/file context, and token counts.
+- `pi-output/token-usage/summary.json`
+  Derived structured token summary with totals plus breakdowns by phase, model, session, attribution, tool, file, and directory.
 - `.pi-runtime/active-run.json`
 - `.pi-runtime/runs/<runId>/...`
 
-`pi-harness report` summarizes recent telemetry and surfaces things like terminal reasons, large-file warnings, and recent failure artifacts.
+Each run also gets run-scoped token artifacts under `.pi-runtime/runs/<runId>/token-usage.events.jsonl` and `.pi-runtime/runs/<runId>/token-usage.summary.json`.
+
+`pi-harness report` summarizes recent telemetry and token artifacts and surfaces things like terminal reasons, large-file warnings, failure artifacts, and top token hotspots.
 
 `pi-harness run` now also starts lightweight local web UI for orchestration flow by default. By default it listens on `127.0.0.1:4317`. Override with `PI_VISUALIZER_HOST` and `PI_VISUALIZER_PORT`. Set `PI_VISUALIZER=0` to disable embedded web UI for a run.
 
@@ -316,6 +322,8 @@ That clears configured harness runtime/history artifacts and verifies they are g
   Agent-facing setup instructions for consuming repos.
 - [docs/PI_SUPERVISOR.md](./docs/PI_SUPERVISOR.md)
   More detailed flow, transport, telemetry, and runtime documentation.
+- [docs/TOKEN_USAGE_ARTIFACTS.md](./docs/TOKEN_USAGE_ARTIFACTS.md)
+  Agent-facing contract and usage guidance for token-usage artifacts and downstream tooling.
 - [templates/PROJECT_SETUP.md](./templates/PROJECT_SETUP.md)
   Minimal consuming-repo layout summary.
 

package/SETUP.md

@@ -67,6 +67,12 @@ Important:
   - mention project-specific constraints, startup flow, or directories
   - keep the harness workflow intact
 
+Recommended:
+
+- If the repo wants agents to learn from harness token data, also reference:
+  - `node_modules/@sebastianandreasson/pi-autonomous-agents/docs/TOKEN_USAGE_ARTIFACTS.md`
+- Add a short repo-local instruction snippet telling agents to read `pi-output/token-usage/summary.json` before investigating retries, hotspots, or large turns.
+
 4. Ensure `TODOS.md` exists.
 
 - If the repo already uses a task file, keep it.
@@ -191,6 +197,7 @@ The harness should fail fast if:
 
 For prompt debugging, inspect `.pi-last-prompt.txt` after a run. It contains the exact assembled prompt that was sent for the active role.
 For flow debugging, inspect `.pi-last-iteration.json` after a run. It summarizes the selected task, repo-change outcome, tester verdict, commit-plan state, and terminal reason.
+For token-hotspot debugging, inspect `pi-output/token-usage/summary.json` first and only read `pi-output/token-usage/events.jsonl` when the summary is not enough.
 
 ## Agent Rules
 

package/docs/PI_SUPERVISOR.md

@@ -211,3 +211,14 @@ Each step records:
 - artifact path for compact failure diagnostics when available
 - output excerpt for failed verification-style events
 - notes
+
+The harness also produces structured token-usage artifacts intended for downstream tooling:
+
+- `pi-output/token-usage/events.jsonl`
+- `pi-output/token-usage/summary.json`
+- `.pi-runtime/runs/<runId>/token-usage.events.jsonl`
+- `.pi-runtime/runs/<runId>/token-usage.summary.json`
+
+These artifacts are the stable machine-readable token contract. The visualizer and report command are consumers of those files, not the source of truth.
+
+For agent-facing guidance on how to interpret and use those files in consuming repos, see [TOKEN_USAGE_ARTIFACTS.md](./TOKEN_USAGE_ARTIFACTS.md).

package/docs/TOKEN_USAGE_ARTIFACTS.md

@@ -0,0 +1,215 @@
+# Token Usage Artifacts
+
+This document is written for autonomous coding agents and repo maintainers who want to use the token-usage artifacts produced by `pi-harness` in their own projects.
+
+The goal is not just to visualize token usage. The goal is to expose a stable machine-readable contract that other tools, prompts, reports, or project-specific scripts can reuse.
+
+## Produced Artifacts
+
+Repo-scoped artifacts:
+
+- `pi-output/token-usage/events.jsonl`
+- `pi-output/token-usage/summary.json`
+
+Run-scoped artifacts:
+
+- `.pi-runtime/runs/<runId>/token-usage.events.jsonl`
+- `.pi-runtime/runs/<runId>/token-usage.summary.json`
+
+Use repo-scoped files when you want the latest cumulative view for the repository.
+Use run-scoped files when you want to inspect one specific harness run in isolation.
+
+## Recommended Consumption Order
+
+When an agent wants to use token data, prefer this order:
+
+1. Read `token-usage.summary.json` first.
+2. Only read `token-usage.events.jsonl` if the summary is not enough.
+3. Prefer run-scoped artifacts when analyzing one run.
+4. Prefer repo-scoped artifacts when looking for long-term hotspots.
+
+This keeps token-analysis prompts compact and avoids spending more tokens just to inspect token data.
+
+## Event Schema
+
+Each line in `events.jsonl` is one normalized token-attribution event.
+
+Important fields:
+
+- `schemaVersion`
+- `timestamp`
+- `runId`
+- `transport`
+- `sessionId`
+- `model`
+- `iteration`
+- `retryCount`
+- `reason`
+- `phase`
+- `role`
+- `kind`
+- `attributionKind`
+- `toolNames`
+- `files`
+- `primaryFile`
+- `inputTokens`
+- `outputTokens`
+- `totalTokens`
+- `cacheReadTokens`
+- `cacheWriteTokens`
+
+Semantics:
+
+- `kind`, `phase`, and `role` identify the harness stage where the tokens were spent.
+- `toolNames` and `files` capture the nearby tool/file context seen around the token event.
+- `attributionKind` explains how the event was classified:
+  - `thinking`
+  - `response`
+  - `tool_context`
+  - `tool_running`
+  - `agent`
+
+Important:
+
+- file and directory attribution are inferred from nearby tool context
+- they are useful for hotspot detection, not exact provider-native accounting
+- if one token event touches multiple files, downstream summaries may split that event across those files
+
+## Summary Schema
+
+`summary.json` contains:
+
+- `schemaVersion`
+- `generatedAt`
+- `source.eventCount`
+- `totals`
+- `coverage`
+- `breakdowns`
+
+`totals` contains:
+
+- `inputTokens`
+- `outputTokens`
+- `totalTokens`
+- `cacheReadTokens`
+- `cacheWriteTokens`
+- `eventCount`
+
+`coverage` contains:
+
+- `fileAttributedTokens`
+- `unattributedTokens`
+- `fileAttributionRatio`
+
+`breakdowns` contains:
+
+- `byKind`
+- `byRole`
+- `byPhase`
+- `byModel`
+- `bySession`
+- `byAttribution`
+- `byTool`
+- `byFile`
+- `byDirectory`
+
+Each breakdown item contains:
+
+- `key`
+- `label`
+- `inputTokens`
+- `outputTokens`
+- `totalTokens`
+- `cacheReadTokens`
+- `cacheWriteTokens`
+- `eventCount`
+
+## How Agents Should Use This Data
+
+Use token artifacts to answer questions like:
+
+- Which harness phases are spending the most tokens?
+- Which files or directories repeatedly consume tokens?
+- Are retries concentrated in one hotspot?
+- Is token usage dominated by thinking, tool-context, or response generation?
+- Are certain models or sessions much more expensive than others?
+
+Good uses:
+
+- splitting a large TODO item into narrower tasks
+- identifying files that should be decomposed before another agent pass
+- deciding whether a hot directory needs refactor work
+- comparing whether `developer` or `tester` is driving most cost
+- checking whether a local model is wasting tokens on repeated tool/file churn
+
+Bad uses:
+
+- treating `byFile` values as exact per-file billing
+- assuming all unattributed tokens are waste
+- optimizing for raw token count while ignoring correctness
+
+## Agent Workflow Guidance
+
+When an agent is asked to improve harness efficiency in a repo:
+
+1. Read `summary.json`.
+2. Inspect `breakdowns.byFile`, `breakdowns.byDirectory`, `breakdowns.byTool`, and `breakdowns.byAttribution`.
+3. If one file or directory dominates, inspect the related source only after confirming the hotspot from the summary.
+4. If `fileAttributionRatio` is low, rely more on `byKind`, `byRole`, `byModel`, and `byAttribution` than on `byFile`.
+5. When proposing changes, explicitly distinguish:
+   - exact token totals from artifacts
+   - inferred file attribution from nearby context
+
+## Recommended Interpretation Rules
+
+Use these heuristics:
+
+- High `byFile` and high `fileAttributionRatio`:
+  Strong signal that the file is a real hotspot.
+- High `byDirectory` with spread across many files:
+  The problem is probably architectural or task-shaping, not one file only.
+- High `byAttribution.tool_context` or `tool_running`:
+  The agent may be rereading, diffing, or patching inefficiently.
+- High `byAttribution.thinking` with low file coverage:
+  The problem may be task ambiguity or prompt shape rather than one code hotspot.
+- High `byModel` on one role:
+  That role may need a smaller scope, different model, or clearer repo instructions.
+
+## Instruction Snippet For Consuming Repos
+
+If a consuming repo wants its own agents to use the artifacts, add guidance like this to repo-local instructions:
+
+```md
+## Token Usage Data
+
+This repo may contain `pi-harness` token artifacts:
+
+- `pi-output/token-usage/summary.json`
+- `pi-output/token-usage/events.jsonl`
+
+When investigating repeated retries, large agent turns, or code hotspots:
+
+1. Read `summary.json` first.
+2. Use `breakdowns.byFile`, `breakdowns.byDirectory`, `breakdowns.byTool`, and `breakdowns.byAttribution` to locate hotspots.
+3. Treat file and directory token attribution as inferred context, not exact billing.
+4. If one file is a clear hotspot, prefer smaller TODOs, narrower reads, or structural refactors over brute-force retries.
+5. If file attribution is weak, rely more on `byKind`, `byRole`, `byModel`, and `byAttribution`.
+```
+
+## Project-Specific Extensions
+
+Projects can build their own tooling on top of these artifacts, for example:
+
+- nightly regression reports that flag rising token hotspots
+- CI checks that warn when one file dominates token spend
+- repo-specific dashboards
+- prompt builders that mention known hotspots before starting a developer turn
+- scripts that compare token patterns before and after a refactor
+
+When doing that, depend on:
+
+- `schemaVersion`
+- the named summary fields
+- the normalized event fields
+
+Do not depend on the visualizer UI structure or CSS. Those are consumers, not the contract.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sebastianandreasson/pi-autonomous-agents",
   "private": false,
-  "version": "0.12.1",
+  "version": "0.13.1",
   "type": "module",
   "description": "Portable unattended PI harness for developer/tester/visual-review loops.",
   "license": "MIT",
@@ -19,8 +19,8 @@
     "@mariozechner/pi-coding-agent": "^0.66.1"
   },
   "scripts": {
-    "check": "node --check src/cli.mjs && node --check src/pi-clear-history.mjs && node --check src/pi-client.mjs && node --check src/pi-config.mjs && node --check src/pi-debug-live.mjs && node --check src/pi-flow.mjs && node --check src/pi-heartbeat.mjs && node --check src/pi-history.mjs && node --check src/pi-preflight.mjs && node --check src/pi-prompts.mjs && node --check src/pi-repo.mjs && node --check src/pi-report.mjs && node --check src/pi-sdk-turn.mjs && node --check src/pi-supervisor.mjs && node --check src/pi-telemetry.mjs && node --check src/pi-visual-once.mjs && node --check src/pi-visual-review.mjs && node --check src/pi-visualizer.mjs && node --check src/pi-visualizer-server.mjs && node --check src/pi-visualizer-shared.mjs && node --check src/index.mjs && node --check test/pi-heartbeat.test.mjs && node --check test/pi-lifecycle.test.mjs && node --check test/pi-role-models.test.mjs && node --check test/pi-flow.test.mjs && node --check test/pi-history.test.mjs && node --check test/pi-prompts.test.mjs && node --check test/pi-preflight.test.mjs && node --check test/pi-repo.test.mjs && node --check test/pi-sdk-supervisor.test.mjs && node --check test/pi-sdk-turn.test.mjs && node --check test/pi-telemetry.test.mjs && node --check test/pi-visualizer-shared.test.mjs && node --check test/fixtures/fake-pi.mjs && node --check test/fixtures/fake-pi-sdk.mjs && node --check test/fixtures/fake-live-pi-sdk.mjs",
-    "test": "node --test test/pi-heartbeat.test.mjs test/pi-lifecycle.test.mjs test/pi-role-models.test.mjs test/pi-flow.test.mjs test/pi-history.test.mjs test/pi-prompts.test.mjs test/pi-preflight.test.mjs test/pi-repo.test.mjs test/pi-sdk-supervisor.test.mjs test/pi-sdk-turn.test.mjs test/pi-telemetry.test.mjs test/pi-visualizer-shared.test.mjs",
+    "check": "node --check src/cli.mjs && node --check src/pi-clear-history.mjs && node --check src/pi-client.mjs && node --check src/pi-config.mjs && node --check src/pi-debug-live.mjs && node --check src/pi-flow.mjs && node --check src/pi-heartbeat.mjs && node --check src/pi-history.mjs && node --check src/pi-preflight.mjs && node --check src/pi-prompts.mjs && node --check src/pi-repo.mjs && node --check src/pi-report.mjs && node --check src/pi-sdk-turn.mjs && node --check src/pi-supervisor.mjs && node --check src/pi-telemetry.mjs && node --check src/pi-token-analysis.mjs && node --check src/pi-visual-once.mjs && node --check src/pi-visual-review.mjs && node --check src/pi-visualizer.mjs && node --check src/pi-visualizer-server.mjs && node --check src/pi-visualizer-shared.mjs && node --check src/index.mjs && node --check test/pi-heartbeat.test.mjs && node --check test/pi-lifecycle.test.mjs && node --check test/pi-role-models.test.mjs && node --check test/pi-flow.test.mjs && node --check test/pi-history.test.mjs && node --check test/pi-prompts.test.mjs && node --check test/pi-preflight.test.mjs && node --check test/pi-repo.test.mjs && node --check test/pi-sdk-supervisor.test.mjs && node --check test/pi-sdk-turn.test.mjs && node --check test/pi-telemetry.test.mjs && node --check test/pi-token-analysis.test.mjs && node --check test/pi-visualizer-shared.test.mjs && node --check test/fixtures/fake-pi.mjs && node --check test/fixtures/fake-pi-sdk.mjs && node --check test/fixtures/fake-live-pi-sdk.mjs",
+    "test": "node --test test/pi-heartbeat.test.mjs test/pi-lifecycle.test.mjs test/pi-role-models.test.mjs test/pi-flow.test.mjs test/pi-history.test.mjs test/pi-prompts.test.mjs test/pi-preflight.test.mjs test/pi-repo.test.mjs test/pi-sdk-supervisor.test.mjs test/pi-sdk-turn.test.mjs test/pi-telemetry.test.mjs test/pi-token-analysis.test.mjs test/pi-visualizer-shared.test.mjs",
     "debug:live-ui": "node src/cli.mjs debug-live --reset",
     "dev:visualizer:ui": "npm --prefix visualizer-ui run dev",
     "build:visualizer:ui": "npm --prefix visualizer-ui run build",

package/pi.config.json

@@ -17,6 +17,8 @@
   "testerFeedbackHistoryDir": "pi-output/tester-feedback/history",
   "visualReviewHistoryDir": "pi-output/visual-review/history",
   "visualCaptureDir": "pi-output/visual-capture",
+  "tokenUsageEventsFile": "pi-output/token-usage/events.jsonl",
+  "tokenUsageSummaryFile": "pi-output/token-usage/summary.json",
   "visualCaptureCommand": "",
   "visualCaptureTimeoutSeconds": 300,
   "visualReviewEnabled": false,

package/src/index.mjs

@@ -13,5 +13,18 @@ export { clearHarnessHistory, collectHistoryTargets } from './pi-history.mjs'
 export { collectLargeFileWarnings } from './pi-repo.mjs'
 export { runAgentTurn } from './pi-client.mjs'
 export { createSdkSession, createTools, normalizeToolNames, resolveModel, runSdkTurn, runSdkTurnWithPi, splitModelSpec } from './pi-sdk-turn.mjs'
+export {
+  appendTokenUsageEvent,
+  applyTokenAttributionEvent,
+  createEmptyTokenBreakdown,
+  createEmptyTokenUsage,
+  deriveTokenBreakdown,
+  ensureTokenUsageFiles,
+  formatTokenUsageSummary,
+  normalizeTokenAttributionEvent,
+  normalizeTokenUsage,
+  readTokenUsageEvents,
+  readTokenUsageSummary,
+} from './pi-token-analysis.mjs'
 export { deriveCurrentIteration, deriveFlowSnapshot, deriveStageGraph, formatActiveLabel, getFlowSteps, getLabelForKind, getStepKeyForActiveRun, getStepKeyForKind } from './pi-visualizer-shared.mjs'
 export { buildSnapshot, readVisualizerHost, readVisualizerPort, renderHtml, startVisualizerServer } from './pi-visualizer-server.mjs'

package/src/pi-client.mjs

@@ -11,6 +11,7 @@ import {
   writeTextFile,
 } from './pi-repo.mjs'
 import { runSdkTurn } from './pi-sdk-turn.mjs'
+import { appendTokenUsageEvent } from './pi-token-analysis.mjs'
 
 function truncateForNotes(text) {
   const trimmed = text.trim()
@@ -26,6 +27,7 @@ function formatLastAgentOutput(response) {
     `sessionId: ${String(response.sessionId ?? '')}`,
     `sessionFile: ${String(response.sessionFile ?? '')}`,
     `terminalReason: ${String(response.terminalReason ?? '')}`,
+    `tokens: total=${Number(response.totalTokens ?? 0)} input=${Number(response.inputTokens ?? 0)} output=${Number(response.outputTokens ?? 0)} cacheRead=${Number(response.cacheReadTokens ?? 0)} cacheWrite=${Number(response.cacheWriteTokens ?? 0)}`,
     `notes: ${String(response.notes ?? '').trim()}`,
   ]
 
@@ -81,10 +83,49 @@ function sanitizeLiveFeedEvent(filePath, event) {
     kind: String(event?.kind ?? ''),
     type: String(event?.type ?? 'event'),
     toolName: String(event?.toolName ?? ''),
+    sessionId: String(event?.sessionId ?? ''),
+    model: String(event?.model ?? ''),
     isError: event?.isError === true,
     text: truncateText(event?.text ?? '', MAX_LIVE_FEED_TEXT),
   }
 
+  const numericFields = {
+    inputTokens: Number(event?.inputTokens),
+    outputTokens: Number(event?.outputTokens),
+    totalTokens: Number(event?.totalTokens),
+    cacheReadTokens: Number(event?.cacheReadTokens),
+    cacheWriteTokens: Number(event?.cacheWriteTokens),
+  }
+  for (const [key, value] of Object.entries(numericFields)) {
+    if (Number.isFinite(value) && value > 0) {
+      normalized[key] = value
+    }
+  }
+
+  const attributionKind = String(event?.attributionKind ?? '').trim()
+  if (attributionKind !== '') {
+    normalized.attributionKind = attributionKind
+  }
+
+  const primaryFile = String(event?.primaryFile ?? '').trim()
+  if (primaryFile !== '') {
+    normalized.primaryFile = primaryFile
+  }
+
+  const toolNames = Array.isArray(event?.toolNames)
+    ? [...new Set(event.toolNames.map((value) => String(value ?? '').trim()).filter(Boolean))]
+    : []
+  if (toolNames.length > 0) {
+    normalized.toolNames = toolNames
+  }
+
+  const files = Array.isArray(event?.files)
+    ? [...new Set(event.files.map((value) => String(value ?? '').trim()).filter(Boolean))]
+    : []
+  if (files.length > 0) {
+    normalized.files = files
+  }
+
   const argsSummary = summarizeValue(event?.args)
   const partialSummary = summarizeValue(event?.partialResult)
   const resultSummary = summarizeValue(event?.result)
@@ -102,21 +143,23 @@ function sanitizeLiveFeedEvent(filePath, event) {
 }
 
 async function appendLiveFeedEvent(config, event) {
-  if (!config.runLiveFeedFile) {
-    return
-  }
-
-  const filePath = config.runLiveFeedFile
-  const previous = liveFeedWriteQueues.get(filePath) ?? Promise.resolve()
+  const filePath = String(config.runLiveFeedFile ?? '').trim()
+  const queueKey = filePath || String(config.runTokenUsageEventsFile ?? config.tokenUsageEventsFile ?? 'token-usage')
+  const previous = liveFeedWriteQueues.get(queueKey) ?? Promise.resolve()
   const next = previous
     .catch(() => {})
     .then(async () => {
-      const sanitized = sanitizeLiveFeedEvent(filePath, event)
-      await fs.mkdir(path.dirname(filePath), { recursive: true })
-      await fs.appendFile(filePath, `${JSON.stringify(sanitized)}\n`, 'utf8')
+      const sanitized = sanitizeLiveFeedEvent(queueKey, event)
+      if (filePath !== '') {
+        await fs.mkdir(path.dirname(filePath), { recursive: true })
+        await fs.appendFile(filePath, `${JSON.stringify(sanitized)}\n`, 'utf8')
+      }
+      if (sanitized.type === 'token_usage') {
+        await appendTokenUsageEvent(config, sanitized)
+      }
     })
 
-  liveFeedWriteQueues.set(filePath, next)
+  liveFeedWriteQueues.set(queueKey, next)
   await next
 }
 
@@ -154,6 +197,11 @@ async function runMockTurn({ config, sessionId, sessionFile, prompt, reason }) {
     toolCalls: 0,
     toolErrors: 0,
     messageUpdates: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
     stopReason: '',
     loopDetected: false,
     loopSignature: '',
@@ -224,6 +272,11 @@ async function runSdkTransportTurn({ config, model, sessionId, sessionFile, prom
       toolCalls: 0,
       toolErrors: 0,
       messageUpdates: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      totalTokens: 0,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
       stopReason: '',
       loopDetected: false,
       loopSignature: '',
@@ -248,6 +301,11 @@ async function runSdkTransportTurn({ config, model, sessionId, sessionFile, prom
     toolCalls: Number.isFinite(Number(response.toolCalls)) ? Number(response.toolCalls) : 0,
     toolErrors: Number.isFinite(Number(response.toolErrors)) ? Number(response.toolErrors) : 0,
     messageUpdates: Number.isFinite(Number(response.messageUpdates)) ? Number(response.messageUpdates) : 0,
+    inputTokens: Number.isFinite(Number(response.inputTokens)) ? Number(response.inputTokens) : 0,
+    outputTokens: Number.isFinite(Number(response.outputTokens)) ? Number(response.outputTokens) : 0,
+    totalTokens: Number.isFinite(Number(response.totalTokens)) ? Number(response.totalTokens) : 0,
+    cacheReadTokens: Number.isFinite(Number(response.cacheReadTokens)) ? Number(response.cacheReadTokens) : 0,
+    cacheWriteTokens: Number.isFinite(Number(response.cacheWriteTokens)) ? Number(response.cacheWriteTokens) : 0,
     stopReason: String(response.stopReason ?? ''),
     loopDetected: response.loopDetected === true,
     loopSignature: String(response.loopSignature ?? ''),

package/src/pi-config.mjs

@@ -319,6 +319,18 @@ export function loadConfig(mode = 'once') {
       file.visualCaptureDir,
       'pi-output/visual-capture'
     ),
+    tokenUsageEventsFile: resolveFromCwd(
+      cwd,
+      'PI_TOKEN_USAGE_EVENTS_FILE',
+      file.tokenUsageEventsFile,
+      'pi-output/token-usage/events.jsonl'
+    ),
+    tokenUsageSummaryFile: resolveFromCwd(
+      cwd,
+      'PI_TOKEN_USAGE_SUMMARY_FILE',
+      file.tokenUsageSummaryFile,
+      'pi-output/token-usage/summary.json'
+    ),
     visualCaptureCommand: readString('PI_VISUAL_CAPTURE_CMD', file.visualCaptureCommand, ''),
     visualCaptureTimeoutSeconds: readInt('PI_VISUAL_CAPTURE_TIMEOUT', file.visualCaptureTimeoutSeconds, 300),
     visualReviewEnabled: readBool('PI_VISUAL_REVIEW_ENABLED', file.visualReviewEnabled, false),

package/src/pi-history.mjs

@@ -22,6 +22,8 @@ export function collectHistoryTargets(config) {
     config.changedFilesFile,
     config.lastPromptFile,
     config.lastIterationSummaryFile,
+    config.tokenUsageEventsFile,
+    config.tokenUsageSummaryFile,
     config.piRuntimeDir,
     config.visualFeedbackFile,
     config.testerFeedbackFile,

package/src/pi-report.mjs

@@ -2,6 +2,7 @@
 
 import { loadConfig } from './pi-config.mjs'
 import { readTelemetry } from './pi-telemetry.mjs'
+import { readTokenUsageSummary } from './pi-token-analysis.mjs'
 
 function summarizeBy(items, key) {
   const counts = new Map()
@@ -14,65 +15,103 @@ function summarizeBy(items, key) {
 
 async function main() {
   const config = loadConfig('once')
-  const events = await readTelemetry(config)
+  const [events, tokenSummary] = await Promise.all([
+    readTelemetry(config),
+    readTokenUsageSummary(config),
+  ])
   const recent = events.slice(-config.reportLimit)
 
   console.log(`Telemetry file: ${config.telemetryJsonl}`)
+  console.log(`Token events file: ${config.tokenUsageEventsFile}`)
+  console.log(`Token summary file: ${config.tokenUsageSummaryFile}`)
   console.log(`Total events: ${events.length}`)
   console.log(`Recent events shown: ${recent.length}`)
+  console.log(`Total attributed tokens: ${tokenSummary.totals.totalTokens}`)
 
   if (recent.length === 0) {
-    return
-  }
+    if (tokenSummary.totals.totalTokens <= 0) {
+      return
+    }
+  } else {
+    console.log('\nStatus counts:')
+    for (const [status, count] of summarizeBy(recent, 'status')) {
+      console.log(`- ${status}: ${count}`)
+    }
 
-  console.log('\nStatus counts:')
-  for (const [status, count] of summarizeBy(recent, 'status')) {
-    console.log(`- ${status}: ${count}`)
-  }
+    console.log('\nKinds:')
+    for (const [kind, count] of summarizeBy(recent, 'kind')) {
+      console.log(`- ${kind}: ${count}`)
+    }
 
-  console.log('\nKinds:')
-  for (const [kind, count] of summarizeBy(recent, 'kind')) {
-    console.log(`- ${kind}: ${count}`)
-  }
+    const iterationSummaries = recent.filter((event) => event.kind === 'iteration_summary')
+    const warningsByIteration = iterationSummaries
+      .filter((event) => String(event.riskWarnings ?? '').trim() !== '')
 
-  const iterationSummaries = recent.filter((event) => event.kind === 'iteration_summary')
-  const warningsByIteration = iterationSummaries
-    .filter((event) => String(event.riskWarnings ?? '').trim() !== '')
+    if (warningsByIteration.length > 0) {
+      console.log('\nLarge file warnings:')
+      for (const event of warningsByIteration.slice(-5)) {
+        console.log(`- iteration ${event.iteration}: ${event.riskWarnings}`)
+      }
+    }
+
+    const failureArtifacts = recent
+      .filter((event) => String(event.artifactPath ?? '').trim() !== '')
+      .slice(-5)
 
-  if (warningsByIteration.length > 0) {
-    console.log('\nLarge file warnings:')
-    for (const event of warningsByIteration.slice(-5)) {
-      console.log(`- iteration ${event.iteration}: ${event.riskWarnings}`)
+    if (failureArtifacts.length > 0) {
+      console.log('\nFailure artifacts:')
+      for (const event of failureArtifacts) {
+        const excerpt = String(event.outputExcerpt ?? '').trim()
+        console.log(`- iteration ${event.iteration} ${event.kind}: ${event.artifactPath}`)
+        if (excerpt !== '') {
+          console.log(`  excerpt: ${excerpt.split('\n')[0]}`)
+        }
+      }
+    }
+
+    const last = recent.at(-1)
+    if (last) {
+      console.log('\nLast event:')
+      console.log(`- timestamp: ${last.timestamp}`)
+      console.log(`- iteration: ${last.iteration}`)
+      console.log(`- phase: ${last.phase}`)
+      console.log(`- kind: ${last.kind}`)
+      console.log(`- status: ${last.status}`)
+      console.log(`- notes: ${last.notes}`)
     }
   }
 
-  const failureArtifacts = recent
-    .filter((event) => String(event.artifactPath ?? '').trim() !== '')
-    .slice(-5)
-
-  if (failureArtifacts.length > 0) {
-    console.log('\nFailure artifacts:')
-    for (const event of failureArtifacts) {
-      const excerpt = String(event.outputExcerpt ?? '').trim()
-      console.log(`- iteration ${event.iteration} ${event.kind}: ${event.artifactPath}`)
-      if (excerpt !== '') {
-        console.log(`  excerpt: ${excerpt.split('\n')[0]}`)
+  if (tokenSummary.totals.totalTokens > 0) {
+    const topFiles = tokenSummary.breakdowns.byFile.slice(0, 5)
+    const topTools = tokenSummary.breakdowns.byTool.slice(0, 5)
+    const topAttribution = tokenSummary.breakdowns.byAttribution.slice(0, 5)
+
+    console.log('\nToken coverage:')
+    console.log(`- file attributed: ${tokenSummary.coverage.fileAttributedTokens}`)
+    console.log(`- unattributed: ${tokenSummary.coverage.unattributedTokens}`)
+    console.log(`- file attribution ratio: ${Math.round(tokenSummary.coverage.fileAttributionRatio * 100)}%`)
+
+    if (topAttribution.length > 0) {
+      console.log('\nTop token attribution buckets:')
+      for (const item of topAttribution) {
+        console.log(`- ${item.label}: ${item.totalTokens}`)
       }
     }
-  }
 
-  const last = recent.at(-1)
-  if (!last) {
-    return
-  }
+    if (topTools.length > 0) {
+      console.log('\nTop token tools:')
+      for (const item of topTools) {
+        console.log(`- ${item.label}: ${item.totalTokens}`)
+      }
+    }
 
-  console.log('\nLast event:')
-  console.log(`- timestamp: ${last.timestamp}`)
-  console.log(`- iteration: ${last.iteration}`)
-  console.log(`- phase: ${last.phase}`)
-  console.log(`- kind: ${last.kind}`)
-  console.log(`- status: ${last.status}`)
-  console.log(`- notes: ${last.notes}`)
+    if (topFiles.length > 0) {
+      console.log('\nTop token files:')
+      for (const item of topFiles) {
+        console.log(`- ${item.label}: ${item.totalTokens}`)
+      }
+    }
+  }
 }
 
 main().catch((error) => {