@agentionai/agents 1.0.2 → 1.2.0

package/dist/mcp/MCPClient.js

@@ -32,9 +32,50 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MCPClient = void 0;
+exports.MCPClient = exports.MCPClientEvent = void 0;
+const events_1 = __importDefault(require("events"));
 const Tool_1 = require("../tools/Tool");
+const content_1 = require("./content");
+const errors_1 = require("./errors");
+/**
+ * Names of the events an {@link MCPClient} emits.
+ *
+ * @example
+ * ```typescript
+ * mcp.on(MCPClientEvent.DISCONNECTED, ({ willReconnect }) => {
+ *   if (!willReconnect) scheduleManualReconnect();
+ * });
+ * ```
+ */
+class MCPClientEvent {
+}
+exports.MCPClientEvent = MCPClientEvent;
+/** Emitted after a successful {@link MCPClient.connect}. */
+MCPClientEvent.CONNECTED = "connected";
+/** Emitted whenever the connection is lost, deliberately or not. */
+MCPClientEvent.DISCONNECTED = "disconnected";
+/** Emitted before each automatic reconnect attempt. */
+MCPClientEvent.RECONNECTING = "reconnecting";
+/** Emitted when an automatic reconnect succeeds. */
+MCPClientEvent.RECONNECTED = "reconnected";
+/** Emitted when the server's tool list changes. */
+MCPClientEvent.TOOLS_CHANGED = "toolsChanged";
+/**
+ * Emitted for out-of-band transport errors and for failures inside background
+ * work such as reconnection or tool refresh.
+ */
+MCPClientEvent.ERROR = "error";
+const DEFAULT_RECONNECT = {
+    enabled: false,
+    maxRetries: 5,
+    initialDelayMs: 500,
+    maxDelayMs: 30000,
+    backoffFactor: 2,
+};
 /**
  * MCPClient connects to an MCP (Model Context Protocol) server and converts its
  * tools into agention-lib {@link Tool} instances that can be passed to any agent.
@@ -43,6 +84,9 @@ const Tool_1 = require("../tools/Tool");
  * - **stdio** — spawns a local process and communicates over stdin/stdout
  * - **http** — connects to a remote MCP server over Streamable HTTP
  *
+ * The client is an `EventEmitter`; see {@link MCPClientEvent} for the lifecycle
+ * events a host can watch.
+ *
  * @requires @modelcontextprotocol/sdk - Install as a peer dependency:
  * ```
  * npm install @modelcontextprotocol/sdk
@@ -81,6 +125,20 @@ const Tool_1 = require("../tools/Tool");
  * agent.addTools(mcp.getTools());
  * ```
  *
+ * @example Cancellable, time-boxed tool calls
+ * ```typescript
+ * let turn = new AbortController();
+ *
+ * const mcp = MCPClient.fromUrl("https://my-mcp-server.com/mcp", {
+ *   // Resolved per call, so each agent turn gets the current signal
+ *   callOptions: () => ({ signal: turn.signal, timeout: 20_000 }),
+ *   reconnect: { enabled: true },
+ * });
+ *
+ * // Interrupting the turn now aborts any in-flight MCP call
+ * turn.abort();
+ * ```
+ *
  * @example HTTP with OAuth
  * ```typescript
  * import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
@@ -90,25 +148,37 @@ const Tool_1 = require("../tools/Tool");
  * });
  * ```
  */
