@hexabot-ai/agentic 3.0.1-alpha.0

package/examples/suspend-resume/actions/wait-for-user.ts

@@ -0,0 +1,51 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { defineAction, type Settings } from '../../../src';
+import type { SuspendResumeContext } from '../context';
+
+const inputSchema = z.object({
+  prompt: z.string(),
+});
+const resumeSchema = z.object({
+  reply: z.string(),
+});
+const outputSchema = z.object({
+  reply: z.string(),
+});
+
+type WaitForUserInput = z.infer<typeof inputSchema>;
+type WaitForUserOutput = z.infer<typeof outputSchema>;
+
+export const waitForUser = defineAction<
+  WaitForUserInput,
+  WaitForUserOutput,
+  SuspendResumeContext,
+  Settings
+>({
+  name: 'wait_for_user',
+  description: 'Pause execution until a reply is provided to the resume call.',
+  inputSchema,
+  outputSchema,
+  execute: async ({ input, context }) => {
+    context.log('Suspending workflow until we get a reply', {
+      prompt: input.prompt,
+    });
+
+    const resumeData = await context.workflow.suspend({
+      reason: 'awaiting_user',
+      data: { prompt: input.prompt },
+    });
+    const parsed = resumeSchema.safeParse(resumeData);
+    if (!parsed.success) {
+      throw new Error('resumeData must include a string reply');
+    }
+
+    return { reply: parsed.data.reply };
+  },
+});

package/examples/suspend-resume/context.ts

@@ -0,0 +1,32 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  BaseWorkflowContext,
+  WorkflowEventEmitter,
+  type WorkflowEventEmitterLike,
+} from '../../src';
+
+export type SuspendResumeContextState = {
+  channel: string;
+};
+
+export class SuspendResumeContext extends BaseWorkflowContext<SuspendResumeContextState> {
+  public eventEmitter: WorkflowEventEmitterLike<WorkflowEventEmitter>;
+
+  constructor(
+    state: SuspendResumeContextState,
+    eventEmitter: WorkflowEventEmitterLike<WorkflowEventEmitter> = new WorkflowEventEmitter(),
+  ) {
+    super(state);
+    this.eventEmitter = eventEmitter;
+  }
+
+  log(message: string, payload?: unknown): void {
+    const suffix = payload === undefined ? '' : ` ${JSON.stringify(payload)}`;
+    console.log(`[suspend/resume] ${message}${suffix}`);
+  }
+}

package/examples/suspend-resume/workflow.ts

@@ -0,0 +1,79 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+import { Workflow, WorkflowEventEmitter } from '../../src';
+
+import { suspendResumeActions } from './actions';
+import { SuspendResumeContext } from './context';
+
+const workflowPath = path.join(__dirname, 'workflow.yml');
+
+async function main() {
+  const yamlSource = fs.readFileSync(workflowPath, 'utf8');
+  const workflow = Workflow.fromYaml(yamlSource, {
+    actions: suspendResumeActions,
+  });
+  const emitter = new WorkflowEventEmitter();
+  const context = new SuspendResumeContext({ channel: 'chat' }, emitter);
+
+  emitter.on('hook:workflow:start', () => context.log('workflow started'));
+  emitter.on('hook:workflow:suspended', ({ step, reason, data }) =>
+    context.log(`workflow suspended at "${step.name}"`, { reason, data }),
+  );
+  emitter.on('hook:workflow:finish', ({ output }) =>
+    context.log('workflow finished', output),
+  );
+
+  const runner = await workflow.buildAsyncRunner();
+  const startResult = await runner.start({
+    inputData: {
+      question: "Can we deploy to production after today's smoke tests?",
+    },
+    context,
+  });
+
+  if (startResult.status === 'finished') {
+    context.log('finished without suspending', startResult.output);
+
+    return;
+  }
+
+  if (startResult.status === 'failed') {
+    console.error('Workflow failed', startResult.error);
+
+    return;
+  }
+
+  context.log('persist this snapshot to resume later', startResult.snapshot);
+
+  const resumeResult = await runner.resume({
+    resumeData: { reply: 'Yes, proceed once monitoring is green.' },
+  });
+
+  if (resumeResult.status === 'finished') {
+    context.log('resumed and completed', resumeResult.output);
+
+    return;
+  }
+
+  if (resumeResult.status === 'suspended') {
+    context.log('suspended again', {
+      step: resumeResult.step.name,
+      reason: resumeResult.reason,
+      data: resumeResult.data,
+    });
+
+    return;
+  }
+
+  console.error('Workflow failed after resume', resumeResult.error);
+}
+
+// pnpm dlx ts-node packages/agentic/examples/suspend-resume/workflow.ts
+void main();

