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

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/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/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)
+  );
+};