@multiplayer-app/ai-agent-node 0.1.0-beta.8 → 0.1.0-beta.81

package/dist/esm/processors/ChatProcessor.js

@@ -1,76 +1,369 @@
-import { AgentStatus, AgentToolCallStatus, ChatType, MessageRole, SortOrder, StreamChunkType } from '@multiplayer-app/ai-agent-types';
-import { socketService } from '../services';
-import { kafkaService } from '../services';
-import { AIHelper } from '../helpers';
-import { AgentProcessEventType, agentStore } from '../store';
-import { ContextLimiter } from '../helpers';
-import { config } from '../config';
-import { PassThrough, pipeline } from 'stream';
-import { promisify } from 'util';
+import { ActivityOperationName, AgentStatus, AgentToolCallStatus, AgentToolType, ChatType, MessageRole, SortOrder, StreamChunkType } from '@multiplayer-app/ai-agent-types';
+import { z } from 'zod';
+import { AgentProcessEventType, ConfigStore } from '../store';
+import { AIHelper, ContextLimiter, FileHelper } from '../helpers';
+import { PassThrough } from 'stream';
 import { logger } from '../libs/logger';
-const pipelineAsync = promisify(pipeline);
+import { AgentSessionKind } from "@multiplayer-app/ai-agent-types";
+import { getAgentToolName } from "../utils/utils";
 export class ChatProcessor {
+    aiHelper;
     chatRepository;
     messageRepository;
     artifactStore;
-    constructor(chatRepository, messageRepository, artifactStore) {
-        this.chatRepository = chatRepository;
-        this.messageRepository = messageRepository;
-        this.artifactStore = artifactStore;
+    activityRepository;
+    agentConfigRepository;
+    config;
+    socketService;
+    agentStore;
+    debug;
+    getChatUserId(chat) {
+        return chat.tenants?.userId;
+    }
+    constructor(params) {
+        this.chatRepository = params.chatRepository;
+        this.messageRepository = params.messageRepository;
+        this.artifactStore = params.artifactStore;
+        this.config = params.config;
+        this.socketService = params.socketService;
+        this.agentStore = params.agentStore;
+        this.activityRepository = params.activityRepository;
+        this.agentConfigRepository = params.agentConfigRepository;
+        const fileHelper = new FileHelper(params.s3Lib, this.config);
+        this.aiHelper = new AIHelper(fileHelper, this.config, params.tenantCredentialResolver);
+        this.debug = this.config.debug;
     }
     getTemporaryTitle(contextKey) {
         return `${contextKey} session ${new Date().toISOString()}`;
     }
+    isTemporaryTitle(title) {
+        // Matches pattern: "{contextKey} session {ISO_DATE_STRING}"
+        // Example: "default session 2026-01-23T10:30:45.123Z"
+        // toISOString() always includes milliseconds, so we require them
+        const pattern = /^.+ session \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+        return pattern.test(title);
+    }
+    isPlainObject(value) {
+        return !!value && typeof value === 'object' && !Array.isArray(value);
+    }
+    getExecutionTenants(payload) {
+        const contextTenants = payload.executionContext?.tenants;
+        if (contextTenants && Object.keys(contextTenants).length > 0) {
+            return contextTenants;
+        }
+        return payload.tenants ?? {};
+    }
+    getParticipantIds(chat) {
+        const primary = chat.userId ?? this.getChatUserId(chat);
+        return Array.from(new Set([primary, ...(chat.participantIds ?? [])].filter(Boolean)));
+    }
+    hasChatAccess(chat, userId) {
+        if (!userId)
+            return true;
+        return this.getParticipantIds(chat).includes(userId);
+    }
+    emitChatToParticipants(chat, chatToEmit, excludeSocketId) {
+        for (const userId of this.getParticipantIds(chatToEmit.participantIds ? chatToEmit : chat)) {
+            this.socketService.emitChatUpdate(userId, chatToEmit, excludeSocketId);
+        }
+    }
+    emitMessageToParticipants(chat, message, excludeSocketId) {
+        for (const userId of this.getParticipantIds(chat)) {
+            this.socketService.emitMessageUpdate(userId, message, excludeSocketId);
+        }
+    }
+    async updateChatAndEmit(chat, update, excludeSocketId) {
+        await this.chatRepository.update(chat.id, update);
+        const updatedChat = await this.chatRepository.findById(chat.id);
+        const chatToEmit = updatedChat ?? { ...chat, ...update };
+        this.emitChatToParticipants(chat, chatToEmit, excludeSocketId);
+        return chatToEmit;
+    }
+    async startSubagentProcess(params) {
+        const parentUserId = params.parentChat.userId ?? this.getChatUserId(params.parentChat) ?? 'guest';
+        const childChat = await this.chatRepository.create({
+            title: `${params.subAgentConfig.name} subagent`,
+            type: ChatType.Agent,
+            status: AgentStatus.Streaming,
+            sessionKind: AgentSessionKind.SUBAGENT,
+            parentChatId: params.parentChat.id,
+            parentMessageId: params.parentMessage.id,
+            parentToolCallId: params.parentToolCallId,
+            contextKey: params.parentChat.contextKey,
+            userId: parentUserId,
+            tenants: { ...params.parentChat.tenants },
+            model: params.subAgentConfig.defaultModel || params.parentChat.model,
+        });
+        try {
+            const parentToolCall = params.parentMessage.toolCalls?.find((toolCall) => toolCall.id === params.parentToolCallId);
+            if (parentToolCall) {
+                parentToolCall.input = {
+                    ...(parentToolCall.input ?? {}),
+                    subagentChatId: childChat.id,
+                };
+                parentToolCall.subagentChatId = childChat.id;
+                const updatedParentMessage = await this.messageRepository.update(params.parentMessage.id, {
+                    toolCalls: params.parentMessage.toolCalls,
+                });
+                if (updatedParentMessage) {
+                    this.emitMessageToParticipants(params.parentChat, updatedParentMessage);
+                }
+            }
+            this.emitChatToParticipants(params.parentChat, childChat);
+            const executionTenants = this.getExecutionTenants(params);
+            const abortController = this.agentStore.registerSubAgentProcess(childChat.id, params.parentChat.id);
+            const userMessage = await this.createMessage(childChat, MessageRole.User, {
+                content: JSON.stringify(params.input),
+                agentName: undefined
+            });
+            await this.agentStore.shareAgentProcessEvent(childChat.id, {
+                type: AgentProcessEventType.Update,
+                data: userMessage
+            });
+            let assistantMessage = await this.createMessage(childChat, MessageRole.Assistant, {
+                content: '',
+                agentName: params.subAgentConfig.name
+            });
+            const parentActivity = await this.activityRepository.create({
+                ownerId: parentUserId,
+                groupId: params.parentChat.id,
+                name: ActivityOperationName.SUBAGENT,
+                tenants: executionTenants,
+                sourceId: assistantMessage.id,
+                sourceType: 'AgentMessage',
+                metadata: {
+                    modelId: this.aiHelper.getLanguageModelId(childChat.model),
+                    agentOptions: {
+                        name: params.subAgentConfig.name,
+                        modelId: this.aiHelper.getLanguageModelId(params.subAgentConfig.defaultModel),
+                        temperature: params.subAgentConfig.temperature,
+                        maxOutputTokens: params.subAgentConfig.maxOutputTokens,
+                        topP: params.subAgentConfig.topP,
+                        topK: params.subAgentConfig.topK,
+                        presencePenalty: params.subAgentConfig.presencePenalty,
+                        frequencyPenalty: params.subAgentConfig.frequencyPenalty,
+                        stopSequences: params.subAgentConfig.stopSequences,
+                        seed: params.subAgentConfig.seed,
+                    },
+                },
+            });
+            const updatedAssistantMessage = await this.messageRepository.update(assistantMessage.id, {
+                activity: parentActivity.id
+            });
+            const agentOptions = this.aiHelper.getAgentOptionsFromConfig(params.subAgentConfig, params.context);
+            agentOptions.onStepFinish = (stepResult) => {
+                return this.storeStepActivity({
+                    chat: params.parentChat,
+                    parentId: assistantMessage.activity,
+                    stepResult,
+                    name: ActivityOperationName.STEP_FINISHED,
+                    sourceId: assistantMessage.id,
+                    sourceType: 'AgentMessage',
+                    tenants: executionTenants,
+                });
+            };
+            const userPreferences = await this.agentConfigRepository.findByUserIdAndAgentName(parentUserId, agentOptions.name);
+            agentOptions.activeTools = this.getAvailableTools(agentOptions, userPreferences);
+            await this.streamMessageStep({
+                chat: childChat,
+                existingMessages: [userMessage, updatedAssistantMessage],
+                assistantMessage: updatedAssistantMessage,
+                agentOptions,
+                signal: abortController.signal,
+                tenants: executionTenants,
+                executionContext: params.executionContext,
+                context: params.context,
+            });
+        }
+        catch (error) {
+            await this.storeSubagentResponse({
+                subagentChat: childChat,
+                content: undefined,
+                error: error,
+                context: params.context,
+                executionContext: params.executionContext,
+            });
+        }
+    }
+    mergeMissingUsageFields(target, source) {
+        for (const [key, sourceValue] of Object.entries(source)) {
+            const targetValue = target[key];
+            if (targetValue === undefined) {
+                target[key] = sourceValue;
+                continue;
+            }
+            if (this.isPlainObject(targetValue) && this.isPlainObject(sourceValue)) {
+                this.mergeMissingUsageFields(targetValue, sourceValue);
+            }
+        }
+    }
+    extractCostUsageFields(source) {
+        const extracted = {};
+        for (const [key, value] of Object.entries(source)) {
+            const normalizedKey = key.toLowerCase();
+            if (normalizedKey.includes('cost')) {
+                extracted[key] = value;
+                continue;
+            }
+            if (this.isPlainObject(value)) {
+                const nestedCostFields = this.extractCostUsageFields(value);
+                if (Object.keys(nestedCostFields).length > 0) {
+                    extracted[key] = nestedCostFields;
+                }
+            }
+        }
+        return extracted;
+    }
+    mergeUsageWithProviderMetadata(stepUsage, providerMetadata) {
+        const mergedUsage = this.isPlainObject(stepUsage) ? { ...stepUsage } : {};
+        let hasProviderUsage = false;
+        if (this.isPlainObject(providerMetadata)) {
+            for (const providerEntry of Object.values(providerMetadata)) {
+                if (!this.isPlainObject(providerEntry) || !this.isPlainObject(providerEntry.usage)) {
+                    continue;
+                }
+                const providerCostUsage = this.extractCostUsageFields(providerEntry.usage);
+                if (Object.keys(providerCostUsage).length === 0) {
+                    continue;
+                }
+                hasProviderUsage = true;
+                this.mergeMissingUsageFields(mergedUsage, providerCostUsage);
+            }
+        }
+        if (this.isPlainObject(stepUsage)) {
+            return mergedUsage;
+        }
+        if (hasProviderUsage) {
+            return mergedUsage;
+        }
+        return stepUsage;
+    }
+    async validateToolCallInput(params) {
+        const agentOptions = await this.aiHelper.getAgentOptions({
+            agentName: params.agentName,
+        });
+        const tool = agentOptions.tools?.[params.toolName] ?? undefined;
+        const schema = tool?.inputSchema;
+        if (!schema) {
+            throw new Error(`Tool "${params.toolName}" schema not found`);
+        }
+        if (!(schema instanceof z.ZodType)) {
+            throw new Error(`Tool "${params.toolName}" inputSchema must be a Zod schema`);
+        }
+        const result = schema.safeParse(params.input);
+        if (!result.success) {
+            throw new Error(`Invalid tool input for "${params.toolName}": ${result.error.message}`);
+        }
+    }
     async listChats(params) {
-        // Build filter object from params
-        const filter = {};
+        // Build filter object from params. Always exclude subagent chats:
+        // the repository translates ROOT into `sessionKind !== SUBAGENT`, which
+        // also includes legacy chats where the field is unset.
+        const filter = {
+            sessionKind: AgentSessionKind.ROOT
+        };
         if (params?.userId) {
+            // Chats visible to this user: owner, tenant owner, or participant (multi-user).
             filter.userId = params.userId;
         }
         if (params?.contextKey) {
             filter.contextKey = params.contextKey;
         }
-        // Build query options for sort and limit with defaults
+        if (params?.multiUser !== undefined) {
+            filter.multiUser = params.multiUser;
+        }
+        // Build query options for sort and limit with defaults.
         const options = {
             sort: {
                 field: params?.sortField ?? 'updatedAt',
                 order: params?.sortOrder ?? SortOrder.Desc
             },
+            skip: params?.skip,
             limit: params?.limit
         };
-        // Use aggregation to fetch chats with related messages
-        return this.chatRepository.findWithMessages(filter, options);
+        const [total, data] = await Promise.all([
+            this.chatRepository.count(filter),
+            this.chatRepository.find(filter, options)
+        ]);
+        return {
+            cursor: {
+                ...(params?.skip != null ? { skip: params.skip } : {}),
+                ...(params?.limit != null ? { limit: params.limit } : {}),
+                total
+            },
+            data
+        };
     }
     async getChat(chatId) {
         const chat = await this.chatRepository.findById(chatId);
         if (!chat) {
             throw new Error('Chat not found');
         }
-        const messages = await this.messageRepository.findByChatId(chatId);
-        return {
-            ...chat,
-            messages
-        };
+        return chat;
+    }
+    /**
+     * Get messages for a chat with optional cursor pagination.
+     * When limit is omitted, returns all messages (backward compatible).
+     * Messages are returned in chronological order (oldest → newest).
+     */
+    async getMessages(chatId, options) {
+        const chat = await this.chatRepository.findById(chatId);
+        if (!chat) {
+            throw new Error('Chat not found');
+        }
+        return this.messageRepository.findByChatIdPaginated(chatId, options);
     }
     async deleteChat(chatId) {
+        // Collect all subagent descendants BEFORE removing the parent, otherwise the
+        // `parentChatId` link is severed and we'd orphan the subtree. Subagents can
+        // themselves spawn subagents, so traversal must be recursive.
+        const descendantIds = await this.collectDescendantChatIds(chatId);
         const deleted = await this.chatRepository.delete(chatId);
         if (!deleted) {
             throw new Error('Chat not found');
         }
-        this.artifactStore.deleteArtifacts(chatId);
+        // Delete descendant chat rows in parallel. Use `Promise.allSettled` so a
+        // missing/already-deleted descendant doesn't abort cleanup of the rest.
+        if (descendantIds.length > 0) {
+            await Promise.allSettled(descendantIds.map(id => this.chatRepository.delete(id)));
+        }
+        const allIds = [chatId, ...descendantIds];
+        await Promise.all([
+            ...allIds.map(id => this.messageRepository.deleteByChatId(id)),
+            ...allIds.map(id => this.activityRepository.deleteByGroupId(id)),
+        ]);
+        for (const id of allIds) {
+            this.artifactStore.deleteArtifacts(id);
+        }
+    }
+    /**
+     * Walk the subagent tree rooted at `rootChatId` and return every descendant
+     * chat id (excluding the root itself). BFS, with parallel fan-out per level
+     * so deeply nested trees don't serialize one DB roundtrip per depth.
+     */
+    async collectDescendantChatIds(rootChatId) {
+        const descendants = [];
+        let frontier = [rootChatId];
+        while (frontier.length > 0) {
+            const childLists = await Promise.all(frontier.map(id => this.chatRepository.find({ parentChatId: id })));
+            const nextFrontier = [];
+            for (const list of childLists) {
+                for (const child of list) {
+                    descendants.push(child.id);
+                    nextFrontier.push(child.id);
+                }
+            }
+            frontier = nextFrontier;
+        }
+        return descendants;
     }
     async upsertAndGetChat(payload, excludeSocketId) {
-        const targetUserId = payload.userId ?? 'guest';
         let chat = null;
         if (payload.chatId) {
             chat = await this.chatRepository.findById(payload.chatId);
             if (!chat) {
                 throw new Error('Chat not found');
             }
-            // Ensure chat is associated with the caller's userId
-            if (chat.userId && chat.userId !== targetUserId) {
-                throw new Error('Chat does not belong to this user');
-            }
         }
         if (!chat) {
             chat = await this.createChat(payload, excludeSocketId);
@@ -92,7 +385,7 @@ export class ChatProcessor {
         if (!content) {
             return this.getTemporaryTitle(payload.contextKey);
         }
-        return AIHelper.generateTitleForMessage(payload.contextKey, [{
+        return this.aiHelper.generateTitleForMessage(payload.contextKey, [{
                 role: MessageRole.User,
                 content: content
             }]);
@@ -103,34 +396,38 @@ export class ChatProcessor {
             role,
             content: messageData.content,
             agentName: messageData.agentName,
+            sender: messageData.sender,
+            mentions: messageData.mentions ?? [],
+            annotations: messageData.annotations,
             attachments: attachments ?? [],
             reasoning: "",
             toolCalls: []
         });
-        if (chat.userId) {
-            socketService.emitMessageUpdate(chat.userId, message, excludeSocketId);
-        }
+        this.emitMessageToParticipants(chat, message, excludeSocketId);
         return message;
     }
     async createChat(payload, excludeSocketId) {
-        const targetUserId = payload.userId ?? 'guest';
+        const targetUserId = payload.userId ?? payload.tenants?.userId ?? 'guest';
         const contextKey = 'contextKey' in payload ? payload.contextKey : 'default';
         const metadata = 'metadata' in payload ? payload.metadata : {};
+        const requestedParticipantIds = 'participantIds' in payload && Array.isArray(payload.participantIds) ? payload.participantIds : [];
+        const participantIds = Array.from(new Set([targetUserId, ...requestedParticipantIds].filter(Boolean)));
         const chat = await this.chatRepository.create({
             title: this.getTemporaryTitle(contextKey),
             type: ChatType.Chat,
             status: AgentStatus.Streaming,
+            sessionKind: AgentSessionKind.ROOT,
             contextKey,
             userId: targetUserId,
+            tenants: {
+                ...(payload.tenants ?? {}),
+                userId: targetUserId,
+            },
+            participantIds,
             metadata,
             ...(payload.model ? { model: payload.model } : {})
         });
-        await kafkaService.sendChatTitleGenerationEvent(chat.id);
-        const initialChatResponse = {
-            ...chat,
-            messages: []
-        };
-        socketService.emitChatUpdate(targetUserId, initialChatResponse, excludeSocketId);
+        this.emitChatToParticipants(chat, chat, excludeSocketId);
         return chat;
     }
     /**
@@ -185,33 +482,163 @@ export class ChatProcessor {
         await this.messageRepository.update(message.id, { toolCalls });
         // Bump chat updatedAt so listChats ordering reflects the action.
         await this.chatRepository.update(chat.id, { updatedAt: now });
-        socketService.emitMessageUpdate(chat.userId, updatedMessage, params.excludeSocketId);
+        this.emitMessageToParticipants(chat, updatedMessage, params.excludeSocketId);
         if (params.systemMessage) {
             //todo discuss support for system messages
             //await this.createMessage(chat, MessageRole.System, params.systemMessage, undefined, params.excludeSocketId);
         }
         return { ok: true };
     }
+    /**
+     * Update selected fields (input/output/status) on a specific tool call.
+     */
+    async updateToolCall(params) {
+        if (params.input === undefined &&
+            params.output === undefined &&
+            params.status === undefined &&
+            params.subagentChatId === undefined) {
+            throw new Error('At least one tool call update field must be provided');
+        }
+        const chat = await this.chatRepository.findById(params.chatId);
+        if (!chat) {
+            throw new Error('Chat not found');
+        }
+        if (params.userId && !this.hasChatAccess(chat, params.userId)) {
+            throw new Error('Chat does not belong to this user');
+        }
+        const message = await this.messageRepository.findById(params.messageId);
+        if (!message || message.chat !== params.chatId) {
+            throw new Error('Message not found or does not belong to this chat');
+        }
+        const targetToolCall = (message.toolCalls ?? []).find((tc) => tc.id === params.toolCallId);
+        if (!targetToolCall) {
+            throw new Error('Tool call not found in message');
+        }
+        if (params.input !== undefined) {
+            await this.validateToolCallInput({
+                agentName: message.agentName,
+                toolName: targetToolCall.name,
+                input: params.input,
+            });
+        }
+        const updatedMessage = await this.messageRepository.updateToolCall(params.messageId, params.toolCallId, {
+            ...(params.input !== undefined ? { input: params.input } : {}),
+            ...(params.output !== undefined ? { output: params.output } : {}),
+            ...(params.status !== undefined ? { status: params.status } : {}),
+            ...(params.subagentChatId !== undefined ? { subagentChatId: params.subagentChatId } : {}),
+        });
+        if (!updatedMessage) {
+            throw new Error('Tool call not found in message');
+        }
+        const now = new Date().toISOString();
+        await this.chatRepository.update(chat.id, { updatedAt: now });
+        this.emitMessageToParticipants(chat, updatedMessage, params.excludeSocketId);
+        return updatedMessage;
+    }
+    async storeSubagentResponse(params) {
+        const { subagentChat, content, error, context, executionContext } = params;
+        if (!subagentChat.parentChatId || !subagentChat.parentMessageId) {
+            throw new Error(`Parent chat or message not found for subagent ${subagentChat.id}`);
+        }
+        const chat = await this.chatRepository.findById(subagentChat.parentChatId);
+        if (!chat) {
+            throw new Error(`Parent chat not found for subagent ${subagentChat.id}`);
+        }
+        const assistantMessage = await this.messageRepository.findById(subagentChat.parentMessageId);
+        if (!assistantMessage || assistantMessage.chat !== subagentChat.parentChatId) {
+            throw new Error(`Assistant message with id ${subagentChat.parentMessageId} not found`);
+        }
+        const toolCall = assistantMessage.toolCalls?.find(tc => tc.id === subagentChat.parentToolCallId);
+        if (!toolCall) {
+            throw new Error(`Tool call with id ${subagentChat.parentToolCallId} not found`);
+        }
+        if (error) {
+            toolCall.output = {
+                type: 'error',
+                message: error,
+            };
+            toolCall.status = AgentToolCallStatus.Failed;
+        }
+        else {
+            toolCall.output = content;
+            toolCall.status = AgentToolCallStatus.Succeeded;
+        }
+        await this.messageRepository.update(assistantMessage.id, assistantMessage);
+        const agentOptions = await this.aiHelper.getAgentOptions({
+            agentName: assistantMessage.agentName,
+            context: context,
+            executionContext: executionContext,
+        });
+        const executionTenants = this.getExecutionTenants(params);
+        const abortController = this.agentStore.registerAgentProcess(chat.id);
+        const existingMessages = await this.messageRepository.findByChatId(chat.id);
+        // Limit context to prevent exceeding token limits
+        const limitedMessages = ContextLimiter.limitContext(existingMessages, {
+            maxMessages: this.config.ai.maxContextMessages,
+            keepFirstUserMessage: true,
+            keepSystemMessages: true,
+        });
+        agentOptions.onStepFinish = (stepResult) => {
+            return this.storeStepActivity({
+                chat,
+                parentId: assistantMessage.activity,
+                stepResult,
+                name: ActivityOperationName.STEP_FINISHED,
+                sourceId: assistantMessage.id,
+                sourceType: 'AgentMessage',
+                tenants: executionTenants,
+            });
+        };
+        const userPreferences = await this.agentConfigRepository.findByUserIdAndAgentName(this.getChatUserId(chat) ?? chat.userId ?? 'guest', agentOptions.name);
+        agentOptions.activeTools = this.getAvailableTools(agentOptions, userPreferences);
+        await this.streamMessageStep({
+            chat,
+            existingMessages: limitedMessages,
+            assistantMessage,
+            agentOptions,
+            signal: abortController.signal,
+            tenants: executionTenants,
+            executionContext,
+            context,
+        });
+    }
     async streamMessageStep(params) {
         const { chat, assistantMessage, existingMessages, signal, excludeSocketId, agentOptions } = params;
+        const persistAndBroadcastToolCalls = async () => {
+            await this.messageRepository.update(assistantMessage.id, { toolCalls: assistantMessage.toolCalls ?? [] });
+            this.emitMessageToParticipants(chat, assistantMessage, excludeSocketId);
+            await this.agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Update, data: assistantMessage });
+        };
         if (signal.aborted) {
             return;
         }
-        const result = await AIHelper.streamAssistantResponse(existingMessages, signal, agentOptions);
+        const result = await this.aiHelper.streamAssistantResponse(existingMessages, signal, {
+            ...agentOptions,
+            executionContext: params.executionContext,
+        });
         try {
             for await (const chunk of result.fullStream) {
                 if (chunk.type === 'error') {
-                    await agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Error, data: chunk.error });
+                    await this.agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Error, data: chunk.error });
                     assistantMessage.content = chunk.error.message || 'Sorry, I cannot process you request due to the error';
                     await this.messageRepository.update(assistantMessage.id, assistantMessage);
-                    await this.chatRepository.update(chat.id, { status: AgentStatus.Error });
+                    await this.updateChatAndEmit(chat, { status: AgentStatus.Error }, excludeSocketId);
+                    if (chat.sessionKind === AgentSessionKind.SUBAGENT) {
+                        await this.storeSubagentResponse({
+                            subagentChat: chat,
+                            content: undefined,
+                            error: chunk.error,
+                            context: params.context,
+                            executionContext: params.executionContext,
+                        });
+                    }
                     continue;
                 }
                 if (chunk.type === 'abort') {
-                    await agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Aborted, data: undefined });
-                    await this.chatRepository.update(chat.id, { status: AgentStatus.Aborted });
+                    await this.agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Aborted, data: undefined });
+                    await this.updateChatAndEmit(chat, { status: AgentStatus.Aborted }, excludeSocketId);
                     await this.messageRepository.update(assistantMessage.id, assistantMessage);
