@hexabot-ai/agentic 3.0.1-alpha.0

package/dist/cjs/workflow.js

@@ -0,0 +1,243 @@
+"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.Workflow = exports.WorkflowRunner = exports.WorkflowEventEmitter = exports.compileWorkflow = void 0;
+const yaml_1 = require("yaml");
+const dsl_types_1 = require("./dsl.types");
+const workflow_definition_1 = require("./utils/workflow-definition");
+const workflow_compiler_1 = require("./workflow-compiler");
+const workflow_runner_1 = require("./workflow-runner");
+var workflow_compiler_2 = require("./workflow-compiler");
+Object.defineProperty(exports, "compileWorkflow", { enumerable: true, get: function () { return workflow_compiler_2.compileWorkflow; } });
+var workflow_event_emitter_1 = require("./workflow-event-emitter");
+Object.defineProperty(exports, "WorkflowEventEmitter", { enumerable: true, get: function () { return workflow_event_emitter_1.WorkflowEventEmitter; } });
+var workflow_runner_2 = require("./workflow-runner");
+Object.defineProperty(exports, "WorkflowRunner", { enumerable: true, get: function () { return workflow_runner_2.WorkflowRunner; } });
+class WorkflowRunSuspendedError extends Error {
+    constructor(stepId, options) {
+        super(`Workflow run suspended at step ${stepId}${options?.reason ? `: ${options.reason}` : ''}`);
+        this.name = 'WorkflowRunSuspendedError';
+        this.stepId = stepId;
+        this.reason = options?.reason;
+        this.data = options?.data;
+    }
+}
+const getTaskNameFromStep = (step) => {
+    if (!step || typeof step !== 'object') {
+        return null;
+    }
+    const taskName = step.do;
+    return typeof taskName === 'string' ? taskName : null;
+};
+const hasTaskReference = (steps, taskName) => {
+    return steps.some((step) => {
+        if ('do' in step) {
+            return step.do === taskName;
+        }
+        if ('parallel' in step) {
+            return hasTaskReference(step.parallel.steps, taskName);
+        }
+        if ('conditional' in step) {
+            return step.conditional.when.some((branch) => hasTaskReference(branch.steps, taskName));
+        }
+        if ('loop' in step) {
+            return hasTaskReference(step.loop.steps, taskName);
+        }
+        return false;
+    });
+};
+/**
+ * Entry point for preparing and executing workflows from YAML or object definitions.
+ * Instances are thin wrappers around a compiled workflow graph.
+ */
+class Workflow {
+    constructor(compiled) {
+        this.compiled = compiled;
+    }
+    /**
+     * Create a workflow from an already parsed definition.
+     * The definition is validated before compilation to catch schema issues early.
+     */
+    static fromDefinition(definition, options) {
+        const validation = (0, dsl_types_1.validateWorkflow)(definition, {
+            bindingKinds: options.bindingKinds,
+            actions: options.actions,
+        });
+        if (!validation.success) {
+            throw new Error(`Workflow validation failed: ${validation.errors.join('; ')}`);
+        }
+        const compiled = (0, workflow_compiler_1.compileWorkflow)(validation.data, options);
+        return new Workflow(compiled);
+    }
+    /**
+     * Create a workflow from YAML source.
+     * YAML is validated and compiled before being wrapped in a {@link Workflow} instance.
+     */
+    static fromYaml(yaml, options) {
+        const validation = (0, dsl_types_1.validateWorkflow)(yaml, {
+            bindingKinds: options.bindingKinds,
+            actions: options.actions,
+        });
+        if (!validation.success) {
+            throw new Error(`Workflow validation failed: ${validation.errors.join('; ')}`);
+        }
+        const compiled = (0, workflow_compiler_1.compileWorkflow)(validation.data, options);
+        return new Workflow(compiled);
+    }
+    /**
+     * Convert a workflow definition to YAML.
+     * The definition is validated before serialization.
+     */
+    static stringifyDefinition(definition) {
+        const parsed = dsl_types_1.WorkflowDefinitionSchema.parse(definition);
+        return (0, yaml_1.stringify)(parsed);
+    }
+    /**
+     * Resolve a nested value from a workflow definition by path.
+     */
+    static getValueAtPath(value, path) {
+        return path.reduce((acc, key) => {
+            if (acc === null || acc === undefined) {
+                return undefined;
+            }
+            if (Array.isArray(acc)) {
+                return typeof key === 'number' ? acc[key] : undefined;
+            }
+            if (typeof acc === 'object') {
+                return acc[String(key)];
+            }
+            return undefined;
+        }, value);
+    }
+    /**
+     * Create a new value with a nested path updated immutably.
+     */
+    static setValueAtPath(value, path, nextValue) {
+        if (path.length === 0) {
+            return nextValue;
+        }
+        const [key, ...rest] = path;
+        if (Array.isArray(value)) {
+            if (typeof key !== 'number') {
+                return value;
+            }
+            const nextArray = [...value];
+            nextArray[key] = Workflow.setValueAtPath(value[key], rest, nextValue);
+            return nextArray;
+        }
+        if (value && typeof value === 'object') {
+            return {
+                ...value,
+                [String(key)]: Workflow.setValueAtPath(value[String(key)], rest, nextValue),
+            };
+        }
+        return value;
+    }
+    /**
+     * Remove a flow step from the definition at the given path, if valid.
+     */
+    static removeStepAtPath(definition, stepPath) {
+        if (!stepPath.length) {
+            return null;
+        }
+        const removeIndex = stepPath[stepPath.length - 1];
+        if (typeof removeIndex !== 'number') {
+            return null;
+        }
+        const stepsPath = stepPath.slice(0, -1);
+        const steps = Workflow.getValueAtPath(definition, stepsPath);
+        if (!Array.isArray(steps)) {
+            return null;
+        }
+        if (removeIndex < 0 || removeIndex >= steps.length) {
+            return null;
+        }
+        const removedTaskName = getTaskNameFromStep(steps[removeIndex]);
+        const nextSteps = [...steps];
+        nextSteps.splice(removeIndex, 1);
+        const nextDefinition = Workflow.setValueAtPath(definition, stepsPath, nextSteps);
+        if (!removedTaskName ||
+            !Object.prototype.hasOwnProperty.call(nextDefinition.defs, removedTaskName)) {
+            return nextDefinition;
+        }
+        if (nextDefinition.defs[removedTaskName]?.kind !== dsl_types_1.TASK_KIND) {
+            return nextDefinition;
+        }
+        if (hasTaskReference(nextDefinition.flow, removedTaskName)) {
+            return nextDefinition;
+        }
+        const { [removedTaskName]: _removedTask, ...remainingDefs } = nextDefinition.defs;
+        return {
+            ...nextDefinition,
+            defs: remainingDefs,
+        };
+    }
+    /**
+     * Insert a flow step into the definition at the given path, if valid.
+     */
+    static insertStepAtPath(definition, insertPath, step) {
+        if (!insertPath.length) {
+            return null;
+        }
+        const insertIndex = insertPath[insertPath.length - 1];
+        if (typeof insertIndex !== 'number') {
+            return null;
+        }
+        const stepsPath = insertPath.slice(0, -1);
+        const steps = Workflow.getValueAtPath(definition, stepsPath);
+        if (!Array.isArray(steps)) {
+            return null;
+        }
+        const nextSteps = [...steps];
+        const safeIndex = Math.min(Math.max(insertIndex, 0), nextSteps.length);
+        nextSteps.splice(safeIndex, 0, step);
+        return Workflow.setValueAtPath(definition, stepsPath, nextSteps);
+    }
+    /**
+     * Rename a task key and update references in flow steps and output expressions.
+     */
+    static safeRenameTaskInDefinition(definition, currentTaskName, nextTaskName) {
+        return (0, workflow_definition_1.safeRenameTaskInDefinition)(definition, currentTaskName, nextTaskName);
+    }
+    /**
+     * Run the workflow until completion or suspension.
+     * Throws when a task suspends so callers can capture the state.
+     */
+    async run(inputData, context, options) {
+        const runner = new workflow_runner_1.WorkflowRunner(this.compiled, options);
+        const result = await runner.start({
+            inputData,
+            context,
+        });
+        if (result.status === 'finished') {
+            return result.output;
+        }
+        if (result.status === 'failed') {
+            throw result.error instanceof Error
+                ? result.error
+                : new Error(String(result.error));
+        }
+        context.attachWorkflowRuntime(undefined);
+        throw new WorkflowRunSuspendedError(result.step.id, {
+            reason: result.reason,
+            data: result.data,
+        });
+    }
+    /**
+     * Construct a runner without executing, allowing hosts to manage start/resume manually.
+     */
+    async buildAsyncRunner(options) {
+        return new workflow_runner_1.WorkflowRunner(this.compiled, options);
+    }
+    /**
+     * Rebuild a runner from persisted state and snapshot, useful after restarts.
+     */
+    async buildRunnerFromState(options) {
+        return workflow_runner_1.WorkflowRunner.fromPersistedState(this.compiled, options);
+    }
+}
+exports.Workflow = Workflow;

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

