@gtrabanco/pi-nan-provider 0.2.1

package/src/mcp/nan-search.ts

@@ -0,0 +1,220 @@
+/**
+ * Bridge to NaN's official remote MCP server over plain HTTP — no MCP client
+ * needed in pi (pi intentionally ships without MCP support; see docs/usage.md).
+ *
+ * Endpoint (NaN OpenAPI spec, tag "MCP"): `https://api.nan.builders/mcp`
+ * (host root, NOT under `/v1`). Transport is streamable HTTP and stateless;
+ * protocol is JSON-RPC 2.0 (`initialize`, `tools/list`, `tools/call`, `ping`).
+ * Auth is the same `sk-` key as the REST API (`Authorization: Bearer`), and
+ * MCP calls share the key's rate limit, daily quota, and concurrency.
+ *
+ * Today the server exposes `web_search` (same arguments as `POST /v1/search`);
+ * it is a growing registry, so this module keeps a generic `callNanMcpTool`
+ * that can invoke any current or future tool by name.
+ */
+
+import { Type, type Static } from "@earendil-works/pi-ai";
+import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+/** NaN's official remote MCP endpoint (host root, not /v1). */
+export const NAN_MCP_URL = "https://api.nan.builders/mcp";
+/** Web search can be slow; the endpoint shares the key's rate limits. */
+export const NAN_MCP_TIMEOUT_MS = 30_000;
+/** Env var that disables MCP tool registration: NAN_MCP_TOOLS=0|false|off. */
+export const NAN_MCP_TOOLS_ENV = "NAN_MCP_TOOLS";
+
+const NAN_PROVIDER_ID = "nan";
+export const NAN_API_KEY_ENV = "NAN_API_KEY";
+
+export interface NapiKeyContext {
+	/** pi's model registry (checks the stored credential and env vars). */
+	modelRegistry?: { getApiKeyForProvider(provider: string): Promise<string | undefined> };
+}
+
+/**
+ * Resolve the NaN API key for tool execution: pi's registry first (it covers
+ * the stored auth.json credential and configured env sources), then a direct
+ * env fallback so the tools also work on pi versions without the registry.
+ * Never logs or embeds the key beyond the Authorization header.
+ */
+export async function resolveNanApiKey(ctx: NapiKeyContext): Promise<string | undefined> {
+	try {
+		const stored = await ctx.modelRegistry?.getApiKeyForProvider(NAN_PROVIDER_ID);
+		if (stored) return stored;
+	} catch {
+		// Registry unavailable (older pi) or provider not registered — env fallback below.
+	}
+	return process.env[NAN_API_KEY_ENV] || undefined;
+}
+
+export interface NanMcpToolCall {
+	/** MCP tool name, e.g. "web_search". */
+	name: string;
+	/** Tool arguments object (JSON-serializable). */
+	arguments?: Record<string, unknown>;
+}
+
+export interface NanMcpToolResult {
+	/** true when the call completed without a tool-level or transport error. */
+	ok: boolean;
+	/** Concatenated text content returned by the tool. */
+	text: string;
+	/** Error description when ok is false. */
+	error?: string;
+}
+
+export interface NanMcpCallOptions {
+	apiKey?: string;
+	timeoutMs?: number;
+	fetchImpl?: typeof fetch;
+}
+
+function renderMcpContent(content: unknown): string {
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const item of content) {
+		if (!item || typeof item !== "object") continue;
+		const block = item as { type?: string; text?: string };
+		if (block.type === "text" && typeof block.text === "string") {
+			parts.push(block.text);
+		} else if (block.type === "image") {
+			parts.push("[image returned by tool; see the saved file path in the text above if present]");
+		}
+	}
+	return parts.join("\n\n");
+}
+
+/**
+ * Invoke a tool on NaN's official MCP server: POST a JSON-RPC 2.0
+ * `tools/call` and flatten the response content. Transport failures,
+ * JSON-RPC errors, and tool errors all surface as `{ ok: false }` with a
+ * message — never as a thrown error, so tool results degrade gracefully.
+ */
+export async function callNanMcpTool(
+	name: string,
+	args: Record<string, unknown> | undefined,
+	options: NanMcpCallOptions = {},
+): Promise<NanMcpToolResult> {
+	const { apiKey, timeoutMs = NAN_MCP_TIMEOUT_MS, fetchImpl = fetch } = options;
+	if (!apiKey) return { ok: false, text: "", error: `${NAN_API_KEY_ENV} is not set — set it or run /login nan.` };
+
+	const controller = new AbortController();
+	const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const response = await fetchImpl(NAN_MCP_URL, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${apiKey}`,
+				"Content-Type": "application/json",
+				Accept: "application/json",
+			},
+			body: JSON.stringify({
+				jsonrpc: "2.0",
+				id: 1,
+				method: "tools/call",
+				params: { name, arguments: args ?? {} },
+			}),
+			signal: controller.signal,
+		});
+		if (!response.ok) {
+			return {
+				ok: false,
+				text: "",
+				error: `NaN MCP returned HTTP ${response.status}${response.status === 401 ? " — check your NaN API key" : ""}`,
+			};
+		}
+		const payload = (await response.json()) as {
+			result?: { content?: unknown; isError?: boolean };
+			error?: { code?: number; message?: string };
+		};
+		if (payload.error) {
+			return { ok: false, text: "", error: `NaN MCP error ${payload.error.code ?? ""}: ${payload.error.message ?? "unknown"}` };
+		}
+		const text = renderMcpContent(payload.result?.content);
+		if (payload.result?.isError) {
+			return { ok: false, text, error: text || "NaN MCP tool reported an error" };
+		}
+		return { ok: true, text: text || "(empty response)" };
+	} catch (error) {
+		const aborted = controller.signal.aborted;
+		return {
+			ok: false,
+			text: "",
+			error: aborted
+				? `NaN MCP call timed out after ${timeoutMs}ms`
+				: `NaN MCP call failed: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	} finally {
+		clearTimeout(timeoutId);
+	}
+}
+
+const webSearchParameters = Type.Object({
+	query: Type.String({ description: "The search query." }),
+	count: Type.Optional(
+		Type.Integer({
+			description: "Number of results to return, 1-20 (values outside the range are clamped). Default 5.",
+			minimum: 1,
+			maximum: 20,
+		}),
+	),
+	freshness: Type.Optional(
+		Type.String({
+			description:
+				"Recency filter: 'pd' (past day), 'pw' (past week), 'pm' (past month), 'py' (past year), or a 'YYYY-MM-DDtoYYYY-MM-DD' date range. Omit for no time filter.",
+		}),
+	),
+	fetch_content: Type.Optional(
+		Type.Boolean({
+			description:
+				"When true, also fetch and include the readable main text of the top results. Slower; defaults to snippets only.",
+		}),
+	),
+});
+
+export type NanWebSearchParams = Static<typeof webSearchParameters>;
+
+/**
+ * pi tool bridging NaN's official MCP `web_search`. Registered by default
+ * when the runtime supports registerTool; disable with NAN_MCP_TOOLS=0.
+ *
+ * Failure convention per pi's AgentTool contract: execute() throws on
+ * failure instead of encoding errors in content — the runtime surfaces the
+ * error to the model so it can self-correct (e.g. ask the user for a key).
+ */
+export function createNanWebSearchTool(): ToolDefinition<typeof webSearchParameters> {
+	return {
+		name: "nan_web_search",
+		label: "NaN Web Search",
+		description:
+			"Web search via NaN's remote MCP server (api.nan.builders/mcp). Returns ranked web results with snippets; requires NAN_API_KEY. Same rate limit and quota as the REST /v1/search endpoint.",
+		promptSnippet: "nan_web_search(query, count?, freshness?, fetch_content?): web search via the NaN MCP server",
+		parameters: webSearchParameters,
+		execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
+			const apiKey = await resolveNanApiKey(contextHasKeySource(ctx));
+			if (!apiKey) {
+				throw new Error(
+					`${NAN_API_KEY_ENV} is not set. Export it (export ${NAN_API_KEY_ENV}="sk-...") or run /login nan.`,
+				);
+			}
+			const result = await callNanMcpTool(
+				"web_search",
+				params as Record<string, unknown>,
+				{ apiKey, timeoutMs: NAN_MCP_TIMEOUT_MS },
+			);
+			if (!result.ok) throw new Error(result.error ?? "NaN MCP call failed");
+			return { content: [{ type: "text", text: result.text }], details: undefined } as const;
+		},
+	};
+}
+
+/** Whether MCP tool registration is disabled via env (NAN_MCP_TOOLS=0|false|off). */
+export function mcpToolsDisabled(): boolean {
+	const value = process.env[NAN_MCP_TOOLS_ENV]?.trim().toLowerCase();
+	return value === "0" || value === "false" || value === "off";
+}
+
+/** Extract an ExtensionContext-shaped key source for tests without full pi. */
+export function contextHasKeySource(ctx: ExtensionContext): NapiKeyContext {
+	return ctx as unknown as NapiKeyContext;
+}