-                    socketService.emitMessageUpdate(chat.userId, assistantMessage, excludeSocketId);
+                    this.emitMessageToParticipants(chat, assistantMessage, excludeSocketId);
                     continue;
                 }
                 if (chunk.type === 'finish') {
@@ -228,38 +655,76 @@ export class ChatProcessor {
                             ((totalUsage.promptTokens ?? 0) + (totalUsage.completionTokens ?? 0));
                     }
                     await this.messageRepository.update(assistantMessage.id, { ...assistantMessage });
+                    this.emitMessageToParticipants(chat, assistantMessage, excludeSocketId);
                     if (chunk.finishReason === 'stop') {
-                        if (assistantMessage.toolCalls?.some(toolCall => toolCall.requiresConfirmation && toolCall.approvalId && !toolCall.output)) {
-                            await this.chatRepository.update(chat.id, { status: AgentStatus.WaitingForUserAction });
+                        let nextChat = await this.updateChatAndEmit(chat, { status: AgentStatus.Finished }, excludeSocketId);
+                        if (chat.title && this.isTemporaryTitle(chat.title)) {
+                            const title = await this.aiHelper.generateTitleForMessage(chat.contextKey, existingMessages.filter(m => m.role === MessageRole.User), (stepResult) => {
+                                return this.storeStepActivity({
+                                    chat,
+                                    stepResult,
+                                    name: ActivityOperationName.TITLE_GENERATION,
+                                    sourceId: chat.id,
+                                    sourceType: 'Chat',
+                                    tenants: params.tenants || {},
+                                });
+                            }, params.executionContext);
+                            nextChat = await this.updateChatAndEmit(nextChat, { title }, excludeSocketId);
                         }
-                        else if (!assistantMessage.content && assistantMessage.toolCalls?.length && assistantMessage.toolCalls[assistantMessage.toolCalls?.length - 1].output) {
-                            // handle tool-calls stop, openrouter provider does not return valid type
-                            await agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Update, data: assistantMessage });
-                            await this.streamMessageStep(params);
-                            continue;
-                        }
-                        else {
-                            await this.chatRepository.update(chat.id, { status: AgentStatus.Finished });
+                        if (chat.sessionKind === AgentSessionKind.SUBAGENT) {
+                            await this.storeSubagentResponse({
+                                subagentChat: chat,
+                                content: assistantMessage.content,
+                                error: undefined,
+                                context: params.context,
+                                executionContext: params.executionContext,
+                            });
                         }
-                        await agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Finished, data: assistantMessage });
-                        continue;
                     }
                     if (chunk.finishReason === 'tool-calls') {
-                        if (assistantMessage.toolCalls?.some(toolCall => toolCall.requiresConfirmation && toolCall.approvalId && !toolCall.output)) {
-                            await this.chatRepository.update(chat.id, { status: AgentStatus.WaitingForUserAction });
-                            await agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Finished, data: assistantMessage });
+                        const toolCall = assistantMessage.toolCalls?.find(toolCall => toolCall.output === undefined && toolCall.status === AgentToolCallStatus.Running);
+                        if (!toolCall) {
+                            await this.agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Finished, data: assistantMessage });
+                            await this.storeSubagentResponse({
+                                subagentChat: chat,
+                                content: JSON.stringify(assistantMessage.toolCalls),
+                                error: undefined,
+                                context: params.context,
+                                executionContext: params.executionContext,
+                            });
+                            continue;
+                        }
+                        const toolConfig = ConfigStore.getInstance().getToolConfig(assistantMessage.agentName || '', toolCall.name);
+                        if (toolCall.requiresConfirmation && toolCall.approvalId) {
+                            await this.updateChatAndEmit(chat, { status: AgentStatus.WaitingForUserAction }, excludeSocketId);
+                            await this.agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Finished, data: assistantMessage });
                         }
