import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
import { type McpServerInfo, type McpSession, type McpToolDescriptor } from "./mcp-session.js";
import type { JsonRpcStdioOptions } from "./json-rpc-stdio.js";
export interface SynthesizeOptions {
    /** Prefix applied to every tool name (e.g. "grove_"). */
    namePrefix: string;
    /** Optional steering bullets appended to the system prompt while active. */
    promptGuidelines?: string[];
}
/**
 * Build a pi ToolDefinition for one MCP tool descriptor. The execute() handler
 * proxies to session.callTool and maps the MCP result onto pi's result shape;
 * any transport failure is surfaced as an isError result (never thrown into the
 * agent loop).
 */
export declare function buildToolDefinition(session: McpSession, descriptor: McpToolDescriptor, opts: SynthesizeOptions): ToolDefinition;
/** Synthesize a pi ToolDefinition for every descriptor the server advertised. */
export declare function synthesizeTools(session: McpSession, descriptors: McpToolDescriptor[], opts: SynthesizeOptions): ToolDefinition[];
export interface McpAttachment {
    /** The synthesized pi tools, ready for pi.registerTool / subagent injection. */
    tools: ToolDefinition[];
    /** Prefixed tool names (for logging / orientation). */
    toolNames: string[];
    /** Server identity (name/version) from the handshake, when advertised. */
    serverInfo?: McpServerInfo;
    /** The live session (kept open for the duration of the pi session). */
    session: McpSession;
    /** Tear down the underlying child process. */
    dispose: () => Promise<void>;
}
export interface AttachMcpServerOptions extends JsonRpcStdioOptions, SynthesizeOptions {
}
/**
 * Spawn an MCP stdio server, perform the handshake, discover its tools, and
 * synthesize pi ToolDefinitions. Throws if the handshake or discovery fails (the
 * caller decides whether that is fatal — for grove it is a graceful no-op).
 */
export declare function attachMcpServer(opts: AttachMcpServerOptions): Promise<McpAttachment>;