agent-world 0.12.3 → 0.15.0

package/dist/core/llm-manager.js

@@ -94,6 +94,16 @@
  * - Queue-based serialization prevents API rate limits and resource conflicts
  *
  * Recent Changes:
+ * - 2026-03-13: Added streamed `reasoningContent` forwarding and world-variable reasoning-effort propagation for OpenAI-compatible and Google direct providers.
+ * - 2026-03-06: Moved `shell_cmd` working-directory prompt guidance into tool-aware system-message injection.
+ * - 2026-03-06: Widened queue timeout field typing to `number` so runtime timeout overrides compile cleanly.
+ * - 2026-03-05: Added chat-scoped LLM timeout status system events (`taking too long` warning + hard-timeout event), enforced timeout-triggered abort signaling in queue processing, and classified queue timeouts separately from user cancellations.
+ * - 2026-03-05: Switched LLM queue timeout defaults to shared reliability config.
+ * - 2026-03-04: Azure client creation now maps `agent.model` to Azure deployment name (with config deployment fallback) so world/agent model selection controls deployment URL routing.
+ * - 2026-02-28: Added canonical feature-path diagnostics (`llm.prep`, `llm.request.*`, `llm.response.*`) with opt-in raw payload logging and correlation metadata.
+ * - 2026-02-24: Required explicit chatId for streaming SSE emission and propagated chatId through start/chunk/end/error events for strict chat-scoped frontend filtering.
+ * - 2026-02-20: Switched injected tool-usage guidance to shared `buildToolUsagePromptSection()` so HITL and other tool rules are centralized in one utility.
+ * - 2026-02-20: Updated injected tool-usage guidance to direct LLMs to use `human_intervention_request` for human clarifications and confirmations.
  * - 2026-02-13: Reclassified stop-triggered aborts as cancellation/info logs (not errors) in queue and non-streaming paths.
  * - 2026-02-13: Added merged external+queue abort-signal support so chat stop requests can cancel follow-up continuation calls.
  * - 2026-02-13: Added chat-scoped LLM cancellation controls so Electron stop requests can abort active and queued calls by `worldId` + `chatId`.
@@ -117,9 +127,11 @@ import { filterClientSideMessages } from './message-prep.js';
 import { createClientForProvider, streamOpenAIResponse, generateOpenAIResponse } from './openai-direct.js';
 import { createAnthropicClientForAgent, streamAnthropicResponse, generateAnthropicResponse } from './anthropic-direct.js';
 import { createGoogleClientForAgent, streamGoogleResponse, generateGoogleResponse } from './google-direct.js';
-import { generateId } from './utils.js';
+import { buildToolUsagePromptSection, generateId, getDefaultWorkingDirectory, getEnvValueFromText } from './utils.js';
 import { createCategoryLogger } from './logger.js';
+import { buildFeaturePathCorrelation, mergeFeaturePathData, sanitizeRawPayloadForLog, shouldEmitRawLog } from './feature-path-logging.js';
 import { createStorageWithWrappers } from './storage/storage-factory.js';
+import { RELIABILITY_CONFIG } from './reliability-config.js';
 // Granular function-specific loggers for detailed debugging control
 const loggerQueue = createCategoryLogger('llm.queue');
 const loggerStreaming = createCategoryLogger('llm.streaming');
@@ -127,6 +139,11 @@ const loggerGeneration = createCategoryLogger('llm.generation');
 const loggerProvider = createCategoryLogger('llm.provider');
 const loggerMCP = createCategoryLogger('llm.mcp');
 const loggerUtil = createCategoryLogger('llm.util');