-                        else {
-                            await agentStore.shareAgentProcessEvent(chat.id, {
-                                type: AgentProcessEventType.Update,
-                                data: assistantMessage
+                        else if (toolConfig && toolConfig.type === AgentToolType.SUBAGENT) {
+                            void this.startSubagentProcess({
+                                parentChat: chat,
+                                parentMessage: assistantMessage,
+                                parentToolCallId: toolCall.id,
+                                toolName: toolCall.name,
+                                input: toolCall.input,
+                                subAgentConfig: toolConfig.data.subAgent,
+                                context: params.context,
+                                executionContext: params.executionContext,
+                            }).catch(error => {
+                                logger.error(error);
+                                //todo: store error in response
                             });
-                            await this.streamMessageStep(params);
                         }
-                        continue;
                     }
                     //todo: Handle other finish reasons // length, content, error, other, undefined
-                    await agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Finished, data: assistantMessage });
+                    await this.agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Finished, data: assistantMessage });
+                    if (assistantMessage.activity) {
+                        const groupedMeta = await this.activityRepository.getGroupedMetadataByParentId(assistantMessage.activity);
+                        await this.activityRepository.updateMetadata(assistantMessage.activity, {
+                            usage: groupedMeta,
+                            finishReason: chunk.finishReason,
+                            responseTimestamp: new Date().toISOString(),
+                        });
+                    }
                     continue;
                 }
                 if (chunk.type === 'text-delta') {
@@ -268,55 +733,85 @@ export class ChatProcessor {
                         ...assistantMessage,
                         content: assistantMessage.content
                     };
-                    socketService.emitMessageUpdate(chat.userId, updatedMessage, excludeSocketId);
-                    await agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Update, data: updatedMessage });
+                    this.emitMessageToParticipants(chat, updatedMessage, excludeSocketId);
+                    await this.agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Update, data: updatedMessage });
                     await this.messageRepository.update(assistantMessage.id, { content: assistantMessage.content });
                     continue;
                 }
                 if (chunk.type === 'tool-input-start') {
                     if (!assistantMessage.toolCalls)
                         assistantMessage.toolCalls = [];
-                    assistantMessage.toolCalls.push({
-                        id: chunk.id,
-                        name: chunk.toolName,
-                        status: AgentToolCallStatus.Pending,
-                        input: {},
-                    });
+                    const existingToolCall = assistantMessage.toolCalls.find((toolCall) => toolCall.id === chunk.id);
+                    if (existingToolCall) {
+                        existingToolCall.name = chunk.toolName;
+                        if (!existingToolCall.status) {
+                            existingToolCall.status = AgentToolCallStatus.Pending;
+                        }
+                        existingToolCall.input = existingToolCall.input ?? {};
+                    }
+                    else {
+                        assistantMessage.toolCalls.push({
+                            id: chunk.id,
+                            name: chunk.toolName,
+                            status: AgentToolCallStatus.Pending,
+                            input: {},
+                        });
+                    }
+                    await persistAndBroadcastToolCalls();
                     continue;
                 }
