xonecas.io
64875
Mc

mini-coder / commit c4dabd7

feat: add context tracking to the tui

xonecas2026-09-22 c4dabd71cd5741cc19fca2fe9d55840624002d53 parent b8846e7

4 files changed

AGENTS.md+32−20
@@ -51,7 +51,7 @@ are references. Extract ideas, do not port code.
5151 - Module boundaries (names may change, boundaries may not move):
5252 - `cli` — argument parsing, mode selection, process wiring.
5353 - `config` — load, validate, merge, resolve config; build `pi-ai` models.
54- - `session` — append-only JSONL store; projection to a `pi-ai` `Context`.
54+ - `session` — append-only JSONL store of `pi-ai` `Message`s.
5555 - `agent` — streaming loop, tool dispatch, pause/cancel state. No UI, no
5656 provider-specific code.
5757 - `tools` — `edit`, `bash` runners. No UI.
@@ -129,8 +129,8 @@ Decisions:
129129 ## Session persistence
130130
131131 `pi-ai` ships no session store. The session layer is a thin append-only JSONL
132-wrapper over `pi-ai`'s own `Context`/`Message` types. Never invent a parallel
133-message model.
132+wrapper around `pi-ai`'s own `Message` type. Never invent a parallel message
133+model.
134134
135135 One JSON object per line; never rewrite or delete committed lines. Records:
136136
@@ -162,11 +162,11 @@ Directory and file layout:
162162 - Append with `writeSync` + `fsyncSync` so committed lines survive a crash. A
163163 persistence failure stops the turn; never continue with unrecorded side
164164 effects.
165-- On read, tolerate a truncated final line; reject corruption in committed
166- history.
167-- Preserve message order and tool-call ↔ tool-result relationships. If partials
168- are ever persisted, use `AssistantMessageFrameEncoder` /
169- `reduceAssistantMessageFrames`, not a custom frame format.
165+- Preserve message order and tool-call ↔ tool-result relationships.
166+- Reading sessions back is deferred; when it is added, tolerate a truncated
167+ final line, reject corruption in committed history, and use `pi-ai`'s
168+ `AssistantMessageFrameEncoder` / `reduceAssistantMessageFrames` rather than a
169+ custom frame format.
170170
171171 ## Agent loop
172172
@@ -177,7 +177,7 @@ each result, and repeat. Stop when the assistant produces no tool calls, on
177177 cancel, or on a surfaced error.
178178
179179 Phases: `preparing`, `waitingModel`, `streaming`, `runningTool`, `pausing`,
180-`idle` (plus `cancelled` reachable from active states). Events: `phase`, `text`,
180+`idle`; a turn may be cancelled from any active phase. Events: `phase`, `text`,
181181 `reasoning`, `toolCall`, `toolOutput`, `toolResult`, `message`, `error`,
182182 `cancelled`, `complete`.
183183
@@ -218,7 +218,7 @@ then agent files (when `discoverAgentFiles`).
218218
219219 - Agent files: load `AGENTS.md` and `CLAUDE.md` from `~/.agents/` and the project
220220 root (`process.cwd()`), trimmed, each under a heading naming its path.
221-- Skills: scan each `skillsDirs` entry for `<dir>/SKILL.md`, read its
221+- Skills: scan each `skillsDirs` entry for `<dir>/<name>/SKILL.md`, read its
222222 frontmatter (`name`, `description`), and advertise the absolute path so the
223223 model can read it with `bash` on demand. Progressive disclosure only — never
224224 inline skill bodies. No directories means no skills; there is no implicit
@@ -238,9 +238,18 @@ Two regions:
238238 redrawn. User turns, assistant text, tool calls, and tool results go here. The
239239 terminal owns scrollback, selection, and scrolling.
240240 - **Live region** — at most the height of the terminal minus one row, holding
241- the in-flight line (the current incomplete line of whichever stream is
242- active), a one-row phase status, and the editor. Only this region is redrawn.
243- When idle it holds the editor alone: no in-flight line, no status row.
241+ a one-row context-usage readout, the in-flight line (the current incomplete
242+ line of whichever stream is active), a one-row phase status, and the editor,
243+ in that order. Only this region is redrawn. When idle it holds the context
244+ readout and the editor: no in-flight line, no status row.
245+
246+The context readout is always present, including idle, and is display-only: it
247+estimates the tokens the next request would send against `model.contextWindow`
248+and is never persisted. Anchor on the last `AssistantMessage.usage` — the prompt
249+that was sent is `totalTokens - output` — and estimate the anchor message and
250+everything after it; fall back to a ~1 token per 4 characters estimate of the
251+whole context. Emphasize as it approaches the window, and mark it full when
252+`used + model.maxTokens` would exceed it.
244253
245254 Scrollback is append-only and written before the live region is redrawn, never
246255 after. Blocks — a user turn, a tool call with its result body, a terminal-state
@@ -279,7 +288,7 @@ machine with a short timeout to distinguish a lone ESC from a sequence.
279288 - **CTRL+C = cancel the turn completely.** Abort the model request via
280289 `AbortSignal` and terminate the running tool's process group. Persist the
281290 aborted assistant message (`stopReason: "aborted"`). Return to idle; do not
282- undo completed side effects.
291+ undo completed side effects. When idle, it clears a non-empty draft instead.
283292 - **CTRL+D = exit**, only when the input is empty. Flush the session, restore the
284293 terminal, exit cleanly.
285294 - No max turns, tool-call budget, or automatic stop.
@@ -302,16 +311,19 @@ Accepted spellings: `-p <prompt>`, `--print <prompt>`, `-p=<prompt>`,
302311
303312 - Persistence failure stops the turn.
304313 - Surface provider errors with their message; do not mask, summarize, or retry.
305-- Local diagnostics only. No remote telemetry. Debug output goes to stderr
306- behind an explicit flag; redact secrets and prompt/tool content by default.
314+- Local diagnostics only. No remote telemetry. Any debug output would go to
315+ stderr behind an explicit flag; redact secrets and prompt/tool content by
316+ default.
307317 - No hidden stalls: every wait (model request, tool, pause) has a visible state
308- in the TUI and a diagnostic path in headless mode.
318+ in the TUI; in headless mode tool calls, tool output, errors, and
319+ cancellation are written to stderr.
309320
310321 ## Scope boundaries
311322
312323 Deferred, not rejected. Do not build unless explicitly promoted:
313324
314325 - context compaction / summarization / masking;
326+- reading or resuming sessions (the JSONL log is write-only today);
315327 - prompt templates;
316328 - custom agents / subagents / delegation;
317329 - an extension or plugin system;
@@ -330,9 +342,9 @@ Deferred, not rejected. Do not build unless explicitly promoted:
330342 code.
331343 - Prefer plain functions and objects over classes; keep exports minimal; define
332344 helpers near their use.
333-- Validate untrusted input once at the boundary (config, session records, tool
334- args) with Typebox, then keep internal code plain-typed. Do not spread
335- schema-derived types everywhere.
345+- Validate untrusted input once at the boundary (config, tool args) with
346+ Typebox, then keep internal code plain-typed. Do not spread schema-derived
347+ types everywhere.
336348 - Ask before adding a dependency. `diff` and `typebox` are approved;
337349 supply-chain risk is a real constraint.
338350 - Do not add tests unless explicitly asked. Verify manually.
src/tui/styles.ts+4−0
@@ -0,0 +1,4 @@
1+/** Dim foreground (SGR 2), restored to normal intensity (SGR 22). */
2+export function dim(text: string): string {
3+ return `\x1b[2m${text}\x1b[22m`;
4+}
src/tui/tui.ts+8−4
@@ -15,6 +15,8 @@ import type { Session } from "../session.ts";
1515 import type { ToolName } from "../config.ts";
1616 import { Terminal, expandTabs, wrapLine, type Key } from "./term.ts";
1717 import { Editor } from "./editor.ts";
18+import { dim } from "./styles.ts";
19+import { contextUsageLine, estimateContextTokens } from "./usage.ts";
1820
1921 export interface TuiOptions {
2022 models: Models;
@@ -43,10 +45,6 @@ const ERROR_PREFIX = " ! ";
4345 const EXIT_LINE = /^exit code: (.+)$/;
4446 const EDIT_HEADER = /^(Index: |={3,}$|--- |\+\+\+ )/;
4547
46-function dim(text: string): string {
47- return `\x1b[2m${text}\x1b[22m`;
48-}
49-
5048 /** The text after the last newline: what is still incomplete. */
5149 function incomplete(text: string): string {
5250 const index = text.lastIndexOf("\n");
@@ -502,6 +500,12 @@ class Tui {
502500 if (this.closed) return;
503501 const width = Math.max(1, this.term.width);
504502 const lines: string[] = [];
503+ lines.push(
504+ contextUsageLine(
505+ estimateContextTokens(this.messages, this.opts.systemPrompt, this.opts.tools),
506+ this.opts.model,
507+ ),
508+ );
505509 const pending = this.pending !== "" ? this.pending : this.preview;
506510 if (pending !== "") {
507511 const styled = this.pending === "" ? dim : (row: string) => row;
src/tui/usage.ts+75−0
@@ -0,0 +1,75 @@
1+import type { Api, AssistantMessage, ImageContent, Message, Model, TextContent, Tool } from "@earendil-works/pi-ai";
2+import { dim } from "./styles.ts";
3+
4+/** ~1 token per 4 characters, the heuristic pi-ai uses. */
5+function estimateText(text: string): number {
6+ return Math.ceil(text.length / 4);
7+}
8+
9+function contentChars(content: string | Array<TextContent | ImageContent>): number {
10+ if (typeof content === "string") return content.length;
11+ let chars = 0;
12+ for (const block of content) if (block.type === "text") chars += block.text.length;
13+ return chars;
14+}
15+
16+/** Characters one message contributes. Image and thinking blocks are ignored: an undercount. */
17+function messageChars(message: Message): number {
18+ if (message.role === "system") return contentChars(message.content);
19+ if (message.role === "user") return contentChars(message.content);
20+ if (message.role === "toolResult") return contentChars(message.content);
21+ let chars = 0;
22+ for (const block of message.content) {
23+ if (block.type === "text") chars += block.text.length;
24+ else if (block.type === "toolCall") chars += block.name.length + JSON.stringify(block.arguments).length;
25+ }
26+ return chars;
27+}
28+
29+/**
30+ * Rough token count for the context the next request would send, used only for
31+ * display. Anchors on the last provider-reported usage — `totalTokens - output`
32+ * is the input side of that request — and estimates the messages at and after
33+ * it; without a usable anchor, estimates system prompt, tools and messages.
34+ * Anchors with `totalTokens === 0` (aborted or errored) are skipped.
35+ */
36+export function estimateContextTokens(messages: Message[], systemPrompt: string, tools: Tool[]): number {
37+ let anchor: AssistantMessage | undefined;
38+ let anchorIndex = -1;
39+ for (let i = messages.length - 1; i >= 0; i--) {
40+ const message = messages[i];
41+ if (message.role === "assistant" && message.usage.totalTokens > 0) {
42+ anchor = message;
43+ anchorIndex = i;
44+ break;
45+ }
46+ }
47+ if (anchor !== undefined) {
48+ let tail = 0;
49+ for (let i = anchorIndex; i < messages.length; i++) tail += messageChars(messages[i]);
50+ return anchor.usage.totalTokens - anchor.usage.output + Math.ceil(tail / 4);
51+ }
52+ let total = estimateText(systemPrompt) + estimateText(JSON.stringify(tools));
53+ for (const message of messages) total += Math.ceil(messageChars(message) / 4);
54+ return total;
55+}
56+
57+/** `812`, `12.3k`, `1.24M` — trailing zeros trimmed. */
58+export function formatTokens(n: number): string {
59+ if (n < 1000) return String(n);
60+ const scaled = n < 1_000_000 ? n / 1000 : n / 1_000_000;
61+ const unit = n < 1_000_000 ? "k" : "M";
62+ return `${scaled.toFixed(unit === "k" ? 1 : 2).replace(/\.?0+$/, "")}${unit}`;
63+}
64+
65+/**
66+ * The context row: dim, SGR 33 as the window nears, SGR 31 once the next
67+ * request could not carry a maximum-size reply.
68+ */
69+export function contextUsageLine(used: number, model: Model<Api>): string {
70+ const percent = (used / model.contextWindow) * 100;
71+ const sizes = `${formatTokens(used)}/${formatTokens(model.contextWindow)}`;
72+ if (used + model.maxTokens > model.contextWindow) return `\x1b[31mctx full · ${sizes}\x1b[39m`;
73+ const text = `ctx ${sizes} · ${Math.round(percent)}%`;
74+ return percent >= 85 ? `\x1b[33m${text}\x1b[39m` : dim(text);
75+}