@@ -0,0 +1,137 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+import { z } from 'zod';
+import { BaseSettingsSchema } from '../dsl.types';
+import { assertSnakeCaseName } from '../utils/naming';
+import { sleep, withTimeout } from '../utils/timeout';
+const BASE_SETTINGS_KEYS = Object.keys(BaseSettingsSchema.shape);
+/**
+ * Base implementation that enforces schema-validated input/output.
+ */
+export class AbstractAction {
+    /**
+     * Sets up core metadata and schemas for the action.
+     *
+     * @param metadata - Describes the action name, description, and schemas.
+     * @param options - Optional configuration or definition override.
+     */
+    constructor(metadata) {
+        if (metadata.settingsSchema instanceof z.ZodObject) {
+            const actionSettingsKeys = Object.keys(metadata.settingsSchema.shape);
+            const overlappingKeys = actionSettingsKeys.filter((key) => BASE_SETTINGS_KEYS.includes(key));
+            if (overlappingKeys.length > 0) {
+                throw new Error(`settingsSchema cannot redefine base settings keys: ${overlappingKeys.join(', ')}`);
+            }
+        }
+        assertSnakeCaseName(metadata.name, 'action');
+        this.name = metadata.name;
+        this.description = metadata.description;
+        this.inputSchema = metadata.inputSchema;
+        this.outputSchema = metadata.outputSchema;
+        this.settingSchema = metadata.settingsSchema;
+        this.supportedBindings = metadata.supportedBindings ?? [];
+    }
+    /**
+     * Parses incoming payloads using the input schema.
+     *
+     * @param payload - Raw input received by the action.
+     * @returns Validated input typed as `I`.
+     */
+    parseInput(payload) {
+        return this.inputSchema.parse(payload);
+    }
+    /**
+     * Validates and returns the raw action output.
+     *
+     * @param payload - Raw output produced by {@link execute}.
+     * @returns Output typed as `O` after schema validation.
+     */
+    parseOutput(payload) {
+        return this.outputSchema.parse(payload);
+    }
+    /**
+     * Executes the action with retry, timeout, and schema safety.
+     *
+     * @param payload - Raw input being provided to the action.
+     * @param context - Workflow context used during execution.
+     * @returns Validated output produced by the action.
+     * @throws Error when retries are exhausted or validation fails.
+     */
+    parseSettings(payload) {
+        const settings = z
+            .intersection(BaseSettingsSchema, this.settingSchema)
+            .parse(payload ?? {});
+        return (settings ?? {});
+    }
+    async run(payload, context, settings, bindings) {
+        const input = this.parseInput(payload);
+        const parsedSettings = this.parseSettings(settings);
+        const parsedBindings = (bindings ?? {});
+        this.assertSupportedBindings(parsedBindings);
+        const timeoutMs = parsedSettings.timeout_ms ?? 0;
+        const retrySettings = parsedSettings.retries ?? {
+            enabled: false,
+            max_attempts: 1,
+            backoff_ms: 0,
+            max_delay_ms: 0,
+            jitter: 0,
+            multiplier: 1,
+        };
+        const retriesEnabled = retrySettings.enabled ?? true;
+        const maxAttempts = retriesEnabled ? retrySettings.max_attempts : 1;
+        let attempt = 0;
+        let currentDelay = retrySettings.backoff_ms ?? 0;
+        const maxDelayMs = retrySettings.max_delay_ms;
+        const jitter = retrySettings.jitter;
+        const multiplier = retrySettings.multiplier;
+        while (attempt < maxAttempts) {
+            try {
+                const result = await withTimeout(this.execute({
+                    input,
+                    context,
+                    settings: parsedSettings,
+                    bindings: parsedBindings,
+                }), timeoutMs);
+                return this.parseOutput(result);
+            }
+            catch (error) {
+                attempt += 1;
+                if (attempt >= maxAttempts) {
+                    throw error;
+                }
+                let delay = currentDelay;
+                if (maxDelayMs > 0) {
+                    delay = Math.min(delay, maxDelayMs);
+                }
+                if (delay > 0) {
+                    const jitterFactor = jitter > 0 ? 1 + (Math.random() * 2 - 1) * jitter : 1;
+                    const jitteredDelay = Math.max(0, Math.round(delay * jitterFactor));
+                    if (jitteredDelay > 0) {
+                        await sleep(jitteredDelay);
+                    }
+                }
+                const nextDelay = currentDelay * multiplier;
+                currentDelay =
+                    maxDelayMs > 0 ? Math.min(nextDelay, maxDelayMs) : nextDelay;
+            }
+        }
+        throw new Error('Action failed after exhausting retry attempts.');
+    }
+    assertSupportedBindings(bindings) {
+        const bindingKinds = Object.keys((bindings ?? {}));
+        if (bindingKinds.length === 0) {
+            return;
+        }
+        const unsupportedKinds = bindingKinds.filter((bindingKind) => !this.supportedBindings.includes(bindingKind));
+        if (unsupportedKinds.length === 0) {
+            return;
+        }
+        const supported = this.supportedBindings.length > 0
+            ? this.supportedBindings.join(', ')
+            : '<none>';
+        throw new Error(`Action "${this.name}" does not support binding kind(s): ${unsupportedKinds.join(', ')}. Supported binding kinds: ${supported}.`);
+    }
+}

