@hexabot-ai/agentic 3.0.1-alpha.0

package/dist/esm/workflow-compiler.js

@@ -0,0 +1,208 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+import { z } from 'zod';
+import { mountTaskBindings, validateAndResolveBindings, } from './bindings/base-binding';
+import { extractTaskDefinitions as extractTaskDefinitionsFromDefs } from './dsl.types';
+import { assertSnakeCaseName } from './utils/naming';
+import { StepType } from './workflow-event-emitter';
+import { compileValue, mergeSettings, } from './workflow-values';
+/** Build a stable identifier for a step using its path and label. */
+const buildStepId = (path, label) => {
+    const pathPart = path.length > 0 ? path.join('.') : 'root';
+    return `${pathPart}:${label}`;
+};
+/** Convert workflow input field metadata to a zod schema. */
+const inputFieldToZod = (field) => {
+    let schema;
+    switch (field.type) {
+        case 'string':
+            schema = z.string();
+            break;
+        case 'number':
+            schema = z.number();
+            break;
+        case 'integer':
+            schema = z.int();
+            break;
+        case 'boolean':
+            schema = z.boolean();
+            break;
+        case 'array':
+            schema = z.array(field.items ? inputFieldToZod(field.items) : z.any());
+            break;
+        case 'object': {
+            const properties = {};
+            if (field.properties) {
+                for (const [name, child] of Object.entries(field.properties)) {
+                    properties[name] = inputFieldToZod(child).optional();
+                }
+            }
+            schema =
+                Object.keys(properties).length > 0
+                    ? z.strictObject(properties).partial()
+                    : z.record(z.string(), z.any());
+            break;
+        }
+        default:
+            schema = z.any();
+    }
+    if (field.enum) {
+        schema = schema.refine((value) => field.enum?.some((allowed) => allowed === value), {
+            message: `Value must be one of: ${field.enum.join(', ')}`,
+        });
+    }
+    return schema;
+};
+/** Assemble a parser for the workflow top-level input payload. */
+const buildInputParser = (schema) => {
+    if (!schema || Object.keys(schema).length === 0) {
+        return z.looseObject({});
+    }
+    const shape = {};
+    for (const [name, field] of Object.entries(schema)) {
+        shape[name] = inputFieldToZod(field).optional();
+    }
+    return z.strictObject(shape).partial();
+};
+/** Compile a raw mapping object into expression-aware value mappings. */
+const compileMapping = (values, options) => {
+    if (!values) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(values).map(([key, value]) => [
+        key,
+        compileValue(value, options),
+    ]));
+};
+/** Ensure every task references a provided action implementation. */
+const assertActionsBound = (tasks, actions) => {
+    const missing = Object.values(tasks)
+        .map((task) => task.action)
+        .filter((actionName) => !Object.prototype.hasOwnProperty.call(actions, actionName));
+    if (missing.length > 0) {
+        throw new Error(`No action implementations provided for: ${missing.join(', ')}`);
+    }
+};
+/** Parse settings, compile inputs, and bind actions for each task. */
+const compileTasks = (definition, options) => {
+    const compiled = {};
+    const defaultSettings = definition.defaults?.settings;
+    const taskDefinitions = extractTaskDefinitionsFromDefs(definition.defs);
+    const bindingValidation = validateAndResolveBindings(definition, {
+        bindingKinds: options.bindingKinds,
+        actions: options.actions,
+    });
+    if (bindingValidation.errors.length > 0) {
+        throw new Error(`Workflow bindings validation failed: ${bindingValidation.errors.join('; ')}`);
+    }
+    assertActionsBound(taskDefinitions, options.actions);
+    for (const [taskName, task] of Object.entries(taskDefinitions)) {
+        assertSnakeCaseName(taskName, 'action');
+        const action = options.actions[task.action];
+        const settingsPayload = mergeSettings(defaultSettings, task.settings);
+        const parsedSettings = action.parseSettings(settingsPayload);
+        compiled[taskName] = {
+            name: taskName,
+            actionName: task.action,
+            definition: task,
+            action,
+            inputs: compileMapping(task.inputs, options) ?? {},
+            settings: parsedSettings,
+            bindings: mountTaskBindings(task.bindings, bindingValidation.resolvedDefs, options.bindingKinds),
+        };
+    }
+    return compiled;
+};
+/** Recursively compile flow steps into executable nodes with generated ids. */
+const compileFlowSteps = (steps, path = [], options) => steps.map((step, index) => {
+    const stepPath = [...path, index];
+    if ('do' in step) {
+        const label = step.do;
+        return {
+            type: StepType.Task,
+            id: buildStepId(stepPath, step.do),
+            label,
+            taskName: step.do,
+        };
+    }
+    if ('parallel' in step) {
+        const label = step.parallel.description ?? 'parallel';
+        return {
+            type: StepType.Parallel,
+            id: buildStepId(stepPath, 'parallel'),
+            label,
+            description: step.parallel.description,
+            strategy: step.parallel.strategy ?? 'wait_all',
+            steps: compileFlowSteps(step.parallel.steps, [...stepPath, 'parallel'], options),
+        };
+    }
+    if ('conditional' in step) {
+        const label = step.conditional.description ?? 'conditional';
+        const branches = step.conditional.when.map((branch, branchIdx) => ({
+            id: buildStepId([...stepPath, 'branch', branchIdx], 'conditional'),
+            condition: 'condition' in branch
+                ? compileValue(branch.condition, options)
+                : undefined,
+            steps: compileFlowSteps(branch.steps, [...stepPath, 'branch', branchIdx], options),
+        }));
+        return {
+            type: StepType.Conditional,
+            id: buildStepId(stepPath, 'conditional'),
+            label,
+            description: step.conditional.description,
+            branches,
+        };
+    }
+    const loop = step.loop;
+    const label = loop.name ?? 'loop';
+    const commonLoop = {
+        type: StepType.Loop,
+        id: buildStepId(stepPath, label),
+        label,
+        name: loop.name,
+        description: loop.description,
+        accumulate: loop.accumulate
+            ? {
+                as: loop.accumulate.as,
+                initial: loop.accumulate.initial,
+                merge: compileValue(loop.accumulate.merge, options),
+            }
+            : undefined,
+        steps: compileFlowSteps(loop.steps, [...stepPath, loop.name ?? 'loop'], options),
+    };
+    if (loop.type === 'for_each') {
+        return {
+            ...commonLoop,
+            loopType: 'for_each',
+            forEach: {
+                item: loop.for_each.item,
+                in: compileValue(loop.for_each.in, options),
+            },
+            maxConcurrency: loop.max_concurrency,
+            until: loop.until ? compileValue(loop.until, options) : undefined,
+        };
+    }
+    return {
+        ...commonLoop,
+        loopType: 'while',
+        while: compileValue(loop.while, options),
+    };
+});
+/** Compile a workflow definition into structures consumable by the runtime. */
+export const compileWorkflow = (definition, options) => {
+    const inputParser = buildInputParser(definition.inputs?.schema);
+    const tasks = compileTasks(definition, options);
+    const flow = compileFlowSteps(definition.flow, [], options);
+    const outputMapping = compileMapping(definition.outputs, options) ?? {};
+    return {
+        definition,
+        tasks,
+        flow,
+        outputMapping,
+        inputParser,
+        defaultSettings: definition.defaults?.settings,
+    };
+};

