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

package/src/transfer/workflow-transfer.types.ts

@@ -0,0 +1,98 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { WorkflowImportResourceResult } from '@hexabot-ai/types';
+import { BadRequestException } from '@nestjs/common';
+
+import { BaseOrmEntity } from '@/database/entities/base.entity';
+
+/**
+ * Workflow transfer persistence contract:
+ * - WorkflowTransferService owns the import transaction boundary.
+ * - Resource adapters receive EntityManager for transactional writes.
+ * - Export reads use owning module services wherever available.
+ * - Transfer does not introduce duplicate repositories for owned resources.
+ */
+
+export const PLACEHOLDER_CREDENTIAL_VALUE =
+  '__HEXABOT_IMPORTED_CREDENTIAL_PLACEHOLDER__';
+
+export type WorkflowTransferPostCreateEvent<
+  Entity extends BaseOrmEntity<any> = BaseOrmEntity<any>,
+> = {
+  entityName: string;
+  entity: Entity;
+  payload: unknown;
+};
+
+export type WorkflowTransferImportAdapterResult = {
+  idMap: Record<string, string>;
+  resources: WorkflowImportResourceResult[];
+  warnings: string[];
+  postCreateEvents: WorkflowTransferPostCreateEvent[];
+  metadata?: Record<string, unknown>;
+};
+
+export type WorkflowTransferResourceIdMaps = Record<
+  string,
+  Record<string, string>
+>;
+
+export type ImportedWorkflowTransferResources = {
+  bindingIdMaps: WorkflowTransferResourceIdMaps;
+  taskIdMaps: WorkflowTransferResourceIdMaps;
+  resources: WorkflowImportResourceResult[];
+  warnings: string[];
+  postCreateEvents: WorkflowTransferPostCreateEvent[];
+};
+
+type ResourceActionInput = Omit<WorkflowImportResourceResult, 'localId'> & {
+  localId?: string;
+};
+
+export const uniqueResourceIds = (ids: string[]): string[] => {
+  return Array.from(new Set(ids));
+};
+
+export const assertFoundAll = (
+  resourceLabel: string,
+  expectedIds: string[],
+  foundIds: string[],
+): void => {
+  const found = new Set(foundIds);
+  const missing = expectedIds.filter((id) => !found.has(id));
+  if (missing.length > 0) {
+    throw new BadRequestException(
+      `Unable to export workflow: missing ${resourceLabel}(s): ${missing.join(
+        ', ',
+      )}`,
+    );
+  }
+};
+
+export const buildResourceResult = (
+  input: ResourceActionInput,
+): WorkflowImportResourceResult => {
+  if (!input.localId) {
+    throw new Error(`Missing local ID for imported ${input.kind}`);
+  }
+
+  return {
+    kind: input.kind,
+    exportId: input.exportId,
+    localId: input.localId,
+    name: input.name,
+    action: input.action,
+  };
+};
+
+export const buildPostCreateEvent = <Entity extends BaseOrmEntity<any>>(
+  entityName: string,
+  entity: Entity,
+  payload: unknown,
+): WorkflowTransferPostCreateEvent<Entity> => {
+  return { entityName, entity, payload };
+};

package/src/user/guards/ability.guard.ts

