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

package/src/flow-step-validation.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Validation for the flow step types the Architect authors — specifically loops.
+ *
+ * **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 —
+ * `ForEach` and `While` were executable but unauthorable, so anything built through the Agent Manager
+ * could not repeat itself. Closing that gap means teaching the prompt *and* checking what comes back,
+ * because a loop is the one step type that saves perfectly well while doing nothing at all: a
+ * `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.
+ *
+ * @module @memberjunction/ai-agent-manager
+ */
+import type { AgentStep } from '@memberjunction/ai-core-plus';
+
+/** The step types that wrap a body and repeat it. */
+export type LoopStepType = Extract<AgentStep['StepType'], 'ForEach' | 'While'>;
+
+/** True when this step repeats a body rather than being one. */
+export function IsLoopStep(step: Pick<AgentStep, 'StepType'>): boolean {
+    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: Record<NonNullable<AgentStep['LoopBodyType']>, 'ActionID' | 'PromptID' | 'SubAgentID'> = {
+    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: AgentStep, index: number): string[] {
+    const errors: string[] = [];
+    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: AgentStep, where: string, errors: string[]): void {
+    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: AgentStep,
+    config: Record<string, unknown>,
+    where: string,
+    errors: string[],
+): void {
+    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: AgentStep, where: string, errors: string[]): Record<string, unknown> | null {
+    const raw: unknown = 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 as Record<string, unknown>;
+    }
+
+    if (typeof raw !== 'string') {
+        errors.push(`❌ ${where} has a Configuration that is neither an object nor JSON text`);
+        return null;
+    }
+
+    try {
+        const parsed: unknown = 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 as Record<string, unknown>;
+    } catch (e) {
+        errors.push(`❌ ${where} has invalid Configuration JSON: ${e instanceof Error ? e.message : String(e)}`);
+        return null;
+    }
+}

package/src/index.ts

@@ -8,8 +8,10 @@
 export * from './old/agent-definition.interface';
 
 export * from './agent-spec-sync';
+export * from './flow-step-validation';
 
 // Export agent implementations
 export * from './agents/architect-agent';
 export * from './agents/builder-agent';
 export * from './agents/planning-designer-agent';
+export * from './workflow-agent-writer';

package/src/workflow-agent-writer.ts

@@ -0,0 +1,117 @@
+/**
+ * @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, UserInfo, IMetadataProvider } from '@memberjunction/core';
+import { RegisterClass } from '@memberjunction/global';
+import {
+    ConvertTaskGraphToAgentSpec,
+    FormatSaveAsWorkflowLosses,
+    type WorkflowSpec,
+} from '@memberjunction/ai-core-plus';
+import { AgentSpecSync } from './agent-spec-sync';
+
+/** 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 abstract class WorkflowAgentWriterBase {
+    public abstract PersistFlowAgent(
+        spec: WorkflowSpec,
+        context: { ContextUser: UserInfo; Provider: IMetadataProvider },
+    ): Promise<string>;
+}
+
+@RegisterClass(WorkflowAgentWriterBase, WORKFLOW_AGENT_WRITER_KEY)
+export 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.
+     */
+    public async PersistFlowAgent(
+        spec: WorkflowSpec,
+        context: { ContextUser: UserInfo; Provider: IMetadataProvider },
+    ): Promise<string> {
+        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. */
+    private async resolveFlowAgentTypeID(context: { ContextUser: UserInfo; Provider: IMetadataProvider }): Promise<string> {
+        const result = await RunView.FromMetadataProvider(context.Provider).RunView<{ ID: string }>(
+            { 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. */
+    private async buildAgentNameIndex(
+        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' },
+            context.ContextUser,
+        );
+        return new Map((result.Results ?? []).map((a) => [a.Name.trim().toLowerCase(), a.ID]));
+    }
+}
+
+/** Prevents tree-shaking of the registered writer. */
+export function LoadWorkflowAgentWriter(): void {
+    void WorkflowAgentWriter;
+}