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

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';
@@ -27,10 +30,11 @@ import { BackendProviderRegistryBackendService } from '../../external-providers/
 import { PromptCompilerBackendService } from './prompt-compiler.backend.service.js';
 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_HostConfigurationInheritance, CodingAgent_UsageSchema, AgentClientProtocol_ExecutionTransportMetadataSchema, CodingAgent_EndOfTurnClassification, CodingAgent_StopReason, } from '@wildo-ai/external-connectors-models';
-import { generateText, streamText, generateObject, generateImage, NoObjectGeneratedError, tool, stepCountIs } from 'ai';
+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, 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');
@@ -727,13 +724,13 @@ let AgentsBackendService = class AgentsBackendService {
             });
         }
         const binding = this.backendProviderRegistryService.getProtocolBinding(providerRef, protocolKind);
-        if (!binding || binding.runtimeContract.kind !== 'image') {
+        if (!binding || binding.runtimeContract.kind !== ProviderProtocolRuntimeKind.IMAGE) {
             throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
                 customMessageReference: ErrorCustomMessageReference.VALIDATION,
                 context: { providerRef, message: 'Image runtime contract not available for provider' },
             });
         }
-        const client = binding.runtimeContract.sdkFactory(apiKey);
+        const client = await binding.runtimeContract.sdkFactory(apiKey);
         if (typeof client?.imageModel !== 'function') {
             throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
                 customMessageReference: ErrorCustomMessageReference.AGENT_IMAGE_GENERATION_NOT_SUPPORTED,
@@ -897,7 +894,7 @@ let AgentsBackendService = class AgentsBackendService {
      * (fail-closed if missing) and build the SDK client (fail-closed if the
      * provider is not available).
      */
-    resolveApiProviderClient(providerRef) {
+    async resolveApiProviderClient(providerRef) {
         const apiKey = this.externalProvidersRegistry.getProviderApiKey(providerRef, ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER);
         if (!apiKey) {
             throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
@@ -909,7 +906,7 @@ let AgentsBackendService = class AgentsBackendService {
                 }
             });
         }
-        const aiProvider = this.getAIProvider(providerRef, apiKey);
+        const aiProvider = await this.getAIProvider(providerRef, apiKey);
         if (!aiProvider) {
             throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
                 customMessageReference: ErrorCustomMessageReference.VALIDATION,
@@ -922,7 +919,7 @@ let AgentsBackendService = class AgentsBackendService {
         return aiProvider;
     }
     async executeAgentViaApi(agent, request, execution, prompts) {
-        const aiProvider = this.resolveApiProviderClient(execution.providerRef);
+        const aiProvider = await this.resolveApiProviderClient(execution.providerRef);
         const limiter = this.getBottleneckForProvider(execution.providerRef, ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER);
         const jobId = `${agent.ref}-api-${Date.now()}-${Math.random().toString(36).substring(7)}`;
         this.logDebug('Scheduling API call through rate limiter', {
@@ -959,7 +956,7 @@ let AgentsBackendService = class AgentsBackendService {
      * Get AI SDK provider client configured with API key.
      *
      * Looks up the provider's `LLM_PROVIDER` runtime contract on the
-     * backend provider registry, narrows by `kind: 'llm'`, and invokes the
+     * backend provider registry, narrows by `kind: ProviderProtocolRuntimeKind.LLM`, and invokes the
      * `sdkFactory` declared on the contract. Per the framework principle
      * (provider behavior lives on the provider module), there is NO
      * `switch (providerRef)` here: adding a new LLM provider only requires
@@ -969,13 +966,13 @@ let AgentsBackendService = class AgentsBackendService {
      * or `null` when the provider has no LLM_PROVIDER binding (i.e. the
      * caller asked for an LLM client of a non-LLM provider).
      */
-    getAIProvider(providerRef, apiKey) {
+    async getAIProvider(providerRef, apiKey) {
         try {
             const binding = this.backendProviderRegistryService.getProtocolBinding(providerRef, ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER);
-            if (!binding || binding.runtimeContract.kind !== 'llm') {
+            if (!binding || binding.runtimeContract.kind !== ProviderProtocolRuntimeKind.LLM) {
                 return null;
             }
-            return binding.runtimeContract.sdkFactory(apiKey);
+            return await binding.runtimeContract.sdkFactory(apiKey);
         }
         catch (error) {
             this.logger.error('Failed to initialize AI provider', { providerRef, ...projectCaughtErrorLogFields(error) });
@@ -1067,7 +1064,23 @@ let AgentsBackendService = class AgentsBackendService {
         return env;
     }
     buildAgentClientProtocolEnvironment(execution) {
-        const env = this.buildSubprocessBaseEnvironment(execution.acpExecutionProfile.inheritedEnvironmentVariables);
+        // UNION of what the AGENT needs and what the APPLICATION asks for.
+        //
+        // The two lists answer different questions and only one of them is policy.
+        // Which variable an agent reads to locate its own credentials is PROVIDER
+        // knowledge — an application cannot be expected to know that Claude Code
+        // resolves its login through `CLAUDE_CONFIG_DIR` — so a provider-declared
+        // variable must reach every profile, including the ones applications author
+        // themselves. Before this, the contract's list was projected ONLY into the
+        // synthesized `default` profile, which the dogfood application deliberately
+        // never selects; the declaration was therefore inert exactly where it
+        // mattered, and the agent failed to authenticate with `OAuth session expired
+        // and could not be refreshed` — a message that is false and sends every
+        // diagnosis at the credential rather than at the environment.
+        const env = this.buildSubprocessBaseEnvironment([
+            ...(execution.acpProfile.inheritedEnvironmentVariables ?? []),
+            ...(execution.acpExecutionProfile.inheritedEnvironmentVariables ?? []),
+        ]);
         if (execution.acpExecutionProfile.authMode === AgentClientProtocol_AuthMode.SECRET_REF_ENV_INJECTION) {
             const secretEnvVarName = execution.acpExecutionProfile.secretEnvVarName;
             const secret = this.externalProvidersRegistry.getAgentClientProtocolExecutionProfileSecret(execution.providerRef, execution.executionProfileRef);
@@ -1094,7 +1107,7 @@ let AgentsBackendService = class AgentsBackendService {
      */
     llmProviderRequestsStrictJsonSchema(providerRef) {
         const binding = this.backendProviderRegistryService.getProtocolBinding(providerRef, ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER);
-        if (!binding || binding.runtimeContract.kind !== 'llm') {
+        if (!binding || binding.runtimeContract.kind !== ProviderProtocolRuntimeKind.LLM) {
             return null;
         }
         const declared = binding.runtimeContract.structuredOutputs?.strictJsonSchema;
@@ -1154,6 +1167,59 @@ let AgentsBackendService = class AgentsBackendService {
         }
         return execution.acpExecutionProfile.sessionMetaExtensions ?? execution.acpProfile.sessionMetaExtensions;
     }
+    /**
+     * What THIS agent's provider declares about escalating before it mutates.
+     *
+     * Read from the ACP runtime contract on the provider binding — never branched
+     * on `providerRef`, and deliberately not taken from the projected
+     * `AgentClientProtocol_Profile`: this is a measured PROVIDER FACT about an
+     * agent's behaviour, not application-authored policy, and it must not sit
+     * anywhere an application configuration could merge over it.
+     *
+     * `undefined` means the provider has no ACP binding at all, which the caller
+     * has already refused by the time this runs.
+     */
+    resolveAgentClientProtocolPermissionEscalation(providerRef) {
+        const binding = this.backendProviderRegistryService.getProtocolBinding(providerRef, ExternalProvider_ExchangeProtocol_Kind.AGENT_CLIENT_PROTOCOL);
+        if (!binding || binding.runtimeContract.kind !== ProviderProtocolRuntimeKind.AGENT_CLIENT_PROTOCOL) {
+            return undefined;
+        }
+        return binding.runtimeContract.permissionEscalation;
+    }
+    /**
+     * Can Wildo's in-flight guards fire for the session this run is about to open?
+     *
+     * Answered from the provider's declaration AND from the environment actually
+     * composed for the child, because for a conditionally-escalating agent those
+     * are two different facts: the agent escalates only if the pointer to its
+     * permission configuration really arrives, and a declaration that it "must be
+     * supplied" is not evidence that anything supplied it.
+     *
+     * The environment is inspected rather than trusted for the same reason the
+     * runner judges a permission request rather than the agent's session mode:
+     * the thing that decides behaviour is what the child receives.
+     */
+    resolveAgentClientProtocolInFlightGuardAvailability(escalation, childEnvironment) {
+        if (!escalation) {
+            // No declaration reachable. Assume the guards CANNOT fire: this field is
+            // required on the contract, so its absence means a provider shape this
+            // build does not understand, and reporting an unverified "yes" is the one
+            // answer that could make an operator trust a ceiling that is not there.
+            return { canFire: false };
+        }
+        const supplied = escalation.behaviour === AgentClientProtocol_PermissionEscalationBehaviour.RAISES_ONLY_UNDER_HOST_CONFIGURATION
+            ? childEnvironment[escalation.configurationEnvironmentVariableName] !== undefined
+            : false;
+        const canFire = agentClientProtocolInFlightGuardsCanFire(escalation.behaviour, supplied);
+        return {
+            behaviour: escalation.behaviour,
+            canFire,
+            ...(!canFire
+                && escalation.behaviour === AgentClientProtocol_PermissionEscalationBehaviour.RAISES_ONLY_UNDER_HOST_CONFIGURATION
+                ? { missingConfigurationEnvironmentVariable: escalation.configurationEnvironmentVariableName }
+                : {}),
+        };
+    }
     async executeAgentViaACP(agent, request, hostContext) {
         const execution = this.resolveAgentExecution(agent);
         if (execution.transport !== 'acp') {
@@ -1185,6 +1251,35 @@ let AgentsBackendService = class AgentsBackendService {
                 },
             });
         }
+        // The authored auth posture must be one the AGENT can actually use.
+        //
+        // `authModes` was consulted only when synthesizing the provider's `default`
+        // execution profile, so an application authoring its own — which the dogfood
+        // application does deliberately — could declare any mode and nothing
+        // checked it. Both directions are silently wrong rather than loud: a profile
+        // declaring HOST_MANAGED against a secret-injecting agent starts a run with
+        // no credential, and one declaring SECRET_REF_ENV_INJECTION against a
+        // host-managed agent injects a secret the agent ignores while the
+        // application believes the run is credentialed by configuration.
+        //
+        // Normalised on both sides at projection time; comparing the contract's
+        // hyphenated spelling against the enum's underscored one is a guard that
+        // never fires.
+        const supportedAuthModes = acpProfile.supportedAuthModes;
+        if (supportedAuthModes && !supportedAuthModes.includes(acpExecutionProfile.authMode)) {
+            throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    providerRef: execution.providerRef,
+                    executionProfileRef: execution.executionProfileRef,
+                    authoredAuthMode: acpExecutionProfile.authMode,
+                    supportedAuthModes: [...supportedAuthModes],
+                    message: 'The authored ACP execution profile declares an authentication mode this provider\'s agent '
+                        + 'does not support, so the session is refused rather than started with a credential posture '
+                        + 'the agent will not honour.',
+                },
+            });
+        }
         const workingDirectory = resolveTrustedWorkingDirectory({
             workspaceRootPath: hostContext?.workspaceRootPath,
             usesRelativePath: acpExecutionProfile.workingDirectoryPolicy === AgentClientProtocol_WorkingDirectoryPolicy.WORKSPACE_RELATIVE_PATH,
@@ -1206,8 +1301,77 @@ let AgentsBackendService = class AgentsBackendService {
             jobId,
         });
         const sessionMetaExtensions = this.resolveAgentClientProtocolSessionMeta(execution);
+        const effectivePermissionCeiling = this.resolveEffectivePermissionCeiling(acpExecutionProfile, request);
+        const permissionEscalation = this.resolveAgentClientProtocolPermissionEscalation(execution.providerRef);
         return limiter.schedule({ id: jobId }, async () => {
             const env = this.buildAgentClientProtocolEnvironment(execution);
+            /*
+             * Does this run's authored ceiling mean anything for THIS agent?
+             *
+             * Both of Wildo's in-flight controls — the permission ceiling and the
+             * task's mutation scope — are enforced in the client's ANSWER to
+             * `session/request_permission`. An agent that does not ask is bound by
+             * neither. Measured: Codex never asks before an in-workspace write (its
+             * safety model is a sandbox), and OpenCode does not either unless the host
+             * points it at a permission configuration file.
+             *
+             * The agents stay ADMISSIBLE. Refusing a tool because its architecture
+             * differs is exactly the hard ceremony the application-creation directive
+             * rejects, and the dogfood lane's `UNRESTRICTED` profile — which asks for
+             * no gate and gets none — runs unchanged through this branch.
+             *
+             * What is refused is a CONTRADICTION: a profile that authored a ceiling
+             * narrower than UNRESTRICTED, i.e. that asked for some autonomy to be
+             * withheld, against an agent from which nothing can be withheld. Running
+             * it anyway would not be permissive, it would be false — the ceiling would
+             * be a label, the mutation scope would never be consulted, and the only
+             * account of what the run touched would be a change set taken afterwards
+             * while the configuration said a gate was in place.
+             *
+             * The same shape as this transport's two existing refusals, and for the
+             * same reason: `resolveAgentClientProtocolSessionMeta` refuses an isolation
+             * posture the provider cannot express, and `modelDelivery` refuses a model
+             * that could not reach the agent. A declared safety field that cannot be
+             * honoured must refuse rather than be silently ignored; that is what makes
+             * it mean something. The door is one word wide and always open —
+             * `permissionCeiling: UNRESTRICTED` states plainly that this run has no
+             * in-flight gate, which is the truth either way.
+             */
+            const guardAvailability = this.resolveAgentClientProtocolInFlightGuardAvailability(permissionEscalation, env);
+            if (!guardAvailability.canFire && effectivePermissionCeiling !== AgentClientProtocol_PermissionCeiling.UNRESTRICTED) {
+                throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                    context: {
+                        providerRef: execution.providerRef,
+                        executionProfileRef: execution.executionProfileRef,
+                        permissionCeiling: effectivePermissionCeiling,
+                        permissionEscalation: guardAvailability.behaviour,
+                        ...(guardAvailability.missingConfigurationEnvironmentVariable
+                            ? { missingConfigurationEnvironmentVariable: guardAvailability.missingConfigurationEnvironmentVariable }
+                            : {}),
+                        message: 'This agent does not raise a permission request before mutating, so the authored permission '
+                            + 'ceiling and the task mutation scope cannot be enforced in flight and the session is refused '
+                            + 'rather than run under a ceiling that would be a label. '
+                            + (guardAvailability.missingConfigurationEnvironmentVariable
+                                ? `Supply ${guardAvailability.missingConfigurationEnvironmentVariable} in the child environment `
+                                    + '(name it in the execution profile\'s `inheritedEnvironmentVariables`, pointing at a permission '
+                                    + 'configuration OUTSIDE the application workspace), or author `permissionCeiling: UNRESTRICTED`.'
+                                : 'Author `permissionCeiling: UNRESTRICTED` to state that this run has no in-flight gate, or '
+                                    + 'select an agent whose provider declares that it escalates before mutating.'),
+                    },
+                });
+            }
+            // Stated at session open, beside the ceiling, so an operator watching a run
+            // start learns whether anything stands between the agent and the workspace
+            // — rather than learning it afterwards from a warning about a change set.
+            this.logDebug('Opening ACP coding session', {
+                agentRef: agent.ref,
+                providerRef: execution.providerRef,
+                executionProfileRef: execution.executionProfileRef,
+                permissionCeiling: effectivePermissionCeiling,
+                permissionEscalation: guardAvailability.behaviour ?? null,
+                inFlightPermissionGuardsCanFire: guardAvailability.canFire,
+            });
             // DELIVER the model, through the channel THIS agent's provider declares.
             //
             // Until 2026-09-03 `requestedModel` was checked against the transport's
@@ -1223,14 +1387,21 @@ let AgentsBackendService = class AgentsBackendService {
             // provider that declares none cannot have a model selected at all —
             // refused here rather than started with the choice quietly dropped.
             const modelDelivery = acpProfile.modelDelivery;
+            // The model is VALIDATED as a semantic id and DELIVERED in the agent's own
+            // spelling. Both halves matter: validation against `supportedModels` is
+            // what refuses a mis-pinned model before an agent is spawned, and the
+            // translation is what lets a multi-vendor agent — whose ids carry the
+            // provider, `anthropic/claude-sonnet-5` — be addressed at all. Absent
+            // means the two vocabularies coincide, which is the common case.
+            const deliveredModel = acpProfile.modelTransportIds?.[requestedModel] ?? requestedModel;
             let modelSelection;
             if (modelDelivery?.channel === 'environment-variable') {
-                env[modelDelivery.environmentVariableName] = requestedModel;
+                env[modelDelivery.environmentVariableName] = deliveredModel;
             }
             else if (modelDelivery?.channel === 'session-config-option') {
                 // Set over ACP after the session opens; the runner fails the session if
                 // the agent rejects it, before any prompt reaches the workspace.
-                modelSelection = { configId: modelDelivery.configId, model: requestedModel };
+                modelSelection = { configId: modelDelivery.configId, model: deliveredModel };
             }
             else {
                 throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
@@ -1260,14 +1431,19 @@ let AgentsBackendService = class AgentsBackendService {
                 // The invocation may request LESS autonomy than the profile allows; it
                 // can never request more. Clamped by rank rather than by trusting the
                 // request, so an input carrying a higher ceiling is lowered, not obeyed.
-                permissionCeiling: this.resolveEffectivePermissionCeiling(acpExecutionProfile, request),
+                //
+                // Resolved ONCE, above, and reused here: the guard-availability refusal
+                // just above decides on this exact value, and re-deriving it per use
+                // would let the value that was CHECKED and the value the session RUNS
+                // under drift apart — the whole class of defect this lane keeps meeting.
+                permissionCeiling: effectivePermissionCeiling,
                 // Agent-vocabulary mode ids from the provider contract. Absent is fine —
                 // the ceiling is enforced by answering permission requests, never by the
                 // agent's mode — but a map hardcoded in the runner silently matched
                 // nothing for any agent but the one it was written for.
-                ...(acpProfile.sessionModeIdsByPermissionCeiling?.[this.resolveEffectivePermissionCeiling(acpExecutionProfile, request)]
+                ...(acpProfile.sessionModeIdsByPermissionCeiling?.[effectivePermissionCeiling]
                     ? {
-                        preferredSessionModeIds: acpProfile.sessionModeIdsByPermissionCeiling[this.resolveEffectivePermissionCeiling(acpExecutionProfile, request)],
+                        preferredSessionModeIds: acpProfile.sessionModeIdsByPermissionCeiling[effectivePermissionCeiling],
                     }
                     : {}),
                 ...(modelSelection ? { modelSelection } : {}),
@@ -1324,6 +1500,13 @@ let AgentsBackendService = class AgentsBackendService {
                         ...(agentSession.agentName ? { agentName: agentSession.agentName } : {}),
                         ...(agentSession.agentVersion ? { agentVersion: agentSession.agentVersion } : {}),
                         ...(agentSession.sessionModeId ? { sessionModeId: agentSession.sessionModeId } : {}),
+                        // Recorded on the run because the ceiling alone does not describe it.
+                        // A change set produced under a ceiling that could be enforced and one
+                        // produced under a ceiling that was inert look identical afterwards,
+                        // and this pair is the only thing that tells a later reader whether
+                        // anything stood between the agent and these files.
+                        ...(guardAvailability.behaviour ? { permissionEscalation: guardAvailability.behaviour } : {}),
+                        inFlightPermissionGuardsCanFire: guardAvailability.canFire,
                         sessionId: agentSession.sessionId,
                     },
                     ...(ladder.usage ? { usage: ladder.usage } : {}),
@@ -2654,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
@@ -2679,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,
@@ -2734,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.
      *
@@ -2770,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: {
@@ -2802,7 +3199,7 @@ let AgentsBackendService = class AgentsBackendService {
     }
     /** API-transport streaming — mirrors executeAgentViaApi but forwards deltas + tool events. */
     async executeAgentViaApiStreaming(agent, request, execution, prompts, handlers, tools, toolApproval, toolApprovalSecret) {
-        const aiProvider = this.resolveApiProviderClient(execution.providerRef);
+        const aiProvider = await this.resolveApiProviderClient(execution.providerRef);
         const limiter = this.getBottleneckForProvider(execution.providerRef, ExternalProvider_ExchangeProtocol_Kind.LLM_PROVIDER);
         const jobId = `${agent.ref}-api-stream-${Date.now()}-${Math.random().toString(36).substring(7)}`;
         this.logDebug('Scheduling streaming API call through rate limiter', {
@@ -3178,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;
     }
     // ================================
@@ -3239,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