@hexabot-ai/api 3.2.2-alpha.15 → 3.2.2-alpha.17

package/src/mcp/tools/workflow-run-mcp.tools.ts

@@ -39,6 +39,9 @@ import {
   paginationSchema,
   uuidSchema,
 } from './hexabot-mcp.schemas';
+import { omitKeysDeep } from './hexabot-mcp.utils';
+
+const WORKFLOW_DEFINITION_RESPONSE_KEYS = ['definitionYml'] as const;
 
 @Injectable()
 export class HexabotWorkflowRunMcpTools extends HexabotMcpToolBase {
@@ -120,11 +123,12 @@ export class HexabotWorkflowRunMcpTools extends HexabotMcpToolBase {
       ...(args.workflowId ? { workflow: { id: args.workflowId } } : {}),
       ...(args.status ? { status: args.status } : {}),
     } as any;
-
-    return await this.listWithCount(
+    const result = await this.listWithCount(
       this.workflowRunService,
       this.findOptions<WorkflowRunOrmEntity>(args, where),
     );
+
+    return this.sanitizeWorkflowRunResponse(result);
   }
 
   @McpPermission('workflowrun', Action.READ)
@@ -142,7 +146,7 @@ export class HexabotWorkflowRunMcpTools extends HexabotMcpToolBase {
       throw new NotFoundException(`Workflow run ${args.id} not found`);
     }
 
-    return run;
+    return this.withoutWorkflowDefinition(run);
   }
 
   @McpPermission('workflowrun', Action.READ)
@@ -186,18 +190,19 @@ export class HexabotWorkflowRunMcpTools extends HexabotMcpToolBase {
           this.workflowRunService.count({ where: childWhere }),
         ])
       : ([null, [], 0] as const);
+    const includeWorkflowDefinition = args.includeWorkflowDefinition ?? true;
     const response: Record<string, unknown> = {
-      run,
+      run: this.withoutWorkflowDefinition(run),
       relatedRuns: {
-        parent: parentRun,
-        children: childRuns,
+        parent: this.withoutWorkflowDefinition(parentRun),
+        children: this.withoutWorkflowDefinition(childRuns),
         childRunTotal,
         childRunsLimit: includeRelatedRuns ? childRunsLimit : 0,
       },
       summary: this.buildWorkflowRunDebugSummary(run, childRunTotal),
     };
 
-    if (args.includeWorkflowDefinition ?? true) {
+    if (includeWorkflowDefinition) {
       response.workflowDefinitionYml =
         run.workflowVersion?.definitionYml ?? null;
     }
@@ -271,4 +276,17 @@ export class HexabotWorkflowRunMcpTools extends HexabotMcpToolBase {
       childRunTotal,
     };
   }
+
+  private sanitizeWorkflowRunResponse<T extends { items: unknown[] }>(
+    response: T,
+  ): T {
+    return {
+      ...response,
+      items: this.withoutWorkflowDefinition(response.items),
+    };
+  }
+
+  private withoutWorkflowDefinition<T>(value: T): T {
+    return omitKeysDeep(value, WORKFLOW_DEFINITION_RESPONSE_KEYS);
+  }
 }

package/src/mcp/tools/workflow-version-mcp.tools.ts

@@ -5,8 +5,16 @@
  */
 
 import { validateWorkflow } from '@hexabot-ai/agentic';
