@memberjunction/ai-agents 6.2.0-edge.1 → 6.2.0-edge.3

package/dist/agent-types/flow-agent-type.js

@@ -17,9 +17,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { RegisterClass, SafeExpressionEvaluator, UUIDsEqual } from '@memberjunction/global';
-import { SelectOutgoingEdges } from '@memberjunction/ai-core-plus';
+import { CollectDecisionStepKeys, DecisionHoldReason, DecisionReferencesIn, NO_DECISIONS, ReadFlowDecisionStepConfiguration, ResolveDecisionState, ResolveDecisionStepAnswers, SelectOutgoingEdges, ValidateTaskGraphSpec, } from '@memberjunction/ai-core-plus';
 import { AIEngineGraphRepository, SafeConditionEvaluator } from './flow-graph-adapters.js';
-import { CompileFlowAgentToTaskGraph, FormatFlowCompileErrors } from './flow-graph-executor.js';
+import { CompileFlowAgentToTaskGraph, FormatFlowCompileErrors, FormatFlowValidationErrors } from './flow-graph-executor.js';
 import { BaseAgentType } from './base-agent-type.js';
 import { LogError, LogStatus, LogStatusEx, IsVerboseLoggingEnabled } from '@memberjunction/core';
 import { AIEngine } from '@memberjunction/aiengine';
@@ -46,9 +46,38 @@ export class FlowExecutionState {
          * later hook, so a run never switches engines part-way through.
          */
         this.executionMode = 'dispatch'; // case-violation-ok-legacy-back-compat: object literals are assigned to this class, so an accessor stub changes what they must supply
+        /**
+         * What this run's Decision steps have answered, keyed by each step's `key` and then by question.
+         *
+         * `Answers` holds the answers a path condition may act on, and is what the `decisions` root
+         * reads. `Unresolved` says why each of the rest is not usable (the call failed, the answer fell
+         * below its question's `minConfidence`, or the step was skipped), and a condition that reads one
+         * of them holds. Never written into the payload.
+         */
+        this.Decisions = NO_DECISIONS;
+        /**
+         * The keys of the Decision steps whose call failed in this run.
+         *
+         * A walker cannot retry, so such a decision never answers in this run, and a path reading it can
+         * never be taken: it is passed over, and a recovery path ranked below it can be. An answer below
+         * its `minConfidence` is different — the path might have been the one to take — and holds.
+         */
+        this.FailedDecisionKeys = new Set();
         this.agentId = agentId;
     }
 }
