@xynogen/pix-9router 0.3.4 → 0.3.5

package/README.md

@@ -37,6 +37,10 @@ export ROUTER_API_KEY="your-key-here"
 - **fetch / search**: POST to `/web/fetch` and `/search` on the router (which proxies to exa). If the router is unreachable, falls back to `curl` (for `fetch`, raw URL fetch; for `search`, the same `/search` endpoint via curl). Tool output is rendered dimmed so fetched web content reads like faded context rather than primary output.
 - **transcribe**: POST to `/audio/transcriptions` (Deepgram Nova 3 by default). Accepts any audio file path; falls back to curl.
 
+## Compact results
+
+Terminal tool results collapse after the shared Pix delay into metadata-driven rows while preserving all model-visible content. Examples include `✓ fetch https://example.com · 12.4K chars · markdown`, `⚡ search “query” · 8 results · curl fallback`, and `✓ transcribe meeting.mp3 · 12.4K chars · dg/nova-3`. Failures use `✗`; cancelled or fallback outcomes use `⚡`. Running and partial updates remain live, and expanding an elapsed row restores the normal dimmed content preview without restarting its timer. Configure the behavior with `collapse.delaySec` and the `fetch`, `search`, or `transcribe` entries under `collapse.tools` in `~/.pi/agent/pix.json`.
+
 ## Full distro
 
 Source: [github.com/xynogen/pix-mono](https://github.com/xynogen/pix-mono)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-9router",
-	"version": "0.3.4",
+	"version": "0.3.5",
 	"description": "Pi extension — 9Router provider + fetch/search tools via router API",
 	"type": "module",
 	"main": "src/index.ts",
@@ -39,10 +39,12 @@
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",
-		"@earendil-works/pi-ai": "*"
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-tui": "*"
 	},
 	"dependencies": {
 		"@xynogen/pix-data": "^0.3.0",
+		"@xynogen/pix-pretty": "^1.7.21",
 		"typebox": "^1.1.38"
 	}
 }

package/src/fetch.ts

@@ -15,6 +15,36 @@ import { makeRenderCall, makeRenderResult } from "./render.js";
 
 const REQUEST_TIMEOUT_MS = 30_000;
 
+type RouterOutcome = "running" | "fallback" | "success" | "cancelled" | "error";
+type FetchFormat = "markdown" | "text" | "html";
+
+export interface FetchResultDetails {
+	_type: "fetchResult";
+	outcome: RouterOutcome;
+	url: string;
+	format: FetchFormat;
+	source?: "api" | "curl-fallback" | "failed";
+	chars?: number;
+	truncated?: boolean;
+}
+
+export interface FetchParams {
+	url: string;
+	format?: FetchFormat;
+	max_characters?: number;
+}
+
+interface FetchResult {
+	content: { type: "text"; text: string }[];
+	details: FetchResultDetails;
+	isError?: boolean;
+}
+
+interface FetchDependencies {
+	apiPost: typeof apiPost;
+	curl: typeof curl;
+}
+
 function auth(): string | undefined {
 	return process.env.ROUTER_API_KEY;
 }
@@ -101,6 +131,135 @@ export function formatFetchResult(raw: string): string {
 	return header.length > 0 ? `${header.join("\n")}\n\n${text}` : text;
 }
 
