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

package/extensions/watch/tui.ts

@@ -6,36 +6,23 @@
  * tracks the selection by id so a live re-sort cannot move the cursor, through
  * the shared `IdCursor` and `LinePane`.
  *
- * The screen is drawn from the design system: a label-first `titleRule`, one
- * `listRow` grammar, and `emptyState`. Matched lines arrive already sanitized by
- * the runtime, so no untrusted escape sequence reaches the terminal here.
+ * The frame, the navigation keys, the y/N confirmation, and the matches pane come
+ * from the shared `DockListScreen`, so this module owns only the watch
+ * vocabulary: the row, the focus block, the counts, the hints, and what the
+ * verbs do. Matched lines arrive already sanitized by the runtime, so no
+ * untrusted escape sequence reaches the terminal here.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { Key, matchesKey, type Component, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
-import { dockListFrame, screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
-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, statusRow, type StatusRow } from "../../lib/tui/rows.ts";
-import { titleRule } from "../../lib/tui/rules.ts";
+import type { Component } from "@earendil-works/pi-tui";
+import type { ScreenHint, ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { DockListScreen, type DetailContents } from "../../lib/tui/dock-screen.ts";
+import { statusRow, type StatusRow } from "../../lib/tui/rows.ts";
+import { TailResult, type TailResultInput } from "../../lib/tui/tool.ts";
 import { paint } from "../../lib/tui/tokens.ts";
 import { compareWatches, formatWatchDetail, shortLabel, statusGlyphChar, statusRole } from "./format.ts";
 import type { WatchRecord } from "./types.ts";
 
-/** Rows the `/watch` screen body shows when the terminal height is unknown. */
-const SCREEN_DEFAULT_ROWS = 14;
-
-/** Fixed rows around the list body: header, summary, blank, blank, hint, blank. */
-const LIST_CHROME_ROWS = 7;
-
-/** Fixed rows around the matches body: header, subtitle, blank, blank, hint, blank. */
-const LINES_CHROME_ROWS = 6;
-
-/** A watcher's stable identity, for the id-anchored cursor. */
-const watchId = (watch: WatchRecord): string => watch.id;
-
 /** One watcher row: marker, status glyph, id, label, and a right-aligned count. */
 function watchRow(
 	watch: WatchRecord,
@@ -48,6 +35,7 @@ function watchRow(
 		glyph: statusGlyphChar(watch.status),
 		glyphRole: statusRole(watch.status),
 		label: `${watch.id}  ${shortLabel(watch)}`,
+		labelRole: options.selected ? "accent" : "label",
 		trailing: `${watch.matchCount}`,
 	});
 }
@@ -57,48 +45,41 @@ export type WatchResultInput =
 	| { kind: "list"; watches: WatchRecord[]; more: number }
 	| { kind: "lines"; label: string; lines: string[]; earlier: number };
 
+/** Map the watch vocabulary onto the shared transcript tail block. */
+function watchTail(input: WatchResultInput): TailResultInput<WatchRecord> {
+	if (input.kind === "lines") {
+		return { kind: "lines", lines: input.lines, earlier: input.earlier, earlierLabel: input.label };
+	}
+	return {
+		kind: "list",
+		rows: input.watches,
+		more: input.more,
+		rowLine: (watch, width, theme) => watchRow(watch, theme, width, { marker: false }),
+	};
+}
+
 /**
- * Transcript result block for the `watch` tool: a blank line, then either the
- * `/watch`-style row rail (already ordered and capped by the caller) or the
- * themed matched-line tail. Reused across renders via `setInput`.
+ * Transcript result block for the `watch` tool: the shared tail block over the
+ * `/watch`-style row rail or the themed matched-line tail. Reused across renders.
  */
 export class WatchResult implements Component {
-	private input: WatchResultInput;
-	private theme: Theme;
+	private readonly view: TailResult<WatchRecord>;
 
 	constructor(input: WatchResultInput, theme: Theme) {
-		this.input = input;
-		this.theme = theme;
+		this.view = new TailResult(watchTail(input), theme);
 	}
 
 	/** Update in place so the transcript can reuse this component across renders. */
 	setInput(input: WatchResultInput, theme: Theme): void {
-		this.input = input;
-		this.theme = theme;
+		this.view.setInput(watchTail(input), theme);
 	}
 
-	invalidate(): void {}
+	invalidate(): void {
+		this.view.invalidate();
+	}
 
 	render(width: number): string[] {
-		const w = Math.max(1, width);
-		// 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, { 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));
-			}
-		} else {
-			if (this.input.earlier > 0) {
-				const note = `${paint(this.theme, "faint", `… ${this.input.earlier} earlier ${this.input.label}`)} ${expandHint(this.theme)}`;
-				lines.push(clip(note, w));
-			}
-			for (const line of this.input.lines) {
-				lines.push(this.theme.fg("toolOutput", clip(line, w)));
-			}
-		}
-		return lines;
+		return this.view.render(width);
 	}
 }
 
