@gavin-hu/my-pi-agent 0.8.1 → 0.10.0

package/extensions/web-access/fetch/tool.ts

@@ -11,8 +11,9 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { formatTokens } from "../../../lib/format.ts";
-import { reuseText } from "../../../lib/tui.ts";
-import { SEPARATORS } from "../../../lib/ui.ts";
+import { reuseText } from "../../../lib/tui/chrome.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import { SEPARATORS } from "../../../lib/tui/glyphs.ts";
 import { charLength } from "../text.ts";
 import { oneLine } from "../transcript.ts";
 import { createPageCache, type PageCache } from "./cache.ts";
@@ -204,9 +205,9 @@ export function registerFetchTool(pi: ExtensionAPI, deps: FetchToolDeps = {}): v
 		renderCall(args, theme, context) {
 			const { url, find, startIndex } = args as WebFetchArgs;
 			const text = reuseText(context?.lastComponent);
-			let line = theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + theme.fg("accent", oneLine(url ?? ""));
-			if (find?.length) line += theme.fg("dim", ` find ${find.map((f) => `"${oneLine(f)}"`).join(", ")}`);
-			else if (startIndex) line += theme.fg("dim", ` (from ${startIndex})`);
+			let line = theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + paint(theme, "label", oneLine(url ?? ""));
+			if (find?.length) line += paint(theme, "faint", ` find ${find.map((f) => `"${oneLine(f)}"`).join(", ")}`);
+			else if (startIndex) line += paint(theme, "faint", ` (from ${startIndex})`);
 			text.setText(line);
 			return text;
 		},
@@ -216,21 +217,21 @@ export function registerFetchTool(pi: ExtensionAPI, deps: FetchToolDeps = {}): v
 			const page = result.details as FetchResponse | undefined;
 			if (page?.error) {
 				const message = oneLine(page.error);
-				text.setText(theme.fg("error", message.startsWith("Error:") ? message : `Error: ${message}`));
+				text.setText(paint(theme, "bad", message.startsWith("Error:") ? message : `Error: ${message}`));
 				return text;
 			}
 			if (!page || result.isError) {
 				const first = result.content[0];
 				const message = oneLine(first?.type === "text" ? first.text : "Fetch failed");
-				text.setText(theme.fg("error", message.startsWith("Error:") ? message : `Error: ${message}`));
+				text.setText(paint(theme, "bad", message.startsWith("Error:") ? message : `Error: ${message}`));
 				return text;
 			}
 
 			const label = oneLine(page.title || page.finalUrl);
-			let line = theme.fg("muted", label);
-			if (page.matches.length > 0) line += theme.fg("dim", `${SEPARATORS.item}${page.matches.length} match(es)`);
-			else line += theme.fg("dim", `${SEPARATORS.item}${formatTokens(page.totalChars)} chars`);
-			if (page.cached) line += theme.fg("dim", " (cached)");
+			let line = paint(theme, "meta", label);
+			if (page.matches.length > 0) line += paint(theme, "faint", `${SEPARATORS.item}${page.matches.length} match(es)`);
+			else line += paint(theme, "faint", `${SEPARATORS.item}${formatTokens(page.totalChars)} chars`);
+			if (page.cached) line += paint(theme, "faint", " (cached)");
 			text.setText(line);
 			return text;
 		},

package/extensions/web-access/search/tool.ts

@@ -10,8 +10,9 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadSearchConfig } from "../config.ts";
 import { oneLine } from "../transcript.ts";
-import { reuseText } from "../../../lib/tui.ts";
-import { expandHint, SEPARATORS } from "../../../lib/ui.ts";
+import { reuseText } from "../../../lib/tui/chrome.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import { expandHint, SEPARATORS } from "../../../lib/tui/glyphs.ts";
 import { formatResults } from "./format.ts";
 import { createThrottle, runSearch, type SearchDeps } from "./search.ts";
 import { resolveRequest, WebSearchOutput, WebSearchParams, type SearchResponse, type WebSearchArgs } from "./schema.ts";
@@ -68,8 +69,8 @@ export function registerSearchTool(pi: ExtensionAPI, deps: SearchDeps = {}): voi
 		renderCall(args, theme, context) {
 			const { query, maxResults } = args as WebSearchArgs;
 			const text = reuseText(context?.lastComponent);
-			let line = theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + theme.fg("accent", oneLine(query ?? ""));
-			if (maxResults) line += theme.fg("dim", ` (${maxResults} results)`);
+			let line = theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + paint(theme, "label", oneLine(query ?? ""));
+			if (maxResults) line += paint(theme, "faint", ` (max ${maxResults})`);
 			text.setText(line);
 			return text;
 		},
