@xynogen/pix-9router 0.4.4 → 0.6.0

package/README.md

@@ -1,58 +1,64 @@
 # 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, speech-to-text, and text-to-speech tools.
 
-## What's included
+## Tools
 
-| 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 |
+| Tool | Default controlled by `/9router` |
+|---|---|
+| `transcribe` | STT model |
+| `tts` | TTS model or voice, plus automatic playback |
 
-## Install
+Tool arguments override saved defaults. Tool calls never fetch the model catalog.
+The `/9router` menu fetches live models or voices only when you open a setting,
+then saves the choice in `~/.pi/agent/9router.json`.
 
-```bash
-pi install npm:@xynogen/pix-9router
-```
+## Settings
 
-> 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.
+Run:
 
-## Environment
+```text
+/9router
+```
 
-| 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 |
+The menu controls:
 
-Add to your `~/.zsh_local` (or equivalent):
+- STT model
+- TTS model or voice
+- TTS playback (`on` by default)
 
-```bash
-export ROUTER_API_KEY="your-key-here"
-# export ROUTER_API_BASE="https://your-router.example.com/v1"  # optional
-```
+Catalogs come from `/v1/models/stt` and `/v1/models/tts`.
 
-## How it works
+Web search and fetch moved to `@xynogen/pix-web`. Its `/search` and `/fetch`
+commands include a 9Router provider that reuses `NINEROUTER_URL` and
+`NINEROUTER_KEY`.
 
-- **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).
+## Environment
+
+Use the upstream standard names:
 
-## Compact results
+```bash
+export NINEROUTER_URL="https://your-router.example.com"
+export NINEROUTER_KEY="your-key-here"
+```
 
