@oh-my-pi/pi-tui 18.2.11 → 18.3.1

package/src/tools/proc-render.ts

@@ -0,0 +1,270 @@
+import type { Component } from "../tui";
+import { Ellipsis, renderStatusLine, renderTreeList, truncateToWidth } from "../render";
+import {
+	cappedHeadLines,
+	formatBadge,
+	formatDuration,
+	formatErrorDetail,
+	formatStatusIcon,
+	PREVIEW_LIMITS,
+	TRUNCATE_LENGTHS,
+	type ToolUIColor,
+} from "../render/render-utils";
+import type { Theme } from "../theme/theme";
+import type { RenderResultOptions } from "./renderer";
+import type { AgentActivitySnapshot, CoordinationDetails, JobSnapshot } from "./wait";
+import type { IrcDeliveryReceipt } from "./irc";
+import type { DaemonSnapshot } from "./daemon";
+import { styleTerminalRow } from "./terminal-output";
+import { card, type CardToolResult as ToolResult, firstText, safe } from "./result-card";
+
+export interface ProcReadDetails {
+	jobs?: JobSnapshot[];
+	agents?: AgentActivitySnapshot[];
+	daemons?: DaemonSnapshot[];
+	job?: JobSnapshot;
+	daemon?: DaemonSnapshot;
+	log?: string;
+	terminalRows?: string[];
+}
+
+export type ProcWriteDetails =
+	| CoordinationDetails
+	| { action: "stop" | "stdin" | "mode"; daemon: DaemonSnapshot; input?: string; mode?: string };
+
+/** Process operation selected by a write URL, independent of its content. */
+export type ProcWriteAction = "stdin" | "mode" | "kill";
+
+function preview(body: string, expanded: boolean, theme: Theme, tone: "dim" | "toolOutput" = "dim"): string[] {
+	if (!body.trim()) return [];
+	const limit = expanded ? PREVIEW_LIMITS.EXPANDED_LINES : PREVIEW_LIMITS.COLLAPSED_LINES;
+	const shown = cappedHeadLines(
+		body.split("\n").filter(line => line.trim()),
+		limit,
+	);
+	const quote = theme.fg("dim", theme.md.quoteBorder);
+	const lines = shown.lines.map(
+		line =>
+			`  ${quote} ${theme.fg(tone, truncateToWidth(safe(line.trim()), TRUNCATE_LENGTHS.LINE, Ellipsis.Unicode))}`,
+	);
+	if (shown.hidden) lines.push(`  ${quote} ${theme.fg("dim", `… +${shown.hidden} more lines`)}`);
+	return lines;
+}
+
+function receiptColor(outcome: IrcDeliveryReceipt["outcome"]): ToolUIColor {
+	return outcome === "failed" ? "error" : outcome === "revived" ? "warning" : "success";
+}
+
+export function renderAgentWrite(
+	to: string,
+	body: string,
+	result: ToolResult | undefined,
+	details: CoordinationDetails | undefined,
+	options: RenderResultOptions,
+	theme: Theme,
+): Component {
+	return card((width, expanded) => {
+		const recipient = safe(details?.to || to || "…");
+		const title = `IRC ${theme.nav.selected} ${recipient}`;
+		const receipts = details?.receipts ?? [];
+		const delivered = receipts.filter(receipt => receipt.outcome !== "failed").length;
+		const failed = receipts.length - delivered;
+		const error = result?.isError || (failed > 0 && delivered === 0);
+		const meta: string[] = [];
+		if (recipient === "all") meta.push("broadcast");
+		if (receipts.length === 1) meta.push(theme.fg(receiptColor(receipts[0]!.outcome), receipts[0]!.outcome));
+		else if (receipts.length > 1) {
+			if (delivered) meta.push(theme.fg("success", `${delivered} delivered`));
+			if (failed) meta.push(theme.fg("error", `${failed} failed`));
+		}
+		const header = renderStatusLine(
+			result === undefined
+				? { icon: "pending", title, meta }
+				: error
+					? { icon: "error", title, meta }
+					: { iconOverride: theme.styledSymbol("tool.irc", "accent"), title, meta },
+			theme,
+		);
+		if (result?.isError && receipts.length === 0)
+			return [header, formatErrorDetail(firstText(result) || "Message delivery failed.", theme)];
+		const lines = [header, ...preview(body, expanded, theme)];
+		if (result && receipts.length === 0)
+			lines.push(theme.fg("muted", firstText(result) || "No live peers to broadcast to."));
+		if (receipts.length > 1 || failed > 0) {
+			lines.push(
+				...renderTreeList(
+					{
+						items: receipts,
+						expanded,
+						maxCollapsed: PREVIEW_LIMITS.COLLAPSED_ITEMS,
+						itemType: "recipient",
+						renderItem: receipt =>
+							`${theme.fg("toolOutput", safe(receipt.to))} ${formatBadge(receipt.outcome, receiptColor(receipt.outcome), theme)}${receipt.error ? ` ${theme.fg("error", `${theme.format.dash} ${safe(receipt.error)}`)}` : ""}`,
+					},
+					theme,
+				),
+			);
+		}
+		return lines.map(line => truncateToWidth(line, width, Ellipsis.Unicode));
+	}, options);
+}
+
+function daemonMeta(daemon: DaemonSnapshot, theme: Theme): string[] {
+	const stateColor =
+		daemon.state === "ready" || daemon.state === "running"
+			? "success"
+			: daemon.state === "failed"
+				? "error"
+				: "warning";
+	const meta = [theme.fg(stateColor, daemon.state)];
+	if (daemon.pid !== undefined) meta.push(`pid ${daemon.pid}`);
+	meta.push(
+		`${daemon.exitedAt === undefined ? "up" : "ran"} ${formatDuration(Math.max(0, (daemon.exitedAt ?? Date.now()) - daemon.startedAt))}`,
+	);
+	if (daemon.detached) meta.push("detached");
+	else if (daemon.persist) meta.push("persistent");
+	return meta;
+}
+
+function jobRow(job: JobSnapshot, theme: Theme): string {
+	const icon = formatStatusIcon(
+		job.status === "cancelled"
+			? "aborted"
+			: job.status === "failed"
+				? "error"
+				: job.status === "running"
+					? "running"
+					: "done",
+		theme,
+	);
+	return `${icon} ${formatBadge(job.type, job.status === "failed" ? "error" : job.status === "cancelled" ? "warning" : "accent", theme)} ${theme.fg("toolOutput", safe(job.id))} ${theme.fg("dim", safe(job.label))} ${theme.fg("dim", formatDuration(job.durationMs))}`;
+}
+
+/** Render live and completed process writes with the URL-selected operation. */
+export function renderProcWrite(
+	id: string,
+	action: ProcWriteAction,
+	content: string | undefined,
+	result: ToolResult | undefined,
+	details: ProcWriteDetails | undefined,
+	options: RenderResultOptions,
+	theme: Theme,
+): Component {
+	return card((_width, expanded) => {
+		const title = `Proc ${action} ${safe(id || "…")}`;
+		const daemon = details && "daemon" in details ? details.daemon : undefined;
+		const header = renderStatusLine(
+			{
+				icon:
+					result === undefined ? "pending" : result.isError ? "error" : action === "kill" ? "aborted" : "success",
+				title,
+				meta: daemon ? daemonMeta(daemon, theme) : action === "mode" && content ? [safe(content)] : [],
+			},
+			theme,
+		);
+		if (result?.isError) return [header, formatErrorDetail(firstText(result) || "Process operation failed.", theme)];
+		const lines = [header];
+		if (content && action === "stdin") lines.push(...preview(content, expanded, theme));
+		if (details && "op" in details && details.op === "cancel") {
+			const jobs = details.jobs ?? [];
+			const outcomes = details.cancelled ?? [];
+			lines.push(
+				...renderTreeList(
+					{
+						items: outcomes,
+						expanded,
+						maxCollapsed: PREVIEW_LIMITS.COLLAPSED_ITEMS,
+						itemType: "job",
+						renderItem: outcome => {
+							const job = jobs.find(item => item.id === outcome.id);
+							return `${job ? `${jobRow(job, theme)} ` : `${theme.fg("toolOutput", safe(outcome.id))} `}${formatBadge(outcome.status, outcome.status === "cancelled" ? "warning" : "error", theme)}`;
+						},
+					},
+					theme,
+				),
+			);
+		}
+		return lines;
+	}, options);
+}
+
+export function renderProcRead(
+	id: string,
+	result: ToolResult | undefined,
+	details: ProcReadDetails | undefined,
+	options: RenderResultOptions,
+	theme: Theme,
+): Component {
+	return card((_width, expanded) => {
+		const title = id ? `Proc ${safe(id)}` : "Proc jobs & services";
+		const daemon = details?.daemon;
+		const header = renderStatusLine(
+			{
+				icon: result === undefined ? "pending" : result.isError ? "error" : "info",
+				title,
+				meta: daemon ? daemonMeta(daemon, theme) : [],
+			},
+			theme,
+		);
+		if (result?.isError) return [header, formatErrorDetail(firstText(result) || "Process read failed.", theme)];
+		if (!result) return [header];
+		if (details?.job)
+			return [
+				header,
+				jobRow(details.job, theme),
+				...preview(
+					details.log ?? details.job.errorText ?? details.job.resultText ?? "",
+					expanded,
+					theme,
+					"toolOutput",
+				),
+			];
+		if (daemon) {
+			const output = details.terminalRows ?? (details.log ?? "").split("\n").filter(Boolean);
+			const limit = expanded ? PREVIEW_LIMITS.EXPANDED_LINES : PREVIEW_LIMITS.COLLAPSED_LINES;
+			const visible = output
+				.slice(-limit)
+				.map(
+					line =>
+						`  ${styleTerminalRow(truncateToWidth(safe(line), TRUNCATE_LENGTHS.LINE, Ellipsis.Unicode), theme.fg("toolOutput", ""))}`,
+				);
+			if (output.length > limit) visible.unshift(theme.fg("dim", `  … ${output.length - limit} earlier lines`));
+			return [header, ...visible];
+		}
+		if (id && !details?.jobs && !details?.daemons && !details?.agents) {
+			return [header, ...preview(firstText(result), expanded, theme, "toolOutput")];
+		}
+		const jobs = details?.jobs ?? [];
+		const services = details?.daemons ?? [];
+		const agents = details?.agents ?? [];
+		const meta = [
+			`${jobs.length} jobs`,
+			`${services.length} services`,
+			...(agents.length ? [`${agents.length} agents`] : []),
+		];
+		const listHeader = renderStatusLine({ icon: "info", title, meta }, theme);
+		const items = [
+			...jobs.map(job => ({ label: jobRow(job, theme) })),
+			...services.map(service => ({
+				label: `${formatBadge("service", "accent", theme)} ${theme.fg("toolOutput", safe(service.name))} ${formatBadge(service.state, service.state === "failed" ? "error" : service.state === "ready" || service.state === "running" ? "success" : "warning", theme)} ${daemonMeta(service, theme).slice(1).join(theme.sep.dot)}`,
+			})),
+			...agents.map(agent => ({
+				label: `${formatBadge("agent", agent.live ? "accent" : "warning", theme)} ${theme.fg("toolOutput", safe(agent.id))} ${theme.fg("dim", formatDuration(agent.ageMs))}`,
+			})),
+		];
+		return [
+			listHeader,
+			...renderTreeList(
+				{
+					items,
+					expanded,
+					maxCollapsed: PREVIEW_LIMITS.COLLAPSED_ITEMS,
+					itemType: "process",
+					renderItem: item => item.label,
+				},
+				theme,
+			),
+			...(items.length ? [] : [theme.fg("dim", "No background jobs or services.")]),
+		];
+	}, options);
+}

