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

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

@@ -18,7 +18,6 @@ import {
   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,
@@ -40,11 +39,6 @@ jest.mock('../step-executors/loop-executor', () => ({
   shouldStopLoop: jest.fn(),
 }));
 
-jest.mock('../step-executors/parallel-executor', () => ({
-  __esModule: true,
-  executeParallel: jest.fn(),
-}));
-
 const mockedRunLoopExecutor = runLoopExecutor as jest.MockedFunction<
   typeof runLoopExecutor
 >;
@@ -54,9 +48,6 @@ const mockedUpdateAccumulator = updateAccumulator as jest.MockedFunction<
 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() };
@@ -268,7 +259,7 @@ describe('rebuildSuspension', () => {
     expect(deps.executeFlow).toHaveBeenCalledWith(compiled.flow, state, [], 1);
   });
 
-  it('rebuilds a parallel suspension and continues remaining siblings when needed', async () => {
+  it('does not rebuild suspensions inside parallel blocks', () => {
     const firstTask = createTask('child_a');
     const secondTask = createTask('child_b');
     const childA: CompiledStep = {
@@ -308,39 +299,9 @@ describe('rebuildSuspension', () => {
       state,
       stepId: '0.parallel.1:child_b',
     });
-    const nextSuspension = {
-      step: {
-        id: '0.parallel.2:child_c',
-        name: 'child_c',
-        type: StepType.Task,
-      },
-      continue: jest.fn().mockResolvedValue(undefined),
-    };
-    mockedRunParallelExecutor.mockResolvedValue(nextSuspension);
 
-    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?.step.id).toBe(nextSuspension.step.id);
-
-    await result?.continue({ done: true });
-
-    expect(nextSuspension.continue).toHaveBeenCalledWith({ done: true });
-    expect(deps.executeFlow).toHaveBeenLastCalledWith(
-      compiled.flow,
-      state,
-      [],
-      1,
-    );
+    expect(suspension).toBeNull();
+    expect(deps.captureTaskOutput).not.toHaveBeenCalled();
   });
 
   it('resumes a loop suspension, updating accumulators and continuing execution', async () => {

package/src/__tests__/workflow-definition-resources.test.ts

@@ -0,0 +1,97 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type { WorkflowDefinition } from '../dsl.types';
+import {
+  collectWorkflowDefinitionResourceRefs,
+  remapWorkflowDefinitionResourceRefs,
+  type WorkflowDefinitionResourceDescriptor,
+} from '../utils/workflow-definition-resources';
+
+const descriptors: WorkflowDefinitionResourceDescriptor[] = [
+  { kind: 'memory', settingsKey: 'definition_id' },
+  { kind: 'mcp', settingsKey: 'server_id' },
+];
+const definition: WorkflowDefinition = {
+  defs: {
+    profile_memory: {
+      kind: 'memory',
+      settings: {
+        definition_id: 'memory-1',
+      },
+    },
+    duplicate_profile_memory: {
+      kind: 'memory',
+      settings: {
+        definition_id: 'memory-1',
+      },
+    },
+    search_mcp: {
+      kind: 'mcp',
+      settings: {
+        server_id: 'mcp-1',
+      },
+    },
+    greet: {
+      kind: 'task',
+      action: 'send_message',
+      bindings: {
+        memory: ['profile_memory'],
+        mcp: ['search_mcp'],
+      },
+    },
+  },
+  flow: [{ do: 'greet' }],
+  outputs: { result: '=$output.greet' },
+};
+
+describe('workflow definition resource helpers', () => {
+  it('collects unique resource references by descriptor kind', () => {
+    expect(
+      collectWorkflowDefinitionResourceRefs(definition, descriptors),
+    ).toEqual({
+      memory: ['memory-1'],
+      mcp: ['mcp-1'],
+    });
+  });
+
+  it('remaps resource references without mutating the original definition', () => {
+    const updated = remapWorkflowDefinitionResourceRefs(
+      definition,
+      descriptors,
+      {
+        memory: { 'memory-1': 'memory-local' },
+        mcp: { 'mcp-1': 'mcp-local' },
+      },
+    );
+
+    expect(updated).not.toBe(definition);
+    expect(updated.defs.profile_memory.settings).toEqual({
+      definition_id: 'memory-local',
+    });
+    expect(updated.defs.duplicate_profile_memory.settings).toEqual({
+      definition_id: 'memory-local',
+    });
+    expect(updated.defs.search_mcp.settings).toEqual({
+      server_id: 'mcp-local',
+    });
+    expect(definition.defs.profile_memory.settings).toEqual({
+      definition_id: 'memory-1',
+    });
+    expect(definition.defs.search_mcp.settings).toEqual({
+      server_id: 'mcp-1',
+    });
+  });
+
+  it('returns the original definition when no refs change', () => {
+    expect(
+      remapWorkflowDefinitionResourceRefs(definition, descriptors, {
+        memory: {},
+        mcp: {},
+      }),
+    ).toBe(definition);
+  });
+});

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

@@ -9,6 +9,7 @@ import { z } from 'zod';
 import { defineAction } from '../action/action';
 import { BaseWorkflowContext } from '../context';
 import type { Settings, WorkflowDefinition } from '../dsl.types';
+import { ParallelSuspensionError } from '../errors';
 import { compileWorkflow } from '../workflow-compiler';
 import {
   StepType,
@@ -298,6 +299,7 @@ describe('WorkflowRunner', () => {
     });
     const runner = new WorkflowRunner(compiled, { runId: 'run-1' });
     const context = new TestContext({});
+    context.eventEmitter = emitter;
     const result = await runner.start({
       inputData: { items: [10, 20] },
       context,
@@ -313,15 +315,13 @@ describe('WorkflowRunner', () => {
     }
 
     expect(firstExecute).toHaveBeenCalledTimes(1);
-    expect(secondExecute).not.toHaveBeenCalled();
+    expect(secondExecute).toHaveBeenCalledTimes(1);
     expect(echoExecute).toHaveBeenCalledTimes(3);
-    expect(
-      eventLog.filter((entry) => entry.includes('second_task')),
-    ).toHaveLength(0);
+    expect(eventLog).toContain('start:second_task');
     expect(runner.getSnapshot().status).toBe('finished');
     const snapshots = runner.getSnapshot().actions;
     expect(snapshots['0.parallel.0:first_task']?.status).toBe('completed');
-    expect(snapshots['0.parallel.1:second_task']?.status).toBe('skipped');
+    expect(snapshots['0.parallel.1:second_task']?.status).toBe('cancelled');
     expect(snapshots['1.branch.0.0:branch_task']?.status).toBe('completed');
     expect(snapshots['1.branch.1.0:second_task']?.status).toBe('skipped');
   });
@@ -741,6 +741,59 @@ describe('WorkflowRunner', () => {
     expect(() => context.workflow).toThrow();
   });
 
+  it('fails when a parallel branch attempts to suspend', async () => {
+    const suspendAction = defineAction<
+      unknown,
+      { reply: string },
+      TestContext,
+      Settings
+    >({
+      name: 'parallel_suspend_action',
+      inputSchema: z.any(),
+      outputSchema: z.object({ reply: z.string() }),
+      execute: async ({ context }) => {
+        await context.workflow.suspend({ reason: 'not_allowed' });
+
+        return { reply: 'unreachable' };
+      },
+    });
+    const definition: WorkflowDefinition = {
+      defs: createTaskDefs({
+        wait_step: { action: 'parallel_suspend_action' },
+      }),
+      flow: [
+        {
+          parallel: {
+            strategy: 'wait_all',
+            steps: [{ do: 'wait_step' }],
+          },
+        },
+      ],
+      outputs: { reply: '=$output.wait_step.reply' },
+    };
+    const compiled = compileWorkflow(definition, {
+      actions: { parallel_suspend_action: suspendAction },
+    });
+    const runner = new WorkflowRunner(compiled, {
+      runId: 'run-parallel-suspend',
+    });
+    const result = await runner.start({
+      inputData: {},
+      context: new TestContext({}),
+    });
+
+    expect(result.status).toBe('failed');
+    if (result.status === 'failed') {
+      expect(result.error).toBeInstanceOf(ParallelSuspensionError);
+    }
+    expect(
+      runner.getSnapshot().actions['0.parallel.0:wait_step'],
+    ).toMatchObject({
+      status: 'failed',
+      reason: 'workflow.suspend() is not supported inside a parallel block.',
+    });
+  });
+
   it('accepts emitter-like implementations without Node EventEmitter', async () => {
     const pingAction = defineAction<
       unknown,

package/src/action/__tests__/action.test.ts

@@ -189,6 +189,7 @@ class FlakyDoubleAction extends DoubleAction {
     context,
     settings,
     bindings,
+    signal,
   }: ActionExecutionArgs<
     z.infer<typeof InputSchema>,
     DoubleContext,
@@ -199,7 +200,7 @@ class FlakyDoubleAction extends DoubleAction {
       throw new Error('Intermittent failure');
     }
 
-    return super.execute({ input, context, settings, bindings });
+    return super.execute({ input, context, settings, bindings, signal });
   }
 }
 

package/src/action/abstract-action.ts

@@ -8,6 +8,7 @@ import { z, ZodType } from 'zod';
 
 import { BaseWorkflowContext } from '../context';
 import { BaseSettingsSchema } from '../dsl.types';
+import { throwIfAborted } from '../errors';
 import { assertSnakeCaseName } from '../utils/naming';
 import { sleep, withTimeout } from '../utils/timeout';
 
@@ -112,6 +113,7 @@ export abstract class AbstractAction<
     context: C,
     settings?: Partial<RuntimeSettings<S>>,
     bindings?: B,
+    signal?: AbortSignal,
   ): Promise<O> {
     const input = this.parseInput(payload);
     const parsedSettings = this.parseSettings(settings);
@@ -136,6 +138,10 @@ export abstract class AbstractAction<
     const multiplier = retrySettings.multiplier;
 
     while (attempt < maxAttempts) {
+      if (signal) {
+        throwIfAborted(signal);
+      }
+
       try {
         const result = await withTimeout(
           this.execute({
@@ -143,8 +149,10 @@ export abstract class AbstractAction<
             context,
             settings: parsedSettings,
             bindings: parsedBindings,
+            signal: signal ?? new AbortController().signal,
           }),
           timeoutMs,
+          signal,
         );
 
         return this.parseOutput(result);
@@ -166,7 +174,7 @@ export abstract class AbstractAction<
           const jitteredDelay = Math.max(0, Math.round(delay * jitterFactor));
 
           if (jitteredDelay > 0) {
-            await sleep(jitteredDelay);
+            await sleep(jitteredDelay, signal);
           }
         }
 

package/src/action/action.types.ts

@@ -34,6 +34,7 @@ export interface ActionExecutionArgs<
   context: C;
   settings: RuntimeSettings<S>;
   bindings: B;
+  signal: AbortSignal;
 }
 
 export interface Action<
@@ -59,6 +60,7 @@ export interface Action<
     context: C,
     settings?: Partial<RuntimeSettings<S>>,
     bindings?: B,
+    signal?: AbortSignal,
   ): Promise<O>;
 }
 

package/src/context.ts

@@ -42,6 +42,7 @@ export const WORKFLOW_RUN_STATUSES: WorkflowRunStatus[] = [
  * - suspended: action paused via `workflow.suspend`; resumes to completed.
  * - completed: action resolved (either immediately or after resume).
  * - failed: action threw an error.
+ * - cancelled: action was aborted by the workflow scheduler.
  * - skipped: control flow bypassed the step (e.g., alternate branch or wait_any short-circuit).
  */
 export type ActionStatus =
@@ -50,6 +51,7 @@ export type ActionStatus =
   | 'suspended'
   | 'completed'
   | 'failed'
+  | 'cancelled'
   | 'skipped';
 
 export interface SuspensionOptions {

package/src/dsl.types.ts

@@ -10,6 +10,7 @@ import { z } from 'zod';
 
 import type { BindingKindSchemas } from './bindings/base-binding';
 import { validateAndResolveBindings } from './bindings/base-binding';
+import { SNAKE_CASE_REGEX } from './utils/naming';
 
 export const ExpressionStringSchema = z
   .string()
@@ -330,7 +331,10 @@ export const WorkflowDefinitionSchema = z.strictObject({
   inputs: InputsSchema.optional(),
   context: z.record(z.string(), JsonValueSchema).optional(),
   defaults: DefaultsSchema.optional(),
-  defs: z.record(z.string(), DefDefinitionSchema),
+  defs: z.record(
+    z.string().regex(SNAKE_CASE_REGEX, 'Name must be snake_case'),
+    DefDefinitionSchema,
+  ),
   flow: z.array(FlowStepSchema),
   outputs: z.record(z.string(), ExpressionStringSchema),
 });

package/src/errors.ts

@@ -0,0 +1,43 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export class WorkflowCancellationError extends Error {
+  constructor(message = 'Workflow execution was cancelled.') {
+    super(message);
+    this.name = 'WorkflowCancellationError';
+  }
+}
+
+export class ParallelSuspensionError extends Error {
+  constructor() {
+    super('workflow.suspend() is not supported inside a parallel block.');
+    this.name = 'ParallelSuspensionError';
+  }
+}
+
+export const isWorkflowCancellationError = (
+  error: unknown,
+): error is WorkflowCancellationError =>
+  error instanceof WorkflowCancellationError ||
+  (error instanceof Error && error.name === 'WorkflowCancellationError');
+
+export const getAbortReason = (signal: AbortSignal): Error => {
+  if (signal.reason instanceof Error) {
+    return signal.reason;
+  }
+
+  if (signal.reason !== undefined) {
+    return new WorkflowCancellationError(String(signal.reason));
+  }
+
+  return new WorkflowCancellationError();
+};
+
+export const throwIfAborted = (signal: AbortSignal): void => {
+  if (signal.aborted) {
+    throw getAbortReason(signal);
+  }
+};

package/src/index.ts

@@ -92,6 +92,8 @@ export type {
 
 export { NonDeterministicWorkflowError } from './runner-runtime-control';
 
+export { ParallelSuspensionError, WorkflowCancellationError } from './errors';
+
 export {
   compileValue,
   evaluateMapping,
@@ -114,3 +116,11 @@ export {
 } from './utils/naming';
 
 export { sleep, withTimeout } from './utils/timeout';
+
+export {
+  collectWorkflowDefinitionResourceRefs,
+  remapWorkflowDefinitionResourceRefs,
+  type WorkflowDefinitionResourceDescriptor,
+  type WorkflowDefinitionResourceIdMaps,
+  type WorkflowDefinitionResourceRefs,
+} from './utils/workflow-definition-resources';

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

@@ -48,10 +48,10 @@ const createEnv = (): StepExecutorEnv => {
     outputMapping: {},
     inputParser: { parse: (value: unknown) => value } as any,
   } as any;
-
-  return {
+  const env = {
     compiled,
     context: new TestContext(),
+    signal: new AbortController().signal,
     runId: 'run-1',
     buildInstanceStepInfo: jest.fn(),
     markSnapshot: jest.fn(),
@@ -68,7 +68,12 @@ const createEnv = (): StepExecutorEnv => {
     captureTaskOutput: jest.fn(),
     executeFlow: jest.fn(),
     executeStep: jest.fn(),
-  };
+    fork: jest.fn(),
+  } as StepExecutorEnv;
+
+  env.fork = jest.fn((overrides) => ({ ...env, ...overrides }));
+
+  return env;
 };
 
 describe('executeConditional', () => {

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

@@ -47,10 +47,10 @@ const createEnv = (executeFlow: jest.Mock): StepExecutorEnv => {
     outputMapping: {},
     inputParser: { parse: (value: unknown) => value } as any,
   } as any;
-
-  return {
+  const env = {
     compiled,
     context: new TestContext(),
+    signal: new AbortController().signal,
     runId: 'run-loop',
     buildInstanceStepInfo: jest.fn(),
     markSnapshot: jest.fn(),
@@ -67,7 +67,12 @@ const createEnv = (executeFlow: jest.Mock): StepExecutorEnv => {
     captureTaskOutput: jest.fn(),
     executeFlow,
     executeStep: jest.fn(),
-  };
+    fork: jest.fn(),
+  } as StepExecutorEnv;
+
+  env.fork = jest.fn((overrides) => ({ ...env, ...overrides }));
+
+  return env;
 };
 const createTaskStep = (id: string): CompiledStep => ({
   id,