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

package/lib/http/headers.ts

@@ -52,3 +52,23 @@ export function scriptHeaders(): Record<string, string> {
 export function jsonHeaders(): Record<string, string> {
 	return secured("application/json; charset=utf-8");
 }
+
+/**
+ * Headers for a Server-Sent Events stream: the one response that is not the page
+ * policy, because it is a long-lived event stream rather than a document. It
+ * carries no policy of its own to relax — the page that opens it is the one
+ * governed by `PAGE_CSP` — but it is declared here so both loopback servers
+ * answer a stream the same way.
+ *
+ * `no-store` stops a cached stream from replaying stale status, `keep-alive`
+ * names the connection's intent, and `X-Accel-Buffering: no` is for any
+ * buffering reverse proxy in front of it, which would otherwise hold the frames.
+ */
+export function eventHeaders(): Record<string, string> {
+	return {
+		"Content-Type": "text/event-stream; charset=utf-8",
+		"Cache-Control": "no-store",
+		Connection: "keep-alive",
+		"X-Accel-Buffering": "no",
+	};
+}

package/lib/http/server.ts

@@ -5,9 +5,10 @@
  * Everything here is behavior a caller cannot get right by accident: a bind on
  * `127.0.0.1` only, an accept-level `error` listener so a transient failure
  * cannot take the host down, a `HEAD` that sends headers and no body, a `filePath`
- * response streamed instead of buffered, and a close that is safe to call twice
- * and drops keep-alive connections. What each server does *around* this — SSE
- * streams, request bodies, session settling — stays with that server.
+ * response streamed instead of buffered, a `stream` response opened as an event
+ * stream, and a close that is safe to call twice and drops keep-alive
+ * connections. What each server does *around* this — which frames an event
+ * stream carries, request bodies, session settling — stays with that server.
  */
 
 import { createReadStream } from "node:fs";
@@ -42,7 +43,7 @@ export async function bindLoopback(server: Server, port: number): Promise<number
  *
  * A `stream` response is deliberately not handled here: keeping a connection
  * open is the owning server's lifecycle, so it must check `stream` before
- * calling this.
+ * calling this and open the stream itself through {@link openEventStream}.
  *
  * `afterFlush` runs once a buffered body is on the wire, which is the point a
  * server may resolve a session without the client seeing a dropped connection.
@@ -68,6 +69,23 @@ export function respond(
 	response.end(result.body ?? "", afterFlush);
 }
 
+/**
+ * Write the head of a Server-Sent Events response and start its stream: the
+ * status and headers, then a `retry:` hint for the browser's own reconnect.
+ *
+ * The connection itself stays the calling server's lifecycle — `respond` must
+ * not be called after this, and the caller owns ending the response and any
+ * periodic frames.
+ */
+export function openEventStream(
+	response: ServerResponse,
+	result: Pick<ServeResponse, "status" | "headers">,
+	retryMs = 2000,
+): void {
+	response.writeHead(result.status, result.headers);
+	response.write(`retry: ${retryMs}\n\n`);
+}
+
 /**
  * An idempotent `close()` for `server`.
  *

package/lib/pdf.ts

@@ -1,11 +1,11 @@
 /**
  * The optional `unpdf` seam: lazy load, module-shape handling, and text
- * extraction, shared by `web-access` and `document`.
+ * extraction, shared by `web-access` and `file-read`.
  *
  * `unpdf` bundles a server-friendly build of PDF.js, so it is imported lazily:
  * an extension registers on every session, and a parser should load only when a
  * read actually needs it. `web-access` treats the package as optional and
- * reports {@link pdfGuidance} when it is absent; `document` ships it as a
+ * reports {@link pdfGuidance} when it is absent; `file-read` ships it as a
  * dependency. Both get the same loader, the same merged-pages call, and the same
  * result unwrapping, so a PDF reads the same way through either surface.
  *

package/lib/pool.ts

@@ -0,0 +1,62 @@
+/**
+ * Bounded concurrency for a fan-out over I/O.
+ *
+ * A directory listing and a managed-worktree status sweep both run one small
+ * read per entry — a `stat`, a git query — and each read is dominated by
+ * waiting, not by work. Run strictly in sequence, a directory of three thousand
+ * files pays three thousand round trips; run all at once, it hands the
+ * filesystem (or a git index lock) an unbounded burst. This is the middle: at
+ * most `limit` calls in flight, results in input order.
+ *
+ * The first rejection stops new work and is rethrown once every worker has
+ * settled, so a failure cannot leave a rejected promise unobserved.
+ *
+ * Value-only: one pure function over its arguments, no module state.
+ */
+
+/**
+ * Run `fn` over `items` with at most `limit` calls in flight, in input order.
+ *
+ * `limit` is clamped to `[1, items.length]`, so a caller may pass a configured
+ * width without guarding it. `fn` receives the item and its index; the returned
+ * array is in `items` order regardless of completion order. An empty input never
+ * calls `fn`.
+ */
+export async function mapConcurrent<T, R>(
+	items: readonly T[],
+	limit: number,
+	fn: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+	const total = items.length;
+	if (total === 0) return [];
+	const width = Math.min(Math.max(1, Math.floor(limit)), total);
+	const results = new Array<R>(total);
+
+	let next = 0;
+	let failed = false;
+	let failure: unknown;
+
+	/** Take the next unclaimed index and run it; stop taking after a failure. */
+	const worker = async (): Promise<void> => {
+		for (;;) {
+			if (failed) return;
+			const index = next++;
+			if (index >= total) return;
+			try {
+				results[index] = await fn(items[index], index);
+			} catch (error) {
+				// Keep the first failure: a later one is a consequence of the work
+				// already in flight, not the cause the caller needs to read.
+				if (!failed) {
+					failed = true;
+					failure = error;
+				}
+				return;
+			}
+		}
+	};
+
+	await Promise.all(Array.from({ length: width }, worker));
+	if (failed) throw failure;
+	return results;
+}

package/lib/requirements.ts

@@ -255,7 +255,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 		optional: [gitCheck("the branch chip and the diff view")],
 		notes: ["The default-browser opener (`open` / `xdg-open` / `cmd`) is best-effort; the URL is printed either way."],
 	},
