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

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

@@ -27,11 +27,19 @@ 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, } 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 { runACPCodingSession } from '../../flows-actors/utils/acp-session-runner.backend.utils.js';
+import { startACPAgentSession, } from '../../flows-actors/utils/acp-session-runner.backend.utils.js';
 import { resolveTrustedWorkingDirectory } from '../../flows-actors/utils/bounded-subprocess.backend.utils.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;
+(function (CodingSessionLadderPhase) {
+    /** A turn is executing. */
+    CodingSessionLadderPhase["RUNNING"] = "running";
+    /** The session parked on a question and is waiting for an operator answer. */
+    CodingSessionLadderPhase["AWAITING_INPUT"] = "awaiting_input";
+})(CodingSessionLadderPhase || (CodingSessionLadderPhase = {}));
 /** True when an execution result carries a CODING transport rather than an LLM one. */
 function isAgentClientProtocolTransport(transport) {
     return transport?.protocolKind === ExternalProvider_ExchangeProtocol_Kind.AGENT_CLIENT_PROTOCOL;
@@ -586,7 +594,17 @@ let AgentsBackendService = class AgentsBackendService {
                 ...(code ? { code } : {}),
             };
         }
-        return { message: typeof error === 'string' ? error : 'Unknown agent invocation error' };
+        // A non-Error, non-string throw still carries information — a JSON-RPC error object, a refusal
+        // shape. Serialize it (bounded) rather than replacing it with a sentence that says nothing.
+        if (typeof error === 'string')
+            return { message: error };
+        try {
+            const serialized = JSON.stringify(error);
+            if (serialized && serialized !== '{}')
+                return { message: `Non-Error thrown: ${serialized.slice(0, 500)}` };
+        }
+        catch { /* circular or hostile — fall through to the sentinel */ }
+        return { message: 'Unknown agent invocation error' };
     }
     /**
      * Normalize executor outputs to the shared transport-neutral LLM contract.
@@ -709,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,
@@ -879,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, {
@@ -891,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,
@@ -904,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', {
@@ -941,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
@@ -951,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) });
@@ -1049,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);
@@ -1076,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;
@@ -1136,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') {
@@ -1167,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,
@@ -1188,67 +1304,223 @@ 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);
-            const sessionResult = await runACPCodingSession({
+            /*
+             * 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
+            // declared set and written into the transport metadata — and never reached
+            // the spawned agent, so under HOST_MANAGED auth every session ran at the
+            // OPERATOR's personal default model (measured: Opus, during a 529-overload
+            // storm the agent definitions' declared model would have avoided).
+            //
+            // The first fix wrote `ANTHROPIC_MODEL` unconditionally from this
+            // agent-NEUTRAL service, which is correct for exactly one adapter and a
+            // silent no-op for every other: the same false result, one agent later.
+            // So the channel is declared by the provider that knows its agent, and a
+            // 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] = 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: deliveredModel };
+            }
+            else {
+                throw this.errorBuilder.buildError(ErrorType.CONFIGURATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                    context: {
+                        providerRef: execution.providerRef,
+                        executionProfileRef: execution.executionProfileRef,
+                        requestedModel,
+                        message: 'ACP provider declares no model-delivery channel, so the selected model cannot reach the '
+                            + 'agent and the session is refused rather than run at the agent\'s own default.',
+                    },
+                });
+            }
+            // A run that ANSWERS a parked session resumes it by id via `session/load`
+            // instead of starting a fresh task; the input's prompt is then the answer.
+            const continuationOfSessionId = request.input
+                ?.continuationOfSessionId;
+            // (4) Open the live session, then drive it turn-by-turn.
+            const agentSession = await startACPAgentSession({
                 // The application may override how the agent is started, but normally
                 // inherits it: the provider owns the package and its pinned version.
                 command: acpExecutionProfile.command ?? acpProfile.agentCommand,
                 args: acpExecutionProfile.command ? acpExecutionProfile.args : acpProfile.agentArgs,
                 cwd: workingDirectory,
                 env,
-                prompt,
                 supportedProtocolVersions: acpProfile.supportedProtocolVersions,
                 // 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?.[effectivePermissionCeiling]
+                    ? {
+                        preferredSessionModeIds: acpProfile.sessionModeIdsByPermissionCeiling[effectivePermissionCeiling],
+                    }
+                    : {}),
+                ...(modelSelection ? { modelSelection } : {}),
                 ...(hostContext?.isPermittedCodingLocation
                     ? { isPermittedLocation: hostContext.isPermittedCodingLocation }
                     : {}),
                 ...(sessionMetaExtensions ? { sessionMetaExtensions } : {}),
-                ...(acpExecutionProfile.turnTimeoutMs !== undefined ? { turnTimeoutMs: acpExecutionProfile.turnTimeoutMs } : {}),
                 ...(acpExecutionProfile.maximumRecordedEventBytes !== undefined
                     ? { maxRecordedEventBytes: acpExecutionProfile.maximumRecordedEventBytes }
                     : {}),
                 ...(hostContext?.onCodingSessionEvent ? { onEvent: hostContext.onCodingSessionEvent } : {}),
-                ...(hostContext?.codingSessionAbortSignal ? { abortSignal: hostContext.codingSessionAbortSignal } : {}),
-            });
-            // (4) Result normalisation into the published contract.
-            const output = {
-                finalMessage: sessionResult.finalMessage,
-                stopReason: sessionResult.stopReason,
-                ...(sessionResult.rawStopReason ? { rawStopReason: sessionResult.rawStopReason } : {}),
-                // Always emitted, including zero: absence would be indistinguishable
-                // from "no denials", and under the strictest ceiling that is exactly the
-                // distinction an operator needs.
-                deniedPermissionCount: sessionResult.deniedPermissionCount,
-                // Copied because the Zod-inferred output type is mutable while the runner's surface is
-                // readonly; the runner must not hand out a reference a consumer could edit.
-                permissionDecisions: sessionResult.permissionDecisions.map((decision) => ({
-                    ...decision,
-                    locations: [...decision.locations],
-                    offeredOptionKinds: [...decision.offeredOptionKinds],
-                })),
-                ...(sessionResult.reportedFileLocations.length > 0
-                    ? { reportedFileLocations: [...sessionResult.reportedFileLocations] }
-                    : {}),
-            };
-            return {
-                output,
-                transport: {
-                    protocolKind: ExternalProvider_ExchangeProtocol_Kind.AGENT_CLIENT_PROTOCOL,
-                    providerRef: execution.providerRef,
-                    executionProfileRef: execution.executionProfileRef,
-                    model: requestedModel,
-                    negotiatedProtocolVersion: sessionResult.negotiatedProtocolVersion,
-                    ...(sessionResult.agentName ? { agentName: sessionResult.agentName } : {}),
-                    ...(sessionResult.agentVersion ? { agentVersion: sessionResult.agentVersion } : {}),
-                    ...(sessionResult.sessionModeId ? { sessionModeId: sessionResult.sessionModeId } : {}),
-                    sessionId: sessionResult.sessionId,
-                },
-                ...(sessionResult.usage ? { usage: sessionResult.usage } : {}),
-            };
+                ...(continuationOfSessionId ? { resumeSessionId: continuationOfSessionId } : {}),
+            });
+            try {
+                const ladder = await this.driveCodingTurnLadder({
+                    session: agentSession,
+                    firstPrompt: prompt,
+                    maxAutoContinuations: acpExecutionProfile.maxAutoContinuations,
+                    awaitingInputTtlMs: acpExecutionProfile.awaitingInputTtlMs,
+                    ...(acpExecutionProfile.turnTimeoutMs !== undefined ? { turnTimeoutMs: acpExecutionProfile.turnTimeoutMs } : {}),
+                    ...(hostContext?.codingSessionAbortSignal ? { abortSignal: hostContext.codingSessionAbortSignal } : {}),
+                    ...(hostContext?.classifyCodingTurnEnd ? { classify: hostContext.classifyCodingTurnEnd } : {}),
+                    ...(hostContext?.onCodingSessionStateChange ? { onStateChange: hostContext.onCodingSessionStateChange } : {}),
+                });
+                // (5) Result normalisation into the published contract.
+                const output = {
+                    finalMessage: ladder.finalMessage,
+                    stopReason: ladder.stopReason,
+                    ...(ladder.rawStopReason ? { rawStopReason: ladder.rawStopReason } : {}),
+                    // Always emitted, including zero: absence would be indistinguishable
+                    // from "no denials", and under the strictest ceiling that is exactly the
+                    // distinction an operator needs.
+                    deniedPermissionCount: ladder.deniedPermissionCount,
+                    permissionDecisions: ladder.permissionDecisions,
+                    ...(ladder.reportedFileLocations.length > 0
+                        ? { reportedFileLocations: ladder.reportedFileLocations }
+                        : {}),
+                    // Absent means one turn — the single-turn shape every pre-ladder
+                    // consumer already assumes.
+                    ...(ladder.turnCount > 1 ? { turnCount: ladder.turnCount } : {}),
+                    ...(ladder.continuations.length > 0 ? { continuations: ladder.continuations } : {}),
+                    // Present ONLY when the run parked on a question — the field that stops
+                    // a suspended turn being read as a completed result.
+                    ...(ladder.suspension ? { suspension: ladder.suspension } : {}),
+                };
+                return {
+                    output,
+                    transport: {
+                        protocolKind: ExternalProvider_ExchangeProtocol_Kind.AGENT_CLIENT_PROTOCOL,
+                        providerRef: execution.providerRef,
+                        executionProfileRef: execution.executionProfileRef,
+                        model: requestedModel,
+                        negotiatedProtocolVersion: agentSession.negotiatedProtocolVersion,
+                        ...(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 } : {}),
+                };
+            }
+            finally {
+                // Closes on completion AND on park: a parked session is answered by a
+                // fresh invocation that resumes it via `session/load`, never by holding
+                // this child alive across the HTTP call that returned the question.
+                agentSession.close();
+            }
         });
     }
     extractCLITextOutput(output) {
@@ -1504,6 +1776,197 @@ let AgentsBackendService = class AgentsBackendService {
      * adapter translates the abort into the TIMEOUT failure kind the retry policy already understands.
      */
     static STRUCTURED_GENERATION_DEADLINE_MS = 900_000;