-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`.
+Legacy aliases remain supported:
 
-## 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.4",
-	"description": "Pi extension — 9Router provider + fetch/search tools via router API",
+	"version": "0.6.0",
+	"description": "Pi extension — 9Router model provider plus audio tools",
 	"type": "module",
 	"main": "src/index.ts",
 	"scripts": {
@@ -44,8 +44,8 @@
 		"@earendil-works/pi-tui": "*"
 	},
 	"dependencies": {
-		"@xynogen/pix-pretty": "^1.19.0",
+		"@xynogen/pix-pretty": "^1.25.0",
 		"typebox": "^1.1.38",
-		"@xynogen/pix-runtime": "^0.8.0"
+		"@xynogen/pix-runtime": "^0.10.1"
 	}
 }

package/src/catalog.ts

@@ -0,0 +1,45 @@
+import { routerBaseUrl } from "./data.js";
+import { auth } from "./http.js";
+
+interface CatalogItem {
+	id?: string;
+	kind?: string;
+	model?: string;
+	name?: string;
+}
+
+async function get(path: string): Promise<unknown> {
+	const key = auth();
+	const response = await fetch(`${routerBaseUrl()}${path}`, {
+		headers: key ? { Authorization: `Bearer ${key}` } : undefined,
+	});
+	if (!response.ok) throw new Error(`9Router catalog ${response.status}`);
+	return response.json();
+}
+
+function items(value: unknown): CatalogItem[] {
+	if (!value || typeof value !== "object") return [];
+	const data = (value as { data?: unknown }).data;
+	return Array.isArray(data) ? (data as CatalogItem[]) : [];
+}
+
+export async function catalogModels(kind: "stt" | "tts"): Promise<string[]> {
+	return items(await get(`/models/${kind}`)).flatMap((item) => (item.id ? [item.id] : []));
+}
+
+export interface VoiceChoice {
+	id: string;
+	language: string;
+	provider: string;
+}
+
+export function groupVoice(id: string): VoiceChoice {
+	const [provider = "other", ...rest] = id.split("/");
+	const voice = rest.join("/") || provider;
+	const locale = voice.match(/(?:^|[^A-Za-z])([a-z]{2,3})[-_]([A-Z]{2})(?:[^A-Za-z]|$)/);
+	return { id, language: locale ? `${locale[1]}-${locale[2]}` : "Other", provider };
+}
+
+export async function catalogVoices(): Promise<VoiceChoice[]> {
+	return (await catalogModels("tts")).map(groupVoice);
+}

package/src/command.ts

@@ -0,0 +1,212 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, type SelectItem, SelectList } from "@earendil-works/pi-tui";
+import { icon } from "@xynogen/pix-pretty/icon-catalog";
+import {
+	frameModal,
+	MIN_MODAL_HEIGHT,
+	ModalPager,
+	modalOverlayOptions,
+	modalWidth,
+	selectListTheme,
+	terminalModalHeight,
+} from "@xynogen/pix-pretty/modal-frame";
+import { catalogModels, catalogVoices } from "./catalog.js";
+import { routerDefaults, saveDefaults } from "./defaults.js";
+
+async function pick(
+	ctx: ExtensionContext,
+	title: string,
+	values: string[],
+	current?: string,
+): Promise<string | undefined> {
+	const items: SelectItem[] = [...new Set(current ? [current, ...values] : values)].map(
+		(value) => ({
+			value,
+			label: value,
+			description: value === current ? "current" : undefined,
+		}),
+	);
+	if (items.length === 0) return undefined;
+
+	return (
+		(await ctx.ui.custom<string | null>(
+			(tui, theme, _keybindings, done) => {
+				const list = new SelectList(items, items.length, selectListTheme(theme));
+				const currentIndex = items.findIndex((item) => item.value === current);
+				if (currentIndex >= 0) list.setSelectedIndex(currentIndex);
+				list.onSelect = (item) => done(item.value);
+				list.onCancel = () => done(null);
+				const pager = new ModalPager();
+
+				return {
+					render(width: number) {
+						const result = frameModal({
+							width: modalWidth(width),
+							maxHeight: terminalModalHeight(tui.terminal?.rows),
+							minHeight: MIN_MODAL_HEIGHT,
+							header: [theme.fg("accent", theme.bold(title)), ""],
+							body: list.render(modalWidth(width) - 4),
+							bodyOffset: pager.bodyOffset,
+							footer: ["", theme.fg("muted", "↑↓ navigate · enter select · esc cancel")],
+							color: (text) => theme.fg("accent", text),
+							bg: (text) => theme.bg("customMessageBg", text),
+							fg: (text) => theme.fg("text", text),
+						});
+						pager.sync(result);
+						return result.lines;
+					},
+					invalidate: () => list.invalidate(),
+					handleInput(data: string) {
+						if (pager.handleInput(data, undefined, true)) tui.requestRender();
+						else if (matchesKey(data, "escape")) done(null);
+						else list.handleInput(data);
+					},
+				};
+			},
+			{ overlay: true, overlayOptions: modalOverlayOptions() },
+		)) ?? undefined
+	);
+}
+
+interface SettingRow {
+	key: string;
+	section: string;
+	label: string;
+	value: string;
+}
+
+async function pickSetting(ctx: ExtensionContext, rows: SettingRow[]): Promise<string | undefined> {
+	return (
+		(await ctx.ui.custom<string | null>(
+			(tui, theme, keybindings, done) => {
+				let selected = 0;
+				const move = (direction: -1 | 1) => {
+					selected = (selected + direction + rows.length) % rows.length;
+				};
+				return {
+					render(width: number) {
+						const labelWidth = Math.max(...rows.map((row) => row.label.length));
+						const body: string[] = [];
+						const rowLines: number[] = [];
+						let section = "";
+						for (let index = 0; index < rows.length; index++) {
+							const row = rows[index];
+							if (!row) continue;
+							if (row.section !== section) {
+								if (section) body.push("");
+								body.push(theme.fg("dim", `  ${row.section}`));
+								section = row.section;
+							}
+							const active = index === selected;
+							rowLines[index] = body.length;
+							body.push(
+								`${active ? theme.fg("accent", "→") : " "} ${theme.fg(active ? "accent" : "text", row.label.padEnd(labelWidth))}  ${theme.fg("success", row.value)}`,
+							);
+						}
+						const result = frameModal({
+							width: modalWidth(width),
+							maxHeight: terminalModalHeight(tui.terminal?.rows),
+							minHeight: MIN_MODAL_HEIGHT,
+							title: `${icon("settings")} 9Router Settings`,
+							titleColor: (text) => theme.fg("accent", theme.bold(text)),
+							header: [""],
+							body,
+							footer: ["", theme.fg("muted", "↑↓ move · enter change · esc close")],
+							selectedBodyLine: rowLines[selected],
+							color: (text) => theme.fg("accent", text),
+							bg: (text) => theme.bg("customMessageBg", text),
+						});
+						return result.lines;
+					},
+					invalidate: () => {},
+					handleInput(data: string) {
+						if (keybindings.matches(data, "tui.select.cancel")) done(null);
+						else if (keybindings.matches(data, "tui.select.up")) move(-1);
+						else if (keybindings.matches(data, "tui.select.down")) move(1);
+						else if (matchesKey(data, "enter")) done(rows[selected]?.key ?? null);
+						else if (matchesKey(data, Key.left) || matchesKey(data, Key.right))
+							done(rows[selected]?.key ?? null);
+						else return;
+						tui.requestRender();
+					},
+				};
+			},
+			{ overlay: true, overlayOptions: modalOverlayOptions() },
+		)) ?? undefined
+	);
+}
+
+async function choose(
+	ctx: ExtensionContext,
+	title: string,
+	current: string,
+	load: () => Promise<string[]>,
+): Promise<string | undefined> {
+	return pick(ctx, `${title} · current: ${current}`, await load(), current);
+}
+
+export default function registerRouterCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("9router", {
+		description: "Set default models, voice, and TTS playback",
+		handler: async (_args, ctx) => {
+			while (true) {
+				const setting = await pickSetting(ctx, [
+					{ key: "stt", section: "Audio", label: "STT model", value: routerDefaults.sttModel },
+					{
+						key: "tts",
+						section: "Audio",
+						label: "TTS voice",
+						value: routerDefaults.ttsModel,
+					},
+					{
+						key: "playback",
+						section: "Audio",
+						label: "play after generation",
+						value: routerDefaults.ttsPlay ? "on" : "off",
+					},
+				]);
+				if (!setting) return;
+
+				try {
+					let value: string | undefined;
+					if (setting === "stt") {
+						value = await choose(ctx, "STT model", routerDefaults.sttModel, () =>
+							catalogModels("stt"),
+						);
+						if (value) routerDefaults.sttModel = value;
+					} else if (setting === "tts") {
+						const voices = await catalogVoices();
+						const language = await pick(
+							ctx,
+							"TTS · 1/3 · language",
+							[...new Set(voices.map((voice) => voice.language))].sort(),
+						);
+						if (!language) continue;
+						const languageVoices = voices.filter((voice) => voice.language === language);
+						const provider = await pick(
+							ctx,
+							`TTS · 2/3 · ${language} · provider`,
+							[...new Set(languageVoices.map((voice) => voice.provider))].sort(),
+						);
+						if (!provider) continue;
+						value = await pick(
+							ctx,
+							`TTS · 3/3 · ${language} · ${provider}`,
+							languageVoices
+								.filter((voice) => voice.provider === provider)
+								.map((voice) => voice.id),
+							routerDefaults.ttsModel,
+						);
+						if (value) routerDefaults.ttsModel = value;
+					} else if (setting === "playback") {
+						value = await pick(ctx, "Play generated speech by default", ["on", "off"]);
+						if (value) routerDefaults.ttsPlay = value === "on";
+					}
+					if (value) saveDefaults(routerDefaults);
+				} catch (error) {
+					ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				}
+			}
+		},
+	});
+}

package/src/data.ts

@@ -11,8 +11,9 @@
  * 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";
@@ -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/defaults.ts

@@ -0,0 +1,44 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export interface RouterDefaults {
+	sttModel: string;
+	ttsModel: string;
+	ttsPlay: boolean;
+	sttDevice: string;
+}
+
+export const DEFAULTS_PATH = join(homedir(), ".pi", "agent", "9router.json");
+
+const FALLBACK: RouterDefaults = {
+	sttModel: "dg/nova-3",
+	ttsModel: "edge-tts/en-US-AriaNeural",
+	ttsPlay: true,
+	sttDevice: "default",
+};
+
+export function loadDefaults(path = DEFAULTS_PATH): RouterDefaults {
+	let value: unknown;
+	try {
+		value = JSON.parse(readFileSync(path, "utf8"));
+	} catch {
+		return { ...FALLBACK };
+	}
+	if (!value || typeof value !== "object") return { ...FALLBACK };
+	const item = value as Record<string, unknown>;
+	return {
+		sttModel: typeof item.sttModel === "string" ? item.sttModel : FALLBACK.sttModel,
+		ttsModel: typeof item.ttsModel === "string" ? item.ttsModel : FALLBACK.ttsModel,
+		ttsPlay: typeof item.ttsPlay === "boolean" ? item.ttsPlay : FALLBACK.ttsPlay,
+		sttDevice: typeof item.sttDevice === "string" ? item.sttDevice : FALLBACK.sttDevice,
+	};
+}
+
+export function saveDefaults(defaults: RouterDefaults, path = DEFAULTS_PATH): void {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(defaults, null, 2)}\n`, { mode: 0o600 });
+}
+
+/** Shared in-memory defaults. Tool calls never fetch the catalog. */
+export const routerDefaults = loadDefaults();

