@haoyiyin/9router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,39 @@
+# @haoyiyin/9router
+
+pi 扩展 — 9Router provider（含 OpenCode Free `oc/` 模型）+ fetch / search / transcribe 工具。
+
+Fork of [`@xynogen/pix-9router`](https://www.npmjs.com/package/@xynogen/pix-9router)，修复了 9router 的 `/v1/models` 永远不列出 OpenCode Free `-free` 模型的问题，本扩展直接暴露这些 `oc/` 模型。
+
+## 安装
+
+```
+pi install npm:@haoyiyin/9router
+```
+
+## 配置
+
+默认无内置地址。运行 `/9router` → 输入 9Router 地址和 API Key → 存入 `~/.pi/agent/9router-oc.json`（权限 `0600`）。Key 已配置时 `/9router` 可留空保持原值。
+
+也可以设置环境变量兜底：`ROUTER_API_BASE` / `ROUTER_API_KEY`（配置文件优先）。
+
+## oc 模型
+
+每 30 分钟自动拉取 `opencode.ai/zen/v1/models` 中 id 以 `-free` 结尾的模型，以 `oc/<id>` 形式注册进 9router provider。列表波动会自动跟随。缓存文件：`~/.cache/pi/zen-oc-models.json`。
+
+## 迁移
+
+如果你装过 `@xynogen/pix-9router`：
+
+```
+pi remove npm:@xynogen/pix-9router
+```
+
+并（可选）删除 `~/.zshrc` 里的 `ROUTER_API_KEY` / `ROUTER_API_BASE` export。
+
+## 工具
+
+`fetch` / `search` / `transcribe` 与 `pix-9router` 一致；collapse 配置仍在 `~/.pi/agent/pix.json`。
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@haoyiyin/9router",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "description": "Pi extension — 9Router provider (OpenCode Free oc/-free models + router models) + fetch/search/transcribe tools",
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "pi": {
+    "extensions": [
+      "src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "@xynogen/pix-data": "*",
+    "@xynogen/pix-pretty": "^1.11.2",
+    "typebox": "^1.1.38",
+    "@xynogen/pix-runtime": "^0.8.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "9router",
+    "opencode"
+  ],
+  "author": "yi",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/command.ts

@@ -0,0 +1,52 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig, saveConfig, DEFAULT_BASE } from "./config.ts";
+import { registerProvider } from "./provider.ts";
+
+// Never contains a real key. If a dialog pre-fills this placeholder as an
+// editable default, an exact match is treated as "keep the current key".
+const API_KEY_PLACEHOLDER = "sk-...（留空保持已配置的 key）";
+
+export function registerCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("9router", {
+		description: "配置 9Router 地址和 API Key（存 ~/.pi/agent/9router-oc.json）",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const current = loadConfig();
+
+			const baseUrl = await ctx.ui.input("9Router 地址", current.baseUrl || DEFAULT_BASE);
+			if (baseUrl === undefined) return;
+			const trimmedBase = baseUrl.trim();
+			const normalizedBase = trimmedBase.endsWith("/")
+				? trimmedBase.slice(0, -1)
+				: trimmedBase;
+
+			const apiKey = await ctx.ui.input("9Router API Key", API_KEY_PLACEHOLDER);
+			if (apiKey === undefined) return;
+			const trimmedKey = apiKey.trim();
+
+			let finalKey: string;
+			if (trimmedKey === "" || trimmedKey === API_KEY_PLACEHOLDER) {
+				// Keep the existing key; never treat the placeholder as a submitted value.
+				if (!current.apiKey) {
+					ctx.ui.notify("未设置 API Key", "error");
+					return;
+				}
+				finalKey = current.apiKey;
+			} else {
+				finalKey = trimmedKey;
+			}
+
+			saveConfig({ baseUrl: normalizedBase, apiKey: finalKey });
+
+			try {
+				await registerProvider(pi);
+			} catch (err) {
+				ctx.ui.notify(
+					`9Router 已保存，但重新注册 provider 失败: ${err instanceof Error ? err.message : String(err)}`,
+					"warning",
+				);
+			}
+
+			ctx.ui.notify(`9Router 已保存: ${normalizedBase}`, "info");
+		},
+	});
+}

package/src/config.ts

@@ -0,0 +1,50 @@
+import { homedir } from "node:os";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export const DEFAULT_BASE = "";
+
+export interface RouterConfig {
+  baseUrl: string;
+  apiKey: string;
+}
+
+export function configPath(): string {
+  return join(homedir(), ".pi", "agent", "9router-oc.json");
+}
+
+export function loadConfig(): RouterConfig {
+  const path = configPath();
+  let fileBase: string | undefined;
+  let fileKey: string | undefined;
+
+  if (existsSync(path)) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf8"));
+      if (parsed && typeof parsed === "object") {
+        if (typeof parsed.baseUrl === "string") fileBase = parsed.baseUrl;
+        if (typeof parsed.apiKey === "string") fileKey = parsed.apiKey;
+      }
+    } catch {
+      // tolerate malformed config -> fall back to env/defaults
+    }
+  }
+
+  let baseUrl = fileBase ?? process.env.ROUTER_API_BASE ?? DEFAULT_BASE;
+  if (baseUrl.endsWith("/")) baseUrl = baseUrl.slice(0, -1);
+
+  const apiKey = fileKey ?? process.env.ROUTER_API_KEY ?? "";
+
+  return { baseUrl, apiKey };
+}
+
+export function saveConfig(cfg: RouterConfig): void {
+  const path = configPath();
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+  try {
+    chmodSync(path, 0o600);
+  } catch {
+    // best-effort enforcement on existing files
+  }
+}

package/src/data.ts

