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

package/extensions/subagent/render.ts

@@ -15,8 +15,9 @@ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { Container, Markdown, Spacer, Text, visibleWidth, type Component } from "@earendil-works/pi-tui";
 import { sanitizeLine, shortenPath, stripControlChars } from "../../lib/format.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
-import { expandHint, GLYPHS } from "../../lib/tui/glyphs.ts";
+import { expandHint, GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { centeredRule } from "../../lib/tui/rules.ts";
+import { BODY_INDENT } from "../../lib/tui/indent.ts";
 import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import { aggregateUsage, clip, formatToolCall, formatUsageStats } from "./format.ts";
 import { COLLAPSED_ERROR_MAX, COLLAPSED_ITEM_COUNT, COLLAPSED_TEXT_LINES, type SubagentArgs } from "./schema.ts";
@@ -187,7 +188,7 @@ function resultHeader(
 	stepPrefix: string,
 	now: number,
 ): string {
-	let header = `${statusIcon(status, theme, now)} ${theme.fg("toolTitle", theme.bold(sanitizeLine(result.agent)))}`;
+	let header = `${statusIcon(status, theme, now)} ${paint(theme, "accent", theme.bold(sanitizeLine(result.agent)))}`;
 	if (result.agentSource && result.agentSource !== "builtin" && result.agentSource !== "unknown") {
 		header += paint(theme, "faint", ` [${sanitizeLine(result.agentSource)}]`);
 	}
@@ -195,12 +196,13 @@ function resultHeader(
 	return header + statusSuffix(result, status, theme, now);
 }
 
-/** Prefix each line of intermediate assistant text with a muted gutter. */
-function quoteLines(text: string, theme: Theme): string {
+/** Prefix each line of intermediate assistant text with the block's body indent. */
+function indentBody(text: string, theme: Theme): string {
+	const indent = " ".repeat(BODY_INDENT);
 	return stripControlChars(text)
 		.trim()
 		.split("\n")
-		.map((line) => paint(theme, "meta", "│ ") + theme.fg("toolOutput", line))
+		.map((line) => indent + theme.fg("toolOutput", line))
 		.join("\n");
 }
 
@@ -233,47 +235,72 @@ export interface SubagentCallContext {
 	lastComponent?: Component;
 }
 
+/**
+ * The call's arguments as Pi hands them to `renderCall`. While the model streams
+ * a call, a field can still be missing, or arrive with a type the schema will
+ * later reject, so the call line reads every one defensively and never throws: a
+ * throwing renderer makes Pi fall back to its own generic call line.
+ */
+export type StreamedSubagentArgs = Partial<Record<keyof SubagentArgs, unknown>>;
+
+/** One field of a partially-streamed element, or undefined when it has not arrived. */
+function streamedText(element: unknown, key: "agent" | "task" | "cwd"): string | undefined {
+	if (typeof element !== "object" || element === null) return undefined;
+	const value = (element as Record<string, unknown>)[key];
+	return typeof value === "string" ? value : undefined;
+}
+
 /** Preview the requested mode and its agents, reusing the slot's `Text`. */
-export function renderSubagentCall(args: SubagentArgs, theme: Theme, context?: SubagentCallContext): Component {
+export function renderSubagentCall(
+	args: StreamedSubagentArgs | undefined,
+	theme: Theme,
+	context?: SubagentCallContext,
+): Component {
 	const text = reuseText(context?.lastComponent);
-	text.setText(callText(args, theme, context));
+	text.setText(callText(args ?? {}, theme, context));
 	return text;
 }
 
-/** The call-line string for the requested mode. */
-function callText(args: SubagentArgs, theme: Theme, context?: { cwd?: string }): string {
+/**
+ * The call-line string for the requested mode. Continuation lines carry no
+ * indent of their own: the tool-block frame headlines the first line and
+ * indents the rest by `BODY_INDENT`.
+ */
+function callText(args: StreamedSubagentArgs, theme: Theme, context?: { cwd?: string }): string {
 	const title =
 		theme.fg("toolTitle", theme.bold("subagent ")) + (args.readOnly ? paint(theme, "faint", "read-only ") : "");
-	const cwdNote = (cwd?: string) => {
-		if (!cwd || cwd === context?.cwd) return "";
+	const cwdNote = (cwd?: unknown) => {
+		if (typeof cwd !== "string" || !cwd || cwd === context?.cwd) return "";
 		return paint(theme, "faint", `  in ${shortenPath(cwd)}`);
 	};
-
-	if (args.chain && args.chain.length > 0) {
-		let text = title + paint(theme, "accent", `chain · ${args.chain.length} step${args.chain.length > 1 ? "s" : ""}`);
-		for (let i = 0; i < Math.min(args.chain.length, 3); i++) {
-			const step = args.chain[i];
-			const clean = sanitizeLine(step.task.replace(/\{previous\}/g, ""));
-			text += `\n  ${paint(theme, "meta", `${i + 1}.`)} ${paint(theme, "accent", sanitizeLine(step.agent))}${paint(theme, "faint", ` ${clip(clean, 40)}`)}${cwdNote(step.cwd)}`;
+	const chain = Array.isArray(args.chain) ? args.chain : [];
+	if (chain.length > 0) {
+		let text =
+			title + paint(theme, "label", `chain${SEPARATORS.item}${chain.length} step${chain.length > 1 ? "s" : ""}`);
+		for (let i = 0; i < Math.min(chain.length, 3); i++) {
+			const step = chain[i];
+			const task = (streamedText(step, "task") ?? "…").replace(/\{previous\}/g, "");
+			text += `\n${paint(theme, "meta", `${i + 1}.`)} ${paint(theme, "label", sanitizeLine(streamedText(step, "agent") || "…"))}${paint(theme, "meta", ` ${clip(sanitizeLine(task), 40)}`)}${cwdNote(streamedText(step, "cwd"))}`;
 		}
-		if (args.chain.length > 3) text += `\n  ${paint(theme, "meta", `… +${args.chain.length - 3} more`)}`;
+		if (chain.length > 3) text += `\n${paint(theme, "meta", `… +${chain.length - 3} more`)}`;
 		return text;
 	}
 
-	if (args.tasks && args.tasks.length > 0) {
+	const tasks = Array.isArray(args.tasks) ? args.tasks : [];
+	if (tasks.length > 0) {
 		let text =
-			title + paint(theme, "accent", `parallel · ${args.tasks.length} task${args.tasks.length > 1 ? "s" : ""}`);
-		for (let i = 0; i < Math.min(args.tasks.length, 3); i++) {
-			const task = args.tasks[i];
-			text += `\n  ${paint(theme, "meta", `${i + 1}.`)} ${paint(theme, "accent", sanitizeLine(task.agent))}${paint(theme, "faint", ` ${clip(sanitizeLine(task.task), 40)}`)}${cwdNote(task.cwd)}`;
+			title + paint(theme, "label", `parallel${SEPARATORS.item}${tasks.length} task${tasks.length > 1 ? "s" : ""}`);
+		for (let i = 0; i < Math.min(tasks.length, 3); i++) {
+			const task = tasks[i];
+			text += `\n${paint(theme, "meta", `${i + 1}.`)} ${paint(theme, "label", sanitizeLine(streamedText(task, "agent") || "…"))}${paint(theme, "meta", ` ${clip(sanitizeLine(streamedText(task, "task") ?? "…"), 40)}`)}${cwdNote(streamedText(task, "cwd"))}`;
 		}
-		if (args.tasks.length > 3) text += `\n  ${paint(theme, "meta", `… +${args.tasks.length - 3} more`)}`;
+		if (tasks.length > 3) text += `\n${paint(theme, "meta", `… +${tasks.length - 3} more`)}`;
 		return text;
 	}
 
-	const agentName = sanitizeLine(args.agent || "…");
-	let text = title + paint(theme, "accent", agentName) + cwdNote(args.cwd);
-	text += `\n  ${paint(theme, "faint", clip(sanitizeLine(args.task ?? "…"), 60))}`;
+	const agentName = sanitizeLine(streamedText(args, "agent") || "…");
+	let text = title + paint(theme, "label", agentName) + cwdNote(streamedText(args, "cwd"));
+	text += `\n${paint(theme, "meta", clip(sanitizeLine(streamedText(args, "task") ?? "…"), 60))}`;
 	return text;
 }
 
@@ -316,7 +343,7 @@ function addExpandedResult(
 			);
 			renderedOutput = true;
 		} else if (item.text.trim() && item.text !== trailingOutput) {
-			container.addChild(new Text(quoteLines(item.text, theme), 0, 0));
+			container.addChild(new Text(indentBody(item.text, theme), 0, 0));
 			renderedOutput = true;
 		}
 	}

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);