@exaudeus/workrail 0.8.6 → 0.9.0

package/dist/application/services/enhanced-loop-validator.d.ts

@@ -1,4 +1,4 @@
-import { LoopStep } from '../../types/workflow-types';
+import type { LoopStepDefinition } from '../../types/workflow-definition';
 export interface EnhancedValidationResult {
     warnings: string[];
     suggestions: string[];
@@ -10,7 +10,7 @@ export declare class EnhancedLoopValidator {
     private readonly TEMPLATE_VAR_PATTERN;
     private readonly TERNARY_PATTERN;
     private readonly NESTED_TERNARY_PATTERN;
-    validateLoopStep(step: LoopStep): EnhancedValidationResult;
+    validateLoopStep(step: LoopStepDefinition): EnhancedValidationResult;
     private getLoopBodySteps;
     private validateConditionalLogic;
     private validatePromptLength;

package/dist/application/services/enhanced-loop-validator.js

@@ -1,7 +1,14 @@
 "use strict";
+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;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EnhancedLoopValidator = void 0;
-class EnhancedLoopValidator {
+const tsyringe_1 = require("tsyringe");
+let EnhancedLoopValidator = class EnhancedLoopValidator {
     constructor() {
         this.PROMPT_WARNING_THRESHOLD = 1500;
         this.PROMPT_ERROR_THRESHOLD = 2000;
@@ -133,5 +140,8 @@ class EnhancedLoopValidator {
             suggestions.push(`Consider if you really need ${step.loop.maxIterations} iterations, or implement pagination/chunking instead.`);
         }
     }
-}
+};
 exports.EnhancedLoopValidator = EnhancedLoopValidator;
+exports.EnhancedLoopValidator = EnhancedLoopValidator = __decorate([
+    (0, tsyringe_1.singleton)()
+], EnhancedLoopValidator);

package/dist/application/services/validation-engine.d.ts

@@ -1,34 +1,13 @@
-import { Condition, ConditionContext } from '../../utils/condition-evaluator';
-import { LoopStep, Workflow } from '../../types/workflow-types';
-export interface ValidationRule {
-    type: 'contains' | 'regex' | 'length' | 'schema';
-    message: string;
-    value?: string;
-    pattern?: string;
-    flags?: string;
-    min?: number;
-    max?: number;
-    schema?: Record<string, any>;
-    condition?: Condition;
-}
-export interface ValidationComposition {
-    and?: ValidationCriteria[];
-    or?: ValidationCriteria[];
-    not?: ValidationCriteria;
-}
-export type ValidationCriteria = ValidationRule | ValidationComposition;
-export interface ValidationResult {
-    valid: boolean;
-    issues: string[];
-    suggestions: string[];
-    warnings?: string[];
-    info?: string[];
-}
+import { ConditionContext } from '../../utils/condition-evaluator';
+import type { LoopStepDefinition } from '../../types/workflow-definition';
+import type { Workflow } from '../../types/workflow';
+import { ValidationCriteria, ValidationResult } from '../../types/validation';
+import { EnhancedLoopValidator } from './enhanced-loop-validator';
 export declare class ValidationEngine {
     private ajv;
     private schemaCache;
     private enhancedLoopValidator;
-    constructor();
+    constructor(enhancedLoopValidator: EnhancedLoopValidator);
     private compileSchema;
     private evaluateCriteria;
     private evaluateRuleArray;
@@ -36,9 +15,9 @@ export declare class ValidationEngine {
     private evaluateSingleCriteria;
     private isValidationRule;
     private isValidationComposition;
-    validate(output: string, criteria: ValidationRule[] | ValidationComposition, context?: ConditionContext): Promise<ValidationResult>;
+    validate(output: string, criteria: ValidationCriteria, context?: ConditionContext): Promise<ValidationResult>;
     private evaluateRule;
-    validateLoopStep(step: LoopStep, workflow: Workflow): ValidationResult;
+    validateLoopStep(step: LoopStepDefinition, workflow: Workflow): ValidationResult;
     validateWorkflow(workflow: Workflow): ValidationResult;
     private isValidVariableName;
     private validateStepFunctionCalls;

package/dist/application/services/validation-engine.js

@@ -1,19 +1,32 @@
 "use strict";
+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;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ValidationEngine = void 0;
+const tsyringe_1 = require("tsyringe");
 const error_handler_1 = require("../../core/error-handler");
 const condition_evaluator_1 = require("../../utils/condition-evaluator");
 const ajv_1 = __importDefault(require("ajv"));
-const workflow_types_1 = require("../../types/workflow-types");
+const workflow_definition_1 = require("../../types/workflow-definition");
 const enhanced_loop_validator_1 = require("./enhanced-loop-validator");
-class ValidationEngine {
-    constructor() {
+let ValidationEngine = class ValidationEngine {
+    constructor(enhancedLoopValidator) {
         this.schemaCache = new Map();
         this.ajv = new ajv_1.default({ allErrors: true });
-        this.enhancedLoopValidator = new enhanced_loop_validator_1.EnhancedLoopValidator();
+        this.enhancedLoopValidator = enhancedLoopValidator;
     }
     compileSchema(schema) {
         const schemaKey = JSON.stringify(schema);
@@ -257,12 +270,12 @@ class ValidationEngine {
         }
         else {
             if (typeof step.body === 'string') {
-                const bodyStep = workflow.steps.find(s => s.id === step.body);
+                const bodyStep = workflow.definition.steps.find(s => s.id === step.body);
                 if (!bodyStep) {
                     issues.push(`Loop body references non-existent step '${step.body}'`);
                     suggestions.push(`Create a step with ID '${step.body}' or update the body reference`);
                 }
-                else if ((0, workflow_types_1.isLoopStep)(bodyStep)) {
+                else if ((0, workflow_definition_1.isLoopStepDefinition)(bodyStep)) {
                     issues.push(`Nested loops are not currently supported. Step '${step.body}' is a loop`);
                     suggestions.push('Refactor to avoid nested loops or use sequential loops');
                 }
@@ -293,11 +306,11 @@ class ValidationEngine {
                         issues.push(`Inline step '${inlineStep.id || 'unknown'}' must have a prompt`);
                         suggestions.push('Add a prompt to all inline steps');
                     }
-                    if ((0, workflow_types_1.isLoopStep)(inlineStep)) {
+                    if ((0, workflow_definition_1.isLoopStepDefinition)(inlineStep)) {
                         issues.push(`Nested loops are not currently supported. Inline step '${inlineStep.id}' is a loop`);
                         suggestions.push('Refactor to avoid nested loops');
                     }
-                    const callValidation = this.validateStepFunctionCalls(inlineStep, workflow.functionDefinitions || [], step.functionDefinitions || []);
+                    const callValidation = this.validateStepFunctionCalls(inlineStep, workflow.definition.functionDefinitions || [], step.functionDefinitions || []);
                     if (!callValidation.valid) {
                         issues.push(...callValidation.issues.map(i => `Step '${inlineStep.id}': ${i}`));
                         if (callValidation.suggestions)
@@ -335,15 +348,15 @@ class ValidationEngine {
         const warnings = [];
         const info = [];
         const stepIds = new Set();
-        for (const step of workflow.steps) {
+        for (const step of workflow.definition.steps) {
             if (stepIds.has(step.id)) {
                 issues.push(`Duplicate step ID '${step.id}'`);
                 suggestions.push('Ensure all step IDs are unique');
             }
             stepIds.add(step.id);
         }
-        for (const step of workflow.steps) {
-            if ((0, workflow_types_1.isLoopStep)(step)) {
+        for (const step of workflow.definition.steps) {
+            if ((0, workflow_definition_1.isLoopStepDefinition)(step)) {
                 const loopResult = this.validateLoopStep(step, workflow);
                 issues.push(...loopResult.issues.map(issue => `Step '${step.id}': ${issue}`));
                 suggestions.push(...loopResult.suggestions);
@@ -364,7 +377,7 @@ class ValidationEngine {
                 if (!step.prompt) {
                     issues.push(`Step '${step.id}' missing required prompt`);
                 }
-                const callValidation = this.validateStepFunctionCalls(step, workflow.functionDefinitions || []);
+                const callValidation = this.validateStepFunctionCalls(step, workflow.definition.functionDefinitions || []);
                 if (!callValidation.valid) {
                     issues.push(...callValidation.issues.map(i => `Step '${step.id}': ${i}`));
                     if (callValidation.suggestions)
@@ -373,21 +386,20 @@ class ValidationEngine {
             }
         }
         const loopBodySteps = new Set();
-        for (const step of workflow.steps) {
-            if ((0, workflow_types_1.isLoopStep)(step)) {
+        for (const step of workflow.definition.steps) {
+            if ((0, workflow_definition_1.isLoopStepDefinition)(step)) {
                 if (typeof step.body === 'string') {
                     loopBodySteps.add(step.body);
                 }
                 else if (Array.isArray(step.body)) {
-                    step.body.forEach(id => {
-                        if (typeof id === 'string') {
-                            loopBodySteps.add(id);
-                        }
-                    });
+                    for (const inlineStep of step.body) {
+                        if (inlineStep?.id)
+                            loopBodySteps.add(inlineStep.id);
+                    }
                 }
             }
         }
-        for (const step of workflow.steps) {
+        for (const step of workflow.definition.steps) {
             if (loopBodySteps.has(step.id) && step.runCondition) {
                 issues.push(`Step '${step.id}' is a loop body but has runCondition - this may cause conflicts`);
                 suggestions.push('Remove runCondition from loop body steps as they are controlled by the loop');
@@ -458,5 +470,10 @@ class ValidationEngine {
             default: return true;
         }
     }
-}
+};
 exports.ValidationEngine = ValidationEngine;
+exports.ValidationEngine = ValidationEngine = __decorate([
+    (0, tsyringe_1.singleton)(),
+    __param(0, (0, tsyringe_1.inject)(enhanced_loop_validator_1.EnhancedLoopValidator)),
+    __metadata("design:paramtypes", [enhanced_loop_validator_1.EnhancedLoopValidator])
+], ValidationEngine);

package/dist/application/services/workflow-compiler.d.ts

@@ -0,0 +1,18 @@
+import { Workflow, WorkflowStepDefinition, LoopStepDefinition } from '../../types/workflow';
+import type { Result } from 'neverthrow';
+import { type DomainError } from '../../domain/execution/error';
+export interface CompiledLoop {
+    readonly loop: LoopStepDefinition;
+    readonly bodySteps: readonly WorkflowStepDefinition[];
+}
+export interface CompiledWorkflow {
+    readonly workflow: Workflow;
+    readonly steps: readonly (WorkflowStepDefinition | LoopStepDefinition)[];
+    readonly stepById: ReadonlyMap<string, WorkflowStepDefinition | LoopStepDefinition>;
+    readonly compiledLoops: ReadonlyMap<string, CompiledLoop>;
+    readonly loopBodyStepIds: ReadonlySet<string>;
+}
+export declare class WorkflowCompiler {
+    compile(workflow: Workflow): Result<CompiledWorkflow, DomainError>;
+    private resolveLoopBody;
+}

package/dist/application/services/workflow-compiler.js

@@ -0,0 +1,79 @@
+"use strict";
+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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkflowCompiler = void 0;
+const tsyringe_1 = require("tsyringe");
+const workflow_1 = require("../../types/workflow");
+const neverthrow_1 = require("neverthrow");
+const error_1 = require("../../domain/execution/error");
+let WorkflowCompiler = class WorkflowCompiler {
+    compile(workflow) {
+        const steps = workflow.definition.steps;
+        const stepById = new Map();
+        for (const step of steps) {
+            if (stepById.has(step.id)) {
+                return (0, neverthrow_1.err)(error_1.Err.invalidState(`Duplicate step id '${step.id}' in workflow '${workflow.definition.id}'`));
+            }
+            stepById.set(step.id, step);
+        }
+        const compiledLoops = new Map();
+        const loopBodyStepIds = new Set();
+        for (const step of steps) {
+            if (!(0, workflow_1.isLoopStepDefinition)(step))
+                continue;
+            const loop = step;
+            const bodyResolved = this.resolveLoopBody(loop, stepById, workflow);
+            if (bodyResolved.isErr())
+                return (0, neverthrow_1.err)(bodyResolved.error);
+            for (const bodyStep of bodyResolved.value) {
+                loopBodyStepIds.add(bodyStep.id);
+            }
+            compiledLoops.set(loop.id, {
+                loop,
+                bodySteps: bodyResolved.value,
+            });
+        }
+        return (0, neverthrow_1.ok)({
+            workflow,
+            steps,
+            stepById,
+            compiledLoops,
+            loopBodyStepIds,
+        });
+    }
+    resolveLoopBody(loop, stepById, workflow) {
+        if (Array.isArray(loop.body)) {
+            for (const s of loop.body) {
+                if ((0, workflow_1.isLoopStepDefinition)(s)) {
+                    return (0, neverthrow_1.err)(error_1.Err.invalidLoop(loop.id, `Nested loops are not supported (inline step '${s.id}' is a loop)`));
+                }
+            }
+            for (const s of loop.body) {
+                const existing = stepById.get(s.id);
+                if (existing) {
+                    return (0, neverthrow_1.err)(error_1.Err.invalidState(`Inline loop body step id '${s.id}' collides with existing step id in workflow '${workflow.definition.id}'`));
+                }
+                stepById.set(s.id, s);
+            }
+            return (0, neverthrow_1.ok)(loop.body);
+        }
+        const bodyRef = loop.body;
+        const referenced = stepById.get(bodyRef);
+        if (!referenced) {
+            return (0, neverthrow_1.err)(error_1.Err.invalidLoop(loop.id, `Loop body references missing step '${bodyRef}'`));
+        }
+        if ((0, workflow_1.isLoopStepDefinition)(referenced)) {
+            return (0, neverthrow_1.err)(error_1.Err.invalidLoop(loop.id, `Nested loops are not supported (referenced step '${referenced.id}' is a loop)`));
+        }
+        return (0, neverthrow_1.ok)([referenced]);
+    }
+};
+exports.WorkflowCompiler = WorkflowCompiler;
+exports.WorkflowCompiler = WorkflowCompiler = __decorate([
+    (0, tsyringe_1.singleton)()
+], WorkflowCompiler);

package/dist/application/services/workflow-interpreter.d.ts

@@ -0,0 +1,31 @@
+import { WorkflowStepDefinition } from '../../types/workflow';
+import { CompiledWorkflow } from './workflow-compiler';
+import type { Result } from 'neverthrow';
+import { type DomainError } from '../../domain/execution/error';
+import { ExecutionState } from '../../domain/execution/state';
+import { WorkflowEvent } from '../../domain/execution/event';
+import { StepInstanceId } from '../../domain/execution/ids';
+export interface NextStep {
+    readonly step: WorkflowStepDefinition;
+    readonly stepInstanceId: StepInstanceId;
+    readonly guidance: {
+        readonly prompt: string;
+        readonly requiresConfirmation?: boolean;
+    };
+}
+export interface InterpreterOutput {
+    readonly state: ExecutionState;
+    readonly next: NextStep | null;
+    readonly isComplete: boolean;
+}
+export declare class WorkflowInterpreter {
+    applyEvent(state: ExecutionState, event: WorkflowEvent): Result<ExecutionState, DomainError>;
+    next(compiled: CompiledWorkflow, state: ExecutionState, context?: Record<string, unknown>): Result<InterpreterOutput, DomainError>;
+    private ensureRunning;
+    private nextTopLevel;
+    private nextInCurrentLoop;
+    private shouldContinueLoop;
+    private projectLoopContext;
+    private lookupStepInstance;
+    private materializeStep;
+}

package/dist/application/services/workflow-interpreter.js

@@ -0,0 +1,280 @@
+"use strict";
+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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkflowInterpreter = void 0;
+const tsyringe_1 = require("tsyringe");
+const condition_evaluator_1 = require("../../utils/condition-evaluator");
+const workflow_1 = require("../../types/workflow");
+const neverthrow_1 = require("neverthrow");
+const error_1 = require("../../domain/execution/error");
+const ids_1 = require("../../domain/execution/ids");
+let WorkflowInterpreter = class WorkflowInterpreter {
+    applyEvent(state, event) {
+        if (state.kind === 'complete')
+            return (0, neverthrow_1.ok)(state);
+        const running = this.ensureRunning(state);
+        if (running.isErr())
+            return (0, neverthrow_1.err)(running.error);
+        const s = running.value;
+        if (!s.pendingStep) {
+            return (0, neverthrow_1.err)(error_1.Err.invalidState('No pending step to complete'));
+        }
+        switch (event.kind) {
+            case 'step_completed': {
+                const expectedKey = (0, ids_1.toStepInstanceKey)(s.pendingStep);
+                const actualKey = (0, ids_1.toStepInstanceKey)(event.stepInstanceId);
+                if (expectedKey !== actualKey) {
+                    return (0, neverthrow_1.err)(error_1.Err.invalidState(`StepCompleted does not match pendingStep (expected '${expectedKey}', got '${actualKey}')`));
+                }
+                return (0, neverthrow_1.ok)({
+                    kind: 'running',
+                    completed: [...s.completed, expectedKey],
+                    loopStack: s.loopStack,
+                    pendingStep: undefined,
+                });
+            }
+            default: {
+                return (0, neverthrow_1.err)(error_1.Err.invalidState('Unsupported event'));
+            }
+        }
+    }
+    next(compiled, state, context = {}) {
+        if (state.kind === 'complete') {
+            return (0, neverthrow_1.ok)({ state, next: null, isComplete: true });
+        }
+        const runningRes = this.ensureRunning(state);
+        if (runningRes.isErr())
+            return (0, neverthrow_1.err)(runningRes.error);
+        let running = runningRes.value;
+        if (running.pendingStep) {
+            const step = this.lookupStepInstance(compiled, running.pendingStep);
+            if (step.isErr())
+                return (0, neverthrow_1.err)(step.error);
+            return (0, neverthrow_1.ok)({
+                state: running,
+                next: step.value,
+                isComplete: false,
+            });
+        }
+        for (let guard = 0; guard < 10000; guard++) {
+            if (running.loopStack.length > 0) {
+                const inLoop = this.nextInCurrentLoop(compiled, running, context);
+                if (inLoop.isErr())
+                    return (0, neverthrow_1.err)(inLoop.error);
+                const result = inLoop.value;
+                running = result.state;
+                if (result.next) {
+                    return (0, neverthrow_1.ok)({ state: running, next: result.next, isComplete: false });
+                }
+                if (running.loopStack.length > 0) {
+                    continue;
+                }
+            }
+            const top = this.nextTopLevel(compiled, running, context);
+            if (top.isErr())
+                return (0, neverthrow_1.err)(top.error);
+            const out = top.value;
+            running = out.state;
+            if (out.next) {
+                return (0, neverthrow_1.ok)({ state: running, next: out.next, isComplete: false });
+            }
+            if (running.loopStack.length > 0) {
+                continue;
+            }
+            return (0, neverthrow_1.ok)({ state: { kind: 'complete' }, next: null, isComplete: true });
+        }
+        return (0, neverthrow_1.err)(error_1.Err.invalidState('Interpreter exceeded guard iterations (possible infinite loop)'));
+    }
+    ensureRunning(state) {
+        if (state.kind === 'init') {
+            return (0, neverthrow_1.ok)({ kind: 'running', completed: [], loopStack: [], pendingStep: undefined });
+        }
+        if (state.kind !== 'running') {
+            return (0, neverthrow_1.err)(error_1.Err.invalidState(`Unsupported state kind '${state.kind}'`));
+        }
+        return (0, neverthrow_1.ok)(state);
+    }
+    nextTopLevel(compiled, state, context) {
+        for (const step of compiled.steps) {
+            if (compiled.loopBodyStepIds.has(step.id))
+                continue;
+            if (state.completed.includes(step.id))
+                continue;
+            if (step.runCondition && !(0, condition_evaluator_1.evaluateCondition)(step.runCondition, context)) {
+                continue;
+            }
+            if ((0, workflow_1.isLoopStepDefinition)(step)) {
+                const entered = { loopId: step.id, iteration: 0, bodyIndex: 0 };
+                return (0, neverthrow_1.ok)({
+                    state: { ...state, loopStack: [...state.loopStack, entered] },
+                    next: null,
+                });
+            }
+            const instance = { stepId: step.id, loopPath: [] };
+            const next = this.materializeStep(compiled, instance, context);
+            if (next.isErr())
+                return (0, neverthrow_1.err)(next.error);
+            return (0, neverthrow_1.ok)({
+                state: { ...state, pendingStep: instance },
+                next: next.value,
+            });
+        }
+        return (0, neverthrow_1.ok)({ state, next: null });
+    }
+    nextInCurrentLoop(compiled, state, context) {
+        const frame = state.loopStack[state.loopStack.length - 1];
+        const loopCompiled = compiled.compiledLoops.get(frame.loopId);
+        if (!loopCompiled) {
+            return (0, neverthrow_1.err)(error_1.Err.invalidLoop(frame.loopId, 'Loop not found in compiled metadata'));
+        }
+        const shouldContinue = this.shouldContinueLoop(loopCompiled.loop, frame, context);
+        if (shouldContinue.isErr())
+            return (0, neverthrow_1.err)(shouldContinue.error);
+        if (!shouldContinue.value) {
+            const popped = state.loopStack.slice(0, -1);
+            return (0, neverthrow_1.ok)({
+                state: {
+                    ...state,
+                    loopStack: popped,
+                    completed: [...state.completed, frame.loopId],
+                },
+                next: null,
+            });
+        }
+        const body = loopCompiled.bodySteps;
+        for (let i = frame.bodyIndex; i < body.length; i++) {
+            const bodyStep = body[i];
+            const instance = {
+                stepId: bodyStep.id,
+                loopPath: [...state.loopStack.map((f) => ({ loopId: f.loopId, iteration: f.iteration }))],
+            };
+            const key = (0, ids_1.toStepInstanceKey)(instance);
+            if (state.completed.includes(key))
+                continue;
+            const projectedContext = this.projectLoopContext(loopCompiled.loop, frame, context);
+            if (bodyStep.runCondition && !(0, condition_evaluator_1.evaluateCondition)(bodyStep.runCondition, projectedContext)) {
+                continue;
+            }
+            const next = this.materializeStep(compiled, instance, projectedContext);
+            if (next.isErr())
+                return (0, neverthrow_1.err)(next.error);
+            const updatedTop = { ...frame, bodyIndex: i };
+            const updatedStack = [...state.loopStack.slice(0, -1), updatedTop];
+            return (0, neverthrow_1.ok)({
+                state: { ...state, loopStack: updatedStack, pendingStep: instance },
+                next: next.value,
+            });
+        }
+        if (frame.iteration + 1 > loopCompiled.loop.loop.maxIterations) {
+            return (0, neverthrow_1.err)(error_1.Err.maxIterationsExceeded(frame.loopId, loopCompiled.loop.loop.maxIterations));
+        }
+        const advanced = { ...frame, iteration: frame.iteration + 1, bodyIndex: 0 };
+        const updatedStack = [...state.loopStack.slice(0, -1), advanced];
+        return (0, neverthrow_1.ok)({ state: { ...state, loopStack: updatedStack }, next: null });
+    }
+    shouldContinueLoop(loop, frame, context) {
+        if (frame.iteration >= loop.loop.maxIterations) {
+            return (0, neverthrow_1.ok)(false);
+        }
+        switch (loop.loop.type) {
+            case 'for': {
+                const count = loop.loop.count;
+                if (typeof count === 'number') {
+                    return (0, neverthrow_1.ok)(frame.iteration < count);
+                }
+                if (typeof count === 'string') {
+                    const raw = context[count];
+                    if (typeof raw !== 'number') {
+                        return (0, neverthrow_1.err)(error_1.Err.missingContext(`for loop '${loop.id}' requires numeric context['${count}']`));
+                    }
+                    return (0, neverthrow_1.ok)(frame.iteration < raw);
+                }
+                return (0, neverthrow_1.err)(error_1.Err.invalidLoop(loop.id, `for loop '${loop.id}' missing count`));
+            }
+            case 'forEach': {
+                const itemsVar = loop.loop.items;
+                if (!itemsVar)
+                    return (0, neverthrow_1.err)(error_1.Err.invalidLoop(loop.id, `forEach loop '${loop.id}' missing items`));
+                const raw = context[itemsVar];
+                if (!Array.isArray(raw)) {
+                    return (0, neverthrow_1.err)(error_1.Err.missingContext(`forEach loop '${loop.id}' requires array context['${itemsVar}']`));
+                }
+                return (0, neverthrow_1.ok)(frame.iteration < raw.length);
+            }
+            case 'while': {
+                if (!loop.loop.condition)
+                    return (0, neverthrow_1.err)(error_1.Err.invalidLoop(loop.id, `while loop '${loop.id}' missing condition`));
+                return (0, neverthrow_1.ok)((0, condition_evaluator_1.evaluateCondition)(loop.loop.condition, this.projectLoopContext(loop, frame, context)));
+            }
+            case 'until': {
+                if (!loop.loop.condition)
+                    return (0, neverthrow_1.err)(error_1.Err.invalidLoop(loop.id, `until loop '${loop.id}' missing condition`));
+                return (0, neverthrow_1.ok)(!(0, condition_evaluator_1.evaluateCondition)(loop.loop.condition, this.projectLoopContext(loop, frame, context)));
+            }
+            default:
+                return (0, neverthrow_1.err)(error_1.Err.invalidLoop(loop.id, `Unknown loop type '${loop.loop.type}'`));
+        }
+    }
+    projectLoopContext(loop, frame, base) {
+        const out = { ...base };
+        const iterationVar = loop.loop.iterationVar || 'currentIteration';
+        out[iterationVar] = frame.iteration + 1;
+        if (loop.loop.type === 'forEach') {
+            const itemsVar = loop.loop.items;
+            const raw = base[itemsVar];
+            if (Array.isArray(raw)) {
+                const index = frame.iteration;
+                const itemVar = loop.loop.itemVar || 'currentItem';
+                const indexVar = loop.loop.indexVar || 'currentIndex';
+                out[itemVar] = raw[index];
+                out[indexVar] = index;
+            }
+        }
+        return out;
+    }
+    lookupStepInstance(compiled, id) {
+        const step = compiled.stepById.get(id.stepId);
+        if (!step)
+            return (0, neverthrow_1.err)(error_1.Err.invalidState(`Unknown stepId '${id.stepId}'`));
+        if ((0, workflow_1.isLoopStepDefinition)(step))
+            return (0, neverthrow_1.err)(error_1.Err.invalidState(`pendingStep cannot be a loop step ('${id.stepId}')`));
+        return this.materializeStep(compiled, id, {});
+    }
+    materializeStep(compiled, instance, context) {
+        const step = compiled.stepById.get(instance.stepId);
+        if (!step)
+            return (0, neverthrow_1.err)(error_1.Err.invalidState(`Unknown stepId '${instance.stepId}'`));
+        if ((0, workflow_1.isLoopStepDefinition)(step)) {
+            return (0, neverthrow_1.err)(error_1.Err.invalidState(`Cannot execute loop step '${step.id}' directly`));
+        }
+        const promptParts = [];
+        if (step.agentRole) {
+            promptParts.push(`## Agent Role Instructions\n${step.agentRole}\n`);
+        }
+        if (step.guidance && step.guidance.length > 0) {
+            promptParts.push(`## Step Guidance\n${step.guidance.map((g) => `- ${g}`).join('\n')}\n`);
+        }
+        promptParts.push(step.prompt);
+        if (instance.loopPath.length > 0) {
+            const current = instance.loopPath[instance.loopPath.length - 1];
+            promptParts.push(`\n\n## Loop Context\n- Loop: ${current.loopId}\n- Iteration: ${current.iteration + 1}`);
+        }
+        return (0, neverthrow_1.ok)({
+            step,
+            stepInstanceId: instance,
+            guidance: {
+                prompt: promptParts.join('\n'),
+                requiresConfirmation: !!step.requireConfirmation,
+            },
+        });
+    }
+};
+exports.WorkflowInterpreter = WorkflowInterpreter;
+exports.WorkflowInterpreter = WorkflowInterpreter = __decorate([
+    (0, tsyringe_1.singleton)()
+], WorkflowInterpreter);