indusagi 0.13.7 → 0.13.8

package/dist/types/facade/bot/types.d.ts

@@ -0,0 +1,267 @@
+import type { AssistantMessageEvent, ImageContent, Message, Model, SimpleStreamOptions, streamSimple, TextContent, ThinkingContent, Tool, ToolCall, ToolResultMessage, UserMessage } from "../ml/index.js";
+import type { Static, TSchema } from "@sinclair/typebox";
+/** Streaming entry point; may resolve synchronously or via a Promise when config is fetched async. */
+export type StreamFn = (...args: Parameters<typeof streamSimple>) => ReturnType<typeof streamSimple> | Promise<ReturnType<typeof streamSimple>>;
+/**
+ * Reasoning effort tier requested from models that expose one.
+ * Heads up: the top "xhigh" tier is currently only honored by a few OpenAI
+ * frontier models; most providers cap out at "high".
+ */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+/**
+ * Open extension point for application-defined message kinds.
+ * Downstream code adds its own kinds by merging this module's interface:
+ *
+ * @example
+ * ```typescript
+ * declare module "./types.js" {
+ *   interface CustomAgentMessages {
+ *     reminder: ReminderMessage;
+ *     statusBanner: StatusBannerMessage;
+ *   }
+ * }
+ * ```
+ */
+export interface CustomAgentMessages {
+}
+/**
+ * AgentMessage: every base LLM message plus any app-registered custom kinds.
+ * The indirection lets applications introduce their own message kinds without
+ * giving up type safety against the underlying LLM message shapes.
+ */
+export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
+export type AgentToolUpdateCallback<T = any> = (partialResult: AgentToolResult<T>) => void;
+export interface AgentToolResult<T> {
+    content: (TextContent | ImageContent)[];
+    details: T;
+    isError?: boolean;
+}
+export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {
+    label: string;
+    /**
+     * Marks a tool that only inspects state and never mutates it (read/ls/grep/
+     * find/websearch/webfetch/todoread). Hosts can lean on this to auto-allow
+     * such tools in a permission policy without re-deriving the read-only set by
+     * name. Optional and defaults to undefined → treated as "not known read-only".
+     */
+    readOnly?: boolean;
+    execute: (toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
+}
+/**
+ * The verdict a {@link CanUseToolFn} returns for a single tool call.
+ *
+ * - `allow` proceeds with execution; an optional `updatedInput` replaces the
+ *   validated arguments before the tool runs (e.g. a sanitized command).
+ * - `deny` short-circuits: the tool never executes and `message` is surfaced as
+ *   an `isError` tool result so the model sees why it was blocked.
+ */
+export type PermissionDecision = {
+    behavior: "allow";
+    updatedInput?: unknown;
+} | {
+    behavior: "deny";
+    message: string;
+};
+/**
+ * Hard permission gate consulted immediately before a tool executes. Hosts
+ * supply it to enforce an allow/ask/deny policy; the loop awaits it (passing the
+ * abort signal so a pending prompt can be cancelled) and acts on the verdict.
+ *
+ * Entirely optional — when omitted the loop allows every tool, preserving
+ * today's behavior.
+ */
+export type CanUseToolFn = (toolName: string, input: unknown, opts: {
+    signal?: AbortSignal;
+}) => Promise<PermissionDecision>;
+export interface AgentContext {
+    systemPrompt: string;
+    messages: AgentMessage[];
+    tools?: AgentTool<any>[];
+}
+/**
+ * The agent's full runtime state: configuration plus live conversation data.
+ */
+export interface AgentState {
+    systemPrompt: string;
+    model: Model<any>;
+    thinkingLevel: ThinkingLevel;
+    tools: AgentTool<any>[];
+    messages: AgentMessage[];
+    isStreaming: boolean;
+    streamMessage: AgentMessage | null;
+    pendingToolCalls: Set<string>;
+    error?: string;
+}
+/**
+ * Settings that drive a single agent loop run.
+ */
+export interface AgentLoopConfig extends SimpleStreamOptions {
+    model: Model<any>;
+    /**
+     * Maps the AgentMessage[] down to a model-ready Message[] ahead of every model call.
+     *
+     * Every AgentMessage has to become a UserMessage, AssistantMessage, or
+     * ToolResultMessage. Anything the model shouldn't see (UI-only notices,
+     * status entries, and so on) is simply dropped here.
+     *
+     * @example
+     * ```typescript
+     * const flatten = (history: AgentMessage[]): Message[] =>
+     *   history.flatMap((entry) => {
+     *     // A bespoke kind gets restated as ordinary user text.
+     *     if (entry.role === "todo") {
+     *       return [{ role: "user", content: entry.content, timestamp: entry.timestamp }];
+     *     }
+     *     // Purely visual entries are withheld from the model.
+     *     if (entry.role === "diagnostic") {
+     *       return [];
+     *     }
+     *     // Everything else is already model-shaped, so pass it straight through.
+     *     return [entry];
+     *   });
+     * ```
+     */
+    convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    /**
+     * Optional hook that reshapes the context while it is still AgentMessages,
+     * i.e. before `convertToLlm` runs.
+     *
+     * Good fit for work that has to happen at the AgentMessage layer:
+     * - keeping the context window in check (trimming older entries)
+     * - pulling in extra context from elsewhere
+     *
+     * @example
+     * ```typescript
+     * const reshape = async (history: AgentMessage[]): Promise<AgentMessage[]> => {
+     *   const spent = await tallyTokens(history);
+     *   if (spent <= windowLimit) {
+     *     return history;
+     *   }
+     *   return trimFromFront(history, windowLimit);
+     * };
+     * ```
+     */
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    /**
+     * Supplies a fresh API key per model call.
+     *
+     * Handy when the credential is a short-lived OAuth token that can lapse
+     * while a slow stretch of tool calls is still running.
+     */
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    /**
+     * Hard permission gate consulted right before each tool executes. When set,
+     * the loop awaits it with the tool name and its VALIDATED arguments; a `deny`
+     * verdict short-circuits to an `isError` tool result (the tool never runs),
+     * while an `allow` verdict proceeds — substituting `updatedInput` when given.
+     *
+     * Omit it to allow every tool, i.e. exactly today's behavior.
+     */
+    canUseTool?: CanUseToolFn;
+    /**
+     * Yields steering messages to splice into the run while it is in flight.
+     *
+     * Consulted after each tool finishes to pick up user interruptions. When it
+     * hands back messages, any still-pending tool calls are abandoned and those
+     * messages join the context before the next model call.
+     *
+     * This is the channel for nudging the agent mid-task.
+     */
+    getSteeringMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Yields follow-up messages to handle once the agent is otherwise done.
+     *
+     * Consulted when there are no remaining tool calls and no steering input.
+     * Returning messages appends them and pushes the agent into another turn.
+     *
+     * Use it for input that should wait until the current work wraps up.
+     */
+    getFollowUpMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Names of tools that are safe to run concurrently because they only read
+     * (never mutate) state. Consecutive runs of such calls within one assistant
+     * turn are dispatched in parallel (bounded by {@link maxToolConcurrency});
+     * everything else still runs one-at-a-time in request order.
+     *
+     * When omitted the loop falls back to a conservative built-in set
+     * (`read`/`ls`/`grep`/`find`/`websearch`/`webfetch`/`todoread`). Tools that
+     * aren't on the list — including dynamic/MCP/composio tools — always run
+     * serially, preserving today's behavior.
+     */
+    readOnlyToolNames?: ReadonlySet<string>;
+    /**
+     * Upper bound on how many read-only tool calls run at once. Defaults to the
+     * `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` / `INDUS_MAX_TOOL_CONCURRENCY`
+     * environment override, or 10. Set to 1 to force fully-sequential dispatch.
+     */
+    maxToolConcurrency?: number;
+}
+type AgentLifecycleEvent = {
+    type: "agent_start";
+} | {
+    type: "agent_end";
+    messages: AgentMessage[];
+};
+type TurnEvent = {
+    type: "turn_start";
+} | {
+    type: "turn_end";
+    message: AgentMessage;
+    toolResults: ToolResultMessage[];
+};
+type MessageEvent = {
+    type: "message_start";
+    message: AgentMessage;
+} | {
+    type: "message_update";
+    message: AgentMessage;
+    assistantMessageEvent: AssistantMessageEvent;
+} | {
+    type: "message_end";
+    message: AgentMessage;
+};
+type ToolExecutionEvent = {
+    type: "tool_execution_start";
+    toolCallId: string;
+    toolName: string;
+    args: any;
+} | {
+    type: "tool_execution_update";
+    toolCallId: string;
+    toolName: string;
+    args: any;
+    partialResult: any;
+} | {
+    type: "tool_execution_end";
+    toolCallId: string;
+    toolName: string;
+    result: any;
+    isError: boolean;
+};
+/**
+ * The events the Agent streams out so a UI can stay in sync.
+ * They report granular lifecycle progress across messages, turns, and tool runs.
+ */
+export type AgentEvent = AgentLifecycleEvent | TurnEvent | MessageEvent | ToolExecutionEvent;
+/** Grouping of the event-type strings, handy for filtering or logging. */
+export declare const AGENT_EVENT_GROUPS: {
+    readonly agent: readonly ["agent_start", "agent_end"];
+    readonly turn: readonly ["turn_start", "turn_end"];
+    readonly message: readonly ["message_start", "message_update", "message_end"];
+    readonly toolExecution: readonly ["tool_execution_start", "tool_execution_update", "tool_execution_end"];
+};
+export type AgentEventType = AgentEvent["type"];
+export type ExtractAgentEvent<TType extends AgentEventType> = Extract<AgentEvent, {
+    type: TType;
+}>;
+/**
+ * Decide at runtime whether a value matches one of the recognized AI message shapes.
+ */
+export declare function validateMessage(value: unknown): value is Message;
+/** Narrows a value to a user message. */
+export declare function isUserMessage(value: AgentMessage | unknown): value is UserMessage;
+/** Narrows a value to a thinking block carried inside an assistant message. */
+export declare function isThinking(value: unknown): value is ThinkingContent;
+/** Narrows a value to a tool-call block carried inside an assistant message. */
+export declare function isToolCall(value: unknown): value is ToolCall;
+export {};

package/dist/types/facade/mcp-core/client-pool.d.ts

@@ -0,0 +1,105 @@
+/**
+ * MCP Client Pool
+ *
+ * Manages multiple MCP client connections.
+ * Provides centralized lifecycle management.
+ *
+ * Reference: MCP client configuration patterns.
+ */
+import { MCPClient } from "./client.js";
+import type { MCPConnectionOptions, MCPToolDefinition, MCPResource, MCPPrompt } from "./types.js";
+/**
+ * Options for creating an MCP client pool.
+ */
+export interface MCPClientPoolOptions {
+    /** List of server configurations */
+    servers: MCPConnectionOptions[];
+}
+/**
+ * Status of a connected server.
+ */
+export interface MCPServerStatus {
+    /** Server name */
+    name: string;
+    /** Whether connected */
+    connected: boolean;
+    /** Number of tools available */
+    toolCount?: number;
+    /** Number of resources available */
+    resourceCount?: number;
+    /** Number of prompts available */
+    promptCount?: number;
+}
+/**
+ * MCP Client Pool - manages multiple MCP server connections.
+ *
+ * @example
+ * ```typescript
+ * const pool = new MCPClientPool({
+ *   servers: [
+ *     { name: "filesystem", config: { command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "."] } },
+ *     { name: "github", config: { command: "npx", args: ["-y", "@modelcontextprotocol/server-github"] } },
+ *   ],
+ * });
+ *
+ * await pool.connectAll();
+ * const status = pool.getStatus();
+ * await pool.disconnectAll();
+ * ```
+ */
+export declare class MCPClientPool {
+    private options;
+    private clients;
+    private isConnecting;
+    constructor(options: MCPClientPoolOptions);
+    /**
+     * Connect to all configured servers.
+     *
+     * Errors for individual servers are logged but don't fail the entire operation.
+     */
+    connectAll(): Promise<void>;
+    /**
+     * Disconnect from all servers.
+     */
+    disconnectAll(): Promise<void>;
+    /**
+     * Get a specific client by name.
+     */
+    getClient(name: string): MCPClient | undefined;
+    /**
+     * Get all connected clients.
+     */
+    getAllClients(): MCPClient[];
+    /**
+     * Check if a client is connected.
+     */
+    isConnected(name: string): boolean;
+    /**
+     * Get status of all servers.
+     */
+    getStatus(): Promise<MCPServerStatus[]>;
+    /**
+     * Get all tools from all connected servers.
+     */
+    listAllTools(): Promise<Record<string, MCPToolDefinition[]>>;
+    /**
+     * Get all resources from all connected servers.
+     */
+    listAllResources(): Promise<Record<string, MCPResource[]>>;
+    /**
+     * Get all prompts from all connected servers.
+     */
+    listAllPrompts(): Promise<Record<string, MCPPrompt[]>>;
+    /**
+     * Reload all connections.
+     */
+    reload(): Promise<void>;
+    /**
+     * Add a new server connection.
+     */
+    addServer(config: MCPConnectionOptions): Promise<boolean>;
+    /**
+     * Remove a server connection.
+     */
+    removeServer(name: string): Promise<boolean>;
+}

package/dist/types/facade/mcp-core/client.d.ts

@@ -0,0 +1,245 @@
+/**
+ * MCP Client - Single Server Connection
+ *
+ * Manages connection to one MCP server and provides
+ * methods to list/call tools, read resources, etc.
+ *
+ * Transport is provided by the official `@modelcontextprotocol/sdk`:
+ *   - stdio  → subprocess JSON-RPC over stdin/stdout
+ *   - http   → Streamable HTTP (POST for client→server, plus a server→client
+ *              push channel — the SDK opens the SSE stream and a standalone GET
+ *              SSE for server-initiated messages, and handles reconnect/
+ *              session-expiry by re-using the session id)
+ *   - sse    → legacy HTTP+SSE transport (when `transport: "sse"` is requested)
+ *
+ * The SDK gives us a real persistent connection, a server→client push channel,
+ * dispatch of server NOTIFICATIONS, answering of server REQUESTS (elicitation,
+ * roots/list, sampling, ping), and bounded reconnect on a dropped stream /
+ * expired session — none of which the hand-rolled POST-only transport did.
+ */
+import { type OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { MCPServerConfig, MCPToolDefinition, MCPResource, MCPPrompt, MCPToolCallResult, MCPLogHandler, MCPProgressHandler, MCPElicitationHandler, MCPRoot } from "./types.js";
+/**
+ * Options for creating an MCP client.
+ */
+export interface MCPClientOptions {
+    /** Unique name for this client */
+    name: string;
+    /** Server connection configuration */
+    config: MCPServerConfig;
+    /** Optional timeout in milliseconds */
+    timeout?: number;
+    /** Optional log handler */
+    logger?: MCPLogHandler;
+    /** Whether to enable server logs (default: true) */
+    enableServerLogs?: boolean;
+    /** Whether to enable progress tracking (default: false) */
+    enableProgressTracking?: boolean;
+    /** Filesystem roots to expose to the server */
+    roots?: MCPRoot[];
+    /**
+     * OAuth client provider for the Streamable HTTP / SSE transport. When set,
+     * the SDK handles 401 → discover → PKCE → token-exchange → retry, plus
+     * mid-session refresh, automatically. Ignored for stdio.
+     *
+     * For first-time interactive auth the provider should also expose
+     * `waitForAuthorizationCode(): Promise<string>` (our
+     * {@link import("./oauth/provider.js").McpOAuthClientProvider} does). After
+     * the SDK throws UnauthorizedError we await that code, call
+     * `transport.finishAuth(code)`, and reconnect — matching the official
+     * MCP SDK CLI example.
+     */
+    authProvider?: OAuthClientProvider & {
+        waitForAuthorizationCode?: () => Promise<string>;
+        dispose?: () => void;
+    };
+}
+/**
+ * MCP Client - manages connection to a single MCP server.
+ *
+ * Supports stdio (subprocess) and HTTP (Streamable HTTP / legacy SSE) transports.
+ * Provides methods to list tools, call tools, read resources, etc.
+ *
+ * @example
+ * ```typescript
+ * const client = new MCPClient({
+ *   name: "filesystem",
+ *   config: {
+ *     command: "npx",
+ *     args: ["-y", "@modelcontextprotocol/server-filesystem", "."],
+ *   },
+ * });
+ *
+ * await client.connect();
+ * const tools = await client.listTools();
+ * const result = await client.callTool("read_file", { path: "./test.txt" });
+ * await client.disconnect();
+ * ```
+ */
+export declare class MCPClient {
+    private options;
+    private client?;
+    private transport?;
+    private isConnected;
+    private connectionPromise;
+    private serverCapabilities?;
+    private logHandler?;
+    private enableServerLogs;
+    private enableProgressTracking;
+    private _roots;
+    private elicitationHandler?;
+    private samplingHandler?;
+    private resourceUpdatedHandler?;
+    private resourceListChangedHandler?;
+    private toolListChangedHandler?;
+    private promptListChangedHandler?;
+    private progressHandler?;
+    /** Server name */
+    readonly serverName: string;
+    /** Server config */
+    readonly config: MCPServerConfig;
+    /** Request timeout */
+    readonly timeout: number;
+    constructor(options: MCPClientOptions);
+    /**
+     * Connect to the MCP server.
+     * Safe to call multiple times - returns existing connection if already connected.
+     */
+    connect(): Promise<void>;
+    private doConnect;
+    /**
+     * If `err` is an OAuth challenge and we have a provider + finishAuth-capable
+     * transport, wait for the browser code, exchange tokens, then reconnect on a
+     * **fresh** transport (the first transport is already `start()`ed and cannot
+     * be reused — see StreamableHTTPClientTransport.start).
+     *
+     * Matches the official SDK CLI example (`simpleOAuthClient`):
+     *   finishAuth(code) → new StreamableHTTPClientTransport → client.connect again
+     *
+     * Client.connect already called `close()` on init failure, so the Client is
+     * free to attach a new transport.
+     */
+    private tryFinishOAuthAndReconnect;
+    /** Turn raw SDK / network errors into a clearer MCPError for callers. */
+    private wrapConnectError;
+    /**
+     * Build the SDK transport for the configured server.
+     *
+     *  - stdio: `StdioClientTransport` (inherits the parent env, merges config.env).
+     *  - http:  `StreamableHTTPClientTransport` (POST + server-push SSE channel,
+     *           reconnect + session-expiry handled by the SDK), unless the config
+     *           asks for the legacy `SSEClientTransport`.
+     */
+    private createTransport;
+    /**
+     * Register handlers for server-initiated REQUESTS and NOTIFICATIONS.
+     *
+     * REQUESTS (have both `.method` AND `.id`) must be ANSWERED with a JSON-RPC
+     * RESPONSE carrying the matching id — the SDK does this automatically for the
+     * value a request handler returns (or rejects). The previous hand-rolled
+     * transport routed these into the notification path, so they were never
+     * answered (bug #13).
+     *
+     * Defaults:
+     *   - ping              → {}
+     *   - roots/list        → the configured roots
+     *   - elicitation/create→ decline ({action:"cancel"}) unless a host handler is set
+     *   - sampling          → reject "Method not found" unless a host handler is set
+     */
+    private registerServerHandlers;
+    /**
+     * Disconnect from the MCP server.
+     *
+     * The SDK's `client.close()` closes the transport and rejects any pending
+     * requests — a clean teardown for both stdio (graceful subprocess shutdown)
+     * and HTTP (close the push channel / end the session).
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Whether the client is connected.
+     */
+    get connected(): boolean;
+    /**
+     * List all tools available from the server.
+     */
+    listTools(): Promise<MCPToolDefinition[]>;
+    /**
+     * Call a tool on the server.
+     */
+    callTool(name: string, args: Record<string, unknown>): Promise<MCPToolCallResult>;
+    /**
+     * List all resources available from the server.
+     */
+    listResources(): Promise<MCPResource[]>;
+    /**
+     * Read a resource from the server.
+     */
+    readResource(uri: string): Promise<unknown>;
+    /**
+     * Subscribe to resource updates.
+     */
+    subscribeResource(uri: string): Promise<void>;
+    /**
+     * Unsubscribe from resource updates.
+     */
+    unsubscribeResource(uri: string): Promise<void>;
+    /**
+     * List all prompts available from the server.
+     */
+    listPrompts(): Promise<MCPPrompt[]>;
+    /**
+     * Get a prompt from the server.
+     */
+    getPrompt(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Get the configured roots.
+     */
+    get roots(): MCPRoot[];
+    /**
+     * Update the roots and notify the server.
+     */
+    setRoots(roots: MCPRoot[]): Promise<void>;
+    /**
+     * Set a handler for resource updated notifications.
+     */
+    setResourceUpdatedHandler(handler: (params: {
+        uri: string;
+    }) => void): void;
+    /**
+     * Set a handler for resource list changed notifications.
+     */
+    setResourceListChangedHandler(handler: () => void): void;
+    /**
+     * Set a handler for tool list changed notifications.
+     */
+    setToolListChangedHandler(handler: () => void): void;
+    /**
+     * Set a handler for prompt list changed notifications.
+     */
+    setPromptListChangedHandler(handler: () => void): void;
+    /**
+     * Set a handler for elicitation requests. When set, the server's
+     * `elicitation/create` REQUEST is answered with the host's decision; when
+     * unset the request is declined ({action:"cancel"}).
+     */
+    setElicitationHandler(handler: MCPElicitationHandler): void;
+    /**
+     * Set a handler for sampling (`sampling/createMessage`) requests. When set,
+     * the server request is answered with the host's result; when unset the
+     * request is rejected with "Method not found".
+     */
+    setSamplingHandler(handler: (params: unknown) => Promise<unknown>): void;
+    /**
+     * Set a handler for progress notifications.
+     */
+    setProgressHandler(handler: MCPProgressHandler): void;
+    private ensureConnected;
+    /**
+     * Normalize an SDK/transport error into an MCPError. Session-expiry style
+     * failures (404 session / -32001) are surfaced as SESSION_ERROR so callers
+     * (the pool) can decide to reconnect; the SDK's StreamableHTTP transport
+     * already attempts a bounded reconnect re-using the session id before this.
+     */
+    private wrapError;
+    private log;
+}

package/dist/types/facade/mcp-core/client.test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * MCP client transport tests (#23 / bug #13).
+ *
+ * These verify the server→client directions that the old hand-rolled,
+ * POST-only transport never handled:
+ *   1. A server-initiated REQUEST (`elicitation/create`) is ANSWERED with a
+ *      JSON-RPC RESPONSE carrying the matching id (not silently dropped into a
+ *      notification path).
+ *   2. A server-initiated NOTIFICATION (`notifications/tools/list_changed`)
+ *      fires the host-registered handler.
+ *   3. The HTTP path builds a real Streamable-HTTP transport with a server-push
+ *      channel, and an SSE-framed server message off that channel is parsed and
+ *      dispatched to the right handler.
+ *
+ * A `MockTransport` (implementing the SDK `Transport` interface) drives the
+ * client without a live MCP server.
+ */
+export {};

package/dist/types/facade/mcp-core/config.d.ts

@@ -0,0 +1,60 @@
+/**
+ * MCP Configuration Loading
+ *
+ * Loads MCP server configurations from XDG-compliant paths:
+ * - Project: ./.indusvx/mcp.json
+ * - User: ~/.config/indusvx/mcp.json (XDG)
+ * - Legacy: ~/.indusvx/agent/mcp.json
+ *
+ * Reference: MCP configuration loading patterns.
+ */
+import type { MCPConnectionOptions, MCPConfigFile } from "./types.js";
+/**
+ * Load MCP configuration from all sources.
+ *
+ * If a specific file path is provided, loads from that file directly.
+ * Otherwise merges configurations from:
+ * 1. Project-level config: ./.indusvx/mcp.json
+ * 2. User-level (XDG): ~/.config/indusvx/mcp.json
+ * 3. Legacy: ~/.indusvx/agent/mcp.json or ~/.indusvx/agent/mcp-servers.json
+ *
+ * @param configPathOrCwd - Either a specific config file path, or a working directory
+ * @returns Array of MCP connection options
+ */
+export declare function loadMCPConfig(configPathOrCwd?: string): MCPConnectionOptions[];
+/**
+ * Get the path where user config should be saved.
+ */
+export declare function getUserConfigPath(): string;
+/**
+ * Get the path where project config should be saved.
+ */
+export declare function getProjectConfigPath(cwd?: string): string;
+/**
+ * Ensure the user config directory exists.
+ */
+export declare function ensureUserConfigDir(): string;
+/**
+ * Ensure the project config directory exists.
+ */
+export declare function ensureProjectConfigDir(cwd?: string): string;
+/**
+ * Save configuration to a file.
+ */
+export declare function saveConfig(path: string, config: MCPConfigFile): void;
+/**
+ * Save user configuration.
+ */
+export declare function saveUserConfig(config: MCPConfigFile): void;
+/**
+ * Save project configuration.
+ */
+export declare function saveProjectConfig(config: MCPConfigFile, cwd?: string): void;
+/**
+ * Create a default configuration.
+ */
+export declare function createDefaultConfig(): MCPConfigFile;
+/**
+ * Example configuration for documentation.
+ */
+export declare const EXAMPLE_CONFIG: MCPConfigFile;