@hexabot-ai/agentic 3.0.1-alpha.0

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

@@ -0,0 +1,299 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type {
+  EvaluationScope,
+  ExecutionState,
+  ForEachLoopStep,
+  LoopStep,
+  Suspension,
+  WhileLoopStep,
+} from '../workflow-types';
+import { evaluateValue } from '../workflow-values';
+
+import type { StepExecutorEnv } from './types';
+
+type LoopScope = EvaluationScope;
+
+/**
+ * Execute a loop step by iterating over input items and executing child steps.
+ *
+ * @param env Executor environment with helpers and workflow context.
+ * @param step The loop step configuration.
+ * @param state Mutable workflow execution state.
+ * @param path Path tokens locating this loop within the workflow.
+ * @param startIndex Index to resume iteration from when continuing.
+ * @returns A suspension if a child step pauses execution, otherwise void.
+ */
+export async function executeLoop(
+  env: StepExecutorEnv,
+  step: LoopStep,
+  state: ExecutionState,
+  path: Array<number | string>,
+  startIndex = 0,
+): Promise<Suspension | void> {
+  if (step.loopType === 'for_each') {
+    return executeForEachLoop(env, step, state, path, startIndex);
+  }
+
+  return executeWhileLoop(env, step, state, path, startIndex);
+}
+
+async function executeForEachLoop(
+  env: StepExecutorEnv,
+  step: ForEachLoopStep,
+  state: ExecutionState,
+  path: Array<number | string>,
+  startIndex: number,
+): Promise<Suspension | void> {
+  const scope = {
+    input: state.input,
+    context: env.context.state,
+    output: state.output,
+    iteration: state.iteration,
+    accumulator: state.accumulator,
+  };
+  const items = await evaluateValue(step.forEach.in, scope);
+  const iterable = Array.isArray(items) ? items : [];
+  let accumulator = step.accumulate?.initial ?? state.accumulator;
+
+  for (let index = startIndex; index < iterable.length; index += 1) {
+    const item = iterable[index];
+    const iterationState: ExecutionState = {
+      ...state,
+      iteration: { item, index },
+      accumulator,
+      iterationStack: [...state.iterationStack, index],
+    };
+    const suspension = await env.executeFlow(step.steps, iterationState, [
+      ...path,
+      index,
+    ]);
+
+    if (suspension) {
+      return {
+        ...suspension,
+        continue: async (resumeData: unknown) => {
+          const next = await suspension.continue(resumeData);
+          if (next) {
+            return next;
+          }
+
+          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 executeForEachLoop(
+            env,
+            step,
+            {
+              ...iterationState,
+              accumulator,
+              iterationStack: state.iterationStack,
+            },
+            path,
+            index + 1,
+          );
+        },
+      };
+    }
+
+    const postScope = buildScope(
+      env,
+      iterationState,
+      { item, index },
+      accumulator,
+    );
+
+    accumulator = await updateAccumulator(step, postScope, accumulator);
+
+    const shouldStop = await shouldStopLoop(step, postScope);
+    if (shouldStop) {
+      break;
+    }
+
+    state.output = iterationState.output;
+  }
+
+  finalizeAccumulatorState(step, state, accumulator);
+
+  return undefined;
+}
+
+async function executeWhileLoop(
+  env: StepExecutorEnv,
+  step: WhileLoopStep,
+  state: ExecutionState,
+  path: Array<number | string>,
+  startIndex: number,
+): Promise<Suspension | void> {
+  let accumulator = step.accumulate?.initial ?? state.accumulator;
+
+  for (let index = startIndex; ; index += 1) {
+    const conditionScope = buildScope(
+      env,
+      state,
+      { item: undefined, index },
+      accumulator,
+    );
+    const shouldContinue = await evaluateValue(step.while, conditionScope);
+    if (!Boolean(shouldContinue)) {
+      break;
+    }
+
+    const iterationState: ExecutionState = {
+      ...state,
+      iteration: { item: undefined, index },
+      accumulator,
+      iterationStack: [...state.iterationStack, index],
+    };
+    const suspension = await env.executeFlow(step.steps, iterationState, [
+      ...path,
+      index,
+    ]);
+
+    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 },
+            accumulator,
+          );
+          accumulator = await updateAccumulator(step, postScope, accumulator);
+
+          return executeWhileLoop(
+            env,
+            step,
+            {
+              ...iterationState,
+              accumulator,
+              iterationStack: state.iterationStack,
+            },
+            path,
+            index + 1,
+          );
+        },
+      };
+    }
+
+    const postScope = buildScope(
+      env,
+      iterationState,
+      { item: undefined, index },
+      accumulator,
+    );
+
+    accumulator = await updateAccumulator(step, postScope, accumulator);
+    state.output = iterationState.output;
+  }
+
+  finalizeAccumulatorState(step, state, accumulator);
+
+  return undefined;
+}
+
+function finalizeAccumulatorState(
+  step: LoopStep,
+  state: ExecutionState,
+  accumulator: unknown,
+): void {
+  if (step.accumulate && step.name) {
+    state.output[step.name] = { [step.accumulate.as]: accumulator };
+  }
+
+  if (step.accumulate) {
+    state.accumulator = accumulator;
+  }
+}
+
+/**
+ * Update the loop accumulator using the configured merge expression.
+ *
+ * @param step The loop step containing accumulation settings.
+ * @param scope Current evaluation scope for expressions.
+ * @param previous Previous accumulator value to merge with.
+ * @returns The updated accumulator value.
+ */
+export async function updateAccumulator(
+  step: LoopStep,
+  scope: LoopScope,
+  previous: unknown,
+): Promise<unknown> {
+  if (!step.accumulate) {
+    return previous;
+  }
+
+  return evaluateValue(step.accumulate.merge, {
+    ...scope,
+    accumulator: previous,
+  });
+}
+
+/**
+ * Determine whether loop execution should stop based on the `until` condition.
+ *
+ * @param step The loop step configuration.
+ * @param scope Current evaluation scope for expressions.
+ * @returns True if the loop should stop, otherwise false.
+ */
+export async function shouldStopLoop(
+  step: LoopStep,
+  scope: LoopScope,
+): Promise<boolean> {
+  if (step.loopType !== 'for_each' || !step.until) {
+    return false;
+  }
+
+  const result = await evaluateValue(step.until, scope);
+
+  return Boolean(result);
+}
+
+/**
+ * Build the evaluation scope for loop iteration and accumulator updates.
+ *
+ * @param env Executor environment with workflow context.
+ * @param state Execution state for the current iteration.
+ * @param iteration The current iteration item and index.
+ * @param accumulator Accumulator value to expose to expressions.
+ * @returns An evaluation scope object.
+ */
+function buildScope(
+  env: StepExecutorEnv,
+  state: ExecutionState,
+  iteration: { item: unknown; index: number },
+  accumulator: unknown,
+): LoopScope {
+  return {
+    input: state.input,
+    context: env.context.state,
+    output: state.output,
+    iteration,
+    accumulator,
+  };
+}

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

