@hexabot-ai/agentic 3.0.1-alpha.0

package/src/action/action.ts

@@ -0,0 +1,83 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z, ZodType } from 'zod';
+
+import { BaseWorkflowContext } from '../context';
+
+import { AbstractAction } from './abstract-action';
+import type {
+  Action,
+  ActionExecutionArgs,
+  ActionMetadata,
+  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 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> {
+  type ActionArgs = ActionExecutionArgs<I, Ctx, S, B>;
+
+  const defaultSettingsSchema = z.any() as ZodType<S>;
+  const defaultInputSchema = z.any() as ZodType<I>;
+  const defaultOutputSchema = z.any() as ZodType<O>;
+
+  class FnAction extends AbstractAction<I, O, Ctx, S, B> {
+    constructor() {
+      const metadata: ActionMetadata<I, O, S> = {
+        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: ActionArgs): Promise<O> {
+      return await Promise.resolve(params.execute(args));
+    }
+  }
+
+  return new FnAction();
+}

package/src/action/action.types.ts

@@ -0,0 +1,93 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+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 };

package/src/bindings/base-binding.ts

@@ -0,0 +1,508 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { z, type ZodIssue } from 'zod';
+
+const TASK_KIND = 'task';
+
+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;
+};
+
+const resolveValidationOptions = (
+  options?: BindingKindSchemas | ValidateAndResolveBindingsOptions,
+): ValidateAndResolveBindingsOptions => {
+  if (!options) {
+    return {};
+  }
+
+  if ('bindingKinds' in options || 'actions' in options) {
+    return options as ValidateAndResolveBindingsOptions;
+  }
+
+  return { bindingKinds: options as BindingKindSchemas };
+};
+const hasBindingsConfigured = (workflow: BindingAwareWorkflowLike): boolean => {
+  const defs = workflow.defs ?? {};
+  const hasNonTaskDefs = Object.values(defs).some(
+    (definition) => definition.kind !== TASK_KIND,
+  );
+  const hasNestedBindings = Object.values(defs).some(
+    (definition) =>
+      definition.bindings && Object.keys(definition.bindings).length > 0,
+  );
+
+  return hasNonTaskDefs || hasNestedBindings;
+};
+const formatZodIssues = (issues: ZodIssue[], prefix: string): string[] =>
+  issues.map((issue) => {
+    const path = issue.path.join('.') || '<root>';
+
+    return `${prefix}.${path}: ${issue.message}`;
+  });
+const collectDuplicateReferences = (refs: string[]): string[] => {
+  const seen = new Set<string>();
+  const duplicates = new Set<string>();
+
+  for (const ref of refs) {
+    if (seen.has(ref)) {
+      duplicates.add(ref);
+      continue;
+    }
+
+    seen.add(ref);
+  }
+
+  return Array.from(duplicates).sort();
+};
+const toBindingRefs = (refs: string | string[]): string[] =>
+  Array.isArray(refs) ? refs : [refs];
+const collectBindingRefs = (
+  bindings?: TaskBindingReferences,
+): Array<{ kind: string; ref: string }> => {
+  if (!bindings) {
+    return [];
+  }
+
+  const refs: Array<{ kind: string; ref: string }> = [];
+  for (const [bindingKind, bindingRefs] of Object.entries(bindings)) {
+    for (const ref of toBindingRefs(bindingRefs)) {
+      refs.push({ kind: bindingKind, ref });
+    }
+  }
+
+  return refs;
+};
+const detectBindingCycles = (defs: Record<string, DefLike>): string[] => {
+  const errors: string[] = [];
+  const reportedCycles = new Set<string>();
+  const states = new Map<string, 'visiting' | 'visited'>();
+  const stack: string[] = [];
+  const defNames = Object.keys(defs);
+  const visit = (defName: string) => {
+    const state = states.get(defName);
+    if (state === 'visited') {
+      return;
+    }
+
+    if (state === 'visiting') {
+      const cycleStart = stack.indexOf(defName);
+      if (cycleStart === -1) {
+        return;
+      }
+
+      const cyclePath = [...stack.slice(cycleStart), defName];
+      const cycleKey = cyclePath.join('->');
+
+      if (!reportedCycles.has(cycleKey)) {
+        reportedCycles.add(cycleKey);
+        errors.push(
+          `defs.${defName}.bindings: Circular binding reference detected (${cyclePath.join(' -> ')}).`,
+        );
+      }
+
+      return;
+    }
+
+    states.set(defName, 'visiting');
+    stack.push(defName);
+
+    const definition = defs[defName];
+    for (const { ref } of collectBindingRefs(definition?.bindings)) {
+      if (!Object.prototype.hasOwnProperty.call(defs, ref)) {
+        continue;
+      }
+
+      visit(ref);
+    }
+
+    stack.pop();
+    states.set(defName, 'visited');
+  };
+
+  for (const defName of defNames) {
+    visit(defName);
+  }
+
+  return errors;
+};
+const resolveSupportedBindingKinds = (
+  definition: DefLike,
+  defName: string,
+  kinds: BindingKindSchemas,
+  actions: Record<string, BindingValidationActionMetadata> | undefined,
+  errors: string[],
+): readonly string[] | null => {
+  if (definition.action) {
+    if (!actions) {
+      return null;
+    }
+
+    const action = actions[definition.action];
+    if (!action) {
+      errors.push(
+        `defs.${defName}.action: No action implementation provided for "${definition.action}".`,
+      );
+
+      return [];
+    }
+
+    return action.supportedBindings ?? [];
+  }
+
+  if (definition.kind === TASK_KIND) {
+    return [];
+  }
+
+  return kinds[definition.kind]?.supportedBindings ?? [];
+};
+
+export const validateAndResolveBindings = (
+  workflow: BindingAwareWorkflowLike,
+  options?: BindingKindSchemas | ValidateAndResolveBindingsOptions,
+): BindingValidationResult => {
+  const errors: string[] = [];
+  const resolvedDefs: ResolvedBindingDefs = {};
+  const defs = workflow.defs ?? {};
+  const resolvedOptions = resolveValidationOptions(options);
+  const kinds = resolvedOptions.bindingKinds ?? {};
+  const actions = resolvedOptions.actions;
+  const kindNames = Object.keys(kinds);
+  const hasBindingUsage = hasBindingsConfigured(workflow);
+  const parsedSettingsByDefName = new Map<string, unknown>();
+
+  if (hasBindingUsage && kindNames.length === 0) {
+    errors.push(
+      'Workflows that declare non-task defs or nested bindings require a non-empty "bindingKinds" registry.',
+    );
+  }
+
+  for (const [defName, defDefinition] of Object.entries(defs)) {
+    if (defDefinition.kind === TASK_KIND) {
+      if (defDefinition.action && actions && !actions[defDefinition.action]) {
+        errors.push(
+          `defs.${defName}.action: No action implementation provided for "${defDefinition.action}".`,
+        );
+      }
+      continue;
+    }
+
+    const kindDefinition = kinds[defDefinition.kind];
+
+    if (!kindDefinition) {
+      errors.push(
+        `defs.${defName}.kind: Unknown binding kind "${defDefinition.kind}".`,
+      );
+      continue;
+    }
+
+    const actionPolicy = kindDefinition.actionPolicy ?? 'optional';
+    if (actionPolicy === 'required' && !defDefinition.action) {
+      errors.push(
+        `defs.${defName}.action: Binding kind "${defDefinition.kind}" requires an action.`,
+      );
+    }
+    if (actionPolicy === 'forbidden' && defDefinition.action) {
+      errors.push(
+        `defs.${defName}.action: Binding kind "${defDefinition.kind}" does not allow action declarations.`,
+      );
+    }
+    if (defDefinition.action && actions && !actions[defDefinition.action]) {
+      errors.push(
+        `defs.${defName}.action: No action implementation provided for "${defDefinition.action}".`,
+      );
+    }
+
+    const { schema } = kindDefinition;
+    const parsedPayload = schema.safeParse(defDefinition.settings);
+
+    if (!parsedPayload.success) {
+      errors.push(
+        ...formatZodIssues(
+          parsedPayload.error.issues,
+          `defs.${defName}.settings`,
+        ),
+      );
+      continue;
+    }
+
+    parsedSettingsByDefName.set(defName, parsedPayload.data);
+  }
+
+  for (const [defName, defDefinition] of Object.entries(defs)) {
+    const defBindings = defDefinition.bindings;
+
+    if (!defBindings) {
+      continue;
+    }
+
+    const supportedKinds = resolveSupportedBindingKinds(
+      defDefinition,
+      defName,
+      kinds,
+      actions,
+      errors,
+    );
+    const shouldValidateSupportedKinds = Array.isArray(supportedKinds);
+
+    for (const [bindingKind, bindingRefs] of Object.entries(defBindings)) {
+      const kindDefinition = kinds[bindingKind];
+
+      if (!kindDefinition) {
+        errors.push(
+          `defs.${defName}.bindings.${bindingKind}: Unknown binding kind "${bindingKind}".`,
+        );
+        continue;
+      }
+
+      const { multiple } = kindDefinition;
+      if (multiple && !Array.isArray(bindingRefs)) {
+        errors.push(
+          `defs.${defName}.bindings.${bindingKind}: Expected an array of def references for binding kind "${bindingKind}".`,
+        );
+        continue;
+      }
+      if (!multiple && typeof bindingRefs !== 'string') {
+        errors.push(
+          `defs.${defName}.bindings.${bindingKind}: Expected a single def reference string for binding kind "${bindingKind}".`,
+        );
+        continue;
+      }
+
+      if (
+        shouldValidateSupportedKinds &&
+        supportedKinds &&
+        !supportedKinds.includes(bindingKind)
+      ) {
+        const supportedKindsLabel =
+          supportedKinds.length > 0 ? supportedKinds.join(', ') : '<none>';
+        errors.push(
+          `defs.${defName}.bindings.${bindingKind}: "${defDefinition.action ?? defDefinition.kind}" does not support binding kind "${bindingKind}". Supported binding kinds: ${supportedKindsLabel}.`,
+        );
+      }
+
+      const refs = toBindingRefs(bindingRefs);
+      const duplicateRefs = collectDuplicateReferences(refs);
+      if (duplicateRefs.length > 0) {
+        errors.push(
+          `defs.${defName}.bindings.${bindingKind}: Duplicate def reference(s): ${duplicateRefs.join(', ')}`,
+        );
+      }
+
+      for (const ref of refs) {
+        const definition = defs[ref];
+
+        if (!definition) {
+          errors.push(
+            `defs.${defName}.bindings.${bindingKind}: Unknown def reference "${ref}".`,
+          );
+          continue;
+        }
+
+        if (definition.kind !== bindingKind) {
+          errors.push(
+            `defs.${defName}.bindings.${bindingKind}: Def "${ref}" has kind "${definition.kind}" and cannot be mounted as "${bindingKind}".`,
+          );
+        }
+      }
+    }
+  }
+
+  errors.push(...detectBindingCycles(defs));
+
+  const inProgress = new Set<string>();
+  const mountResolvedDef = (
+    defName: string,
+  ): MountedBindingPayload | undefined => {
+    const existing = resolvedDefs[defName];
+    if (existing) {
+      return existing.payload;
+    }
+
+    const definition = defs[defName];
+    if (!definition || definition.kind === TASK_KIND) {
+      return undefined;
+    }
+
+    const parsedSettings = parsedSettingsByDefName.get(defName);
+    if (parsedSettings === undefined) {
+      return undefined;
+    }
+
+    if (inProgress.has(defName)) {
+      return undefined;
+    }
+
+    inProgress.add(defName);
+    const nestedBindings = mountTaskBindings(
+      definition.bindings,
+      resolvedDefs,
+      kinds,
+      mountResolvedDef,
+    );
+    const payload: MountedBindingPayload = {
+      settings: parsedSettings,
+      ...(definition.action ? { action: definition.action } : {}),
+      ...(Object.keys(nestedBindings).length > 0
+        ? { bindings: nestedBindings }
+        : {}),
+    };
+
+    resolvedDefs[defName] = {
+      kind: definition.kind,
+      payload,
+    };
+    inProgress.delete(defName);
+
+    return payload;
+  };
+
+  for (const [defName, definition] of Object.entries(defs)) {
+    if (definition.kind === TASK_KIND) {
+      continue;
+    }
+
+    mountResolvedDef(defName);
+  }
+
+  return { errors, resolvedDefs };
+};
+
+export const mountTaskBindings = (
+  taskBindings: TaskBindingReferences | undefined,
+  resolvedDefs: ResolvedBindingDefs,
+  bindingKinds?: BindingKindSchemas,
+  resolveDef?: (defName: string) => MountedBindingPayload | undefined,
+): CompiledTaskBindings => {
+  if (!taskBindings) {
+    return {};
+  }
+
+  const mounted: CompiledTaskBindings = {};
+  const kinds = bindingKinds ?? {};
+
+  for (const [bindingKind, bindingRefs] of Object.entries(taskBindings)) {
+    const refs = toBindingRefs(bindingRefs);
+    const isMultiple =
+      kinds[bindingKind]?.multiple ?? Array.isArray(bindingRefs);
+
+    if (!isMultiple) {
+      const ref = refs[0];
+
+      if (!ref) {
+        continue;
+      }
+
+      const resolvedDefPayload =
+        resolvedDefs[ref]?.payload ?? resolveDef?.(ref) ?? undefined;
+
+      if (!resolvedDefPayload) {
+        continue;
+      }
+
+      mounted[bindingKind] = resolvedDefPayload;
+      continue;
+    }
+
+    const mountedKindDefs: Record<string, MountedBindingPayload> = {};
+
+    for (const ref of refs) {
+      const resolvedDefPayload =
+        resolvedDefs[ref]?.payload ?? resolveDef?.(ref) ?? undefined;
+
+      if (!resolvedDefPayload) {
+        continue;
+      }
+
+      mountedKindDefs[ref] = resolvedDefPayload;
+    }
+
+    if (Object.keys(mountedKindDefs).length > 0) {
+      mounted[bindingKind] = mountedKindDefs;
+    }
+  }
+
+  return mounted;
+};