package/src/mcp/stdio-client.ts

@@ -0,0 +1,222 @@
+/**
+ * Minimal MCP (Model Context Protocol) stdio client — just enough protocol to
+ * call one tool per spawned process, so bridging stdio MCP servers is lazy by
+ * construction: nothing starts, connects, or costs anything until a tool is
+ * actually invoked.
+ *
+ * Protocol: JSON-RPC 2.0 over the child's stdin/stdout, one message per line
+ * (MCP stdio transport). Handshake: `initialize` request → `initialized`
+ * notification → request. The child process is terminated after the call, so
+ * each invocation pays a fresh spawn (~npx overhead on first use, cached
+ * afterwards) in exchange for zero idle cost and no daemon management.
+ */
+
+import { spawn } from "node:child_process";
+
+/** Oldest stable protocol version; accepted by every MCP SDK server. */
+const PROTOCOL_VERSION = "2024-11-05";
+const CLIENT_INFO = { name: "pi-nan-provider", version: "0.2.0" };
+
+export interface StdioMcpCallOptions {
+	/** Command to spawn, e.g. ["npx", "-y", "nan-mcp-server@1.0.7"]. */
+	command: readonly string[];
+	/** Extra environment for the child (merged over process.env). */
+	env?: Record<string, string | undefined>;
+	/** Kill the child and fail the call after this long. */
+	timeoutMs?: number;
+	/** Cooperative cancellation from the host tool call. */
+	signal?: AbortSignal;
+	/** Working directory for the child. */
+	cwd?: string;
+}
+
+export interface StdioMcpToolResult {
+	/** true when the tool call completed without a tool-level or transport error. */
+	ok: boolean;
+	/** Concatenated text content returned by the tool. */
+	text: string;
+	/** Error description when ok is false. */
+	error?: string;
+	/** Server stderr tail, attached to failures for diagnosis. */
+	stderrTail?: string;
+}
+
+interface JsonRpcMessage {
+	jsonrpc?: string;
+	id?: number | string | null;
+	method?: string;
+	params?: unknown;
+	result?: {
+		content?: Array<{ type?: string; text?: string }>;
+		isError?: boolean;
+		tools?: unknown[];
+	};
+	error?: { code?: number; message?: string };
+}
+
+function renderContent(result: JsonRpcMessage["result"]): string {
+	const parts: string[] = [];
+	for (const item of result?.content ?? []) {
+		if (item?.type === "text" && typeof item.text === "string") {
+			parts.push(item.text);
+		} else if (item?.type === "image") {
+			parts.push("[image returned by tool]");
+		}
+	}
+	return parts.join("\n\n");
+}
+
+/**
+ * Spawn the MCP server, run the handshake, call one tool, and terminate the
+ * process. Never throws — every failure mode resolves to
+ * `{ ok: false, error }` so callers can decide how to surface it.
+ */
+export async function callStdioMcpTool(
+	toolName: string,
+	toolArguments: Record<string, unknown> | undefined,
+	options: StdioMcpCallOptions,
+): Promise<StdioMcpToolResult> {
+	const { command, env, timeoutMs = 120_000, signal, cwd } = options;
+
+	if (command.length === 0) {
+		return { ok: false, text: "", error: "No MCP server command configured" };
+	}
+
+	return new Promise<StdioMcpToolResult>((resolve) => {
+		let child: ReturnType<typeof spawn>;
+		try {
+			child = spawn(command[0]!, command.slice(1), {
+				stdio: ["pipe", "pipe", "pipe"],
+				env: { ...process.env, ...env },
+				...(cwd ? { cwd } : {}),
+			});
+		} catch (error) {
+			resolve({
+				ok: false,
+				text: "",
+				error: `Failed to start MCP server: ${error instanceof Error ? error.message : String(error)}`,
+			});
+			return;
+		}
+
+		let settled = false;
+		let stdoutBuffer = "";
+		let stderr = "";
+		let timeoutId: ReturnType<typeof setTimeout> | undefined;
+		let lastResponse: JsonRpcMessage | undefined;
+
+		const cleanup = () => {
+			if (timeoutId !== undefined) clearTimeout(timeoutId);
+			if (signal) signal.removeEventListener("abort", onAbort);
+			try {
+				child.stdin?.end();
+			} catch {
+				// stdin already closed
+			}
+			if (!child.killed) {
+				child.kill("SIGTERM");
+			}
+			// Escalate if the server ignores SIGTERM.
+			const escalate = setTimeout(() => child.kill("SIGKILL"), 1_000);
+			child.once("exit", () => clearTimeout(escalate));
+		};
+
+		const finish = (result: StdioMcpToolResult) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			resolve(result);
+		};
+
+		const onAbort = () => finish({ ok: false, text: "", error: "MCP tool call aborted" });
+		signal?.addEventListener("abort", onAbort, { once: true });
+
+		const fail = (error: string): void => {
+			finish({
+				ok: false,
+				text: "",
+				error,
+				...(stderr ? { stderrTail: stderr.split("\n").slice(-5).join("\n").slice(-500) } : {}),
+			});
+		};
+
+		timeoutId = setTimeout(() => {
+			fail(`MCP server did not answer within ${timeoutMs}ms`);
+		}, timeoutMs);
+
+		const send = (message: object) => {
+			child.stdin?.write(`${JSON.stringify(message)}\n`);
+		};
+
+		child.stdout?.setEncoding("utf8");
+		child.stdout?.on("data", (chunk: string) => {
+			stdoutBuffer += chunk;
+			let newlineIndex = stdoutBuffer.indexOf("\n");
+			while (newlineIndex !== -1) {
+				const line = stdoutBuffer.slice(0, newlineIndex).trim();
+				stdoutBuffer = stdoutBuffer.slice(newlineIndex + 1);
+				if (line.length > 0) {
+					try {
+						handleLine(JSON.parse(line) as JsonRpcMessage);
+					} catch {
+						// Non-JSON stdout line — tolerate server banners/logs.
+					}
+				}
+				newlineIndex = stdoutBuffer.indexOf("\n");
+			}
+		});
+
+		child.stderr?.setEncoding("utf8");
+		child.stderr?.on("data", (chunk: string) => {
+			stderr += chunk;
+			if (stderr.length > 8_000) stderr = stderr.slice(-4_000);
+		});
+
+		child.once("error", (error) => {
+			fail(`MCP server process error: ${error instanceof Error ? error.message : String(error)}`);
+		});
+		child.once("exit", (code, exitSignal) => {
+			if (!settled) fail(`MCP server exited early (code=${code ?? "null"}, signal=${exitSignal ?? "null"})`);
+		});
+
+		const handleLine = (message: JsonRpcMessage) => {
+			if (message.id === 1) {
+				// initialize response → complete handshake, then call the tool.
+				if (message.error) {
+					fail(`MCP handshake failed: ${message.error.message ?? "unknown error"}`);
+					return;
+				}
+				send({ jsonrpc: "2.0", method: "notifications/initialized" });
+				send({
+					jsonrpc: "2.0",
+					id: 2,
+					method: "tools/call",
+					params: { name: toolName, arguments: toolArguments ?? {} },
+				});
+				return;
+			}
+			if (message.id === 2) {
+				lastResponse = message;
+				if (message.error) {
+					fail(`MCP tool error ${message.error.code ?? ""}: ${message.error.message ?? "unknown"}`);
+					return;
+				}
+				const text = renderContent(message.result);
+				if (message.result?.isError) {
+					finish({ ok: false, text, error: text || "MCP tool reported an error" });
+					return;
+				}
+				finish({ ok: true, text: text || "(empty response)" });
+			}
+			// Other lines (notifications, keep-alives) are ignored.
+		};
+
+		// Handshake start.
+		send({
+			jsonrpc: "2.0",
+			id: 1,
+			method: "initialize",
+			params: { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: CLIENT_INFO },
+		});
+	});
+}

