@gavin-hu/my-pi-agent 0.15.1 → 0.17.0

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/tool-result.ts

@@ -1,17 +1,67 @@
 /**
- * The shared shape of a rejected tool call.
+ * The shared shape of a tool result.
  *
- * Extension tools return an `isError: true` result carrying their own `details`
- * type. `toolError` builds the content and the flag so the extensions that
- * reject a call (`job` and `watch`, plus any future tool) agree on the shape.
+ * Every extension tool returns the same envelope: one text block the model
+ * reads, the extension's own `details` for the renderer and the session branch,
+ * and — where the tool declares an `outputSchema` — the JSON mirror Pi calls
+ * `structuredContent`. A rejected call is that envelope marked `isError`, still
+ * carrying the previous state so the model can retry.
+ *
+ * `textResult` and `failedResult` build the two, so the flag and the absent
+ * `structuredContent` are decided once. What stays with the extension is the
+ * text and the mirror: `structuredContent` drops `undefined` field by field and
+ * projects nested objects, so it is written per `details` type rather than
+ * derived. `toolError` / `errorResult` keep the shorthand the
+ * action-and-message tools (`job` and `watch`) share.
  */
 
+import type { JsonValue } from "@earendil-works/pi-ai";
+
 /** One text block in a tool result. */
 export interface ToolErrorContent {
 	type: "text";
 	text: string;
 }
 
