@wildo-ai/saas-backend-lib 1.1.3 → 1.1.4

package/dist/esm/flows-actors/services/agents.backend.service.d.ts

@@ -1,4 +1,7 @@
 import 'reflect-metadata';
+import type { AuditLogsBackendService } from '../../compliance/audit-trails/services/audit-logs.backend.service';
+import type { McpClientBackendService } from '../../flows-actors/services/mcp-client.backend.service';
+import type { McpCredentialResolverBackendService } from '../../flows-actors/services/mcp-credential-resolver.backend.service';
 import { LoggerService } from '../../monitoring/logger/services/logger.service';
 import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service';
 import { FlowsActorsRegistryService } from './flows-actors-registry.service';
@@ -161,9 +164,34 @@ export declare class AgentsBackendService {
     private readonly promptCompiler;
     private readonly agentTraceSink?;
     private readonly agentTracePolicy?;
+    /**
+     * OPTIONAL, because an application that declares no MCP server needs neither bound — and an
+     * agent with no `mcpRefs` never reaches them. Absence degrades to "this agent gets its
+     * `functionRefs` and nothing else", which is exactly what it got before #491.
+     */
+    private readonly mcpClient?;
+    private readonly mcpCredentialResolver?;
+    /**
+     * OPTIONAL, and feature-detected at every emission. An audit sink that is absent must never fail
+     * the act it was going to observe — the same stance the file-scanning lane takes, and the reason
+     * an observation is fire-and-forget rather than awaited into the turn's critical path.
+     */
+    private readonly auditLogs?;
     protected logDebug: (message: string, context?: Record<string, unknown>) => void;
     private readonly bottleneckInstances;
-    constructor(logger: LoggerService, errorBuilder: ErrorBuilderBackendService, flowsActorsRegistry: FlowsActorsRegistryService, externalProvidersRegistry: ExternalProvidersRegistryBackendService, backendProviderRegistryService: BackendProviderRegistryBackendService, promptCompiler: PromptCompilerBackendService, agentTraceSink?: AgentCallTraceSink, agentTracePolicy?: AgentTraceabilityPolicy);
+    constructor(logger: LoggerService, errorBuilder: ErrorBuilderBackendService, flowsActorsRegistry: FlowsActorsRegistryService, externalProvidersRegistry: ExternalProvidersRegistryBackendService, backendProviderRegistryService: BackendProviderRegistryBackendService, promptCompiler: PromptCompilerBackendService, agentTraceSink?: AgentCallTraceSink, agentTracePolicy?: AgentTraceabilityPolicy, 
+    /**
+     * OPTIONAL, because an application that declares no MCP server needs neither bound — and an
+     * agent with no `mcpRefs` never reaches them. Absence degrades to "this agent gets its
+     * `functionRefs` and nothing else", which is exactly what it got before #491.
+     */
+    mcpClient?: McpClientBackendService, mcpCredentialResolver?: McpCredentialResolverBackendService, 
+    /**
+     * OPTIONAL, and feature-detected at every emission. An audit sink that is absent must never fail
+     * the act it was going to observe — the same stance the file-scanning lane takes, and the reason
+     * an observation is fire-and-forget rather than awaited into the turn's critical path.
+     */
+    auditLogs?: AuditLogsBackendService);
     private mergeChunkedObjects;
     private getBottleneckForProvider;
     /**
@@ -565,6 +593,51 @@ export declare class AgentsBackendService {
      * CLI transport and for image agents — neither produces a token stream in v1.
      */
     private executeAgentStreaming;
+    /**
+     * Record one outbound MCP attempt on the audit trail.
+     *
+     * Fire-and-forget and feature-detected: an absent or failing audit sink must never fail the act it
+     * was going to observe. A turn that produced its answer must not be turned into a failure because
+     * the trail could not be written — the observation is evidence, not a gate.
+     *
+     * Emitted for the CALL path always, and for DISCOVERY only when the outbound guard refused the
+     * target. That asymmetry is deliberate: a refused target is an attempted egress a reviewer wants
+     * beside the calls that succeeded, whereas a server being unreachable or slow is availability, and
+     * putting every timeout on the security trail would bury the rows that mean something. Those still
+     * reach the log, at WARN, with the same server ref and host.
+     */
+    private recordMcpAttempt;
+    /**
+     * Resolve an agent's `capabilities.tools.mcpRefs` into callable tools by DISCOVERING what each
+     * declared server offers (#491).
+     *
+     * ## A server that cannot be reached contributes NOTHING, and the turn continues
+     *
+     * Fail-closed on the CLAIM, fail-open on the turn. Discovery happens here, at turn start, so a
+     * server that is unreachable, whose credential is unavailable, or whose target is refused simply
+     * adds no tools — and the model is never offered a capability it cannot use. That is the whole
+     * correction #491 exists for, one level down: the agent card advertised MCP servers that resolved
+     * to nothing, and the fix is not to advertise more carefully but to make what is offered be what
+     * can actually be called.
+     *
+     * Every one of those is logged at WARN with the server ref and destination HOST. A server quietly
+     * unreachable for a week must be visible as that, rather than as an agent that became less capable
+     * for no stated reason.
+     *
+     * ## The tools are NOT the same kind of thing as a functionRef, and are named so
+     *
+     * A `functionRef` dispatches a LOCAL resource operation and owes that operation's declared roles
+     * ACL and rate limit (#556). An MCP tool dispatches nothing locally — it leaves the trust boundary
+     * — so those gates have no operation to apply to. What it owes instead is enforced where a caller
+     * cannot skip it: the outbound target guard and the timeouts live inside the client, the credential
+     * comes from a resolver service, and the endpoint was refused at registration if it was plaintext.
+     *
+     * The `mcp_<serverRef>_<toolName>` prefix keeps the two planes distinguishable in a trace and
+     * prevents a third-party tool name from colliding with a declared `functionRef`.
+     *
+     * Returns the open sessions so the caller can release them; see `executeAgentStreaming`.
+     */
+    private resolveAgentMcpTools;
     /**
      * Resolve an agent's declarative `capabilities.tools.functionRefs` into AI-SDK
      * `tool(...)` definitions, closing each over the caller's `toolContext` so the
@@ -581,6 +654,20 @@ export declare class AgentsBackendService {
      * `tool-approval-request`; the other statuses (`approved` / `denied` / `not-applicable`) decide
      * without a human and are not what a `requiresHumanApproval` declaration means.
      */
+    /**
+     * The approval-signing key, or `undefined` when the application's primary secret is not set.
+     *
+     * PUBLIC because there are two moments that need this exact key and only one of them is a turn:
+     * the tool loop SIGNS an approval request when it suspends, and — since approve-with-modifications
+     * (#566) — a resume RE-SIGNS it after an approver authored different arguments. A second
+     * derivation in the resume path would be a second key the day either expression moved, and the
+     * failure would present as a forged approval rather than as the configuration skew it is.
+     *
+     * Returns rather than throws, because the two callers owe different answers: a TURN that cannot
+     * sign must be refused outright (see below), while a MODIFICATION that cannot be re-signed must
+     * leave the pause standing so the approver can still approve the call as proposed.
+     */
+    resolveToolApprovalSigningKey(): string | undefined;
     /**
      * The HMAC secret that signs approval requests — REQUIRED once any tool is approval-gated.
      *
@@ -665,10 +752,22 @@ export declare class AgentsBackendService {
     private extractProviderErrorDetails;
     private validateAgentStatus;
     /**
-     * Validate that an agent's declared function tools are all registered (so a
-     * streaming invocation can resolve them) and that any explicitly-required
-     * function refs are declared by the agent. Returns false on any gap rather
-     * than throwing, so callers can decide how to degrade.
+     * Validate that everything an agent DECLARES resolves — function tools in the registry and MCP
+     * servers in the application's declaration — and that any explicitly-required function refs are
+     * declared by the agent. Returns false on any gap rather than throwing, so callers can decide how
+     * to degrade.
+     *
+     * ## Why `mcpRefs` are checked here as well (#491)
+     *
+     * `FlowsActorsRegistryService.initialize` already REFUSES an agent whose `mcpRefs` name no
+     * declared server, so on the ordinary path this is redundant — and it is kept anyway, because
+     * `registerAgent` is PUBLIC and the refusal is not on it. An agent registered after initialization
+     * bypasses that gate entirely today, so this is the only site that would notice.
+     *
+     * The refusal is deliberately NOT moved onto `registerAgent`: addon load order is not guaranteed,
+     * and a per-registration check would refuse a coherent application for the order its addons
+     * happened to load in. Two sites answering the same question at two different moments is the
+     * correct shape here — one fails the boot, one degrades an invocation.
      */
     validateAgentCapabilities(agentRef: string, requiredCapabilities: string[]): boolean;
     getAvailableAgents(): FlowsActors_Agent[];

package/dist/esm/flows-actors/services/agents.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/flows-actors/services/agents.backend.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agents.backend.service.d.ts","sourceRoot":"","sources":["../../../../src/flows-actors/services/agents.backend.service.ts"],"names":[],"mappings":"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"}

package/dist/esm/flows-actors/services/agents.backend.service.js

@@ -13,10 +13,13 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 var AgentsBackendService_1;
 import 'reflect-metadata';
 import { injectable, inject, optional } from 'inversify';
-import { createHmac } from 'crypto';
 import { ApplicationBackendBootstrapEnvKeys } from '@wildo-ai/platform-config-lib';
 import { ExecutionContext_ExecutionType } from '@wildo-ai/saas-models';
 import Bottleneck from 'bottleneck';
+import { mcpServerDestinationHost } from '@wildo-ai/saas-models';
+import { McpOutcomeKind } from '../../flows-actors/models/mcp-client.backend.definitions.js';
+import { deriveToolApprovalSigningKey } from '../../flows-actors/utils/tool-approval-signing.backend.utils.js';
+import { McpCredentialOutcomeKind } from '../../flows-actors/services/mcp-credential-resolver.backend.service.js';
 import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
 import { LoggerService } from '../../monitoring/logger/services/logger.service.js';
 import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service.js';
@@ -28,9 +31,10 @@ import { PromptCompilerBackendService } from './prompt-compiler.backend.service.
 import { FlowsActors_Agent_Status, isImageAgentConfiguration, isCodingAgentConfiguration, PromptIR_TrustLevel, PromptIR_ContextSourceKind, ErrorType, ErrorCustomMessageReference, isWildoBackendError, AgentCallOutcome, AgentTraceabilityLevel, StructuredGenerationExecutionMode, } from '@wildo-ai/saas-models';
 import { MetaWorkflowStructuredGenerationPlanKind } from '@wildo-ai/saas-models/meta-workflows';
 import { APPLICATION_ENVIRONMENT, LLMProvider_ExecutionTransportKind, LLMProvider_ExecutionTransportMetadataSchema, LLMProvider_UsageSchema, LLMProvider_StructuredGenerationFailureKind, LLMProvider_StructuredGenerationFailureSchema, ExternalProvider_ExchangeProtocol_Kind, ExternalProvider_RateLimitConfigurationSchema, LLMProvider_OperationKey, LLMProvider_MessageRole, AgentClientProtocol_AuthMode, AgentClientProtocol_PermissionCeiling, AgentClientProtocol_WorkingDirectoryPolicy, agentClientProtocolPermissionCeilingRank, AgentClientProtocol_PermissionEscalationBehaviour, agentClientProtocolInFlightGuardsCanFire, AgentClientProtocol_HostConfigurationInheritance, CodingAgent_UsageSchema, AgentClientProtocol_ExecutionTransportMetadataSchema, CodingAgent_EndOfTurnClassification, CodingAgent_StopReason, ProviderProtocolRuntimeKind, } from '@wildo-ai/external-connectors-models';
-import { generateText, streamText, generateObject, generateImage, NoObjectGeneratedError, tool, stepCountIs } from 'ai';
+import { generateText, streamText, generateObject, generateImage, NoObjectGeneratedError, tool, jsonSchema, stepCountIs } from 'ai';
 import { startACPAgentSession, } from '../../flows-actors/utils/acp-session-runner.backend.utils.js';
 import { resolveTrustedWorkingDirectory } from '../../flows-actors/utils/bounded-subprocess.backend.utils.js';
+import { modelToolNameForFunctionRef } from '../../flows-actors/models/function-tools.backend.definitions.js';
 import { DEFAULT_MAX_STRUCTURED_DATA_FIELD_ALLOWED, planStructuredGenerationShape, } from '../../flows-actors/utils/meta-workflow-structured-generation-plan.backend.utils.js';
 /** The ladder phases a live coding session transitions through. */
 export var CodingSessionLadderPhase;
@@ -132,19 +136,6 @@ export function stripEmptyReasoningParts(messages) {
     }
     return result;
 }
