@gtrabanco/pi-nan-provider 0.8.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;

package/src/usage.ts

@@ -13,8 +13,11 @@
  * (NaN docs, checked 2026-09-27).
  *
  * The endpoint reports consumption, never caps: quotas below come from
- * https://nan.builders/docs/models (checked 2026-09-21) and are merged with
- * the returned per-model totals. `/usage` returns daily rows (paginated) plus
+ * https://nan.builders/docs/models (checked 2026-09-29) and are merged with
+ * the returned per-model totals. mimo-v2.5 has no row: NaN removed it from
+ * the docs (checked 2026-09-29), so a cap for it would have no source —
+ * historical consumption still appears under the undocumented-models section.
+ * `/usage` returns daily rows (paginated) plus
  * `totals` covering the whole requested window — max 90 inclusive days, wider
  * windows are rejected with 400 — so the command reads `totals.by_model` and
  * asks for a single-row page. Rate limit: 30 requests/min, separate from the
@@ -22,7 +25,7 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { NAN_API_KEY_ENV, resolveNanApiKey } from "./mcp/nan-search.ts";
+import { NAN_API_KEY_ENV, resolveNanApiKey, tryResolveNanApiKeyViaRegistry } from "./mcp/api-key.ts";
 
 // ── Known quota limits per model (from NaN docs) ──────────────────────────
 
