onbuzz 4.0.2 → 4.2.0

package/src/core/__tests__/agentScheduler.emptyResponseDiagnostics.test.js

@@ -0,0 +1,191 @@
+/**
+ * Tests for empty-response diagnostic capture.
+ *
+ * When an AI response lands and our accumulator classifies it as "empty"
+ * (no content and no tool calls), the scheduler records a SHAPE SNAPSHOT
+ * of that response onto `_emptyResponseTracker[agentId].samples`. The
+ * /scheduler visualizer surfaces the last snapshot's `hint` as a subline
+ * under the Empties chip so an operator can tell WHY it was empty:
+ * tool-call-only turn (bridge bug), reasoning-only turn (streaming never
+ * reached text), content-filter, length, etc.
+ *
+ * These tests cover the classifier's hint logic and the per-agent
+ * ring-buffer (cap 3 samples) behavior. They do not exercise the full
+ * stall path — agentScheduler.test.js handles that.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+
+// Silence activity service
+const mockShouldAgentBeActive = jest.fn(() => ({ active: false, reason: 'idle' }));
+const mockGetActiveAgents = jest.fn(() => []);
+const mockShouldSkipIteration = jest.fn(() => false);
+jest.unstable_mockModule('../../services/agentActivityService.js', () => ({
+  shouldAgentBeActive: mockShouldAgentBeActive,
+  getActiveAgents: mockGetActiveAgents,
+  shouldSkipIteration: mockShouldSkipIteration,
+}));
+
+const { default: AgentScheduler } = await import('../agentScheduler.js');
+
+function makeScheduler() {
+  const logger = createMockLogger();
+  const agentPool = {
+    getAgent: jest.fn().mockResolvedValue(null),
+    getAllAgents: jest.fn().mockResolvedValue([]),
+    persistAgentState: jest.fn().mockResolvedValue(undefined),
+    getCompactionMetadata: jest.fn().mockResolvedValue(null),
+    getMessagesForAI: jest.fn().mockResolvedValue([]),
+  };
+  const messageProcessor = {};
+  const aiService = { abortRequest: jest.fn().mockReturnValue(false), getActiveRequest: () => null };
+  const scheduler = new AgentScheduler(agentPool, messageProcessor, aiService, logger);
+  return { scheduler, agentPool };
+}
+
+describe('_snapshotResponseShape', () => {
+  let scheduler;
+  beforeEach(() => {
+    jest.clearAllMocks();
+    ({ scheduler } = makeScheduler());
+  });
+
+  test('null / undefined response produces a null-content snapshot with a clear hint', () => {
+    const s = scheduler._snapshotResponseShape(null);
+    expect(s.contentType).toBe('null');
+    expect(s.contentLength).toBe(0);
+    expect(s.hint).toMatch(/null\/undefined/);
+  });
+
+  test('string content measures length correctly', () => {
+    const s = scheduler._snapshotResponseShape({ content: 'hello world' });
+    expect(s.contentType).toBe('string');
+    expect(s.contentLength).toBe(11);
+  });
+
+  test('array content (Responses API shape) sums text-part lengths', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: [{ type: 'text', text: 'hi ' }, { type: 'text', text: 'there' }],
+    });
+    expect(s.contentType).toBe('array');
+    expect(s.contentLength).toBe(8);
+  });
+
+  test('tool-call-only turn (content null + toolCalls present) → bridge-gap hint', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: null,
+      toolCalls: [{ id: 'call_1', function: { name: 'x', arguments: '{}' } }],
+    });
+    expect(s.hasToolCalls).toBe(true);
+    expect(s.toolCallCount).toBe(1);
+    expect(s.hint).toMatch(/Tool-call-only turn/);
+    expect(s.hint).toMatch(/Chat Completions bridge gap/);
+  });
+
+  test('snake_case tool_calls also detected (OpenAI raw shape)', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: '',
+      tool_calls: [{ id: 'a' }, { id: 'b' }],
+    });
+    expect(s.hasToolCalls).toBe(true);
+    expect(s.toolCallCount).toBe(2);
+  });
+
+  test('reasoning-only turn (empty content + reasoning field) → reasoning-only hint', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: '',
+      reasoning: 'long chain of thought...',
+    });
+    expect(s.hasReasoning).toBe(true);
+    expect(s.hint).toMatch(/Reasoning-only turn/);
+    expect(s.hint).toMatch(/output_text/);
+  });
+
+  test('reasoning detected when content is an array with a reasoning part', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: [{ type: 'reasoning', text: '…' }],
+    });
+    expect(s.hasReasoning).toBe(true);
+  });
+
+  test('finish_reason content_filter → safety-filter hint', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: '',
+      finish_reason: 'content_filter',
+    });
+    expect(s.hint).toMatch(/content filter/i);
+  });
+
+  test('finish_reason length → max_tokens hint', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: '',
+      finishReason: 'length',
+    });
+    expect(s.hint).toMatch(/max_tokens/);
+  });
+
+  test('clean stop with empty content → silent-rejection hint', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: '',
+      finishReason: 'stop',
+    });
+    expect(s.hint).toMatch(/silent prompt-rejection|context-limit|upstream timeout/);
+  });
+
+  test('unknown-shape fallback hint is present', () => {
+    const s = scheduler._snapshotResponseShape({ content: '' });
+    expect(s.hint).toMatch(/unclear|inspect raw/);
+  });
+
+  test('does not leak content body — only metadata', () => {
+    const s = scheduler._snapshotResponseShape({
+      content: 'a very secret payload that must not appear in /scheduler or logs',
+    });
+    expect(JSON.stringify(s)).not.toContain('secret payload');
+  });
+});
+
+describe('_trackEmptyResponse + samples ring buffer', () => {
+  let scheduler, agentPool;
+  beforeEach(() => {
+    jest.clearAllMocks();
+    ({ scheduler, agentPool } = makeScheduler());
+    const agent = { id: 'a1', name: 'A', mode: 'agent', conversations: { full: { messages: [] } } };
+    agentPool.getAgent.mockResolvedValue(agent);
+  });
+
+  test('records a sample snapshot on each empty-response cycle', async () => {
+    await scheduler._trackEmptyResponse('a1', { content: '' });
+    const entry = scheduler._emptyResponseTracker.get('a1');
+    expect(entry.samples).toHaveLength(1);
+    expect(entry.samples[0].contentType).toBe('string');
+    expect(entry.samples[0].hint).toBeDefined();
+  });
+
+  test('samples ring buffer caps at 3 entries', async () => {
+    for (let i = 0; i < 5; i++) {
+      await scheduler._trackEmptyResponse('a1', { content: `sample-${i}` });
+    }
+    const entry = scheduler._emptyResponseTracker.get('a1');
+    // Note: threshold may have fired and cleared the tracker — we only get
+    // here if the tracker survives. Either way, the ring buffer's cap is
+    // the contract we want to lock.
+    if (entry) expect(entry.samples.length).toBeLessThanOrEqual(3);
+  });
+
+  test('missing aiResponse is tolerated (null-safe snapshot)', async () => {
+    await scheduler._trackEmptyResponse('a1', null);
+    const entry = scheduler._emptyResponseTracker.get('a1');
+    expect(entry.samples[0].contentType).toBe('null');
+  });
+
+  test('samples carry over from previous cycles on same agent', async () => {
+    await scheduler._trackEmptyResponse('a1', { content: '' });
+    await scheduler._trackEmptyResponse('a1', { content: null, toolCalls: [{ id: 'x' }] });
+    const entry = scheduler._emptyResponseTracker.get('a1');
+    expect(entry.count).toBe(2);
+    expect(entry.samples).toHaveLength(2);
+    expect(entry.samples[1].hasToolCalls).toBe(true);
+  });
+});

package/src/core/__tests__/agentScheduler.modeTransitions.test.js

@@ -0,0 +1,233 @@
+/**
+ * Tests for the mode-transition history surface on AgentScheduler.
+ *
+ * The scheduler owns the ring buffer (`_modeTransitionHistory`) and exposes
+ * two entry points:
+ *
+ *   - `recordModeTransition(agentId, from, to, reasonCode, detail)`
+ *     Bookkeeping only — no mutation, no persist, no broadcast. Called by
+ *     agentPool.updateAgent when an external flip happens (UI toggle, etc.).
+ *
+ *   - `_transitionMode(agentId, to, reasonCode, detail)`
+ *     End-to-end — mutates agent.mode, pushes transcript message (if any),
+ *     persists via agentPool, broadcasts two events. Used by the scheduler's
+ *     own protective flips (user stop, AI timeout, empty stall, loop).
+ *
+ * Tests exercise both without a real agent pool — a minimal mock pool is
+ * plenty to lock the contract. The point here is "bookkeeping correctness
+ * and broadcast shape", not agent lifecycle.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+import AgentScheduler from '../agentScheduler.js';
+import { AGENT_MODES } from '../../utilities/constants.js';
+
+function makeScheduler(opts = {}) {
+  const broadcastToSession = jest.fn();
+  const webSocketManager = { broadcastToSession };
+  const persistAgentState = jest.fn().mockResolvedValue(undefined);
+  const broadcastAgentStateUpdate = jest.fn().mockResolvedValue(undefined);
+  const agent = opts.agent || {
+    id: 'a1', name: 'A', mode: AGENT_MODES.AGENT,
+    sessionId: 's1', conversations: { full: { messages: [] } },
+  };
+  const agentPool = {
+    getAgent: jest.fn().mockImplementation(id => Promise.resolve(id === agent.id ? agent : null)),
+    getAllAgents: jest.fn().mockResolvedValue([agent]),
+    persistAgentState,
+    getCompactionMetadata: jest.fn().mockResolvedValue(null),
+    getMessagesForAI: jest.fn().mockResolvedValue([]),
+  };
+  const messageProcessor = {
+    extractAndExecuteTools: jest.fn().mockResolvedValue([]),
+    extractToolCommands: jest.fn().mockResolvedValue([]),
+  };
+  const aiService = {
+    sendMessage: jest.fn().mockResolvedValue({ content: 'x', tokenUsage: {} }),
+    abortRequest: jest.fn().mockReturnValue(false),
+    getActiveRequest: jest.fn().mockReturnValue(null),
+  };
+  // Actual constructor signature: (agentPool, messageProcessor, aiService, logger, webSocketManager, ...)
+  const scheduler = new AgentScheduler(agentPool, messageProcessor, aiService,
+    createMockLogger(), webSocketManager);
+  // broadcastAgentStateUpdate is a real method on the scheduler that does UI
+  // broadcasts — stub it so tests can focus on the agent_mode_changed event
+  // shape without caring about the canonical-state event's wiring.
+  scheduler.broadcastAgentStateUpdate = broadcastAgentStateUpdate;
+  // Pretend we have a session map so the broadcast finds a target.
+  scheduler.registerAgentSession(agent.id, agent.sessionId);
+  return { scheduler, agent, agentPool, webSocketManager, broadcastToSession,
+           persistAgentState, broadcastAgentStateUpdate };
+}
+
+describe('AgentScheduler.recordModeTransition', () => {
+  test('appends an entry with timestamp + human reason', () => {
+    const { scheduler } = makeScheduler();
+    scheduler.recordModeTransition('a1', 'agent', 'chat', 'user-stop');
+
+    const history = scheduler._modeTransitionHistory.get('a1');
+    expect(history).toHaveLength(1);
+    expect(history[0]).toMatchObject({
+      from: 'agent',
+      to: 'chat',
+      reasonCode: 'user-stop',
+      humanReason: 'Stopped by user.',
+    });
+    expect(new Date(history[0].at).getTime()).not.toBeNaN();
+  });
+
+  test('interpolates detail into the human reason', () => {
+    const { scheduler } = makeScheduler();
+    scheduler.recordModeTransition('a1', 'agent', 'chat', 'empty-response-stall',
+      { count: 5, elapsedSec: 57 });
+
+    const entry = scheduler._modeTransitionHistory.get('a1')[0];
+    expect(entry.humanReason).toBe(
+      'The model returned 5 empty responses in a row over 57s — likely rate-limited, misconfigured, or rejecting the conversation. Switched to Guided Chat.'
+    );
+    expect(entry.detail).toEqual({ count: 5, elapsedSec: 57 });
+  });
+
+  test('no-op when from === to (prevents phantom same-mode entries)', () => {
+    const { scheduler } = makeScheduler();
+    scheduler.recordModeTransition('a1', 'chat', 'chat', 'user-toggle');
+    expect(scheduler._modeTransitionHistory.get('a1')).toBeUndefined();
+  });
+
+  test('no-op when agentId is missing', () => {
+    const { scheduler } = makeScheduler();
+    scheduler.recordModeTransition('', 'agent', 'chat', 'user-stop');
+    scheduler.recordModeTransition(null, 'agent', 'chat', 'user-stop');
+    expect(scheduler._modeTransitionHistory.size).toBe(0);
+  });
+
+  test('ring buffer trims to MAX_PER_AGENT', () => {
+    const { scheduler } = makeScheduler();
+    const MAX = scheduler._MODE_TRANSITION_HISTORY_MAX_PER_AGENT;
+    for (let i = 0; i < MAX + 10; i++) {
+      // Alternate direction so from !== to every time.
+      scheduler.recordModeTransition('a1',
+        i % 2 === 0 ? 'agent' : 'chat',
+        i % 2 === 0 ? 'chat' : 'agent',
+        'user-toggle');
+    }
+    expect(scheduler._modeTransitionHistory.get('a1')).toHaveLength(MAX);
+  });
+
+  test('stores null detail when none provided (avoids empty-object noise)', () => {
+    const { scheduler } = makeScheduler();
+    scheduler.recordModeTransition('a1', 'agent', 'chat', 'user-stop');
+    expect(scheduler._modeTransitionHistory.get('a1')[0].detail).toBeNull();
+  });
+
+  test('unknown reason codes still produce a readable humanReason (no bare symbol)', () => {
+    const { scheduler } = makeScheduler();
+    scheduler.recordModeTransition('a1', 'agent', 'chat', 'some-future-code');
+    const entry = scheduler._modeTransitionHistory.get('a1')[0];
+    expect(entry.humanReason).toBe('Mode change (some future code).');
+  });
+});
+
+describe('AgentScheduler._transitionMode', () => {
+  test('mutates agent.mode, records transition, persists, and broadcasts', async () => {
+    const { scheduler, agent, persistAgentState, broadcastToSession,
+            broadcastAgentStateUpdate } = makeScheduler();
+
+    const changed = await scheduler._transitionMode('a1', AGENT_MODES.CHAT, 'user-stop');
+
+    expect(changed).toBe(true);
+    expect(agent.mode).toBe(AGENT_MODES.CHAT);
+    expect(persistAgentState).toHaveBeenCalledWith('a1');
+    expect(broadcastAgentStateUpdate).toHaveBeenCalledWith('a1', 'user-stop');
+
+    // Find the agent_mode_changed broadcast
+    const modeEvent = broadcastToSession.mock.calls
+      .find(c => c[1].type === 'agent_mode_changed');
+    expect(modeEvent).toBeDefined();
+    expect(modeEvent[1].data).toMatchObject({
+      agentId: 'a1',
+      mode: AGENT_MODES.CHAT,
+      reason: 'user-stop',                      // back-compat symbolic
+      humanReason: 'Stopped by user.',          // new natural-language field
+    });
+
+    // Ring buffer records the flip
+    expect(scheduler._modeTransitionHistory.get('a1')).toHaveLength(1);
+  });
+
+  test('transcriptMessage is pushed into conversations.full and broadcast as message_added', async () => {
+    const { scheduler, agent, broadcastToSession } = makeScheduler();
+
+    const msg = {
+      id: 'm-1', role: 'assistant', content: 'Stalled.',
+      timestamp: new Date().toISOString(),
+    };
+    await scheduler._transitionMode('a1', AGENT_MODES.CHAT, 'empty-response-stall',
+      { count: 5, elapsedSec: 57, transcriptMessage: msg });
+
+    // Conversation got the bubble
+    expect(agent.conversations.full.messages).toHaveLength(1);
+    expect(agent.conversations.full.messages[0].id).toBe('m-1');
+
+    // transcriptMessage was excluded from the saved detail
+    const entry = scheduler._modeTransitionHistory.get('a1')[0];
+    expect(entry.detail).toEqual({ count: 5, elapsedSec: 57 });
+    expect(entry.detail.transcriptMessage).toBeUndefined();
+
+    // message_added broadcast fired
+    const msgEvent = broadcastToSession.mock.calls
+      .find(c => c[1].type === 'message_added');
+    expect(msgEvent).toBeDefined();
+    expect(msgEvent[1].data.message.id).toBe('m-1');
+    expect(msgEvent[1].data.type).toBe('empty-response-stall');
+  });
+
+  test('no-op (returns false) when agent is already in the target mode', async () => {
+    const { scheduler, persistAgentState } = makeScheduler();
+    const changed = await scheduler._transitionMode('a1', AGENT_MODES.AGENT, 'user-toggle');
+    expect(changed).toBe(false);
+    expect(persistAgentState).not.toHaveBeenCalled();
+    expect(scheduler._modeTransitionHistory.size).toBe(0);
+  });
+
+  test('returns false when agent does not exist', async () => {
+    const { scheduler, persistAgentState } = makeScheduler();
+    const changed = await scheduler._transitionMode('nonexistent', AGENT_MODES.CHAT, 'user-stop');
+    expect(changed).toBe(false);
+    expect(persistAgentState).not.toHaveBeenCalled();
+  });
+
+  test('persistence failure does NOT crash the flip (mode still mutated)', async () => {
+    const { scheduler, agent, persistAgentState } = makeScheduler();
+    persistAgentState.mockRejectedValueOnce(new Error('disk full'));
+
+    const changed = await scheduler._transitionMode('a1', AGENT_MODES.CHAT, 'user-stop');
+    expect(changed).toBe(true);
+    expect(agent.mode).toBe(AGENT_MODES.CHAT);
+    expect(scheduler._modeTransitionHistory.get('a1')).toHaveLength(1);
+  });
+});
+
+describe('AgentScheduler.getState — surfaces modeTransitions per agent', () => {
+  test('agent row includes the last N transitions', async () => {
+    const { scheduler } = makeScheduler();
+    scheduler.recordModeTransition('a1', 'agent', 'chat', 'empty-response-stall',
+      { count: 5, elapsedSec: 57 });
+    scheduler.recordModeTransition('a1', 'chat', 'agent', 'user-toggle');
+
+    const state = await scheduler.getState();
+    expect(state.agents).toHaveLength(1);
+    expect(state.agents[0].modeTransitions).toHaveLength(2);
+    expect(state.agents[0].modeTransitions[0].reasonCode).toBe('empty-response-stall');
+    expect(state.agents[0].modeTransitions[1].reasonCode).toBe('user-toggle');
+    // humanReason is already interpolated — the frontend can render verbatim
+    expect(state.agents[0].modeTransitions[0].humanReason).toContain('5 empty responses');
+  });
+
+  test('agent with no transitions reports an empty array (not undefined)', async () => {
+    const { scheduler } = makeScheduler();
+    const state = await scheduler.getState();
+    expect(state.agents[0].modeTransitions).toEqual([]);
+  });
+});

package/src/core/__tests__/agentScheduler.taskLifecycleInstruction.test.js

@@ -0,0 +1,78 @@
+/**
+ * Contract test for the AGENT-mode TaskManager instruction that
+ * agentScheduler injects into every system prompt on an agent-mode turn.
+ *
+ * The instruction and the tool's getDescription() (see
+ * tools/__tests__/taskManagerTool.lifecycleGuidance.test.js) must agree
+ * on the lifecycle — if they drift, the agent gets conflicting guidance
+ * and reverts to whichever one the model's attention happens to anchor
+ * on, which in practice is the older, shorter one. Both tripwires
+ * together lock the contract end-to-end.
+ *
+ * The assertions are keyword-level and case-insensitive so wording can
+ * evolve without breaking the test — but the underlying concepts
+ * (sync-first, in_progress → completed, jobdone at the end) must stay
+ * named.
+ */
+
+import { jest, describe, test, expect } from '@jest/globals';
+
+// Read the scheduler source file directly and grep for the instruction
+// string. Importing the class would drag the whole compaction / AI /
+// websocket stack along for a plain-text check, which is wasteful.
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCHEDULER_SRC = readFileSync(
+  join(__dirname, '../agentScheduler.js'),
+  'utf-8'
+);
+
+describe('agentScheduler AGENT-mode TaskManager instruction — lifecycle contract', () => {
+  // Locate the instruction literal. It starts with "IMPORTANT: You are in
+  // AGENT mode" and is followed by the lifecycle guidance block.
+  const startIdx = SCHEDULER_SRC.indexOf('IMPORTANT: You are in AGENT mode');
+  const endIdx = SCHEDULER_SRC.indexOf('enhancedSystemPrompt = (agent.systemPrompt',
+    startIdx + 1);
+  const instruction = SCHEDULER_SRC.slice(startIdx, endIdx);
+
+  const has = (needle) => expect(instruction).toMatch(new RegExp(needle, 'i'));
+
+  test('the instruction block was located in the source', () => {
+    expect(startIdx).toBeGreaterThan(-1);
+    expect(instruction.length).toBeGreaterThan(100);
+  });
+
+  test('names TASK LIFECYCLE up front', () => {
+    has('TASK LIFECYCLE');
+  });
+
+  test('first call must be sync, not per-task create', () => {
+    has('FIRST TaskManager call must be');
+    has('sync');
+    has("Don't `create` tasks one at a time");
+  });
+
+  test('per-step pattern: in_progress → do work → completed', () => {
+    has('in_progress');
+    has('completed');
+    has('one at a time');
+  });
+
+  test('mid-flight refinement allowed via create or sync', () => {
+    has('`create`');
+    has('`sync`');
+    has("Don't `sync` every turn");
+  });
+
+  test('jobdone is the terminal action', () => {
+    has('jobdone');
+  });
+
+  test('preserves the agent-mode behavioral constraints (no thank-yous, etc.)', () => {
+    has("no thank-you");
+    has('no self-commentary');
+  });
+});

