onbuzz 4.3.0 → 4.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onbuzz",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "Loxia OnBuzz - Your AI Fleet",
   "type": "module",
   "main": "src/index.js",

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

@@ -0,0 +1,258 @@
+/**
+ * Tests for the scheduler-visualizer surface on AgentScheduler.
+ *
+ * Covers the in-memory bookkeeping that backs the /scheduler page:
+ *   - _recordCycle ring buffer (push + trim to _CYCLE_HISTORY_MAX)
+ *   - lock acquire/release timestamping (_lockAcquiredAt)
+ *   - processingCycle records exactly one entry per outcome path
+ *       idle / all-locked / concurrency-cap / launched
+ *   - getState() shape: scheduler block, locks block, agent rows
+ *   - lockHeldMs reflects elapsed time since acquisition
+ *
+ * No real agent processing is exercised — we drive processingCycle directly
+ * with a stubbed agent pool so each cycle's outcome is deterministic.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+import AgentScheduler from '../agentScheduler.js';
+import { AGENT_MODES, AGENT_STATUS } from '../../utilities/constants.js';
+
+function makeAgent(overrides = {}) {
+  return {
+    id: 'a1', name: 'Alpha',
+    mode: AGENT_MODES.AGENT,
+    status: AGENT_STATUS.ACTIVE,
+    sessionId: 's1',
+    taskList: { tasks: [{ status: 'pending', content: 'do the thing' }] },
+    messageQueues: { userMessages: [], interAgentMessages: [], toolResults: [] },
+    conversations: { full: { messages: [] } },
+    ...overrides,
+  };
+}
+
+function makeScheduler(agents = [makeAgent()]) {
+  const agentPool = {
+    getAgent: jest.fn(id => Promise.resolve(agents.find(a => a.id === id) || null)),
+    getAllAgents: jest.fn().mockResolvedValue(agents),
+    persistAgentState: jest.fn().mockResolvedValue(undefined),
+    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),
+  };
+  const webSocketManager = { broadcastToSession: jest.fn() };
+  const scheduler = new AgentScheduler(
+    agentPool, messageProcessor, aiService,
+    createMockLogger(), webSocketManager
+  );
+  // Don't actually spawn timers — we drive processingCycle by hand.
+  scheduler.broadcastAgentStateUpdate = jest.fn().mockResolvedValue(undefined);
+  // Stub processAgentsInParallel: a real launch acquires the lock inside
+  // processAgent, but for visualizer tests we only care about pre-launch
+  // bookkeeping (skip lists, recorded cycle entries). Make it a no-op.
+  scheduler.processAgentsInParallel = jest.fn().mockResolvedValue(undefined);
+  return { scheduler, agents, agentPool, aiService };
+}
+
+describe('_recordCycle ring buffer', () => {
+  test('appends entries newest-last', () => {
+    const { scheduler } = makeScheduler();
+    scheduler._recordCycle({ n: 1, outcome: 'idle' });
+    scheduler._recordCycle({ n: 2, outcome: 'launched' });
+    expect(scheduler._cycleHistory).toHaveLength(2);
+    expect(scheduler._cycleHistory[0].n).toBe(1);
+    expect(scheduler._cycleHistory[1].n).toBe(2);
+  });
+
+  test('trims to _CYCLE_HISTORY_MAX, keeping the newest entries', () => {
+    const { scheduler } = makeScheduler();
+    scheduler._CYCLE_HISTORY_MAX = 5;
+    for (let i = 1; i <= 12; i++) scheduler._recordCycle({ n: i, outcome: 'idle' });
+    expect(scheduler._cycleHistory).toHaveLength(5);
+    expect(scheduler._cycleHistory[0].n).toBe(8);   // 12-5+1
+    expect(scheduler._cycleHistory[4].n).toBe(12);
+  });
+});
+
+describe('processingCycle records one entry per outcome', () => {
+  test('outcome=idle when no agent is active', async () => {
+    const idleAgent = makeAgent({ taskList: { tasks: [] } });   // no pending tasks → not active
+    const { scheduler } = makeScheduler([idleAgent]);
+    await scheduler.processingCycle();
+    expect(scheduler._cycleHistory).toHaveLength(1);
+    expect(scheduler._cycleHistory[0].outcome).toBe('idle');
+    expect(scheduler._cycleHistory[0].activeCount).toBe(0);
+    expect(scheduler._cycleHistory[0].launched).toEqual([]);
+  });
+
+  test('outcome=all-locked when every active agent is already locked', async () => {
+    const { scheduler } = makeScheduler();
+    // Pre-lock the only active agent.
+    scheduler.agentProcessingLocks.set('a1', true);
+    scheduler._lockAcquiredAt.set('a1', new Date());
+    await scheduler.processingCycle();
+    expect(scheduler._cycleHistory).toHaveLength(1);
+    expect(scheduler._cycleHistory[0].outcome).toBe('all-locked');
+    expect(scheduler._cycleHistory[0].skippedLocked).toEqual(['a1']);
+    expect(scheduler._cycleHistory[0].launched).toEqual([]);
+  });
+
+  test('outcome=launched and includes the agent id in launched[]', async () => {
+    const { scheduler } = makeScheduler();
+    await scheduler.processingCycle();
+    expect(scheduler._cycleHistory).toHaveLength(1);
+    expect(scheduler._cycleHistory[0].outcome).toBe('launched');
+    expect(scheduler._cycleHistory[0].launched).toEqual(['a1']);
+    expect(scheduler._cycleHistory[0].activeCount).toBe(1);
+    expect(scheduler._cycleHistory[0].active[0]).toMatchObject({ agentId: 'a1', name: 'Alpha' });
+  });
+
+  test('outcome=concurrency-cap when slots are exhausted by in-flight work', async () => {
+    // Two active agents, but pretend the cap is already saturated by 3 unrelated
+    // in-flight ids. unlockedAgents.length > 0 but slotsAvailable === 0.
+    const a = makeAgent({ id: 'a1', name: 'A' });
+    const b = makeAgent({ id: 'a2', name: 'B' });
+    const { scheduler } = makeScheduler([a, b]);
+    // Saturate concurrency. Default MAX_CONCURRENT_AGENTS in scheduler = 3.
+    scheduler.agentProcessingLocks.set('ghost-1', true);
+    scheduler.agentProcessingLocks.set('ghost-2', true);
+    scheduler.agentProcessingLocks.set('ghost-3', true);
+    await scheduler.processingCycle();
+    const entry = scheduler._cycleHistory.at(-1);
+    expect(entry.outcome).toBe('concurrency-cap');
+    expect(entry.launched).toEqual([]);
+    expect(entry.skippedConcurrency.length).toBe(2);  // a1 + a2 both deferred
+    expect(entry.skippedLocked).toEqual([]);
+  });
+
+  test('cycleCounter increments monotonically, n matches the cycle order', async () => {
+    const { scheduler } = makeScheduler();
+    await scheduler.processingCycle();
+    await scheduler.processingCycle();
+    await scheduler.processingCycle();
+    expect(scheduler._cycleCounter).toBe(3);
+    const ns = scheduler._cycleHistory.map(c => c.n);
+    expect(ns).toEqual([1, 2, 3]);
+  });
+});
+
+describe('lock timestamping', () => {
+  test('processAgent acquires lock + records timestamp; release clears both', async () => {
+    const { scheduler } = makeScheduler();
+    // Stub the heavy bits inside processAgent so we exercise just the
+    // lock-acquire/release path.
+    scheduler._processAgentInner = jest.fn().mockResolvedValue(undefined);
+    // The simplest check: drive the lock map directly via the same code path
+    // processAgent uses (set + _lockAcquiredAt.set / delete + delete).
+    scheduler.agentProcessingLocks.set('a1', true);
+    scheduler._lockAcquiredAt.set('a1', new Date(Date.now() - 1234));
+    expect(scheduler.agentProcessingLocks.has('a1')).toBe(true);
+    expect(scheduler._lockAcquiredAt.get('a1')).toBeInstanceOf(Date);
+    // Release path
+    scheduler.agentProcessingLocks.delete('a1');
+    scheduler._lockAcquiredAt.delete('a1');
+    expect(scheduler.agentProcessingLocks.has('a1')).toBe(false);
+    expect(scheduler._lockAcquiredAt.has('a1')).toBe(false);
+  });
+
+  test('removeAgent clears the lock-acquired timestamp', () => {
+    const { scheduler } = makeScheduler();
+    scheduler.agentProcessingLocks.set('a1', true);
+    scheduler._lockAcquiredAt.set('a1', new Date());
+    scheduler.removeAgent('a1', 'unit-test');
+    expect(scheduler._lockAcquiredAt.has('a1')).toBe(false);
+    expect(scheduler.agentProcessingLocks.has('a1')).toBe(false);
+  });
+
+  test('stop() clears the entire _lockAcquiredAt map and _cycleHistory', () => {
+    const { scheduler } = makeScheduler();
+    // stop() early-returns if !isRunning. Force the running flag so cleanup runs.
+    scheduler.isRunning = true;
+    scheduler.agentProcessingLocks.set('a1', true);
+    scheduler._lockAcquiredAt.set('a1', new Date());
+    scheduler._recordCycle({ n: 1, outcome: 'idle' });
+    scheduler.stop();
+    expect(scheduler._lockAcquiredAt.size).toBe(0);
+    expect(scheduler._cycleHistory.length).toBe(0);
+  });
+});
+
+describe('getState() snapshot shape', () => {
+  test('top-level shape: serverTime, scheduler{}, locks[], cycles[], agents[]', async () => {
+    const { scheduler } = makeScheduler();
+    const state = await scheduler.getState();
+    expect(state).toMatchObject({
+      serverTime: expect.any(String),
+      scheduler: expect.objectContaining({
+        running: expect.any(Boolean),
+        iterationDelayMs: expect.any(Number),
+        maxConcurrent: expect.any(Number),
+        currentlyInFlight: expect.any(Number),
+        cycleCount: expect.any(Number),
+      }),
+      locks: expect.any(Array),
+      cycles: expect.any(Array),
+      agents: expect.any(Array),
+    });
+    // serverTime is ISO-parseable
+    expect(Number.isNaN(new Date(state.serverTime).getTime())).toBe(false);
+  });
+
+  test('agent row carries activity/lockHeld/queues/tasks fields', async () => {
+    const { scheduler } = makeScheduler();
+    const state = await scheduler.getState();
+    expect(state.agents).toHaveLength(1);
+    const row = state.agents[0];
+    expect(row).toMatchObject({
+      id: 'a1', name: 'Alpha',
+      mode: AGENT_MODES.AGENT,
+      status: AGENT_STATUS.ACTIVE,
+      lockHeld: false,
+      lockHeldMs: null,
+      activity: expect.objectContaining({ active: expect.any(Boolean) }),
+      tasks: expect.objectContaining({ total: 1, pending: 1 }),
+      queues: expect.objectContaining({ userMessages: 0, interAgentMessages: 0, toolResults: 0 }),
+    });
+  });
+
+  test('lockHeldMs is non-null and ≥ 0 once the lock is held', async () => {
+    const { scheduler } = makeScheduler();
+    scheduler.agentProcessingLocks.set('a1', true);
+    scheduler._lockAcquiredAt.set('a1', new Date(Date.now() - 50));
+    const state = await scheduler.getState();
+    const row = state.agents.find(r => r.id === 'a1');
+    expect(row.lockHeld).toBe(true);
+    expect(typeof row.lockHeldMs).toBe('number');
+    expect(row.lockHeldMs).toBeGreaterThanOrEqual(40);   // tolerate timer slop
+    // locks[] surfaces it too
+    expect(state.locks).toEqual([
+      expect.objectContaining({ agentId: 'a1', heldMs: expect.any(Number) }),
+    ]);
+    expect(state.scheduler.currentlyInFlight).toBe(1);
+  });
+
+  test('cycles[] reflects what was recorded by processingCycle', async () => {
+    const { scheduler } = makeScheduler();
+    await scheduler.processingCycle();   // outcome=launched, n=1
+    const state = await scheduler.getState();
+    expect(state.cycles).toHaveLength(1);
+    expect(state.cycles[0]).toMatchObject({ n: 1, outcome: 'launched', launched: ['a1'] });
+    expect(state.scheduler.cycleCount).toBe(1);
+  });
+
+  test('survives an agent without a taskList / messageQueues without throwing', async () => {
+    const stub = makeAgent({ id: 'a1', taskList: undefined, messageQueues: undefined });
+    const { scheduler } = makeScheduler([stub]);
+    const state = await scheduler.getState();
+    expect(state.agents[0].tasks).toMatchObject({ total: 0, pending: 0, inProgress: 0, completed: 0 });
+    expect(state.agents[0].queues).toMatchObject({ userMessages: 0, interAgentMessages: 0, toolResults: 0 });
+  });
+});

package/src/core/agentPool.js

@@ -203,6 +203,10 @@ class AgentPool {
       createdAt: now,
       lastActivity: now,
       pausedUntil: null,
+      // Used by platformControlTool for ancestry checks. null = created
+      // via the UI / no parent agent. Set to <agentId> when an agent
+      // creates another via the platformcontrol tool.
+      createdBy: typeof config.createdBy === 'string' ? config.createdBy : null,
       metadata: config.metadata || {},
       
       // CRITICAL: Store sessionId for API key resolution

package/src/core/agentScheduler.js

@@ -981,7 +981,13 @@ class AgentScheduler {
         role: MESSAGE_ROLES.USER,
         content: boundaryContent.trim(),
         timestamp: new Date().toISOString(),
-        type: 'task-boundary'
+        // `task-boundary` stays as the specific subtype, but it IS a
+        // tool-result drain — mark it so downstream consumers (UI filter,
+        // token accounting, export) can treat it uniformly without
+        // having to enumerate every subtype.
+        type: 'task-boundary',
+        isToolResultInjection: true,
+        originalMessageCount: staleCount,
       }, false);
 
       queues.toolResults.length = 0;
@@ -1934,6 +1940,15 @@ class AgentScheduler {
         enhancedSystemPrompt = (enhancedSystemPrompt || '') + systemConstraints;
       }
 
+      // Inject current local time. Re-evaluated every turn so the agent
+      // always sees the wall-clock time the model is answering at — useful
+      // for time-sensitive reasoning (cron expressions, "schedule for
+      // tomorrow morning", "is it past business hours?", etc.).
+      const timeContext = this.contextInjectionService.buildCurrentTimeContext();
+      if (timeContext) {
+        enhancedSystemPrompt = (enhancedSystemPrompt || '') + timeContext;
+      }
+
       // Inject external-channel routing guidance ONLY when the agent has
       // at least one live bridge. Pulls the per-channel alias list from
       // each service so the agent can address specific channels/threads

package/src/core/stateManager.js

@@ -388,6 +388,11 @@ class StateManager {
       description: teamData.description || '',
       memberAgentIds: [],
       color: teamData.color || '#3B82F6', // Default blue
+      // Used by platformControlTool's `ownedByMe` team scope. null when
+      // the team was created via the UI / by no specific agent. When an
+      // agent creates a team via the platformcontrol tool, this carries
+      // the caller's id so ownership scope filtering works.
+      createdBy: typeof teamData.createdBy === 'string' ? teamData.createdBy : null,
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString()
     };

package/src/index.js

@@ -56,6 +56,7 @@ import VisionTool from './tools/visionTool.js';
 import UserPromptTool from './tools/userPromptTool.js';
 import CodeMapTool from './tools/codeMapTool.js';
 import WhatsAppTool from './tools/whatsappTool.js';
+import PlatformControlTool from './tools/platformControlTool.js';
 import ScheduleService from './services/scheduleService.js';
 import AsyncToolManager from './tools/asyncToolManager.js';
 import WebServer from './interfaces/webServer.js';
@@ -485,6 +486,18 @@ class LoxiaApplication {
     // Register WhatsApp Tool
     await this.toolsRegistry.registerTool(WhatsAppTool);
 
+    // Register Platform Control Tool — agent-facing platform control
+    // (currently: scheduled tasks; per-agent permission, default DISABLED).
+    await this.toolsRegistry.registerTool(PlatformControlTool);
+
+    // widget-module: remove this block if the module is deleted.
+    // Registers the WidgetTool for agent-facing custom-UI rendering.
+    // Honors LOXIA_DISABLE_WIDGETS=1 env flag for a zero-source kill switch.
+    const widgetModule = await import('./modules/widget/index.js');
+    if (!widgetModule.isDisabled()) {
+      await this.toolsRegistry.registerTool(widgetModule.WidgetTool);
+    }
+
     // Set ToolsRegistry dependency for HelpTool (two-layer tool description system)
     const helpTool = this.toolsRegistry.getTool('help');
     if (helpTool && typeof helpTool.setToolsRegistry === 'function') {
@@ -497,6 +510,27 @@ class LoxiaApplication {
     if (agentDelayTool && typeof agentDelayTool.setAgentPool === 'function') {
       agentDelayTool.setAgentPool(this.agentPool);
     }
+
+    // Wire ScheduleService into PlatformControlTool. Without this, the
+    // tool reports "ScheduleService is not available" for any feature
+    // action — useful as a defensive default but not what we want here.
+    const platformControlTool = this.toolsRegistry.getTool('platformcontrol');
+    if (platformControlTool) {
+      if (typeof platformControlTool.setScheduleService === 'function') {
+        platformControlTool.setScheduleService(this.scheduleService);
+      }
+      // Agent + team CRUD requires AgentPool, StateManager, MemoryService.
+      if (typeof platformControlTool.setAgentPool === 'function') {
+        platformControlTool.setAgentPool(this.agentPool);
+      }
+      if (typeof platformControlTool.setStateManager === 'function') {
+        platformControlTool.setStateManager(this.stateManager);
+      }
+      if (typeof platformControlTool.setMemoryService === 'function') {
+        const { getMemoryService } = await import('./services/memoryService.js');
+        platformControlTool.setMemoryService(getMemoryService(this.logger));
+      }
+    }
     
     // Set AgentPool dependency for JobDoneTool
     const jobDoneTool = this.toolsRegistry.getTool('jobdone');

package/src/interfaces/__tests__/agentContextRoutes.test.js

@@ -0,0 +1,272 @@
+/**
+ * HTTP route tests for the agent memory + context-snapshot routes.
+ *
+ * Mounts a real express app + the production registerAgentContextRoutes
+ * helper with stubbed memory service / agent pool, hits each endpoint via
+ * fetch, asserts the JSON shape. Same approach as schedulerRoutes.test.js.
+ */
+import { jest, describe, it, expect, beforeAll, afterAll } from '@jest/globals';
+import express from 'express';
+import { createServer } from 'http';
+import { registerAgentContextRoutes } from '../agentContextRoutes.js';
+
+async function http(url, options = {}) {
+  const resp = await globalThis.fetch(url, options);
+  const ct = resp.headers.get('content-type') || '';
+  const body = ct.includes('json') ? await resp.json() : await resp.text();
+  return { status: resp.status, body };
+}
+
+function makeMemoryService() {
+  const mems = new Map();   // agentId → memories[]
+  return {
+    loadMemories: jest.fn(async (agentId) => mems.get(agentId) || []),
+    addMemory:    jest.fn(async (agentId, data) => {
+      const mem = { id: 'm-' + Date.now() + '-' + Math.random().toString(36).slice(2, 6), ...data, createdAt: new Date().toISOString() };
+      const list = mems.get(agentId) || [];
+      list.push(mem);
+      mems.set(agentId, list);
+      return mem;
+    }),
+    updateMemory: jest.fn(async (agentId, memId, updates) => {
+      const list = mems.get(agentId) || [];
+      const i = list.findIndex(m => m.id === memId);
+      if (i === -1) return null;
+      list[i] = { ...list[i], ...updates, updatedAt: new Date().toISOString() };
+      return list[i];
+    }),
+    deleteMemory: jest.fn(async (agentId, memId) => {
+      const list = mems.get(agentId) || [];
+      const i = list.findIndex(m => m.id === memId);
+      if (i === -1) return false;
+      list.splice(i, 1);
+      return true;
+    }),
+    _store: mems,
+  };
+}
+
+function startApp({ memoryService, agentPool }) {
+  const app = express();
+  app.use(express.json());
+  registerAgentContextRoutes(app, {
+    getAgentPool: () => agentPool,
+    getMemoryService: () => memoryService,
+    logger: { error: jest.fn(), warn: jest.fn() },
+  });
+  const server = createServer(app);
+  return new Promise(resolve => {
+    server.listen(0, () => {
+      const port = server.address().port;
+      resolve({ server, baseUrl: `http://localhost:${port}` });
+    });
+  });
+}
+
+describe('memory CRUD', () => {
+  let server, baseUrl, mem;
+  beforeAll(async () => {
+    mem = makeMemoryService();
+    ({ server, baseUrl } = await startApp({ memoryService: mem, agentPool: null }));
+  });
+  afterAll(() => server?.close());
+
+  it('GET memories returns empty list initially', async () => {
+    const r = await http(`${baseUrl}/api/agents/agent-x/memories`);
+    expect(r.status).toBe(200);
+    expect(r.body).toEqual({ success: true, count: 0, memories: [] });
+  });
+
+  it('POST adds a memory and returns it', async () => {
+    const r = await http(`${baseUrl}/api/agents/agent-x/memories`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: 'A note', content: 'remember this' }),
+    });
+    expect(r.status).toBe(200);
+    expect(r.body.memory).toMatchObject({ title: 'A note', content: 'remember this' });
+    expect(r.body.memory.id).toMatch(/^m-/);
+  });
+
+  it('POST trims title/description; rejects empty title', async () => {
+    const r1 = await http(`${baseUrl}/api/agents/agent-x/memories`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: '   ', content: 'x' }),
+    });
+    expect(r1.status).toBe(400);
+    const r2 = await http(`${baseUrl}/api/agents/agent-x/memories`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: '  Trimmed  ', description: '  desc  ', content: 'c' }),
+    });
+    expect(r2.status).toBe(200);
+    expect(r2.body.memory.title).toBe('Trimmed');
+    expect(r2.body.memory.description).toBe('desc');
+  });
+
+  it('POST rejects when content is missing', async () => {
+    const r = await http(`${baseUrl}/api/agents/agent-x/memories`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: 'no content' }),
+    });
+    expect(r.status).toBe(400);
+    expect(r.body.error).toMatch(/content/);
+  });
+
+  it('PUT updates an existing memory', async () => {
+    const created = await http(`${baseUrl}/api/agents/agent-x/memories`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: 'orig', content: 'c' }),
+    });
+    const id = created.body.memory.id;
+    const r = await http(`${baseUrl}/api/agents/agent-x/memories/${id}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: 'updated' }),
+    });
+    expect(r.status).toBe(200);
+    expect(r.body.memory.title).toBe('updated');
+  });
+
+  it('PUT 404s on unknown memoryId', async () => {
+    const r = await http(`${baseUrl}/api/agents/agent-x/memories/nope`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: 'x' }),
+    });
+    expect(r.status).toBe(404);
+  });
+
+  it('DELETE removes a memory', async () => {
+    const created = await http(`${baseUrl}/api/agents/agent-x/memories`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: 'goner', content: 'bye' }),
+    });
+    const id = created.body.memory.id;
+    const r = await http(`${baseUrl}/api/agents/agent-x/memories/${id}`, { method: 'DELETE' });
+    expect(r.status).toBe(200);
+    expect(r.body.success).toBe(true);
+    // PUT after delete → 404
+    const after = await http(`${baseUrl}/api/agents/agent-x/memories/${id}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title: 'x' }),
+    });
+    expect(after.status).toBe(404);
+  });
+
+  it('DELETE 404s on unknown memoryId', async () => {
+    const r = await http(`${baseUrl}/api/agents/agent-x/memories/nope`, { method: 'DELETE' });
+    expect(r.status).toBe(404);
+  });
+});
+
+describe('context snapshot', () => {
+  let server, baseUrl;
+  const messages = [
+    { role: 'system', content: 'system…' },
+    { role: 'user', content: 'hello' },
+    { role: 'assistant', content: 'hi there' },
+  ];
+  const agent = {
+    id: 'agent-x', name: 'Test', mode: 'AGENT', status: 'ACTIVE',
+    currentModel: 'gpt-x',
+    preferredModel: 'gpt-x',
+    originalSystemPrompt: 'You are helpful.',
+    systemPrompt: 'You are helpful.\n\n[Tools: ...]',
+    messageQueues: {
+      userMessages: [{ content: 'pending user msg', timestamp: '2026-04-26T00:00:00Z' }],
+      interAgentMessages: [],
+      toolResults: [{ content: 'tool result body' }],
+    },
+  };
+  const agentPool = {
+    getAgent: jest.fn(async (id) => id === 'agent-x' ? agent : null),
+    getMessagesForAI: jest.fn(async () => messages),
+  };
+
+  beforeAll(async () => {
+    ({ server, baseUrl } = await startApp({
+      memoryService: makeMemoryService(),
+      agentPool,
+    }));
+  });
+  afterAll(() => server?.close());
+
+  it('returns the full snapshot shape', async () => {
+    const r = await http(`${baseUrl}/api/agents/agent-x/context-snapshot`);
+    expect(r.status).toBe(200);
+    expect(r.body).toMatchObject({
+      success: true,
+      agent: { id: 'agent-x', name: 'Test', currentModel: 'gpt-x' },
+      systemPrompt: {
+        original: 'You are helpful.',
+        full: 'You are helpful.\n\n[Tools: ...]',
+        originalLength: 16,
+        fullLength: 30,
+        enhancementBytes: 14,
+      },
+      pendingQueues: {
+        userMessages: [expect.objectContaining({ contentPreview: 'pending user msg' })],
+        interAgentMessages: [],
+        toolResults: [expect.objectContaining({ contentPreview: 'tool result body' })],
+      },
+    });
+    expect(r.body.messages).toHaveLength(3);
+    expect(r.body.messages[0]).toMatchObject({ index: 0, role: 'system' });
+    expect(r.body.stats.messageCount).toBe(3);
+    expect(r.body.stats.estimatedTokens).toBeGreaterThan(0);
+  });
+
+  it('truncates very long message content (with `truncated:true`)', async () => {
+    const huge = 'x'.repeat(10_000);
+    agentPool.getMessagesForAI.mockResolvedValueOnce([{ role: 'user', content: huge }]);
+    const r = await http(`${baseUrl}/api/agents/agent-x/context-snapshot`);
+    expect(r.body.messages[0].truncated).toBe(true);
+    expect(r.body.messages[0].contentPreview.length).toBeLessThan(huge.length);
+    expect(r.body.messages[0].contentLength).toBe(huge.length);
+  });
+
+  it('returns 404 for unknown agent', async () => {
+    const r = await http(`${baseUrl}/api/agents/missing/context-snapshot`);
+    expect(r.status).toBe(404);
+  });
+
+  it('surfaces messagesError when getMessagesForAI throws (rather than 500ing)', async () => {
+    agentPool.getMessagesForAI.mockRejectedValueOnce(new Error('boom'));
+    const r = await http(`${baseUrl}/api/agents/agent-x/context-snapshot`);
+    expect(r.status).toBe(200);          // snapshot still returns
+    expect(r.body.messages).toEqual([]);
+    expect(r.body.messagesError).toMatch(/boom/);
+    // System prompt + queues still surface for UI use
+    expect(r.body.systemPrompt.full).toBeTruthy();
+  });
+});
+
+describe('defensive', () => {
+  it('agentPool unavailable → 503 on context-snapshot, but memory routes still work', async () => {
+    const mem = makeMemoryService();
+    const { server, baseUrl } = await startApp({ memoryService: mem, agentPool: null });
+    try {
+      const ctx = await http(`${baseUrl}/api/agents/agent-x/context-snapshot`);
+      expect(ctx.status).toBe(503);
+      const list = await http(`${baseUrl}/api/agents/agent-x/memories`);
+      expect(list.status).toBe(200);
+    } finally { server.close(); }
+  });
+
+  it('registerAgentContextRoutes(null) is a no-op', () => {
+    expect(() => registerAgentContextRoutes(null, {})).not.toThrow();
+  });
+
+  it('registerAgentContextRoutes without getMemoryService skips registration', () => {
+    const app = express();
+    expect(() => registerAgentContextRoutes(app, { getAgentPool: () => null })).not.toThrow();
+    // No routes added — sanity check by hitting one (will 404 since unmounted).
+    // We don't need a server; the express stack just won't have these handlers.
+  });
+});