@gtrabanco/pi-nan-provider 0.7.0 → 0.10.0

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * @gtrabanco/pi-nan-provider — NaN Builders provider + MCP bridges for pi.
+ * @gtrabanco/pi-nan-provider — NaN Builders provider + native MCP servers for pi.
  *
  * What this extension registers:
  *
@@ -15,14 +15,17 @@
  *     0.84 alike), and the openai-completions streaming implementation is
  *     resolved dynamically — see provider-factory.ts for why.
  *
- *  2. MCP tools over pi's registerTool (pi intentionally has no MCP client):
- *     - `nan_web_search` via NaN's official remote MCP server
- *       (https://api.nan.builders/mcp) — on by default, NAN_MCP_TOOLS=0 to
- *       disable.
- *     - Media tools bridging the optional community `nan-mcp-server`
- *       (stdio, spawned per call) — on by default, NAN_MEDIA_MCP=0 to
- *       disable. The server spawns per tool call, so nothing runs unless
- *       audio/image/transcription is actually invoked.
+ *  2. MCP servers via pi's native registerMcpServer (pi >=0.99):
+ *     - `nan-search` — the official NaN remote MCP server
+ *       (https://api.nan.builders/mcp), exposing `mcp__nan-search__web_search`.
+ *       Default: enabled. NAN_MCP_TOOLS=0 to disable.
+ *     - `nan-media` — the community stdio media server
+ *       (flux-2-klein / kokoro / whisper), exposing
+ *       `mcp__nan-media__generate_image` etc. Default: enabled,
+ *       NAN_MEDIA_MCP=0 to disable.
+ *
+ *     Both are session-scoped (visible in /mcp with source "extension").
+ *     Exposure: `direct` — tools are declared to the model like built-ins.
  */
 
 import type { ContextEvent, ExtensionAPI, ProviderConfig } from "@earendil-works/pi-coding-agent";
@@ -34,10 +37,10 @@ import {
 	stripCrossModelThinking,
 } from "./cross-model-thinking-guard.ts";
 import { baselineModels } from "./fetch-models.ts";
-import { createNanWebSearchTool, webSearchBridgeEnabled, NAN_API_KEY_ENV } from "./mcp/nan-search.ts";
-import { createNanMediaTools, mediaMcpEnabled } from "./mcp/nan-media.ts";
 import { createNanCompatibleProvider, type OpenAICompatibleProviderConfig } from "./provider-factory.ts";
 import { PROVIDERS } from "./providers.ts";
+import { NAN_API_KEY_ENV, mcpToolsDisabled, mcpToolsEnvExplicit, resolveNanApiKey, tryResolveNanApiKeyViaRegistry, NAN_MCP_TOOLS_ENV, webSearchBridgeEnabled } from "./mcp/api-key.ts";
+import { mediaMcpCommand, mediaMcpEnabled, mediaMcpEnvExplicit, mediaMcpEnvTruthy, mediaMcpTimeoutSec } from "./mcp/media-server.ts";
 
 /**
  * Register a provider on any pi version: the native full-Provider overload
@@ -80,45 +83,78 @@ async function registerProviderCompat(
 	pi.registerProvider(config.id, legacy);
 }
 
+// ── Native MCP registration ──────────────────────────────────────────────
+
 /**
- * Register MCP-bridged tools when the runtime supports them. Both bridges
- * are enabled by default and lazy (nothing runs until a tool is invoked);
- * `/nan-mcp` (and the NAN_MCP_TOOLS / NAN_MEDIA_MCP env vars) toggle them.
- * Old pi versions without registerTool/registerCommand skip gracefully.
- *
- * Registration is tracked in `registeredToolNames` so `/nan-mcp enable` can
- * add tools mid-session without double-registering.
+ * Guard message shown when pi lacks native MCP support (pi <0.99 despite peers).
+ * Matches the loud-skip style of existing guards (pi-ai, registerTool).
  */
-function registerMcpToolsCompat(pi: ExtensionAPI): void {
-	if (typeof pi.registerTool !== "function") return;
-	const registeredToolNames = new Set<string>();
-	const registerSearchTool = () => {
-		const search = createNanWebSearchTool();
-		if (registeredToolNames.has(search.name)) return;
-		registeredToolNames.add(search.name);
-		pi.registerTool(search);
-	};
-	const registerMediaTools = () => {
-		for (const tool of createNanMediaTools()) {
-			if (registeredToolNames.has(tool.name)) continue;
-			registeredToolNames.add(tool.name);
-			pi.registerTool(tool);
-		}
-	};
+const NO_NATIVE_MCP_GUARD_MSG =
+	"pi-nan-provider 0.10+ requires pi >= 0.99 for MCP tools (native MCP); upgrade pi or stay on package 0.9.x";
 
-	if (webSearchBridgeEnabled()) registerSearchTool();
-	if (mediaMcpEnabled()) registerMediaTools();
-	if (typeof pi.registerCommand === "function") {
-		registerNanMcpCommand(pi, { registerWebSearchTools: registerSearchTool, registerMediaTools });
-		registerNanUsageCommand(pi);
+/** Register the official NaN web-search MCP server (session-scoped). */
+async function registerWebSearchMcpServer(pi: ExtensionAPI): Promise<boolean> {
+	if (!webSearchBridgeEnabled()) return false;
+	const apiKey = process.env[NAN_API_KEY_ENV];
+	if (!apiKey) {
+		return false;
 	}
+	pi.registerMcpServer("nan-search", {
+		type: "http",
+		url: "https://api.nan.builders/mcp",
+		headers: { Authorization: `Bearer ${apiKey}` },
+		exposure: "direct",
+	});
+	return true;
+}
+
+/** Register the community media stdio MCP server (session-scoped). */
+function registerMediaMcpServer(pi: ExtensionAPI): boolean {
+	if (!mediaMcpEnabled()) return false;
+	const mediaArgs = mediaMcpCommand();
+	pi.registerMcpServer("nan-media", {
+		type: "stdio",
+		command: mediaArgs[0]!,
+		args: mediaArgs.slice(1),
+		env: { [NAN_API_KEY_ENV]: process.env[NAN_API_KEY_ENV] ?? "" },
+		exposure: "direct",
+		timeout: mediaMcpTimeoutSec(),
+	});
+	return true;
 }
 
+/**
+ * Register MCP servers via pi's native registerMcpServer.
+ *
+ * Session-scoped: servers appear in /mcp with source "extension", are
+ * visible to the model (exposure: "direct"), and user mcp.json entries
+ * with the same name take precedence.
+ *
+ * On pi <0.99 (registerMcpServer absent) this does NOT bridge — it
+ * notifies once and skips (same loud-skip style as existing guards).
+ * Hard cutover: users on older pi stay on package 0.9.x.
+ */
+async function registerMcpServersNative(pi: ExtensionAPI): Promise<void> {
+	// Guard: pi >= 0.99 required for native MCP.
+	if (typeof pi.registerMcpServer !== "function") {
+		console.warn(NO_NATIVE_MCP_GUARD_MSG);
+		return;
+	}
+
+
+	const didWebSearch = await registerWebSearchMcpServer(pi);
+	registerMediaMcpServer(pi);
+
+
+}
+
+// ── Extension entrypoint ─────────────────────────────────────────────────
+
 /**
  * Drop the reasoning pi-ai replays across a model switch.
  *
  * pi-ai's `transformMessages` downgrades a previous model's `thinking` blocks
- * to plain text with no size bound (still true on 0.85.1 / main), and nothing
+ * to plain text with no size bound (verified on 0.87.1), and nothing
  * bounds the sum across messages — measured at 30–60% of the whole context on
  * real sessions. Switching from a 1M-context model to a 262K one (`qwen3.6`)
  * then overflows the window, and NaN's gateway answers a generic
@@ -146,7 +182,11 @@ export default async function nanProviderExtension(pi: ExtensionAPI): Promise<vo
 	for (const config of PROVIDERS) {
 		await registerProviderCompat(pi, config);
 	}
-	registerMcpToolsCompat(pi);
+	await registerMcpServersNative(pi);
+	if (typeof pi.registerCommand === "function") {
+		registerNanMcpCommand(pi);
+		registerNanUsageCommand(pi);
+	}
 }
 
 /** Exposed for tests: the env var this package uses for every NaN surface. */

package/src/mcp/api-key.ts

@@ -0,0 +1,76 @@
+import { bridgeSource, resolveBridgeEnabled } from "./state.ts";
+
+/**
+ * NaN API key resolution — shared across every surface (web search, media, usage).
+ *
+ * Strategy: pi's stored credential (modelRegistry) wins → env var fallback.
+ * Never logs or embeds the key beyond the Authorization header.
+ */
+
+/** Env var that overrides the official web_search bridge. */
+export const NAN_MCP_TOOLS_ENV = "NAN_MCP_TOOLS";
+/** Env var that overrides the media bridge. */
+export const NAN_MEDIA_MCP_ENV = "NAN_MEDIA_MCP";
+/** The NaN API key env var used everywhere. */
+export const NAN_API_KEY_ENV = "NAN_API_KEY";
+/** NaN provider id used for stored-credential lookup. */
+const NAN_PROVIDER_ID = "nan";
+
+/**
+ * Resolve the NaN API key: pi's registry first (covers stored auth.json),
+ * then env fallback. `registryKey` is the result of an attempted registry
+ * lookup (already caught and converted to string | undefined by the caller).
+ */
+export function resolveNanApiKey(registryKey: string | undefined): string | undefined {
+	if (registryKey) return registryKey;
+	return process.env[NAN_API_KEY_ENV] || undefined;
+}
+
+/**
+ * Attempt to resolve the API key through pi's model registry.
+ * Catches any error and returns undefined so the caller can fall back to env.
+ */
+export async function tryResolveNanApiKeyViaRegistry(
+	modelRegistry: { getApiKeyForProvider(provider: string): Promise<string | undefined> } | undefined,
+): Promise<string | undefined> {
+	try {
+		return await modelRegistry?.getApiKeyForProvider(NAN_PROVIDER_ID);
+	} catch {
+		// Registry unavailable — caller falls back to env.
+		return undefined;
+	}
+}
+
+/** 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";
+}
+
+/** Whether NAN_MCP_TOOLS is explicitly set (any value). */
+export function mcpToolsEnvExplicit(): boolean {
+	const value = process.env[NAN_MCP_TOOLS_ENV];
+	return value !== undefined && value.trim() !== "";
+}
+
+/** Whether NAN_MEDIA_MCP is explicitly set (any value). */
+export function mediaMcpEnvExplicit(): boolean {
+	const value = process.env[NAN_MEDIA_MCP_ENV];
+	return value !== undefined && value.trim() !== "";
+}
+
+/** Whether NAN_MEDIA_MCP is explicitly set and truthy. */
+export function mediaMcpEnvTruthy(): boolean {
+	const value = process.env[NAN_MEDIA_MCP_ENV]?.trim().toLowerCase();
+	return value === "1" || value === "true" || value === "on";
+}
+
+/** Source of the effective web-search enablement (env / persisted / default). */
+export function webSearchBridgeSource(): import("./state.ts").BridgeSource {
+	return bridgeSource("webSearch", mcpToolsEnvExplicit());
+}
+
+/** Whether the web-search bridge is enabled by gate (env → persisted → default). */
+export function webSearchBridgeEnabled(): boolean {
+	return resolveBridgeEnabled("webSearch", mcpToolsEnvExplicit(), !mcpToolsDisabled(), true);
+}

package/src/mcp/media-server.ts

@@ -0,0 +1,56 @@
+/**
+ * Media server construction helpers — version pin, command, timeout.
+ * Also exports bridge gate resolution (mediaMcpEnabled / mediaMcpSource)
+ * to keep the native MCP registration in index.ts minimal.
+ */
+import { bridgeSource, resolveBridgeEnabled, type BridgeSource } from "./state.ts";
+
+/**
+ * Default spawn: `npx -y nan-mcp-server@<pinned version>` (npx caches after first use).
+ */
+export function mediaMcpCommand(version = process.env[NAN_MEDIA_MCP_VERSION_ENV] || DEFAULT_NAN_MEDIA_MCP_VERSION): string[] {
+	const custom = process.env[NAN_MEDIA_MCP_COMMAND_ENV]?.trim();
+	if (custom) return custom.split(/\s+/);
+	return ["npx", "-y", `nan-mcp-server@${version}`];
+}
+
+/** Per-request timeout in milliseconds. Native MCP uses seconds. */
+export function mediaMcpTimeoutMs(): number {
+	const parsed = Number.parseInt(process.env[NAN_MEDIA_MCP_TIMEOUT_ENV] ?? "", 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MEDIA_MCP_TIMEOUT_MS;
+}
+
+/** Per-request timeout in **seconds** for the native MCP config. */
+export function mediaMcpTimeoutSec(): number {
+	return Math.ceil(mediaMcpTimeoutMs() / 1000);
+}
+
+export const NAN_MEDIA_MCP_ENV = "NAN_MEDIA_MCP";
+
+export const DEFAULT_NAN_MEDIA_MCP_VERSION = "1.1.2";
+export const DEFAULT_MEDIA_MCP_TIMEOUT_MS = 120_000;
+export const NAN_MEDIA_MCP_VERSION_ENV = "NAN_MEDIA_MCP_VERSION";
+export const NAN_MEDIA_MCP_COMMAND_ENV = "NAN_MEDIA_MCP_COMMAND";
+export const NAN_MEDIA_MCP_TIMEOUT_ENV = "NAN_MEDIA_MCP_TIMEOUT_MS";
+
+/** Whether NAN_MEDIA_MCP is explicitly set (any value). */
+export function mediaMcpEnvExplicit(): boolean {
+	const value = process.env[NAN_MEDIA_MCP_ENV];
+	return value !== undefined && value.trim() !== "";
+}
+
+/** Whether NAN_MEDIA_MCP is explicitly set and truthy. */
+export function mediaMcpEnvTruthy(): boolean {
+	const value = process.env[NAN_MEDIA_MCP_ENV]?.trim().toLowerCase();
+	return value === "1" || value === "true" || value === "on";
+}
+
+/** Whether the media bridge is enabled by gate (env → persisted → default). */
+export function mediaMcpEnabled(): boolean {
+	return resolveBridgeEnabled("mediaMcp", mediaMcpEnvExplicit(), mediaMcpEnvTruthy(), true);
+}
+
+/** Source of the effective media enablement. */
+export function mediaMcpSource(): BridgeSource {
+	return bridgeSource("mediaMcp", mediaMcpEnvExplicit());
+}

package/src/provider-factory.ts

@@ -14,8 +14,8 @@
  * statically import ONLY the bare `@earendil-works/pi-ai` root. pi's
  * extension loader maps that specifier to the compat entrypoint on every
  * supported runtime (bundled CLI, Node-mode aliases, compiled-binary
- * virtualModules; pi 0.83 and 0.84 alike), and compat re-exports every lazy
- * API factory. Subpath specifiers (`@earendil-works/pi-ai/api/...`) get the
+ * virtualModules; pi 0.83 through 0.87.1 alike), and compat re-exports every
+ * lazy API factory. Subpath specifiers (`@earendil-works/pi-ai/api/...`) get the
  * alias applied as a prefix and resolve to `<compat.js>/api/...`, which does
  * not exist — the extension then fails to load entirely.
  *
@@ -79,6 +79,11 @@ export interface NanCompatibleProviderOptions {
  * Any caller-supplied `onPayload` (e.g. pi's own debug/passthrough hook) is
  * preserved and chained AFTER sanitization, so the final payload is always
  * schema-valid.
+ *
+ * Note (pi-ai ≥ 0.86): this wrapper forwards the `TranscriptContext` parameter
+ * unchanged and only rewrites `options.onPayload` — the `TranscriptContext`
+ * migration (branded `TranscriptContext = { messages: Message[] }` replacing
+ * `Context`) does not affect this function's behavior.
  */
 function isObject(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;