@hexabot-ai/agentic 3.0.1-alpha.0

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

@@ -0,0 +1,257 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type { Action } from '../action/action.types';
+import { BaseWorkflowContext } from '../context';
+import type { RuntimeSuspensionRequest } from '../runner-runtime-control';
+import { createDeferred } from '../utils/deferred';
+import {
+  type EventEmitterLike,
+  type StepInfo,
+  StepType,
+} from '../workflow-event-emitter';
+import type {
+  CompiledTask,
+  CompiledWorkflow,
+  ExecutionState,
+  TaskStep,
+} from '../workflow-types';
+
+import { executeTaskStep } from './task-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 createAction = (
+  impl: jest.Mock,
+): Action<unknown, unknown, BaseWorkflowContext, any> =>
+  ({
+    name: 'mock_action',
+    description: 'runs a task',
+    inputSchema: {} as any,
+    outputSchema: {} as any,
+    execute: jest.fn(),
+    parseInput: jest.fn(),
+    parseOutput: jest.fn(),
+    parseSettings: jest.fn(),
+    run: impl,
+  }) as Action<unknown, unknown, BaseWorkflowContext, any>;
+const createTask = (runImpl: jest.Mock): CompiledTask => ({
+  name: 'test_task',
+  definition: {} as any,
+  actionName: 'mock_action',
+  action: createAction(runImpl),
+  inputs: { payload: { kind: 'literal', value: 123 } },
+  settings: {} as any,
+  bindings: {
+    tools: { calculate: { action: 'calculate_score', settings: {} } },
+  },
+});
+const createCompiled = (task: CompiledTask): CompiledWorkflow =>
+  ({
+    definition: {} as any,
+    tasks: { [task.name]: task },
+    flow: [],
+    outputMapping: {},
+    inputParser: { parse: (value: unknown) => value } as any,
+  }) as 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(),
+});
+const step: TaskStep = {
+  id: '0:test_task',
+  type: StepType.Task,
+  label: 'test_task',
+  taskName: 'test_task',
+};
+const stepInfo: StepInfo = {
+  id: step.id,
+  name: step.label,
+  type: StepType.Task,
+};
+
+describe('executeTaskStep', () => {
+  it('runs the task, records snapshots, and emits success events', async () => {
+    const task = createTask(jest.fn().mockResolvedValue({ result: 'ok' }));
+    const compiled = createCompiled(task);
+    const env = createEnv(compiled, stepInfo);
+    const state = createState();
+    const result = await executeTaskStep(env, step, state, []);
+
+    expect(result).toBeUndefined();
+    expect(env.buildInstanceStepInfo).toHaveBeenCalledWith(
+      step,
+      state.iterationStack,
+    );
+    expect(task.action.run).toHaveBeenCalledWith(
+      { payload: 123 },
+      env.context,
+      task.settings,
+      task.bindings,
+    );
+    expect(env.setCurrentStep).toHaveBeenNthCalledWith(1, stepInfo);
+    expect(env.markSnapshot).toHaveBeenNthCalledWith(1, stepInfo, 'running');
+    expect(env.markSnapshot).toHaveBeenNthCalledWith(2, stepInfo, 'completed');
+    expect(env.recordStepExecution).toHaveBeenNthCalledWith(
+      1,
+      stepInfo,
+      expect.objectContaining({
+        action: 'mock_action',
+        status: 'running',
+        startedAt: expect.any(Number),
+        input: { payload: 123 },
+        context: { before: {} },
+      }),
+    );
+    expect(env.recordStepExecution).toHaveBeenNthCalledWith(
+      2,
+      stepInfo,
+      expect.objectContaining({
+        status: 'completed',
+        endedAt: expect.any(Number),
+        output: { result: 'ok' },
+        context: { after: {} },
+      }),
+    );
+    expect(env.captureTaskOutput).toHaveBeenCalledWith(task, state, {
+      result: 'ok',
+    });
+    expect(env.emit).toHaveBeenCalledWith('hook:step:start', {
+      runId: 'run-123',
+      step: stepInfo,
+    });
+    expect(env.emit).toHaveBeenCalledWith('hook:step:success', {
+      runId: 'run-123',
+      step: stepInfo,
+    });
+    expect(env.setCurrentStep).toHaveBeenLastCalledWith(undefined);
+  });
+
+  it('throws when the task is missing', async () => {
+    const compiled = createCompiled(createTask(jest.fn()));
+    compiled.tasks = {};
+    const env = createEnv(compiled, stepInfo);
+    const state = createState();
+
+    await expect(executeTaskStep(env, step, state, [])).rejects.toThrow(
+      'Task "test_task" is not defined.',
+    );
+    expect(env.buildInstanceStepInfo).not.toHaveBeenCalled();
+  });
+
+  it('resumes an in-flight action and captures post-suspend output', async () => {
+    const request: RuntimeSuspensionRequest = {
+      stepId: step.id,
+      stepExecId: `${step.id}#1`,
+      suspendIndex: 1,
+      suspendKey: 'index:1',
+      reason: 'awaiting_user',
+      data: { channel: 'sms' },
+      awaitResults: {},
+      resume: createDeferred<unknown>(),
+    };
+    const task = createTask(
+      jest.fn().mockImplementation(async () => {
+        const resumed = (await request.resume.promise) as { reply: string };
+
+        return { reply: resumed.reply.toUpperCase() };
+      }),
+    );
+    const compiled = createCompiled(task);
+    const env = createEnv(compiled, stepInfo);
+    const state = createState();
+
+    (env.waitForStepSuspension as jest.Mock)
+      .mockResolvedValueOnce(request)
+      .mockImplementationOnce(
+        () => new Promise<RuntimeSuspensionRequest>(() => undefined),
+      );
+
+    const suspension = await executeTaskStep(env, step, state, []);
+
+    expect(suspension).toEqual(
+      expect.objectContaining({
+        step: stepInfo,
+        reason: 'awaiting_user',
+        data: { channel: 'sms' },
+      }),
+    );
+    expect(env.markSnapshot).toHaveBeenCalledWith(
+      stepInfo,
+      'suspended',
+      'awaiting_user',
+    );
+
+    await suspension?.continue({ reply: 'Sure' });
+
+    expect(env.captureTaskOutput).toHaveBeenCalledWith(task, state, {
+      reply: 'SURE',
+    });
+    expect(env.recordStepExecution).toHaveBeenCalledWith(
+      stepInfo,
+      expect.objectContaining({
+        status: 'completed',
+        output: { reply: 'SURE' },
+      }),
+    );
+  });
+
+  it('marks failure and rethrows errors from the task', async () => {
+    const task = createTask(jest.fn().mockRejectedValue(new Error('boom')));
+    const compiled = createCompiled(task);
+    const env = createEnv(compiled, stepInfo);
+    const state = createState();
+
+    await expect(executeTaskStep(env, step, state, [])).rejects.toThrow('boom');
+    expect(env.recordStepExecution).toHaveBeenCalledWith(
+      stepInfo,
+      expect.objectContaining({
+        status: 'failed',
+        endedAt: expect.any(Number),
+        error: { message: 'boom', stack: expect.any(String) },
+        context: { after: {} },
+      }),
+    );
+    expect(env.markSnapshot).toHaveBeenCalledWith(stepInfo, 'failed', 'boom');
+    expect(env.emit).toHaveBeenCalledWith('hook:step:error', {
+      runId: 'run-123',
+      step: stepInfo,
+      error: expect.any(Error),
+    });
+    expect(env.setCurrentStep).toHaveBeenLastCalledWith(undefined);
+  });
+});

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