@@ -0,0 +1,182 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { BaseWorkflowContext } from '../context';
+import type { RuntimeSuspensionRequest } from '../runner-runtime-control';
+import {
+  StepType,
+  type EventEmitterLike,
+  type StepInfo,
+} from '../workflow-event-emitter';
+import type {
+  CompiledStep,
+  ExecutionState,
+  ParallelStep,
+  Suspension,
+} from '../workflow-types';
+
+import { executeParallel } from './parallel-executor';
+import type { StepExecutorEnv } from './types';
+
+class TestContext extends BaseWorkflowContext {
+  public eventEmitter: EventEmitterLike = { emit: jest.fn(), on: jest.fn() };
+
+  constructor() {
+    super({});
+  }
+}
+
+const createState = (): ExecutionState => ({
+  input: {},
+  output: {},
+  iterationStack: [],
+});
+const createChild = (id: string): CompiledStep => ({
+  id,
+  type: StepType.Task,
+  label: id,
+  taskName: `task_${id}`,
+});
+const createEnv = (): StepExecutorEnv => {
+  const compiled = {
+    definition: {} as any,
+    tasks: {},
+    flow: [],
+    outputMapping: {},
+    inputParser: { parse: (value: unknown) => value } as any,
+  } as any;
+
+  return {
+    compiled,
+    context: new TestContext(),
+    runId: 'run-1',
+    buildInstanceStepInfo: jest.fn(),
+    markSnapshot: jest.fn(),
+    recordStepExecution: jest.fn(),
+    emit: jest.fn(),
+    setCurrentStep: jest.fn(),
+    waitForStepSuspension: jest
+      .fn()
+      .mockImplementation(
+        () => new Promise<RuntimeSuspensionRequest>(() => undefined),
+      ),
+    clearStepSuspensions: jest.fn(),
+    primeStepResumeData: jest.fn(),
+    captureTaskOutput: jest.fn(),
+    executeFlow: jest.fn(),
+    executeStep: jest.fn(),
+  };
+};
+
+describe('executeParallel', () => {
+  it('executes all children when using wait_all', async () => {
+    const env = createEnv();
+    const state = createState();
+    const step: ParallelStep = {
+      id: 'parallel',
+      type: StepType.Parallel,
+      label: 'parallel',
+      strategy: 'wait_all',
+      steps: [createChild('a'), createChild('b')],
+    };
+    env.executeStep = jest.fn().mockResolvedValue(undefined);
+
+    const result = await executeParallel(env, step, state, [0]);
+
+    expect(result).toBeUndefined();
+    expect(env.executeStep).toHaveBeenCalledTimes(2);
+    expect(env.executeStep).toHaveBeenNthCalledWith(1, step.steps[0], state, [
+      0,
+      'parallel',
+      0,
+    ]);
+    expect(env.executeStep).toHaveBeenNthCalledWith(2, step.steps[1], state, [
+      0,
+      'parallel',
+      1,
+    ]);
+  });
+
+  it('short-circuits on first completion when using wait_any', async () => {
+    const env = createEnv();
+    const state = createState();
+    const step: ParallelStep = {
+      id: 'parallel',
+      type: StepType.Parallel,
+      label: 'parallel',
+      strategy: 'wait_any',
+      steps: [createChild('a'), createChild('b')],
+    };
+    env.executeStep = jest.fn().mockResolvedValue(undefined);
+
+    const result = await executeParallel(env, step, state, []);
+
+    expect(result).toBeUndefined();
+    expect(env.executeStep).toHaveBeenCalledTimes(1);
+    expect(env.executeStep).toHaveBeenCalledWith(step.steps[0], state, [
+      'parallel',
+      0,
+    ]);
+  });
+
+  it('continues remaining steps after resuming from suspension (wait_all)', async () => {
+    const env = createEnv();
+    const state = createState();
+    const innerSuspension: Suspension = {
+      step: { id: 'a', name: 'a', type: StepType.Task } as StepInfo,
+      continue: jest.fn().mockResolvedValue(undefined),
+    };
+    const step: ParallelStep = {
+      id: 'parallel',
+      type: StepType.Parallel,
+      label: 'parallel',
+      strategy: 'wait_all',
+      steps: [createChild('a'), createChild('b')],
+    };
+    env.executeStep = jest
+      .fn()
+      .mockResolvedValueOnce(innerSuspension)
+      .mockResolvedValueOnce(undefined);
+
+    const suspension = await executeParallel(env, step, state, []);
+    expect(suspension).toEqual(
+      expect.objectContaining({ step: innerSuspension.step }),
+    );
+
+    const result = await suspension?.continue('resume-data');
+    expect(result).toBeUndefined();
+    expect(innerSuspension.continue).toHaveBeenCalledWith('resume-data');
+    expect(env.executeStep).toHaveBeenCalledTimes(2);
+    expect(env.executeStep).toHaveBeenLastCalledWith(step.steps[1], state, [
+      'parallel',
+      1,
+    ]);
+  });
+
+  it('stops after resuming a suspended child when using wait_any', async () => {
+    const env = createEnv();
+    const state = createState();
+    const innerSuspension: Suspension = {
+      step: { id: 'a', name: 'a', type: StepType.Task } as StepInfo,
+      continue: jest.fn().mockResolvedValue(undefined),
+    };
+    const step: ParallelStep = {
+      id: 'parallel',
+      type: StepType.Parallel,
+      label: 'parallel',
+      strategy: 'wait_any',
+      steps: [createChild('a'), createChild('b')],
+    };
+    env.executeStep = jest.fn().mockResolvedValueOnce(innerSuspension);
+
+    const suspension = await executeParallel(env, step, state, []);
+    const result = await suspension?.continue('resume-data');
+
+    expect(result).toBeUndefined();
+    expect(innerSuspension.continue).toHaveBeenCalledWith('resume-data');
+    expect(env.executeStep).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -0,0 +1,77 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type {
+  ExecutionState,
+  ParallelStep,
+  Suspension,
+} from '../workflow-types';
+
+import { markStepsSkipped } from './skip-helpers';
+import type { StepExecutorEnv } from './types';
+
+/**
+ * Execute a set of steps in parallel order, respecting the configured strategy.
+ *
+ * @param env Executor environment providing helpers and workflow context.
+ * @param step The parallel step definition including strategy and children.
+ * @param state Mutable workflow execution state.
+ * @param path Path tokens locating this parallel block in the workflow.
+ * @param startIndex Index to resume execution from when continuing.
+ * @returns A suspension if a child pauses execution, otherwise void.
+ */
+export async function executeParallel(
+  env: StepExecutorEnv,
+  step: ParallelStep,
+  state: ExecutionState,
+  path: Array<number | string>,
+  startIndex = 0,
+): Promise<Suspension | void> {
+  for (let index = startIndex; index < step.steps.length; index += 1) {
+    const child = step.steps[index];
+    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;
+          }
+
+          if (step.strategy === 'wait_any') {
+            if (index + 1 < step.steps.length) {
+              markStepsSkipped(
+                env,
+                step.steps.slice(index + 1),
+                state.iterationStack,
+              );
+            }
+
+            return undefined;
+          }
+
+          return executeParallel(env, step, state, path, index + 1);
+        },
+      };
+    }
+
+    if (step.strategy === 'wait_any') {
+      if (index + 1 < step.steps.length) {
+        markStepsSkipped(
+          env,
+          step.steps.slice(index + 1),
+          state.iterationStack,
+        );
+      }
+
+      return undefined;
+    }
+  }
+
+  return undefined;
+}