@@ -0,0 +1,81 @@
+/**
+ * data.ts — 9Router data layer
+ *
+ * Router-specific data only:
+ *   - routerBaseUrl()  — resolved API base URL from config
+ *   - routerApiKey()   — resolved API key from config
+ *   - routerModels     — DataSource<RouterModel[]>, cached 30m at ~/.cache/pi/9router.json
+ *
+ * Config (base URL + key, with env fallback) is owned by ./config.ts.
+ *
+ * models.dev + modelgrep data is provided by @xynogen/pix-data, which shares
+ * the same ~/.cache/pi/ cache directory. The DataSource implementation and the
+ * models.dev index helpers live there — imported here, not duplicated.
+ */
+
+import { join } from "node:path";
+import { CACHE_DIR, DataSource } from "@xynogen/pix-data/src/index.ts";
+
+export { CACHE_DIR, DataSource };
+export {
+	buildModelsDevIndex,
+	fetchModelsDevIndex,
+	lookupInIndex,
+} from "@xynogen/pix-data/src/index.ts";
+export type {
+	ModelGrepModel,
+	ModelsDevApi,
+	ModelsDevModel,
+} from "@xynogen/pix-data/src/index.ts";
+
+import { loadConfig } from "./config.ts";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface RouterModel {
+	id?: string;
+	name?: string;
+	context_window?: number;
+	contextWindow?: number;
+	max_tokens?: number;
+	maxTokens?: number;
+	owned_by?: string;
+	/** 9router v1 API nests these inside capabilities */
+	capabilities?: {
+		contextWindow?: number;
+		maxOutput?: number;
+		[key: string]: unknown;
+	};
+}
+
+interface RouterModelsResponse {
+	data?: RouterModel[];
+}
+
+// ── Resolved config helpers ───────────────────────────────────────────────────
+
+export function routerBaseUrl(): string {
+	return loadConfig().baseUrl;
+}
+
+export function routerApiKey(): string {
+	return loadConfig().apiKey;
+}
+
+// ── Router models ──────────────────────────────────────────────────────────────
+
+export const routerModels = new DataSource<RouterModel[]>({
+	label: "9router",
+	url: () => `${routerBaseUrl()}/models`,
+	headers: () => {
+		const key = routerApiKey();
+		return key ? { Authorization: `Bearer ${key}` } : undefined;
+	},
+	skip: () => !routerApiKey(),
+	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: [],
+});

package/src/fetch.ts

@@ -0,0 +1,262 @@
+/**
+ * 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.ts";
+import { makeRenderCall, makeRenderResult } from "./render.ts";
+
+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: [
+			"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.",
+		],
+		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

@@ -0,0 +1,87 @@
+/**
+ * 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 { type ExecFileException, execFile } from "node:child_process";
+import { ioTimeoutMs, ioTimeoutSignal } from "@xynogen/pix-runtime/io";
+import { loadConfig } from "./config.ts";
+import { routerBaseUrl } from "./data.ts";
+
+export function auth(): string | undefined {
+	return loadConfig().apiKey || undefined;
+}
+
+/** 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 {
+	/** curl --max-time in seconds (default 25). */
+	maxTime?: number;
+	/** child-process kill timeout in ms (default 30_000). */
+	timeoutMs?: number;
+	/** Optional stdin body piped into curl. */
+	stdin?: string;
+}
+
+/** Run curl with sane defaults, rejecting on non-zero exit or timeout. */
+export function curl(args: string[], opts: CurlOptions = {}): Promise<string> {
+	const timeoutMs = opts.timeoutMs ?? ioTimeoutMs();
+	const maxTime = opts.maxTime ?? timeoutMs / 1000;
+	const { stdin } = opts;
+	return new Promise((resolve, reject) => {
+		const child = execFile(
+			"curl",
+			["-sS", "--connect-timeout", "10", "--max-time", String(maxTime), ...args],
+			{ maxBuffer: 10 * 1024 * 1024, timeout: timeoutMs },
+			(err, stdout, stderr) => {
+				if (err) {
+					const e = err as ExecFileException;
+					const msg = e.killed
+						? "curl timed out"
+						: `curl exit ${e.code ?? "??"}: ${stderr.slice(0, 300)}`;
+					reject(new Error(msg));
+					return;
+				}
+				resolve(stdout);
+			},
+		);
+		if (stdin && child.stdin) {
+			child.stdin.write(stdin);
+			child.stdin.end();
+		}
+	});
+}
+
+export function isCancelled(error: unknown, signal: AbortSignal | undefined): boolean {
+	return signal?.aborted === true || (error instanceof DOMException && error.name === "AbortError");
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import registerFetch from "./fetch.ts";
+import registerSearch from "./search.ts";
+import registerTranscribe from "./transcribe.ts";
+import { registerProvider } from "./provider.ts";
+import { registerCommand } from "./command.ts";
+
+export default async function (pi: ExtensionAPI): Promise<void> {
+	registerFetch(pi);
+	registerSearch(pi);
+	registerTranscribe(pi);
+
+	registerCommand(pi);
+
+	await registerProvider(pi);
+
+	let refreshing = false;
+	const timer = setInterval(
+		async () => {
+			// ponytail: models refresh by unregister+register; zen cache TTL is
+			// 30m so refetch happens naturally. Overlap guard avoids re-entrancy.
+			if (refreshing) return;
+			refreshing = true;
+			try {
+				await registerProvider(pi);
+			} finally {
+				refreshing = false;
+			}
+		},
+		30 * 60 * 1000,
+	);
+	if (typeof (timer as { unref?: () => void }).unref === "function") {
+		(timer as { unref: () => void }).unref();
+	}
+}