@@ -80,11 +81,11 @@ export function registerSearchTool(pi: ExtensionAPI, deps: SearchDeps = {}): voi
 			if (!details || result.isError) {
 				const first = result.content[0];
 				const message = first?.type === "text" ? first.text : "Search failed";
-				text.setText(theme.fg("error", `Error: ${oneLine(message)}`));
+				text.setText(paint(theme, "bad", `Error: ${oneLine(message)}`));
 				return text;
 			}
 			if (details.provider === "none") {
-				text.setText(theme.fg("dim", `No results for "${oneLine(details.query)}".`));
+				text.setText(paint(theme, "faint", `No results for "${oneLine(details.query)}".`));
 				return text;
 			}
 
@@ -92,19 +93,21 @@ export function registerSearchTool(pi: ExtensionAPI, deps: SearchDeps = {}): voi
 			// A blank line separates the call header from the result body.
 			const lines: string[] = [
 				"",
-				theme.fg("dim", `via ${details.provider}${SEPARATORS.item}${count} result${count === 1 ? "" : "s"}`),
+				paint(theme, "faint", `via ${details.provider}${SEPARATORS.item}${count} result${count === 1 ? "" : "s"}`),
 			];
-			if (details.answer) lines.push(`${theme.fg("dim", "answer")} ${theme.fg("muted", oneLine(details.answer, 160))}`);
+			if (details.answer)
+				lines.push(`${paint(theme, "faint", "Answer:")} ${paint(theme, "meta", oneLine(details.answer, 160))}`);
 
 			const shown = options.expanded ? details.results : details.results.slice(0, 5);
-			const indent = theme.fg("dim", "   ");
+			const indent = paint(theme, "faint", "   ");
 			for (const [index, item] of shown.entries()) {
-				lines.push(`${theme.fg("accent", `${index + 1}.`)} ${theme.fg("muted", oneLine(item.title, 100))}`);
-				lines.push(`${indent}${theme.fg("dim", oneLine(item.url, 100))}`);
-				if (options.expanded && item.snippet) lines.push(`${indent}${theme.fg("muted", oneLine(item.snippet, 160))}`);
+				lines.push(`${paint(theme, "accent", `${index + 1}.`)} ${paint(theme, "meta", oneLine(item.title, 100))}`);
+				lines.push(`${indent}${paint(theme, "faint", oneLine(item.url, 100))}`);
+				if (options.expanded && item.snippet)
+					lines.push(`${indent}${paint(theme, "meta", oneLine(item.snippet, 160))}`);
 			}
 			const extra = count - shown.length;
-			if (extra > 0) lines.push(`${theme.fg("dim", `+${extra} more`)} ${expandHint(theme)}`);
+			if (extra > 0) lines.push(`${paint(theme, "faint", `+${extra} more`)} ${expandHint(theme)}`);
 			text.setText(lines.join("\n"));
 			return text;
 		},

package/extensions/wechat/README.md