+const loggerPrep = createCategoryLogger('llm.prep');
+const loggerRequestMeta = createCategoryLogger('llm.request.meta');
+const loggerRequestRaw = createCategoryLogger('llm.request.raw');
+const loggerResponseMeta = createCategoryLogger('llm.response.meta');
+const loggerResponseRaw = createCategoryLogger('llm.response.raw');
 import { getLLMProviderConfig } from './llm-config.js';
 // LLM Integration Utilities
 function stripCustomFields(message) {
@@ -142,17 +159,90 @@ function stripCustomFieldsFromMessages(messages) {
     // Then strip custom fields
     return filteredMessages.map(stripCustomFields);
 }
+function summarizeMessagesForLLM(messages) {
+    return {
+        messageCount: messages.length,
+        systemMessages: messages.filter(m => m.role === 'system').length,
+        userMessages: messages.filter(m => m.role === 'user').length,
+        assistantMessages: messages.filter(m => m.role === 'assistant').length,
+        toolMessages: messages.filter(m => m.role === 'tool').length,
+    };
+}
+function emitLLMRequestDiagnostics(params) {
+    const correlation = buildFeaturePathCorrelation({
+        worldId: params.world.id,
+        chatId: params.chatId,
+        agentId: params.agent.id,
+        messageId: params.messageId,
+        turnId: params.messageId,
+    });
+    const messageSummary = summarizeMessagesForLLM(params.preparedMessages);
+    const toolNames = Object.keys(params.mcpTools);
+    loggerPrep.debug('Prepared messages for LLM request', mergeFeaturePathData(correlation, {
+        ...messageSummary,
+        toolCount: toolNames.length,
+    }));
+    loggerRequestMeta.debug('LLM request ready', mergeFeaturePathData(correlation, {
+        provider: params.agent.provider,
+        model: params.agent.model,
+        ...messageSummary,
+        toolCount: toolNames.length,
+        toolNames,
+    }));
+    if (shouldEmitRawLog('llm.request.raw')) {
+        loggerRequestRaw.debug('LLM request payload', mergeFeaturePathData(correlation, {
+            provider: params.agent.provider,
+            model: params.agent.model,
+            payload: sanitizeRawPayloadForLog({
+                messages: params.preparedMessages,
+                tools: params.mcpTools,
+            }),
+        }));
+    }
+}
+function emitLLMResponseDiagnostics(params) {
+    const correlation = buildFeaturePathCorrelation({
+        worldId: params.world.id,
+        chatId: params.chatId,
+        agentId: params.agent.id,
+        messageId: params.messageId,
+        turnId: params.messageId,
+    });
+    loggerResponseMeta.debug('LLM response received', mergeFeaturePathData(correlation, {
+        provider: params.agent.provider,
+        model: params.agent.model,
+        responseType: params.response.type,
+        contentLength: params.response.content?.length || 0,
+        toolCallCount: params.response.tool_calls?.length || 0,
+    }));
+    if (shouldEmitRawLog('llm.response.raw')) {
+        loggerResponseRaw.debug('LLM response payload', mergeFeaturePathData(correlation, {
+            provider: params.agent.provider,
+            model: params.agent.model,
+            payload: sanitizeRawPayloadForLog(params.response),
+        }));
+    }
+}
 /**
  * Append tool usage guidance to system message when tools are available
  * Returns a new array with updated system message (doesn't mutate original)
  */
-function appendToolRulesToSystemMessage(messages, hasMCPTools) {
-    if (!hasMCPTools || messages.length === 0 || messages[0].role !== 'system') {
+export function appendToolRulesToSystemMessage(messages, toolNames, options) {
+    if (messages.length === 0 || messages[0].role !== 'system') {
         return messages;
     }
     const systemMessage = messages[0];
-    // Simple guidance: Only use tools when user explicitly requests an action
-    const toolRules = '\n\nYou have access to tools. Use them only when the user explicitly requests an action.';
+    const normalizedToolNames = new Set(toolNames.map((toolName) => String(toolName || '').trim().toLowerCase()).filter(Boolean));
+    const toolUsageSection = buildToolUsagePromptSection({ toolNames });
+    const workingDirectory = typeof options?.workingDirectory === 'string' ? options.workingDirectory.trim() : '';
+    const shellExecutionRule = normalizedToolNames.has('shell_cmd') && workingDirectory
+        ? 'When using `shell_cmd`, execute commands only within this trusted working directory scope: ' + workingDirectory
+        : '';
+    const injectedSections = [shellExecutionRule, toolUsageSection].filter(Boolean);
+    if (injectedSections.length === 0) {
+        return messages;
+    }
+    const toolRules = `\n\n${injectedSections.join('\n\n')}`;
     return [
         { ...systemMessage, content: systemMessage.content + toolRules },
         ...messages.slice(1)
@@ -171,13 +261,25 @@ function normalizeChatId(chatId) {
         return '__none__';
     return String(chatId);
 }
+function createLLMQueueTimeoutError(agentId, timeoutMs) {
+    const error = new Error(`LLM call timeout after ${timeoutMs}ms for agent ${agentId}`);
+    error.name = 'LLMQueueTimeoutError';
+    error.code = 'LLM_QUEUE_TIMEOUT';
+    return error;
+}
+function isLLMQueueTimeoutError(error) {
+    return Boolean(error &&
+        typeof error === 'object' &&
+        'code' in error &&
+        error.code === 'LLM_QUEUE_TIMEOUT');
+}
 class LLMQueue {
     queue = [];
     processing = false;
     activeItem = null;
     maxQueueSize = 100; // Prevent memory issues
-    processingTimeoutMs = 900000; // 15 minute max processing time per call (for long-running tools)
-    async add(agentId, worldId, chatId, task) {
+    processingTimeoutMs = RELIABILITY_CONFIG.llm.processingTimeoutMs; // 15 minute max processing time per call (for long-running tools)
+    async add(agentId, worldId, chatId, task, options) {
         // Prevent queue overflow
         if (this.queue.length >= this.maxQueueSize) {
             throw new Error(`LLM queue is full (${this.maxQueueSize} items). Please try again later.`);
@@ -192,6 +294,8 @@ class LLMQueue {
                 abortController: new AbortController(),
                 canceled: false,
                 execute: task,
+                onTakingTooLong: options?.onTakingTooLong,
+                onTimedOut: options?.onTimedOut,
                 resolve,
                 reject
             };
@@ -214,13 +318,13 @@ class LLMQueue {
                 this.activeItem = item;
                 const taskStartTime = Date.now();
                 loggerQueue.debug(`LLMQueue: Processing task for agent=${item.agentId}, world=${item.worldId}, chat=${normalizeChatId(item.chatId)}, queueItemId=${item.id}`);
-                // Add processing timeout to prevent stuck queue
+                // Add processing timeout to prevent stuck queue.
                 const processPromise = item.execute(item.abortController.signal);
-                // Store timeout ID so we can cancel it if process completes first
+                // Store timeout IDs so we can cancel them on all exits.
                 let timeoutId;
                 let warningTimeoutId;
-                // Warn if processing takes more than 50% of timeout
-                const warningThreshold = this.processingTimeoutMs * 0.5;
+                // Warn if processing exceeds configured threshold ratio of timeout.
+                const warningThreshold = this.processingTimeoutMs * RELIABILITY_CONFIG.llm.warningThresholdRatio;
                 warningTimeoutId = setTimeout(() => {
                     const elapsed = Date.now() - taskStartTime;
                     loggerQueue.warn(`LLM task is taking longer than expected`, {
@@ -230,22 +334,74 @@ class LLMQueue {
                         timeoutMs: this.processingTimeoutMs,
                         percentComplete: Math.round((elapsed / this.processingTimeoutMs) * 100)
                     });
+                    try {
+                        item.onTakingTooLong?.({
+                            elapsedMs: elapsed,
+                            timeoutMs: this.processingTimeoutMs,
+                        });
+                    }
+                    catch (callbackError) {
+                        loggerQueue.warn('LLM queue taking-too-long callback failed', {
+                            agentId: item.agentId,
+                            worldId: item.worldId,
+                            chatId: normalizeChatId(item.chatId),
+                            queueItemId: item.id,
+                            error: callbackError instanceof Error ? callbackError.message : String(callbackError)
+                        });
+                    }
                 }, warningThreshold);
                 const timeoutPromise = new Promise((_, reject) => {
                     timeoutId = setTimeout(() => {
-                        reject(new Error(`LLM call timeout after ${this.processingTimeoutMs}ms for agent ${item.agentId}`));
+                        const elapsed = Date.now() - taskStartTime;
+                        if (!item.abortController.signal.aborted) {
+                            item.abortController.abort();
+                        }
+                        try {
+                            item.onTimedOut?.({
+                                elapsedMs: elapsed,
+                                timeoutMs: this.processingTimeoutMs,
+                            });
+                        }
+                        catch (callbackError) {
+                            loggerQueue.warn('LLM queue timeout callback failed', {
+                                agentId: item.agentId,
+                                worldId: item.worldId,
+                                chatId: normalizeChatId(item.chatId),
+                                queueItemId: item.id,
+                                error: callbackError instanceof Error ? callbackError.message : String(callbackError)
+                            });
+                        }
+                        reject(createLLMQueueTimeoutError(item.agentId, this.processingTimeoutMs));
                     }, this.processingTimeoutMs);
                 });
-                const result = await Promise.race([processPromise, timeoutPromise]);
-                // Clear both timeouts to prevent Jest from hanging
-                clearTimeout(timeoutId);
-                clearTimeout(warningTimeoutId);
+                let result;
+                try {
+                    result = await Promise.race([processPromise, timeoutPromise]);
+                }
+                finally {
+                    if (timeoutId) {
+                        clearTimeout(timeoutId);
+                    }
+                    if (warningTimeoutId) {
+                        clearTimeout(warningTimeoutId);
+                    }
+                }
                 item.resolve(result);
                 loggerQueue.debug(`LLMQueue: Finished processing task for agent=${item.agentId}, world=${item.worldId}, queueItemId=${item.id}`);
             }
             catch (error) {
-                const wasCanceled = item.canceled || item.abortController.signal.aborted || isAbortError(error);
-                if (wasCanceled) {
+                const isTimeout = isLLMQueueTimeoutError(error);
+                const wasCanceled = !isTimeout && (item.canceled || item.abortController.signal.aborted || isAbortError(error));
+                if (isTimeout) {
+                    loggerQueue.warn('LLM queue call timed out', {
+                        agentId: item.agentId,
+                        worldId: item.worldId,
+                        chatId: normalizeChatId(item.chatId),
+                        queueItemId: item.id,
+                        reason: error instanceof Error ? error.message : String(error)
+                    });
+                }
+                else if (wasCanceled) {
                     loggerQueue.info('LLM queue call canceled', {
                         agentId: item.agentId,
                         worldId: item.worldId,
@@ -322,8 +478,8 @@ class LLMQueue {
     }
     // Set processing timeout (useful for testing or adjusting for long-running operations)
     setProcessingTimeout(timeoutMs) {
-        if (timeoutMs < 1000) {
-            throw new Error('Processing timeout must be at least 1000ms');
+        if (timeoutMs < RELIABILITY_CONFIG.llm.minProcessingTimeoutMs) {
+            throw new Error(`Processing timeout must be at least ${RELIABILITY_CONFIG.llm.minProcessingTimeoutMs}ms`);
         }
         this.processingTimeoutMs = timeoutMs;
         loggerQueue.info('LLM queue processing timeout updated', { timeoutMs });
@@ -345,6 +501,18 @@ function isAbortError(error) {
     const message = error instanceof Error ? error.message : String(error);
     return message.toLowerCase().includes('abort');
 }
+function emitLLMTimeoutSystemStatus(world, chatId, content) {
+    const scopedChatId = typeof chatId === 'string' ? chatId.trim() : '';
+    if (!scopedChatId) {
+        return;
+    }
+    world.eventEmitter.emit('system', {
+        content,
+        timestamp: new Date(),
+        messageId: generateId(),
+        chatId: scopedChatId,
+    });
+}
 function createCombinedAbortSignal(first, second) {
     const signals = [first, second].filter((value) => Boolean(value));
     if (signals.length === 0) {
@@ -380,24 +548,36 @@ export async function streamAgentResponse(world, agent, messages, publishSSE, ch
     if (abortSignal?.aborted) {
         throw new DOMException(`LLM call aborted before queue for agent ${agent.id}`, 'AbortError');
     }
+    const normalizedChatId = typeof chatId === 'string' ? chatId.trim() : '';
+    const resolvedChatId = normalizedChatId || null;
+    if (!resolvedChatId) {
+        throw new Error(`streamAgentResponse: chatId is required for agent ${agent.id}`);
+    }
     // Queue the LLM call to ensure serialized execution
-    return llmQueue.add(agent.id, world.id, chatId, async (queueAbortSignal) => {
+    return llmQueue.add(agent.id, world.id, resolvedChatId, async (queueAbortSignal) => {
         const { signal: mergedAbortSignal, dispose } = createCombinedAbortSignal(queueAbortSignal, abortSignal);
         try {
             if (mergedAbortSignal?.aborted) {
                 throw new DOMException(`LLM call aborted before execution for agent ${agent.id}`, 'AbortError');
             }
-            return await executeStreamAgentResponse(world, agent, messages, publishSSE, mergedAbortSignal);
+            return await executeStreamAgentResponse(world, agent, messages, publishSSE, resolvedChatId, mergedAbortSignal);
         }
         finally {
             dispose();
         }
+    }, {
+        onTakingTooLong: ({ elapsedMs, timeoutMs }) => {
+            emitLLMTimeoutSystemStatus(world, resolvedChatId, `LLM processing taking too long for ${agent.id} (elapsed ${Math.floor(elapsedMs / 1000)}s, timeout ${Math.floor(timeoutMs / 1000)}s).`);
+        },
+        onTimedOut: ({ timeoutMs }) => {
+            emitLLMTimeoutSystemStatus(world, resolvedChatId, `LLM processing timed out for ${agent.id} after ${Math.floor(timeoutMs / 1000)}s.`);
+        },
     });
 }
 /**
  * Internal streaming implementation (executed within queue)
  */
-async function executeStreamAgentResponse(world, agent, messages, publishSSE, abortSignal) {
+async function executeStreamAgentResponse(world, agent, messages, publishSSE, chatId, abortSignal) {
     const messageId = generateId();
     try {
         if (abortSignal?.aborted) {
@@ -407,7 +587,8 @@ async function executeStreamAgentResponse(world, agent, messages, publishSSE, ab
         publishSSE(world, {
             agentName: agent.id,
             type: 'start',
-            messageId
+            messageId,
+            chatId
         });
         loggerStreaming.debug(`LLM: Starting streaming response for agent=${agent.id}, world=${world.id}, messageId=${messageId}`);
         // Convert messages for LLM (strip custom fields)
@@ -415,9 +596,11 @@ async function executeStreamAgentResponse(world, agent, messages, publishSSE, ab
         let preparedMessages = stripCustomFieldsFromMessages(messages);
         // Get MCP tools for this world
         const mcpTools = await getMCPToolsForWorld(world.id);
-        const hasMCPTools = Object.keys(mcpTools).length > 0;
+        const mcpToolNames = Object.keys(mcpTools);
+        const hasMCPTools = mcpToolNames.length > 0;
+        const workingDirectory = getEnvValueFromText(world.variables, 'working_directory') || getDefaultWorkingDirectory();
         // Add tool usage instructions to system message when tools are available
-        preparedMessages = appendToolRulesToSystemMessage(preparedMessages, hasMCPTools);
+        preparedMessages = appendToolRulesToSystemMessage(preparedMessages, mcpToolNames, { workingDirectory });
         if (hasMCPTools) {
             loggerMCP.debug(`LLM: Including ${Object.keys(mcpTools).length} MCP tools for agent=${agent.id}, world=${world.id}`);
             // Debug: Log complete tool definitions being sent to LLM
@@ -430,28 +613,71 @@ async function executeStreamAgentResponse(world, agent, messages, publishSSE, ab
                 });
             }
         }
+        emitLLMRequestDiagnostics({
+            world,
+            agent,
+            chatId,
+            messageId,
+            preparedMessages,
+            mcpTools,
+        });
         // Use direct OpenAI integration for OpenAI providers
         if (isOpenAIProvider(agent.provider)) {
             const client = createOpenAIClientForAgent(agent);
-            const response = await streamOpenAIResponse(client, agent.model, preparedMessages, agent, mcpTools, world, (content) => publishSSE(world, { agentName: agent.id, type: 'chunk', content, messageId }), messageId, abortSignal);
+            const response = await streamOpenAIResponse(client, agent.model, preparedMessages, agent, mcpTools, world, (chunk) => publishSSE(world, {
+                agentName: agent.id,
+                type: 'chunk',
+                content: chunk.content,
+                reasoningContent: chunk.reasoningContent,
+                messageId,
+                chatId,
+            }), messageId, abortSignal);
+            emitLLMResponseDiagnostics({
+                world,
+                agent,
+                chatId,
+                messageId,
+                response,
+            });
             // Emit end event after streaming completes
-            publishSSE(world, { agentName: agent.id, type: 'end', messageId });
+            publishSSE(world, { agentName: agent.id, type: 'end', messageId, chatId });
             return { response, messageId };
         }
         // Use direct Anthropic integration for Anthropic provider
         if (isAnthropicProvider(agent.provider)) {
             const client = createAnthropicClientForAgent(agent);
-            const response = await streamAnthropicResponse(client, agent.model, preparedMessages, agent, mcpTools, world, (content) => publishSSE(world, { agentName: agent.id, type: 'chunk', content, messageId }), messageId, abortSignal);
+            const response = await streamAnthropicResponse(client, agent.model, preparedMessages, agent, mcpTools, world, (content) => publishSSE(world, { agentName: agent.id, type: 'chunk', content, messageId, chatId }), messageId, abortSignal);
+            emitLLMResponseDiagnostics({
+                world,
+                agent,
+                chatId,
+                messageId,
+                response,
+            });
             // Emit end event after streaming completes
-            publishSSE(world, { agentName: agent.id, type: 'end', messageId });
+            publishSSE(world, { agentName: agent.id, type: 'end', messageId, chatId });
             return { response, messageId };
         }
         // Use direct Google integration for Google provider
         if (isGoogleProvider(agent.provider)) {
             const client = createGoogleClientForAgent(agent);
-            const response = await streamGoogleResponse(client, agent.model, preparedMessages, agent, mcpTools, world, (content) => publishSSE(world, { agentName: agent.id, type: 'chunk', content, messageId }), messageId, abortSignal);
+            const response = await streamGoogleResponse(client, agent.model, preparedMessages, agent, mcpTools, world, (chunk) => publishSSE(world, {
+                agentName: agent.id,
+                type: 'chunk',
+                content: chunk.content,
+                reasoningContent: chunk.reasoningContent,
+                messageId,
+                chatId,
+            }), messageId, abortSignal);
+            emitLLMResponseDiagnostics({
+                world,
+                agent,
+                chatId,
+                messageId,
+                response,
+            });
             // Emit end event after streaming completes
-            publishSSE(world, { agentName: agent.id, type: 'end', messageId });
+            publishSSE(world, { agentName: agent.id, type: 'end', messageId, chatId });
             return { response, messageId };
         }
         // All providers now use direct integrations - no AI SDK needed
@@ -462,7 +688,8 @@ async function executeStreamAgentResponse(world, agent, messages, publishSSE, ab
             publishSSE(world, {
                 agentName: agent.id,
                 type: 'end',
-                messageId
+                messageId,
+                chatId
             });
             loggerStreaming.info(`LLM: Streaming response canceled for agent=${agent.id}, world=${world.id}, messageId=${messageId}`);
             throw new Error(`LLM call canceled for agent ${agent.id}`);
@@ -472,9 +699,16 @@ async function executeStreamAgentResponse(world, agent, messages, publishSSE, ab
             agentName: agent.id,
             type: 'error',
             error: error.message,
-            messageId
+            messageId,
+            chatId
+        });
+        loggerStreaming.error('LLM: Error during streaming response', {
+            agentId: agent.id,
+            worldId: world.id,
+            chatId,
+            messageId,
+            error: error instanceof Error ? error.message : String(error)
         });
-        loggerStreaming.error(`LLM: Error during streaming response for agent=${agent.id}, world=${world.id}, messageId=${messageId}, error=${error.message}`);
         throw error;
     }
 }
@@ -485,24 +719,36 @@ export async function generateAgentResponse(world, agent, messages, _publishSSE,
     if (abortSignal?.aborted) {
         throw new DOMException(`LLM call aborted before queue for agent ${agent.id}`, 'AbortError');
     }
+    const normalizedChatId = typeof chatId === 'string' ? chatId.trim() : '';
+    const resolvedChatId = normalizedChatId || null;
+    if (!resolvedChatId) {
+        throw new Error(`generateAgentResponse: chatId is required for agent ${agent.id}`);
+    }
     // Queue the LLM call to ensure serialized execution
-    return llmQueue.add(agent.id, world.id, chatId, async (queueAbortSignal) => {
+    return llmQueue.add(agent.id, world.id, resolvedChatId, async (queueAbortSignal) => {
         const { signal: mergedAbortSignal, dispose } = createCombinedAbortSignal(queueAbortSignal, abortSignal);
         try {
             if (mergedAbortSignal?.aborted) {
                 throw new DOMException(`LLM call aborted before execution for agent ${agent.id}`, 'AbortError');
             }
-            return await executeGenerateAgentResponse(world, agent, messages, skipTools, mergedAbortSignal);
+            return await executeGenerateAgentResponse(world, agent, messages, skipTools, resolvedChatId, mergedAbortSignal);
         }
         finally {
             dispose();
         }
+    }, {
+        onTakingTooLong: ({ elapsedMs, timeoutMs }) => {
+            emitLLMTimeoutSystemStatus(world, resolvedChatId, `LLM processing taking too long for ${agent.id} (elapsed ${Math.floor(elapsedMs / 1000)}s, timeout ${Math.floor(timeoutMs / 1000)}s).`);
+        },
+        onTimedOut: ({ timeoutMs }) => {
+            emitLLMTimeoutSystemStatus(world, resolvedChatId, `LLM processing timed out for ${agent.id} after ${Math.floor(timeoutMs / 1000)}s.`);
+        },
     });
 }
 /**
  * Internal generation implementation (executed within queue)
  */
-async function executeGenerateAgentResponse(world, agent, messages, skipTools, abortSignal) {
+async function executeGenerateAgentResponse(world, agent, messages, skipTools, chatId = null, abortSignal) {
     if (abortSignal?.aborted) {
         throw new DOMException('LLM call aborted before start', 'AbortError');
     }
@@ -512,9 +758,19 @@ async function executeGenerateAgentResponse(world, agent, messages, skipTools, a
     let preparedMessages = stripCustomFieldsFromMessages(messages);
     // Get MCP tools for this world (skip if requested, e.g., for title generation)
     const mcpTools = skipTools ? {} : await getMCPToolsForWorld(world.id);
-    const hasMCPTools = Object.keys(mcpTools).length > 0;
+    const mcpToolNames = Object.keys(mcpTools);
+    const hasMCPTools = mcpToolNames.length > 0;
+    const workingDirectory = getEnvValueFromText(world.variables, 'working_directory') || getDefaultWorkingDirectory();
     // Add tool usage instructions to system message when tools are available
-    preparedMessages = appendToolRulesToSystemMessage(preparedMessages, hasMCPTools);
+    preparedMessages = appendToolRulesToSystemMessage(preparedMessages, mcpToolNames, { workingDirectory });
+    emitLLMRequestDiagnostics({
+        world,
+        agent,
+        chatId,
+        messageId,
+        preparedMessages,
+        mcpTools,
+    });
     if (hasMCPTools) {
         loggerMCP.debug(`LLM: Including ${Object.keys(mcpTools).length} MCP tools for agent=${agent.id}, world=${world.id}`);
         // Debug: Log complete tool definitions being sent to LLM
@@ -548,6 +804,13 @@ async function executeGenerateAgentResponse(world, agent, messages, skipTools, a
             agent.lastActive = new Date();
             agent.llmCallCount++;
             agent.lastLLMCall = new Date();
+            emitLLMResponseDiagnostics({
+                world,
+                agent,
+                chatId,
+                messageId,
+                response,
+            });
             loggerGeneration.debug(`LLM: Finished non-streaming OpenAI response for agent=${agent.id}, world=${world.id}`, {
                 responseType: response.type,
                 contentLength: response.content?.length || 0,
@@ -565,6 +828,13 @@ async function executeGenerateAgentResponse(world, agent, messages, skipTools, a
             agent.lastActive = new Date();
             agent.llmCallCount++;
             agent.lastLLMCall = new Date();
+            emitLLMResponseDiagnostics({
+                world,
+                agent,
+                chatId,
+                messageId,
+                response,
+            });
             loggerGeneration.debug(`LLM: Finished non-streaming Anthropic response for agent=${agent.id}, world=${world.id}`, {
                 responseType: response.type,
                 contentLength: response.content?.length || 0,
@@ -582,6 +852,13 @@ async function executeGenerateAgentResponse(world, agent, messages, skipTools, a
             agent.lastActive = new Date();
             agent.llmCallCount++;
             agent.lastLLMCall = new Date();
+            emitLLMResponseDiagnostics({
+                world,
+                agent,
+                chatId,
+                messageId,
+                response,
+            });
             loggerGeneration.debug(`LLM: Finished non-streaming Google response for agent=${agent.id}, world=${world.id}`, {
                 responseType: response.type,
                 contentLength: response.content?.length || 0,
@@ -599,7 +876,13 @@ async function executeGenerateAgentResponse(world, agent, messages, skipTools, a
             loggerGeneration.info(`LLM: Non-streaming response canceled for agent=${agent.id}, world=${world.id}, messageId=${messageId}`);
             throw new Error(`LLM call canceled for agent ${agent.id}`);
         }
-        loggerGeneration.error(`LLM: Error during non-streaming response for agent=${agent.id}, world=${world.id}, error=${error.message}`);
+        loggerGeneration.error('LLM: Error during non-streaming response', {
+            agentId: agent.id,
+            worldId: world.id,
+            chatId,
+            messageId,
+            error: error instanceof Error ? error.message : String(error)
+        });
         throw error;
     }
 }
@@ -654,8 +937,17 @@ function createOpenAIClientForAgent(agent) {
     switch (agent.provider) {
         case LLMProvider.OPENAI:
             return createClientForProvider('openai', config);
-        case LLMProvider.AZURE:
-            return createClientForProvider('azure', config);
+        case LLMProvider.AZURE: {
+            const configuredDeployment = typeof config.deployment === 'string'
+                ? config.deployment.trim()
+                : '';
+            const modelDeployment = typeof agent.model === 'string' ? agent.model.trim() : '';
+            // For Azure, deployment is selected in the URL path. Prefer runtime model when provided.
+            return createClientForProvider('azure', {
+                ...config,
+                deployment: modelDeployment || configuredDeployment,
+            });
+        }
         case LLMProvider.OPENAI_COMPATIBLE:
             return createClientForProvider('openai-compatible', config);
         case LLMProvider.XAI: