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

package/dist/flow-step-validation.js

@@ -0,0 +1,102 @@
+/** True when this step repeats a body rather than being one. */
+export function IsLoopStep(step) {
+    return step.StepType === 'ForEach' || step.StepType === 'While';
+}
+/**
+ * Which field carries the body's id, per body type.
+ *
+ * The body's id lives in the SAME field a plain step of that type would use — a `ForEach` whose body
+ * is an Action still puts it in `ActionID`. Introducing a parallel `LoopBodyActionID` would have been
+ * a second place an action id can live, and the two would drift.
+ */
+const BODY_ID_FIELD = {
+    Action: 'ActionID',
+    Prompt: 'PromptID',
+    'Sub-Agent': 'SubAgentID',
+};
+/**
+ * Checks one `ForEach` / `While` step, returning every problem rather than the first.
+ *
+ * Returns messages rather than throwing, matching how the Architect reports the rest of its
+ * validation — one pass gives the model everything it has to fix, instead of a fix-and-retry loop
+ * that surfaces one error per round trip.
+ */
+export function ValidateLoopStep(step, index) {
+    const errors = [];
+    if (!IsLoopStep(step))
+        return errors;
+    const where = `${step.StepType} step "${step.Name}" (index ${index})`;
+    validateLoopBody(step, where, errors);
+    const config = parseLoopConfiguration(step, where, errors);
+    if (config)
+        validateLoopBounds(step, config, where, errors);
+    return errors;
+}
+/** The loop must name what it repeats, and that thing must exist. */
+function validateLoopBody(step, where, errors) {
+    if (!step.LoopBodyType) {
+        errors.push(`❌ ${where} must have LoopBodyType — one of "Action", "Prompt" or "Sub-Agent" — naming what runs on each pass`);
+        return;
+    }
+    const field = BODY_ID_FIELD[step.LoopBodyType];
+    if (step[field])
+        return;
+    // Two legitimate reasons the id is still empty:
+    //  - a Sub-Agent body that AgentSpecSync will link by name once the sub-agent is created, exactly
+    //    as it already does for a plain Sub-Agent step;
+    //  - a Prompt body supplied inline as PromptText, which becomes an AIPrompt on save.
+    const linkedLater = step.LoopBodyType === 'Sub-Agent';
+    const inlinePrompt = step.LoopBodyType === 'Prompt' && !!step.PromptText?.trim();
+    if (linkedLater || inlinePrompt)
+        return;
+    errors.push(`❌ ${where} has LoopBodyType "${step.LoopBodyType}" but no ${field} to run`);
+}
+/** ForEach needs something to iterate; While needs something to test; both need a name for the item. */
+function validateLoopBounds(step, config, where, errors) {
+    if (step.StepType === 'ForEach' && !config['collectionPath']) {
+        errors.push(`❌ ${where} must set Configuration.collectionPath — the payload path holding the items to iterate`);
+    }
+    if (step.StepType === 'While' && !config['condition']) {
+        errors.push(`❌ ${where} must set Configuration.condition — the expression checked before each pass`);
+    }
+    if (!config['itemVariable']) {
+        errors.push(`❌ ${where} must set Configuration.itemVariable — the name the body refers to the current item by`);
+    }
+}
+/**
+ * Reads a loop's `Configuration`, reporting rather than throwing. Null when unusable.
+ *
+ * Accepts an object as well as a JSON string — the same latitude the action mappings already get,
+ * because a model that has just been shown an object literal in the prompt will send one.
+ */
+function parseLoopConfiguration(step, where, errors) {
+    const raw = step.Configuration;
+    if (raw == null || raw === '') {
+        errors.push(`❌ ${where} must have a Configuration object describing the loop's bounds`);
+        return null;
+    }
+    if (typeof raw === 'object') {
+        if (Array.isArray(raw)) {
+            errors.push(`❌ ${where} has a Configuration that is an array rather than an object`);
+            return null;
+        }
+        return raw;
+    }
+    if (typeof raw !== 'string') {
+        errors.push(`❌ ${where} has a Configuration that is neither an object nor JSON text`);
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            errors.push(`❌ ${where} has a Configuration that is not a JSON object`);
+            return null;
+        }
+        return parsed;
+    }
+    catch (e) {
+        errors.push(`❌ ${where} has invalid Configuration JSON: ${e instanceof Error ? e.message : String(e)}`);
+        return null;
+    }
+}
+//# sourceMappingURL=flow-step-validation.js.map

