pi-posthorse 0.4.4 → 0.4.6

package/README.md

@@ -8,6 +8,8 @@ Native, no-summary context windows for the [`fitchmultz/pi`](https://github.com/
 
 Pi owns the persisted boundary. Posthorse owns the policy: stable window guidance, one best-effort checkpoint reminder, `new_context`, `get_context_remaining`, durable `notes`, and window-aware `history`. A rollover removes the old window from active model context while the JSONL transcript stays append-only and complete.
 
+An isolated [Codex prototype](adapters/codex-posthorse/README.md) tests local notes and recovery with Codex's native context reset. It is not ready for everyday use and is not included in the Pi package.
+
 ## Requirements
 
 - Node `>=22.19.0`.
@@ -40,7 +42,7 @@ pi -e git:github.com/fitchmultz/pi-posthorse              # try it for one run w
 
 Update with `pi update npm:pi-posthorse` or `pi update --extensions`; move a pinned Git install with `pi install git:github.com/fitchmultz/pi-posthorse@<new tag>`. Uninstall with `pi remove npm:pi-posthorse` (or the Git source you installed). Removing the package leaves `.pi/notes` and Pi's session history in place.
 
-After installing or updating Posthorse, run `/reload` in existing Pi sessions or restart them to load the new version.
+Restart Pi after installing or updating Posthorse to load the new extension code.
 
 Keep exactly one copy loaded. `pi list` shows every package source; if an older entry such as `git:github.com/fitchmultz/pi-headroom.git` or a local checkout is still listed, `pi remove` it before installing the npm package, otherwise two copies register the same tools and compete for the same rollover hook.
 
@@ -52,7 +54,7 @@ Keep exactly one copy loaded. `pi list` shows every package source; if an older
 4. **`new_context`.** Requests an atomic rollover after the complete tool batch succeeds. An optional handoff is persisted and becomes the first state of the fresh window. If a sibling tool in the same batch fails, Pi does not commit the boundary; the checkpoint reminder still applies.
 5. **Automatic rollover without summaries.** With a supported context budget and room for a recovery record, Posthorse claims Pi's automatic threshold and overflow trigger through `session_before_auto_compact`, before Pi resolves summarization credentials or prepares a summary. Oversized first turns and tool results can then roll over even without summarization credentials. Otherwise Pi's own compaction remains in control. Manual `/compact` is unchanged.
 6. **Bounded recovery record.** The automatic handoff keeps direct user inputs, `ask_question` outcomes, visible coordination messages, and the trailing tool batch that no model has consumed yet (call arguments, bounded result text, and the entry ids to recover the rest). A clearly labeled, possibly stale older checkpoint comes last, after the current inputs and unseen results. Older assistant prose and consumed tool results are not treated as state. Newly submitted input stays separate and is saved after the boundary, not copied into the handoff.
-7. **`notes` and `history`.** Notes live with the repository root, shared across linked worktrees. History searches normalized transcript text and returns stored images for a requested entry.
+7. **`notes` and `history`.** Notes are shared across linked worktrees, at the main checkout for conventional Git layouts or inside the common Git directory when metadata is stored separately. History searches normalized transcript text and returns stored images for a requested entry.
 
 At turn end, Posthorse checks whether usage is in the reminder band before explicitly looking up the full branch. Context filtering skips its branch lookup when model input contains neither `posthorse-reminder` nor legacy `headroom-reminder` messages. History searches, reads, and recovery remain available with no new limits.
 
@@ -75,20 +77,24 @@ Only one automatic compaction or rollover policy extension should be enabled at
 - `notes({ op, ... })`: `list`, `read` (paged; `offset` continues), `write` (empty content clears), `append` (one atomic newline-terminated record), `search` (excerpts centered on the match)
 - `history({ op, ... })`: `search`, `read`; results carry native window ids, reads return stored images with the first page and the next character offset when text remains
 
-Read pages, including returned images, shrink to the context that is actually left. Before usage is known, they reserve prompt/tool overhead and leave half the rest free. Unsafe pages are refused with the offset preserved; call `new_context` and retry.
+In the TUI, tools use Pi's native expandable cards. Collapsed cards show the operation and target, a short content preview, and counts or page ranges with the next offset when more remains. Expand with Pi's tool-output shortcut (`Ctrl+O` by default), or click the card's header or body in fullscreen mode. Expanded cards show the complete returned page and its metadata, not content the tool has not fetched yet. Writes and context requests also show the submitted content or handoff.
+
+Committed context-window messages and checkpoint reminders are compact, expandable cards too. The `new_context` tool card describes a request; only the committed context-window message says a fresh window has started.
+
+Read pages, including returned images, shrink to the context that is actually left. Parallel note and history reads share that budget; pages already counted by Pi are not counted twice. Before usage is known, they reserve prompt/tool overhead and leave half the rest free. Unsafe pages are refused with the offset preserved in the call; call `new_context` and retry. Refusal text uses the same budget, so later failures omit repeated guidance once no more fits.
 
 `history search` puts matching original content before recovery material: handoffs, compaction and branch summaries, checkpoint reminders, and `notes`, `new_context`, and `history` calls/results. Ordinary prose or another tool call in the same assistant entry keeps its priority when that content matches. Every entry remains searchable; `history read` returns the complete normalized entry, including any recovery content omitted from a search excerpt.
 
 Within each group, current-branch matches are newest first. With `all: true`, Posthorse searches every session file in the active Pi session directory, newest-modified sessions first and newest entries within each session; this is not a global timestamp sort. The result limit applies after priority, so newer echoes cannot displace older original matches. Entries copied by a fork are reported once.
 
-Notes live in `.pi/notes/` at the repository root (the main checkout for a linked worktree, the current directory outside Git). Add the directory to `.gitignore` when the project should not track it.
+Notes live in `.pi/notes/` at the main checkout for conventional Git layouts, or the current directory outside Git. When Git metadata is stored separately, including in submodules, all checkouts use `.pi/notes/` inside Git's common directory instead; no configuration is needed. If that metadata is unavailable, notes stay local to the checkout. Old checkout-local notes are imported when that checkout is accessed, without overwriting shared files or deleting the originals. Writes report the actual storage path. Add `.pi/notes/` to `.gitignore` when the project should not track it.
 
 ## Data and privacy
 
 - Posthorse makes no network requests.
 - Notes are plaintext files under `.pi/notes`. They survive package removal and may be committed unless ignored.
 - `history` with `all: true` scans nested JSONL files in the active Pi session directory, including subagent sessions.
-- History can return user text, assistant text and thinking, tool arguments and results, handoffs, custom messages, and images. Direct shell entries Pi marked `excludeFromContext` come back as a placeholder only.
+- History can return user text, assistant text and thinking, assistant failure status and error messages, tool arguments and results, handoffs, custom messages, and images. Direct shell entries Pi marked `excludeFromContext` come back as a placeholder only.
 - Returned history content enters the currently selected model and provider context.
 - Removing Posthorse does not remove notes or Pi session history.
 
@@ -105,4 +111,4 @@ npm run check
 PI_FORK=../pi scripts/integration.sh   # loads the real extension into the fork's test harness (fork built)
 ```
 
-`npm run check` type-checks `index.ts` and the unit tests; the integration test runs inside the fork's harness. Unit tests cover reminder boundaries, skipped branch lookups, and legacy reminders; native integration tests cover rollover and history recovery. CI runs the unit tests on Node 22.19 and 24, `npm audit`, `npm pack --dry-run`, and the integration job against the pinned fork revision.
+`npm run check` type-checks the extension, renderers, and tests. Tests cover reminder policy, notes/history behavior, and real native card components, including width, expansion, and legacy results. The pinned Pi 0.85.0 SDK's unbundled entry imports an undeclared server package, so test-only resolution loads its shipped native bundle. Integration tests run inside the fork's harness and cover rollover and history recovery; use a disposable built fork checkout because the script briefly copies the test into its test directory. CI runs the unit tests on Node 22.19 and 24, `npm audit`, `npm pack --dry-run`, and the integration job against the pinned fork revision.

package/index.ts

@@ -8,18 +8,21 @@
 
 import {
 	appendFileSync,
+	constants,
+	copyFileSync,
 	createReadStream,
 	existsSync,
 	mkdirSync,
 	readdirSync,
 	readFileSync,
+	realpathSync,
 	statSync,
 	writeFileSync,
 } from "node:fs";
-import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
-import { createInterface } from "node:readline";
+import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { registerPosthorseMessages, toolCards, type PosthorseDisplay } from "./ui.ts";
 
 const REMINDER_BUFFER_TOKENS = 32_000;
 /** Absolute ceiling for handoffs and read pages; pages shrink to the live remaining budget. */
@@ -63,6 +66,7 @@ type ImageLike = { type: "image"; data: string; mimeType: string };
 type MessageLike = {
 	role?: string;
 	stopReason?: string;
+	errorMessage?: string;
 	content?: unknown;
 	toolName?: string;
 	toolCallId?: string;
@@ -86,7 +90,7 @@ type EntryLike = {
 };
 
 type WindowedEntry = { entry: EntryLike; windowId: string; text: string; images: ImageLike[] };
-type HistoryHit = { id: string; text: string; priority: 0 | 1 };
+type HistoryHit = { id: string; text: string; headerLength: number; priority: 0 | 1 };
 type RecoveryRecord = {
 	id: string;
 	timestamp: string;
@@ -159,25 +163,53 @@ function textOf(message: MessageLike): string {
 		.join("\n");
 }
 
-function textResult(text: string, images: ImageLike[] = []) {
-	return { content: [{ type: "text" as const, text }, ...images], details: undefined };
+function textResult(text: string, images: ImageLike[] = [], display?: PosthorseDisplay) {
+	return { content: [{ type: "text" as const, text }, ...images], details: display };
 }
 
-/**
- * Notes belong to the repository root, walking up from cwd. A linked worktree's `.git` is a file
- * ("gitdir: <main>/.git/worktrees/<name>"); its notes belong to the main checkout so every worktree
- * shares them and they outlive the worktree. Outside Git, cwd is the root.
- */
+/** Import old checkout-local notes without overwriting shared notes, including concurrent writes. */
+function importLegacyNotes(source: string, target: string): void {
+	if (!existsSync(source)) return;
+	if (existsSync(target) && (!statSync(target).isDirectory() || realpathSync(source) === realpathSync(target))) return;
+	mkdirSync(target, { recursive: true });
+	for (const name of readdirSync(source)) {
+		const from = join(source, name);
+		const to = join(target, name);
+		if (statSync(from).isDirectory()) {
+			importLegacyNotes(from, to);
+		} else {
+			try {
+				copyFileSync(from, to, constants.COPYFILE_EXCL);
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+			}
+		}
+	}
+}
+
+/** Conventional repos use the main checkout; separate Git directories are their own shared root. */
 function notesRoot(cwd: string): string {
 	for (let dir = cwd; ; dir = dirname(dir)) {
 		const marker = join(dir, ".git");
 		if (existsSync(marker)) {
+			let root: string;
 			try {
-				const gitdir = readFileSync(marker, "utf8").match(/^gitdir:\s*(.+?)\s*$/m)?.[1];
-				const main = gitdir && resolve(dir, gitdir).match(/^(.+)[\\/]\.git[\\/]worktrees[\\/][^\\/]+$/)?.[1];
-				if (main) return main;
-			} catch {}
-			return dir;
+				let target = marker;
+				if (!statSync(marker).isDirectory()) {
+					const gitdir = readFileSync(marker, "utf8").match(/^gitdir:\s*(.+?)\s*$/m)?.[1];
+					if (!gitdir) return dir;
+					target = resolve(dir, gitdir);
+				}
+				target = realpathSync(target);
+				const commonFile = join(target, "commondir");
+				const common = realpathSync(existsSync(commonFile) ? resolve(target, readFileSync(commonFile, "utf8").trim()) : target);
+				root = basename(common) === ".git" ? dirname(common) : common;
+			} catch {
+				// Orphaned/copied worktrees can outlive their Git metadata; local notes still work.
+				return dir;
+			}
+			if (root !== dir) importLegacyNotes(join(dir, ".pi", "notes"), join(root, ".pi", "notes"));
+			return root;
 		}
 		if (dirname(dir) === dir) return cwd;
 	}
@@ -194,6 +226,12 @@ function excerptAround(text: string, index: number, before: number, length: numb
 	return `${start ? "…" : ""}${text.slice(start, end)}${end < text.length ? "…" : ""}`;
 }
 
+function assistantFailure(message: MessageLike): string {
+	if (message.role !== "assistant") return "";
+	if (message.stopReason !== "error" && message.stopReason !== "aborted" && !message.errorMessage) return "";
+	return `[${message.stopReason ?? "error"}]${message.errorMessage ? ` ${message.errorMessage}` : ""}`;
+}
+
 function flattenEntry(entry: EntryLike): string | undefined {
 	if (entry.type === "message") {
 		const message = entry.message ?? {};
@@ -202,7 +240,7 @@ function flattenEntry(entry: EntryLike): string | undefined {
 			if (message.excludeFromContext === true) return "[bashExecution] (excluded from model context by Pi)";
 			return `[bashExecution] $ ${message.command ?? ""}\n${message.output ?? ""}`;
 		}
-		return `[${message.role ?? "message"}] ${[textOf(message), imageSummary(imagesOf(message.content))].filter(Boolean).join("\n")}`;
+		return `[${message.role ?? "message"}] ${[textOf(message), assistantFailure(message), imageSummary(imagesOf(message.content))].filter(Boolean).join("\n")}`;
 	}
 	if (entry.type === "compaction" || entry.type === "branch_summary") {
 		return `[${entry.type}] ${entry.summary ?? ""}`;
@@ -253,8 +291,8 @@ function historyHit(item: WindowedEntry, query: string, source = ""): HistoryHit
 				if (partText) originals[originals.length - 1] += `${originals.at(-1) ? "\n" : ""}${partText}`;
 			}
 		}
-		const images = imageSummary(item.images);
-		if (images) originals[originals.length - 1] += `${originals.at(-1) ? "\n" : ""}${images}`;
+		const metadata = [assistantFailure(entry.message), imageSummary(item.images)].filter(Boolean).join("\n");
+		if (metadata) originals[originals.length - 1] += `${originals.at(-1) ? "\n" : ""}${metadata}`;
 		if (originals[0]) originals[0] = `[assistant] ${originals[0]}`;
 		const original = originals.find((part) => part.toLowerCase().includes(query));
 		priority = original ? 0 : 1;
@@ -263,10 +301,12 @@ function historyHit(item: WindowedEntry, query: string, source = ""): HistoryHit
 			matchIndex = text.toLowerCase().indexOf(query);
 		}
 	}
+	const header = `${source ? `${source} ` : ""}${entry.timestamp ?? ""} [window ${item.windowId}] [${entry.id}] `;
 	return {
 		id: entry.id!,
 		priority,
-		text: `${source ? `${source} ` : ""}${entry.timestamp ?? ""} [window ${item.windowId}] [${entry.id}] ${excerptAround(text, matchIndex, 100, 400)}`,
+		text: `${header}${excerptAround(text, matchIndex, 100, 400)}`,
+		headerLength: header.length,
 	};
 }
 
@@ -288,25 +328,30 @@ function* windowEntries(entries: Iterable<EntryLike>): Generator<WindowedEntry>
 	}
 }
 
+/** JSONL splits on LF, not the Unicode separators that Node's readline also recognizes. */
+async function* jsonlLines(file: string, signal?: AbortSignal): AsyncGenerator<string> {
+	const stream = createReadStream(file, { encoding: "utf8", signal });
+	let pending = "";
+	for await (const chunk of stream) {
+		const lines = (pending + chunk).split("\n");
+		pending = lines.pop()!;
+		yield* lines;
+	}
+	if (pending) yield pending;
+}
+
 async function* sessionWindowEntries(file: string, signal?: AbortSignal): AsyncGenerator<WindowedEntry> {
 	if (!existsSync(file)) return;
-	const stream = createReadStream(file, { encoding: "utf8", signal });
-	const lines = createInterface({ input: stream, crlfDelay: Number.POSITIVE_INFINITY });
 	const windows = new Map<string, string>();
-	try {
-		for await (const line of lines) {
-			let entry: EntryLike;
-			try {
-				entry = JSON.parse(line) as EntryLike;
-			} catch {
-				continue;
-			}
-			const item = toWindowedEntry(entry, windows);
-			if (item) yield item;
+	for await (const line of jsonlLines(file, signal)) {
+		let entry: EntryLike;
+		try {
+			entry = JSON.parse(line) as EntryLike;
+		} catch {
+			continue;
 		}
-	} finally {
-		lines.close();
-		stream.destroy();
+		const item = toWindowedEntry(entry, windows);
+		if (item) yield item;
 	}
 }
 
@@ -633,26 +678,13 @@ function unsupportedMessage(budget: Budget): string {
 	return `Posthorse: unsupported configuration. The model's context window (${n(budget.contextWindow)} tokens) minus Pi's compaction.reserveTokens (${n(budget.reserveTokens)}) leaves ${n(budget.usable)} usable tokens; Posthorse needs at least ${n(MIN_USABLE_TOKENS)}. Automatic rollover and checkpoint reminders are off for this model. Lower compaction.reserveTokens in Pi settings or use a larger-context model. new_context remains available with a model-aware handoff limit.`;
 }
 
-/** Characters that fit before Pi's automatic line (or the hard limit), capped at the absolute ceiling. */
-function requirePage(ctx: NativeContext, offset: number, imageCount: number, toolTokens: number): number {
+/** Capacity before Pi's automatic line (or hard limit), including the margin for page metadata and refusals. */
+function pageCapacity(ctx: NativeContext, toolTokens: number): number {
 	const usage = ctx.getContextUsage();
-	let chars: number;
-	if (!usage || usage.tokens == null) {
-		chars = Math.max(0, freshPayloadChars(ctx, toolTokens) - imageCount * ESTIMATED_IMAGE_CHARS);
-	} else {
-		const budget = budgetFor(ctx, usage.contextWindow);
-		const line = budget?.enabled && budget.supported ? budget.rolloverAt : usage.contextWindow;
-		chars = Math.min(
-			MAX_HANDOFF_CHARS,
-			Math.max(0, line - usage.tokens - PAGE_MARGIN_TOKENS) * 4 - imageCount * ESTIMATED_IMAGE_CHARS,
-		);
-	}
-	if (chars < MIN_PAGE_CHARS) {
-		throw new Error(
-			`Too little context remains to read a page safely. Call new_context first, then retry with offset ${offset}.`,
-		);
-	}
-	return chars;
+	if (!usage || usage.tokens == null) return freshPayloadChars(ctx, toolTokens) / 4 + PAGE_MARGIN_TOKENS;
+	const budget = budgetFor(ctx, usage.contextWindow);
+	const line = budget?.enabled && budget.supported ? budget.rolloverAt : usage.contextWindow;
+	return line - usage.tokens;
 }
 
 function buildGuidance(ctx: NativeContext): string {
@@ -678,6 +710,7 @@ Automatic handoffs are emergency recovery records, not proof of current state. R
 }
 
 export default function (pi: ExtensionAPI) {
+	registerPosthorseMessages(pi);
 	const activeToolTokens = () => {
 		const active = new Set(pi.getActiveTools());
 		return pi
@@ -694,7 +727,42 @@ export default function (pi: ExtensionAPI) {
 			);
 	};
 
+	let pendingPageTokens = 0;
+	let previousPageUsage: number | null | undefined;
+	const pageSize = (ctx: NativeContext, offset: number, imageCount: number) => {
+		const usage = ctx.getContextUsage()?.tokens;
+		// Parallel siblings are not in native usage yet; sequential results must not be counted twice.
+		if (usage != null && previousPageUsage != null) {
+			pendingPageTokens = Math.max(0, pendingPageTokens - Math.max(0, usage - previousPageUsage));
+		}
+		previousPageUsage = usage;
+		const remaining = pageCapacity(ctx, activeToolTokens()) - pendingPageTokens;
+		const chars = Math.min(
+			MAX_HANDOFF_CHARS,
+			Math.max(0, remaining - PAGE_MARGIN_TOKENS) * 4 - imageCount * ESTIMATED_IMAGE_CHARS,
+		);
+		if (chars < MIN_PAGE_CHARS) {
+			const message = `Too little context remains to read a page safely. Call new_context first, then retry with offset ${offset}.`;
+			// Refusals consume context too. Once even the guidance no longer fits, omit repeated text;
+			// the failed call still carries its original offset and earlier refusals explain the retry.
+			const text = Math.ceil(message.length / 4) <= remaining ? message : "";
+			pendingPageTokens += Math.ceil(text.length / 4);
+			throw new Error(text);
+		}
+		return chars;
+	};
+	const pageResult = (text: string, images: ImageLike[], display: PosthorseDisplay) => {
+		pendingPageTokens += Math.ceil(text.length / 4) + images.length * (ESTIMATED_IMAGE_CHARS / 4);
+		return textResult(text, images, display);
+	};
+	pi.on("turn_start", () => {
+		pendingPageTokens = 0;
+		previousPageUsage = undefined;
+	});
+
 	pi.on("session_start", (_event, ctx) => {
+		pendingPageTokens = 0;
+		previousPageUsage = undefined;
 		nativeContext(ctx);
 	});
 
@@ -781,6 +849,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "new_context",
 		label: "New Context",
+		...toolCards("new_context"),
 		description:
 			"Start a genuinely fresh context window after this tool batch. Earlier conversation leaves active context without a generated summary but remains recoverable through history. Pass concise continuation state in handoff, or save richer state with notes first.",
 		promptSnippet: "start a fresh context window with an optional atomic handoff",
@@ -807,6 +876,8 @@ export default function (pi: ExtensionAPI) {
 			return {
 				...textResult(
 					"Requested a fresh Pi context after this complete tool batch succeeds. Earlier conversation stays in session history.",
+					[],
+					{ kind: "new-context" },
 				),
 				newContext: { handoff: trimmed },
 			};
@@ -816,6 +887,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "get_context_remaining",
 		label: "Context Remaining",
+		...toolCards("get_context_remaining"),
 		description:
 			"Best available native estimate of the context budget: tokens until Pi's automatic rollover line and until the model's hard limit.",
 		promptSnippet: "check the remaining context budget only when needed",
@@ -823,14 +895,20 @@ export default function (pi: ExtensionAPI) {
 		async execute(_id, _params, _signal, _onUpdate, ctx) {
 			const native = nativeContext(ctx);
 			const usage = native.getContextUsage();
-			if (!usage || usage.tokens == null) return textResult("Context usage is not known until the next model response.");
+			if (!usage || usage.tokens == null) return textResult("Context usage is not known until the next model response.", [], { kind: "context" });
 			const n = (value: number) => value.toLocaleString("en-US");
 			const budget = budgetFor(native, usage.contextWindow);
+			const display: PosthorseDisplay = {
+				kind: "context", usage,
+				rollover: !budget?.enabled ? "disabled" : budget.supported ? "enabled" : "unsupported",
+				rolloverAt: budget?.rolloverAt,
+			};
 			const hard = `≈${n(Math.max(0, usage.contextWindow - usage.tokens))} tokens until the hard context limit (${n(usage.tokens)}/${n(usage.contextWindow)} used, ${Math.round(usage.percent ?? 0)}%). Best available native estimate.`;
-			if (!budget?.enabled) return textResult(`Automatic rollover is disabled (Pi compaction.enabled=false). ${hard}`);
-			if (!budget.supported) return textResult(`${unsupportedMessage(budget)} ${hard}`);
+			if (!budget?.enabled) return textResult(`Automatic rollover is disabled (Pi compaction.enabled=false). ${hard}`, [], display);
+			if (!budget.supported) return textResult(`${unsupportedMessage(budget)} ${hard}`, [], display);
 			return textResult(
 				`≈${n(Math.max(0, budget.rolloverAt - usage.tokens))} tokens until automatic rollover (line at ${n(budget.rolloverAt)}); ${hard}`,
+				[], display,
 			);
 		},
 	});
@@ -838,8 +916,9 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "notes",
 		label: "Notes",
+		...toolCards("notes"),
 		description:
-			"Persistent notes in .pi/notes/ that survive context resets. Ops: list, read (paged; pass offset to continue), write (create/replace; empty content clears), append, search (case-insensitive substring over note lines). Inside a Git repository, including nested directories and linked worktrees, notes belong to the main checkout.",
+			"Persistent notes in .pi/notes/ that survive context resets. Ops: list, read (paged; pass offset to continue), write (create/replace; empty content clears), append, search (case-insensitive substring over note lines). Git worktrees share notes: at the main checkout for conventional .git layouts, or in the common Git directory when metadata is stored separately. Old checkout-local notes are imported without overwriting shared notes.",
 		promptSnippet: "save and recall durable state that survives context resets",
 		promptGuidelines: [
 			"Use notes for durable state too large for a new_context handoff",
@@ -874,10 +953,10 @@ export default function (pi: ExtensionAPI) {
 
 			switch (params.op) {
 				case "list": {
-					if (!existsSync(dir)) return textResult("(no notes yet)");
+					if (!existsSync(dir)) return textResult("(no notes yet)", [], { kind: "notes-list", count: 0 });
 					const files: string[] = [];
 					walk(dir, files);
-					return textResult(files.length ? files.map((file) => file.slice(dir.length + 1)).join("\n") : "(no notes yet)");
+					return textResult(files.length ? files.map((file) => file.slice(dir.length + 1)).join("\n") : "(no notes yet)", [], { kind: "notes-list", count: files.length });
 				}
 				case "read": {
 					const relative = requireValue(params.path, "path", params.op);
@@ -888,10 +967,10 @@ export default function (pi: ExtensionAPI) {
 					if (offset && offset >= text.length) {
 						throw new Error(`Offset ${offset} is past the end of ${relative} (${text.length} chars).`);
 					}
-					const end = Math.min(text.length, offset + requirePage(nativeContext(ctx), offset, 0, activeToolTokens()));
+					const end = Math.min(text.length, offset + pageSize(nativeContext(ctx), offset, 0));
 					const more =
 						end < text.length ? `\n[chars ${offset}-${end} of ${text.length}; continue with offset ${end}]` : "";
-					return textResult(`${text.slice(offset, end)}${more}`);
+					return pageResult(`${text.slice(offset, end)}${more}`, [], { kind: "note-read", offset, end, total: text.length });
 				}
 				case "write": {
 					const relative = requireValue(params.path, "path", params.op);
@@ -899,7 +978,7 @@ export default function (pi: ExtensionAPI) {
 					const path = safeJoin(relative);
 					mkdirSync(dirname(path), { recursive: true });
 					writeFileSync(path, params.content);
-					return textResult(`Wrote .pi/notes/${relative}`);
+					return textResult(`Wrote ${path}`, [], { kind: "note-write" });
 				}
 				case "append": {
 					const relative = requireValue(params.path, "path", params.op);
@@ -912,11 +991,11 @@ export default function (pi: ExtensionAPI) {
 					const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
 					const separator = existing && !existing.endsWith("\n") ? "\n" : "";
 					appendFileSync(path, `${separator}${content.replace(/\n?$/, "\n")}`);
-					return textResult(`Appended to .pi/notes/${relative}`);
+					return textResult(`Appended to ${path}`, [], { kind: "note-append" });
 				}
 				case "search": {
 					const query = requireValue(params.query, "query", params.op).toLowerCase();
-					if (!existsSync(dir)) return textResult("(no notes yet)");
+					if (!existsSync(dir)) return textResult("(no notes yet)", [], { kind: "notes-search", count: 0 });
 					const files: string[] = [];
 					walk(dir, files);
 					const hits: string[] = [];
@@ -930,7 +1009,7 @@ export default function (pi: ExtensionAPI) {
 							}
 						}
 					}
-					return textResult(hits.length ? hits.join("\n") : `No notes match "${params.query}".`);
+					return textResult(hits.length ? hits.join("\n") : `No notes match "${params.query}".`, [], { kind: "notes-search", count: hits.length });
 				}
 			}
 		},
@@ -939,6 +1018,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "history",
 		label: "History",
+		...toolCards("history"),
 		description:
 			"Search or read normalized session entries, including earlier native context windows. Search prioritizes original content before recovery notes, handoffs, and history lookups; all remain searchable. Current branch by default; all=true searches every project session file. Within each group: newest-modified sessions first, newest entries per session. Reads return stored images and page long text with the next offset.",
 		promptSnippet: "recover earlier conversation that left the active context window",
@@ -957,13 +1037,13 @@ export default function (pi: ExtensionAPI) {
 			if (params.op === "search") {
 				const query = requireValue(params.query, "query", params.op).toLowerCase();
 				const limit = params.limit ?? 10;
-				const hits: string[][] = [[], []];
+				const hits: HistoryHit[][] = [[], []];
 				// Forks copy ancestor entries under the same ids into new session files; report each id once.
 				const seen = new Set<string>();
 				const addHit = (hit: HistoryHit | undefined) => {
 					if (!hit || seen.has(hit.id) || hits[hit.priority].length >= limit) return;
 					seen.add(hit.id);
-					hits[hit.priority].push(hit.text);
+					hits[hit.priority].push(hit);
 				};
 
 				if (params.all) {
@@ -989,7 +1069,10 @@ export default function (pi: ExtensionAPI) {
 					}
 				}
 				const results = hits.flat().slice(0, limit);
-				return textResult(results.length ? results.join("\n") : `No history matches "${params.query}".`);
+				return textResult(results.length ? results.map((hit) => hit.text).join("\n") : `No history matches "${params.query}".`, [], {
+					kind: "history-search",
+					entries: results.map((hit) => ({ headerLength: hit.headerLength, length: hit.text.length })),
+				});
 			}
 
 			const id = requireValue(params.id, "id", params.op);
@@ -1000,13 +1083,15 @@ export default function (pi: ExtensionAPI) {
 				}
 				const end = Math.min(
 					item.text.length,
-					offset + requirePage(nativeContext(ctx), offset, offset === 0 ? item.images.length : 0, activeToolTokens()),
+					offset + pageSize(nativeContext(ctx), offset, offset === 0 ? item.images.length : 0),
 				);
 				const more = end < item.text.length ? `\nMore remains; call history read with id "${id}" and offset ${end}.` : "";
+				const header = `${source ? `${source} ` : ""}${item.entry.timestamp ?? ""} [window ${item.windowId}] [${id}] [chars ${offset}-${end} of ${item.text.length}] `;
 				// Stored images ride along with the first page only.
-				return textResult(
-					`${source ? `${source} ` : ""}${item.entry.timestamp ?? ""} [window ${item.windowId}] [${id}] [chars ${offset}-${end} of ${item.text.length}] ${item.text.slice(offset, end)}${more}`,
+				return pageResult(
+					`${header}${item.text.slice(offset, end)}${more}`,
 					offset === 0 ? item.images : [],
+					{ kind: "history-read", headerLength: header.length, offset, end, total: item.text.length },
 				);
 			};
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-posthorse",
-	"version": "0.4.4",
+	"version": "0.4.6",
 	"type": "module",
 	"description": "Posthorse: fresh context, same journey. Native no-summary context windows for the fitchmultz/pi fork, with sparse budget reminders, handoffs, notes, and history.",
 	"keywords": ["pi-package", "pi-extension", "context", "posthorse", "rollover"],
@@ -9,7 +9,7 @@
 		"url": "git+https://github.com/fitchmultz/pi-posthorse.git"
 	},
 	"license": "MIT",
-	"files": ["index.ts"],
+	"files": ["index.ts", "ui.ts"],
 	"engines": {
 		"node": ">=22.19.0"
 	},
@@ -19,23 +19,28 @@
 	},
 	"scripts": {
 		"check": "tsc --noEmit",
-		"test": "node --test test/posthorse.test.ts",
+		"test": "node --import ./test/pi-loader.ts --test test/*.test.ts",
 		"prepublishOnly": "npm test && npm run check"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
 		"typebox": "*"
 	},
 	"peerDependenciesMeta": {
 		"@earendil-works/pi-coding-agent": {
 			"optional": true
 		},
+		"@earendil-works/pi-tui": {
+			"optional": true
+		},
 		"typebox": {
 			"optional": true
 		}
 	},
 	"devDependencies": {
 		"@earendil-works/pi-coding-agent": "0.85.0",
+		"@earendil-works/pi-tui": "0.85.0",
 		"typebox": "1.3.7",
 		"typescript": "^5.5.0"
 	}

package/ui.ts

@@ -0,0 +1,180 @@
+import { keyText, type ExtensionAPI, type MessageRenderer, type Theme, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Box, MouseRegion, Text, stripTerminalSequences, truncateToWidth, type Component } from "@earendil-works/pi-tui";
+
+/** Display-only facts and offsets into content, never a second copy of a note or history page. */
+export type PosthorseDisplay =
+	| { kind: "context"; usage?: { tokens: number | null; contextWindow: number; percent: number | null }; rollover?: "enabled" | "disabled" | "unsupported"; rolloverAt?: number }
+	| { kind: "notes-list" | "notes-search"; count: number }
+	| { kind: "note-read"; offset: number; end: number; total: number }
+	| { kind: "note-write" | "note-append" | "new-context" }
+	| { kind: "history-search"; entries: Array<{ headerLength: number; length: number }> }
+	| { kind: "history-read"; headerLength: number; offset: number; end: number; total: number };
+
+type ToolName = "notes" | "history" | "get_context_remaining" | "new_context";
+const titles: Record<ToolName, string> = { notes: "Notes", history: "History", get_context_remaining: "Context budget", new_context: "New context" };
+const n = (value: number) => value.toLocaleString("en-US");
+
+function clean(value: string): string {
+	return stripTerminalSequences(value).replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f\ufff9-\ufffb]/g, "");
+}
+function argsOf(value: unknown): Record<string, unknown> {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+function argument(value: unknown, name: string): string {
+	return typeof value === "string" ? clean(value) : value == null ? "…" : `[invalid ${name}]`;
+}
+function textOf(content: unknown): string {
+	if (typeof content === "string") return content;
+	return Array.isArray(content) ? content.filter((part) => part?.type === "text" && typeof part.text === "string").map((part) => part.text).join("\n") : "";
+}
+function textBlock(text: string, theme: Theme, color: "toolOutput" | "muted" | "dim" | "error" | "warning" = "toolOutput"): Text {
+	return new Text(text ? theme.fg(color, clean(text)) : "", 0, 0);
+}
+function hint(theme: Theme, width: number): string {
+	const key = keyText("app.tools.expand");
+	return truncateToWidth(theme.fg("dim", key ? `… ${key} to expand` : "… details hidden"), width);
+}
+function pageSummary(page: { offset: number; end: number; total: number }): string {
+	if (!page.total) return "Empty note";
+	if (!page.offset && page.end === page.total) return `${n(page.total)} chars · complete`;
+	return `Chars ${n(page.offset)}–${n(page.end)} of ${n(page.total)}${page.end < page.total ? `\nNext offset ${n(page.end)}` : " · final page"}`;
+}
+
+function historySections(raw: string, display: PosthorseDisplay | undefined): Array<{ body: string; header: string }> | undefined {
+	const spans = display?.kind === "history-search" ? display.entries : display?.kind === "history-read" ? [{ headerLength: display.headerLength, length: raw.length }] : undefined;
+	if (!Array.isArray(spans) || !spans.length) return undefined;
+	let start = 0;
+	const sections: Array<{ body: string; header: string }> = [];
+	for (const span of spans) {
+		if (!Number.isInteger(span.headerLength) || !Number.isInteger(span.length) || span.headerLength < 0 || span.headerLength > span.length || start + span.length > raw.length) return undefined;
+		sections.push({ header: raw.slice(start, start + span.headerLength).trimEnd(), body: raw.slice(start + span.headerLength, start + span.length) });
+		start += span.length + 1;
+	}
+	return start === raw.length + 1 ? sections : undefined;
+}
+
+export function toolCards(name: ToolName): Pick<ToolDefinition, "renderCall" | "renderResult"> {
+	return {
+		renderCall(rawArgs, theme, context) {
+			const args = argsOf(rawArgs);
+			const action = name === "notes" || name === "history" ? ` · ${argument(args.op, "op")}` : name === "new_context" ? " · request" : "";
+			const status = context.isError ? " · error" : context.isPartial ? context.executionStarted ? " · running" : " · preparing" : "";
+			const target = args.op === "search" ? ` · “${argument(args.query, "query")}”` : name === "notes" && args.op !== "list" ? ` · ${argument(args.path, "path")}` : name === "history" && args.op === "read" ? ` · ${argument(args.id, "id")}` : "";
+			const label = `${context.isPartial ? "…" : context.expanded ? "▾" : "▸"} ${titles[name]}${action}${status}${target}`;
+			return {
+				invalidate() {},
+				render(width) {
+					const heading = theme.fg(context.isError ? "error" : "toolTitle", theme.bold(label));
+					if (!context.expanded) return [truncateToWidth(heading.replace(/\s+/g, " "), width)];
+					const details = [
+						name === "history" && args.op === "search" ? `Scope: ${args.all === true ? "all project sessions" : "current branch"}` : "",
+						args.offset !== undefined ? `Offset: ${typeof args.offset === "number" ? n(args.offset) : "[invalid offset]"}` : "",
+						args.limit !== undefined ? `Limit: ${typeof args.limit === "number" ? n(args.limit) : "[invalid limit]"}` : "",
+					].filter(Boolean).join(" · ");
+					return [...new Text(heading, 0, 0).render(width), ...textBlock(details, theme, "muted").render(width)];
+				},
+			};
+		},
+		renderResult(result, { expanded, isPartial }, theme, context) {
+			const args = argsOf(context.args);
+			const raw = textOf(result.content);
+			const display = result.details as PosthorseDisplay | undefined;
+			const sections = !context.isError && !isPartial ? historySections(raw, display) : undefined;
+			let summary = "";
+			let body = raw;
+			let color: "toolOutput" | "warning" | "error" = context.isError ? "error" : "toolOutput";
+			if (!context.isError && !isPartial) {
+				switch (display?.kind) {
+					case "context": {
+						const usage = display.usage;
+						if (!usage || usage.tokens == null) { summary = "Context usage unknown"; break; }
+						const hard = `≈${n(Math.max(0, usage.contextWindow - usage.tokens))} tokens to hard limit`;
+						const rollover = display.rollover === "enabled" && display.rolloverAt !== undefined ? `≈${n(Math.max(0, display.rolloverAt - usage.tokens))} tokens to rollover` : `Automatic rollover ${display.rollover ?? "unknown"}`;
+						summary = `${rollover}\n${hard}\n≈${n(usage.tokens)} / ${n(usage.contextWindow)} used${usage.percent == null ? "" : ` (≈${Math.round(usage.percent)}%)`}`;
+						if (display.rollover === "unsupported") color = "warning";
+						break;
+					}
+					case "notes-list": summary = display.count ? `${n(display.count)} note${display.count === 1 ? "" : "s"}` : "No notes yet"; break;
+					case "notes-search": summary = display.count ? `${n(display.count)} matches returned` : "No matches"; break;
+					case "note-read": summary = pageSummary(display); break;
+					case "note-write": summary = args.content === "" ? "Cleared note" : "Saved note"; break;
+					case "note-append": summary = "Appended to note"; break;
+					case "history-search": if (Array.isArray(display.entries) && (!display.entries.length || sections)) summary = `${display.entries.length ? `${n(display.entries.length)} matches` : "No matches"} · ${args.all === true ? "all sessions" : "current branch"}`; break;
+					case "history-read": summary = pageSummary(display); break;
+					case "new-context": summary = "Requested for after the whole tool batch succeeds."; break;
+				}
+			}
+			if (!body.trim()) body = context.isError ? "No error details returned." : isPartial ? "Running…" : name === "notes" && args.op === "read" ? "Empty note" : "No text returned.";
+			const submitted = name === "new_context" && typeof args.handoff === "string" ? `Handoff supplied:\n${args.handoff}` : name === "notes" && (args.op === "write" || args.op === "append") && typeof args.content === "string" ? `Submitted content:\n${args.content || "(empty)"}` : "";
+			const images = Array.isArray(result.content) ? result.content.filter((part) => part.type === "image") : [];
+			const attachment = images.length ? `${images.length} image${images.length === 1 ? "" : "s"} attached${context.showImages ? "" : " (display hidden)"}` : "";
+			const fullText = sections ? new Text(sections.map(({ body, header }) => `${theme.fg("toolOutput", clean(body))}\n${theme.fg("dim", clean(header))}`).join("\n\n"), 0, 0) : textBlock(body, theme, color);
+			const summaryText = textBlock(summary, theme, color);
+			const submittedText = textBlock(submitted, theme);
+			const attachmentText = textBlock(attachment, theme, "muted");
+			// Old results have no spans. Only the preview sheds the known history prefix.
+			const preview = sections ? sections.map(({ body }) => body).join("\n") : name === "history" && !context.isError ? body.replace(/^[^\n]*?\[window [^\]\n]+\] \[[^\]\n]+\](?: \[chars \d+-\d+ of \d+\])? /gm, "") : body;
+			const previewText = textBlock(preview, theme, color);
+			const searchPreviews = sections && display?.kind === "history-search" ? sections.slice(0, 3).map(({ body }) => theme.fg("toolOutput", clean(body).replace(/\s+/g, " "))) : undefined;
+			const summaryOnly = display?.kind === "context" || display?.kind === "new-context" || display?.kind === "note-write" || display?.kind === "note-append" || ((display?.kind === "notes-list" || display?.kind === "notes-search") && display.count === 0) || (display?.kind === "note-read" && display.total === 0) || (display?.kind === "history-search" && Array.isArray(display.entries) && display.entries.length === 0);
+			return {
+				invalidate() {},
+				render(width) {
+					if (expanded) {
+						return [...fullText.render(width), ...attachmentText.render(width), ...(submitted ? ["", ...submittedText.render(width)] : [])];
+					}
+					const summaryRows = summaryText.render(width).slice(0, 5);
+					const previewRows = summaryOnly && !context.isError && !isPartial ? [] : searchPreviews
+						? searchPreviews.map((line) => truncateToWidth(line, width))
+						: previewText.render(width);
+					const shown = previewRows.slice(0, Math.max(0, Math.min(3, 5 - summaryRows.length - (attachment ? 1 : 0))));
+					const hidden = summaryOnly || previewRows.length > shown.length || Boolean(sections || submitted);
+					return [...summaryRows, ...shown, ...(attachment ? [truncateToWidth(theme.fg("muted", attachment), width)] : []), ...(hidden ? [hint(theme, width)] : [])];
+				},
+			};
+		},
+	};
+}
+
+export function registerPosthorseMessages(pi: ExtensionAPI): void {
+	const states = new WeakMap<object, { global: boolean; expanded: boolean }>();
+	const renderer: MessageRenderer = (message, options, theme) => {
+		let state = states.get(message);
+		if (!state || state.global !== options.expanded) {
+			state = { global: options.expanded, expanded: options.expanded };
+			states.set(message, state);
+		}
+		const view = state;
+		const window = message.customType === "context-window";
+		const raw = textOf(message.content);
+		const handoffLabel = "\n\nHandoff from the previous window:\n";
+		const handoffAt = raw.indexOf(handoffLabel);
+		const preview = window ? handoffAt < 0 ? "" : raw.slice(handoffAt + handoffLabel.length) : raw;
+		const fullText = textBlock(raw, theme);
+		const previewText = textBlock(preview, theme);
+		const historyText = textBlock("Earlier conversation remains in history.", theme, "muted");
+		const content: Component = {
+			invalidate() {},
+			render(width) {
+				const padding = Math.min(options.outputPad, Math.max(0, Math.floor((width - 1) / 2)));
+				const inner = Math.max(1, width - padding * 2);
+				const title = `${view.expanded ? "▾" : "▸"} ${window ? "Context window started" : "Checkpoint reminder"}`;
+				const heading = truncateToWidth(theme.fg(window ? "customMessageLabel" : "warning", theme.bold(title)), inner);
+				const body = view.expanded ? fullText.render(inner) : [
+					...(window ? historyText.render(inner).slice(0, 2) : []),
+					...previewText.render(inner).slice(0, window ? 2 : 3),
+					hint(theme, inner),
+				];
+				const box = new Box(padding, 1, (line) => theme.bg("customMessageBg", line));
+				box.addChild({ render: () => [heading, ...body], invalidate() {} });
+				return box.render(width);
+			},
+		};
+		return new MouseRegion(content, (event) => {
+			if (event.type !== "click" || event.button !== "left") return undefined;
+			view.expanded = !view.expanded;
+			return { handled: true };
+		});
+	};
+	for (const type of ["context-window", "posthorse-reminder", "headroom-reminder"]) pi.registerMessageRenderer(type, renderer);
+}