+    /**
+     * The one prompt sent to auto-continue a coding agent past a self-imposed
+     * pause. Named here rather than improvised at the call site so a run's
+     * continuations are all identical and auditable, and so the wording — which
+     * tells the agent to keep working AND to stop only when genuinely done or
+     * genuinely blocked — lives in exactly one place.
+     */
+    static CODING_AUTO_CONTINUE_PROMPT = 'Continue with the task. Do not stop to ask whether to proceed — keep going until the task is '
+        + 'genuinely complete. Only stop if you have finished, or if you need a decision or input that '
+        + 'only the operator can provide, in which case state the specific question plainly.';
+    /** Characters of an end-of-turn message kept on a continuation record for audit. */
+    static CONTINUATION_MESSAGE_TAIL_CHARS = 500;
+    /**
+     * Drive a coding session turn-by-turn: continue a self-imposed pause, park a
+     * genuine question, settle on completion — bounded by the profile's
+     * continuation budget.
+     *
+     * The MECHANISM lives here; the JUDGMENT (`classify`) is the host's. The whole
+     * loop fails toward settlement: any terminal stop reason, an exhausted budget,
+     * or a classifier that is absent or throws all end the run with what the agent
+     * has produced rather than hanging. A `NEEDS_INPUT` classification is the only
+     * path that returns a `suspension`, and the caller must not read that as a
+     * completed result.
+     */
+    async driveCodingTurnLadder(params) {
+        const { session } = params;
+        const reportedFileLocations = [];
+        // Copied into the OUTPUT's mutable element shape here: the runner hands out
+        // readonly records, and the published contract's field is mutable.
+        const permissionDecisions = [];
+        const continuations = [];
+        let usage;
+        let deniedPermissionCount = 0;
+        let turnIndex = 0;
+        let autoContinuesUsed = 0;
+        let prompt = params.firstPrompt;
+        const emitState = (state) => {
+            try {
+                params.onStateChange?.(state);
+            }
+            catch {
+                // A live-relay sink must never fail the run it observes.
+            }
+        };
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            turnIndex += 1;
+            emitState({ phase: CodingSessionLadderPhase.RUNNING, turnIndex });
+            const turn = await session.promptTurn(prompt, {
+                ...(params.turnTimeoutMs !== undefined ? { turnTimeoutMs: params.turnTimeoutMs } : {}),
+                ...(params.abortSignal ? { abortSignal: params.abortSignal } : {}),
+            });
+            // Aggregate every turn's evidence, whatever the ladder decides next.
+            for (const path of turn.reportedFileLocations) {
+                if (!reportedFileLocations.includes(path))
+                    reportedFileLocations.push(path);
+            }
+            for (const decision of turn.permissionDecisions) {
+                permissionDecisions.push({
+                    ...decision,
+                    locations: [...decision.locations],
+                    offeredOptionKinds: [...decision.offeredOptionKinds],
+                });
+            }
+            deniedPermissionCount += turn.deniedPermissionCount;
+            usage = this.mergeCodingUsage(usage, turn.usage);
+            const settle = (suspension) => ({
+                finalMessage: turn.finalMessage,
+                stopReason: turn.stopReason,
+                ...(turn.rawStopReason ? { rawStopReason: turn.rawStopReason } : {}),
+                usage,
+                reportedFileLocations,
+                deniedPermissionCount,
+                permissionDecisions,
+                turnCount: turnIndex,
+                continuations,
+                ...(suspension ? { suspension } : {}),
+            });
+            // A non-voluntary stop (cancelled, max_tokens, refusal, or a reason this
+            // version does not recognise) is terminal: there is nothing to continue.
+            if (turn.stopReason !== CodingAgent_StopReason.END_TURN) {
+                return settle();
+            }
+            // END_TURN: decide what it meant. No classifier → treat as complete AND
+            // record nothing (the pre-ladder behaviour, preserved for every caller
+            // that supplies none — a plain single turn carries no continuations).
+            if (!params.classify) {
+                return settle();
+            }
+            const classification = await this.classifyCodingTurnEndSafely(params.classify, turn.finalMessage, turnIndex);
+            // A boundary is recorded only when the classifier was actually consulted,
+            // so `continuations` is the audit trail of judgments, never a per-run
+            // artefact that pollutes the single-turn shape.
+            continuations.push({
+                turnIndex,
+                classification,
+                agentMessageTail: turn.finalMessage.slice(-AgentsBackendService_1.CONTINUATION_MESSAGE_TAIL_CHARS),
+            });
+            if (classification === CodingAgent_EndOfTurnClassification.NEEDS_INPUT) {
+                const suspension = {
+                    sessionId: session.sessionId,
+                    question: turn.finalMessage,
+                    turnIndex,
+                    // Answerable across the child's death only if the agent persists sessions.
+                    resumable: session.capabilities.loadSession,
+                    parkedUntil: new Date(Date.now() + params.awaitingInputTtlMs).toISOString(),
+                };
+                emitState({ phase: CodingSessionLadderPhase.AWAITING_INPUT, turnIndex, question: turn.finalMessage });
+                return settle(suspension);
+            }
+            const isSelfPause = classification === CodingAgent_EndOfTurnClassification.SELF_PAUSE;
+            if (!isSelfPause || autoContinuesUsed >= params.maxAutoContinuations) {
+                // TASK_COMPLETE, CLASSIFIER_UNAVAILABLE, or a self-pause past the budget:
+                // settle with what the agent last produced.
+                return settle();
+            }
+            autoContinuesUsed += 1;
+            prompt = AgentsBackendService_1.CODING_AUTO_CONTINUE_PROMPT;
+        }
+    }
+    /**
+     * Run the host's end-of-turn classifier, mapping every failure to
+     * `CLASSIFIER_UNAVAILABLE` so the ladder can settle rather than hang.
+     *
+     * The whole point of a separate method: the fail-open contract is one place,
+     * and an unexpected classifier value (a host returning a string outside the
+     * enum) degrades the same way a throw does.
+     */
+    async classifyCodingTurnEndSafely(classify, finalMessage, turnIndex) {
+        try {
+            const result = await classify({ finalMessage, turnIndex });
+            if (Object.values(CodingAgent_EndOfTurnClassification).includes(result)) {
+                return result;
+            }
+            this.logger.warn('Coding turn-end classifier returned an unrecognised value; treating the turn as complete', {
+                turnIndex,
+                received: String(result),
+            });
+            return CodingAgent_EndOfTurnClassification.CLASSIFIER_UNAVAILABLE;
+        }
+        catch (error) {
+            // Fail OPEN. An auxiliary judgment must never make the autonomous lane hang
+            // or discard a mutated workspace; the failure is recorded, not laundered.
+            this.logger.warn('Coding turn-end classifier failed; treating the turn as complete', {
+                turnIndex,
+                // A WildoBackendError does not pass `instanceof Error`, and String() on it is
+                // "[object Object]" — which is exactly what this warn printed while the classifier was
+                // refusing every call over a missing config bound (2026-09-04). Bounded JSON names it.
+                error: error instanceof Error
+                    ? error.message
+                    : (() => { try {
+                        return JSON.stringify(error)?.slice(0, 600) ?? String(error);
+                    }
+                    catch {
+                        return String(error);
+                    } })(),
+            });
+            return CodingAgent_EndOfTurnClassification.CLASSIFIER_UNAVAILABLE;
+        }
+    }
+    /**
+     * Combine per-turn usage into a session total: token counts and cost SUM
+     * across turns; the context-window pair is a snapshot, so the latest turn's
+     * value wins. Absence stays absence — a field nobody reported must not read as
+     * zero, per the usage contract.
+     */
+    mergeCodingUsage(accumulated, turn) {
+        if (!turn)
+            return accumulated;
+        if (!accumulated)
+            return turn;
+        const merged = { ...accumulated };
+        for (const key of ['inputTokens', 'outputTokens', 'cachedReadTokens', 'cachedWriteTokens', 'totalTokens']) {
+            const a = accumulated[key];
+            const b = turn[key];
+            if (a !== undefined || b !== undefined)
+                merged[key] = (a ?? 0) + (b ?? 0);
+        }
+        // The context window is a level, not a flow: the newest reading is current.
+        if (turn.contextUsed !== undefined)
+            merged.contextUsed = turn.contextUsed;
+        if (turn.contextWindowSize !== undefined)
+            merged.contextWindowSize = turn.contextWindowSize;
+        if (turn.cost || accumulated.cost) {
+            merged.cost = {
+                amount: (accumulated.cost?.amount ?? 0) + (turn.cost?.amount ?? 0),
+                currency: turn.cost?.currency ?? accumulated.cost?.currency ?? 'USD',
+            };
+        }
+        return merged;
+    }
     buildBaseOptions(config) {
         const baseOptions = {
             temperature: config.temperature,
@@ -2525,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', {