-class MCPClient {
+class MCPClient extends events_1.default {
     constructor(transportConfig, options = {}) {
+        super();
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.sdkClient = null;
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         this.sdkTransport = null;
         this._tools = [];
-        this.connected = false;
+        /** Signature per tool name, used to keep Tool identity stable across refreshes. */
+        this.toolSignatures = new Map();
+        this._state = "disconnected";
+        this.connectPromise = null;
+        this.reconnectPromise = null;
+        this.reconnectAttempts = 0;
+        this.reconnectTimer = null;
+        this.reconnectWake = null;
+        this.closedByUser = false;
         this.transportConfig = transportConfig;
-        this.options = {
-            clientName: options.clientName ?? "agention-mcp-client",
-            clientVersion: options.clientVersion ?? "1.0.0",
-        };
+        this.clientName = options.clientName ?? "agention-mcp-client";
+        this.clientVersion = options.clientVersion ?? "1.0.0";
+        this.callOptions = options.callOptions;
+        this.throwOnToolError = options.throwOnToolError ?? true;
+        this.refreshToolsOnListChanged = options.refreshToolsOnListChanged ?? true;
+        this.formatResult = options.formatResult;
+        this.reconnectOptions = { ...DEFAULT_RECONNECT, ...options.reconnect };
     }
     /**
      * Create an MCPClient that connects to a local MCP server process via stdio.
      *
      * @param config - Command and arguments to spawn the MCP server process
-     * @param options - Optional client identification options
+     * @param options - Optional client identification and behaviour options
      */
     static fromStdio(config, options) {
         return new MCPClient({ type: "stdio", config }, options);
@@ -130,14 +200,158 @@ class MCPClient {
     /**
      * Connect to the MCP server and discover all available tools.
      *
-     * This method is idempotent — calling it when already connected is a no-op.
+     * This method is idempotent — calling it when already connected is a no-op, and
+     * concurrent calls share a single connection attempt.
      * Must be called before {@link getTools}.
      *
      * @throws If the MCP server cannot be reached or the SDK is not installed
      */
     async connect() {
-        if (this.connected)
+        if (this._state === "connected")
             return;
+        if (this.connectPromise)
+            return this.connectPromise;
+        this.closedByUser = false;
+        this._state = "connecting";
+        this.connectPromise = this.establish()
+            .then(() => {
+            this._state = "connected";
+            this.reconnectAttempts = 0;
+            this.emitEvent(MCPClientEvent.CONNECTED, { tools: this._tools });
+        })
+            .catch((error) => {
+            this._state = "disconnected";
+            throw error;
+        })
+            .finally(() => {
+            this.connectPromise = null;
+        });
+        return this.connectPromise;
+    }
+    /**
+     * Return all tools discovered from the MCP server as agention-lib Tool instances.
+     *
+     * Returns an empty array if {@link connect} has not been called yet.
+     * The returned tools can be passed directly to any agent via the `tools` config
+     * option or {@link BaseAgent.addTools}.
+     *
+     * Tool instances are stable across reconnects and tool-list refreshes: a tool
+     * whose definition is unchanged keeps its identity, so agents already holding it
+     * keep working. Listen for {@link MCPClientEvent.TOOLS_CHANGED} to learn when the
+     * list itself changed.
+     */
+    getTools() {
+        return this._tools;
+    }
+    /**
+     * Current connection state.
+     *
+     * @see {@link MCPConnectionState}
+     */
+    getState() {
+        return this._state;
+    }
+    /** Whether the client currently has a usable connection. */
+    isConnected() {
+        return this._state === "connected";
+    }
+    /**
+     * Replace the default options applied to every tool call.
+     *
+     * Pass a function to have them resolved per call — the usual way to scope an
+     * `AbortSignal` to the current agent turn.
+     *
+     * @example
+     * ```typescript
+     * mcp.setCallOptions(() => ({ signal: currentTurn.signal, timeout: 15_000 }));
+     * ```
+     */
+    setCallOptions(options) {
+        this.callOptions = options;
+    }
+    /**
+     * Call an MCP tool directly and receive the raw `CallToolResult`, including any
+     * image, audio or resource blocks and the `isError` flag.
+     *
+     * Unlike the wrapped {@link Tool} instances from {@link getTools}, this does not
+     * render the result or throw on `isError` — it is the escape hatch for hosts
+     * that want to handle MCP content themselves.
+     *
+     * @param name - Name of the tool as advertised by the server
+     * @param input - Arguments for the tool
+     * @param options - Per-call options, merged over the client defaults
+     */
+    async callTool(name, input = {}, options) {
+        return this.invokeTool(name, input, options);
+    }
+    /**
+     * Re-run tool discovery against the connected server.
+     *
+     * Called automatically when the server sends `notifications/tools/list_changed`
+     * (unless `refreshToolsOnListChanged` is disabled) and after a successful
+     * reconnect. Emits {@link MCPClientEvent.TOOLS_CHANGED} when the list differs.
+     *
+     * @returns The refreshed tool list
+     */
+    async refreshTools() {
+        const sdkClient = this.sdkClient;
+        if (!sdkClient) {
+            throw new errors_1.MCPNotConnectedError("MCPClient: Cannot refresh tools — client is not connected", "", this._state);
+        }
+        const definitions = await this.listAllTools(sdkClient);
+        this.applyToolDefinitions(definitions);
+        return this._tools;
+    }
+    /**
+     * Disconnect from the MCP server and release all resources.
+     *
+     * This method is idempotent — calling it when not connected is a no-op. It also
+     * cancels any pending automatic reconnect. After disconnecting, {@link getTools}
+     * returns an empty array; call {@link connect} again to start over.
+     */
+    async disconnect() {
+        const wasActive = this._state !== "disconnected" || this.sdkClient !== null;
+        this.closedByUser = true;
+        this.cancelReconnectWait();
+        if (this.reconnectPromise) {
+            await this.reconnectPromise.catch(() => undefined);
+        }
+        try {
+            if (this.transportConfig.type === "http" && this.sdkTransport) {
+                await this.sdkTransport.terminateSession?.();
+            }
+            if (this.sdkClient) {
+                await this.sdkClient.close();
+            }
+        }
+        finally {
+            this.sdkClient = null;
+            this.sdkTransport = null;
+            this._tools = [];
+            this.toolSignatures.clear();
+            this.reconnectAttempts = 0;
+            this._state = "disconnected";
+        }
+        if (wasActive) {
+            this.emitEvent(MCPClientEvent.DISCONNECTED, {
+                deliberate: true,
+                willReconnect: false,
+            });
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    once(event, listener) {
+        return super.once(event, listener);
+    }
+    /**
+     * Open the SDK client and transport, wire up lifecycle handlers and discover
+     * tools. Shared by {@link connect} and the reconnect loop.
+     */
+    async establish() {
         // Build module paths at runtime so tsc does not attempt to resolve them at
         // compile time. @modelcontextprotocol/sdk is an optional peer dependency and
         // may not be installed on the build host.
@@ -145,7 +359,7 @@ class MCPClient {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const { Client } = await Promise.resolve(`${`${pkg}/client/index.js`}`).then(s => __importStar(require(s)));
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const sdkClient = new Client({ name: this.options.clientName, version: this.options.clientVersion }, { capabilities: {} });
+        const sdkClient = new Client({ name: this.clientName, version: this.clientVersion }, { capabilities: {} });
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         let transport;
         if (this.transportConfig.type === "stdio") {
@@ -166,53 +380,249 @@ class MCPClient {
                 ...(authProvider ? { authProvider } : {}),
             });
         }
+        // Registered before connect() so a notification arriving immediately after the
+        // handshake is not missed.
+        await this.subscribeToToolListChanges(sdkClient, pkg);
+        sdkClient.onclose = () => this.handleClose(sdkClient);
+        sdkClient.onerror = (error) => this.handleTransportError(sdkClient, error);
         await sdkClient.connect(transport);
         this.sdkClient = sdkClient;
         this.sdkTransport = transport;
-        this.connected = true;
-        // Paginate through all tools
-        const allMcpTools = [];
+        const definitions = await this.listAllTools(sdkClient);
+        this.applyToolDefinitions(definitions, { silent: this._tools.length === 0 });
+    }
+    /**
+     * Ask the server to notify us about tool list changes. Failures here are not
+     * fatal — an older SDK or a server without the capability simply means the
+     * cached list stays as it was at connect time.
+     */
+    async subscribeToToolListChanges(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    sdkClient, pkg) {
+        if (!this.refreshToolsOnListChanged)
+            return;
+        try {
+            const { ToolListChangedNotificationSchema } = (await Promise.resolve(`${
+            /* @vite-ignore */ `${pkg}/types.js`}`).then(s => __importStar(require(s))));
+            sdkClient.setNotificationHandler(ToolListChangedNotificationSchema, () => {
+                void this.refreshTools().catch((error) => this.emitError(error));
+            });
+        }
+        catch (error) {
+            this.emitError(error);
+        }
+    }
+    /** Page through `tools/list` until the server stops handing back a cursor. */
+    async listAllTools(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    sdkClient) {
+        const definitions = [];
         let cursor;
         do {
             const response = await sdkClient.listTools(cursor ? { cursor } : {});
-            allMcpTools.push(...response.tools);
+            definitions.push(...response.tools);
             cursor = response.nextCursor;
         } while (cursor);
-        this._tools = allMcpTools.map((mcpTool) => this.wrapMcpTool(mcpTool));
+        return definitions;
     }
     /**
-     * Return all tools discovered from the MCP server as agention-lib Tool instances.
-     *
-     * Returns an empty array if {@link connect} has not been called yet.
-     * The returned tools can be passed directly to any agent via the `tools` config
-     * option or {@link BaseAgent.addTools}.
+     * Reconcile the cached tool list with a fresh set of definitions, reusing the
+     * existing {@link Tool} instance for every definition that has not changed so
+     * agents holding a reference keep working.
      */
-    getTools() {
-        return this._tools;
+    applyToolDefinitions(definitions, { silent = false } = {}) {
+        const previous = new Map(this._tools.map((tool) => [tool.name, tool]));
+        const previousSignatures = this.toolSignatures;
+        const tools = [];
+        const signatures = new Map();
+        const added = [];
+        let changed = false;
+        for (const definition of definitions) {
+            const signature = JSON.stringify({
+                description: definition.description ?? null,
+                inputSchema: definition.inputSchema ?? null,
+            });
+            const existing = previous.get(definition.name);
+            if (existing && previousSignatures.get(definition.name) === signature) {
+                tools.push(existing);
+            }
+            else {
+                tools.push(this.wrapMcpTool(definition));
+                changed = true;
+                if (!existing)
+                    added.push(definition.name);
+            }
+            signatures.set(definition.name, signature);
+            previous.delete(definition.name);
+        }
+        const removed = [...previous.keys()];
+        this._tools = tools;
+        this.toolSignatures = signatures;
+        if (!silent && (changed || removed.length > 0)) {
+            this.emitEvent(MCPClientEvent.TOOLS_CHANGED, { tools, added, removed });
+        }
     }
     /**
-     * Disconnect from the MCP server and release all resources.
-     *
-     * This method is idempotent — calling it when not connected is a no-op.
-     * After disconnecting, {@link getTools} returns an empty array.
+     * Handle the transport closing. Deliberate closes are reported by
+     * {@link disconnect} itself; everything else is an unexpected drop.
      */
-    async disconnect() {
-        if (!this.connected)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handleClose(sdkClient) {
+        if (this.closedByUser)
             return;
-        try {
-            if (this.transportConfig.type === "http" && this.sdkTransport) {
-                await this.sdkTransport.terminateSession?.();
-            }
-            if (this.sdkClient) {
-                await this.sdkClient.close();
+        // A close from a client we have already replaced or abandoned is stale.
+        if (this.sdkClient !== sdkClient)
+            return;
+        this.sdkClient = null;
+        this.sdkTransport = null;
+        const willReconnect = this.reconnectOptions.enabled && this.reconnectAttempts < this.reconnectOptions.maxRetries;
+        // A transport that fails reports the cause through onerror just before it
+        // closes, so the most recent one is the reason for this drop.
+        const error = this.lastTransportError;
+        this.lastTransportError = undefined;
+        this._state = willReconnect ? "reconnecting" : "failed";
+        this.emitEvent(MCPClientEvent.DISCONNECTED, {
+            ...(error ? { error } : {}),
+            deliberate: false,
+            willReconnect,
+        });
+        if (willReconnect)
+            this.startReconnectLoop();
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handleTransportError(sdkClient, error) {
+        if (this.sdkClient !== null && this.sdkClient !== sdkClient)
+            return;
+        this.lastTransportError = error instanceof Error ? error : new Error(String(error));
+        this.emitError(error);
+    }
+    /**
+     * Retry {@link establish} with exponential backoff until it succeeds, the retry
+     * budget runs out, or {@link disconnect} is called.
+     */
+    startReconnectLoop() {
+        if (this.reconnectPromise)
+            return;
+        this.reconnectPromise = (async () => {
+            while (!this.closedByUser) {
+                const attempt = ++this.reconnectAttempts;
+                const delayMs = Math.min(this.reconnectOptions.initialDelayMs *
+                    Math.pow(this.reconnectOptions.backoffFactor, attempt - 1), this.reconnectOptions.maxDelayMs);
+                this.emitEvent(MCPClientEvent.RECONNECTING, { attempt, delayMs });
+                await this.waitBeforeReconnect(delayMs);
+                if (this.closedByUser)
+                    return;
+                try {
+                    await this.establish();
+                    this._state = "connected";
+                    this.reconnectAttempts = 0;
+                    this.emitEvent(MCPClientEvent.RECONNECTED, { tools: this._tools });
+                    return;
+                }
+                catch (error) {
+                    this.emitError(error);
+                    if (attempt >= this.reconnectOptions.maxRetries) {
+                        this._state = "failed";
+                        return;
+                    }
+                }
             }
+        })().finally(() => {
+            this.reconnectPromise = null;
+        });
+    }
+    waitBeforeReconnect(delayMs) {
+        return new Promise((resolve) => {
+            this.reconnectWake = resolve;
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = null;
+                this.reconnectWake = null;
+                resolve();
+            }, delayMs);
+        });
+    }
+    cancelReconnectWait() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
         }
-        finally {
-            this.sdkClient = null;
-            this.sdkTransport = null;
-            this._tools = [];
-            this.connected = false;
+        if (this.reconnectWake) {
+            const wake = this.reconnectWake;
+            this.reconnectWake = null;
+            wake();
+        }
+    }
+    /**
+     * `EventEmitter` throws when an `error` event has no listener, which would turn
+     * a background transport hiccup into a process crash. Only emit when someone is
+     * actually listening.
+     */
+    emitError(error) {
+        if (this.listenerCount(MCPClientEvent.ERROR) === 0)
+            return;
+        this.emit(MCPClientEvent.ERROR, error instanceof Error ? error : new Error(String(error)));
+    }
+    emitEvent(event, payload) {
+        this.emit(event, payload);
+    }
+    /**
+     * Resolve the effective request options for a call: client defaults (static or
+     * per-call), with explicit per-call options layered on top.
+     */
+    resolveCallOptions(context, overrides) {
+        const defaults = typeof this.callOptions === "function" ? this.callOptions(context) : this.callOptions;
+        const merged = { ...defaults, ...overrides };
+        const hasOption = Object.values(merged).some((value) => value !== undefined);
+        return hasOption ? merged : undefined;
+    }
+    /**
+     * Wait for the client to become usable, then issue the call. Wrapping every
+     * transport-level failure keeps the error surface stable, while `cause` lets a
+     * host tell an abort apart from a server error.
+     */
+    async invokeTool(name, input, overrides) {
+        const callOptions = this.resolveCallOptions({ toolName: name, input }, overrides);
+        const sdkClient = await this.awaitUsableClient(name, callOptions?.signal);
+        try {
+            const params = { name, arguments: input };
+            return callOptions
+                ? await sdkClient.callTool(params, undefined, callOptions)
+                : await sdkClient.callTool(params);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new errors_1.MCPCallError(`MCPClient: Tool "${name}" execution failed: ${message}`, name, error);
+        }
+    }
+    /**
+     * Return the SDK client once one is usable. While a reconnect is in flight the
+     * call waits for it rather than failing outright, so a transient drop does not
+     * surface as a tool error — but an aborted signal still wins immediately.
+     */
+    async awaitUsableClient(toolName, signal
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ) {
+        if (signal?.aborted) {
+            throw new errors_1.MCPCallError(`MCPClient: Tool "${toolName}" execution failed: request was aborted`, toolName, signal.reason);
+        }
+        if (this._state === "reconnecting" && this.reconnectPromise) {
+            await this.raceAbort(this.reconnectPromise, toolName, signal);
         }
+        if (this._state !== "connected" || !this.sdkClient) {
+            throw new errors_1.MCPNotConnectedError(`MCPClient: Cannot execute tool "${toolName}" — client is not connected`, toolName, this._state);
+        }
+        return this.sdkClient;
+    }
+    raceAbort(promise, toolName, signal) {
+        if (!signal)
+            return promise;
+        return new Promise((resolve, reject) => {
+            const onAbort = () => reject(new errors_1.MCPCallError(`MCPClient: Tool "${toolName}" execution failed: request was aborted`, toolName, signal.reason));
+            signal.addEventListener("abort", onAbort, { once: true });
+            promise
+                .then(resolve, reject)
+                .finally(() => signal.removeEventListener("abort", onAbort));
+        });
     }
     wrapMcpTool(mcpTool) {
         const inputSchema = {
@@ -225,37 +635,16 @@ class MCPClient {
             description: mcpTool.description ?? mcpTool.name,
             inputSchema,
             execute: async (input) => {
-                if (!this.connected || !this.sdkClient) {
-                    throw new Error(`MCPClient: Cannot execute tool "${mcpTool.name}" — client is not connected`);
-                }
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                let result;
-                try {
-                    result = await this.sdkClient.callTool({
-                        name: mcpTool.name,
-                        arguments: input,
-                    });
-                }
-                catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
-                    throw new Error(`MCPClient: Tool "${mcpTool.name}" execution failed: ${message}`);
-                }
-                // Extract text content items from MCP result
-                if (result?.content && Array.isArray(result.content)) {
-                    const textItems = result.content
-                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                        .filter((item) => item.type === "text")
-                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                        .map((item) => item.text);
-                    if (textItems.length > 0) {
-                        return textItems.length === 1 ? textItems[0] : textItems.join("\n");
-                    }
-                }
-                // Fall back to structured content or full JSON serialization
-                if (result?.structuredContent !== undefined) {
-                    return result.structuredContent;
+                const result = await this.invokeTool(mcpTool.name, input ?? {});
+                const context = { toolName: mcpTool.name, input: input ?? {} };
+                if (result?.isError && this.throwOnToolError) {
+                    const rendered = (0, content_1.renderToolResult)(result);
+                    const detail = typeof rendered === "string" ? rendered : JSON.stringify(rendered);
+                    throw new errors_1.MCPToolError(`MCPClient: Tool "${mcpTool.name}" reported an error: ${detail}`, mcpTool.name, result);
                 }
-                return JSON.stringify(result ?? null);
+                return this.formatResult
+                    ? this.formatResult(result, context)
+                    : (0, content_1.renderToolResult)(result);
             },
         });
     }

package/dist/mcp/content.d.ts

@@ -0,0 +1,28 @@
+import type { MCPCallToolResult, MCPContentBlock } from "./types";
+/**
+ * Render a single MCP content block as text.
+ *
+ * Text blocks are returned verbatim. Binary blocks (image, audio, blob
+ * resources) cannot be represented as text, so they are rendered as a
+ * descriptive placeholder carrying their mime type and size — enough for a model
+ * to know the content exists and to ask for it another way. Text-bearing
+ * resources are inlined under a header naming their URI.
+ *
+ * Unrecognised block types — content types added to the protocol after this
+ * release — are serialised as JSON rather than dropped.
+ */
+export declare function renderContentBlock(block: MCPContentBlock): string;
+/**
+ * Convert a raw MCP `CallToolResult` into the value handed to the agent.
+ *
+ * Resolution order:
+ * 1. When the result has content blocks, every block is rendered and the
+ *    segments are joined with newlines. `structuredContent` is appended as JSON
+ *    when the result carries no text block, so structured output is never lost
+ *    behind a binary-only result.
+ * 2. Otherwise `structuredContent` is returned as-is, so tools with an
+ *    `outputSchema` keep giving the agent a real object.
+ * 3. Otherwise the whole result is JSON-serialised.
+ */
+export declare function renderToolResult(result: MCPCallToolResult | null | undefined): unknown;
+//# sourceMappingURL=content.d.ts.map