@gavin-hu/my-pi-agent 0.9.0 → 0.11.0

package/extensions/todo/README.md

@@ -8,12 +8,20 @@ about to end after mutating work without a todo update, the extension injects
 one short reminder and forces a continuation, so the list does not silently
 drift behind the work.
 
+<img src="../../assets/todo.png" alt="The /todos screen: a Todos title rule, a 3/7 completed summary, and the list with check, spinner, and circle glyphs" width="100%">
+
 ```
 pi --extension ./extensions/todo    # load just this extension
 pi -e .                             # load the whole @gavin-hu/my-pi-agent package
 pi install ./                       # install the package
 ```
 
+## Tool rendering
+
+How the `todo` call and its result look in the transcript — the call line as a headline and the body indented under it:
+
+<img src="../../assets/tools/todo.png" alt="The todo tool's result: the call line and an indented body with the progress line and the task rows below it, each led by a check, spinner, or circle glyph" width="100%">
+
 ## What it does
 
 - Registers one model-callable tool, `todo`, that **replaces** the task list.
@@ -49,22 +57,20 @@ Todos · 1/3 · Writing the tests
 `/todos` is the expanded view and keeps the model's list order (use it to see
 the plan as written).
 
-In the transcript, the call line pairs progress with the active item
-(`todo → 1/4 · Writing tests`), and the result keeps the shared
-`✓` / `◒` / `◌` rail used by the goal result, separated from the call line by a
-blank line. Collapsed, it leads with active work; expanded, it keeps the
-submitted order:
+In the transcript, the call line carries progress only (`todo → 1/4`); the
+result keeps the `✓` / `◒` / `◌` rows, directly under the call line. The item
+text lives on the rows, so the call line never repeats it. Collapsed, it leads
+with active work; expanded, it keeps the submitted order:
 
 ```
-todo → 1/4 · Writing tests
-
+todo → 1/4
   ◒ Writing tests
   ◌ Ship it
   ◌ Write docs
   ✓ Write schema
 ```
 
-Progress lives on the call line, so the rail has no footer; the persistent
+Progress lives on the call line, so the rows have no footer; the persistent
 widget and `/todos` still show the count. A capped collapsed rail ends with
 `… N more` and the `app.tools.expand` hint.
 
@@ -204,10 +210,11 @@ depends on config.
   widget is a single line (`currentTodo` picks the `in_progress` item, else the
   first pending); `/todos` keeps the submitted order, and the transcript result
   orders by status via `compareByActivity` so active work is never hidden. The
-  transcript result draws the same indented glyph rail as the goal result
-  (`BODY_INDENT` / `GLYPH_GAP` from [`lib/tui/glyphs.ts`](../../lib/tui/glyphs.ts)), wrapping
-  long items with continuation rows aligned under the text. Progress lives on
-  the call line, so the rail carries no footer.
+  transcript result draws the glyph rows at the block's body indent (the frame
+  supplies `BODY_INDENT`; `GLYPH_GAP` comes from
+  [`lib/tui/glyphs.ts`](../../lib/tui/glyphs.ts)), wrapping long items with
+  continuation rows aligned under the text. Progress lives on the call line, so
+  the rows carry no footer.
 - **The transcript reuses its components.** `renderCall` reuses the slot's
   `Text`, and `renderResult` reuses the `TodoResult` view via
   `context.lastComponent`, updating each in place instead of allocating on every

package/extensions/todo/format.ts

