@memberjunction/ai-agents 6.1.0-edge.0 → 6.1.0-edge.2

package/dist/base-agent.js

@@ -10,7 +10,7 @@
  * @author MemberJunction.com
  * @since 2.49.0
  */
-import { FileStorageEngineBase } from '@memberjunction/core-entities';
+import { FileStorageEngineBase, MJEnvironmentEntityExtended } from '@memberjunction/core-entities';
 import { Metadata, RunView, LogStatus, LogStatusEx, LogError, LogErrorEx, IsVerboseLoggingEnabled, DatabaseProviderBase } from '@memberjunction/core';
 import { AgentRunWatchdog } from './agent-run-watchdog.js';
 import { AIPromptRunner } from '@memberjunction/ai-prompts';
@@ -23,8 +23,9 @@ import { CrushJSON, DescribeCrush, PartitionStablePrefix } from '@memberjunction
 import { CrushCode } from '@memberjunction/context-crush/code';
 import { RealtimeSessionRunner } from './realtime/realtime-session-runner.js';
 import { ResolveNarrationInstructionsTemplate } from './realtime/realtime-narration.js';
-import { BuildRealtimeOverridesJson, BuildVoiceMannerSection, GetNarrationPaceMs, GetProviderVoiceSettings, GetSessionTuningSettings, DeepMergeConfigs, ResolveEffectiveRealtimeConfig } from './realtime/realtime-coagent-config.js';
-import { RealtimeClientSessionService } from './realtime/realtime-client-session-service.js';
+import { BuildRealtimeOverridesJson, BuildVoiceMannerSection, GetNarrationPaceMs, GetProviderVoiceSettings, GetSessionTuningSettings, GetModelCatalogSessionSettings, DeepMergeConfigs, ResolveEffectiveRealtimeConfig } from './realtime/realtime-coagent-config.js';
+import { SelectRealtimeVendorForModel } from './realtime/realtime-vendor-resolution.js';
+import { RealtimeClientSessionService, WarnOnUnmatchedProviderVoice } from './realtime/realtime-client-session-service.js';
 import { BuildRealtimeAgentFraming } from './realtime/realtime-tool-broker.js';
 import { RealtimeRecordingController } from './realtime/realtime-recording-capture.js';
 import { resolveRecordingStorageAccountID, storeRealtimeRecording } from './realtime/realtime-recording-store.js';