package/src/tools/read.ts

@@ -1,10 +1,12 @@
 import type { SummaryResult } from "@oh-my-pi/pi-natives";
 import { formatNumberedLine } from "./hashline-format";
 import { LINE_RANGE_CHUNK_SOURCE, parseLineRanges } from "./line-ranges";
+import * as os from "node:os";
 import * as path from "node:path";
+import { parseArchivePathCandidates } from "@oh-my-pi/pi-utils/ar";
 import type { Component } from "../tui";
 import { Text } from "../components/text";
-import type { RenderResultOptions, ToolRenderer } from "./renderer";
+import type { RenderResultOptions, ToolActivityContext, ToolActivitySummary, ToolRenderer } from "./renderer";
 import { getLanguageFromPath } from "../lang-from-path";
 import type { Theme } from "../theme/theme";
 import { fileHyperlink, renderCodeCell, renderMarkdownCell, renderStatusLine } from "../render";
@@ -16,6 +18,10 @@ import { formatBytes, sanitizeDisplayLines, shortenPath, wrapBrackets } from "..
 
 import type { OutputMeta } from "./output-meta";
 import type { TruncationResult } from "./streaming-output";
+import { renderProcRead, type ProcReadDetails } from "./proc-render";
+import { renderCfgRead, type CfgReadDetails } from "./cfg-render";
+import type { CardToolResult } from "./result-card";
+import { type InternalUrlSchemeSpec, internalUrlSchemeSpec, splitUrlScheme } from "./url-scheme-host";
 
 /** Read result metadata retains truncation statistics, not a second copy of the body. */
 export type ReadTruncationStats = Omit<TruncationResult, "content">;
