@xynogen/pix-9router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xynogen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# pix-9router
+
+Pi coding agent extension — **9Router provider** + **fetch** and **search** tools backed by an internal OpenAI-compatible router API.
+
+## What's included
+
+| 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 |
+
+## Install
+
+```bash
+pi install git:github.com/xynogen/pix-9router
+```
+
+## 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):
+
+```bash
+export ROUTER_API_KEY="your-key-here"
+# export ROUTER_API_BASE="https://your-router.example.com/v1"  # optional
+```
+
+## How it works
+
+- **Provider**: on load, fetches `/models` from the router and registers them with Pi. [models.dev](https://models.dev/api.json) 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 1h).
+- **fetch / search**: POST to `/web/fetch` and `/search` on the router (which proxies to exa). If the router is unreachable, falls back to raw `curl`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@xynogen/pix-9router",
+  "version": "0.1.0",
+  "description": "Pi extension — 9Router provider + fetch/search tools via router API",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "test": "bun test"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": ["src/index.ts"]
+  },
+  "keywords": ["pi", "pi-package", "pi-extension", "9router"],
+  "author": "xynogen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xynogen/pix-mono.git",
+    "directory": "packages/pix-9router"
+  },
+  "homepage": "https://github.com/xynogen/pix-mono/tree/main/packages/pix-9router#readme",
+  "bugs": {
+    "url": "https://github.com/xynogen/pix-mono/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*"
+  },
+  "dependencies": {
+    "typebox": "^1.1.38"
+  }
+}

package/src/data.test.ts

@@ -0,0 +1,179 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import {
+	routerBaseUrl,
+	buildModelsDevIndex,
+	lookupInIndex,
+	type ModelsDevApi,
+	type ModelsDevModel,
+} from "./data.ts";
+
+// ── routerBaseUrl ────────────────────────────────────────────────────────────
+
+describe("routerBaseUrl", () => {
+	const ORIGINAL = process.env.ROUTER_API_BASE;
+
+	afterEach(() => {
+		if (ORIGINAL === undefined) delete process.env.ROUTER_API_BASE;
+		else process.env.ROUTER_API_BASE = ORIGINAL;
+	});
+
+	it("returns default when env unset", () => {
+		delete process.env.ROUTER_API_BASE;
+		expect(routerBaseUrl()).toBe("https://9router.example.com/v1");
+	});
+
+	it("uses ROUTER_API_BASE when set", () => {
+		process.env.ROUTER_API_BASE = "https://my.router.dev/v1";
+		expect(routerBaseUrl()).toBe("https://my.router.dev/v1");
+	});
+
+	it("strips trailing slash", () => {
+		process.env.ROUTER_API_BASE = "https://my.router.dev/v1/";
+		expect(routerBaseUrl()).toBe("https://my.router.dev/v1");
+	});
+});
+
+// ── buildModelsDevIndex ──────────────────────────────────────────────────────
+
+describe("buildModelsDevIndex", () => {
+	const api: ModelsDevApi = {
+		anthropic: {
+			models: {
+				"claude-sonnet-4-5": {
+					id: "claude-sonnet-4-5",
+					name: "Claude Sonnet 4.5",
+					reasoning: false,
+					limit: { context: 200_000, output: 8_192 },
+					cost: { input: 3, output: 15 },
+				},
+				"claude-opus-4": {
+					id: "claude-opus-4",
+					name: "Claude Opus 4",
+					reasoning: true,
+					limit: { context: 200_000, output: 32_000 },
+					cost: { input: 15, output: 75 },
+				},
+			},
+		},
+		openai: {
+			models: {
+				"gpt-4o": {
+					id: "gpt-4o",
+					name: "GPT-4o",
+					modalities: { input: ["text", "image"], output: ["text"] },
+				},
+			},
+		},
+	};
+
+	it("indexes all models by exact id", () => {
+		const idx = buildModelsDevIndex(api);
+		expect(idx.has("claude-sonnet-4-5")).toBe(true);
+		expect(idx.has("claude-opus-4")).toBe(true);
+		expect(idx.has("gpt-4o")).toBe(true);
+	});
+
+	it("indexes normalized ids (strip date suffix)", () => {
+		const apiWithDate: ModelsDevApi = {
+			anthropic: {
+				models: {
+					"claude-sonnet-4-5-20250514": {
+						id: "claude-sonnet-4-5-20250514",
+						name: "Claude Sonnet 4.5",
+					},
+				},
+			},
+		};
+		const idx = buildModelsDevIndex(apiWithDate);
+		// normalized: strip -20250514
+		expect(idx.has("claude-sonnet-4-5")).toBe(true);
+	});
+
+	it("handles empty api gracefully", () => {
+		const idx = buildModelsDevIndex({});
+		expect(idx.size).toBe(0);
+	});
+
+	it("handles provider with no models key", () => {
+		const idx = buildModelsDevIndex({ anthropic: {} });
+		expect(idx.size).toBe(0);
+	});
+
+	it("preserves first-seen on id collision", () => {
+		const collide: ModelsDevApi = {
+			a: { models: { "gpt-4o": { id: "gpt-4o", name: "First" } } },
+			b: { models: { "gpt-4o": { id: "gpt-4o", name: "Second" } } },
+		};
+		const idx = buildModelsDevIndex(collide);
+		expect(idx.get("gpt-4o")?.name).toBe("First");
+	});
+});
+
+// ── lookupInIndex ────────────────────────────────────────────────────────────
+
+describe("lookupInIndex", () => {
+	let index: Map<string, ModelsDevModel>;
+
+	beforeEach(() => {
+		const api: ModelsDevApi = {
+			anthropic: {
+				models: {
+					"claude-sonnet-4-5": {
+						id: "claude-sonnet-4-5",
+						name: "Claude Sonnet 4.5",
+					},
+					"claude-opus-4": { id: "claude-opus-4", name: "Claude Opus 4" },
+				},
+			},
+			openai: {
+				models: {
+					"gpt-4o": { id: "gpt-4o", name: "GPT-4o" },
+					"o3-mini": { id: "o3-mini", name: "o3 mini" },
+				},
+			},
+		};
+		index = buildModelsDevIndex(api);
+	});
+
+	it("finds exact match", () => {
+		expect(lookupInIndex("claude-sonnet-4-5", index)?.name).toBe(
+			"Claude Sonnet 4.5",
+		);
+	});
+
+	it("finds by stripping provider prefix (router style: provider/model)", () => {
+		expect(lookupInIndex("anthropic/claude-opus-4", index)?.name).toBe(
+			"Claude Opus 4",
+		);
+	});
+
+	it("finds with deep prefix e.g. cc/claude-opus-4", () => {
+		expect(lookupInIndex("cc/claude-opus-4", index)?.name).toBe(
+			"Claude Opus 4",
+		);
+	});
+
+	it("finds with date suffix stripped", () => {
+		expect(lookupInIndex("claude-sonnet-4-5-20250514", index)?.name).toBe(
+			"Claude Sonnet 4.5",
+		);
+	});
+
+	it("finds with provider prefix + date suffix", () => {
+		expect(
+			lookupInIndex("anthropic/claude-sonnet-4-5-20250514", index)?.name,
+		).toBe("Claude Sonnet 4.5");
+	});
+
+	it("returns undefined for unknown model", () => {
+		expect(lookupInIndex("nonexistent-model-xyz", index)).toBeUndefined();
+	});
+
+	it("finds gpt-4o exact", () => {
+		expect(lookupInIndex("gpt-4o", index)?.name).toBe("GPT-4o");
+	});
+
+	it("finds o3-mini exact", () => {
+		expect(lookupInIndex("o3-mini", index)?.name).toBe("o3 mini");
+	});
+});

