onbuzz 4.0.1 → 4.1.0

package/src/core/agentScheduler.js

@@ -28,6 +28,7 @@ import {
 import ContextInjectionService from '../services/contextInjectionService.js';
 import FlowContextService from '../services/flowContextService.js';
 import TokenCountingService from '../services/tokenCountingService.js';
+import { render as renderModeTransitionReason } from '../utilities/modeTransitionReasons.js';
 import ConversationCompactionService from '../services/conversationCompactionService.js';
 import { getToolSchemasForAgent } from '../tools/openaiFunctionSchemas.js';
 import {
@@ -112,6 +113,18 @@ class AgentScheduler {
     this._lockAcquiredAt = new Map(); // agentId -> Date when lock was acquired
     this._CYCLE_HISTORY_MAX = 200;
 
+    // Per-agent mode-transition ring buffer. Every CHAT ↔ AGENT flip, internal
+    // (user stop, AI timeout, empty-response stall, loop detection) or external
+    // (UI toggle, programmatic update_agent), lands here with a timestamp and
+    // a human-readable reason. The /scheduler visualizer surfaces the last
+    // entry per agent so operators immediately see why an agent flipped.
+    //
+    // Structure: Map<agentId, Array<{ at: ISOString, from: string, to: string,
+    //                                 reasonCode: string, humanReason: string,
+    //                                 detail?: Object }>>
+    this._modeTransitionHistory = new Map();
+    this._MODE_TRANSITION_HISTORY_MAX_PER_AGENT = 50;
+
     // Empty-response stall tracker. Populated only when a cycle received an
     // AI response whose content was empty/whitespace AND carried no tool calls.
     // Reset on any productive cycle. Structure: Map<agentId, { count, firstAt }>.
@@ -134,6 +147,131 @@ class AgentScheduler {
     }
   }
 
+  /**
+   * Record a mode transition into the per-agent ring buffer. Pure bookkeeping —
+   * does NOT mutate agent.mode, does NOT persist, does NOT broadcast. Callers
+   * who need those effects should go through `_transitionMode` (internal,
+   * scheduler-initiated flips) or call this method AFTER they've already
+   * persisted/broadcast (agentPool does that for UI-driven flips).
+   *
+   * @param {string} agentId
+   * @param {string} from        Previous mode ('chat' | 'agent')
+   * @param {string} to          New mode ('chat' | 'agent')
+   * @param {string} reasonCode  Stable reason key — see utilities/modeTransitionReasons.js
+   * @param {Object} [detail]    Template substitution values (count, elapsedSec, …)
+   */
+  recordModeTransition(agentId, from, to, reasonCode, detail = {}) {
+    if (!agentId || from === to) return;
+    const humanReason = renderModeTransitionReason(reasonCode, detail);
+    const entry = {
+      at: new Date().toISOString(),
+      from, to,
+      reasonCode: reasonCode || 'unknown',
+      humanReason,
+      detail: detail && Object.keys(detail).length > 0 ? { ...detail } : null,
+    };
+    if (!this._modeTransitionHistory.has(agentId)) {
+      this._modeTransitionHistory.set(agentId, []);
+    }
+    const arr = this._modeTransitionHistory.get(agentId);
+    arr.push(entry);
+    if (arr.length > this._MODE_TRANSITION_HISTORY_MAX_PER_AGENT) {
+      arr.splice(0, arr.length - this._MODE_TRANSITION_HISTORY_MAX_PER_AGENT);
+    }
+  }
+
+  /**
+   * Apply a scheduler-initiated mode transition end-to-end: mutate the agent,
+   * record in history, persist, and broadcast both legacy + canonical state
+   * events with BOTH reasonCode (machine) and humanReason (UI-friendly).
+   *
+   * This is the ONLY sanctioned way for the scheduler to flip mode. Direct
+   * `agent.mode = …` assignments in this file are a mistake — they skip the
+   * history, the humanReason, and the broadcast.
+   *
+   * Broadcast events:
+   *   - `agent_mode_changed`    — carries { agentId, mode, reason, humanReason }.
+   *                                `reason` kept for back-compat with existing UI.
+   *   - `broadcastAgentStateUpdate` — canonical UI state refresh.
+   *
+   * @param {string} agentId
+   * @param {string} toMode        AGENT_MODES.CHAT | AGENT_MODES.AGENT
+   * @param {string} reasonCode    e.g. 'empty-response-stall' — see utilities/modeTransitionReasons.js
+   * @param {Object} [detail]      Template values + optional { transcriptMessage } to
+   *                                push as a chat message.
+   * @returns {Promise<boolean>}   true if the transition happened, false if skipped (no-op).
+   * @private
+   */
+  async _transitionMode(agentId, toMode, reasonCode, detail = {}) {
+    const agent = await this.agentPool.getAgent(agentId);
+    if (!agent) return false;
+    const fromMode = agent.mode;
+    if (fromMode === toMode) return false;
+
+    // 1. Mutate in-memory state.
+    agent.mode = toMode;
+
+    // 2. Optional transcript message (the existing stall / loop / timeout
+    //    handlers push a chat bubble explaining what happened; we accept it
+    //    here so all mode-change bookkeeping lives in one place).
+    if (detail.transcriptMessage && agent.conversations?.full) {
+      agent.conversations.full.messages.push(detail.transcriptMessage);
+      agent.conversations.full.lastUpdated = new Date().toISOString();
+    }
+
+    // 3. Record in the visualizer ring buffer (natural-language included).
+    //    Don't leak transcriptMessage into the saved detail — it can be large.
+    const persistedDetail = { ...detail };
+    delete persistedDetail.transcriptMessage;
+    this.recordModeTransition(agentId, fromMode, toMode, reasonCode, persistedDetail);
+    const entry = this._modeTransitionHistory.get(agentId)?.slice(-1)[0];
+
+    // 4. Persist — best-effort. A persistence failure should NOT leave us in
+    //    a re-firing state; scheduler trackers (stall, loop) are expected to
+    //    be cleared by the caller BEFORE invoking us.
+    try {
+      await this.agentPool.persistAgentState(agentId);
+    } catch (err) {
+      this.logger?.error?.(`[_transitionMode] persist failed`, { agentId, error: err.message });
+    }
+
+    // 5. Broadcast — two events. Legacy `agent_mode_changed` is what the UI
+    //    toggle listens to; we enrich it with `humanReason` without breaking
+    //    older consumers that only read `reason`.
+    const sessionId = this.getAgentSession(agentId) || agent.sessionId;
+    if (sessionId && this.webSocketManager?.broadcastToSession) {
+      try {
+        if (detail.transcriptMessage) {
+          this.webSocketManager.broadcastToSession(sessionId, {
+            type: 'message_added',
+            data: {
+              agentId,
+              message: detail.transcriptMessage,
+              type: reasonCode,
+            },
+          });
+        }
+        this.webSocketManager.broadcastToSession(sessionId, {
+          type: 'agent_mode_changed',
+          data: {
+            agentId,
+            mode: toMode,
+            reason: reasonCode,        // back-compat
+            humanReason: entry?.humanReason || '',  // new: UI-friendly
+            timestamp: entry?.at || new Date().toISOString(),
+          },
+        });
+      } catch (err) {
+        this.logger?.warn?.(`[_transitionMode] broadcast failed`, { agentId, error: err.message });
+      }
+    }
+    try {
+      await this.broadcastAgentStateUpdate(agentId, reasonCode);
+    } catch { /* broadcast errors are best-effort */ }
+
+    return true;
+  }
+
   /**
    * Start the agent scheduler
    */
@@ -197,6 +335,7 @@ class AgentScheduler {
     this._lockAcquiredAt.clear();
     this._cycleHistory.length = 0;
     this._emptyResponseTracker.clear();
+    this._modeTransitionHistory.clear();
 
     // Cleanup services
     if (this.tokenCountingService && this.tokenCountingService.cleanup) {
@@ -263,6 +402,10 @@ class AgentScheduler {
         activeAIRequest: activeAIReq,
         stateHashHistory: (this.stateHashHistory.get(agent.id) || []).slice(-10),
         emptyResponse: this._emptyResponseTracker.get(agent.id) || null,
+        // Last 10 mode transitions (CHAT ↔ AGENT) for this agent. Newest-last.
+        // Each entry: { at, from, to, reasonCode, humanReason, detail }.
+        // The /scheduler visualizer surfaces humanReason under the mode cell.
+        modeTransitions: (this._modeTransitionHistory.get(agent.id) || []).slice(-10),
       });
     }
 
@@ -430,39 +573,34 @@ class AgentScheduler {
         }
       }
 
-      // Set agent mode back to CHAT - this will cause shouldAgentBeActive to return false
-      agent.mode = AGENT_MODES.CHAT;
-
-      // Clear any delays
+      // Clear any delays BEFORE the mode flip — _transitionMode persists after.
       agent.delayEndTime = null;
 
-      // Clear stop request flag after mode is set (it has been honored)
-      agent.stopRequested = false;
+      // Flip mode → CHAT (records transition + persists + broadcasts
+      // agent_mode_changed with humanReason "Stopped by user.")
+      await this._transitionMode(agentId, AGENT_MODES.CHAT, 'user-stop');
 
-      // Persist the change
-      await this.agentPool.persistAgentState(agentId);
+      // Clear stop request flag after mode is set (it has been honored).
+      agent.stopRequested = false;
 
-      // Clean up session tracking
+      // Clean up session tracking.
       this.removeAgent(agentId, 'stopped-by-user');
 
-      // Get session ID for broadcast
+      // Legacy `execution_stopped` event — some UI paths key off it rather
+      // than agent_mode_changed. Kept for back-compat; the mode flip itself
+      // was already broadcast by _transitionMode above.
       const sessionId = this.getAgentSession(agentId) || agent.sessionId;
-
-      // Broadcast stop event if we have a valid session ID
       if (sessionId && this.webSocketManager && this.webSocketManager.broadcastToSession) {
         this.webSocketManager.broadcastToSession(sessionId, {
           type: 'execution_stopped',
           data: {
             agentId,
             type: 'execution_stopped',
-            mode: AGENT_MODES.CHAT, // Include mode change for UI toggle
+            mode: AGENT_MODES.CHAT,
             timestamp: new Date().toISOString()
           }
         });
       }
-      // Canonical state broadcast — ensures the UI flips the mode toggle
-      // even if it isn't listening for the legacy `execution_stopped` event.
-      await this.broadcastAgentStateUpdate(agentId, 'user-stopped');
 
       this.logger.info(`Agent execution stopped: ${agentId}`, {
         mode: agent.mode
@@ -734,6 +872,10 @@ class AgentScheduler {
       //                 "no-op cycle" that must NOT pollute stateHashHistory.
       let gotResponse = false;
       let advanced = false;
+      // Preserved for the empty-response-stall diagnostic snapshot — we want
+      // to show the operator the raw shape of an "empty" response (finish
+      // reason, has-tool-calls, content length) so the root cause is visible.
+      let lastAiResponse = null;
 
       // Process based on whether there are messages or agent needs autonomous processing
       if (totalMessages === 0 && agent.mode === AGENT_MODES.AGENT) {
@@ -742,6 +884,7 @@ class AgentScheduler {
         const result = await this.processAgentAutonomously(agentId);
         gotResponse = result.gotResponse;
         advanced = result.advanced;
+        lastAiResponse = result.aiResponse ?? null;
       } else if (totalMessages > 0) {
         // Has messages to process
         const processedMessages = await this.processAgentQueues(agentId);
@@ -752,6 +895,7 @@ class AgentScheduler {
 
           if (aiResponse) {
             gotResponse = true;
+            lastAiResponse = aiResponse;
             advanced = await this.processAIResponse(agentId, aiResponse);
 
             // Clear token limit retry tracker on successful AI response
@@ -776,9 +920,11 @@ class AgentScheduler {
       // whitespace-only response with no tool calls, we keep retrying — the
       // next cycle may produce a real message. But we ring-buffer the empties
       // so a genuinely stuck model eventually surfaces as a user-facing error
-      // instead of silently spinning forever.
+      // instead of silently spinning forever. We also snapshot the response
+      // shape so the operator can see WHY the model returned nothing
+      // (content_filter? tool-call-only? reasoning-only? etc).
       if (gotResponse && !advanced) {
-        await this._trackEmptyResponse(agentId);
+        await this._trackEmptyResponse(agentId, lastAiResponse);
       } else if (advanced) {
         // Productive cycle — any previous stall has resolved itself.
         if (this._emptyResponseTracker.has(agentId)) {
@@ -1125,7 +1271,7 @@ class AgentScheduler {
       // No response - activity service will determine if we should continue.
       // Reported as { gotResponse: false } so the caller doesn't count this
       // as an "empty-response stall" (which is specifically about empty content).
-      return { gotResponse: false, advanced: false };
+      return { gotResponse: false, advanced: false, aiResponse: null };
     }
 
     // Process AI response and execute tools. processAIResponse returns `true`
@@ -1137,7 +1283,9 @@ class AgentScheduler {
     // Clear token limit retry tracker on successful AI response
     this.clearTokenLimitRetryTracker(agentId);
 
-    return { gotResponse: true, advanced };
+    // Return aiResponse alongside flags so the caller can snapshot the raw
+    // shape into the empty-response diagnostic tracker when advanced=false.
+    return { gotResponse: true, advanced, aiResponse };
   }
 
   /**
@@ -1747,7 +1895,18 @@ class AgentScheduler {
       // Inject TaskManager instructions for AGENT mode
       let enhancedSystemPrompt = agent.systemPrompt;
       if (agent.mode === AGENT_MODES.AGENT) {
-        const taskManagerInstruction = "\n\nIMPORTANT: You are in AGENT mode. The use of TaskManager tool is mandatory. Always create and update tasks to track your work progress. Update the user about task-list status periodically. Use the jobdone tool when your main task is complete. While in agent mode: no thank-you's, no compliments, no rhetorical questions, no self-commentary - stay focused on executing tasks. Only ask questions through dedicated tools designed for user interaction (if available).";
+        const taskManagerInstruction = "\n\nIMPORTANT: You are in AGENT mode. The use of TaskManager tool is mandatory.\n\n" +
+          "TASK LIFECYCLE (follow this, don't improvise):\n" +
+          "  1. If your task list is empty, your FIRST TaskManager call must be `sync` with your complete plan as a single call. " +
+          "Don't `create` tasks one at a time at the start — use `sync` once to establish the whole plan.\n" +
+          "  2. Then process tasks one at a time: `update` the next task to `in_progress`, do the work with other tools, " +
+          "`update` it to `completed`, move on. The scheduler enforces at most one task `in_progress` at a time.\n" +
+          "  3. If you discover new work mid-execution, `create` a single new task, or issue another `sync` when the plan materially changes. " +
+          "Don't `sync` every turn — prefer targeted `update`/`create` unless the plan itself shifted.\n" +
+          "  4. When every task is `completed`, call the `jobdone` tool.\n\n" +
+          "Update the user about task-list status periodically. While in agent mode: no thank-you's, no compliments, " +
+          "no rhetorical questions, no self-commentary — stay focused on executing tasks. " +
+          "Only ask questions through dedicated tools designed for user interaction (if available).";
         enhancedSystemPrompt = (agent.systemPrompt || '') + taskManagerInstruction;
 
         // Note: Consecutive no-tool reminders are now sent as tool results (see _processAIResponse)
@@ -2176,12 +2335,16 @@ class AgentScheduler {
         status: error.status
       });
 
-      // Switch agent to CHAT mode - no delay, user can retry when ready
-      agent.mode = AGENT_MODES.CHAT;
-      await this.agentPool.persistAgentState(agentId);
-      await this.broadcastAgentStateUpdate(agentId, 'timeout');
+      // Flip mode → CHAT via the central helper so the transition gets
+      // captured in _modeTransitionHistory with a natural-language reason.
+      // elapsedSec is best-effort; many timeout errors don't carry timing.
+      const elapsedSec = Number.isFinite(error.elapsedMs)
+        ? Math.round(error.elapsedMs / 1000)
+        : 60;   // SCHEDULER_CONFIG's default AI-call watchdog window
+      await this._transitionMode(agentId, AGENT_MODES.CHAT, 'ai-request-timeout', { elapsedSec });
 
-      // Broadcast timeout notification to UI (toast + console log only, no chat message)
+      // Toast-only notification (separate event so the UI can render a
+      // corner toast in addition to the mode-change indicator).
       if (this.webSocketManager && this.webSocketManager.broadcastToSession) {
         this.webSocketManager.broadcastToSession(sessionId, {
           type: 'agent_timeout',
@@ -3590,15 +3753,27 @@ class AgentScheduler {
    * next cycle may produce a real message — but we buffer the empties so
    * we can surface a clear error to the user if the stall persists.
    *
+   * A snapshot of the raw response's shape is captured per cycle (capped at
+   * 3 samples per entry) so the operator can see WHY the model returned
+   * nothing: was it a content-filter trip, a tool-call-only turn whose
+   * tool_calls failed to bridge, a reasoning-only stream that never emitted
+   * text, or an actual silent-but-200 upstream. Without this the stall is
+   * indistinguishable from "the model is broken" vs "our parser missed it".
+   *
    * @param {string} agentId
+   * @param {Object|null} aiResponse  Raw AI response from aiService; null OK.
    * @private
    */
-  async _trackEmptyResponse(agentId) {
+  async _trackEmptyResponse(agentId, aiResponse = null) {
     const now = Date.now();
     const existing = this._emptyResponseTracker.get(agentId);
+    const sample = this._snapshotResponseShape(aiResponse);
+    const prevSamples = existing?.samples || [];
+    // Keep up to 3 samples so operators see the pattern, not just the last one.
+    const samples = [...prevSamples, sample].slice(-3);
     const entry = existing
-      ? { count: existing.count + 1, firstAt: existing.firstAt, lastAt: now }
-      : { count: 1, firstAt: now, lastAt: now };
+      ? { count: existing.count + 1, firstAt: existing.firstAt, lastAt: now, samples }
+      : { count: 1, firstAt: now, lastAt: now, samples };
 
     this._emptyResponseTracker.set(agentId, entry);
 
@@ -3607,6 +3782,7 @@ class AgentScheduler {
       elapsedMs: now - entry.firstAt,
       threshold: SCHEDULER_CONFIG.EMPTY_RESPONSE_STALL_THRESHOLD,
       windowMs: SCHEDULER_CONFIG.EMPTY_RESPONSE_STALL_WINDOW_MS,
+      sample,  // snapshot of THIS empty response — aids root-cause analysis
     });
 
     const shouldStall =
@@ -3622,6 +3798,83 @@ class AgentScheduler {
     }
   }
 
+  /**
+   * Reduce an AI response object to the minimum forensic info needed to
+   * diagnose WHY it was classified as empty. Keeps the snapshot tiny (fits
+   * in WebSocket + UI) and avoids leaking full conversation content.
+   *
+   * Fields probed:
+   *   - contentType / contentLength  : what the accumulator got
+   *   - hasToolCalls                  : was it a tool-only turn?
+   *   - toolCallCount                 : how many, if so
+   *   - finishReason                  : provider's stop signal (length,
+   *                                      content_filter, tool_calls, stop, …)
+   *   - hasReasoning                  : reasoning-only turn indicator
+   *   - model                         : which model produced it
+   *
+   * Each field is a cheap string/number/bool. No content bodies included.
+   *
+   * @param {Object|null} r  Raw aiService response.
+   * @returns {{ at: string, contentType: string, contentLength: number, hasToolCalls: boolean, toolCallCount: number, finishReason: string|null, hasReasoning: boolean, model: string|null, hint: string }}
+   * @private
+   */
+  _snapshotResponseShape(r) {
+    const at = new Date().toISOString();
+    if (!r || typeof r !== 'object') {
+      return { at, contentType: 'null', contentLength: 0, hasToolCalls: false,
+               toolCallCount: 0, finishReason: null, hasReasoning: false,
+               model: null, hint: 'aiService returned null/undefined' };
+    }
+    const content = r.content;
+    let contentType, contentLength;
+    if (typeof content === 'string') {
+      contentType = 'string';
+      contentLength = content.length;
+    } else if (Array.isArray(content)) {
+      contentType = 'array';
+      contentLength = content.reduce((n, p) => n + (typeof p?.text === 'string' ? p.text.length : 0), 0);
+    } else if (content == null) {
+      contentType = 'null';
+      contentLength = 0;
+    } else {
+      contentType = typeof content;
+      contentLength = 0;
+    }
+
+    const toolCalls = Array.isArray(r.toolCalls) ? r.toolCalls
+                    : Array.isArray(r.tool_calls) ? r.tool_calls
+                    : null;
+    const hasToolCalls = Array.isArray(toolCalls) && toolCalls.length > 0;
+    const toolCallCount = hasToolCalls ? toolCalls.length : 0;
+
+    const finishReason = r.finishReason || r.finish_reason || r.stop_reason || null;
+    const hasReasoning = !!(r.reasoning || r.reasoning_content
+                            || (Array.isArray(content) && content.some(p => p?.type === 'reasoning')));
+    const model = r.model || null;
+
+    // Best-guess hint. The operator sees this at the top of the sample so
+    // they don't have to read the other fields to get a first theory. Wrong
+    // hints are easy to override visually because all the raw fields are
+    // right there.
+    let hint;
+    if (hasToolCalls && contentLength === 0) {
+      hint = 'Tool-call-only turn — tool_calls did not reach the content accumulator. Likely a Chat Completions bridge gap.';
+    } else if (hasReasoning && contentLength === 0) {
+      hint = 'Reasoning-only turn — model emitted thinking tokens but no text output. Likely a Responses API stream that never reached output_text.';
+    } else if (finishReason === 'content_filter') {
+      hint = 'Blocked by the provider content filter.';
+    } else if (finishReason === 'length') {
+      hint = 'Hit max_tokens before producing any output. Raise the model\'s output cap or compact the conversation.';
+    } else if (contentLength === 0 && finishReason === 'stop') {
+      hint = 'Model returned 200 with clean stop and no output. Possible silent prompt-rejection / context-limit / upstream timeout.';
+    } else {
+      hint = 'Classified empty by the detector; root cause unclear — inspect raw fields.';
+    }
+
+    return { at, contentType, contentLength, hasToolCalls, toolCallCount,
+             finishReason, hasReasoning, model, hint };
+  }
+
   /**
    * Circuit breaker fired when an agent has produced N empty responses across
    * at least the configured time window. Surfaces a user-facing error message,
@@ -3645,63 +3898,21 @@ class AgentScheduler {
     this.consecutiveNoToolMessages.delete(agentId);
 
     const elapsedSec = Math.round((entry.lastAt - entry.firstAt) / 1000);
-    const interventionMessage = `The model returned ${entry.count} empty responses in a row over ${elapsedSec}s. ` +
-      `I've switched to chat mode so you can retry or adjust. Common causes: ` +
-      `the selected model is unreachable, rate-limited, or rejecting the current ` +
-      `conversation. You can pick a different model or send a new message to try again.`;
-
-    const messageToAdd = {
-      id: `msg-empty-response-stall-${Date.now()}`,
-      role: 'assistant',
-      content: interventionMessage,
-      timestamp: new Date().toISOString(),
-      isSystemMessage: true,
-      emptyResponseStall: {
-        count: entry.count,
-        elapsedMs: entry.lastAt - entry.firstAt,
-      },
-    };
-
-    if (agent.conversations && agent.conversations.full) {
-      agent.conversations.full.messages.push(messageToAdd);
-      agent.conversations.full.lastUpdated = new Date().toISOString();
-    }
-
-    agent.mode = AGENT_MODES.CHAT;
 
-    // Persist + broadcast are best-effort — a failure here must NOT leave the
-    // agent in a re-firing state. Scheduler state was cleared above.
-    try {
-      await this.agentPool.persistAgentState(agentId);
-    } catch (err) {
-      this.logger.error(`Failed to persist agent after empty-response stall: ${err.message}`, { agentId });
-    }
-
-    const sessionId = this.getAgentSession(agentId) || agent.sessionId;
-    if (sessionId && this.webSocketManager && this.webSocketManager.broadcastToSession) {
-      try {
-        this.webSocketManager.broadcastToSession(sessionId, {
-          type: 'message_added',
-          data: { agentId, message: messageToAdd, type: 'empty_response_stall' },
-        });
-        this.webSocketManager.broadcastToSession(sessionId, {
-          type: 'agent_mode_changed',
-          data: {
-            agentId,
-            mode: AGENT_MODES.CHAT,
-            reason: 'empty_response_stall',
-            timestamp: new Date().toISOString(),
-          },
-        });
-      } catch (err) {
-        this.logger.warn(`Failed to broadcast empty-response stall: ${err.message}`, { agentId });
-      }
-    }
-    await this.broadcastAgentStateUpdate(agentId, 'empty-response-stall');
+    // Flip mode → CHAT. System events like this one are NOT pushed into the
+    // chat transcript — they surface via the `agent_mode_changed` +
+    // `agent_notification` broadcasts as toast + notification-center entries.
+    // Transcript bubbles are for conversation content only; filling the feed
+    // with "I've switched to chat mode" bodies made every stall triple-post.
+    await this._transitionMode(agentId, AGENT_MODES.CHAT, 'empty-response-stall', {
+      count: entry.count,
+      elapsedSec,
+    });
 
     this.logger.error(`Agent ${agentId} switched to CHAT mode after ${entry.count} empty responses`, {
       agentName: agent.name,
       elapsedMs: entry.lastAt - entry.firstAt,
+      samples: entry.samples || [],   // diagnostic — see _trackEmptyResponse
     });
   }
 
@@ -3753,72 +3964,16 @@ class AgentScheduler {
     this._emptyResponseTracker.delete(agentId);
     this.consecutiveNoToolMessages.delete(agentId);
 
-    // Create a user-friendly message
-    const interventionMessage = `I notice I've been producing similar responses repeatedly (${loopDetection.occurrences} times). This usually means I'm stuck or need your guidance. I've switched to chat mode so you can provide direction.
-
-What would you like me to do next? You can:
-- Give me new instructions or clarify the task
-- Switch me back to agent mode if you want me to continue
-- Ask me to try a different approach`;
-
-    // Add the intervention message as an assistant message so it shows in the chat
-    const messageToAdd = {
-      id: `msg-loop-intervention-${Date.now()}`,
-      role: 'assistant',
-      content: interventionMessage,
-      timestamp: new Date().toISOString(),
-      isSystemMessage: true,
-      loopDetection: {
-        occurrences: loopDetection.occurrences,
-        windowSize: loopDetection.windowSize
-      }
-    };
-
-    // Add to the full conversation history directly
-    if (agent.conversations && agent.conversations.full) {
-      agent.conversations.full.messages.push(messageToAdd);
-      agent.conversations.full.lastUpdated = new Date().toISOString();
-    }
-
-    // Stop the agent execution - switch to chat mode
-    agent.mode = AGENT_MODES.CHAT;
-
-    // Persist + broadcast are best-effort. Scheduler state was already cleared
-    // above, so a failure here can still leave the intervention un-persisted
-    // but won't cause the loop detector to re-fire.
-    try {
-      await this.agentPool.persistAgentState(agentId);
-    } catch (err) {
-      this.logger.error(`Failed to persist agent after loop detection: ${err.message}`, { agentId });
-    }
-
-    // Broadcast the message to UI so it appears in the chat
-    const sessionId = this.getAgentSession(agentId) || agent.sessionId;
-    if (sessionId && this.webSocketManager && this.webSocketManager.broadcastToSession) {
-      try {
-        this.webSocketManager.broadcastToSession(sessionId, {
-          type: 'message_added',
-          data: {
-            agentId,
-            message: messageToAdd,
-            type: 'loop_intervention'
-          }
-        });
-
-        this.webSocketManager.broadcastToSession(sessionId, {
-          type: 'agent_mode_changed',
-          data: {
-            agentId,
-            mode: AGENT_MODES.CHAT,
-            reason: 'loop_detected',
-            timestamp: new Date().toISOString()
-          }
-        });
-      } catch (err) {
-        this.logger.warn(`Failed to broadcast loop intervention: ${err.message}`, { agentId });
-      }
-    }
-    await this.broadcastAgentStateUpdate(agentId, 'loop-detected');
+    // Flip mode → CHAT. No chat-transcript bubble — the humanReason
+    // ("The same action repeated N times…") is surfaced by the UI as a
+    // toast + notification-center entry via the agent_mode_changed /
+    // agent_notification broadcasts fired inside _transitionMode. Putting
+    // system events into the transcript cluttered the feed every time the
+    // loop tripped.
+    await this._transitionMode(agentId, AGENT_MODES.CHAT, 'loop-detected', {
+      occurrences: loopDetection.occurrences,
+      windowSize: loopDetection.windowSize,
+    });
 
     this.logger.warn(`Agent ${agentId} stopped due to repetitive loop - awaiting user intervention`, {
       occurrences: loopDetection.occurrences,

package/src/core/messageProcessor.js

@@ -12,6 +12,7 @@ import TagParser from '../utilities/tagParser.js';
 import { TOOL_IDS, COMMAND_FORMATS } from '../utilities/toolConstants.js';
 import { getVisualEditorBridge } from '../services/visualEditorBridge.js';
 import { VisualEditorTool } from '../tools/visualEditorTool.js';
+import { prependSourceHeader } from '../services/messageSource.js';
 
 class MessageProcessor {
   constructor(config, logger, toolsRegistry, agentPool, contextManager, aiService, modelRouterService = null, modelsService = null) {
@@ -132,6 +133,18 @@ class MessageProcessor {
         this.logger.warn?.(`Failed to inject visual context: ${err.message}`);
       }
 
+      // Prepend the source attribution header when the message arrived from
+      // an external channel (Discord / Telegram). The header is plain text
+      // of the form "(Message by alice from Discord > MyGuild > #ops)" and
+      // becomes part of the persisted content, so the agent sees it in its
+      // LLM context and the operator sees it in the web-UI transcript. The
+      // operation is idempotent — re-serialization (state restore, replay)
+      // won't double-prefix. Sources of kind web/api/internal produce no
+      // header and leave the content untouched. See services/messageSource.js.
+      if (context.source) {
+        enhancedMessage = prependSourceHeader(enhancedMessage, context.source);
+      }
+
       await this.agentPool.addUserMessage(agentId, {
         content: enhancedMessage,
         role: 'user',
@@ -140,6 +153,10 @@ class MessageProcessor {
         sessionId: context.sessionId,
         visualContextInjected,
         streamingEnabled: context.streamingEnabled !== false, // Pass streaming preference from context
+        // Preserve the structured source on the queued message too, so any
+        // downstream consumer (logs, analytics, relay) can reason about
+        // provenance without re-parsing the inline header.
+        source: context.source || null,
         // Flow execution context (if this message is part of a flow)
         isFlowExecution: context.isFlowExecution || false,
         flowRunId: context.flowRunId,

package/src/core/orchestrator.js

@@ -388,7 +388,7 @@ class Orchestrator {
    * @private
    */
   async _handleSendMessage(request) {
-    const { agentId, message, mode, contextReferences, apiKey, customApiKeys, streamingEnabled } = request.payload;
+    const { agentId, message, mode, contextReferences, apiKey, customApiKeys, streamingEnabled, source } = request.payload;
 
     const context = {
       projectDir: request.projectDir,
@@ -398,7 +398,11 @@ class Orchestrator {
       contextReferences: contextReferences || [],
       apiKey: apiKey, // Pass Loxia API key through context
       customApiKeys: customApiKeys || {}, // Pass custom API keys through context
-      streamingEnabled: streamingEnabled !== false // Default to true if not specified
+      streamingEnabled: streamingEnabled !== false, // Default to true if not specified
+      // Provenance metadata from the inbound adapter (Discord/Telegram/…).
+      // Preserved verbatim by messageProcessor and agentPool so the agent
+      // can see where the message came from. See services/messageSource.js.
+      source: source || null,
     };
 
     return await this.routeToAgent(agentId, message, context);