@memberjunction/ai-agent-manager 6.2.0-edge.0 → 6.2.0-edge.2

package/src/agents/architect-agent.ts

@@ -1,9 +1,16 @@
 import { BaseAgent, PayloadManager } from '@memberjunction/ai-agents';
-import { ExecuteAgentParams, BaseAgentNextStep, AgentSpec, MJAIAgentRunEntityExtended, MJAIAgentRunStepEntityExtended } from '@memberjunction/ai-core-plus';
+import { ExecuteAgentParams, BaseAgentNextStep, AgentSpec, AgentStep, MJAIAgentRunEntityExtended, MJAIAgentRunStepEntityExtended } from '@memberjunction/ai-core-plus';
 import { MJActionEntity } from "@memberjunction/core-entities";
 import { RunView } from '@memberjunction/core';
-import { RegisterClass, NormalizeUUID } from '@memberjunction/global';
-import { IsLoopStep, ValidateLoopStep } from '../flow-step-validation';
+import { RegisterClass, NormalizeUUID, UUIDsEqual } from '@memberjunction/global';
+import { AIEngine } from '@memberjunction/aiengine';
+import { ValidateLoopStep, ValidateFlowGraph } from '../flow-step-validation';
+
+/**
+ * The model type a Decision step's prompt runs on: the name of an `MJ: AI Model Types` row, and what
+ * the decision runner requires (`AIDecisionRunner.RequiredModelType`).
+ */
+const DECISION_MODEL_TYPE = 'Decision';
 
 /**
  * Architect Agent - Transforms technical design into validated AgentSpec JSON
@@ -161,8 +168,9 @@ export class AgentArchitectAgent extends BaseAgent {
         }
 
         // 5. Validate agent type-specific requirements
-        const isLoopAgent = specWithType.TypeID?.includes('Loop');
-        const isFlowAgent = specWithType.TypeID?.includes('Flow');
+        const typeName = this.agentTypeName(specWithType.TypeID);
+        const isLoopAgent = typeName.includes('Loop');
+        const isFlowAgent = typeName.includes('Flow');
 
         if (isLoopAgent) {
             // Loop agents require at least one prompt
@@ -188,81 +196,7 @@ export class AgentArchitectAgent extends BaseAgent {
                 }
             }
 
-            // Validate that at least one step is marked as StartingStep
-            if (correctedSpec.Steps && correctedSpec.Steps.length > 0) {
-                const hasStartingStep = correctedSpec.Steps.some(step => step.StartingStep === true);
-                if (!hasStartingStep) {
-                    errors.push('❌ Flow agents require at least ONE step with StartingStep: true');
-                }
-
-                // Validate each step based on its type
-                for (let i = 0; i < correctedSpec.Steps.length; i++) {
-                    const step = correctedSpec.Steps[i];
-
-                    // Validate Action steps
-                    if (step.StepType === 'Action') {
-                        if (!step.ActionID) {
-                            errors.push(`❌ Action step "${step.Name}" (index ${i}) must have ActionID field`);
-                        }
-
-                        // Validate ActionInputMapping if provided (supports both string and object)
-                        if (step.ActionInputMapping) {
-                            try {
-                                if (typeof step.ActionInputMapping === 'string') {
-                                    JSON.parse(step.ActionInputMapping);
-                                }
-                                // else it's already an object, which is valid and will be stringified later
-                            } catch (e: any) {
-                                errors.push(`❌ Step "${step.Name}" (index ${i}) has invalid ActionInputMapping JSON: ${e?.message || String(e)}`);
-                            }
-                        }
-
-                        // Validate ActionOutputMapping if provided (supports both string and object)
-                        if (step.ActionOutputMapping) {
-                            try {
-                                if (typeof step.ActionOutputMapping === 'string') {
-                                    JSON.parse(step.ActionOutputMapping);
-                                }
-                                // else it's already an object, which is valid and will be stringified later
-                            } catch (e: any) {
-                                errors.push(`❌ Step "${step.Name}" (index ${i}) has invalid ActionOutputMapping JSON: ${e?.message || String(e)}`);
-                            }
-                        }
-                    }
-
-                    // Validate Prompt steps
-                    if (step.StepType === 'Prompt') {
-                        // If PromptID is empty or not provided, PromptText is required for inline creation
-                        if (!step.PromptID || step.PromptID === '') {
-                            if (!step.PromptText || step.PromptText.trim() === '') {
-                                errors.push(`❌ Prompt step "${step.Name}" (index ${i}) has empty PromptID but missing PromptText. For inline prompt creation, PromptText is required.`);
-                            }
-                            // PromptName and PromptDescription are recommended but not required
-                            if (!step.PromptName) {
-                                console.log(`⚠️ Warning: Prompt step "${step.Name}" (index ${i}) is missing PromptName (will default to "[Step Name] Prompt")`);
-                            }
-                        }
-                        // If PromptID is provided (existing prompt), other fields are optional
-                    }
-
-                    // Validate Sub-Agent steps
-                    if (step.StepType === 'Sub-Agent') {
-                        // SubAgentID can be empty "" for new sub-agents (will be linked by name matching)
-                        // No validation needed here - linking happens in AgentSpecSync
-                    }
-
-                    // Validate loop steps (ForEach / While)
-                    //
-                    // A loop is a wrapper, not a leaf: LoopBodyType names which of Action/Prompt/
-                    // Sub-Agent runs each pass, and Configuration carries the bounds. A loop missing
-                    // either is the failure mode worth catching here — it saves cleanly and then
-                    // iterates over nothing at runtime, which looks like the agent doing no work
-                    // rather than like a malformed step.
-                    if (IsLoopStep(step)) {
-                        errors.push(...ValidateLoopStep(step, i));
-                    }
-                }
-            }
+            errors.push(...this.validateFlowSteps(correctedSpec));
         }
 
         // 6. Validate optional but important fields
@@ -390,8 +324,9 @@ export class AgentArchitectAgent extends BaseAgent {
                     errors.push(`❌ Child SubAgent[${i}] "${subAgent.SubAgent.Name}" is missing TypeID field`);
                 } else {
                     // Validate Loop/Flow specific requirements for child sub-agents
-                    const isLoopSubAgent = subAgent.SubAgent.TypeID.includes('Loop');
-                    const isFlowSubAgent = subAgent.SubAgent.TypeID.includes('Flow');
+                    const subAgentTypeName = this.agentTypeName(subAgent.SubAgent.TypeID);
+                    const isLoopSubAgent = subAgentTypeName.includes('Loop');
+                    const isFlowSubAgent = subAgentTypeName.includes('Flow');
 
                     if (isLoopSubAgent) {
                         // Loop sub-agents require at least one prompt
@@ -410,6 +345,11 @@ export class AgentArchitectAgent extends BaseAgent {
                         if (!subAgent.SubAgent.Steps || subAgent.SubAgent.Steps.length === 0) {
                             errors.push(`❌ Flow SubAgent[${i}] "${subAgent.SubAgent.Name}" requires at least ONE step in Steps array`);
                         }
+
+                        // A Flow child runs its steps exactly as a Flow agent does, so they get the same checks.
+                        errors.push(...this.validateFlowSteps(subAgent.SubAgent).map(
+                            err => `Flow SubAgent[${i}] "${subAgent.SubAgent.Name}" -> ${err}`
+                        ));
                     }
                 }
             } else if (subAgent.Type === 'related') {
@@ -477,6 +417,103 @@ export class AgentArchitectAgent extends BaseAgent {
         return { errors, corrected };
     }
 
+    /**
+     * Every problem with a Flow agent's steps and paths: a starting step, each step on its own, and
+     * then the flow as the runtime compiles and validates it ({@link ValidateFlowGraph}). Used for the
+     * agent itself and for each Flow child sub-agent, which runs its steps the same way.
+     */
+    private validateFlowSteps(spec: Pick<AgentSpec, 'Name' | 'Steps' | 'Paths'>): string[] {
+        const steps = spec.Steps ?? [];
+        if (steps.length === 0) {
+            return [];
+        }
+        const stepErrors = steps.flatMap((step, i) => this.validateFlowStep(step, i));
+        if (!steps.some(step => step.StartingStep === true)) {
+            // The compiler would refuse the flow for this alone, so there is nothing more to learn from it.
+            return ['❌ Flow agents require at least ONE step with StartingStep: true', ...stepErrors];
+        }
+        return [...stepErrors, ...ValidateFlowGraph(steps, spec.Paths ?? [], spec.Name)];
+    }
+
+    /** The checks one step gets on its own, by type. */
+    private validateFlowStep(step: AgentStep, index: number): string[] {
+        switch (step.StepType) {
+            case 'Action':
+                return this.validateActionStep(step, index);
+            case 'Prompt':
+                return this.validatePromptStep(step, index);
+            case 'ForEach':
+            case 'While':
+                // A loop is a wrapper, not a leaf: LoopBodyType names which of Action/Prompt/Sub-Agent
+                // runs each pass, and Configuration carries the bounds. A loop missing either saves
+                // cleanly and then iterates over nothing, which looks like the agent doing no work
+                // rather than like a malformed step.
+                return ValidateLoopStep(step, index);
+            case 'Decision':
+                return this.validateDecisionPrompt(step, index);
+            default:
+                // A Sub-Agent step's SubAgentID may be empty for a sub-agent this spec creates.
+                return [];
+        }
+    }
+
+    /** An Action step needs its action, and any mapping written as text must be JSON. */
+    private validateActionStep(step: AgentStep, index: number): string[] {
+        const errors: string[] = [];
+        if (!step.ActionID) {
+            errors.push(`❌ Action step "${step.Name}" (index ${index}) must have ActionID field`);
+        }
+        for (const [field, mapping] of [['ActionInputMapping', step.ActionInputMapping], ['ActionOutputMapping', step.ActionOutputMapping]] as const) {
+            // An object is valid as it is, and is stringified when saved.
+            if (typeof mapping !== 'string' || !mapping) continue;
+            try {
+                JSON.parse(mapping);
+            } catch (e) {
+                errors.push(`❌ Step "${step.Name}" (index ${index}) has invalid ${field} JSON: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        return errors;
+    }
+
+    /** A Prompt step names an existing prompt, or writes one inline as PromptText for the Builder to create. */
+    private validatePromptStep(step: AgentStep, index: number): string[] {
+        if (step.PromptID) {
+            return [];
+        }
+        // PromptName and PromptDescription are recommended but not required
+        if (!step.PromptName) {
+            console.log(`⚠️ Warning: Prompt step "${step.Name}" (index ${index}) is missing PromptName (will default to "[Step Name] Prompt")`);
+        }
+        return step.PromptText?.trim()
+            ? []
+            : [`❌ Prompt step "${step.Name}" (index ${index}) has empty PromptID but missing PromptText. For inline prompt creation, PromptText is required.`];
+    }
+
+    /**
+     * A Decision step's `PromptID`, when it sets one, must be a prompt that can run a decision. Empty
+     * means the Default Decision prompt.
+     *
+     * The runtime runs the step's prompt on Decision-type models only, and refuses a prompt whose model
+     * type is set to anything else; it finds that out only when the step runs. A prompt with no model
+     * type takes the runner's, so it is not refused here.
+     */
+    private validateDecisionPrompt(step: AgentStep, index: number): string[] {
+        if (!step.PromptID) {
+            return [];
+        }
+        const where = `Decision step "${step.Name}" (index ${index})`;
+        const prompt = AIEngine.Instance.Prompts.find(p => UUIDsEqual(p.ID, step.PromptID));
+        if (!prompt) {
+            return [`❌ ${where} has PromptID "${step.PromptID}", which is not a prompt. Leave PromptID empty to use the Default Decision prompt.`];
+        }
+        const decisionType = AIEngine.Instance.ModelTypes.find(t => t.Name.trim().toLowerCase() === DECISION_MODEL_TYPE.toLowerCase());
+        if (!prompt.AIModelTypeID || !decisionType || UUIDsEqual(prompt.AIModelTypeID, decisionType.ID)) {
+            return [];
+        }
+        const typeName = AIEngine.Instance.ModelTypes.find(t => UUIDsEqual(t.ID, prompt.AIModelTypeID))?.Name ?? prompt.AIModelTypeID;
+        return [`❌ ${where} uses the prompt "${prompt.Name}", whose model type is "${typeName}". A Decision step's prompt must run on ${DECISION_MODEL_TYPE} models. Leave PromptID empty to use the Default Decision prompt.`];
+    }
+
     /**
      * Deduplicates arrays in AgentSpec to fix common LLM retry issues
      * Modifies spec in place and returns whether duplicates were found
@@ -599,6 +636,18 @@ export class AgentArchitectAgent extends BaseAgent {
         return { hadDuplicates };
     }
 
+    /**
+     * The agent type's name for a spec's `TypeID`. The Architect's template has the model write the
+     * type's ID (a GUID), which never contains 'Loop' or 'Flow', so the ID is resolved through
+     * AIEngine's agent types. Anything that is not a known type's ID (an older spec that wrote the
+     * name) is returned as written.
+     */
+    private agentTypeName(typeID: string | undefined): string {
+        if (!typeID) return '';
+        const type = AIEngine.Instance.AgentTypes.find(t => UUIDsEqual(t.ID, typeID));
+        return type?.Name ?? typeID;
+    }
+
     /**
      * Simple hash function for string deduplication
      */

package/src/flow-step-validation.ts

@@ -1,5 +1,5 @@
 /**
- * @fileoverview Validation for the flow step types the Architect authors — specifically loops.
+ * @fileoverview Validation for the flow step types the Architect authors, and for a flow as a whole.
  *
  * **Why loops needed their own module.** The Architect's spec taught three step types
  * (`Action`, `Prompt`, `Sub-Agent`) while `AIAgentStep.StepType` has accepted five for releases —
@@ -9,11 +9,28 @@
  * `ForEach` with no `collectionPath` iterates over nothing, and at runtime that reads as the agent
  * declining to work rather than as a malformed step.
  *
- * Pure and dependency-free so the rules are unit-testable without an agent run.
+ * **A flow as a whole is checked by the runtime's own code.** {@link ValidateFlowGraph} compiles the
+ * flow with `CompileFlowToTaskGraph` and validates the result with `ValidateTaskGraphSpec`, as a Flow
+ * agent is before it runs, rather than re-implementing any of their rules. A second copy of those
+ * rules is a copy that drifts: it passed conditions the runtime refused and refused forks the
+ * runtime ran.
+ *
+ * Pure: no database and no engine, so the rules are unit-testable without an agent run.
  *
  * @module @memberjunction/ai-agent-manager
  */
-import type { AgentStep } from '@memberjunction/ai-core-plus';
+import type {
+    AgentStep,
+    AgentStepPath,
+    FlowCompileError,
+    FlowCompilerOptions,
+    FlowCompilerPath,
+    FlowCompilerStep,
+    TaskGraphSpec,
+    TaskGraphValidationError,
+} from '@memberjunction/ai-core-plus';
+import { CollectDecisionStepKeys, CompileFlowToTaskGraph, ValidateTaskGraphSpec } from '@memberjunction/ai-core-plus';
+import { UUIDsEqual } from '@memberjunction/global';
 
 /** The step types that wrap a body and repeat it. */
 export type LoopStepType = Extract<AgentStep['StepType'], 'ForEach' | 'While'>;
@@ -23,6 +40,11 @@ export function IsLoopStep(step: Pick<AgentStep, 'StepType'>): boolean {
     return step.StepType === 'ForEach' || step.StepType === 'While';
 }
 
+/** True when this step is a fast typed decision. */
+export function IsDecisionStep(step: Pick<AgentStep, 'StepType'>): boolean {
+    return step.StepType === 'Decision';
+}
+
 /**
  * Which field carries the body's id, per body type.
  *
@@ -135,3 +157,232 @@ function parseLoopConfiguration(step: AgentStep, where: string, errors: string[]
         return null;
     }
 }
+
+/**
+ * Normalizes a Decision step's configuration so the aliases a model tends to write (`text` for a
+ * question's `instructions`, and `text` for an option's `description`) read as the fields
+ * `ReadFlowDecisionStepConfiguration` expects. Returns a copy; the input is not changed.
+ */
+export function NormalizeDecisionConfiguration(raw: Record<string, unknown>): Record<string, unknown> {
+    const cloned = structuredClone(raw);
+    const questions = cloned.questions;
+    if (!isPlainObject(questions)) {
+        return cloned;
+    }
+    for (const question of Object.values(questions)) {
+        if (!isPlainObject(question)) continue;
+        copyAlias(question, 'text', 'instructions');
+        if (Array.isArray(question.options)) {
+            for (const option of question.options) {
+                if (isPlainObject(option)) copyAlias(option, 'text', 'description');
+            }
+        }
+    }
+    return cloned;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Sets `record[to]` from `record[from]` when only the alias is present. */
+function copyAlias(record: Record<string, unknown>, from: string, to: string): void {
+    if (!record[to] && typeof record[from] === 'string') {
+        record[to] = record[from];
+    }
+}
+
+/**
+ * A Decision step's configuration as JSON text, normalized. A model may write the configuration as
+ * an object rather than as JSON text, as it may for a loop; text that is not a JSON object is
+ * returned unchanged, so `ReadFlowDecisionStepConfiguration` reports why it cannot be read.
+ */
+export function DecisionConfigurationText(raw: AgentStep['Configuration'] | null): string | null {
+    if (raw == null) return null;
+    if (typeof raw !== 'string') {
+        // Typed as an object, but it is a model's JSON: an array or a number can arrive here too, and
+        // is written as the JSON it is so the reader can say it is not an object.
+        return isPlainObject(raw) ? JSON.stringify(NormalizeDecisionConfiguration(raw)) : JSON.stringify(raw);
+    }
+    try {
+        const parsed: unknown = JSON.parse(raw);
+        return isPlainObject(parsed) ? JSON.stringify(NormalizeDecisionConfiguration(parsed)) : raw;
+    } catch {
+        return raw;
+    }
+}
+
+/**
+ * A step's `Configuration` as the JSON text `AIAgentStep.Configuration` stores, which is what the
+ * runtime reads. An object is written as text, and a Decision step's is normalized
+ * ({@link DecisionConfigurationText}). `AgentSpecSync` saves this and {@link ValidateFlowGraph}
+ * compiles it, so what is validated is what is saved.
+ */
+export function StepConfigurationText(step: Pick<AgentStep, 'StepType' | 'Configuration'>): string | null {
+    if (step.StepType === 'Decision') return DecisionConfigurationText(step.Configuration);
+    const raw = step.Configuration;
+    if (raw == null || raw === '') return null;
+    return typeof raw === 'string' ? raw : JSON.stringify(raw);
+}
+
+/**
+ * Every problem the runtime would refuse a Flow agent's steps and paths for, as messages that name
+ * the steps. Empty when the flow can run.
+ *
+ * The flow is compiled with `CompileFlowToTaskGraph` and the result validated with
+ * `ValidateTaskGraphSpec`, exactly as a Flow agent is before it runs, so a flow this passes is one
+ * the runtime runs and a flow it refuses is one the runtime refuses. That covers every Decision step
+ * the flow can reach: its configuration, its key, each condition that reads `decisions.<key>` (the
+ * key, the question, and whether that question's answer has the field read), and a fork on a Choice
+ * question that has no path for one of its options.
+ *
+ * Two checks come from outside the compiler, because it cannot see what they catch:
+ *  - a path whose origin or destination names no step, which the compiler drops without a word and
+ *    `AgentSpecSync` cannot save;
+ *  - a key two Decision steps share when the flow cannot reach one of them. The compiler checks only
+ *    the steps it compiles, but the in-run walker checks every step, since it can start at any.
+ *
+ * Names behind IDs are not resolved here: each ID stands in for its own name. The Architect checks
+ * a spec's actions, and a Decision step's prompt, separately. It also accepts a step whose sub-agent
+ * or inline prompt has no ID until the spec is saved, so a placeholder stands in for that ID.
+ *
+ * @param steps the flow's steps
+ * @param paths the flow's paths: `AgentSpec.Paths`, which is what `AgentSpecSync` saves
+ * @param workflowName the agent's name, which the compiled workflow carries
+ */
+export function ValidateFlowGraph(
+    steps: readonly AgentStep[],
+    paths: readonly AgentStepPath[],
+    workflowName: string | undefined,
+): string[] {
+    const compilerSteps = steps.map(toCompilerStep);
+    const resolved = resolvePaths(paths, steps);
+    const compiled = CompileFlowToTaskGraph(compilerSteps, resolved.Paths, compilerOptions(workflowName));
+    return [
+        ...resolved.Errors,
+        // Over every step, as the in-run walker checks them. The compiler's own check covers only the
+        // steps it compiles, so every step it flags is flagged here too.
+        ...CollectDecisionStepKeys(compilerSteps).Errors.map(compileErrorMessage),
+        ...compiled.Errors.filter((e) => e.Code !== 'DuplicateDecisionKey').map(compileErrorMessage),
+        ...(compiled.Spec ? graphErrorMessages(compiled.Spec) : []),
+    ];
+}
+
+/** What stands in for an ID the Architect lets a spec leave empty until it is saved. */
+const FILLED_ON_SAVE = '(set when the spec is saved)';
+
+/** A step's identity in a spec: its ID, or its name for a step not yet saved. */
+function stepRef(step: Pick<AgentStep, 'ID' | 'Name'>): string {
+    return step.ID || step.Name;
+}
+
+/** A spec step as the compiler reads it: the row `AgentSpecSync` would save. */
+function toCompilerStep(step: AgentStep): FlowCompilerStep {
+    return {
+        ID: stepRef(step),
+        Name: step.Name,
+        Description: step.Description ?? null,
+        StepType: step.StepType,
+        StartingStep: step.StartingStep === true,
+        // AgentSpecSync saves every step Active.
+        Status: 'Active',
+        ActionID: step.ActionID || null,
+        SubAgentID: step.SubAgentID || (runsSubAgent(step) ? FILLED_ON_SAVE : null),
+        PromptID: step.PromptID || (hasInlinePrompt(step) ? FILLED_ON_SAVE : null),
+        LoopBodyType: step.LoopBodyType,
+        Configuration: StepConfigurationText(step),
+        ActionInputMapping: mappingText(step.ActionInputMapping),
+        ActionOutputMapping: mappingText(step.ActionOutputMapping),
+    };
+}
+
+/** A Sub-Agent step, or a loop whose body is one. The Architect accepts either with no sub-agent ID yet. */
+function runsSubAgent(step: AgentStep): boolean {
+    return step.StepType === 'Sub-Agent' || (IsLoopStep(step) && step.LoopBodyType === 'Sub-Agent');
+}
+
+/** A Prompt step, or a loop whose body is one, with its prompt written inline as `PromptText`. */
+function hasInlinePrompt(step: AgentStep): boolean {
+    const runsPrompt = step.StepType === 'Prompt' || (IsLoopStep(step) && step.LoopBodyType === 'Prompt');
+    return runsPrompt && !!step.PromptText?.trim();
+}
+
+/** An action mapping as the JSON text the column stores. */
+function mappingText(mapping: AgentStep['ActionInputMapping']): string | null {
+    if (mapping == null || mapping === '') return null;
+    return typeof mapping === 'string' ? mapping : JSON.stringify(mapping);
+}
+
+/**
+ * The spec's paths with both ends resolved to their steps, and a message for each path that names a
+ * step no spec step has. An end names a step by its ID, compared as a UUID, or by its name, exactly
+ * as written — the match `AgentSpecSync` makes when it saves the path.
+ */
+function resolvePaths(
+    paths: readonly AgentStepPath[],
+    steps: readonly AgentStep[],
+): { Paths: FlowCompilerPath[]; Errors: string[] } {
+    const resolved: { Paths: FlowCompilerPath[]; Errors: string[] } = { Paths: [], Errors: [] };
+    paths.forEach((path, index) => {
+        const origin = findStep(steps, path.OriginStepID);
+        const destination = findStep(steps, path.DestinationStepID);
+        if (!origin || !destination) {
+            resolved.Errors.push(unknownEndMessage(path, !origin, !destination));
+            return;
+        }
+        resolved.Paths.push({
+            // A new path has no ID yet, and the compiler tells a fork's paths apart by ID.
+            ID: path.ID || `new-path-${index}`,
+            OriginStepID: stepRef(origin),
+            DestinationStepID: stepRef(destination),
+            Condition: path.Condition ?? null,
+            Priority: Number.isFinite(path.Priority) ? path.Priority : 0,
+            PathPoints: path.PathPoints ?? null,
+        });
+    });
+    return resolved;
+}
+
+/** The step a path end names, if any. */
+function findStep(steps: readonly AgentStep[], ref: string | undefined): AgentStep | undefined {
+    if (!ref) return undefined;
+    return steps.find((s) => !!s.ID && UUIDsEqual(s.ID, ref)) ?? steps.find((s) => s.Name === ref);
+}
+
+function unknownEndMessage(path: AgentStepPath, originUnknown: boolean, destinationUnknown: boolean): string {
+    const ends = [originUnknown ? 'origin' : null, destinationUnknown ? 'destination' : null].filter((e) => e !== null);
+    return `❌ The path from "${path.OriginStepID}" to "${path.DestinationStepID}" names no step as its ${ends.join(' or ')}. `
+        + 'Name each end by a step\'s exact Name, or by its ID for a step that already exists.';
+}
+
+/** The compiler's settings: names are placeholders, and a fork is an exclusive choice, as when a Flow agent runs. */
+function compilerOptions(workflowName: string | undefined): FlowCompilerOptions {
+    const placeholderName = (id: string): string => id;
+    return {
+        WorkflowName: workflowName?.trim() || 'Flow agent',
+        ResolveAgentName: placeholderName,
+        ResolveActionName: placeholderName,
+        ResolvePromptName: placeholderName,
+        TraversalMode: 'sequential',
+    };
+}
+
+function compileErrorMessage(error: FlowCompileError): string {
+    return `❌ [${error.Code}] ${error.Message}`;
+}
+
+/**
+ * What `ValidateTaskGraphSpec` refuses in the compiled workflow. A compiled step is named by its
+ * spec step's ID where it has one, so each ID in a message becomes the step's name, as the Flow agent
+ * does when it reports these.
+ */
+function graphErrorMessages(spec: TaskGraphSpec): string[] {
+    return ValidateTaskGraphSpec(spec).Errors.map((e: TaskGraphValidationError) => `❌ [${e.Code}] ${namedBySteps(e.Message, spec)}`);
+}
+
+function namedBySteps(message: string, spec: TaskGraphSpec): string {
+    return spec.tasks.reduce(
+        (text, task) => (task.tempId && task.name && task.tempId !== task.name ? text.split(task.tempId).join(task.name) : text),
+        message,
+    );
+}

package/src/workflow-agent-writer.ts

@@ -49,7 +49,8 @@ export class WorkflowAgentWriter extends WorkflowAgentWriterBase {
         context: { ContextUser: UserInfo; Provider: IMetadataProvider },
     ): Promise<string> {
         const flowTypeID = await this.resolveFlowAgentTypeID(context);
-        const agentIDsByName = await this.buildAgentNameIndex(context);
+        const { Agents, Actions, Prompts } = await this.buildNameIndexes(context);
+        const byName = (index: Map<string, string>, name: string): string | null => index.get(name.trim().toLowerCase()) ?? null;
 
         let counter = 0;
         const result = ConvertTaskGraphToAgentSpec(spec.graph, {
@@ -57,7 +58,11 @@ export class WorkflowAgentWriter extends WorkflowAgentWriterBase {
             // insert — these only have to correlate steps to paths inside this payload.
             AgentID: `workflow-${Date.now()}-${counter}`,
             NextID: () => `wf-node-${++counter}`,
-            ResolveAgentID: (name) => agentIDsByName.get(name.trim().toLowerCase()) ?? null,
+            ResolveAgentID: (name) => byName(Agents, name),
+            // Without these, a saved Action step carries no action and a Decision step loses its
+            // named prompt: the spec addresses both by name, and a step stores the ID.
+            ResolveActionID: (name) => byName(Actions, name),
+            ResolvePromptID: (name) => byName(Prompts, name),
             FlowAgentTypeID: flowTypeID,
             Name: spec.name,
         });
@@ -99,15 +104,35 @@ export class WorkflowAgentWriter extends WorkflowAgentWriterBase {
         return id;
     }
 
-    /** Name → ID for every agent, lowercased so a spec's human-entered name still resolves. */
-    private async buildAgentNameIndex(
+    /**
+     * Name → ID for every agent, action and prompt, in one batch, lowercased so a spec's
+     * human-entered name still resolves.
+     *
+     * A failed load throws rather than leaving an index empty: an empty index resolves nothing, and
+     * every agent, action and prompt in the workflow would then be reported lost — or, for an action,
+     * saved pointing at nothing.
+     */
+    private async buildNameIndexes(
         context: { ContextUser: UserInfo; Provider: IMetadataProvider },
-    ): Promise<Map<string, string>> {
-        const result = await RunView.FromMetadataProvider(context.Provider).RunView<{ ID: string; Name: string }>(
-            { EntityName: 'MJ: AI Agents', Fields: ['ID', 'Name'], ResultType: 'simple' },
+    ): Promise<{ Agents: Map<string, string>; Actions: Map<string, string>; Prompts: Map<string, string> }> {
+        const entityNames = ['MJ: AI Agents', 'MJ: Actions', 'MJ: AI Prompts'];
+        const results = await RunView.FromMetadataProvider(context.Provider).RunViews<{ ID: string; Name: string }>(
+            entityNames.map((EntityName) => ({
+                EntityName,
+                Fields: ['ID', 'Name'],
+                ResultType: 'simple' as const,
+            })),
             context.ContextUser,
         );
-        return new Map((result.Results ?? []).map((a) => [a.Name.trim().toLowerCase(), a.ID]));
+        const failed = entityNames.filter((_, i) => !results[i]?.Success);
+        if (failed.length > 0) {
+            const reasons = failed.map((name) => `${name}: ${results[entityNames.indexOf(name)]?.ErrorMessage || 'no result'}`);
+            throw new Error(`Could not load the names a workflow's steps refer to (${reasons.join('; ')}).`);
+        }
+        const [agents, actions, prompts] = results;
+        const index = (rows: Array<{ ID: string; Name: string }>): Map<string, string> =>
+            new Map(rows.map((r) => [r.Name.trim().toLowerCase(), r.ID]));
+        return { Agents: index(agents.Results), Actions: index(actions.Results), Prompts: index(prompts.Results) };
     }
 }