@hexabot-ai/agentic 3.1.2-alpha.1 → 3.1.2-alpha.11

package/src/__tests__/workflow-runner.test.ts

@@ -588,6 +588,103 @@ describe('WorkflowRunner', () => {
     }
   });
 
+  it('continues following steps after a repeatedly suspended while loop exits', async () => {
+    const suspendAction = defineAction<
+      { prompt: string },
+      { reply: string; done: boolean },
+      TestContext,
+      Settings
+    >({
+      name: 'loop_suspend_action',
+      inputSchema: z.object({ prompt: z.string() }),
+      outputSchema: z.object({ reply: z.string(), done: z.boolean() }),
+      execute: async ({ input, context }) => {
+        const resumeData = (await context.workflow.suspend({
+          reason: 'awaiting_reply',
+          data: { prompt: input.prompt },
+        })) as { reply: string };
+
+        return {
+          reply: resumeData.reply,
+          done: resumeData.reply === 'stop',
+        };
+      },
+    });
+    const afterExecute = jest.fn(async ({ input }) => ({
+      stored: `stored:${input.reply}`,
+    }));
+    const afterAction = defineAction<
+      { reply: string },
+      { stored: string },
+      TestContext,
+      Settings
+    >({
+      name: 'after_loop_action',
+      inputSchema: z.object({ reply: z.string() }),
+      outputSchema: z.object({ stored: z.string() }),
+      execute: afterExecute,
+    });
+    const definition: WorkflowDefinition = {
+      defs: createTaskDefs({
+        wait_step: {
+          action: 'loop_suspend_action',
+          inputs: { prompt: '="Attempt " & $string($iteration.index)' },
+        },
+        after_loop_step: {
+          action: 'after_loop_action',
+          inputs: { reply: '=$output.wait_step.reply' },
+        },
+      }),
+      flow: [
+        {
+          loop: {
+            type: 'while',
+            name: 'wait_until_stop',
+            while:
+              '=$not($exists($output.wait_step.done) and $output.wait_step.done = true)',
+            steps: [{ do: 'wait_step' }],
+          },
+        },
+        { do: 'after_loop_step' },
+      ],
+      outputs: {
+        reply: '=$output.wait_step.reply',
+        stored: '=$output.after_loop_step.stored',
+      },
+    };
+    const compiled = compileWorkflow(definition, {
+      actions: {
+        loop_suspend_action: suspendAction,
+        after_loop_action: afterAction,
+      },
+    });
+    const runner = new WorkflowRunner(compiled, {
+      runId: 'run-while-suspend-after',
+    });
+    const context = new TestContext({});
+    const startResult = await runner.start({ inputData: {}, context });
+
+    expect(startResult.status).toBe('suspended');
+    const firstResume = await runner.resume({
+      resumeData: { reply: 'continue' },
+    });
+
+    expect(firstResume.status).toBe('suspended');
+    const secondResume = await runner.resume({
+      resumeData: { reply: 'stop' },
+    });
+
+    expect(secondResume.status).toBe('finished');
+    if (secondResume.status === 'finished') {
+      expect(secondResume.output.reply).toBe('stop');
+      expect(secondResume.output.stored).toBe('stored:stop');
+    }
+    expect(afterExecute).toHaveBeenCalledTimes(1);
+    expect(afterExecute).toHaveBeenCalledWith(
+      expect.objectContaining({ input: { reply: 'stop' } }),
+    );
+  });
+
   it('handles suspension and resumes with provided data', async () => {
     const suspendAction = defineAction<
       { prompt: string },
@@ -994,12 +1091,27 @@ describe('WorkflowRunner', () => {
         return { reply: `ack:${resumeData.reply}` };
       },
     });
+    const afterAction = defineAction<
+      { reply: string },
+      { summary: string },
+      TestContext,
+      Settings
+    >({
+      name: 'after_loop_action',
+      inputSchema: z.object({ reply: z.string() }),
+      outputSchema: z.object({ summary: z.string() }),
+      execute: async ({ input }) => ({ summary: `after:${input.reply}` }),
+    });
     const definition: WorkflowDefinition = {
       defs: createTaskDefs({
         wait_step: {
           action: 'loop_suspend_action',
           inputs: { prompt: '="Ping"' },
         },
+        after_step: {
+          action: 'after_loop_action',
+          inputs: { reply: '=$output.wait_step.reply' },
+        },
       }),
       flow: [
         {
@@ -1010,8 +1122,12 @@ describe('WorkflowRunner', () => {
             steps: [{ do: 'wait_step' }],
           },
         },
+        { do: 'after_step' },
       ],
-      outputs: { reply: '=$output.wait_step.reply' },
+      outputs: {
+        reply: '=$output.wait_step.reply',
+        summary: '=$output.after_step.summary',
+      },
       inputs: {
         schema: {
           items: { type: 'array', items: { type: 'string' } },
@@ -1021,6 +1137,7 @@ describe('WorkflowRunner', () => {
     const compiled = compileWorkflow(definition, {
       actions: {
         loop_suspend_action: suspendAction,
+        after_loop_action: afterAction,
       },
     });
     const runner = new WorkflowRunner(compiled);
@@ -1061,6 +1178,7 @@ describe('WorkflowRunner', () => {
     expect(resumeResult.status).toBe('finished');
     if (resumeResult.status === 'finished') {
       expect(resumeResult.output.reply).toBe('ack:Pong');
+      expect(resumeResult.output.summary).toBe('after:ack:Pong');
     }
   });
 

package/src/index.ts

@@ -114,3 +114,11 @@ export {
 } from './utils/naming';
 
 export { sleep, withTimeout } from './utils/timeout';
+
+export {
+  collectWorkflowDefinitionResourceRefs,
+  remapWorkflowDefinitionResourceRefs,
+  type WorkflowDefinitionResourceDescriptor,
+  type WorkflowDefinitionResourceIdMaps,
+  type WorkflowDefinitionResourceRefs,
+} from './utils/workflow-definition-resources';

package/src/step-executors/loop-executor.ts

@@ -14,6 +14,7 @@ import type {
 } from '../workflow-types';
 import { evaluateValue } from '../workflow-values';
 
+import { wrapSuspensionContinuation } from './suspension-continuation';
 import type { StepExecutorEnv } from './types';
 
 type LoopScope = EvaluationScope;
@@ -74,45 +75,37 @@ async function executeForEachLoop(
     ]);
 
     if (suspension) {
-      return {
-        ...suspension,
-        continue: async (resumeData: unknown) => {
-          const next = await suspension.continue(resumeData);
-          if (next) {
-            return next;
+      return wrapSuspensionContinuation(suspension, async () => {
+        const postScope = buildScope(
+          env,
+          iterationState,
+          { item, index },
+          accumulator,
+        );
+        accumulator = await updateAccumulator(step, postScope, accumulator);
+
+        const shouldStop = await shouldStopLoop(step, postScope);
+        if (shouldStop) {
+          state.accumulator = accumulator;
+          if (step.accumulate && step.name) {
+            state.output[step.name] = { [step.accumulate.as]: accumulator };
           }
 
-          const postScope = buildScope(
-            env,
-            iterationState,
-            { item, index },
-            accumulator,
-          );
-          accumulator = await updateAccumulator(step, postScope, accumulator);
-
-          const shouldStop = await shouldStopLoop(step, postScope);
-          if (shouldStop) {
-            state.accumulator = accumulator;
-            if (step.accumulate && step.name) {
-              state.output[step.name] = { [step.accumulate.as]: accumulator };
-            }
-
-            return undefined;
-          }
+          return undefined;
+        }
 
-          return executeForEachLoop(
-            env,
-            step,
-            {
-              ...iterationState,
-              accumulator,
-              iterationStack: state.iterationStack,
-            },
-            path,
-            index + 1,
-          );
-        },
-      };
+        return executeForEachLoop(
+          env,
+          step,
+          {
+            ...iterationState,
+            accumulator,
+            iterationStack: state.iterationStack,
+          },
+          path,
+          index + 1,
+        );
+      });
     }
 
     const postScope = buildScope(
@@ -170,35 +163,27 @@ async function executeWhileLoop(
     ]);
 
     if (suspension) {
-      return {
-        ...suspension,
-        continue: async (resumeData: unknown) => {
-          const next = await suspension.continue(resumeData);
-          if (next) {
-            return next;
-          }
-
-          const postScope = buildScope(
-            env,
-            iterationState,
-            { item: undefined, index },
+      return wrapSuspensionContinuation(suspension, async () => {
+        const postScope = buildScope(
+          env,
+          iterationState,
+          { item: undefined, index },
+          accumulator,
+        );
+        accumulator = await updateAccumulator(step, postScope, accumulator);
+
+        return executeWhileLoop(
+          env,
+          step,
+          {
+            ...iterationState,
             accumulator,
-          );
-          accumulator = await updateAccumulator(step, postScope, accumulator);
-
-          return executeWhileLoop(
-            env,
-            step,
-            {
-              ...iterationState,
-              accumulator,
-              iterationStack: state.iterationStack,
-            },
-            path,
-            index + 1,
-          );
-        },
-      };
+            iterationStack: state.iterationStack,
+          },
+          path,
+          index + 1,
+        );
+      });
     }
 
     const postScope = buildScope(

package/src/step-executors/parallel-executor.ts

@@ -11,6 +11,7 @@ import type {
 } from '../workflow-types';
 
 import { markStepsSkipped } from './skip-helpers';
+import { wrapSuspensionContinuation } from './suspension-continuation';
 import type { StepExecutorEnv } from './types';
 
 /**
@@ -35,29 +36,21 @@ export async function executeParallel(
     const childPath = [...path, 'parallel', index];
     const suspension = await env.executeStep(child, state, childPath);
     if (suspension) {
-      return {
-        ...suspension,
-        continue: async (resumeData: unknown) => {
-          const next = await suspension.continue(resumeData);
-          if (next) {
-            return next;
+      return wrapSuspensionContinuation(suspension, async () => {
+        if (step.strategy === 'wait_any') {
+          if (index + 1 < step.steps.length) {
+            markStepsSkipped(
+              env,
+              step.steps.slice(index + 1),
+              state.iterationStack,
+            );
           }
 
-          if (step.strategy === 'wait_any') {
-            if (index + 1 < step.steps.length) {
-              markStepsSkipped(
-                env,
-                step.steps.slice(index + 1),
-                state.iterationStack,
-              );
-            }
+          return undefined;
+        }
 
-            return undefined;
-          }
-
-          return executeParallel(env, step, state, path, index + 1);
-        },
-      };
+        return executeParallel(env, step, state, path, index + 1);
+      });
     }
 
     if (step.strategy === 'wait_any') {

package/src/step-executors/suspension-continuation.ts

@@ -0,0 +1,31 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type { Suspension } from '../workflow-types';
+
+/**
+ * Compose a suspension with the continuation that should run once it completes.
+ *
+ * When resuming a suspension yields another suspension from the same logical
+ * step, the follow-up suspension still needs to remember how to continue the
+ * surrounding flow after that step eventually finishes.
+ */
+export function wrapSuspensionContinuation(
+  suspension: Suspension,
+  onComplete: () => Promise<Suspension | void>,
+): Suspension {
+  return {
+    ...suspension,
+    continue: async (resumeData: unknown) => {
+      const next = await suspension.continue(resumeData);
+      if (next) {
+        return wrapSuspensionContinuation(next, onComplete);
+      }
+
+      return onComplete();
+    },
+  };
+}

package/src/suspension-rebuilder.ts

@@ -12,6 +12,7 @@ import {
 } from './step-executors/loop-executor';
 import { executeParallel as runParallelExecutor } from './step-executors/parallel-executor';
 import { markStepsSkipped } from './step-executors/skip-helpers';
+import { wrapSuspensionContinuation } from './step-executors/suspension-continuation';
 import type { StepExecutorEnv } from './step-executors/types';
 import {
   StepType,
@@ -272,17 +273,9 @@ export function buildSuspensionForPath(
 
           const resumed = await executeStep(step, state, currentPath);
           if (resumed) {
-            return {
-              ...resumed,
-              continue: async (nextResumeData: unknown) => {
-                const next = await resumed.continue(nextResumeData);
-                if (next) {
-                  return next;
-                }
-
-                return deps.executeFlow(steps, state, pathPrefix, current + 1);
-              },
-            };
+            return wrapSuspensionContinuation(resumed, () =>
+              deps.executeFlow(steps, state, pathPrefix, current + 1),
+            );
           }
 
           return deps.executeFlow(steps, state, pathPrefix, current + 1);
@@ -324,35 +317,35 @@ export function buildSuspensionForPath(
     const childIndex =
       typeof childPath[0] === 'number' ? (childPath[0] as number) : 0;
 
-    return {
-      ...childSuspension,
-      continue: async (resumeData: unknown) => {
-        const next = await childSuspension.continue(resumeData);
-        if (next) {
-          return next;
-        }
-
-        if (step.strategy === 'wait_any') {
-          if (childIndex + 1 < step.steps.length) {
-            markStepsSkipped(
-              env,
-              step.steps.slice(childIndex + 1),
-              state.iterationStack ?? [],
-            );
-          }
-
-          return undefined;
+    return wrapSuspensionContinuation(childSuspension, async () => {
+      if (step.strategy === 'wait_any') {
+        if (childIndex + 1 < step.steps.length) {
+          markStepsSkipped(
+            env,
+            step.steps.slice(childIndex + 1),
+            state.iterationStack ?? [],
+          );
         }
 
-        return runParallelExecutor(
-          env,
-          step,
-          state,
-          currentPath,
-          childIndex + 1,
+        return deps.executeFlow(steps, state, pathPrefix, current + 1);
+      }
+
+      const next = await runParallelExecutor(
+        env,
+        step,
+        state,
+        currentPath,
+        childIndex + 1,
+      );
+
+      if (next) {
+        return wrapSuspensionContinuation(next, () =>
+          deps.executeFlow(steps, state, pathPrefix, current + 1),
         );
-      },
-    };
+      }
+
+      return deps.executeFlow(steps, state, pathPrefix, current + 1);
+    });
   }
 
   if (step.type === StepType.Conditional) {
@@ -382,17 +375,9 @@ export function buildSuspensionForPath(
       return null;
     }
 
-    return {
-      ...branchSuspension,
-      continue: async (resumeData: unknown) => {
-        const next = await branchSuspension.continue(resumeData);
-        if (next) {
-          return next;
-        }
-
-        return deps.executeFlow(steps, state, pathPrefix, current + 1);
-      },
-    };
+    return wrapSuspensionContinuation(branchSuspension, () =>
+      deps.executeFlow(steps, state, pathPrefix, current + 1),
+    );
   }
 
   if (step.type === StepType.Loop) {
@@ -441,63 +426,72 @@ export function buildSuspensionForPath(
     const accumulator =
       iterationState.accumulator ?? state.accumulator ?? undefined;
 
-    return {
-      ...childSuspension,
-      continue: async (resumeData: unknown) => {
-        const next = await childSuspension.continue(resumeData);
-        if (next) {
-          return next;
-        }
-
-        const scope: EvaluationScope = {
-          input: iterationState.input,
-          context: env.context.state,
-          output: iterationState.output,
-          iteration: iterationState.iteration ?? {
-            item: undefined,
-            index: iterationIndex,
-          },
-          accumulator,
+    return wrapSuspensionContinuation(childSuspension, async () => {
+      const scope: EvaluationScope = {
+        input: iterationState.input,
+        context: env.context.state,
+        output: iterationState.output,
+        iteration: iterationState.iteration ?? {
+          item: undefined,
+          index: iterationIndex,
+        },
+        accumulator,
+      };
+      const updatedAccumulator = await updateAccumulator(
+        step,
+        scope,
+        accumulator,
+      );
+      const shouldStop = await shouldStopLoop(step, scope);
+
+      state.output = iterationState.output;
+
+      if (step.accumulate && step.name) {
+        state.output[step.name] = {
+          [step.accumulate.as]: updatedAccumulator,
         };
-        const updatedAccumulator = await updateAccumulator(
-          step,
-          scope,
-          accumulator,
-        );
-        const shouldStop = await shouldStopLoop(step, scope);
-
-        state.output = iterationState.output;
-
-        if (step.accumulate && step.name) {
-          state.output[step.name] = {
-            [step.accumulate.as]: updatedAccumulator,
-          };
-        }
+      }
 
-        if (step.accumulate) {
-          state.accumulator = updatedAccumulator;
-        }
+      if (step.accumulate) {
+        state.accumulator = updatedAccumulator;
+      }
 
-        if (shouldStop) {
-          return undefined;
-        }
+      if (shouldStop) {
+        return deps.executeFlow(steps, state, pathPrefix, current + 1);
+      }
+
+      const baseState: ExecutionState = {
+        ...iterationState,
+        iterationStack: ancestorIterationStack,
+        accumulator: updatedAccumulator,
+        output: state.output,
+      };
+      const next = await runLoopExecutor(
+        env,
+        step,
+        baseState,
+        currentPath,
+        iterationIndex + 1,
+      );
+
+      state.output = baseState.output;
+      if (step.accumulate) {
+        state.accumulator = baseState.accumulator;
+      }
+
+      if (next) {
+        return wrapSuspensionContinuation(next, async () => {
+          state.output = baseState.output;
+          if (step.accumulate) {
+            state.accumulator = baseState.accumulator;
+          }
 
-        const baseState: ExecutionState = {
-          ...iterationState,
-          iterationStack: ancestorIterationStack,
-          accumulator: updatedAccumulator,
-          output: state.output,
-        };
+          return deps.executeFlow(steps, state, pathPrefix, current + 1);
+        });
+      }
 
-        return runLoopExecutor(
-          env,
-          step,
-          baseState,
-          currentPath,
-          iterationIndex + 1,
-        );
-      },
-    };
+      return deps.executeFlow(steps, state, pathPrefix, current + 1);
+    });
   }
 
   return null;