package/src/data.ts

@@ -0,0 +1,225 @@
+/**
+ * data.ts — 9Router data layer
+ *
+ * Router-specific data only:
+ *   - routerBaseUrl()  — resolved API base URL from env
+ *   - routerModels     — DataSource<RouterModel[]>, cached 30m at ~/.cache/pi/9router.json
+ *
+ * models.dev + BenchLM data is provided by pix-data (github.com/xynogen/pix-data),
+ * which shares the same ~/.cache/pi/ cache directory.
+ *
+ * Environment:
+ *   ROUTER_API_BASE  — override base URL (default: https://9router.example.com/v1)
+ *   ROUTER_API_KEY   — bearer token (required)
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface RouterModel {
+	id?: string;
+	name?: string;
+	context_window?: number;
+	contextWindow?: number;
+	max_tokens?: number;
+	maxTokens?: number;
+	owned_by?: string;
+}
+
+// Re-export ModelsDevModel for provider.ts — sourced from pix-data at runtime
+// via shared cache; typed here to avoid a hard import dependency.
+export interface ModelsDevModel {
+	id: string;
+	name?: string;
+	reasoning?: boolean;
+	modalities?: { input?: string[]; output?: string[] };
+	limit?: { context?: number; output?: number };
+	cost?: { input?: number; output?: number; cache_read?: number; cache_write?: number };
+}
+
+export type ModelsDevApi = Record<string, { models?: Record<string, ModelsDevModel> }>;
+
+interface RouterModelsResponse {
+	data?: RouterModel[];
+}
+
+// ── DataSource (minimal, router-only) ────────────────────────────────────────
+
+interface DataSourceOptions<T> {
+	url: string | (() => string);
+	headers?: () => Record<string, string> | undefined;
+	cachePath: string;
+	ttlMs?: number;
+	timeoutMs?: number;
+	parse: (raw: unknown) => T;
+	parseCache: (data: unknown) => T;
+	empty: T;
+	label: string;
+	skip?: () => boolean;
+}
+
+class DataSource<T> {
+	private _mem: T | null = null;
+	private _inflight: Promise<T> | null = null;
+	private readonly opts: Required<DataSourceOptions<T>>;
+
+	constructor(opts: DataSourceOptions<T>) {
+		this.opts = {
+			ttlMs: 24 * 60 * 60 * 1000,
+			timeoutMs: 10_000,
+			headers: () => undefined,
+			skip: () => false,
+			...opts,
+		};
+	}
+
+	async get(): Promise<T> {
+		if (this._inflight) return this._inflight;
+		this._inflight = this._load().finally(() => { this._inflight = null; });
+		return this._inflight;
+	}
+
+	getCached(): T {
+		if (this._mem) return this._mem;
+		try {
+			if (existsSync(this.opts.cachePath)) {
+				const raw = JSON.parse(readFileSync(this.opts.cachePath, "utf-8")) as { data: unknown };
+				this._mem = this.opts.parseCache(raw.data);
+				return this._mem;
+			}
+		} catch {
+			// No cache file or parse error — return empty
+		}
+		return this.opts.empty;
+	}
+
+	private async _load(): Promise<T> {
+		if (this.opts.skip()) { this._mem = this.opts.empty; return this.opts.empty; }
+		const cached = await this._readCache();
+		if (cached !== undefined && Date.now() - cached.ts < this.opts.ttlMs) {
+			const val = this.opts.parseCache(cached.data);
+			this._mem = val;
+			return val;
+		}
+		try {
+			const url = typeof this.opts.url === "function" ? this.opts.url() : this.opts.url;
+			const controller = new AbortController();
+			const timer = setTimeout(() => controller.abort(), this.opts.timeoutMs);
+			const response = await fetch(url, { signal: controller.signal, headers: this.opts.headers() }).finally(() => clearTimeout(timer));
+			if (!response.ok) throw new Error(`${this.opts.label} fetch failed: ${response.status}`);
+			const raw = await response.json();
+			const val = this.opts.parse(raw);
+			this._mem = val;
+			void this._writeCache(raw);
+			return val;
+		} catch (error) {
+			const msg = error instanceof Error ? error.message : String(error);
+			if (cached !== undefined) {
+				console.warn(`${this.opts.label} fetch failed, using stale cache: ${msg}`);
+				const val = this.opts.parseCache(cached.data);
+				this._mem = val;
+				return val;
+			}
+			console.warn(`${this.opts.label} unavailable: ${msg}`);
+			return this.opts.empty;
+		}
+	}
+
+	private async _readCache(): Promise<{ ts: number; data: unknown } | undefined> {
+		try {
+			const raw = await readFile(this.opts.cachePath, "utf8");
+			const parsed = JSON.parse(raw) as { ts: number; data: unknown };
+			if (typeof parsed.ts !== "number") return undefined;
+			return parsed;
+		} catch { return undefined; }
+	}
+
+	private async _writeCache(data: unknown): Promise<void> {
+		try {
+			await mkdir(dirname(this.opts.cachePath), { recursive: true });
+			await writeFile(this.opts.cachePath, JSON.stringify({ ts: Date.now(), data }));
+		} catch {
+			// Write failure is non-fatal
+		}
+	}
+}
+
+// ── Constants ──────────────────────────────────────────────────────────────────
+
+const CACHE_DIR = join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "pi");
+
+const ROUTER_DEFAULT_BASE = "https://9router.example.com/v1";
+
+export function routerBaseUrl(): string {
+	return (process.env.ROUTER_API_BASE || ROUTER_DEFAULT_BASE).replace(/\/$/, "");
+}
+
+// ── Router models ──────────────────────────────────────────────────────────────
+
+export const routerModels = new DataSource<RouterModel[]>({
+	label: "9router",
+	url: () => `${routerBaseUrl()}/models`,
+	headers: () => {
+		const key = process.env.ROUTER_API_KEY;
+		return key ? { Authorization: `Bearer ${key}` } : undefined;
+	},
+	skip: () => !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)),
+	parseCache: (data) => ((data as RouterModelsResponse | undefined)?.data ?? []).filter((m) => Boolean(m.id)),
+	empty: [],
+});
+
+// ── models.dev index (read from pix-data shared cache) ────────────────────────
+
+const modelsDevCache = new DataSource<ModelsDevApi>({
+	label: "models.dev",
+	url: "https://models.dev/api.json",
+	cachePath: join(CACHE_DIR, "models.json"),
+	parse: (raw) => raw as ModelsDevApi,
+	parseCache: (data) => (data as ModelsDevApi) ?? {},
+	empty: {},
+});
+
+function normalize(id: string): string {
+	return id.toLowerCase().replace(/[:@].*$/, "").replace(/-\d{8}$/, "");
+}
+
+function stripPrefix(id: string): string {
+	const i = id.lastIndexOf("/");
+	return i >= 0 ? id.slice(i + 1) : id;
+}
+
+export function buildModelsDevIndex(api: ModelsDevApi): Map<string, ModelsDevModel> {
+	const index = new Map<string, ModelsDevModel>();
+	for (const provider of Object.values(api)) {
+		if (!provider?.models) continue;
+		for (const [modelId, model] of Object.entries(provider.models)) {
+			const m: ModelsDevModel = { ...model, id: modelId };
+			if (!index.has(modelId)) index.set(modelId, m);
+			const norm = normalize(modelId);
+			if (!index.has(norm)) index.set(norm, m);
+		}
+	}
+	return index;
+}
+
+export function lookupInIndex(id: string, index: Map<string, ModelsDevModel>): ModelsDevModel | undefined {
+	const stripped = stripPrefix(id);
+	const direct = index.get(stripped) ?? index.get(normalize(stripped));
+	if (direct) return direct;
+	const norm = normalize(stripped);
+	for (const [key, model] of index) {
+		if (key.startsWith(norm) || norm.startsWith(key)) return model;
+	}
+	return undefined;
+}
+
+export async function fetchModelsDevIndex(): Promise<Map<string, ModelsDevModel>> {
+	return buildModelsDevIndex(await modelsDevCache.get());
+}

package/src/fetch.ts

@@ -0,0 +1,181 @@
+/**
+ * fetch.ts — fetch tool via 9Router API, with curl fallback.
+ *
+ * Environment:
+ *   ROUTER_API_BASE  — router API base URL (default: https://9r.xynogen.xyz/v1)
+ *   ROUTER_API_KEY   — bearer token for the router
+ */
+
+import { execFile } from "node:child_process";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { routerBaseUrl } from "./data.js";
+
+const REQUEST_TIMEOUT_MS = 30_000;
+
+function auth(): string | undefined {
+	return process.env.ROUTER_API_KEY;
+}
+
+async function apiPost(
+	path: string,
+	body: Record<string, unknown>,
+	signal?: AbortSignal,
+): 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 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);
+	}
+}
+
+function curl(args: string[]): Promise<string> {
+	return new Promise((resolve, reject) => {
+		execFile(
+			"curl",
+			["-sS", "--connect-timeout", "10", "--max-time", "25", ...args],
+			{ maxBuffer: 10 * 1024 * 1024, timeout: 30_000 },
+			(err, stdout, stderr) => {
+				if (err) {
+					const msg = (err as NodeJS.ErrnoException).killed
+						? "curl timed out"
+						: `curl exit ${(err as NodeJS.ErrnoException).code ?? "??"}: ${stderr.slice(0, 300)}`;
+					reject(new Error(msg));
+					return;
+				}
+				resolve(stdout);
+			},
+		);
+	});
+}
+
+export default function registerFetch(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "fetch",
+		label: "Fetch",
+		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: [
+			"Use fetch when you need to read the full content of a specific URL.",
+			"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.",
+			"Always prefer fetch over raw curl/browser for reading page content.",
+		],
+		parameters: Type.Object({
+			url: Type.String({ description: "URL to fetch" }),
+			format: StringEnum(["markdown", "text", "html"] as const, {
+				description: "Desired output format",
+			}),
+			max_characters: Type.Optional(
+				Type.Number({
+					description: "Max characters (default 1000, 0 = unlimited)",
+					default: 1000,
+				}),
+			),
+		}),
+
+		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}...` },
+					],
+				});
+
+				const raw = await apiPost(
+					"/web/fetch",
+					{
+						model: "exa",
+						url: params.url,
+						format: fmt,
+						max_characters: maxChars,
+					},
+					signal,
+				);
+
+				const truncated =
+					maxChars > 0 && raw.length > maxChars
+						? raw.slice(0, maxChars) + "\n\n[truncated]"
+						: raw;
+
+				return {
+					content: [{ type: "text", text: truncated.slice(0, 20_000) }],
+					details: {
+						source: "api",
+						chars: raw.length,
+						truncated: maxChars > 0 && raw.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...`,
+						},
+					],
+				});
+			}
+
+			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,
+				};
+			}
+		},
+	});
+}