@@ -11,6 +11,12 @@ pi -e .                              # load the whole @gavin-hu/my-pi-agent pack
 pi install ./                        # install the package
 ```
 
+## Tool rendering
+
+How the `send_wechat` call and its result look in the transcript — the call line as a headline and the body indented under it:
+
+<img src="../../assets/tools/send_wechat.png" alt="The send_wechat tool's call and result: the call line and an indented body with the message text and the sent confirmation" width="100%">
+
 ## What it does
 
 - **Inbound** — a long-poll loop receives WeChat text, images, and files and
@@ -252,8 +258,8 @@ status, which is what the old start/stop guidance used to do.
 | `outbound.ts` | Upload and send a local file: hash, encrypt, `getUploadUrl`, upload, `sendFileMessage`. |
 | `login.ts` | QR login state machine. |
 | `qrcode.ts` | QR matrix → Unicode half-block terminal lines. |
-| `login-screen.ts` | The `/wechat login` screen (`ctx.ui.custom`). |
-| `status-screen.ts` | The `/wechat` control screen (`ctx.ui.custom`) and the pure one-line/body renderers. |
+| `login-screen.ts` | The `/wechat login` screen (`ctx.ui.custom`), drawn from the `lib/tui/` kit (`titleRule`, `clip`, `isCloseKey`). |
+| `status-screen.ts` | The `/wechat` control screen (`ctx.ui.custom`) and the pure one-line/body renderers, drawn from the `lib/tui/` kit (`titleRule`, `keyValueRow`, `paint`). |
 | `config.ts` | The `wechat` section of `bytefly.json` loading and normalization. |
 | `credentials.ts` | `credentials.json` (`0600`, multi-account). |
 | `state.ts` | `state.json` (cursor, owner, per-peer tokens). |

package/extensions/wechat/index.ts

@@ -14,7 +14,8 @@
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { join } from "node:path";
 import { isExtensionEnabled } from "../../lib/env.ts";
-import { GLYPHS, STATUS_KEYS } from "../../lib/ui.ts";
+import { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
+import { paint } from "../../lib/tui/tokens.ts";
 import { createBridge, type Bridge, type BridgeState } from "./bridge.ts";
 import { createFetchRunner, WechatClient } from "./client.ts";
 import { registerCommands, type CommandDeps } from "./commands.ts";
@@ -34,9 +35,9 @@ import { registerTools } from "./tools.ts";
 export function wechatChip(theme: Theme, state: BridgeState): string | undefined {
 	switch (state) {
 		case "running":
-			return theme.fg("success", `${GLYPHS.wechat} wechat`);
+			return paint(theme, "ok", `${GLYPHS.wechat} wechat`);
 		case "expired":
-			return theme.fg("error", `${GLYPHS.wechat} wechat expired`);
+			return paint(theme, "bad", `${GLYPHS.wechat} wechat expired`);
 		case "stopped":
 			return undefined;
 	}

package/extensions/wechat/login-screen.ts

@@ -7,8 +7,11 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { Key, matchesKey, type Component, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { screenHeader, screenHint } from "../../lib/tui.ts";
+import { type Component, visibleWidth } from "@earendil-works/pi-tui";
+import { screenHint } from "../../lib/tui/chrome.ts";
+import { clip } from "../../lib/tui/columns.ts";
+import { isCloseKey } from "../../lib/tui/cursor.ts";
+import { titleRule } from "../../lib/tui/rules.ts";
 
 export interface LoginViewState {
 	/** Raw `get_qrcode_status` value, or `wait` before the first poll. */
@@ -51,7 +54,7 @@ export function loginBody(state: LoginViewState, width: number): string[] {
 			lines.push(state.url.slice(index, index + target));
 		}
 	}
-	return lines.map((line) => truncateToWidth(line, target));
+	return lines.map((line) => clip(line, target));
 }
 
 export interface LoginScreenOptions {
@@ -69,7 +72,7 @@ export class LoginScreenComponent implements Component {
 	constructor(private readonly options: LoginScreenOptions) {}
 
 	handleInput(data: string): void {
-		if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+		if (isCloseKey(data)) {
 			this.options.onCancel();
 		}
 	}
@@ -81,7 +84,7 @@ export class LoginScreenComponent implements Component {
 		const target = Math.max(1, width);
 		const theme = this.options.theme;
 		return [
-			screenHeader(theme, target, "wechat · login"),
+			titleRule(theme, target, "wechat · login"),
 			"",
 			...loginBody(this.options.state(), target),
 			"",

package/extensions/wechat/status-screen.ts

@@ -10,8 +10,13 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { Key, matchesKey, truncateToWidth, type Component } from "@earendil-works/pi-tui";
-import { screenHeader, screenHint, type ScreenHint } from "../../lib/tui.ts";
+import type { Component } from "@earendil-works/pi-tui";
+import { screenHint, type ScreenHint } from "../../lib/tui/chrome.ts";
+import { clip } from "../../lib/tui/columns.ts";
+import { isCloseKey } from "../../lib/tui/cursor.ts";
+import { keyValueRow } from "../../lib/tui/rows.ts";
+import { titleRule } from "../../lib/tui/rules.ts";
+import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import type { BridgeStatus } from "./bridge.ts";
 import { peerLabel } from "./format.ts";
 import type { BotCredentials } from "./types.ts";
@@ -72,18 +77,32 @@ export function statusLine(view: StatusView): string {
 /** Label column width in the screen body. */
 const LABEL_WIDTH = 11;
 
-function row(theme: Theme, label: string, value: string): string {
-	return `  ${theme.fg("muted", label.padEnd(LABEL_WIDTH))}${value}`;
+/** One body row: a `meta` label column and a value in `valueRole`. */
+function row(theme: Theme, width: number, label: string, value: string, valueRole: TuiRole = "label"): string {
+	return keyValueRow(theme, width, { label, value, labelWidth: LABEL_WIDTH, labelRole: "meta", valueRole });
 }
 
-function connectionText(theme: Theme, connection: StatusConnection): string {
+/** The connection word, uncolored; {@link row} paints it. */
+function connectionText(connection: StatusConnection): string {
 	switch (connection) {
 		case "open":
-			return theme.fg("success", "open");
+			return "open";
 		case "expired":
-			return theme.fg("error", "expired");
+			return "expired";
 		case "closed":
-			return theme.fg("muted", "closed");
+			return "closed";
+	}
+}
+
+/** The design role the connection word is drawn in. */
+function connectionRole(connection: StatusConnection): TuiRole {
+	switch (connection) {
+		case "open":
+			return "ok";
+		case "expired":
+			return "bad";
+		case "closed":
+			return "meta";
 	}
 }
 
@@ -91,28 +110,28 @@ function connectionText(theme: Theme, connection: StatusConnection): string {
 export function statusBody(view: StatusView, theme: Theme, width: number): string[] {
 	const target = Math.max(1, width);
 	const lines = [
-		row(theme, "Account", view.account ?? theme.fg("muted", "not logged in")),
-		row(theme, "Connection", connectionText(theme, view.connection)),
+		row(theme, target, "Account", view.account ?? "not logged in", view.account ? "label" : "meta"),
+		row(theme, target, "Connection", connectionText(view.connection), connectionRole(view.connection)),
 	];
 	if (view.bridge) {
-		if (view.owner && view.owner !== view.account) lines.push(row(theme, "Owner", view.owner));
-		lines.push(row(theme, "Peers", String(view.peers)));
-		lines.push(row(theme, "Queued", String(view.queued)));
-		if (view.refused > 0) lines.push(row(theme, "Refused", String(view.refused)));
-		if (view.mediaDropped > 0) lines.push(row(theme, "Media", `${view.mediaDropped} dropped`));
-		if (view.promptPending) lines.push(row(theme, "Prompt", theme.fg("accent", "waiting for a reply")));
+		if (view.owner && view.owner !== view.account) lines.push(row(theme, target, "Owner", view.owner));
+		lines.push(row(theme, target, "Peers", String(view.peers), "meta"));
+		lines.push(row(theme, target, "Queued", String(view.queued), "meta"));
+		if (view.refused > 0) lines.push(row(theme, target, "Refused", String(view.refused), "meta"));
+		if (view.mediaDropped > 0) lines.push(row(theme, target, "Media", `${view.mediaDropped} dropped`, "meta"));
+		if (view.promptPending) lines.push(row(theme, target, "Prompt", "waiting for a reply", "accent"));
 	}
 	if (view.connection === "expired") {
 		lines.push("");
-		lines.push(`  ${theme.fg("error", "Session expired — press l to log in again.")}`);
+		lines.push(clip(`  ${paint(theme, "bad", "Session expired — press l to log in again.")}`, target));
 	} else if (view.connection === "closed" && view.account) {
 		lines.push("");
-		lines.push(`  ${theme.fg("muted", "Not connected — press l to log in again.")}`);
+		lines.push(clip(`  ${paint(theme, "meta", "Not connected — press l to log in again.")}`, target));
 	} else if (view.connection === "closed") {
 		lines.push("");
-		lines.push(`  ${theme.fg("muted", "Run /wechat login to connect an account.")}`);
+		lines.push(clip(`  ${paint(theme, "meta", "Run /wechat login to connect an account.")}`, target));
 	}
-	return lines.map((line) => truncateToWidth(line, target));
+	return lines;
 }
 
 export interface StatusScreenOptions {
@@ -140,7 +159,7 @@ export class StatusScreenComponent implements Component {
 	}
 
 	handleInput(data: string): void {
-		if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+		if (isCloseKey(data)) {
 			this.options.onClose("close");
 			return;
 		}
@@ -166,7 +185,7 @@ export class StatusScreenComponent implements Component {
 		const target = Math.max(1, width);
 		const theme = this.options.theme;
 		return [
-			screenHeader(theme, target, "wechat · control"),
+			titleRule(theme, target, "wechat · control"),
 			"",
 			...statusBody(this.options.view(), theme, target),
 			"",

package/extensions/wechat/tools.ts

@@ -11,7 +11,8 @@ import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import { sanitizeLine } from "../../lib/format.ts";
-import { reuseText, toolDetails } from "../../lib/tui.ts";
+import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import { paint } from "../../lib/tui/tokens.ts";
 import type { Bridge } from "./bridge.ts";
 
 export const TOOL_NAME = "send_wechat";
@@ -85,7 +86,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolDeps): void {
 			const text = reuseText(context.lastComponent);
 			const body = (args as { text?: unknown }).text;
 			const label = context.argsComplete && typeof body === "string" ? sanitizeLine(body) : "…";
-			text.setText(theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + theme.fg("muted", label));
+			text.setText(theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + paint(theme, "meta", label));
 			return text;
 		},
 
@@ -93,16 +94,16 @@ export function registerTools(pi: ExtensionAPI, deps: ToolDeps): void {
 			const text = reuseText(context.lastComponent);
 			const details = toolDetails<{ sent?: boolean; error?: string }>(result.details);
 			if (details?.sent) {
-				text.setText(theme.fg("success", "sent to WeChat owner"));
+				text.setText(paint(theme, "ok", "sent to WeChat owner"));
 				return text;
 			}
 			if (details?.error) {
-				text.setText(theme.fg("error", `Error: ${sanitizeLine(details.error)}`));
+				text.setText(paint(theme, "bad", `Error: ${sanitizeLine(details.error)}`));
 				return text;
 			}
 			// Pi's rejection result carries `{}`; show its message instead.
 			const first = result.content[0];
-			text.setText(first?.type === "text" ? first.text : theme.fg("error", "Error: send failed"));
+			text.setText(first?.type === "text" ? first.text : paint(theme, "bad", "Error: send failed"));
 			return text;
 		},
 	});

package/extensions/worktree/README.md

@@ -14,6 +14,12 @@ pi install ./                          # install the package
 pi -e . --worktree feature-auth        # load the package and enter a worktree at startup
 ```
 