+/** A tool result: what the model reads, the extension's details, and its JSON mirror. */
+export interface ToolResult<Details> {
+	content: ToolErrorContent[];
+	details: Details;
+	structuredContent?: Record<string, JsonValue>;
+}
+
+/** A rejected call: the result, marked so the host reports it as an error. */
+export interface ToolFailure<Details> extends ToolResult<Details> {
+	isError: true;
+}
+
+/** The content and details both results share. */
+function envelope<Details>(text: string, details: Details): ToolResult<Details> {
+	return { content: [{ type: "text", text }], details };
+}
+
+/** A successful call. */
+export function textResult<Details>(
+	text: string,
+	details: Details,
+	structuredContent?: Record<string, JsonValue>,
+): ToolResult<Details> {
+	const result = envelope(text, details);
+	return structuredContent === undefined ? result : { ...result, structuredContent };
+}
+
+/** A rejected call, keeping the state the caller had before it. */
+export function failedResult<Details>(
+	text: string,
+	details: Details,
+	structuredContent?: Record<string, JsonValue>,
+): ToolFailure<Details> {
+	const result = envelope(text, details);
+	return structuredContent === undefined
+		? { ...result, isError: true }
+		: { ...result, structuredContent, isError: true };
+}
+
 /** A rejected tool call: the message as content, the extension's details, and the error flag. */
 export function toolError<Details extends { action: string; error: string }>(
 	message: string,

package/lib/tui/README.md

@@ -35,17 +35,24 @@ Reach for a `lib/tui/` primitive before composing your own: `plainRule` /
 `fitCells` for two columns, `LinePane` for a scrollable log, `ListCursor` /
 `IdCursor` for selection, `byRunningFirst` for a live list's order,
 `DockListScreen` for a list that opens a pane, `TailResult` for a tool result
-that lists rows or tails output, and `ConfirmState` before a destructive action.
+that lists rows or tails output, `screenFooter` for a screen's own last three
+rows, and `ConfirmState` before a destructive action.
 
 ## Docked list screens
 
 Every list screen is `dockListFrame`: the header rule, an optional summary and
-its blank line, the body, an optional range row, an optional detail block, and
-the blank-padded hint. The frame owns that spacing, so a screen never hand-rolls
-it — including the blank line above the detail block, which keeps a footnote
-from reading as one more row. A screen that sizes its body through `fitRows`
-counts the block with `detailBlockRows`, or the hint row is pushed off the
-bottom of a short terminal.
+its blank line, the body, an optional range row, an optional detail block, the
+key-hint row, and the closing rule. The frame owns that spacing, so a screen
+never hand-rolls it — including the blank line above the detail block, which
+keeps a footnote from reading as one more row. A screen that sizes its body
+through `fitRows` counts the block with `detailBlockRows`, or the hint row is
+pushed off the bottom of a short terminal.
+
+The closing rule is not decoration: Pi's built-in selectors draw one under the
+list and over the footer, and the editor a docked screen replaces draws its own,
+so a screen that ends on a blank removes the dock's bottom edge. A screen that
+lays out its own rows closes its block with `screenFooter(theme, width, hint)`;
+a screen whose row above the hint varies places `plainRule` itself.
 
 A list that **opens a pane over one row** — `/jobs`, `/watch`, `/agents`,
 `/check` — subclasses [`dock-screen.ts`](./dock-screen.ts) instead of
@@ -92,7 +99,8 @@ Resolve colors through a [`tokens.ts`](./tokens.ts) role
 (`paint(theme, role, text)`), never a literal ANSI sequence, hex value, or Pi
 token named inline; a theme swap must re-skin every surface. Use the shared
 `selectionMarker`, `GLYPHS`, `SEPARATORS`, and `STATUS_KEYS` instead of retyping
-their literals, and `screenHint` / Pi's `keyHint` for the hint row.
+their literals, `screenHint` / Pi's `keyHint` for the hint row, and
+`screenFooter` for the hint row with its blank and closing rule.
 
 A list accents the focused row's label (`labelRole: selected ? "accent" :
 "label"`); the `❯` marker alone is not enough to tell which row is live. The
@@ -151,6 +159,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/chrome.ts

@@ -8,9 +8,9 @@
  * the transcript visible.
  *
  * Screens are full-width, terminal-height-aware components. These helpers build
- * the top rule, clamp a screen's body to the terminal, and render the key-hint
- * footer, so each screen keeps its own layout but not its own copy of the
- * arithmetic or hint vocabulary.
+ * the top rule and the closing rule, clamp a screen's body to the terminal, and
+ * render the key-hint footer, so each screen keeps its own layout but not its
+ * own copy of the arithmetic or hint vocabulary.
  *
  * No runtime dependencies beyond `@earendil-works/pi-tui`: the theme is passed
  * in, and the viewport options are explicit.
@@ -20,6 +20,7 @@ import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth, visibleWidth, type EditorTheme, type OverlayOptions } from "@earendil-works/pi-tui";
 import { SEPARATORS } from "./glyphs.ts";
 import { BODY_INDENT } from "./indent.ts";
+import { plainRule } from "./rules.ts";
 
 /**
  * `ctx.ui.custom` options that give a screen the whole terminal.
@@ -88,12 +89,29 @@ export function screenHint(theme: Theme, width: number, hints: ScreenHint[], ind
 	return truncateToWidth(`${lead}${kept.map(render).join(separator)}`, target);
 }
 
+/**
+ * The bottom of a screen: a blank row, its key-hint row, and the closing rule.
+ *
+ * {@link dockListFrame} ends a docked list screen with this, and a screen that
+ * lays out its own rows — `/context`, the WeChat login and control screens —
+ * closes its block with it too, so no screen spells the three rows out alone. A
+ * screen whose row above the hint varies (a scroll gauge or a blank) places its
+ * own rule with `plainRule` instead.
+ */
+export function screenFooter(theme: Theme, width: number, hint: string): string[] {
+	return ["", hint, plainRule(theme, width)];
+}
+
 /**
  * The sections of a docked list screen, assembled by {@link dockListFrame}.
  * `body`, `range`, and `detail` lines are built (and truncated) by the caller;
  * the frame only places them.
  */
 export interface DockListFrame {
+	/** The active theme, used for the closing rule. */
+	theme: Theme;
+	/** The screen width in columns, used for the closing rule. */
+	width: number;
 	/** The pre-rendered header line, usually `titleRule(theme, width, title)`. */
 	header: string;
 	/** A summary line under the header; a blank line follows it. */
@@ -132,11 +150,14 @@ export function detailBlockRows(detail: readonly string[] | undefined, blank = t
 /**
  * Assemble a docked list screen: the caller's header rule, an optional summary
  * and its blank line, the body, an optional range row, optional detail rows after
- * their own blank line, and the blank-line-padded key-hint footer.
+ * their own blank line, the key-hint row, and the closing rule.
  *
  * This is the convention every docked list screen shares — the bytefly panel,
  * `/jobs`, `/watch`, `/todos`, `/memory`, and `/rewind`. The header line is built
- * by the caller (usually `titleRule`), so the frame never picks a rule style.
+ * by the caller (usually `titleRule`), so the frame never picks the *opening*
+ * rule style; the closing rule is always the muted fill, matching the closing
+ * rule Pi's built-in selectors draw and the bottom border of the editor slot the
+ * screen replaces.
  */
 export function dockListFrame(frame: DockListFrame): string[] {
 	const lines: string[] = [frame.header];
@@ -147,7 +168,7 @@ export function dockListFrame(frame: DockListFrame): string[] {
 		if (frame.detailBlank !== false) lines.push("");
 		lines.push(...frame.detail);
 	}
-	lines.push("", frame.hint, "");
+	lines.push(...screenFooter(frame.theme, frame.width, frame.hint));
 	return lines;
 }
 

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

@@ -33,10 +33,10 @@ import { paint } from "./tokens.ts";
 /** Rows the body shows when the terminal height is unknown. */
 const SCREEN_DEFAULT_ROWS = 14;
 
-/** Fixed rows around the list body: header, summary, blank, blank, hint, blank. */
+/** Fixed rows around the list body: header, summary, blank, blank, hint, closing rule. */
 const LIST_CHROME_ROWS = 6;
 
-/** Fixed rows around a detail body: header, subtitle, blank, blank, hint, blank. */
+/** Fixed rows around a detail body: header, subtitle, blank, blank, hint, closing rule. */
 const DETAIL_CHROME_ROWS = 6;
 
 /** What a detail pane shows: its title, lines, and the one-line subtitle. */
@@ -353,6 +353,8 @@ export abstract class DockListScreen<T> implements Component {
 		}
 
 		return dockListFrame({
+			theme: this.theme,
+			width: w,
 			header: titleRule(this.theme, w, this.options.title),
 			summary: this.summary(rows, w),
 			body,
@@ -389,6 +391,8 @@ export abstract class DockListScreen<T> implements Component {
 		}
 
 		return dockListFrame({
+			theme: this.theme,
+			width: w,
 			header: titleRule(this.theme, w, this.pane.title(this.options.detailTitle)),
 			summary: clip(`  ${paint(this.theme, "faint", this.pane.subtitleLine())}`, w),
 			body,

package/lib/tui/gauge.ts

@@ -26,16 +26,20 @@ export const DEFAULT_GAUGE_THRESHOLDS: GaugeThresholds = { warn: 70, danger: 90
 /**
  * Filled and empty block counts for a percentage across `blocks` cells.
  *
- * The fill floors so the bar reads full only at 100%, and forces one block for
- * any non-zero usage so a small percentage is still visible. A `null` percent
- * (unknown) fills nothing, leaving the caller to decide whether to draw the
- * empty track; a known `0` draws it.
+ * The fill rounds to the nearest cell, so a bar sits no more than half a cell
+ * away from the number printed beside it, and the last cell is kept for 100% so
+ * a bar reads full only at a full value. Any non-zero usage still forces one
+ * block, so a small percentage stays visible. A `null` percent (unknown) fills
+ * nothing, leaving the caller to decide whether to draw the empty track; a known
+ * `0` draws it.
  */
 export function computeGauge(percent: number | null, blocks: number): { filled: number; empty: number } {
 	if (blocks <= 0) return { filled: 0, empty: 0 };
 	if (percent === null) return { filled: 0, empty: blocks };
 	const clamped = Math.max(0, Math.min(100, percent));
-	const filled = Math.max(clamped > 0 ? 1 : 0, Math.floor((clamped / 100) * blocks));
+	const nearest = Math.round((clamped / 100) * blocks);
+	const capped = clamped < 100 ? Math.min(blocks - 1, nearest) : nearest;
+	const filled = Math.max(clamped > 0 ? 1 : 0, capped);
 	return { filled, empty: blocks - filled };
 }
 

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/lib/usage.ts

@@ -0,0 +1,26 @@
+/**
+ * The usage counters this package accounts in.
+ *
+ * A session, a delegated child run, and a priced record are all measured in the
+ * same five numbers, so the list lives here rather than in each caller:
+ * bytefly's footer accumulates them for the session and for its `↳` roll-up, and
+ * `subagent` accumulates them from a child's JSON events.
+ *
+ * `turns` and the context size are deliberately not counters — one is counted
+ * per message, the other is a window occupancy rather than something to sum — so
+ * each owner tracks those beside these.
+ */
+
+/** The counters, in the order a usage line prints them. */
+export const USAGE_COUNTERS = ["input", "output", "cacheRead", "cacheWrite", "cost"] as const;
+
+/** One counter in a usage accumulator. */
+export type UsageCounter = (typeof USAGE_COUNTERS)[number];
+
+/** A usage accumulator: one running total per counter. */
+export type UsageCounts = Record<UsageCounter, number>;
+
+/** A zeroed accumulator, ready to sum into. */
+export function zeroUsage(): UsageCounts {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+}