@xynogen/pix-9router 0.3.9 → 0.3.11

package/README.md

@@ -35,7 +35,7 @@ export ROUTER_API_KEY="your-key-here"
 
 - **Provider**: on load, fetches `/models` from the router and registers them with Pi. The [modelgrep](https://modelgrep.com) catalog (via [`@xynogen/pix-data`](https://github.com/xynogen/pix-mono/tree/main/packages/pix-data)'s shared cache) is used internally to fill missing context window / modality fields where the router response omits them. Model list is cached at `~/.cache/pi/9router.json` (TTL 30 min).
 - **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.
+- **transcribe**: POST to `/audio/transcriptions` (Deepgram Nova 3 by default). Accepts any audio file path; falls back to curl. Pass the optional `output_file` to write the full transcription to disk (parent dirs created, path pre-flight checked) and return only a short path summary to the model — useful for long results; without it the text is returned inline (truncated to 50,000 chars).
 
 ## Compact results
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-9router",
-	"version": "0.3.9",
+	"version": "0.3.11",
 	"description": "Pi extension — 9Router provider + fetch/search tools via router API",
 	"type": "module",
 	"main": "src/index.ts",
@@ -46,6 +46,6 @@
 		"@xynogen/pix-data": "^0.4.0",
 		"@xynogen/pix-pretty": "^1.7.21",
 		"typebox": "^1.1.38",
-		"@xynogen/pix-runtime": "^0.3.0"
+		"@xynogen/pix-runtime": "^0.4.0"
 	}
 }

package/src/fetch.ts