package/src/provider-factory.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared factory for OpenAI-compatible providers registered from this package.
+ *
+ * One implementation, N provider configs. A second provider-specific source
+ * file is a smell — add a config entry (see src/providers.ts) and, if needed,
+ * catalog data, never a parallel implementation.
+ *
+ * The resulting provider follows pi-ai's built-in provider shape (see
+ * `deepseekProvider()` in pi-ai): `createProvider` + `envApiKeyAuth` +
+ * `openAICompletionsApi`, with a `fetchModels` overlay that merges the live
+ * /models listing with the generated fallback catalog.
+ */
+
+import {
+	createProvider,
+	envApiKeyAuth,
+	type Provider,
+	type RefreshModelsContext,
+} from "@earendil-works/pi-ai";
+import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
+import {
+	baselineModels,
+	DEFAULT_MODELS_TIMEOUT_MS,
+	resolveCatalog,
+	type CatalogSource,
+} from "./fetch-models.ts";
+
+export interface OpenAICompatibleProviderConfig {
+	/** Provider id as registered in pi, e.g. "nan". */
+	id: string;
+	/** Display name shown in /login and the model selector, e.g. "NaN". */
+	name: string;
+	/** OpenAI-compatible base URL including version path, e.g. "https://api.nan.builders/v1". */
+	baseUrl: string;
+	/** Env vars consulted (in order) when no credential is stored, e.g. ["NAN_API_KEY"]. */
+	envVars: readonly string[];
+}
+
+export interface NanCompatibleProviderOptions {
+	/** Timeout for the live /models fetch. Default: 3000ms. */
+	timeoutMs?: number;
+	/** Injectable for tests; defaults to global fetch. */
+	fetchImpl?: typeof fetch;
+}
+
+/**
+ * Build a complete pi-ai Provider for an OpenAI-compatible endpoint:
+ *
+ * - auth: stored credential key wins, then the first set env var resolves;
+ *   `/login <id>` prompts for the key (pi's `envApiKeyAuth` semantics — the
+ *   same precedence the built-in providers use). No prompt is needed when the
+ *   env var is set.
+ * - models: the generated fallback catalog as static baseline, so models are
+ *   available with zero network.
+ * - fetchModels: live `/models` IDs × generated capability data; falls back
+ *   to the baseline when the endpoint is unreachable. pi's Models runtime
+ *   drives refreshes (startup/periodic) and persists the overlay.
+ * - api: `openAICompletionsApi()` (lazy-loaded streaming implementation).
+ */
+export function createNanCompatibleProvider(
+	config: OpenAICompatibleProviderConfig,
+	options: NanCompatibleProviderOptions = {},
+): Provider<"openai-completions"> {
+	const source: CatalogSource = { providerId: config.id, baseUrl: config.baseUrl };
+
+	// Last successful live /models result, shared between fetchModels (writes)
+	// and filterModels (reads). When set it is authoritative for what your key
+	// can use — tier detection: NaN lists exactly the models your membership
+	// can call, so models absent from the live list are filtered out of
+	// `available` (e.g. premium-tier models you are not subscribed to).
+	let liveIds: Set<string> | undefined;
+
+	return createProvider({
+		id: config.id,
+		name: config.name,
+		baseUrl: config.baseUrl,
+		auth: { apiKey: envApiKeyAuth(`${config.name} API key`, config.envVars) },
+		models: baselineModels(source),
+		fetchModels: async (context: RefreshModelsContext) => {
+			const credential = context.credential;
+			const resolved = await resolveCatalog(source, {
+				apiKey: credential?.type === "api_key" ? credential.key : undefined,
+				timeoutMs: options.timeoutMs ?? DEFAULT_MODELS_TIMEOUT_MS,
+				fetchImpl: options.fetchImpl,
+			});
+			liveIds = resolved.liveIds;
+			return resolved.models;
+		},
+		filterModels: (models) => {
+			// Snapshot: TS can't prove `liveIds` unchanged across the closure boundary.
+			const current = liveIds;
+			return current ? models.filter((model) => current.has(model.id)) : models;
+		},
+		api: openAICompletionsApi(),
+	});
+}

