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

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

@@ -27,7 +27,7 @@ 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 { 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 { startACPAgentSession, } from '../../flows-actors/utils/acp-session-runner.backend.utils.js';
 import { resolveTrustedWorkingDirectory } from '../../flows-actors/utils/bounded-subprocess.backend.utils.js';
@@ -727,13 +727,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 +897,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 +909,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 +922,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 +959,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 +969,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 +1067,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 +1110,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 +1170,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 +1254,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 +1304,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 +1390,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 +1434,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 +1503,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 } : {}),
@@ -2802,7 +2988,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', {