@hexabot-ai/agentic 3.0.1-alpha.0

package/dist/esm/workflow-values.js

@@ -0,0 +1,89 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+import jsonata from '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.
+ */
+export const compileValue = (value, options) => {
+    if (typeof value === 'string' && value.startsWith('=')) {
+        const expression = jsonata(value.slice(1));
+        registerJsonataFunctions(expression, options?.jsonataFunctions);
+        return { kind: 'expression', source: value, expression };
+    }
+    return { kind: 'literal', value };
+};
+/**
+ * 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.
+ */
+export 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,
+    });
+};
+/**
+ * Evaluate all entries of a compiled mapping, returning a plain object.
+ * Missing mappings resolve to an empty object.
+ */
+export const evaluateMapping = async (mapping, scope) => {
+    if (!mapping) {
+        return {};
+    }
+    const result = {};
+    for (const [key, compiled] of Object.entries(mapping)) {
+        result[key] = await evaluateValue(compiled, scope);
+    }
+    return result;
+};
+/**
+ * Deep-merge workflow settings, preferring non-undefined overrides.
+ * Nested objects are merged recursively to preserve defaults.
+ */
+export 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] = mergeSettings(previous, value);
+        }
+        else if (value !== undefined) {
+            merged[key] = value;
+        }
+    }
+    return merged;
+};

package/dist/esm/workflow.js

@@ -0,0 +1,236 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+import { stringify as stringifyYaml } from 'yaml';
+import { TASK_KIND, WorkflowDefinitionSchema, validateWorkflow, } from './dsl.types';
+import { safeRenameTaskInDefinition as safeRenameTaskInDefinitionHelper } from './utils/workflow-definition';
+import { compileWorkflow, } from './workflow-compiler';
+import { WorkflowRunner } from './workflow-runner';
+export { compileWorkflow } from './workflow-compiler';
+export { WorkflowEventEmitter } from './workflow-event-emitter';
+export { WorkflowRunner } from './workflow-runner';
+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.
+ */
+export 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 = validateWorkflow(definition, {
+            bindingKinds: options.bindingKinds,
+            actions: options.actions,
+        });
+        if (!validation.success) {
+            throw new Error(`Workflow validation failed: ${validation.errors.join('; ')}`);
+        }
+        const compiled = 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 = validateWorkflow(yaml, {
+            bindingKinds: options.bindingKinds,
+            actions: options.actions,
+        });
+        if (!validation.success) {
+            throw new Error(`Workflow validation failed: ${validation.errors.join('; ')}`);
+        }
+        const compiled = 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 = WorkflowDefinitionSchema.parse(definition);
+        return stringifyYaml(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 !== 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 safeRenameTaskInDefinitionHelper(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 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 WorkflowRunner(this.compiled, options);
+    }
+    /**
+     * Rebuild a runner from persisted state and snapshot, useful after restarts.
+     */
+    async buildRunnerFromState(options) {
+        return WorkflowRunner.fromPersistedState(this.compiled, options);
+    }
+}

package/dist/types/action/abstract-action.d.ts

@@ -0,0 +1,54 @@
+import { ZodType } from 'zod';
+import { BaseWorkflowContext } from '../context';
+import { Action, ActionExecutionArgs, ActionMetadata, AnyRuntimeBindings, RuntimeSettings } from './action.types';
+/**
+ * Base implementation that enforces schema-validated input/output.
+ */
+export declare abstract class AbstractAction<I, O, C extends BaseWorkflowContext, S, B extends AnyRuntimeBindings = AnyRuntimeBindings> implements Action<I, O, C, S, B> {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: ZodType<I>;
+    readonly outputSchema: ZodType<O>;
+    readonly settingSchema: ZodType<S>;
+    readonly supportedBindings: readonly string[];
+    /**
+     * 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.
+     */
+    protected constructor(metadata: ActionMetadata<I, O, S>);
+    /**
+     * Parses incoming payloads using the input schema.
+     *
+     * @param payload - Raw input received by the action.
+     * @returns Validated input typed as `I`.
+     */
+    parseInput(payload: unknown): I;
+    /**
+     * 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: unknown): O;
+    /**
+     * 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: unknown): RuntimeSettings<S>;
+    run(payload: unknown, context: C, settings?: Partial<RuntimeSettings<S>>, bindings?: B): Promise<O>;
+    private assertSupportedBindings;
+    /**
+     * Runs the core business logic for the action.
+     *
+     * @param args - Strongly typed input and context for the action.
+     * @returns Action output wrapped in a promise.
+     */
+    abstract execute(args: ActionExecutionArgs<I, C, S, B>): Promise<O>;
+}
+//# sourceMappingURL=abstract-action.d.ts.map