package/src/step-executors/skip-helpers.ts

@@ -0,0 +1,68 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type { ActionSnapshot } from '../context';
+import {
+  StepType,
+  type StepInfo,
+  type WorkflowEventMap,
+} from '../workflow-event-emitter';
+import type { CompiledStep } from '../workflow-types';
+
+type SkipStepEnv = {
+  runId?: string;
+  buildInstanceStepInfo: (
+    step: CompiledStep,
+    iterationStack: number[],
+  ) => StepInfo;
+  markSnapshot: (
+    step: StepInfo,
+    status: ActionSnapshot['status'],
+    reason?: string,
+  ) => void;
+  emit: <K extends keyof WorkflowEventMap>(
+    event: K,
+    payload: WorkflowEventMap[K],
+  ) => void;
+};
+
+const markStepSkipped = (
+  env: SkipStepEnv,
+  step: CompiledStep,
+  iterationStack: number[],
+  reason?: string,
+) => {
+  const stepInfo = env.buildInstanceStepInfo(step, iterationStack);
+  env.markSnapshot(stepInfo, 'skipped', reason);
+  env.emit('hook:step:skipped', { runId: env.runId, step: stepInfo, reason });
+
+  switch (step.type) {
+    case StepType.Parallel:
+      step.steps.forEach((child) =>
+        markStepSkipped(env, child, iterationStack, reason),
+      );
+      break;
+    case StepType.Conditional:
+      step.branches.forEach((branch) =>
+        branch.steps.forEach((child) =>
+          markStepSkipped(env, child, iterationStack, reason),
+        ),
+      );
+      break;
+    case StepType.Loop:
+    case StepType.Task:
+      break;
+  }
+};
+
+export const markStepsSkipped = (
+  env: SkipStepEnv,
+  steps: CompiledStep[],
+  iterationStack: number[],
+  reason?: string,
+) => {
+  steps.forEach((step) => markStepSkipped(env, step, iterationStack, reason));
+};