@@ -0,0 +1,248 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type { RuntimeSuspensionRequest } from '../runner-runtime-control';
+import type {
+  CompiledTask,
+  EvaluationScope,
+  ExecutionState,
+  Suspension,
+  TaskStep,
+} from '../workflow-types';
+import { evaluateMapping } from '../workflow-values';
+
+import type { StepExecutorEnv } from './types';
+
+type TaskProgressOutcome =
+  | { type: 'completed'; value: unknown }
+  | { type: 'failed'; error: unknown }
+  | { type: 'suspended'; request: RuntimeSuspensionRequest };
+
+/**
+ * Execute a task step by running its task and handling suspension or output mapping.
+ *
+ * @param env Executor environment with compiled workflow and helpers.
+ * @param step The compiled task step to execute.
+ * @param state Mutable workflow execution state.
+ * @param _path Location of the step within the workflow (unused in this executor).
+ * @returns A suspension if the task pauses execution, otherwise void.
+ */
+export async function executeTaskStep(
+  env: StepExecutorEnv,
+  step: TaskStep,
+  state: ExecutionState,
+  _path: Array<number | string>,
+): Promise<Suspension | void> {
+  void _path;
+  const task = env.compiled.tasks[step.taskName];
+  if (!task) {
+    throw new Error(`Task "${step.taskName}" is not defined.`);
+  }
+
+  const stepInfo = env.buildInstanceStepInfo(step, state.iterationStack);
+  const scope: EvaluationScope = {
+    input: state.input,
+    context: env.context.state,
+    output: state.output,
+    iteration: state.iteration,
+    accumulator: state.accumulator,
+  };
+  const inputs = await evaluateMapping(task.inputs, scope);
+  env.recordStepExecution(stepInfo, {
+    action: task.actionName,
+    status: 'running',
+    startedAt: Date.now(),
+    input: inputs,
+    context: { before: env.context.snapshot() },
+  });
+  env.beginStepExecution?.(stepInfo.id);
+  env.setCurrentStep(stepInfo);
+  env.markSnapshot(stepInfo, 'running');
+  env.emit('hook:step:start', { runId: env.runId, step: stepInfo });
+
+  try {
+    const actionPromise = Promise.resolve().then(() =>
+      task.action.run(inputs, env.context, task.settings, task.bindings),
+    );
+    const outcome = await waitForTaskProgress(env, stepInfo.id, actionPromise);
+
+    if (outcome.type === 'completed') {
+      await completeTask(
+        env,
+        stepInfo.id,
+        stepInfo,
+        task,
+        state,
+        outcome.value,
+      );
+
+      return undefined;
+    }
+
+    if (outcome.type === 'failed') {
+      env.clearStepSuspensions(stepInfo.id, outcome.error);
+      recordTaskFailure(env, stepInfo, outcome.error);
+      throw outcome.error;
+    }
+
+    return buildSuspensionContinuation(
+      env,
+      stepInfo.id,
+      stepInfo,
+      task,
+      state,
+      actionPromise,
+      outcome.request,
+    );
+  } finally {
+    env.setCurrentStep(undefined);
+  }
+}
+
+const waitForTaskProgress = async (
+  env: StepExecutorEnv,
+  stepId: string,
+  actionPromise: Promise<unknown>,
+): Promise<TaskProgressOutcome> => {
+  const completion = actionPromise.then(
+    (value): TaskProgressOutcome => ({ type: 'completed', value }),
+    (error): TaskProgressOutcome => ({ type: 'failed', error }),
+  );
+  const suspension = env
+    .waitForStepSuspension(stepId)
+    .then<TaskProgressOutcome>((request) => ({ type: 'suspended', request }));
+
+  return Promise.race([completion, suspension]);
+};
+const completeTask = async (
+  env: StepExecutorEnv,
+  stepId: string,
+  stepInfo: Suspension['step'],
+  task: CompiledTask,
+  state: ExecutionState,
+  result: unknown,
+) => {
+  await env.captureTaskOutput(task, state, result);
+  env.recordStepExecution(stepInfo, {
+    status: 'completed',
+    endedAt: Date.now(),
+    output: result,
+    context: { after: env.context.snapshot() },
+  });
+  env.markSnapshot(stepInfo, 'completed');
+  env.emit('hook:step:success', { runId: env.runId, step: stepInfo });
+  env.clearStepSuspensions(stepId);
+};
+const recordSuspension = (
+  env: StepExecutorEnv,
+  stepInfo: Suspension['step'],
+  reason?: string,
+  data?: unknown,
+) => {
+  env.recordStepExecution(stepInfo, {
+    status: 'suspended',
+    endedAt: Date.now(),
+    reason,
+    context: { after: env.context.snapshot() },
+  });
+  env.markSnapshot(stepInfo, 'suspended', reason);
+  env.emit('hook:step:suspended', {
+    runId: env.runId,
+    step: stepInfo,
+    reason,
+    data,
+  });
+};
+const buildSuspensionContinuation = (
+  env: StepExecutorEnv,
+  stepId: string,
+  stepInfo: Suspension['step'],
+  task: CompiledTask,
+  state: ExecutionState,
+  actionPromise: Promise<unknown>,
+  request: RuntimeSuspensionRequest,
+): Suspension => {
+  recordSuspension(env, stepInfo, request.reason, request.data);
+
+  let resumed = false;
+
+  return {
+    step: stepInfo,
+    reason: request.reason,
+    data: request.data,
+    stepExecId: request.stepExecId,
+    suspendIndex: request.suspendIndex,
+    suspendKey: request.suspendKey,
+    awaitResults: request.awaitResults,
+    continue: async (resumeData: unknown) => {
+      if (resumed) {
+        throw new Error(
+          `Suspension for step "${stepInfo.id}" has already been resumed.`,
+        );
+      }
+
+      resumed = true;
+      env.setCurrentStep(stepInfo);
+      env.recordStepSuspendResult?.({
+        stepId,
+        stepExecId: request.stepExecId,
+        suspendIndex: request.suspendIndex,
+        suspendKey: request.suspendKey,
+        resumeData,
+      });
+      request.resume.resolve(resumeData);
+
+      let outcome: TaskProgressOutcome;
+      try {
+        outcome = await waitForTaskProgress(env, stepId, actionPromise);
+      } finally {
+        env.setCurrentStep(undefined);
+      }
+
+      if (outcome.type === 'suspended') {
+        return buildSuspensionContinuation(
+          env,
+          stepId,
+          stepInfo,
+          task,
+          state,
+          actionPromise,
+          outcome.request,
+        );
+      }
+
+      if (outcome.type === 'completed') {
+        await completeTask(env, stepId, stepInfo, task, state, outcome.value);
+
+        return undefined;
+      }
+
+      env.clearStepSuspensions(stepId, outcome.error);
+      recordTaskFailure(env, stepInfo, outcome.error);
+      throw outcome.error;
+    },
+  };
+};
+const recordTaskFailure = (
+  env: StepExecutorEnv,
+  stepInfo: Suspension['step'],
+  error: unknown,
+) => {
+  env.recordStepExecution(stepInfo, {
+    status: 'failed',
+    endedAt: Date.now(),
+    error: normalizeError(error),
+    context: { after: env.context.snapshot() },
+  });
+  env.markSnapshot(stepInfo, 'failed', normalizeErrorMessage(error));
+  env.emit('hook:step:error', { runId: env.runId, step: stepInfo, error });
+};
+const normalizeError = (error: unknown): { message: string; stack?: string } =>
+  error instanceof Error
+    ? { message: error.message, stack: error.stack }
+    : { message: String(error) };
+const normalizeErrorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);

