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

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_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 { 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.
@@ -1190,65 +1208,133 @@ let AgentsBackendService = class AgentsBackendService {
         const sessionMetaExtensions = this.resolveAgentClientProtocolSessionMeta(execution);
         return limiter.schedule({ id: jobId }, async () => {
             const env = this.buildAgentClientProtocolEnvironment(execution);
-            const sessionResult = await runACPCodingSession({
+            // 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;
+            let modelSelection;
+            if (modelDelivery?.channel === 'environment-variable') {
+                env[modelDelivery.environmentVariableName] = requestedModel;
+            }
+            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 };
+            }
+            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),
+                // 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)]
+                    ? {
+                        preferredSessionModeIds: acpProfile.sessionModeIdsByPermissionCeiling[this.resolveEffectivePermissionCeiling(acpExecutionProfile, request)],
+                    }
+                    : {}),
+                ...(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 } : {}),
+                ...(continuationOfSessionId ? { resumeSessionId: continuationOfSessionId } : {}),
             });
-            // (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 } : {}),
-            };
+            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 } : {}),
+                        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 +1590,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,