@@ -38,13 +39,16 @@ import { FormatToolResultSection, FormatToolErrorSection, RenderToolResultData,
 import { PriorTurnToolResultCache } from './prior-turn-tool-result-cache.js';
 import { PromptComponentResolver, InjectScopedPromptParts } from './prompt-component-resolver.js';
 import { ScopedPromptConfigResolver, ApplyScopedPromptConfig } from './scoped-prompt-config-resolver.js';
-import { AIPromptParams, ChildPromptParam, ConversationUtility, ParseFileOutputRef, parseAssignmentStrategy, ResolveClientTools, initAgentRunStep, finalizeAgentRunStep, AgentRunStepSaveQueue, ExtractPromptResultText } from '@memberjunction/ai-core-plus';
+import { AIPromptParams, ChildPromptParam, ConversationUtility, ParseFileOutputRef, parseAssignmentStrategy, ResolveClientTools, initAgentRunStep, finalizeAgentRunStep, AgentRunStepSaveQueue, ExtractPromptResultText, GetTaskGraphSubmitter } from '@memberjunction/ai-core-plus';
 import { AgentRunner } from './AgentRunner.js';
 import { PayloadManager } from './PayloadManager.js';
 import { ScratchpadManager } from './ScratchpadManager.js';
 import { ArtifactToolManager } from './ArtifactToolManager.js';
 import { MemoryWriteManager } from './MemoryWriteManager.js';
 import { PipelineExecutor, PipelineToolRegistry, ActionInvocable, ArtifactToolInvocable, BuildPipelineToolDocs, formatFinalOutput, summarizePipelineStages, } from './pipeline/index.js';
+// The ONE payload-mapping dialect. Loop agents and the task-graph dispatcher read the same authored
+// mapping strings, so these must be the same functions rather than two copies that agree today.
+import { GetValueFromPath, SetMappedValue } from '@memberjunction/ai-core-plus';
 import { AgentDataPreloader } from './AgentDataPreloader.js';
 import { ClientToolRequestManager } from './ClientToolRequestManager.js';
 import { ConversationMessageResolver } from './utils/ConversationMessageResolver.js';
@@ -144,6 +148,29 @@ export class BaseAgent {
          * @private
          */
         this._agentRun = null;
+        /**
+         * The task graph this run submitted and is now waiting on, or null.
+         *
+         * **Why a run parks instead of completing.** Submitting a graph is submit-and-detach: the run
+         * returns as soon as the graph is durable, and the dispatcher executes it afterwards — possibly
+         * minutes later, possibly on another instance, and for a graph containing a human approval,
+         * possibly days later. That is deliberate and must not change: awaiting would hold a run (and the
+         * conversation turn behind it) open for the length of an approval, and a graph that settles on a
+         * different host could never complete an awaiting run at all.
+         *
+         * But finishing as `Completed` said something untrue. A run that reported success, a duration of
+         * 441ms and a green COMPLETED badge, above a workflow where nothing had happened yet, is not a
+         * display problem — the row itself claimed to be done. So the run ends in `Paused`, which the
+         * conversation UI already reads as in-progress, and the DISPATCHER completes it when the graph
+         * settles (`TaskGraphDispatcher.settleSubmittingRun`). Nothing blocks, and no row claims to be
+         * finished while work it caused is still in flight.
+         *
+         * Set for whichever run submitted — root or sub-agent. A sub-agent that dispatches a graph parks
+         * its own run exactly the same way; its parent is unaffected and completes normally, which is
+         * correct, because the parent's own work IS done. What a viewer of the PARENT sees is covered by
+         * the run tree, which walks into the sub-agent's graph and reports it still running.
+         */
+        this._awaitingWorkflowTaskID = null;
         /**
          * Stores the ID of an AIAgentRequest created when a Chat step fires.
          * Populated by executeChatStep(), returned in ExecuteAgentResult.feedbackRequestId.
@@ -602,7 +629,7 @@ export class BaseAgent {
             // Check if this param is marked as MediaOutput in action metadata
             // Note: 'MediaOutput' ValueType is added in v3.1.x migration.
             // Before CodeGen runs, this property may not exist on the entity type.
-            const paramMetadata = actionEntity?.Params?.find(p => p.Name === param.Name);
+            const paramMetadata = actionEntity?.Params?.Items.find(p => p.Name === param.Name);
             const valueType = paramMetadata?.ValueType;
             const isMediaOutputParam = valueType === 'MediaOutput';
             // Handle MediaOutput params (e.g., Generate Image action)
@@ -1355,6 +1382,7 @@ export class BaseAgent {
             // passed in, not our chained signal.
             params.cancellationToken = upstreamToken;
             this.releasePerRunDataCache();
+            await this.finalizeRun(this.deriveRunOutcome());
         }
     }
     /**
@@ -1369,6 +1397,32 @@ export class BaseAgent {
             AgentDataPreloader.Instance.clearRunCache(this._agentRun.ID);
         }
     }
+    /**
+     * Subclass extension point for per-run cleanup of resources this instance owns outside of
+     * MJ's own tracked state (e.g. an external sandbox or session). No-op by default. Called
+     * unconditionally from `Execute()`'s top-level `finally` block, once per `Execute()` call,
+     * so it runs on every exit path (success, failure, or cancellation) exactly like
+     * {@link releasePerRunDataCache}.
+     */
+    async finalizeRun(outcome) {
+        // Intentionally empty — subclasses override as needed.
+    }
+    /**
+     * Maps the just-completed run's final `AgentRun.Status` to the 3-value outcome that
+     * {@link finalizeRun} hooks care about. `'AwaitingFeedback'` is a normal settled end-of-turn
+     * (see {@link settledRunStatuses}) — the conversational turn is genuinely over, not paused
+     * mid-`Execute()` — so it maps to `'success'`, same as `'Completed'`.
+     */
+    deriveRunOutcome() {
+        switch (this._agentRun?.Status) {
+            case 'Cancelled':
+                return 'cancelled';
+            case 'Failed':
+                return 'failure';
+            default:
+                return 'success';
+        }
+    }
     // =====================================================================================
     // REALTIME (SESSION-DRIVEN) AGENT SUPPORT
     //
@@ -1544,19 +1598,26 @@ export class BaseAgent {
         // a usable model exists. This mirrors the same fix in RealtimeClientSessionService.
         const candidates = this.selectRealtimeModelCandidates(params.agent, overrideModelID);
         for (const model of candidates) {
-            const vendor = this.selectRealtimeVendor(model.ID);
+            const vendor = SelectRealtimeVendorForModel(model.ID);
             if (!vendor) {
                 continue;
             }
-            const apiKey = GetAIAPIKey(vendor.driverClass);
+            const apiKey = GetAIAPIKey(vendor.DriverClass);
             if (!apiKey) {
                 continue;
             }
-            const instance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseRealtimeModel, vendor.driverClass, apiKey);
+            const instance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseRealtimeModel, vendor.DriverClass, apiKey);
             if (!instance) {
                 continue;
             }
-            return { model: instance, modelID: model.ID, vendorID: vendor.vendorID, apiName: vendor.apiName, driverClass: vendor.driverClass };
+            return {
+                model: instance,
+                modelID: model.ID,
+                vendorID: vendor.VendorID,
+                modelVendorID: vendor.ModelVendorID,
+                apiName: vendor.APIName,
+                driverClass: vendor.DriverClass
+            };
         }
         return null;
     }
