@gtrabanco/pi-nan-provider 0.7.0 → 0.10.0

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" })),
-			}),
-		}),
-	];
-}

package/src/mcp/nan-search.ts

@@ -1,241 +0,0 @@
-/**
- * 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";
-import { bridgeSource, resolveBridgeEnabled, type BridgeSource } from "./state.ts";
-
-/** 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 overrides the official web_search bridge: NAN_MCP_TOOLS=0|false|off disables it. */
-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";
-}
-
-/** Whether NAN_MCP_TOOLS is explicitly set (any value) — it overrides the persisted toggle. */
-export function mcpToolsEnvExplicit(): boolean {
-	const value = process.env[NAN_MCP_TOOLS_ENV];
-	return value !== undefined && value.trim() !== "";
-}
-
-/**
- * Effective enablement of the official web_search bridge: explicit
- * NAN_MCP_TOOLS env var wins (any value, e.g. 0 to force one session off);
- * then the toggle persisted by /nan-mcp; default: enabled.
- */
-export function webSearchBridgeEnabled(): boolean {
-	return resolveBridgeEnabled("webSearch", mcpToolsEnvExplicit(), !mcpToolsDisabled(), true);
-}
-
-/** Source of the effective web_search enablement (env / persisted / default). */
-export function webSearchBridgeSource(): BridgeSource {
-	return bridgeSource("webSearch", mcpToolsEnvExplicit());
-}
-
-/** 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

@@ -1,222 +0,0 @@
-/**
- * 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.1.2"]. */
-	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 },
-		});
-	});
-}