-import { Action } from '@hexabot-ai/types';
-import { Injectable, NotFoundException } from '@nestjs/common';
+import {
+  Action,
+  type WorkflowVersion,
+  type WorkflowVersionFull,
+} from '@hexabot-ai/types';
+import {
+  BadRequestException,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
 import { Tool, ToolGuards } from '@rekog/mcp-nest';
 import { z } from 'zod';
 
@@ -67,11 +75,14 @@ export class HexabotWorkflowVersionMcpTools extends HexabotMcpToolBase {
     request?: HexabotMcpRequest,
   ) {
     const actorId = this.getActorId(request);
-
-    return await this.workflowHelper.commitWorkflowDefinition({
+    const version = await this.workflowHelper.commitWorkflowDefinition({
       ...args,
       createdBy: actorId,
     });
+
+    return this.workflowHelper.summarizeWorkflowVersion(version, {
+      includeDefinitionYmlByteLength: true,
+    });
   }
 
   @McpPermission('workflow', Action.READ)
@@ -108,7 +119,8 @@ export class HexabotWorkflowVersionMcpTools extends HexabotMcpToolBase {
   @ToolGuards([McpPermissionGuard])
   @Tool({
     name: 'hexabot_workflow_version_search',
-    description: 'List workflow definition YAML versions for a workflow.',
+    description:
+      'List compact workflow definition version metadata for a workflow, excluding YAML bodies.',
     parameters: z.object({
       workflowId: uuidSchema,
       ...paginationSchema,
@@ -118,18 +130,28 @@ export class HexabotWorkflowVersionMcpTools extends HexabotMcpToolBase {
   })
   async searchWorkflowVersions(args: { workflowId: string } & PaginationArgs) {
     const where = { workflow: { id: args.workflowId } } as any;
-
-    return await this.listWithCount(
+    const result = await this.listWithCount(
       this.workflowVersionService,
       this.findOptions<WorkflowVersionOrmEntity>(args, where),
     );
+
+    return {
+      ...result,
+      items: result.items.map((version) =>
+        this.workflowHelper.summarizeWorkflowVersion(
+          version as WorkflowVersion,
+          { includeDefinitionYmlByteLength: true },
+        ),
+      ),
+    };
   }
 
   @McpPermission('workflowversion', Action.READ)
   @ToolGuards([McpPermissionGuard])
   @Tool({
     name: 'hexabot_workflow_version_get',
-    description: 'Read one workflow definition YAML version.',
+    description:
+      'Read compact workflow definition version metadata, excluding the YAML body.',
     parameters: z.object({
       id: uuidSchema,
       workflowId: uuidSchema.optional(),
@@ -147,7 +169,57 @@ export class HexabotWorkflowVersionMcpTools extends HexabotMcpToolBase {
       throw new NotFoundException(`Workflow version ${args.id} not found`);
     }
 
-    return version;
+    return this.workflowHelper.summarizeWorkflowVersion(version, {
+      includeDefinitionYmlByteLength: true,
+    });
+  }
+
+  @McpPermission('workflowversion', Action.READ)
+  @ToolGuards([McpPermissionGuard])
+  @Tool({
+    name: 'hexabot_workflow_yaml_get',
+    description:
+      'Read workflow definition YAML by workflowId/current version or versionId, with checksum, byte length, and UTF-8 byte offset/limit chunking.',
+    parameters: z.object({
+      workflowId: uuidSchema.optional(),
+      versionId: uuidSchema.optional(),
+      offset: z.number().int().min(0).default(0),
+      limit: z.number().int().min(1).max(64000).default(16000),
+    }),
+  })
+  async getWorkflowYaml(args: {
+    workflowId?: string;
+    versionId?: string;
+    offset?: number;
+    limit?: number;
+  }) {
+    const version = await this.requireWorkflowVersionForYaml(args);
+    const definitionYml = version.definitionYml;
+    const offset = args.offset ?? 0;
+    const limit = args.limit ?? 16000;
+    const { chunk, chunkByteLength, endOffset, totalByteLength } =
+      this.sliceUtf8Chunk(definitionYml, offset, limit);
+    const workflowId = this.resolveRelationId(version.workflow);
+
+    return {
+      workflowId,
+      versionId: version.id,
+      version: version.version,
+      checksum: version.checksum,
+      definitionYmlByteLength: totalByteLength,
+      definitionYmlLength: definitionYml.length,
+      chunk: {
+        offset,
+        limit,
+        unit: 'utf8Bytes',
+        endOffset,
+        length: chunk.length,
+        byteLength: chunkByteLength,
+        hasMore: endOffset < totalByteLength,
+        nextOffset: endOffset < totalByteLength ? endOffset : null,
+      },
+      definitionYml: chunk,
+    };
   }
 
   @McpPermission('workflowversion', Action.UPDATE)
@@ -162,9 +234,13 @@ export class HexabotWorkflowVersionMcpTools extends HexabotMcpToolBase {
     }),
   })
   async updateWorkflowVersion(args: { id: string; message?: string | null }) {
-    return await this.workflowVersionService.updateOne(args.id, {
+    const version = await this.workflowVersionService.updateOne(args.id, {
       message: args.message ?? undefined,
     });
+
+    return this.workflowHelper.summarizeWorkflowVersion(version, {
+      includeDefinitionYmlByteLength: true,
+    });
   }
 
   @McpPermission('workflowversion', Action.CREATE)
@@ -184,10 +260,14 @@ export class HexabotWorkflowVersionMcpTools extends HexabotMcpToolBase {
     _context: unknown,
     request?: HexabotMcpRequest,
   ) {
-    return await this.workflowHelper.restoreWorkflowVersionSnapshot(
+    const version = await this.workflowHelper.restoreWorkflowVersionSnapshot(
       args,
       this.getActorId(request),
     );
+
+    return this.workflowHelper.summarizeWorkflowVersion(version, {
+      includeDefinitionYmlByteLength: true,
+    });
   }
 
   @McpPermission('workflowversion', Action.CREATE)
@@ -207,10 +287,14 @@ export class HexabotWorkflowVersionMcpTools extends HexabotMcpToolBase {
     _context: unknown,
     request?: HexabotMcpRequest,
   ) {
-    return await this.workflowHelper.restoreWorkflowVersionSnapshot(
+    const version = await this.workflowHelper.restoreWorkflowVersionSnapshot(
       args,
       this.getActorId(request),
     );
+
+    return this.workflowHelper.summarizeWorkflowVersion(version, {
+      includeDefinitionYmlByteLength: true,
+    });
   }
 
   private getWorkflowValidationActions() {
@@ -223,4 +307,153 @@ export class HexabotWorkflowVersionMcpTools extends HexabotMcpToolBase {
       ),
     );
   }
+
+  private async requireWorkflowVersionForYaml(args: {
+    workflowId?: string;
+    versionId?: string;
+  }): Promise<WorkflowVersion | WorkflowVersionFull> {
+    if (!args.workflowId && !args.versionId) {
+      throw new BadRequestException(
+        'workflowId or versionId is required to read workflow YAML',
+      );
+    }
+
+    if (args.versionId) {
+      const version = await this.workflowVersionService.findOneAndPopulate({
+        where: {
+          id: args.versionId,
+          ...(args.workflowId ? { workflow: { id: args.workflowId } } : {}),
+        } as any,
+      });
+
+      if (!version) {
+        throw new NotFoundException(
+          `Workflow version ${args.versionId} not found`,
+        );
+      }
+
+      return version;
+    }
+
+    const workflowId = args.workflowId;
+    if (!workflowId) {
+      throw new BadRequestException(
+        'workflowId is required when versionId is not provided',
+      );
+    }
+    const workflow = await this.workflowHelper.requireWorkflow(workflowId);
+    const currentVersionId = this.resolveRelationId(workflow.currentVersion);
+    if (!currentVersionId) {
+      throw new NotFoundException(
+        `Workflow ${workflowId} has no current version`,
+      );
+    }
+
+    const version = await this.workflowVersionService.findOneAndPopulate({
+      where: {
+        id: currentVersionId,
+        workflow: { id: workflowId },
+      } as any,
+    });
+
+    if (!version) {
+      throw new NotFoundException(
+        `Workflow version ${currentVersionId} not found`,
+      );
+    }
+
+    return version;
+  }
+
+  private sliceUtf8Chunk(
+    value: string,
+    offset: number,
+    limit: number,
+  ): {
+    chunk: string;
+    chunkByteLength: number;
+    endOffset: number;
+    totalByteLength: number;
+  } {
+    const totalByteLength = Buffer.byteLength(value, 'utf8');
+    if (offset > totalByteLength) {
+      throw new BadRequestException(
+        `Offset ${offset} exceeds workflow YAML byte length ${totalByteLength}`,
+      );
+    }
+
+    const startIndex = this.findUtf8IndexForOffset(value, offset);
+    let endIndex = value.length;
+    let byteOffset = offset;
+
+    for (let index = startIndex; index < value.length; ) {
+      const char = this.readCodePoint(value, index);
+      const nextByteOffset = byteOffset + Buffer.byteLength(char, 'utf8');
+
+      if (nextByteOffset > offset + limit) {
+        if (index === startIndex) {
+          throw new BadRequestException(
+            `Limit ${limit} is too small to include the next UTF-8 character at offset ${offset}`,
+          );
+        }
+        endIndex = index;
+        break;
+      }
+
+      byteOffset = nextByteOffset;
+      index += char.length;
+    }
+
+    const chunk = value.slice(startIndex, endIndex);
+    const chunkByteLength = Buffer.byteLength(chunk, 'utf8');
+
+    return {
+      chunk,
+      chunkByteLength,
+      endOffset: offset + chunkByteLength,
+      totalByteLength,
+    };
+  }
+
+  private findUtf8IndexForOffset(value: string, offset: number): number {
+    if (offset === 0) {
+      return 0;
+    }
+
+    let byteOffset = 0;
+    for (let index = 0; index < value.length; ) {
+      const char = this.readCodePoint(value, index);
+      const nextByteOffset = byteOffset + Buffer.byteLength(char, 'utf8');
+
+      if (offset === nextByteOffset) {
+        return index + char.length;
+      }
+
+      if (offset < nextByteOffset) {
+        throw new BadRequestException(
+          `Offset ${offset} is not aligned to a UTF-8 character boundary`,
+        );
+      }
+
+      byteOffset = nextByteOffset;
+      index += char.length;
+    }
+
+    if (offset === byteOffset) {
+      return value.length;
+    }
+
+    throw new BadRequestException(
+      `Offset ${offset} exceeds workflow YAML byte length ${byteOffset}`,
+    );
+  }
+
+  private readCodePoint(value: string, index: number): string {
+    const codePoint = value.codePointAt(index);
+    if (codePoint === undefined) {
+      return '';
+    }
+
+    return String.fromCodePoint(codePoint);
+  }
 }

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/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,
@@ -232,6 +232,7 @@ export class WorkflowService extends BaseOrmService<WorkflowOrmEntity> {
     this.gateway.broadcastWorkflowEvent({
       ...payload,
       t,
+      workflowRun,
       workflowId,
       initiatorId,
       threadId: typeof threadId === 'string' ? threadId : undefined,
@@ -249,6 +250,13 @@ export class WorkflowService extends BaseOrmService<WorkflowOrmEntity> {
     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')
   async sendWorkflowFailure(payload: WorkflowEventMap[keyof WorkflowEventMap]) {
     await this.sendWorkflowEvent('hook:workflow:failure', payload);