package/examples/suspend-resume/workflow.yml

@@ -0,0 +1,29 @@
+# Minimal flow that pauses until an external reply is supplied.
+inputs:
+  schema:
+    question:
+      type: string
+      description: "Prompt shown to the user when the workflow suspends."
+
+defs:
+  wait_for_confirmation:
+    kind: task
+    description: "Sends a prompt and suspends until the reply is provided via resume."
+    action: wait_for_user
+    inputs:
+      prompt: "=$input.question"
+
+  format_acknowledgement:
+    kind: task
+    description: "Formats a message using the reply captured after resuming the run."
+    action: format_reply
+    inputs:
+      reply: "=$output.wait_for_confirmation.reply"
+
+flow:
+  - do: wait_for_confirmation
+  - do: format_acknowledgement
+
+outputs:
+  user_reply: "=$output.wait_for_confirmation.reply"
+  message: "=$output.format_acknowledgement.message"

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@hexabot-ai/agentic",
+  "version": "3.0.1-alpha.0",
+  "description": "Schemas and utilities for the Hexabot agentic workflow DSL.",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "examples",
+    "src"
+  ],
+  "dependencies": {
+    "jsonata": "^2.1.0",
+    "yaml": "^2.5.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.46.0",
+    "@typescript-eslint/parser": "^8.46.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.7.4",
+    "eslint": "^9.37.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-header": "^3.1.1",
+    "eslint-plugin-import": "^2.32.0",
+    "lint-staged": "^15.3.0",
+    "prettier": "^3.6.2",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.6.2"
+  },
+  "lint-staged": {
+    "*.{ts}": "eslint --fix --config eslint.config-staged.cjs"
+  },
+  "engines": {
+    "node": ">=20.18.1"
+  },
+  "license": "FCL-1.0-ALv2",
+  "scripts": {
+    "build": "pnpm run build:cjs && pnpm run build:esm",
+    "build:cjs": "tsc -p tsconfig.build.cjs.json",
+    "build:esm": "tsc -p tsconfig.build.esm.json",
+    "dev": "pnpm run build:watch",
+    "build:watch": "tsc -p tsconfig.json --watch",
+    "lint": "eslint \"{src,examples}/**/*.ts\" \"jest.config.ts\"",
+    "lint:fix": "eslint \"{src,examples}/**/*.ts\" \"jest.config.ts\" --fix",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "jest --config jest.config.ts"
+  }
+}

package/src/__tests__/parser.test.ts

@@ -0,0 +1,95 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { WorkflowDefinitionSchema } from '../dsl.types';
+
+describe('WorkflowDefinitionSchema', () => {
+  it('parses a minimal valid workflow', () => {
+    const minimal = {
+      defs: {
+        noop: { kind: 'task', action: 'call' },
+      },
+      flow: [{ do: 'noop' }],
+      outputs: { result: '=$output.noop' },
+    };
+
+    expect(() => WorkflowDefinitionSchema.parse(minimal)).not.toThrow();
+  });
+
+  it('rejects workflows with invalid JSONata expressions', () => {
+    const invalid = {
+      defs: {
+        noop: { kind: 'task', action: 'call' },
+      },
+      flow: [{ do: 'noop' }],
+      outputs: { result: '=$sum([1,2' }, // missing closing bracket makes JSONata invalid
+    };
+
+    expect(() => WorkflowDefinitionSchema.parse(invalid)).toThrow(
+      /Invalid JSONata expression/,
+    );
+  });
+
+  it('rejects task output mappings', () => {
+    const invalid = {
+      defs: {
+        noop: { kind: 'task', action: 'call', outputs: { value: '=1' } },
+      },
+      flow: [{ do: 'noop' }],
+      outputs: { result: '=$output.noop' },
+    };
+
+    expect(() => WorkflowDefinitionSchema.parse(invalid)).toThrow(
+      /Unrecognized key/i,
+    );
+  });
+
+  it('parses workflows with defs and task bindings', () => {
+    const workflow = {
+      defs: {
+        calculate: {
+          kind: 'tools',
+          action: 'calculate_score',
+          settings: { multiplier: 2 },
+        },
+        agent_step: {
+          kind: 'task',
+          action: 'ai_agent',
+          bindings: {
+            tools: ['calculate'],
+          },
+        },
+      },
+      flow: [{ do: 'agent_step' }],
+      outputs: { result: '=$output.agent_step' },
+    };
+
+    expect(() => WorkflowDefinitionSchema.parse(workflow)).not.toThrow();
+  });
+
+  it('rejects malformed task bindings definitions', () => {
+    const invalid = {
+      defs: {
+        calculate: {
+          kind: 'tools',
+          action: 'calculate_score',
+          settings: {},
+        },
+        agent_step: {
+          kind: 'task',
+          action: 'ai_agent',
+          bindings: {
+            tools: 42,
+          },
+        },
+      },
+      flow: [{ do: 'agent_step' }],
+      outputs: { result: '=$output.agent_step' },
+    };
+
+    expect(() => WorkflowDefinitionSchema.parse(invalid)).toThrow();
+  });
+});

