@xynogen/pix-9router 0.3.3 → 0.3.5

package/src/render.test.ts

@@ -18,61 +18,150 @@ function stubComponent() {
 	return { component, get: () => captured };
 }
 
+function context(stub: ReturnType<typeof stubComponent>, overrides: Record<string, unknown> = {}) {
+	return {
+		lastComponent: stub.component as never,
+		isError: false,
+		state: {},
+		expanded: false,
+		invalidate: () => {},
+		...overrides,
+	} as never;
+}
+
+const config = {
+	tool: "fetch",
+	target: (_details: { _type: "fetchResult"; chars: number }) => "https://example.com",
+	meta: (details: { _type: "fetchResult"; chars: number }) => `${details.chars} chars`,
+};
+
 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,
-	});
+	rc({ url: "https://x.com" }, theme, context(stub));
 	expect(stub.get()).toBe("[toolTitle]*fetch* [accent]https://x.com");
 });
 
-test("renderResult dims every line", () => {
+test("renderCall hides only an effectively collapsed call row", () => {
+	const stub = stubComponent();
+	const rc = makeRenderCall<{ url: string }>("fetch", (a) => a.url);
+	rc({ url: "https://x.com" }, theme, context(stub, { state: { collapsed: true } }));
+	expect(stub.get()).toBe("");
+
+	rc(
+		{ url: "https://x.com" },
+		theme,
+		context(stub, { state: { collapsed: true }, expanded: true }),
+	);
+	expect(stub.get()).toBe("[toolTitle]*fetch* [accent]https://x.com");
+});
+
+test("renderResult renders structured compact details after collapse", () => {
+	const stub = stubComponent();
+	const rr = makeRenderResult(config);
+	rr(
+		{
+			content: [{ type: "text", text: "full body" }],
+			details: { _type: "fetchResult", chars: 9 },
+		} as never,
+		{ expanded: false, isPartial: false },
+		theme,
+		context(stub, { state: { collapsed: true } }),
+	);
+	expect(stub.get()).toContain("[success]✓");
+	expect(stub.get()).toContain("https://example.com");
+	expect(stub.get()).toContain("9 chars");
+});
+
+test("partial updates keep detail visible and do not schedule collapse", () => {
 	const stub = stubComponent();
-	const rr = makeRenderResult();
+	const state: Record<string, unknown> = {};
+	const rr = makeRenderResult(config);
 	rr(
-		{ content: [{ type: "text", text: "a\nb" }] } as never,
+		{
+			content: [{ type: "text", text: "streaming body" }],
+			details: { _type: "fetchResult", chars: 14 },
+		} as never,
+		{ expanded: false, isPartial: true },
+		theme,
+		context(stub, { state }),
+	);
+	expect(stub.get()).toContain("streaming body");
+	expect(state.timer).toBeUndefined();
+});
+
+test("expanded mode restores full joined text", () => {
+	const stub = stubComponent();
+	const rr = makeRenderResult(config);
+	rr(
+		{
+			content: [
+				{ type: "text", text: "first" },
+				{ type: "image", data: "ignored", mimeType: "image/png" },
+				{ type: "text", text: "second" },
+			],
+			details: { _type: "fetchResult", chars: 12 },
+		} as never,
 		{ expanded: true, isPartial: false },
 		theme,
-		{ lastComponent: stub.component as never, isError: false },
+		context(stub, { state: { collapsed: true }, expanded: true }),
 	);
-	expect(stub.get()).toBe("  [dim]a\n  [dim]b");
+	expect(stub.get()).toBe("  [dim]first\n  [dim]second");
 });
 
-test("renderResult caps preview when not expanded", () => {
+test("renderResult caps the normal preview", () => {
 	const stub = stubComponent();
-	const rr = makeRenderResult();
+	const rr = makeRenderResult(config);
 	const body = Array.from({ length: 37 }, (_, i) => `L${i}`).join("\n");
 	rr(
-		{ content: [{ type: "text", text: body }] } as never,
+		{
+			content: [{ type: "text", text: body }],
+			details: { _type: "fetchResult", chars: body.length },
+		} as never,
 		{ expanded: false, isPartial: false },
 		theme,
-		{ lastComponent: stub.component as never, isError: false },
+		context(stub, { state: { timer: 1 } }),
 	);
-	expect(stub.get()).toContain("… 5 more lines"); // 37 lines − 32 cap
+	expect(stub.get()).toContain("… 5 more lines");
 });
 
-test("renderResult renders empty body marker", () => {
-	const stub = stubComponent();
-	const rr = makeRenderResult();
+test("warning and error callbacks select shared status glyphs", () => {
+	for (const [status, glyph] of [
+		["warning", "⚡"],
+		["error", "✗"],
+	] as const) {
+		const stub = stubComponent();
+		const rr = makeRenderResult({ ...config, status: () => status });
+		rr(
+			{
+				content: [{ type: "text", text: "body" }],
+				details: { _type: "fetchResult", chars: 4 },
+			} as never,
+			{ expanded: false, isPartial: false },
+			theme,
+			context(stub, { state: { collapsed: true } }),
+		);
+		expect(stub.get()).toContain(`[${status}]${glyph}`);
+	}
+});
+
+test("renderResult renders empty and errors without compacting", () => {
+	const rr = makeRenderResult(config);
+	const empty = stubComponent();
 	rr(
 		{ content: [{ type: "text", text: "   " }] } as never,
 		{ expanded: false, isPartial: false },
 		theme,
-		{ lastComponent: stub.component as never, isError: false },
+		context(empty),
 	);
-	expect(stub.get()).toBe("  [dim](empty)");
-});
+	expect(empty.get()).toBe("  [dim](empty)");
 
-test("renderResult uses error token on failure", () => {
-	const stub = stubComponent();
-	const rr = makeRenderResult();
+	const failed = stubComponent();
 	rr(
 		{ content: [{ type: "text", text: "boom" }] } as never,
 		{ expanded: false, isPartial: false },
 		theme,
-		{ lastComponent: stub.component as never, isError: true },
+		context(failed, { isError: true, state: { collapsed: true } }),
 	);
-	expect(stub.get()).toBe("  [error]boom");
+	expect(failed.get()).toBe("  [error]boom");
 });

package/src/render.ts

@@ -16,6 +16,12 @@ import type {
 	ToolRenderResultOptions,
 } from "@earendil-works/pi-coding-agent";
 import type { Component } from "@earendil-works/pi-tui";
+import { type CollapseState, tickCollapse } from "@xynogen/pix-data/collapse";
+import {
+	type CollapsedToolStatus,
+	formatCollapsedToolRow,
+	hideCollapsedToolCall,
+} from "@xynogen/pix-pretty/utils";
 
 interface TextLike extends Component {
 	setText(text: string): void;
@@ -26,6 +32,16 @@ interface TextLike extends Component {
 interface RenderCtx {
 	lastComponent: Component | undefined;
 	isError: boolean;
+	state: Record<string, unknown>;
+	expanded: boolean;
+	invalidate: () => void;
+}
+
+interface CompactRendererConfig<TDetails> {
+	tool: string;
+	target: (details: TDetails) => string;
+	meta: (details: TDetails) => string;
+	status?: (details: TDetails) => CollapsedToolStatus;
 }
 
 type TextCtor = new (text?: string, padX?: number, padY?: number) => TextLike;
@@ -51,9 +67,11 @@ function getText(lastComponent: Component | undefined): TextLike {
 	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 allText(result: AgentToolResult<unknown>): string {
+	return (result.content ?? [])
+		.filter((block): block is { type: "text"; text: string } => block.type === "text")
+		.map((block) => block.text)
+		.join("\n");
 }
 
 function dimBody(body: string, theme: Theme, expanded: boolean): string {
@@ -72,14 +90,20 @@ function dimBody(body: string, theme: Theme, expanded: boolean): string {
 export function makeRenderCall<TArgs>(title: string, pickArg: (args: TArgs) => string) {
 	return (args: TArgs, theme: Theme, ctx: RenderCtx): Component => {
 		const text = getText(ctx.lastComponent);
+		if (
+			hideCollapsedToolCall(ctx.state as CollapseState, ctx.expanded, (value) =>
+				text.setText(value),
+			)
+		)
+			return text;
 		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() {
+/** Build a `renderResult` with a bounded detail preview and optional compact terminal row. */
+export function makeRenderResult<TDetails>(config?: CompactRendererConfig<TDetails>) {
 	return (
 		result: AgentToolResult<unknown>,
 		opts: ToolRenderResultOptions,
@@ -87,7 +111,7 @@ export function makeRenderResult() {
 		ctx: RenderCtx,
 	): Component => {
 		const text = getText(ctx.lastComponent);
-		const body = firstText(result);
+		const body = allText(result);
 
 		if (ctx.isError) {
 			text.setText(`  ${theme.fg("error", body || "Error")}`);
@@ -98,6 +122,25 @@ export function makeRenderResult() {
 			return text;
 		}
 
+		const details = result.details as TDetails | undefined;
+		if (
+			!opts.isPartial &&
+			config &&
+			details &&
+			tickCollapse(config.tool, ctx.state as CollapseState, ctx.invalidate, opts.expanded)
+		) {
+			text.setText(
+				formatCollapsedToolRow(
+					theme,
+					config.tool,
+					config.target(details),
+					config.meta(details),
+					config.status?.(details) ?? "success",
+				),
+			);
+			return text;
+		}
+
 		text.setText(dimBody(body, theme, opts.expanded));
 		return text;
 	};

package/src/search.ts

@@ -15,6 +15,35 @@ import { makeRenderCall, makeRenderResult } from "./render.js";
 
 const REQUEST_TIMEOUT_MS = 30_000;
 
+type RouterOutcome = "running" | "fallback" | "success" | "cancelled" | "error";
+type SearchType = "web" | "news";
+
+export interface SearchResultDetails {
+	_type: "searchResult";
+	outcome: RouterOutcome;
+	query: string;
+	searchType: SearchType;
+	source?: "api" | "curl-fallback" | "failed";
+	resultCount?: number;
+}
+
+export interface SearchParams {
+	query: string;
+	search_type?: SearchType;
+	max_results?: number;
+}
+
+interface SearchResult {
+	content: { type: "text"; text: string }[];
+	details: SearchResultDetails;
+	isError?: boolean;
+}
+
+interface SearchDependencies {
+	apiPost: typeof apiPost;
+	curl: typeof curl;
+}
+
 function auth(): string | undefined {
 	return process.env.ROUTER_API_KEY;
 }
@@ -84,25 +113,22 @@ interface SearchResultItem {
 	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 {
+/** Parse and format a raw exa search response with its authoritative result count. */
+export function parseSearchResults(raw: string): { text: string; count: number } {
 	let parsed: unknown;
 	try {
 		parsed = JSON.parse(raw);
 	} catch {
-		return raw.slice(0, 20_000);
+		return { text: raw.slice(0, 20_000), count: 0 };
 	}
 
 	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);
+		return { text: JSON.stringify(parsed, null, 2).slice(0, 20_000), count: 0 };
 	}
 
-	if (results.length === 0) return "No results.";
+	if (results.length === 0) return { text: "No results.", count: 0 };
 
 	const lines: string[] = [];
 	results.forEach((r: SearchResultItem, i: number) => {
@@ -119,7 +145,148 @@ export function formatSearchResults(raw: string): string {
 		lines.push("");
 	});
 
-	return lines.join("\n").trim().slice(0, 20_000);
+	return {
+		text: lines.join("\n").trim().slice(0, 20_000),
+		count: results.length,
+	};
+}
+
+/** Format a raw exa search response as a compact markdown list. */
+export function formatSearchResults(raw: string): string {
+	return parseSearchResults(raw).text;
+}
+
+function isCancelled(error: unknown, signal: AbortSignal | undefined): boolean {
+	return signal?.aborted === true || (error instanceof DOMException && error.name === "AbortError");
+}
+
+export async function executeSearch(
+	params: SearchParams,
+	signal?: AbortSignal,
+	onUpdate?: (result: SearchResult) => void,
+	dependencies: SearchDependencies = { apiPost, curl },
+): Promise<SearchResult> {
+	const max = Math.min(params.max_results ?? 5, 10);
+	const searchType = params.search_type ?? "web";
+	let apiMsg = "";
+
+	try {
+		onUpdate?.({
+			content: [{ type: "text", text: `Searching (${searchType}): ${params.query}...` }],
+			details: {
+				_type: "searchResult",
+				outcome: "running",
+				query: params.query,
+				searchType,
+			},
+		});
+
+		const raw = await dependencies.apiPost(
+			"/search",
+			{
+				model: "exa",
+				query: params.query,
+				search_type: searchType,
+				max_results: max,
+			},
+			signal,
+		);
+		const parsed = parseSearchResults(raw);
+
+		return {
+			content: [{ type: "text", text: parsed.text }],
+			details: {
+				_type: "searchResult",
+				outcome: "success",
+				query: params.query,
+				searchType,
+				source: "api",
+				resultCount: parsed.count,
+			},
+		};
+	} catch (apiErr: unknown) {
+		apiMsg = apiErr instanceof Error ? apiErr.message : String(apiErr);
+		if (isCancelled(apiErr, signal)) {
+			return {
+				content: [{ type: "text", text: `Search cancelled.\nAPI: ${apiMsg}` }],
+				details: {
+					_type: "searchResult",
+					outcome: "cancelled",
+					query: params.query,
+					searchType,
+				},
+			};
+		}
+		onUpdate?.({
+			content: [
+				{
+					type: "text",
+					text: `API failed: ${apiMsg}\nFalling back to curl...`,
+				},
+			],
+			details: {
+				_type: "searchResult",
+				outcome: "running",
+				query: params.query,
+				searchType,
+			},
+		});
+	}
+
+	try {
+		const body = JSON.stringify({
+			model: "exa",
+			query: params.query,
+			search_type: searchType,
+			max_results: max,
+		});
+		const raw = await dependencies.curl([
+			"-X",
+			"POST",
+			"-H",
+			"Content-Type: application/json",
+			...(auth() ? ["-H", `Authorization: Bearer ${auth()}`] : []),
+			"-d",
+			body,
+			`${routerBaseUrl()}/search`,
+		]);
+		const parsed = parseSearchResults(raw);
+
+		return {
+			content: [
+				{
+					type: "text",
+					text: `[FALLBACK — curl] API called via curl instead of fetch.\n\n${parsed.text.slice(0, 19_500)}`,
+				},
+			],
+			details: {
+				_type: "searchResult",
+				outcome: "fallback",
+				query: params.query,
+				searchType,
+				source: "curl-fallback",
+				resultCount: parsed.count,
+			},
+		};
+	} catch (curlErr: unknown) {
+		const curlMsg = curlErr instanceof Error ? curlErr.message : String(curlErr);
+		return {
+			content: [
+				{
+					type: "text",
+					text: `Search failed (both API and curl).\nAPI: ${apiMsg}\nCurl: ${curlMsg}`,
+				},
+			],
+			details: {
+				_type: "searchResult",
+				outcome: "error",
+				query: params.query,
+				searchType,
+				source: "failed",
+			},
+			isError: true,
+		};
+	}
 }
 
 export default function registerSearch(pi: ExtensionAPI): void {
@@ -133,12 +300,38 @@ export default function registerSearch(pi: ExtensionAPI): void {
 			"Use search when you need up-to-date information or facts from the web.",
 			"Set search_type='web' for general web results, search_type='news' for recent news articles.",
 		],
-		renderCall: makeRenderCall("search", (args) => String(args.query ?? "")),
-		renderResult: makeRenderResult(),
+		renderCall: makeRenderCall<unknown>("search", (args) =>
+			String((args as Partial<SearchParams>).query ?? ""),
+		),
+		renderResult: (
+			(renderTerminal) => (result, options, theme, context) =>
+				renderTerminal(result, options, theme, {
+					...context,
+					isError: context.isError && options.expanded,
+				})
+		)(
+			makeRenderResult<SearchResultDetails>({
+				tool: "search",
+				target: (details) => `“${details.query}”`,
+				meta: (details) => {
+					if (details.outcome === "error") return "failed";
+					if (details.outcome === "cancelled") return "cancelled";
+					const count = details.resultCount ?? 0;
+					return `${count} ${count === 1 ? "result" : "results"} · ${details.searchType}`;
+				},
+				status: (details) =>
+					details.outcome === "error"
+						? "error"
+						: details.outcome === "fallback" || details.outcome === "cancelled"
+							? "warning"
+							: "success",
+			}),
+		),
 		parameters: Type.Object({
 			query: Type.String({ description: "Search query" }),
 			search_type: StringEnum(["web", "news"] as const, {
-				description: "web or news search",
+				description:
+					'Required choice. Enter exactly "web" for general web results or "news" for recent news articles.',
 			}),
 			max_results: Type.Optional(
 				Type.Number({
@@ -149,94 +342,7 @@ export default function registerSearch(pi: ExtensionAPI): void {
 		}),
 
 		async execute(_toolCallId, params, signal, onUpdate) {
-			const max = Math.min(params.max_results ?? 5, 10);
-			const searchType = params.search_type ?? "web";
-			let apiMsg = "";
-
-			try {
-				onUpdate?.({
-					content: [
-						{
-							type: "text",
-							text: `Searching (${searchType}): ${params.query}...`,
-						},
-					],
-					details: undefined,
-				});
-
-				const raw = await apiPost(
-					"/search",
-					{
-						model: "exa",
-						query: params.query,
-						search_type: searchType,
-						max_results: max,
-					},
-					signal,
-				);
-
-				return {
-					content: [
-						{
-							type: "text",
-							text: formatSearchResults(raw),
-						},
-					],
-					details: { source: "api" },
-				};
-			} 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 {
-				const body = JSON.stringify({
-					model: "exa",
-					query: params.query,
-					search_type: searchType,
-					max_results: max,
-				});
-				const raw = await curl([
-					"-X",
-					"POST",
-					"-H",
-					"Content-Type: application/json",
-					...(auth() ? ["-H", `Authorization: Bearer ${auth()}`] : []),
-					"-d",
-					body,
-					`${routerBaseUrl()}/search`,
-				]);
-
-				return {
-					content: [
-						{
-							type: "text",
-							text: `[FALLBACK — curl] API called via curl instead of fetch.\n\n${formatSearchResults(raw).slice(0, 19_500)}`,
-						},
-					],
-					details: { source: "curl-fallback" },
-				};
-			} catch (curlErr: unknown) {
-				const curlMsg = curlErr instanceof Error ? curlErr.message : String(curlErr);
-				return {
-					content: [
-						{
-							type: "text",
-							text: `Search failed (both API and curl).\nAPI: ${apiMsg}\nCurl: ${curlMsg}`,
-						},
-					],
-					details: { source: "failed" },
-					isError: true,
-				};
-			}
+			return executeSearch(params as SearchParams, signal, onUpdate);
 		},
 	});
 }

package/src/tool-schema.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import registerFetch from "./fetch.ts";
+import registerSearch from "./search.ts";
+
+function captureParameters(register: (pi: never) => void): {
+	properties: Record<string, { type?: string; enum?: string[]; description?: string }>;
+} {
+	let parameters: unknown;
+	register({
+		registerTool(tool: { parameters: unknown }) {
+			parameters = tool.parameters;
+		},
+	} as never);
+	if (!parameters) throw new Error("tool parameters not captured");
+	return parameters as {
+		properties: Record<string, { type?: string; enum?: string[]; description?: string }>;
+	};
+}
+
+describe("enum-like tool parameters", () => {
+	test("search_type exposes values and their semantics", () => {
+		const searchType = captureParameters(registerSearch).properties.search_type;
+		if (!searchType) throw new Error("search_type schema not found");
+
+		expect(searchType.type).toBe("string");
+		expect(searchType.enum).toEqual(["web", "news"]);
+		expect(searchType.description).toContain('exactly "web"');
+		expect(searchType.description).toContain('"news"');
+	});
+
+	test("fetch format exposes values and their semantics", () => {
+		const format = captureParameters(registerFetch).properties.format;
+		if (!format) throw new Error("format schema not found");
+
+		expect(format.type).toBe("string");
+		expect(format.enum).toEqual(["markdown", "text", "html"]);
+		expect(format.description).toContain('exactly "markdown"');
+		expect(format.description).toContain('"html"');
+	});
+});