@hexabot-ai/agentic 3.0.1-alpha.0

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

@@ -0,0 +1,132 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { BaseWorkflowContext } from '../context';
+import type { Settings } from '../dsl.types';
+import { EventEmitterLike } from '../workflow-event-emitter';
+import {
+  compileValue,
+  evaluateMapping,
+  evaluateValue,
+  mergeSettings,
+} from '../workflow-values';
+
+class TestContext extends BaseWorkflowContext {
+  public eventEmitter: EventEmitterLike = { emit: jest.fn(), on: jest.fn() };
+
+  constructor() {
+    super({});
+  }
+}
+
+describe('workflow values', () => {
+  it('registers custom JSONata functions on expressions', async () => {
+    const translate = jest.fn((text: string) => `translated:${text}`);
+    const compiled = compileValue("=$i18n('Bye bye')", {
+      jsonataFunctions: { i18n: translate },
+    });
+    const result = await evaluateValue(compiled, {
+      input: {},
+      context: new TestContext().state,
+      output: {},
+    });
+
+    expect(result).toBe('translated:Bye bye');
+    expect(translate).toHaveBeenCalledWith('Bye bye');
+  });
+
+  it('compiles expressions and evaluates against the runtime scope', async () => {
+    const compiled = compileValue(
+      '=$input.amount + $context.offset + $iteration.index + $accumulator',
+    );
+    const result = await evaluateValue(compiled, {
+      input: { amount: 10 },
+      context: { offset: 5 },
+      output: {},
+      iteration: { item: 'item', index: 2 },
+      accumulator: 3,
+      result: { value: 7 },
+    });
+
+    expect(result).toBe(20);
+  });
+
+  it('returns literal values unchanged and evaluates mappings', async () => {
+    const literal = compileValue({ raw: true });
+    const mapping = {
+      literal,
+      expression: compileValue('=$result.value'),
+    };
+    const values = await evaluateMapping(mapping, {
+      input: {},
+      context: new TestContext().state,
+      output: {},
+      result: { value: 42 },
+    });
+
+    expect(values).toEqual({
+      literal: { raw: true },
+      expression: 42,
+    });
+  });
+
+  it('handles missing mappings and deep merges settings', async () => {
+    await expect(
+      evaluateMapping(undefined, {
+        input: {},
+        context: new TestContext().state,
+        output: {},
+      }),
+    ).resolves.toEqual({});
+
+    const merged = mergeSettings(
+      {
+        timeout_ms: 10,
+        retries: {
+          enabled: true,
+          max_attempts: 3,
+          backoff_ms: 10,
+          max_delay_ms: 100,
+          jitter: 0,
+          multiplier: 2,
+        },
+        llm: {
+          model: 'gpt-4o',
+          options: { temperature: 0.2, top_p: 0.9 },
+        },
+      } satisfies Partial<Settings>,
+      {
+        retries: {
+          enabled: true,
+          max_attempts: 5,
+          backoff_ms: 10,
+          max_delay_ms: 100,
+          jitter: 0,
+          multiplier: 1,
+        },
+        llm: {
+          options: { temperature: 0.5 },
+        },
+      },
+    );
+
+    expect(merged).toEqual({
+      timeout_ms: 10,
+      retries: {
+        enabled: true,
+        max_attempts: 5,
+        backoff_ms: 10,
+        max_delay_ms: 100,
+        jitter: 0,
+        multiplier: 1,
+      },
+      llm: {
+        model: 'gpt-4o',
+        options: { temperature: 0.5, top_p: 0.9 },
+      },
+    });
+  });
+});

package/src/__tests__/workflow.test.ts

