@hexabot-ai/api 3.2.2-alpha.9 → 3.2.2-beta.1

package/src/workflow/services/agentic.service.ts

@@ -11,7 +11,7 @@ import {
   StepExecutionRecord,
   WorkflowRunner,
 } from '@hexabot-ai/agentic';
-import { WorkflowRunFull, WorkflowFull } from '@hexabot-ai/types';
+import { WorkflowFull, WorkflowRunFull } from '@hexabot-ai/types';
 import { Injectable } from '@nestjs/common';
 
 import { ActionService } from '@/actions/actions.service';
@@ -20,16 +20,30 @@ import { I18nService } from '@/i18n/services/i18n.service';
 import { LoggerService } from '@/logger/logger.service';
 
 import { WorkflowContextFactory } from '../contexts/workflow-context-factory';
-import { WorkflowRuntimeContext } from '../contexts/workflow-runtime.context';
+import type { WorkflowRuntimeContext } from '../contexts/workflow-runtime.context';
 import { TriggerEventWrapper } from '../lib/trigger-event-wrapper';
 import { parseWorkflowDefinition } from '../lib/workflow-definition';
-import { RunStrategy, RunWorkflowOptions, WorkflowResult } from '../types';
+import type {
+  CallWorkflowOptions,
+  CallWorkflowResult,
+  RunStrategy,
+  RunWorkflowOptions,
+  WorkflowCallService,
+  WorkflowResult,
+} from '../types';
 
 import { WorkflowRunService } from './workflow-run.service';
 import { WorkflowService } from './workflow.service';
 
+const MAX_CALL_STACK_DEPTH = 10;
+
+type RunWorkflowExecution = {
+  run: WorkflowRunFull;
+  result: WorkflowResult;
+};
+
 @Injectable()
