@rk0429/agentic-relay 19.14.4 → 20.0.0

package/dist/application/workflow-execution-service.d.ts

@@ -12,6 +12,7 @@ export interface WorkflowExecutionDeps {
     executeAgentStep: AgentStepExecutor;
     executeCommand: CommandExecutor;
     workflowRepo: WorkflowFileRepository;
+    readFile: (path: string, encoding: BufferEncoding) => Promise<string>;
 }
 export interface AgentStepExecutor {
     execute(opts: {
@@ -116,11 +117,15 @@ export declare class WorkflowExecutionService {
     private finalizeRootResult;
     private persistInterruptState;
     private runWorkflowFrame;
+    private handlePendingExitCondition;
+    private beginNewIterationIfNeeded;
+    private executeIterationSteps;
     private resumeFrames;
     private resumeParentFrames;
     private executeStep;
     private runSubWorkflow;
     private evaluateExitCondition;
+    private evaluateExitConditionsAt;
     private handleStepFailure;
     private logNewlySkippedSteps;
     private reportProgress;
@@ -134,9 +139,11 @@ export declare class WorkflowExecutionService {
     private buildExitConditionCheckpoint;
     private rebaseInterruptState;
     private getNextStepIdAfter;
+    private getContinuationStepId;
     private getStepIndex;
     private getStepDefinition;
-    private requireCompletedStepResult;
+    private resolveExitConditionTargetStepId;
+    private findCompletedStepResult;
     private findTerminalCompletedResult;
     private toPublicResult;
     private assertFrameMatchesWorkflow;

package/dist/application/workflow-execution-service.js

@@ -1,9 +1,10 @@
-import { access, readFile } from "node:fs/promises";
+import { access } from "node:fs/promises";
 import { dirname, basename, resolve } from "node:path";
 import { ValidationError } from "../core/errors.js";
 import { ExitConditionEvaluator, } from "../domain/exit-condition-evaluator.js";
 import { LoopExecution, NestDepth, } from "../domain/loop-execution.js";
 import { SessionResolver } from "../domain/session-resolver.js";
+import { isWorkflowStep } from "../domain/workflow-schema.js";
 import { computeWorkflowDigest, loadWorkflow, } from "../domain/workflow-loader.js";
 const DEFAULT_INTERRUPT_GRACE_MS = 30_000;
 const EXIT_VERDICT_INSTRUCTION = "Respond with STOP or CONTINUE on the first non-empty line. You may explain your reasoning after that first line.";
@@ -129,159 +130,258 @@ export class WorkflowExecutionService {
         let continuationStepId;
         while (execution.status === "running") {
             if (execution.pendingExitCondition) {
-                const checkpoint = execution.pendingExitCondition;
-                const outcome = await this.evaluateExitCondition({
+                const pendingResult = await this.handlePendingExitCondition({
                     execution,
                     workflow,
+                    workflowPath,
+                    workflowDigest,
                     cwd,
                     signal,
                     interruptTracker,
-                    checkpoint,
                 });
-                if (outcome.kind === "interrupted") {
-                    return {
+                if (pendingResult.kind === "interrupted") {
+                    return pendingResult.result;
+                }
+                if (pendingResult.kind === "stop") {
+                    break;
+                }
+                continuationStepId = pendingResult.continuationStepId;
+            }
+            const iteration = await this.beginNewIterationIfNeeded({
+                execution,
+                workflow,
+                continuationStepId,
+            });
+            continuationStepId = undefined;
+            if (iteration.action === "completed") {
+                break;
+            }
+            if (!iteration.nextStepId) {
+                continue;
+            }
+            const stepExecution = await this.executeIterationSteps({
+                execution,
+                workflow,
+                workflowPath,
+                workflowDigest,
+                cwd,
+                signal,
+                interruptTracker,
+                startIndex: this.getStepIndex(workflow, iteration.nextStepId),
+                vars: opts.vars,
+            });
+            if (stepExecution.kind === "interrupted") {
+                return stepExecution.result;
+            }
+            if (stepExecution.exitConditionMet) {
+                break;
+            }
+            if (execution.nextStepId === null &&
+                execution.currentIteration >= workflow.loop.maxIterations) {
+                execution.complete("max_iterations_reached", this.now().toISOString());
+            }
+        }
+        if (execution.status === "completed") {
+            await this.deps.eventLog.logLoopCompleted(execution.executionId, execution.completionReason, execution.currentIteration, this.computeDuration(execution.startedAt, execution.completedAt));
+        }
+        return {
+            status: "completed",
+            execution,
+            workflow,
+            workflowPath,
+            workflowDigest,
+        };
+    }
+    async handlePendingExitCondition(opts) {
+        const { execution, workflow, workflowPath, workflowDigest, cwd, signal, interruptTracker, } = opts;
+        const checkpoint = execution.pendingExitCondition;
+        const evaluation = await this.evaluateExitConditionsAt({
+            execution,
+            workflow,
+            cwd,
+            signal,
+            interruptTracker,
+            timing: checkpoint.timing,
+            stepId: checkpoint.stepId,
+            startIndex: checkpoint.conditionIndex,
+        });
+        if (evaluation.kind === "interrupted") {
+            return {
+                kind: "interrupted",
+                result: {
+                    status: "interrupted",
+                    execution,
+                    workflow,
+                    workflowPath,
+                    workflowDigest,
+                    interruptState: evaluation.interruptState,
+                },
+            };
+        }
+        if (evaluation.kind === "stop") {
+            return { kind: "stop" };
+        }
+        const continuationStepId = this.getContinuationStepId(workflow, checkpoint.timing, checkpoint.stepId);
+        if (interruptTracker.isInterruptRequested()) {
+            return {
+                kind: "interrupted",
+                result: {
+                    status: "interrupted",
+                    execution,
+                    workflow,
+                    workflowPath,
+                    workflowDigest,
+                    interruptState: execution.interrupt({
+                        nextStepId: continuationStepId ?? undefined,
+                    }),
+                },
+            };
+        }
+        return {
+            kind: "continue",
+            continuationStepId,
+        };
+    }
+    async beginNewIterationIfNeeded(opts) {
+        const { execution, workflow } = opts;
+        const shouldBeginIteration = execution.currentIteration === 0 ||
+            opts.continuationStepId === null ||
+            (opts.continuationStepId === undefined && execution.nextStepId === null);
+        let continuationStepId = opts.continuationStepId;
+        if (shouldBeginIteration) {
+            if (execution.currentIteration >= workflow.loop.maxIterations) {
+                execution.complete("max_iterations_reached", this.now().toISOString());
+                return { action: "completed" };
+            }
+            execution.beginIteration();
+            continuationStepId = undefined;
+            await this.deps.eventLog.logIterationStarted(execution.executionId, execution.currentIteration);
+            await this.reportProgress({
+                snapshot: execution.toProgressSnapshot(),
+                event: { type: "iteration_started" },
+            });
+        }
+        const nextStepId = continuationStepId ?? execution.nextStepId ?? workflow.steps[0]?.id ?? null;
+        if (!nextStepId && execution.currentIteration >= workflow.loop.maxIterations) {
+            execution.complete("max_iterations_reached", this.now().toISOString());
+            return { action: "completed" };
+        }
+        return { action: "continue", nextStepId };
+    }
+    async executeIterationSteps(opts) {
+        const { execution, workflow, workflowPath, workflowDigest, cwd, signal, interruptTracker, startIndex, vars, } = opts;
+        let exitConditionMet = false;
+        for (const step of workflow.steps.slice(startIndex)) {
+            const beforeEvaluation = await this.evaluateExitConditionsAt({
+                execution,
+                workflow,
+                cwd,
+                signal,
+                interruptTracker,
+                timing: "before",
+                stepId: step.id,
+            });
+            if (beforeEvaluation.kind === "interrupted") {
+                return {
+                    kind: "interrupted",
+                    result: {
                         status: "interrupted",
                         execution,
                         workflow,
                         workflowPath,
                         workflowDigest,
-                        interruptState: outcome.interruptState,
-                    };
-                }
-                const before = execution.stepResults;
-                execution.applyExitVerdict(outcome.verdict, {
-                    evaluatedAfter: checkpoint.evaluateAfterStepId,
-                });
-                await this.logNewlySkippedSteps(execution, before);
-                if (outcome.verdict === "stop") {
-                    break;
-                }
-                continuationStepId =
-                    checkpoint.kind === "after_step"
-                        ? this.getNextStepIdAfter(workflow, checkpoint.evaluateAfterStepId)
-                        : null;
-                if (interruptTracker.isInterruptRequested()) {
-                    return {
+                        interruptState: beforeEvaluation.interruptState,
+                    },
+                };
+            }
+            if (beforeEvaluation.kind === "stop") {
+                exitConditionMet = true;
+                break;
+            }
+            if (interruptTracker.isInterruptRequested()) {
+                return {
+                    kind: "interrupted",
+                    result: {
                         status: "interrupted",
                         execution,
                         workflow,
                         workflowPath,
                         workflowDigest,
                         interruptState: execution.interrupt({
-                            nextStepId: continuationStepId ?? undefined,
+                            nextStepId: step.id,
                         }),
-                    };
-                }
-            }
-            const shouldBeginIteration = execution.currentIteration === 0 ||
-                continuationStepId === null ||
-                (continuationStepId === undefined && execution.nextStepId === null);
-            if (shouldBeginIteration) {
-                if (execution.currentIteration >= workflow.loop.maxIterations) {
-                    execution.complete("max_iterations_reached", this.now().toISOString());
-                    break;
-                }
-                execution.beginIteration();
-                continuationStepId = undefined;
-                await this.deps.eventLog.logIterationStarted(execution.executionId, execution.currentIteration);
-                await this.reportProgress({
-                    snapshot: execution.toProgressSnapshot(),
-                    event: { type: "iteration_started" },
-                });
-            }
-            const nextStepId = continuationStepId ?? execution.nextStepId ?? workflow.steps[0]?.id ?? null;
-            continuationStepId = undefined;
-            if (!nextStepId) {
-                if (execution.currentIteration >= workflow.loop.maxIterations) {
-                    execution.complete("max_iterations_reached", this.now().toISOString());
-                    break;
-                }
-                continue;
+                    },
+                };
             }
-            const startIndex = this.getStepIndex(workflow, nextStepId);
-            let completedViaExitCondition = false;
-            for (const step of workflow.steps.slice(startIndex)) {
-                const outcome = await this.executeStep({
-                    step,
-                    execution,
-                    workflow,
-                    workflowPath,
-                    cwd,
-                    signal,
-                    vars: opts.vars,
-                    interruptTracker,
-                });
-                if (outcome.kind === "interrupted") {
-                    return {
+            const outcome = await this.executeStep({
+                step,
+                execution,
+                workflow,
+                workflowPath,
+                cwd,
+                signal,
+                vars,
+                interruptTracker,
+            });
+            if (outcome.kind === "interrupted") {
+                return {
+                    kind: "interrupted",
+                    result: {
                         status: "interrupted",
                         execution,
                         workflow,
                         workflowPath,
                         workflowDigest,
                         interruptState: outcome.interruptState,
-                    };
-                }
-                if (execution.status !== "running") {
-                    break;
-                }
-                if (execution.shouldEvaluateAfter(step.id)) {
-                    const checkpoint = this.buildExitConditionCheckpoint(workflow, step.id);
-                    const evaluation = await this.evaluateExitCondition({
-                        execution,
-                        workflow,
-                        cwd,
-                        signal,
-                        interruptTracker,
-                        checkpoint,
-                    });
-                    if (evaluation.kind === "interrupted") {
-                        return {
-                            status: "interrupted",
-                            execution,
-                            workflow,
-                            workflowPath,
-                            workflowDigest,
-                            interruptState: evaluation.interruptState,
-                        };
-                    }
-                    const before = execution.stepResults;
-                    execution.applyExitVerdict(evaluation.verdict, {
-                        evaluatedAfter: checkpoint.evaluateAfterStepId,
-                    });
-                    await this.logNewlySkippedSteps(execution, before);
-                    if (evaluation.verdict === "stop") {
-                        completedViaExitCondition = true;
-                        break;
-                    }
-                }
-                if (interruptTracker.isInterruptRequested()) {
-                    return {
+                    },
+                };
+            }
+            if (execution.status !== "running") {
+                break;
+            }
+            const afterEvaluation = await this.evaluateExitConditionsAt({
+                execution,
+                workflow,
+                cwd,
+                signal,
+                interruptTracker,
+                timing: "after",
+                stepId: step.id,
+            });
+            if (afterEvaluation.kind === "interrupted") {
+                return {
+                    kind: "interrupted",
+                    result: {
                         status: "interrupted",
                         execution,
                         workflow,
                         workflowPath,
                         workflowDigest,
-                        interruptState: execution.interrupt(),
-                    };
-                }
+                        interruptState: afterEvaluation.interruptState,
+                    },
+                };
             }
-            if (completedViaExitCondition) {
+            if (afterEvaluation.kind === "stop") {
+                exitConditionMet = true;
                 break;
             }
-            if (execution.nextStepId === null &&
-                execution.currentIteration >= workflow.loop.maxIterations) {
-                execution.complete("max_iterations_reached", this.now().toISOString());
+            if (interruptTracker.isInterruptRequested()) {
+                return {
+                    kind: "interrupted",
+                    result: {
+                        status: "interrupted",
+                        execution,
+                        workflow,
+                        workflowPath,
+                        workflowDigest,
+                        interruptState: execution.interrupt(),
+                    },
+                };
             }
         }
-        if (execution.status === "completed") {
-            await this.deps.eventLog.logLoopCompleted(execution.executionId, execution.completionReason, execution.currentIteration, this.computeDuration(execution.startedAt, execution.completedAt));
-        }
         return {
-            status: "completed",
-            execution,
-            workflow,
-            workflowPath,
-            workflowDigest,
+            kind: "completed",
+            exitConditionMet,
         };
     }
     async resumeFrames(opts) {
@@ -533,30 +633,27 @@ export class WorkflowExecutionService {
         };
     }
     async evaluateExitCondition(opts) {
-        const { execution, workflow, cwd, signal, interruptTracker, checkpoint } = opts;
-        const exitCondition = workflow.loop.exitCondition;
-        if (!exitCondition) {
-            return {
-                kind: "continue",
-                verdict: "continue",
-                checkpoint,
-            };
-        }
-        const evaluationSignal = interruptTracker.beginOperation(`exit:${execution.currentIteration}`, signal);
+        const { execution, workflow, condition, cwd, signal, interruptTracker, checkpoint } = opts;
+        const evaluationSignal = interruptTracker.beginOperation(`exit:${execution.currentIteration}:${checkpoint.timing}:${checkpoint.stepId}:${checkpoint.conditionIndex}`, signal);
         try {
-            if (exitCondition.type === "agent") {
-                const targetStepId = checkpoint.kind === "after_step"
-                    ? checkpoint.evaluateAfterStepId
-                    : workflow.steps.at(-1)?.id;
-                const targetResult = this.requireCompletedStepResult(execution, targetStepId, `exit condition evaluation in iteration ${execution.currentIteration}`);
+            if (condition.type === "agent") {
+                const targetStepId = this.resolveExitConditionTargetStepId(workflow, checkpoint);
+                const targetResult = this.findCompletedStepResult(execution, targetStepId);
+                if (!targetResult) {
+                    return {
+                        kind: "continue",
+                        verdict: "continue",
+                        checkpoint,
+                    };
+                }
                 if (!targetResult.fullResponsePath) {
-                    throw new ValidationError(`Step "${targetStepId}" is missing fullResponsePath required for exit condition evaluation.`);
+                    throw new ValidationError(`Step "${targetResult.stepId}" is missing fullResponsePath required for exit condition evaluation.`);
                 }
-                const responseContent = await readFile(targetResult.fullResponsePath, "utf8");
-                const prompt = this.buildExitConditionPrompt(exitCondition.agent.prompt, targetResult.fullResponsePath, responseContent);
+                const responseContent = await this.deps.readFile(targetResult.fullResponsePath, "utf8");
+                const prompt = this.buildExitConditionPrompt(condition.agent.prompt, targetResult.fullResponsePath, responseContent);
                 const result = await this.deps.executeAgentStep.execute({
                     prompt,
-                    backend: exitCondition.agent.backend,
+                    backend: condition.agent.backend,
                     cwd,
                     signal: evaluationSignal,
                 });
@@ -573,11 +670,11 @@ export class WorkflowExecutionService {
                     parsedVerdict,
                 };
             }
-            const commandResult = await this.deps.executeCommand.execute(exitCondition.command.run, {
+            const commandResult = await this.deps.executeCommand.execute(condition.command.run, {
                 cwd,
                 signal: evaluationSignal,
             });
-            const verdict = ExitConditionEvaluator.evaluateExitCode(commandResult.exitCode, exitCondition.command.successMeans);
+            const verdict = ExitConditionEvaluator.evaluateExitCode(commandResult.exitCode, condition.command.successMeans);
             await this.deps.eventLog.logExitConditionEvaluated(execution.executionId, verdict, execution.currentIteration);
             return {
                 kind: "continue",
@@ -592,7 +689,8 @@ export class WorkflowExecutionService {
                     checkpoint,
                     interruptState: execution.interrupt({
                         pendingExitCondition: checkpoint,
-                        nextStepId: null,
+                        nextStepId: this.getContinuationStepId(workflow, checkpoint.timing, checkpoint.stepId) ??
+                            undefined,
                     }),
                 };
             }
@@ -610,7 +708,8 @@ export class WorkflowExecutionService {
                 checkpoint,
                 interruptState: execution.interrupt({
                     pendingExitCondition: checkpoint,
-                    nextStepId: null,
+                    nextStepId: this.getContinuationStepId(workflow, checkpoint.timing, checkpoint.stepId) ??
+                        undefined,
                 }),
             };
         }
@@ -618,6 +717,59 @@ export class WorkflowExecutionService {
             interruptTracker.endOperation();
         }
     }
+    async evaluateExitConditionsAt(opts) {
+        const { execution, workflow, cwd, signal, interruptTracker, timing, stepId, startIndex = 0, } = opts;
+        const conditions = execution.getConditionsAt(timing, stepId);
+        if (conditions.length === 0) {
+            if (execution.pendingExitCondition) {
+                execution.applyExitVerdict("continue");
+            }
+            return { kind: "continue" };
+        }
+        for (let index = startIndex; index < conditions.length; index += 1) {
+            const checkpoint = this.buildExitConditionCheckpoint(timing, stepId, index);
+            const outcome = await this.evaluateExitCondition({
+                execution,
+                workflow,
+                condition: conditions[index],
+                cwd,
+                signal,
+                interruptTracker,
+                checkpoint,
+            });
+            if (outcome.kind === "interrupted") {
+                return {
+                    kind: "interrupted",
+                    checkpoint,
+                    interruptState: outcome.interruptState,
+                };
+            }
+            if (outcome.verdict === "stop") {
+                const before = execution.stepResults;
+                execution.applyExitVerdict("stop", { checkpoint });
+                await this.logNewlySkippedSteps(execution, before);
+                return {
+                    kind: "stop",
+                    checkpoint,
+                };
+            }
+            if (interruptTracker.isInterruptRequested()) {
+                const nextIndex = index + 1;
+                if (nextIndex < conditions.length) {
+                    return {
+                        kind: "interrupted",
+                        checkpoint,
+                        interruptState: execution.interrupt({
+                            pendingExitCondition: this.buildExitConditionCheckpoint(timing, stepId, nextIndex),
+                            nextStepId: this.getContinuationStepId(workflow, timing, stepId) ?? undefined,
+                        }),
+                    };
+                }
+            }
+        }
+        execution.applyExitVerdict("continue");
+        return { kind: "continue" };
+    }
     async handleStepFailure(opts) {
         const { execution, workflow, step, message, duration } = opts;
         await this.deps.eventLog.logStepFailed(execution.executionId, step.id, execution.currentIteration, message, duration);
@@ -763,21 +915,18 @@ ${responseContent}`;
     }
     async readVerdictOutput(fullResponsePath, summary) {
         try {
-            return await readFile(fullResponsePath, "utf8");
+            return await this.deps.readFile(fullResponsePath, "utf8");
         }
         catch {
             return summary;
         }
     }
-    buildExitConditionCheckpoint(workflow, stepId) {
-        return workflow.loop.exitCondition?.evaluateAfter
-            ? {
-                kind: "after_step",
-                evaluateAfterStepId: stepId,
-            }
-            : {
-                kind: "iteration_end",
-            };
+    buildExitConditionCheckpoint(timing, stepId, conditionIndex) {
+        return {
+            timing,
+            stepId,
+            conditionIndex,
+        };
     }
     rebaseInterruptState(state, executionId, startedAt, prefixFrames) {
         return {
@@ -791,6 +940,9 @@ ${responseContent}`;
         const index = this.getStepIndex(workflow, stepId);
         return workflow.steps[index + 1]?.id ?? null;
     }
+    getContinuationStepId(workflow, timing, stepId) {
+        return timing === "before" ? stepId : this.getNextStepIdAfter(workflow, stepId);
+    }
     getStepIndex(workflow, stepId) {
         const index = workflow.steps.findIndex((step) => step.id === stepId);
         if (index === -1) {
@@ -801,18 +953,22 @@ ${responseContent}`;
     getStepDefinition(workflow, stepId) {
         return workflow.steps[this.getStepIndex(workflow, stepId)];
     }
-    requireCompletedStepResult(execution, stepId, context) {
+    resolveExitConditionTargetStepId(workflow, checkpoint) {
+        if (checkpoint.timing === "after") {
+            return checkpoint.stepId;
+        }
+        const stepIndex = this.getStepIndex(workflow, checkpoint.stepId);
+        return workflow.steps[stepIndex - 1]?.id;
+    }
+    findCompletedStepResult(execution, stepId) {
         if (!stepId) {
-            throw new ValidationError(`Cannot resolve step result for ${context}: target step is missing.`);
+            return undefined;
         }
         const result = execution.stepResults
             .filter((candidate) => candidate.stepId === stepId &&
             candidate.iteration === execution.currentIteration)
             .at(-1);
-        if (!result || result.status !== "completed") {
-            throw new ValidationError(`Step "${stepId}" is not completed and cannot be used for ${context}.`);
-        }
-        return result;
+        return result?.status === "completed" ? result : undefined;
     }
     findTerminalCompletedResult(execution) {
         const stepResults = execution.stepResults;
@@ -849,12 +1005,24 @@ ${responseContent}`;
                 recoveryHint: "Retry with a checkpoint created from the same workflow definition, or discard the tampered state file.",
             });
         }
-        if (frame.pendingExitCondition?.kind === "after_step" &&
-            (!frame.pendingExitCondition.evaluateAfterStepId ||
-                !stepIds.has(frame.pendingExitCondition.evaluateAfterStepId))) {
-            throw new ValidationError(`Resume preflight failed: frames[${frameIndex}].pendingExitCondition references an unknown step in workflow "${frame.workflowPath}".`, {
-                recoveryHint: "Use a checkpoint whose pendingExitCondition still matches the workflow definition.",
-            });
+        if (frame.pendingExitCondition) {
+            if (!stepIds.has(frame.pendingExitCondition.stepId)) {
+                throw new ValidationError(`Resume preflight failed: frames[${frameIndex}].pendingExitCondition.stepId "${frame.pendingExitCondition.stepId}" does not exist in workflow "${frame.workflowPath}".`, {
+                    recoveryHint: "Use a checkpoint whose pendingExitCondition still matches the workflow definition.",
+                });
+            }
+            const matchingConditions = workflow.loop.exitConditions?.filter((condition) => {
+                const defaultStepId = condition.timing === "before"
+                    ? workflow.steps[0]?.id
+                    : workflow.steps.at(-1)?.id;
+                return (condition.timing === frame.pendingExitCondition.timing &&
+                    (condition.step ?? defaultStepId) === frame.pendingExitCondition.stepId);
+            }) ?? [];
+            if (frame.pendingExitCondition.conditionIndex >= matchingConditions.length) {
+                throw new ValidationError(`Resume preflight failed: frames[${frameIndex}].pendingExitCondition.conditionIndex ${frame.pendingExitCondition.conditionIndex} is out of range for workflow "${frame.workflowPath}".`, {
+                    recoveryHint: "Use a checkpoint whose pendingExitCondition still matches the workflow definition.",
+                });
+            }
         }
         for (const result of frame.stepResults) {
             if (!stepIds.has(result.stepId)) {
@@ -990,7 +1158,4 @@ class InterruptTracker {
         }
     }
 }
-function isWorkflowStep(step) {
-    return typeof step.workflow === "string";
-}
 //# sourceMappingURL=workflow-execution-service.js.map