-	document: {},
+	"file-read": {},
 	"file-open": {
 		notes: [
 			"The `/open` command and its notification need an interactive UI; the `open_path` tool works without one.",
@@ -266,6 +266,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	memory: {
 		optional: [gitCheck("project-scope memory under the repository root")],
 	},
+	context: {},
 	wechat: {
 		optional: [
 			{
@@ -301,7 +302,6 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 		],
 	},
 };
-
 // --- Probing ----------------------------------------------------------------
 
 /** Run a command and report its exit code; production backs this with `pi.exec`. */

package/lib/screen-session.ts

@@ -0,0 +1,85 @@
+/**
+ * Mounting a dock screen: rails suppressed, an optional repaint tick, and one
+ * teardown.
+ *
+ * Pi mounts a `ctx.ui.custom` screen in the editor slot the above-editor rails
+ * share, so every screen wraps itself in `withRailsSuppressed`. Three of them —
+ * `/jobs`, `/watch`, and `/memory` — also poll while they are open (a log pane,
+ * a line pane, a store another process can edit), and each re-derived the same
+ * `let timer` / `stopTimer` / `setInterval(...).unref?.()` / `finally` skeleton
+ * around its own component. The rails lifetime and the timer lifetime are the
+ * same window, so they are one helper rather than two wrappers each caller
+ * stacks and unwinds by hand.
+ *
+ * The timer is a seam (`RepeatTimer`), so a test drives the tick instead of
+ * waiting for one, and it is armed after the mount returns: a component whose
+ * constructor throws leaves no timer behind.
+ *
+ * Value-only: the timer handle lives in the caller's closure.
+ */
+
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { withRailsSuppressed } from "./rails.ts";
+import { defaultInterval, type RepeatTimer } from "./timer.ts";
+
+/** What the host accepts back from a screen's mount. */
+export type ScreenComponent = Component & { dispose?(): void };
+
+/** What a mounted screen is given: the host's mount parameters, narrowed. */
+export interface PolledScreen {
+	/** The host's component handle; a screen that needs an `Editor` builds it from this. */
+	readonly tui: TUI;
+	/** The theme the host handed the mount. */
+	readonly theme: Theme;
+	/** Ask the host to repaint. */
+	requestRender(): void;
+	/** Close the screen, as its own close key would. */
+	close(): void;
+	/** The terminal's height in rows, or `undefined` when the host cannot say. */
+	viewportRows(): number | undefined;
+}
+
+export interface PolledScreenOptions<Screen> {
+	/** How often `poll` runs while the screen is open, in ms. */
+	pollMs: number;
+	/** Run once per tick; `screen` is what `mount` returned. */
+	poll(screen: Screen, handles: PolledScreen): void;
+	/** Timer seam; defaults to an unref'd interval. */
+	timer?: RepeatTimer;
+}
+
+/**
+ * Show one polled dock screen and resolve when it closes.
+ *
+ * The caller still owns the `ctx.mode !== "tui"` branch, because the text
+ * fallback differs per command; everything from the mount to the teardown is
+ * here.
+ */
+export async function withPolledScreen<Screen extends ScreenComponent>(
+	pi: Pick<ExtensionAPI, "events">,
+	ctx: Pick<ExtensionContext, "ui">,
+	mount: (handles: PolledScreen) => Screen,
+	options: PolledScreenOptions<Screen>,
+): Promise<void> {
+	const { pollMs, poll, timer = defaultInterval } = options;
+	let stop: (() => void) | undefined;
+	try {
+		await withRailsSuppressed(pi, () =>
+			ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
+				const handles: PolledScreen = {
+					tui,
+					theme,
+					requestRender: () => tui.requestRender(),
+					close: () => done(),
+					viewportRows: () => tui.terminal?.rows,
+				};
+				const screen = mount(handles);
+				stop = timer(pollMs, () => poll(screen, handles));
+				return screen;
+			}),
+		);
+	} finally {
+		stop?.();
+	}
+}

