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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hexabot-ai/api",
   "private": false,
-  "version": "3.2.2-alpha.16",
+  "version": "3.2.2-alpha.18",
   "description": "Hexabot is a solution for creating and managing chatbots across multiple channels, leveraging AI for advanced conversational capabilities. It provides a user-friendly interface for building, training, and deploying chatbots with integrated support for various messaging platforms.",
   "author": "Hexastack",
   "license": "FCL-1.0-ALv2",
@@ -92,8 +92,8 @@
     "typeorm": "^0.3.28",
     "yaml": "^2.8.3",
     "zod": "^4.3.6",
-    "@hexabot-ai/agentic": "3.1.2-alpha.16",
-    "@hexabot-ai/types": "3.0.2-alpha.16"
+    "@hexabot-ai/types": "3.0.2-alpha.18",
+    "@hexabot-ai/agentic": "3.1.2-alpha.18"
   },
   "devDependencies": {
     "@compodoc/compodoc": "^1.1.31",
@@ -144,7 +144,7 @@
     "tsconfig-paths": "^4.2.0",
     "tsconfig-paths-jest": "^0.0.1",
     "typescript": "^5.1.3",
-    "@hexabot-ai/frontend": "3.2.2-alpha.16"
+    "@hexabot-ai/frontend": "3.2.2-alpha.18"
   },
   "optionalDependencies": {
     "@css-inline/css-inline-linux-arm64-musl": "^0.14.1",

package/src/mcp/README.md

@@ -13,11 +13,11 @@ Claude Code.
 
 All routes are mounted under the existing API prefix.
 
-| Route | Purpose |
-| --- | --- |
-| `/api/mcp` | Streamable HTTP MCP endpoint. |
-| `/api/mcp-token` | List and create MCP personal access tokens for the current Hexabot user. |
-| `/api/mcp-token/:id/revoke` | Revoke one MCP personal access token owned by the current Hexabot user. |
+| Route                       | Purpose                                                                  |
+| --------------------------- | ------------------------------------------------------------------------ |
+| `/api/mcp`                  | Streamable HTTP MCP endpoint.                                            |
+| `/api/mcp-token`            | List and create MCP personal access tokens for the current Hexabot user. |
+| `/api/mcp-token/:id/revoke` | Revoke one MCP personal access token owned by the current Hexabot user.  |
 
 The MCP endpoint is stateful and uses `mcp-session-id` headers for sessions.
 
@@ -141,19 +141,20 @@ client, but the effective configuration should be equivalent to:
 
 ### Workflows
 
-| Tool | Permission | Purpose |
-| --- | --- | --- |
-| `hexabot_workflow_search` | `workflow:read` | Search workflows by metadata. |
-| `hexabot_workflow_get` | `workflow:read` | Read one workflow with populated version metadata. |
-| `hexabot_workflow_version_status` | `workflow:read` | Check current and published version pointers for one workflow. |
-| `hexabot_workflow_create` | `workflow:create` | Create a workflow and optionally commit initial YAML. |
-| `hexabot_workflow_update` | `workflow:update` | Update workflow metadata and optionally commit YAML. |
-| `hexabot_workflow_yaml_validate` | `workflow:read` | Validate workflow definition YAML without creating a version. |
-| `hexabot_workflow_yaml_commit` | `workflowversion:create` | Validate and commit workflow definition YAML. |
-| `hexabot_workflow_rollback` | `workflowversion:create` | Roll back to a previous version by creating a new restore snapshot. |
-| `hexabot_workflow_publish` | `workflow:update` | Publish the current workflow version. |
-| `hexabot_workflow_unpublish` | `workflow:update` | Clear the published workflow version. |
-| `hexabot_workflow_run` | `workflowrun:create` | Run a manual or scheduled workflow and return the run summary. |
+| Tool                              | Permission               | Purpose                                                                                      |
+| --------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------- |
+| `hexabot_workflow_search`         | `workflow:read`          | Search workflows by metadata.                                                                |
+| `hexabot_workflow_get`            | `workflow:read`          | Read one workflow with compact version metadata.                                             |
+| `hexabot_workflow_version_status` | `workflow:read`          | Check current and published version pointers for one workflow.                               |
+| `hexabot_workflow_create`         | `workflow:create`        | Create a workflow and optionally commit initial YAML.                                        |
+| `hexabot_workflow_update`         | `workflow:update`        | Update workflow metadata and optionally commit YAML.                                         |
+| `hexabot_workflow_yaml_validate`  | `workflow:read`          | Validate workflow definition YAML without creating a version.                                |
+| `hexabot_workflow_yaml_get`       | `workflowversion:read`   | Read exact workflow YAML by current workflow version or version ID with byte-range chunking. |
+| `hexabot_workflow_yaml_commit`    | `workflowversion:create` | Validate and commit workflow definition YAML.                                                |
+| `hexabot_workflow_rollback`       | `workflowversion:create` | Roll back to a previous version by creating a new restore snapshot.                          |
+| `hexabot_workflow_publish`        | `workflow:update`        | Publish the current workflow version.                                                        |
+| `hexabot_workflow_unpublish`      | `workflow:update`        | Clear the published workflow version.                                                        |
+| `hexabot_workflow_run`            | `workflowrun:create`     | Run a manual or scheduled workflow and return the run summary.                               |
 
 Workflow YAML is validated with `parseWorkflowDefinition()` before a version is
 created. Coding agents can call `hexabot_workflow_yaml_validate` first to get
@@ -164,42 +165,53 @@ explicitly supplied. `hexabot_workflow_rollback` and
 publish that snapshot with `hexabot_workflow_publish` when it should become the
 published version.
 
+Large YAML definitions are intentionally omitted from workflow and version list
+or metadata tools. Use `hexabot_workflow_yaml_get` with `workflowId` or
+`versionId` to retrieve the exact YAML. Its `offset`, `limit`, `endOffset`, and
+`nextOffset` fields use UTF-8 byte offsets; the response also includes the
+version checksum and total byte length so clients can verify reconstruction.
+
 ### Workflow versions and runs
 
-| Tool | Permission | Purpose |
-| --- | --- | --- |
-| `hexabot_workflow_version_search` | `workflowversion:read` | List YAML versions for a workflow. |
-| `hexabot_workflow_version_get` | `workflowversion:read` | Read one workflow YAML version. |
-| `hexabot_workflow_version_update` | `workflowversion:update` | Update workflow version metadata. |
-| `hexabot_workflow_version_restore` | `workflowversion:create` | Restore a previous version by creating a new snapshot. |
-| `hexabot_workflow_run_search` | `workflowrun:read` | Search workflow runs by workflow and status. |
-| `hexabot_workflow_run_get` | `workflowrun:read` | Read one workflow run with populated workflow metadata. |
-| `hexabot_workflow_run_debug` | `workflowrun:read` | Inspect one workflow run with execution state, workflow YAML, and parent/child run context for troubleshooting. |
+| Tool                               | Permission               | Purpose                                                                                         |
+| ---------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
+| `hexabot_workflow_version_search`  | `workflowversion:read`   | List compact version metadata for a workflow.                                                   |
+| `hexabot_workflow_version_get`     | `workflowversion:read`   | Read compact version metadata.                                                                  |
+| `hexabot_workflow_version_update`  | `workflowversion:update` | Update workflow version metadata.                                                               |
+| `hexabot_workflow_version_restore` | `workflowversion:create` | Restore a previous version by creating a new snapshot.                                          |
+| `hexabot_workflow_run_search`      | `workflowrun:read`       | Search workflow runs by workflow and status.                                                    |
+| `hexabot_workflow_run_get`         | `workflowrun:read`       | Read one workflow run with populated workflow metadata but no nested YAML body.                 |
+| `hexabot_workflow_run_debug`       | `workflowrun:read`       | Inspect one workflow run with execution state and parent/child run context for troubleshooting. |
+
+Workflow run search/get responses strip nested `definitionYml` fields from
+populated workflow-version relations. `hexabot_workflow_run_debug` returns the
+executed YAML once as top-level `workflowDefinitionYml` only when
+`includeWorkflowDefinition=true`.
 
 ### Memory definitions
 
-| Tool | Permission | Purpose |
-| --- | --- | --- |
-| `hexabot_memory_definition_search` | `memorydefinition:read` | Search memory definitions. |
-| `hexabot_memory_definition_get` | `memorydefinition:read` | Read one memory definition. |
+| Tool                               | Permission                | Purpose                     |
+| ---------------------------------- | ------------------------- | --------------------------- |
+| `hexabot_memory_definition_search` | `memorydefinition:read`   | Search memory definitions.  |
+| `hexabot_memory_definition_get`    | `memorydefinition:read`   | Read one memory definition. |
 | `hexabot_memory_definition_create` | `memorydefinition:create` | Create a memory definition. |
 | `hexabot_memory_definition_update` | `memorydefinition:update` | Update a memory definition. |
 
 ### Actions and runtime bindings
 
-| Tool | Permission | Purpose |
-| --- | --- | --- |
-| `hexabot_action_search` | `workflow:read` | Search available workflow actions and schemas. |
-| `hexabot_action_get` | `workflow:read` | Read one workflow action schema. |
-| `hexabot_binding_search` | `workflow:read` | Search runtime binding kind schemas. |
-| `hexabot_binding_get` | `workflow:read` | Read one runtime binding schema. |
+| Tool                     | Permission      | Purpose                                        |
+| ------------------------ | --------------- | ---------------------------------------------- |
+| `hexabot_action_search`  | `workflow:read` | Search available workflow actions and schemas. |
+| `hexabot_action_get`     | `workflow:read` | Read one workflow action schema.               |
+| `hexabot_binding_search` | `workflow:read` | Search runtime binding kind schemas.           |
+| `hexabot_binding_get`    | `workflow:read` | Read one runtime binding schema.               |
 
 ### Credentials
 
-| Tool | Permission | Purpose |
-| --- | --- | --- |
+| Tool                        | Permission        | Purpose                                      |
+| --------------------------- | ----------------- | -------------------------------------------- |
 | `hexabot_credential_search` | `credential:read` | Search credential metadata by name or owner. |
-| `hexabot_credential_get` | `credential:read` | Read credential metadata. |
+| `hexabot_credential_get`    | `credential:read` | Read credential metadata.                    |
 
 Credential secret values are never returned. The MCP tools remove the `value`
 field from all credential responses and do not support searching by secret
@@ -207,26 +219,26 @@ value.
 
 ### MCP servers
 
-| Tool | Permission | Purpose |
-| --- | --- | --- |
-| `hexabot_mcp_server_search` | `mcpserver:read` | Search configured MCP servers. |
-| `hexabot_mcp_server_get` | `mcpserver:read` | Read one configured MCP server. |
+| Tool                        | Permission         | Purpose                             |
+| --------------------------- | ------------------ | ----------------------------------- |
+| `hexabot_mcp_server_search` | `mcpserver:read`   | Search configured MCP servers.      |
+| `hexabot_mcp_server_get`    | `mcpserver:read`   | Read one configured MCP server.     |
 | `hexabot_mcp_server_create` | `mcpserver:create` | Create an MCP server configuration. |
 | `hexabot_mcp_server_update` | `mcpserver:update` | Update an MCP server configuration. |
 
 ### CMS and RAG content
 
-| Tool | Permission | Purpose |
-| --- | --- | --- |
-| `hexabot_content_type_search` | `contenttype:read` | Search CMS content types. |
-| `hexabot_content_type_get` | `contenttype:read` | Read one content type. |
-| `hexabot_content_type_create` | `contenttype:create` | Create a content type. |
-| `hexabot_content_type_update` | `contenttype:update` | Update a content type. |
-| `hexabot_content_search` | `content:read` | Search CMS content records. |
-| `hexabot_content_get` | `content:read` | Read one content record. |
-| `hexabot_content_create` | `content:create` | Create a content record. |
-| `hexabot_content_update` | `content:update` | Update a content record. |
-| `hexabot_rag_content_search` | `content:read` | Search indexed CMS content through RAG retrieval. |
+| Tool                          | Permission           | Purpose                                           |
+| ----------------------------- | -------------------- | ------------------------------------------------- |
+| `hexabot_content_type_search` | `contenttype:read`   | Search CMS content types.                         |
+| `hexabot_content_type_get`    | `contenttype:read`   | Read one content type.                            |
+| `hexabot_content_type_create` | `contenttype:create` | Create a content type.                            |
+| `hexabot_content_type_update` | `contenttype:update` | Update a content type.                            |
+| `hexabot_content_search`      | `content:read`       | Search CMS content records.                       |
+| `hexabot_content_get`         | `content:read`       | Read one content record.                          |
+| `hexabot_content_create`      | `content:create`     | Create a content record.                          |
+| `hexabot_content_update`      | `content:update`     | Update a content record.                          |
+| `hexabot_rag_content_search`  | `content:read`       | Search indexed CMS content through RAG retrieval. |
 
 ## Extending the MCP module
 

package/src/mcp/guards/hexabot-mcp-token.guard.ts

@@ -44,9 +44,9 @@ export class HexabotMcpTokenGuard implements CanActivate {
       return undefined;
     }
 
-    const [type, token] = authHeader.split(' ');
+    const match = authHeader.trim().match(/^Bearer\s+(\S+)$/i);
 
-    return type === 'Bearer' ? token : undefined;
+    return match?.[1];
   }
 
   private getMcpTokenService(): McpTokenService {

package/src/mcp/tools/hexabot-mcp.utils.ts

@@ -6,8 +6,24 @@
 
 export const sanitizeCredential = <T extends Record<string, unknown>>(
   credential: T,
-): T => {
+): Omit<T, 'value'> => {
   const { value: _value, ...safeCredential } = credential;
 
-  return safeCredential as T;
+  return safeCredential;
+};
+
+export const omitKeysDeep = <T>(value: T, keys: readonly string[]): T => {
+  if (Array.isArray(value)) {
+    return value.map((item) => omitKeysDeep(item, keys)) as T;
+  }
+
+  if (value === null || typeof value !== 'object' || value instanceof Date) {
+    return value;
+  }
+
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([key]) => !keys.includes(key))
+      .map(([key, nestedValue]) => [key, omitKeysDeep(nestedValue, keys)]),
+  ) as T;
 };

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

