@hexabot-ai/agentic 3.0.1-alpha.0

package/src/utils/workflow-definition.ts

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

package/src/workflow-compiler.ts

@@ -0,0 +1,317 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z, ZodType } from 'zod';
+
+import type { Action } from './action/action.types';
+import type { BindingKindSchemas } from './bindings/base-binding';
+import {
+  mountTaskBindings,
+  validateAndResolveBindings,
+} from './bindings/base-binding';
+import type { BaseWorkflowContext } from './context';
+import type {
+  FlowStep,
+  InputField,
+  TaskDefinition,
+  WorkflowDefinition,
+} from './dsl.types';
+import { extractTaskDefinitions as extractTaskDefinitionsFromDefs } from './dsl.types';
+import { assertSnakeCaseName } from './utils/naming';
+import { StepType } from './workflow-event-emitter';
+import type {
+  CompiledMapping,
+  CompiledStep,
+  CompiledTask,
+  CompiledWorkflow,
+  ConditionalBranch,
+  LoopStep,
+  ParallelStep,
+} from './workflow-types';
+import {
+  compileValue,
+  mergeSettings,
+  type CompileValueOptions,
+} from './workflow-values';
+
+export type WorkflowCompileOptions = CompileValueOptions & {
+  actions: Record<string, Action>;
+  bindingKinds?: BindingKindSchemas;
+};
+
+/** Build a stable identifier for a step using its path and label. */
+const buildStepId = (path: Array<number | string>, label: string): string => {
+  const pathPart = path.length > 0 ? path.join('.') : 'root';
+
+  return `${pathPart}:${label}`;
+};
+/** Convert workflow input field metadata to a zod schema. */
+const inputFieldToZod = (field: InputField): ZodType => {
+  let schema: ZodType;
+
+  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: Record<string, ZodType> = {};
+      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?: Record<string, InputField>,
+): ZodType<Record<string, unknown>> => {
+  if (!schema || Object.keys(schema).length === 0) {
+    return z.looseObject({});
+  }
+
+  const shape: Record<string, ZodType> = {};
+
+  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?: Record<string, unknown>,
+  options?: WorkflowCompileOptions,
+): CompiledMapping | undefined => {
+  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: Record<string, TaskDefinition>,
+  actions: Record<string, Action<unknown, unknown, BaseWorkflowContext>>,
+) => {
+  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: WorkflowDefinition,
+  options: WorkflowCompileOptions,
+): Record<string, CompiledTask> => {
+  const compiled: Record<string, CompiledTask> = {};
+  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: FlowStep[],
+  path: Array<number | string> = [],
+  options?: WorkflowCompileOptions,
+): CompiledStep[] =>
+  steps.map<CompiledStep>((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,
+        ),
+      } as ParallelStep;
+    }
+
+    if ('conditional' in step) {
+      const label = step.conditional.description ?? 'conditional';
+      const branches: ConditionalBranch[] = 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,
+      ),
+    } as const;
+
+    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,
+      } as LoopStep;
+    }
+
+    return {
+      ...commonLoop,
+      loopType: 'while',
+      while: compileValue(loop.while, options),
+    } as LoopStep;
+  });
+
+/** Compile a workflow definition into structures consumable by the runtime. */
+export const compileWorkflow = (
+  definition: WorkflowDefinition,
+  options: WorkflowCompileOptions,
+): CompiledWorkflow => {
+  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/src/workflow-event-emitter.ts

@@ -0,0 +1,86 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+export enum StepType {
+  Task = 'task',
+  Parallel = 'parallel',
+  Conditional = 'conditional',
+  Loop = 'loop',
+}
+
+export type StepInfo = {
+  id: string;
+  name: string;
+  type: StepType;
+};
+
+export type WorkflowEventMap = {
+  'hook:workflow:start': { runId?: string };
+  'hook:workflow:finish': { runId?: string; output: Record<string, unknown> };
+  'hook:workflow:failure': { runId?: string; error: unknown };
+  'hook:workflow:suspended': {
+    runId?: string;
+    step: StepInfo;
+    reason?: string;
+    data?: unknown;
+  };
+  'hook:step:start': { runId?: string; step: StepInfo };
+  'hook:step:success': { runId?: string; step: StepInfo };
+  'hook:step:error': { runId?: string; step: StepInfo; error: unknown };
+  'hook:step:suspended': {
+    runId?: string;
+    step: StepInfo;
+    reason?: string;
+    data?: unknown;
+  };
+  'hook:step:skipped': { runId?: string; step: StepInfo; reason?: string };
+};
+
+export type EventEmitterLike = {
+  emit(event: string | symbol, ...args: any[]): unknown;
+  on(event: string | symbol, listener: (...args: any[]) => void): unknown;
+};
+
+export type WorkflowEventEmitterLike<E = unknown> = E & EventEmitterLike;
+
+type EventKey = keyof WorkflowEventMap;
+type AnyListener = (payload: WorkflowEventMap[EventKey]) => void;
+
+/**
+ * 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
+  implements WorkflowEventEmitterLike<WorkflowEventEmitter>
+{
+  private listeners = new Map<EventKey, Set<AnyListener>>();
+
+  emit<K extends keyof WorkflowEventMap>(
+    event: K,
+    payload: WorkflowEventMap[K],
+  ): boolean {
+    const eventListeners = this.listeners.get(event);
+    if (!eventListeners || eventListeners.size === 0) {
+      return false;
+    }
+
+    eventListeners.forEach((listener) => listener(payload));
+
+    return true;
+  }
+
+  on<K extends keyof WorkflowEventMap>(
+    event: K,
+    listener: (payload: WorkflowEventMap[K]) => void,
+  ): this {
+    const listeners = this.listeners.get(event) ?? new Set<AnyListener>();
+    listeners.add(listener as AnyListener);
+    this.listeners.set(event, listeners);
+
+    return this;
+  }
+}