@hexabot-ai/agentic 3.0.1-alpha.0

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

@@ -0,0 +1,152 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+import { evaluateMapping } from '../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.
+ */
+export 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 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/esm/step-executors/types.js

@@ -0,0 +1,6 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+export {};

package/dist/esm/suspension-rebuilder.js

@@ -0,0 +1,296 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+import { executeLoop as runLoopExecutor, shouldStopLoop, updateAccumulator, } from './step-executors/loop-executor';
+import { executeParallel as runParallelExecutor } from './step-executors/parallel-executor';
+import { markStepsSkipped } from './step-executors/skip-helpers';
+import { StepType, } from './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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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 !== 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 === 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) {
+                        markStepsSkipped(env, step.steps.slice(childIndex + 1), state.iterationStack ?? []);
+                    }
+                    return undefined;
+                }
+                return runParallelExecutor(env, step, state, currentPath, childIndex + 1);
+            },
+        };
+    }
+    if (step.type === 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 === 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 updateAccumulator(step, scope, accumulator);
+                const shouldStop = await 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 runLoopExecutor(env, step, baseState, currentPath, iterationIndex + 1);
+            },
+        };
+    }
+    return null;
+}

package/dist/esm/utils/deferred.js

@@ -0,0 +1,14 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+export function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}

package/dist/esm/utils/naming.js

@@ -0,0 +1,42 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+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.
+ */
+export 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`.
+ */
+export const isSnakeCaseName = (value) => SNAKE_CASE_REGEX.test(value);
+/**
+ * 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.
+ */
+export 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/esm/utils/timeout.js

@@ -0,0 +1,37 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+/**
+ * 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.
+ */
+export const sleep = (durationMs) => new Promise((resolve) => setTimeout(resolve, durationMs));
+/**
+ * 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.
+ */
+export 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);
+        });
+    });
+}

package/dist/esm/utils/workflow-definition.js

@@ -0,0 +1,98 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+import { TASK_KIND, } from '../dsl.types';
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const replaceOutputTaskReferences = (source, currentTaskName, nextTaskName) => {
+    if (!source.includes('$output')) {
+        return source;
+    }
+    const escapedTaskName = escapeRegExp(currentTaskName);
+    const dotNotationPattern = new RegExp(`(\\$output\\.)${escapedTaskName}(?=[^a-zA-Z0-9_]|$)`, 'g');
+    const singleQuotePattern = new RegExp(`(\\$output\\s*\\[\\s*')${escapedTaskName}('\\s*\\])`, 'g');
+    const doubleQuotePattern = new RegExp(`(\\$output\\s*\\[\\s*")${escapedTaskName}("\\s*\\])`, 'g');
+    return source
+        .replace(dotNotationPattern, `$1${nextTaskName}`)
+        .replace(singleQuotePattern, `$1${nextTaskName}$2`)
+        .replace(doubleQuotePattern, `$1${nextTaskName}$2`);
+};
+const renameTaskInFlow = (steps, currentTaskName, nextTaskName) => {
+    return steps.map((step) => {
+        if ('do' in step) {
+            return {
+                ...step,
+                do: step.do === currentTaskName ? nextTaskName : step.do,
+            };
+        }
+        if ('parallel' in step) {
+            return {
+                ...step,
+                parallel: {
+                    ...step.parallel,
+                    steps: renameTaskInFlow(step.parallel.steps, currentTaskName, nextTaskName),
+                },
+            };
+        }
+        if ('conditional' in step) {
+            return {
+                ...step,
+                conditional: {
+                    ...step.conditional,
+                    when: step.conditional.when.map((branch) => ({
+                        ...branch,
+                        steps: renameTaskInFlow(branch.steps, currentTaskName, nextTaskName),
+                    })),
+                },
+            };
+        }
+        if ('loop' in step) {
+            return {
+                ...step,
+                loop: {
+                    ...step.loop,
+                    steps: renameTaskInFlow(step.loop.steps, currentTaskName, nextTaskName),
+                },
+            };
+        }
+        return step;
+    });
+};
+const renameOutputTaskReferencesInValue = (value, currentTaskName, nextTaskName) => {
+    if (typeof value === 'string') {
+        return replaceOutputTaskReferences(value, currentTaskName, nextTaskName);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => renameOutputTaskReferencesInValue(item, currentTaskName, nextTaskName));
+    }
+    if (!value || typeof value !== 'object') {
+        return value;
+    }
+    return Object.entries(value).reduce((acc, [key, nestedValue]) => {
+        acc[key] = renameOutputTaskReferencesInValue(nestedValue, currentTaskName, nextTaskName);
+        return acc;
+    }, {});
+};
+export const safeRenameTaskInDefinition = (definition, currentTaskName, nextTaskName) => {
+    if (currentTaskName === nextTaskName) {
+        return definition;
+    }
+    if (!Object.prototype.hasOwnProperty.call(definition.defs, currentTaskName)) {
+        return definition;
+    }
+    const currentDefinition = definition.defs[currentTaskName];
+    if (!currentDefinition || currentDefinition.kind !== TASK_KIND) {
+        return definition;
+    }
+    const renamedDefs = Object.entries(definition.defs).reduce((acc, [defName, def]) => {
+        acc[defName === currentTaskName ? nextTaskName : defName] = def;
+        return acc;
+    }, {});
+    const definitionWithRenamedFlow = {
+        ...definition,
+        defs: renamedDefs,
+        flow: renameTaskInFlow(definition.flow, currentTaskName, nextTaskName),
+    };
+    return renameOutputTaskReferencesInValue(definitionWithRenamedFlow, currentTaskName, nextTaskName);
+};