@superdurable/dex-agents 0.1.0 → 0.3.0

package/dist/src/mcp/mcp-tool-source.d.ts

@@ -0,0 +1,470 @@
+import { type CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type AgentEventWriter, type AgentTurnContext, type DeferredToolCall, type DeferredToolExecution, type McpToolAnnotations, type ToolExecutionResult, type ToolPolicy, type ToolTaskCancellation, type ToolTaskPoll, type ToolTaskPollOutcome, type ToolTaskStarted } from "../agent-framework-runner.js";
+import type { ToolEffect } from "../agent-session-values.js";
+import type { SourceToolDefinition } from "../stepwise/tool-source.js";
+import { type McpServerConfig } from "./mcp-server-config.js";
+/** `_meta` key that carries the session's idempotency key on every `tools/call`. */
+export declare const mcpIdempotencyKeyMetaKey = "io.superdurable.dex/idempotencyKey";
+/** `AgentEvents` type for an MCP `notifications/progress` of a running tool call. */
+export declare const mcpToolProgressEventType = "mcp.tool_progress";
+/** `AgentEvents` type for each observed status of an MCP task. */
+export declare const mcpTaskStatusEventType = "mcp.task_status";
+/** Default bound on one MCP `tools/call` or task request, in milliseconds: 10 minutes. */
+export declare const defaultMcpRequestTimeoutMs = 600000;
+/** Default bound on polling one MCP task inside one tool Step attempt, in milliseconds: 10 minutes. */
+export declare const defaultMcpTaskWaitTimeoutMs = 600000;
+/** Default TTL the source requests for a task that `PollToolTask` polls, in milliseconds: 24 hours. */
+export declare const defaultMcpTaskTtlMs = 86400000;
+/** Default bound on connecting, the `initialize` handshake, and `tools/list`, in milliseconds: 30 seconds. */
+export declare const defaultMcpConnectionTimeoutMs = 30000;
+/** Default number of connection attempts before a request reports the server unreachable. */
+export declare const defaultMcpConnectionAttempts = 3;
+/** Default {@link McpToolSourceOptions.sourceName}, which stored Stepwise calls are routed by. */
+export declare const defaultMcpSourceName = "mcp";
+/** Default age in milliseconds after which `listTools` lists a server again, in the background: 5 minutes. */
+export declare const defaultMcpListingTtlMs = 300000;
+/** Default wait in milliseconds after a failed listing before `listTools` tries that server again: 30 seconds. */
+export declare const defaultMcpListingFailureBackoffMs = 30000;
+/** Handler that runs one deferred tool call, as {@link McpToolSource.executeDeferredToolCall} does. */
+export type DeferredToolHandler = (call: DeferredToolExecution) => Promise<ToolExecutionResult | ToolTaskStarted>;
+/** One MCP tool described as an agent tool definition, returned by {@link McpToolSource.listTools}. */
+export interface McpTool {
+    /**
+     * Agent tool name, `<serverName>__<mcpToolName>`. Characters other than letters, digits, `_`, and
+     * `-` become `_`. A name longer than 64 characters is cut to 55 and ends with `_` and 8 hex digits
+     * of its SHA-256. Key {@link ToolPolicy} entries by this name. The resource and prompt tools have the fixed
+     * names `mcp_list_resources_and_prompts`, `mcp_read_resource`, and `mcp_get_prompt`.
+     */
+    readonly name: string;
+    /**
+     * Name of the configured server that offers the tool, or `""` for a resource and prompt tool, which takes the
+     * server as its `server` argument.
+     */
+    readonly serverName: string;
+    /** The tool's name on its MCP server, or `""` for a resource and prompt tool. */
+    readonly mcpToolName: string;
+    /** Tool description for the model. */
+    readonly description: string;
+    /** JSON Schema of the tool's arguments object. */
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    /** The server's behavior hints, or `undefined` when it sent none. */
+    readonly annotations: McpToolAnnotations | undefined;
+    /**
+     * Effect from {@link toolEffectFromMcpToolAnnotations} when the server configuration trusts the
+     * annotations, else `undefined`. An explicit {@link ToolPolicy} overrides it.
+     */
+    readonly frameworkEffect: ToolEffect | undefined;
+    /**
+     * The tool's MCP `execution.taskSupport`. A `required` tool is called as a task; see
+     * {@link McpToolSource} for who polls it.
+     */
+    readonly taskSupport: "required" | "optional" | "forbidden" | undefined;
+}
+/** Options of {@link McpToolSource}. */
+export interface McpToolSourceOptions {
+    /**
+     * Bound on one `tools/call` or task request in milliseconds. A `tools/call` that times out throws
+     * {@link McpToolCallInterruptedError}. Defaults to {@link defaultMcpRequestTimeoutMs}.
+     */
+    readonly requestTimeoutMs?: number;
+    /**
+     * Bound on polling one MCP task inside one tool Step attempt, in milliseconds: a stdio server's task, a
+     * task of a server that keeps protocol sessions, and any task that {@link McpToolSource.callTool}
+     * polls. When it passes, the source throws {@link McpToolCallInterruptedError} and leaves the task
+     * running; a retried attempt resumes polling it. The source requests such a task's TTL as four times
+     * this bound, so the task outlives every attempt. Defaults to {@link defaultMcpTaskWaitTimeoutMs}.
+     */
+    readonly taskWaitTimeoutMs?: number;
+    /**
+     * TTL the source requests for a task that `PollToolTask` polls, in milliseconds. The server keeps the
+     * task and its result for this long after it creates the task, and it may grant less. `PollToolTask`
+     * polls on Timers that outlive Worker restarts, so the TTL must cover the task's run time plus the
+     * longest time no Worker serves the session; a task whose TTL passes first is lost, and the call is
+     * recorded by its effect. Defaults to {@link defaultMcpTaskTtlMs}, 24 hours.
+     */
+    readonly taskTtlMs?: number;
+    /**
+     * Bound on connecting, the `initialize` handshake, and each `tools/list` request, in milliseconds.
+     * Defaults to {@link defaultMcpConnectionTimeoutMs}.
+     */
+    readonly connectionTimeoutMs?: number;
+    /** Connection attempts per request. Defaults to {@link defaultMcpConnectionAttempts}. */
+    readonly connectionAttempts?: number;
+    /** `clientInfo.name` sent to the servers. Defaults to `dex-agents`. */
+    readonly clientName?: string;
+    /**
+     * Whether {@link McpToolSource.listTools} also offers `mcp_list_resources_and_prompts`, `mcp_read_resource`,
+     * and `mcp_get_prompt`, after the servers' tools, when at least one server is configured. Their requests are
+     * bounded by `connectionTimeoutMs`. Defaults to `false`. Enable it on one source of an agent only: two sources
+     * with it list the same names, which the Stepwise runner refuses. See {@link McpToolSource}.
+     */
+    readonly resourceAndPromptToolsEnabled?: boolean;
+    /**
+     * Age in milliseconds after which {@link McpToolSource.listTools} lists a server again. The refresh runs in the
+     * background, and the earlier listing is returned meanwhile. Defaults to {@link defaultMcpListingTtlMs}.
+     */
+    readonly listingTtlMs?: number;
+    /**
+     * How long in milliseconds {@link McpToolSource.listTools} leaves a server that failed to list alone before it
+     * tries again, in the background. Defaults to {@link defaultMcpListingFailureBackoffMs}.
+     */
+    readonly listingFailureBackoffMs?: number;
+    /**
+     * The source's stable name in a Stepwise agent's `toolSources`, which stored calls are routed by. Defaults to
+     * {@link defaultMcpSourceName}, `"mcp"`, so adding or removing a server keeps it. An agent with two `McpToolSource`
+     * instances must name at least one, because names must be unique.
+     */
+    readonly sourceName?: string;
+}
+/** Per-call options of {@link McpToolSource.callTool}. */
+export interface McpToolCallOptions {
+    /** Key sent in `_meta` under {@link mcpIdempotencyKeyMetaKey}. Defaults to none. */
+    readonly idempotencyKey?: string;
+    /** Tool call ID stamped on progress and task events. */
+    readonly toolCallId?: string;
+    /** Writer for `mcp.tool_progress` and `mcp.task_status` events. */
+    readonly events?: AgentEventWriter;
+    /** Awaited between task polls. */
+    readonly heartbeat?: () => Promise<void>;
+    /** `DeferredToolExecution.heartbeatCheckpoint`, so a retried attempt resumes the earlier attempt's task. */
+    readonly heartbeatCheckpoint?: string;
+    /** `DeferredToolExecution.saveHeartbeatCheckpoint`, so an MCP task survives a retry. */
+    readonly saveHeartbeatCheckpoint?: (checkpoint: string) => Promise<void>;
+    /** Aborts the requests, for example the tool Step's cancellation signal. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * A `tools/call` that reached an MCP server but returned no result.
+ *
+ * {@link McpToolSource} throws it when the connection broke, the request timed out, the server process
+ * exited, the server or a gateway answered with an internal error, an HTTP error status, or an unreadable
+ * body, or an MCP task stopped being observable. The tool may or may not have taken effect. It is not a
+ * {@link ToolExecutionError}, so the tool Step's effect decides what happens next: `CallTool` re-issues
+ * a `read` or `idempotent_write` call as a new request with the same idempotency key, and
+ * `CallSingleAttemptTool` records `outcome_unknown` for the other effects and never sends it again.
+ */
+export declare class McpToolCallInterruptedError extends Error {
+    readonly serverName: string;
+    readonly mcpToolName: string;
+    readonly detail: string;
+    /**
+     * Creates the error.
+     * @param serverName - Configured name of the MCP server.
+     * @param mcpToolName - The tool's name on that server.
+     * @param detail - What went wrong.
+     */
+    constructor(serverName: string, mcpToolName: string, detail: string);
+}
+/**
+ * No configured MCP server could be listed.
+ *
+ * {@link McpToolSource.listTools} leaves out a server it cannot list and logs a warning; it throws this
+ * error only when every configured server failed and none has an earlier listing. Thrown from
+ * `runModelStep`, it fails the `RunModel` attempt, which retries.
+ */
+export declare class McpToolListingError extends Error {
+    readonly serverName: string;
+    readonly detail: string;
+    /**
+     * Creates the error.
+     * @param serverName - Configured name of the last MCP server that failed.
+     * @param detail - What went wrong with that server.
+     */
+    constructor(serverName: string, detail: string);
+}
+declare const nodeInspectSymbol: unique symbol;
+/**
+ * Offers the tools of configured MCP servers to an agent, one Dex Step per call.
+ *
+ * Configure the servers on the Worker, never from Flow input, a user message, or a browser.
+ * {@link listTools} lists each server's tools and caches them per server as {@link McpTool} definitions
+ * that a runner offers to the model. When the model calls one, the runner returns
+ * {@link deferredToolCall}, so the session runs the call in its own tool Step, and the Step calls
+ * {@link executeDeferredToolCall}. No MCP call runs inside `RunModel`. {@link deferredToolCall} stores
+ * the server and the tool's MCP name on the call's record, so the tool Step calls that server directly,
+ * whatever the other servers do.
+ *
+ * Each tool's effect comes from its annotations through {@link toolEffectFromMcpToolAnnotations}:
+ * `readOnlyHint` makes it `read`, and `idempotentHint` makes it `idempotent_write`. Any other tool gets
+ * the session's `defaultToolEffect`, `unclassified` by default. Annotations are trusted by default. A
+ * {@link ToolPolicy} in `AgentSessionOptions.toolPolicies` keyed by {@link McpTool.name} wins.
+ *
+ * The source uses `@modelcontextprotocol/sdk` 1.x, which speaks MCP up to 2025-11-25: every request
+ * opens a new connection, performs the `initialize` handshake, ends the HTTP protocol session, and
+ * closes it, so no protocol session outlives a request. Every `tools/call` carries the session's
+ * idempotency key in `_meta` under {@link mcpIdempotencyKeyMetaKey}.
+ *
+ * Results map onto the session contract:
+ * - A result becomes the tool output: text blocks joined with newlines, other blocks and structured
+ *   content as JSON.
+ * - An `isError` result, a JSON-RPC error response other than an internal error, and a failed,
+ *   cancelled, or `input_required` task throw {@link ToolExecutionError}, so the session records
+ *   `failed` and the model sees the text. The 2025-11-25 tasks deliver input requests as server requests
+ *   that must be answered on a live connection, so no durable question can carry them; the source cancels
+ *   an `input_required` task.
+ * - No result after the request was sent throws {@link McpToolCallInterruptedError}; the tool Step's
+ *   effect decides whether it is re-issued.
+ * - A call that was never sent, because its server is not configured or cannot be reached, throws
+ *   {@link ToolExecutionError}.
+ * - A tool whose `execution.taskSupport` is `required` is called as a task. A Streamable HTTP server
+ *   without protocol sessions gets {@link ToolTaskStarted}: the tool Step ends, and `PollToolTask` calls
+ *   {@link pollToolTask} on a Timer, so no Step or connection is held while the task runs. The source
+ *   requests a TTL of `taskTtlMs` for such a task. `cancel_turn` abandons the task, and
+ *   {@link cancelToolTask} sends `tasks/cancel`.
+ * - A stdio server's task lives in its process, and a server that keeps protocol sessions, as the SDK's
+ *   task store does, binds its tasks to the session, which ends with the request. The tool Step polls
+ *   such a task with `tasks/get`, with a heartbeat per poll, for at most `taskWaitTimeoutMs` per attempt.
+ *   A retried attempt of a stateful server's call cannot see the task from its new session, so it calls
+ *   the tool again.
+ * - For a Streamable HTTP server the task ID is saved as the attempt's heartbeat checkpoint before
+ *   anything else, so once that checkpoint reaches Dex, a retried attempt resumes the same task instead of
+ *   calling again. Dex may drop a heartbeat checkpoint; the idempotency key lets the server drop the
+ *   duplicate then.
+ * - Without `DeferredToolExecution.supportsToolTasks`, for a runner without `pollToolTask`, the tool Step
+ *   polls every task itself, as {@link callTool} does.
+ *
+ * With `resourceAndPromptToolsEnabled`, the listing also offers three `read` tools for the servers' resources
+ * and prompts: `mcp_list_resources_and_prompts` lists a server's resources, resource templates, and prompts;
+ * `mcp_read_resource` reads one resource by URI; and `mcp_get_prompt` gets one prompt with its arguments. Each
+ * takes the configured server's name as its `server` argument and opens a new connection to that server with
+ * the same transport and headers as a tool call. Its output is the server's answer as JSON with sorted keys:
+ * `{"resources", "resource_templates", "prompts"}`, `{"contents"}`, or `{"messages", "description"}`. A server
+ * that does not offer resources or prompts lists none of them. An MCP error answer throws
+ * {@link ToolExecutionError}. The names, descriptions, and argument schemas match the Python core. Both cores
+ * support every resource and prompt request that `@modelcontextprotocol/sdk` 1.32.2 supports; this core does
+ * not follow `notifications/resources/list_changed` or subscribe to resources, and neither does Python.
+ *
+ * Share one source between the parallel tool Steps of a Worker; build it once at startup.
+ *
+ * @example
+ * ```ts
+ * const tools = new McpToolSource([
+ *   { transport: "stdio", name: "files", command: "mcp-server-files" },
+ *   { transport: "streamable_http", name: "tickets", url: ticketsUrl },
+ * ]);
+ * class MyRunner implements AgentFrameworkRunner {
+ *   // buildUserMessage omitted
+ *   public async runModelStep(turn: AgentTurnContext): Promise<AgentTurnOutcome> {
+ *     const offered = await tools.listTools(); // name, description, inputSchema
+ *     const response = await callMyModel(turn.messages, offered);
+ *     return {
+ *       kind: "tool_calls_requested",
+ *       frameworkRunState: JSON.stringify(response),
+ *       usage: response.usage,
+ *       toolCalls: response.toolCalls.map((call) =>
+ *         tools.deferredToolCall(turn, { toolCallId: call.id, toolName: call.name, arguments: call.arguments })),
+ *     };
+ *   }
+ *   public executeDeferredToolCall(call: DeferredToolExecution): Promise<ToolExecutionResult | ToolTaskStarted> {
+ *     return tools.executeDeferredToolCall(call);
+ *   }
+ *   public pollToolTask(poll: ToolTaskPoll): Promise<ToolTaskPollOutcome> {
+ *     return tools.pollToolTask(poll);
+ *   }
+ *   public cancelToolTask(cancellation: ToolTaskCancellation): Promise<void> {
+ *     return tools.cancelToolTask(cancellation);
+ *   }
+ * }
+ * ```
+ */
+export declare class McpToolSource {
+    private readonly servers;
+    private readonly requestTimeoutMs;
+    private readonly taskWaitTimeoutMs;
+    private readonly taskTtlMs;
+    private readonly connectionTimeoutMs;
+    private readonly connectionAttempts;
+    private readonly connector;
+    private readonly listings;
+    private readonly listingTtlMs;
+    private readonly listingFailureBackoffMs;
+    private readonly configuredSourceName;
+    private tools;
+    private readonly resourceAndPromptTools;
+    /**
+     * Describes the servers without connecting to them.
+     * @param servers - Server configurations with unique names.
+     * @param options - Timeouts, connection attempts, and client name.
+     * @throws {TypeError} When a configuration is invalid, server names repeat, a timeout, `taskTtlMs`,
+     * `listingTtlMs`, or `listingFailureBackoffMs` is not positive, or `connectionAttempts` is less than 1.
+     */
+    constructor(servers: readonly McpServerConfig[], options?: McpToolSourceOptions);
+    /**
+     * Returns the tools of every reachable configured server.
+     *
+     * Each server is listed on its own and cached per Worker process. The first listing of a server is awaited.
+     * After that, a listing older than `listingTtlMs` is refreshed in the background while the earlier one is
+     * returned. A server that cannot be listed is left out with a warning and is not tried again until
+     * `listingFailureBackoffMs` has passed; then it is listed in the background. One listing per server runs at a
+     * time, however many sessions call this. `refresh: true` lists every server again now and waits for it. When two
+     * tools map to the same agent tool name, the first in server order wins and the other is left out with a
+     * warning. Call it from `runModelStep` to offer the tools, or at Worker startup to warm the cache.
+     * @param options - `refresh: true` lists every server again now, ignoring the cache and the failure backoff.
+     * @returns Every offered tool, in server order and then in each server's order, then the resource and prompt
+     * tools when enabled.
+     * @throws {McpToolListingError} When servers are configured and none has a listing, because every one failed.
+     */
+    listTools(options?: {
+        readonly refresh?: boolean;
+    }): Promise<readonly McpTool[]>;
+    /**
+     * The name a Stepwise agent's `toolSources` routes stored calls by: `sourceName` as passed, or
+     * {@link defaultMcpSourceName}, `"mcp"`.
+     */
+    get sourceName(): string;
+    /**
+     * Shows the source in `console.log` and `util.inspect` output without secrets.
+     * @param depth - Remaining inspection depth.
+     * @param options - Node's inspection options.
+     * @param inspect - Node's `util.inspect`.
+     * @returns The source name and the server configurations, with environment and header values replaced by `***`.
+     */
+    [nodeInspectSymbol](depth: number, options: {
+        readonly depth?: number | null;
+    }, inspect: (value: unknown, options: object) => string): string;
+    /**
+     * Returns the tools of the last listings without listing, for estimates.
+     * @returns The cached tools, as {@link listTools} would return them, or none before any listing finished.
+     */
+    cachedTools(): readonly McpTool[];
+    /**
+     * Returns the tool names this source lists whatever its servers offer, so the Stepwise runner refuses a name
+     * collision when it is constructed instead of on every model call.
+     * @returns The resource and prompt tool names when they are enabled, else none.
+     */
+    declaredToolNames(): ReadonlySet<string>;
+    /**
+     * Returns one listed tool by its agent tool name.
+     * @param toolName - {@link McpTool.name}.
+     * @returns The cached definition.
+     * @throws {RangeError} When {@link listTools} has not run or no listed server offers the tool.
+     */
+    tool(toolName: string): McpTool;
+    /**
+     * Returns a {@link ToolPolicy} for every listed tool whose annotations declare an effect.
+     *
+     * Use it with a framework adapter that offers the MCP tools as its own tools: pass it in the
+     * adapter's `toolPolicies` and spread your own policies after it, so yours win.
+     * @example
+     * ```ts
+     * await tools.listTools();
+     * const toolPolicies = { ...tools.toolPolicies(), files__delete: { effect: "non_idempotent_write" } };
+     * ```
+     * @returns Policies by {@link McpTool.name}, with the effect's default approval.
+     * @throws {RangeError} When {@link listTools} has not run.
+     */
+    toolPolicies(): Record<string, ToolPolicy>;
+    /**
+     * Builds the {@link DeferredToolCall} for one model call of a listed MCP tool.
+     *
+     * The policy comes from `turn.resolveToolPolicy` with the tool's annotation effect, so an explicit
+     * {@link ToolPolicy} wins. The call's `toolSourceReference` names the server, the tool's MCP name, and
+     * its task support.
+     * @param turn - The `RunModel` context.
+     * @param call - Framework tool call ID, the {@link McpTool.name} the model called, the arguments as JSON
+     * text, and optionally `listedTool`, the {@link McpTool} the listing offered for this model call, as the
+     * Stepwise runner passes it, so a refresh that finished meanwhile cannot change or remove it. Without it, the
+     * tool is looked up in the current listing.
+     * @returns The call to put in `ToolCallsRequested.toolCalls`.
+     * @throws {RangeError} When no `listedTool` is given and {@link listTools} has not run or the tool is unknown.
+     */
+    deferredToolCall(turn: AgentTurnContext, call: {
+        readonly toolCallId: string;
+        readonly toolName: string;
+        readonly arguments: string;
+        readonly listedTool?: SourceToolDefinition;
+    }): DeferredToolCall;
+    /**
+     * Returns one deferred-call handler per listed MCP tool, keyed by agent tool name.
+     *
+     * Merge them with a runner's own handlers and dispatch `executeDeferredToolCall` by
+     * `call.toolCall.toolName`. Build the map inside `executeDeferredToolCall`, not once at construction:
+     * a replacement Worker runs tool Steps before any `RunModel`.
+     * @example
+     * ```ts
+     * public async executeDeferredToolCall(call: DeferredToolExecution): Promise<ToolExecutionResult> {
+     *   const handlers = { ...this.localHandlers, ...(await tools.deferredToolHandlers()) };
+     *   return handlers[call.toolCall.toolName]!(call);
+     * }
+     * ```
+     * @returns Handlers that each call {@link executeDeferredToolCall}.
+     * @throws {McpToolListingError} When no server could be listed.
+     */
+    deferredToolHandlers(): Promise<Record<string, DeferredToolHandler>>;
+    /**
+     * Runs one deferred MCP tool call in its tool Step.
+     *
+     * Call it from `AgentFrameworkRunner.executeDeferredToolCall`, and implement
+     * `AgentFrameworkRunner.pollToolTask` with {@link pollToolTask}. A call built by {@link deferredToolCall}
+     * goes straight to the server named on its record, without a listing. It passes the call's idempotency
+     * key, events, heartbeat, heartbeat checkpoint, and cancellation signal on.
+     *
+     * A Streamable HTTP server without protocol sessions that answers with a task gets {@link ToolTaskStarted}.
+     * The source saves the task ID as the heartbeat checkpoint first; a retried attempt that reads it returns
+     * the same task without calling the tool again.
+     * @param call - The approved call from the tool Step.
+     * @returns The tool output the model sees, or {@link ToolTaskStarted} for a task that `PollToolTask` polls.
+     * @throws {ToolExecutionError} When the arguments are not a JSON object, the tool failed, the server
+     * answered with an error or asked for input, or the call was never sent.
+     * @throws {McpToolCallInterruptedError} When the call was sent and no result came back.
+     */
+    executeDeferredToolCall(call: DeferredToolExecution): Promise<ToolExecutionResult | ToolTaskStarted>;
+    /**
+     * Polls one MCP task that {@link executeDeferredToolCall} started, once.
+     *
+     * Call it from `AgentFrameworkRunner.pollToolTask`. It reads the task with `tasks/get` and writes an
+     * `mcp.task_status` event when the status changed. A completed task's result comes from `tasks/result`. A task in
+     * `input_required` is cancelled and fails, because its input requests need a live connection.
+     * @param poll - The call's record from `PollToolTask`.
+     * @returns The tool output, or `tool_task_pending` with the next poll interval, which backs off from the
+     * server's `pollInterval` to at most a minute.
+     * @throws {ToolExecutionError} When the task failed, was cancelled, returned an `isError` result, or asked
+     * for input.
+     * @throws {McpToolCallInterruptedError} When the server could not be reached, no longer knows the task, or
+     * answered a poll with an error. The task may still run, so `PollToolTask` retries and then records the
+     * call by its effect.
+     */
+    pollToolTask(poll: ToolTaskPoll): Promise<ToolTaskPollOutcome>;
+    /**
+     * Sends `tasks/cancel` for one MCP task that `cancel_turn` abandoned.
+     *
+     * Call it from `AgentFrameworkRunner.cancelToolTask`. Cancellation is best-effort: the server may finish the
+     * task anyway, and the session drops a result that arrives later. Any answer from the server ends the
+     * cancellation, including an error for a task that already finished or that the server no longer knows, so a
+     * repeated call is harmless.
+     * @param cancellation - The abandoned call's record from `CancelToolTask`.
+     * @returns A Promise that resolves once the server answered.
+     * @throws {McpToolCallInterruptedError} When the server could not be reached or did not answer;
+     * `CancelToolTask` retries, then records the call `outcome_unknown` anyway.
+     */
+    cancelToolTask(cancellation: ToolTaskCancellation): Promise<void>;
+    /**
+     * Calls one listed MCP tool once, as a tool Step does.
+     *
+     * Use it from a framework tool that wraps an MCP tool, when the adapter gives the tool only the
+     * idempotency key. It finds the tool's server through the per-server listing. Call it only inside a
+     * tool Step: the session's retry rules for the effect assume it.
+     * @param toolName - {@link McpTool.name}.
+     * @param toolArguments - Tool arguments.
+     * @param options - Idempotency key, events, heartbeat, checkpoints, and abort signal.
+     * @returns The tool output the model sees. A task is polled inside the call, for at most
+     * `taskWaitTimeoutMs`.
+     * @throws {ToolExecutionError} When the tool failed, the server answered with an error or asked for
+     * input, or the call was never sent.
+     * @throws {McpToolCallInterruptedError} When the call was sent and no result came back.
+     */
+    callTool(toolName: string, toolArguments: Readonly<Record<string, unknown>>, options?: McpToolCallOptions): Promise<ToolExecutionResult>;
+    private isResourceAndPromptTool;
+    private runResourceAndPromptTool;
+    private callLimits;
+    private resolveTarget;
+    private callTarget;
+    private targetFromReference;
+    private targetFromListing;
+    private refreshListing;
+    private combineServerTools;
+    private listServerTools;
+}
+/** Joins text blocks; other content blocks and structured content render as `serializeToolOutputJson` text. */
+export declare function renderToolResultText(result: CallToolResult): string;
+export {};