-/**
- * Domain-separation label for the tool-approval signing key.
- *
- * The key is derived from the application's primary secret; this label is what makes the derived
- * key specific to approval signing, so it can never be confused with — or substituted for — any
- * other key derived from the same secret. Versioned (`:v1`) so a future change to the derivation
- * is a NEW key rather than a silent reinterpretation of the existing one.
- *
- * semantic-literal-boundary: this string is cryptographic key material, not a semantic vocabulary
- * member. Changing it invalidates every approval signed under the old label — that is the point of
- * versioning it, and the reason it must never be "tidied".
- */
-const TOOL_APPROVAL_SIGNING_KEY_LABEL = 'wildo:tool-approval-signing:v1';
 /**
  * The principals that can actually ANSWER an approval request.
  *
@@ -231,10 +222,13 @@ let AgentsBackendService = class AgentsBackendService {
     promptCompiler;
     agentTraceSink;
     agentTracePolicy;
+    mcpClient;
+    mcpCredentialResolver;
+    auditLogs;
     logDebug;
     // Bottleneck instances per provider for rate limiting LLM calls
     bottleneckInstances = new Map();
-    constructor(logger, errorBuilder, flowsActorsRegistry, externalProvidersRegistry, backendProviderRegistryService, promptCompiler, agentTraceSink, agentTracePolicy) {
+    constructor(logger, errorBuilder, flowsActorsRegistry, externalProvidersRegistry, backendProviderRegistryService, promptCompiler, agentTraceSink, agentTracePolicy, mcpClient, mcpCredentialResolver, auditLogs) {
         this.logger = logger;
         this.errorBuilder = errorBuilder;
         this.flowsActorsRegistry = flowsActorsRegistry;
@@ -243,6 +237,9 @@ let AgentsBackendService = class AgentsBackendService {
         this.promptCompiler = promptCompiler;
         this.agentTraceSink = agentTraceSink;
         this.agentTracePolicy = agentTracePolicy;
+        this.mcpClient = mcpClient;
+        this.mcpCredentialResolver = mcpCredentialResolver;
+        this.auditLogs = auditLogs;
         this.logDebug = this.logger.debugByType('AgentsBackend');
         this.logger.setDebugTypeLogging('AgentsBackend', false);
         this.logDebug('Agents backend service created');
@@ -2840,10 +2837,205 @@ let AgentsBackendService = class AgentsBackendService {
             throw new AgentStreamingUnsupportedError('transport', 'Token streaming is not supported for the ACP coding transport; use invokeAgent and observe progress through onCodingSessionEvent.');
         }
         const approvalGatedToolNames = new Set();
-        const tools = this.resolveAgentTools(agent, toolContext, approvalGatedToolNames);
+        const functionTools = this.resolveAgentTools(agent, toolContext, approvalGatedToolNames);
+        /*
+         * MCP tools are DISCOVERED, which means a network call per declared server, bounded by that
+         * server's discovery budget. A server that does not answer contributes nothing and the turn
+         * proceeds — so this cannot fail the invocation, only shorten the tool list.
+         */
+        const { tools: mcpTools, sessions: mcpSessions } = await this.resolveAgentMcpTools(agent, toolContext);
+        const tools = functionTools || Object.keys(mcpTools).length > 0
+            ? { ...(functionTools ?? {}), ...mcpTools }
+            : undefined;
         const toolApproval = this.buildToolApprovalConfiguration(approvalGatedToolNames, toolContext?.auth?.executionType);
         const toolApprovalSecret = toolApproval ? this.resolveToolApprovalSecretOrThrow(agent, approvalGatedToolNames) : undefined;
