@hexabot-ai/api 3.2.2-alpha.16 → 3.2.2-alpha.18

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