-                if (chunk.type === 'tool-call') { //Todo possible place to handle user-approval
-                    const toolCall = assistantMessage.toolCalls?.find(toolCall => toolCall.id === chunk.toolCallId);
-                    if (toolCall) {
+                if (chunk.type === 'tool-call') {
+                    if (!assistantMessage.toolCalls)
+                        assistantMessage.toolCalls = [];
+                    let toolCall = assistantMessage.toolCalls.find(toolCall => toolCall.id === chunk.toolCallId);
+                    if (!toolCall) {
+                        toolCall = {
+                            id: chunk.toolCallId,
+                            name: chunk.toolName,
+                            status: AgentToolCallStatus.Running,
+                            input: chunk.input,
+                        };
+                        assistantMessage.toolCalls.push(toolCall);
+                    }
+                    else {
                         toolCall.status = AgentToolCallStatus.Running;
                         toolCall.input = chunk.input;
                     }
+                    await persistAndBroadcastToolCalls();
                     continue;
                 }
                 if (chunk.type === 'tool-error') {
                     const toolCall = assistantMessage.toolCalls?.find(toolCall => toolCall.id === chunk.toolCallId);
                     if (toolCall) {
                         toolCall.status = AgentToolCallStatus.Failed;
-                        toolCall.error = JSON.stringify(chunk.error);
+                        toolCall.error = chunk.error.message || JSON.stringify(chunk.error);
+                        await persistAndBroadcastToolCalls();
                     }
                     continue;
                 }
                 if (chunk.type === 'tool-approval-request') {
                     const toolCall = assistantMessage.toolCalls?.find(toolCall => toolCall.id === chunk.toolCall.toolCallId);
                     if (toolCall) {
+                        const toolConfig = ConfigStore.getInstance().getToolConfig(assistantMessage.agentName || '', toolCall.name);
+                        if (toolConfig && toolConfig.type === AgentToolType.SUBAGENT) {
+                            // TODO: allow needsApproval flow for the subagents too
+                            continue;
+                        }
                         toolCall.requiresConfirmation = true;
                         toolCall.approvalId = chunk.approvalId;
+                        if (toolCall.name === AgentToolType.REQUEST_CLARIFICATION) {
+                            toolCall.requiresUserAction = true;
+                        }
+                        await persistAndBroadcastToolCalls();
                     }
                     continue;
                 }
                 if (chunk.type === 'tool-result') {
                     const toolCall = assistantMessage.toolCalls?.find(toolCall => toolCall.id === chunk.toolCallId);
                     if (toolCall) {
-                        if (chunk.output.requiresApproval) {
-                            toolCall.requiresConfirmation = true;
-                            continue;
-                        }
                         toolCall.status = AgentToolCallStatus.Succeeded;
                         toolCall.output = chunk.output;
+                        await persistAndBroadcastToolCalls();
                     }
                     continue;
                 }
@@ -324,9 +819,9 @@ export class ChatProcessor {
                     if (!assistantMessage.reasoning)
                         assistantMessage.reasoning = '';
                     assistantMessage.reasoning += chunk.text;
-                    socketService.emitMessageUpdate(chat.userId, assistantMessage, excludeSocketId);
+                    this.emitMessageToParticipants(chat, assistantMessage, excludeSocketId);
                     await this.messageRepository.update(assistantMessage.id, { reasoning: assistantMessage.reasoning });
-                    await agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Update, data: assistantMessage });
+                    await this.agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Update, data: assistantMessage });
                     continue;
                 }
             }