-        return this.executeAgentViaApiStreaming(agent, request, execution, prompts, handlers, tools, toolApproval, toolApprovalSecret);
+        try {
+            return await this.executeAgentViaApiStreaming(agent, request, execution, prompts, handlers, tools, toolApproval, toolApprovalSecret);
+        }
+        finally {
+            /*
+             * Released in a `finally` so a thrown turn does not leak a session on somebody else's server.
+             * `closeSession` swallows its own failures by contract — a server MAY refuse to let a client
+             * end a session — so this can never turn a successful turn into a failed one, nor mask the
+             * error of a failing one.
+             */
+            await Promise.all(mcpSessions.map((session) => this.mcpClient?.closeSession(session, null)));
+        }
+    }
+    /**
+     * Record one outbound MCP attempt on the audit trail.
+     *
+     * Fire-and-forget and feature-detected: an absent or failing audit sink must never fail the act it
+     * was going to observe. A turn that produced its answer must not be turned into a failure because
+     * the trail could not be written — the observation is evidence, not a gate.
+     *
+     * Emitted for the CALL path always, and for DISCOVERY only when the outbound guard refused the
+     * target. That asymmetry is deliberate: a refused target is an attempted egress a reviewer wants
+     * beside the calls that succeeded, whereas a server being unreachable or slow is availability, and
+     * putting every timeout on the security trail would bury the rows that mean something. Those still
+     * reach the log, at WARN, with the same server ref and host.
+     */
+    recordMcpAttempt(input) {
+        if (!this.auditLogs)
+            return;
+        void this.auditLogs.logMcpToolCall({
+            mcpServerRef: input.mcpServerRef,
+            destinationHost: input.destinationHost,
+            toolName: input.toolName,
+            outcome: input.outcome,
+            connectionOwnerScope: input.connectionOwnerScope,
+            credentialId: input.credentialId,
+            initiatorUserId: input.actingIdentity.userId,
+            organizationId: input.actingIdentity.organizationId,
+            agentRef: input.agentRef,
+        }).catch((error) => {
+            this.logger.warn('Could not record an MCP tool attempt on the audit trail; the turn is unaffected', {
+                agentRef: input.agentRef,
+                mcpServerRef: input.mcpServerRef,
+                ...projectCaughtErrorLogFields(error),
+            });
+        });
+    }
+    /**
+     * Resolve an agent's `capabilities.tools.mcpRefs` into callable tools by DISCOVERING what each
+     * declared server offers (#491).
+     *
+     * ## A server that cannot be reached contributes NOTHING, and the turn continues
+     *
+     * Fail-closed on the CLAIM, fail-open on the turn. Discovery happens here, at turn start, so a
+     * server that is unreachable, whose credential is unavailable, or whose target is refused simply
+     * adds no tools — and the model is never offered a capability it cannot use. That is the whole
+     * correction #491 exists for, one level down: the agent card advertised MCP servers that resolved
+     * to nothing, and the fix is not to advertise more carefully but to make what is offered be what
+     * can actually be called.
+     *
+     * Every one of those is logged at WARN with the server ref and destination HOST. A server quietly
+     * unreachable for a week must be visible as that, rather than as an agent that became less capable
+     * for no stated reason.
+     *
+     * ## The tools are NOT the same kind of thing as a functionRef, and are named so
+     *
+     * A `functionRef` dispatches a LOCAL resource operation and owes that operation's declared roles
+     * ACL and rate limit (#556). An MCP tool dispatches nothing locally — it leaves the trust boundary
+     * — so those gates have no operation to apply to. What it owes instead is enforced where a caller
+     * cannot skip it: the outbound target guard and the timeouts live inside the client, the credential
+     * comes from a resolver service, and the endpoint was refused at registration if it was plaintext.
+     *
+     * The `mcp_<serverRef>_<toolName>` prefix keeps the two planes distinguishable in a trace and
+     * prevents a third-party tool name from colliding with a declared `functionRef`.
+     *
+     * Returns the open sessions so the caller can release them; see `executeAgentStreaming`.
+     */
+    async resolveAgentMcpTools(agent, toolContext) {
+        const mcpRefs = agent.capabilities?.tools?.mcpRefs;
+        const empty = { tools: {}, sessions: [] };
+        if (!mcpRefs?.length || !toolContext)
+            return empty;
+        if (!this.mcpClient || !this.mcpCredentialResolver) {
+            // Declared, and this deployment bound no MCP services. Reported rather than silently empty:
+            // the agent is about to be less capable than its declaration says, and nothing else would say so.
+            this.logger.warn('Agent declares MCP servers but this deployment binds no MCP client; the agent will run without those tools', {
+                agentRef: agent.ref,
+                mcpRefs,
+            });
+            return empty;
+        }
+        const actingIdentity = {
+            userId: toolContext.auth?.initiatorIds?.userId,
+            organizationId: toolContext.organizationId,
+        };
+        const tools = {};
+        const sessions = [];
+        for (const ref of mcpRefs) {
+            const server = this.flowsActorsRegistry.getMcpServer(ref);
+            if (!server) {
+                // The registry refuses this at initialization, so reaching it means the agent was registered
+                // afterwards through the public `registerAgent`. Skipped rather than thrown: a turn is the
+                // wrong place to fail an application's configuration.
+                this.logger.warn('Agent declares an MCP server the application never declared; skipping', { agentRef: agent.ref, mcpRef: ref });
+                continue;
+            }
+            const credential = await this.mcpCredentialResolver.resolve(server, actingIdentity);
+            if (credential.kind !== McpCredentialOutcomeKind.RESOLVED) {
+                this.logger.warn('No credential for a declared MCP server; the agent will run without its tools', {
+                    agentRef: agent.ref,
+                    mcpServerRef: ref,
+                    outcome: credential.kind,
+                });
+                continue;
+            }
+            const discovery = await this.mcpClient.openSession(server, credential.token);
+            if (discovery.kind !== McpOutcomeKind.OK) {
+                this.logger.warn('An MCP server contributed no tools to this turn', {
+                    agentRef: agent.ref,
+                    mcpServerRef: discovery.mcpServerRef,
+                    destinationHost: discovery.destinationHost,
+                    outcome: discovery.kind,
+                    detail: discovery.detail,
+                });
+                // A refused TARGET is an attempted egress a guard blocked — a security event, and the row a
+                // reviewer wants beside the calls that succeeded. Everything else here is availability.
+                if (discovery.kind === McpOutcomeKind.REFUSED_TARGET) {
+                    this.recordMcpAttempt({
+                        agentRef: agent.ref,
+                        mcpServerRef: discovery.mcpServerRef,
+                        destinationHost: discovery.destinationHost,
+                        outcome: discovery.kind,
+                        connectionOwnerScope: credential.source,
+                        credentialId: credential.credentialId,
+                        actingIdentity,
+                    });
+                }
+                continue;
+            }
+            sessions.push(discovery.session);
+            for (const descriptor of discovery.session.tools) {
+                const toolName = `mcp_${ref}_${descriptor.name}`.replace(/[^a-zA-Z0-9_-]/g, '_');
+                tools[toolName] = tool({
+                    description: descriptor.description ?? descriptor.title ?? `${server.displayName}: ${descriptor.name}`,
+                    // The server's own JSON Schema, passed to the model unchanged. Re-deriving it as Zod would
+                    // be a second description of somebody else's contract, and the two would drift.
+                    inputSchema: jsonSchema(descriptor.inputSchema),
+                    execute: async (args) => {
+                        const outcome = await this.mcpClient.callTool(discovery.session, descriptor.name, args ?? {}, credential.token);
+                        /*
+                         * Every ATTEMPT is recorded, not only what worked. Recording successes alone would hide
+                         * exactly what a reviewer looks for first — the refusals, the timeouts, and the tools
+                         * that answered with their own error.
+                         */
+                        this.recordMcpAttempt({
+                            agentRef: agent.ref,
+                            mcpServerRef: server.ref,
+                            destinationHost: mcpServerDestinationHost(server.url),
+                            outcome: outcome.kind,
+                            toolName: descriptor.name,
+                            connectionOwnerScope: credential.source,
+                            credentialId: credential.credentialId,
+                            actingIdentity,
+                        });
+                        if (outcome.kind === McpOutcomeKind.OK)
+                            return outcome.content;
+                        /*
+                         * Returned to the MODEL as a result rather than thrown, and the difference is deliberate.
+                         * A thrown tool error becomes an SDK tool-error result the model narrates as prose, which
+                         * is how an ACL denial once got narrated as "I don't have permission to write to that
+                         * list" and sent an investigator at the list. A typed value the model can read lets it
+                         * retry or route around — which is the whole reason these five kinds are kept apart.
+                         */
+                        this.logger.warn('An MCP tool call did not succeed; the model is told and may route around it', {
+                            agentRef: agent.ref,
+                            mcpServerRef: outcome.mcpServerRef,
+                            destinationHost: outcome.destinationHost,
+                            toolName: descriptor.name,
+                            outcome: outcome.kind,
+                            detail: outcome.detail,
+                        });
+                        return { error: outcome.kind, detail: outcome.detail };
+                    },
+                });
+            }
+        }
+        return { tools, sessions };
     }
     /**
      * Resolve an agent's declarative `capabilities.tools.functionRefs` into AI-SDK
@@ -2865,8 +3057,9 @@ let AgentsBackendService = class AgentsBackendService {
                 this.logDebug('Agent declares an unknown function tool; skipping', { agentRef: agent.ref, functionRef: ref });
                 continue;
             }
-            // Provider tool names must be identifier-safe; functionRefs use dots.
-            const toolName = ref.replace(/[^a-zA-Z0-9_-]/g, '_');
+            // Provider tool names must be identifier-safe; functionRefs use dots. Shared with the
+            // approval-modification path, which must reverse it — see `modelToolNameForFunctionRef`.
+            const toolName = modelToolNameForFunctionRef(ref);
             tools[toolName] = tool({
                 description: functionTool.description,
                 inputSchema: functionTool.inputSchema,
@@ -2920,6 +3113,25 @@ let AgentsBackendService = class AgentsBackendService {
      * `tool-approval-request`; the other statuses (`approved` / `denied` / `not-applicable`) decide
      * without a human and are not what a `requiresHumanApproval` declaration means.
      */