package/dist/flow-step-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-step-validation.js","sourceRoot":"","sources":["../src/flow-step-validation.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -5,7 +5,9 @@
  */
 export * from './old/agent-definition.interface.js';
 export * from './agent-spec-sync.js';
+export * from './flow-step-validation.js';
 export * from './agents/architect-agent.js';
 export * from './agents/builder-agent.js';
 export * from './agents/planning-designer-agent.js';
+export * from './workflow-agent-writer.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,kCAAkC,CAAC;AAEjD,cAAc,mBAAmB,CAAC;AAGlC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kCAAkC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,kCAAkC,CAAC;AAEjD,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AAGvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kCAAkC,CAAC;AACjD,cAAc,yBAAyB,CAAC"}

package/dist/index.js

@@ -6,8 +6,10 @@
 // Export all interfaces
 export * from './old/agent-definition.interface.js';
 export * from './agent-spec-sync.js';
+export * from './flow-step-validation.js';
 // Export agent implementations
 export * from './agents/architect-agent.js';
 export * from './agents/builder-agent.js';
 export * from './agents/planning-designer-agent.js';
+export * from './workflow-agent-writer.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAwB;AACxB,cAAc,kCAAkC,CAAC;AAEjD,cAAc,mBAAmB,CAAC;AAElC,+BAA+B;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kCAAkC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAwB;AACxB,cAAc,kCAAkC,CAAC;AAEjD,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AAEvC,+BAA+B;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kCAAkC,CAAC;AACjD,cAAc,yBAAyB,CAAC"}

package/dist/workflow-agent-writer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Persists a workflow's graph as a Flow agent, via `AgentSpecSync`.
+ *
+ * This is the host side of the seam `WorkflowSpecSync` declares. It lives here, in the agent-manager,
+ * because `AgentSpecSync` is the **one place that writes an agent** — it already owns atomic
+ * multi-entity writes and the mutation audit, and a second writer would be a second set of rules
+ * about what a valid agent record is.
+ *
+ * The conversion itself is `ConvertTaskGraphToAgentSpec`, shipped in Phase 4. That it is reusable
+ * here without modification is the practical payoff of the convergence: "save a runtime graph as a
+ * workflow" and "persist a workflow's graph" turn out to be the same operation, because after Phase 4
+ * they are the same model.
+ *
+ * @module @memberjunction/ai-agent-manager
+ */
+import { UserInfo, IMetadataProvider } from '@memberjunction/core';
+import { type WorkflowSpec } from '@memberjunction/ai-core-plus';
+/** ClassFactory key under which hosts resolve the writer. */
+export declare const WORKFLOW_AGENT_WRITER_KEY = "WorkflowAgentWriter";
+/** Base so hosts can resolve an implementation without importing this package directly. */
+export declare abstract class WorkflowAgentWriterBase {
+    abstract PersistFlowAgent(spec: WorkflowSpec, context: {
+        ContextUser: UserInfo;
+        Provider: IMetadataProvider;
+    }): Promise<string>;
+}
+export declare class WorkflowAgentWriter extends WorkflowAgentWriterBase {
+    /**
+     * Converts the workflow's graph to a Flow `AgentSpec` and persists it.
+     *
+     * **Losses are logged, not swallowed.** The converter reports what it could not carry across —
+     * human steps, unresolvable agents, run-specific inputs. Dropping that silently would hand
+     * someone a workflow missing an approval they believed they had saved, and they would only find
+     * out by running it. The save still proceeds: a workflow that is 90% right and says so is more
+     * useful than a refusal, and the losses are surfaced to the caller by the operation above.
+     */
+    PersistFlowAgent(spec: WorkflowSpec, context: {
+        ContextUser: UserInfo;
+        Provider: IMetadataProvider;
+    }): Promise<string>;
+    /** Resolves the Flow agent type, so the persisted agent is a Flow rather than a Loop. */
+    private resolveFlowAgentTypeID;
+    /** Name → ID for every agent, lowercased so a spec's human-entered name still resolves. */
+    private buildAgentNameIndex;
+}
+/** Prevents tree-shaking of the registered writer. */
+export declare function LoadWorkflowAgentWriter(): void;
+//# sourceMappingURL=workflow-agent-writer.d.ts.map

