@superdurable/dex-agents 0.4.0 → 0.6.0

package/dist/src/mcp/mcp-tool-source.js

@@ -10,12 +10,20 @@ import { createRequire } from "node:module";
 import { setTimeout as delay } from "node:timers/promises";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { CallToolResultSchema, CreateTaskResultSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
-import { ToolExecutionError, toolEffectFromMcpToolAnnotations, } from "../agent-framework-runner.js";
+import { ToolExecutionError, ToolOutcomeUnknownError, toolEffectFromMcpToolAnnotations, } from "../agent-framework-runner.js";
 import { buildResourceAndPromptToolDefinitions, readServerName, resourceAndPromptToolNames, runResourceAndPromptTool, serializeToolOutputJson, } from "./mcp-resource-and-prompt-tools.js";
+import { readDexErrorOutcome, readDexToolDeclaration, readDexToolOutcome, rejectedOutcomeFallbackMessage, unknownOutcomeFallbackMessage, } from "./mcp-dex-conventions.js";
+import { hasImageContent, renderToolFailureText, storeToolResultImages } from "./mcp-image-content.js";
 import { redactMcpServerConfigSecrets, validateMcpServerConfig } 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 const mcpIdempotencyKeyMetaKey = "io.superdurable.dex/idempotencyKey";
 /** `AgentEvents` type for an MCP `notifications/progress` of a running tool call. */
 export const mcpToolProgressEventType = "mcp.tool_progress";
@@ -31,7 +39,7 @@ export const defaultMcpTaskTtlMs = 86_400_000;
 export const defaultMcpConnectionTimeoutMs = 30_000;
 /** Default number of connection attempts before a request reports the server unreachable. */
 export 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 const defaultMcpSourceName = "mcp";
 /** Default age in milliseconds after which `listTools` lists a server again, in the background: 5 minutes. */
 export const defaultMcpListingTtlMs = 300_000;
@@ -50,6 +58,13 @@ const taskTtlWaitMultiple = 4;
 // A durable poll is a Step: backing off to a minute bounds a long task's history.
 const durableTaskPollBackoffCapSeconds = 60;
 const maximumDurableTaskPollIntervalSeconds = 3_600;
+// unclassified ranks highest: nothing is known, and it runs like a non-idempotent write.
+const effectConservatism = {
+    read: 0,
+    idempotent_write: 1,
+    non_idempotent_write: 2,
+    unclassified: 3,
+};
 // The server or a gateway may report InternalError after the call ran, so it leaves the outcome unknown.
 const noResultErrorCodes = new Set([
     ErrorCode.ConnectionClosed,
@@ -94,16 +109,26 @@ export class McpToolCallInterruptedError extends Error {
 export class McpToolListingError extends Error {
     serverName;
     detail;
+    /**
+     * 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
+     */
+    httpStatus;
     /**
      * 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, detail) {
+    constructor(serverName, detail, httpStatus) {
         super(`could not list the tools of MCP server ${serverName}: ${detail}`);
         this.serverName = serverName;
         this.detail = detail;
         this.name = "McpToolListingError";
+        this.httpStatus = httpStatus;
     }
 }
 const nodeInspectSymbol = Symbol.for("nodejs.util.inspect.custom");
@@ -123,6 +148,14 @@ const nodeInspectSymbol = Symbol.for("nodejs.util.inspect.custom");
  * 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
@@ -131,11 +164,19 @@ const nodeInspectSymbol = Symbol.for("nodejs.util.inspect.custom");
  * 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
@@ -213,6 +254,7 @@ export class McpToolSource {
     listingTtlMs;
     listingFailureBackoffMs;
     configuredSourceName;
+    mediaStore;
     tools;
     resourceAndPromptTools;
     /**
@@ -252,10 +294,11 @@ export class McpToolSource {
             throw new TypeError("listingTtlMs and listingFailureBackoffMs must be positive");
         }
         this.configuredSourceName = options.sourceName ?? defaultMcpSourceName;
+        this.mediaStore = options.mediaStore;
         for (const name of serversByName.keys()) {
             this.listings.set(name, { tools: undefined, listedAtMs: 0, failure: undefined, failedUntilMs: 0, pending: undefined });
         }
-        this.connector = new McpConnector({ name: options.clientName ?? "dex-agents", version: dexAgentsVersion() }, this.connectionTimeoutMs);
+        this.connector = new McpConnector({ name: options.clientName ?? "dex-agents", version: dexAgentsVersion() }, this.connectionTimeoutMs, warningLoggerFallingBackToConsole(options.logWarning));
         this.resourceAndPromptTools =
             options.resourceAndPromptToolsEnabled === true && serversByName.size > 0
                 ? buildResourceAndPromptToolDefinitions([...serversByName.keys()]).map((definition) => ({
@@ -315,7 +358,7 @@ export class McpToolSource {
         return [...this.tools.values()];
     }
     /**
-     * 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() {
@@ -341,7 +384,7 @@ export class McpToolSource {
         return this.tools === undefined ? [] : [...this.tools.values()];
     }
     /**
-     * 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.
      */
@@ -365,16 +408,19 @@ export class McpToolSource {
         return tool;
     }
     /**
-     * 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() {
@@ -383,22 +429,78 @@ export class McpToolSource {
         }
         const policies = {};
         for (const tool of this.tools.values()) {
-            if (tool.frameworkEffect !== undefined) {
+            if (tool.dexEffect !== undefined) {
+                policies[tool.name] = { effect: tool.dexEffect, requiresApproval: tool.isApprovalRecommended === true };
+            }
+            else if (tool.frameworkEffect !== undefined) {
                 policies[tool.name] = { effect: tool.frameworkEffect };
             }
         }
         return policies;
     }
+    /**
+     * 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) {
+        if (this.tools === undefined) {
+            throw new RangeError("call listTools before merging MCP tool policies");
+        }
+        const policies = { ...this.toolPolicies(), ...applicationPolicies };
+        for (const tool of this.tools.values()) {
+            if (tool.dexEffect !== undefined) {
+                const applicationPolicy = Object.hasOwn(applicationPolicies, tool.name)
+                    ? applicationPolicies[tool.name]
+                    : undefined;
+                policies[tool.name] = combineDeclaredToolPolicy(tool.dexEffect, tool.isApprovalRecommended === true, applicationPolicy);
+            }
+        }
+        return policies;
+    }
     /**
      * 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.
@@ -406,20 +508,35 @@ export class McpToolSource {
     deferredToolCall(turn, call) {
         const listedTool = call.listedTool;
         const tool = isMcpTool(listedTool) && listedTool.name === call.toolName ? listedTool : this.tool(call.toolName);
+        const reference = this.isResourceAndPromptTool(call.toolName)
+            ? {}
+            : {
+                toolSourceReference: JSON.stringify({
+                    mcp_server: tool.serverName,
+                    mcp_tool: tool.mcpToolName,
+                    ...(tool.taskSupport === undefined ? {} : { task_support: tool.taskSupport }),
+                }),
+            };
+        if (tool.dexEffect === undefined) {
+            return {
+                toolCallId: call.toolCallId,
+                toolName: call.toolName,
+                arguments: call.arguments,
+                policy: turn.resolveToolPolicy(call.toolName, tool.frameworkEffect),
+                ...reference,
+            };
+        }
+        const sessionPolicy = turn.toolPolicies !== undefined && Object.hasOwn(turn.toolPolicies, call.toolName)
+            ? turn.toolPolicies[call.toolName]
+            : undefined;
+        const policy = combineDeclaredToolPolicy(tool.dexEffect, tool.isApprovalRecommended === true, sessionPolicy);
         return {
             toolCallId: call.toolCallId,
             toolName: call.toolName,
             arguments: call.arguments,
-            policy: turn.resolveToolPolicy(call.toolName, tool.frameworkEffect),
-            ...(this.isResourceAndPromptTool(call.toolName)
-                ? {}
-                : {
-                    toolSourceReference: JSON.stringify({
-                        mcp_server: tool.serverName,
-                        mcp_tool: tool.mcpToolName,
-                        ...(tool.taskSupport === undefined ? {} : { task_support: tool.taskSupport }),
-                    }),
-                }),
+            policy,
+            ...reference,
+            ordered: policy.effect !== "read",
         };
     }
     /**
@@ -456,13 +573,17 @@ export 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.
      */
-    async executeDeferredToolCall(call) {
+    async executeDeferredToolCall(call, options = {}) {
         const toolArguments = parseToolArguments(call.toolCall.arguments);
         if (this.isResourceAndPromptTool(call.toolCall.toolName)) {
             return this.runResourceAndPromptTool(call.toolCall.toolName, toolArguments, call.cancellationSignal);
@@ -485,8 +606,41 @@ export class McpToolSource {
                 ? {}
                 : { saveHeartbeatCheckpoint: (checkpoint) => call.saveHeartbeatCheckpoint(checkpoint) }),
             signal: call.cancellationSignal,
+            ...(options.requestMeta === undefined ? {} : { requestMeta: options.requestMeta }),
         }, isTaskPolledBySession);
     }
+    /**
+     * 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) {
+        const reference = parseToolSourceReference(call.toolCall.toolSourceReference);
+        const saved = parseJsonObject(call.heartbeatCheckpoint);
+        return (call.supportsToolTasks === true &&
+            reference !== undefined &&
+            saved?.["mcp_server"] === reference.serverName &&
+            saved["mcp_tool"] === reference.mcpToolName &&
+            typeof saved["mcp_task_id"] === "string" &&
+            saved["mcp_task_polled_by_session"] === true);
+    }
     /**
      * Polls one MCP task that {@link executeDeferredToolCall} started, once.
      *
@@ -498,6 +652,8 @@ export 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.
@@ -518,9 +674,11 @@ export class McpToolSource {
         const outcome = await call.pollTaskOnce(taskId, record.taskPollIntervalSeconds ?? null);
         switch (outcome.kind) {
             case "succeeded":
-                return { output: outcome.output };
+                return await this.toolExecutionResult(outcome, target);
             case "failed":
                 throw new ToolExecutionError(outcome.message);
+            case "outcome_unknown":
+                throw new ToolOutcomeUnknownError(outcome.message);
             case "task_pending":
                 return { kind: "tool_task_pending", pollIntervalSeconds: outcome.pollIntervalSeconds };
             case "interrupted":
@@ -633,16 +791,24 @@ export class McpToolSource {
     async resolveTarget(toolName, toolSourceReference) {
         return this.targetFromReference(toolName, toolSourceReference) ?? (await this.targetFromListing(toolName));
     }
+    async toolExecutionResult(outcome, target) {
+        if (this.mediaStore === undefined || outcome.result === undefined || !hasImageContent(outcome.result)) {
+            return { output: outcome.output };
+        }
+        return await storeToolResultImages(outcome.result, this.mediaStore, target.toolName);
+    }
     async callTarget(target, toolArguments, options, isTaskPolledBySession) {
         const call = new McpToolCall(this.connector, this.callLimits(isTaskPolledBySession), target, toolArguments, options);
         const outcome = await call.run(savedTaskFromCheckpoint(options.heartbeatCheckpoint, target)?.taskId);
         switch (outcome.kind) {
             case "succeeded":
-                return { output: outcome.output };
+                return await this.toolExecutionResult(outcome, target);
             case "task_started":
                 return { kind: "tool_task_started", taskId: outcome.taskId, pollIntervalSeconds: outcome.pollIntervalSeconds };
             case "failed":
                 throw new ToolExecutionError(outcome.message);
+            case "outcome_unknown":
+                throw new ToolOutcomeUnknownError(outcome.message);
             case "interrupted":
             case "task_lost":
             case "task_pending":
@@ -695,7 +861,7 @@ export class McpToolSource {
             const failure = error instanceof McpToolListingError ? error : new McpToolListingError(server.name, describeError(error));
             listing.failure = failure;
             listing.failedUntilMs = Date.now() + this.listingFailureBackoffMs;
-            console.warn(`left MCP server ${server.name} out of the tool listing: ${failure.message}`);
+            this.connector.logWarning(`left MCP server ${server.name} out of the tool listing: ${failure.message}`);
         }
     }
     combineServerTools() {
@@ -704,7 +870,7 @@ export class McpToolSource {
             for (const tool of this.listings.get(serverName)?.tools ?? []) {
                 const existing = tools.get(tool.name);
                 if (existing !== undefined) {
-                    console.warn(`left MCP tool ${tool.serverName}/${tool.mcpToolName} out: ${existing.serverName}/${existing.mcpToolName} already has the agent tool name ${tool.name}`);
+                    this.connector.logWarning(`left MCP tool ${tool.serverName}/${tool.mcpToolName} out: ${existing.serverName}/${existing.mcpToolName} already has the agent tool name ${tool.name}`);
                     continue;
                 }
                 tools.set(tool.name, tool);
@@ -717,6 +883,7 @@ export class McpToolSource {
     }
     async listServerTools(server) {
         let detail = "no listing attempt";
+        let httpStatus;
         for (let listingAttempt = 1; listingAttempt <= this.connectionAttempts; listingAttempt += 1) {
             let connection;
             try {
@@ -737,6 +904,7 @@ export class McpToolSource {
             }
             catch (error) {
                 detail = describeError(error);
+                httpStatus = streamableHttpStatusOf(error);
             }
             finally {
                 await this.connector.disconnectQuietly(connection);
@@ -745,16 +913,18 @@ export class McpToolSource {
                 await delay(connectionRetryDelayMs * listingAttempt);
             }
         }
-        throw new McpToolListingError(server.name, detail);
+        throw new McpToolListingError(server.name, detail, httpStatus);
     }
 }
 /** Opens one connection per request with a bounded handshake, and ends it. */
 class McpConnector {
     clientInfo;
     connectionTimeoutMs;
-    constructor(clientInfo, connectionTimeoutMs) {
+    logWarning;
+    constructor(clientInfo, connectionTimeoutMs, logWarning) {
         this.clientInfo = clientInfo;
         this.connectionTimeoutMs = connectionTimeoutMs;
+        this.logWarning = logWarning;
     }
     async connect(server) {
         const client = new Client(this.clientInfo, { capabilities: {} });
@@ -801,14 +971,14 @@ class McpConnector {
         }
         catch (error) {
             // The server times idle sessions out; the outcome is already known.
-            console.warn(`ending an MCP session failed: ${describeError(error)}`);
+            this.logWarning(`ending an MCP session failed: ${describeError(error)}`);
         }
         try {
             await client.close();
         }
         catch (error) {
             // The outcome is already known; a failed close only leaks this one connection.
-            console.warn(`closing an MCP connection failed: ${describeError(error)}`);
+            this.logWarning(`closing an MCP connection failed: ${describeError(error)}`);
         }
     }
 }
@@ -842,7 +1012,7 @@ class McpToolCall {
                 return outcome;
             }
             // Only CallTool retries an attempt, and it may send the call again.
-            console.warn(`calling MCP tool ${this.target.mcpToolName} again: ${outcome.detail}`);
+            this.connector.logWarning(`calling MCP tool ${this.target.mcpToolName} again: ${outcome.detail}`);
         }
         return this.withConnection((connection) => this.sendToolCall(connection));
     }
@@ -915,7 +1085,12 @@ class McpToolCall {
         }
     }
     async sendToolCall({ client, transport }) {
-        const meta = this.options.idempotencyKey === undefined ? undefined : { [mcpIdempotencyKeyMetaKey]: this.options.idempotencyKey };
+        const meta = this.options.idempotencyKey === undefined && this.options.requestMeta === undefined
+            ? undefined
+            : {
+                ...this.options.requestMeta,
+                ...(this.options.idempotencyKey === undefined ? {} : { [mcpIdempotencyKeyMetaKey]: this.options.idempotencyKey }),
+            };
         const params = { name: this.target.mcpToolName, arguments: this.toolArguments, ...(meta === undefined ? {} : { _meta: meta }) };
         const requestOptions = {
             timeout: this.limits.requestTimeoutMs,
@@ -945,8 +1120,9 @@ class McpToolCall {
             })).task;
         }
         catch (error) {
-            if (error instanceof McpError && !noResultErrorCodes.has(error.code)) {
-                return { kind: "failed", message: error.message };
+            const outcome = error instanceof McpError ? outcomeFromMcpError(error) : undefined;
+            if (outcome !== undefined) {
+                return outcome;
             }
             throw error;
         }
@@ -1017,7 +1193,7 @@ class McpToolCall {
             return { kind: "failed", message: `MCP task ${taskId} was cancelled${reason}` };
         }
         if (task.status === "input_required") {
-            await cancelTaskQuietly(client, taskId);
+            await cancelTaskQuietly(client, taskId, this.connector.logWarning);
             const detail = task.statusMessage === undefined ? "" : ` (${task.statusMessage})`;
             return {
                 kind: "failed",
@@ -1055,7 +1231,7 @@ class McpToolCallReporter {
         });
     }
 }
-function mcpToolFromListing(server, tool) {
+export function mcpToolFromListing(server, tool) {
     const annotations = tool.annotations === undefined
         ? undefined
         : {
@@ -1064,6 +1240,13 @@ function mcpToolFromListing(server, tool) {
             ...(tool.annotations.destructiveHint === undefined ? {} : { destructiveHint: tool.annotations.destructiveHint }),
         };
     const trustsAnnotations = server.trustsToolAnnotations ?? true;
+    const declaration = trustsAnnotations ? readDexToolDeclaration(tool._meta, server.name, tool.name) : undefined;
+    // A Dex declaration replaces the annotations, even when its effect is invalid.
+    const frameworkEffect = declaration !== undefined
+        ? declaration.effect
+        : trustsAnnotations && annotations !== undefined
+            ? toolEffectFromMcpToolAnnotations(annotations)
+            : undefined;
     return {
         name: buildAgentToolName(server.name, tool.name),
         serverName: server.name,
@@ -1071,10 +1254,24 @@ function mcpToolFromListing(server, tool) {
         description: tool.description ?? tool.title ?? `MCP tool ${tool.name} of ${server.name}`,
         inputSchema: tool.inputSchema,
         annotations,
-        frameworkEffect: trustsAnnotations && annotations !== undefined ? toolEffectFromMcpToolAnnotations(annotations) : undefined,
+        frameworkEffect,
+        dexEffect: declaration?.effect,
+        isApprovalRecommended: declaration?.effect !== undefined && declaration.isApprovalRecommended,
         taskSupport: tool.execution?.taskSupport,
     };
 }
+/** Returns a declared tool's policy; a session policy may raise its safety, never lower it. */
+function combineDeclaredToolPolicy(declaredEffect, isApprovalRecommended, sessionPolicy) {
+    if (sessionPolicy === undefined) {
+        return { effect: declaredEffect, requiresApproval: isApprovalRecommended };
+    }
+    const effect = effectConservatism[sessionPolicy.effect] > effectConservatism[declaredEffect] ? sessionPolicy.effect : declaredEffect;
+    const isApprovalRequiredBySessionEffect = sessionPolicy.effect === "non_idempotent_write" || sessionPolicy.effect === "unclassified";
+    return {
+        effect,
+        requiresApproval: sessionPolicy.requiresApproval ?? (isApprovalRecommended || isApprovalRequiredBySessionEffect),
+    };
+}
 function buildAgentToolName(serverName, mcpToolName) {
     const candidate = `${serverName}__${mcpToolName}`.replace(/[^A-Za-z0-9_-]/g, "_");
     if (candidate.length <= toolNameLengthLimit) {
@@ -1142,12 +1339,32 @@ function savedTaskFromCheckpoint(checkpoint, target) {
         ? { taskId, isPolledBySession: saved["mcp_task_polled_by_session"] === true }
         : undefined;
 }
-function outcomeFromToolResult(result) {
-    const text = renderToolResultText(result);
+export function outcomeFromToolResult(result) {
+    const failureText = hasImageContent(result) ? renderToolFailureText(result) : renderToolResultText(result);
+    // The Dex outcome wins over isError in both directions.
+    const dexOutcome = readDexToolOutcome(result._meta);
+    if (dexOutcome === "unknown") {
+        return { kind: "outcome_unknown", message: failureText === "" ? unknownOutcomeFallbackMessage : failureText };
+    }
+    if (dexOutcome === "rejected") {
+        return { kind: "failed", message: failureText === "" ? rejectedOutcomeFallbackMessage : failureText };
+    }
     if (result.isError === true) {
-        return { kind: "failed", message: text === "" ? "the MCP tool reported an error" : text };
+        return { kind: "failed", message: failureText === "" ? "the MCP tool reported an error" : failureText };
+    }
+    return { kind: "succeeded", output: renderToolResultText(result), result };
+}
+/** Maps a JSON-RPC error answer; `undefined` leaves the outcome open, so the effect class decides. */
+export function outcomeFromMcpError(error) {
+    // A Dex-aware server's outcome is known, even for an error code that usually leaves it open.
+    const dexOutcome = readDexErrorOutcome(error.data);
+    if (dexOutcome === "unknown") {
+        return { kind: "outcome_unknown", message: error.message };
+    }
+    if (dexOutcome === "rejected" || !noResultErrorCodes.has(error.code)) {
+        return { kind: "failed", message: error.message };
     }
-    return { kind: "succeeded", output: text };
+    return undefined;
 }
 /** Seconds until the next durable poll: the server's hint, backed off from the last interval to a minute. */
 function durableTaskPollIntervalSeconds(task, previousSeconds) {
@@ -1161,13 +1378,38 @@ function taskPollIntervalMs(task) {
     }
     return Math.min(Math.max(task.pollInterval, minimumTaskPollIntervalMs), maximumTaskPollIntervalMs);
 }
-async function cancelTaskQuietly(client, taskId) {
+/** Returns the HTTP status of a Streamable HTTP failure in the error or its causes, if any. */
+function streamableHttpStatusOf(error) {
+    let current = error;
+    for (let depth = 0; depth < 5 && current instanceof Error; depth += 1) {
+        if (current instanceof StreamableHTTPError && current.code !== undefined && current.code > 0) {
+            return current.code;
+        }
+        current = current.cause;
+    }
+    return undefined;
+}
+/** Wraps an application's warning callback so that a throwing callback falls back to `console.warn`. */
+function warningLoggerFallingBackToConsole(logWarning) {
+    if (logWarning === undefined) {
+        return (message) => console.warn(message);
+    }
+    return (message) => {
+        try {
+            logWarning(message);
+        }
+        catch (error) {
+            console.warn(`${message} (logWarning failed: ${describeError(error)})`);
+        }
+    };
+}
+async function cancelTaskQuietly(client, taskId, logWarning) {
     try {
         await client.experimental.tasks.cancelTask(taskId, { timeout: taskCancelTimeoutMs });
     }
     catch (error) {
         // Cancellation is cooperative; the tool's outcome is already reported either way.
-        console.warn(`tasks/cancel for MCP task ${taskId} failed: ${describeError(error)}`);
+        logWarning(`tasks/cancel for MCP task ${taskId} failed: ${describeError(error)}`);
     }
 }
 function describeError(error) {