@xynogen/pix-9router 0.1.0 → 0.2.0

package/package.json

@@ -1,40 +1,47 @@
 {
-  "name": "@xynogen/pix-9router",
-  "version": "0.1.0",
-  "description": "Pi extension — 9Router provider + fetch/search tools via router API",
-  "type": "module",
-  "main": "src/index.ts",
-  "scripts": {
-    "test": "bun test"
-  },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "pi": {
-    "extensions": ["src/index.ts"]
-  },
-  "keywords": ["pi", "pi-package", "pi-extension", "9router"],
-  "author": "xynogen",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/xynogen/pix-mono.git",
-    "directory": "packages/pix-9router"
-  },
-  "homepage": "https://github.com/xynogen/pix-mono/tree/main/packages/pix-9router#readme",
-  "bugs": {
-    "url": "https://github.com/xynogen/pix-mono/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-ai": "*"
-  },
-  "dependencies": {
-    "typebox": "^1.1.38"
-  }
+	"name": "@xynogen/pix-9router",
+	"version": "0.2.0",
+	"description": "Pi extension — 9Router provider + fetch/search tools via router API",
+	"type": "module",
+	"main": "src/index.ts",
+	"scripts": {
+		"test": "bun test"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"src/index.ts"
+		]
+	},
+	"keywords": [
+		"pi",
+		"pi-package",
+		"pi-extension",
+		"9router"
+	],
+	"author": "xynogen",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/xynogen/pix-mono.git",
+		"directory": "packages/pix-9router"
+	},
+	"homepage": "https://github.com/xynogen/pix-mono/tree/main/packages/pix-9router#readme",
+	"bugs": {
+		"url": "https://github.com/xynogen/pix-mono/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-ai": "*"
+	},
+	"dependencies": {
+		"typebox": "^1.1.38"
+	}
 }

package/src/data.test.ts

@@ -1,10 +1,10 @@
-import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
 import {
-	routerBaseUrl,
 	buildModelsDevIndex,
 	lookupInIndex,
 	type ModelsDevApi,
 	type ModelsDevModel,
+	routerBaseUrl,
 } from "./data.ts";
 
 // ── routerBaseUrl ────────────────────────────────────────────────────────────

package/src/data.ts

@@ -13,8 +13,8 @@
  *   ROUTER_API_KEY   — bearer token (required)
  */
 
-import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -38,10 +38,18 @@ export interface ModelsDevModel {
 	reasoning?: boolean;
 	modalities?: { input?: string[]; output?: string[] };
 	limit?: { context?: number; output?: number };
-	cost?: { input?: number; output?: number; cache_read?: number; cache_write?: number };
+	cost?: {
+		input?: number;
+		output?: number;
+		cache_read?: number;
+		cache_write?: number;
+	};
 }
 