package/src/core/__tests__/agentScheduler.test.js

@@ -256,19 +256,27 @@ describe('AgentScheduler', () => {
 
   // ─── handleRepetitiveLoop ──────────────────────────────────────────────
   describe('handleRepetitiveLoop', () => {
-    test('switches agent to chat mode and adds intervention message', async () => {
-      const agent = makeAgent({ id: 'agent-loop' });
+    test('switches agent to chat mode without polluting the chat transcript', async () => {
+      // Loop detection is a system event, not conversation content. The mode
+      // flip is the action; the humanReason is surfaced via the
+      // `agent_mode_changed` broadcast so the UI can render a toast /
+      // notification-center entry. NO transcript bubble is added (previous
+      // behavior tripled-posted the same "I notice I've been producing
+      // similar responses..." text every time the loop tripped).
+      const agent = makeAgent({ id: 'agent-loop', mode: 'agent' });
       agentPool.getAgent.mockResolvedValue(agent);
 
       await scheduler.handleRepetitiveLoop('agent-loop', { occurrences: 5, windowSize: 20 });
 
       expect(agent.mode).toBe('chat');
-      expect(agent.conversations.full.messages.length).toBe(1);
-      const msg = agent.conversations.full.messages[0];
-      expect(msg.role).toBe('assistant');
-      expect(msg.content).toContain('similar responses repeatedly');
-      expect(msg.loopDetection.occurrences).toBe(5);
+      expect(agent.conversations.full.messages.length).toBe(0); // no chat bubble
       expect(agentPool.persistAgentState).toHaveBeenCalledWith('agent-loop');
+
+      // Mode transition was recorded with a human-readable reason.
+      const history = scheduler._modeTransitionHistory.get('agent-loop');
+      expect(history).toHaveLength(1);
+      expect(history[0].reasonCode).toBe('loop-detected');
+      expect(history[0].humanReason).toMatch(/repeated 5 times in a 20-step window/);
     });
 
     test('clears hash history after handling', async () => {
@@ -288,7 +296,8 @@ describe('AgentScheduler', () => {
     });
 
     test('broadcasts to websocket if available', async () => {
-      const agent = makeAgent({ id: 'agent-loop', sessionId: 'sess-abc' });
+      // See sibling test — needs mode:'agent' so the flip is a real transition.
+      const agent = makeAgent({ id: 'agent-loop', mode: 'agent', sessionId: 'sess-abc' });
       agentPool.getAgent.mockResolvedValue(agent);
       const ws = { broadcastToSession: jest.fn() };
       scheduler.webSocketManager = ws;
@@ -403,11 +412,20 @@ describe('AgentScheduler', () => {
 
       expect(agent.mode).toBe('chat');
       expect(scheduler._emptyResponseTracker.has('agent-empty')).toBe(false);
-      // User-facing intervention message appended
-      const msgs = agent.conversations.full.messages;
-      expect(msgs.length).toBe(1);
-      expect(msgs[0].role).toBe('assistant');
-      expect(msgs[0].content).toContain('empty responses');
+
+      // NO chat-transcript bubble — the stall is surfaced via the
+      // `agent_mode_changed` broadcast's `humanReason`, not a fake
+      // assistant message in the conversation. Previously every stall
+      // posted the same "I've switched to chat mode" paragraph into the
+      // feed, which operators (reasonably) complained about.
+      expect(agent.conversations.full.messages.length).toBe(0);
+
+      // The transition, however, is recorded with count + elapsedSec
+      // interpolated into the human reason.
+      const history = scheduler._modeTransitionHistory.get('agent-empty');
+      expect(history).toHaveLength(1);
+      expect(history[0].reasonCode).toBe('empty-response-stall');
+      expect(history[0].humanReason).toMatch(/5 empty responses/);
     });
 
     test('stall handler is crash-safe when persist throws', async () => {

package/src/core/__tests__/messageProcessor.test.js

@@ -454,6 +454,48 @@ describe('MessageProcessor', () => {
       const toolContext = mockTool.execute.mock.calls[0][1];
       expect(toolContext.projectDir).toBe('/custom/dir');
     });
+
+    // Per-agent tool config passthrough — see agentPool `toolConfig`
+    // schema and BaseTool#getEffectiveConfig. These tests lock the
+    // message-processor side of the plumbing: the correct slice of
+    // agent.toolConfig must land on the tool execution context.
+    test('passes agent.toolConfig[toolId] to the tool as context.toolConfig', async () => {
+      const mockTool = { execute: jest.fn().mockResolvedValue({ ok: true }) };
+      toolsRegistry.getTool.mockReturnValue(mockTool);
+      const commands = [{ toolId: 'terminal', parameters: {}, isAsync: false }];
+      const context = {
+        agentId: 'a1',
+        agentToolConfig: {
+          terminal:   { allowedCommands: ['git', 'npm'] },
+          filesystem: { maxFileSize: 500 },
+        },
+      };
+      await mp.executeTools(commands, context);
+      const toolContext = mockTool.execute.mock.calls[0][1];
+      expect(toolContext.toolConfig).toEqual({ allowedCommands: ['git', 'npm'] });
+    });
+
+    test('context.toolConfig is null when agent has no config for this tool', async () => {
+      const mockTool = { execute: jest.fn().mockResolvedValue({ ok: true }) };
+      toolsRegistry.getTool.mockReturnValue(mockTool);
+      const commands = [{ toolId: 'vision', parameters: {}, isAsync: false }];
+      const context = {
+        agentId: 'a1',
+        agentToolConfig: { terminal: { allowedCommands: ['git'] } },
+      };
+      await mp.executeTools(commands, context);
+      const toolContext = mockTool.execute.mock.calls[0][1];
+      expect(toolContext.toolConfig).toBeNull();
+    });
+
+    test('context.toolConfig is null when agent has no toolConfig at all', async () => {
+      const mockTool = { execute: jest.fn().mockResolvedValue({ ok: true }) };
+      toolsRegistry.getTool.mockReturnValue(mockTool);
+      const commands = [{ toolId: 'terminal', parameters: {}, isAsync: false }];
+      await mp.executeTools(commands, { agentId: 'a1' });
+      const toolContext = mockTool.execute.mock.calls[0][1];
+      expect(toolContext.toolConfig).toBeNull();
+    });
   });
 
   // ─── executeAsyncTool ─────────────────────────────────────────────────