-export class AgenticService {
+export class AgenticService implements WorkflowCallService {
   constructor(
     private readonly workflowService: WorkflowService,
     private readonly workflowRunService: WorkflowRunService,
@@ -42,9 +56,11 @@ export class AgenticService {
 
   /**
    * Process an event by resuming a suspended workflow run if it exists,
-   * otherwise start a new run using the latest configured workflow (or the default fallback).
+   * otherwise start a new run using the latest configured workflow.
    */
-  async handleEvent(event: TriggerEventWrapper): Promise<void> {
+  async handleEvent(
+    event: TriggerEventWrapper,
+  ): Promise<WorkflowRunFull | null> {
     const initiator = event.getInitiator();
     const requestedWorkflowId = event.getWorkflowId();
     const threadId = event.getThreadId();
@@ -54,7 +70,7 @@ export class AgenticService {
         'Skipping workflow execution due to missing event initiator',
       );
 
-      return;
+      return null;
     }
 
     try {
@@ -72,9 +88,14 @@ export class AgenticService {
           suspendedStep: suspendedRun.suspendedStep,
           suspensionReason: suspendedRun.suspensionReason,
         });
-        await this.runWorkflow({ mode: 'resume', run: suspendedRun, event });
 
-        return;
+        const execution = await this.runWorkflow({
+          mode: 'resume',
+          run: suspendedRun,
+          event,
+        });
+
+        return execution.run;
       }
 
       const workflowToRun = requestedWorkflowId
@@ -85,46 +106,102 @@ export class AgenticService {
           requestedWorkflowId: requestedWorkflowId ?? null,
         });
 
-        return;
+        return null;
       }
       if (!workflowToRun.definition) {
         this.logger.warn('Workflow definition is missing', {
           workflowId: workflowToRun.id,
         });
 
-        return;
+        return null;
       }
 
       this.logger.log('Starting workflow run', {
         workflowId: workflowToRun.id,
       });
 
-      await this.runWorkflow({
+      const execution = await this.runWorkflow({
         mode: 'start',
         workflow: workflowToRun,
         event,
       });
+
+      return execution.run;
     } catch (err) {
       this.logger.error(
         'Unable to process incoming event through agentic workflow',
         err,
       );
+
+      return null;
+    }
+  }
+
+  /**
+   * Call another workflow from a running parent workflow.
+   *
+   * This is intentionally an API-level operation: workflows are database
+   * records, so type enforcement, call-stack validation, child run creation,
+   * and durable parent/child linkage all live here instead of in the agentic
+   * DSL runner.
+   */
+  async callWorkflow({
+    workflowId,
+    input,
+    parentContext,
+  }: CallWorkflowOptions): Promise<CallWorkflowResult> {
+    const parentRun = await this.workflowRunService.findOneAndPopulate(
+      parentContext.workflowRunId,
+    );
+    if (!parentRun) {
+      throw new Error(
+        `Unable to load parent workflow run ${parentContext.workflowRunId}`,
+      );
+    }
+
+    const workflow = await this.workflowService.findOneAndPopulate(workflowId);
+    if (!workflow) {
+      throw new Error(`Workflow with ID ${workflowId} not found`);
+    }
+    if (!workflow.definition) {
+      throw new Error(`Workflow ${workflowId} is missing a definition`);
+    }
+    if (workflow.type !== parentRun.workflow.type) {
+      throw new Error(
+        `Workflow ${workflowId} has type "${workflow.type}" and cannot be called from a "${parentRun.workflow.type}" workflow`,
+      );
     }
+
+    await this.assertCanCallWorkflow(parentRun, workflow.id);
+
+    const execution = await this.runWorkflow({
+      mode: 'start',
+      workflow,
+      event: parentContext.event,
+      parentRun,
+      input,
+    });
+
+    return this.toCallWorkflowResult(execution.run, execution.result);
   }
 
   /**
-   * Shared runner lifecycle for starting or resuming a workflow.
+   * Shared runner lifecycle for starts, external resumes, and internal parent
+   * resumes. When a resumed child reaches a terminal state, this method also
+   * unwinds the suspended parent with the child result payload.
    */
-  private async runWorkflow(options: RunWorkflowOptions): Promise<void> {
+  private async runWorkflow(
+    options: RunWorkflowOptions,
+  ): Promise<RunWorkflowExecution> {
     const { event, mode } = options;
     const run =
       mode === 'start'
-        ? await this.createRun(options.workflow, event)
+        ? await this.createRun(options.workflow, event, {
+            parentRun: options.parentRun,
+            input: options.input,
+          })
         : options.run;
-    const workflow = await this.workflowService.findOneAndPopulate(
-      run.workflow.id,
-    );
-    const definition = this.resolveRunDefinition(run, workflow);
+    const definition = this.resolveRunDefinition(run);
     if (!definition) {
       throw new Error('Workflow definition is required to run the workflow');
     }
@@ -142,7 +219,7 @@ export class AgenticService {
     this.logger.debug('Preparing workflow runner', {
       mode,
       runId: run.id,
-      workflowId: workflow?.id,
+      workflowId: run.workflow?.id,
       triggeredById: run.triggeredBy?.id,
     });
 
@@ -151,6 +228,7 @@ export class AgenticService {
       run,
       context,
       workflowInstance,
+      mode === 'resume' ? options.resumeData : undefined,
     );
 
     this.logger.debug('Marking workflow run as running', {
@@ -180,6 +258,17 @@ export class AgenticService {
     } catch (err) {
       this.logger.error('Workflow runner threw during execution', err);
       await this.markRunFailed(run, strategy.runner, context.state, err);
+      if (mode === 'resume') {
+        await this.resumeParentRunFromChild(
+          run,
+          {
+            status: 'failed',
+            error: err,
+            snapshot: strategy.runner.getSnapshot(),
+          },
+          event,
+        );
+      }
 
       throw err;
     }
@@ -198,6 +287,16 @@ export class AgenticService {
       strategy.resumeData,
       context,
     );
+
+    if (mode === 'resume') {
+      await this.resumeParentRunFromChild(run, result, event);
+    }
+
+    const persistedRun = await this.workflowRunService.findOneAndPopulate(
+      run.id,
+    );
+
+    return { run: persistedRun ?? run, result };
   }
 
   /**
@@ -220,12 +319,16 @@ export class AgenticService {
 
   /**
    * Build the execution strategy for starting a new workflow or resuming an existing one.
+   *
+   * `resumeData` is supplied only for internal child-to-parent unwinds; normal
+   * event resumes use the current event input.
    */
   private async createRunStrategy(
     mode: 'start' | 'resume',
     run: WorkflowRunFull,
     context: WorkflowRuntimeContext,
     workflowInstance: AgenticWorkflow,
+    resumeData?: unknown,
   ): Promise<RunStrategy> {
     if (mode === 'start') {
       const runner = await workflowInstance.buildAsyncRunner({
@@ -245,7 +348,7 @@ export class AgenticService {
       };
     }
 
-    const latestInput = context.event.buildInput();
+    const latestInput = resumeData ?? context.event.buildInput();
     const runner = await workflowInstance.buildRunnerFromState({
       state: this.buildExecutionState(run),
       context,
@@ -278,10 +381,18 @@ export class AgenticService {
 
   /**
    * Create a workflow run record and load it with relations.
+   *
+   * Child calls inherit the same event metadata, initiator, and thread as the
+   * parent, but store an explicit `parentRun` relation so future events can
+   * resume the deepest suspended child before returning to the parent.
    */
   private async createRun(
     workflow: WorkflowFull,
     event: TriggerEventWrapper,
+    options: {
+      parentRun?: WorkflowRunFull;
+      input?: Record<string, unknown>;
+    } = {},
   ): Promise<WorkflowRunFull> {
     const initiator = event.getInitiator();
     if (!workflow.definition) {
@@ -296,7 +407,8 @@ export class AgenticService {
       workflowVersion: workflow.currentVersion?.id ?? null,
       triggeredBy: initiator.id,
       thread: event.getThreadId() ?? null,
-      input: event.buildInput(),
+      parentRun: options.parentRun?.id ?? null,
+      input: options.input ?? event.buildInput(),
       context: Object.keys(initialContext).length > 0 ? initialContext : null,
       metadata: event.getMetadata(),
     });
@@ -310,18 +422,147 @@ export class AgenticService {
   }
 
   /**
-   * Resolve the workflow definition used by the current run.
+   * Validate that a workflow call does not create a recursive or overly deep stack.
+   *
+   * The walk follows active parent links, so only the current call stack is
+   * rejected; a workflow can still be called again after an earlier stack has
+   * completed.
+   */
+  private async assertCanCallWorkflow(
+    parentRun: WorkflowRunFull,
+    targetWorkflowId: string,
+  ): Promise<void> {
+    let current: WorkflowRunFull | null = parentRun;
+    let depth = 0;
+
+    while (current) {
+      depth += 1;
+      if (depth >= MAX_CALL_STACK_DEPTH) {
+        throw new Error(
+          `Workflow call stack depth cannot exceed ${MAX_CALL_STACK_DEPTH}`,
+        );
+      }
+
+      if (current.workflow.id === targetWorkflowId) {
+        throw new Error(
+          `Workflow call cycle detected for workflow ${targetWorkflowId}`,
+        );
+      }
+
+      const parentRunId = this.resolveRunId(current.parentRun);
+      current = parentRunId
+        ? await this.workflowRunService.findOneAndPopulate(parentRunId)
+        : null;
+    }
+  }
+
+  /**
+   * Convert a child run terminal/suspended result into the `call_workflow`
+   * contract. The same payload shape is used for immediate returns and for
+   * resuming a parent after the child completed in a later event.
    */
-  private resolveRunDefinition(
+  private toCallWorkflowResult(
     run: WorkflowRunFull,
-    workflow?: WorkflowFull | null,
-  ) {
+    result: WorkflowResult,
+  ): CallWorkflowResult {
+    if (result.status === 'finished') {
+      return {
+        status: 'finished',
+        workflow_id: run.workflow.id,
+        workflow_run_id: run.id,
+        output: result.output,
+      };
+    }
+
+    if (result.status === 'suspended') {
+      return {
+        status: 'suspended',
+        workflow_id: run.workflow.id,
+        workflow_run_id: run.id,
+      };
+    }
+
+    return {
+      status: 'failed',
+      workflow_id: run.workflow.id,
+      workflow_run_id: run.id,
+      error: this.stringifyError(result.error),
+    };
+  }
+
+  /**
+   * Resume a suspended parent run after its child run completes or fails.
+   *
+   * This may cascade through multiple ancestors because resuming the parent can
+   * itself finish a child call that belongs to another suspended parent.
+   */
+  private async resumeParentRunFromChild(
+    childRun: WorkflowRunFull,
+    result: WorkflowResult,
+    event: TriggerEventWrapper,
+  ): Promise<void> {
+    if (result.status === 'suspended') {
+      return;
+    }
+
+    const parentRunId = this.resolveRunId(childRun.parentRun);
+    if (!parentRunId) {
+      return;
+    }
+
+    const parentRun =
+      await this.workflowRunService.findOneAndPopulate(parentRunId);
+    if (!parentRun) {
+      this.logger.warn('Unable to resume missing parent workflow run', {
+        childRunId: childRun.id,
+        parentRunId,
+      });
+
+      return;
+    }
+
+    if (parentRun.status !== 'suspended') {
+      this.logger.warn(
+        'Skipping parent workflow resume because it is not suspended',
+        {
+          childRunId: childRun.id,
+          parentRunId,
+          parentStatus: parentRun.status,
+        },
+      );
+
+      return;
+    }
+
+    await this.runWorkflow({
+      mode: 'resume',
+      run: parentRun,
+      event,
+      resumeData: this.toCallWorkflowResult(childRun, result),
+    });
+  }
+
+  /**
+   * Resolve a workflow run relation from either a populated object or id.
+   */
+  private resolveRunId(
+    run: string | { id?: string | null } | null | undefined,
+  ): string | null {
+    if (typeof run === 'string') {
+      return run;
+    }
+
+    return run?.id ?? null;
+  }
+
+  /**
+   * Resolve the workflow definition snapshot used by the current run.
+   */
+  private resolveRunDefinition(run: WorkflowRunFull) {
     const definitionYml = run.workflowVersion?.definitionYml;
     if (typeof definitionYml === 'string' && definitionYml.trim() !== '') {
       return parseWorkflowDefinition(definitionYml);
     }
-
-    return workflow?.definition;
   }
 
   /**
@@ -460,7 +701,7 @@ export class AgenticService {
   private pickOutput(
     result: WorkflowResult,
     state: ExecutionState | undefined,
-    fallback?: Record<string, unknown> | null,
+    previousOutput?: Record<string, unknown> | null,
   ): Record<string, unknown> | null {
     if (result.status === 'finished' && result.output) {
       return result.output;
@@ -470,7 +711,7 @@ export class AgenticService {
       return state.output;
     }
 
-    return fallback ?? null;
+    return previousOutput ?? null;
   }
 
   /**

package/src/workflow/services/workflow-run.service.ts

@@ -4,9 +4,10 @@
  * Full terms: see LICENSE.md.
  */
 
-import { WorkflowSnapshot } from '@hexabot-ai/agentic';
+import { EWorkflowRunStatus, WorkflowSnapshot } from '@hexabot-ai/agentic';
 import { WorkflowRun, WorkflowRunFull } from '@hexabot-ai/types';
 import { Injectable } from '@nestjs/common';
+import { In } from 'typeorm';
 
 import { BaseOrmService } from '@/utils/generics/base-orm.service';
 
@@ -18,6 +19,12 @@ type StateUpdate = {
   context?: Record<string, unknown> | null;
 };
 
+const ACTIVE_WORKFLOW_RUN_STATUSES = [
+  EWorkflowRunStatus.IDLE,
+  EWorkflowRunStatus.RUNNING,
+  EWorkflowRunStatus.SUSPENDED,
+];
+
 @Injectable()
 export class WorkflowRunService extends BaseOrmService<WorkflowRunOrmEntity> {
   /**
@@ -130,25 +137,131 @@ export class WorkflowRunService extends BaseOrmService<WorkflowRunOrmEntity> {
   }
 
   /**
-   * Find the latest suspended run for a triggering subscriber.
+   * Find the suspended run that should receive the next event.
+   *
+   * For call-and-return stacks, the parent can be suspended while the child is
+   * either running or suspended for the same initiator/thread. The next external
+   * event must resume the deepest suspended leaf first; once that child
+   * completes, AgenticService resumes its parent internally with the child
+   * result.
    *
    * @param triggeredById - Identifier of the subscriber whose suspended run should be fetched.
-   * @param workflowId - Optional workflow identifier to scope the suspended run lookup.
-   * @returns The most recently suspended run populated with relations, or `null` when none exists.
+   * @param threadId - Optional thread id for conversational continuity.
+   * @param workflowId - Optional workflow id; a parent match still resolves to its child leaf.
+   * @returns The suspended leaf run populated with relations, or `null` when none exists.
    */
   async findSuspendedRunByInitiator(
     triggeredById: string,
     threadId?: string,
     workflowId?: string,
   ): Promise<WorkflowRunFull | null> {
-    return await this.findOneAndPopulate({
+    const runs = await this.findAndPopulate({
       where: {
         triggeredBy: { id: triggeredById },
         ...(threadId ? { thread: { id: threadId } } : {}),
-        status: 'suspended',
-        ...(workflowId ? { workflow: { id: workflowId } } : {}),
+        status: In(ACTIVE_WORKFLOW_RUN_STATUSES),
       },
       order: { suspendedAt: 'DESC', createdAt: 'DESC' },
     });
+
+    if (runs.length === 0) {
+      return null;
+    }
+
+    const runsById = new Map(runs.map((run) => [run.id, run]));
+    const parentRunIds = new Set(
+      runs
+        .map((run) => this.resolveRunId(run.parentRun))
+        .filter((value): value is string => typeof value === 'string'),
+    );
+    // Leaves are active runs that are not the parent of another unfinished
+    // candidate. Only suspended leaves can consume external events; running or
+    // idle leaves are still in flight and block their suspended ancestors.
+    const leaves = runs.filter((run) => !parentRunIds.has(run.id));
+    const candidates = (leaves.length > 0 ? leaves : runs)
+      .filter((run) => run.status === EWorkflowRunStatus.SUSPENDED)
+      .filter((run) =>
+        workflowId
+          ? this.isRunInWorkflowStack(run, workflowId, runsById)
+          : true,
+      );
+
+    return this.pickDeepestSuspendedRun(candidates, runsById);
+  }
+
+  private resolveRunId(
+    run: string | { id?: string | null } | null | undefined,
+  ): string | null {
+    if (typeof run === 'string') {
+      return run;
+    }
+
+    return run?.id ?? null;
+  }
+
+  private isRunInWorkflowStack(
+    run: WorkflowRunFull,
+    workflowId: string,
+    runsById: Map<string, WorkflowRunFull>,
+  ): boolean {
+    let current: WorkflowRunFull | undefined = run;
+    const visited = new Set<string>();
+
+    while (current && !visited.has(current.id)) {
+      visited.add(current.id);
+      if (current.workflow.id === workflowId) {
+        return true;
+      }
+      const parentRunId = this.resolveRunId(current.parentRun);
+      current = parentRunId ? runsById.get(parentRunId) : undefined;
+    }
+
+    return false;
+  }
+
+  private pickDeepestSuspendedRun(
+    runs: WorkflowRunFull[],
+    runsById: Map<string, WorkflowRunFull>,
+  ): WorkflowRunFull | null {
+    if (runs.length === 0) {
+      return null;
+    }
+
+    const getDepth = (run: WorkflowRunFull): number => {
+      let depth = 0;
+      let current: WorkflowRunFull | undefined = run;
+      const visited = new Set<string>();
+
+      while (current && !visited.has(current.id)) {
+        visited.add(current.id);
+        depth += 1;
+        const parentRunId = this.resolveRunId(current.parentRun);
+        current = parentRunId ? runsById.get(parentRunId) : undefined;
+      }
+
+      return depth;
+    };
+    const getTime = (value?: Date | string | null): number => {
+      if (!value) {
+        return 0;
+      }
+
+      const date = value instanceof Date ? value : new Date(value);
+      const timestamp = date.getTime();
+
+      return Number.isNaN(timestamp) ? 0 : timestamp;
+    };
+
+    return [...runs].sort((a, b) => {
+      const depthDiff = getDepth(b) - getDepth(a);
+      if (depthDiff !== 0) {
+        return depthDiff;
+      }
+
+      return (
+        getTime(b.suspendedAt) - getTime(a.suspendedAt) ||
+        getTime(b.createdAt) - getTime(a.createdAt)
+      );
+    })[0];
   }
 }

package/src/workflow/services/workflow-version.service.ts

@@ -6,6 +6,7 @@
 
 import { WorkflowVersion } from '@hexabot-ai/types';
 import { Injectable, NotFoundException } from '@nestjs/common';
+import { EntityManager } from 'typeorm';
 
 import { BaseOrmService } from '@/utils/generics/base-orm.service';
 
@@ -63,6 +64,38 @@ export class WorkflowVersionService extends BaseOrmService<WorkflowVersionOrmEnt
     });
   }
 
+  /**
+   * Persist a workflow version snapshot with the provided transaction manager.
+   *
+   * This method mirrors createSnapshot's version-number behavior without
+   * escaping the caller's transaction or emitting repository-level events.
+   */
+  public async createSnapshotWithManager(
+    manager: EntityManager,
+    params: WorkflowNewVersionDto,
+  ): Promise<WorkflowVersionOrmEntity> {
+    const latestVersion = await manager.findOne(WorkflowVersionOrmEntity, {
+      where: { workflow: { id: params.workflow } },
+      order: { version: 'DESC' },
+    });
+    const nextVersion = latestVersion ? latestVersion.version + 1 : 1;
+
+    return await manager.save(
+      WorkflowVersionOrmEntity,
+      manager.create(WorkflowVersionOrmEntity, {
+        workflow: { id: params.workflow },
+        version: nextVersion,
+        definitionYml: params.definitionYml,
+        action: params.action,
+        message: params.message,
+        parentVersion: params.parentVersion
+          ? { id: params.parentVersion }
+          : null,
+        createdBy: params.createdBy ? { id: params.createdBy } : null,
+      }),
+    );
+  }
+
   /**
    * Restore a workflow to a prior version by creating a new snapshot.
    *