-export type ModelsDevApi = Record<string, { models?: Record<string, ModelsDevModel> }>;
+export type ModelsDevApi = Record<
+	string,
+	{ models?: Record<string, ModelsDevModel> }
+>;
 
 interface RouterModelsResponse {
 	data?: RouterModel[];
@@ -79,7 +87,9 @@ class DataSource<T> {
 
 	async get(): Promise<T> {
 		if (this._inflight) return this._inflight;
-		this._inflight = this._load().finally(() => { this._inflight = null; });
+		this._inflight = this._load().finally(() => {
+			this._inflight = null;
+		});
 		return this._inflight;
 	}
 
@@ -87,7 +97,9 @@ class DataSource<T> {
 		if (this._mem) return this._mem;
 		try {
 			if (existsSync(this.opts.cachePath)) {
-				const raw = JSON.parse(readFileSync(this.opts.cachePath, "utf-8")) as { data: unknown };
+				const raw = JSON.parse(readFileSync(this.opts.cachePath, "utf-8")) as {
+					data: unknown;
+				};
 				this._mem = this.opts.parseCache(raw.data);
 				return this._mem;
 			}
@@ -98,7 +110,10 @@ class DataSource<T> {
 	}
 
 	private async _load(): Promise<T> {
-		if (this.opts.skip()) { this._mem = this.opts.empty; return this.opts.empty; }
+		if (this.opts.skip()) {
+			this._mem = this.opts.empty;
+			return this.opts.empty;
+		}
 		const cached = await this._readCache();
 		if (cached !== undefined && Date.now() - cached.ts < this.opts.ttlMs) {
 			const val = this.opts.parseCache(cached.data);
@@ -106,11 +121,16 @@ class DataSource<T> {
 			return val;
 		}
 		try {
-			const url = typeof this.opts.url === "function" ? this.opts.url() : this.opts.url;
+			const url =
+				typeof this.opts.url === "function" ? this.opts.url() : this.opts.url;
 			const controller = new AbortController();
 			const timer = setTimeout(() => controller.abort(), this.opts.timeoutMs);
-			const response = await fetch(url, { signal: controller.signal, headers: this.opts.headers() }).finally(() => clearTimeout(timer));
-			if (!response.ok) throw new Error(`${this.opts.label} fetch failed: ${response.status}`);
+			const response = await fetch(url, {
+				signal: controller.signal,
+				headers: this.opts.headers(),
+			}).finally(() => clearTimeout(timer));
+			if (!response.ok)
+				throw new Error(`${this.opts.label} fetch failed: ${response.status}`);
 			const raw = await response.json();
 			const val = this.opts.parse(raw);
 			this._mem = val;
@@ -119,7 +139,9 @@ class DataSource<T> {
 		} catch (error) {
 			const msg = error instanceof Error ? error.message : String(error);
 			if (cached !== undefined) {
-				console.warn(`${this.opts.label} fetch failed, using stale cache: ${msg}`);
+				console.warn(
+					`${this.opts.label} fetch failed, using stale cache: ${msg}`,
+				);
 				const val = this.opts.parseCache(cached.data);
 				this._mem = val;
 				return val;
@@ -129,19 +151,26 @@ class DataSource<T> {
 		}
 	}
 
-	private async _readCache(): Promise<{ ts: number; data: unknown } | undefined> {
+	private async _readCache(): Promise<
+		{ ts: number; data: unknown } | undefined
+	> {
 		try {
 			const raw = await readFile(this.opts.cachePath, "utf8");
 			const parsed = JSON.parse(raw) as { ts: number; data: unknown };
 			if (typeof parsed.ts !== "number") return undefined;
 			return parsed;
-		} catch { return undefined; }
+		} catch {
+			return undefined;
+		}
 	}
 
 	private async _writeCache(data: unknown): Promise<void> {
 		try {
 			await mkdir(dirname(this.opts.cachePath), { recursive: true });
-			await writeFile(this.opts.cachePath, JSON.stringify({ ts: Date.now(), data }));
+			await writeFile(
+				this.opts.cachePath,
+				JSON.stringify({ ts: Date.now(), data }),
+			);
 		} catch {
 			// Write failure is non-fatal
 		}
@@ -150,12 +179,18 @@ class DataSource<T> {
 
 // ── Constants ──────────────────────────────────────────────────────────────────
 
-const CACHE_DIR = join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "pi");
+const CACHE_DIR = join(
+	process.env.XDG_CACHE_HOME || join(homedir(), ".cache"),
+	"pi",
+);
 
 const ROUTER_DEFAULT_BASE = "https://9router.example.com/v1";
 
 export function routerBaseUrl(): string {
-	return (process.env.ROUTER_API_BASE || ROUTER_DEFAULT_BASE).replace(/\/$/, "");
+	return (process.env.ROUTER_API_BASE || ROUTER_DEFAULT_BASE).replace(
+		/\/$/,
+		"",
+	);
 }
 
 // ── Router models ──────────────────────────────────────────────────────────────
@@ -170,8 +205,12 @@ export const routerModels = new DataSource<RouterModel[]>({
 	skip: () => !process.env.ROUTER_API_KEY,
 	cachePath: join(CACHE_DIR, "9router.json"),
 	ttlMs: 30 * 60 * 1000, // 30 minutes
-	parse: (raw) => ((raw as RouterModelsResponse).data ?? []).filter((m) => Boolean(m.id)),
-	parseCache: (data) => ((data as RouterModelsResponse | undefined)?.data ?? []).filter((m) => Boolean(m.id)),
+	parse: (raw) =>
+		((raw as RouterModelsResponse).data ?? []).filter((m) => Boolean(m.id)),
+	parseCache: (data) =>
+		((data as RouterModelsResponse | undefined)?.data ?? []).filter((m) =>
+			Boolean(m.id),
+		),
 	empty: [],
 });
 
@@ -187,7 +226,10 @@ const modelsDevCache = new DataSource<ModelsDevApi>({
 });
 
 function normalize(id: string): string {
-	return id.toLowerCase().replace(/[:@].*$/, "").replace(/-\d{8}$/, "");
+	return id
+		.toLowerCase()
+		.replace(/[:@].*$/, "")
+		.replace(/-\d{8}$/, "");
 }
 
 function stripPrefix(id: string): string {
@@ -195,7 +237,9 @@ function stripPrefix(id: string): string {
 	return i >= 0 ? id.slice(i + 1) : id;
 }
 
-export function buildModelsDevIndex(api: ModelsDevApi): Map<string, ModelsDevModel> {
+export function buildModelsDevIndex(
+	api: ModelsDevApi,
+): Map<string, ModelsDevModel> {
 	const index = new Map<string, ModelsDevModel>();
 	for (const provider of Object.values(api)) {
 		if (!provider?.models) continue;
@@ -209,7 +253,10 @@ export function buildModelsDevIndex(api: ModelsDevApi): Map<string, ModelsDevMod
 	return index;
 }
 
-export function lookupInIndex(id: string, index: Map<string, ModelsDevModel>): ModelsDevModel | undefined {
+export function lookupInIndex(
+	id: string,
+	index: Map<string, ModelsDevModel>,
+): ModelsDevModel | undefined {
 	const stripped = stripPrefix(id);
 	const direct = index.get(stripped) ?? index.get(normalize(stripped));
 	if (direct) return direct;
@@ -220,6 +267,8 @@ export function lookupInIndex(id: string, index: Map<string, ModelsDevModel>): M
 	return undefined;
 }
 
-export async function fetchModelsDevIndex(): Promise<Map<string, ModelsDevModel>> {
+export async function fetchModelsDevIndex(): Promise<
+	Map<string, ModelsDevModel>
+> {
 	return buildModelsDevIndex(await modelsDevCache.get());
 }

package/src/fetch.ts

@@ -6,11 +6,12 @@
  *   ROUTER_API_KEY   — bearer token for the router
  */
 
-import { execFile } from "node:child_process";
+import { type ExecFileException, execFile } from "node:child_process";
+import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { StringEnum } from "@earendil-works/pi-ai";
 import { routerBaseUrl } from "./data.js";
+import { makeRenderCall, makeRenderResult } from "./render.js";
 
 const REQUEST_TIMEOUT_MS = 30_000;
 
@@ -59,9 +60,10 @@ function curl(args: string[]): Promise<string> {
 			{ maxBuffer: 10 * 1024 * 1024, timeout: 30_000 },
 			(err, stdout, stderr) => {
 				if (err) {
-					const msg = (err as NodeJS.ErrnoException).killed
+					const e = err as ExecFileException;
+					const msg = e.killed
 						? "curl timed out"
-						: `curl exit ${(err as NodeJS.ErrnoException).code ?? "??"}: ${stderr.slice(0, 300)}`;
+						: `curl exit ${e.code ?? "??"}: ${stderr.slice(0, 300)}`;
 					reject(new Error(msg));
 					return;
 				}
@@ -71,6 +73,39 @@ function curl(args: string[]): Promise<string> {
 	});
 }
 
+/**
+ * Extract readable page content from the exa fetch JSON envelope.
+ * Shape: { provider, url, title, content: { format, text }, ... }
+ * Falls back to the raw string when it isn't the expected JSON shape.
+ */
+export function formatFetchResult(raw: string): string {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return raw;
+	}
+	if (typeof parsed !== "object" || parsed === null) return raw;
+
+	const obj = parsed as {
+		title?: string | null;
+		url?: string | null;
+		content?: { text?: string | null } | string | null;
+	};
+
+	const text =
+		typeof obj.content === "string"
+			? obj.content
+			: (obj.content?.text ?? undefined);
+	if (typeof text !== "string") return raw;
+
+	const header: string[] = [];
+	if (obj.title) header.push(`# ${obj.title}`);
+	if (obj.url) header.push(`URL: ${obj.url}`);
+
+	return header.length > 0 ? `${header.join("\n")}\n\n${text}` : text;
+}
+
 export default function registerFetch(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "fetch",
@@ -85,6 +120,8 @@ export default function registerFetch(pi: ExtensionAPI): void {
 			"Set max_characters to cap response size (default 1000, 0 = unlimited). Use 5000-10000 for typical pages.",
 			"Always prefer fetch over raw curl/browser for reading page content.",
 		],
+		renderCall: makeRenderCall("fetch", (args) => String(args.url ?? "")),
+		renderResult: makeRenderResult(),
 		parameters: Type.Object({
 			url: Type.String({ description: "URL to fetch" }),
 			format: StringEnum(["markdown", "text", "html"] as const, {
@@ -108,6 +145,7 @@ export default function registerFetch(pi: ExtensionAPI): void {
 					content: [
 						{ type: "text", text: `Fetching (${fmt}): ${params.url}...` },
 					],
+					details: undefined,
 				});
 
 				const raw = await apiPost(
@@ -121,17 +159,18 @@ export default function registerFetch(pi: ExtensionAPI): void {
 					signal,
 				);
 
+				const formatted = formatFetchResult(raw);
 				const truncated =
-					maxChars > 0 && raw.length > maxChars
-						? raw.slice(0, maxChars) + "\n\n[truncated]"
-						: raw;
+					maxChars > 0 && formatted.length > maxChars
+						? `${formatted.slice(0, maxChars)}\n\n[truncated]`
+						: formatted;
 
 				return {
 					content: [{ type: "text", text: truncated.slice(0, 20_000) }],
 					details: {
 						source: "api",
-						chars: raw.length,
-						truncated: maxChars > 0 && raw.length > maxChars,
+						chars: formatted.length,
+						truncated: maxChars > 0 && formatted.length > maxChars,
 					},
 				};
 			} catch (apiErr: unknown) {
@@ -143,13 +182,14 @@ export default function registerFetch(pi: ExtensionAPI): void {
 							text: `API failed: ${apiMsg}\nFalling back to curl...`,
 						},
 					],
+					details: undefined,
 				});
 			}
 
 			try {
 				let html = await curl(["-L", params.url]);
 				if (maxChars > 0 && html.length > maxChars)
-					html = html.slice(0, maxChars) + "\n\n[truncated]";
+					html = `${html.slice(0, maxChars)}\n\n[truncated]`;
 
 				const banner =
 					"[FALLBACK — raw curl] API unavailable, content may differ from exa formatted output.";

package/src/format.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "bun:test";
+import { formatFetchResult } from "./fetch.ts";
+import { formatSearchResults } from "./search.ts";
+
+describe("formatSearchResults", () => {
+	it("formats results as a numbered markdown list", () => {
+		const raw = JSON.stringify({
+			provider: "exa",
+			query: "test",
+			results: [
+				{
+					title: "First Result",
+					url: "https://example.com/a",
+					snippet: "Some   snippet\n  text here",
+					published_at: "2026-03-04T22:36:57.000Z",
+					metadata: { author: "alice" },
+				},
+				{
+					title: "",
+					url: "https://example.com/b",
+					snippet: null,
+				},
+			],
+		});
+
+		const out = formatSearchResults(raw);
+		expect(out).toContain("1. First Result");
+		expect(out).toContain("   https://example.com/a");
+		expect(out).toContain("(alice — 2026-03-04)");
+		expect(out).toContain("Some snippet text here");
+		// untitled result falls back to url as title
+		expect(out).toContain("2. https://example.com/b");
+		// no raw JSON noise
+		expect(out).not.toContain("{");
+		expect(out).not.toContain('"provider"');
+	});
+
+	it("handles empty results", () => {
+		expect(formatSearchResults(JSON.stringify({ results: [] }))).toBe(
+			"No results.",
+		);
+	});
+
+	it("falls back to pretty JSON for unexpected shapes", () => {
+		const raw = JSON.stringify({ answer: "42" });
+		expect(formatSearchResults(raw)).toContain('"answer"');
+	});
+
+	it("returns raw string when not JSON", () => {
+		expect(formatSearchResults("plain text error")).toBe("plain text error");
+	});
+
+	it("truncates long snippets to 300 chars", () => {
+		const raw = JSON.stringify({
+			results: [
+				{ title: "T", url: "https://x.dev", snippet: "y".repeat(1000) },
+			],
+		});
+		const out = formatSearchResults(raw);
+		const snippetLine = out
+			.split("\n")
+			.find((l) => l.trimStart().startsWith("yyy"));
+		expect(snippetLine?.trim().length).toBe(300);
+	});
+});
+
+describe("formatFetchResult", () => {
+	it("extracts content.text with title/url header", () => {
+		const raw = JSON.stringify({
+			provider: "exa",
+			url: "https://example.com",
+			title: "Example Page",
+			content: { format: "markdown", text: "# Hello\n\nBody text." },
+		});
+
+		const out = formatFetchResult(raw);
+		expect(out).toBe(
+			"# Example Page\nURL: https://example.com\n\n# Hello\n\nBody text.",
+		);
+	});
+
+	it("supports content as a plain string", () => {
+		const raw = JSON.stringify({ content: "just text" });
+		expect(formatFetchResult(raw)).toBe("just text");
+	});
+
+	it("returns raw when content.text is missing", () => {
+		const raw = JSON.stringify({ status: "error" });
+		expect(formatFetchResult(raw)).toBe(raw);
+	});
+
+	it("returns raw when not JSON", () => {
+		expect(formatFetchResult("<html>raw</html>")).toBe("<html>raw</html>");
+	});
+});

package/src/index.ts

@@ -13,8 +13,8 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import registerProvider from "./provider.js";
 import registerFetch from "./fetch.js";
+import registerProvider from "./provider.js";
 import registerSearch from "./search.js";
 import registerTranscribe from "./transcribe.js";
 

package/src/provider.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "bun:test";
+import { describe, expect, it } from "bun:test";
 import type { ModelsDevModel, RouterModel } from "./data.ts";
 
 // ── Re-export internal helpers for testing via module augmentation ────────────

package/src/provider.ts

@@ -10,13 +10,13 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ModelsDevModel, RouterModel } from "./data.js";
 import {
 	fetchModelsDevIndex,
 	lookupInIndex,
 	routerBaseUrl,
 	routerModels,
 } from "./data.js";
-import type { ModelsDevModel, RouterModel } from "./data.js";
 
 const DEFAULT_CONTEXT_WINDOW = 128_000;
 const DEFAULT_MAX_TOKENS = 16_384;
@@ -106,17 +106,21 @@ export default async function registerProvider(
 		fetchModelsDevIndex().catch(() => new Map<string, ModelsDevModel>()),
 	]);
 
+	// Upstream moved OpenAI `compat` settings from the provider level to the
+	// per-model level (ProviderModelConfig.compat). Apply the same shim to every
+	// registered model.
+	const COMPAT = {
+		supportsDeveloperRole: false,
+		supportsUsageInStreaming: false,
+		maxTokensField: "max_tokens",
+	} as const;
+
 	pi.registerProvider("9router", {
 		name: "9Router",
 		baseUrl: routerBaseUrl(),
 		apiKey: "$ROUTER_API_KEY",
 		api: "openai-completions",
 		headers: { "User-Agent": "pi-coding-agent" },
-		compat: {
-			supportsDeveloperRole: false,
-			supportsUsageInStreaming: false,
-			maxTokensField: "max_tokens",
-		},
 		models: models.map((model) => {
 			const devModel = lookupInIndex(model.id!, devIndex);
 			return {
@@ -127,6 +131,7 @@ export default async function registerProvider(
 				cost: ZERO_COST,
 				contextWindow: getContextWindow(model, devModel),
 				maxTokens: getMaxTokens(model, devModel),
+				compat: COMPAT,
 			};
 		}),
 	});

package/src/render.test.ts

@@ -0,0 +1,78 @@
+import { expect, test } from "bun:test";
+import { makeRenderCall, makeRenderResult } from "./render.js";
+
+const theme = {
+	fg: (t: string, s: string) => `[${t}]${s}`,
+	bold: (s: string) => `*${s}*`,
+} as never;
+
+function stubComponent() {
+	let captured = "";
+	const component = {
+		setText: (s: string) => {
+			captured = s;
+		},
+		render: () => [],
+		invalidate: () => {},
+	};
+	return { component, get: () => captured };
+}
+
+test("renderCall shows title + accent arg", () => {
+	const stub = stubComponent();
+	const rc = makeRenderCall<{ url: string }>("fetch", (a) => a.url);
+	rc({ url: "https://x.com" }, theme, {
+		lastComponent: stub.component as never,
+		isError: false,
+	});
+	expect(stub.get()).toBe("[toolTitle]*fetch* [accent]https://x.com");
+});
+
+test("renderResult dims every line", () => {
+	const stub = stubComponent();
+	const rr = makeRenderResult();
+	rr(
+		{ content: [{ type: "text", text: "a\nb" }] } as never,
+		{ expanded: true, isPartial: false },
+		theme,
+		{ lastComponent: stub.component as never, isError: false },
+	);
+	expect(stub.get()).toBe("  [dim]a\n  [dim]b");
+});
+
+test("renderResult caps preview when not expanded", () => {
+	const stub = stubComponent();
+	const rr = makeRenderResult();
+	const body = Array.from({ length: 45 }, (_, i) => `L${i}`).join("\n");
+	rr(
+		{ content: [{ type: "text", text: body }] } as never,
+		{ expanded: false, isPartial: false },
+		theme,
+		{ lastComponent: stub.component as never, isError: false },
+	);
+	expect(stub.get()).toContain("… 5 more lines");
+});
+
+test("renderResult renders empty body marker", () => {
+	const stub = stubComponent();
+	const rr = makeRenderResult();
+	rr(
+		{ content: [{ type: "text", text: "   " }] } as never,
+		{ expanded: false, isPartial: false },
+		theme,
+		{ lastComponent: stub.component as never, isError: false },
+	);
+	expect(stub.get()).toBe("  [dim](empty)");
+});
+
+test("renderResult uses error token on failure", () => {
+	const stub = stubComponent();
+	const rr = makeRenderResult();
+	rr(
+		{ content: [{ type: "text", text: "boom" }] } as never,
+		{ expanded: false, isPartial: false },
+		theme,
+		{ lastComponent: stub.component as never, isError: true },
+	);
+	expect(stub.get()).toBe("  [error]boom");
+});

package/src/render.ts

@@ -0,0 +1,111 @@
+/**
+ * render.ts — shared dim renderers for fetch/search tool output.
+ *
+ * fetch/search return external web content the model already consumed; the
+ * full body is noise in the transcript. We render it dim (theme `dim` token)
+ * so it reads like faded reasoning — present for inspection, visually quiet.
+ * The tool title line stays normal so calls remain scannable.
+ *
+ * pi-tui's Text component is loaded via require() so the renderers degrade to
+ * the default pi renderer (undefined-safe via cast) when pi-tui is absent.
+ */
+
+import type {
+	AgentToolResult,
+	Theme,
+	ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+
+interface TextLike extends Component {
+	setText(text: string): void;
+}
+
+// ToolRenderContext is not re-exported by pi-coding-agent; model the fields the
+// renderers actually read. Structurally compatible with the SDK context.
+interface RenderCtx {
+	lastComponent: Component | undefined;
+	isError: boolean;
+}
+
+type TextCtor = new (text?: string, padX?: number, padY?: number) => TextLike;
+
+// Preview cap is intentionally generous — dimming already de-emphasises the
+// body, so we only truncate to keep pathological multi-thousand-line dumps
+// from flooding the viewport. Expanding shows everything.
+const MAX_PREVIEW_LINES = 40;
+
+let TextComponent: TextCtor | undefined;
+try {
+	TextComponent = (require("@earendil-works/pi-tui") as { Text: TextCtor })
+		.Text;
+} catch {
+	TextComponent = undefined;
+}
+
+function getText(lastComponent: Component | undefined): TextLike {
+	if (lastComponent && "setText" in lastComponent)
+		return lastComponent as TextLike;
+	// TextComponent is always present in the interactive TUI (pi-tui peer); the
+	// require() guard only matters for headless/test contexts where renderers
+	// are never invoked.
+	if (TextComponent) return new TextComponent("", 0, 0);
+	throw new Error("pi-tui Text component unavailable");
+}
+
+function firstText(result: AgentToolResult<unknown>): string {
+	const block = result.content?.find((c) => c.type === "text");
+	return (block as { text?: string } | undefined)?.text ?? "";
+}
+
+function dimBody(body: string, theme: Theme, expanded: boolean): string {
+	const lines = body.split("\n");
+	const maxShow = expanded ? lines.length : MAX_PREVIEW_LINES;
+	const shown = lines.slice(0, maxShow);
+	const out = shown.map((line) => `  ${theme.fg("dim", line)}`);
+	const remaining = lines.length - maxShow;
+	if (remaining > 0) {
+		out.push(`  ${theme.fg("dim", `… ${remaining} more lines`)}`);
+	}
+	return out.join("\n");
+}
+
+/** Build a `renderCall` that shows `<title> <accent arg>`. */
+export function makeRenderCall<TArgs>(
+	title: string,
+	pickArg: (args: TArgs) => string,
+) {
+	return (args: TArgs, theme: Theme, ctx: RenderCtx): Component => {
+		const text = getText(ctx.lastComponent);
+		const arg = pickArg(args);
+		text.setText(
+			`${theme.fg("toolTitle", theme.bold(title))} ${theme.fg("accent", arg)}`,
+		);
+		return text;
+	};
+}
+
+/** Build a `renderResult` that dims the whole result body. */
+export function makeRenderResult() {
+	return (
+		result: AgentToolResult<unknown>,
+		opts: ToolRenderResultOptions,
+		theme: Theme,
+		ctx: RenderCtx,
+	): Component => {
+		const text = getText(ctx.lastComponent);
+		const body = firstText(result);
+
+		if (ctx.isError) {
+			text.setText(`  ${theme.fg("error", body || "Error")}`);
+			return text;
+		}
+		if (!body.trim()) {
+			text.setText(`  ${theme.fg("dim", "(empty)")}`);
+			return text;
+		}
+
+		text.setText(dimBody(body, theme, opts.expanded));
+		return text;
+	};
+}

package/src/search.ts

@@ -6,11 +6,12 @@
  *   ROUTER_API_KEY   — bearer token for the router
  */
 
-import { execFile } from "node:child_process";
+import { type ExecFileException, execFile } from "node:child_process";
+import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { StringEnum } from "@earendil-works/pi-ai";
 import { routerBaseUrl } from "./data.js";
+import { makeRenderCall, makeRenderResult } from "./render.js";
 
 const REQUEST_TIMEOUT_MS = 30_000;
 
@@ -59,9 +60,10 @@ function curl(args: string[], stdin?: string): Promise<string> {
 			{ maxBuffer: 10 * 1024 * 1024, timeout: 30_000 },
 			(err, stdout, stderr) => {
 				if (err) {
-					const msg = (err as NodeJS.ErrnoException).killed
+					const e = err as ExecFileException;
+					const msg = e.killed
 						? "curl timed out"
-						: `curl exit ${(err as NodeJS.ErrnoException).code ?? "??"}: ${stderr.slice(0, 300)}`;
+						: `curl exit ${e.code ?? "??"}: ${stderr.slice(0, 300)}`;
 					reject(new Error(msg));
 					return;
 				}
@@ -75,6 +77,53 @@ function curl(args: string[], stdin?: string): Promise<string> {
 	});
 }
 
+interface SearchResultItem {
+	title?: string | null;
+	url?: string | null;
+	snippet?: string | null;
+	published_at?: string | null;
+	metadata?: { author?: string | null } | null;
+	author?: string | null;
+}
+
+/**
+ * Format a raw exa search response as a compact markdown list.
+ * Falls back to pretty-printed JSON when the shape is unexpected.
+ */
+export function formatSearchResults(raw: string): string {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return raw.slice(0, 20_000);
+	}
+
+	const obj = parsed as Record<string, unknown>;
+	const results = obj?.results;
+	if (!Array.isArray(results)) {
+		return JSON.stringify(parsed, null, 2).slice(0, 20_000);
+	}
+
+	if (results.length === 0) return "No results.";
+
+	const lines: string[] = [];
+	results.forEach((r: SearchResultItem, i: number) => {
+		const title = (r.title ?? "").trim() || r.url || "(untitled)";
+		lines.push(`${i + 1}. ${title}`);
+		if (r.url) lines.push(`   ${r.url}`);
+		const meta: string[] = [];
+		const author = r.author ?? r.metadata?.author;
+		if (author) meta.push(author);
+		if (r.published_at) meta.push(r.published_at.slice(0, 10));
+		if (meta.length > 0) lines.push(`   (${meta.join(" — ")})`);
+		const snippet = (r.snippet ?? "").trim();
+		if (snippet) lines.push(`   ${snippet.replace(/\s+/g, " ").slice(0, 300)}`);
+		lines.push("");
+	});
+
+	return lines.join("\n").trim().slice(0, 20_000);
+}
+
 export default function registerSearch(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "search",
@@ -88,6 +137,8 @@ export default function registerSearch(pi: ExtensionAPI): void {
 			"Set search_type='web' for general web results, search_type='news' for recent news articles.",
 			"Always prefer search over raw curl/browser requests for information lookup.",
 		],
+		renderCall: makeRenderCall("search", (args) => String(args.query ?? "")),
+		renderResult: makeRenderResult(),
 		parameters: Type.Object({
 			query: Type.String({ description: "Search query" }),
 			search_type: StringEnum(["web", "news"] as const, {
@@ -114,6 +165,7 @@ export default function registerSearch(pi: ExtensionAPI): void {
 							text: `Searching (${searchType}): ${params.query}...`,
 						},
 					],
+					details: undefined,
 				});
 
 				const raw = await apiPost(
@@ -127,18 +179,11 @@ export default function registerSearch(pi: ExtensionAPI): void {
 					signal,
 				);
 
-				let parsed: unknown;
-				try {
-					parsed = JSON.parse(raw);
-				} catch {
-					parsed = raw;
-				}
-
 				return {
 					content: [
 						{
 							type: "text",
-							text: JSON.stringify(parsed, null, 2).slice(0, 20_000),
+							text: formatSearchResults(raw),
 						},
 					],
 					details: { source: "api" },
@@ -152,6 +197,7 @@ export default function registerSearch(pi: ExtensionAPI): void {
 							text: `API failed: ${apiMsg}\nFalling back to curl...`,
 						},
 					],
+					details: undefined,
 				});
 			}
 
@@ -173,18 +219,11 @@ export default function registerSearch(pi: ExtensionAPI): void {
 					`${routerBaseUrl()}/search`,
 				]);
 
-				let parsed: unknown;
-				try {
-					parsed = JSON.parse(raw);
-				} catch {
-					parsed = raw;
-				}
-
 				return {
 					content: [
 						{
 							type: "text",
-							text: `[FALLBACK — curl] API called via curl instead of fetch.\n\n${JSON.stringify(parsed, null, 2).slice(0, 19_500)}`,
+							text: `[FALLBACK — curl] API called via curl instead of fetch.\n\n${formatSearchResults(raw).slice(0, 19_500)}`,
 						},
 					],
 					details: { source: "curl-fallback" },

package/src/transcribe.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "bun:test";
+import { describe, expect, it } from "bun:test";
 import { extname } from "node:path";
 
 // ── Re-export internal helpers for testing via module augmentation ────────────

package/src/transcribe.ts

@@ -11,8 +11,8 @@
  *   ROUTER_API_KEY   — bearer token for the router
  */
 
+import { type ExecFileException, execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
-import { execFile } from "node:child_process";
 import { basename, extname } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -91,9 +91,10 @@ function curl(args: string[]): Promise<string> {
 			{ maxBuffer: 10 * 1024 * 1024, timeout: REQUEST_TIMEOUT_MS },
 			(err, stdout, stderr) => {
 				if (err) {
-					const msg = (err as NodeJS.ErrnoException).killed
+					const e = err as ExecFileException;
+					const msg = e.killed
 						? "curl timed out"
-						: `curl exit ${(err as NodeJS.ErrnoException).code ?? "??"}: ${stderr.slice(0, 300)}`;
+						: `curl exit ${e.code ?? "??"}: ${stderr.slice(0, 300)}`;
 					reject(new Error(msg));
 					return;
 				}
@@ -149,6 +150,7 @@ export default function registerTranscribe(pi: ExtensionAPI): void {
 							text: `Transcribing: ${filePath} (model: ${model})...`,
 						},
 					],
+					details: undefined,
 				});
 
 				const raw = await apiMultipart(
@@ -185,6 +187,7 @@ export default function registerTranscribe(pi: ExtensionAPI): void {
 							text: `API failed: ${apiMsg}\nFalling back to curl...`,
 						},
 					],
+					details: undefined,
 				});
 			}