package/src/http.ts

@@ -1,47 +1,17 @@
 /**
  * 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.
+ * auth and curl serve the transcribe/tts fallback paths and the catalog reader.
+ * curl differs only by timeout (audio needs longer) and stdin 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";
+import { ioTimeoutMs } from "@xynogen/pix-runtime/io";
 
 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();
+	return process.env.NINEROUTER_KEY || process.env.ROUTER_API_KEY;
 }
 
 export interface CurlOptions {
@@ -130,7 +100,3 @@ export async function curl(args: string[], opts: CurlOptions = {}): Promise<stri
 	}
 	return res.text();
 }
-
-export function isCancelled(error: unknown, signal: AbortSignal | undefined): boolean {
-	return signal?.aborted === true || (error instanceof DOMException && error.name === "AbortError");
-}

package/src/index.ts

@@ -3,24 +3,26 @@
  *
  * 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)
+ *   - tts tool          (text-to-speech via audio speech API)
  *
  * 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 registerRouterCommand from "./command.js";
 import registerProvider from "./provider.js";
-import registerSearch from "./search.js";
+import registerSttCommand from "./stt-command.js";
 import registerTranscribe from "./transcribe.js";
+import registerTts from "./tts.js";
 
 export default async function (pi: ExtensionAPI): Promise<void> {
 	await registerProvider(pi);
-	registerFetch(pi);
-	registerSearch(pi);
+	registerRouterCommand(pi);
+	registerSttCommand(pi);
 	registerTranscribe(pi);
+	registerTts(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)),