82 lines
6.3 KiB
Markdown
82 lines
6.3 KiB
Markdown
---
|
|
status: resolved
|
|
parent: "[[057-pi-ui-customization-map]]"
|
|
blocked-by: []
|
|
resolved-at: "2026-07-31T23:58:11-04:00"
|
|
tags:
|
|
- ticket/research
|
|
---
|
|
|
|
# Pi context token data research
|
|
|
|
## Question
|
|
|
|
What token and context-window usage data does Pi expose to extensions, footer renderers, session state, or model state, and is there enough structured data to draw a multi-colored context usage bar by token category?
|
|
|
|
## Findings
|
|
|
|
Pi exposes a current context-usage API to extensions.
|
|
The extensions docs define `ctx.getContextUsage()` and say it returns current context usage for the active model, using last assistant usage when available and estimating tokens for trailing messages.
|
|
The implementation returns `{ tokens, contextWindow, percent }` when the model has a positive context window.
|
|
After compaction, if there is no valid assistant usage after the compaction boundary, it returns `{ tokens: null, contextWindow, percent: null }` because the context token count is unknown until the next LLM response.
|
|
Sources: `docs/extensions.md` section `ctx.getContextUsage()`; `dist/core/agent-session.js` `getContextUsage()`.
|
|
|
|
Pi's built-in footer already uses the same context-usage data.
|
|
The footer calls `this.session.getContextUsage()`, falls back to the active model's `contextWindow` when needed, formats percentage as either a number or `?`, and colors the text as warning above 70% and error above 90%.
|
|
It appends an `(auto)` marker when automatic compaction is enabled.
|
|
Sources: `dist/modes/interactive/components/footer.js`.
|
|
|
|
Pi session usage totals have structured categories for `input`, `output`, `cacheRead`, and `cacheWrite`.
|
|
The built-in footer iterates all session entries, adds assistant-message usage, tool-result nested usage, branch-summary usage, and compaction usage, then renders usage parts as `↑`, `↓`, `R`, and `W` plus cache-hit rate when cache data exists.
|
|
The session export helper likewise exposes totals with `input`, `output`, `cacheRead`, `cacheWrite`, `total`, `cost`, and `contextUsage`.
|
|
Sources: `dist/modes/interactive/components/footer.js`; `dist/core/agent-session.js` session stats export logic.
|
|
|
|
Custom footers can calculate usage totals by iterating `ctx.sessionManager.getBranch()` or broader session entries if available.
|
|
The shipped custom footer example sums `m.usage.input`, `m.usage.output`, and `m.usage.cost.total` from assistant messages and notes that token stats come from `ctx.sessionManager` and `ctx.model`.
|
|
That example does not include cache read/write or compaction/tool-result usage, but the built-in footer source shows those categories exist in session entries.
|
|
Sources: `examples/extensions/custom-footer.ts`; `dist/modes/interactive/components/footer.js`.
|
|
|
|
The model context-window size is exposed on the active model.
|
|
The model docs define `contextWindow` as a model field with a default of `128000`, and custom provider examples register models with `contextWindow` and `maxTokens`.
|
|
The built-in footer reads `state.model?.contextWindow`, and `ctx.getContextUsage()` reads `model.contextWindow`.
|
|
Sources: `docs/models.md` model field table; `docs/extensions.md` dynamic provider example; `dist/core/agent-session.js`; `dist/modes/interactive/components/footer.js`.
|
|
|
|
There is not enough public structured data for a true by-content-type context-window bar in version one.
|
|
`ctx.getContextUsage()` exposes total tokens, context window, and percent, but not a breakdown by prompt category such as system prompt, user messages, assistant messages, tool results, context files, skills, or summaries.
|
|
The session usage categories are billing/usage categories from provider responses and nested calls: input, output, cache read, and cache write.
|
|
They are not a decomposition of the current context window contents.
|
|
Sources: `docs/extensions.md` `ctx.getContextUsage()`; `dist/core/agent-session.js` `getContextUsage()`; `dist/modes/interactive/components/footer.js` usage aggregation.
|
|
|
|
A multi-colored bar is still feasible, but the honest v1 categories are limited.
|
|
The bar can show total context-window usage from `ctx.getContextUsage()` and, while below a chosen danger threshold, can color segments using available provider usage categories such as input, output, cache read, and cache write.
|
|
However, that would visualize cumulative usage totals rather than what is actually occupying the current context window.
|
|
If the user specifically wants “what type of tokens are taking up the context window,” the implementation needs either an approximation from session entries or a new Pi API that exposes context-preparation buckets.
|
|
|
|
## Answer
|
|
|
|
Pi exposes enough data for a compact context usage bar showing total context-window percentage and threshold coloring.
|
|
Pi exposes structured token usage categories for cumulative session accounting.
|
|
Pi does not currently expose a public structured breakdown of current context-window occupancy by content type.
|
|
|
|
The prototype should therefore test two layers:
|
|
|
|
1. A truthful total context bar using `ctx.getContextUsage()`.
|
|
2. Optional segment coloring from available usage categories, clearly treated as usage composition rather than exact context occupancy.
|
|
|
|
## Limitations
|
|
|
|
This research used Pi docs and installed package source.
|
|
It did not instrument a live extension to inspect all runtime context objects.
|
|
The prototype can confirm whether additional useful fields are reachable in practice.
|
|
|
|
The source code contains an `estimateContextTokens(this.messages)` call, but the public extension API returns only the aggregate estimate.
|
|
Without depending on private internals, a customization should not claim exact content-type breakdown.
|
|
|
|
## Citations
|
|
|
|
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md`, section `ctx.getContextUsage()`.
|
|
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/models.md`, model field table and provider examples.
|
|
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/examples/extensions/custom-footer.ts`.
|
|
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/dist/core/agent-session.js`, `getContextUsage()` and session stats export logic.
|
|
- `/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/dist/modes/interactive/components/footer.js`.
|