@@ -241,10 +241,12 @@ export default function registerFetch(pi: ExtensionAPI): void {
 		),
 		parameters: Type.Object({
 			url: Type.String({ description: "URL to fetch" }),
-			format: StringEnum(["markdown", "text", "html"] as const, {
-				description:
-					'Required choice. Enter exactly "markdown" for readable Markdown, "text" for plain text, or "html" for raw HTML.',
-			}),
+			format: Type.Optional(
+				StringEnum(["markdown", "text", "html"] as const, {
+					description:
+						'Optional choice. Enter exactly "markdown" for readable Markdown, "text" for plain text, or "html" for raw HTML. Default is "markdown".',
+				}),
+			),
 			max_characters: Type.Optional(
 				Type.Number({
 					description: "Max characters (default 1000, 0 = unlimited)",

package/src/format.test.ts

@@ -101,6 +101,30 @@ describe("fetch execution metadata", () => {
 		expect(result.content).toEqual(originalContent);
 	});
 
+	it("defaults format to markdown when omitted (schema now optional)", async () => {
+		let sentFormat: unknown;
+		const raw = JSON.stringify({ url: "https://example.com", content: { text: "hello" } });
+		const result = await executeFetch(
+			// No `format` — valid now that the schema no longer requires it.
+			{ url: "https://example.com" },
+			undefined,
+			undefined,
+			{
+				apiPost: async (_path, body) => {
+					sentFormat = (body as { format?: unknown }).format;
+					return raw;
+				},
+				curl: async () => {
+					throw new Error("curl should not run");
+				},
+			},
+		);
+
+		// The default flows through to both the API request and the metadata.
+		expect(sentFormat).toBe("markdown");
+		expect(result.details).toMatchObject({ outcome: "success", format: "markdown" });
+	});
+
 	it("reports curl fallback metadata while preserving the fallback banner", async () => {
 		const result = await executeFetch(
 			{ url: "https://example.com", format: "html", max_characters: 1000 },

package/src/http.ts

@@ -8,11 +8,9 @@
  */
 
 import { type ExecFileException, execFile } from "node:child_process";
+import { ioTimeoutMs, ioTimeoutSignal } from "@xynogen/pix-runtime/io";
 import { routerBaseUrl } from "./data.js";
 
-/** Default request timeout — audio transcription overrides with a longer one. */
-export const REQUEST_TIMEOUT_MS = 30_000;
-
 export function auth(): string | undefined {
 	return process.env.ROUTER_API_KEY;
 }
@@ -22,32 +20,27 @@ export async function apiPost(
 	path: string,
 	body: Record<string, unknown>,
 	signal?: AbortSignal,
-	timeoutMs: number = REQUEST_TIMEOUT_MS,
+	timeoutMs: number = ioTimeoutMs(),
 ): Promise<string> {
 	const url = `${routerBaseUrl()}${path}`;
 	const key = auth();
-	const controller = new AbortController();
-	const timeout = setTimeout(() => controller.abort(), timeoutMs);
-	const s = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
-
-	try {
-		const res = await fetch(url, {
-			method: "POST",
-			headers: {
-				"Content-Type": "application/json",
-				...(key ? { Authorization: `Bearer ${key}` } : {}),
-			},
-			body: JSON.stringify(body),
-			signal: s,
-		});
-		if (!res.ok) {
-			const errText = await res.text().catch(() => "");
-			throw new Error(`API ${res.status}: ${errText.slice(0, 500)}`);
-		}
-		return await res.text();
-	} finally {
-		clearTimeout(timeout);
+	const timeoutSignal =
+		timeoutMs === ioTimeoutMs() ? ioTimeoutSignal() : AbortSignal.timeout(timeoutMs);
+	const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+	const res = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			...(key ? { Authorization: `Bearer ${key}` } : {}),
+		},
+		body: JSON.stringify(body),
+		signal: requestSignal,
+	});
+	if (!res.ok) {
+		const errText = await res.text().catch(() => "");
+		throw new Error(`API ${res.status}: ${errText.slice(0, 500)}`);
 	}
+	return res.text();
 }
 
 export interface CurlOptions {
@@ -61,7 +54,9 @@ export interface CurlOptions {
 
 /** Run curl with sane defaults, rejecting on non-zero exit or timeout. */
 export function curl(args: string[], opts: CurlOptions = {}): Promise<string> {
-	const { maxTime = 25, timeoutMs = 30_000, stdin } = opts;
+	const timeoutMs = opts.timeoutMs ?? ioTimeoutMs();
+	const maxTime = opts.maxTime ?? timeoutMs / 1000;
+	const { stdin } = opts;
 	return new Promise((resolve, reject) => {
 		const child = execFile(
 			"curl",

package/src/tool-schema.test.ts

@@ -4,6 +4,7 @@ import registerSearch from "./search.ts";
 
 function captureParameters(register: (pi: never) => void): {
 	properties: Record<string, { type?: string; enum?: string[]; description?: string }>;
+	required?: string[];
 } {
 	let parameters: unknown;
 	register({
@@ -14,6 +15,7 @@ function captureParameters(register: (pi: never) => void): {
 	if (!parameters) throw new Error("tool parameters not captured");
 	return parameters as {
 		properties: Record<string, { type?: string; enum?: string[]; description?: string }>;
+		required?: string[];
 	};
 }
 
@@ -38,3 +40,21 @@ describe("enum-like tool parameters", () => {
 		expect(format.description).toContain('"html"');
 	});
 });
+
+describe("fetch parameter requiredness", () => {
+	test("only url is required; format is optional and defaults to markdown", () => {
+		const params = captureParameters(registerFetch);
+
+		// url must be required, format must NOT be — this is the exact validator
+		// bug the optionality fix addresses (executeFetch already defaults format
+		// to "markdown"), so guard against a regression back to a required format.
+		expect(params.required).toEqual(["url"]);
+		expect(params.required).not.toContain("format");
+
+		// format stays a fully described enum in properties even while optional.
+		const format = params.properties.format;
+		if (!format) throw new Error("format schema not found");
+		expect(format.enum).toEqual(["markdown", "text", "html"]);
+		expect(format.description?.toLowerCase()).toContain("default");
+	});
+});

package/src/transcribe.ts

@@ -16,12 +16,12 @@ import { access, lstat, mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, extname, isAbsolute, resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ioTimeoutSignal } from "@xynogen/pix-runtime/io";
 import { Type } from "typebox";
 import { routerBaseUrl } from "./data.js";
 import { auth, curl } from "./http.js";
 import { makeRenderCall, makeRenderResult } from "./render.js";
 
-const REQUEST_TIMEOUT_MS = 120_000; // audio transcription can take longer
 const CHAT_TRUNCATE_LIMIT = 50_000; // only when no output_file is provided
 const DEFAULT_MODEL = "dg/nova-3";
 
@@ -71,35 +71,28 @@ async function apiMultipart(
 ): Promise<string> {
 	const url = `${routerBaseUrl()}${path}`;
 	const key = auth();
-	const controller = new AbortController();
-	const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
-	const s = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
-
-	try {
-		const fileData = await readFile(filePath);
-		const blob = new Blob([fileData], { type: mimeType(filePath) });
-
-		const form = new FormData();
-		form.append("file", blob, basename(filePath));
-		form.append("model", model);
-		if (language) form.append("language", language);
-
-		const res = await fetch(url, {
-			method: "POST",
-			headers: {
-				...(key ? { Authorization: `Bearer ${key}` } : {}),
-			},
-			body: form,
-			signal: s,
-		});
-		if (!res.ok) {
-			const errText = await res.text().catch(() => "");
-			throw new Error(`API ${res.status}: ${errText.slice(0, 500)}`);
-		}
-		return await res.text();
-	} finally {
-		clearTimeout(timeout);
+	const requestSignal = ioTimeoutSignal(signal);
+	const fileData = await readFile(filePath, { signal: requestSignal });
+	const blob = new Blob([fileData], { type: mimeType(filePath) });
+
+	const form = new FormData();
+	form.append("file", blob, basename(filePath));
+	form.append("model", model);
+	if (language) form.append("language", language);
+
+	const res = await fetch(url, {
+		method: "POST",
+		headers: {
+			...(key ? { Authorization: `Bearer ${key}` } : {}),
+		},
+		body: form,
+		signal: requestSignal,
+	});
+	if (!res.ok) {
+		const errText = await res.text().catch(() => "");
+		throw new Error(`API ${res.status}: ${errText.slice(0, 500)}`);
 	}
+	return res.text();
 }
 
 /** Extract the `text` field from a JSON envelope, or return the raw string. */
@@ -448,7 +441,7 @@ export default function registerTranscribe(pi: ExtensionAPI): void {
 					`${routerBaseUrl()}/audio/transcriptions`,
 				];
 
-				const raw = await curl(curlArgs, { maxTime: 120, timeoutMs: REQUEST_TIMEOUT_MS });
+				const raw = await curl(curlArgs);
 				return await run("curl-fallback", raw);
 			} catch (curlErr: unknown) {
 				const curlMsg = curlErr instanceof Error ? curlErr.message : String(curlErr);