@@ -4,7 +4,11 @@
  * Full terms: see LICENSE.md.
  */
 
-import { type WorkflowFull, type WorkflowVersion } from '@hexabot-ai/types';
+import {
+  type WorkflowFull,
+  type WorkflowVersion,
+  type WorkflowVersionFull,
+} from '@hexabot-ai/types';
 import {
   BadRequestException,
   Injectable,
@@ -17,6 +21,8 @@ import { WorkflowVersionService } from '@/workflow/services/workflow-version.ser
 import { WorkflowService } from '@/workflow/services/workflow.service';
 import { WorkflowVersionAction } from '@/workflow/types';
 
+type WorkflowVersionLike = WorkflowVersion | WorkflowVersionFull;
+
 type WorkflowVersionSummary = Pick<
   WorkflowVersion,
   | 'id'
@@ -24,12 +30,26 @@ type WorkflowVersionSummary = Pick<
   | 'checksum'
   | 'message'
   | 'action'
-  | 'parentVersion'
-  | 'workflow'
-  | 'createdBy'
   | 'createdAt'
   | 'updatedAt'
->;
+> & {
+  parentVersion:
+    | WorkflowVersion['parentVersion']
+    | WorkflowVersionFull['parentVersion'];
+  workflow: WorkflowVersion['workflow'] | WorkflowVersionFull['workflow'];
+  createdBy: WorkflowVersion['createdBy'] | WorkflowVersionFull['createdBy'];
+  definitionYmlByteLength?: number;
+};
+
+type WorkflowSummary = Omit<
+  WorkflowFull,
+  'currentVersion' | 'publishedVersion' | 'definitionYml' | 'definition'
+> & {
+  currentVersion: WorkflowVersionSummary | null;
+  publishedVersion: WorkflowVersionSummary | null;
+  currentVersionId: string | null;
+  publishedVersionId: string | null;
+};
 
 @Injectable()
 export class HexabotWorkflowMcpHelper {
@@ -121,8 +141,30 @@ export class HexabotWorkflowMcpHelper {
     };
   }
 
-  private summarizeWorkflowVersion(
-    version: WorkflowVersion | null | undefined,
+  summarizeWorkflow(workflow: WorkflowFull): WorkflowSummary {
+    const {
+      currentVersion,
+      publishedVersion,
+      definitionYml: _definitionYml,
+      definition: _definition,
+      ...metadata
+    } = workflow;
+    const currentVersionSummary = this.summarizeWorkflowVersion(currentVersion);
+    const publishedVersionSummary =
+      this.summarizeWorkflowVersion(publishedVersion);
+
+    return {
+      ...metadata,
+      currentVersion: currentVersionSummary,
+      publishedVersion: publishedVersionSummary,
+      currentVersionId: currentVersionSummary?.id ?? null,
+      publishedVersionId: publishedVersionSummary?.id ?? null,
+    };
+  }
+
+  summarizeWorkflowVersion(
+    version: WorkflowVersionLike | null | undefined,
+    options?: { includeDefinitionYmlByteLength?: boolean },
   ): WorkflowVersionSummary | null {
     if (!version) {
       return null;
@@ -139,8 +181,7 @@ export class HexabotWorkflowMcpHelper {
       createdAt,
       updatedAt,
     } = version;
-
-    return {
+    const summary = {
       id,
       version: versionNumber,
       checksum,
@@ -151,7 +192,19 @@ export class HexabotWorkflowMcpHelper {
       createdBy,
       createdAt,
       updatedAt,
+      ...(options?.includeDefinitionYmlByteLength
+        ? {
+            definitionYmlByteLength:
+              typeof version.definitionYml === 'string'
+                ? Buffer.byteLength(version.definitionYml, 'utf8')
+                : undefined,
+          }
+        : {}),
     };
+
+    return Object.fromEntries(
+      Object.entries(summary).filter(([, value]) => value !== undefined),
+    ) as WorkflowVersionSummary;
   }
 
   private resolveRelationId(

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

@@ -4,7 +4,7 @@
  * Full terms: see LICENSE.md.
  */
 
-import { Action } from '@hexabot-ai/types';
+import { Action, type WorkflowFull } from '@hexabot-ai/types';
 import {
   BadRequestException,
   Injectable,
@@ -64,21 +64,30 @@ export class HexabotWorkflowMcpTools extends HexabotMcpToolBase {
   ) {
     const where = this.buildWorkflowWhere(args);
     const options = this.findOptions<WorkflowOrmEntity>(args, where);
+    const result = await this.listWithCount(this.workflowService, options);
 
-    return await this.listWithCount(this.workflowService, options);
+    return {
+      ...result,
+      items: result.items.map((workflow) =>
+        this.workflowHelper.summarizeWorkflow(workflow as WorkflowFull),
+      ),
+    };
   }
 
   @McpPermission('workflow', Action.READ)
   @ToolGuards([McpPermissionGuard])
   @Tool({
     name: 'hexabot_workflow_get',
-    description: 'Read a Hexabot workflow with populated version metadata.',
+    description:
+      'Read a Hexabot workflow with compact version metadata, excluding YAML definition bodies.',
     parameters: z.object({
       id: uuidSchema,
     }),
   })
   async getWorkflow(args: { id: string }) {
-    return await this.workflowHelper.requireWorkflow(args.id);
+    const workflow = await this.workflowHelper.requireWorkflow(args.id);
+
+    return this.workflowHelper.summarizeWorkflow(workflow);
   }
 
   @McpPermission('workflow', Action.READ)
@@ -145,7 +154,9 @@ export class HexabotWorkflowMcpTools extends HexabotMcpToolBase {
       });
     }
 
-    return await this.workflowHelper.requireWorkflow(workflow.id);
+    return this.workflowHelper.summarizeWorkflow(
+      await this.workflowHelper.requireWorkflow(workflow.id),
+    );
   }
 
   @McpPermission('workflow', Action.UPDATE)
@@ -188,7 +199,9 @@ export class HexabotWorkflowMcpTools extends HexabotMcpToolBase {
       });
     }
 
-    return await this.workflowHelper.requireWorkflow(id);
+    return this.workflowHelper.summarizeWorkflow(
+      await this.workflowHelper.requireWorkflow(id),
+    );
   }
 
   @McpPermission('workflow', Action.UPDATE)
@@ -215,7 +228,9 @@ export class HexabotWorkflowMcpTools extends HexabotMcpToolBase {
       publishedVersion: workflow.currentVersion,
     });
 
-    return await this.workflowHelper.requireWorkflow(args.id);
+    return this.workflowHelper.summarizeWorkflow(
+      await this.workflowHelper.requireWorkflow(args.id),
+    );
   }
 
   @McpPermission('workflow', Action.UPDATE)
@@ -231,7 +246,9 @@ export class HexabotWorkflowMcpTools extends HexabotMcpToolBase {
     await this.workflowHelper.requireWorkflow(args.id);
     await this.workflowService.updateOne(args.id, { publishedVersion: null });
 
-    return await this.workflowHelper.requireWorkflow(args.id);
+    return this.workflowHelper.summarizeWorkflow(
+      await this.workflowHelper.requireWorkflow(args.id),
+    );
   }
 
   private buildWorkflowWhere(args: {

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