@hexabot-ai/api 3.2.2-alpha.8 → 3.2.2-beta.0

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

@@ -4,7 +4,7 @@
  * Full terms: see LICENSE.md.
  */
 
-import { WorkflowEventMap } from '@hexabot-ai/agentic';
+import type { WorkflowEventMap } from '@hexabot-ai/agentic';
 import { WorkflowFull, Workflow } from '@hexabot-ai/types';
 import {
   BadRequestException,
@@ -12,11 +12,12 @@ import {
   InternalServerErrorException,
 } from '@nestjs/common';
 import { HookEventKey, OnEvent } from '@nestjs/event-emitter';
-import { FindOneOptions } from 'typeorm';
+import { EntityManager, FindOneOptions } from 'typeorm';
 import { z, ZodType } from 'zod';
 
 import { UpdateOneOptions } from '@/utils/generics/base-orm.repository';
 import { BaseOrmService } from '@/utils/generics/base-orm.service';
+import { InferCreateDto } from '@/utils/types/dto.types';
 import {
   Room,
   SocketGet,
@@ -68,6 +69,25 @@ export class WorkflowService extends BaseOrmService<WorkflowOrmEntity> {
     return latest ?? null;
   }
 
+  /**
+   * Persist a workflow using the provided transaction manager.
+   *
+   * This method intentionally does not emit BaseOrmRepository mutation events;
+   * callers that own a larger transaction must emit app-level events after
+   * commit.
+   */
+  async createWithManager(
+    manager: EntityManager,
+    payload: InferCreateDto<WorkflowOrmEntity>,
+  ): Promise<WorkflowOrmEntity> {
+    const entity = manager.create(
+      WorkflowOrmEntity,
+      this.repository.actionDtoToEntity(payload),
+    );
+
+    return await manager.save(WorkflowOrmEntity, entity);
+  }
+
   /**
    * Update a workflow while enforcing immutability of its trigger type.
    */
@@ -188,57 +208,92 @@ export class WorkflowService extends BaseOrmService<WorkflowOrmEntity> {
 
       return;
     }
-    const { initiatorId, workflowId, threadId } = workflowRun?.context;
+    const { initiatorId, workflowId, threadId } = workflowRun.context;
+    if (
+      typeof initiatorId !== 'string' ||
+      !initiatorId ||
+      typeof workflowId !== 'string' ||
+      !workflowId
+    ) {
+      this.logger.error(
+        'workflowRun context requires initiatorId and workflowId',
+      );
+
+      return;
+    }
+
     const workflow = await this.findOne(workflowId);
-    const canBroadcastEvents =
-      initiatorId &&
-      workflow?.type &&
-      [WorkflowType.conversational].includes(workflow.type);
-
-    if (canBroadcastEvents) {
-      this.gateway.broadcastWorkflowEvent({
-        ...payload,
-        t,
-        workflowId,
-        initiatorId,
-        threadId: typeof threadId === 'string' ? threadId : undefined,
-        workflowEvent: workflowEvent.replace('hook:', ''),
-      });
+    if (!workflow?.type) {
+      this.logger.error('workflow is required');
+
+      return;
     }
+
+    this.gateway.broadcastWorkflowEvent({
+      ...payload,
+      t,
+      workflowRun,
+      workflowId,
+      initiatorId,
+      threadId: typeof threadId === 'string' ? threadId : undefined,
+      workflowEvent: workflowEvent.replace('hook:', ''),
+    });
   }
 
   @OnEvent('hook:workflow:start')
-  sendWorkflowStart(payload: WorkflowEventMap[keyof WorkflowEventMap]) {
-    this.sendWorkflowEvent('hook:workflow:start', payload);
+  async sendWorkflowStart(payload: WorkflowEventMap[keyof WorkflowEventMap]) {
+    await this.sendWorkflowEvent('hook:workflow:start', payload);
   }
 
   @OnEvent('hook:workflow:finish')
-  sendWorkflowFinish(payload: WorkflowEventMap[keyof WorkflowEventMap]) {
-    this.sendWorkflowEvent('hook:workflow:finish', payload);
+  async sendWorkflowFinish(payload: WorkflowEventMap[keyof WorkflowEventMap]) {
+    await this.sendWorkflowEvent('hook:workflow:finish', payload);
+  }
+
+  @OnEvent('hook:workflow:suspended')
+  async sendWorkflowSuspended(
+    payload: WorkflowEventMap[keyof WorkflowEventMap],
+  ) {
+    await this.sendWorkflowEvent('hook:workflow:suspended', payload);
   }
 
   @OnEvent('hook:workflow:failure')
-  sendWorkflowFailure(payload: WorkflowEventMap[keyof WorkflowEventMap]) {
-    this.sendWorkflowEvent('hook:workflow:failure', payload);
+  async sendWorkflowFailure(payload: WorkflowEventMap[keyof WorkflowEventMap]) {
+    await this.sendWorkflowEvent('hook:workflow:failure', payload);
   }
 
   @OnEvent('hook:step:start')
-  sendWorkflowStepStart(payload: WorkflowEventMap[keyof WorkflowEventMap]) {
-    this.sendWorkflowEvent('hook:step:start', payload);
+  async sendWorkflowStepStart(
+    payload: WorkflowEventMap[keyof WorkflowEventMap],
+  ) {
+    await this.sendWorkflowEvent('hook:step:start', payload);
   }
 
   @OnEvent('hook:step:suspended')
-  sendWorkflowStepSuspended(payload: WorkflowEventMap[keyof WorkflowEventMap]) {
-    this.sendWorkflowEvent('hook:step:suspended', payload);
+  async sendWorkflowStepSuspended(
+    payload: WorkflowEventMap[keyof WorkflowEventMap],
+  ) {
+    await this.sendWorkflowEvent('hook:step:suspended', payload);
   }
 
   @OnEvent('hook:step:success')
-  sendWorkflowStepSuccess(payload: WorkflowEventMap[keyof WorkflowEventMap]) {
-    this.sendWorkflowEvent('hook:step:success', payload);
+  async sendWorkflowStepSuccess(
+    payload: WorkflowEventMap[keyof WorkflowEventMap],
+  ) {
+    await this.sendWorkflowEvent('hook:step:success', payload);
   }
 
   @OnEvent('hook:step:error')
-  sendWorkflowStepError(payload: WorkflowEventMap[keyof WorkflowEventMap]) {
-    this.sendWorkflowEvent('hook:step:error', payload);
+  async sendWorkflowStepError(
+    payload: WorkflowEventMap[keyof WorkflowEventMap],
+  ) {
+    await this.sendWorkflowEvent('hook:step:error', payload);
+  }
+
+  @OnEvent('hook:step:cancelled')
+  async sendWorkflowStepCancelled(
+    payload: WorkflowEventMap[keyof WorkflowEventMap],
+  ) {
+    await this.sendWorkflowEvent('hook:step:cancelled', payload);
   }
 }

package/src/workflow/types.ts

@@ -21,6 +21,7 @@ import {
   WorkflowFull,
 } from '@hexabot-ai/types';
 
+import type { WorkflowRuntimeContext } from './contexts/workflow-runtime.context';
 import { TriggerEventWrapper } from './lib/trigger-event-wrapper';
 import { SchemaInstance } from './utils/schema-instance';
 
@@ -36,16 +37,67 @@ export type MemoryValue = Record<string, unknown>;
 
 export type WorkflowResult = WorkflowStartResult | WorkflowResumeResult;
 
+/**
+ * Payload passed from a child workflow back to the suspended `call_workflow`
+ * action in its parent. Only `finished` is exposed as the action output; the
+ * action converts `failed` into a thrown error and treats `suspended` as a
+ * durable wait state.
+ */
+export type CallWorkflowFinishedResult = {
+  status: 'finished';
+  workflow_id: string;
+  workflow_run_id: string;
+  output: Record<string, unknown>;
+};
+
+export type CallWorkflowSuspendedResult = {
+  status: 'suspended';
+  workflow_id: string;
+  workflow_run_id: string;
+};
+
+export type CallWorkflowFailedResult = {
+  status: 'failed';
+  workflow_id: string;
+  workflow_run_id: string;
+  error: string;
+};
+
+export type CallWorkflowResult =
+  | CallWorkflowFinishedResult
+  | CallWorkflowSuspendedResult
+  | CallWorkflowFailedResult;
+
+export type CallWorkflowOptions = {
+  workflowId: string;
+  /** Optional child start input. When omitted, the parent event input is reused. */
+  input?: Record<string, unknown>;
+  /** Runtime context of the parent action that is issuing the workflow call. */
+  parentContext: WorkflowRuntimeContext;
+};
+
+export interface WorkflowCallService {
+  callWorkflow(options: CallWorkflowOptions): Promise<CallWorkflowResult>;
+}
+
+export const WORKFLOW_CALL_SERVICE = Symbol('WORKFLOW_CALL_SERVICE');
+
 export type RunWorkflowOptions =
   | {
       mode: 'start';
       workflow: WorkflowFull;
       event: TriggerEventWrapper;
+      /** Present when this run is a child workflow call. */
+      parentRun?: WorkflowRunFull;
+      /** Start input override for child calls. */
+      input?: Record<string, unknown>;
     }
   | {
       mode: 'resume';
       run: WorkflowRunFull;
       event: TriggerEventWrapper;
+      /** Internal resume payload used to unwind a completed child into its parent. */
+      resumeData?: unknown;
     };
 
 export type MarkRunningInput = {

package/src/workflow/workflow.module.ts

@@ -46,6 +46,7 @@ import { WorkflowRunService } from './services/workflow-run.service';
 import { WorkflowSchedulerService } from './services/workflow-scheduler.service';
 import { WorkflowVersionService } from './services/workflow-version.service';
 import { WorkflowService } from './services/workflow.service';
+import { WORKFLOW_CALL_SERVICE } from './types';
 
 @Module({
   imports: [
@@ -93,6 +94,7 @@ import { WorkflowService } from './services/workflow.service';
     ScheduledWorkflowContext,
     WorkflowContextFactory,
     AgenticService,
+    { provide: WORKFLOW_CALL_SERVICE, useExisting: AgenticService },
   ],
   exports: [
     WorkflowRepository,
@@ -111,6 +113,7 @@ import { WorkflowService } from './services/workflow.service';
     McpClientPoolService,
     ConversationalWorkflowContext,
     AgenticService,
+    WORKFLOW_CALL_SERVICE,
   ],
 })
 export class WorkflowModule {}

package/types/event-emitter.d.ts

@@ -4,7 +4,7 @@
  * Full terms: see LICENSE.md.
  */
 
-import type { StepInfo } from '@hexabot-ai/agentic';
+import type { StepExecutionRecord, StepInfo } from '@hexabot-ai/agentic';
 import type { HttpException } from '@nestjs/common';
 import type { OnEventType } from '@nestjs/event-emitter';
 import type { OnEventOptions } from '@nestjs/event-emitter/dist/interfaces';
@@ -135,6 +135,12 @@ type HookEventPayload<
 
 type HookWildcardPayload<Entity> = [OrmLifecycleEvent<Entity>];
 
+type StepWorkflowEventPayload = {
+  runId?: string;
+  step: StepInfo;
+  stepExecution?: StepExecutionRecord;
+};
+
 declare module '@nestjs/event-emitter' {
   interface IHookSettingsGroupLabelOperationMap
     extends DefaultHookSettingsMap {}
@@ -239,11 +245,12 @@ declare module '@nestjs/event-emitter' {
     '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:start': [StepWorkflowEventPayload];
+    'hook:step:success': [StepWorkflowEventPayload];
+    'hook:step:error': [StepWorkflowEventPayload & { error: unknown }];
+    'hook:step:cancelled': [StepWorkflowEventPayload & { error: unknown }];
     'hook:step:suspended': [
-      { runId?: string; step: StepInfo; reason?: string; data?: unknown },
+      StepWorkflowEventPayload & { reason?: string; data?: unknown },
     ];
     'hook:step:skipped': [{ runId?: string; step: StepInfo; reason?: string }];
   }