+function isCancelled(error: unknown, signal: AbortSignal | undefined): boolean {
+	return signal?.aborted === true || (error instanceof DOMException && error.name === "AbortError");
+}
+
+export async function executeFetch(
+	params: FetchParams,
+	signal?: AbortSignal,
+	onUpdate?: (result: FetchResult) => void,
+	dependencies: FetchDependencies = { apiPost, curl },
+): Promise<FetchResult> {
+	const maxChars = params.max_characters ?? 1000;
+	const fmt = params.format ?? "markdown";
+	let apiMsg = "";
+
+	try {
+		onUpdate?.({
+			content: [{ type: "text", text: `Fetching (${fmt}): ${params.url}...` }],
+			details: {
+				_type: "fetchResult",
+				outcome: "running",
+				url: params.url,
+				format: fmt,
+			},
+		});
+
+		const raw = await dependencies.apiPost(
+			"/web/fetch",
+			{
+				model: "exa",
+				url: params.url,
+				format: fmt,
+				max_characters: maxChars,
+			},
+			signal,
+		);
+
+		const formatted = formatFetchResult(raw);
+		const truncated =
+			maxChars > 0 && formatted.length > maxChars
+				? `${formatted.slice(0, maxChars)}\n\n[truncated]`
+				: formatted;
+
+		return {
+			content: [{ type: "text", text: truncated.slice(0, 20_000) }],
+			details: {
+				_type: "fetchResult",
+				outcome: "success",
+				url: params.url,
+				format: fmt,
+				source: "api",
+				chars: formatted.length,
+				truncated: maxChars > 0 && formatted.length > maxChars,
+			},
+		};
+	} catch (apiErr: unknown) {
+		apiMsg = apiErr instanceof Error ? apiErr.message : String(apiErr);
+		if (isCancelled(apiErr, signal)) {
+			return {
+				content: [{ type: "text", text: `Fetch cancelled.\nAPI: ${apiMsg}` }],
+				details: {
+					_type: "fetchResult",
+					outcome: "cancelled",
+					url: params.url,
+					format: fmt,
+				},
+			};
+		}
+		onUpdate?.({
+			content: [
+				{
+					type: "text",
+					text: `API failed: ${apiMsg}\nFalling back to curl...`,
+				},
+			],
+			details: {
+				_type: "fetchResult",
+				outcome: "running",
+				url: params.url,
+				format: fmt,
+			},
+		});
+	}
+
+	try {
+		let html = await dependencies.curl(["-L", params.url]);
+		const chars = html.length;
+		const truncated = maxChars > 0 && html.length > maxChars;
+		if (truncated) html = `${html.slice(0, maxChars)}\n\n[truncated]`;
+
+		const banner =
+			"[FALLBACK — raw curl] API unavailable, content may differ from exa formatted output.";
+		const body =
+			fmt === "html"
+				? `${banner}\n\n${html.slice(0, 19_500)}`
+				: `${banner}\n\nRaw HTML (format='${fmt}' not applied):\n\n${html.slice(0, 19_000)}`;
+
+		return {
+			content: [{ type: "text", text: body.slice(0, 20_000) }],
+			details: {
+				_type: "fetchResult",
+				outcome: "fallback",
+				url: params.url,
+				format: fmt,
+				source: "curl-fallback",
+				chars,
+				truncated,
+			},
+		};
+	} catch (curlErr: unknown) {
+		const curlMsg = curlErr instanceof Error ? curlErr.message : String(curlErr);
+		return {
+			content: [
+				{
+					type: "text",
+					text: `Fetch failed (both API and curl).\nAPI: ${apiMsg}\nCurl: ${curlMsg}`,
+				},
+			],
+			details: {
+				_type: "fetchResult",
+				outcome: "error",
+				url: params.url,
+				format: fmt,
+				source: "failed",
+			},
+			isError: true,
+		};
+	}
+}
+
 export default function registerFetch(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "fetch",
@@ -113,8 +272,35 @@ export default function registerFetch(pi: ExtensionAPI): void {
 			"Prefer format='markdown' for readable content, 'text' for plain text extraction, 'html' for raw source.",
 			"Set max_characters to cap response size (default 1000, 0 = unlimited). Use 5000-10000 for typical pages.",
 		],
-		renderCall: makeRenderCall("fetch", (args) => String(args.url ?? "")),
-		renderResult: makeRenderResult(),
+		renderCall: makeRenderCall<unknown>("fetch", (args) =>
+			String((args as Partial<FetchParams>).url ?? ""),
+		),
+		renderResult: (
+			(renderTerminal) => (result, options, theme, context) =>
+				renderTerminal(result, options, theme, {
+					...context,
+					isError: context.isError && options.expanded,
+				})
+		)(
+			makeRenderResult<FetchResultDetails>({
+				tool: "fetch",
+				target: (details) => details.url,
+				meta: (details) => {
+					if (details.outcome === "error") return "failed";
+					if (details.outcome === "cancelled") return "cancelled";
+					const chars = `${details.chars ?? 0} chars`;
+					return details.outcome === "fallback"
+						? `${chars} · curl fallback`
+						: `${chars} · ${details.format}`;
+				},
+				status: (details) =>
+					details.outcome === "error"
+						? "error"
+						: details.outcome === "fallback" || details.outcome === "cancelled"
+							? "warning"
+							: "success",
+			}),
+		),
 		parameters: Type.Object({
 			url: Type.String({ description: "URL to fetch" }),
 			format: StringEnum(["markdown", "text", "html"] as const, {
@@ -130,83 +316,7 @@ export default function registerFetch(pi: ExtensionAPI): void {
 		}),
 
 		async execute(_toolCallId, params, signal, onUpdate) {
-			const maxChars = params.max_characters ?? 1000;
-			const fmt = params.format ?? "markdown";
-			let apiMsg = "";
-
-			try {
-				onUpdate?.({
-					content: [{ type: "text", text: `Fetching (${fmt}): ${params.url}...` }],
-					details: undefined,
-				});
-
-				const raw = await apiPost(
-					"/web/fetch",
-					{
-						model: "exa",
-						url: params.url,
-						format: fmt,
-						max_characters: maxChars,
-					},
-					signal,
-				);
-
-				const formatted = formatFetchResult(raw);
-				const truncated =
-					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: formatted.length,
-						truncated: maxChars > 0 && formatted.length > maxChars,
-					},
-				};
-			} catch (apiErr: unknown) {
-				apiMsg = apiErr instanceof Error ? apiErr.message : String(apiErr);
-				onUpdate?.({
-					content: [
-						{
-							type: "text",
-							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]`;
-
-				const banner =
-					"[FALLBACK — raw curl] API unavailable, content may differ from exa formatted output.";
-				const body =
-					fmt === "html"
-						? `${banner}\n\n${html.slice(0, 19_500)}`
-						: `${banner}\n\nRaw HTML (format='${fmt}' not applied):\n\n${html.slice(0, 19_000)}`;
-
-				return {
-					content: [{ type: "text", text: body.slice(0, 20_000) }],
-					details: { source: "curl-fallback", chars: html.length },
-				};
-			} catch (curlErr: unknown) {
-				const curlMsg = curlErr instanceof Error ? curlErr.message : String(curlErr);
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Fetch failed (both API and curl).\nAPI: ${apiMsg}\nCurl: ${curlMsg}`,
-						},
-					],
-					details: { source: "failed" },
-					isError: true,
-				};
-			}
+			return executeFetch(params as FetchParams, signal, onUpdate);
 		},
 	});
 }

