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

package/dist/cjs/suspension-rebuilder.js

@@ -9,8 +9,6 @@ exports.parseSuspendedStepId = parseSuspendedStepId;
 exports.rebuildSuspension = rebuildSuspension;
 exports.buildSuspensionForPath = buildSuspensionForPath;
 const loop_executor_1 = require("./step-executors/loop-executor");
-const parallel_executor_1 = require("./step-executors/parallel-executor");
-const skip_helpers_1 = require("./step-executors/skip-helpers");
 const suspension_continuation_1 = require("./step-executors/suspension-continuation");
 const workflow_event_emitter_1 = require("./workflow-event-emitter");
 /**
@@ -171,28 +169,7 @@ function buildSuspensionForPath(deps, steps, state, targetPath, pathPrefix, iter
         };
     }
     if (step.type === workflow_event_emitter_1.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] : 0;
-        return (0, suspension_continuation_1.wrapSuspensionContinuation)(childSuspension, async () => {
-            if (step.strategy === 'wait_any') {
-                if (childIndex + 1 < step.steps.length) {
-                    (0, skip_helpers_1.markStepsSkipped)(env, step.steps.slice(childIndex + 1), state.iterationStack ?? []);
-                }
-                return deps.executeFlow(steps, state, pathPrefix, current + 1);
-            }
-            const next = await (0, parallel_executor_1.executeParallel)(env, step, state, currentPath, childIndex + 1);
-            if (next) {
-                return (0, suspension_continuation_1.wrapSuspensionContinuation)(next, () => deps.executeFlow(steps, state, pathPrefix, current + 1));
-            }
-            return deps.executeFlow(steps, state, pathPrefix, current + 1);
-        });
+        return null;
     }
     if (step.type === workflow_event_emitter_1.StepType.Conditional) {
         if (rest[0] !== 'branch' || typeof rest[1] !== 'number') {

package/dist/cjs/utils/naming.js

@@ -5,10 +5,10 @@
  * Full terms: see LICENSE.md.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isSnakeCaseName = void 0;
+exports.isSnakeCaseName = exports.SNAKE_CASE_REGEX = void 0;
 exports.assertSnakeCaseName = assertSnakeCaseName;
 exports.toSnakeCase = toSnakeCase;
-const SNAKE_CASE_REGEX = /^[a-z0-9]+(?:_[a-z0-9]+)+$/;
+exports.SNAKE_CASE_REGEX = /^[a-z0-9]+(?:_[a-z0-9]+)*$/;
 /**
  * Verifies that names follow the snake_case convention required by the system.
  *
@@ -17,7 +17,7 @@ const SNAKE_CASE_REGEX = /^[a-z0-9]+(?:_[a-z0-9]+)+$/;
  * @throws Error when the name is not snake_case.
  */
 function assertSnakeCaseName(name, entity) {
-    if (!SNAKE_CASE_REGEX.test(name)) {
+    if (!exports.SNAKE_CASE_REGEX.test(name)) {
         throw new Error(`${entity} name must be snake_case with at least one underscore. Received: "${name}"`);
     }
 }
@@ -27,7 +27,7 @@ function assertSnakeCaseName(name, entity) {
  * @param value - Text to evaluate.
  * @returns `true` when the value is snake_case; otherwise `false`.
  */
-const isSnakeCaseName = (value) => SNAKE_CASE_REGEX.test(value);
+const isSnakeCaseName = (value) => exports.SNAKE_CASE_REGEX.test(value);
 exports.isSnakeCaseName = isSnakeCaseName;
 /**
  * Converts arbitrary text into snake_case for use in workflow entities.

package/dist/cjs/utils/timeout.js

@@ -7,35 +7,90 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sleep = void 0;
 exports.withTimeout = withTimeout;
+const errors_1 = require("../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.
  */
-const sleep = (durationMs) => new Promise((resolve) => setTimeout(resolve, durationMs));
+const sleep = (durationMs, signal) => {
+    if (!signal) {
+        return new Promise((resolve) => setTimeout(resolve, durationMs));
+    }
+    (0, errors_1.throwIfAborted)(signal);
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, durationMs);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject((0, errors_1.getAbortReason)(signal));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+};
 exports.sleep = sleep;
 /**
  * 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.
  */
-async function withTimeout(promise, timeoutMs) {
-    if (!timeoutMs) {
+async function withTimeout(promise, timeoutMs, signal) {
+    if (!timeoutMs && !signal) {
         return promise;
     }
     return new Promise((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((0, errors_1.getAbortReason)(signal));
+        };
+        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/dist/cjs/utils/workflow-definition-resources.js

@@ -0,0 +1,73 @@
+"use strict";
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.remapWorkflowDefinitionResourceRefs = exports.collectWorkflowDefinitionResourceRefs = void 0;
+const getSettingsRef = (definition, settingsKey) => {
+    const settings = definition.settings;
+    if (!settings || typeof settings !== 'object') {
+        return null;
+    }
+    const value = settings[settingsKey];
+    return typeof value === 'string' && value.trim() ? value : null;
+};
+/**
+ * Collect external resource IDs referenced by workflow definition defs.
+ */
+const collectWorkflowDefinitionResourceRefs = (definition, descriptors) => {
+    const result = Object.fromEntries(descriptors.map((descriptor) => [descriptor.kind, new Set()]));
+    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)]));
+};
+exports.collectWorkflowDefinitionResourceRefs = collectWorkflowDefinitionResourceRefs;
+/**
+ * Rewrite external resource IDs referenced by workflow definition defs.
+ */
+const remapWorkflowDefinitionResourceRefs = (definition, descriptors, idMaps) => {
+    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,
+                },
+            },
+        ];
+    }));
+    if (!didChange) {
+        return definition;
+    }
+    return {
+        ...definition,
+        defs: nextDefs,
+    };
+};
+exports.remapWorkflowDefinitionResourceRefs = remapWorkflowDefinitionResourceRefs;

