@hexabot-ai/agentic 3.0.1-alpha.0

package/dist/cjs/workflow-runner.js

@@ -0,0 +1,448 @@
+"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.WorkflowRunner = void 0;
+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");
+const parallel_executor_1 = require("./step-executors/parallel-executor");
+const task_executor_1 = require("./step-executors/task-executor");
+const suspension_rebuilder_1 = require("./suspension-rebuilder");
+const workflow_event_emitter_1 = require("./workflow-event-emitter");
+const workflow_values_1 = require("./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.
+ */
+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 runner_runtime_control_1.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 runner_runtime_control_1.RunnerRuntimeControl(runner);
+        options.context.attachWorkflowRuntime(runner.runtimeControl);
+        if (options.suspension) {
+            const suspension = (0, suspension_rebuilder_1.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 (0, workflow_values_1.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 workflow_event_emitter_1.StepType.Task:
+                return (0, task_executor_1.executeTaskStep)(env, step, state, path);
+            case workflow_event_emitter_1.StepType.Parallel:
+                return (0, parallel_executor_1.executeParallel)(env, step, state, path);
+            case workflow_event_emitter_1.StepType.Conditional:
+                return (0, conditional_executor_1.executeConditional)(env, step, state, path);
+            case workflow_event_emitter_1.StepType.Loop:
+                return (0, loop_executor_1.executeLoop)(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;
+    }
+}
+exports.WorkflowRunner = WorkflowRunner;

package/dist/cjs/workflow-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/workflow-values.js

@@ -0,0 +1,99 @@
+"use strict";
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeSettings = exports.evaluateMapping = exports.evaluateValue = exports.compileValue = void 0;
+const jsonata_1 = __importDefault(require("jsonata"));
+/** Basic object guard that rejects arrays and null. */
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const registerJsonataFunctions = (expression, registry) => {
+    if (!registry) {
+        return;
+    }
+    for (const [name, config] of Object.entries(registry)) {
+        if (typeof config === 'function') {
+            expression.registerFunction(name, config);
+            continue;
+        }
+        if (config && typeof config.implementation === 'function') {
+            expression.registerFunction(name, config.implementation, config.signature);
+            continue;
+        }
+        throw new Error(`Invalid JSONata function config for "${name}"`);
+    }
+};
+/**
+ * Prepares a workflow value for evaluation.
+ * Strings prefixed with `=` are treated as JSONata expressions; everything else is a literal.
+ */
+const compileValue = (value, options) => {
+    if (typeof value === 'string' && value.startsWith('=')) {
+        const expression = (0, jsonata_1.default)(value.slice(1));
+        registerJsonataFunctions(expression, options?.jsonataFunctions);
+        return { kind: 'expression', source: value, expression };
+    }
+    return { kind: 'literal', value };
+};
+exports.compileValue = compileValue;
+/**
+ * Evaluate a compiled value against the current workflow scope.
+ * Expressions are executed via JSONata with the scope exposed as variables; `context`
+ * represents the workflow context state, not the context instance itself.
+ */
+const evaluateValue = async (compiled, scope) => {
+    if (compiled.kind === 'literal') {
+        return compiled.value;
+    }
+    return compiled.expression.evaluate({}, {
+        input: scope.input,
+        context: scope.context,
+        output: scope.output,
+        iteration: scope.iteration,
+        accumulator: scope.accumulator,
+        result: scope.result,
+    });
+};
+exports.evaluateValue = evaluateValue;
+/**
+ * Evaluate all entries of a compiled mapping, returning a plain object.
+ * Missing mappings resolve to an empty object.
+ */
+const evaluateMapping = async (mapping, scope) => {
+    if (!mapping) {
+        return {};
+    }
+    const result = {};
+    for (const [key, compiled] of Object.entries(mapping)) {
+        result[key] = await (0, exports.evaluateValue)(compiled, scope);
+    }
+    return result;
+};
+exports.evaluateMapping = evaluateMapping;
+/**
+ * Deep-merge workflow settings, preferring non-undefined overrides.
+ * Nested objects are merged recursively to preserve defaults.
+ */
+const mergeSettings = (base, override) => {
+    const merged = { ...(base ?? {}) };
+    if (!override) {
+        return merged;
+    }
+    for (const key of Object.keys(override)) {
+        const value = override[key];
+        const previous = merged[key];
+        if (isPlainObject(previous) && isPlainObject(value)) {
+            merged[key] = (0, exports.mergeSettings)(previous, value);
+        }
+        else if (value !== undefined) {
+            merged[key] = value;
+        }
+    }
+    return merged;
+};
+exports.mergeSettings = mergeSettings;