package/lib/timer.ts

@@ -0,0 +1,61 @@
+/**
+ * The timer seams: one shot, repeating, and a sleep that can be aborted.
+ *
+ * Extensions need the same three things, and each has the same two properties a
+ * test cares about: it is cancellable, and its production default never holds
+ * the process open. The WeChat bridge arms a one-shot per acknowledgement,
+ * typing keep-alive, and prompt timeout; plan's review page arms one for the
+ * closed-tab grace; `job` and `watch` repaint on a repeating one; the browse
+ * live channel needs both; `job`, `watch`, `check`, `subagent`, and `wechat`
+ * sleep between polls. Keeping the defaults here means one definition of "arm
+ * it, and let it be cancelled", and one place where the `unref` lives.
+ *
+ * Value-only: types and constant functions, no module state.
+ */
+
+/** Arm a one-shot timer; the returned function cancels it. */
+export type ArmTimer = (ms: number, fn: () => void) => () => void;
+
+/** The production timer: `setTimeout`, detached from the event loop. */
+export const defaultTimer: ArmTimer = (ms, fn) => {
+	const timer = setTimeout(fn, ms);
+	(timer as { unref?: () => void }).unref?.();
+	return () => clearTimeout(timer);
+};
+
+/** Arm a repeating timer; the returned function stops it. */
+export type RepeatTimer = (ms: number, tick: () => void) => () => void;
+
+/** The production ticker: `setInterval`, detached from the event loop. */
+export const defaultInterval: RepeatTimer = (ms, tick) => {
+	const timer = setInterval(tick, ms);
+	(timer as { unref?: () => void }).unref?.();
+	return () => clearInterval(timer);
+};
+
+/**
+ * Resolve after `ms`, or reject when `signal` aborts first.
+ *
+ * The one rejection is `Error("aborted")` whatever the signal carries, so a
+ * caller that names its own abort error maps one case rather than inspecting a
+ * reason. The timer is cleared on both paths and never `unref`'d: a sleep exists
+ * to keep the caller waiting, so nothing else is pending to keep the process
+ * alive, and an unref'd one could be dropped mid-wait.
+ */
+export function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new Error("aborted"));
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = (): void => {
+			clearTimeout(timer);
+			reject(new Error("aborted"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}

package/lib/tui/README.md

@@ -151,6 +151,6 @@ and the first call throws at runtime.
 
 ## Tests
 
-A module here gets a sibling `<module>.test.ts` covering fields, width bounds,
-ordering, and glyphs — never literal column padding. An extension's screen test
-is the `tui.test.ts` beside its `tui.ts`.
+A capability suite groups the modules it covers and asserts fields, width
+bounds, ordering, and glyphs — never literal column padding. An extension's
+screen coverage lives in its declared capability suite (for example `ui.test.ts`).

package/lib/tui/columns.ts

@@ -15,14 +15,17 @@ import { sanitizeLine, sanitizeUntrustedLine } from "../format.ts";
 /** The columns a label gets before it stops reading as a label. */
 export const LABEL_WIDTH = 48;
 
-/** A usable origin: terminal arithmetic starts from one column, never zero. */
-function columns(width: number): number {
+/**
+ * A usable drawing width in columns: terminal arithmetic starts from one column,
+ * never zero, so a narrow or unknown width never produces an empty frame.
+ */
+export function usableWidth(width: number): number {
 	return Math.max(1, Math.floor(width));
 }
 
 /** Clip a possibly-themed string to `width` columns, marking a cut with `ellipsis`. */
 export function clip(text: string, width: number, ellipsis = "…"): string {
-	return truncateToWidth(text, columns(width), ellipsis);
+	return truncateToWidth(text, usableWidth(width), ellipsis);
 }
 
 /**
@@ -34,7 +37,7 @@ export function clip(text: string, width: number, ellipsis = "…"): string {
  * A themed string keeps its colours on both the head and the tail.
  */
 export function clipMiddle(text: string, width: number, ellipsis = "…"): string {
-	const w = columns(width);
+	const w = usableWidth(width);
 	if (visibleWidth(text) <= w) return text;
 	const ellipsisWidth = visibleWidth(ellipsis);
 	const budget = w - ellipsisWidth;
@@ -69,7 +72,7 @@ export function clipLabel(text: string): string {
 
 /** Pad `text` on the right to exactly `width` columns. Never truncates. */
 export function padTo(text: string, width: number): string {
-	const missing = columns(width) - visibleWidth(text);
+	const missing = usableWidth(width) - visibleWidth(text);
 	return missing > 0 ? text + " ".repeat(missing) : text;
 }
 
@@ -83,7 +86,7 @@ export function padTo(text: string, width: number): string {
  * plain left-aligned line with no trailing spaces.
  */
 export function splitRow(left: string, right: string, width: number, minGap = 1): string {
-	const w = columns(width);
+	const w = usableWidth(width);
 	if (!right) return clip(left, w);
 	const gap = Math.max(0, Math.floor(minGap));
 	const rightCell = clip(right, w);
@@ -93,13 +96,35 @@ export function splitRow(left: string, right: string, width: number, minGap = 1)
 	return padTo(clip(left, leftBudget), w - rightWidth) + rightCell;
 }
 
+/**
+ * Left cell, then a gap, then the right cell, with the result ending after the
+ * right cell instead of filling the width.
+ *
+ * The sibling of {@link splitRow}: a label and its value read as one pair on a
+ * wide terminal instead of sitting at opposite edges, while a tight line still
+ * keeps the value — the left cell is clipped to make room, and the gap shrinks
+ * in whole columns before the right cell loses anything.
+ */
+export function inlineRow(left: string, right: string, width: number, gap = 2): string {
+	const w = usableWidth(width);
+	if (!right) return clip(left, w);
+	const space = Math.max(0, Math.floor(gap));
+	const rightCell = clip(right, w);
+	const rightWidth = visibleWidth(rightCell);
+	const leftBudget = w - rightWidth - space;
+	if (leftBudget <= 0) return rightCell;
+	const leftCell = clip(left, leftBudget);
+	const separator = " ".repeat(Math.max(0, Math.min(space, w - visibleWidth(leftCell) - rightWidth)));
+	return `${leftCell}${separator}${rightCell}`;
+}
+
 /**
  * Join as many whole cells as fit, dropping trailing cells rather than
  * clipping one in half. The first cell is always kept, so an over-wide line
  * degrades to a clipped first cell instead of an empty one.
  */
 export function fitCells(cells: readonly string[], width: number, separator = " "): string {
-	const w = columns(width);
+	const w = usableWidth(width);
 	const kept: string[] = [];
 	for (const cell of cells) {
 		const candidate = [...kept, cell].join(separator);
@@ -118,7 +143,7 @@ export function fitCells(cells: readonly string[], width: number, separator = "
  * {@link fitCells} it may return several lines, and always returns one.
  */
 export function flowCells(cells: readonly string[], width: number): string[] {
-	const w = columns(width);
+	const w = usableWidth(width);
 	const lines: string[] = [];
 	let current = "";
 	let currentWidth = 0;

package/lib/tui/dock-screen.ts

@@ -136,8 +136,16 @@ export abstract class DockListScreen<T> implements Component {
 		return this.options.theme;
 	}
 
-	/** The row under the cursor, if any. */
-	protected get focused(): T | undefined {
+	/**
+	 * The row under the cursor, if any.
+	 *
+	 * Not named `focused`: Pi's `Focusable` check is `"focused" in component`, and a
+	 * component that answers it is handed the focus flag by assignment
+	 * (`component.focused = true`). A read-only accessor under that name throws a
+	 * `TypeError` on the way back to the editor and takes the process with it. This
+	 * screen paints its own selection marker and needs no hardware cursor.
+	 */
+	protected get focusedRow(): T | undefined {
 		const rows = this.rows();
 		return rows[this.cursor.indexOf(rows, (row) => this.idOf(row))];
 	}
@@ -229,7 +237,7 @@ export abstract class DockListScreen<T> implements Component {
 	}
 
 	private openDetail(): void {
-		const row = this.focused;
+		const row = this.focusedRow;
 		if (!row) return;
 		const contents = this.detailFor(row);
 		this.mode = "detail";
@@ -274,7 +282,7 @@ export abstract class DockListScreen<T> implements Component {
 			this.openDetail();
 			return;
 		}
-		this.handleVerb(data, this.focused);
+		this.handleVerb(data, this.focusedRow);
 	}
 
 	private handleConfirmKey(data: string): void {

package/lib/tui/rows.ts

@@ -13,7 +13,7 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { clip, padTo, splitRow } from "./columns.ts";
+import { clip, inlineRow, padTo, splitRow } from "./columns.ts";
 import { selectionMarker } from "./cursor.ts";
 import { GLYPHS } from "./glyphs.ts";
 import { BODY_INDENT } from "./indent.ts";
@@ -41,21 +41,29 @@ export interface ListRow {
 	/** The row's text. */
 	label: string;
 	labelRole?: TuiRole;
-	/** Right-aligned meta (a count, a time, a state). */
+	/** Meta that closes the row: right-aligned, or beside the label when `align` is `inline`. */
 	trailing?: string;
 	trailingRole?: TuiRole;
+	/**
+	 * Where the trailing cell sits. `end` (the default) pushes it to the right
+	 * edge, which suits a column of counts. `inline` keeps it beside the label
+	 * with a two-column gap, so a label and its value read as one pair on a wide
+	 * terminal instead of sitting at opposite ends of the line.
+	 */
+	align?: "end" | "inline";
 	/** Extra columns before the marker, for a nested row. */
 	indent?: number;
 }
 
 /**
  * One list row: an optional indent, the selection marker, an optional glyph,
- * the label, and right-aligned trailing meta.
+ * the label, and the trailing meta.
  *
  * The marker column is reserved by default, so selected and unselected rows
  * align; `marker: false` drops it for a non-interactive row. The trailing meta
- * is the anchor when the terminal is narrow (see `splitRow`), so a value at the
- * end of the row survives.
+ * is the anchor when the terminal is narrow (see `splitRow` and `inlineRow`),
+ * so a value at the end of the row survives either way; `align` decides whether
+ * it sits at the right edge or right after the label.
  */
 export function listRow(theme: Theme, width: number, row: ListRow): string {
 	const indent = " ".repeat(Math.max(0, Math.floor(row.indent ?? 0)));
@@ -64,7 +72,8 @@ export function listRow(theme: Theme, width: number, row: ListRow): string {
 	const glyph = row.glyph ? `${paint(theme, row.glyphRole ?? "info", row.glyph)} ` : "";
 	const label = paint(theme, row.labelRole ?? "label", row.label);
 	const trailing = row.trailing ? paint(theme, row.trailingRole ?? "meta", row.trailing) : "";
-	return splitRow(`${indent}${marker}${leading}${glyph}${label}`, trailing, width);
+	const head = `${indent}${marker}${leading}${glyph}${label}`;
+	return row.align === "inline" ? inlineRow(head, trailing, width) : splitRow(head, trailing, width);
 }
 
 /** A status row (a job, a watcher): the marker, a status glyph, a label, and right-aligned meta. */

package/lib/tui/rules.ts

@@ -15,6 +15,7 @@
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { visibleWidth } from "@earendil-works/pi-tui";
+import { usableWidth } from "./columns.ts";
 import { paint, type TuiRole } from "./tokens.ts";
 
 /** The glyph and colors a rule is drawn with. */
@@ -39,14 +40,9 @@ export interface CenteredRuleStyle extends RuleStyle {
  */
 export const RULE_GLYPH = "─";
 
-/** A usable origin: terminal arithmetic starts from one column, never zero. */
-function widthOf(width: number): number {
-	return Math.max(1, Math.floor(width));
-}
-
 /** A full-width divider in one color. */
 export function plainRule(theme: Theme, width: number, style: RuleStyle = {}): string {
-	const w = widthOf(width);
+	const w = usableWidth(width);
 	return paint(theme, style.fillRole ?? "rule", (style.glyph ?? RULE_GLYPH).repeat(w));
 }
 
@@ -64,7 +60,7 @@ function labelRule(
 	fillRole: TuiRole,
 	style: RuleStyle,
 ): string {
-	const w = widthOf(width);
+	const w = usableWidth(width);
 	const text = label.trim();
 	if (!text) return plainRule(theme, w, style);
 	const labelWidth = visibleWidth(text);
@@ -75,7 +71,7 @@ function labelRule(
 
 /** A centered rule: fill, label, and the rest of the fill. */
 export function centeredRule(theme: Theme, width: number, label: string, style: CenteredRuleStyle = {}): string {
-	const w = widthOf(width);
+	const w = usableWidth(width);
 	const glyph = style.glyph ?? RULE_GLYPH;
 	const fillRole = style.fillRole ?? "ruleStrong";
 	if (!label.trim()) return paint(theme, fillRole, glyph.repeat(w));

package/lib/tui/tool.ts

@@ -1,6 +1,7 @@
 /**
- * The shared tool-transcript kit: a call title, a width-safe call component,
- * sanitized error lines, the expand hint, and the running timer.
+ * The shared tool-transcript kit: a call title, the call line a renderer draws
+ * with it, the failure line a result shows before its body, the expand hint, and
+ * the running timer.
  *
  * Every extension's `renderCall` / `renderResult` used to repeat the same four
  * idioms — a bold `toolTitle`, a raw `result.content[0]`, a hand-built
@@ -34,6 +35,58 @@ export function toolCallTitle(theme: Theme, name: string): string {
 	return theme.fg("toolTitle", theme.bold(name));
 }
 
+/**
+ * One call line: the bold tool name, then the subject in the meta role.
+ *
+ * The subject is flattened to one line here, because a call line is a label: a
+ * stored note, a task, or a path carrying a newline cannot wrap it into the body
+ * column, where it would read as a result. Pass the clip the subject deserves —
+ * `middle` for a path or a URL whose tail is the identity, `end` for prose.
+ *
+ * A subject drawn in another role (an argument value in `label`, a suffix in
+ * `faint`) stays hand-built at its call site; this is the plain headline.
+ */
+export function callLine(
+	theme: Theme,
+	last: unknown,
+	name: string,
+	subject: string,
+	clip: CallClip = "end",
+): ToolCallText {
+	const text = reuseCallText(last, "", clip);
+	text.setText(toolCallTitle(theme, `${name} `) + paint(theme, "meta", sanitizeLine(subject)));
+	return text;
+}
+
+/**
+ * A result resolved to its details, or to the one line a failure shows.
+ */
+export type DetailsOrLine<Details> = { line: string } | { details: Details };
+
+/**
+ * Resolve a result to its details, or to the line to show instead.
+ *
+ * The failure is one branch whether the call carried no details at all (Pi's
+ * `{ details: {}, isError: true }` envelope) or the extension reported its own
+ * `details.error`, and it goes through `errorLine`: a multi-line message keeps
+ * its lines and `Error:` is prefixed exactly once, which a hand-built
+ * `paint(theme, "bad", \`Error: ${sanitizeLine(...)}\`)` does not.
+ */
+export function detailsOrLine<Details extends object>(
+	theme: Theme,
+	result: ToolMessageResult,
+	expanded: boolean,
+	details: Details | undefined,
+): DetailsOrLine<Details> {
+	if (!details) return { line: rejectionLine(theme, result, expanded) };
+	// The one property this reads is the extension's own report field; a details
+	// block without it (a plan summary, a check report) simply has no failure.
+	if ("error" in details && typeof details.error === "string" && details.error !== "") {
+		return { line: errorLine(theme, details.error) };
+	}
+	return { details };
+}
+
 /** How a call line gives up columns when the terminal is narrow. */
 export type CallClip = "end" | "middle";
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gavin-hu/my-pi-agent",
-  "version": "0.15.0",
-  "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, document, check, memory, wechat, and bytefly.",
+  "version": "0.16.0",
+  "description": "Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, file-read, check, memory, context, wechat, and bytefly.",
   "keywords": [
     "pi-package",
     "pi",
@@ -39,7 +39,7 @@
     "open_path",
     "reveal",
     "doc",
-    "document",
+    "file-read",
     "doctor",
     "diagnostics",
     "prerequisites",
@@ -50,6 +50,9 @@
     "read_doc",
     "memory",
     "cross-session",
+    "context",
+    "compaction",
+    "tokens",
     "wechat",
     "web-access",
     "bytefly",
@@ -94,9 +97,10 @@
       "./extensions/watch/index.ts",
       "./extensions/web-access/index.ts",
       "./extensions/file-browse/index.ts",
-      "./extensions/document/index.ts",
+      "./extensions/file-read/index.ts",
       "./extensions/file-open/index.ts",
       "./extensions/memory/index.ts",
+      "./extensions/context/index.ts",
       "./extensions/wechat/index.ts",
       "./extensions/bytefly/index.ts"
     ],