@gavin-hu/my-pi-agent 0.15.0 → 0.16.0

package/extensions/bytefly/panel/tui/frame.ts

@@ -28,8 +28,8 @@ import { selectableRange, type PanelEntry } from "./entries.ts";
 export const SCREEN_DEFAULT_ROWS = 16;
 /** Fixed rows around the body: header, summary, blank, blank, hint, blank. */
 export const FRAME_ROWS = 6;
-/** Detail rows reserved for the focused row. */
-export const DETAIL_ROWS = 4;
+/** Detail rows reserved for the focused row: its head, one description line, and its origin. */
+export const DETAIL_ROWS = 3;
 /** Body rows that must survive before the detail pane collapses to its title. */
 export const MIN_BODY_ROWS = 3;
 /** Detail rows when the terminal height is unknown and the focused row is expanded. */

package/extensions/bytefly/panel/tui/settings-view.ts

@@ -27,6 +27,8 @@ const PI_SETTINGS_FILE = "settings.json";
 const ROW_PREFIX_WIDTH = 4;
 /** Columns a value keeps when the row has to choose between the label and the value. */
 const MIN_VALUE_WIDTH = 8;
+/** Columns between the label and its value. */
+const VALUE_GAP = 2;
 
 /**
  * The editing cell: the buffer around the caret, scrolled so the caret is always
@@ -56,7 +58,7 @@ export function settingsSummary(theme: Theme, width: number, scope: PanelScope,
 	return countsLine(theme, width, settingsSummarySegments(scope, count));
 }
 
-/** One setting row: a checkbox for booleans, the value right-aligned. */
+/** One setting row: a checkbox for booleans, and the value beside the label. */
 export function settingRow(
 	theme: Theme,
 	width: number,
@@ -67,7 +69,7 @@ export function settingRow(
 	const label = sanitizeLine(view.label);
 	// Keep the whole label when it fits, and never let a long value or an editing
 	// buffer erase it: the value gets what is left, with a floor of eight columns.
-	const available = Math.max(1, width - ROW_PREFIX_WIDTH - 1);
+	const available = Math.max(1, width - ROW_PREFIX_WIDTH - VALUE_GAP);
 	const labelReserve = Math.min(visibleWidth(label), Math.max(0, available - MIN_VALUE_WIDTH));
 	const valueBudget = Math.max(1, available - labelReserve);
 	const rawValue = editing ? editingCell(editing.buffer, editing.caret, valueBudget) : view.valueLabel;
@@ -78,6 +80,9 @@ export function settingRow(
 		labelRole: selected ? "accent" : "label",
 		trailing: clip(sanitizeLine(rawValue), valueBudget),
 		trailingRole: editing ? "accent" : "meta",
+		// The value sits beside the label, so a wide terminal never strands it at
+		// the far edge where the eye has to travel to read it.
+		align: "inline",
 	});
 }
 
