@hexabot-ai/agentic 3.0.1-alpha.0

package/src/workflow-types.ts

@@ -0,0 +1,207 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type { Expression } from 'jsonata';
+import type { ZodType } from 'zod';
+
+import type { Action } from './action/action.types';
+import type { CompiledTaskBindings } from './bindings/base-binding';
+import type { BaseWorkflowContext, WorkflowSnapshot } from './context';
+import type { Settings, TaskDefinition, WorkflowDefinition } from './dsl.types';
+import { StepType, type StepInfo } from './workflow-event-emitter';
+
+export type { CompiledTaskBindings } from './bindings/base-binding';
+
+/** Value representation used by the runtime after compilation. */
+export type CompiledValue =
+  | { kind: 'literal'; value: unknown }
+  | { kind: 'expression'; source: string; expression: Expression };
+
+/** Map of variable names to compiled values. */
+export type CompiledMapping = Record<string, CompiledValue>;
+
+/** Fully resolved task with parsed settings and compiled IO mappings. */
+export type CompiledTask = {
+  name: string;
+  definition: TaskDefinition;
+  actionName: string;
+  action: Action;
+  inputs: CompiledMapping;
+  settings: Settings;
+  bindings: CompiledTaskBindings;
+};
+
+/** Complete workflow ready for execution. */
+export type CompiledWorkflow = {
+  definition: WorkflowDefinition;
+  tasks: Record<string, CompiledTask>;
+  flow: CompiledStep[];
+  outputMapping: CompiledMapping;
+  inputParser: ZodType<Record<string, unknown>>;
+  defaultSettings?: Settings;
+};
+
+/** Any executable step inside the compiled flow. */
+export type CompiledStep = TaskStep | ParallelStep | ConditionalStep | LoopStep;
+
+export type BaseStep = {
+  id: string;
+  label: string;
+  type: StepType;
+};
+
+/** Single task execution. */
+export type TaskStep = BaseStep & {
+  type: StepType.Task;
+  taskName: string;
+};
+
+/** Runs nested steps with either wait-all or wait-any semantics. */
+export type ParallelStep = BaseStep & {
+  type: StepType.Parallel;
+  description?: string;
+  strategy: 'wait_all' | 'wait_any';
+  steps: CompiledStep[];
+};
+
+/** Conditional branch tree describing when to run a step list. */
+export type ConditionalBranch = {
+  id: string;
+  condition?: CompiledValue;
+  steps: CompiledStep[];
+};
+
+/** Conditional step with multiple branches. */
+export type ConditionalStep = BaseStep & {
+  type: StepType.Conditional;
+  description?: string;
+  branches: ConditionalBranch[];
+};
+
+type BaseLoopStep = BaseStep & {
+  type: StepType.Loop;
+  name?: string;
+  description?: string;
+  accumulate?: { as: string; initial: unknown; merge: CompiledValue };
+  steps: CompiledStep[];
+};
+
+/** Loop over items with optional post-iteration break condition. */
+export type ForEachLoopStep = BaseLoopStep & {
+  loopType: 'for_each';
+  forEach: { item: string; in: CompiledValue };
+  maxConcurrency?: number;
+  until?: CompiledValue;
+};
+
+/** Classic while-loop evaluated before each iteration. */
+export type WhileLoopStep = BaseLoopStep & {
+  loopType: 'while';
+  while: CompiledValue;
+};
+
+export type LoopStep = ForEachLoopStep | WhileLoopStep;
+
+/** Scope passed to value evaluators, reflecting the live runtime state. */
+export type EvaluationScope = {
+  input: Record<string, unknown>;
+  context: Record<string, unknown>;
+  output: Record<string, unknown>;
+  iteration?: { item: unknown; index: number };
+  accumulator?: unknown;
+  result?: unknown;
+};
+
+/** Minimal mutable state for the executor. */
+export type ExecutionState = {
+  input: Record<string, unknown>;
+  output: Record<string, unknown>;
+  iteration?: { item: unknown; index: number };
+  accumulator?: unknown;
+  iterationStack: number[];
+};
+
+/** Encapsulates a suspended step and how to continue it. */
+export type Suspension = {
+  step: StepInfo;
+  reason?: string;
+  data?: unknown;
+  stepExecId?: string;
+  suspendIndex?: number;
+  suspendKey?: string;
+  awaitResults?: Record<string, unknown>;
+  continue: (resumeData: unknown) => Promise<Suspension | void>;
+};
+
+export type PersistedSuspension = {
+  stepId: string;
+  reason?: string | null;
+  data?: unknown;
+  stepExecId?: string;
+  suspendIndex?: number;
+  suspendKey?: string;
+  awaitResults?: Record<string, unknown>;
+};
+
+/** Result of starting a workflow run. */
+export type StartResult =
+  | {
+      status: 'finished';
+      output: Record<string, unknown>;
+      snapshot: WorkflowSnapshot;
+    }
+  | {
+      status: 'suspended';
+      step: StepInfo;
+      reason?: string;
+      data?: unknown;
+      stepExecId?: string;
+      suspendIndex?: number;
+      suspendKey?: string;
+      awaitResults?: Record<string, unknown>;
+      snapshot: WorkflowSnapshot;
+    }
+  | { status: 'failed'; error: unknown; snapshot: WorkflowSnapshot };
+
+/** Result of resuming a suspended workflow. */
+export type ResumeResult =
+  | {
+      status: 'finished';
+      output: Record<string, unknown>;
+      snapshot: WorkflowSnapshot;
+    }
+  | {
+      status: 'suspended';
+      step: StepInfo;
+      reason?: string;
+      data?: unknown;
+      stepExecId?: string;
+      suspendIndex?: number;
+      suspendKey?: string;
+      awaitResults?: Record<string, unknown>;
+      snapshot: WorkflowSnapshot;
+    }
+  | { status: 'failed'; error: unknown; snapshot: WorkflowSnapshot };
+
+/** Options that influence how the workflow runner behaves. */
+export type WorkflowRunOptions = {
+  runId?: string;
+};
+
+export type WorkflowStartResult = StartResult;
+
+export type WorkflowResumeResult = ResumeResult;
+
+/** Arguments required to start a run. */
+export type RunnerStartArgs = {
+  inputData: unknown;
+  context: BaseWorkflowContext;
+};
+
+/** Payload passed when resuming a suspended run. */
+export type RunnerResumeArgs = {
+  resumeData?: unknown;
+};

