@hexabot-ai/agentic 3.0.1-alpha.0

package/dist/cjs/step-executors/parallel-executor.js

@@ -0,0 +1,51 @@
+"use strict";
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeParallel = executeParallel;
+const skip_helpers_1 = require("./skip-helpers");
+/**
+ * Execute a set of steps in parallel order, respecting the configured strategy.
+ *
+ * @param env Executor environment providing helpers and workflow context.
+ * @param step The parallel step definition including strategy and children.
+ * @param state Mutable workflow execution state.
+ * @param path Path tokens locating this parallel block in the workflow.
+ * @param startIndex Index to resume execution from when continuing.
+ * @returns A suspension if a child pauses execution, otherwise void.
+ */
+async function executeParallel(env, step, state, path, startIndex = 0) {
+    for (let index = startIndex; index < step.steps.length; index += 1) {
+        const child = step.steps[index];
+        const childPath = [...path, 'parallel', index];
+        const suspension = await env.executeStep(child, state, childPath);
+        if (suspension) {
+            return {
+                ...suspension,
+                continue: async (resumeData) => {
+                    const next = await suspension.continue(resumeData);
+                    if (next) {
+                        return next;
+                    }
+                    if (step.strategy === 'wait_any') {
+                        if (index + 1 < step.steps.length) {
+                            (0, skip_helpers_1.markStepsSkipped)(env, step.steps.slice(index + 1), state.iterationStack);
+                        }
+                        return undefined;
+                    }
+                    return executeParallel(env, step, state, path, index + 1);
+                },
+            };
+        }
+        if (step.strategy === 'wait_any') {
+            if (index + 1 < step.steps.length) {
+                (0, skip_helpers_1.markStepsSkipped)(env, step.steps.slice(index + 1), state.iterationStack);
+            }
+            return undefined;
+        }
+    }
+    return undefined;
+}

package/dist/cjs/step-executors/skip-helpers.js

@@ -0,0 +1,29 @@
+"use strict";
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.markStepsSkipped = void 0;
+const workflow_event_emitter_1 = require("../workflow-event-emitter");
+const markStepSkipped = (env, step, iterationStack, reason) => {
+    const stepInfo = env.buildInstanceStepInfo(step, iterationStack);
+    env.markSnapshot(stepInfo, 'skipped', reason);
+    env.emit('hook:step:skipped', { runId: env.runId, step: stepInfo, reason });
+    switch (step.type) {
+        case workflow_event_emitter_1.StepType.Parallel:
+            step.steps.forEach((child) => markStepSkipped(env, child, iterationStack, reason));
+            break;
+        case workflow_event_emitter_1.StepType.Conditional:
+            step.branches.forEach((branch) => branch.steps.forEach((child) => markStepSkipped(env, child, iterationStack, reason)));
+            break;
+        case workflow_event_emitter_1.StepType.Loop:
+        case workflow_event_emitter_1.StepType.Task:
+            break;
+    }
+};
+const markStepsSkipped = (env, steps, iterationStack, reason) => {
+    steps.forEach((step) => markStepSkipped(env, step, iterationStack, reason));
+};
+exports.markStepsSkipped = markStepsSkipped;

package/dist/cjs/step-executors/task-executor.js