@@ -137,16 +142,7 @@ export function settingDetail(options: {
 
 /** The section's key hints, in the order they drop as the width runs out. */
 export function settingsHints(json = false): string[] {
-	return [
-		"Esc close",
-		"←/→",
-		"Space change",
-		"Tab scope",
-		"u reset",
-		json ? "J hide" : "J JSON",
-		"[ ] group",
-		"↑/↓ select",
-	];
+	return ["Esc close", "←/→", "Space change", "Tab scope", "u reset", json ? "J hide" : "J JSON", "↑/↓ select"];
 }
 
 /**

package/extensions/bytefly/panel/tui.ts

@@ -352,12 +352,10 @@ export class PanelComponent implements Component {
 			this.select(lastRow(this.activeEntries()));
 			return;
 		}
-		if (data === "[") {
-			this.jumpGroup(-1);
-			return;
-		}
-		if (data === "]") {
-			this.jumpGroup(1);
+		// Only Extensions carries group headings; the Settings list is flat, so the
+		// keys would move the cursor nowhere there.
+		if (this.section === "extensions" && (data === "[" || data === "]")) {
+			this.jumpGroup(data === "[" ? -1 : 1);
 			return;
 		}
 		switch (navIntent(data)) {

package/extensions/bytefly/picker/resources.ts

@@ -141,8 +141,12 @@ export function getDisplayName(item: ResourceItem): string {
 	return parentFolder === "extensions" ? fileName : `${parentFolder}/${fileName}`;
 }
 
-/** Stable identity for a resource row, used to keep the cursor across renders. */
-function itemKey(item: ResourceItem): string {
+/**
+ * Stable identity for one resource, independent of the directory it sits in: a
+ * row key for the cursor, a merge key for the panel, and `report:<name>` for a
+ * report with no resolved item.
+ */
+export function resourceKey(item: ResourceItem): string {
 	return `${item.metadata.source}:${item.path}`;
 }
 
@@ -190,7 +194,7 @@ export function buildEntries(items: ResourceItem[], agentDir: string): Entry[] {
 	for (const group of sorted) {
 		const items = [...group.items].sort((a, b) => getDisplayName(a).localeCompare(getDisplayName(b)));
 		entries.push({ kind: "group", key: group.key, label: group.label, count: items.length });
-		for (const item of items) entries.push({ kind: "item", key: itemKey(item), item, label: getDisplayName(item) });
+		for (const item of items) entries.push({ kind: "item", key: resourceKey(item), item, label: getDisplayName(item) });
 	}
 	return entries;
 }

package/extensions/bytefly/working/register.ts

@@ -30,6 +30,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { defaultInterval } from "../../../lib/timer.ts";
 import { WORKING_CONFIG } from "./config.ts";
 import { workingCounter } from "./format.ts";
 
@@ -41,17 +42,10 @@ export interface WorkingDeps {
 	schedule?: (tick: () => void, intervalMs: number) => () => void;
 }
 
-/** A repeating timer that never holds the process open on its own. */
-function defaultSchedule(tick: () => void, intervalMs: number): () => void {
-	const timer = setInterval(tick, intervalMs);
-	(timer as { unref?: () => void }).unref?.();
-	return () => clearInterval(timer);
-}
-
 /** Register the timer; it runs only in interactive (`tui`) sessions. */
 export function registerWorkingTimer(pi: ExtensionAPI, deps: WorkingDeps = {}): void {
 	const now = deps.now ?? (() => Date.now());
-	const schedule = deps.schedule ?? defaultSchedule;
+	const schedule = deps.schedule ?? ((tick, intervalMs) => defaultInterval(intervalMs, tick));
 	let cancel: (() => void) | undefined;
 	let startedAt = 0;
 	// A boolean, not `startedAt === 0`: an injected clock is allowed to start at 0.

package/extensions/check/tools.ts

@@ -16,14 +16,7 @@ import type { ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-codi
 import { Type, type Static } from "typebox";
 import { sanitizeLine } from "../../lib/format.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
-import {
-	elapsedSuffix,
-	errorLine,
-	rejectionLine,
-	reuseCallText,
-	syncElapsedTimer,
-	toolCallTitle,
-} from "../../lib/tui/tool.ts";
+import { callLine, elapsedSuffix, errorLine, rejectionLine, syncElapsedTimer } from "../../lib/tui/tool.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { formatCheckReport } from "./format.ts";
 import { CheckResultBlock } from "./render.ts";
@@ -138,9 +131,7 @@ export function registerCheckTool(pi: ExtensionAPI, runtime: CheckRuntime): void
 
 		renderCall(args, theme, context) {
 			const subject = context.argsComplete ? (args.target ?? "all") : "…";
-			const text = reuseCallText(context.lastComponent, "", "middle");
-			text.setText(toolCallTitle(theme, `${TOOL_NAME} `) + paint(theme, "meta", sanitizeLine(subject)));
-			return text;
+			return callLine(theme, context.lastComponent, TOOL_NAME, subject, "middle");
 		},
 
 		renderResult(result, options, theme, context) {

package/extensions/context/README.md

@@ -0,0 +1,162 @@
+# context — see where the window goes
+
+A read-only report of the context window, with one action hanging off it: when
+the conversation is too full, the report is where you decide to compact. It is
+command-only on purpose — no tool is declared, so the model's prompt budget is
+untouched.
+
+```bash
+pi --extension ./extensions/context    # load just this extension
+pi -e .                                # load the whole @gavin-hu/my-pi-agent package
+pi install ./                          # install the package
+```
+
+## What it does
+
+- Registers one command, `/context`. In the TUI it opens a docked screen; in
+  `rpc`, `json`, and `print` it notifies the same facts as plain text.
+- Reports Pi's own estimate first — tokens, window, percentage, free space, the
+  auto-compaction threshold, and the headroom left before it — then the
+  composition: the system prompt, the active tool definitions, the conversation
+  by role, injected pack context grouped by type, summaries, and shell output.
+- Names the difference between Pi's total and the composition estimate instead
+  of forcing the parts to add up: provider usage plus trailing messages is not
+  the same measurement as characters/4 over the rows.
+- Reads the branch's compaction history: how many compactions there have been,
+  what the newest one cut from and to, and how much its summary costs.
+- Lists the five largest single blocks, so a report that is mostly one tool
+  result says so.
+- Compacts from the report: `c` on the screen asks first, `/context compact
+  [instructions]` runs directly. Both refuse while the agent is busy — a
+  streaming turn or a running compaction.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/context` | The report: a screen in the TUI, a notification elsewhere |
+| `/context compact [instructions]` | Compact from the report; refuses while a turn or a compaction is running, so it never interrupts one. Instructions focus the summary |
+
+### Screen keys
+
+| Key | Action |
+|---|---|
+| `↑` / `↓`, `j` / `k` | Scroll one line |
+| `PgUp` / `PgDn` | Scroll one page |
+| `Home` / `End`, `g` / `G` | Jump to the start or the end |
+| `c` | Compact after a `y`/`N` confirmation |
+| `r` | Re-read the session and repaint |
+| `Esc` / `q` | Close the screen |
+
+`c` is refused while the agent is busy — a streaming turn or a compaction
+already running: Pi's compaction starts by aborting the active turn, and one
+keystroke should not discard a running answer. Wait for the turn (or stop it),
+then compact. Pi's built-in `/compact` still aborts when that is what you asked
+for.
+
+## Behaviour by mode
+
+`/context` works everywhere. The screen needs `ctx.mode === "tui"`; the other
+modes notify the same report as text, including the composition rows and the
+largest blocks. `/context compact` is the same in every mode and reports through
+`ctx.ui.notify` when it finishes or fails.
+
+## How the numbers are computed
+
+| Row | Source |
+|---|---|
+| Headline (`tokens`, `percent`) | `ctx.getContextUsage()`: the last valid provider usage plus Pi's estimate of the messages after it. `tokens` is `null` between a compaction and the next successful reply, because the last usage describes the pre-compaction context. |
+| Window | `getContextUsage().contextWindow`, then the active model's `contextWindow`. |
+| System prompt | A `system` message in the projection when one exists, otherwise `ctx.getSystemPrompt()` at characters/4. |
+| Tool definitions | `pi.getAllTools()` filtered to `pi.getActiveTools()`, over each active tool's name, description, and parameter schema at characters/4. `promptGuidelines` are counted in the system prompt instead, because Pi renders them into its rules section. |
+| Conversation rows | `sessionManager.buildSessionProjection().messages`, each counted with Pi's own `estimateTokens` (characters/4; an image is 4800 characters; a tool call is its name plus its JSON arguments). |
+| Injected context | `custom` messages grouped by `customType`, biggest first; the five largest types are named and the rest fold into one row. |
+| Threshold | `compaction.modelOverrides["provider/id"]`, then `compaction`, then `DEFAULT_COMPACTION_SETTINGS` — the same three-step fallback Pi uses. |
+| Compaction history | `getLatestCompactionEntry(branch)` and the branch's `compaction` count. The summary's cost is the summary text at characters/4. |
+| Drift | `tokens - estimate`. Positive means Pi's total includes overhead no row attributes; negative means the rows are larger, which happens before the first reply because Pi's message-only fallback omits the system prompt and tool definitions. Both numbers are estimates and the row says which direction the gap runs. |
+
+## Limitations
+
+- The composition is an estimate. A provider tokenizer differs from characters/4,
+  images are a fixed guess, and the system prompt is measured from its string, so
+  the rows will not exactly equal the headline. The drift row is the honest
+  difference, not a rounding bug.
+- Right after a compaction `tokens` is unknown until the next reply. The screen
+  shows the composition estimate and says the total is pending.
+- The report is a snapshot. It is re-read when the screen opens, on `r`, and after
+  a compaction; it does not watch the session.
+- Tool definitions are estimated from the schemas, not from the rendered prompt, so
+  a host that formats them differently will move the drift.
+- Before the session's first reply, Pi's total is a message-only estimate: it
+  leaves out the system prompt and tool definitions, so the rows can exceed it.
+  Once a reply exists the host total includes them.
+- Without a model whose `contextWindow` is known there is no threshold to show;
+  the report says so and leaves compaction to Pi.
+- Descriptors in **Largest blocks** are one line, clipped to 40 characters; a long
+  tool result is represented by its tool name, not its content.
+
+## Non-goals
+
+- No automatic compaction policy: Pi owns the threshold, and this extension only
+  reports it and forwards a manual request.
+- No tokenizer API call, no provider SDK, and no network.
+- No trimming, editing, or pinning of individual messages.
+- No second `/compact`: the guarded compact is the screen's own action, not a
+  replacement.
+- No persistent widget; unlike `goal`/`todo`, nothing is added to the rails.
+
+## Pi integration
+
+| Contract | Detail |
+|---|---|
+| Registration | The default export registers the `/context` command and nothing else. No tool, no flag, no shortcut, no session hook. |
+| Tool surface | None. Command-only, so there is no `promptSnippet`, `annotations`, `executionMode`, or `outputSchema`. |
+| Host reads | `ctx.getContextUsage()`, `ctx.getSystemPrompt()`, `ctx.model`, `ctx.isIdle()`, `ctx.sessionManager.buildSessionProjection()` / `getBranch()`, `pi.getActiveTools()` / `getAllTools()` / `getSettings()`. All in `collect.ts`. |
+| Action | `ctx.compact({ customInstructions, onComplete, onError })`. It is fire-and-forget; the callbacks repaint the screen or notify the command's caller. |
+| State | None. The report is derived from the live session on demand, so `/resume` and `/tree` need no replay and nothing can drift. |
+| UI | `ctx.ui.custom` behind `ctx.mode === "tui"` and `withRailsSuppressed`; `ctx.ui.notify` elsewhere. |
+| Plan mode | `/context` is usable while planning. `/context compact` mutates the session; commands are user-initiated and are not gated by the read-only tool policy. |
+
+## Design notes
+
+- **The headline is the host's, the parts are ours.** Pi already computes a
+  context estimate that blends the last provider usage with a trailing estimate;
+  recomputing it would be a second policy. The report reads it and then labels
+  its own composition as an estimate, with `drift` as the visible difference.
+- **One collector.** `getContextUsage()` rebuilds the session projection, and the
+  composition needs that projection too, so `collect.ts` reads once per open or
+  refresh. The screen holds the report; arrow keys only move a slice.
+- **The threshold is resolved, not approximated.** The report repeats Pi's
+  three-step fallback rather than reading only the shared setting, because
+  predicting the wrong threshold is worse than not predicting one.
+- **A guarded compact, not a second one.** `/compact` is Pi's; `/context compact`
+  exists so the report's action works in every mode, and it adds the one guard
+  that matches this package's "never lose work" rule: it will not abort a turn.
+- **Sanitized at the boundary.** Custom types, message text, and tool names are
+  model- or extension-authored, so every descriptor goes through `sanitizeLine`
+  before it is painted.
+- **A docked screen with a clamped body.** The frame follows
+  `lib/tui/chrome.ts` and `lib/tui/cursor.ts`, and the body budget leaves the hint
+  row visible on a short terminal.
+
+## Files
+
+| File | Responsibility |
+|---|---|
+| `index.ts` | Factory: the `PI_DISABLED_EXTENSIONS` guard and command registration. |
+| `commands.ts` | `/context` and `/context compact`: the TUI mount, the text fallback, and the idle guard. |
+| `collect.ts` | The host boundary: one read of usage, prompt, tools, settings, projection, and branch. |
+| `report.ts` | The pure builder: composition, reserve resolution, compaction history, largest blocks. |
+| `format.ts` | The plain-text report for non-TUI modes. |
+| `tui.ts` | `ContextComponent`: gauge, rows, scroll, confirmation, feedback. |
+| `types.ts` | `ContextInputs`, `ContextReport`, buckets, and the host types named through `ReturnType<…>`. |
+
+## Testing
+
+`bun test extensions/context` covers the pure report (composition, the reserve
+fallback chain, an unknown window, a missing host total, drift in both
+directions, compaction history, and descriptor clipping/sanitization), the
+screen (width safety at five widths, scroll, refresh, the confirmation, a
+running-turn refusal, and failures), and the extension surface (one command, no
+tool, the disabled switch, and every command path) through
+`test/helpers/fixtures/context.ts`.

package/extensions/context/collect.ts

@@ -0,0 +1,53 @@
+/**
+ * The host boundary: read Pi's own numbers once, in one place.
+ *
+ * Everything here is a read. `getContextUsage()` already rebuilds the session
+ * projection, and the composition needs that projection too, so the caller
+ * collects once per screen open or refresh rather than per frame; the component
+ * then renders from the report it was handed.
+ *
+ * Only active tools are counted, because only they are declared to the model.
+ * A tool definition is estimated from the schema and text the host would send,
+ * not from a rendered prompt, so the number is an estimate like every other row.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { estimateChars } from "./report.ts";
+import type { ContextInputs } from "./types.ts";
+
+/** Estimated tokens a set of tool definitions adds to the request. */
+function toolTokens(tools: ReturnType<ExtensionAPI["getAllTools"]>): number {
+	let chars = 0;
+	for (const tool of tools) {
+		// `promptGuidelines` are rendered into the system prompt's rules section,
+		// which `ctx.getSystemPrompt()` already contains, so counting them here
+		// would count them twice.
+		chars += JSON.stringify({ name: tool.name, description: tool.description, parameters: tool.parameters }).length;
+	}
+	return estimateChars(chars);
+}
+
+/** Read everything the report needs from one host context. */
+export function collectInputs(pi: ExtensionAPI, ctx: ExtensionContext): ContextInputs {
+	const usage = ctx.getContextUsage();
+	const model = ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : null;
+	const activeNames = new Set(pi.getActiveTools());
+	const allTools = pi.getAllTools();
+	const activeTools = allTools.filter((tool) => activeNames.has(tool.name));
+	const session = ctx.sessionManager;
+
+	return {
+		model,
+		window: usage?.contextWindow ?? ctx.model?.contextWindow ?? 0,
+		systemPrompt: ctx.getSystemPrompt(),
+		tools: {
+			active: activeNames.size,
+			total: allTools.length,
+			tokens: toolTokens(activeTools),
+		},
+		usage,
+		messages: session.buildSessionProjection().messages,
+		branch: session.getBranch(),
+		settings: pi.getSettings(),
+	};
+}

package/extensions/context/commands.ts

@@ -0,0 +1,100 @@
+/**
+ * The `/context` command: the report, and the one action it justifies.
+ *
+ * A bare `/context` opens the screen in the TUI and prints the same facts as
+ * text everywhere else. `/context compact [instructions]` is deliberately not a
+ * second `/compact`: it refuses to start while a turn is streaming, because Pi's
+ * own compaction begins with an abort, and reports the before/after numbers when
+ * it finishes.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { formatTokens } from "../../lib/format.ts";
+import { withRailsSuppressed } from "../../lib/rails.ts";
+import { messageOf } from "../../lib/errors.ts";
+import { collectInputs } from "./collect.ts";
+import { formatReport } from "./format.ts";
+import { buildReport } from "./report.ts";
+import { ContextComponent } from "./tui.ts";
+
+/** The command's argument surface, shared by the description and the usage warning. */
+const CONTEXT_USAGE = "/context [compact [instructions]]";
+
+/** Advise the next token after `/context`. */
+function completeArg(prefix: string): Array<{ value: string; label: string }> | null {
+	const trimmed = prefix.trimStart();
+	if (trimmed.includes(" ")) return null;
+	const options = ["compact"].filter((option) => option.startsWith(trimmed));
+	return options.length > 0 ? options.map((value) => ({ value: `${value} `, label: value })) : null;
+}
+
+/** The report as a screen in the TUI, or as a notification elsewhere. */
+async function openReport(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<void> {
+	const report = buildReport(collectInputs(pi, ctx));
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(formatReport(report));
+		return;
+	}
+
+	// The dock screen owns the editor slot; hide the rails for its lifetime.
+	await withRailsSuppressed(pi, () =>
+		ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+			return new ContextComponent({
+				theme,
+				report,
+				read: () => buildReport(collectInputs(pi, ctx)),
+				isIdle: () => ctx.isIdle(),
+				compact: (instructions, callbacks) => {
+					ctx.compact({
+						customInstructions: instructions,
+						onComplete: callbacks.done,
+						onError: callbacks.fail,
+					});
+				},
+				close: () => done(),
+				requestRender: () => tui.requestRender(),
+				viewportRowsSource: () => tui.terminal?.rows,
+			});
+		}),
+	);
+}
+
+/** Compact without interrupting a running turn, then report what changed. */
+function compact(ctx: ExtensionCommandContext, instructions: string): void {
+	if (!ctx.isIdle()) {
+		ctx.ui.notify(
+			"The agent is busy — a turn or a compaction is running. Wait for it to finish (or stop the turn) " +
+				"before compacting; `/context compact` never interrupts a turn. Pi's `/compact` aborts it if that is what you want.",
+			"warning",
+		);
+		return;
+	}
+	ctx.compact({
+		customInstructions: instructions || undefined,
+		onComplete: (result) => {
+			const after = result.estimatedTokensAfter === undefined ? "?" : formatTokens(result.estimatedTokensAfter);
+			ctx.ui.notify(`Compacted ${formatTokens(result.tokensBefore)} → ${after}.`, "info");
+		},
+		onError: (error) => ctx.ui.notify(`Compaction failed: ${messageOf(error)}`, "error"),
+	});
+}
+
+export function registerCommands(pi: ExtensionAPI): void {
+	pi.registerCommand("context", {
+		description: `Show where the context window goes, and compact from the report: ${CONTEXT_USAGE}`,
+		getArgumentCompletions: completeArg,
+		handler: async (args, ctx) => {
+			const trimmed = args.trim();
+			if (trimmed === "") {
+				await openReport(pi, ctx);
+				return;
+			}
+			const [sub = "", ...rest] = trimmed.split(/\s+/);
+			if (sub === "compact") {
+				compact(ctx, rest.join(" ").trim());
+				return;
+			}
+			ctx.ui.notify(`Unknown /context subcommand "${sub}". Usage: ${CONTEXT_USAGE}`, "warning");
+		},
+	});
+}

package/extensions/context/format.ts

@@ -0,0 +1,82 @@
+/**
+ * The plain-text form of a report, for RPC, JSON, and print sessions.
+ *
+ * The screen draws its own colour and width-aware rows; this module keeps the
+ * same facts in the order the screen uses, so a reader in a non-TUI mode sees
+ * the same sentence the terminal would. No theme, no terminal width.
+ */
+
+import { formatTokens } from "../../lib/format.ts";
+import type { ContextBucket, ContextReport } from "./types.ts";
+
+/** `Context · 124k / 200k (62%)`, or why one of the numbers is missing. */
+export function formatHeadline(report: ContextReport): string {
+	if (report.window <= 0) return "Context · model context window unknown";
+	if (report.tokens === null) {
+		return `Context · ${formatTokens(report.window)} window · tokens unknown until the next reply`;
+	}
+	const percent = report.percent === null ? "?" : `${Math.round(report.percent)}%`;
+	return `Context · ${formatTokens(report.tokens)} / ${formatTokens(report.window)} (${percent})`;
+}
+
+/** The free space, the auto-compaction threshold, and what it keeps. */
+export function formatBudget(report: ContextReport): string {
+	if (report.window <= 0) {
+		return "No model window, so no threshold: Pi's compaction needs a model with a known context window.";
+	}
+	const parts: string[] = [];
+	if (report.free !== null) parts.push(`${formatTokens(report.free)} free`);
+	parts.push(report.enabled ? `auto-compact at ${formatTokens(report.autoCompactAt)}` : "auto-compaction off");
+	if (report.headroom !== null) {
+		parts.push(
+			report.headroom >= 0
+				? `${formatTokens(report.headroom)} headroom`
+				: `past the threshold by ${formatTokens(-report.headroom)}`,
+		);
+	}
+	parts.push(`keeps newest ${formatTokens(report.keepRecentTokens)}`);
+	return parts.join(" · ");
+}
+
+/** The branch's compaction history in one line. */
+export function formatCompaction(report: ContextReport): string {
+	const { count, last } = report.compaction;
+	if (!last) return "none yet";
+	const times = `${count} so far`;
+	return `${times} · last ${last.at} cut ${formatTokens(last.tokensBefore)} → ${formatTokens(last.summaryTokens)} summary (freed ${formatTokens(last.freed)})`;
+}
+
+/** The difference between the host's total and the composition estimate, when it is not zero. */
+export function formatDrift(report: ContextReport): string | undefined {
+	if (report.drift === null || report.drift === 0) return undefined;
+	if (report.drift > 0) {
+		return `Provider overhead · +${formatTokens(report.drift)} not attributed to a row`;
+	}
+	return `Estimate drift · the rows are ${formatTokens(-report.drift)} above the host's total; both are estimates`;
+}
+
+/** One composition row, as plain text. */
+export function formatBucket(bucket: ContextBucket): string {
+	const indent = bucket.depth > 0 ? "    " : "  ";
+	const label = bucket.label.padEnd(bucket.depth > 0 ? 22 : 24);
+	const tokens = formatTokens(bucket.tokens).padStart(6);
+	const share = `${bucket.share.toFixed(1)}%`.padStart(6);
+	const note = bucket.note ? `  ${bucket.note}` : "";
+	return `${indent}${label}${tokens}${share}${note}`;
+}
+
+/** The report as a notification body: headline, budget, rows, then what happened. */
+export function formatReport(report: ContextReport): string {
+	const lines = [formatHeadline(report), formatBudget(report)];
+	if (report.buckets.length > 0) lines.push("", ...report.buckets.map(formatBucket));
+	const drift = formatDrift(report);
+	if (drift) lines.push("", drift);
+	lines.push("", `Compaction · ${formatCompaction(report)}`);
+	if (report.largest.length > 0) {
+		const blocks = report.largest
+			.map((block) => `${formatTokens(block.tokens)} ${block.role} ${block.label}`)
+			.join(" · ");
+		lines.push(`Largest · ${blocks}`);
+	}
+	return lines.join("\n");
+}

package/extensions/context/index.ts

@@ -0,0 +1,16 @@
+/**
+ * `context` — see where the window goes, and compact from the report.
+ *
+ * Command-only by design: usage is a user-facing concern, so no tool is declared
+ * and the model's prompt budget is untouched. The factory only registers; the
+ * report reads the session on demand and keeps no resources.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isExtensionEnabled } from "../../lib/env.ts";
+import { registerCommands } from "./commands.ts";
+
+export default function context(pi: ExtensionAPI): void {
+	if (!isExtensionEnabled("context")) return;
+	registerCommands(pi);
+}