@@ -0,0 +1,320 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { defineAction } from '../action/action';
+import { BaseWorkflowContext } from '../context';
+import { Settings, WorkflowDefinition, validateWorkflow } from '../dsl.types';
+import { Workflow, WorkflowEventEmitter } from '../workflow';
+import { EventEmitterLike } from '../workflow-event-emitter';
+
+import { createTaskDefs } from './test-helpers';
+
+class TestContext extends BaseWorkflowContext {
+  public eventEmitter: EventEmitterLike = { emit: jest.fn(), on: jest.fn() };
+
+  constructor() {
+    super({});
+  }
+}
+
+describe('Workflow execution', () => {
+  it('runs a sequential workflow with JSONata inputs and merged settings', async () => {
+    const greetAction = defineAction<
+      { name: string },
+      { name: string; settings: Settings },
+      TestContext,
+      Settings
+    >({
+      name: 'greet_action',
+      inputSchema: z.object({ name: z.string() }),
+      outputSchema: z
+        .object({
+          name: z.string(),
+          settings: z.custom<Settings>(),
+        })
+        .strict(),
+      execute: async ({ input, settings }) => ({
+        name: input.name,
+        settings,
+      }),
+    });
+    const definition: WorkflowDefinition = {
+      defaults: {
+        settings: {
+          timeout_ms: 50,
+          retries: {
+            enabled: true,
+            max_attempts: 3,
+            backoff_ms: 10,
+            max_delay_ms: 1000,
+            jitter: 0,
+            multiplier: 2,
+          },
+        },
+      },
+      defs: createTaskDefs({
+        greet_user: {
+          action: 'greet_action',
+          inputs: {
+            name: '=$trim($input.name)',
+          },
+          settings: {
+            timeout_ms: 20,
+            retries: {
+              enabled: true,
+              max_attempts: 2,
+              backoff_ms: 10,
+              max_delay_ms: 1000,
+              jitter: 0,
+              multiplier: 2,
+            },
+          },
+        },
+      }),
+      flow: [{ do: 'greet_user' }],
+      outputs: {
+        final: "='Hello ' & $output.greet_user.name",
+        timeout_ms: '=$output.greet_user.settings.timeout_ms',
+        max_attempts: '=$output.greet_user.settings.retries.max_attempts',
+      },
+      inputs: {
+        schema: {
+          name: { type: 'string' },
+        },
+      },
+    };
+    const workflow = Workflow.fromDefinition(definition, {
+      actions: { greet_action: greetAction },
+    });
+    const result = await workflow.run({ name: '  Ada  ' }, new TestContext());
+
+    expect(result.final).toBe('Hello Ada');
+    expect(result.timeout_ms).toBe(20);
+    expect(result.max_attempts).toBe(2);
+  });
+
+  it('supports suspension and resume through the WorkflowRunner', async () => {
+    const suspendingAction = defineAction<
+      { prompt: string },
+      { reply?: string },
+      TestContext,
+      Settings
+    >({
+      name: 'await_reply',
+      inputSchema: z.object({ prompt: z.string() }),
+      outputSchema: z.object({ reply: z.string().optional() }),
+      execute: async ({ context }) => {
+        const resumeData = (await context.workflow.suspend({
+          reason: 'waiting_for_user',
+          data: { channel: 'email' },
+        })) as { reply?: string };
+
+        return { reply: resumeData.reply };
+      },
+    });
+    const definition: WorkflowDefinition = {
+      defs: createTaskDefs({
+        ask_user: {
+          action: 'await_reply',
+          inputs: { prompt: '="Ping"' },
+        },
+      }),
+      flow: [{ do: 'ask_user' }],
+      outputs: { reply: '=$output.ask_user.reply' },
+    };
+    const workflow = Workflow.fromDefinition(definition, {
+      actions: { await_reply: suspendingAction },
+    });
+    const runner = await workflow.buildAsyncRunner();
+    const startResult = await runner.start({
+      inputData: {},
+      context: new TestContext(),
+    });
+    expect(startResult.status).toBe('suspended');
+    if (startResult.status === 'suspended') {
+      expect(startResult.reason).toBe('waiting_for_user');
+      expect(runner.getSnapshot().actions[startResult.step.id]?.status).toBe(
+        'suspended',
+      );
+    }
+
+    const resumeResult = await runner.resume({
+      resumeData: { reply: 'Sure, go ahead.' },
+    });
+    expect(resumeResult.status).toBe('finished');
+    if (resumeResult.status === 'finished') {
+      expect(resumeResult.output.reply).toBe('Sure, go ahead.');
+      expect(runner.getStatus()).toBe('finished');
+    }
+  });
+
+  it('emits lifecycle events', async () => {
+    const noopAction = defineAction<
+      { value: number },
+      { doubled: number },
+      TestContext,
+      Settings
+    >({
+      name: 'double_value',
+      inputSchema: z.object({ value: z.number() }),
+      outputSchema: z.object({ doubled: z.number() }),
+      execute: async ({ input }) => ({ doubled: input.value * 2 }),
+    });
+    const definition: WorkflowDefinition = {
+      defs: createTaskDefs({
+        double_step: {
+          action: 'double_value',
+          inputs: { value: '=$input.value' },
+        },
+      }),
+      flow: [{ do: 'double_step' }],
+      outputs: { result: '=$output.double_step.doubled' },
+      inputs: {
+        schema: {
+          value: { type: 'number' },
+        },
+      },
+    };
+    const events: string[] = [];
+    const emitter = new WorkflowEventEmitter();
+    emitter.on('hook:workflow:start', () => events.push('hook:workflow:start'));
+    emitter.on('hook:step:start', ({ step }: { step: { name: string } }) =>
+      events.push(`hook:step:start:${step.name}`),
+    );
+    emitter.on('hook:step:success', ({ step }: { step: { name: string } }) =>
+      events.push(`hook:step:success:${step.name}`),
+    );
+    emitter.on('hook:workflow:finish', () =>
+      events.push('hook:workflow:finish'),
+    );
+
+    const workflow = Workflow.fromDefinition(definition, {
+      actions: { double_value: noopAction },
+    });
+    const runner = await workflow.buildAsyncRunner();
+    const context = new TestContext();
+    context.eventEmitter = emitter;
+    const outcome = await runner.start({ inputData: { value: 5 }, context });
+
+    expect(outcome.status).toBe('finished');
+    if (outcome.status === 'finished') {
+      expect(outcome.output.result).toBe(10);
+    }
+    expect(events).toEqual([
+      'hook:workflow:start',
+      'hook:step:start:double_step',
+      'hook:step:success:double_step',
+      'hook:workflow:finish',
+    ]);
+  });
+
+  it('throws on invalid YAML input', () => {
+    expect(() =>
+      Workflow.fromYaml('defs: {}', {
+        actions: {} as Record<string, never>,
+      }),
+    ).toThrow(/Workflow validation failed/);
+  });
+
+  it('stringifies a workflow definition to YAML', () => {
+    const definition: WorkflowDefinition = {
+      defs: createTaskDefs({
+        greet_user: {
+          action: 'greet_action',
+          inputs: { name: '=$input.name' },
+        },
+      }),
+      flow: [{ do: 'greet_user' }],
+      outputs: { result: '=$output.greet_user.name' },
+    };
+    const yaml = Workflow.stringifyDefinition(definition);
+    const validation = validateWorkflow(yaml);
+
+    expect(validation.success).toBe(true);
+    if (validation.success) {
+      expect(validation.data).toEqual(definition);
+    }
+  });
+
+  it('propagates action errors thrown during run', async () => {
+    const failingAction = defineAction<unknown, unknown, TestContext, Settings>(
+      {
+        name: 'failing_action',
+        inputSchema: z.any(),
+        outputSchema: z.any(),
+        execute: async () => {
+          throw new Error('failed to execute');
+        },
+      },
+    );
+    const definition: WorkflowDefinition = {
+      defs: createTaskDefs({
+        failing_task: {
+          action: 'failing_action',
+          inputs: {},
+        },
+      }),
+      flow: [{ do: 'failing_task' }],
+      outputs: { result: '=$output.failing_task' },
+    };
+    const workflow = Workflow.fromDefinition(definition, {
+      actions: { failing_action: failingAction },
+    });
+    const context = new TestContext();
+
+    await expect(workflow.run({}, context)).rejects.toThrow(
+      'failed to execute',
+    );
+    expect(() => context.workflow).toThrow(
+      'Workflow runtime is not attached to this context.',
+    );
+  });
+
+  it('throws suspension details from run when a task suspends', async () => {
+    const suspendingAction = defineAction<
+      unknown,
+      { reply?: string },
+      TestContext,
+      Settings
+    >({
+      name: 'suspending_action',
+      inputSchema: z.any(),
+      outputSchema: z.object({ reply: z.string().optional() }),
+      execute: async ({ context }) => {
+        await context.workflow.suspend({
+          reason: 'need_input',
+          data: { prompt: 'ok?' },
+        });
+
+        return { reply: 'never' };
+      },
+    });
+    const definition: WorkflowDefinition = {
+      defs: createTaskDefs({
+        pause_step: {
+          action: 'suspending_action',
+          inputs: {},
+        },
+      }),
+      flow: [{ do: 'pause_step' }],
+      outputs: { reply: '=$output.pause_step.reply' },
+    };
+    const workflow = Workflow.fromDefinition(definition, {
+      actions: { suspending_action: suspendingAction },
+    });
+    const context = new TestContext();
+
+    await expect(workflow.run({}, context)).rejects.toMatchObject({
+      stepId: '0:pause_step',
+      reason: 'need_input',
+    });
+    expect(() => context.workflow).toThrow(
+      'Workflow runtime is not attached to this context.',
+    );
+  });
+});