package/src/workflow-values.ts

@@ -0,0 +1,159 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import type { Expression, Focus } from 'jsonata';
+import jsonata from 'jsonata';
+
+import type { JsonValue, Settings } from './dsl.types';
+import type {
+  CompiledMapping,
+  CompiledValue,
+  EvaluationScope,
+} from './workflow-types';
+
+export type JsonataFunctionImplementation = (
+  this: Focus,
+  ...args: any[]
+) => unknown;
+
+export type JsonataFunctionConfig =
+  | JsonataFunctionImplementation
+  | {
+      implementation: JsonataFunctionImplementation;
+      signature?: string;
+    };
+
+export type JsonataFunctionRegistry = Record<string, JsonataFunctionConfig>;
+
+export type CompileValueOptions = {
+  jsonataFunctions?: JsonataFunctionRegistry;
+};
+
+/** Basic object guard that rejects arrays and null. */
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+const registerJsonataFunctions = (
+  expression: Expression,
+  registry?: JsonataFunctionRegistry,
+) => {
+  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: unknown,
+  options?: CompileValueOptions,
+): CompiledValue => {
+  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: CompiledValue,
+  scope: EvaluationScope,
+): Promise<unknown> => {
+  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: CompiledMapping | undefined,
+  scope: EvaluationScope,
+): Promise<Record<string, unknown>> => {
+  if (!mapping) {
+    return {};
+  }
+
+  const result: Record<string, unknown> = {};
+
+  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?: Partial<Settings>,
+  override?: Partial<Settings>,
+): Partial<Settings> => {
+  const merged: Partial<Settings> = { ...(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 as Partial<Settings>,
+        value as Partial<Settings>,
+      ) as JsonValue;
+    } else if (value !== undefined) {
+      merged[key] = value;
+    }
+  }
+
+  return merged;
+};