@hexabot-ai/agentic 3.1.2-alpha.9 → 3.1.2-beta.1

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

@@ -4,67 +4,435 @@
  * Full terms: see LICENSE.md.
  */
 
+import type { BaseWorkflowContext, WorkflowRuntimeControl } from '../context';
+import {
+  getAbortReason,
+  ParallelSuspensionError,
+  throwIfAborted,
+  WorkflowCancellationError,
+} from '../errors';
 import type {
+  CompiledStep,
   ExecutionState,
   ParallelStep,
   Suspension,
 } from '../workflow-types';
 
-import { markStepsSkipped } from './skip-helpers';
-import { wrapSuspensionContinuation } from './suspension-continuation';
+import { markStepsCancelled } from './skip-helpers';
 import type { StepExecutorEnv } from './types';
 
+type BranchResult =
+  | { status: 'fulfilled'; index: number; outputDelta: Record<string, unknown> }
+  | { status: 'failed'; index: number; error: unknown }
+  | { status: 'cancelled'; index: number; error: Error };
+
+type BranchHandle = {
+  index: number;
+  step: CompiledStep;
+  iterationStack: number[];
+  controller: AbortController;
+  promise: Promise<BranchResult>;
+};
+
+type TrackedOutput = {
+  output: Record<string, unknown>;
+  getDelta: () => Record<string, unknown>;
+};
+
 /**
- * Execute a set of steps in parallel order, respecting the configured strategy.
+ * Execute a set of child steps concurrently and resolve according to 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.
+ * @returns Always undefined; suspensions are rejected inside parallel blocks.
  */
 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 (step.steps.length === 0) {
+    return undefined;
+  }
+
+  throwIfAborted(env.signal);
+
+  const baseOutput = cloneRecord(state.output);
+  const baseContextState = cloneRecord(env.context.state);
+  const branches = step.steps.map((child, index) =>
+    launchBranch({
+      env,
+      child,
+      index,
+      path,
+      parentState: state,
+      baseOutput,
+      baseContextState,
+    }),
+  );
+
+  if (step.strategy === 'wait_any') {
+    return executeWaitAny(env, branches, state);
+  }
+
+  return executeWaitAll(env, branches, state);
+}
+
+async function executeWaitAll(
+  env: StepExecutorEnv,
+  branches: BranchHandle[],
+  state: ExecutionState,
+): Promise<void> {
+  const pending = new Set(branches);
+  const outcomes = new Map<number, BranchResult>();
+
+  while (pending.size > 0) {
+    const { branch, result } = await raceNext(pending);
+    pending.delete(branch);
+    outcomes.set(result.index, result);
+
+    if (result.status === 'failed' || result.status === 'cancelled') {
+      cancelBranches(
+        env,
+        pending,
+        result.error,
+        'Parallel branch execution was cancelled.',
+      );
+      await settleBranches(branches);
+      throw result.error;
+    }
+  }
+
+  mergeBranchOutputs(state, outcomes);
+}
+
+async function executeWaitAny(
+  env: StepExecutorEnv,
+  branches: BranchHandle[],
+  state: ExecutionState,
+): Promise<void> {
+  const pending = new Set(branches);
+  const outcomes = new Map<number, BranchResult>();
+
+  while (pending.size > 0) {
+    const { branch, result } = await raceNext(pending);
+    pending.delete(branch);
+    outcomes.set(result.index, result);
+
+    if (result.status === 'fulfilled') {
+      cancelBranches(
+        env,
+        pending,
+        new WorkflowCancellationError('Parallel wait_any winner selected.'),
+        'Parallel wait_any branch lost the race.',
+      );
+      await settleBranches(branches);
+      mergeBranchOutputs(state, new Map([[result.index, result]]));
+
+      return;
+    }
+
+    cancelBranches(
+      env,
+      pending,
+      result.error,
+      'Parallel branch execution was cancelled.',
+    );
+    await settleBranches(branches);
+    throw result.error;
+  }
+}
+
+function launchBranch({
+  env,
+  child,
+  index,
+  path,
+  parentState,
+  baseOutput,
+  baseContextState,
+}: {
+  env: StepExecutorEnv;
+  child: CompiledStep;
+  index: number;
+  path: Array<number | string>;
+  parentState: ExecutionState;
+  baseOutput: Record<string, unknown>;
+  baseContextState: Record<string, unknown>;
+}): BranchHandle {
+  const controller = createBranchController(env.signal);
+  const trackedOutput = createTrackedOutput(baseOutput);
+  const branchState: ExecutionState = {
+    input: parentState.input,
+    output: trackedOutput.output,
+    iteration: parentState.iteration ? { ...parentState.iteration } : undefined,
+    accumulator: cloneValue(parentState.accumulator),
+    iterationStack: [...parentState.iterationStack],
+  };
+  const branchContext = createParallelBranchContext(
+    env.context,
+    cloneRecord(baseContextState),
+  );
+  const branchEnv = env.fork({
+    context: branchContext,
+    signal: controller.signal,
+    setCurrentStep: () => undefined,
+  });
+  const childPath = [...path, 'parallel', index];
+  const promise = runBranch(
+    branchEnv,
+    child,
+    branchState,
+    childPath,
+    trackedOutput,
+    index,
+  );
+
+  return {
+    index,
+    step: child,
+    iterationStack: [...parentState.iterationStack],
+    controller,
+    promise,
+  };
+}
+
+async function runBranch(
+  env: StepExecutorEnv,
+  child: CompiledStep,
+  branchState: ExecutionState,
+  childPath: Array<number | string>,
+  trackedOutput: TrackedOutput,
+  index: number,
+): Promise<BranchResult> {
+  try {
+    throwIfAborted(env.signal);
+
+    const suspension = await env.executeStep(child, branchState, childPath);
     if (suspension) {
-      return wrapSuspensionContinuation(suspension, async () => {
-        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);
-      });
+      throw new ParallelSuspensionError();
+    }
+
+    throwIfAborted(env.signal);
+
+    return {
+      status: 'fulfilled',
+      index,
+      outputDelta: trackedOutput.getDelta(),
+    };
+  } catch (error) {
+    if (env.signal.aborted) {
+      return { status: 'cancelled', index, error: getAbortReason(env.signal) };
     }
 
-    if (step.strategy === 'wait_any') {
-      if (index + 1 < step.steps.length) {
-        markStepsSkipped(
-          env,
-          step.steps.slice(index + 1),
-          state.iterationStack,
-        );
+    return { status: 'failed', index, error };
+  }
+}
+
+async function raceNext(
+  pending: Set<BranchHandle>,
+): Promise<{ branch: BranchHandle; result: BranchResult }> {
+  return Promise.race(
+    [...pending].map((branch) =>
+      branch.promise.then((result) => ({ branch, result })),
+    ),
+  );
+}
+
+async function settleBranches(branches: BranchHandle[]): Promise<void> {
+  await Promise.all(branches.map((branch) => branch.promise.catch(() => null)));
+}
+
+function cancelBranches(
+  env: StepExecutorEnv,
+  branches: Iterable<BranchHandle>,
+  reason: unknown,
+  snapshotReason: string,
+): void {
+  for (const branch of branches) {
+    if (!branch.controller.signal.aborted) {
+      branch.controller.abort(
+        reason instanceof Error
+          ? reason
+          : new WorkflowCancellationError(String(reason)),
+      );
+    }
+
+    markStepsCancelled(
+      env,
+      [branch.step],
+      branch.iterationStack,
+      reason instanceof Error ? reason.message : snapshotReason,
+    );
+  }
+}
+
+function mergeBranchOutputs(
+  state: ExecutionState,
+  outcomes: Map<number, BranchResult>,
+): void {
+  const ordered = [...outcomes.values()].sort((left, right) => {
+    return left.index - right.index;
+  });
+
+  for (const outcome of ordered) {
+    if (outcome.status !== 'fulfilled') {
+      continue;
+    }
+
+    Object.assign(state.output, outcome.outputDelta);
+  }
+}
+
+function createBranchController(parentSignal: AbortSignal): AbortController {
+  const controller = new AbortController();
+
+  if (parentSignal.aborted) {
+    controller.abort(getAbortReason(parentSignal));
+
+    return controller;
+  }
+
+  parentSignal.addEventListener(
+    'abort',
+    () => controller.abort(getAbortReason(parentSignal)),
+    { once: true },
+  );
+
+  return controller;
+}
+
+function createTrackedOutput(
+  baseOutput: Record<string, unknown>,
+): TrackedOutput {
+  const writtenKeys = new Set<string>();
+  const target = cloneRecord(baseOutput);
+  const output = new Proxy(target, {
+    set(record, property, value) {
+      if (typeof property === 'string') {
+        writtenKeys.add(property);
       }
 
-      return undefined;
+      return Reflect.set(record, property, value);
+    },
+    deleteProperty(record, property) {
+      if (typeof property === 'string') {
+        writtenKeys.add(property);
+      }
+
+      return Reflect.deleteProperty(record, property);
+    },
+  });
+
+  return {
+    output,
+    getDelta: () =>
+      Object.fromEntries(
+        [...writtenKeys]
+          .filter((key) => Object.prototype.hasOwnProperty.call(target, key))
+          .map((key) => [key, target[key]]),
+      ),
+  };
+}
+
+class ParallelWorkflowRuntimeControl implements WorkflowRuntimeControl {
+  constructor(private readonly getParent: () => WorkflowRuntimeControl) {}
+
+  get status() {
+    return this.getParent().status;
+  }
+
+  get resumeData() {
+    return this.getParent().resumeData;
+  }
+
+  suspend<T = unknown>(): Promise<T> {
+    return Promise.reject(new ParallelSuspensionError());
+  }
+
+  resume(data?: unknown): void {
+    this.getParent().resume(data);
+  }
+
+  getSnapshot() {
+    return this.getParent().getSnapshot();
+  }
+}
+
+function createParallelBranchContext(
+  context: BaseWorkflowContext,
+  branchState: Record<string, unknown>,
+): BaseWorkflowContext {
+  let state = branchState;
+  const workflow = new ParallelWorkflowRuntimeControl(() => context.workflow);
+
+  return new Proxy(context, {
+    get(target, property, receiver) {
+      if (property === 'state') {
+        return state;
+      }
+
+      if (property === 'workflow') {
+        return workflow;
+      }
+
+      if (property === 'snapshot') {
+        return () => cloneRecord(state);
+      }
+
+      if (property === 'attachWorkflowRuntime') {
+        return () => undefined;
+      }
+
+      return Reflect.get(target, property, receiver);
+    },
+    set(target, property, value, receiver) {
+      if (property === 'state') {
+        state = isRecord(value) ? value : {};
+
+        return true;
+      }
+
+      return Reflect.set(target, property, value, receiver);
+    },
+  });
+}
+
+function cloneRecord(value: Record<string, unknown>): Record<string, unknown> {
+  return cloneValue(value) as Record<string, unknown>;
+}
+
+function cloneValue<T>(value: T): T {
+  if (value === undefined || value === null) {
+    return value;
+  }
+
+  if (typeof structuredClone === 'function') {
+    try {
+      return structuredClone(value);
+    } catch {
+      // Fall through to JSON clone below.
     }
   }
 
-  return undefined;
+  try {
+    return JSON.parse(JSON.stringify(value)) as T;
+  } catch {
+    if (Array.isArray(value)) {
+      return [...value] as T;
+    }
+
+    if (isRecord(value)) {
+      return { ...value } as T;
+    }
+
+    return value;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }

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

@@ -57,6 +57,38 @@ const markStepSkipped = (
       break;
   }
 };
+const markStepCancelled = (
+  env: SkipStepEnv,
+  step: CompiledStep,
+  iterationStack: number[],
+  reason?: string,
+) => {
+  const stepInfo = env.buildInstanceStepInfo(step, iterationStack);
+  env.markSnapshot(stepInfo, 'cancelled', reason);
+  env.emit('hook:step:cancelled', {
+    runId: env.runId,
+    step: stepInfo,
+    error: new Error(reason ?? 'Step execution was cancelled.'),
+  });
+
+  switch (step.type) {
+    case StepType.Parallel:
+      step.steps.forEach((child) =>
+        markStepCancelled(env, child, iterationStack, reason),
+      );
+      break;
+    case StepType.Conditional:
+      step.branches.forEach((branch) =>
+        branch.steps.forEach((child) =>
+          markStepCancelled(env, child, iterationStack, reason),
+        ),
+      );
+      break;
+    case StepType.Loop:
+    case StepType.Task:
+      break;
+  }
+};
 
 export const markStepsSkipped = (
   env: SkipStepEnv,
@@ -66,3 +98,12 @@ export const markStepsSkipped = (
 ) => {
   steps.forEach((step) => markStepSkipped(env, step, iterationStack, reason));
 };
+
+export const markStepsCancelled = (
+  env: SkipStepEnv,
+  steps: CompiledStep[],
+  iterationStack: number[],
+  reason?: string,
+) => {
+  steps.forEach((step) => markStepCancelled(env, step, iterationStack, reason));
+};

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

@@ -5,7 +5,7 @@
  */
 
 import type { Action } from '../action/action.types';
-import { BaseWorkflowContext } from '../context';
+import { BaseWorkflowContext, type StepExecutionRecord } from '../context';
 import type { RuntimeSuspensionRequest } from '../runner-runtime-control';
 import { createDeferred } from '../utils/deferred';
 import {
@@ -72,26 +72,59 @@ const createCompiled = (task: CompiledTask): CompiledWorkflow =>
 const createEnv = (
   compiled: CompiledWorkflow,
   stepInfo: StepInfo,
-): StepExecutorEnv => ({
-  compiled,
-  context: new TestContext(),
-  runId: 'run-123',
-  buildInstanceStepInfo: jest.fn().mockReturnValue(stepInfo),
-  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().mockResolvedValue(undefined),
-  executeFlow: jest.fn(),
-  executeStep: jest.fn(),
-});
+): StepExecutorEnv => {
+  const stepRecords: Record<string, StepExecutionRecord> = {};
+  const env = {
+    compiled,
+    context: new TestContext(),
+    signal: new AbortController().signal,
+    runId: 'run-123',
+    buildInstanceStepInfo: jest.fn().mockReturnValue(stepInfo),
+    markSnapshot: jest.fn(),
+    recordStepExecution: jest.fn((step, update) => {
+      const existing =
+        stepRecords[step.id] ??
+        ({
+          id: step.id,
+          name: step.name,
+          status: 'pending',
+        } satisfies StepExecutionRecord);
+      const context =
+        existing.context || update.context
+          ? { ...existing.context, ...update.context }
+          : undefined;
+      const nextRecord = {
+        ...existing,
+        ...update,
+        id: step.id,
+        name: step.name,
+        status: update.status ?? existing.status,
+        context,
+      } satisfies StepExecutionRecord;
+
+      stepRecords[step.id] = nextRecord;
+
+      return nextRecord;
+    }),
+    emit: jest.fn(),
+    setCurrentStep: jest.fn(),
+    waitForStepSuspension: jest
+      .fn()
+      .mockImplementation(
+        () => new Promise<RuntimeSuspensionRequest>(() => undefined),
+      ),
+    clearStepSuspensions: jest.fn(),
+    primeStepResumeData: jest.fn(),
+    captureTaskOutput: jest.fn().mockResolvedValue(undefined),
+    executeFlow: jest.fn(),
+    executeStep: jest.fn(),
+    fork: jest.fn(),
+  } as StepExecutorEnv;
+
+  env.fork = jest.fn((overrides) => ({ ...env, ...overrides }));
+
+  return env;
+};
 const step: TaskStep = {
   id: '0:test_task',
   type: StepType.Task,
@@ -122,6 +155,7 @@ describe('executeTaskStep', () => {
       env.context,
       task.settings,
       task.bindings,
+      env.signal,
     );
     expect(env.setCurrentStep).toHaveBeenNthCalledWith(1, stepInfo);
     expect(env.markSnapshot).toHaveBeenNthCalledWith(1, stepInfo, 'running');
@@ -153,10 +187,18 @@ describe('executeTaskStep', () => {
     expect(env.emit).toHaveBeenCalledWith('hook:step:start', {
       runId: 'run-123',
       step: stepInfo,
+      stepExecution: expect.objectContaining({
+        id: stepInfo.id,
+        status: 'running',
+      }),
     });
     expect(env.emit).toHaveBeenCalledWith('hook:step:success', {
       runId: 'run-123',
       step: stepInfo,
+      stepExecution: expect.objectContaining({
+        id: stepInfo.id,
+        status: 'completed',
+      }),
     });
     expect(env.setCurrentStep).toHaveBeenLastCalledWith(undefined);
   });
@@ -215,6 +257,16 @@ describe('executeTaskStep', () => {
       'suspended',
       'awaiting_user',
     );
+    expect(env.emit).toHaveBeenCalledWith('hook:step:suspended', {
+      runId: 'run-123',
+      step: stepInfo,
+      stepExecution: expect.objectContaining({
+        id: stepInfo.id,
+        status: 'suspended',
+      }),
+      reason: 'awaiting_user',
+      data: { channel: 'sms' },
+    });
 
     await suspension?.continue({ reply: 'Sure' });
 
@@ -228,6 +280,14 @@ describe('executeTaskStep', () => {
         output: { reply: 'SURE' },
       }),
     );
+    expect(env.emit).toHaveBeenCalledWith('hook:step:success', {
+      runId: 'run-123',
+      step: stepInfo,
+      stepExecution: expect.objectContaining({
+        id: stepInfo.id,
+        status: 'completed',
+      }),
+    });
   });
 
   it('marks failure and rethrows errors from the task', async () => {
@@ -250,6 +310,10 @@ describe('executeTaskStep', () => {
     expect(env.emit).toHaveBeenCalledWith('hook:step:error', {
       runId: 'run-123',
       step: stepInfo,
+      stepExecution: expect.objectContaining({
+        id: stepInfo.id,
+        status: 'failed',
+      }),
       error: expect.any(Error),
     });
     expect(env.setCurrentStep).toHaveBeenLastCalledWith(undefined);