@hexabot-ai/api 3.2.2-alpha.1 → 3.2.2-alpha.11

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-scheduler.service.ts

@@ -13,7 +13,7 @@ import { RemoveEvent } from 'typeorm';
 import { AppInstance } from '@/app.instance';
 import { config } from '@/config';
 import { LoggerService } from '@/logger/logger.service';
-import { UserService } from '@/user';
+import { UserService } from '@/user/services/user.service';
 import {
   InsertEntityEvent,
   UpdateEntityEvent,

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.
    *

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

@@ -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.
    */

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/utils/memory-store.ts

@@ -9,6 +9,7 @@ import { ZodSchema, z } from 'zod';
 
 import { cloneObject } from '@/utils/helpers/clone';
 import { deepFreeze } from '@/utils/helpers/freeze';
+import { deepMerge } from '@/utils/helpers/object';
 
 import { WorkflowRuntimeContext } from '../contexts/workflow-runtime.context';
 import {
@@ -377,9 +378,20 @@ export class MemoryStore {
 
     const updates = await Promise.all(
       entries.map(async ([slug, value]) => {
+        const currentValue = this.raw[slug];
+        const canMerge =
+          currentValue !== null &&
+          value !== null &&
+          typeof currentValue === 'object' &&
+          typeof value === 'object' &&
+          !Array.isArray(currentValue) &&
+          !Array.isArray(value);
+        const nextValue = canMerge
+          ? deepMerge(cloneObject(currentValue), value)
+          : value;
         const parsedValue = await this.updateStoreEntry(
           slug,
-          value,
+          nextValue,
           persistRecord,
         );
 

package/src/workflow/workflow.module.ts

@@ -10,8 +10,8 @@ import { TypeOrmModule } from '@nestjs/typeorm';
 
 import { ChatModule } from '@/chat/chat.module';
 import { ThreadOrmEntity } from '@/chat/entities/thread.entity';
-import { CmsModule } from '@/cms';
-import { UserModule } from '@/user';
+import { CmsModule } from '@/cms/cms.module';
+import { UserModule } from '@/user/user.module';
 
 import { ConversationalWorkflowContext } from './contexts/conversational-workflow.context';
 import { ManualWorkflowContext } from './contexts/manual-workflow.context';
@@ -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/dist/mailer/mjml-adapter.class.d.ts

@@ -1,4 +0,0 @@
-import { TemplateAdapter } from '@nestjs-modules/mailer';
-export declare class MjmlAdapter implements TemplateAdapter {
-    compile: TemplateAdapter['compile'];
-}

package/dist/mailer/mjml-adapter.class.js

@@ -1,67 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MjmlAdapter = void 0;
-const fs = __importStar(require("fs"));
-const path_1 = __importDefault(require("path"));
-const common_1 = require("@nestjs/common");
-const handlebars_1 = __importDefault(require("handlebars"));
-class MjmlAdapter {
-    constructor() {
-        this.compile = async (mail, callback, options) => {
-            try {
-                const templatePath = path_1.default.join(options.template?.dir || '', mail.data.template || '');
-                const content = fs.readFileSync(templatePath, 'utf-8');
-                const delegate = handlebars_1.default.compile(content);
-                const compiledHandlebars = delegate(mail.data.context);
-                const mjml2html = await Promise.resolve().then(() => __importStar(require('mjml')));
-                const { errors, html } = await mjml2html.default(compiledHandlebars);
-                if (errors.length) {
-                    throw 'Unable to compiling mjml';
-                }
-                mail.data.html = html;
-                callback();
-            }
-            catch (err) {
-                common_1.Logger.error('@nestjs-modules/mailer: Unable to compiling mjml', err);
-            }
-        };
-    }
-}
-exports.MjmlAdapter = MjmlAdapter;
-//# sourceMappingURL=mjml-adapter.class.js.map

package/dist/mailer/mjml-adapter.class.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"mjml-adapter.class.js","sourceRoot":"","sources":["../../src/mailer/mjml-adapter.class.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMA,uCAAyB;AACzB,gDAAwB;AAExB,2CAAwC;AAExC,4DAAoC;AAEpC,MAAa,WAAW;IAAxB;QACE,YAAO,GAA+B,KAAK,EACzC,IAAgC,EAChC,QAAQ,EACR,OAAO,EACP,EAAE;YACF,IAAI,CAAC;gBACH,MAAM,YAAY,GAAG,cAAI,CAAC,IAAI,CAC5B,OAAO,CAAC,QAAQ,EAAE,GAAG,IAAI,EAAE,EAC3B,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CACzB,CAAC;gBACF,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;gBACvD,MAAM,QAAQ,GAAG,oBAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;gBAC7C,MAAM,kBAAkB,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACvD,MAAM,SAAS,GAAG,wDAAa,MAAM,GAAC,CAAC;gBACvC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;gBAErE,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;oBAClB,MAAM,0BAA0B,CAAC;gBACnC,CAAC;gBACD,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;gBAEtB,QAAQ,EAAE,CAAC;YACb,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,eAAM,CAAC,KAAK,CAAC,kDAAkD,EAAE,GAAG,CAAC,CAAC;YACxE,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;CAAA;AA3BD,kCA2BC"}

package/dist/utils/types/extension.d.ts

@@ -1,4 +0,0 @@
-import { ChannelName } from '@/channel/types';
-import { HelperName } from '@/helper/types';
-export type ExtensionName = ChannelName | HelperName;
-export type HyphenToUnderscore<S extends string> = S extends `${infer P}-${infer Q}` ? `${P}_${HyphenToUnderscore<Q>}` : S;

package/dist/utils/types/extension.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"extension.js","sourceRoot":"","sources":["../../../src/utils/types/extension.ts"],"names":[],"mappings":""}

package/src/mailer/mjml-adapter.class.ts

@@ -1,41 +0,0 @@
-/*
- * Hexabot — Fair Core License (FCL-1.0-ALv2)
- * Copyright (c) 2025 Hexastack.
- * Full terms: see LICENSE.md.
- */
-
-import * as fs from 'fs';
-import path from 'path';
-
-import { Logger } from '@nestjs/common';
-import { ISendMailOptions, TemplateAdapter } from '@nestjs-modules/mailer';
-import Handlebars from 'handlebars';
-
-export class MjmlAdapter implements TemplateAdapter {
-  compile: TemplateAdapter['compile'] = async (
-    mail: { data: ISendMailOptions },
-    callback,
-    options,
-  ) => {
-    try {
-      const templatePath = path.join(
-        options.template?.dir || '',
-        mail.data.template || '',
-      );
-      const content = fs.readFileSync(templatePath, 'utf-8');
-      const delegate = Handlebars.compile(content);
-      const compiledHandlebars = delegate(mail.data.context);
-      const mjml2html = await import('mjml');
-      const { errors, html } = await mjml2html.default(compiledHandlebars);
-
-      if (errors.length) {
-        throw 'Unable to compiling mjml';
-      }
-      mail.data.html = html;
-
-      callback();
-    } catch (err) {
-      Logger.error('@nestjs-modules/mailer: Unable to compiling mjml', err);
-    }
-  };
-}

package/src/utils/types/extension.ts

@@ -1,13 +0,0 @@
-/*
- * Hexabot — Fair Core License (FCL-1.0-ALv2)
- * Copyright (c) 2025 Hexastack.
- * Full terms: see LICENSE.md.
- */
-
-import { ChannelName } from '@/channel/types';
-import { HelperName } from '@/helper/types';
-
-export type ExtensionName = ChannelName | HelperName;
-
-export type HyphenToUnderscore<S extends string> =
-  S extends `${infer P}-${infer Q}` ? `${P}_${HyphenToUnderscore<Q>}` : S;