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

package/src/extensions/channels/web/base-web-channel.ts

@@ -4,6 +4,8 @@
  * Full terms: see LICENSE.md.
  */
 
+import { randomUUID } from 'crypto';
+
 import type {
   Attachment,
   Source,
@@ -25,7 +27,6 @@ import {
 import { OnEvent } from '@nestjs/event-emitter';
 import { Request, Response } from 'express';
 import { Socket } from 'socket.io';
-import { v4 as uuidv4 } from 'uuid';
 import type { z } from 'zod';
 
 import { AttachmentOrmEntity } from '@/attachment/entities/attachment.entity';
@@ -37,16 +38,16 @@ import {
 import {
   ChannelCapabilities,
   DEFAULT_CHANNEL_CAPABILITIES,
-  ExtensionInject,
-  WebSocketChannelHandler,
-} from '@/channel';
+} from '@/channel/lib/channel-capabilities';
+import { ExtensionInject } from '@/channel/lib/extension-inject.decorator';
 import { MessageInboundEvent } from '@/channel/lib/inbound-events';
+import { WebSocketChannelHandler } from '@/channel/lib/transports/websocket-channel-handler';
 import { SourceService } from '@/channel/services/source.service';
 import { ChannelName } from '@/channel/types';
-import { SubscriberChannelData } from '@/chat';
 import { MessageCreateDto } from '@/chat/dto/message.dto';
 import { SubscriberCreateDto } from '@/chat/dto/subscriber.dto';
 import { MessageService } from '@/chat/services/message.service';
+import type { SubscriberChannelData } from '@/chat/types/channel';
 import { MenuService } from '@/cms/services/menu.service';
 import { config } from '@/config';
 import { SocketRequest } from '@/websocket/utils/socket-request';
@@ -73,6 +74,10 @@ import { WebSessionService } from './services/web-session.service';
 import { WEB_CHANNEL_NAME } from './settings.schema';
 import { Web } from './types';
 
+type WebSocketData = Socket['data'] & {
+  webMessageQueue?: Promise<void>;
+};
+
 /**
  * Base handler for the Socket.IO-backed "web" channel.
  *
@@ -125,7 +130,7 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
   }
 
   generateId(): string {
-    return `${this.name}-${uuidv4()}`;
+    return `${this.name}-${randomUUID()}`;
   }
 
   getChannelAttributes(
@@ -160,6 +165,30 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
     return normalizedSourceId.length > 0 ? normalizedSourceId : null;
   }
 
+  private enqueueMessageDispatch(
+    req: SocketRequest,
+    event: MessageInboundEvent,
+  ): void {
+    const socket = req.socket as Socket & { data?: WebSocketData };
+    const socketData = (socket.data ??= {});
+    // Keep chatbot processing ordered per socket without making the client ack
+    // wait for slow actions, LLM calls, or external integrations.
+    const previous = socketData.webMessageQueue ?? Promise.resolve();
+    const next = previous
+      .catch(() => undefined)
+      .then(() => this.channelEventBus.emitMessage(event))
+      .catch((err) => {
+        this.logger.error('Failed to process web socket message', err);
+      });
+
+    socketData.webMessageQueue = next;
+    void next.finally(() => {
+      if (socketData.webMessageQueue === next) {
+        delete socketData.webMessageQueue;
+      }
+    });
+  }
+
   @OnEvent('hook:websocket:connection', { async: true })
   async onWebSocketConnection(client: Socket) {
     try {
@@ -546,15 +575,24 @@ export default abstract class BaseWebChannelHandler<N extends ChannelName>
           messageEvent.setAuthorForeignId(profile.foreignId);
         }
         messageEvent.setCreatedAt(new Date());
+        // Resolve the thread before acknowledging the socket request so the
+        // client receives a stable thread_id, then dispatch chatbot work later.
+        const thread = await this.sessionService.resolveThreadForIncoming(
+          req,
+          profile.id,
+          {
+            explicitThreadId: messageEvent.getThreadId(),
+            inactivityHours: this.sessionService.resolveInactivityHours(
+              source.settings,
+            ),
+            sourceId: source.id,
+          },
+        );
+        messageEvent.setThreadId(thread.id);
+        messageEvent.setThreadIdOnRaw(thread.id);
 
         this.broadcast(profile, StdEventType.message, messageEvent.getRaw());
-        await this.channelEventBus.emitMessage(messageEvent);
-
-        const resolvedThreadId = messageEvent.getThreadId();
-        if (resolvedThreadId) {
-          messageEvent.setThreadIdOnRaw(resolvedThreadId);
-          if (req.session.web) req.session.web.threadId = resolvedThreadId;
-        }
+        this.enqueueMessageDispatch(req, messageEvent);
 
         continue;
       }

package/src/extensions/channels/web/outbound/web-outbound-message-encoder.ts

@@ -24,8 +24,8 @@ import { ChannelOutboundMessageEncoder } from '@/channel/lib/outbound';
 import { ChannelAttachmentService } from '@/channel/services/channel-attachment.service';
 import { VIEW_MORE_PAYLOAD } from '@/chat/helpers/constants';
 import { ContentOrmEntity } from '@/cms/entities/content.entity';
-import { I18nService } from '@/i18n';
-import { LoggerService } from '@/logger';
+import { I18nService } from '@/i18n/services/i18n.service';
+import { LoggerService } from '@/logger/logger.service';
 
 import { Web } from '../types';
 

package/src/extensions/channels/web/services/web-session.service.ts

@@ -215,6 +215,10 @@ export class WebSessionService {
     return this.threadService.resolveThread({ subscriberId, explicitThreadId });
   }
 
+  resolveInactivityHours(settings: unknown): number {
+    return this.threadService.resolveInactivityHours(settings);
+  }
+
   /**
    * Resolves a thread from the request query/body and writes the result back
    * to the session. Used by the subscribe/history flows.
@@ -232,4 +236,35 @@ export class WebSessionService {
 
     return thread;
   }
+
+  /**
+   * Resolves the writable thread for an incoming message and persists it on the
+   * socket session before chatbot processing continues asynchronously.
+   */
+  async resolveThreadForIncoming(
+    req: SocketRequest,
+    subscriberId: string,
+    {
+      explicitThreadId,
+      inactivityHours,
+      sourceId,
+    }: {
+      explicitThreadId?: string;
+      inactivityHours?: number;
+      sourceId?: string;
+    },
+  ): Promise<Thread> {
+    const thread = await this.threadService.resolveThreadForIncoming({
+      subscriberId,
+      explicitThreadId,
+      inactivityHours,
+      sourceId,
+    });
+
+    if (req.session.web) {
+      req.session.web.threadId = thread.id;
+    }
+
+    return thread;
+  }
 }

package/src/global.d.ts

@@ -8,10 +8,4 @@ import '../types/event-emitter';
 import '../types/express-session';
 import './types/ai-sdk-mcp-stdio';
 
-declare global {
-  type HyphenToUnderscore<S extends string> = S extends `${infer P}-${infer Q}`
-    ? `${P}_${HyphenToUnderscore<Q>}`
-    : S;
-}
-
 export {};

package/src/license/services/lemon-squeezy.service.ts

@@ -4,10 +4,11 @@
  * Full terms: see LICENSE.md.
  */
 
+import { randomUUID } from 'crypto';
+
 import { HttpService } from '@nestjs/axios';
 import { Injectable } from '@nestjs/common';
 import { AxiosError } from 'axios';
-import { v4 as uuidv4 } from 'uuid';
 
 import {
   LemonSqueezyActivationResponse,
@@ -52,7 +53,7 @@ export class LemonSqueezyService {
         `${LEMON_SQUEEZY_API_BASE_URL}/v1/licenses/activate`,
         {
           license_key: licenseKey,
-          instance_name: uuidv4(),
+          instance_name: randomUUID(),
         },
         {
           headers: {

package/src/mailer/mailer.module.ts

@@ -4,66 +4,13 @@
  * Full terms: see LICENSE.md.
  */
 
-import path from 'path';
-
 import { Global, Module } from '@nestjs/common';
-import {
-  ISendMailOptions,
-  MAILER_OPTIONS,
-  MailerOptions,
-  MailerModule as NestjsMailerModule,
-} from '@nestjs-modules/mailer';
-import SMTPTransport from 'nodemailer/lib/smtp-transport';
-
-import { config } from '@/config';
 
 import { MailerService } from './mailer.service';
-import { MjmlAdapter } from './mjml-adapter.class';
-
-const mailerOptions: MailerOptions = {
-  transport: new SMTPTransport({
-    ...config.emails.smtp,
-    logger: true,
-    debug: false,
-  }),
-  template: {
-    adapter: new MjmlAdapter(),
-    dir: path.join(process.cwd(), 'dist', 'templates'),
-    options: {
-      context: {
-        appName: config.parameters.appName,
-        appUrl: config.uiBaseUrl,
-      },
-    },
-  },
-  defaults: { from: config.emails.from },
-};
 
 @Global()
 @Module({
-  imports: [
-    ...(config.emails.isEnabled
-      ? [NestjsMailerModule.forRoot(mailerOptions)]
-      : []),
-  ],
-  providers: [
-    {
-      provide: MAILER_OPTIONS,
-      useValue: mailerOptions,
-    },
-    ...(config.emails.isEnabled
-      ? [MailerService]
-      : [
-          {
-            provide: MailerService,
-            useValue: {
-              sendMail(_options: ISendMailOptions) {
-                throw new Error('Email Service is not enabled');
-              },
-            },
-          },
-        ]),
-  ],
+  providers: [MailerService],
   exports: [MailerService],
 })
 export class MailerModule {}

package/src/mailer/mailer.service.ts

@@ -4,6 +4,90 @@
  * Full terms: see LICENSE.md.
  */
 
-import { MailerService as NestjsMailerService } from '@nestjs-modules/mailer';
+import { readFile } from 'fs/promises';
+import path from 'path';
 
-export class MailerService extends NestjsMailerService {}
+import { Injectable } from '@nestjs/common';
+import Handlebars from 'handlebars';
+import mjml2html from 'mjml';
+import nodemailer, {
+  SendMailOptions as NodemailerSendMailOptions,
+  SentMessageInfo,
+  Transporter,
+} from 'nodemailer';
+import SMTPTransport from 'nodemailer/lib/smtp-transport';
+
+import { config } from '@/config';
+
+export type SendMailOptions = NodemailerSendMailOptions & {
+  template?: string;
+  context?: Record<string, unknown>;
+};
+
+@Injectable()
+export class MailerService {
+  private readonly transporter?: Transporter<SentMessageInfo>;
+
+  constructor() {
+    if (!config.emails.isEnabled) {
+      return;
+    }
+
+    this.transporter = nodemailer.createTransport(
+      new SMTPTransport({
+        ...config.emails.smtp,
+        logger: true,
+        debug: false,
+      }),
+    );
+  }
+
+  async sendMail({ template, context, ...options }: SendMailOptions) {
+    if (!this.transporter) {
+      throw new Error('Email Service is not enabled');
+    }
+
+    const html = template
+      ? await this.renderTemplate(template, context)
+      : options.html;
+
+    return await this.transporter.sendMail({
+      from: config.emails.from,
+      ...options,
+      html,
+    });
+  }
+
+  async verifyAllTransporters(): Promise<boolean> {
+    if (!this.transporter) {
+      return false;
+    }
+
+    return await this.transporter.verify();
+  }
+
+  private async renderTemplate(
+    template: string,
+    context: Record<string, unknown> = {},
+  ): Promise<string> {
+    const templatePath = path.join(
+      process.cwd(),
+      'dist',
+      'templates',
+      template,
+    );
+    const content = await readFile(templatePath, 'utf-8');
+    const compiledHandlebars = Handlebars.compile(content)({
+      appName: config.parameters.appName,
+      appUrl: config.uiBaseUrl,
+      ...context,
+    });
+    const { errors, html } = mjml2html(compiledHandlebars);
+
+    if (errors.length) {
+      throw new Error('Unable to compile mjml template');
+    }
+
+    return html;
+  }
+}

package/src/mcp/README.md

@@ -0,0 +1,244 @@
+# Hexabot API MCP Server
+
+This module exposes Hexabot API capabilities through the Model Context Protocol
+(MCP) so coding agents can inspect and manage workflows, workflow runs, memory
+definitions, actions, credentials, and CMS content.
+
+The implementation uses `@rekog/mcp-nest` with Streamable HTTP transport.
+Authentication is Hexabot-native: users create personal MCP bearer tokens from
+their Hexabot account and paste those tokens into MCP clients such as Codex or
+Claude Code.
+
+## Runtime endpoints
+
+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. |
+
+The MCP endpoint is stateful and uses `mcp-session-id` headers for sessions.
+
+## Enabling the server
+
+Set the MCP variables in `packages/api/.env` and restart the API.
+
+```dotenv
+MCP_ENABLED=true
+MCP_SERVER_NAME=hexabot-api
+MCP_SERVER_TITLE=Hexabot API MCP Server
+MCP_SERVER_VERSION=1.0.0
+```
+
+## Authentication and authorization
+
+MCP requests use Hexabot-issued bearer tokens. Tokens are prefixed with
+`hbt_mcp_` and are shown only once when created.
+
+The guard chain is:
+
+1. `HexabotMcpTokenGuard` validates the bearer token hash and resolves its
+   active Hexabot owner.
+2. `McpPermissionGuard` checks the requested tool against Hexabot role
+   permissions.
+
+Token storage is intentionally secret-safe:
+
+- Raw token values are never stored.
+- Only a SHA-256 token hash and short display prefix are persisted.
+- The full token is returned only in the create-token response.
+- Revoked, expired, unknown, or inactive-owner tokens are rejected.
+
+The token owner must be an active Hexabot user.
+
+Tool permissions use `@McpPermission(model, action)` metadata and the existing
+`PermissionService`. For example, workflow read tools require the caller role to
+have `workflow:read`; workflow mutation tools require the corresponding create
+or update permission.
+
+## Creating a bearer token
+
+Use the authenticated Hexabot REST API to create a token for the current user:
+
+```http
+POST /api/mcp-token
+Content-Type: application/json
+
+{
+  "name": "Codex",
+  "expiresAt": "2026-12-31T23:59:59.000Z"
+}
+```
+
+The response includes the raw bearer token once:
+
+```json
+{
+  "token": "hbt_mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+  "record": {
+    "id": "token-id",
+    "name": "Codex",
+    "tokenPrefix": "hbt_mcp_xxxxxxxx",
+    "owner": "user-id",
+    "expiresAt": "2026-12-31T23:59:59.000Z",
+    "lastUsedAt": null,
+    "revokedAt": null,
+    "createdAt": "2026-05-05T00:00:00.000Z",
+    "updatedAt": "2026-05-05T00:00:00.000Z"
+  }
+}
+```
+
+Copy the `token` value into the MCP client. After this response, Hexabot cannot
+show the raw token again.
+
+List token metadata:
+
+```http
+GET /api/mcp-token
+```
+
+Revoke a token:
+
+```http
+POST /api/mcp-token/{id}/revoke
+```
+
+## Connecting an MCP client
+
+Use a Streamable HTTP MCP client pointed at:
+
+```text
+http://localhost:3000/api/mcp
+```
+
+Production clients should use the public API origin, for example:
+
+```text
+https://api.example.com/api/mcp
+```
+
+If a client requires a JSON config entry, the exact field names depend on the
+client, but the effective configuration should be equivalent to:
+
+```json
+{
+  "mcpServers": {
+    "hexabot": {
+      "type": "http",
+      "url": "http://localhost:3000/api/mcp",
+      "headers": {
+        "Authorization": "Bearer hbt_mcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+## Tool surface
+
+### 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_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_commit` | `workflowversion:create` | Validate and commit workflow definition YAML. |
+| `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.
+
+### 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. |
+
+### Memory definitions
+
+| 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. |
+
+### Credentials
+
+| Tool | Permission | Purpose |
+| --- | --- | --- |
+| `hexabot_credential_search` | `credential:read` | Search credential metadata by name or owner. |
+| `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
+value.
+
+### 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. |
+
+## Extending the MCP module
+
+Add new tools in `tools/hexabot-mcp.tools.ts`.
+
+Each tool should:
+
+1. Use `@Tool()` with a stable `hexabot_*` name and a Zod parameter schema.
+2. Use `@ToolGuards([McpPermissionGuard])`.
+3. Use `@McpPermission(model, action)` with existing Hexabot permission models.
+4. Return plain JSON-serializable data.
+5. Avoid exposing secrets, tokens, connection strings, or raw credential values.
+
+If a tool changes API behavior or a public contract, update this README and the
+relevant tests in `packages/api/src/mcp`.
+
+## Tests
+
+Run the API checks from the repository root:
+
+```bash
+pnpm --filter @hexabot-ai/api run typecheck
+pnpm --filter @hexabot-ai/api run lint
+pnpm --filter @hexabot-ai/api run test
+pnpm --filter @hexabot-ai/api run test:e2e
+pnpm --filter @hexabot-ai/api run build
+```
+
+The MCP e2e tests are enabled only when `MCP_ENABLED=true`. A local test command
+is:
+
+```bash
+NODE_ENV=test MCP_ENABLED=true pnpm --filter @hexabot-ai/api run test:e2e
+```

package/src/mcp/controllers/mcp-token.controller.ts

@@ -0,0 +1,64 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2026 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import {
+  Body,
+  Controller,
+  Get,
+  HttpCode,
+  Post,
+  Req,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { Request } from 'express';
+
+import { UuidParam } from '@/utils';
+
+import { McpTokenCreateDto } from '../dto/mcp-token.dto';
+import { McpTokenService } from '../services/mcp-token.service';
+
+type AuthenticatedRequest = Request & {
+  user?: { id?: string };
+  session?: Request['session'] & {
+    passport?: { user?: { id?: string } };
+  };
+};
+
+@Controller('mcp-token')
+export class McpTokenController {
+  constructor(private readonly mcpTokenService: McpTokenService) {}
+
+  @Get()
+  async list(@Req() req: AuthenticatedRequest) {
+    return await this.mcpTokenService.findOwnedTokens(this.getUserId(req));
+  }
+
+  @Post()
+  async create(
+    @Body() dto: McpTokenCreateDto,
+    @Req() req: AuthenticatedRequest,
+  ) {
+    return await this.mcpTokenService.createPersonalToken(
+      this.getUserId(req),
+      dto,
+    );
+  }
+
+  @Post(':id/revoke')
+  @HttpCode(200)
+  async revoke(@UuidParam('id') id: string, @Req() req: AuthenticatedRequest) {
+    return await this.mcpTokenService.revokeOwnedToken(this.getUserId(req), id);
+  }
+
+  private getUserId(req: AuthenticatedRequest): string {
+    const userId = req.user?.id ?? req.session?.passport?.user?.id;
+    if (!userId) {
+      throw new UnauthorizedException('Authenticated user is required');
+    }
+
+    return userId;
+  }
+}