package/dist/workflow-agent-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-agent-writer.d.ts","sourceRoot":"","sources":["../src/workflow-agent-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAqB,QAAQ,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEtF,OAAO,EAGH,KAAK,YAAY,EACpB,MAAM,8BAA8B,CAAC;AAGtC,6DAA6D;AAC7D,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAE/D,2FAA2F;AAC3F,8BAAsB,uBAAuB;aACzB,gBAAgB,CAC5B,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE;QAAE,WAAW,EAAE,QAAQ,CAAC;QAAC,QAAQ,EAAE,iBAAiB,CAAA;KAAE,GAChE,OAAO,CAAC,MAAM,CAAC;CACrB;AAED,qBACa,mBAAoB,SAAQ,uBAAuB;IAC5D;;;;;;;;OAQG;IACU,gBAAgB,CACzB,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE;QAAE,WAAW,EAAE,QAAQ,CAAC;QAAC,QAAQ,EAAE,iBAAiB,CAAA;KAAE,GAChE,OAAO,CAAC,MAAM,CAAC;IAyClB,yFAAyF;YAC3E,sBAAsB;IAUpC,2FAA2F;YAC7E,mBAAmB;CASpC;AAED,sDAAsD;AACtD,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C"}

package/dist/workflow-agent-writer.js

@@ -0,0 +1,97 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+/**
+ * @fileoverview Persists a workflow's graph as a Flow agent, via `AgentSpecSync`.
+ *
+ * This is the host side of the seam `WorkflowSpecSync` declares. It lives here, in the agent-manager,
+ * because `AgentSpecSync` is the **one place that writes an agent** — it already owns atomic
+ * multi-entity writes and the mutation audit, and a second writer would be a second set of rules
+ * about what a valid agent record is.
+ *
+ * The conversion itself is `ConvertTaskGraphToAgentSpec`, shipped in Phase 4. That it is reusable
+ * here without modification is the practical payoff of the convergence: "save a runtime graph as a
+ * workflow" and "persist a workflow's graph" turn out to be the same operation, because after Phase 4
+ * they are the same model.
+ *
+ * @module @memberjunction/ai-agent-manager
+ */
+import { LogError, RunView } from '@memberjunction/core';
+import { RegisterClass } from '@memberjunction/global';
+import { ConvertTaskGraphToAgentSpec, FormatSaveAsWorkflowLosses, } from '@memberjunction/ai-core-plus';
+import { AgentSpecSync } from './agent-spec-sync.js';
+/** ClassFactory key under which hosts resolve the writer. */
+export const WORKFLOW_AGENT_WRITER_KEY = 'WorkflowAgentWriter';
+/** Base so hosts can resolve an implementation without importing this package directly. */
+export class WorkflowAgentWriterBase {
+}
+let WorkflowAgentWriter = class WorkflowAgentWriter extends WorkflowAgentWriterBase {
+    /**
+     * Converts the workflow's graph to a Flow `AgentSpec` and persists it.
+     *
+     * **Losses are logged, not swallowed.** The converter reports what it could not carry across —
+     * human steps, unresolvable agents, run-specific inputs. Dropping that silently would hand
+     * someone a workflow missing an approval they believed they had saved, and they would only find
+     * out by running it. The save still proceeds: a workflow that is 90% right and says so is more
+     * useful than a refusal, and the losses are surfaced to the caller by the operation above.
+     */
+    async PersistFlowAgent(spec, context) {
+        const flowTypeID = await this.resolveFlowAgentTypeID(context);
+        const agentIDsByName = await this.buildAgentNameIndex(context);
+        let counter = 0;
+        const result = ConvertTaskGraphToAgentSpec(spec.graph, {
+            // Deterministic within one call, and unique because AgentSpecSync assigns real keys on
+            // 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,
+            FlowAgentTypeID: flowTypeID,
+            Name: spec.name,
+        });
+        if (!result.Success || !result.Spec) {
+            throw new Error(result.ErrorMessage ?? 'The workflow graph could not be converted to an agent.');
+        }
+        if (result.Losses.length > 0) {
+            LogError(`[WorkflowAgentWriter] "${spec.name}" saved with losses:\n${FormatSaveAsWorkflowLosses(result.Losses)}`);
+        }
+        result.Spec.Description = spec.description ?? result.Spec.Description;
+        // A Draft or Paused workflow persists as a Disabled agent, so nothing can invoke it before
+        // its author has turned it on — the schedule side makes the same choice for the same reason.
+        // 'Disabled' and not 'Inactive': the latter is not a value `AIAgent.Status` accepts, so this
+        // line used to make every non-Active save fail its CHECK constraint.
+        result.Spec.Status = spec.status === 'Active' ? 'Active' : 'Disabled';
+        const sync = AgentSpecSync.FromRawSpec(result.Spec, context.ContextUser, context.Provider);
+        // AgentSpecSyncResult uses camelCase — it predates the PascalCase-public convention and is
+        // consumed by MCP tools, so it is left alone rather than renamed under this change.
+        const saved = await sync.SaveToDatabase();
+        if (!saved?.success) {
+            throw new Error(`Could not save the workflow's agent "${spec.name}".`);
+        }
+        return saved.agentId;
+    }
+    /** Resolves the Flow agent type, so the persisted agent is a Flow rather than a Loop. */
+    async resolveFlowAgentTypeID(context) {
+        const result = await RunView.FromMetadataProvider(context.Provider).RunView({ EntityName: 'MJ: AI Agent Types', ExtraFilter: `Name='Flow'`, Fields: ['ID'], ResultType: 'simple' }, context.ContextUser);
+        const id = result.Results?.[0]?.ID;
+        if (!id)
+            throw new Error("The 'Flow' agent type was not found — has the metadata seed been pushed?");
+        return id;
+    }
+    /** Name → ID for every agent, lowercased so a spec's human-entered name still resolves. */
+    async buildAgentNameIndex(context) {
+        const result = await RunView.FromMetadataProvider(context.Provider).RunView({ EntityName: 'MJ: AI Agents', Fields: ['ID', 'Name'], ResultType: 'simple' }, context.ContextUser);
+        return new Map((result.Results ?? []).map((a) => [a.Name.trim().toLowerCase(), a.ID]));
+    }
+};
+WorkflowAgentWriter = __decorate([
+    RegisterClass(WorkflowAgentWriterBase, WORKFLOW_AGENT_WRITER_KEY)
+], WorkflowAgentWriter);
+export { WorkflowAgentWriter };
+/** Prevents tree-shaking of the registered writer. */
+export function LoadWorkflowAgentWriter() {
+    void WorkflowAgentWriter;
+}
+//# sourceMappingURL=workflow-agent-writer.js.map