package/dist/esm/action/action.js

@@ -0,0 +1,44 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+import { z } from 'zod';
+import { AbstractAction } from './abstract-action';
+/**
+ * Builds an {@link AbstractAction} subclass from simple configuration.
+ *
+ * @param params - Action definition containing metadata and runtime logic.
+ * @returns Instantiated action ready to be used by a workflow.
+ * @typeParam I - Action input type.
+ * @typeParam O - Action output type.
+ * @typeParam Ctx - Workflow context type.
+ */
+export function defineAction(params) {
+    const defaultSettingsSchema = z.any();
+    const defaultInputSchema = z.any();
+    const defaultOutputSchema = z.any();
+    class FnAction extends AbstractAction {
+        constructor() {
+            const metadata = {
+                name: params.name,
+                description: params.description ?? '',
+                inputSchema: params.inputSchema ?? defaultInputSchema,
+                outputSchema: params.outputSchema ?? defaultOutputSchema,
+                settingsSchema: params.settingSchema ?? defaultSettingsSchema,
+                supportedBindings: params.supportedBindings,
+            };
+            super(metadata);
+        }
+        /**
+         * Delegates to the user supplied execute callback.
+         *
+         * @param args - Action execution arguments supplied by the runner.
+         * @returns Result of the user callback as a promise.
+         */
+        async execute(args) {
+            return await Promise.resolve(params.execute(args));
+        }
+    }
+    return new FnAction();
+}

package/dist/esm/action/action.types.js

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