@@ -43,7 +46,6 @@ export interface ModelQuota {
 
 export const MODEL_QUOTAS: readonly ModelQuota[] = [
 	{ model: "deepseek-v4-flash", label: "DeepSeek V4 Flash", monthlyCap: 3_000_000_000, rollingWindowCap: 0, rollingWindowHours: 0, premium: false },
-	{ model: "mimo-v2.5", label: "MiMo V2.5", monthlyCap: 1_000_000_000, rollingWindowCap: 0, rollingWindowHours: 0, premium: false },
 	{ model: "mimo-v2.6-flash", label: "MiMo V2.6 Flash", monthlyCap: 1_000_000_000, rollingWindowCap: 0, rollingWindowHours: 0, premium: false },
 	{ model: "qwen3.6", label: "Qwen 3.6", monthlyCap: 0, rollingWindowCap: 0, rollingWindowHours: 0, premium: false },
 	{ model: "gemma4", label: "Gemma 4", monthlyCap: 0, rollingWindowCap: 0, rollingWindowHours: 0, premium: false },
@@ -429,7 +431,10 @@ export interface NanUsageCommandOptions {
 export function registerNanUsageCommand(pi: ExtensionAPI, options: NanUsageCommandOptions = {}): void {
 	if (typeof pi.registerCommand !== "function") return;
 
-	const resolveApiKey = options.resolveApiKey ?? ((ctx: ExtensionCommandContext) => resolveNanApiKey(ctx));
+	const resolveApiKey = options.resolveApiKey ?? (async (ctx: ExtensionCommandContext): Promise<string | undefined> => {
+				const registryKey = await tryResolveNanApiKeyViaRegistry(ctx.modelRegistry);
+				return resolveNanApiKey(registryKey);
+			});
 
 	pi.registerCommand("nan-usage", {
 		description: "Show NaN token usage vs monthly caps, window/all-time totals, and time until billing reset",

package/src/mcp/nan-media.ts

@@ -1,236 +0,0 @@
-/**
- * Optional bridge to the community stdio MCP server
- * `nan-mcp-server` (https://github.com/luciferfran/nan-mcp-server), which
- * exposes NaN's media tools: image generation/editing (flux-2-klein), TTS
- * (kokoro), STT (whisper), plus voice listing.
- *
- * Both MCP bridges are enabled by default and fully lazy:
- * - ON by default. NAN_MEDIA_MCP=0 (or false/off) disables it for one
- *   session; `/nan-mcp disable nan-mcp-server` persists the toggle.
- * - The server process is spawned per tool call and terminated right after —
- *   zero startup cost, nothing runs unless audio/image/transcription is
- *   actually invoked.
- * - NAN_API_KEY is forwarded to the child; NAN_OUTPUT_DIR and the server's
- *   other env vars inherit from your environment (generated files land in
- *   ~/nan-mcp-output/ by default).
- * - Version pinning follows the upstream server's own supply-chain guidance:
- *   NAN_MEDIA_MCP_VERSION (default "1.1.2"), or pass a custom command with
- *   NAN_MEDIA_MCP_COMMAND (space-separated, e.g. "bunx nan-mcp-server@1.1.2").
- */
-
-import { Type, type TSchema } from "@earendil-works/pi-ai";
-import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
-import { callStdioMcpTool } from "./stdio-client.ts";
-import { bridgeSource, resolveBridgeEnabled, type BridgeSource } from "./state.ts";
-import { NAN_API_KEY_ENV, resolveNanApiKey, type NapiKeyContext } from "./nan-search.ts";
-
-export const NAN_MEDIA_MCP_ENV = "NAN_MEDIA_MCP";
-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";
-export const DEFAULT_NAN_MEDIA_MCP_VERSION = "1.1.2";
-
-/**
- * The MCP tool names on the stdio nan-mcp-server that this package bridges as
- * pi tools. Kept as the single source of truth for the check script
- * (scripts/check-nan-mcp-server.ts) and to type each spec's `mcpTool` so the
- * bridge cannot drift from the set it claims to expose.
- */
-export const NAN_MEDIA_MCP_SERVER_TOOLS = [
-	"generate_image",
-	"edit_image",
-	"text_to_speech",
-	"list_voices",
-	"speech_to_text",
-] as const;
-export const DEFAULT_MEDIA_MCP_TIMEOUT_MS = 120_000;
-
-/** Media tools bridged from the stdio MCP server (audio/image/transcription scope). */
-export const NAN_MEDIA_TOOLS = [
-	"nan_generate_image",
-	"nan_edit_image",
-	"nan_text_to_speech",
-	"nan_list_voices",
-	"nan_speech_to_text",
-] as const;
-
-/** Truthy env parse for the media bridge env var: 1/true/on (case-insensitive). */
-function envTruthy(): boolean {
-	return envValueIsTruthy(process.env[NAN_MEDIA_MCP_ENV]);
-}
-
-/** Whether the env var is explicitly set (any value) — it overrides the persisted toggle. */
-function envExplicit(): boolean {
-	const value = process.env[NAN_MEDIA_MCP_ENV];
-	return value !== undefined && value.trim() !== "";
-}
-
-function envValueIsTruthy(value: string | undefined): boolean {
-	return value?.trim().toLowerCase() === "1" || value?.trim().toLowerCase() === "true" || value?.trim().toLowerCase() === "on";
-}
-
-/**
- * Effective enablement of the community media MCP bridge: an explicit
- * `NAN_MEDIA_MCP` env var (any value, e.g. `0` to force one session off)
- * wins; then the toggle persisted by `/nan-mcp`; default: **enabled** (both
- * bridges are on and lazy by default — the server spawns per tool call).
- */
-export function mediaMcpEnabled(): boolean {
-	return resolveBridgeEnabled("mediaMcp", envExplicit(), envTruthy(), true);
-}
-
-/** Source of the effective media enablement (env / persisted / default). */
-export function mediaMcpSource(): BridgeSource {
-	return bridgeSource("mediaMcp", envExplicit());
-}
-
-/** 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}`];
-}
-
-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;
-}
-
-interface MediaToolSpec<TParams extends TSchema = TSchema> {
-	name: (typeof NAN_MEDIA_TOOLS)[number];
-	mcpTool: (typeof NAN_MEDIA_MCP_SERVER_TOOLS)[number];
-	label: string;
-	description: string;
-	promptSnippet: string;
-	parameters: TParams;
-}
-
-const sizeProperty = () =>
-	Type.Optional(
-		Type.String({
-			description: 'Image size "WxH" divisible by 16, e.g. 1024x1024, 1536x1024, 1024x1536. Default 1024x1024',
-		}),
-	);
-
-function defineMediaTool<TParams extends TSchema>(spec: MediaToolSpec<TParams>): ToolDefinition<TParams> {
-	return {
-		name: spec.name,
-		label: spec.label,
-		description: spec.description,
-		promptSnippet: spec.promptSnippet,
-		parameters: spec.parameters,
-		execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
-			const apiKey = await resolveNanApiKey(ctx as unknown as NapiKeyContext);
-			if (!apiKey) {
-				throw new Error(`${NAN_API_KEY_ENV} is not set. Export it or run /login nan to use NaN media tools.`);
-			}
-			const result = await callStdioMcpTool(spec.mcpTool, params as Record<string, unknown>, {
-				command: mediaMcpCommand(),
-				env: { [NAN_API_KEY_ENV]: apiKey },
-				timeoutMs: mediaMcpTimeoutMs(),
-				...(signal ? { signal } : {}),
-			});
-			if (!result.ok) {
-				throw new Error(
-					`${result.error ?? "nan-mcp-server call failed"}${result.stderrTail ? ` (server stderr: ${result.stderrTail})` : ""}`,
-				);
-			}
-			return { content: [{ type: "text", text: result.text }], details: undefined } as const;
-		},
-	};
-}
-
-/**
- * Build the media tool set. Registered only when NAN_MEDIA_MCP=1 and the
- * runtime supports registerTool; execution spawns the MCP server per call.
- * Schemas mirror nan-mcp-server's zod input schemas (v1.1.2).
- */
-export function createNanMediaTools(): ToolDefinition[] {
-	return [
-		defineMediaTool({
-			name: "nan_generate_image",
-			mcpTool: "generate_image",
-			label: "NaN Generate Image",
-			description:
-				"Generate an image with flux-2-klein (NaN API). Returns the saved image file path (under ~/nan-mcp-output/ by default) and its URL.",
-			promptSnippet: "nan_generate_image(prompt, size?, n?, seed?, guidance?, outputName?): generate an image via NaN (flux-2-klein)",
-			parameters: Type.Object({
-				prompt: Type.String({ description: "Textual description of the image to generate" }),
-				size: sizeProperty(),
-				n: Type.Optional(Type.Integer({ description: "Number of images to generate (1-4). Default 1", minimum: 1, maximum: 4 })),
-				seed: Type.Optional(Type.Number({ description: "Base seed for reproducibility" })),
-				guidance: Type.Optional(Type.Number({ description: "FLUX guidance scale" })),
-				outputName: Type.Optional(Type.String({ description: "Optional base name for the output file(s)" })),
-			}),
-		}),
-		defineMediaTool({
-			name: "nan_edit_image",
-			mcpTool: "edit_image",
-			label: "NaN Edit Image",
-			description:
-				"Edit an image with flux-2-klein image-to-image (NaN API). Takes reference image files and applies a transformation. Returns the saved output image path.",
-			promptSnippet: "nan_edit_image(prompt, images, size?, n?, seed?, guidance?, outputName?): edit images via NaN (flux-2-klein)",
-			parameters: Type.Object({
-				prompt: Type.String({ description: "Description of the edit or transformation to apply" }),
-				images: Type.Array(Type.String(), {
-					description: "Absolute paths to reference image files (PNG, JPEG, WebP; up to 4, each < 25MB)",
-					minItems: 1,
-					maxItems: 4,
-				}),
-				size: sizeProperty(),
-				n: Type.Optional(Type.Integer({ description: "Number of images to generate (1-4). Default 1", minimum: 1, maximum: 4 })),
-				seed: Type.Optional(Type.Number({ description: "Base seed for reproducibility" })),
-				guidance: Type.Optional(Type.Number({ description: "FLUX guidance scale" })),
-				outputName: Type.Optional(Type.String({ description: "Optional base name for the output file(s)" })),
-			}),
-		}),
-		defineMediaTool({
-			name: "nan_text_to_speech",
-			mcpTool: "text_to_speech",
-			label: "NaN Text To Speech",
-			description:
-				"Synthesize audio from text with kokoro (NaN API TTS). Returns the saved audio file path. Use nan_list_voices to see all available voices per language.",
-			promptSnippet: "nan_text_to_speech(text, voice?, format?, speed?, outputName?): synthesize speech via NaN (kokoro)",
-			parameters: Type.Object({
-				text: Type.String({ description: "Text to synthesize" }),
-				voice: Type.Optional(
-					Type.String({
-						description:
-							'Voice to use, e.g. "af_heart" (American English female), "ef_dora" (Spanish female), "em_alex" (Spanish male). Use nan_list_voices for the full catalog',
-					}),
-				),
-				format: Type.Optional(
-					Type.Unsafe<"mp3" | "wav" | "flac" | "aac" | "pcm" | "opus">({
-						type: "string",
-						enum: ["mp3", "wav", "flac", "aac", "pcm", "opus"],
-						description: "Audio format. Default mp3",
-					}),
-				),
-				speed: Type.Optional(Type.Number({ description: "Speech speed. Default 1.0" })),
-				outputName: Type.Optional(Type.String({ description: "Optional base name for the output file" })),
-			}),
-		}),
-		defineMediaTool({
-			name: "nan_list_voices",
-			mcpTool: "list_voices",
-			label: "NaN List Voices",
-			description: "List all available kokoro TTS voices grouped by language.",
-			promptSnippet: "nan_list_voices(): list available kokoro TTS voices",
-			parameters: Type.Object({}),
-		}),
-		defineMediaTool({
-			name: "nan_speech_to_text",
-			mcpTool: "speech_to_text",
-			label: "NaN Speech To Text",
-			description: "Transcribe an audio file with whisper (NaN API STT). Returns the transcript.",
-			promptSnippet: "nan_speech_to_text(file, language?, verbose?): transcribe an audio file via NaN (whisper)",
-			parameters: Type.Object({
-				file: Type.String({ description: "Absolute path to the audio file to transcribe" }),
-				language: Type.Optional(
-					Type.String({ description: 'ISO-639-1 language code, e.g. "es", "en". Auto-detected if omitted' }),
-				),
-				verbose: Type.Optional(Type.Boolean({ description: "Return verbose JSON with segments instead of plain text" })),
-			}),
-		}),
-	];
-}