package/dist/esm/workflow-event-emitter.js

@@ -0,0 +1,36 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+export var StepType;
+(function (StepType) {
+    StepType["Task"] = "task";
+    StepType["Parallel"] = "parallel";
+    StepType["Conditional"] = "conditional";
+    StepType["Loop"] = "loop";
+})(StepType || (StepType = {}));
+/**
+ * Minimal, browser-friendly event emitter that preserves the typed payloads
+ * exposed by {@link WorkflowEventMap}. It supports the subset of the Node.js
+ * EventEmitter API that the runtime relies on (`emit` and `on`).
+ */
+export class WorkflowEventEmitter {
+    constructor() {
+        this.listeners = new Map();
+    }
+    emit(event, payload) {
+        const eventListeners = this.listeners.get(event);
+        if (!eventListeners || eventListeners.size === 0) {
+            return false;
+        }
+        eventListeners.forEach((listener) => listener(payload));
+        return true;
+    }
+    on(event, listener) {
+        const listeners = this.listeners.get(event) ?? new Set();
+        listeners.add(listener);
+        this.listeners.set(event, listeners);
+        return this;
+    }
+}

package/dist/esm/workflow-runner.js

@@ -0,0 +1,444 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+import { RunnerRuntimeControl } from './runner-runtime-control';
+import { executeConditional as runConditionalExecutor } from './step-executors/conditional-executor';
+import { executeLoop as runLoopExecutor } from './step-executors/loop-executor';
+import { executeParallel as runParallelExecutor } from './step-executors/parallel-executor';
+import { executeTaskStep as runTaskExecutor } from './step-executors/task-executor';
+import { rebuildSuspension, } from './suspension-rebuilder';
+import { StepType, } from './workflow-event-emitter';
+import { evaluateMapping } from './workflow-values';
+/**
+ * Executes a compiled workflow definition, tracking state, suspensions, and event hooks.
+ * Create a new instance per execution to avoid leaking state between runs.
+ */
+export class WorkflowRunner {
+    /**
+     * Create a new runner for a compiled workflow definition.
+     *
+     * @param compiled The compiled workflow to execute.
+     * @param options Optional runner configuration such as run id.
+     */
+    constructor(compiled, options) {
+        // Current lifecycle status of the workflow execution.
+        this.status = 'idle';
+        // Snapshots of action execution keyed by step id for inspection/resume.
+        this.snapshots = {};
+        // Detailed execution records for each task step, used by UI/telemetry.
+        this.stepLog = {};
+        this.compiled = compiled;
+        this.runId = options?.runId;
+    }
+    /**
+     * Get the current state of the workflow run.
+     *
+     * @returns The state of the workflow execution.
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Get the current lifecycle status of the workflow run.
+     *
+     * @returns The status of the workflow execution.
+     */
+    getStatus() {
+        return this.status;
+    }
+    /**
+     * Snapshot the current workflow status and action states.
+     *
+     * @returns A snapshot representing the workflow and each action's status.
+     */
+    getSnapshot() {
+        return {
+            status: this.status,
+            actions: { ...this.snapshots },
+        };
+    }
+    /**
+     * Read the per-step execution records captured for UI/telemetry.
+     *
+     * @returns A shallow copy of the step execution log.
+     */
+    getStepLog() {
+        return Object.fromEntries(Object.entries(this.stepLog).map(([id, record]) => [
+            id,
+            {
+                ...record,
+                context: record.context ? { ...record.context } : undefined,
+                error: record.error ? { ...record.error } : undefined,
+            },
+        ]));
+    }
+    /**
+     * Read the step currently being executed.
+     *
+     * @returns Metadata for the in-flight step, if any.
+     */
+    getCurrentStep() {
+        return this.currentStep;
+    }
+    /**
+     * Access the last payload supplied to a resume call.
+     *
+     * @returns The most recent resume data, or undefined if none.
+     */
+    getLastResumeData() {
+        return this.lastResumeData;
+    }
+    /**
+     * Begin executing the workflow from the first step.
+     * Returns a status object describing whether execution finished, suspended, or failed.
+     *
+     * @param args Input payload and context to seed execution.
+     * @returns Execution result including status and snapshot.
+     */
+    async start(args) {
+        this.status = 'running';
+        this.snapshots = {};
+        this.stepLog = {};
+        this.suspension = undefined;
+        this.lastResumeData = undefined;
+        this.currentStep = undefined;
+        this.context = args.context;
+        this.state = {
+            input: this.compiled.inputParser.parse(args.inputData ?? {}),
+            output: {},
+            iterationStack: [],
+        };
+        this.runtimeControl = new RunnerRuntimeControl(this);
+        this.context.attachWorkflowRuntime(this.runtimeControl);
+        this.emit('hook:workflow:start', { runId: this.runId });
+        const state = this.state;
+        if (!state) {
+            throw new Error('Workflow state not initialized.');
+        }
+        return this.runExecution(() => this.executeFlow(this.compiled.flow, state, []));
+    }
+    /**
+     * Resume a previously suspended workflow using the supplied resume data.
+     *
+     * @param args Data provided to resume the suspended step.
+     * @returns Execution result including status and snapshot.
+     */
+    async resume(args) {
+        if (this.status !== 'suspended' || !this.suspension) {
+            throw new Error('Cannot resume a workflow that is not suspended.');
+        }
+        if (!this.context || !this.state) {
+            throw new Error('Workflow state is not initialized.');
+        }
+        this.status = 'running';
+        this.lastResumeData = args.resumeData;
+        const suspension = this.suspension;
+        return this.runExecution(() => suspension.continue(args.resumeData));
+    }
+    /**
+     * Execute the provided workflow operation and normalize suspension, finish, and failure handling.
+     *
+     * @param execute Function that advances workflow execution and may return a suspension.
+     * @returns Result of the execution attempt.
+     */
+    async runExecution(execute) {
+        try {
+            const suspension = await execute();
+            if (suspension) {
+                this.suspension = suspension;
+                this.status = 'suspended';
+                this.emit('hook:workflow:suspended', {
+                    runId: this.runId,
+                    step: suspension.step,
+                    reason: suspension.reason,
+                    data: suspension.data,
+                });
+                return {
+                    status: 'suspended',
+                    step: suspension.step,
+                    reason: suspension.reason,
+                    data: suspension.data,
+                    stepExecId: suspension.stepExecId,
+                    suspendIndex: suspension.suspendIndex,
+                    suspendKey: suspension.suspendKey,
+                    awaitResults: suspension.awaitResults,
+                    snapshot: this.getSnapshot(),
+                };
+            }
+            const output = await this.evaluateWorkflowOutputs();
+            this.status = 'finished';
+            this.suspension = undefined;
+            this.currentStep = undefined;
+            this.emit('hook:workflow:finish', { runId: this.runId, output });
+            if (!this.context) {
+                throw new Error('Workflow context is not attached.');
+            }
+            this.context.attachWorkflowRuntime(undefined);
+            return { status: 'finished', output, snapshot: this.getSnapshot() };
+        }
+        catch (error) {
+            this.status = 'failed';
+            this.currentStep = undefined;
+            this.emit('hook:workflow:failure', { runId: this.runId, error });
+            this.context?.attachWorkflowRuntime(undefined);
+            return { status: 'failed', error, snapshot: this.getSnapshot() };
+        }
+    }
+    /**
+     * Rebuild a runner from persisted state, allowing hosts to resume after restarts.
+     *
+     * @param compiled The compiled workflow definition.
+     * @param options Persisted state and metadata needed to rebuild the runner.
+     * @returns A runner positioned to continue from the prior suspension or status.
+     */
+    static async fromPersistedState(compiled, options) {
+        const runner = new WorkflowRunner(compiled, {
+            runId: options.runId,
+        });
+        runner.state = {
+            input: options.state.input ?? {},
+            output: options.state.output ?? {},
+            iteration: options.state.iteration,
+            accumulator: options.state.accumulator,
+            iterationStack: [...(options.state.iterationStack ?? [])],
+        };
+        runner.context = options.context;
+        runner.snapshots = options.snapshot.actions ?? {};
+        runner.stepLog = {};
+        runner.status = options.snapshot.status ?? 'idle';
+        runner.lastResumeData = options.lastResumeData;
+        runner.runtimeControl = new RunnerRuntimeControl(runner);
+        options.context.attachWorkflowRuntime(runner.runtimeControl);
+        if (options.suspension) {
+            const suspension = rebuildSuspension(runner.createSuspensionRebuilderDeps(), {
+                state: runner.state,
+                stepId: options.suspension.stepId,
+                reason: options.suspension.reason ?? undefined,
+                data: options.suspension.data,
+                stepExecId: options.suspension.stepExecId,
+                suspendIndex: options.suspension.suspendIndex,
+                suspendKey: options.suspension.suspendKey,
+                awaitResults: options.suspension.awaitResults,
+            });
+            if (!suspension) {
+                throw new Error(`Unable to rebuild suspension for step ${options.suspension.stepId}`);
+            }
+            runner.suspension = suspension;
+            runner.status = 'suspended';
+        }
+        return runner;
+    }
+    /**
+     * Emit an event if an emitter is provided.
+     *
+     * @param event The event name to emit.
+     * @param payload The event payload.
+     */
+    emit(event, payload) {
+        this.context?.eventEmitter?.emit(event, payload);
+    }
+    /**
+     * Evaluate and map the workflow outputs after all steps have completed.
+     * Throws if the internal state or context were not initialized.
+     *
+     * @returns The evaluated workflow outputs.
+     * @throws When state or context are missing.
+     */
+    async evaluateWorkflowOutputs() {
+        if (!this.state || !this.context) {
+            throw new Error('Workflow state not initialized.');
+        }
+        return evaluateMapping(this.compiled.outputMapping, {
+            input: this.state.input,
+            context: this.context.state,
+            output: this.state.output,
+        });
+    }
+    /**
+     * Build a stable step id that reflects the current loop iteration stack.
+     *
+     * @param step The compiled step to annotate.
+     * @param iterationStack The loop stack representing nested iterations.
+     * @returns A step info object with an iteration-aware id.
+     */
+    buildInstanceStepInfo(step, iterationStack) {
+        const suffix = iterationStack.length > 0 ? `[${iterationStack.join('.')}]` : '';
+        return {
+            id: `${step.id}${suffix}`,
+            name: step.label,
+            type: step.type,
+        };
+    }
+    /**
+     * Record an action snapshot for the given step id.
+     *
+     * @param step The step being updated.
+     * @param status The new snapshot status.
+     * @param reason Optional reason to include when marking failure/suspension.
+     */
+    markSnapshot(step, status, reason) {
+        this.snapshots[step.id] = {
+            id: step.id,
+            name: step.name,
+            status,
+            reason,
+        };
+    }
+    /**
+     * Record a detailed execution entry for the given step.
+     *
+     * @param step The step being updated.
+     * @param update Partial record fields to merge into the log.
+     */
+    recordStepExecution(step, update) {
+        const existing = this.stepLog[step.id];
+        const base = existing ??
+            {
+                id: step.id,
+                name: step.name,
+                status: 'pending',
+            };
+        const mergedContext = existing?.context || update.context
+            ? { ...existing?.context, ...update.context }
+            : undefined;
+        this.stepLog[step.id] = {
+            ...base,
+            ...update,
+            id: step.id,
+            name: step.name,
+            status: update.status ?? base.status,
+            context: mergedContext,
+        };
+    }
+    /**
+     * Construct the environment object passed to step executors.
+     *
+     * @returns A step executor environment bound to this runner.
+     * @throws When the workflow context is missing.
+     */
+    createExecutorEnv() {
+        if (!this.context) {
+            throw new Error('Workflow context is not attached.');
+        }
+        return {
+            compiled: this.compiled,
+            context: this.context,
+            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;
+            },
+            beginStepExecution: (stepId) => {
+                if (!this.runtimeControl) {
+                    return `${stepId}#1`;
+                }
+                return this.runtimeControl.beginStepExecution(stepId);
+            },
+            waitForStepSuspension: (stepId) => {
+                if (!this.runtimeControl) {
+                    throw new Error('Workflow runtime control is not initialized.');
+                }
+                return this.runtimeControl.waitForStepSuspension(stepId);
+            },
+            clearStepSuspensions: (stepId, error) => {
+                this.runtimeControl?.clearStepSuspensions(stepId, error);
+            },
+            primeStepResumeData: (stepId, resumeData) => {
+                this.runtimeControl?.primeStepResumeData(stepId, resumeData);
+            },
+            prepareStepReplay: (seed) => {
+                this.runtimeControl?.prepareStepReplay(seed);
+            },
+            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),
+        };
+    }
+    /**
+     * Build dependencies used to reconstruct a suspension from persisted state.
+     *
+     * @returns Dependency bag for suspension rebuilders.
+     */
+    createSuspensionRebuilderDeps() {
+        return {
+            compiled: this.compiled,
+            context: this.context,
+            runId: this.runId,
+            createExecutorEnv: () => this.createExecutorEnv(),
+            buildInstanceStepInfo: (step, iterationStack) => this.buildInstanceStepInfo(step, iterationStack),
+            captureTaskOutput: (task, state, result) => this.captureTaskOutput(task, state, result),
+            markSnapshot: (step, status, reason) => this.markSnapshot(step, status, reason),
+            emit: (event, payload) => this.emit(event, payload),
+            executeFlow: (steps, state, path, startIndex) => this.executeFlow(steps, state, path, startIndex),
+        };
+    }
+    /**
+     * Walk a list of compiled steps, threading state and returning a suspension when encountered.
+     *
+     * @param steps The steps to execute sequentially.
+     * @param state Mutable execution state shared across steps.
+     * @param path Path tokens leading to the current step for tracing.
+     * @param startIndex Index to resume from within the flow.
+     * @returns A suspension if execution pauses, otherwise void.
+     */
+    async executeFlow(steps, state, path, startIndex = 0) {
+        // 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) {
+            const step = steps[index];
+            const stepPath = [...path, index];
+            const suspension = await this.executeStep(step, state, stepPath);
+            if (suspension) {
+                return {
+                    ...suspension,
+                    continue: async (resumeData) => {
+                        const next = await suspension.continue(resumeData);
+                        if (next) {
+                            return next;
+                        }
+                        return this.executeFlow(steps, state, path, index + 1);
+                    },
+                };
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Execute a single compiled step by delegating to its executor.
+     *
+     * @param step The step to run.
+     * @param state The shared execution state.
+     * @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();
+        switch (step.type) {
+            case StepType.Task:
+                return runTaskExecutor(env, step, state, path);
+            case StepType.Parallel:
+                return runParallelExecutor(env, step, state, path);
+            case StepType.Conditional:
+                return runConditionalExecutor(env, step, state, path);
+            case StepType.Loop:
+                return runLoopExecutor(env, step, state, path);
+        }
+    }
+    /**
+     * Store the raw task result under the task name in the workflow output state.
+     * @reviewed
+     * @param task The task whose output is being captured.
+     * @param state Current execution state to mutate.
+     * @param result Raw result returned by the task action.
+     */
+    async captureTaskOutput(task, state, result) {
+        state.output[task.name] = result;
+    }
+}

package/dist/esm/workflow-types.js

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