@@ -23,6 +29,8 @@ export type ReadTruncationStats = Omit<TruncationResult, "content">;
 /** Display metadata for file and URL reads. */
 export interface ReadToolDetails {
 	kind?: "file" | "url";
+	proc?: ProcReadDetails;
+	cfg?: CfgReadDetails;
 	/** Filesystem hyperlink target resolved by the executing tool. */
 	displayTarget?: string;
 	truncation?: ReadTruncationStats;
@@ -75,36 +83,6 @@ const INTERNAL_URL_SELECTOR_PART_RE = new RegExp(
 	String.raw`^(?:raw|conflicts|img|${RANGE_LIST_SRC}|-\d+(?:[-+]\d+)?)$`,
 	"i",
 );
-// Schemes whose host grammar is identifier-shaped, so any trailing
-// `:<selector-chunk>` is unambiguously a read-tool selector. `mcp://` is
-// excluded because mcp resource URIs may legitimately contain colons. `ssh://`
-// is included despite an optional `:port`; `splitInternalUrlSel` skips the peel
-// for an `ssh://host:port` that has no `/path`, so the port colon is never
-// mistaken for a selector (a real ssh selector trails the `/path`, e.g.
-// `ssh://h/f:1-5`).
-const INTERNAL_SCHEMES_WITH_SELECTORS: Record<string, true> = {
-	agent: true,
-	artifact: true,
-	issue: true,
-	history: true,
-	local: true,
-	memory: true,
-	omp: true,
-	pr: true,
-	rule: true,
-	security: true,
-	skill: true,
-	ssh: true,
-	vault: true,
-};
-// Schemes whose resource URIs are server-defined and may legitimately end
-// with selector-shaped tails (e.g. `:raw`, `:conflicts`, `:1-50`, `/:raw`).
-// `McpProtocolHandler` resolves by exact URI match (`r.uri === uri`), so
-// peeling syntactically can make valid resources unreachable. Keep these
-// schemes opaque; selector support for them needs a resolver-aware path that
-// tries the exact URI before interpreting any suffix as a read selector.
-const OPAQUE_RESOURCE_SCHEMES: ReadonlySet<string> = new Set(["mcp"]);
-const INTERNAL_URL_SCHEME_RE = /^([a-z][a-z0-9+.-]*):\/\//i;
 /** Split a filesystem path from its trailing read selector. */
 export function splitPathAndSel(rawPath: string): { path: string; sel?: string } {
 	const colon = rawPath.lastIndexOf(":");
@@ -148,30 +126,28 @@ export function splitPathAndSel(rawPath: string): { path: string; sel?: string }
  * This function iteratively peels selector-shaped chunks (well-formed plus
  * common malformed shapes like `:-N-M`) so the rest of the read tool can pass a
  * clean URL to the protocol handler and surface selector errors via parseSel
- * instead of as misleading "host invalid" errors from the handler. Schemes
- * whose resource URIs may legitimately contain colons (`mcp://`) are skipped.
+ * instead of as misleading "host invalid" errors from the handler.
+ *
+ * Only schemes whose spec declares `lines` selectors peel; server-defined URIs
+ * (`opaque`), selector-free schemes, and unregistered schemes pass through
+ * verbatim. `specOf` defaults to the installed scheme host, so nothing peels
+ * before a host is installed.
  *
  * Falls back to the input unchanged when nothing matches.
  */
-
-export function splitInternalUrlSel(rawPath: string): { path: string; sel?: string } {
-	const schemeMatch = rawPath.match(INTERNAL_URL_SCHEME_RE);
-	if (!schemeMatch) return { path: rawPath };
-	const scheme = schemeMatch[1].toLowerCase();
-	// Opaque schemes (mcp://, etc.) carry server-defined resource URIs that may
-	// legitimately end in selector-shaped tails. Forward verbatim — see
-	// OPAQUE_RESOURCE_SCHEMES.
-	if (OPAQUE_RESOURCE_SCHEMES.has(scheme)) return { path: rawPath };
-	if (!INTERNAL_SCHEMES_WITH_SELECTORS[scheme]) return { path: rawPath };
-
-	const schemeEnd = schemeMatch[0].length;
-	// ssh:// authority carries an optional `:port`; with no `/path` after the
-	// authority, a trailing `:NNNN` is the port, not a read selector
-	// (e.g. ssh://host:2222). Other schemes' authority-trailing selectors
-	// (artifact://5:1-50) still peel, so this guard is ssh-specific.
-	if (scheme === "ssh" && rawPath.indexOf("/", schemeEnd) === -1) {
-		return { path: rawPath };
-	}
+export function splitInternalUrlSel(
+	rawPath: string,
+	specOf: (scheme: string) => InternalUrlSchemeSpec | undefined = internalUrlSchemeSpec,
+): { path: string; sel?: string } {
+	const url = splitUrlScheme(rawPath);
+	if (!url) return { path: rawPath };
+	const spec = specOf(url.scheme);
+	if (spec?.selectors !== "lines") return { path: rawPath };
+	// With no `/path` after the authority, a trailing `:N` is the port
+	// (ssh://host:2222), not a read selector.
+	if (spec.portAuthority && !url.rest.includes("/")) return { path: rawPath };
+
+	const schemeEnd = rawPath.length - url.rest.length;
 	let path = rawPath;
 	const chunks: string[] = [];
 	while (true) {
@@ -215,10 +191,77 @@ export interface ReadRenderArgs {
 	raw?: boolean;
 }
 
-const INTERNAL_URL_LIKE_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
+/** Transcript card for reads of a scheme with its own UI (process table, settings tree). */
+interface ReadUrlCard {
+	/** Activity label, e.g. `Process · web`. */
+	readonly label: string;
+	/** Activity detail when the URL names no target. */
+	readonly rootDetail: string;
+	/** Result details field whose presence identifies this card. */
+	readonly detailsKey: "proc" | "cfg";
+	/** Pending call card when `result` is undefined, else the finished result card. */
+	render(
+		url: string,
+		target: string,
+		result: CardToolResult | undefined,
+		details: ReadToolDetails | undefined,
+		options: RenderResultOptions,
+		uiTheme: Theme,
+	): Component;
+}
+
+/** Read cards keyed by URL scheme. */
+const READ_URL_CARDS: Record<string, ReadUrlCard> = {
+	proc: {
+		label: "Process",
+		rootDetail: "jobs & services",
+		detailsKey: "proc",
+		render: (_url, target, result, details, options, uiTheme) =>
+			renderProcRead(target, result, details?.proc, options, uiTheme),
+	},
+	cfg: {
+		label: "Config",
+		rootDetail: "all settings",
+		detailsKey: "cfg",
+		render: (url, _target, result, details, options, uiTheme) =>
+			renderCfgRead(splitInternalUrlSel(url).path, result, details?.cfg, options, uiTheme),
+	},
+};
+
+/**
+ * Card that renders a read of `rawPath` with the text after `scheme://` as its target.
+ * Result details identify the card before the URL scheme does.
+ */
+function readUrlCard(rawPath: string, details?: ReadToolDetails): { card: ReadUrlCard; target: string } | undefined {
+	const url = splitUrlScheme(rawPath);
+	const target = url?.rest ?? "";
+	if (details) {
+		for (const scheme in READ_URL_CARDS) {
+			const card = READ_URL_CARDS[scheme];
+			if (details[card.detailsKey] !== undefined) return { card, target };
+		}
+	}
+	if (!url || !Object.hasOwn(READ_URL_CARDS, url.scheme)) return undefined;
+	return { card: READ_URL_CARDS[url.scheme], target };
+}
+
+// A scheme-less host followed by a slash can be a web target. Do not force a
+// file: link onto it; explicit relative paths (./host/path) remain filesystem paths.
+const BARE_WEB_HOST_RE = /^(?:(?:[a-z][a-z0-9-]*|\[[0-9a-f:]+\])(?::\d+)|(?:[a-z0-9-]+\.)+[a-z0-9-]+(?::\d+)?)\//i;
+
+/** Local file a pending read/write input points at, before the tool resolves it:
+ * expands `~` and drops archive-member / SQLite-row selectors so the link opens
+ * the containing file. */
+export function pendingFileLinkPath(inputPath: string): string {
+	const expanded = inputPath.replace(/^~(?=$|[\\/])/, os.homedir());
+	if (!expanded.includes(":")) return path.resolve(expanded);
+	const archive = parseArchivePathCandidates(expanded).find(candidate => candidate.archivePath !== expanded);
+	const sqlite = expanded.match(/^(.+\.(?:sqlite3?|db3?))(?=[:?])/i);
+	return path.resolve(archive?.archivePath ?? sqlite?.[1] ?? expanded);
+}
 
 function splitReadRenderPath(rawPath: string): { path: string; sel?: string } {
-	if (INTERNAL_URL_LIKE_RE.test(rawPath)) {
+	if (splitUrlScheme(rawPath)) {
 		const internal = splitInternalUrlSel(rawPath);
 		if (internal.sel) return internal;
 	}
@@ -256,8 +299,14 @@ function formatReadPathLink(
 	const plainDisplayPath = options.suffixResolution
 		? shortenPath(options.suffixResolution.to)
 		: shortenPath(basePath || options.resolvedPath || options.fallbackLabel || rawPath);
-	const absoluteInputPath = path.isAbsolute(basePath) ? basePath : undefined;
-	const target = options.resolvedPath ?? options.sourcePath ?? absoluteInputPath;
+	// Calls render before the tool has resolved a filesystem target. Preserve
+	// protocol resources as plain text, but resolve direct relative file paths
+	// so terminals receive an explicit file: link rather than guessing HTTPS.
+	const inputPath =
+		basePath && !splitUrlScheme(basePath) && !BARE_WEB_HOST_RE.test(basePath)
+			? pendingFileLinkPath(basePath)
+			: undefined;
+	const target = options.resolvedPath ?? options.sourcePath ?? inputPath;
 	const line = firstReadSelectorLine(split.sel) ?? options.offset;
 	const linkOptions = line !== undefined ? { line } : undefined;
 	const linkedPath = target ? fileHyperlink(target, plainDisplayPath, linkOptions) : plainDisplayPath;
@@ -266,9 +315,19 @@ function formatReadPathLink(
 
 /** Render file, image, and URL reads in the transcript. */
 export const readToolRenderer = {
+	activitySummary(args: unknown, _context: ToolActivityContext): ToolActivitySummary {
+		const input = args as ReadRenderArgs | undefined;
+		const rawPath =
+			typeof input?.file_path === "string" ? input.file_path : typeof input?.path === "string" ? input.path : "";
+		const routed = readUrlCard(rawPath);
+		if (routed) return { label: routed.card.label, detail: routed.target || routed.card.rootDetail };
+		return { label: "Read", detail: shortenPath(rawPath) };
+	},
 	renderCall(args: ReadRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component {
 		const rawPath =
 			typeof args.file_path === "string" ? args.file_path : typeof args.path === "string" ? args.path : "";
+		const routed = readUrlCard(rawPath);
+		if (routed) return routed.card.render(rawPath, routed.target, undefined, undefined, _options, uiTheme);
 		if (isReadableUrlPath(rawPath)) {
 			return renderReadUrlCall({ path: rawPath, raw: args.raw }, _options, uiTheme);
 		}
@@ -296,6 +355,9 @@ export const readToolRenderer = {
 		const urlDetails = result.details as ReadUrlToolDetails | undefined;
 		const baseRawPathForKind =
 			typeof args?.file_path === "string" ? args.file_path : typeof args?.path === "string" ? args.path : "";
+		const routed = readUrlCard(baseRawPathForKind, result.details);
+		if (routed)
+			return routed.card.render(baseRawPathForKind, routed.target, result, result.details, options, uiTheme);
 		if (urlDetails?.kind === "url" || isReadableUrlPath(baseRawPathForKind)) {
 			return renderReadUrlResult(
 				result as {

package/src/tools/result-card.ts

@@ -0,0 +1,36 @@
+/**
+ * Line-based status cards shared by the internal-URL renderers (`proc://`,
+ * `agent://`, `cfg://`): a header plus sanitized, width-truncated body lines.
+ */
+import type { Component } from "../tui";
+import { createCachedComponent, Ellipsis, truncateToWidth } from "../render";
+import { replaceTabs } from "../render/render-utils";
+import type { RenderResultOptions } from "./renderer";
+
+/** Tool result fields the card renderers read. */
+export interface CardToolResult {
+	content: Array<{ type: string; text?: string }>;
+	isError?: boolean;
+}
+
+/** First text block of a tool result, or `""`. */
+export function firstText(result: CardToolResult): string {
+	return result.content.find(item => item.type === "text")?.text ?? "";
+}
+
+/** Sanitize one display line: tabs become spaces, carriage returns are dropped. */
+export function safe(value: string): string {
+	return replaceTabs(value).replace(/\r/g, "");
+}
+
+/** Padded card whose lines are sanitized and truncated, re-rendered when the expanded state flips. */
+export function card(lines: (width: number, expanded: boolean) => string[], options: RenderResultOptions): Component {
+	return createCachedComponent(
+		() => Boolean(options.expanded),
+		(width, expanded) =>
+			lines(width, expanded)
+				.flatMap(line => line.split("\n"))
+				.map(line => truncateToWidth(safe(line), width, Ellipsis.Unicode)),
+		{ paddingX: 1 },
+	);
+}

package/src/tools/url-scheme-host.ts

@@ -0,0 +1,42 @@
+/**
+ * Scheme facts supplied by the internal URL host. pi-tui cannot import the
+ * coding-agent router, so the router installs this bridge when it loads;
+ * selector peeling and transcript renderers consult it instead of hardcoding
+ * scheme names.
+ */
+
+/** Renderer-relevant subset of a registered scheme's declared spec. */
+export interface InternalUrlSchemeSpec {
+	/** `lines`: a trailing `:<selector>` chain is a read selector; `none`/`opaque`: never peel. */
+	readonly selectors: "lines" | "none" | "opaque";
+	/** A trailing `:N` with no path after the authority is a port, not a selector (ssh://host:2222). */
+	readonly portAuthority?: boolean;
+	/** Read cards collapse into the compact read group like plain files instead of expanding. */
+	readonly compactTranscript?: boolean;
+}
+
+/** Scheme registry capabilities installed by the internal URL host. */
+export interface InternalUrlSchemeHost {
+	/** Declared spec of a registered scheme (case-insensitive); undefined when unregistered. */
+	spec(scheme: string): InternalUrlSchemeSpec | undefined;
+}
+
+let schemeHost: InternalUrlSchemeHost | undefined;
+
+/** Install the scheme registry. Until one is installed, no URL counts as an internal scheme. */
+export function setInternalUrlSchemeHost(host: InternalUrlSchemeHost): void {
+	schemeHost = host;
+}
+
+/** Declared spec of `scheme`; undefined when it is unregistered or no host is installed. */
+export function internalUrlSchemeSpec(scheme: string): InternalUrlSchemeSpec | undefined {
+	return schemeHost?.spec(scheme);
+}
+
+const URL_SCHEME_RE = /^([a-z][a-z0-9+.-]*):\/\//i;
+
+/** Split a hierarchical `scheme://rest` URL into its lowercased scheme and the text after `://`. */
+export function splitUrlScheme(input: string): { scheme: string; rest: string } | undefined {
+	const match = URL_SCHEME_RE.exec(input);
+	return match ? { scheme: match[1].toLowerCase(), rest: input.slice(match[0].length) } : undefined;
+}