package/src/providers.ts

@@ -0,0 +1,34 @@
+/**
+ * Provider registry for this package. Each entry is registered through the
+ * shared factory in src/provider-factory.ts — adding a provider is one entry
+ * here (plus catalog data), never a second implementation file.
+ */
+
+import type { OpenAICompatibleProviderConfig } from "./provider-factory.ts";
+
+/**
+ * NaN Builders — https://nan.builders — community LiteLLM gateway.
+ *
+ * Base URL and env var confirmed by models.dev (provider "nan") and NaN's own
+ * getting-started docs; `openai-completions` + `supportsDeveloperRole: true`
+ * per NaN's published .pi/agent/models.json example.
+ */
+export const NAN_PROVIDER: OpenAICompatibleProviderConfig = {
+	id: "nan",
+	name: "NaN",
+	baseUrl: "https://api.nan.builders/v1",
+	envVars: ["NAN_API_KEY"],
+};
+
+/**
+ * `helmcode` is intentionally NOT registered in v0.1.0. The founding prompt
+ * references it (shared factory + HELLMCODE_API_KEY), but no confirmed base
+ * URL or capability source exists — it is absent from models.dev and from
+ * NaN's docs, and fabricating either is against this repo's rules.
+ *
+ * When an endpoint and catalog source are confirmed: add an entry here (same
+ * shape as NAN_PROVIDER) and a models.dev/generator source if available. The
+ * shared factory covers it with zero new code — see the factory test that
+ * registers a second provider through the same code path.
+ */
+export const PROVIDERS: readonly OpenAICompatibleProviderConfig[] = [NAN_PROVIDER];