package/src/__tests__/suspension-rebuilder.test.ts

@@ -0,0 +1,361 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import type { Action } from '../action/action.types';
+import { BaseWorkflowContext } from '../context';
+import type {
+  Settings,
+  TaskDefinition,
+  WorkflowDefinition,
+} from '../dsl.types';
+import {
+  executeLoop as runLoopExecutor,
+  shouldStopLoop,
+  updateAccumulator,
+} from '../step-executors/loop-executor';
+import { executeParallel as runParallelExecutor } from '../step-executors/parallel-executor';
+import type { StepExecutorEnv } from '../step-executors/types';
+import {
+  parseSuspendedStepId,
+  rebuildSuspension,
+  type SuspensionRebuilderDeps,
+} from '../suspension-rebuilder';
+import { type EventEmitterLike, StepType } from '../workflow-event-emitter';
+import type {
+  CompiledStep,
+  CompiledTask,
+  CompiledWorkflow,
+  ExecutionState,
+} from '../workflow-types';
+
+jest.mock('../step-executors/loop-executor', () => ({
+  __esModule: true,
+  executeLoop: jest.fn(),
+  updateAccumulator: jest.fn(),
+  shouldStopLoop: jest.fn(),
+}));
+
+jest.mock('../step-executors/parallel-executor', () => ({
+  __esModule: true,
+  executeParallel: jest.fn(),
+}));
+
+const mockedRunLoopExecutor = runLoopExecutor as jest.MockedFunction<
+  typeof runLoopExecutor
+>;
+const mockedUpdateAccumulator = updateAccumulator as jest.MockedFunction<
+  typeof updateAccumulator
+>;
+const mockedShouldStopLoop = shouldStopLoop as jest.MockedFunction<
+  typeof shouldStopLoop
+>;
+const mockedRunParallelExecutor = runParallelExecutor as jest.MockedFunction<
+  typeof runParallelExecutor
+>;
+
+class TestContext extends BaseWorkflowContext {
+  public eventEmitter: EventEmitterLike = { emit: jest.fn(), on: jest.fn() };
+
+  constructor(initial: Record<string, unknown>) {
+    super(initial);
+  }
+}
+
+const dummyAction: Action<unknown, unknown, BaseWorkflowContext, Settings> = {
+  name: 'dummy',
+  description: 'dummy',
+  inputSchema: z.any(),
+  outputSchema: z.any(),
+  execute: jest.fn(),
+  parseInput: (value) => value as unknown,
+  parseOutput: (value) => value as unknown,
+  parseSettings: (value) => value as Settings,
+  run: jest.fn(),
+};
+const buildStepInfo = (step: CompiledStep, iterationStack: number[]) => ({
+  id: `${step.id}${
+    iterationStack.length > 0 ? `[${iterationStack.join('.')}]` : ''
+  }`,
+  name: step.label,
+  type: step.type,
+});
+const createCompiledWorkflow = (
+  flow: CompiledStep[],
+  tasks: Record<string, CompiledTask>,
+): CompiledWorkflow =>
+  ({
+    definition: {} as WorkflowDefinition,
+    tasks,
+    flow,
+    outputMapping: {},
+    inputParser: { parse: (value: unknown) => value },
+  }) as CompiledWorkflow;
+const createDeps = (
+  compiled: CompiledWorkflow,
+  overrides?: Partial<SuspensionRebuilderDeps>,
+): SuspensionRebuilderDeps => {
+  const context = overrides?.context ?? new TestContext({});
+  const captureTaskOutput =
+    overrides?.captureTaskOutput ?? jest.fn().mockResolvedValue(undefined);
+  const markSnapshot =
+    overrides?.markSnapshot ??
+    (jest.fn() as SuspensionRebuilderDeps['markSnapshot']);
+  const emit =
+    overrides?.emit ?? (jest.fn() as SuspensionRebuilderDeps['emit']);
+  const executeFlow =
+    overrides?.executeFlow ??
+    (jest
+      .fn()
+      .mockResolvedValue(undefined) as SuspensionRebuilderDeps['executeFlow']);
+  const deps: SuspensionRebuilderDeps = {
+    compiled,
+    context,
+    runId: overrides?.runId ?? 'run-123',
+    createExecutorEnv:
+      overrides?.createExecutorEnv ??
+      jest.fn(
+        () =>
+          ({
+            context,
+          }) as unknown as StepExecutorEnv,
+      ),
+    buildInstanceStepInfo: overrides?.buildInstanceStepInfo ?? buildStepInfo,
+    captureTaskOutput,
+    markSnapshot,
+    emit,
+    executeFlow,
+  };
+
+  return deps;
+};
+const createTask = (name: string): CompiledTask =>
+  ({
+    name,
+    definition: { action: name } as TaskDefinition,
+    actionName: name,
+    action: dummyAction,
+    inputs: {},
+    settings: {} as Settings,
+    bindings: {},
+  }) as CompiledTask;
+
+afterEach(() => {
+  jest.clearAllMocks();
+});
+
+describe('parseSuspendedStepId', () => {
+  it('extracts path and iteration stack from a nested id', () => {
+    expect(parseSuspendedStepId('1.branch.0:conditional[2.4]')).toEqual({
+      path: [1, 'branch', 0],
+      iterationStack: [2, 4],
+    });
+  });
+
+  it('returns empty path and iteration data for root ids', () => {
+    expect(parseSuspendedStepId('root:task')).toEqual({
+      path: [],
+      iterationStack: [],
+    });
+  });
+});
+
+describe('rebuildSuspension', () => {
+  it('returns null when no state is available', () => {
+    const compiled = createCompiledWorkflow([], {});
+    const deps = createDeps(compiled);
+    const suspension = rebuildSuspension(deps, {
+      state: undefined,
+      stepId: '0:task',
+    });
+
+    expect(suspension).toBeNull();
+  });
+
+  it('rebuilds a task suspension and resumes the flow', async () => {
+    const task = createTask('first_task');
+    const taskStep: CompiledStep = {
+      type: StepType.Task,
+      id: '0:first_task',
+      label: 'first_task',
+      taskName: 'first_task',
+    };
+    const compiled = createCompiledWorkflow([taskStep], {
+      first_task: task,
+    });
+    const state: ExecutionState = {
+      input: {},
+      output: {},
+      iterationStack: [3],
+    };
+    const deps = createDeps(compiled);
+    const suspension = rebuildSuspension(deps, {
+      state,
+      stepId: '0:first_task',
+      reason: 'needs_input',
+      data: { foo: 'bar' },
+    });
+
+    expect(suspension?.step.id).toBe('0:first_task[3]');
+    expect(suspension?.reason).toBe('needs_input');
+    expect(suspension?.data).toEqual({ foo: 'bar' });
+
+    await suspension?.continue({ reply: 'ok' });
+
+    expect(deps.captureTaskOutput).toHaveBeenCalledWith(task, state, {
+      reply: 'ok',
+    });
+    expect(deps.markSnapshot).toHaveBeenCalledWith(
+      expect.objectContaining({ id: '0:first_task[3]' }),
+      'completed',
+    );
+    expect(deps.emit).toHaveBeenCalledWith('hook:step:success', {
+      runId: 'run-123',
+      step: expect.objectContaining({ id: '0:first_task[3]' }),
+    });
+    expect(deps.executeFlow).toHaveBeenCalledWith(compiled.flow, state, [], 1);
+  });
+
+  it('rebuilds a parallel suspension and continues remaining siblings when needed', async () => {
+    const firstTask = createTask('child_a');
+    const secondTask = createTask('child_b');
+    const childA: CompiledStep = {
+      type: StepType.Task,
+      id: '0.parallel.0:child_a',
+      label: 'child_a',
+      taskName: 'child_a',
+    };
+    const childB: CompiledStep = {
+      type: StepType.Task,
+      id: '0.parallel.1:child_b',
+      label: 'child_b',
+      taskName: 'child_b',
+    };
+    const parallelStep: CompiledStep = {
+      type: StepType.Parallel,
+      id: '0:parallel',
+      label: 'parallel',
+      strategy: 'wait_all',
+      steps: [childA, childB],
+    };
+    const compiled = createCompiledWorkflow([parallelStep], {
+      child_a: firstTask,
+      child_b: secondTask,
+    });
+    const state: ExecutionState = {
+      input: {},
+      output: {},
+      iterationStack: [],
+    };
+    const deps = createDeps(compiled);
+
+    deps.executeFlow = jest
+      .fn()
+      .mockResolvedValue(undefined) as SuspensionRebuilderDeps['executeFlow'];
+    const suspension = rebuildSuspension(deps, {
+      state,
+      stepId: '0.parallel.1:child_b',
+    });
+
+    mockedRunParallelExecutor.mockResolvedValue(
+      'next-suspension' as unknown as void,
+    );
+
+    const result = await suspension?.continue({ payload: true });
+
+    expect(deps.captureTaskOutput).toHaveBeenCalledWith(secondTask, state, {
+      payload: true,
+    });
+    expect(mockedRunParallelExecutor).toHaveBeenCalledWith(
+      expect.anything(),
+      parallelStep,
+      state,
+      [0],
+      2,
+    );
+    expect(result).toBe('next-suspension');
+  });
+
+  it('resumes a loop suspension, updating accumulators and continuing execution', async () => {
+    const loopTask = createTask('loop_task');
+    const childTask: CompiledStep = {
+      type: StepType.Task,
+      id: '0.collector.0:loop_task',
+      label: 'loop_task',
+      taskName: 'loop_task',
+    };
+    const loopStep: CompiledStep = {
+      type: StepType.Loop,
+      id: '0:collector',
+      loopType: 'for_each',
+      label: 'collector',
+      name: 'collector',
+      forEach: { item: 'entry', in: { kind: 'literal', value: [] } },
+      steps: [childTask],
+      accumulate: {
+        as: 'sum',
+        initial: 0,
+        merge: { kind: 'literal', value: 0 },
+      },
+    };
+    const compiled = createCompiledWorkflow([loopStep], {
+      loop_task: loopTask,
+    });
+    const state: ExecutionState = {
+      input: {},
+      output: {},
+      iterationStack: [1],
+      accumulator: 2,
+    };
+    const deps = createDeps(compiled);
+
+    deps.executeFlow = jest
+      .fn()
+      .mockResolvedValue(undefined) as SuspensionRebuilderDeps['executeFlow'];
+
+    mockedUpdateAccumulator.mockResolvedValue(5);
+    mockedShouldStopLoop.mockResolvedValue(false);
+    mockedRunLoopExecutor.mockResolvedValue(
+      'loop-continued' as unknown as void,
+    );
+
+    const suspension = rebuildSuspension(deps, {
+      state,
+      stepId: '0.collector.0:loop_task[1]',
+    });
+    const result = await suspension?.continue({ resumed: true });
+
+    expect(deps.captureTaskOutput).toHaveBeenCalledWith(
+      loopTask,
+      expect.objectContaining({ iteration: { index: 1, item: undefined } }),
+      { resumed: true },
+    );
+    expect(mockedUpdateAccumulator).toHaveBeenCalledWith(
+      loopStep,
+      expect.objectContaining({
+        iteration: { item: undefined, index: 1 },
+        accumulator: 2,
+      }),
+      2,
+    );
+    expect(mockedShouldStopLoop).toHaveBeenCalled();
+    expect((state.output as { collector: { sum: number } }).collector.sum).toBe(
+      5,
+    );
+    expect(mockedRunLoopExecutor).toHaveBeenCalledWith(
+      expect.anything(),
+      loopStep,
+      expect.objectContaining({ accumulator: 5, iterationStack: [] }),
+      [0],
+      2,
+    );
+    const loopState = mockedRunLoopExecutor.mock.calls[0]?.[2];
+    expect(loopState?.accumulator).toBe(5);
+    expect(loopState?.iterationStack).toEqual([]);
+    expect(result).toBe('loop-continued');
+  });
+});