@@ -109,265 +90,114 @@ export interface WatchListCallbacks {
 	clear(): void;
 }
 
-/** A destructive action waiting for y/N confirmation. */
-type PendingConfirm = { kind: "stop"; id: string; label: string } | { kind: "clear"; count: number };
-
 /** Dismissible `/watch` screen: a selectable list with a focus pane and a matches view. */
-export class WatchListComponent implements Component {
-	private mode: "list" | "lines" = "list";
-	/** Focus anchored to a watcher id; the list is re-sorted from live state each render. */
-	private readonly cursor = new IdCursor();
-	/** The open matches tail. */
-	private readonly pane = new LinePane();
-	private confirm: PendingConfirm | undefined;
-	private notice: string | undefined;
-
+export class WatchListComponent extends DockListScreen<WatchRecord> {
 	constructor(
 		private readonly watches: () => WatchRecord[],
-		private readonly theme: Theme,
+		theme: Theme,
 		private readonly callbacks: WatchListCallbacks,
-		private readonly onClose: () => void,
-		private readonly requestRender: () => void,
-		private readonly viewportRowsSource?: ViewportRowsSource,
-	) {}
-
-	invalidate(): void {}
+		onClose: () => void,
+		requestRender: () => void,
+		viewportRowsSource?: ViewportRowsSource,
+	) {
+		super({
+			theme,
+			title: "Watch",
+			detailTitle: "Watch Matches",
+			emptyList: "No watchers.",
+			emptyDetail: "No matches yet.",
+			requestRender,
+			onClose,
+			viewportRowsSource,
+		});
+	}
 
 	/** Replace the matches pane contents (called by the command's poll loop). */
 	setLines(title: string, lines: string[], meta: { more?: boolean } = {}): void {
-		if (this.pane.update({ title, lines, more: meta.more })) this.requestRender();
+		this.setDetail({ title, lines, more: meta.more });
 	}
 
 	/** The watcher whose matches pane is open, or undefined in list mode. */
 	currentLineId(): string | undefined {
-		return this.mode === "lines" && this.pane.id ? this.pane.id : undefined;
+		return this.currentDetailId();
 	}
 
 	/** Re-read the open matches pane from the runtime. */
 	refreshLines(id: string): void {
-		const result = this.callbacks.lines(id);
-		if (result && this.pane.update({ lines: result.lines, more: result.more })) this.requestRender();
+		this.refreshDetail(id);
 	}
 
-	private get ordered(): WatchRecord[] {
+	protected rows(): readonly WatchRecord[] {
 		return [...this.watches()].sort(compareWatches);
 	}
 
-	/** Focus watcher `next` (clamped) and keep it visible. */
-	private select(next: number): void {
-		const ordered = this.ordered;
-		if (ordered.length === 0) return;
-		this.cursor.select(ordered, watchId, next);
-		this.requestRender();
-	}
-
-	private openLines(): void {
-		const watch = this.ordered[this.cursor.indexOf(this.ordered, watchId)];
-		if (!watch) return;
-		this.mode = "lines";
-		const result = this.callbacks.lines(watch.id);
-		this.pane.open(watch.id, {
-			title: `${watch.id} ${shortLabel(watch)}`,
-			lines: result?.lines ?? [],
-			more: result?.more ?? false,
-		});
-		this.requestRender();
+	protected idOf(watch: WatchRecord): string {
+		return watch.id;
 	}
 
-	handleInput(data: string): void {
-		if (this.confirm) {
-			this.handleConfirmInput(data);
-			return;
-		}
-		if (this.mode === "list") this.handleListInput(data);
-		else this.handleLinesInput(data);
+	protected rowLine(watch: WatchRecord, width: number, selected: boolean): string {
+		return watchRow(watch, this.theme, width, { selected });
 	}
 
-	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
-		const delta = wheelDelta(event);
-		if (delta === undefined) return undefined;
-		if (this.confirm) return { handled: true };
-		if (this.mode === "list") {
-			this.select(this.cursor.indexOf(this.ordered, watchId) + delta);
-		} else {
-			this.pane.setScroll(this.pane.scroll + delta);
-			this.requestRender();
-		}
-		return { handled: true };
-	}
-
-	private handleListInput(data: string): void {
-		if (isCloseKey(data) || data === "q") {
-			this.onClose();
-			return;
-		}
-		if (this.notice !== undefined) {
-			this.notice = undefined;
-			this.requestRender();
-		}
-		const ordered = this.ordered;
-		const index = this.cursor.indexOf(ordered, watchId);
-		switch (navIntent(data)) {
-			case "up":
-				this.select(index - 1);
-				return;
-			case "down":
-				this.select(index + 1);
-				return;
-			case "pageUp":
-				this.select(index - this.cursor.visible);
-				return;
-			case "pageDown":
-				this.select(index + this.cursor.visible);
-				return;
-			case "home":
-				this.select(0);
-				return;
-			case "end":
-				this.select(ordered.length - 1);
-				return;
-		}
-		if (matchesKey(data, Key.enter) || data === "l") {
-			this.openLines();
-		} else if (data === "x" || data === "K") {
-			const watch = ordered[index];
-			if (!watch) return;
-			if (watch.status === "running") {
-				this.confirm = { kind: "stop", id: watch.id, label: shortLabel(watch) };
-			} else {
-				this.notice = `${watch.id} is ${watch.status}; nothing to stop.`;
-			}
-			this.requestRender();
-		} else if (data === "d") {
-			const stopped = ordered.filter((watch) => watch.status !== "running");
-			if (stopped.length > 0) this.confirm = { kind: "clear", count: stopped.length };
-			else this.notice = "No stopped watchers to clear.";
-			this.requestRender();
-		}
+	protected detailBlock(watch: WatchRecord): string[] {
+		return formatWatchDetail(watch, Date.now());
 	}
 
-	private handleConfirmInput(data: string): void {
-		const pending = this.confirm;
-		if (!pending) return;
-		if (data === "y" || data === "Y" || matchesKey(data, Key.enter)) {
-			this.confirm = undefined;
-			if (pending.kind === "stop") this.callbacks.stop(pending.id);
-			else this.callbacks.clear();
-			this.cursor.clamp(this.ordered, watchId);
-			this.requestRender();
-			return;
-		}
-		if (data === "n" || data === "N" || isCloseKey(data) || data === "q") {
-			this.confirm = undefined;
-			this.requestRender();
-		}
+	protected summaryCells(rows: readonly WatchRecord[]): string[] {
+		const cells = [paint(this.theme, "meta", `${rows.length} watcher${rows.length === 1 ? "" : "s"}`)];
+		const running = rows.filter((watch) => watch.status === "running").length;
+		const matched = rows.reduce((sum, watch) => sum + watch.matchCount, 0);
+		if (running > 0) cells.push(paint(this.theme, "meta", `${running} running`));
+		if (matched > 0) cells.push(paint(this.theme, "accent", `${matched} matches`));
+		return cells;
 	}
 
-	private confirmPrompt(): string {
-		const pending = this.confirm;
-		if (!pending) return "";
-		if (pending.kind === "stop") return `Stop ${pending.id} (${pending.label})? y/N`;
-		return `Clear ${pending.count} stopped watcher${pending.count === 1 ? "" : "s"}? y/N`;
+	protected listHints(): ScreenHint[] {
+		return [
+			"Esc close",
+			"↑/↓ or j/k select",
+			{ text: "Enter or l matches", color: "accent" },
+			{ text: "x or K stop", color: "warning" },
+			{ text: "d clear stopped", color: "warning" },
+			"PgUp/PgDn",
+		];
 	}
 
-	private handleLinesInput(data: string): void {
-		if (matchesKey(data, Key.escape) || matchesKey(data, Key.backspace) || data === "q") {
-			this.mode = "list";
-			this.pane.close();
-			this.requestRender();
-			return;
-		}
-		if (this.pane.handleKey(data)) this.requestRender();
+	protected detailHints(): ScreenHint[] {
+		return ["Esc back", "↑/↓ scroll", "g/G ends", "PgUp/PgDn"];
 	}
 
-	private summary(watches: WatchRecord[], width: number): string {
-		const cells = [paint(this.theme, "meta", `${watches.length} watcher${watches.length === 1 ? "" : "s"}`)];
-		const running = watches.filter((watch) => watch.status === "running").length;
-		const matched = watches.reduce((sum, watch) => sum + watch.matchCount, 0);
-		if (running > 0) cells.push(paint(this.theme, "meta", `${running} running`));
-		if (matched > 0) cells.push(paint(this.theme, "accent", `${matched} matches`));
-		const separator = paint(this.theme, "meta", SEPARATORS.item);
-		return clip(`  ${fitCells(cells, Math.max(1, width - 2), separator)}`, width);
+	protected detailFor(watch: WatchRecord): DetailContents {
+		const result = this.callbacks.lines(watch.id);
+		return {
+			title: `${watch.id} ${shortLabel(watch)}`,
+			lines: result?.lines ?? [],
+			more: result?.more ?? false,
+		};
 	}
 
-	render(width: number): string[] {
-		const w = Math.max(1, width);
-		return this.mode === "lines" ? this.renderLines(w) : this.renderList(w);
+	protected detailById(id: string): { lines: string[]; more?: boolean } | undefined {
+		return this.callbacks.lines(id);
 	}
 
-	private renderList(w: number): string[] {
-		const watches = this.ordered;
-		this.cursor.clamp(watches, watchId);
-		const index = this.cursor.indexOf(watches, watchId);
-		const focused = watches[index];
-		const detail = focused ? formatWatchDetail(focused, Date.now()) : [];
-		this.cursor.visible = fitRows(
-			this.viewportRowsSource,
-			watches.length,
-			LIST_CHROME_ROWS + detail.length,
-			SCREEN_DEFAULT_ROWS,
-		);
-		this.cursor.clamp(watches, watchId);
-
-		const body: string[] = [];
-		let range: string | undefined;
-		if (watches.length === 0) {
-			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, { selected: i === index }));
-			if (this.cursor.scroll > 0 || end < watches.length) {
-				range = formatRange(this.theme, w, { start: this.cursor.scroll, end, total: watches.length });
+	protected handleVerb(key: string, watch: WatchRecord | undefined): void {
+		if (key === "x" || key === "K") {
+			if (!watch) return;
+			if (watch.status === "running") {
+				this.confirm(`Stop ${watch.id} (${shortLabel(watch)})? y/N`, () => this.callbacks.stop(watch.id));
+			} else {
+				this.notify(`${watch.id} is ${watch.status}; nothing to stop.`);
 			}
+			return;
 		}
-
-		const hint = this.confirm
-			? clip(`  ${paint(this.theme, "warn", this.confirmPrompt())}`, w)
-			: this.notice
-				? clip(`  ${paint(this.theme, "meta", this.notice)}`, w)
-				: screenHint(this.theme, w, [
-						"Esc close",
-						"↑/↓ or j/k select",
-						"Enter or l matches",
-						"x or K stop",
-						"d clear stopped",
-						"PgUp/PgDn",
-					]);
-
-		return dockListFrame({
-			header: titleRule(this.theme, w, "Watch"),
-			summary: this.summary(watches, w),
-			body,
-			range,
-			// The detail pane is separated from the list by a blank line.
-			detail: ["", ...detail.map((line) => clip(`  ${paint(this.theme, "meta", line)}`, w))],
-			hint,
-		});
-	}
-
-	private renderLines(w: number): string[] {
-		const visible = fitRows(this.viewportRowsSource, this.pane.count, LINES_CHROME_ROWS, SCREEN_DEFAULT_ROWS);
-		this.pane.fit(visible);
-
-		const body: string[] = [];
-		let range: string | undefined;
-		if (this.pane.count === 0) {
-			body.push(...emptyState(this.theme, w, { label: "No matches yet." }));
-		} else {
-			const { start, end } = this.pane.window();
-			for (let i = start; i < end; i++) body.push(clip(`  ${this.pane.lines[i]}`, w));
-			if (start > 0 || end < this.pane.count) {
-				range = formatRange(this.theme, w, { start, end, total: this.pane.count, label: "line" });
-			}
+		if (key !== "d") return;
+		const stopped = this.rows().filter((row) => row.status !== "running");
+		if (stopped.length === 0) {
+			this.notify("No stopped watchers to clear.");
+			return;
 		}
-
-		return dockListFrame({
-			header: titleRule(this.theme, w, this.pane.title("Watch Matches")),
-			summary: clip(`  ${paint(this.theme, "faint", this.pane.subtitleLine())}`, w),
-			body,
-			range,
-			hint: screenHint(this.theme, w, ["Esc back", "↑/↓ scroll", "g/G ends", "PgUp/PgDn"]),
-		});
+		this.confirm(`Clear ${stopped.length} stopped watcher${stopped.length === 1 ? "" : "s"}? y/N`, () =>
+			this.callbacks.clear(),
+		);
 	}
 }

package/extensions/watch/ui.ts

@@ -2,13 +2,11 @@
  * Presentation for the watch extension: the footer status chips and the match
  * alert.
  *
- * Kept separate from the runtime so the runtime owns lifecycle (the watcher
- * table, the tail clock) and this owns "how watchers are shown". The chips come
- * from the shared `lib/tui/status-controller.ts`, so only the vocabulary — the
- * keys, glyphs, and counts — is watch-specific.
+ * The chips and the context they paint through come from the shared
+ * `lib/tui/status-controller.ts`, so only the vocabulary — the keys, glyphs,
+ * counts, and message text — is watch-specific.
  */
 
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
 import { createStatusController, type StatusChip, type StatusController } from "../../lib/tui/status-controller.ts";
 import type { WatchConfig } from "./config.ts";
@@ -28,8 +26,6 @@ export interface UiOptions {
 
 export function createUiController(options: UiOptions): UiController {
 	const { getWatches, getUnseenMatches, getConfig } = options;
-	// The match alert also needs the context, so it is mirrored here.
-	let ctx: ExtensionContext | undefined;
 
 	const controller = createStatusController({
 		keys: [STATUS_KEYS.watch, STATUS_KEYS.watchMatches],
@@ -45,31 +41,8 @@ export function createUiController(options: UiOptions): UiController {
 	});
 
 	const notifyMatch = (watch: WatchRecord, line: string): void => {
-		const target = ctx;
-		if (!target) return;
-		try {
-			target.ui.notify(`watch ${watch.id} (${shortLabel(watch)}) matched: ${line}`, "warning");
-		} catch {
-			// UI may be unavailable in non-interactive modes.
-		}
+		controller.notify(`watch ${watch.id} (${shortLabel(watch)}) matched: ${line}`, "warning");
 	};
 
-	return {
-		attach: (next) => {
-			ctx = next;
-			controller.attach(next);
-		},
-		detach: () => {
-			ctx = undefined;
-			controller.detach();
-		},
-		paint: () => {
-			controller.paint();
-		},
-		setStatus: (next) => {
-			if (next) ctx = next;
-			controller.setStatus(next);
-		},
-		notifyMatch,
-	};
+	return { ...controller, notifyMatch };
 }

package/extensions/web-access/README.md

@@ -371,7 +371,7 @@ the content type and size.
 | `fetch/page.ts` | Fetch + redirect-following + content-type routing |
 | `fetch/ssrf.ts` | URL/host validation and private-address blocking |
 | `fetch/extract.ts` | HTML → title + readable text |
-| `fetch/pdf.ts` | Optional PDF text extraction via lazy `unpdf` (injected via `FetchDeps`) |
+| `fetch/page.ts` | Fetch + redirect-following + content-type routing; PDF extraction is injected via `FetchDeps` from the shared `lib/pdf.ts` |
 | `fetch/find.ts` | Passage search (exact/insensitive/fuzzy) |
 | `fetch/cache.ts` | Per-registration LRU/TTL page cache (`createPageCache`) |
 | `fetch/format.ts`, `fetch/types.ts` | Result text and data types |

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

@@ -11,7 +11,7 @@
 
 import type { WebFetchConfig } from "./config.ts";
 import { extractReadable } from "./extract.ts";
-import { extractPdfText, type PdfExtractor } from "./pdf.ts";
+import { extractPdfText, type PdfExtractor } from "../../../lib/pdf.ts";
 import { createFetchRunner, type HttpRunner, type HttpResponse } from "../http.ts";
 import { decodeHtml } from "../charset.ts";
 import { assertAllowedUrl } from "./ssrf.ts";

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

@@ -149,7 +149,11 @@ function pageResult(loaded: LoadedPage, request: FetchRequest): { response: Fetc
 }
 
 /** Build the response entry and text for a failed URL. */
-function errorResult(url: string, request: FetchRequest, message: string): { response: FetchResponse; text: string } {
+function fetchErrorResult(
+	url: string,
+	request: FetchRequest,
+	message: string,
+): { response: FetchResponse; text: string } {
 	return {
 		response: {
 			url,
@@ -209,7 +213,7 @@ export function registerFetchTool(pi: ExtensionAPI, deps: FetchToolDeps = {}): v
 				({ response: page, text } = pageResult(loaded, request));
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
-				({ response: page, text } = errorResult(request.url, request, message));
+				({ response: page, text } = fetchErrorResult(request.url, request, message));
 			}
 
 			return {

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

@@ -7,6 +7,7 @@
  * object created per extension instance, so there is no module-level state.
  */
 
+import { messageOf } from "../../../lib/errors.ts";
 import { createFetchRunner, type HttpRunner } from "../http.ts";
 import { resolveSearchApiKey, type WebSearchConfig } from "./config.ts";
 import { resolveProvider } from "./registry.ts";
@@ -75,10 +76,6 @@ export function createThrottle(now: () => number = Date.now, sleep: ThrottleSlee
 	};
 }
 
-function describe(error: unknown): string {
-	return error instanceof Error ? error.message : String(error);
-}
-
 /** A model-readable reason a forced provider cannot run. */
 function notConfigured(id: SearchProviderId): string {
 	if (id === "searxng") {
@@ -119,7 +116,7 @@ export async function runSearch(
 		});
 	} catch (error) {
 		if (error instanceof WebSearchError) throw error;
-		throw new WebSearchError(`Search failed: ${describe(error)}`);
+		throw new WebSearchError(`Search failed: ${messageOf(error)}`);
 	}
 
 	if (!result.answer && result.results.length === 0) {

package/extensions/wechat/README.md

@@ -516,7 +516,7 @@ status, which is what the old start/stop guidance used to do.
 | `lock.ts` | Poller lockfile. |
 | `format.ts` | Sanitize, chunk, and label helpers (text only). |
 | `notices.ts` | The peer-facing notice catalog: one line per kind, in the peer's language. |
-| `errors.ts` | `messageOf`, the one error-to-line helper every notice and tool error uses. |
+| `errors.ts` | Re-exports `messageOf` from `lib/errors.ts`, the one error-to-line helper every notice and tool error uses. |
 | `timer.ts` | The timer seam: the cancellable one-shot `ArmTimer`, `defaultTimer`, and the abortable `defaultSleep`. |
 | `interaction.ts` | The WeChat `InteractionChannel`: pending-prompt state machine and reply routing. |
 | `prompt.ts` | Pure prompt formatting and reply parsing. |

package/extensions/wechat/client.ts

@@ -421,6 +421,29 @@ export class WechatClient {
 	}
 }
 
+/** A response body's rejection: the code it reported and the server's own description. */
+export interface Rejection {
+	/** The non-zero `ret`, or the `errcode` when `ret` is zero or absent. */
+	code: number;
+	/** The server's `errmsg`, when it sent one. */
+	detail?: string;
+}
+
+/**
+ * The body-level rejection a response carries, or `undefined` when it was
+ * accepted.
+ *
+ * A body may carry `ret: 0` plus a real `errcode`, so the non-zero value wins:
+ * reporting `ret 0` would hide the actual reason. The server's `errmsg` is the
+ * only way to tell a bad token from a rate limit, so it travels with the code.
+ */
+export function rejectionOf(response: { ret?: number; errcode?: number; errmsg?: string }): Rejection | undefined {
+	const ret = response.ret ?? 0;
+	const errcode = response.errcode ?? 0;
+	if (ret === 0 && errcode === 0) return undefined;
+	return { code: ret !== 0 ? ret : errcode, detail: response.errmsg };
+}
+
 /** True when a response reports an expired bot token. */
 export function isSessionExpired(response: { ret?: number; errcode?: number }): boolean {
 	return response.ret === SESSION_EXPIRED || response.errcode === SESSION_EXPIRED;