@@ -0,0 +1,155 @@
+"use strict";
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeTaskStep = executeTaskStep;
+const workflow_values_1 = require("../workflow-values");
+/**
+ * Execute a task step by running its task and handling suspension or output mapping.
+ *
+ * @param env Executor environment with compiled workflow and helpers.
+ * @param step The compiled task step to execute.
+ * @param state Mutable workflow execution state.
+ * @param _path Location of the step within the workflow (unused in this executor).
+ * @returns A suspension if the task pauses execution, otherwise void.
+ */
+async function executeTaskStep(env, step, state, _path) {
+    void _path;
+    const task = env.compiled.tasks[step.taskName];
+    if (!task) {
+        throw new Error(`Task "${step.taskName}" is not defined.`);
+    }
+    const stepInfo = env.buildInstanceStepInfo(step, state.iterationStack);
+    const scope = {
+        input: state.input,
+        context: env.context.state,
+        output: state.output,
+        iteration: state.iteration,
+        accumulator: state.accumulator,
+    };
+    const inputs = await (0, workflow_values_1.evaluateMapping)(task.inputs, scope);
+    env.recordStepExecution(stepInfo, {
+        action: task.actionName,
+        status: 'running',
+        startedAt: Date.now(),
+        input: inputs,
+        context: { before: env.context.snapshot() },
+    });
+    env.beginStepExecution?.(stepInfo.id);
+    env.setCurrentStep(stepInfo);
+    env.markSnapshot(stepInfo, 'running');
+    env.emit('hook:step:start', { runId: env.runId, step: stepInfo });
+    try {
+        const actionPromise = Promise.resolve().then(() => task.action.run(inputs, env.context, task.settings, task.bindings));
+        const outcome = await waitForTaskProgress(env, stepInfo.id, actionPromise);
+        if (outcome.type === 'completed') {
+            await completeTask(env, stepInfo.id, stepInfo, task, state, outcome.value);
+            return undefined;
+        }
+        if (outcome.type === 'failed') {
+            env.clearStepSuspensions(stepInfo.id, outcome.error);
+            recordTaskFailure(env, stepInfo, outcome.error);
+            throw outcome.error;
+        }
+        return buildSuspensionContinuation(env, stepInfo.id, stepInfo, task, state, actionPromise, outcome.request);
+    }
+    finally {
+        env.setCurrentStep(undefined);
+    }
+}
+const waitForTaskProgress = async (env, stepId, actionPromise) => {
+    const completion = actionPromise.then((value) => ({ type: 'completed', value }), (error) => ({ type: 'failed', error }));
+    const suspension = env
+        .waitForStepSuspension(stepId)
+        .then((request) => ({ type: 'suspended', request }));
+    return Promise.race([completion, suspension]);
+};
+const completeTask = async (env, stepId, stepInfo, task, state, result) => {
+    await env.captureTaskOutput(task, state, result);
+    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.clearStepSuspensions(stepId);
+};
+const recordSuspension = (env, stepInfo, reason, data) => {
+    env.recordStepExecution(stepInfo, {
+        status: 'suspended',
+        endedAt: Date.now(),
+        reason,
+        context: { after: env.context.snapshot() },
+    });
+    env.markSnapshot(stepInfo, 'suspended', reason);
+    env.emit('hook:step:suspended', {
+        runId: env.runId,
+        step: stepInfo,
+        reason,
+        data,
+    });
+};
+const buildSuspensionContinuation = (env, stepId, stepInfo, task, state, actionPromise, request) => {
+    recordSuspension(env, stepInfo, request.reason, request.data);
+    let resumed = false;
+    return {
+        step: stepInfo,
+        reason: request.reason,
+        data: request.data,
+        stepExecId: request.stepExecId,
+        suspendIndex: request.suspendIndex,
+        suspendKey: request.suspendKey,
+        awaitResults: request.awaitResults,
+        continue: async (resumeData) => {
+            if (resumed) {
+                throw new Error(`Suspension for step "${stepInfo.id}" has already been resumed.`);
+            }
+            resumed = true;
+            env.setCurrentStep(stepInfo);
+            env.recordStepSuspendResult?.({
+                stepId,
+                stepExecId: request.stepExecId,
+                suspendIndex: request.suspendIndex,
+                suspendKey: request.suspendKey,
+                resumeData,
+            });
+            request.resume.resolve(resumeData);
+            let outcome;
+            try {
+                outcome = await waitForTaskProgress(env, stepId, actionPromise);
+            }
+            finally {
+                env.setCurrentStep(undefined);
+            }
+            if (outcome.type === 'suspended') {
+                return buildSuspensionContinuation(env, stepId, stepInfo, task, state, actionPromise, outcome.request);
+            }
+            if (outcome.type === 'completed') {
+                await completeTask(env, stepId, stepInfo, task, state, outcome.value);
+                return undefined;
+            }
+            env.clearStepSuspensions(stepId, outcome.error);
+            recordTaskFailure(env, stepInfo, outcome.error);
+            throw outcome.error;
+        },
+    };
+};
+const recordTaskFailure = (env, stepInfo, error) => {
+    env.recordStepExecution(stepInfo, {
+        status: 'failed',
+        endedAt: Date.now(),
+        error: normalizeError(error),
+        context: { after: env.context.snapshot() },
+    });
+    env.markSnapshot(stepInfo, 'failed', normalizeErrorMessage(error));
+    env.emit('hook:step:error', { runId: env.runId, step: stepInfo, error });
+};
+const normalizeError = (error) => error instanceof Error
+    ? { message: error.message, stack: error.stack }
+    : { message: String(error) };
+const normalizeErrorMessage = (error) => error instanceof Error ? error.message : String(error);

