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

package/extensions/bytefly/update/format.ts

@@ -9,10 +9,11 @@
  */
 
 import pkg from "../../../package.json";
-import { noticeMessage, type NoticeMessage } from "../../../lib/notice.ts";
+import { sanitizeLine } from "../../../lib/format.ts";
+import { noticeMessage, type NoticeItem, type NoticeMessage } from "../../../lib/notice.ts";
 import { GLYPHS } from "../../../lib/tui/glyphs.ts";
 import type { UpdateOutcome } from "./state.ts";
-import type { PackageUpdate } from "./types.ts";
+import type { PackageUpdate, PiRelease } from "./types.ts";
 
 /** The header marker: an up arrow and this package's newest version. */
 export function updateMarker(latest: string): string {
@@ -22,6 +23,12 @@ export function updateMarker(latest: string): string {
 /** The command that resolves every row in the notice. */
 export const UPDATE_COMMAND = "pi update --extensions";
 
+/** The command that updates Pi itself. */
+export const PI_UPDATE_COMMAND = "pi update";
+
+/** Where Pi publishes its own changelog; Pi hardcodes the same URL in its box. */
+export const PI_CHANGELOG_URL = "https://pi.dev/changelog";
+
 /**
  * The release page for a version, or `undefined` when this checkout does not name
  * a GitHub repository. Derived from `package.json` so a rename cannot leave a dead
@@ -73,14 +80,66 @@ function ownRelease(ownLatest?: string): string | undefined {
 	return ownLatest ? releaseUrl(ownLatest) : undefined;
 }
 
+/** The row that names the command resolving an update. */
+function commandRow(command: string): NoticeItem {
+	return { label: "update", detail: command };
+}
+
+/** The row that names a page the answer points at, e.g. a release or a changelog. */
+function linkRow(label: string, url: string): NoticeItem {
+	return { label, detail: url };
+}
+
+/**
+ * The tail both answers end with: the command to run, then where the notes are
+ * when they are known. Each caller supplies its own sentence, because the notice
+ * is read in the transcript and the re-check answer is read as one printed line.
+ */
+function actionParts(action: string, release?: string): string[] {
+	return release ? [action, `Release notes: ${release}`] : [action];
+}
+
+/**
+ * The notice that replaces Pi's own `Update Available` box.
+ *
+ * Pi resolves the release and then draws a bordered warning block; bytefly takes
+ * the same release and draws the shared transcript notice, so the news reads like
+ * every other bytefly message and states the version movement, the command, and
+ * the changelog. `note` is Pi's changelog excerpt when the release API sends one;
+ * it is a free-form paragraph, so it is sanitized to a single row rather than
+ * given a layout of its own.
+ */
+export function piReleaseNotice(release: PiRelease, current: string): NoticeMessage {
+	const note = release.note?.trim();
+	const parts = [
+		`Pi v${release.version} is available; this session runs v${current}.`,
+		`Run \`${PI_UPDATE_COMMAND}\`.`,
+		`Changelog: ${PI_CHANGELOG_URL}`,
+	];
+	if (note) parts.push(`Release notes: ${note}`);
+	return noticeMessage({
+		content: parts.join(" "),
+		details: {
+			source: "bytefly",
+			title: `pi v${release.version} is available`,
+			severity: "info",
+			items: [
+				{ label: "pi", detail: `v${current} → v${release.version}` },
+				commandRow(PI_UPDATE_COMMAND),
+				linkRow("changelog", PI_CHANGELOG_URL),
+				...(note ? [{ label: "release notes", detail: sanitizeLine(note) }] : []),
+			],
+		},
+	});
+}
+
 /** The single notice a session posts when Pi reports package updates. */
 export function updateNotice(updates: readonly PackageUpdate[], current: string, ownLatest?: string): NoticeMessage {
 	const own = updates.find(isOwnPackage);
 	const release = own ? ownRelease(ownLatest) : undefined;
 	const parts = [namesLine(updates)];
 	if (own && ownLatest) parts.push(`${pkg.name} v${current} → v${ownLatest}.`);
-	parts.push(`Run \`${UPDATE_COMMAND}\` to update.`);
-	if (release) parts.push(`Release notes: ${release}`);
+	parts.push(...actionParts(`Run \`${UPDATE_COMMAND}\` to update.`, release));
 	return noticeMessage({
 		content: parts.join(" "),
 		details: {
@@ -89,8 +148,8 @@ export function updateNotice(updates: readonly PackageUpdate[], current: string,
 			severity: "info",
 			items: [
 				...updates.map((update) => packageRow(update, current, ownLatest)),
-				{ label: "update", detail: UPDATE_COMMAND },
-				...(release ? [{ label: "release", detail: release }] : []),
+				commandRow(UPDATE_COMMAND),
+				...(release ? [linkRow("release", release)] : []),
 			],
 		},
 	});
@@ -120,8 +179,7 @@ export function updateOutcomeText(
 			const release = own ? ownRelease(outcome.ownLatest) : undefined;
 			const parts = [`bytefly: ${namesLine(outcome.updates)}`];
 			if (own && outcome.ownLatest) parts.push(`This package is v${current} → v${outcome.ownLatest}.`);
-			parts.push(`Run ${UPDATE_COMMAND}.`);
-			if (release) parts.push(`Release notes: ${release}`);
+			parts.push(...actionParts(`Run ${UPDATE_COMMAND}.`, release));
 			return { text: parts.join(" "), severity: "info" };
 		}
 	}

package/extensions/bytefly/update/patch.ts

@@ -0,0 +1,66 @@
+/**
+ * The one way bytefly replaces a host method it has to own.
+ *
+ * Pi draws two update blocks from methods an extension can reach but cannot turn
+ * off: its package list from `DefaultPackageManager.prototype`, and its
+ * `Update Available` box from `InteractiveMode.prototype`. Both replacements are
+ * the same operation, so the rules that make it safe live here once instead of
+ * being restated per surface:
+ *
+ * - The patch is process-wide, so it is installed at `session_start` and restored
+ *   at `session_shutdown`; the record travels on the target under a per-method
+ *   `Symbol.for` key, which survives the isolated module caches `lib/` is loaded
+ *   with and makes a second registration reuse the first patch.
+ * - A restore only puts the original back while the patch is still the method
+ *   installed, so a host or another extension that replaced it later keeps its
+ *   own version.
+ * - A method the host does not have makes the patch inert rather than an error.
+ *   The caller's surface then falls back to what the host draws, which is always
+ *   correct and merely less styled.
+ */
+
+/** One installed patch, and the method it replaced. */
+export interface MethodPatch<F> {
+	/** The method as it was before the patch; `undefined` when the host lacks it. */
+	readonly original: F | undefined;
+	/** Put the original back while this patch is still installed; safe to call more than once. */
+	restore(): void;
+}
+
+/** The marker for one method's patch, stable across isolated module caches. */
+function markerFor(method: string): symbol {
+	return Symbol.for(`@gavin-hu/my-pi-agent/host-patch/${method}`);
+}
+
+/**
+ * Replace `target[method]` with `replacement`.
+ *
+ * `target` is a prototype, a seam a test can supply as a plain object. The
+ * returned patch carries the captured original, because a caller usually needs it
+ * for something: the package check still serves bytefly's own query, and the
+ * release notification is the fallback when bytefly's rendering throws.
+ */
+export function patchPrototypeMethod<T extends object, K extends keyof T & string>(
+	target: T,
+	method: K,
+	replacement: T[K],
+): MethodPatch<T[K]> {
+	const marker = markerFor(method);
+	const store = target as unknown as Record<symbol, MethodPatch<T[K]> | undefined>;
+	const existing = store[marker];
+	if (existing) return existing;
+
+	const original = target[method];
+	if (typeof original !== "function") return { original: undefined, restore: () => {} };
+
+	const patch: MethodPatch<T[K]> = {
+		original,
+		restore() {
+			if (target[method] === replacement) target[method] = original;
+			delete store[marker];
+		},
+	};
+	target[method] = replacement;
+	store[marker] = patch;
+	return patch;
+}

package/extensions/bytefly/update/register.ts

@@ -28,7 +28,7 @@ import {
 } from "./cache.ts";
 import { fetchAvailableUpdates, fetchLatestVersion } from "./check.ts";
 import { isOwnPackage, updateNotice } from "./format.ts";
-import type { UpdateOutcome, UpdateSource } from "./state.ts";
+import { paintLatest, type UpdateOutcome, type UpdateSource } from "./state.ts";
 import { suppressPiPackageUpdates, type UpdateSuppression } from "./suppress.ts";
 import type { PackageUpdate, PackageUpdateCheck } from "./types.ts";
 import { isNewerVersion } from "./version.ts";
@@ -125,13 +125,6 @@ export function registerUpdate(pi: ExtensionAPI, updates: UpdateSource, deps: Up
 		return entry.updates.some(isOwnPackage) ? entry.latest : undefined;
 	};
 
-	/** Paint the header marker, or clear it when this package is current. */
-	const paint = (latest?: string): void => {
-		if (updates.latest() === latest) return;
-		updates.set(latest);
-		deps.onUpdate?.();
-	};
-
 	/** The once-per-load transcript notice, posted only for a non-empty list. */
 	const announce = (entry: UpdateCacheEntry): void => {
 		if (announced || entry.updates.length === 0) return;
@@ -141,13 +134,13 @@ export function registerUpdate(pi: ExtensionAPI, updates: UpdateSource, deps: Up
 
 	/** One snapshot: paint the marker and, when it has rows, announce it once. */
 	const record = (entry: UpdateCacheEntry): void => {
-		paint(ownLatestOf(entry));
+		paintLatest(updates, ownLatestOf(entry), deps.onUpdate);
 		announce(entry);
 	};
 
 	/** Offline: the cached marker is advisory, but no notice is posted. */
 	const recordMarkerOnly = (entry: UpdateCacheEntry): void => {
-		paint(ownLatestOf(entry));
+		paintLatest(updates, ownLatestOf(entry), deps.onUpdate);
 	};
 
 	/** Resolve this package's version label, dropping an equal or older answer. */
@@ -238,7 +231,7 @@ export function registerUpdate(pi: ExtensionAPI, updates: UpdateSource, deps: Up
 			};
 			writeCache(entry);
 			// The caller prints the answer, so this path never posts a notice.
-			paint(latest);
+			paintLatest(updates, latest, deps.onUpdate);
 			return list.length > 0
 				? { kind: "available", updates: list, ...(latest ? { ownLatest: latest } : {}) }
 				: { kind: "current" };

package/extensions/bytefly/update/release.ts

@@ -0,0 +1,65 @@
+/**
+ * Pi's own release notice, re-drawn as bytefly's.
+ *
+ * Pi resolves its new version from `pi.dev`, then draws a bordered `Update
+ * Available` block. This lifecycle replaces the method that draws it, so the
+ * release Pi already fetched becomes one shared transcript notice and a `↑`
+ * marker on the header's Pi line. No request of bytefly's own is made, and the
+ * release's changelog note, when Pi's API sends one, travels with it.
+ *
+ * The patch is installed at `session_start` in `tui` mode — `run()` starts the
+ * version check only after the session is up — and restored at
+ * `session_shutdown`, the same shape as the package-update surface. A release
+ * that lands after the session is gone is dropped rather than posted into it.
+ */
+
+import { type ExtensionAPI, VERSION } from "@earendil-works/pi-coding-agent";
+import { piReleaseNotice } from "./format.ts";
+import { paintLatest, type UpdateSource } from "./state.ts";
+import { suppressPiReleaseNotice, type ReleaseNoticeShim } from "./suppress.ts";
+import type { PiRelease, ReleaseNoticePrototype } from "./types.ts";
+
+/** Test seams; production patches Pi's interactive mode and reads its version. */
+export interface ReleaseDeps {
+	/** Replace the host method bytefly patches; defaults to `InteractiveMode.prototype`. */
+	prototype?: ReleaseNoticePrototype;
+	/** Replace the running Pi version; defaults to the host's `VERSION`. */
+	currentVersion?: string;
+	/** Called once a version is recorded, so a mounted header repaints. */
+	onUpdate?: () => void;
+}
+
+/**
+ * Register the release-notice lifecycle. `latest` is the store the header reads,
+ * so recording Pi's new version is what puts the marker on the agent line.
+ */
+export function registerPiRelease(pi: ExtensionAPI, latest: UpdateSource, deps: ReleaseDeps = {}): void {
+	const current = deps.currentVersion ?? VERSION;
+	let shim: ReleaseNoticeShim | undefined;
+	let live = false;
+	// Pi checks once per process, but a reload re-registers this surface: a second
+	// notice in the same load would be a duplicate, not news.
+	let announced = false;
+
+	const record = (release: PiRelease): void => {
+		if (!live) return;
+		paintLatest(latest, release.version, deps.onUpdate);
+		if (announced) return;
+		announced = true;
+		pi.sendMessage(piReleaseNotice(release, current));
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		// Only the interactive mode draws Pi's box, so only there is there one to replace.
+		if (ctx.mode !== "tui") return;
+		live = true;
+		shim ??= suppressPiReleaseNotice(record, deps.prototype);
+	});
+
+	pi.on("session_shutdown", () => {
+		live = false;
+		shim?.restore();
+		shim = undefined;
+		latest.set();
+	});
+}

package/extensions/bytefly/update/state.ts

@@ -40,3 +40,17 @@ export function createUpdateState(): UpdateSource {
 		},
 	};
 }
+
+/**
+ * Record a version in the store and repaint the surface that reads it.
+ *
+ * The comparison is what keeps this cheap and quiet: a check that finds the same
+ * version again must not re-install the header, and clearing an unknown version
+ * must still clear the marker. `onUpdate` is the surface's repaint hook, so a
+ * registration that has no mounted surface can omit it.
+ */
+export function paintLatest(store: UpdateSource, latest: string | undefined, onUpdate?: () => void): void {
+	if (store.latest() === latest) return;
+	store.set(latest);
+	onUpdate?.();
+}

package/extensions/bytefly/update/suppress.ts

@@ -1,20 +1,24 @@
 /**
- * Pi suppresses its own package-update block while bytefly owns the surface.
+ * Pi draws two update blocks bytefly replaces, and this module expresses both
+ * through the install/restore rules in `patch.ts`.
  *
  * Pi draws `Package Updates Available` from `InteractiveMode.run()` after the
  * session starts, with no setting or extension event to turn it off. The one
  * public seam is the package manager it calls: replacing
  * `checkForAvailableUpdates` with an empty result suppresses that block, while
- * the captured original still serves bytefly's own query. The patch is
- * process-wide, so it is installed at `session_start` and restored at
- * `session_shutdown`.
+ * the captured original still serves bytefly's own query.
  *
- * A future host that changes the method shape makes the patch a no-op rather
- * than an error; the update surface then falls back to Pi's block.
+ * Pi draws `Update Available` from the same `run()`, through a public method on
+ * `InteractiveMode`; replacing that method hands bytefly the release Pi resolved
+ * (its version and notes) so it can draw the shared notice instead.
+ *
+ * A future host that changes either shape makes that patch a no-op rather than an
+ * error; the update surface then falls back to Pi's own block.
  */
 
-import { DefaultPackageManager } from "@earendil-works/pi-coding-agent";
-import type { PackageUpdate, PackageUpdateCheck } from "./types.ts";
+import { DefaultPackageManager, InteractiveMode } from "@earendil-works/pi-coding-agent";
+import { patchPrototypeMethod } from "./patch.ts";
+import type { PackageUpdate, PackageUpdateCheck, PiRelease, ReleaseNoticePrototype } from "./types.ts";
 
 /** A patchable class prototype, kept narrow so a test needs no host object. */
 export interface PackageManagerPrototype {
@@ -29,12 +33,8 @@ export interface UpdateSuppression {
 	restore(): void;
 }
 
-/** Marker for the installed patch, so a second registration reuses it. */
-const SUPPRESSION = Symbol.for("@gavin-hu/my-pi-agent/pi-update-suppression");
-
-interface MarkedPrototype extends PackageManagerPrototype {
-	[SUPPRESSION]?: UpdateSuppression;
-}
+/** The replacement the patch installs, so a test can tell it from Pi's method. */
+const SUPPRESSED: PackageUpdateCheck = async () => [];
 
 /**
  * Replace Pi's package-update check with one that reports nothing.
@@ -46,21 +46,39 @@ interface MarkedPrototype extends PackageManagerPrototype {
 export function suppressPiPackageUpdates(
 	prototype: PackageManagerPrototype = DefaultPackageManager.prototype as PackageManagerPrototype,
 ): UpdateSuppression {
-	const marked = prototype as MarkedPrototype;
-	const existing = marked[SUPPRESSION];
-	if (existing) return existing;
+	const patch = patchPrototypeMethod(prototype, "checkForAvailableUpdates", SUPPRESSED);
+	if (!patch.original) return { check: async () => [], restore: patch.restore };
+
+	const originalCheck = patch.original as unknown as (this: DefaultPackageManager) => Promise<PackageUpdate[]>;
+	return { check: (manager) => originalCheck.call(manager), restore: patch.restore };
+}
+
+/** The installed release-notice shim, and how to give Pi its method back. */
+export interface ReleaseNoticeShim {
+	/** Put Pi's method back; safe to call more than once. */
+	restore(): void;
+}
 
-	const original = prototype.checkForAvailableUpdates;
-	if (typeof original !== "function") return { check: async () => [], restore: () => {} };
-	const originalCheck = original as unknown as (this: DefaultPackageManager) => Promise<PackageUpdate[]>;
-	const check: PackageUpdateCheck = (manager) => originalCheck.call(manager);
-	const patched: PackageUpdateCheck = async () => [];
-	const restore = (): void => {
-		if (prototype.checkForAvailableUpdates === patched) prototype.checkForAvailableUpdates = original;
-		delete marked[SUPPRESSION];
+/**
+ * Hand Pi's `Update Available` release to `notify` instead of letting Pi draw it.
+ *
+ * `prototype` is a seam for tests; production passes `InteractiveMode.prototype`.
+ * When the host has no such method the shim is inert and Pi's box is what shows,
+ * which is exactly the state this replaces. A `notify` that throws is also a
+ * fallback to Pi's box: a release nobody hears about is worse than Pi's own
+ * rendering of it, and the error itself is not allowed to escape into `run()`.
+ */
+export function suppressPiReleaseNotice(
+	notify: (release: PiRelease) => void,
+	prototype: ReleaseNoticePrototype = InteractiveMode.prototype as ReleaseNoticePrototype,
+): ReleaseNoticeShim {
+	const original = prototype.showNewVersionNotification as (this: ReleaseNoticePrototype, release: PiRelease) => void;
+	const patched = function (this: ReleaseNoticePrototype, release: PiRelease): void {
+		try {
+			notify(release);
+		} catch {
+			if (typeof original === "function") original.call(this, release);
+		}
 	};
-	const suppression: UpdateSuppression = { check, restore };
-	prototype.checkForAvailableUpdates = patched;
-	marked[SUPPRESSION] = suppression;
-	return suppression;
+	return patchPrototypeMethod(prototype, "showNewVersionNotification", patched);
 }

package/extensions/bytefly/update/types.ts

@@ -1,15 +1,25 @@
 /**
- * The package-update shape Pi's manager returns.
+ * The update shapes Pi publishes, derived from the public methods that carry
+ * them.
  *
- * Pi exports the manager but not its `PackageUpdate` interface, so the type is
- * derived from the public method. That keeps the extension on the same contract
- * without reaching into a dist path or restating the fields.
+ * Pi exports the package manager and the interactive mode but not the interfaces
+ * they pass around, so each type here is read off a public signature. That keeps
+ * the extension on the same contract without reaching into a dist path or
+ * restating the fields a host version may change.
  */
 
-import type { DefaultPackageManager } from "@earendil-works/pi-coding-agent";
+import type { DefaultPackageManager, InteractiveMode } from "@earendil-works/pi-coding-agent";
 
 /** One package Pi reports as updateable. */
 export type PackageUpdate = Awaited<ReturnType<DefaultPackageManager["checkForAvailableUpdates"]>>[number];
 
 /** Pi's check, captured before suppression and called with a manager. */
 export type PackageUpdateCheck = (manager: DefaultPackageManager) => Promise<PackageUpdate[]>;
+
+/** A newer Pi release as Pi itself resolved it: the version, and its notes when any. */
+export type PiRelease = Parameters<InteractiveMode["showNewVersionNotification"]>[0];
+
+/** The notification method bytefly replaces, narrow enough for a test to fake. */
+export interface ReleaseNoticePrototype {
+	showNewVersionNotification(release: PiRelease): void;
+}

package/extensions/check/tui.ts

@@ -79,6 +79,8 @@ export class CheckRunComponent implements Component {
 		});
 		if (body.length === 0) body.push(...emptyState(this.theme, w, { label: "Starting…" }));
 		return dockListFrame({
+			theme: this.theme,
+			width: w,
 			header: titleRule(this.theme, w, "Check"),
 			summary: clip(
 				`  ${paint(this.theme, "meta", `running${SEPARATORS.item}${sanitizeLine(this.options.command)}${SEPARATORS.item}${formatDuration(this.options.elapsedMs())}`)}`,

package/extensions/context/README.md

@@ -16,15 +16,19 @@ pi install ./                          # install the package
 - 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.
+  auto-compaction threshold, and the headroom left before it while compaction is
+  on — then the composition under a header that names the composition's own
+  estimate: 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.
+  of forcing the parts to add up: one line with both figures, `unattributed` when
+  the host's total is the larger one, and `host counts messages only` before the
+  first reply, when Pi's fallback leaves the prompt and the tools out.
+- Rounds each bar to the nearest cell, so a bar sits within half a cell of the
+  percentage printed beside it; the percentage itself is exact.
 - 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
+- Lists the five largest single messages, 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
@@ -58,7 +62,7 @@ for.
 
 `/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
+largest messages. `/context compact` is the same in every mode and reports through
 `ctx.ui.notify` when it finishes or fails.
 
 ## How the numbers are computed
@@ -67,13 +71,14 @@ largest blocks. `/context compact` is the same in every mode and reports through
 |---|---|
 | 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`. |
+| Headroom | `window - reserve - tokens`, `null` when the total is unknown or automatic compaction is off — there is no threshold in effect. |
 | 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. |
+| Drift | `tokens - estimate`, printed with both figures. A positive value appends `+… unattributed` — usage the rows do not explain; a negative one appends `host counts messages only` while the projection holds no assistant message, because Pi's message-only fallback omits the system prompt and the tool definitions. |
 
 ## Limitations
 
@@ -92,8 +97,13 @@ largest blocks. `/context compact` is the same in every mode and reports through
   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.
+- A percentage is computed from unrounded tokens and shown to one decimal, while
+  the token column is compact (`5.1k`), so re-deriving a percentage from the
+  printed figures can differ by a couple of points. A bar rounds to the nearest
+  cell and a non-zero share always gets one, so a `0.2%` row draws one cell
+  beside its label.
+- Descriptors in **Largest messages** are one line, clipped to 40 characters; a
+  long tool result is represented by its tool name, not its content.
 
 ## Non-goals
 
@@ -146,7 +156,7 @@ largest blocks. `/context compact` is the same in every mode and reports through
 | `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. |
+| `report.ts` | The pure builder: composition, reserve resolution, compaction history, largest messages. |
 | `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<…>`. |

package/extensions/context/format.ts

@@ -48,11 +48,11 @@ export function formatCompaction(report: ContextReport): string {
 
 /** 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`;
+	const tokens = report.tokens;
+	if (report.drift === null || report.drift === 0 || tokens === null) return undefined;
+	const base = `Estimate drift · rows ${formatTokens(report.estimate)} vs host ${formatTokens(tokens)}`;
+	if (report.drift > 0) return `${base} · +${formatTokens(report.drift)} unattributed`;
+	return report.beforeFirstReply ? `${base} · host counts messages only` : base;
 }
 
 /** One composition row, as plain text. */
@@ -65,10 +65,12 @@ export function formatBucket(bucket: ContextBucket): string {
 	return `${indent}${label}${tokens}${share}${note}`;
 }
 
-/** The report as a notification body: headline, budget, rows, then what happened. */
+/** The report as a notification body: headline, budget, composition, 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));
+	if (report.buckets.length > 0) {
+		lines.push("", `Composition · ${formatTokens(report.estimate)} estimate`, ...report.buckets.map(formatBucket));
+	}
 	const drift = formatDrift(report);
 	if (drift) lines.push("", drift);
 	lines.push("", `Compaction · ${formatCompaction(report)}`);
@@ -76,7 +78,7 @@ export function formatReport(report: ContextReport): string {
 		const blocks = report.largest
 			.map((block) => `${formatTokens(block.tokens)} ${block.role} ${block.label}`)
 			.join(" · ");
-		lines.push(`Largest · ${blocks}`);
+		lines.push("", `Largest · ${blocks}`);
 	}
 	return lines.join("\n");
 }

package/extensions/context/report.ts

@@ -94,7 +94,7 @@ function firstText(content: unknown): string {
 	return "";
 }
 
-/** A one-line, bounded descriptor for the "largest blocks" list. */
+/** A one-line, bounded descriptor for the "largest messages" list. */
 function boundedLabel(text: string, maxLength = 40): string {
 	const line = sanitizeLine(text);
 	return line.length > maxLength ? `${line.slice(0, maxLength - 1)}…` : line;
@@ -184,7 +184,10 @@ export function buildReport(inputs: ContextInputs): ContextReport {
 	const percent = inputs.usage?.percent ?? (tokens !== null && window > 0 ? (tokens / window) * 100 : null);
 	const free = tokens !== null && window > 0 ? window - tokens : null;
 	const autoCompactAt = window > 0 ? Math.max(0, window - resolved.reserve) : 0;
-	const headroom = tokens !== null && free !== null && window > 0 ? autoCompactAt - tokens : null;
+	const headroom = resolved.enabled && tokens !== null && window > 0 ? autoCompactAt - tokens : null;
+	// Pi's total is a message-only estimate until an assistant reply reports real
+	// usage, so the drift row names that cause instead of calling the gap noise.
+	const beforeFirstReply = !inputs.messages.some((message) => roleOf(message) === "assistant");
 
 	const messageCounts = new Map<string, number>();
 	const messageTokens = new Map<string, number>();
@@ -267,12 +270,21 @@ export function buildReport(inputs: ContextInputs): ContextReport {
 	const children = [...injectedTokens.entries()].sort((a, b) => b[1] - a[1]);
 	const shown = children.slice(0, 5);
 	const rest = children.slice(5);
-	const childDrafts: BucketDraft[] = shown.map(([customType, estimateForType]) => ({
-		id: `injected:${customType}`,
-		label: customType,
-		tokens: estimateForType,
-		note: countNote(injectedCounts.get(customType) ?? 0),
-	}));
+	// A child's count is informative only when it divides the parent's; one
+	// injected type would otherwise repeat the same `1 message` twice.
+	const childNote = (customType: string): string | undefined => {
+		const count = injectedCounts.get(customType) ?? 0;
+		return count > 0 && count < injectedCount ? countNote(count) : undefined;
+	};
+	const childDrafts: BucketDraft[] = shown.map(([customType, estimateForType]) => {
+		const note = childNote(customType);
+		return {
+			id: `injected:${customType}`,
+			label: customType,
+			tokens: estimateForType,
+			...(note ? { note } : {}),
+		};
+	});
 	if (rest.length > 0) {
 		childDrafts.push({
 			id: "injected:other",
@@ -313,6 +325,7 @@ export function buildReport(inputs: ContextInputs): ContextReport {
 		buckets,
 		estimate,
 		drift: tokens !== null ? tokens - estimate : null,
+		beforeFirstReply,
 		compaction: compactionHistory(inputs),
 		largest,
 	};