@hexabot-ai/agentic 3.0.1-alpha.0

package/src/context.ts

@@ -0,0 +1,179 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+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 abstract class BaseWorkflowContext<
+  S extends Record<string, unknown> = Record<string, unknown>,
+  E = EventEmitterLike,
+> {
+  public state: S;
+
+  private _workflowControl?: WorkflowRuntimeControl;
+
+  public 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) {
+    this.state = (initialState ?? {}) as S;
+  }
+
+  /**
+   * Snapshot the context state for telemetry or UI rendering.
+   * Override to filter or reshape the exposed state.
+   */
+  snapshot(): Record<string, unknown> {
+    return safeCloneRecord(this.state);
+  }
+
+  /**
+   * 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 {
+    if (!this._workflowControl) {
+      throw new Error('Workflow runtime is not attached to this context.');
+    }
+
+    return this._workflowControl;
+  }
+
+  /**
+   * 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 {
+    this._workflowControl = control;
+  }
+}
+
+const safeCloneRecord = (
+  value: Record<string, unknown>,
+): Record<string, unknown> => {
+  if (!value) {
+    return {};
+  }
+
+  if (typeof structuredClone === 'function') {
+    try {
+      return structuredClone(value) as Record<string, unknown>;
+    } catch {
+      // Fall through to JSON clone below.
+    }
+  }
+
+  try {
+    return JSON.parse(JSON.stringify(value)) as Record<string, unknown>;
+  } catch {
+    const shallow: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value)) {
+      if (typeof entry !== 'function') {
+        shallow[key] = entry;
+      }
+    }
+
+    return shallow;
+  }
+};

package/src/dsl.types.ts

@@ -0,0 +1,473 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import jsonata from 'jsonata';
+import { parse as parseYaml } from 'yaml';
+import { z } from 'zod';
+
+import type { BindingKindSchemas } from './bindings/base-binding';
+import { validateAndResolveBindings } from './bindings/base-binding';
+
+export const ExpressionStringSchema = z
+  .string()
+  .regex(/^=/, 'Expression strings must start with "="')
+  .superRefine((value, ctx) => {
+    try {
+      jsonata(value.slice(1));
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : 'Unknown JSONata parse error';
+      ctx.addIssue({
+        code: 'custom',
+        message: `Invalid JSONata expression: ${message}`,
+      });
+    }
+  });
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+// Per-action timeout in milliseconds; 0 disables the timeout wrapper.
+export const DEFAULT_TIMEOUT_MS = 0;
+
+// Retry defaults: disabled with 3 attempts and exponential backoff starting at 25ms, capped at 10s, no jitter.
+export const DEFAULT_RETRY_SETTINGS = {
+  enabled: false,
+  max_attempts: 3,
+  backoff_ms: 25,
+  max_delay_ms: 10_000,
+  jitter: 0,
+  multiplier: 1,
+} as const;
+
+export type InputField = {
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+  description?: string;
+  enum?: Array<string | number | boolean>;
+  items?: InputField;
+  properties?: Record<string, InputField>;
+};
+
+export type ConditionalBranch =
+  | { condition: string; steps: FlowStep[] }
+  | { else?: unknown; steps: FlowStep[] };
+
+export type ConditionalBlock = {
+  description?: string;
+  when: ConditionalBranch[];
+};
+
+export type ParallelBlock = {
+  description?: string;
+  strategy?: 'wait_all' | 'wait_any';
+  steps: FlowStep[];
+};
+
+export type LoopAccumulate = {
+  as: string;
+  initial: JsonValue;
+  merge: string;
+};
+
+type BaseLoopStep = {
+  name?: string;
+  description?: string;
+  accumulate?: LoopAccumulate;
+  steps: FlowStep[];
+};
+
+export type ForEachLoopStep = BaseLoopStep & {
+  type: 'for_each';
+  for_each: { item: string; in: string };
+  max_concurrency?: number;
+  until?: string;
+};
+
+export type WhileLoopStep = BaseLoopStep & {
+  type: 'while';
+  while: string;
+};
+
+export type LoopStep = ForEachLoopStep | WhileLoopStep;
+
+export type FlowStep =
+  | { do: string }
+  | { parallel: ParallelBlock }
+  | { conditional: ConditionalBlock }
+  | { loop: LoopStep };
+
+export const JsonValueSchema: z.ZodType<JsonValue> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(JsonValueSchema),
+    z.record(z.string(), JsonValueSchema),
+  ]),
+);
+
+const InputFieldSchema: z.ZodType<InputField> = z.lazy(() =>
+  z
+    .strictObject({
+      type: z.enum([
+        'string',
+        'number',
+        'integer',
+        'boolean',
+        'array',
+        'object',
+      ]),
+      description: z.string().optional(),
+      enum: z.array(z.union([z.string(), z.number(), z.boolean()])).optional(),
+      items: InputFieldSchema.optional(),
+      properties: z.record(z.string(), InputFieldSchema).optional(),
+    })
+    .superRefine((value, ctx) => {
+      if (value.type === 'array' && !value.items) {
+        ctx.addIssue({
+          code: 'custom',
+          message: 'Array inputs must declare "items"',
+          path: ['items'],
+        });
+      }
+      if (value.type !== 'array' && value.items) {
+        ctx.addIssue({
+          code: 'custom',
+          message: '"items" is only valid when type is "array"',
+          path: ['items'],
+        });
+      }
+      if (value.type !== 'object' && value.properties) {
+        ctx.addIssue({
+          code: 'custom',
+          message: '"properties" is only valid when type is "object"',
+          path: ['properties'],
+        });
+      }
+    }),
+);
+// Retry policy: exponential backoff per attempt, capped by max_delay_ms, with optional jitter multiplier.
+const RetriesSchema = z.strictObject({
+  enabled: z.boolean().optional().meta({
+    title: 'Enabled',
+    description:
+      'Enable retry attempts when an action fails (disabled = no retries).',
+  }),
+  max_attempts: z
+    .int()
+    .min(1)
+    .default(DEFAULT_RETRY_SETTINGS.max_attempts)
+    .meta({
+      title: 'Max Attempts',
+      description: 'Total number of attempts before giving up.',
+    }),
+  backoff_ms: z.int().min(0).default(DEFAULT_RETRY_SETTINGS.backoff_ms).meta({
+    title: 'Initial Backoff (ms)',
+    description: 'Delay in milliseconds before the first retry.',
+  }),
+  max_delay_ms: z
+    .int()
+    .min(0)
+    .default(DEFAULT_RETRY_SETTINGS.max_delay_ms)
+    .meta({
+      title: 'Max Delay (ms)',
+      description: 'Maximum delay cap in milliseconds between retries.',
+    }),
+  jitter: z.number().min(0).default(DEFAULT_RETRY_SETTINGS.jitter).meta({
+    title: 'Jitter',
+    description: 'Randomization factor applied to retry delays (0 = none).',
+  }),
+  multiplier: z
+    .number()
+    .min(1)
+    .default(DEFAULT_RETRY_SETTINGS.multiplier)
+    .meta({
+      title: 'Backoff Multiplier',
+      description: 'Multiplier applied to the delay after each retry.',
+    }),
+});
+
+// Shared execution settings applied to every action invocation.
+export const BaseSettingsSchema = z.strictObject({
+  timeout_ms: z.int().nonnegative().optional().meta({
+    title: 'Timeout (ms)',
+    description:
+      'Maximum runtime in milliseconds for a single action invocation (0 = disabled).',
+  }),
+  retries: RetriesSchema.optional().meta({
+    title: 'Retries',
+    description: 'Retry policy applied when an action fails.',
+  }),
+});
+
+export const SettingsSchema = BaseSettingsSchema.catchall(JsonValueSchema);
+
+const TaskBindingReferenceSchema = z.union([z.string(), z.array(z.string())]);
+const TaskBindingsSchema = z.record(z.string(), TaskBindingReferenceSchema);
+
+export const TASK_KIND = 'task' as const;
+
+export const TaskDefinitionSchema = z.strictObject({
+  kind: z.literal(TASK_KIND),
+  description: z.string().optional(),
+  action: z.string(),
+  inputs: z.record(z.string(), JsonValueSchema).optional(),
+  bindings: TaskBindingsSchema.optional(),
+  settings: SettingsSchema.optional(),
+});
+
+const NonTaskDefinitionSchema = z.strictObject({
+  kind: z
+    .string()
+    .refine(
+      (kind) => kind !== TASK_KIND,
+      `kind "${TASK_KIND}" must follow the task definition shape.`,
+    ),
+  description: z.string().optional(),
+  action: z.string().optional(),
+  settings: z.record(z.string(), z.unknown()),
+  bindings: TaskBindingsSchema.optional(),
+});
+
+export const DefDefinitionSchema = z.union([
+  TaskDefinitionSchema,
+  NonTaskDefinitionSchema,
+]);
+const ConditionalWhenSchema: z.ZodType<ConditionalBranch> = z.lazy(() =>
+  z.strictObject({
+    condition: ExpressionStringSchema,
+    steps: z.array(FlowStepSchema),
+  }),
+);
+const ConditionalElseSchema: z.ZodType<ConditionalBranch> = z.lazy(() =>
+  z.strictObject({
+    else: z.unknown().optional(),
+    steps: z.array(FlowStepSchema),
+  }),
+);
+const ConditionalSchema: z.ZodType<{
+  description?: string;
+  when: ConditionalBranch[];
+}> = z.strictObject({
+  description: z.string().optional(),
+  when: z.array(z.union([ConditionalWhenSchema, ConditionalElseSchema])).min(1),
+});
+const ParallelSchema: z.ZodType<ParallelBlock> = z.strictObject({
+  description: z.string().optional(),
+  strategy: z.enum(['wait_all', 'wait_any']).optional(),
+  steps: z.array(z.lazy(() => FlowStepSchema)),
+});
+const LoopAccumulateSchema: z.ZodType<LoopAccumulate> = z.strictObject({
+  as: z.string(),
+  initial: JsonValueSchema,
+  merge: ExpressionStringSchema,
+});
+const ForEachLoopSchema = z.strictObject({
+  type: z.literal('for_each'),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  for_each: z.strictObject({
+    item: z.string(),
+    in: ExpressionStringSchema,
+  }),
+  max_concurrency: z.int().positive().optional(),
+  until: ExpressionStringSchema.optional(),
+  accumulate: LoopAccumulateSchema.optional(),
+  steps: z.array(z.lazy(() => FlowStepSchema)),
+});
+const WhileLoopSchema = z.strictObject({
+  type: z.literal('while'),
+  name: z.string().optional(),
+  description: z.string().optional(),
+  while: ExpressionStringSchema,
+  accumulate: LoopAccumulateSchema.optional(),
+  steps: z.array(z.lazy(() => FlowStepSchema)),
+});
+const LoopSchema: z.ZodType<LoopStep> = z.lazy(() =>
+  z.union([ForEachLoopSchema, WhileLoopSchema]),
+);
+
+export const FlowStepSchema: z.ZodType<FlowStep> = z.lazy(() =>
+  z.union([
+    z.strictObject({
+      do: z.string(),
+    }),
+    z.strictObject({
+      parallel: ParallelSchema,
+    }),
+    z.strictObject({
+      conditional: ConditionalSchema,
+    }),
+    z.strictObject({
+      loop: LoopSchema,
+    }),
+  ]),
+);
+
+export const WorkflowMetadataSchema = z.strictObject({
+  name: z.string().min(1),
+  version: z.string().min(1),
+  description: z.string().optional(),
+});
+
+const InputsSchema = z.strictObject({
+  schema: z.record(z.string(), InputFieldSchema).optional(),
+});
+const DefaultsSchema = z.strictObject({
+  settings: SettingsSchema.optional(),
+});
+
+export const WorkflowDefinitionSchema = z.strictObject({
+  inputs: InputsSchema.optional(),
+  context: z.record(z.string(), JsonValueSchema).optional(),
+  defaults: DefaultsSchema.optional(),
+  defs: z.record(z.string(), DefDefinitionSchema),
+  flow: z.array(FlowStepSchema),
+  outputs: z.record(z.string(), ExpressionStringSchema),
+});
+
+export type Settings = z.infer<typeof SettingsSchema>;
+
+export type Conditional = z.infer<typeof ConditionalSchema>;
+
+export type TaskDefinition = z.infer<typeof TaskDefinitionSchema>;
+
+export type DefDefinition = z.infer<typeof DefDefinitionSchema>;
+
+export type DefDefinitions = z.infer<typeof WorkflowDefinitionSchema>['defs'];
+
+export type TaskDefinitions = Record<string, TaskDefinition>;
+
+export type WorkflowMetadata = z.infer<typeof WorkflowMetadataSchema>;
+
+export type WorkflowDefinition = z.infer<typeof WorkflowDefinitionSchema>;
+
+export type WorkflowValidationActionMetadata = {
+  supportedBindings?: readonly string[];
+};
+
+export type ValidateWorkflowOptions = {
+  bindingKinds?: BindingKindSchemas;
+  actions?: Record<string, WorkflowValidationActionMetadata>;
+};
+
+export type WorkflowValidationResult =
+  | { success: true; data: WorkflowDefinition }
+  | { success: false; errors: string[] };
+
+const collectTaskReferences = (steps: FlowStep[]): string[] => {
+  const refs: string[] = [];
+
+  for (const step of steps) {
+    if ('do' in step) {
+      refs.push(step.do);
+      continue;
+    }
+
+    if ('parallel' in step) {
+      refs.push(...collectTaskReferences(step.parallel.steps));
+      continue;
+    }
+
+    if ('conditional' in step) {
+      for (const branch of step.conditional.when) {
+        if ('condition' in branch) {
+          refs.push(...collectTaskReferences(branch.steps));
+        } else if ('else' in branch) {
+          refs.push(...collectTaskReferences(branch.steps));
+        }
+      }
+      continue;
+    }
+
+    if ('loop' in step) {
+      refs.push(...collectTaskReferences(step.loop.steps));
+    }
+  }
+
+  return refs;
+};
+
+export const isTaskDefinition = (
+  definition: DefDefinition,
+): definition is TaskDefinition => definition.kind === TASK_KIND;
+
+export const extractTaskDefinitions = (defs: DefDefinitions): TaskDefinitions =>
+  Object.entries(defs).reduce<TaskDefinitions>((tasks, [defName, def]) => {
+    if (isTaskDefinition(def)) {
+      tasks[defName] = def;
+    }
+
+    return tasks;
+  }, {});
+
+const formatZodErrors = (issues: z.ZodIssue[]): string[] =>
+  issues.map((issue) => {
+    const path = issue.path.join('.') || '<root>';
+
+    return `${path}: ${issue.message}`;
+  });
+
+export function validateWorkflow(
+  input: string | unknown,
+  options?: ValidateWorkflowOptions,
+): WorkflowValidationResult {
+  let candidate: unknown = input;
+
+  if (typeof input === 'string') {
+    try {
+      candidate = parseYaml(input);
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : 'Unknown YAML parse error';
+
+      return {
+        success: false,
+        errors: ['Unable to parse workflow YAML', message],
+      };
+    }
+  }
+
+  const parsed = WorkflowDefinitionSchema.safeParse(candidate);
+
+  if (!parsed.success) {
+    return { success: false, errors: formatZodErrors(parsed.error.issues) };
+  }
+
+  const errors: string[] = [];
+  const taskDefinitions = extractTaskDefinitions(parsed.data.defs);
+  const referencedTasks = new Set(collectTaskReferences(parsed.data.flow));
+  const missingTasks = Array.from(referencedTasks).filter(
+    (task) => !Object.prototype.hasOwnProperty.call(taskDefinitions, task),
+  );
+
+  if (missingTasks.length > 0) {
+    errors.push(
+      `Unknown task(s) referenced in flow: ${missingTasks.join(', ')}`,
+    );
+  }
+
+  const bindingValidation = validateAndResolveBindings(parsed.data, {
+    bindingKinds: options?.bindingKinds,
+    actions: options?.actions,
+  });
+
+  if (bindingValidation.errors.length > 0) {
+    errors.push(...bindingValidation.errors);
+  }
+
+  if (errors.length > 0) {
+    return { success: false, errors };
+  }
+
+  return { success: true, data: parsed.data };
+}