package/dist/cjs/step-executors/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/suspension-rebuilder.js

@@ -0,0 +1,301 @@
+"use strict";
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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 workflow_event_emitter_1 = require("./workflow-event-emitter");
+/**
+ * Parse a suspended step id into its execution path and iteration stack.
+ *
+ * @param stepId The serialized step identifier stored in snapshots.
+ * @returns The decoded path tokens and iteration stack.
+ */
+function parseSuspendedStepId(stepId) {
+    const iterationMatch = stepId.match(/^(.*)\[(.+)\]$/);
+    const baseId = iterationMatch ? iterationMatch[1] : stepId;
+    const iterationStack = iterationMatch
+        ? iterationMatch[2]
+            .split('.')
+            .map((token) => Number.parseInt(token, 10))
+            .filter((value) => !Number.isNaN(value))
+        : [];
+    const [pathPart] = baseId.split(':');
+    const path = pathPart.length === 0 || pathPart === 'root'
+        ? []
+        : pathPart.split('.').map((token) => {
+            const numeric = Number.parseInt(token, 10);
+            return Number.isNaN(numeric) ? token : numeric;
+        });
+    return { path, iterationStack };
+}
+/**
+ * Rebuild a suspension object based on persisted state and step identifiers.
+ *
+ * @param deps Dependencies needed to reconstruct executors and events.
+ * @param param0 Persisted state and metadata about the suspended step.
+ * @param param0.state Execution state captured at suspension time.
+ * @param param0.stepId Serialized step id used to locate the suspension point.
+ * @param param0.reason Optional reason supplied when the workflow suspended.
+ * @param param0.data Arbitrary payload provided with the suspension.
+ * @returns A suspension ready to be resumed, or null if reconstruction fails.
+ */
+function rebuildSuspension(deps, { state, stepId, reason, data, stepExecId, suspendIndex, suspendKey, awaitResults, }) {
+    if (!state) {
+        return null;
+    }
+    const { path, iterationStack } = parseSuspendedStepId(stepId);
+    const executionState = {
+        ...state,
+        iterationStack: iterationStack.length > 0 ? iterationStack : (state.iterationStack ?? []),
+    };
+    const suspensionMetadata = {
+        stepExecId,
+        suspendIndex,
+        suspendKey,
+        reason,
+        awaitResults,
+    };
+    const suspension = buildSuspensionForPath(deps, deps.compiled.flow, executionState, path, [], 0, suspensionMetadata);
+    if (!suspension) {
+        return null;
+    }
+    return {
+        ...suspension,
+        reason,
+        data,
+        stepExecId,
+        suspendIndex,
+        suspendKey,
+        awaitResults,
+    };
+}
+/**
+ * Walk the compiled flow to rebuild the continuation matching a target path.
+ *
+ * @param deps Dependencies for executor creation and event emission.
+ * @param steps The steps to search for the suspended step.
+ * @param state Mutable execution state to thread through the traversal.
+ * @param targetPath Path tokens identifying the suspended step location.
+ * @param pathPrefix Prefix accumulated while descending the tree.
+ * @param iterationDepth Current loop depth to match iteration stacks.
+ * @returns A rebuilt suspension or null if the path cannot be matched.
+ */
+function buildSuspensionForPath(deps, steps, state, targetPath, pathPrefix, iterationDepth = 0, suspensionMetadata = {}) {
+    if (!deps.context) {
+        throw new Error('Workflow context is not attached.');
+    }
+    const env = deps.createExecutorEnv();
+    if (targetPath.length === 0) {
+        return null;
+    }
+    const [current, ...rest] = targetPath;
+    if (typeof current !== 'number') {
+        return null;
+    }
+    const step = steps[current];
+    const currentPath = [...pathPrefix, current];
+    if (!step) {
+        return null;
+    }
+    if (rest.length === 0) {
+        if (step.type !== workflow_event_emitter_1.StepType.Task) {
+            return null;
+        }
+        const stepInfo = deps.buildInstanceStepInfo(step, state.iterationStack);
+        const replayStepExecId = suspensionMetadata.stepExecId ?? `${stepInfo.id}#1`;
+        const replaySuspension = suspensionMetadata.suspendIndex !== undefined ||
+            suspensionMetadata.suspendKey !== undefined
+            ? {
+                suspendIndex: suspensionMetadata.suspendIndex,
+                suspendKey: suspensionMetadata.suspendKey,
+                reason: suspensionMetadata.reason,
+            }
+            : undefined;
+        return {
+            step: stepInfo,
+            continue: async (resumeData) => {
+                const executorEnv = deps.createExecutorEnv();
+                const prepareStepReplay = executorEnv
+                    .prepareStepReplay;
+                const recordStepSuspendResult = executorEnv.recordStepSuspendResult;
+                const primeStepResumeData = executorEnv
+                    .primeStepResumeData;
+                const executeStep = executorEnv
+                    .executeStep;
+                if (typeof executeStep === 'function') {
+                    if (typeof prepareStepReplay === 'function') {
+                        prepareStepReplay({
+                            stepId: stepInfo.id,
+                            stepExecId: replayStepExecId,
+                            awaitResults: suspensionMetadata.awaitResults,
+                            activeSuspension: replaySuspension,
+                        });
+                    }
+                    if (typeof recordStepSuspendResult === 'function' &&
+                        replaySuspension) {
+                        recordStepSuspendResult({
+                            stepId: stepInfo.id,
+                            stepExecId: replayStepExecId,
+                            suspendIndex: suspensionMetadata.suspendIndex,
+                            suspendKey: suspensionMetadata.suspendKey,
+                            resumeData,
+                        });
+                    }
+                    else if (typeof primeStepResumeData === 'function') {
+                        primeStepResumeData(stepInfo.id, resumeData);
+                    }
+                    const resumed = await executeStep(step, state, currentPath);
+                    if (resumed) {
+                        return {
+                            ...resumed,
+                            continue: async (nextResumeData) => {
+                                const next = await resumed.continue(nextResumeData);
+                                if (next) {
+                                    return next;
+                                }
+                                return deps.executeFlow(steps, state, pathPrefix, current + 1);
+                            },
+                        };
+                    }
+                    return deps.executeFlow(steps, state, pathPrefix, current + 1);
+                }
+                const task = deps.compiled.tasks[step.taskName];
+                if (!task) {
+                    throw new Error(`Task "${step.taskName}" is not defined.`);
+                }
+                await deps.captureTaskOutput(task, state, resumeData);
+                deps.markSnapshot(stepInfo, 'completed');
+                deps.emit('hook:step:success', { runId: deps.runId, step: stepInfo });
+                return deps.executeFlow(steps, state, pathPrefix, current + 1);
+            },
+        };
+    }
+    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 {
+            ...childSuspension,
+            continue: async (resumeData) => {
+                const next = await childSuspension.continue(resumeData);
+                if (next) {
+                    return next;
+                }
+                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 undefined;
+                }
+                return (0, parallel_executor_1.executeParallel)(env, step, state, currentPath, childIndex + 1);
+            },
+        };
+    }
+    if (step.type === workflow_event_emitter_1.StepType.Conditional) {
+        if (rest[0] !== 'branch' || typeof rest[1] !== 'number') {
+            return null;
+        }
+        const branchIndex = rest[1];
+        const childPath = rest.slice(2);
+        const branch = step.branches[branchIndex];
+        if (!branch) {
+            return null;
+        }
+        const branchSuspension = buildSuspensionForPath(deps, branch.steps, state, childPath, [...currentPath, 'branch', branchIndex], iterationDepth, suspensionMetadata);
+        if (!branchSuspension) {
+            return null;
+        }
+        return {
+            ...branchSuspension,
+            continue: async (resumeData) => {
+                const next = await branchSuspension.continue(resumeData);
+                if (next) {
+                    return next;
+                }
+                return undefined;
+            },
+        };
+    }
+    if (step.type === workflow_event_emitter_1.StepType.Loop) {
+        if (rest.length < 1 || typeof rest[0] !== 'string') {
+            return null;
+        }
+        const loopToken = rest[0];
+        const childPath = rest.slice(1);
+        const targetIterationStack = state.iterationStack ?? [];
+        const iterationIndex = targetIterationStack[iterationDepth] ?? state.iteration?.index;
+        if (iterationIndex === undefined) {
+            return null;
+        }
+        const ancestorIterationStack = targetIterationStack.slice(0, iterationDepth);
+        const iterationState = {
+            ...state,
+            iterationStack: targetIterationStack,
+            iteration: state.iteration ??
+                {
+                    item: undefined,
+                    index: iterationIndex,
+                },
+        };
+        const childSuspension = buildSuspensionForPath(deps, step.steps, iterationState, childPath, [...currentPath, loopToken], iterationDepth + 1, suspensionMetadata);
+        if (!childSuspension) {
+            return null;
+        }
+        const accumulator = iterationState.accumulator ?? state.accumulator ?? undefined;
+        return {
+            ...childSuspension,
+            continue: async (resumeData) => {
+                const next = await childSuspension.continue(resumeData);
+                if (next) {
+                    return next;
+                }
+                const scope = {
+                    input: iterationState.input,
+                    context: env.context.state,
+                    output: iterationState.output,
+                    iteration: iterationState.iteration ?? {
+                        item: undefined,
+                        index: iterationIndex,
+                    },
+                    accumulator,
+                };
+                const updatedAccumulator = await (0, loop_executor_1.updateAccumulator)(step, scope, accumulator);
+                const shouldStop = await (0, loop_executor_1.shouldStopLoop)(step, scope);
+                state.output = iterationState.output;
+                if (step.accumulate && step.name) {
+                    state.output[step.name] = {
+                        [step.accumulate.as]: updatedAccumulator,
+                    };
+                }
+                if (step.accumulate) {
+                    state.accumulator = updatedAccumulator;
+                }
+                if (shouldStop) {
+                    return undefined;
+                }
+                const baseState = {
+                    ...iterationState,
+                    iterationStack: ancestorIterationStack,
+                    accumulator: updatedAccumulator,
+                    output: state.output,
+                };
+                return (0, loop_executor_1.executeLoop)(env, step, baseState, currentPath, iterationIndex + 1);
+            },
+        };
+    }
+    return null;
+}