package/src/action/__tests__/abstract-action-timing.test.ts

@@ -0,0 +1,183 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z } from 'zod';
+
+import { BaseWorkflowContext } from '../../context';
+import { Settings } from '../../dsl.types';
+import { EventEmitterLike } from '../../workflow-event-emitter';
+import { AbstractAction } from '../abstract-action';
+import { ActionExecutionArgs, ActionMetadata } from '../action.types';
+
+const InputSchema = z.object({ value: z.number() });
+const OutputSchema = z.object({ result: z.number() });
+
+type Input = z.infer<typeof InputSchema>;
+type Output = z.infer<typeof OutputSchema>;
+const NoSettingsSchema = z.any();
+type NoSettings = unknown;
+
+class TestContext extends BaseWorkflowContext {
+  public eventEmitter: EventEmitterLike = { emit: jest.fn(), on: jest.fn() };
+
+  constructor() {
+    super({});
+  }
+}
+
+class HarnessedAction extends AbstractAction<
+  Input,
+  Output,
+  TestContext,
+  NoSettings
+> {
+  constructor(
+    private readonly executor: (
+      args: ActionExecutionArgs<Input, TestContext, NoSettings>,
+    ) => Promise<Output>,
+  ) {
+    const metadata: ActionMetadata<Input, Output, NoSettings> = {
+      name: 'timing_action',
+      description: 'Action used to validate retry and timeout behavior.',
+      inputSchema: InputSchema,
+      outputSchema: OutputSchema,
+      settingsSchema: NoSettingsSchema,
+    };
+
+    super(metadata);
+  }
+
+  execute(
+    args: ActionExecutionArgs<Input, TestContext, NoSettings>,
+  ): Promise<Output> {
+    return this.executor(args);
+  }
+}
+
+describe('AbstractAction timing and retries', () => {
+  afterEach(() => {
+    jest.useRealTimers();
+    jest.restoreAllMocks();
+  });
+
+  it('fails when execution exceeds the configured timeout', async () => {
+    jest.useFakeTimers();
+    let attempts = 0;
+
+    const action = new HarnessedAction(async () => {
+      attempts += 1;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+
+      return { result: 1 };
+    });
+    const settings: Partial<Settings> = {
+      timeout_ms: 50,
+      retries: {
+        enabled: true,
+        max_attempts: 1,
+        backoff_ms: 0,
+        max_delay_ms: 0,
+        jitter: 0,
+        multiplier: 1,
+      },
+    };
+    const runPromise = action.run({ value: 1 }, new TestContext(), settings);
+    const runExpectation =
+      expect(runPromise).rejects.toThrow(/timeout of 50ms/);
+    await jest.advanceTimersByTimeAsync(60);
+
+    await runExpectation;
+    expect(attempts).toBe(1);
+  });
+
+  it('applies exponential backoff capped by max_delay_ms', async () => {
+    jest.useFakeTimers();
+
+    let attempts = 0;
+    const attemptTimestamps: number[] = [];
+    const action = new HarnessedAction(async () => {
+      attempts += 1;
+      attemptTimestamps.push(Date.now());
+
+      if (attempts < 3) {
+        throw new Error('Retry me');
+      }
+
+      return { result: attempts };
+    });
+    const runPromise = action.run({ value: 1 }, new TestContext(), {
+      timeout_ms: 0,
+      retries: {
+        enabled: true,
+        max_attempts: 3,
+        backoff_ms: 10,
+        max_delay_ms: 15,
+        jitter: 0,
+        multiplier: 2,
+      },
+    });
+
+    await Promise.resolve();
+    expect(attempts).toBe(1);
+
+    await jest.advanceTimersByTimeAsync(9);
+    expect(attempts).toBe(1);
+    await jest.advanceTimersByTimeAsync(1);
+    expect(attempts).toBe(2);
+
+    await jest.advanceTimersByTimeAsync(14);
+    expect(attempts).toBe(2);
+    await jest.advanceTimersByTimeAsync(1);
+
+    await expect(runPromise).resolves.toEqual({ result: 3 });
+
+    expect(attempts).toBe(3);
+    expect(attemptTimestamps[1] - attemptTimestamps[0]).toBe(10);
+    expect(attemptTimestamps[2] - attemptTimestamps[1]).toBe(15);
+  });
+
+  it('uses jitter to randomize retry delays', async () => {
+    jest.useFakeTimers();
+
+    const randomSpy = jest.spyOn(Math, 'random').mockReturnValue(1);
+    let attempts = 0;
+    const attemptTimestamps: number[] = [];
+    const action = new HarnessedAction(async () => {
+      attempts += 1;
+      attemptTimestamps.push(Date.now());
+
+      if (attempts < 2) {
+        throw new Error('Intermittent');
+      }
+
+      return { result: attempts };
+    });
+    const runPromise = action.run({ value: 1 }, new TestContext(), {
+      timeout_ms: 0,
+      retries: {
+        enabled: true,
+        max_attempts: 2,
+        backoff_ms: 100,
+        max_delay_ms: 0,
+        jitter: 0.5,
+        multiplier: 1,
+      },
+    });
+
+    await Promise.resolve();
+    expect(attempts).toBe(1);
+
+    await jest.advanceTimersByTimeAsync(149);
+    expect(attempts).toBe(1);
+    await jest.advanceTimersByTimeAsync(1);
+
+    await expect(runPromise).resolves.toEqual({ result: 2 });
+
+    expect(attempts).toBe(2);
+    expect(randomSpy).toHaveBeenCalled();
+    expect(attemptTimestamps[1] - attemptTimestamps[0]).toBe(150);
+  });
+});