@xynogen/pix-9router 0.4.5 → 0.7.0

package/README.md

@@ -1,58 +1,40 @@
 # pix-9router
 
-Pi coding agent extension — **9Router provider** + **fetch**, **search**, and **transcribe** tools backed by an internal OpenAI-compatible router API.
+Pi extension with a 9Router model provider.
 
-## What's included
+Other 9Router features live in separate packages. Each one reuses
+`NINEROUTER_URL` and `NINEROUTER_KEY`:
 
-| Module | Type | Description |
-|---|---|---|
-| `provider` | provider | Registers `9router` provider with live model list from the router API |
-| `fetch` | tool | `fetch(url, format, max_characters?)` — fetches web pages via exa through the router, falls back to curl |
-| `search` | tool | `search(query, search_type, max_results?)` — web/news search via exa through the router, falls back to curl |
-| `transcribe` | tool | `transcribe(file, model?, language?)` — speech-to-text via `/audio/transcriptions` endpoint (default: `dg/nova-3`), falls back to curl |
-
-## Install
-
-```bash
-pi install npm:@xynogen/pix-9router
-```
-
-> Standalone/opt-in — **not** bundled by [`@xynogen/pix-core`](https://www.npmjs.com/package/@xynogen/pix-core). Needs a 9Router API key, so only useful if you route through 9Router.
+- Speech tools (`transcribe`, `speak`, `/stt`) moved to `@xynogen/pix-voice` in
+  0.7.0. Pick `9router` as the provider in its `/voice` command.
+- Web search and fetch live in `@xynogen/pix-web`.
 
 ## Environment
 
-| Variable | Required | Default | Description |
-|---|---|---|---|
-| `ROUTER_API_KEY` | Yes | — | Bearer token for the router API |
-| `ROUTER_API_BASE` | No | `https://9router.example.com/v1` | Override router base URL |
-
-Add to your `~/.zsh_local` (or equivalent):
+Use the upstream standard names:
 
 ```bash
-export ROUTER_API_KEY="your-key-here"
-# export ROUTER_API_BASE="https://your-router.example.com/v1"  # optional
+export NINEROUTER_URL="https://your-router.example.com"
+export NINEROUTER_KEY="your-key-here"
 ```
 
-## How it works
+Legacy aliases remain supported:
 
-- **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. 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
-
-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
+```text
+ROUTER_API_BASE
+ROUTER_API_KEY
+```
 
-Source: [github.com/xynogen/pix-mono](https://github.com/xynogen/pix-mono)
+The standard names win when both sets exist.
 
-To install the complete pix suite (all packages + Pi itself):
+## Install
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh
+pi install npm:@xynogen/pix-9router
 ```
 
+This package is standalone and opt-in. It is not bundled by `@xynogen/pix-core`.
+
 ## License
 
 MIT

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@xynogen/pix-9router",
-	"version": "0.4.5",
-	"description": "Pi extension — 9Router provider + fetch/search tools via router API",
+	"version": "0.7.0",
+	"description": "Pi extension — 9Router model provider",
 	"type": "module",
 	"main": "src/index.ts",
 	"scripts": {
@@ -44,8 +44,7 @@
 		"@earendil-works/pi-tui": "*"
 	},
 	"dependencies": {
-		"@xynogen/pix-pretty": "^1.25.0",
-		"typebox": "^1.1.38",
-		"@xynogen/pix-runtime": "^0.8.0"
+		"@xynogen/pix-data": "^0.5.1",
+		"@xynogen/pix-runtime": "^0.10.2"
 	}
 }

package/src/data.ts

@@ -11,25 +11,26 @@
  * models.dev index helpers live there — imported here, not duplicated.
  *
  * Environment:
- *   ROUTER_API_BASE  — override base URL (default: https://9router.example.com/v1)
- *   ROUTER_API_KEY   — bearer token (required)
+ *   NINEROUTER_URL   — canonical base URL
+ *   NINEROUTER_KEY   — canonical bearer token
+ *   ROUTER_API_BASE / ROUTER_API_KEY — legacy aliases
  */
 
 import { join } from "node:path";
-import { CACHE_DIR, DataSource } from "../../pix-data/src/index.ts";
+import { CACHE_DIR, DataSource } from "@xynogen/pix-data";
 
 export type {
 	ModelGrepModel,
 	ModelsDevApi,
 	ModelsDevModel,
-} from "../../pix-data/src/index.ts";
+} from "@xynogen/pix-data";
 // Re-export the shared models.dev API so existing consumers (provider.ts)
 // can keep importing these names from "./data".
 export {
 	buildModelsDevIndex,
 	fetchModelsDevIndex,
 	lookupInIndex,
-} from "../../pix-data/src/index.ts";
+} from "@xynogen/pix-data";
 
 // ── Types ─────────────────────────────────────────────────────────────────────
 
@@ -58,7 +59,9 @@ interface RouterModelsResponse {
 const ROUTER_DEFAULT_BASE = "https://9router.example.com/v1";
 
 export function routerBaseUrl(): string {
-	return (process.env.ROUTER_API_BASE || ROUTER_DEFAULT_BASE).replace(/\/$/, "");
+	const configured = process.env.NINEROUTER_URL || process.env.ROUTER_API_BASE;
+	const base = (configured || ROUTER_DEFAULT_BASE).replace(/\/$/, "");
+	return base.endsWith("/v1") ? base : `${base}/v1`;
 }
 
 // ── Router models ──────────────────────────────────────────────────────────────
@@ -67,10 +70,10 @@ export const routerModels = new DataSource<RouterModel[]>({
 	label: "9router",
 	url: () => `${routerBaseUrl()}/models`,
 	headers: () => {
-		const key = process.env.ROUTER_API_KEY;
+		const key = process.env.NINEROUTER_KEY || process.env.ROUTER_API_KEY;
 		return key ? { Authorization: `Bearer ${key}` } : undefined;
 	},
-	skip: () => !process.env.ROUTER_API_KEY,
+	skip: () => !(process.env.NINEROUTER_KEY || 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)),

package/src/index.ts

@@ -1,26 +1,19 @@
 /**
- * pix-9router — Pi extension bundle
+ * pix-9router — Pi extension
  *
- * Registers:
- *   - 9router provider  (model list from self-hosted router API)
- *   - fetch tool        (web page fetch via exa through router)
- *   - search tool       (web/news search via exa through router)
- *   - transcribe tool   (speech-to-text via audio transcription API)
+ * Registers the 9router model provider (model list from the self-hosted router API).
+ * Speech tools moved to @xynogen/pix-voice. Web search and fetch live in
+ * @xynogen/pix-web. Both reuse the same 9Router environment variables.
  *
  * Environment:
- *   ROUTER_API_BASE  — override base URL  (default: https://9router.example.com/v1)
- *   ROUTER_API_KEY   — bearer token       (required for provider + tools)
+ *   NINEROUTER_URL   — canonical base URL
+ *   NINEROUTER_KEY   — canonical bearer token
+ *   ROUTER_API_BASE / ROUTER_API_KEY — legacy aliases
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import registerFetch from "./fetch.js";
 import registerProvider from "./provider.js";
-import registerSearch from "./search.js";
-import registerTranscribe from "./transcribe.js";
 
 export default async function (pi: ExtensionAPI): Promise<void> {
 	await registerProvider(pi);
-	registerFetch(pi);
-	registerSearch(pi);
-	registerTranscribe(pi);
 }

package/src/provider.ts

@@ -97,14 +97,14 @@ export function getReasoning(model: RouterModel, devModel?: ModelsDevModel): boo
 }
 
 export default async function registerProvider(pi: ExtensionAPI): Promise<void> {
-	const apiKey = process.env.ROUTER_API_KEY;
+	const apiKey = process.env.NINEROUTER_KEY || process.env.ROUTER_API_KEY;
 
 	if (!apiKey) {
 		// Register shell provider so the name is known; no models available yet.
 		pi.registerProvider("9router", {
 			name: "9Router",
 			baseUrl: routerBaseUrl(),
-			apiKey: "$ROUTER_API_KEY",
+			apiKey: "$NINEROUTER_KEY",
 			api: "openai-completions",
 			models: [],
 		});
@@ -137,7 +137,7 @@ function providerConfig(
 	return {
 		name: "9Router",
 		baseUrl: routerBaseUrl(),
-		apiKey: "$ROUTER_API_KEY",
+		apiKey,
 		api: "openai-completions",
 		headers: { "User-Agent": "pi-coding-agent" },
 		models: models.map(toModelConfig(devIndex)),

package/src/fetch.ts

@@ -1,260 +0,0 @@
-/**
- * fetch.ts — fetch tool via 9Router API, with curl fallback.
- *
- * Environment:
- *   ROUTER_API_BASE  — router API base URL (default: https://9router.example.com/v1)
- *   ROUTER_API_KEY   — bearer token for the router
- */
-
-import { StringEnum } from "@earendil-works/pi-ai";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { apiPost, curl, isCancelled } from "./http.js";
-import { makeRenderCall, makeRenderResult } from "./render.js";
-
-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;
-}
-
-/**
- * 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 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",
-		label: "Fetch",
-		renderShell: "self",
-		description: "Fetch a web page as markdown, text, or raw HTML via exa. Returns page content.",
-		promptSnippet:
-			"fetch(url, format, max_characters?) — format: 'markdown', 'text', or 'html'. Read page content via exa.",
-		promptGuidelines: [
-			"fetch: format='markdown' for readable content, 'text' for plain extraction, 'html' for raw source. max_characters caps size (default 1000, 0 = unlimited; 5000-10000 for typical pages).",
-		],
-		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: 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)",
-					default: 1000,
-				}),
-			),
-		}),
-
-		async execute(_toolCallId, params, signal, onUpdate) {
-			return executeFetch(params as FetchParams, signal, onUpdate);
-		},
-	});
-}

package/src/http.ts

@@ -1,136 +0,0 @@
-/**
- * http.ts — shared 9Router HTTP plumbing.
- *
- * auth / apiPost / curl / isCancelled were duplicated across fetch.ts,
- * search.ts and transcribe.ts. Extracted here; the only real differences were
- * timeout values (audio needs longer) and curl stdin (search pipes a body),
- * so both are parameters with the old per-file defaults.
- */
-
-import { readFileSync } from "node:fs";
-import { basename } from "node:path";
-import { ioTimeoutMs, ioTimeoutSignal } from "@xynogen/pix-runtime/io";
-import { routerBaseUrl } from "./data.js";
-
-export function auth(): string | undefined {
-	return process.env.ROUTER_API_KEY;
-}
-
-/** POST a JSON body to a router path, returning the raw response text. */
-export async function apiPost(
-	path: string,
-	body: Record<string, unknown>,
-	signal?: AbortSignal,
-	timeoutMs: number = ioTimeoutMs(),
-): Promise<string> {
-	const url = `${routerBaseUrl()}${path}`;
-	const key = auth();
-	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 {
-	/** Request timeout in ms (default ioTimeoutMs()). */
-	timeoutMs?: number;
-	/** Optional request body (was piped to curl stdin). */
-	stdin?: string;
-}
-
-// ponytail: this is NOT a general curl shim — it parses only the flag forms the
-// three fallback call sites actually pass (-L, -X, -H, -d, -F key=value /
-// file=@path, plus the -sS/--connect-timeout/--max-time defaults added below).
-// New curl flags won't work here; extend the parser or call fetch directly.
-function curlArgsToRequest(args: string[]): { url: string; init: RequestInit } {
-	const headers = new Headers();
-	let method = "GET";
-	let body: string | undefined;
-	let form: FormData | undefined;
-	let url = "";
-	for (let i = 0; i < args.length; i++) {
-		const a = args[i] ?? "";
-		switch (a) {
-			case "-sS":
-			case "-L":
-				break; // silent / follow-redirects are fetch defaults
-			case "--connect-timeout":
-			case "--max-time":
-				i++; // value handled by AbortSignal below
-				break;
-			case "-X":
-				method = args[++i] ?? method;
-				break;
-			case "-H": {
-				const h = args[++i] ?? "";
-				const idx = h.indexOf(":");
-				if (idx >= 0) headers.set(h.slice(0, idx).trim(), h.slice(idx + 1).trim());
-				break;
-			}
-			case "-d":
-				body = args[++i] ?? "";
-				break;
-			case "-F": {
-				form ??= new FormData();
-				const field = args[++i] ?? "";
-				const eq = field.indexOf("=");
-				const key = field.slice(0, eq);
-				const val = field.slice(eq + 1);
-				if (val.startsWith("@")) {
-					const path = val.slice(1);
-					form.set(key, new Blob([readFileSync(path)]), basename(path));
-				} else {
-					form.set(key, val);
-				}
-				break;
-			}
-			default:
-				if (!a.startsWith("-")) url = a; // positional = URL
-		}
-	}
-	const init: RequestInit = { method };
-	if (form)
-		init.body = form; // let fetch set the multipart boundary
-	else if (body !== undefined) init.body = body;
-	if ([...headers.keys()].length > 0) init.headers = headers;
-	return { url, init };
-}
-
-/** Raw fetch fallback (curl-signature compatible), rejecting on non-2xx or timeout. */
-export async function curl(args: string[], opts: CurlOptions = {}): Promise<string> {
-	const timeoutMs = opts.timeoutMs ?? ioTimeoutMs();
-	const { url, init } = curlArgsToRequest(args);
-	if (opts.stdin !== undefined) init.body = opts.stdin;
-	init.signal = AbortSignal.timeout(timeoutMs);
-	let res: Response;
-	try {
-		res = await fetch(url, init);
-	} catch (err) {
-		if (err instanceof DOMException && err.name === "TimeoutError") {
-			throw new Error("curl timed out");
-		}
-		throw new Error(`curl failed: ${err instanceof Error ? err.message : String(err)}`);
-	}
-	if (!res.ok) {
-		const errText = await res.text().catch(() => "");
-		throw new Error(`curl exit ${res.status}: ${errText.slice(0, 300)}`);
-	}
-	return res.text();
-}
-
-export function isCancelled(error: unknown, signal: AbortSignal | undefined): boolean {
-	return signal?.aborted === true || (error instanceof DOMException && error.name === "AbortError");
-}