package/src/step-executors/types.ts

@@ -0,0 +1,70 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type {
+  ActionSnapshot,
+  BaseWorkflowContext,
+  StepExecutionRecord,
+} from '../context';
+import type {
+  RuntimeResolvedSuspension,
+  RuntimeStepReplaySeed,
+  RuntimeSuspensionRequest,
+} from '../runner-runtime-control';
+import type { StepInfo, WorkflowEventMap } from '../workflow-event-emitter';
+import type {
+  CompiledStep,
+  CompiledTask,
+  CompiledWorkflow,
+  ExecutionState,
+  Suspension,
+} from '../workflow-types';
+
+export type StepExecutorEnv = {
+  compiled: CompiledWorkflow;
+  context: BaseWorkflowContext;
+  runId?: string;
+  buildInstanceStepInfo: (
+    step: CompiledStep,
+    iterationStack: number[],
+  ) => StepInfo;
+  markSnapshot: (
+    step: StepInfo,
+    status: ActionSnapshot['status'],
+    reason?: string,
+  ) => void;
+  recordStepExecution: (
+    step: StepInfo,
+    update: Partial<StepExecutionRecord>,
+  ) => void;
+  emit: <K extends keyof WorkflowEventMap>(
+    event: K,
+    payload: WorkflowEventMap[K],
+  ) => void;
+  setCurrentStep: (step?: StepInfo) => void;
+  beginStepExecution?: (stepId: string) => string;
+  waitForStepSuspension: (stepId: string) => Promise<RuntimeSuspensionRequest>;
+  clearStepSuspensions: (stepId: string, error?: unknown) => void;
+  primeStepResumeData: (stepId: string, resumeData: unknown) => void;
+  prepareStepReplay?: (seed: RuntimeStepReplaySeed) => void;
+  recordStepSuspendResult?: (params: RuntimeResolvedSuspension) => void;
+  captureTaskOutput: (
+    task: CompiledTask,
+    state: ExecutionState,
+    result: unknown,
+  ) => Promise<void>;
+  executeFlow: (
+    steps: CompiledStep[],
+    state: ExecutionState,
+    path: Array<number | string>,
+    startIndex?: number,
+  ) => Promise<Suspension | void>;
+  executeStep: (
+    step: CompiledStep,
+    state: ExecutionState,
+    path: Array<number | string>,
+  ) => Promise<Suspension | void>;
+};