package/dist/workflow-agent-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-agent-writer.js","sourceRoot":"","sources":["../src/workflow-agent-writer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/ai-agent-manager",
   "type": "module",
-  "version": "6.1.0-edge.0",
+  "version": "6.1.0-edge.2",
   "description": "Core interfaces and types for the MemberJunction Agent Manager system",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,14 +14,14 @@
   "author": "MemberJunction",
   "license": "ISC",
   "dependencies": {
-    "@memberjunction/ai-agents": "6.1.0-edge.0",
-    "@memberjunction/ai-core-plus": "6.1.0-edge.0",
-    "@memberjunction/ai-engine-base": "6.1.0-edge.0",
-    "@memberjunction/aiengine": "6.1.0-edge.0",
-    "@memberjunction/core": "6.1.0-edge.0",
-    "@memberjunction/core-entities": "6.1.0-edge.0",
-    "@memberjunction/global": "6.1.0-edge.0",
-    "@memberjunction/templates": "6.1.0-edge.0"
+    "@memberjunction/ai-agents": "6.1.0-edge.2",
+    "@memberjunction/ai-core-plus": "6.1.0-edge.2",
+    "@memberjunction/ai-engine-base": "6.1.0-edge.2",
+    "@memberjunction/aiengine": "6.1.0-edge.2",
+    "@memberjunction/core": "6.1.0-edge.2",
+    "@memberjunction/core-entities": "6.1.0-edge.2",
+    "@memberjunction/global": "6.1.0-edge.2",
+    "@memberjunction/templates": "6.1.0-edge.2"
   },
   "devDependencies": {
     "@types/node": "^24.10.11",

package/src/__tests__/flow-step-validation.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Tests for loop-step validation.
+ *
+ * The assertion that matters most here is the one about a loop that saves cleanly and then does
+ * nothing: a `ForEach` with no `collectionPath` is structurally valid SQL, passes every other check,
+ * and at runtime iterates zero times — which reads as the agent declining to do the work rather than
+ * as a malformed step. That is precisely the class of error the Architect has to catch before save.
+ */
+import { describe, it, expect } from 'vitest';
+import type { AgentStep } from '@memberjunction/ai-core-plus';
+import { IsLoopStep, ValidateLoopStep } from '../flow-step-validation';
+
+const step = (over: Partial<AgentStep> = {}): AgentStep => ({
+    ID: '',
+    Name: 'Score each lead',
+    StepType: 'ForEach',
+    StartingStep: false,
+    LoopBodyType: 'Action',
+    ActionID: 'AC71E1DA-1111-2222-3333-444455556666',
+    Configuration: JSON.stringify({ type: 'ForEach', collectionPath: 'leads', itemVariable: 'lead' }),
+    ...over,
+});
+
+describe('IsLoopStep', () => {
+    it('recognises exactly the two wrapping step types', () => {
+        expect(IsLoopStep({ StepType: 'ForEach' })).toBe(true);
+        expect(IsLoopStep({ StepType: 'While' })).toBe(true);
+        expect(IsLoopStep({ StepType: 'Action' })).toBe(false);
+        expect(IsLoopStep({ StepType: 'Prompt' })).toBe(false);
+        expect(IsLoopStep({ StepType: 'Sub-Agent' })).toBe(false);
+    });
+});
+
+describe('ValidateLoopStep — the happy paths', () => {
+    it('accepts a well-formed ForEach', () => {
+        expect(ValidateLoopStep(step(), 0)).toEqual([]);
+    });
+
+    it('accepts a well-formed While', () => {
+        const s = step({
+            StepType: 'While',
+            Name: 'Poll until done',
+            Configuration: JSON.stringify({ type: 'While', condition: "payload.status !== 'Complete'", itemVariable: 'attempt' }),
+        });
+        expect(ValidateLoopStep(s, 0)).toEqual([]);
+    });
+
+    it('accepts a Configuration supplied as an object, not only as JSON text', () => {
+        // A model that was just shown an object literal in the prompt will send one. Rejecting that
+        // would make the prompt and the validator disagree about the same example.
+        const s = step({ Configuration: { type: 'ForEach', collectionPath: 'leads', itemVariable: 'lead' } as unknown as string });
+        expect(ValidateLoopStep(s, 0)).toEqual([]);
+    });
+
+    it('ignores non-loop steps entirely', () => {
+        expect(ValidateLoopStep(step({ StepType: 'Action', LoopBodyType: undefined, Configuration: undefined }), 0)).toEqual([]);
+    });
+});
+
+describe('ValidateLoopStep — a loop that would silently do nothing', () => {
+    it('rejects a ForEach with nothing to iterate over', () => {
+        const s = step({ Configuration: JSON.stringify({ type: 'ForEach', itemVariable: 'lead' }) });
+        const errors = ValidateLoopStep(s, 2);
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toContain('collectionPath');
+        expect(errors[0]).toContain('index 2');
+    });
+
+    it('rejects a While with nothing to test', () => {
+        const s = step({ StepType: 'While', Configuration: JSON.stringify({ type: 'While', itemVariable: 'attempt' }) });
+        const errors = ValidateLoopStep(s, 0);
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toContain('condition');
+    });
+
+    it('rejects either kind with no name for the current item', () => {
+        const s = step({ Configuration: JSON.stringify({ type: 'ForEach', collectionPath: 'leads' }) });
+        expect(ValidateLoopStep(s, 0).join(' ')).toContain('itemVariable');
+    });
+
+    it('rejects a loop with no Configuration at all', () => {
+        const s = step({ Configuration: undefined });
+        const errors = ValidateLoopStep(s, 0);
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toContain('Configuration');
+    });
+
+    it('does not cascade bound errors when the Configuration could not be read', () => {
+        // One clear "this is not parseable" beats three downstream complaints about fields that
+        // could never have been found.
+        const s = step({ Configuration: '{not json' });
+        const errors = ValidateLoopStep(s, 0);
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toContain('invalid Configuration JSON');
+    });
+
+    it('rejects a Configuration that parses to something other than an object', () => {
+        expect(ValidateLoopStep(step({ Configuration: '"just a string"' }), 0)[0]).toContain('not a JSON object');
+        expect(ValidateLoopStep(step({ Configuration: '[1,2,3]' }), 0)[0]).toContain('not a JSON object');
+        expect(
+            ValidateLoopStep(step({ Configuration: [1, 2, 3] as unknown as string }), 0)[0],
+        ).toContain('array rather than an object');
+    });
+});
+
+describe('ValidateLoopStep — the body', () => {
+    it('rejects a loop that does not say what it repeats', () => {
+        const errors = ValidateLoopStep(step({ LoopBodyType: undefined }), 0);
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toContain('LoopBodyType');
+    });
+
+    it('looks for the body id in the field that body type would normally use', () => {
+        // No parallel LoopBodyActionID: an action id lives in ActionID whether or not a loop wraps it.
+        const errors = ValidateLoopStep(step({ ActionID: undefined }), 0);
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toContain('ActionID');
+    });
+
+    it('rejects a Prompt body with neither a prompt to use nor one to create', () => {
+        const s = step({ LoopBodyType: 'Prompt', ActionID: undefined });
+        expect(ValidateLoopStep(s, 0)[0]).toContain('PromptID');
+    });
+
+    it('accepts a Prompt body supplied inline, which becomes a prompt on save', () => {
+        const s = step({ LoopBodyType: 'Prompt', ActionID: undefined, PromptText: 'Summarise this lead.' });
+        expect(ValidateLoopStep(s, 0)).toEqual([]);
+    });
+
+    it('treats whitespace-only inline prompt text as absent', () => {
+        const s = step({ LoopBodyType: 'Prompt', ActionID: undefined, PromptText: '   ' });
+        expect(ValidateLoopStep(s, 0)[0]).toContain('PromptID');
+    });
+
+    it('accepts a Sub-Agent body with no id, because it is linked by name after the sub-agent is created', () => {
+        // Same latitude a plain Sub-Agent step already gets — requiring an id here would make it
+        // impossible to author a loop over a sub-agent being created in the same spec.
+        const s = step({ LoopBodyType: 'Sub-Agent', ActionID: undefined, SubAgentID: '' });
+        expect(ValidateLoopStep(s, 0)).toEqual([]);
+    });
+});
+
+describe('ValidateLoopStep — reporting', () => {
+    it('returns every problem at once rather than only the first', () => {
+        // One pass gives the model everything it must fix. Reporting one error per round trip turns
+        // a single correction into a retry loop.
+        const s = step({ LoopBodyType: undefined, ActionID: undefined, Configuration: JSON.stringify({}) });
+        const errors = ValidateLoopStep(s, 0);
+        expect(errors.length).toBeGreaterThanOrEqual(3);
+        expect(errors.join(' ')).toContain('LoopBodyType');
+        expect(errors.join(' ')).toContain('collectionPath');
+        expect(errors.join(' ')).toContain('itemVariable');
+    });
+
+    it('names the step and its index so the model can find it', () => {
+        const errors = ValidateLoopStep(step({ Name: 'Retry the import', Configuration: undefined }), 7);
+        expect(errors[0]).toContain('"Retry the import"');
+        expect(errors[0]).toContain('index 7');
+        expect(errors[0]).toContain('ForEach');
+    });
+});

package/src/agent-spec-sync.ts

@@ -15,6 +15,7 @@ import {
 import {
     AgentSpec,
     AgentActionSpec,
+    AgentStep,
     SubAgentSpec
 } from '@memberjunction/ai-core-plus';
 import { UUIDsEqual } from '@memberjunction/global';
@@ -553,7 +554,7 @@ export class AgentSpecSync {
             Name: agent.Name || '',
             Description: agent.Description || undefined,
             TypeID: agent.TypeID || undefined,
-            Status: (agent.Status as 'Active' | 'Inactive' | 'Pending') || undefined,
+            Status: agent.Status || undefined,
             IconClass: agent.IconClass || undefined,
             LogoURL: agent.LogoURL || undefined,
             ParentID: agent.ParentID || undefined,
@@ -718,7 +719,7 @@ export class AgentSpecSync {
      * @param step - The agent step entity
      * @returns Mapped step spec
      */
-    private mapStepEntityToSpec(step: MJAIAgentStepEntity): any {
+    private mapStepEntityToSpec(step: MJAIAgentStepEntity): AgentStep {
         return {
             ID: step.ID,
             Name: step.Name,
@@ -728,8 +729,13 @@ export class AgentSpecSync {
             ActionID: step.ActionID || undefined,
             SubAgentID: step.SubAgentID || undefined,
             PromptID: step.PromptID || undefined,
-            ActionInputMapping: this.parseJsonField<any>(step.ActionInputMapping),
-            ActionOutputMapping: this.parseJsonField<any>(step.ActionOutputMapping)
+            // Loop steps round-trip their body type and bounds; without these, reading a flow agent
+            // that contains a loop and writing it back would silently turn the loop into an
+            // unconfigured step that iterates over nothing.
+            LoopBodyType: step.LoopBodyType || undefined,
+            Configuration: step.Configuration || undefined,
+            ActionInputMapping: this.parseJsonField<Record<string, unknown>>(step.ActionInputMapping),
+            ActionOutputMapping: this.parseJsonField<Record<string, unknown>>(step.ActionOutputMapping)
         };
     }
 
@@ -882,12 +888,9 @@ export class AgentSpecSync {
             agentEntity.TypeID = (this.spec as any).TypeID;
         }
 
-        // Handle Status - defaults to Active if not specified
-        if ((this.spec as any).Status) {
-            agentEntity.Status = (this.spec as any).Status;
-        } else {
-            agentEntity.Status = 'Active';
-        }
+        // Handle Status - defaults to Active if not specified. Typed rather than cast: the cast is
+        // what let `'Inactive'` — a value the CHECK constraint rejects — reach the entity unchallenged.
+        agentEntity.Status = this.spec.Status ?? 'Active';
 
         // Serialize JSON fields
         agentEntity.PayloadDownstreamPaths = JSON.stringify(
@@ -1362,6 +1365,11 @@ export class AgentSpecSync {
             stepEntity.ActionID = stepSpec.ActionID || null;
             stepEntity.SubAgentID = stepSpec.SubAgentID || null;
             stepEntity.Status = 'Active'; // Default to Active
+            // Loop steps: the body type says which of Action/Prompt/Sub-Agent runs each pass, and
+            // Configuration carries the bounds. Written for every step because a step that STOPS
+            // being a loop must have these cleared, not left behind from its previous shape.
+            stepEntity.LoopBodyType = stepSpec.LoopBodyType || null;
+            stepEntity.Configuration = stepSpec.Configuration || null;
 
             // Handle inline prompt creation for Prompt-type steps
             // If StepType is Prompt and PromptID is empty, create a new AIPrompt record

package/src/agents/architect-agent.ts

@@ -3,6 +3,7 @@ import { ExecuteAgentParams, BaseAgentNextStep, AgentSpec, MJAIAgentRunEntityExt
 import { MJActionEntity } from "@memberjunction/core-entities";
 import { RunView } from '@memberjunction/core';
 import { RegisterClass, NormalizeUUID } from '@memberjunction/global';
+import { IsLoopStep, ValidateLoopStep } from '../flow-step-validation';
 
 /**
  * Architect Agent - Transforms technical design into validated AgentSpec JSON
@@ -153,8 +154,10 @@ export class AgentArchitectAgent extends BaseAgent {
             specWithType.Status = 'Active';
             corrected = true;
             console.log('✓ Auto-corrected: Added default Status = "Active"');
-        } else if (!['Active', 'Inactive', 'Pending'].includes(specWithType.Status)) {
-            errors.push(`❌ Status must be "Active", "Inactive", or "Pending", got: "${specWithType.Status}"`);
+        } else if (!['Active', 'Disabled', 'Pending'].includes(specWithType.Status)) {
+            // 'Disabled', not 'Inactive' — this validator used to accept a value the AIAgent CHECK
+            // constraint rejects, so a spec it passed could still fail at save with no explanation.
+            errors.push(`❌ Status must be "Active", "Disabled", or "Pending", got: "${specWithType.Status}"`);
         }
 
         // 5. Validate agent type-specific requirements
@@ -247,6 +250,17 @@ export class AgentArchitectAgent extends BaseAgent {
                         // 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));
+                    }
                 }
             }
         }