@@ -3,8 +3,8 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { sliceByColumn, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-import { BODY_INDENT, expandHint, GLYPH_GAP, GLYPHS } from "../../lib/tui/glyphs.ts";
+import { truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { expandHint, GLYPH_GAP, GLYPHS } from "../../lib/tui/glyphs.ts";
 import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import { completedCount, currentTodo } from "./state.ts";
 import type { Todo, TodoStatus } from "./types.ts";
@@ -17,9 +17,6 @@ export function compareByActivity(a: Todo, b: Todo): number {
 	return STATUS_ORDER[a.status] - STATUS_ORDER[b.status];
 }
 
-/** Longest first-item preview shown in the transcript call line. */
-const CALL_PREVIEW_WIDTH = 40;
-
 /** Plain status glyph per status; `todoGlyph` adds the theme color. */
 const STATUS_GLYPH: Record<TodoStatus, string> = {
 	pending: GLYPHS.pending,
@@ -107,22 +104,16 @@ export function formatTodoText(todos: Todo[]): string {
  * One-line body for the transcript call renderer.
  *
  * The renderer owns the styled `todo ` title, so this returns only the body.
- * `todos` is `undefined` while the call's arguments are still streaming, which
- * is distinct from an empty list (a real clear). `argsComplete` disambiguates
- * the tail end of the stream.
+ * Progress is the summary; the result rail lists the items (active work first),
+ * so the call line does not repeat the current item. `todos` is `undefined`
+ * while the call's arguments are still streaming, which is distinct from an
+ * empty list (a real clear). `argsComplete` disambiguates the tail end of the
+ * stream.
  */
 export function formatCallText(todos: Todo[] | undefined, argsComplete = true): string {
 	if (todos === undefined) return argsComplete ? "→ clear list" : "→ …";
 	if (todos.length === 0) return "→ clear list";
-
-	const current = currentTodo(todos);
-	const label = current ? (current.activeForm ?? current.content).trim() : "completed";
-	if (!label) return argsComplete ? `→ ${progressCount(todos)} · …` : "→ …";
-	// `strict` drops a wide grapheme that would cross the boundary, so the slice
-	// plus ellipsis never exceeds `CALL_PREVIEW_WIDTH` columns.
-	const preview =
-		visibleWidth(label) > CALL_PREVIEW_WIDTH ? `${sliceByColumn(label, 0, CALL_PREVIEW_WIDTH - 1, true)}…` : label;
-	return `→ ${progressCount(todos)} · ${preview}`;
+	return `→ ${progressCount(todos)}`;
 }
 
 /** Rows and footer for the transcript result rail. */
@@ -134,18 +125,19 @@ export interface TodoRailInput {
 }
 
 /**
- * Transcript result rail: each row is indented by `BODY_INDENT`, led by its
- * status glyph, and its label wrapped with continuation rows aligned under the
- * text. A trailing `… N more` follows when rows were capped. Progress lives on
- * the call line, so the rail carries no footer. Every line is clipped to
- * `width`.
+ * Transcript result rail: each row is led by its status glyph, and its label
+ * wrapped with continuation rows aligned under the text. A trailing `… N more`
+ * follows when rows were capped. Progress lives on the call line, so the rail
+ * carries no footer. Every line is clipped to `width`.
+ *
+ * The rail draws at its own left edge; the tool-block frame supplies
+ * `BODY_INDENT`, so the rail must not add it again.
  */
 export function todoRailLines(input: TodoRailInput, theme: Theme, width: number): string[] {
 	const w = Math.max(1, width);
 	// All three status glyphs are single-column, so the text column is fixed.
-	const textColumn = BODY_INDENT + 1 + GLYPH_GAP;
+	const textColumn = 1 + GLYPH_GAP;
 	const inner = Math.max(1, w - textColumn);
-	const pad = " ".repeat(BODY_INDENT);
 	const gap = " ".repeat(GLYPH_GAP);
 	const continuation = " ".repeat(textColumn);
 	const lines: string[] = [];
@@ -153,7 +145,7 @@ export function todoRailLines(input: TodoRailInput, theme: Theme, width: number)
 		const glyph = todoGlyph(todo, theme);
 		const wrapped = wrapTextWithAnsi(todoLabel(todo, theme), inner);
 		wrapped.forEach((line, index) => {
-			lines.push(index === 0 ? `${pad}${glyph}${gap}${line}` : `${continuation}${line}`);
+			lines.push(index === 0 ? `${glyph}${gap}${line}` : `${continuation}${line}`);
 		});
 	}
 	if (input.more && input.more > 0) {

package/extensions/todo/tools.ts

@@ -14,6 +14,7 @@ import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { sanitizeLine } from "../../lib/format.ts";
 import { TODO_TOOL } from "../../lib/tool-names.ts";
+import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { compareByActivity, formatCallText, formatTodoText, type TodoRailInput } from "./format.ts";
@@ -118,7 +119,7 @@ export function registerTools(pi: ExtensionAPI, runtime: TodoRuntime): void {
 				return text;
 			}
 			if (details.todos.length === 0) {
-				text.setText(paint(theme, "ok", "✓ ") + paint(theme, "meta", "Cleared the todo list"));
+				text.setText(paint(theme, "ok", `${GLYPHS.check} `) + paint(theme, "meta", "Cleared the todo list"));
 				return text;
 			}
 

package/extensions/todo/tui.ts

@@ -12,6 +12,7 @@ import { clampScroll, fitRows, formatRange, isCloseKey, navigateScroll, wheelDel
 import { dockListFrame, screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
 import { clip } from "../../lib/tui/columns.ts";
 import { emptyState, listRow } from "../../lib/tui/rows.ts";
+import { SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { titleRule } from "../../lib/tui/rules.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import {
@@ -50,10 +51,10 @@ function todoRow(todo: Todo, theme: Theme, width: number): string {
  * `jobs` widgets. Callers clip it to the available width.
  */
 function todoLine(todos: Todo[], theme: Theme): string {
-	const head = `${paint(theme, "accent", "Todos")} ${paint(theme, "faint", "·")} ${paint(theme, "faint", progressCount(todos))}`;
+	const head = `${paint(theme, "accent", "Todos")}${paint(theme, "faint", SEPARATORS.item)}${paint(theme, "faint", progressCount(todos))}`;
 	const current = currentTodo(todos);
 	if (!current) return `${head} ${paint(theme, "faint", "completed")}`;
-	return `${head} ${paint(theme, "faint", "·")} ${todoLabel(current, theme)}`;
+	return `${head}${paint(theme, "faint", SEPARATORS.item)}${todoLabel(current, theme)}`;
 }
 
 /** Transcript result block: the indented glyph rail, wrapping at the render width. */

package/extensions/watch/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 `watch` call and its result look in the transcript — the call line as a headline and the body indented under it:
+
+<img src="../../assets/tools/watch.png" alt="The watch tool's result: the call line and an indented body with a running file watcher and an exited command watcher" width="100%">
+
 ## What it does
 
 - Registers one model-callable tool, `watch`, with actions `add`, `list`,
@@ -85,9 +91,11 @@ and the command's `pid`/`exitCode`/`signal` when applicable.
 
 ### Transcript
 
-`add` and `stop` render one outcome line; `list` renders a `/watch`-style rail
-capped at eight rows; `matches` and `logs` render the tail of the sanitized
-lines, with the hidden count noted above and `(ctrl+o to expand)`.
+`add` and `stop` render one outcome line; `list` renders the `/watch` rows
+capped at eight rows, minus the selection-marker column (`listRow`'s
+`marker: false`) that only the interactive screen needs; `matches` and `logs`
+render the tail of the sanitized lines, with the hidden count noted above and
+`(ctrl+o to expand)`.
 
 ### Command: /watch
 
@@ -172,8 +180,8 @@ other.
 | Annotations | `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: false`, `openWorldHint: true`. |
 | `outputSchema` | None; the result carries `details` only (no `structuredContent` mirror). |
 | State storage | In-memory runtime closure; no registry, no `getBranch()` rebuild. |
-| Injected context | A hidden `watch-context` custom message; pending matches are read from the runtime, never from the transcript. |
-| Lifecycle | `session_start` loads config and re-arms `onMatch`; `session_tree` repaints; `agent_start`/`agent_settled` track busy; `before_agent_start` injects pending matches; `context` keeps the newest note; `session_shutdown` kills commands and clears chips. |
+| Injected context | A shared transcript notice (`my-pi-agent/notice`), rendered by bytefly; pending matches are read from the runtime, never from the transcript. |
+| Lifecycle | `session_start` loads config and re-arms `onMatch`; `session_tree` repaints; `agent_start`/`agent_settled` track busy; `before_agent_start` posts pending matches as a notice; `context` prunes stale notices of its own source; `session_shutdown` kills commands and clears chips. |
 
 `watch` is gated by `PI_DISABLED_EXTENSIONS` like every extension.
 
@@ -193,7 +201,7 @@ turn — so a match is never dropped when the wake window is busy.
 
 | Module | Responsibility |
 |---|---|
-| `index.ts` | Extension factory: registers the tool and command, wires the lifecycle and injected context. |
+| `index.ts` | Extension factory: registers the tool and command, wires the lifecycle and the shared notices. |
 | `tools.ts` | The `watch` tool definition, execution, and transcript rendering. |
 | `schema.ts` | TypeBox parameters and pure `normalizeCall` validation. |
 | `types.ts` | `WatchAction`/`WatchStatus`, `WatchRecord`, `WatchDetails`, `PendingMatch`. |

package/extensions/watch/format.ts

@@ -12,7 +12,7 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import { sanitizeLine } from "../../lib/format.ts";
-import { GLYPHS } from "../../lib/tui/glyphs.ts";
+import { GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import type { PendingMatch, WatchRecord, WatchStatus } from "./types.ts";
 
@@ -195,7 +195,7 @@ export function formatCallText(action: string, args: Record<string, unknown>, ar
 
 /** One-line outcome for a watcher, themed for the transcript result. */
 export function formatWatchOutcomeLine(watch: WatchRecord, theme: Theme, now = Date.now()): string {
-	const sep = paint(theme, "faint", " · ");
+	const sep = paint(theme, "faint", SEPARATORS.item);
 	const age = Math.max(0, (watch.endedAt ?? now) - watch.startedAt);
 	const outcome =
 		watch.status === "error"

package/extensions/watch/index.ts

@@ -3,19 +3,20 @@
  *
  * Registers the `watch` tool and `/watch` command. Watchers read a file or a
  * command's merged output, match each new line against a regular expression,
- * and alert the user; matching lines are reported to the model at the next
- * turn, or wake a turn immediately when the watcher opted into `wake`. Watchers
- * are session-only and stopped on shutdown.
+ * and alert the user; matching lines are reported to the model — and shown as a
+ * bytefly notice — at the next turn, or wake a turn immediately when the
+ * watcher opted into `wake`. Watchers are session-only and stopped on shutdown.
  *
  * Load with:  pi --extension ./extensions/watch
  */
 
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
+import { sanitizeLine } from "../../lib/format.ts";
+import { noticeMessage, type NoticeMessage, pruneStaleNotices } from "../../lib/notice.ts";
 import { STATUS_KEYS } from "../../lib/tui/glyphs.ts";
 import { registerCommands } from "./commands.ts";
-import { formatPendingMatch } from "./format.ts";
+import { clipLabel, formatPendingMatch } from "./format.ts";
 import { createWatchRuntime, type WatchRuntime } from "./runtime.ts";
 import { registerTools } from "./tools.ts";
 import type { PendingMatch } from "./types.ts";
@@ -23,13 +24,10 @@ import type { PendingMatch } from "./types.ts";
 /** Marker embedded in the injected match context. */
 const WATCH_CONTEXT_MARKER = "[WATCH MATCHES]";
 
-/** Custom-entry type used for the injected match message. */
-export const WATCH_CONTEXT_TYPE = "watch-context";
-
 /** At most this many match lines are injected in one message. */
 const MAX_CONTEXT_MATCHES = 20;
 
-/** Build the hidden context injected for pending matches. */
+/** Build the model-facing text for the pending-match notice. */
 export function buildWatchContext(matches: PendingMatch[]): string {
 	const shown = matches.slice(0, MAX_CONTEXT_MATCHES);
 	const lines = shown.map(formatPendingMatch);
@@ -38,8 +36,21 @@ export function buildWatchContext(matches: PendingMatch[]): string {
 	return `${WATCH_CONTEXT_MARKER}\n${matches.length} watched line${matches.length === 1 ? "" : "s"} matched:\n${lines.join("\n")}${suffix}\nRead more with \`watch matches <id>\`.`;
 }
 
-function isWatchContext(message: AgentMessage): boolean {
-	return (message as AgentMessage & { customType?: string }).customType === WATCH_CONTEXT_TYPE;
+/** The shared notice for pending matches: model text plus renderer details. */
+function watchNotice(matches: PendingMatch[]): NoticeMessage {
+	const count = matches.length;
+	return noticeMessage({
+		content: buildWatchContext(matches),
+		details: {
+			source: "watch",
+			title: `${count} watched line${count === 1 ? "" : "s"} matched`,
+			items: matches.slice(0, MAX_CONTEXT_MATCHES).map((match) => ({
+				label: `${match.watcherId} ${clipLabel(match.label)}`,
+				detail: sanitizeLine(match.line),
+				severity: "warn",
+			})),
+		},
+	});
 }
 
 export interface WatchDeps {
@@ -64,10 +75,7 @@ export default function watch(pi: ExtensionAPI, deps: WatchDeps = {}): void {
 		const pending = runtime.pendingMatches();
 		if (pending.length === 0) return;
 		try {
-			pi.sendMessage(
-				{ customType: WATCH_CONTEXT_TYPE, content: buildWatchContext(pending), display: false },
-				{ triggerTurn: true },
-			);
+			pi.sendMessage(watchNotice(pending), { triggerTurn: true });
 			runtime.markReported(pending);
 			waking = true;
 		} catch {
@@ -103,17 +111,14 @@ export default function watch(pi: ExtensionAPI, deps: WatchDeps = {}): void {
 		if (pending.length === 0) return undefined;
 		runtime.markReported(pending);
 		runtime.setStatus(ctx);
-		return {
-			message: { customType: WATCH_CONTEXT_TYPE, content: buildWatchContext(pending), display: false },
-		};
+		return { message: watchNotice(pending) };
 	});
 
-	// Keep stale match notes out of later turns.
+	// Keep stale match notices out of later turns. Only this extension's notices
+	// are pruned; another source's are left for its own handler.
 	pi.on("context", (event) => {
-		const contexts = event.messages.filter(isWatchContext);
-		if (contexts.length <= 1) return undefined;
-		const last = contexts[contexts.length - 1];
-		return { messages: event.messages.filter((message) => !isWatchContext(message) || message === last) };
+		const pruned = pruneStaleNotices(event.messages, "watch");
+		return pruned ? { messages: pruned } : undefined;
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {

package/extensions/watch/tools.ts

@@ -10,6 +10,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { sanitizeLine } from "../../lib/format.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import { SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import {
 	compareWatches,
@@ -193,8 +194,9 @@ export function registerTools(pi: ExtensionAPI, runtime: WatchRuntime): void {
 			const text = reuseText(context.lastComponent);
 			text.setText(
 				theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) +
-					theme.fg(
-						"muted",
+					paint(
+						theme,
+						"meta",
 						sanitizeLine(formatCallText(action, args as Record<string, unknown>, context.argsComplete)),
 					),
 			);
@@ -269,7 +271,7 @@ export function registerTools(pi: ExtensionAPI, runtime: WatchRuntime): void {
 					const badges: string[] = [];
 					if (details.watch.wake) badges.push("wake");
 					if (details.watch.fromStart) badges.push("from start");
-					if (badges.length > 0) line += paint(theme, "faint", ` · ${badges.join(" · ")}`);
+					if (badges.length > 0) line += paint(theme, "faint", `${SEPARATORS.item}${badges.join(SEPARATORS.item)}`);
 				}
 				text.setText(line);
 				return text;

package/extensions/watch/tui.ts

@@ -18,7 +18,7 @@ import { clip, fitCells } from "../../lib/tui/columns.ts";
 import { fitRows, formatRange, IdCursor, isCloseKey, navIntent, wheelDelta } from "../../lib/tui/cursor.ts";
 import { expandHint, SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { LinePane } from "../../lib/tui/line-pane.ts";
-import { emptyState, listRow } from "../../lib/tui/rows.ts";
+import { emptyState, statusRow, type StatusRow } from "../../lib/tui/rows.ts";
 import { titleRule } from "../../lib/tui/rules.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { compareWatches, formatWatchDetail, shortLabel, statusGlyphChar, statusRole } from "./format.ts";
@@ -37,14 +37,18 @@ const LINES_CHROME_ROWS = 6;
 const watchId = (watch: WatchRecord): string => watch.id;
 
 /** One watcher row: marker, status glyph, id, label, and a right-aligned count. */
-function watchRow(watch: WatchRecord, theme: Theme, width: number, selected = false): string {
-	return listRow(theme, width, {
-		selected,
+function watchRow(
+	watch: WatchRecord,
+	theme: Theme,
+	width: number,
+	options: Pick<StatusRow, "selected" | "marker"> = {},
+): string {
+	return statusRow(theme, width, {
+		...options,
 		glyph: statusGlyphChar(watch.status),
 		glyphRole: statusRole(watch.status),
 		label: `${watch.id}  ${shortLabel(watch)}`,
 		trailing: `${watch.matchCount}`,
-		trailingRole: "faint",
 	});
 }
 
@@ -80,7 +84,7 @@ export class WatchResult implements Component {
 		// A leading blank line separates the result from the call header.
 		const lines: string[] = [""];
 		if (this.input.kind === "list") {
-			for (const watch of this.input.watches) lines.push(watchRow(watch, this.theme, w));
+			for (const watch of this.input.watches) lines.push(watchRow(watch, this.theme, w, { marker: false }));
 			if (this.input.more > 0) {
 				const note = `${paint(this.theme, "faint", `… ${this.input.more} more`)} ${expandHint(this.theme)}`;
 				lines.push(clip(`  ${note}`, w));
@@ -311,7 +315,8 @@ export class WatchListComponent implements Component {
 			body.push(...emptyState(this.theme, w, { label: "No watchers." }));
 		} else {
 			const end = Math.min(watches.length, this.cursor.scroll + this.cursor.visible);
-			for (let i = this.cursor.scroll; i < end; i++) body.push(watchRow(watches[i], this.theme, w, i === index));
+			for (let i = this.cursor.scroll; i < end; i++)
+				body.push(watchRow(watches[i], this.theme, w, { selected: i === index }));
 			if (this.cursor.scroll > 0 || end < watches.length) {
 				range = formatRange(this.theme, w, { start: this.cursor.scroll, end, total: watches.length });
 			}

package/extensions/web-access/README.md

@@ -12,6 +12,14 @@ pi -e .                                   # load the whole @gavin-hu/my-pi-agent
 pi install ./                             # or install the package
 ```
 
+## Tool rendering
+
+How the `web_search` and `web_fetch` calls and their results look in the transcript — the call line as a headline and the body indented under it:
+
+<img src="../../assets/tools/web_search.png" alt="The web_search tool's call and result: the call line and an indented body with the query and the ranked results" width="100%">
+
+<img src="../../assets/tools/web_fetch.png" alt="The web_fetch tool's call and result: the call line and an indented body with the URL, title, and fetched text preview" width="100%">
+
 ## What it does
 
 - Registers `web_search`, general web search through a pluggable provider:
@@ -46,17 +54,18 @@ web_fetch({ url: "https://pi.dev/", find: ["documentation", "extensions"] })
 
 ### Transcript
 
-The call line names the query or URL. The result separates the header from its
-body and sanitizes untrusted web text (answers, titles, fetched titles and
-errors) to one line before it reaches the terminal. A search result labels its
-answer and lists one URL per result; expanding reveals snippets and the full
-result list.
+The call line names the query or URL and states the requested limit
+(`(max 8)`), so it never reads as the number of results returned. The result
+separates the header from its body and sanitizes untrusted web text (answers,
+titles, fetched titles and errors) to one line before it reaches the terminal.
+A search result labels its answer and lists one URL per result; expanding
+reveals snippets and the full result list.
 
 ```
-web_search "pi coding agent" (8 results)
+web_search "pi coding agent" (max 8)
 
 via searxng · 8 results
-answer Pi is a coding agent harness …
+Answer: Pi is a coding agent harness …
 1. Pi — a coding agent harness
    https://pi.dev/
 2. GitHub - earendil-works/pi

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

@@ -205,7 +205,7 @@ 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} `)) + paint(theme, "accent", oneLine(url ?? ""));
+			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);

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

@@ -69,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} `)) + paint(theme, "accent", oneLine(query ?? ""));
-			if (maxResults) line += paint(theme, "faint", ` (${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;
 		},
@@ -96,7 +96,7 @@ export function registerSearchTool(pi: ExtensionAPI, deps: SearchDeps = {}): voi
 				paint(theme, "faint", `via ${details.provider}${SEPARATORS.item}${count} result${count === 1 ? "" : "s"}`),
 			];
 			if (details.answer)
-				lines.push(`${paint(theme, "faint", "answer")} ${paint(theme, "meta", oneLine(details.answer, 160))}`);
+				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 = paint(theme, "faint", "   ");

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

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/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. |
-| [`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`, `BODY_INDENT` / `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) (`plainRule` / `titleRule` / `centeredRule`), [`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). |
+| [`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. |

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.