+## Tool rendering
+
+How the `list_worktrees` call and its result look in the transcript — the call line as a headline and the body indented under it:
+
+<img src="../../assets/tools/list_worktrees.png" alt="The list_worktrees tool's call and result, drawn by the generic fallback" width="100%">
+
 ## What it does
 
 - `enter_worktree` creates `<repo>/.pi/worktrees/<name>` on branch

package/extensions/worktree/enter.ts

@@ -7,7 +7,7 @@ import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isInside } from "../../lib/path.ts";
-import { GLYPHS } from "../../lib/ui.ts";
+import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import { loadConfig, type WorktreeConfig } from "./config.ts";
 import { WorktreeCancelledError } from "./errors.ts";
 import {

package/extensions/worktree/index.ts

@@ -24,7 +24,7 @@ import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
-import { GLYPHS } from "../../lib/ui.ts";
+import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import { canonicalize, checkCheckout, repoRoot, unlockWorktree } from "./git.ts";
 import { analyzeBashCommand, guardFileTool } from "./guard.ts";
 import {

package/extensions/worktree/runtime.ts

@@ -8,7 +8,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { STATUS_KEYS } from "../../lib/ui.ts";
+import { STATUS_KEYS } from "../../lib/tui/glyphs.ts";
 import { ENV_ROOT } from "../../lib/env.ts";
 import { loadConfig, type WorktreeConfig } from "./config.ts";
 import type { WorktreeState } from "./state.ts";

package/lib/README.md

@@ -20,11 +20,12 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | [`env.ts`](./env.ts) | Env-var contracts shared across extensions: the worktree environment (`ENV_ROOT`, `worktreeRoot`, `resolveEffectiveCwd`) used by worktree, file-browse, job, and rewind, plus `isExtensionEnabled` / `ENV_DISABLED_EXTENSIONS` for the package-wide disable list. |
 | [`escape.ts`](./escape.ts) | `escapeHtml`: the single HTML text/attribute escape used by the browse page renderers and the Markdown and syntax highlighters. |
 | [`events.ts`](./events.ts) | Inter-extension `pi.events` channels and payloads: `JOB_FINISHED_CHANNEL` and `JobFinishedEvent`, published by `job` and consumed by bytefly's notify capability. |
+| [`notice.ts`](./notice.ts) | The shared transcript notice: `NOTICE_TYPE`, the `NoticeDetails` / `NoticeItem` shape, `noticeMessage` (the `display: true` message both send paths accept), `isNotice`, and `pruneStaleNotices` — posted by `job` and `watch`, rendered by bytefly. |
 | [`format.ts`](./format.ts) | Pure text/number formatting shared by renderers: `formatTokens`, `stripControlChars`, `sanitize`, `sanitizeLine` — the boundary for untrusted, single-line text — and `shortenPath`. |
 | [`interaction.ts`](./interaction.ts) | Turn-affinity prompt contract: the channel a remote adapter installs on `ctx.ui` under a string key, the `InteractionChannel` interface (`request` / `post` / `postFile`), and `remoteChannel` / `isRemoteTurn` / `supportsCustomUI` / `askHuman` (with an optional file/text preface) plus the shared “Other” label. |
 | [`git/`](./git/) | Shared git plumbing. [`git/runner.ts`](./git/runner.ts) is the `RunGit` seam (`createExecRunner` with timeout/env handling, `runGitOrThrow`, `GitError`); [`git/read.ts`](./git/read.ts) holds the read helpers (`repoRoot`, `repoRootFor`, `gitDir`, `revParse`, `hasCommits`, `currentBranch`); [`git/index.ts`](./git/index.ts) is the barrel. |
 | [`highlight.ts`](./highlight.ts) | First-party, escape-first syntax tokenizer (`detectLanguage`, `fenceLanguage`, `highlightLines`, `HighlightLanguage`, `TokenClass`) for js/ts, json, css, html, shell, python, java, yaml, and sql; shared by `file-browse` and plan's code blocks. |
-| [`list-cursor.ts`](./list-cursor.ts) | Scrollable-list behavior for the `/rewind`, `/bytefly`, `/todos`, and `/jobs` screens: `fitRows`, `keepVisible`, `clampScroll`, `navIntent`, `navigateList`, `navigateScroll`, `wheelDelta`, `scrollList`, `isCloseKey`, `selectionMarker`, `formatRange`, and the `ListCursor` state. |
+| [`tui/`](./tui/) | The Bytefly terminal design system shared by every interactive surface: [`tui/tokens.ts`](./tui/tokens.ts) (semantic role -> theme color, `paint`), [`tui/glyphs.ts`](./tui/glyphs.ts) (`GLYPHS`, `SEPARATORS`, `STATUS_KEYS`, `EXPAND_KEYBINDING` with `expandKey` / `expandHint`, `GLYPH_GAP` — the vocabulary both sides of a status must agree on), [`tui/chrome.ts`](./tui/chrome.ts) (`screenHint`, `dockListFrame` (the docked-list frame), `viewportRows`, `FULL_SCREEN_OVERLAY`, `reuseText`, `editorTheme`), [`tui/rules.ts`](./tui/rules.ts) (the rule glyph `RULE_GLYPH`, and `plainRule` / `titleRule` / `centeredRule`), [`tui/indent.ts`](./tui/indent.ts) (the transcript block indent: `BODY_INDENT`, an optional rail prefix that a wrapped call line is kept out of, and `bodyLines` / `indentBlockLines` / `indentedLines`), [`tui/rows.ts`](./tui/rows.ts) (`listRow`, `checkbox`, `chip`, `keyValueRow`, `emptyState`), [`tui/columns.ts`](./tui/columns.ts) (`splitRow`, `fitCells`, `flowCells`, `padTo`, `clip`), [`tui/gauge.ts`](./tui/gauge.ts) (`computeGauge`, `gaugeRole`, `gaugeBar`), [`tui/line-pane.ts`](./tui/line-pane.ts) (`LinePane`, the scrollable log/match pane), [`tui/status-controller.ts`](./tui/status-controller.ts) (`createStatusController`, the footer chips `job` and `watch` share), and [`tui/cursor.ts`](./tui/cursor.ts) (scroll and navigation: `fitRows`, `keepVisible`, `clampScroll`, `navIntent`, `navigateList`, `navigateScroll`, `wheelDelta`, `scrollList`, `isCloseKey`, `selectionMarker`, `formatRange`, and the `ListCursor` (by index) and `IdCursor` (by stable id) state). |
 | [`path.ts`](./path.ts) | `isInside` (string containment) plus `realPathOfNearest` / `isInsideReal` (symlink-aware): the containment predicates the file-browse, worktree, and doc guards share. |
 | [`pi-invocation.ts`](./pi-invocation.ts) | `getPiInvocation`: how to launch a nested `pi` process, shared by `subagent` and bytefly's doctor surface. |
 | [`policy.ts`](./policy.ts) | `createReadOnlyPolicy`: default-deny tool classification from `readOnlyHint` + explicit allow/deny. |
@@ -32,8 +33,6 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | [`requirements.ts`](./requirements.ts) | Per-extension runtime prerequisite table plus a pure `probeExtension(seams)` over injected seams (exec, config reads, optional imports): bytefly's doctor surface reports on it and the extensions that own a dependency format their errors from it. |
 | [`shell.ts`](./shell.ts) | Shell escape rule shared by the worktree isolation guard and plan mode's read-only git guard: `SHELL_ESCAPABLE`, `isShellEscapable`, `hasShellEscape`. |
 | [`tool-names.ts`](./tool-names.ts) | Tool names and one parameter name that more than one extension must agree on, so an orchestrating `ctx.executeTool()` call or schema probe breaks the build on a rename. |
-| [`tui.ts`](./tui.ts) | Screen chrome: `screenHeader`, `screenHint`, `dockListFrame` (the shared docked-list assembly), `viewportRows`, and `FULL_SCREEN_OVERLAY`, plus `reuseText` (per-render `Text` reuse) and `editorTheme` (inline-editor theme). |
-| [`ui.ts`](./ui.ts) | Shared UI vocabulary: `GLYPHS`, `SEPARATORS`, `STATUS_KEYS` (`ctx.ui.setStatus` keys), `EXPAND_KEYBINDING` with `expandKey` / `expandHint`, and the transcript rail `BODY_INDENT` / `GLYPH_GAP`. |
 | [`web/`](./web/) | The Bytefly web brand system shared by the browser surfaces: [`web/tokens.ts`](./web/tokens.ts) (palette derived from the Bytefly terminal themes, scales, and the `tok-*` map), [`web/base.ts`](./web/base.ts), [`web/components.ts`](./web/components.ts), [`web/layout.ts`](./web/layout.ts), [`web/runtime.ts`](./web/runtime.ts) (`WEB_THEME_STORAGE_KEY`, `THEME_JS`, `THEME_TOGGLE_JS`), [`web/markup.ts`](./web/markup.ts), and the [`web/index.ts`](./web/index.ts) barrel. |
 
 ## Conventions
@@ -43,7 +42,12 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 - **Inject the host seam.** Modules that need a host capability take a function
   (`RunGit`, `HttpRunner`) rather than the whole `ExtensionAPI`, so the logic is
   testable without a runtime.
-- **Constants that must agree across both sides live in `ui.ts`** — a glyph and
-  the `setStatus` key are one contract, not two literals. Tool names shared by
-  an orchestrating tool and the tool it calls — and parameter names one
-  extension probes on another — live in `tool-names.ts`.
+- **Constants that must agree across both sides live in `tui/glyphs.ts`** — a
+  glyph and the `setStatus` key are one contract, not two literals. Tool names
+  shared by an orchestrating tool and the tool it calls — and parameter names
+  one extension probes on another — live in `tool-names.ts`.
+- **A color is a role, not a token.** Draw through [`tui/tokens.ts`](./tui/tokens.ts)
+  (`paint(theme, role, text)`) so a theme swap re-skins every surface; the
+  primitives in `tui/` already do, and a new one should too. The one exception is
+  Pi's tool-rendering vocabulary (`toolOutput`, `toolTitle`), which stays direct:
+  those tokens style a tool block, and no role maps to them.

package/lib/format.ts

@@ -17,6 +17,23 @@ export function formatTokens(count: number): string {
 	return `${Math.round(count / 1000000)}M`;
 }
 
+/**
+ * An integer grouped with thousands separators (`999`, `8,000`, `42,478`).
+ * Hand-rolled rather than `toLocaleString`, so a count is identical under any
+ * locale and ICU build.
+ */
+export function formatCount(count: number): string {
+	if (!Number.isFinite(count)) return "0";
+	const sign = count < 0 ? "-" : "";
+	const digits = Math.abs(Math.trunc(count)).toString();
+	let out = "";
+	for (let i = 0; i < digits.length; i++) {
+		if (i > 0 && (digits.length - i) % 3 === 0) out += ",";
+		out += digits[i];
+	}
+	return sign + out;
+}
+
 /**
  * Replace terminal control characters (including ESC and the C1 block) with
  * spaces, keeping `\n` and `\t` for callers that render multi-line text.

package/lib/notice.ts

@@ -0,0 +1,87 @@
+/**
+ * The shared transcript notice: one custom-message type that any extension in
+ * the package can post, plus the model-facing content and the renderer-facing
+ * details it carries.
+ *
+ * Pi renders a custom message only when it was sent with `display: true`, and
+ * it resolves a renderer by the exact `customType` — there is no wildcard — so
+ * the type and the shape behind it are one contract the producing extension and
+ * bytefly's renderer must agree on. Keep both here, never re-typed on either
+ * side.
+ *
+ * `content` is what the model reads; `details` is never sent to the model and
+ * is the renderer's whole input, so a producer states the facts once and the
+ * renderer decides the look. Value-only: constants and pure functions, no
+ * state.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+/** The custom-message type every transcript notice is sent under. */
+export const NOTICE_TYPE = "my-pi-agent/notice";
+
+/** How a notice, or one of its rows, reads at a glance. */
+export type NoticeSeverity = "info" | "ok" | "warn" | "bad";
+
+/** One row under a notice's headline. */
+export interface NoticeItem {
+	/** The row's text, e.g. `j1 build`. Sanitized by the renderer. */
+	label: string;
+	/** Short trailing detail, e.g. `exit 1`. Sanitized by the renderer. */
+	detail?: string;
+	/** The row's severity; falls back to the notice's own. */
+	severity?: NoticeSeverity;
+}
+
+/** Everything the renderer draws, and nothing the model sees. */
+export interface NoticeDetails {
+	/** Who raised it, e.g. `job` or `watch`. */
+	source: string;
+	/** One-line headline. */
+	title: string;
+	/** The headline's severity; a row may override it. */
+	severity?: NoticeSeverity;
+	/** Rows under the headline, in order. */
+	items?: readonly NoticeItem[];
+}
+
+export interface NoticeInput {
+	/** Model-facing text; the notice is also shown when non-empty. */
+	content: string;
+	/** Renderer-facing structure. */
+	details: NoticeDetails;
+}
+
+/** The message shape both send paths accept (`pi.sendMessage`, `before_agent_start`). */
+export interface NoticeMessage {
+	customType: string;
+	content: string;
+	display: true;
+	details: NoticeDetails;
+}
+
+/** A conversation message narrowed to a notice. */
+export type NoticeEntry = AgentMessage & { customType: string; details?: NoticeDetails };
+
+/** Build a visible notice message: shared type, `display: true`, the given content and details. */
+export function noticeMessage(input: NoticeInput): NoticeMessage {
+	return { customType: NOTICE_TYPE, content: input.content, display: true, details: input.details };
+}
+
+/** Whether a conversation message is a notice. */
+export function isNotice(message: AgentMessage): message is NoticeEntry {
+	return message.role === "custom" && (message as { customType?: string }).customType === NOTICE_TYPE;
+}
+
+/**
+ * Keep only the newest notice of `source` in a transcript, so stale injected
+ * context does not accumulate. Notices of other sources and every non-notice
+ * are left alone. Returns `undefined` when nothing is stale, so a `context`
+ * handler can leave the messages untouched.
+ */
+export function pruneStaleNotices(messages: readonly AgentMessage[], source: string): AgentMessage[] | undefined {
+	const ofSource = messages.filter((message) => isNotice(message) && message.details?.source === source);
+	if (ofSource.length <= 1) return undefined;
+	const keep = ofSource[ofSource.length - 1];
+	return messages.filter((message) => !(isNotice(message) && message.details?.source === source && message !== keep));
+}

package/lib/requirements.ts

@@ -166,7 +166,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 		optional: [{ kind: "module", name: "unpdf", enables: "PDF text extraction in `web_fetch`", hint: pdfGuidance() }],
 	},
 	"file-browse": {
-		optional: [gitCheck("the branch chip")],
+		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: {},
@@ -194,7 +194,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	bytefly: {
 		configFiles: [SHARED_CONFIG_FILE],
 		notes: [
-			"TUI only for the header, footer, and turn rule; `/bytefly` (and the `/extensions` and `/doctor` aliases) prints a listing and report in RPC, JSON, and print modes.",
+			"TUI only for the header, footer, and turn rule; `/bytefly` prints a listing and `/bytefly doctor` the report in RPC, JSON, and print modes.",
 			"The panel writes extension enablement through Pi's own settings; project scope requires a trusted project.",
 			"`/bytefly`'s list screen and the proactive missing-prerequisite warning need an interactive UI.",
 		],