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

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

@@ -4,6 +4,7 @@
  * Full terms: see LICENSE.md.
  */
 
+import { getAbortReason, throwIfAborted } from '../errors';
 import type { RuntimeSuspensionRequest } from '../runner-runtime-control';
 import type {
   CompiledTask,
@@ -19,6 +20,7 @@ import type { StepExecutorEnv } from './types';
 type TaskProgressOutcome =
   | { type: 'completed'; value: unknown }
   | { type: 'failed'; error: unknown }
+  | { type: 'cancelled'; error: Error }
   | { type: 'suspended'; request: RuntimeSuspensionRequest };
 
 /**
@@ -43,6 +45,12 @@ export async function executeTaskStep(
   }
 
   const stepInfo = env.buildInstanceStepInfo(step, state.iterationStack);
+  if (env.signal.aborted) {
+    const error = getAbortReason(env.signal);
+    recordTaskCancellation(env, stepInfo, error);
+    throw error;
+  }
+
   const scope: EvaluationScope = {
     input: state.input,
     context: env.context.state,
@@ -51,7 +59,13 @@ export async function executeTaskStep(
     accumulator: state.accumulator,
   };
   const inputs = await evaluateMapping(task.inputs, scope);
-  env.recordStepExecution(stepInfo, {
+  if (env.signal.aborted) {
+    const error = getAbortReason(env.signal);
+    recordTaskCancellation(env, stepInfo, error);
+    throw error;
+  }
+
+  const stepExecution = env.recordStepExecution(stepInfo, {
     action: task.actionName,
     status: 'running',
     startedAt: Date.now(),
@@ -61,11 +75,23 @@ export async function executeTaskStep(
   env.beginStepExecution?.(stepInfo.id);
   env.setCurrentStep(stepInfo);
   env.markSnapshot(stepInfo, 'running');
-  env.emit('hook:step:start', { runId: env.runId, step: stepInfo });
+  env.emit('hook:step:start', {
+    runId: env.runId,
+    step: stepInfo,
+    stepExecution,
+  });
 
   try {
+    throwIfAborted(env.signal);
+
     const actionPromise = Promise.resolve().then(() =>
-      task.action.run(inputs, env.context, task.settings, task.bindings),
+      task.action.run(
+        inputs,
+        env.context,
+        task.settings,
+        task.bindings,
+        env.signal,
+      ),
     );
     const outcome = await waitForTaskProgress(env, stepInfo.id, actionPromise);
 
@@ -88,6 +114,12 @@ export async function executeTaskStep(
       throw outcome.error;
     }
 
+    if (outcome.type === 'cancelled') {
+      env.clearStepSuspensions(stepInfo.id, outcome.error);
+      recordTaskCancellation(env, stepInfo, outcome.error);
+      throw outcome.error;
+    }
+
     return buildSuspensionContinuation(
       env,
       stepInfo.id,
@@ -114,8 +146,29 @@ const waitForTaskProgress = async (
   const suspension = env
     .waitForStepSuspension(stepId)
     .then<TaskProgressOutcome>((request) => ({ type: 'suspended', request }));
+  let cleanupCancellation = () => undefined;
+  const cancellation = new Promise<TaskProgressOutcome>((resolve) => {
+    if (env.signal.aborted) {
+      resolve({ type: 'cancelled', error: getAbortReason(env.signal) });
+
+      return;
+    }
+
+    const onAbort = () => {
+      resolve({ type: 'cancelled', error: getAbortReason(env.signal) });
+    };
 
-  return Promise.race([completion, suspension]);
+    env.signal.addEventListener('abort', onAbort, { once: true });
+    cleanupCancellation = () => {
+      env.signal.removeEventListener('abort', onAbort);
+    };
+  });
+
+  try {
+    return await Promise.race([completion, suspension, cancellation]);
+  } finally {
+    cleanupCancellation();
+  }
 };
 const completeTask = async (
   env: StepExecutorEnv,
@@ -126,14 +179,18 @@ const completeTask = async (
   result: unknown,
 ) => {
   await env.captureTaskOutput(task, state, result);
-  env.recordStepExecution(stepInfo, {
+  const stepExecution = 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.emit('hook:step:success', {
+    runId: env.runId,
+    step: stepInfo,
+    stepExecution,
+  });
   env.clearStepSuspensions(stepId);
 };
 const recordSuspension = (
@@ -142,7 +199,7 @@ const recordSuspension = (
   reason?: string,
   data?: unknown,
 ) => {
-  env.recordStepExecution(stepInfo, {
+  const stepExecution = env.recordStepExecution(stepInfo, {
     status: 'suspended',
     endedAt: Date.now(),
     reason,
@@ -152,6 +209,7 @@ const recordSuspension = (
   env.emit('hook:step:suspended', {
     runId: env.runId,
     step: stepInfo,
+    stepExecution,
     reason,
     data,
   });
@@ -231,14 +289,40 @@ const recordTaskFailure = (
   stepInfo: Suspension['step'],
   error: unknown,
 ) => {
-  env.recordStepExecution(stepInfo, {
+  const normalizedError = normalizeError(error);
+  const stepExecution = env.recordStepExecution(stepInfo, {
     status: 'failed',
     endedAt: Date.now(),
-    error: normalizeError(error),
+    error: normalizedError,
     context: { after: env.context.snapshot() },
   });
   env.markSnapshot(stepInfo, 'failed', normalizeErrorMessage(error));
-  env.emit('hook:step:error', { runId: env.runId, step: stepInfo, error });
+  env.emit('hook:step:error', {
+    runId: env.runId,
+    step: stepInfo,
+    stepExecution,
+    error,
+  });
+};
+const recordTaskCancellation = (
+  env: StepExecutorEnv,
+  stepInfo: Suspension['step'],
+  error: unknown,
+) => {
+  const normalizedError = normalizeError(error);
+  const stepExecution = env.recordStepExecution(stepInfo, {
+    status: 'cancelled',
+    endedAt: Date.now(),
+    error: normalizedError,
+    context: { after: env.context.snapshot() },
+  });
+  env.markSnapshot(stepInfo, 'cancelled', normalizeErrorMessage(error));
+  env.emit('hook:step:cancelled', {
+    runId: env.runId,
+    step: stepInfo,
+    stepExecution,
+    error,
+  });
 };
 const normalizeError = (error: unknown): { message: string; stack?: string } =>
   error instanceof Error

package/src/step-executors/types.ts

@@ -23,9 +23,21 @@ import type {
   Suspension,
 } from '../workflow-types';
 
+export type StepExecutorEnvForkOverrides = {
+  context?: BaseWorkflowContext;
+  signal?: AbortSignal;
+  setCurrentStep?: (step?: StepInfo) => void;
+  captureTaskOutput?: (
+    task: CompiledTask,
+    state: ExecutionState,
+    result: unknown,
+  ) => Promise<void>;
+};
+
 export type StepExecutorEnv = {
   compiled: CompiledWorkflow;
   context: BaseWorkflowContext;
+  signal: AbortSignal;
   runId?: string;
   buildInstanceStepInfo: (
     step: CompiledStep,
@@ -39,7 +51,7 @@ export type StepExecutorEnv = {
   recordStepExecution: (
     step: StepInfo,
     update: Partial<StepExecutionRecord>,
-  ) => void;
+  ) => StepExecutionRecord;
   emit: <K extends keyof WorkflowEventMap>(
     event: K,
     payload: WorkflowEventMap[K],
@@ -67,4 +79,5 @@ export type StepExecutorEnv = {
     state: ExecutionState,
     path: Array<number | string>,
   ) => Promise<Suspension | void>;
+  fork: (overrides: StepExecutorEnvForkOverrides) => StepExecutorEnv;
 };

package/src/suspension-rebuilder.ts

@@ -10,8 +10,6 @@ import {
   shouldStopLoop,
   updateAccumulator,
 } from './step-executors/loop-executor';
-import { executeParallel as runParallelExecutor } from './step-executors/parallel-executor';
-import { markStepsSkipped } from './step-executors/skip-helpers';
 import { wrapSuspensionContinuation } from './step-executors/suspension-continuation';
 import type { StepExecutorEnv } from './step-executors/types';
 import {
@@ -295,57 +293,7 @@ export function buildSuspensionForPath(
   }
 
   if (step.type === StepType.Parallel) {
-    if (rest[0] !== 'parallel') {
-      return null;
-    }
-
-    const childPath = rest.slice(1);
-    const childSuspension = buildSuspensionForPath(
-      deps,
-      step.steps,
-      state,
-      childPath,
-      [...currentPath, 'parallel'],
-      iterationDepth,
-      suspensionMetadata,
-    );
-
-    if (!childSuspension) {
-      return null;
-    }
-
-    const childIndex =
-      typeof childPath[0] === 'number' ? (childPath[0] as number) : 0;
-
-    return wrapSuspensionContinuation(childSuspension, async () => {
-      if (step.strategy === 'wait_any') {
-        if (childIndex + 1 < step.steps.length) {
-          markStepsSkipped(
-            env,
-            step.steps.slice(childIndex + 1),
-            state.iterationStack ?? [],
-          );
-        }
-
-        return deps.executeFlow(steps, state, pathPrefix, current + 1);
-      }
-
-      const next = await runParallelExecutor(
-        env,
-        step,
-        state,
-        currentPath,
-        childIndex + 1,
-      );
-
-      if (next) {
-        return wrapSuspensionContinuation(next, () =>
-          deps.executeFlow(steps, state, pathPrefix, current + 1),
-        );
-      }
-
-      return deps.executeFlow(steps, state, pathPrefix, current + 1);
-    });
+    return null;
   }
 
   if (step.type === StepType.Conditional) {

package/src/utils/timeout.ts

@@ -4,43 +4,113 @@
  * Full terms: see LICENSE.md.
  */
 
+import { getAbortReason, throwIfAborted } from '../errors';
+
 /**
  * Resolves after the specified duration; useful for retry delays.
  *
  * @param durationMs - Number of milliseconds to wait before resolving.
+ * @param signal - Optional signal used to cancel the wait.
  * @returns A promise that resolves once the duration elapses.
  */
-export const sleep = (durationMs: number): Promise<void> =>
-  new Promise((resolve) => setTimeout(resolve, durationMs));
+export const sleep = (
+  durationMs: number,
+  signal?: AbortSignal,
+): Promise<void> => {
+  if (!signal) {
+    return new Promise((resolve) => setTimeout(resolve, durationMs));
+  }
+
+  throwIfAborted(signal);
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, durationMs);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(getAbortReason(signal));
+    };
+
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+};
 
 /**
  * Wraps a promise and rejects if it does not settle within the timeout.
  *
  * @param promise - Operation that may take longer than the allowed timeout.
  * @param timeoutMs - Maximum time in milliseconds to wait before rejecting.
+ * @param signal - Optional signal used to cancel the operation.
  * @returns The result of the original promise when it resolves in time.
  * @throws Error when the timeout is exceeded.
  */
 export async function withTimeout<T>(
   promise: Promise<T>,
   timeoutMs?: number,
+  signal?: AbortSignal,
 ): Promise<T> {
-  if (!timeoutMs) {
+  if (!timeoutMs && !signal) {
     return promise;
   }
 
   return new Promise<T>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      reject(new Error(`Step execution exceeded timeout of ${timeoutMs}ms`));
-    }, timeoutMs);
+    let settled = false;
+    const timer = timeoutMs
+      ? setTimeout(() => {
+          settled = true;
+          signal?.removeEventListener('abort', onAbort);
+          reject(
+            new Error(`Step execution exceeded timeout of ${timeoutMs}ms`),
+          );
+        }, timeoutMs)
+      : undefined;
+    const onAbort = () => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+      reject(getAbortReason(signal as AbortSignal));
+    };
+
+    if (signal) {
+      if (signal.aborted) {
+        onAbort();
+
+        return;
+      }
+
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
 
     promise.then(
       (value) => {
-        clearTimeout(timer);
+        if (settled) {
+          return;
+        }
+
+        settled = true;
+        if (timer) {
+          clearTimeout(timer);
+        }
+        signal?.removeEventListener('abort', onAbort);
         resolve(value);
       },
       (error) => {
-        clearTimeout(timer);
+        if (settled) {
+          return;
+        }
+
+        settled = true;
+        if (timer) {
+          clearTimeout(timer);
+        }
+        signal?.removeEventListener('abort', onAbort);
         reject(error);
       },
     );

package/src/utils/workflow-definition-resources.ts

@@ -0,0 +1,111 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type { DefDefinition, WorkflowDefinition } from '../dsl.types';
+
+export type WorkflowDefinitionResourceDescriptor = {
+  kind: string;
+  settingsKey: string;
+};
+
+export type WorkflowDefinitionResourceRefs = Record<string, string[]>;
+
+export type WorkflowDefinitionResourceIdMaps = Record<
+  string,
+  Record<string, string>
+>;
+
+const getSettingsRef = (
+  definition: DefDefinition,
+  settingsKey: string,
+): string | null => {
+  const settings = definition.settings;
+  if (!settings || typeof settings !== 'object') {
+    return null;
+  }
+
+  const value = (settings as Record<string, unknown>)[settingsKey];
+
+  return typeof value === 'string' && value.trim() ? value : null;
+};
+
+/**
+ * Collect external resource IDs referenced by workflow definition defs.
+ */
+export const collectWorkflowDefinitionResourceRefs = (
+  definition: WorkflowDefinition,
+  descriptors: WorkflowDefinitionResourceDescriptor[],
+): WorkflowDefinitionResourceRefs => {
+  const result = Object.fromEntries(
+    descriptors.map((descriptor) => [descriptor.kind, new Set<string>()]),
+  ) as Record<string, Set<string>>;
+
+  for (const def of Object.values(definition.defs ?? {})) {
+    for (const descriptor of descriptors) {
+      if (def.kind !== descriptor.kind) {
+        continue;
+      }
+
+      const ref = getSettingsRef(def, descriptor.settingsKey);
+      if (ref) {
+        result[descriptor.kind].add(ref);
+      }
+    }
+  }
+
+  return Object.fromEntries(
+    Object.entries(result).map(([kind, refs]) => [kind, Array.from(refs)]),
+  );
+};
+
+/**
+ * Rewrite external resource IDs referenced by workflow definition defs.
+ */
+export const remapWorkflowDefinitionResourceRefs = (
+  definition: WorkflowDefinition,
+  descriptors: WorkflowDefinitionResourceDescriptor[],
+  idMaps: WorkflowDefinitionResourceIdMaps,
+): WorkflowDefinition => {
+  let didChange = false;
+  const nextDefs = Object.fromEntries(
+    Object.entries(definition.defs ?? {}).map(([defName, def]) => {
+      const descriptor = descriptors.find((item) => item.kind === def.kind);
+      if (!descriptor) {
+        return [defName, def];
+      }
+
+      const currentRef = getSettingsRef(def, descriptor.settingsKey);
+      const nextRef = currentRef
+        ? idMaps[descriptor.kind]?.[currentRef]
+        : undefined;
+      if (!currentRef || !nextRef || nextRef === currentRef) {
+        return [defName, def];
+      }
+
+      didChange = true;
+
+      return [
+        defName,
+        {
+          ...def,
+          settings: {
+            ...(def.settings ?? {}),
+            [descriptor.settingsKey]: nextRef,
+          },
+        },
+      ];
+    }),
+  ) as WorkflowDefinition['defs'];
+
+  if (!didChange) {
+    return definition;
+  }
+
+  return {
+    ...definition,
+    defs: nextDefs,
+  };
+};

package/src/workflow-event-emitter.ts

@@ -4,6 +4,8 @@
  * Full terms: see LICENSE.md.
  */
 
+import type { StepExecutionRecord } from './context';
+
 export enum StepType {
   Task = 'task',
   Parallel = 'parallel',
@@ -17,6 +19,12 @@ export type StepInfo = {
   type: StepType;
 };
 
+export type StepWorkflowEventPayload = {
+  runId?: string;
+  step: StepInfo;
+  stepExecution?: StepExecutionRecord;
+};
+
 export type WorkflowEventMap = {
   'hook:workflow:start': { runId?: string };
   'hook:workflow:finish': { runId?: string; output: Record<string, unknown> };
@@ -27,12 +35,11 @@ export type WorkflowEventMap = {
     reason?: string;
     data?: unknown;
   };
-  'hook:step:start': { runId?: string; step: StepInfo };
-  'hook:step:success': { runId?: string; step: StepInfo };
-  'hook:step:error': { runId?: string; step: StepInfo; error: unknown };
-  'hook:step:suspended': {
-    runId?: string;
-    step: StepInfo;
+  'hook:step:start': StepWorkflowEventPayload;
+  'hook:step:success': StepWorkflowEventPayload;
+  'hook:step:error': StepWorkflowEventPayload & { error: unknown };
+  'hook:step:cancelled': StepWorkflowEventPayload & { error: unknown };
+  'hook:step:suspended': StepWorkflowEventPayload & {
     reason?: string;
     data?: unknown;
   };