package/src/format.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, it } from "bun:test";
-import { formatFetchResult } from "./fetch.ts";
-import { formatSearchResults } from "./search.ts";
+import registerFetch, { executeFetch, formatFetchResult } from "./fetch.ts";
+import registerSearch, {
+	executeSearch,
+	formatSearchResults,
+	parseSearchResults,
+} from "./search.ts";
 
 describe("formatSearchResults", () => {
 	it("formats results as a numbered markdown list", () => {
@@ -35,7 +39,11 @@ describe("formatSearchResults", () => {
 		expect(out).not.toContain('"provider"');
 	});
 
-	it("handles empty results", () => {
+	it("handles empty results and reports the authoritative count", () => {
+		expect(parseSearchResults(JSON.stringify({ results: [] }))).toEqual({
+			text: "No results.",
+			count: 0,
+		});
 		expect(formatSearchResults(JSON.stringify({ results: [] }))).toBe("No results.");
 	});
 
@@ -58,6 +66,311 @@ describe("formatSearchResults", () => {
 	});
 });
 
+describe("fetch execution metadata", () => {
+	it("attaches API success metadata without changing returned content", async () => {
+		const raw = JSON.stringify({
+			url: "https://example.com",
+			content: { text: "x".repeat(120) },
+		});
+		const originalContent = [
+			{
+				type: "text" as const,
+				text: `URL: https://example.com\n\n${"x".repeat(120)}`,
+			},
+		];
+		const result = await executeFetch(
+			{ url: "https://example.com", format: "markdown", max_characters: 1000 },
+			undefined,
+			undefined,
+			{
+				apiPost: async () => raw,
+				curl: async () => {
+					throw new Error("curl should not run");
+				},
+			},
+		);
+
+		expect(result.details).toMatchObject({
+			_type: "fetchResult",
+			outcome: "success",
+			url: "https://example.com",
+			format: "markdown",
+			source: "api",
+			chars: 146,
+		});
+		expect(result.content).toEqual(originalContent);
+	});
+
+	it("reports curl fallback metadata while preserving the fallback banner", async () => {
+		const result = await executeFetch(
+			{ url: "https://example.com", format: "html", max_characters: 1000 },
+			undefined,
+			undefined,
+			{
+				apiPost: async () => {
+					throw new Error("API unavailable");
+				},
+				curl: async () => "<p>fallback</p>",
+			},
+		);
+
+		expect(result.details).toMatchObject({
+			_type: "fetchResult",
+			outcome: "fallback",
+			source: "curl-fallback",
+			chars: 15,
+		});
+		expect(result.content[0]?.text).toContain("[FALLBACK — raw curl]");
+	});
+
+	it("returns a structured failure when both sources fail", async () => {
+		const result = await executeFetch(
+			{ url: "https://example.com", format: "text" },
+			undefined,
+			undefined,
+			{
+				apiPost: async () => {
+					throw new Error("api boom");
+				},
+				curl: async () => {
+					throw new Error("curl boom");
+				},
+			},
+		);
+
+		expect(result.isError).toBe(true);
+		expect(result.details).toMatchObject({
+			_type: "fetchResult",
+			outcome: "error",
+			source: "failed",
+		});
+		expect(result.content[0]?.text).toContain("API: api boom");
+		expect(result.content[0]?.text).toContain("Curl: curl boom");
+	});
+
+	it("does not attempt curl after caller cancellation", async () => {
+		const controller = new AbortController();
+		controller.abort();
+		let curlCalls = 0;
+		const result = await executeFetch(
+			{ url: "https://example.com", format: "markdown" },
+			controller.signal,
+			undefined,
+			{
+				apiPost: async () => {
+					throw new DOMException("aborted", "AbortError");
+				},
+				curl: async () => {
+					curlCalls++;
+					return "unexpected";
+				},
+			},
+		);
+
+		expect(curlCalls).toBe(0);
+		expect(result.details).toMatchObject({
+			_type: "fetchResult",
+			outcome: "cancelled",
+		});
+	});
+});
+
+describe("search execution metadata", () => {
+	it("records API result count and preserves formatted content", async () => {
+		const raw = JSON.stringify({
+			results: [{ title: "One", url: "https://example.com/one" }],
+		});
+		const originalContent = [{ type: "text" as const, text: "1. One\n   https://example.com/one" }];
+		const result = await executeSearch(
+			{ query: "example", search_type: "web", max_results: 5 },
+			undefined,
+			undefined,
+			{
+				apiPost: async () => raw,
+				curl: async () => {
+					throw new Error("curl should not run");
+				},
+			},
+		);
+
+		expect(result.details).toMatchObject({
+			_type: "searchResult",
+			outcome: "success",
+			query: "example",
+			searchType: "web",
+			source: "api",
+			resultCount: 1,
+		});
+		expect(result.content).toEqual(originalContent);
+	});
+
+	it("records zero API results", async () => {
+		const result = await executeSearch(
+			{ query: "nothing", search_type: "news" },
+			undefined,
+			undefined,
+			{
+				apiPost: async () => '{"results":[]}',
+				curl: async () => "",
+			},
+		);
+		expect(result.content).toEqual([{ type: "text", text: "No results." }]);
+		expect(result.details.resultCount).toBe(0);
+	});
+
+	it("records curl fallback count and banner", async () => {
+		const result = await executeSearch(
+			{ query: "fallback", search_type: "web" },
+			undefined,
+			undefined,
+			{
+				apiPost: async () => {
+					throw new Error("api boom");
+				},
+				curl: async () => '{"results":[{"title":"A"},{"title":"B"}]}',
+			},
+		);
+		expect(result.details).toMatchObject({
+			outcome: "fallback",
+			source: "curl-fallback",
+			resultCount: 2,
+		});
+		expect(result.content[0]?.text).toContain("[FALLBACK — curl]");
+	});
+
+	it("reports both-source failure and skips fallback after abort", async () => {
+		const failed = await executeSearch(
+			{ query: "failure", search_type: "web" },
+			undefined,
+			undefined,
+			{
+				apiPost: async () => {
+					throw new Error("api boom");
+				},
+				curl: async () => {
+					throw new Error("curl boom");
+				},
+			},
+		);
+		expect(failed.isError).toBe(true);
+		expect(failed.details).toMatchObject({ outcome: "error", source: "failed" });
+
+		const controller = new AbortController();
+		controller.abort();
+		let curlCalls = 0;
+		const cancelled = await executeSearch(
+			{ query: "cancelled", search_type: "news" },
+			controller.signal,
+			undefined,
+			{
+				apiPost: async () => {
+					throw new DOMException("aborted", "AbortError");
+				},
+				curl: async () => {
+					curlCalls++;
+					return "unexpected";
+				},
+			},
+		);
+		expect(curlCalls).toBe(0);
+		expect(cancelled.details.outcome).toBe("cancelled");
+	});
+});
+
+const renderTheme = {
+	fg: (token: string, text: string) => `[${token}]${text}`,
+	bold: (text: string) => `*${text}*`,
+} as never;
+
+function renderRegisteredResult(
+	register: (pi: never) => void,
+	result: Record<string, unknown>,
+	expanded = false,
+	isError = false,
+): string {
+	let tool: { renderResult?: (...args: never[]) => unknown } | undefined;
+	register({
+		registerTool(value: { renderResult?: (...args: never[]) => unknown }) {
+			tool = value;
+		},
+	} as never);
+	let text = "";
+	const component = {
+		setText(value: string) {
+			text = value;
+		},
+		render: () => [],
+		invalidate: () => {},
+	};
+	tool?.renderResult?.(result as never, { expanded, isPartial: false } as never, renderTheme, {
+		lastComponent: component,
+		isError,
+		state: { collapsed: true },
+		expanded,
+		invalidate: () => {},
+	} as never);
+	return text;
+}
+
+describe("fetch and search compact renderers", () => {
+	it("renders fallback and failure rows from metadata", () => {
+		const fetchRow = renderRegisteredResult(registerFetch, {
+			content: [{ type: "text", text: "fallback body" }],
+			details: {
+				_type: "fetchResult",
+				outcome: "fallback",
+				url: "https://example.com",
+				format: "markdown",
+				source: "curl-fallback",
+				chars: 120,
+			},
+		});
+		expect(fetchRow).toContain("⚡");
+		expect(fetchRow).toContain("120 chars · curl fallback");
+
+		const searchRow = renderRegisteredResult(
+			registerSearch,
+			{
+				content: [{ type: "text", text: "exact API and curl diagnostics" }],
+				details: {
+					_type: "searchResult",
+					outcome: "error",
+					query: "broken query",
+					searchType: "web",
+					source: "failed",
+				},
+			},
+			false,
+			true,
+		);
+		expect(searchRow).toContain("✗");
+		expect(searchRow).toContain("“broken query”");
+		expect(searchRow).toContain("failed");
+	});
+
+	it("restores exact failure diagnostics on expansion", () => {
+		const diagnostic = "Search failed.\nAPI: unavailable\nCurl: exit 7";
+		const output = renderRegisteredResult(
+			registerSearch,
+			{
+				content: [{ type: "text", text: diagnostic }],
+				details: {
+					_type: "searchResult",
+					outcome: "error",
+					query: "broken query",
+					searchType: "web",
+					source: "failed",
+				},
+			},
+			true,
+			true,
+		);
+		expect(output).toContain("Search failed.");
+		expect(output).toContain("API: unavailable");
+		expect(output).toContain("Curl: exit 7");
+	});
+});
+
 describe("formatFetchResult", () => {
 	it("extracts content.text with title/url header", () => {
 		const raw = JSON.stringify({