package/dist/cjs/workflow-compiler.js

@@ -9,7 +9,6 @@ exports.compileWorkflow = void 0;
 const zod_1 = require("zod");
 const base_binding_1 = require("./bindings/base-binding");
 const dsl_types_1 = require("./dsl.types");
-const naming_1 = require("./utils/naming");
 const workflow_event_emitter_1 = require("./workflow-event-emitter");
 const workflow_values_1 = require("./workflow-values");
 /** Build a stable identifier for a step using its path and label. */
@@ -103,7 +102,6 @@ const compileTasks = (definition, options) => {
     }
     assertActionsBound(taskDefinitions, options.actions);
     for (const [taskName, task] of Object.entries(taskDefinitions)) {
-        (0, naming_1.assertSnakeCaseName)(taskName, 'action');
         const action = options.actions[task.action];
         const settingsPayload = (0, workflow_values_1.mergeSettings)(defaultSettings, task.settings);
         const parsedSettings = action.parseSettings(settingsPayload);

package/dist/cjs/workflow-runner.js

@@ -7,6 +7,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkflowRunner = void 0;
 const context_1 = require("./context");
+const errors_1 = require("./errors");
 const runner_runtime_control_1 = require("./runner-runtime-control");
 const conditional_executor_1 = require("./step-executors/conditional-executor");
 const loop_executor_1 = require("./step-executors/loop-executor");
@@ -122,7 +123,8 @@ class WorkflowRunner {
         if (!state) {
             throw new Error('Workflow state not initialized.');
         }
-        return this.runExecution(() => this.executeFlow(this.compiled.flow, state, []));
+        const env = this.createExecutorEnv();
+        return this.runExecution(() => this.executeFlow(this.compiled.flow, state, [], 0, env));
     }
     /**
      * Resume a previously suspended workflow using the supplied resume data.
@@ -316,7 +318,7 @@ class WorkflowRunner {
         const mergedContext = existing?.context || update.context
             ? { ...existing?.context, ...update.context }
             : undefined;
-        this.stepLog[step.id] = {
+        const nextRecord = {
             ...base,
             ...update,
             id: step.id,
@@ -324,6 +326,12 @@ class WorkflowRunner {
             status: update.status ?? base.status,
             context: mergedContext,
         };
+        this.stepLog[step.id] = nextRecord;
+        return {
+            ...nextRecord,
+            context: nextRecord.context ? { ...nextRecord.context } : undefined,
+            error: nextRecord.error ? { ...nextRecord.error } : undefined,
+        };
     }
     /**
      * Construct the environment object passed to step executors.
@@ -331,21 +339,28 @@ class WorkflowRunner {
      * @returns A step executor environment bound to this runner.
      * @throws When the workflow context is missing.
      */
-    createExecutorEnv() {
-        if (!this.context) {
+    createExecutorEnv(overrides = {}) {
+        const context = overrides.context ?? this.context;
+        if (!context) {
             throw new Error('Workflow context is not attached.');
         }
-        return {
+        const signal = overrides.signal ?? new AbortController().signal;
+        const setCurrentStep = overrides.setCurrentStep ??
+            ((step) => {
+                this.currentStep = step;
+            });
+        const captureTaskOutput = overrides.captureTaskOutput ??
+            ((task, state, result) => this.captureTaskOutput(task, state, result));
+        const executorEnv = {
             compiled: this.compiled,
-            context: this.context,
+            context,
+            signal,
             runId: this.runId,
             buildInstanceStepInfo: (step, iterationStack) => this.buildInstanceStepInfo(step, iterationStack),
             markSnapshot: (step, status, reason) => this.markSnapshot(step, status, reason),
             recordStepExecution: (step, update) => this.recordStepExecution(step, update),
             emit: (event, payload) => this.emit(event, payload),
-            setCurrentStep: (step) => {
-                this.currentStep = step;
-            },
+            setCurrentStep,
             beginStepExecution: (stepId) => {
                 if (!this.runtimeControl) {
                     return `${stepId}#1`;
@@ -370,10 +385,17 @@ class WorkflowRunner {
             recordStepSuspendResult: (params) => {
                 this.runtimeControl?.recordStepSuspendResult(params);
             },
-            captureTaskOutput: (task, state, result) => this.captureTaskOutput(task, state, result),
-            executeFlow: (steps, state, path, startIndex) => this.executeFlow(steps, state, path, startIndex),
-            executeStep: (step, state, path) => this.executeStep(step, state, path),
+            captureTaskOutput,
+            executeFlow: (steps, state, path, startIndex) => this.executeFlow(steps, state, path, startIndex, executorEnv),
+            executeStep: (step, state, path) => this.executeStep(step, state, path, executorEnv),
+            fork: (forkOverrides) => this.createExecutorEnv({
+                context: forkOverrides.context ?? context,
+                signal: forkOverrides.signal ?? signal,
+                setCurrentStep: forkOverrides.setCurrentStep ?? setCurrentStep,
+                captureTaskOutput: forkOverrides.captureTaskOutput ?? captureTaskOutput,
+            }),
         };
+        return executorEnv;
     }
     /**
      * Build dependencies used to reconstruct a suspension from persisted state.
@@ -402,14 +424,15 @@ class WorkflowRunner {
      * @param startIndex Index to resume from within the flow.
      * @returns A suspension if execution pauses, otherwise void.
      */
-    async executeFlow(steps, state, path, startIndex = 0) {
+    async executeFlow(steps, state, path, startIndex = 0, env = this.createExecutorEnv()) {
         // Walk the flow sequentially; if a step suspends, wrap its continuation so we resume at the same index.
         for (let index = startIndex; index < steps.length; index += 1) {
+            (0, errors_1.throwIfAborted)(env.signal);
             const step = steps[index];
             const stepPath = [...path, index];
-            const suspension = await this.executeStep(step, state, stepPath);
+            const suspension = await this.executeStep(step, state, stepPath, env);
             if (suspension) {
-                return (0, suspension_continuation_1.wrapSuspensionContinuation)(suspension, () => this.executeFlow(steps, state, path, index + 1));
+                return (0, suspension_continuation_1.wrapSuspensionContinuation)(suspension, () => this.executeFlow(steps, state, path, index + 1, env));
             }
         }
         return undefined;
@@ -422,8 +445,8 @@ class WorkflowRunner {
      * @param path Tokens describing the location of the step in the workflow.
      * @returns A suspension if the step pauses execution, otherwise void.
      */
-    async executeStep(step, state, path) {
-        const env = this.createExecutorEnv();
+    async executeStep(step, state, path, env = this.createExecutorEnv()) {
+        (0, errors_1.throwIfAborted)(env.signal);
         switch (step.type) {
             case workflow_event_emitter_1.StepType.Task:
                 return (0, task_executor_1.executeTaskStep)(env, step, state, path);

package/dist/esm/action/abstract-action.js

@@ -5,6 +5,7 @@
  */
 import { z } from 'zod';
 import { BaseSettingsSchema } from '../dsl.types';
+import { throwIfAborted } from '../errors';
 import { assertSnakeCaseName } from '../utils/naming';
 import { sleep, withTimeout } from '../utils/timeout';
 const BASE_SETTINGS_KEYS = Object.keys(BaseSettingsSchema.shape);
@@ -64,7 +65,7 @@ export class AbstractAction {
             .parse(payload ?? {});
         return (settings ?? {});
     }
-    async run(payload, context, settings, bindings) {
+    async run(payload, context, settings, bindings, signal) {
         const input = this.parseInput(payload);
         const parsedSettings = this.parseSettings(settings);
         const parsedBindings = (bindings ?? {});
@@ -86,13 +87,17 @@ export class AbstractAction {
         const jitter = retrySettings.jitter;
         const multiplier = retrySettings.multiplier;
         while (attempt < maxAttempts) {
+            if (signal) {
+                throwIfAborted(signal);
+            }
             try {
                 const result = await withTimeout(this.execute({
                     input,
                     context,
                     settings: parsedSettings,
                     bindings: parsedBindings,
-                }), timeoutMs);
+                    signal: signal ?? new AbortController().signal,
+                }), timeoutMs, signal);
                 return this.parseOutput(result);
             }
             catch (error) {
@@ -108,7 +113,7 @@ export class AbstractAction {
                     const jitterFactor = jitter > 0 ? 1 + (Math.random() * 2 - 1) * jitter : 1;
                     const jitteredDelay = Math.max(0, Math.round(delay * jitterFactor));
                     if (jitteredDelay > 0) {
-                        await sleep(jitteredDelay);
+                        await sleep(jitteredDelay, signal);
                     }
                 }
                 const nextDelay = currentDelay * multiplier;

package/dist/esm/dsl.types.js

@@ -7,6 +7,7 @@ import jsonata from 'jsonata';
 import { parse as parseYaml } from 'yaml';
 import { z } from 'zod';
 import { validateAndResolveBindings } from './bindings/base-binding';
+import { SNAKE_CASE_REGEX } from './utils/naming';
 export const ExpressionStringSchema = z
     .string()
     .regex(/^=/, 'Expression strings must start with "="')
@@ -227,7 +228,7 @@ 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/dist/esm/errors.js

@@ -0,0 +1,33 @@
+/*
+ * 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) => error instanceof WorkflowCancellationError ||
+    (error instanceof Error && error.name === 'WorkflowCancellationError');
+export const getAbortReason = (signal) => {
+    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) => {
+    if (signal.aborted) {
+        throw getAbortReason(signal);
+    }
+};

package/dist/esm/index.js

@@ -10,7 +10,9 @@ export * from './dsl.types';
 export { compileWorkflow, Workflow, WorkflowEventEmitter, WorkflowRunner, } from './workflow';
 export { StepType } from './workflow-event-emitter';
 export { NonDeterministicWorkflowError } from './runner-runtime-control';
+export { ParallelSuspensionError, WorkflowCancellationError } from './errors';
 export { compileValue, evaluateMapping, evaluateValue, mergeSettings, } from './workflow-values';
 export { createDeferred } from './utils/deferred';
 export { assertSnakeCaseName, isSnakeCaseName, toSnakeCase, } from './utils/naming';
 export { sleep, withTimeout } from './utils/timeout';
+export { collectWorkflowDefinitionResourceRefs, remapWorkflowDefinitionResourceRefs, } from './utils/workflow-definition-resources';