@superdurable/dex-agents 0.4.0 → 0.6.0

package/dist/src/mcp/mcp-image-content.js

@@ -0,0 +1,82 @@
+// Copyright (c) 2026 Super Durable, Inc.
+//
+// Licensed under the Sustainable Use License 1.0.
+// You may not use this file except in compliance with the License.
+// See the LICENSE file in the repository root.
+//
+// SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+import { ToolExecutionError } from "../agent-framework-runner.js";
+import { ImageValidationError, maxImagesPerMessage } from "../agent-media.js";
+import { serializeToolOutputJson } from "./mcp-resource-and-prompt-tools.js";
+// Canonical padded base64, the same check as the Python core's.
+const base64Pattern = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+/** Reports whether a result carries at least one `image` content block. */
+export function hasImageContent(result) {
+    return result.content.some((block) => block.type === "image");
+}
+/**
+ * Renders a failed result's text with `[image <n> omitted]` for each image block.
+ *
+ * The text becomes the record's `error`, so image bytes never reach session state.
+ */
+export function renderToolFailureText(result) {
+    let imageCount = 0;
+    return result.content
+        .map((block) => {
+        if (block.type === "text") {
+            return block.text;
+        }
+        if (block.type === "image") {
+            imageCount += 1;
+            return `[image ${imageCount} omitted]`;
+        }
+        return serializeToolOutputJson(block);
+    })
+        .join("\n");
+}
+/**
+ * Uploads a successful result's image blocks and returns the tool output with their references.
+ *
+ * Each image block becomes `[image <n>]` in the output text, `n` counting from 1 in `images` order. The caller
+ * passes only a result with image blocks.
+ * @throws {ToolExecutionError} When the result has more than {@link maxImagesPerMessage} images, or an image is not
+ * valid base64 or not an image the store accepts.
+ */
+export async function storeToolResultImages(result, store, toolName) {
+    const imageCount = result.content.filter((block) => block.type === "image").length;
+    if (imageCount > maxImagesPerMessage) {
+        throw new ToolExecutionError(`MCP tool ${toolName} returned ${imageCount} images; a tool result carries at most ${maxImagesPerMessage}`);
+    }
+    const references = [];
+    const parts = [];
+    for (const block of result.content) {
+        if (block.type === "text") {
+            parts.push(block.text);
+        }
+        else if (block.type === "image") {
+            references.push(await storeImage(block, store, toolName, references.length + 1));
+            parts.push(`[image ${references.length}]`);
+        }
+        else {
+            parts.push(serializeToolOutputJson(block));
+        }
+    }
+    return { output: parts.join("\n"), images: references };
+}
+async function storeImage(block, store, toolName, imageNumber) {
+    const data = typeof block.data === "string" && base64Pattern.test(block.data) ? Buffer.from(block.data, "base64") : undefined;
+    // Re-encoding refuses unused trailing bits, so one image has one accepted text.
+    if (data === undefined || data.toString("base64") !== block.data) {
+        throw new ToolExecutionError(`MCP tool ${toolName} returned image ${imageNumber}, which is not valid base64`);
+    }
+    try {
+        return await store.putImage(new Uint8Array(data));
+    }
+    catch (error) {
+        if (error instanceof ImageValidationError) {
+            throw new ToolExecutionError(`MCP tool ${toolName} returned image ${imageNumber}, which is not a supported image: ${error.message}`);
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=mcp-image-content.js.map

package/dist/src/mcp/mcp-image-content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-image-content.js","sourceRoot":"","sources":["../../../src/mcp/mcp-image-content.ts"],"names":[],"mappings":"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"}

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

@@ -1,9 +1,16 @@
-import { type CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { McpError, type CallToolResult, type Tool } 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 { SourceToolDefinition } from "../builtin-loop/tool-source.js";
+import type { MediaStore } from "../agent-media.js";
 import { type McpServerConfig } from "./mcp-server-config.js";
-/** `_meta` key that carries the session's idempotency key on every `tools/call`. */
+/**
+ * `_meta` key that carries the session's idempotency key on every `tools/call`.
+ *
+ * The key is `<flowId>/<turnId>/<toolCallId>`: the same on every attempt of one tool call, and unique per
+ * call. A server that follows the Dex MCP conventions derives its own call ID from it, so a retried attempt
+ * is recognized as the same 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";
@@ -19,7 +26,7 @@ export declare const defaultMcpTaskTtlMs = 86400000;
 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. */
+/** Default {@link McpToolSourceOptions.sourceName}, which stored built-in loop 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;
@@ -50,10 +57,26 @@ export interface McpTool {
     /** 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.
+     * The effect the server declares when its configuration trusts it, else `undefined`: {@link dexEffect}
+     * when the tool declares one, otherwise the effect from {@link toolEffectFromMcpToolAnnotations}. An
+     * explicit {@link ToolPolicy} overrides it, except for a tool with a {@link dexEffect}, where
+     * {@link McpToolSource.deferredToolCall} lets the policy raise the effect but never lower it.
      */
     readonly frameworkEffect: ToolEffect | undefined;
+    /**
+     * The effect the tool declares under `mcpToolEffectMetaKey` in its definition's `_meta`, when the server
+     * configuration trusts the server, else `undefined`. A tool with a `dexEffect` follows the Dex MCP
+     * conventions in the package README: a session {@link ToolPolicy} may raise its effect or its approval but
+     * never lowers its effect.
+     * @since 0.5.0
+     */
+    readonly dexEffect?: ToolEffect | undefined;
+    /**
+     * Whether the tool declares `mcpToolApprovalMetaKey` together with a {@link dexEffect}. Always `false` or
+     * absent without a {@link dexEffect}.
+     * @since 0.5.0
+     */
+    readonly isApprovalRecommended?: boolean;
     /**
      * The tool's MCP `execution.taskSupport`. A `required` tool is called as a task; see
      * {@link McpToolSource} for who polls it.
@@ -96,7 +119,7 @@ export interface McpToolSourceOptions {
      * 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}.
+     * with it list the same names, which the built-in loop runner refuses. See {@link McpToolSource}.
      */
     readonly resourceAndPromptToolsEnabled?: boolean;
     /**
@@ -110,11 +133,37 @@ export interface McpToolSourceOptions {
      */
     readonly listingFailureBackoffMs?: number;
     /**
-     * The source's stable name in a Stepwise agent's `toolSources`, which stored calls are routed by. Defaults to
+     * The source's stable name in a built-in loop 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;
+    /**
+     * The store for the images of tool results. With a store, each `image` content block of a successful result is
+     * uploaded inside the tool Step and returned in {@link ToolExecutionResult.images}; the output text shows it as
+     * `[image <n>]`, counting from 1. More than `maxImagesPerMessage` images, invalid base64, or bytes the store
+     * refuses throw {@link ToolExecutionError}. Omitted, image blocks stay JSON in the output text. Pass the store the
+     * session's runner reads images from.
+     * @since 0.5.0
+     */
+    readonly mediaStore?: MediaStore;
+    /**
+     * Writes one warning of the source, such as a server left out of the listing, a tool left out for a duplicate
+     * name, a retried call, or a failed `tasks/cancel`. The source keeps working after each warning. A listing that
+     * keeps failing warns again on each retry, so an application with a terminal can send the warnings to a log file
+     * instead. Defaults to `console.warn`.
+     *
+     * The callback must not throw. If it does, the source catches the error, writes the warning and the error to
+     * `console.warn`, and keeps working, so a full disk does not fail `listTools()` or a tool call.
+     *
+     * ```ts
+     * const source = new McpToolSource(servers, {
+     *   logWarning: (message) => appendFileSync("agent.log", `${message}\n`),
+     * });
+     * ```
+     * @since 0.6.0
+     */
+    readonly logWarning?: (message: string) => void;
 }
 /** Per-call options of {@link McpToolSource.callTool}. */
 export interface McpToolCallOptions {
@@ -132,6 +181,13 @@ export interface McpToolCallOptions {
     readonly saveHeartbeatCheckpoint?: (checkpoint: string) => Promise<void>;
     /** Aborts the requests, for example the tool Step's cancellation signal. */
     readonly signal?: AbortSignal;
+    /**
+     * More `_meta` entries to send with the `tools/call` request, such as the identity the caller expects the tool
+     * to have. The {@link mcpIdempotencyKeyMetaKey} entry from {@link idempotencyKey} wins over an entry with the
+     * same key. Defaults to none.
+     * @since 0.5.0
+     */
+    readonly requestMeta?: Readonly<Record<string, unknown>>;
 }
 /**
  * A `tools/call` that reached an MCP server but returned no result.
@@ -165,13 +221,49 @@ export declare class McpToolCallInterruptedError extends Error {
 export declare class McpToolListingError extends Error {
     readonly serverName: string;
     readonly detail: string;
+    /**
+     * The HTTP status a Streamable HTTP server answered to the failed listing, such as 401 or 403 for denied access.
+     * It is `undefined` for a stdio server, or when no HTTP response came, such as for a refused connection or a
+     * timeout.
+     *
+     * @since 0.6.0
+     */
+    readonly httpStatus: number | undefined;
     /**
      * Creates the error.
      * @param serverName - Configured name of the last MCP server that failed.
      * @param detail - What went wrong with that server.
+     * @param httpStatus - The HTTP status the server answered, when it answered one. Since 0.6.0.
      */
-    constructor(serverName: string, detail: string);
+    constructor(serverName: string, detail: string, httpStatus?: number);
 }
+export type ToolCallOutcome = {
+    readonly kind: "succeeded";
+    readonly output: string;
+    readonly result?: CallToolResult;
+} | {
+    readonly kind: "failed";
+    readonly message: string;
+} | {
+    readonly kind: "outcome_unknown";
+    readonly message: string;
+} | {
+    readonly kind: "interrupted";
+    readonly detail: string;
+} | {
+    readonly kind: "server_unreachable";
+    readonly detail: string;
+} | {
+    readonly kind: "task_lost";
+    readonly detail: string;
+} | {
+    readonly kind: "task_started";
+    readonly taskId: string;
+    readonly pollIntervalSeconds: number;
+} | {
+    readonly kind: "task_pending";
+    readonly pollIntervalSeconds: number;
+};
 declare const nodeInspectSymbol: unique symbol;
 /**
  * Offers the tools of configured MCP servers to an agent, one Dex Step per call.
@@ -189,6 +281,14 @@ declare const nodeInspectSymbol: unique symbol;
  * the session's `defaultToolEffect`, `unclassified` by default. Annotations are trusted by default. A
  * {@link ToolPolicy} in `AgentSessionOptions.toolPolicies` keyed by {@link McpTool.name} wins.
  *
+ * A server that follows the Dex MCP conventions declares each tool's effect and approval in its definition's
+ * `_meta` instead, under `mcpToolEffectMetaKey` and `mcpToolApprovalMetaKey`, as a connector manifest does for
+ * `ConnectorToolSource`. A session {@link ToolPolicy} for such a tool may keep or raise its safety but never
+ * lowers it: the call gets the more conservative of the two effects, and its writes run in the model's order.
+ * A result or JSON-RPC error
+ * whose `_meta` reports `mcpToolOutcomeUnknown` records `outcome_unknown` without a retry, and
+ * `mcpToolOutcomeRejected` records `failed`. See the package README, "Dex MCP conventions".
+ *
  * 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
@@ -197,11 +297,19 @@ declare const nodeInspectSymbol: unique symbol;
  * Results map onto the session contract:
  * - A result becomes the tool output: text blocks joined with newlines, other blocks and structured
  *   content as JSON.
+ * - With {@link McpToolSourceOptions.mediaStore}, a successful result's `image` blocks are uploaded and returned
+ *   as {@link ToolExecutionResult.images}, and the text shows `[image <n>]` in their place. More than
+ *   `maxImagesPerMessage` images, invalid base64, or bytes the store refuses throw {@link ToolExecutionError}.
+ * - A failed result's text, with or without a media store, shows `[image <n> omitted]` for each `image` block, so
+ *   no image bytes reach the recorded error.
  * - 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.
+ * - A result or JSON-RPC error whose `_meta` reports the Dex outcome `unknown` throws
+ *   {@link ToolOutcomeUnknownError}, so the session records `outcome_unknown` and never sends the call again.
+ *   The outcome `rejected` throws {@link ToolExecutionError}. Either wins over `isError` and the error code.
  * - 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
@@ -279,6 +387,7 @@ export declare class McpToolSource {
     private readonly listingTtlMs;
     private readonly listingFailureBackoffMs;
     private readonly configuredSourceName;
+    private readonly mediaStore;
     private tools;
     private readonly resourceAndPromptTools;
     /**
@@ -308,7 +417,7 @@ export declare class McpToolSource {
         readonly refresh?: boolean;
     }): Promise<readonly McpTool[]>;
     /**
-     * The name a Stepwise agent's `toolSources` routes stored calls by: `sourceName` as passed, or
+     * The name a built-in loop agent's `toolSources` routes stored calls by: `sourceName` as passed, or
      * {@link defaultMcpSourceName}, `"mcp"`.
      */
     get sourceName(): string;
@@ -328,7 +437,7 @@ export declare class McpToolSource {
      */
     cachedTools(): readonly McpTool[];
     /**
-     * Returns the tool names this source lists whatever its servers offer, so the Stepwise runner refuses a name
+     * Returns the tool names this source lists whatever its servers offer, so the built-in loop 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.
      */
@@ -341,29 +450,71 @@ export declare class McpToolSource {
      */
     tool(toolName: string): McpTool;
     /**
-     * Returns a {@link ToolPolicy} for every listed tool whose annotations declare an effect.
+     * Returns a {@link ToolPolicy} for every listed tool whose server declares 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.
+     * A tool with a {@link McpTool.dexEffect} gets that effect and requires approval exactly when
+     * {@link McpTool.isApprovalRecommended}. To give a framework adapter these policies together with your own,
+     * use {@link mergeToolPolicies}. Do not spread your policies after these: yours would then replace a
+     * declaration and could lower its effect.
      * @example
      * ```ts
      * await tools.listTools();
-     * const toolPolicies = { ...tools.toolPolicies(), files__delete: { effect: "non_idempotent_write" } };
+     * const declaredPolicies = tools.toolPolicies();
      * ```
-     * @returns Policies by {@link McpTool.name}, with the effect's default approval.
+     * @returns Policies by {@link McpTool.name}: the declared approval for a tool with a
+     * {@link McpTool.dexEffect}, else the effect's default approval.
      * @throws {RangeError} When {@link listTools} has not run.
      */
     toolPolicies(): Record<string, ToolPolicy>;
+    /**
+     * Returns the application's tool policies merged with what the listed servers declare.
+     *
+     * Use it with a framework adapter that offers the MCP tools as its own tools: pass the result as the
+     * adapter's `toolPolicies`, so every call gets the policy {@link deferredToolCall} would give it.
+     *
+     * For a tool with a {@link McpTool.dexEffect}, your policy may keep or raise its safety but never lowers
+     * it. The tool gets the more conservative of `dexEffect` and your policy's effect, ranked `read`,
+     * `idempotent_write`, `non_idempotent_write`, then `unclassified`. Your `requiresApproval`, when set, wins,
+     * so `false` turns off a recommended approval. When you leave it out, the tool requires approval when
+     * {@link McpTool.isApprovalRecommended} is `true` or your policy's effect requires approval by default.
+     *
+     * For any other tool, your policy wins over its annotation effect, as before. Policies for tools that no
+     * listed server offers pass through unchanged.
+     * @example
+     * ```ts
+     * await tools.listTools();
+     * const toolPolicies = tools.mergeToolPolicies({
+     *   files__delete: { effect: "non_idempotent_write" },
+     *   lookup_order: { effect: "read" },
+     * });
+     * ```
+     * @param applicationPolicies - Your policies by tool name, keyed by {@link McpTool.name} for MCP tools.
+     * @returns A new record with every entry of `applicationPolicies` and of {@link toolPolicies}. A tool with
+     * a {@link McpTool.dexEffect} gets the combined policy, with `requiresApproval` set.
+     * @throws {RangeError} When {@link listTools} has not run.
+     * @since 0.5.0
+     */
+    mergeToolPolicies(applicationPolicies: Readonly<Record<string, ToolPolicy>>): 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.
+     *
+     * For a tool with a {@link McpTool.dexEffect}, the session's {@link ToolPolicy} for the tool may keep or
+     * raise its safety but never lowers it. The call gets the more conservative of `dexEffect` and the policy's
+     * effect, ranked `read`, `idempotent_write`, `non_idempotent_write`, then `unclassified`. It waits for
+     * approval when the policy sets `requiresApproval`. When the policy leaves `requiresApproval` out, the call
+     * waits when {@link McpTool.isApprovalRecommended} is `true` or the policy's effect requires approval by
+     * default. Without a policy, it waits exactly when {@link McpTool.isApprovalRecommended} is `true`. A write
+     * runs in the model's order after the turn's earlier writes (`DeferredToolCall.ordered`). Changed in
+     * 0.5.0: for a tool with a `dexEffect`, a {@link ToolPolicy} may raise the effect or the approval but never
+     * lowers the effect.
      * @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
+     * built-in loop 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.
@@ -402,13 +553,42 @@ export declare class McpToolSource {
      * 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.
+     *
+     * Changed in 0.5.0: takes `options`, whose `requestMeta` adds entries to the `tools/call` request's `_meta`.
      * @param call - The approved call from the tool Step.
+     * @param options - `requestMeta`: more `_meta` entries for the `tools/call` request, as in
+     * {@link McpToolCallOptions.requestMeta}. The idempotency key entry wins on a name clash. Defaults to none.
      * @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>;
+    executeDeferredToolCall(call: DeferredToolExecution, options?: {
+        readonly requestMeta?: Readonly<Record<string, unknown>>;
+    }): Promise<ToolExecutionResult | ToolTaskStarted>;
+    /**
+     * Returns whether {@link executeDeferredToolCall} will resume a task that an earlier attempt of the same call
+     * started and can never send a new `tools/call` for this call.
+     *
+     * It is `true` only when the call's heartbeat checkpoint names a task of the same server and tool that the
+     * session polls, and the session still polls tool tasks (`call.supportsToolTasks`). Then the call returns that
+     * task at once, without contacting the server. In every other case, including a task polled inside the tool
+     * Step, such as one bound to an MCP protocol session, the call may send `tools/call`: a task the server no longer
+     * knows is called again. Use it to skip a check that only guards a new send, such as checking a tool's current
+     * listing, so a catalog that is down or changed does not stop the recovery of a task already running.
+     *
+     * @example
+     * ```ts
+     * if (!tools.willResumeToolTaskWithoutSending(call)) {
+     *   await checkCurrentListing(call.toolCall.toolName);
+     * }
+     * return tools.executeDeferredToolCall(call);
+     * ```
+     * @param call - The tool Step's call, with this source's own `toolSourceReference`.
+     * @returns `true` when the call resumes a session-polled task and sends nothing; otherwise `false`.
+     * @since 0.5.0
+     */
+    willResumeToolTaskWithoutSending(call: DeferredToolExecution): boolean;
     /**
      * Polls one MCP task that {@link executeDeferredToolCall} started, once.
      *
@@ -420,6 +600,8 @@ export declare class McpToolSource {
      * 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 {ToolOutcomeUnknownError} When the task's result reported the Dex outcome `unknown`; the session
+     * records `outcome_unknown`.
      * @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.
@@ -458,6 +640,7 @@ export declare class McpToolSource {
     private runResourceAndPromptTool;
     private callLimits;
     private resolveTarget;
+    private toolExecutionResult;
     private callTarget;
     private targetFromReference;
     private targetFromListing;
@@ -465,6 +648,10 @@ export declare class McpToolSource {
     private combineServerTools;
     private listServerTools;
 }
+export declare function mcpToolFromListing(server: McpServerConfig, tool: Tool): McpTool;
+export declare function outcomeFromToolResult(result: CallToolResult): ToolCallOutcome;
+/** Maps a JSON-RPC error answer; `undefined` leaves the outcome open, so the effect class decides. */
+export declare function outcomeFromMcpError(error: McpError): ToolCallOutcome | undefined;
 /** Joins text blocks; other content blocks and structured content render as `serializeToolOutputJson` text. */
 export declare function renderToolResultText(result: CallToolResult): string;
 export {};