feat: add agent mention bot (@studybot ) for room and DM messaging

- Add createSystemMessage() to MessagesService (bypass membership check)
- Add sendSystemDM() to DMsService (bypass participant check)
- Create AgentModule with mention detection and external API call
- Integrate agent mention handling in MessagesService and DMsService
- Add agent config (AGENT_API_URL, AGENT_BOT_USER_ID, AGENT_BOT_USERNAME)
- Add migration to create bot user in profiles table
- Remove AgentApiKeyGuard (internal service only)

.env.example

@@ -66,3 +66,15 @@ LOG_LEVEL=debug
 
 # Frontend URL (for emails, invites)
 FRONTEND_URL=http://localhost:5173
+
+# ======================================
+# Agent / Bot Mention Handler
+# ======================================
+# Base URL of your agent API (without trailing slash, e.g. https://agent.example.com)
+AGENT_API_URL=https://anhkhoiphan-092-agent-api.hf.space
+# API key for your agent service (optional, depends on your agent)
+AGENT_API_KEY=
+# User ID of the bot profile in the database (must exist in profiles table)
+AGENT_BOT_USER_ID=uuid-of-bot-profile
+# Username to trigger mention (default: studybot)
+AGENT_BOT_USERNAME=StudyBot

migrations/001_initial_schema.sql