+    /**
+     * The approval-signing key, or `undefined` when the application's primary secret is not set.
+     *
+     * PUBLIC because there are two moments that need this exact key and only one of them is a turn:
+     * the tool loop SIGNS an approval request when it suspends, and — since approve-with-modifications
+     * (#566) — a resume RE-SIGNS it after an approver authored different arguments. A second
+     * derivation in the resume path would be a second key the day either expression moved, and the
+     * failure would present as a forged approval rather than as the configuration skew it is.
+     *
+     * Returns rather than throws, because the two callers owe different answers: a TURN that cannot
+     * sign must be refused outright (see below), while a MODIFICATION that cannot be re-signed must
+     * leave the pause standing so the approver can still approve the call as proposed.
+     */
+    resolveToolApprovalSigningKey() {
+        const applicationSecret = process.env[ApplicationBackendBootstrapEnvKeys.PLATFORM_APPLICATION_PRIMARY_SECRET];
+        if (!applicationSecret || applicationSecret.trim().length === 0)
+            return undefined;
+        return deriveToolApprovalSigningKey(applicationSecret);
+    }
     /**
      * The HMAC secret that signs approval requests — REQUIRED once any tool is approval-gated.
      *
@@ -2956,10 +3168,9 @@ let AgentsBackendService = class AgentsBackendService {
      * approval is valid — and the failure would look like a forged approval rather than a config skew.
      */
     resolveToolApprovalSecretOrThrow(agent, approvalGatedToolNames) {
-        const applicationSecret = process.env[ApplicationBackendBootstrapEnvKeys.PLATFORM_APPLICATION_PRIMARY_SECRET];
-        if (applicationSecret && applicationSecret.trim().length > 0) {
-            return createHmac('sha256', applicationSecret).update(TOOL_APPROVAL_SIGNING_KEY_LABEL).digest('hex');
-        }
+        const signingKey = this.resolveToolApprovalSigningKey();
+        if (signingKey)
+            return signingKey;
         throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
             customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
             context: {
@@ -3364,20 +3575,35 @@ let AgentsBackendService = class AgentsBackendService {
         }
     }
     /**
-     * Validate that an agent's declared function tools are all registered (so a
-     * streaming invocation can resolve them) and that any explicitly-required
-     * function refs are declared by the agent. Returns false on any gap rather
-     * than throwing, so callers can decide how to degrade.
+     * Validate that everything an agent DECLARES resolves — function tools in the registry and MCP
+     * servers in the application's declaration — and that any explicitly-required function refs are
+     * declared by the agent. Returns false on any gap rather than throwing, so callers can decide how
+     * to degrade.
+     *
+     * ## Why `mcpRefs` are checked here as well (#491)
+     *
+     * `FlowsActorsRegistryService.initialize` already REFUSES an agent whose `mcpRefs` name no
+     * declared server, so on the ordinary path this is redundant — and it is kept anyway, because
+     * `registerAgent` is PUBLIC and the refusal is not on it. An agent registered after initialization
+     * bypasses that gate entirely today, so this is the only site that would notice.
+     *
+     * The refusal is deliberately NOT moved onto `registerAgent`: addon load order is not guaranteed,
+     * and a per-registration check would refuse a coherent application for the order its addons
+     * happened to load in. Two sites answering the same question at two different moments is the
+     * correct shape here — one fails the boot, one degrades an invocation.
      */
     validateAgentCapabilities(agentRef, requiredCapabilities) {
         const agent = this.flowsActorsRegistry.getAgentOrThrow(agentRef);
         const declaredFunctionRefs = agent.capabilities?.tools?.functionRefs ?? [];
+        const declaredMcpRefs = agent.capabilities?.tools?.mcpRefs ?? [];
         // Every tool the agent declares must resolve in the registry.
         const unresolved = declaredFunctionRefs.filter((ref) => !this.flowsActorsRegistry.hasFunctionTool(ref));
+        // And every MCP server it names must be one the application declared.
+        const unresolvedMcpRefs = declaredMcpRefs.filter((ref) => !this.flowsActorsRegistry.hasMcpServer(ref));
         // Every explicitly-required capability must be declared by the agent.
         const missingRequired = requiredCapabilities.filter((ref) => !declaredFunctionRefs.includes(ref));
-        const isValid = unresolved.length === 0 && missingRequired.length === 0;
-        this.logDebug('Agent capabilities validated', { agentRef, requiredCapabilities, unresolved, missingRequired, isValid });
+        const isValid = unresolved.length === 0 && unresolvedMcpRefs.length === 0 && missingRequired.length === 0;
+        this.logDebug('Agent capabilities validated', { agentRef, requiredCapabilities, unresolved, unresolvedMcpRefs, missingRequired, isValid });
         return isValid;
     }
     // ================================
@@ -3425,12 +3651,18 @@ AgentsBackendService = AgentsBackendService_1 = __decorate([
     __param(6, optional()),
     __param(7, inject(SAAS_SERVICE_TYPES.AgentTraceabilityPolicy)),
     __param(7, optional()),
+    __param(8, inject(SAAS_SERVICE_TYPES.McpClientService)),
+    __param(8, optional()),
+    __param(9, inject(SAAS_SERVICE_TYPES.McpCredentialResolverService)),
+    __param(9, optional()),
+    __param(10, inject(SAAS_SERVICE_TYPES.AuditLogsService)),
+    __param(10, optional()),
     __metadata("design:paramtypes", [LoggerService,
         ErrorBuilderBackendService,
         FlowsActorsRegistryService,
         ExternalProvidersRegistryBackendService,
         BackendProviderRegistryBackendService,
-        PromptCompilerBackendService, Object, Object])
+        PromptCompilerBackendService, Object, Object, Function, Function, Function])
 ], AgentsBackendService);
 export { AgentsBackendService };
 //# sourceMappingURL=agents.backend.service.js.map