@@ -335,7 +830,7 @@ export class ChatProcessor {
             if (streamError instanceof Error && streamError.name === 'AbortError') {
                 return;
             }
-            await agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Error, data: streamError });
+            await this.agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Error, data: streamError });
             throw streamError;
         }
     }
@@ -347,9 +842,10 @@ export class ChatProcessor {
         if (!assistantMessage || assistantMessage.chat !== chat.id) {
             throw new Error(`Assistant message with id ${payload.messageId} not found`);
         }
-        const agentOptions = await AIHelper.getAgentOptions({
+        const agentOptions = await this.aiHelper.getAgentOptions({
             agentName: assistantMessage.agentName,
-            context: payload.context
+            context: payload.context,
+            executionContext: payload.executionContext,
         });
         const toolCall = assistantMessage.toolCalls?.find(tc => tc.approvalId === payload.approvalId);
         if (!toolCall) {
@@ -360,14 +856,20 @@ export class ChatProcessor {
             };
         }
         toolCall.approved = payload.approved;
-        toolCall.reason = payload.reason;
+        toolCall.userResponse = payload.userResponse;
         if (!toolCall.approved) {
             toolCall.output = {
                 type: 'execution-denied',
-                reason: toolCall.reason
+                reason: toolCall.userResponse
             };
             toolCall.status = AgentToolCallStatus.Failed;
         }
+        else if (toolCall.requiresUserAction) {
+            toolCall.output = {
+                userResponse: toolCall.userResponse
+            };
+            toolCall.status = AgentToolCallStatus.Succeeded;
+        }
         else {
             const executeFunction = agentOptions.tools?.[toolCall.name]?.execute;
             if (executeFunction) {
@@ -399,33 +901,333 @@ export class ChatProcessor {
         };
     }
     async processNewUserMessage(chat, payload, prevMessages, excludeSocketId) {
+        const executionTenants = this.getExecutionTenants(payload);
+        const chatUserId = this.getChatUserId(chat) ?? 'guest';
         const userMessage = await this.createMessage(chat, MessageRole.User, { content: payload.content, agentName: undefined }, payload.attachments);
-        await agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Update, data: userMessage });
-        const agentOptions = await AIHelper.getAgentOptions({
+        await this.agentStore.shareAgentProcessEvent(chat.id, { type: AgentProcessEventType.Update, data: userMessage });
+        let assistantMessage = await this.createMessage(chat, MessageRole.Assistant, { content: '', agentName: undefined }, undefined, excludeSocketId);
+        const parentActivity = await this.activityRepository.create({
+            ownerId: chatUserId,
+            groupId: chat.id,
+            name: ActivityOperationName.MESSAGE_PROCESSING,
+            tenants: executionTenants,
+            sourceId: userMessage.id,
+            sourceType: 'AgentMessage',
+            metadata: {
+                contextKey: chat.contextKey,
+                modelId: this.aiHelper.getLanguageModelId(chat.model),
+            },
+        });
+        const agentOptions = await this.aiHelper.getAgentOptions({
             contextKey: chat.contextKey,
-            messages: await AIHelper.convertMessages([...prevMessages, userMessage], true),
+            messages: [...prevMessages, userMessage],
             context: payload.context,
             agentName: undefined,
             modelId: chat.model,
+            executionContext: payload.executionContext,
+        }, {
+            onStepFinish: async (stepResult) => {
+                await this.storeStepActivity({
+                    chat,
+                    parentId: parentActivity.id,
+                    stepResult,
+                    name: ActivityOperationName.AGENT_SELECTION,
+                    sourceId: userMessage.id,
+                    sourceType: 'AgentMessage',
+                    tenants: executionTenants,
+                });
+            }
         });
-        const assistantMessage = await this.createMessage(chat, MessageRole.Assistant, { content: ' ', agentName: agentOptions.name }, undefined, excludeSocketId);
-        assistantMessage.content = '';
+        const updatedAssistantMessage = await this.messageRepository.update(assistantMessage.id, {
+            agentName: agentOptions.name,
+            activity: parentActivity.id
+        });
+        await this.activityRepository.update(parentActivity.id, {
+            metadata: {
+                ...parentActivity.metadata,
+                agentOptions: {
+                    name: agentOptions.name,
+                    modelId: this.aiHelper.getLanguageModelId(agentOptions.model),
+                    temperature: agentOptions.temperature,
+                    maxOutputTokens: agentOptions.maxOutputTokens,
+                    topP: agentOptions.topP,
+                    topK: agentOptions.topK,
+                    presencePenalty: agentOptions.presencePenalty,
+                    frequencyPenalty: agentOptions.frequencyPenalty,
+                    stopSequences: agentOptions.stopSequences,
+                    seed: agentOptions.seed,
+                },
+            },
+        });
+        if (!updatedAssistantMessage) {
+            throw new Error(`Assistant message with id ${assistantMessage.id} not found after update`);
+        }
+        assistantMessage = updatedAssistantMessage;
         return {
             userMessage,
             assistantMessage,
             agentOptions,
         };
     }
+    getAgentNamesForContext(contextKey) {
+        try {
+            return ConfigStore.getInstance().getAgentsForContext(contextKey).map((config) => config.name);
+        }
+        catch {
+            return [];
+        }
+    }
+    normalizeMentionName(value) {
+        return value.trim().replace(/^@/, '').toLowerCase();
+    }
+    extractMentionNames(content) {
+        const mentions = content.matchAll(/(^|[\s([{])@([a-zA-Z0-9_.-]+)/g);
+        return Array.from(mentions, (match) => match[2]).filter(Boolean);
+    }
+    getExplicitAgentMention(params) {
+        const agentNames = this.getAgentNamesForContext(params.contextKey);
+        const normalizedAgentNames = new Map(agentNames.map((name) => [this.normalizeMentionName(name), name]));
+        for (const mention of params.mentions ?? []) {
+            if (mention.type !== 'agent')
+                continue;
+            const normalized = this.normalizeMentionName(mention.name);
+            return { mentioned: true, agentName: normalizedAgentNames.get(normalized) };
+        }
+        for (const name of this.extractMentionNames(params.content)) {
+            const normalized = this.normalizeMentionName(name);
+            if (normalized === 'agent') {
+                return { mentioned: true };
+            }
+            const agentName = normalizedAgentNames.get(normalized);
+            if (agentName) {
+                return { mentioned: true, agentName };
+            }
+        }
+        return { mentioned: false };
+    }
+    hasNonAgentMention(params) {
+        const agentNames = this.getAgentNamesForContext(params.contextKey);
+        const normalizedAgentNames = new Set(['agent', ...agentNames.map((name) => this.normalizeMentionName(name))]);
+        if ((params.mentions ?? []).some((mention) => mention.type === 'user')) {
+            return true;
+        }
+        return this.extractMentionNames(params.content).some((name) => {
+            const normalized = this.normalizeMentionName(name);
+            return !normalizedAgentNames.has(normalized);
+        });
+    }
+    renderMessageForDecision(message) {
+        const sender = message.sender?.displayName || message.sender?.id || message.agentName || message.role;
+        return `${sender}: ${message.content}`;
+    }
+    async analyzeAgentShouldRespond(params) {
+        try {
+            const recentMessages = [...params.previousMessages.slice(-8), params.userMessage]
+                .map((message) => this.renderMessageForDecision(message))
+                .join('\n');
+            const response = await this.aiHelper.getAssistantResponse([
+                {
+                    role: MessageRole.User,
+                    content: `Conversation:\n${recentMessages}\n\nShould the AI agent respond to the latest message?`
+                }
+            ], {
+                system: [
+                    'You decide whether an AI agent should reply in a multi-user chat.',
+                    'Reply with exactly YES or NO.',
+                    'YES only when the latest message asks for help, requests agent action, or is clearly addressed to the AI.',
+                    'NO when the latest message is human-to-human chatter, status, acknowledgement, or otherwise does not need the AI.'
+                ].join('\n'),
+                temperature: 0,
+                maxOutputTokens: 5,
+                model: params.chat.model,
+                executionContext: params.executionContext
+            });
+            return /^yes\b/i.test(response.trim());
+        }
+        catch (error) {
+            logger.warn({ error, chatId: params.chat.id }, 'Agent response decision failed');
+            return false;
+        }
+    }
+    async shouldRunAgentForMultiUserMessage(params) {
+        const firstUserMessage = !params.previousMessages.some((message) => message.role === MessageRole.User);
+        if (firstUserMessage) {
+            return { shouldRun: true };
+        }
+        const explicitAgent = this.getExplicitAgentMention({
+            content: params.payload.content,
+            mentions: params.payload.mentions,
+            contextKey: params.chat.contextKey,
+        });
+        if (explicitAgent.mentioned) {
+            return { shouldRun: true, agentName: explicitAgent.agentName };
+        }
+        if (this.hasNonAgentMention({
+            content: params.payload.content,
+            mentions: params.payload.mentions,
+            contextKey: params.chat.contextKey,
+        })) {
+            return { shouldRun: false };
+        }
+        const shouldRun = await this.analyzeAgentShouldRespond({
+            chat: params.chat,
+            previousMessages: params.previousMessages,
+            userMessage: params.userMessage,
+            executionContext: params.payload.executionContext,
+        });
+        return { shouldRun };
+    }
+    async prepareAgentResponseForUserMessage(chat, payload, prevMessages, userMessage, excludeSocketId, agentName) {
+        const executionTenants = this.getExecutionTenants(payload);
+        let assistantMessage = await this.createMessage(chat, MessageRole.Assistant, {
+            content: '',
+            agentName: agentName,
+            sender: {
+                id: agentName ?? 'agent',
+                type: 'agent',
+                displayName: agentName ?? 'Agent',
+            }
+        }, undefined, excludeSocketId);
+        const ownerId = payload.userId ?? chat.userId ?? this.getChatUserId(chat) ?? 'guest';
+        const parentActivity = await this.activityRepository.create({
+            ownerId,
+            groupId: chat.id,
+            name: ActivityOperationName.MESSAGE_PROCESSING,
+            tenants: executionTenants,
+            sourceId: userMessage.id,
+            sourceType: 'AgentMessage',
+            metadata: {
+                contextKey: chat.contextKey,
+                modelId: this.aiHelper.getLanguageModelId(chat.model),
+            },
+        });
+        const agentOptions = await this.aiHelper.getAgentOptions(agentName
+            ? {
+                agentName,
+                modelId: chat.model,
+                context: payload.context,
+                executionContext: payload.executionContext,
+            }
+            : {
+                contextKey: chat.contextKey,
+                messages: [...prevMessages, userMessage],
+                context: payload.context,
+                agentName: undefined,
+                modelId: chat.model,
+                executionContext: payload.executionContext,
+            }, {
+            onStepFinish: async (stepResult) => {
+                await this.storeStepActivity({
+                    chat,
+                    parentId: parentActivity.id,
+                    stepResult,
+                    name: ActivityOperationName.AGENT_SELECTION,
+                    sourceId: userMessage.id,
+                    sourceType: 'AgentMessage',
+                    tenants: executionTenants,
+                });
+            }
+        });
+        const updatedAssistantMessage = await this.messageRepository.update(assistantMessage.id, {
+            agentName: agentOptions.name,
+            activity: parentActivity.id,
+            sender: {
+                id: agentOptions.name,
+                type: 'agent',
+                displayName: agentOptions.name,
+            }
+        });
+        await this.activityRepository.update(parentActivity.id, {
+            metadata: {
+                ...parentActivity.metadata,
+                agentOptions: {
+                    name: agentOptions.name,
+                    modelId: this.aiHelper.getLanguageModelId(agentOptions.model),
+                    temperature: agentOptions.temperature,
+                    maxOutputTokens: agentOptions.maxOutputTokens,
+                    topP: agentOptions.topP,
+                    topK: agentOptions.topK,
+                    presencePenalty: agentOptions.presencePenalty,
+                    frequencyPenalty: agentOptions.frequencyPenalty,
+                    stopSequences: agentOptions.stopSequences,
+                    seed: agentOptions.seed,
+                },
+            },
+        });
+        if (!updatedAssistantMessage) {
+            throw new Error(`Assistant message with id ${assistantMessage.id} not found after update`);
+        }
+        assistantMessage = updatedAssistantMessage;
+        return {
+            assistantMessage,
+            agentOptions,
+            executionTenants,
+        };
+    }
+    async streamAgentResponseForUserMessage(params) {
+        const { assistantMessage, agentOptions, executionTenants } = await this.prepareAgentResponseForUserMessage(params.chat, params.payload, params.previousMessages, params.userMessage, params.excludeSocketId, params.agentName);
+        const messagesForAgent = [...params.previousMessages, params.userMessage];
+        agentOptions.onStepFinish = (stepResult) => {
+            return this.storeStepActivity({
+                chat: params.chat,
+                parentId: assistantMessage.activity,
+                stepResult,
+                name: ActivityOperationName.STEP_FINISHED,
+                sourceId: assistantMessage.id,
+                sourceType: 'AgentMessage',
+                tenants: executionTenants,
+            });
+        };
+        const userPreferences = await this.agentConfigRepository.findByUserIdAndAgentName(params.payload.userId ?? params.chat.userId ?? this.getChatUserId(params.chat) ?? 'guest', agentOptions.name);
+        agentOptions.activeTools = this.getAvailableTools(agentOptions, userPreferences);
+        await this.streamMessageStep({
+            chat: params.chat,
+            existingMessages: messagesForAgent,
+            assistantMessage,
+            agentOptions,
+            excludeSocketId: params.excludeSocketId,
+            signal: params.signal,
+            tenants: executionTenants,
+            executionContext: params.payload.executionContext,
+            context: params.payload.context,
+        });
+    }
+    async storeStepActivity(params) {
+        try {
+            const stepResult = params.stepResult;
+            const mergedUsage = this.mergeUsageWithProviderMetadata(stepResult.usage, stepResult.providerMetadata);
+            const activity = await this.activityRepository.create({
+                ownerId: this.getChatUserId(params.chat) ?? 'guest',
+                groupId: params.chat.id,
+                name: params.name,
+                tenants: params.tenants || {},
+                sourceId: params.sourceId,
+                sourceType: params.sourceType,
+                metadata: {
+                    finishReason: stepResult.finishReason,
+                    usage: mergedUsage,
+                    responseTimestamp: stepResult.response.timestamp,
+                    modelId: stepResult.response.modelId,
+                    messages: this.debug ? stepResult.request?.body?.messages : undefined,
+                },
+                parentId: params.parentId,
+            });
+        }
+        catch (error) {
+            logger.error({ error, chatId: params.chat.id, parentId: params.parentId }, 'Failed to store step activity');
+        }
+    }
     async streamMessage(chat, payload, excludeSocketId, onAgentStart) {
         try {
-            const abortController = agentStore.registerAgentProcess(chat.id);
+            const executionTenants = this.getExecutionTenants(payload);
+            const abortController = this.agentStore.registerAgentProcess(chat.id);
             onAgentStart?.();
             let assistantMessage;
             let agentOptions;
             const existingMessages = await this.messageRepository.findByChatId(chat.id);
             // Limit context to prevent exceeding token limits
             const limitedMessages = ContextLimiter.limitContext(existingMessages, {
-                maxMessages: config.ai.maxContextMessages,
+                maxMessages: this.config.ai.maxContextMessages,
                 keepFirstUserMessage: true,
                 keepSystemMessages: true,
             });
@@ -447,6 +1249,19 @@ export class ChatProcessor {
                 agentOptions = result.agentOptions;
                 limitedMessages.push(result.userMessage);
             }
+            agentOptions.onStepFinish = (stepResult) => {
+                return this.storeStepActivity({
+                    chat,
+                    parentId: assistantMessage.activity,
+                    stepResult,
+                    name: ActivityOperationName.STEP_FINISHED,
+                    sourceId: assistantMessage.id,
+                    sourceType: 'AgentMessage',
+                    tenants: executionTenants,
+                });
+            };
+            const userPreferences = await this.agentConfigRepository.findByUserIdAndAgentName(this.getChatUserId(chat) ?? 'guest', agentOptions.name);
+            agentOptions.activeTools = this.getAvailableTools(agentOptions, userPreferences);
             await this.streamMessageStep({
                 chat,
                 existingMessages: limitedMessages,
@@ -454,12 +1269,30 @@ export class ChatProcessor {
                 agentOptions,
                 excludeSocketId: excludeSocketId,
                 signal: abortController.signal,
+                tenants: executionTenants,
+                executionContext: payload.executionContext,
+                context: payload.context,
             });
         }
         catch (error) {
             throw error;
         }
     }
+    getAvailableTools(agentOptions, userPreferences) {
+        const toolNames = Object.keys(agentOptions.tools || {});
+        const availableToolsMap = Object.fromEntries(toolNames.map(key => [key, true]));
+        const agentsConfiguration = ConfigStore.getInstance().getAgentConfigByName(agentOptions.name);
+        agentsConfiguration.tools.forEach((tool) => {
+            const toolTitle = getAgentToolName(tool);
+            if (tool.disabledByDefault) {
+                availableToolsMap[toolTitle] = false;
+            }
+            if (tool.userConfigurable && userPreferences?.tools?.[toolTitle] !== undefined) {
+                availableToolsMap[toolTitle] = userPreferences.tools[toolTitle];
+            }
+        });
+        return Object.keys(availableToolsMap).filter(key => availableToolsMap[key]);
+    }
     listArtifacts(chatId) {
         return this.artifactStore.listArtifacts(chatId);
     }
@@ -490,7 +1323,7 @@ export class ChatProcessor {
                 return null;
         }
     }
-    getMessageStream(chatId) {
+    getMessageStream(chatId, signal) {
         const stream = new PassThrough();
         let ended = false;
         const endStream = (error) => {
@@ -511,13 +1344,15 @@ export class ChatProcessor {
             }
         };
         const pushChunk = (chunk) => {
-            if (ended || stream.destroyed || stream.writableEnded)
+            if (ended || stream.destroyed || stream.writableEnded || signal?.aborted)
                 return;
             stream.write(`data: ${JSON.stringify(chunk)}\n\n`);
         };
         const listener = (event) => {
-            if (ended)
+            if (signal?.aborted) {
+                endStream();
                 return;
+            }
             try {
                 const chunk = this.eventToChunk(event);
                 if (chunk) {
@@ -527,7 +1362,6 @@ export class ChatProcessor {
                     event.type === AgentProcessEventType.Error ||
                     event.type === AgentProcessEventType.Aborted) {
                     endStream();
-                    agentStore.removeListener(chatId, listener);
                 }
             }
             catch (err) {
@@ -536,21 +1370,18 @@ export class ChatProcessor {
                     error: err instanceof Error ? err.message : 'Unknown error occurred',
                 });
                 endStream(err);
-                agentStore.removeListener(chatId, listener);
             }
         };
-        // Cleanup on consumer side closing
         const closeHandler = () => {
-            agentStore.removeListener(chatId, listener);
+            this.agentStore.removeListener(chatId, listener);
         };
         const errorHandler = (err) => {
-            logger.error({ err }, 'Readable stream error');
-            agentStore.removeListener(chatId, listener);
+            signal?.removeEventListener('abort', endStream);
             endStream(err);
         };
         stream.on('close', closeHandler);
         stream.on('error', errorHandler);
-        const listenerAttached = agentStore.addListener(chatId, listener);
+        const listenerAttached = this.agentStore.addListener(chatId, listener);
         if (!listenerAttached) {
             // Remove stream listeners if listener attachment failed to prevent memory leak
             stream.removeListener('close', closeHandler);
@@ -559,50 +1390,107 @@ export class ChatProcessor {
         }
         return stream;
     }
-    async createMessageStream(payload, excludeSocketId) {
-        const stream = new PassThrough();
-        (async () => {
-            try {
-                const chat = await this.upsertAndGetChat(payload, excludeSocketId);
-                // Send chat metadata first
-                if (!('chatId' in payload) && !('messageId' in payload) && chat) {
-                    stream.write(`data: ${JSON.stringify({
-                        type: StreamChunkType.Chat,
-                        chatId: chat.id,
-                        chat,
-                    })}\n\n`);
-                }
-                await this.streamMessage(chat, payload, excludeSocketId, async () => {
-                    if (stream.destroyed || stream.writableEnded) {
-                        return;
-                    }
-                    const messageStream = this.getMessageStream(chat.id);
-                    // If client disconnects, destroy inner stream
-                    stream.on('close', () => {
-                        if (!messageStream.destroyed) {
-                            messageStream.destroy();
-                        }
-                    });
-                    await pipelineAsync(messageStream, stream);
-                });
+    async upsertAndGetMultiUserChat(payload, excludeSocketId) {
+        const targetUserId = payload.userId ?? 'guest';
+        let chat = null;
+        let isNewChat = false;
+        if (payload.chatId) {
+            chat = await this.chatRepository.findById(payload.chatId);
+            if (!chat) {
+                throw new Error('Chat not found');
             }
-            catch (error) {
-                logger.error({ error }, 'createMessageStream failed');
-                if (!stream.destroyed && !stream.writableEnded) {
-                    stream.write(`data: ${JSON.stringify({
-                        type: StreamChunkType.Error,
-                        error: error instanceof Error ? error.message : 'Unknown error occurred',
-                    })}\n\n`);
-                    stream.write('data: [DONE]\n\n');
-                    stream.end();
-                }
+            if (!this.hasChatAccess(chat, targetUserId)) {
+                throw new Error('Chat does not belong to this user');
+            }
+            const participantIds = Array.from(new Set([
+                ...this.getParticipantIds(chat),
+                ...(payload.participantIds ?? []),
+                targetUserId,
+            ].filter(Boolean)));
+            const updates = {};
+            if (participantIds.length !== this.getParticipantIds(chat).length) {
+                updates.participantIds = participantIds;
+            }
+            if ('model' in payload) {
+                updates.model = payload.model || undefined;
             }
-        })().catch((err) => {
-            logger.error({ err }, 'Unhandled stream task error');
-            if (!stream.destroyed)
-                stream.destroy(err);
+            if (Object.keys(updates).length > 0) {
+                chat = await this.updateChatAndEmit(chat, updates, excludeSocketId);
+            }
+        }
+        if (!chat) {
+            chat = await this.createChat(payload, excludeSocketId);
+            isNewChat = true;
+        }
+        return { chat, isNewChat };
+    }
+    async postMultiUserMessage(payload, excludeSocketId) {
+        const { chat } = await this.upsertAndGetMultiUserChat(payload, excludeSocketId);
+        const existingMessages = await this.messageRepository.findByChatId(chat.id);
+        const sender = {
+            id: payload.userId ?? 'guest',
+            type: 'user',
+            ...(payload.senderDisplayName ? { displayName: payload.senderDisplayName } : {}),
+            ...(payload.senderAvatarUrl ? { avatarUrl: payload.senderAvatarUrl } : {}),
+        };
+        const userMessage = await this.createMessage(chat, MessageRole.User, {
+            content: payload.content,
+            agentName: undefined,
+            sender,
+            mentions: payload.mentions ?? [],
+        }, payload.attachments, excludeSocketId);
+        const decision = await this.shouldRunAgentForMultiUserMessage({
+            chat,
+            previousMessages: existingMessages,
+            userMessage,
+            payload,
+        });
+        if (!decision.shouldRun) {
+            const updatedChat = await this.updateChatAndEmit(chat, { status: AgentStatus.Finished }, excludeSocketId);
+            return { chat: updatedChat, message: userMessage, agentTriggered: false };
+        }
+        const updatedChat = await this.updateChatAndEmit(chat, { status: AgentStatus.Streaming }, undefined);
+        const abortController = this.agentStore.registerAgentProcess(chat.id);
+        const limitedMessages = ContextLimiter.limitContext(existingMessages, {
+            maxMessages: this.config.ai.maxContextMessages,
+            keepFirstUserMessage: true,
+            keepSystemMessages: true,
+        });
+        void this.streamAgentResponseForUserMessage({
+            chat,
+            payload,
+            previousMessages: limitedMessages,
+            userMessage,
+            excludeSocketId: undefined,
+            signal: abortController.signal,
+            agentName: decision.agentName,
+        }).catch(async (error) => {
+            logger.error({ error, chatId: chat.id }, 'Multi-user background agent flow failed');
+            await this.updateChatAndEmit(chat, { status: AgentStatus.Error }, undefined);
+        });
+        return { chat: updatedChat, message: userMessage, agentTriggered: true };
+    }
+    async createMessageStream(payload, excludeSocketId, signal) {
+        const stream = new PassThrough();
+        this.runMessageStream(stream, payload, excludeSocketId, signal)
+            .catch(err => {
+            logger.error({ err }, 'Stream task failed');
         });
         return stream;
     }
+    async runMessageStream(stream, payload, excludeSocketId, signal) {
+        const chat = await this.upsertAndGetChat(payload, excludeSocketId);
+        if (!('chatId' in payload) && !('messageId' in payload) && chat) {
+            stream.write(`data: ${JSON.stringify({
+                type: StreamChunkType.Chat,
+                chatId: chat.id,
+                chat,
+            })}\n\n`);
+        }
+        await this.streamMessage(chat, payload, excludeSocketId, () => {
+            const messageStream = this.getMessageStream(chat.id, signal);
+            messageStream.pipe(stream);
+        });
+    }
 }
 //# sourceMappingURL=ChatProcessor.js.map