@@ -23,7 +23,7 @@ CREATE TABLE spaces (
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
   name TEXT NOT NULL,
   description TEXT,
-  icon_url TEXT,
+  icon TEXT,
   owner_id UUID REFERENCES profiles(id),
   is_private BOOLEAN DEFAULT false,
   invite_code TEXT UNIQUE,

migrations/017_add_bot_user.sql

@@ -0,0 +1,114 @@
+-- Migration: Create bot user for agent/AI assistant
+-- This creates a system bot user that will send replies when mentioned (@studybot)
+
+-- Insert bot user into auth.users (using a fixed UUID for consistency)
+-- Note: In production, you may want to use Supabase Auth API to create this user properly
+-- This SQL is for development/testing purposes
+
+-- First, check if the bot user already exists
+DO $$
+DECLARE
+  bot_uuid UUID := '00000000-0000-0000-0000-000000000001';
+  bot_email TEXT := 'studybot@system.local';
+  bot_username TEXT := 'studybot';
+  bot_display_name TEXT := 'StudyBot';
+BEGIN
+  -- Check if bot user exists in auth.users
+  IF NOT EXISTS (SELECT 1 FROM auth.users WHERE id = bot_uuid) THEN
+    -- Insert into auth.users (minimal required fields)
+    INSERT INTO auth.users (
+      id,
+      email,
+      encrypted_password,
+      email_confirmed_at,
+      created_at,
+      updated_at,
+      raw_app_meta_data,
+      raw_user_meta_data
+    ) VALUES (
+      bot_uuid,
+      bot_email,
+      crypt('bot-password-change-me', gen_salt('bf')), -- Change this password!
+      NOW(),
+      NOW(),
+      NOW(),
+      '{"provider":"email","providers":["email"]}',
+      '{"username":"studybot","display_name":"StudyBot"}'
+    );
+  END IF;
+
+  -- Check if bot profile exists
+  IF NOT EXISTS (SELECT 1 FROM profiles WHERE id = bot_uuid) THEN
+    -- Check if profiles table has username column
+    IF EXISTS (SELECT 1 FROM information_schema.columns 
+               WHERE table_name = 'profiles' AND column_name = 'username') THEN
+      INSERT INTO profiles (
+        id,
+        email,
+        username,
+        display_name,
+        avatar_url,
+        bio,
+        color,
+        status,
+        created_at,
+        updated_at
+      ) VALUES (
+        bot_uuid,
+        bot_email,
+        bot_username,
+        bot_display_name,
+        'https://api.dicebear.com/7.x/bottts/svg?seed=studybot',
+        'AI assistant ready to help! Mention me with @studybot',
+        '#6366f1',
+        'online',
+        NOW(),
+        NOW()
+      );
+    ELSE
+      INSERT INTO profiles (
+        id,
+        email,
+        display_name,
+        avatar_url,
+        bio,
+        color,
+        status,
+        created_at,
+        updated_at
+      ) VALUES (
+        bot_uuid,
+        bot_email,
+        bot_display_name,
+        'https://api.dicebear.com/7.x/bottts/svg?seed=studybot',
+        'AI assistant ready to help! Mention me with @studybot',
+        '#6366f1',
+        'online',
+        NOW(),
+        NOW()
+      );
+    END IF;
+  END IF;
+
+  -- Update username if column exists and is null/empty
+  BEGIN
+    IF EXISTS (SELECT 1 FROM information_schema.columns 
+               WHERE table_name = 'profiles' AND column_name = 'username') THEN
+      UPDATE profiles 
+      SET username = bot_username 
+      WHERE id = bot_uuid AND (username IS NULL OR username = '');
+    END IF;
+  EXCEPTION WHEN OTHERS THEN
+    RAISE NOTICE 'Username update failed, skipping';
+  END;
+
+END $$;
+
+-- Output the bot user ID for reference
+SELECT 
+  'Bot user created/updated with ID: ' || id as message,
+  id as bot_user_id,
+  email,
+  display_name
+FROM profiles 
+WHERE id = '00000000-0000-0000-0000-000000000001';

src/app.module.ts

@@ -4,7 +4,7 @@ import { ThrottlerModule } from '@nestjs/throttler';
 import { APP_GUARD } from '@nestjs/core';
 import { AppController } from './app.controller';
 import { AppService } from './app.service';
-import { appConfig, databaseConfig, redisConfig, jwtConfig } from './config';
+import { appConfig, databaseConfig, redisConfig, jwtConfig, agentConfig } from './config';
 import { SupabaseModule } from './database';
 import { RedisModule } from './redis';
 import { AuthModule } from './modules/auth/auth.module';
@@ -17,6 +17,7 @@ import { DMsModule } from './modules/dms/dms.module';
 import { NotificationsModule } from './modules/notifications/notifications.module';
 import { FilesModule } from './modules/files/files.module';
 import { SearchModule } from './modules/search/search.module';
+import { AgentModule } from './modules/agent/agent.module';
 import { ChatGatewayModule } from './gateways/chat.gateway.module';
 import { JwtAuthGuard } from './common/guards/jwt-auth.guard';
 
@@ -25,7 +26,7 @@ import { JwtAuthGuard } from './common/guards/jwt-auth.guard';
     // Configuration
     ConfigModule.forRoot({
       isGlobal: true,
-      load: [appConfig, databaseConfig, redisConfig, jwtConfig],
+      load: [appConfig, databaseConfig, redisConfig, jwtConfig, agentConfig],
       envFilePath: ['.env.local', '.env'],
     }),
 
@@ -66,6 +67,9 @@ import { JwtAuthGuard } from './common/guards/jwt-auth.guard';
 
     // Phase 4 - WebSocket & Real-time
     ChatGatewayModule,
+
+    // Agent/Bot Messaging API
+    AgentModule,
   ],
   controllers: [AppController],
   providers: [

src/config/agent.config.ts

@@ -0,0 +1,8 @@
+import { registerAs } from '@nestjs/config';
+
+export default registerAs('agent', () => ({
+  apiUrl: process.env.AGENT_API_URL || '',
+  apiKey: process.env.AGENT_API_KEY || '',
+  botUserId: process.env.AGENT_BOT_USER_ID || '',
+  botUsername: process.env.AGENT_BOT_USERNAME || 'studybot',
+}));

src/config/index.ts

@@ -2,3 +2,4 @@ export { default as appConfig } from './app.config';
 export { default as databaseConfig } from './database.config';
 export { default as redisConfig } from './redis.config';
 export { default as jwtConfig } from './jwt.config';
+export { default as agentConfig } from './agent.config';

src/modules/agent/agent.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { AgentService } from './agent.service';
+
+@Module({
+  imports: [ConfigModule],
+  providers: [AgentService],
+  exports: [AgentService],
+})
+export class AgentModule {}

src/modules/agent/agent.service.ts

@@ -0,0 +1,145 @@
+import {
+  Injectable,
+  Logger,
+} from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+
+interface AgentApiRequest {
+  conversation_id: string;
+  query: string;
+  sender_id: string;
+}
+
+interface AgentApiResponse {
+  reply?: string;
+  message?: string;
+  content?: string;
+  response?: string;
+  text?: string;
+  answer?: string;
+}
+
+@Injectable()
+export class AgentService {
+  private readonly logger = new Logger(AgentService.name);
+
+  constructor(
+    private readonly configService: ConfigService,
+  ) {}
+
+  // ==================== Mention Bot Logic ====================
+
+  /**
+   * Check if message contains a mention of the configured bot username
+   */
+  containsMention(content: string): boolean {
+    const botUsername = this.configService.get<string>('AGENT_BOT_USERNAME') || this.configService.get<string>('agent.botUsername') || 'studybot';
+    const pattern = new RegExp(`@${botUsername}\\b`, 'i');
+    return pattern.test(content);
+  }
+
+  /**
+   * Extract the prompt from a message by removing the bot mention
+   */
+  extractPrompt(content: string): string {
+    const botUsername = this.configService.get<string>('AGENT_BOT_USERNAME') || this.configService.get<string>('agent.botUsername') || 'studybot';
+    const pattern = new RegExp(`@${botUsername}\\b`, 'gi');
+    return content.replace(pattern, '').trim();
+  }
+
+  /**
+   * Get bot user ID from config
+   */
+  getBotUserId(): string | undefined {
+    const botUserId = this.configService.get<string>('AGENT_BOT_USER_ID');
+    if (botUserId) return botUserId;
+    return this.configService.get<string>('agent.botUserId') || undefined;
+  }
+
+  /**
+   * Call the external agent API and return the reply text
+   * Returns null if agent is not configured or returns empty
+   */
+  async callAgent(
+    roomId: string,
+    userId: string,
+    prompt: string,
+    username?: string,
+  ): Promise<string | null> {
+    const baseUrl = this.configService.get<string>('AGENT_API_URL') || this.configService.get<string>('agent.apiUrl');
+
+    if (!baseUrl) {
+      this.logger.warn('AGENT_API_URL not configured, skipping agent call');
+      return 'Xin lỗi, tôi đang gặp sự cố kết nối. Vui lòng thử lại sau!';
+    }
+
+    if (!prompt) {
+      this.logger.debug('Empty prompt, skipping agent call');
+      return null;
+    }
+
+    try {
+      this.logger.log(`Calling agent API for room ${roomId}, user ${userId}`);
+      const reply = await this.callAgentApi({
+        conversation_id: roomId,
+        query: prompt,
+        sender_id: username || userId,
+      });
+
+      if (!reply || reply.trim().length === 0) {
+        this.logger.warn('Agent returned empty reply');
+        return 'Xin lỗi, tôi không hiểu câu hỏi của bạn. Vui lòng thử lại!';
+      }
+
+      this.logger.log(`Agent replied for room ${roomId}`);
+      return reply;
+    } catch (error) {
+      this.logger.error(`Failed to call agent: ${error.message}`);
+      return 'Xin lỗi, tôi đang gặp sự cố kỹ thuật. Vui lòng thử lại sau nhé!';
+    }
+  }
+
+  /**
+   * Call the external agent API at POST /api/v1/chat
+   */
+  private async callAgentApi(payload: AgentApiRequest): Promise<string> {
+    const baseUrl = this.configService.get<string>('AGENT_API_URL') || this.configService.get<string>('agent.apiUrl');
+    const apiKey = this.configService.get<string>('AGENT_API_KEY') || this.configService.get<string>('agent.apiKey');
+
+    const url = `${baseUrl}/api/v1/chat`;
+
+    this.logger.debug(`Agent API URL: ${url}`);
+    this.logger.debug(`Agent API payload: ${JSON.stringify(payload)}`);
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+
+    if (apiKey) {
+      headers['Authorization'] = `Bearer ${apiKey}`;
+    }
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Agent API returned ${response.status}: ${await response.text()}`);
+    }
+
+    const data = (await response.json()) as AgentApiResponse;
+
+    // Support multiple response formats
+    return (
+      data.reply ||
+      data.message ||
+      data.content ||
+      data.response ||
+      data.text ||
+      data.answer ||
+      ''
+    );
+  }
+}

src/modules/agent/dto/send-agent-message.dto.ts

@@ -0,0 +1,29 @@
+import { IsString, IsOptional, IsUUID, MaxLength } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class SendAgentRoomMessageDto {
+  @ApiProperty({ description: 'Sender user ID (agent/bot user ID)' })
+  @IsUUID()
+  senderId: string;
+
+  @ApiProperty({ description: 'Message content' })
+  @IsString()
+  @MaxLength(4000)
+  content: string;
+
+  @ApiPropertyOptional({ description: 'ID of message being replied to' })
+  @IsOptional()
+  @IsUUID()
+  replyToId?: string;
+}
+
+export class SendAgentDMMessageDto {
+  @ApiProperty({ description: 'Sender user ID (agent/bot user ID)' })
+  @IsUUID()
+  senderId: string;
+
+  @ApiProperty({ description: 'Message content' })
+  @IsString()
+  @MaxLength(4000)
+  content: string;
+}

src/modules/dms/dms.module.ts

@@ -3,9 +3,10 @@ import { DMsController } from './dms.controller';
 import { DMsService } from './dms.service';
 import { SupabaseModule } from '../../database/supabase.module';
 import { RedisModule } from '../../redis/redis.module';
+import { AgentModule } from '../agent/agent.module';
 
 @Module({
-  imports: [SupabaseModule, RedisModule],
+  imports: [SupabaseModule, RedisModule, AgentModule],
   controllers: [DMsController],
   providers: [DMsService],
   exports: [DMsService],

src/modules/dms/dms.service.ts

@@ -9,6 +9,7 @@ import {
 import { SupabaseService } from '../../database/supabase.service';
 import { RedisService } from '../../redis/redis.service';
 import { RedisKeys } from '../../redis/keys';
+import { AgentService } from '../agent/agent.service';
 import {
   CreateDMConversationDto,
   SendDMDto,
@@ -79,6 +80,7 @@ export class DMsService {
   constructor(
     private readonly supabaseService: SupabaseService,
     private readonly redisService: RedisService,
+    private readonly agentService: AgentService,
   ) {}
 
   /**
@@ -414,6 +416,117 @@ export class DMsService {
     };
   }
 
+  /**
+   * Send a system/agent DM without participant check.
+   * Used by AI agents, bots, and system notifications.
+   */
+  async sendSystemDM(
+    conversationId: string,
+    senderId: string,
+    dto: SendDMDto,
+  ): Promise<DMMessageWithSender> {
+    // Verify conversation exists (but don't check membership)
+    const { data: conversation, error: convError } = await this.supabaseService
+      .from('dm_conversations')
+      .select('*')
+      .eq('id', conversationId)
+      .single();
+
+    if (convError || !conversation) {
+      throw new NotFoundException('Conversation not found');
+    }
+
+    const receiverId =
+      conversation.user1_id === senderId
+        ? conversation.user2_id
+        : conversation.user1_id;
+
+    // Create message
+    const { data: message, error } = await this.supabaseService
+      .from('dm_messages')
+      .insert({
+        conversation_id: conversationId,
+        sender_id: senderId,
+        content: dto.content,
+        is_read: false,
+      })
+      .select(
+        `*, sender:profiles!dm_messages_sender_id_fkey ( id, email, username, display_name, avatar_url, bio, color, status )`,
+      )
+      .single();
+
+    if (error) {
+      this.logger.error('Failed to send system DM:', error.message);
+      throw new ConflictException('Failed to send message');
+    }
+
+    // Pipeline Redis operations
+    const pipeline = this.redisService.pipeline();
+    const dmKey = RedisKeys.dm.messages(
+      conversation.user1_id,
+      conversation.user2_id,
+    );
+
+    // Cache message
+    pipeline.hset(`dmmsg:${message.id}`, {
+      id: message.id,
+      conversation_id: message.conversation_id,
+      sender_id: message.sender_id,
+      sender_username: message.sender?.username || '',
+      content: message.content,
+      created_at: message.created_at,
+      deleted_at: message.deleted_at || '',
+    });
+    pipeline.expire(`dmmsg:${message.id}`, this.DM_CACHE_TTL);
+
+    // Add to conversation messages list
+    pipeline.zadd(
+      dmKey,
+      new Date(message.created_at).getTime(),
+      message.id,
+    );
+
+    // Increment unread count for receiver
+    const unreadKey = RedisKeys.dm.unread(receiverId, senderId);
+    pipeline.incr(unreadKey);
+
+    await pipeline.exec();
+
+    // Create notification for receiver
+    await this.supabaseService.from('notifications').insert({
+      user_id: receiverId,
+      type: 'dm',
+      title: 'New direct message',
+      message: 'You have a new direct message',
+      data: { conversationId, senderId, messageId: message.id },
+    });
+
+    // Publish to Redis for multi-server support
+    // Sort user IDs to match WebSocket room naming convention
+    const sortedUserIds = [conversation.user1_id, conversation.user2_id].sort();
+    const dmChannel = `channel:dm:${sortedUserIds[0]}:${sortedUserIds[1]}`;
+    this.logger.debug(`Publishing newDM to ${dmChannel}`);
+    await this.redisService.publish(
+      dmChannel,
+      JSON.stringify({
+        event: 'newDM',
+        data: {
+          id: message.id,
+          conversation_id: conversation.id,
+          sender_id: senderId,
+          content: message.content,
+          created_at: message.created_at,
+          sender: message.sender,
+          tempId: null,
+        },
+        timestamp: new Date().toISOString(),
+      }),
+    );
+
+    this.logger.log(`System DM sent from ${senderId} to ${receiverId}`);
+    return this.transformMessageWithSender(message);
+  }
+
   /**
    * Send DM
    */
@@ -502,8 +615,10 @@ export class DMsService {
     });
 
     // Publish to Redis for multi-server support
+    // Sort user IDs to match WebSocket room naming convention
+    const sortedUserIds = [conversation.user1_id, conversation.user2_id].sort();
     await this.redisService.publish(
-      `channel:dm:${conversation.user1_id}:${conversation.user2_id}`,
+      `channel:dm:${sortedUserIds[0]}:${sortedUserIds[1]}`,
       JSON.stringify({
         event: 'newDM',
         data: {
@@ -519,6 +634,13 @@ export class DMsService {
     );
 
     this.logger.log(`DM sent from ${senderId} to ${receiverId}`);
+
+    // Check for bot mention and handle asynchronously (fire-and-forget)
+    if (this.agentService.containsMention(dto.content)) {
+      this.handleAgentMention(conversationId, senderId, dto.content, message.sender?.username)
+        .catch((err) => this.logger.error('Agent DM mention handling failed:', err));
+    }
+
     return this.transformMessageWithSender(message);
   }
 
@@ -1067,4 +1189,28 @@ export class DMsService {
       },
     };
   }
+
+  /**
+   * Handle agent mention in DM: call agent API and send reply
+   */
+  private async handleAgentMention(
+    conversationId: string,
+    userId: string,
+    content: string,
+    username?: string,
+  ): Promise<void> {
+    const botUserId = this.agentService.getBotUserId();
+    if (!botUserId) {
+      this.logger.warn('AGENT_BOT_USER_ID not configured, skipping DM mention');
+      return;
+    }
+
+    const prompt = this.agentService.extractPrompt(content);
+    const reply = await this.agentService.callAgent(conversationId, userId, prompt, username);
+
+    if (reply) {
+      await this.sendSystemDM(conversationId, botUserId, { content: reply });
+      this.logger.log(`Agent replied in DM conversation ${conversationId}`);
+    }
+  }
 }

src/modules/messages/messages.module.ts

@@ -3,9 +3,10 @@ import { MessagesController } from './messages.controller';
 import { MessagesService } from './messages.service';
 import { SupabaseModule } from '../../database/supabase.module';
 import { RedisModule } from '../../redis/redis.module';
+import { AgentModule } from '../agent/agent.module';
 
 @Module({
-  imports: [SupabaseModule, RedisModule],
+  imports: [SupabaseModule, RedisModule, AgentModule],
   controllers: [MessagesController],
   providers: [MessagesService],
   exports: [MessagesService],

src/modules/messages/messages.service.ts

@@ -9,6 +9,7 @@ import {
 import { SupabaseService } from '../../database/supabase.service';
 import { RedisService } from '../../redis/redis.service';
 import { RedisKeys } from '../../redis/keys';
+import { AgentService } from '../agent/agent.service';
 import {
   CreateMessageDto,
   UpdateMessageDto,
@@ -62,6 +63,7 @@ export class MessagesService {
   constructor(
     private readonly supabaseService: SupabaseService,
     private readonly redisService: RedisService,
+    private readonly agentService: AgentService,
   ) {}
 
   // ==================== WebSocket Event Helpers ====================
@@ -85,6 +87,119 @@ export class MessagesService {
     }
   }
 
+  /**
+   * Create a system/agent message in a room without membership check.
+   * Used by AI agents, bots, and system notifications.
+   */
+  async createSystemMessage(
+    roomId: string,
+    senderId: string,
+    dto: CreateMessageDto,
+  ): Promise<MessageWithAuthor> {
+    // Verify room exists
+    const { data: room, error: roomError } = await this.supabaseService
+      .from('rooms')
+      .select('id')
+      .eq('id', roomId)
+      .single();
+
+    if (roomError || !room) {
+      throw new NotFoundException('Room not found');
+    }
+
+    // Validate reply_to_id if provided
+    if (dto.replyToId) {
+      const parentMessage = await this.getMessageById(dto.replyToId);
+      if (parentMessage.room_id !== roomId) {
+        throw new BadRequestException('Reply message must be in the same room');
+      }
+    }
+
+    // Create message in database
+    const { data: message, error } = await this.supabaseService
+      .from('messages')
+      .insert({
+        room_id: roomId,
+        user_id: senderId,
+        content: dto.content,
+        reply_to_id: dto.replyToId || null,
+      })
+      .select(
+        `*, author:profiles!messages_user_id_fkey ( id, username, display_name, avatar_url )`,
+      )
+      .single();
+
+    if (error) {
+      this.logger.error('Failed to create system message:', error.message);
+      throw new ConflictException('Failed to create message');
+    }
+
+    // Cache the message with author username
+    this.logger.debug(`System message author from DB: ${JSON.stringify(message.author)}`);
+    const messageToCache: Message = {
+      ...message,
+      username: message.author?.username || '',
+    };
+    this.logger.debug(`System message to cache: ${JSON.stringify(messageToCache)}`);
+
+    // Pipeline Redis operations for better performance
+    const pipeline = this.redisService.pipeline();
+    const messageKey = RedisKeys.message.byId(message.id);
+
+    // Cache message hash
+    pipeline.hset(messageKey, {
+      id: messageToCache.id,
+      room_id: messageToCache.room_id,
+      user_id: messageToCache.user_id,
+      content: messageToCache.content,
+      username: messageToCache.username || '',
+      reply_to_id: messageToCache.reply_to_id || '',
+      is_pinned: String(messageToCache.is_pinned || false),
+      created_at: messageToCache.created_at,
+      updated_at: messageToCache.updated_at || '',
+      deleted_at: messageToCache.deleted_at || '',
+    });
+    pipeline.expire(messageKey, this.MESSAGE_CACHE_TTL);
+
+    // Add to room's recent messages list (Redis sorted set)
+    pipeline.zadd(
+      RedisKeys.room.messages(roomId),
+      new Date(message.created_at).getTime(),
+      messageKey,
+    );
+
+    // Trim to keep only recent messages
+    pipeline.zremrangebyrank(
+      RedisKeys.room.messages(roomId),
+      0,
+      -this.RECENT_MESSAGES_LIMIT - 1,
+    );
+
+    // Update room stats
+    pipeline.hincrby(
+      RedisKeys.room.stats(roomId),
+      'messageCount',
+      1,
+    );
+
+    await pipeline.exec();
+
+    // Handle mentions
+    if (dto.mentions && dto.mentions.length > 0) {
+      await this.processMentions(message.id, roomId, senderId, dto.mentions);
+    }
+
+    // Publish real-time event
+    const messageWithAuthor = this.transformMessageWithAuthor(message);
+    await this.publishMessageEvent('newMessage', roomId, {
+      ...messageWithAuthor,
+      tempId: null,
+    });
+
+    this.logger.log(`System message ${message.id} created in room ${roomId} by ${senderId}`);
+    return messageWithAuthor;
+  }
+
   /**
    * Send a message to a room
    */
@@ -186,6 +301,13 @@ export class MessagesService {
     await this.publishMessageEvent('newMessage', roomId, messageWithAuthor);
 
     this.logger.log(`Message ${message.id} created in room ${roomId}`);
+
+    // Check for bot mention and handle asynchronously (fire-and-forget)
+    if (this.agentService.containsMention(dto.content)) {
+      this.handleAgentMention(roomId, userId, dto.content, messageWithAuthor.username)
+        .catch((err) => this.logger.error('Agent mention handling failed:', err));
+    }
+
     return messageWithAuthor;
   }
 
@@ -965,4 +1087,28 @@ export class MessagesService {
       },
     };
   }
+
+  /**
+   * Handle agent mention: call agent API and send reply to room
+   */
+  private async handleAgentMention(
+    roomId: string,
+    userId: string,
+    content: string,
+    username?: string,
+  ): Promise<void> {
+    const botUserId = this.agentService.getBotUserId();
+    if (!botUserId) {
+      this.logger.warn('AGENT_BOT_USER_ID not configured, skipping mention');
+      return;
+    }
+
+    const prompt = this.agentService.extractPrompt(content);
+    const reply = await this.agentService.callAgent(roomId, userId, prompt, username);
+
+    if (reply) {
+      await this.createSystemMessage(roomId, botUserId, { content: reply });
+      this.logger.log(`Agent replied in room ${roomId}`);
+    }
+  }
 }

src/modules/spaces/dto/create-space.dto.ts

@@ -22,6 +22,7 @@ export class CreateSpaceDto {
 
   @IsOptional()
   @IsString()
+  @MaxLength(20)
   icon?: string;
 
   @IsOptional()

src/modules/spaces/spaces.service.ts

@@ -18,7 +18,7 @@ interface Space {
   id: string;
   name: string;
   description: string | null;
-  icon_url: string | null;
+  icon: string | null;
   owner_id: string;
   is_private: boolean;
   invite_code: string;
@@ -87,7 +87,7 @@ export class SpacesService {
       id: space.id,
       name: space.name,
       description: space.description || '',
-      icon_url: space.icon_url || '',
+      icon: space.icon || '',
       owner_id: space.owner_id,
       is_private: String(space.is_private),
       invite_code: space.invite_code,
@@ -109,7 +109,7 @@ export class SpacesService {
         id: cached.id,
         name: cached.name,
         description: cached.description || null,
-        icon_url: cached.icon_url || null,
+        icon: cached.icon || null,
         owner_id: cached.owner_id,
         is_private: cached.is_private === 'true',
         invite_code: cached.invite_code,
@@ -193,7 +193,7 @@ export class SpacesService {
       .insert({
         name: dto.name,
         description: dto.description || null,
-        icon_url: dto.icon || null,
+        icon: dto.icon || null,
         owner_id: userId,
         is_private: dto.isPrivate ?? false,
         invite_code: inviteCode,
@@ -558,7 +558,7 @@ export class SpacesService {
       .update({
         name: dto.name,
         description: dto.description,
-        icon_url: dto.icon,
+        icon: dto.icon,
         is_private: dto.isPrivate,
         updated_at: new Date().toISOString(),
       })