+/** A run's decisions with one Decision step's answers replacing whatever that step gave before. */
+function withDecisionStep(decisions, config, resolved) {
+    const answers = { ...decisions.Answers };
+    const unresolved = { ...decisions.Unresolved };
+    delete answers[config.key];
+    delete unresolved[config.key];
+    if (Object.keys(resolved.Answers).length > 0)
+        answers[config.key] = resolved.Answers;
+    if (Object.keys(resolved.Unresolved).length > 0)
+        unresolved[config.key] = resolved.Unresolved;
+    return { Answers: answers, Unresolved: unresolved };
+}
 /**
  * Implementation of the Flow Agent Type pattern.
  *
@@ -199,7 +228,11 @@ let FlowAgentType = class FlowAgentType extends BaseAgentType {
             }
             // Find valid paths from current step
             // Pass params to enable data/context access in path conditions (Phase 1)
-            const paths = await this.getValidPaths(flowState.currentStepId, payload, flowState, params);
+            const selection = await this.getValidPaths(flowState.currentStepId, payload, flowState, params);
+            if (selection.HoldReason) {
+                return this.stopOnHeldPath(flowState.currentStepId, selection.HoldReason, payload);
+            }
+            const paths = selection.Paths;
             if (paths.length === 0) {
                 // No valid paths - flow is complete
                 return this.createSuccessStep({
@@ -300,6 +333,7 @@ let FlowAgentType = class FlowAgentType extends BaseAgentType {
      * - flowContext: Flow execution metadata (current step, completed steps, path)
      * - data: Transient template data from ExecuteAgentParams (NEW in Phase 1)
      * - context: Runtime context from ExecuteAgentParams (NEW in Phase 1)
+     * - decisions: The usable answers of the run's Decision steps, by key (`decisions.<key>.<question>`)
      *
      * This allows path conditions to access runtime parameters like:
      * - `data.userApproval === true`
@@ -324,21 +358,69 @@ let FlowAgentType = class FlowAgentType extends BaseAgentType {
      */
     async getValidPaths(stepId, payload, flowState, params) {
         const repo = new AIEngineGraphRepository(flowState.agentId);
-        const selection = SelectOutgoingEdges(stepId, repo, this._conditionEvaluator, this.buildConditionContext(payload, flowState, params));
+        // The Decision hold runs BEFORE any condition is evaluated, on every step's paths: a later
+        // step's condition can read an earlier Decision step's answer. A condition reading an answer
+        // that is not usable is never evaluated, because `undefined === 'billing'` is a confident,
+        // wrong `false`.
+        const selection = SelectOutgoingEdges(stepId, repo, this._conditionEvaluator, this.buildConditionContext(payload, flowState, params), (condition) => this.decisionHold(condition, flowState));
         for (const rejection of selection.Rejected) {
             // ConditionFalse is the normal case and stays quiet. The other three are all "this graph
             // is not shaped the way its author thinks", and each previously vanished: a broken
             // expression was logged as if it were a false one, and a dangling edge failed the run
             // with a message that named the missing ID but not the edge that pointed at it.
-            if (rejection.Reason === 'ConditionFalse')
+            // ConditionHeld is quiet too: one that outranks the choice stops the run with its reason,
+            // and one ranked below the choice could not have won.
+            if (rejection.Reason === 'ConditionFalse' || rejection.Reason === 'ConditionHeld')
                 continue;
             LogError(`Flow path ${rejection.EdgeId} from step ${stepId} not followed (${rejection.Reason})` +
                 `${rejection.Detail ? `: ${rejection.Detail}` : ''}`);
         }
         const byId = new Map(AIEngine.Instance.GetPathsFromStep(stepId).map(p => [p.ID, p]));
-        return selection.Edges
-            .map(e => byId.get(e.id))
-            .filter((p) => !!p);
+        return {
+            Paths: selection.Edges
+                .map(e => byId.get(e.id))
+                .filter((p) => !!p),
+            HoldReason: selection.Held?.Detail ?? null
+        };
+    }
+    /**
+     * Why a path condition must not be evaluated, because of a decision it reads, or `null`.
+     *
+     * A condition reading a decision whose call failed is UNANSWERABLE in this run: a walker has no
+     * retry, so the path can never be taken, and a recovery path ranked below it is taken instead.
+     * Any other unusable answer — below its `minConfidence`, or not given — holds, because the path
+     * might have been the one to take.
+     */
+    decisionHold(condition, flowState) {
+        const reason = DecisionHoldReason(condition, flowState.Decisions);
+        if (!reason)
+            return null;
+        const failed = DecisionReferencesIn(condition).References.find(r => flowState.FailedDecisionKeys.has(r.NodeId));
+        if (!failed)
+            return { Detail: reason };
+        const unresolved = flowState.Decisions.Unresolved[failed.NodeId];
+        return { Detail: unresolved?.[failed.QuestionKey] ?? reason, Unanswerable: true };
+    }
+    /**
+     * Stops the run because a step cannot choose its next step without guessing.
+     *
+     * A path ranked at or above every followable one reads a decision that is not usable, so it
+     * might have been the one to take. The dispatcher holds such a fork; a walker cannot wait, so it
+     * fails the run with the reason instead, and never takes a lower-ranked path in its place.
+     */
+    stopOnHeldPath(stepId, holdReason, payload) {
+        const stepName = AIEngine.Instance.GetAgentStepByID(stepId)?.Name ?? stepId;
+        return this.stopFlow(`Step "${stepName}" cannot choose its next step: a path from it that ranks at or above the ` +
+            `others reads a decision that is not usable, because ${holdReason}. The flow stops rather than guess.`, payload);
+    }
+    /** A failed step that ends the run: no recovery path is taken after it. */
+    stopFlow(errorMessage, payload) {
+        return this.createNextStep('Failed', {
+            errorMessage,
+            terminate: true,
+            newPayload: payload,
+            previousPayload: payload
+        });
     }
     /**
      * The variables a path condition can reference.
@@ -361,7 +443,9 @@ let FlowAgentType = class FlowAgentType extends BaseAgentType {
                 stepCount: flowState.completedStepIds.size
             },
             data: params.data || {},
-            context: params.context || {}
+            context: params.context || {},
+            // Only the usable answers. A condition reading any other one holds before it is evaluated.
+            decisions: flowState.Decisions.Answers
         };
     }
     /**
@@ -518,8 +602,16 @@ let FlowAgentType = class FlowAgentType extends BaseAgentType {
             flowState.executionPath.push(node.ID);
             // Store a skip marker as the step result
             flowState.stepResults.set(node.ID, { skipped: true, stepName: node.Name });
+            // A skipped Decision step answered nothing, so every condition that reads it holds.
+            if (node.StepType === 'Decision') {
+                this.recordDecisionOutcome(flowState, node, { Status: 'Skipped' });
+            }
             // Find the next step by evaluating paths from this skipped step
-            const paths = await this.getValidPaths(node.ID, payload, flowState, params);
+            const selection = await this.getValidPaths(node.ID, payload, flowState, params);
+            if (selection.HoldReason) {
+                return this.stopOnHeldPath(node.ID, selection.HoldReason, payload);
+            }
+            const paths = selection.Paths;
             if (paths.length === 0) {
                 // No more paths - flow is complete
                 return this.createSuccessStep({
@@ -634,6 +726,8 @@ let FlowAgentType = class FlowAgentType extends BaseAgentType {
                 return await this.convertForEachStepToOperation(node, payload, flowState, params);
             case 'While':
                 return await this.convertWhileStepToOperation(node, payload, flowState, params);
+            case 'Decision':
+                return this.createDecisionStep(node, payload);
             default:
                 return this.createNextStep('Failed', {
                     errorMessage: `Unknown step type: ${node.StepType}`,
@@ -660,6 +754,120 @@ let FlowAgentType = class FlowAgentType extends BaseAgentType {
         const agent = AIEngine.Instance.Agents.find(a => UUIDsEqual(a.ID, agentId));
         return agent?.Name || null;
     }
+    /**
+     * Turns a Decision step into the `'Decision'` next step BaseAgent runs.
+     *
+     * The same hand-off a Prompt step makes with its marker: the walker does not call a model
+     * itself. BaseAgent runs the request through its own decision execution, so the call gets the
+     * prompt default, state resolution and error handling every agent decision gets, and is logged
+     * as a `Decision` run step. The answers come back to {@link completeDecisionStep}.
+     *
+     * A configuration that cannot be read, or a prompt that no longer exists, ends the run: the
+     * dispatched path refuses the same flow before it starts.
+     *
+     * A state the dispatched path refuses — missing, or empty, `{}` and whitespace-only text
+     * included — is refused here by the same rule (`ResolveDecisionState`), before any model is
+     * asked. The step then fails as a failed call does, so its recovery path runs.
+     */
+    createDecisionStep(node, payload) {
+        const read = ReadFlowDecisionStepConfiguration(node.Configuration);
+        if ('Error' in read) {
+            return this.stopFlow(`Decision step "${node.Name}" cannot run: ${read.Error}.`, payload);
+        }
+        const promptName = this.decisionPromptName(node);
+        if (promptName === null) {
+            return this.stopFlow(`Decision step "${node.Name}" refers to a prompt that no longer exists (${node.PromptID}). ` +
+                `Point it at an existing one, or clear it to use the Default Decision prompt.`, payload);
+        }
+        const { key, state, questions } = read.Config;
+        const resolved = ResolveDecisionState(state, payload);
+        if ('ErrorMessage' in resolved) {
+            return this.decisionNotAsked(key, resolved.ErrorMessage, payload);
+        }
+        return this.createNextStep('Decision', {
+            decisions: [{ id: key, state: state ?? 'payload', questions }],
+            ...(promptName ? { decisionPromptName: promptName } : {}),
+            newPayload: payload,
+            previousPayload: payload
+        });
+    }
+    /**
+     * A Decision step that is not asked, handed back the way BaseAgent hands back a failed call: a
+     * `'Retry'` carrying one failed result. {@link completeDecisionStep} then fails the step, so a
+     * condition reading its answers holds or is passed over, and its recovery path is taken, as
+     * after any failed call. No model is asked and no Decision run step is logged; the dispatched
+     * path logs none for a step it does not ask either.
+     */
+    decisionNotAsked(key, reason, payload) {
+        return this.createNextStep('Retry', {
+            decisionResults: [{ id: key, success: false, error: `it was not asked: ${reason}` }],
+            newPayload: payload,
+            previousPayload: payload
+        });
+    }
+    /**
+     * A Decision step's prompt by name: `undefined` when it has none (BaseAgent then uses
+     * `Default Decision`), `null` when the prompt it names is gone.
+     */
+    decisionPromptName(node) {
+        if (!node.PromptID)
+            return undefined;
+        return AIEngine.Instance.Prompts.find(p => UUIDsEqual(p.ID, node.PromptID))?.Name ?? null;
+    }
+    /**
+     * Records what the current Decision step answered, and turns BaseAgent's `'Retry'` into the
+     * step's outcome.
+     *
+     * A call that succeeded makes the step `'Success'`; one that failed makes it `'Failed'`, so a
+     * failed decision takes the same recovery handling as any failed step: the paths that read its
+     * answers are passed over, and a recovery path is taken whatever its rank.
+     *
+     * @param payload the payload the step hands on, which is its `stepResult.result`
+     */
+    completeDecisionStep(step, flowState, payload) {
+        const node = flowState.currentStepId ? AIEngine.Instance.GetAgentStepByID(flowState.currentStepId) : null;
+        const result = step.decisionResults?.[0];
+        const answers = result?.success && result.answers && !Array.isArray(result.answers) ? result.answers : null;
+        const outcome = answers
+            ? { Status: 'Complete', Answers: answers }
+            : { Status: 'Failed', ErrorMessage: result?.error || 'the decision returned no answers' };
+        if (node)
+            this.recordDecisionOutcome(flowState, node, outcome);
+        if (outcome.Status === 'Complete') {
+            return {
+                Next: { ...step, step: 'Success' },
+                StepResult: { Success: true, step: 'Success', result: payload }
+            };
+        }
+        const errorMessage = `Decision step "${node?.Name ?? flowState.currentStepId}" failed: ${outcome.ErrorMessage}`;
+        return {
+            Next: { ...step, step: 'Failed', errorMessage },
+            StepResult: { Success: false, step: 'Failed', result: payload }
+        };
+    }
+    /**
+     * Puts a Decision step's answers into the flow state under its key, replacing any it gave on an
+     * earlier visit. The shared answer rules decide which are usable and say why the rest are not.
+     */
+    recordDecisionOutcome(flowState, node, outcome) {
+        const read = ReadFlowDecisionStepConfiguration(node.Configuration);
+        // A step whose settings cannot be read has no key, so nothing can name it: a condition that
+        // tries still holds, on "no Decision step has answered".
+        if ('Error' in read)
+            return;
+        const run = {
+            Name: node.Name,
+            Status: outcome.Status,
+            ErrorMessage: outcome.Status === 'Failed' ? outcome.ErrorMessage : null
+        };
+        const given = outcome.Status === 'Complete' ? outcome.Answers : {};
+        const resolved = ResolveDecisionStepAnswers(run, read.Config.questions, given);
+        flowState.Decisions = withDecisionStep(flowState.Decisions, read.Config, resolved);
+        if (outcome.Status === 'Failed')
+            flowState.FailedDecisionKeys.add(read.Config.key);
+        else
+            flowState.FailedDecisionKeys.delete(read.Config.key);
+    }
     /**
      * Processes action results and applies output mapping if configured
      * This should be called by BaseAgent after action execution
@@ -1036,24 +1244,44 @@ let FlowAgentType = class FlowAgentType extends BaseAgentType {
                     `workflow from its starting step, or split it so the portion you want is its own workflow.`
             });
         }
-        const compiled = CompileFlowAgentToTaskGraph(params.agent.ID, params.agent.Name, params.agent.Description ?? undefined);
-        if (!compiled.Success || !compiled.Spec) {
-            return this.createNextStep('Failed', {
-                errorMessage: `Workflow '${params.agent.Name}' could not be prepared to run:\n${FormatFlowCompileErrors(compiled)}`
-            });
+        const prepared = this.compileAndValidateFlow(params);
+        if ('ErrorMessage' in prepared) {
+            return this.createNextStep('Failed', { errorMessage: prepared.ErrorMessage });
         }
-        this.logCompiledGraph(params.agent.Name, compiled.Spec.tasks.length, compiled.Excluded);
+        this.logCompiledGraph(params.agent.Name, prepared.Spec.tasks.length, prepared.Excluded);
         // 'Tasks' is not in the BaseAgentNextStep step union — it is non-terminal in the same sense
         // as 'ClientTools'/'Plan' (see that type's doc comment), and BaseAgent routes it to
         // executeTasksStep, whose terminal step is 'Success'.
         return {
             step: 'Tasks',
             terminate: false,
-            taskGraph: { spec: compiled.Spec, folded: false },
+            taskGraph: { spec: prepared.Spec, folded: false },
             previousPayload: payload,
             newPayload: payload
         };
     }
+    /**
+     * Compiles the flow and holds it to the checks `Submit` makes, or says why it cannot run.
+     *
+     * The dispatched path runs this before it submits, and the in-run walker before its first step
+     * when the flow has a Decision step, so a flow one mode accepts the other cannot refuse — an
+     * incomplete Choice fork, a decision read before it can answer, or one read through the payload
+     * is refused in both. The refusal names the author's steps: a compiled graph's tempIds are step
+     * IDs, and an incomplete fork, for one, is reported by its group, which is its origin's ID.
+     */
+    compileAndValidateFlow(params) {
+        const compiled = CompileFlowAgentToTaskGraph(params.agent.ID, params.agent.Name, params.agent.Description ?? undefined);
+        if (!compiled.Success || !compiled.Spec) {
+            return { ErrorMessage: `Workflow '${params.agent.Name}' could not be prepared to run:\n${FormatFlowCompileErrors(compiled)}` };
+        }
+        const validation = ValidateTaskGraphSpec(compiled.Spec);
+        if (!validation.Valid) {
+            return {
+                ErrorMessage: `Workflow '${params.agent.Name}' could not be prepared to run:\n${FormatFlowValidationErrors(validation.Errors, compiled.Spec)}`
+            };
+        }
+        return { Spec: compiled.Spec, Excluded: compiled.Excluded };
+    }
     /**
      * Logs what the compile produced.
      *
@@ -1084,6 +1312,25 @@ let FlowAgentType = class FlowAgentType extends BaseAgentType {
     async determineInitialStepInRun(params, payload, agentTypeState) {
         const flowState = agentTypeState;
         const payloadToUse = payload || {};
+        // The compiler's own key check, over every active step: the walker can start anywhere
+        // (startAtStep), so it cannot limit itself to what the entry reaches. A shared key would
+        // leave a condition's `decisions.<key>` naming two steps, and the dispatched path refuses
+        // the same flow before it starts.
+        const activeSteps = AIEngine.Instance.GetAgentSteps(flowState.agentId, 'Active') ?? [];
+        const duplicateKeys = CollectDecisionStepKeys(activeSteps).Errors;
+        if (duplicateKeys.length > 0) {
+            return this.stopFlow(`Workflow '${params.agent.Name}' cannot run:\n${FormatFlowCompileErrors({ Success: false, Errors: duplicateKeys, Excluded: [] })}`, payloadToUse);
+        }
+        // A flow with a Decision step gets the dispatched path's whole check, once, before its first
+        // step: an incomplete Choice fork ends the flow "successfully" on the option nobody drew a
+        // path for, and in-run is the default mode for every sub-agent flow. So such a flow must be
+        // one the dispatcher would accept — which also rules out a loop drawn with a path back. A
+        // flow without a Decision step is walked as it always was.
+        if (activeSteps.some(s => s.StepType === 'Decision')) {
+            const prepared = this.compileAndValidateFlow(params);
+            if ('ErrorMessage' in prepared)
+                return this.stopFlow(prepared.ErrorMessage, payloadToUse);
+        }
         // Check for startAtStep in agentTypeParams (FlowAgentExecuteParams)
         const flowParams = params.agentTypeParams;
         if (flowParams?.startAtStep) {
@@ -1171,9 +1418,14 @@ let FlowAgentType = class FlowAgentType extends BaseAgentType {
                 previousPayload: currentPayload
             });
         }
+        // A Decision step's answers come back on the 'Retry' BaseAgent returns after running it. They
+        // are recorded first, so this step's paths, and every later step's, can read them. From here
+        // on the step is its outcome: Success, or Failed when the call failed.
+        const decision = step.decisionResults ? this.completeDecisionStep(step, flowState, currentPayload) : null;
+        const finished = decision?.Next ?? step;
         // Store the step result so path conditions can access it via stepResult
         // The step parameter contains the result from the just-completed step (Sub-Agent, Action, or Prompt)
-        flowState.stepResults.set(flowState.currentStepId, step);
+        flowState.stepResults.set(flowState.currentStepId, decision ? decision.StepResult : step);
         // Add to execution path if not already present
         if (!flowState.executionPath.includes(flowState.currentStepId)) {
             flowState.executionPath.push(flowState.currentStepId);
@@ -1182,17 +1434,21 @@ let FlowAgentType = class FlowAgentType extends BaseAgentType {
         flowState.completedStepIds.add(flowState.currentStepId);
         // Find valid paths from current step using updated payload
         // Pass params to enable data/context access in path conditions (Phase 1)
-        const paths = await this.getValidPaths(flowState.currentStepId, currentPayload, flowState, params);
+        const selection = await this.getValidPaths(flowState.currentStepId, currentPayload, flowState, params);
+        if (selection.HoldReason) {
+            return this.stopOnHeldPath(flowState.currentStepId, selection.HoldReason, currentPayload);
+        }
+        const paths = selection.Paths;
         if (paths.length === 0) {
             // No valid paths found
             // If the previous step failed, propagate the failure with its error message
-            if (step.step === 'Failed') {
+            if (finished.step === 'Failed') {
                 LogStatusEx({
-                    message: `⚠️ Flow Agent: Step failed with no recovery path. Error: ${step.errorMessage || 'No error message'}`,
+                    message: `⚠️ Flow Agent: Step failed with no recovery path. Error: ${finished.errorMessage || 'No error message'}`,
                     verboseOnly: false
                 });
                 return this.createNextStep('Failed', {
-                    errorMessage: step.errorMessage || 'Flow step failed with no recovery path',
+                    errorMessage: finished.errorMessage || 'Flow step failed with no recovery path',
                     newPayload: currentPayload,
                     previousPayload: currentPayload,
                     terminate: true
@@ -1221,7 +1477,7 @@ let FlowAgentType = class FlowAgentType extends BaseAgentType {
             });
         }
         // Log when we're navigating to a recovery path after a failure
-        if (step.step === 'Failed') {
+        if (finished.step === 'Failed') {
             LogStatusEx({
                 message: `🔄 Flow Agent: Failure detected, navigating to recovery path: '${nextStep.Name}'`,
                 verboseOnly: false
@@ -1233,7 +1489,7 @@ let FlowAgentType = class FlowAgentType extends BaseAgentType {
             for (let i = 1; i < paths.length; i++) {
                 const alternateStep = await this.getStepById(paths[i].DestinationStepID);
                 if (alternateStep && alternateStep.Status === 'Active') {
-                    if (step.step === 'Failed') {
+                    if (finished.step === 'Failed') {
                         LogStatusEx({
                             message: `🔄 Flow Agent: Using alternate recovery path: '${alternateStep.Name}'`,
                             verboseOnly: false
@@ -1468,6 +1724,7 @@ let FlowAgentType = class FlowAgentType extends BaseAgentType {
      */
     GetPromptConfigurationGuidance() {
         return `   - Flow agents use step-level prompts (StepType="Prompt" with PromptID)\n` +
+            `   - Decision steps (StepType="Decision") use PromptID for their decision prompt; empty means "Default Decision"\n` +
             `   - Prompts should be configured in agent steps, not AI Agent Prompts relationship\n` +
             `   - Verify that prompts exist in AI Prompts table and are active`;
     }