package/dist/cjs/utils/deferred.js

@@ -0,0 +1,17 @@
+"use strict";
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDeferred = createDeferred;
+function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}

package/dist/cjs/utils/naming.js

@@ -0,0 +1,48 @@
+"use strict";
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSnakeCaseName = void 0;
+exports.assertSnakeCaseName = assertSnakeCaseName;
+exports.toSnakeCase = toSnakeCase;
+const SNAKE_CASE_REGEX = /^[a-z0-9]+(?:_[a-z0-9]+)+$/;
+/**
+ * Verifies that names follow the snake_case convention required by the system.
+ *
+ * @param name - Candidate name that should be validated.
+ * @param entity - Entity type used to customize the error message.
+ * @throws Error when the name is not snake_case.
+ */
+function assertSnakeCaseName(name, entity) {
+    if (!SNAKE_CASE_REGEX.test(name)) {
+        throw new Error(`${entity} name must be snake_case with at least one underscore. Received: "${name}"`);
+    }
+}
+/**
+ * Checks whether the provided string is snake_case compliant.
+ *
+ * @param value - Text to evaluate.
+ * @returns `true` when the value is snake_case; otherwise `false`.
+ */
+const isSnakeCaseName = (value) => SNAKE_CASE_REGEX.test(value);
+exports.isSnakeCaseName = isSnakeCaseName;
+/**
+ * Converts arbitrary text into snake_case for use in workflow entities.
+ *
+ * @param value - Input text that should be converted.
+ * @returns Snake cased version of the input.
+ */
+function toSnakeCase(value) {
+    if (!value) {
+        return '';
+    }
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/[^a-zA-Z0-9]+/g, '_')
+        .replace(/_{2,}/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toLowerCase();
+}

package/dist/cjs/utils/timeout.js

@@ -0,0 +1,42 @@
+"use strict";
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = void 0;
+exports.withTimeout = withTimeout;
+/**
+ * Resolves after the specified duration; useful for retry delays.
+ *
+ * @param durationMs - Number of milliseconds to wait before resolving.
+ * @returns A promise that resolves once the duration elapses.
+ */
+const sleep = (durationMs) => new Promise((resolve) => setTimeout(resolve, durationMs));
+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.
+ * @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) {
+        return promise;
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`Step execution exceeded timeout of ${timeoutMs}ms`));
+        }, timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}