package/dist/types/action/abstract-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-action.d.ts","sourceRoot":"","sources":["../../../src/action/abstract-action.ts"],"names":[],"mappings":"AAMA,OAAO,EAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAEjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAKjD,OAAO,EACL,MAAM,EACN,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAClB,eAAe,EAChB,MAAM,gBAAgB,CAAC;AAIxB;;GAEG;AACH,8BAAsB,cAAc,CAClC,CAAC,EACD,CAAC,EACD,CAAC,SAAS,mBAAmB,EAC7B,CAAC,EACD,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,CACjD,YAAW,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAEhC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC,SAAgB,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAExC,SAAgB,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAEzC,SAAgB,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAE1C,SAAgB,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAErD;;;;;OAKG;IACH,SAAS,aAAa,QAAQ,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAuBvD;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC;IAI/B;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC;IAIhC;;;;;;;OAOG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,CAAC,CAAC,CAAC;IAQ7C,GAAG,CACP,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,CAAC,EACV,QAAQ,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EACtC,QAAQ,CAAC,EAAE,CAAC,GACX,OAAO,CAAC,CAAC,CAAC;IAmEb,OAAO,CAAC,uBAAuB;IAwB/B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CACpE"}

package/dist/types/action/action.d.ts

@@ -0,0 +1,23 @@
+import { ZodType } from 'zod';
+import { BaseWorkflowContext } from '../context';
+import type { Action, ActionExecutionArgs, AnyRuntimeBindings } from './action.types';
+export type DefineActionParams<I, O, Ctx extends BaseWorkflowContext, S, B extends AnyRuntimeBindings = AnyRuntimeBindings> = {
+    name: string;
+    description?: string;
+    supportedBindings?: readonly string[];
+    inputSchema?: ZodType<I>;
+    outputSchema?: ZodType<O>;
+    settingSchema?: ZodType<S>;
+    execute: (args: ActionExecutionArgs<I, Ctx, S, B>) => Promise<O> | O;
+};
+/**
+ * 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 declare function defineAction<I, O, Ctx extends BaseWorkflowContext, S, B extends AnyRuntimeBindings = AnyRuntimeBindings>(params: DefineActionParams<I, O, Ctx, S, B>): Action<I, O, Ctx, S, B>;
+//# sourceMappingURL=action.d.ts.map

package/dist/types/action/action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../../src/action/action.ts"],"names":[],"mappings":"AAMA,OAAO,EAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAEjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGjD,OAAO,KAAK,EACV,MAAM,EACN,mBAAmB,EAEnB,kBAAkB,EACnB,MAAM,gBAAgB,CAAC;AAExB,MAAM,MAAM,kBAAkB,CAC5B,CAAC,EACD,CAAC,EACD,GAAG,SAAS,mBAAmB,EAC/B,CAAC,EACD,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,IAC/C;IACF,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,OAAO,EAAE,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;CACtE,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,CAAC,EACD,CAAC,EACD,GAAG,SAAS,mBAAmB,EAC/B,CAAC,EACD,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,EACjD,MAAM,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAiCtE"}

package/dist/types/action/action.types.d.ts

@@ -0,0 +1,55 @@
+import { ZodType } from 'zod';
+import type { InferWorkflowBindings } from '../bindings/base-binding';
+import { BaseWorkflowContext } from '../context';
+import { Settings } from '../dsl.types';
+import { Deferred } from '../utils/deferred';
+export type RuntimeSettings<S = unknown> = Settings & S;
+export type AnyRuntimeBindings = InferWorkflowBindings;
+export interface ActionMetadata<I, O, S> {
+    name: string;
+    description: string;
+    inputSchema: ZodType<I>;
+    outputSchema: ZodType<O>;
+    settingsSchema: ZodType<S>;
+    supportedBindings?: readonly string[];
+}
+export interface ActionExecutionArgs<I, C extends BaseWorkflowContext = BaseWorkflowContext, S = unknown, B extends AnyRuntimeBindings = AnyRuntimeBindings> {
+    input: I;
+    context: C;
+    settings: RuntimeSettings<S>;
+    bindings: B;
+}
+export interface Action<I = unknown, O = unknown, C extends BaseWorkflowContext = BaseWorkflowContext, S = unknown, B extends AnyRuntimeBindings = AnyRuntimeBindings> {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: ZodType<I>;
+    readonly outputSchema: ZodType<O>;
+    readonly settingSchema?: ZodType<S>;
+    readonly supportedBindings?: readonly string[];
+    execute(args: ActionExecutionArgs<I, C, S, B>): Promise<O>;
+    parseInput(payload: unknown): I;
+    parseOutput(payload: unknown): O;
+    parseSettings(payload: unknown): RuntimeSettings<S>;
+    run(payload: unknown, context: C, settings?: Partial<RuntimeSettings<S>>, bindings?: B): Promise<O>;
+}
+export type Actions = Record<string, Action>;
+export type InferActionArgs<A extends Action> = Parameters<A['execute']>[0];
+export type InferActionInput<A extends Action> = InferActionArgs<A>['input'];
+export type InferActionContext<A extends Action> = InferActionArgs<A>['context'];
+export type InferActionOutput<A extends Action> = Awaited<ReturnType<A['execute']>>;
+export type InferActionSettings<S extends Action> = InferActionArgs<S>['settings'];
+export type InferActionBindings<S extends Action> = InferActionArgs<S>['bindings'];
+export interface SuspensionNotice {
+    stepId: string;
+    reason?: string;
+    data?: unknown;
+    resume: Deferred<unknown>;
+}
+export type ActionExecutionOutcome<T> = {
+    type: 'completed';
+    value: T;
+} | {
+    type: 'suspended';
+    notice: SuspensionNotice;
+};
+//# sourceMappingURL=action.types.d.ts.map

package/dist/types/action/action.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action.types.d.ts","sourceRoot":"","sources":["../../../src/action/action.types.ts"],"names":[],"mappings":"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"}

package/dist/types/bindings/base-binding.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+export type BindingKindSchema = z.ZodTypeAny;
+export type BindingActionPolicy = 'forbidden' | 'optional' | 'required';
+export type BindingValidationActionMetadata = {
+    supportedBindings?: readonly string[];
+};
+export type BindingKindDescriptor<TSchema extends z.ZodTypeAny = BindingKindSchema, TMultiple extends boolean = boolean> = {
+    schema: TSchema;
+    multiple: TMultiple;
+    supportedBindings?: readonly string[];
+    actionPolicy?: BindingActionPolicy;
+};
+export type BindingKindSchemas = Record<string, BindingKindDescriptor>;
+export type MountedBindingPayload<TBindingKind extends BindingKindDescriptor = BindingKindDescriptor, TBindingKinds extends BindingKindSchemas = BindingKindSchemas> = {
+    settings: z.infer<TBindingKind['schema']>;
+    action?: string;
+    bindings?: InferWorkflowBindings<TBindingKinds>;
+};
+export type InferMountedBindingValue<TBindingKind extends BindingKindDescriptor = BindingKindDescriptor, TBindingKinds extends BindingKindSchemas = BindingKindSchemas> = TBindingKind['multiple'] extends true ? Record<string, MountedBindingPayload<TBindingKind, TBindingKinds>> : TBindingKind['multiple'] extends false ? MountedBindingPayload<TBindingKind, TBindingKinds> : MountedBindingPayload<TBindingKind, TBindingKinds> | Record<string, MountedBindingPayload<TBindingKind, TBindingKinds>>;
+export type InferWorkflowBindings<TBindingKinds extends BindingKindSchemas = BindingKindSchemas> = Partial<{
+    [K in keyof TBindingKinds & string]: InferMountedBindingValue<TBindingKinds[K], TBindingKinds>;
+}>;
+export type CompiledTaskBindings = InferWorkflowBindings;
+export type TaskBindingReferences = Record<string, string | string[]>;
+export type DefLike = {
+    kind: string;
+    description?: string;
+    action?: string;
+    settings?: unknown;
+    bindings?: TaskBindingReferences;
+    [key: string]: unknown;
+};
+export type BindingAwareWorkflowLike = {
+    defs: Record<string, DefLike>;
+};
+export type ResolvedBindingDef = {
+    kind: string;
+    payload: MountedBindingPayload;
+};
+export type ResolvedBindingDefs = Record<string, ResolvedBindingDef>;
+export type ValidateAndResolveBindingsOptions = {
+    bindingKinds?: BindingKindSchemas;
+    actions?: Record<string, BindingValidationActionMetadata>;
+};
+type BindingValidationResult = {
+    errors: string[];
+    resolvedDefs: ResolvedBindingDefs;
+};
+export declare const validateAndResolveBindings: (workflow: BindingAwareWorkflowLike, options?: BindingKindSchemas | ValidateAndResolveBindingsOptions) => BindingValidationResult;
+export declare const mountTaskBindings: (taskBindings: TaskBindingReferences | undefined, resolvedDefs: ResolvedBindingDefs, bindingKinds?: BindingKindSchemas, resolveDef?: (defName: string) => MountedBindingPayload | undefined) => CompiledTaskBindings;
+export {};
+//# sourceMappingURL=base-binding.d.ts.map

package/dist/types/bindings/base-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-binding.d.ts","sourceRoot":"","sources":["../../../src/bindings/base-binding.ts"],"names":[],"mappings":"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"}

package/dist/types/context.d.ts

@@ -0,0 +1,105 @@
+import type { EventEmitterLike, WorkflowEventEmitterLike } from './workflow-event-emitter';
+/**
+ * Lifecycle of a workflow run:
+ * - idle: runner constructed but `start` not invoked.
+ * - running: set when `start` or `resume` begins executing steps.
+ * - suspended: an action awaited `workflow.suspend`; `resume` moves back to running.
+ * - finished: all steps completed and outputs were evaluated successfully.
+ * - failed: an uncaught error bubbled out of a step or continuation.
+ */
+export type WorkflowRunStatus = 'idle' | 'running' | 'suspended' | 'finished' | 'failed';
+/**
+ * Lifecycle of an individual action/step captured in snapshots:
+ * - pending: defined but not yet executed (default before runner touches the step).
+ * - running: inputs evaluated and action invoked.
+ * - suspended: action paused via `workflow.suspend`; resumes to completed.
+ * - completed: action resolved (either immediately or after resume).
+ * - failed: action threw an error.
+ * - skipped: control flow bypassed the step (e.g., alternate branch or wait_any short-circuit).
+ */
+export type ActionStatus = 'pending' | 'running' | 'suspended' | 'completed' | 'failed' | 'skipped';
+export interface SuspensionOptions {
+    key?: string;
+    reason?: string;
+    data?: unknown;
+}
+export interface ActionSnapshot {
+    id: string;
+    name: string;
+    status: ActionStatus;
+    reason?: string;
+}
+export type StepExecutionRecord = {
+    id: string;
+    name: string;
+    action?: string;
+    status: ActionStatus;
+    startedAt?: number;
+    endedAt?: number;
+    input?: unknown;
+    output?: unknown;
+    context?: {
+        before?: Record<string, unknown>;
+        after?: Record<string, unknown>;
+    };
+    error?: {
+        message: string;
+        stack?: string;
+    };
+    reason?: string;
+};
+export interface WorkflowSnapshot {
+    status: WorkflowRunStatus;
+    actions: Record<string, ActionSnapshot>;
+}
+export interface WorkflowRuntimeControl {
+    readonly status: WorkflowRunStatus;
+    readonly resumeData: unknown;
+    /**
+     * Suspends the currently running action and returns a promise that settles when the workflow resumes.
+     *
+     * @param options - Optional metadata describing why the suspension occurred.
+     * @returns Promise resolved with the data supplied to {@link resume}.
+     */
+    suspend<T = unknown>(options?: SuspensionOptions): Promise<T>;
+    resume(data?: unknown): void;
+    getSnapshot(): WorkflowSnapshot;
+}
+/**
+ * Base context that is threaded through every workflow execution.
+ *
+ * Extend this class in user-land to expose shared services such as loggers,
+ * event emitters, database connections, or feature flags.
+ */
+export declare abstract class BaseWorkflowContext<S extends Record<string, unknown> = Record<string, unknown>, E = EventEmitterLike> {
+    state: S;
+    private _workflowControl?;
+    abstract eventEmitter: WorkflowEventEmitterLike<E>;
+    /**
+     * Sets up the context and copies any initial state onto the instance.
+     *
+     * @param initialState - Optional properties to assign to the context instance.
+     * @param eventEmitter - Optional workflow event emitter to expose to actions.
+     */
+    constructor(initialState: S);
+    /**
+     * Snapshot the context state for telemetry or UI rendering.
+     * Override to filter or reshape the exposed state.
+     */
+    snapshot(): Record<string, unknown>;
+    /**
+     * Provides access to the workflow runtime API for the current execution.
+     *
+     * @returns Runtime control methods that allow suspension and inspection.
+     * @throws Error when the context is not currently attached to a runner.
+     */
+    get workflow(): WorkflowRuntimeControl;
+    /**
+     * Attaches or detaches the runtime control object.
+     *
+     * @param control - Runtime control instance or `undefined` to detach.
+     * @returns Nothing; the method mutates internal state.
+     */
+    attachWorkflowRuntime(control: WorkflowRuntimeControl | undefined): void;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/types/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/context.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,gBAAgB,EAChB,wBAAwB,EACzB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,SAAS,GACT,WAAW,GACX,UAAU,GACV,QAAQ,CAAC;AAEb;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,SAAS,GACT,WAAW,GACX,WAAW,GACX,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACjC,CAAC;IACF,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B;;;;;OAKG;IACH,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9D,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B,WAAW,IAAI,gBAAgB,CAAC;CACjC;AAED;;;;;GAKG;AACH,8BAAsB,mBAAmB,CACvC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,CAAC,GAAG,gBAAgB;IAEb,KAAK,EAAE,CAAC,CAAC;IAEhB,OAAO,CAAC,gBAAgB,CAAC,CAAyB;IAElD,SAAgB,YAAY,EAAE,wBAAwB,CAAC,CAAC,CAAC,CAAC;IAE1D;;;;;OAKG;gBACS,YAAY,EAAE,CAAC;IAI3B;;;OAGG;IACH,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAInC;;;;;OAKG;IACH,IAAI,QAAQ,IAAI,sBAAsB,CAMrC;IAED;;;;;OAKG;IACH,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,SAAS,GAAG,IAAI;CAGzE"}