@@ -1622,24 +1683,6 @@ export class BaseAgent {
         }
         return ResolveEffectiveRealtimeConfig(typeDefault, agent.TypeConfiguration ?? null, null);
     }
-    /**
-     * Selects the highest-priority active vendor for a model whose `DriverClass` has a resolvable
-     * API key. Mirrors the vendor-selection pattern used by prompt execution.
-     *
-     * @param modelID The chosen model's ID.
-     * @returns The vendor driver/api identifiers, or `null` when none has a usable key.
-     */
-    selectRealtimeVendor(modelID) {
-        const vendors = AIEngine.Instance.ModelVendors
-            .filter(mv => UUIDsEqual(mv.ModelID, modelID) && mv.Status === 'Active' && mv.DriverClass != null)
-            .sort((a, b) => (b.Priority ?? 0) - (a.Priority ?? 0));
-        for (const v of vendors) {
-            if (GetAIAPIKey(v.DriverClass)) {
-                return { vendorID: v.VendorID ?? '', driverClass: v.DriverClass, apiName: v.APIName ?? '' };
-            }
-        }
-        return null;
-    }
     /**
      * Creates the single long-lived `AIPromptRun` that realtime usage is checkpointed onto.
      *
@@ -1699,7 +1742,7 @@ export class BaseAgent {
      */
     async buildRealtimeSessionDeps(params, config, modelResolution, promptRun) {
         const effectiveConfig = this.resolveRealtimeEffectiveConfig(params.agent);
-        const sessionParams = await this.buildRealtimeSessionParams(params, config, modelResolution.apiName, effectiveConfig, modelResolution.driverClass);
+        const sessionParams = await this.buildRealtimeSessionParams(params, config, modelResolution.apiName, effectiveConfig, modelResolution.driverClass, modelResolution.modelID, modelResolution.modelVendorID);
         return {
             Model: modelResolution.model,
             SessionParams: sessionParams,
@@ -1737,7 +1780,7 @@ export class BaseAgent {
      * @param modelApiName The vendor API name of the resolved realtime model.
      * @returns The session parameters.
      */
-    async buildRealtimeSessionParams(params, config, modelApiName, effectiveConfig, driverClass) {
+    async buildRealtimeSessionParams(params, config, modelApiName, effectiveConfig, driverClass, modelID, modelVendorID) {
         // Identity framing comes from the ONE shared producer so the agent speaks first-person AS the
         // TARGET (Sage / Marketing Agent / …), identical to every other realtime host — not as the co-agent.
         // See BuildRealtimeAgentFraming + plans/realtime/realtime-core-host-convergence.md.
@@ -1750,13 +1793,22 @@ export class BaseAgent {
         const systemPrompt = [framing, basePrompt, voiceManner, memoryContext]
             .filter(part => part && part.trim().length > 0)
             .join('\n\n');
-        // Provider-matched voice settings (realtime.voice.providers.<provider>) AND session-tuning
-        // knobs (realtime.session) flow into the driver's open Config bag — the same pact every
-        // other config entry rides, mirroring the client-direct builder's cascade exactly.
+        // Model-catalog defaults (the AIModelType < AIModel < AIModelVendor ModelConfiguration
+        // cascade) merge as the BASE layer, then the voice settings — the persona's agnostic
+        // wire-level slots (see RealtimeVoicePersona) plus any matching
+        // `realtime.voice.providers.<provider>` bag —
+        // AND session-tuning knobs (realtime.session) flow into the driver's open Config bag: the same
+        // pact every other config entry rides, mirroring the client-direct builder's cascade exactly.
+        // Same unmatched-provider diagnosis too, so this surface cannot drift back into dropping
+        // authored settings silently (#3530).
+        const catalogSettings = modelID
+            ? GetModelCatalogSessionSettings(AIEngine.Instance.GetEffectiveModelConfiguration(modelID, modelVendorID))
+            : null;
         const providerVoice = GetProviderVoiceSettings(effectiveConfig, driverClass ?? null);
+        WarnOnUnmatchedProviderVoice(effectiveConfig, driverClass, 'BaseAgent.buildRealtimeSessionParams');
         const sessionTuning = GetSessionTuningSettings(effectiveConfig);
-        const configBag = (sessionTuning || providerVoice)
-            ? DeepMergeConfigs(sessionTuning, providerVoice)
+        const configBag = (catalogSettings || sessionTuning || providerVoice)
+            ? DeepMergeConfigs(catalogSettings, sessionTuning, providerVoice)
             : undefined;
         return {
             Model: modelApiName,
@@ -3124,6 +3176,12 @@ export class BaseAgent {
             case 'ClientTools':
                 // Client tools are valid - execution handled by executeClientToolsStep
                 return nextStep;
+            // Type assertion required because 'Tasks' is not part of the BaseAgentNextStep step
+            // union (submit-and-detach — the terminal step it produces is 'Success'). The graph was
+            // already validated against TaskGraphSpec by the agent type, so there is nothing left
+            // to check here; submission is handled by executeTasksStep.
+            case 'Tasks':
+                return nextStep;
             default:
                 // if we get here, the next step is not recognized, we can return a retry step
                 this.logError(`Invalid next step '${nextStep.step}' for agent '${params.agent.Name}'`, {
@@ -3782,6 +3840,29 @@ export class BaseAgent {
      */
     async hasExceededAgentRunGuardrails(params, agentRun) {
         const agent = params.agent;
+        // Refresh the run's accumulated cost/token actuals before comparing them to the agent's
+        // static limits.
+        //
+        // The LIMITS are static — MaxCostPerRun and MaxTokensPerRun live on the agent and never
+        // change during a run. What was missing is the other side of the comparison: TotalCost and
+        // TotalTokensUsed are DERIVED from the run's steps by calculateTokenStats(), and the only
+        // writer (applyTokenStatsToRun) previously ran on terminal paths alone —
+        // createFailureResult / createCancelledResult / finalizeAgentRun — plus the post-compaction
+        // top-up, which only fires if compaction happens to trigger.
+        //
+        // So mid-run both fields sat at 0, and because the checks below are guarded on
+        // `agent.MaxCostPerRun && agentRun.TotalCost`, a falsy 0 short-circuited them entirely. The
+        // cost and token ceilings were evaluated only at the moment a run ENDED, which is too late
+        // to stop anything: they became reporting, not guardrails. Only the iteration and time
+        // limits actually interrupted a run, because TotalPromptIterations is incremented in the
+        // loop.
+        //
+        // Recomputing here rather than at the call site means every caller — including subclasses
+        // that override the loop — gets a truthful comparison, and the recompute is cheap: it walks
+        // the in-memory step array, with no database round trip.
+        if (this._agentRun === agentRun) {
+            this.applyTokenStatsToRun(agentRun, this.calculateTokenStats());
+        }
         // Check absolute maximum iterations (safety net to prevent infinite loops)
         const DEFAULT_ABSOLUTE_MAX_ITERATIONS = 5000;
         const absoluteMaxIterations = params.absoluteMaxIterations ?? DEFAULT_ABSOLUTE_MAX_ITERATIONS;
@@ -5610,6 +5691,20 @@ The context is now within limits. Please retry your request with the recovered c
                 responseType[responseTypeKey] = true;
             }
         }
+        // Capability gates align the OTHER way: default OFF, and the section appears only when the
+        // gate is explicitly on. Running these through the loop above would invert their meaning —
+        // that loop's `else` branch defaults an unset key to true, which is exactly what a gated
+        // capability must never do.
+        const gateMappings = [
+            { gateFlag: 'enableTaskGraphs', responseTypeKey: 'tasks' }
+        ];
+        for (const { gateFlag, responseTypeKey } of gateMappings) {
+            const wasExplicitlySet = explicitResponseType &&
+                Object.prototype.hasOwnProperty.call(explicitResponseType, responseTypeKey);
+            if (!wasExplicitlySet) {
+                responseType[responseTypeKey] = params[gateFlag] === true;
+            }
+        }
     }
     /**
      * Extracts default values from a JSON Schema definition.
@@ -5967,12 +6062,12 @@ The context is now within limits. Please retry your request with the recovered c
             const lines = [];
             lines.push(`### ${action.Name}`);
             lines.push(action.Description);
-            const inputParams = action.Params
+            const inputParams = action.Params.Items
                 .filter(p => {
                 const t = p.Type.trim().toLowerCase();
                 return t === 'input' || t === 'both';
             });
-            const outputParams = action.Params
+            const outputParams = action.Params.Items
                 .filter(p => {
                 const t = p.Type.trim().toLowerCase();
                 return t === 'output' || t === 'both';
@@ -5983,8 +6078,8 @@ The context is now within limits. Please retry your request with the recovered c
             if (outputParams.length > 0) {
                 lines.push(`**Output:** ${outputParams.map(p => this.formatActionParameter(p)).join(', ')}`);
             }
-            if (action.ResultCodes.length > 0) {
-                const rcParts = action.ResultCodes.map(rc => {
+            if (action.ResultCodes.Items.length > 0) {
+                const rcParts = action.ResultCodes.Items.map(rc => {
                     const marker = rc.IsSuccess ? '✓' : '✗';
                     const desc = rc.Description && rc.Description.toLowerCase() !== rc.ResultCode.toLowerCase()
                         ? ` ${rc.Description}`
@@ -6590,6 +6685,10 @@ The context is now within limits. Please retry your request with the recovered c
         // If neither is set, EffortLevel remains null (no effort level override was used)
         // Set parent run ID if we're in a sub-agent context
         this._agentRun.ParentRunID = params.parentRun?.ID;
+        // Only a continuation deliverer sets this; every ordinary run stays at the column default of
+        // 0. It has to be recorded on the run itself because the run is the only thing that outlives
+        // the dispatcher that started it, and the next graph this run submits reads it back.
+        this._agentRun.ContinuationDepth = params.continuationDepth ?? 0;
         // Set LastRunID for run chaining (different from ParentRunID)
         if (params.lastRunId) {
             // Check for circular references in the run chain
@@ -7166,6 +7265,10 @@ The context is now within limits. Please retry your request with the recovered c
                 }
                 return await this.executePromptStep(params, config, previousDecision, stepCount);
             case 'Sub-Agent':
+                // A Sub-Agent step carrying a task graph is a FOLDED graph (D9): the agent type
+                // rewrote a one-node graph into an ordinary in-run call. Record it before running,
+                // so the run shows what was emitted even if the sub-agent then fails.
+                await this.recordFoldedTaskGraph(params, previousDecision);
                 return await this.processSubAgentStep(params, previousDecision, undefined, undefined, stepCount);
             case 'Actions':
                 return await this.executeActionsStep(params, previousDecision, undefined, true, stepCount);
@@ -7179,6 +7282,11 @@ The context is now within limits. Please retry your request with the recovered c
             // (Plan Mode). executePlanStep's terminal return is 'Chat'-shaped (see its doc comment).
             case 'Plan':
                 return await this.executePlanStep(params, previousDecision);
+            // Type assertion required because 'Tasks' is not part of the BaseAgentNextStep step
+            // union — LoopAgentType.DetermineNextStep() emits it when an opted-in agent submits a
+            // durable task graph. executeTasksStep detaches (see its doc comment).
+            case 'Tasks':
+                return await this.executeTasksStep(params, previousDecision);
             // Type assertion required because 'ClientTools' is not part of the BaseAgentNextStep
             // step union — LoopAgentType.DetermineNextStep() emits it when the LLM chooses client tools.
             case 'ClientTools':
@@ -8793,24 +8901,14 @@ The context is now within limits. Please retry your request with the recovered c
      * @param value - Value to set or append
      * @private
      */
+    /**
+     * Sets a value on a target object, honouring the `[]` array-append suffix.
+     *
+     * Delegates for the same reason as {@link getValueFromPath} — `results[]` must mean append in
+     * both engines, or a workflow accumulates in one and overwrites in the other.
+     */
     setMappedValue(target, key, value) {
-        const isArrayAppend = key.endsWith('[]');
-        const actualKey = isArrayAppend ? key.slice(0, -2) : key;
-        if (isArrayAppend) {
-            // Array append operation
-            if (!(actualKey in target)) {
-                target[actualKey] = [];
-            }
-            if (!Array.isArray(target[actualKey])) {
-                throw new Error(`Cannot append to '${actualKey}': target is not an array. ` +
-                    `Use '${actualKey}' without [] suffix for property update.`);
-            }
-            target[actualKey].push(value);
-        }
-        else {
-            // Normal property assignment
-            target[actualKey] = value;
-        }
+        SetMappedValue(target, key, value);
     }
     /**
      * Applies sub-agent input mapping to prepare initial payload for related sub-agent.
@@ -9731,6 +9829,131 @@ The context is now within limits. Please retry your request with the recovered c
      *
      * @protected
      */
+    /**
+     * Submits a durable task graph and ends the turn (submit-and-detach).
+     *
+     * **Why detaching is the whole point.** The alternative — holding the run open until the graph
+     * finishes — is exactly what the old client-driven path did, and it is what made a page reload
+     * lose the work, a server restart orphan it, and every non-Explorer channel unable to reach it
+     * at all. Once submission returns, the graph lives in Task rows and a server-side dispatcher
+     * owns it; the run has no reason to stay alive, so it doesn't.
+     *
+     * **The run step is written whether or not submission succeeds.** A rejected graph is the case
+     * where forensics matter most — the operator needs to see what the model emitted and why it was
+     * refused, and a step written only on the happy path would erase precisely that.
+     *
+     * **A missing submitter is reported, never swallowed.** In a host with no durable-execution
+     * package loaded there is nobody to run the graph. Returning a failure the model can read is
+     * the honest outcome; silently continuing would leave the agent believing it had scheduled work
+     * that does not exist.
+     *
+     * @protected
+     */
+    async executeTasksStep(params, previousDecision) {
+        const graph = previousDecision.taskGraph;
+        const spec = graph?.spec;
+        if (!spec) {
+            return {
+                step: 'Failed',
+                terminate: true,
+                errorMessage: 'A Tasks step reached execution with no task graph attached.',
+                previousPayload: previousDecision.previousPayload,
+                newPayload: previousDecision.newPayload || previousDecision.previousPayload
+            };
+        }
+        const stepEntity = await this.createStepEntity({
+            stepType: 'TaskGraph',
+            stepName: `Task Graph: ${spec.workflowName}`,
+            contextUser: params.contextUser,
+            inputData: { spec, folded: false }
+        });
+        const submitter = GetTaskGraphSubmitter();
+        if (!submitter) {
+            const errorMessage = 'No task-graph submitter is registered on this host, so the graph could not be made durable. ' +
+                'Task graphs require the durable-execution package to be loaded.';
+            await this.finalizeStepEntity(stepEntity, false, errorMessage, { spec, submitted: false });
+            return {
+                step: 'Failed',
+                terminate: true,
+                errorMessage,
+                previousPayload: previousDecision.previousPayload,
+                newPayload: previousDecision.newPayload || previousDecision.previousPayload
+            };
+        }
+        const outcome = await submitter.Submit({
+            Spec: spec,
+            EnvironmentID: MJEnvironmentEntityExtended.DefaultEnvironmentID,
+            ConversationDetailID: params.conversationDetailId ?? null,
+            AgentRunID: this._agentRun?.ID ?? null,
+            // If THIS run was itself started by a finished graph, the graph it emits inherits that
+            // depth + 1. Without this the chain restarts at zero on every hop and
+            // MAX_REINVOKE_DEPTH never fires — a graph reinvoking an agent that emits a graph would
+            // run forever.
+            ReinvokeDepth: this._agentRun?.ContinuationDepth ?? 0,
+            ContextUser: params.contextUser,
+            Provider: this.ProviderToUse
+        });
+        await this.finalizeStepEntity(stepEntity, outcome.Success, outcome.ErrorMessage, { spec, submitted: outcome.Success, parentTaskID: outcome.ParentTaskID });
+        if (!outcome.Success) {
+            return {
+                step: 'Failed',
+                terminate: true,
+                errorMessage: outcome.ErrorMessage || 'Task graph submission failed.',
+                previousPayload: previousDecision.previousPayload,
+                newPayload: previousDecision.newPayload || previousDecision.previousPayload
+            };
+        }
+        // Success means "this graph is durable and will run", NOT "this graph has run". Saying
+        // otherwise here is the exact lie the old await-everything path told when it returned early.
+        //
+        // The run PARKS on it rather than completing — see `_awaitingWorkflowTaskID`. Recorded only
+        // on a successful submission with a real parent task: a failed submission has nothing to
+        // wait for, and a graph nobody can point at could never be settled by the dispatcher, which
+        // would leave the run parked forever.
+        if (outcome.ParentTaskID) {
+            this._awaitingWorkflowTaskID = outcome.ParentTaskID;
+        }
+        return {
+            step: 'Success',
+            terminate: true,
+            message: previousDecision.message ||
+                `Started **${spec.workflowName}** — ${spec.tasks.length} task(s) running. ` +
+                    `I'll follow up when it finishes.`,
+            reasoning: previousDecision.reasoning,
+            confidence: previousDecision.confidence,
+            previousPayload: previousDecision.previousPayload,
+            newPayload: previousDecision.newPayload || previousDecision.previousPayload
+        };
+    }
+    /**
+     * Records a constant-folded task graph (D9) without submitting it.
+     *
+     * Folding rewrites a one-node graph into an ordinary in-run sub-agent call, which means no Task
+     * row and no dispatcher hop. Writing the step anyway is what keeps that decision legible: run
+     * forensics show why a graph did not reach the dispatcher, a user who edits a two-node graph
+     * down to one can read the durability change off the run record instead of inferring it, and
+     * Save as Workflow (D17) can attach to the recorded spec — so the single-node case, the shape
+     * most likely worth promoting, is promotable like any other.
+     *
+     * @protected
+     */
+    async recordFoldedTaskGraph(params, nextStep) {
+        const graph = nextStep.taskGraph;
+        if (!graph?.folded)
+            return;
+        const stepEntity = await this.createStepEntity({
+            stepType: 'TaskGraph',
+            stepName: `Task Graph (folded): ${graph.spec.workflowName}`,
+            contextUser: params.contextUser,
+            inputData: { spec: graph.spec, folded: true, foldReason: graph.foldReason }
+        });
+        await this.finalizeStepEntity(stepEntity, true, undefined, {
+            spec: graph.spec,
+            folded: true,
+            foldReason: graph.foldReason,
+            submitted: false
+        });
+    }
     async executePlanStep(params, previousDecision) {
         const planText = previousDecision.planDetails?.plan ?? '';
         const stepEntity = await this.createStepEntity({
@@ -10812,7 +11035,15 @@ The context is now within limits. Please retry your request with the recovered c
             ? this.resolveMediaPlaceholdersInPayload(finalStep.actionableCommands)
             : finalStep.actionableCommands;
         if (this._agentRun) {
-            this._agentRun.CompletedAt = new Date();
+            // A run waiting on a workflow has NOT completed, so it gets no completion time. The
+            // dispatcher stamps this when the graph settles; until then the absence is the honest
+            // record, and a duration computed from it would be the 441ms it took to hand the work
+            // off rather than the time the work took.
+            const parkedOnWorkflow = !!this._awaitingWorkflowTaskID
+                && (finalStep.step === 'Success' || finalStep.step === 'Chat');
+            if (!parkedOnWorkflow) {
+                this._agentRun.CompletedAt = new Date();
+            }
             this._agentRun.Success = finalStep.step === 'Success' || finalStep.step === 'Chat';
             if (!this._agentRun.Success) {
                 // Capture error message from either errorMessage or message field
@@ -10826,6 +11057,17 @@ The context is now within limits. Please retry your request with the recovered c
                 // set status to Failed
                 this._agentRun.Status = 'Failed';
             }
+            else if (parkedOnWorkflow) {
+                // Waiting on a task graph the dispatcher is still executing. `Paused` rather than a
+                // new status because it already exists on the entity AND the conversation's process
+                // panel already reads it as in-progress (`Status === 'Running' || === 'Paused'`), so
+                // a parked run presents correctly with no UI change.
+                //
+                // `Success` stays true: the turn genuinely succeeded at what it was asked to do —
+                // start the workflow. Whether the WORKFLOW succeeded is a different question, and
+                // the dispatcher answers it here when the graph settles.
+                this._agentRun.Status = 'Paused';
+            }
             else if (finalStep.step === 'Chat') {
                 // Chat steps mean the agent is waiting for human input
                 this._agentRun.Status = 'AwaitingFeedback';
@@ -11797,43 +12039,16 @@ The context is now within limits. Please retry your request with the recovered c
         });
     }
     /**
-     * Helper to get value from nested object path - extracts from LoopAgentType
+     * Reads a value out of a nested object by dotted path, with `name[0]` array indexing.
+     *
+     * **Delegates to the one implementation.** This used to be a private copy of the same walk the
+     * task-graph dispatcher performs, and the two had to agree exactly: a Loop agent and the
+     * compiled graph of the same workflow read the SAME authored mapping strings, so any divergence
+     * would make a workflow behave differently depending on which engine ran it — silently, and only
+     * for the paths where they differed.
      */
     getValueFromPath(obj, path) {
-        const parts = path.split('.');
-        let current = obj;
-        for (const part of parts) {
-            if (!part)
-                continue;
-            // Check for array indexing
-            const arrayMatch = part.match(/^([^[]+)\[(\d+)\]$/);
-            if (arrayMatch) {
-                const arrayName = arrayMatch[1];
-                const index = parseInt(arrayMatch[2], 10);
-                if (current && typeof current === 'object' && arrayName in current) {
-                    current = current[arrayName];
-                    if (Array.isArray(current) && index >= 0 && index < current.length) {
-                        current = current[index];
-                    }
-                    else {
-                        return undefined;
-                    }
-                }
-                else {
-                    return undefined;
-                }
-            }
-            else {
-                // Regular property access
-                if (current && typeof current === 'object' && part in current) {
-                    current = current[part];
-                }
-                else {
-                    return undefined;
-                }
-            }
-        }
-        return current;
+        return GetValueFromPath(obj, path);
     }
     /**
      * Parse the agent's SecondaryScopeConfig from the ScopeConfig field.