@@ -17,6 +17,8 @@ import {
 import { Reflector } from '@nestjs/core';
 import { Request } from 'express';
 
+import { config } from '@/config';
+
 import { TRole } from '../entities/role.entity';
 import { PermissionService } from '../services/permission.service';
 import { MethodToAction } from '../types/action.type';
@@ -31,12 +33,20 @@ export class Ability implements CanActivate {
 
   async canActivate(context: ExecutionContext): Promise<boolean> {
     const roles = this.reflector.get<TRole[]>('roles', context.getHandler());
+    const { _parsedUrl } = context
+      .switchToHttp()
+      .getRequest<Request & { _parsedUrl: Url }>();
+    const pathname = _parsedUrl.pathname?.replace(`/api`, '');
+
+    if (config.mcp.enabled && pathname && pathname === '/mcp') {
+      return true;
+    }
 
     if (roles?.includes('public')) {
       return true;
     }
 
-    const { user, method, _parsedUrl, session } = context
+    const { user, method, session } = context
       .switchToHttp()
       .getRequest<Request & { user: User; _parsedUrl: Url }>();
     if (!user) {
@@ -49,11 +59,13 @@ export class Ability implements CanActivate {
       throw new UnauthorizedException('Session expired');
     }
 
+    if (config.mcp.enabled && pathname?.startsWith('/mcp-token')) {
+      return true;
+    }
+
     const roleIds = Array.isArray(user.roles) ? user.roles : [];
 
     if (roleIds.length) {
-      const pathname = _parsedUrl.pathname?.replace(`/api`, '');
-
       if (
         pathname &&
         [

package/src/utils/test/fixtures/workflow-run.ts

@@ -64,6 +64,7 @@ export const workflowRunOrmFixtures: WorkflowRunOrmFixture[] = [
     workflow: workflowRunWorkflowFixtureId,
     workflowVersion: workflowRunWorkflowVersionFixtureId,
     triggeredBy: userFixtureIds.admin,
+    parentRun: null,
     status: 'running',
     input: { source: 'fixture' },
     output: null,
@@ -92,6 +93,7 @@ export const workflowRunOrmFixtures: WorkflowRunOrmFixture[] = [
     workflow: workflowRunWorkflowFixtureId,
     workflowVersion: workflowRunWorkflowVersionFixtureId,
     triggeredBy: null,
+    parentRun: null,
     status: 'finished',
     input: null,
     output: { result: 'ok' },
@@ -117,7 +119,7 @@ export const workflowRunOrmFixtures: WorkflowRunOrmFixture[] = [
 
 const findRunsWithRelations = async (dataSource: DataSource) =>
   await dataSource.getRepository(WorkflowRunOrmEntity).find({
-    relations: ['workflow', 'workflowVersion', 'triggeredBy'],
+    relations: ['workflow', 'workflowVersion', 'triggeredBy', 'parentRun'],
   });
 const ensureWorkflowFixture = async (dataSource: DataSource) => {
   const workflowRepository = dataSource.getRepository(WorkflowOrmEntity);
@@ -212,6 +214,7 @@ export const installWorkflowRunFixturesTypeOrm = async (
         ? { id: fixture.workflowVersion }
         : null,
       triggeredBy: fixture.triggeredBy ? { id: fixture.triggeredBy } : null,
+      parentRun: fixture.parentRun ? { id: fixture.parentRun } : null,
       status: fixture.status ?? 'idle',
       input: fixture.input ?? null,
       output: fixture.output ?? null,

package/src/utils/test/port.ts

@@ -0,0 +1,48 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+const DEFAULT_JEST_PORT = 3001;
+const JEST_HOST = '127.0.0.1';
+const parsePort = (value: string | undefined, envName: string): number => {
+  if (!value) {
+    return DEFAULT_JEST_PORT;
+  }
+
+  if (!/^\d+$/.test(value)) {
+    throw new Error(
+      `Invalid ${envName} "${value}". Expected a TCP port between 1 and 65535.`,
+    );
+  }
+
+  const port = Number(value);
+
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(
+      `Invalid ${envName} "${value}". Expected a TCP port between 1 and 65535.`,
+    );
+  }
+
+  return port;
+};
+
+export const getJestPort = (): number =>
+  parsePort(process.env.JEST_PORT, 'JEST_PORT');
+
+export const getJestHost = (): string => JEST_HOST;
+
+export const getJestBaseUrl = (): string =>
+  `http://${getJestHost()}:${getJestPort()}`;
+
+export const configureJestNetworkEnv = () => {
+  const port = getJestPort();
+  const baseUrl = `http://${getJestHost()}:${port}`;
+  const apiOrigin = process.env.JEST_API_ORIGIN ?? `${baseUrl}/api`;
+
+  process.env.PORT = `${port}`;
+  process.env.API_ORIGIN = apiOrigin;
+
+  return { port, baseUrl, apiOrigin };
+};

package/src/websocket/websocket.gateway.ts

@@ -5,7 +5,7 @@
  */
 
 import { type WorkflowEventMap } from '@hexabot-ai/agentic';
-import { StdEventType, Subscriber } from '@hexabot-ai/types';
+import { StdEventType, Subscriber, type WorkflowRun } from '@hexabot-ai/types';
 import { ForbiddenException, Optional } from '@nestjs/common';
 import { EventEmitter2, OnEvent } from '@nestjs/event-emitter';
 import {
@@ -69,6 +69,7 @@ export class WebsocketGateway
     Partial<Pick<WorkflowContextState, 'initiatorId'>> & {
       workflowId: string;
       threadId?: string;
+      workflowRun?: WorkflowRun;
       workflowEvent: string;
       t: number;
     }): void {

package/src/workflow/contexts/workflow-runtime.context.ts

@@ -19,7 +19,12 @@ import { LoggerService } from '@/logger/logger.service';
 import { SettingService } from '@/setting/services/setting.service';
 import { CredentialService } from '@/user/services/credential.service';
 import { cloneObject } from '@/utils/helpers/clone';
-import { WorkflowContextState, WorkflowType } from '@/workflow/types';
+import {
+  WORKFLOW_CALL_SERVICE,
+  WorkflowContextState,
+  WorkflowType,
+  type WorkflowCallService,
+} from '@/workflow/types';
 
 import { TriggerEventWrapper } from '../lib/trigger-event-wrapper';
 import { McpClientPoolService } from '../services/mcp-client-pool.service';
@@ -64,6 +69,9 @@ export abstract class WorkflowRuntimeContext<
   @Inject(McpClientPoolService)
   protected readonly mcp: McpClientPoolService;
 
+  @Inject(WORKFLOW_CALL_SERVICE)
+  protected readonly workflowCallService: WorkflowCallService;
+
   public memoryStore: MemoryStore;
 
   constructor() {
@@ -82,6 +90,9 @@ export abstract class WorkflowRuntimeContext<
       actions: this.actionService,
       credentials: this.credentialService,
       mcp: this.mcp,
+      // Expose the workflow-call contract, not the concrete AgenticService, so
+      // contexts do not create a JS import cycle with WorkflowContextFactory.
+      agentic: this.workflowCallService,
     };
   }
 

package/src/workflow/controllers/workflow-run.controller.ts

@@ -42,6 +42,7 @@ export class WorkflowRunController extends BaseOrmController<WorkflowRunOrmEntit
           'workflowVersion.version',
           'triggeredBy.id',
           'thread.id',
+          'parentRun.id',
           'status',
           'suspendedStep',
           'suspensionReason',
@@ -76,6 +77,7 @@ export class WorkflowRunController extends BaseOrmController<WorkflowRunOrmEntit
           'workflowVersion.version',
           'triggeredBy.id',
           'thread.id',
+          'parentRun.id',
           'status',
           'suspendedStep',
           'suspensionReason',

package/src/workflow/dto/workflow-run.dto.ts

@@ -64,6 +64,16 @@ export class WorkflowRunCreateDto {
   })
   workflowVersion?: string | null;
 
+  @ApiPropertyOptional({
+    description: 'Parent workflow run waiting for this run',
+    type: String,
+  })
+  @IsOptional()
+  @IsUUIDv4({
+    message: 'Parent workflow run must be a valid UUID',
+  })
+  parentRun?: string | null;
+
   @ApiPropertyOptional({
     description: 'Lifecycle status of the run',
     enum: WORKFLOW_RUN_STATUSES,

package/src/workflow/entities/workflow-run.entity.ts

@@ -12,7 +12,14 @@ import {
   type WorkflowSnapshot,
 } from '@hexabot-ai/agentic';
 import { workflowRunSchema, workflowRunFullSchema } from '@hexabot-ai/types';
-import { Column, Entity, JoinColumn, ManyToOne, RelationId } from 'typeorm';
+import {
+  Column,
+  Entity,
+  Index,
+  JoinColumn,
+  ManyToOne,
+  RelationId,
+} from 'typeorm';
 
 import { ThreadOrmEntity } from '@/chat/entities/thread.entity';
 import { DatetimeColumn } from '@/database/decorators/datetime-column.decorator';
@@ -29,6 +36,7 @@ import { WorkflowVersionOrmEntity } from './workflow-version.entity';
 import { WorkflowOrmEntity } from './workflow.entity';
 
 @Entity({ name: 'workflow_runs' })
+@Index(['parentRun'])
 export class WorkflowRunOrmEntity extends BaseOrmEntity<WorkflowRunDto> {
   plainCls = workflowRunSchema;
 
@@ -86,6 +94,19 @@ export class WorkflowRunOrmEntity extends BaseOrmEntity<WorkflowRunDto> {
   @RelationId((run: WorkflowRunOrmEntity) => run.thread)
   private readonly threadId?: string | null;
 
+  /** Parent workflow run that is waiting for this run to return. */
+  @ManyToOne(() => WorkflowRunOrmEntity, {
+    nullable: true,
+    onDelete: 'SET NULL',
+  })
+  @JoinColumn({ name: 'parent_run_id' })
+  @AsRelation()
+  parentRun?: WorkflowRunOrmEntity | null;
+
+  /** Identifier of the parent run (for internal relations). */
+  @RelationId((run: WorkflowRunOrmEntity) => run.parentRun)
+  private readonly parentRunId?: string | null;
+
   /** Lifecycle status of the run (idle, running, suspended, finished, failed). */
   @EnumColumn({
     enum: WORKFLOW_RUN_STATUSES,

package/src/workflow/index.ts

@@ -72,4 +72,18 @@ export * from './services/mcp-server.service';
 
 export * from './services/mcp-client-pool.service';
 
+export * from '../transfer/workflow-transfer.module';
+
+export * from '../transfer/workflow-transfer.controller';
+
+export * from '../transfer/workflow-transfer-definition.service';
+
+export * from '../transfer/workflow-transfer-resource-adapter';
+
+export * from '../transfer/workflow-transfer-adapter.registry';
+
+export * from '../transfer/workflow-transfer.types';
+
+export * from '../transfer/workflow-transfer.service';
+
 export * from './defaults/default-workflow';

package/src/workflow/repositories/workflow-run.repository.ts

@@ -23,6 +23,12 @@ export class WorkflowRunRepository extends BaseOrmRepository<WorkflowRunOrmEntit
     @InjectRepository(WorkflowRunOrmEntity)
     repository: Repository<WorkflowRunOrmEntity>,
   ) {
-    super(repository, ['workflow', 'workflowVersion', 'triggeredBy', 'thread']);
+    super(repository, [
+      'workflow',
+      'workflowVersion',
+      'triggeredBy',
+      'thread',
+      'parentRun',
+    ]);
   }
 }

package/src/workflow/resource-refs.ts

@@ -0,0 +1,44 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { WORKFLOW_TRANSFER_RESOURCE_KIND_PATTERN } from '@hexabot-ai/types';
+
+export type WorkflowResourceRefKind = string;
+
+export const WORKFLOW_RESOURCE_REF_METADATA_KEY = 'x-hexabot:resourceRef';
+
+export type WorkflowResourceRefMetadata = {
+  kind: WorkflowResourceRefKind;
+};
+
+export type WorkflowActionResourceRefSource = 'input' | 'settings';
+
+export type WorkflowSchemaResourceRefDescriptor = {
+  kind: WorkflowResourceRefKind;
+  path: string;
+};
+
+export type WorkflowActionResourceRefDescriptor =
+  WorkflowSchemaResourceRefDescriptor & {
+    source: WorkflowActionResourceRefSource;
+  };
+
+export const workflowResourceRef = (
+  kind: WorkflowResourceRefKind,
+): {
+  [WORKFLOW_RESOURCE_REF_METADATA_KEY]: WorkflowResourceRefMetadata;
+} => ({
+  [WORKFLOW_RESOURCE_REF_METADATA_KEY]: { kind },
+});
+
+export const isWorkflowResourceRefKind = (
+  value: unknown,
+): value is WorkflowResourceRefKind => {
+  return (
+    typeof value === 'string' &&
+    WORKFLOW_TRANSFER_RESOURCE_KIND_PATTERN.test(value)
+  );
+};