onbuzz 4.4.0 → 4.6.0

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()
     };
@@ -616,8 +621,10 @@ class StateManager {
       throw new Error(`Flow ${flowId} not found`);
     }
 
-    // Only allow updating specific fields
-    const allowedFields = ['name', 'description', 'nodes', 'edges', 'variables'];
+    // Only allow updating specific fields. `version` and `schemaVersion`
+    // are added so the Phase 6 version-stamp write-back persists, and
+    // so v2 flows can be marked when typed I/O is added.
+    const allowedFields = ['name', 'description', 'nodes', 'edges', 'variables', 'version', 'schemaVersion'];
     for (const field of allowedFields) {
       if (updates[field] !== undefined) {
         flowIndex[flowId][field] = updates[field];
@@ -781,25 +788,77 @@ class StateManager {
     const stateDir = this.getStateDir(projectDir);
     const stateFile = path.join(stateDir, agentInfo.stateFile);
     const conversationsFile = path.join(stateDir, agentInfo.conversationsFile);
-    
+
+    // Skeleton defaults the resilient loader falls back to when a state
+    // file is missing, empty, or unrepairable. The state skeleton derives
+    // the agent name from the index entry so even a total wipe leaves
+    // the agent identifiable in the UI rather than ending up nameless.
+    const stateDefault = () => ({
+      version: 2,
+      agentId,
+      state: {
+        id: agentId,
+        name: agentInfo.name || agentId,
+        type: agentInfo.type || 'user-created',
+        status: 'active',
+        mode: 'chat',
+        currentModel: agentInfo.preferredModel || agentInfo.model || null,
+        preferredModel: agentInfo.preferredModel || agentInfo.model || null,
+        systemPrompt: '',
+        capabilities: agentInfo.capabilities || [],
+        taskList: { tasks: [], lastUpdated: new Date().toISOString() },
+        messageQueues: { userMessages: [], interAgentMessages: [], toolResults: [] },
+        interAgentTracking: {},
+      },
+      lastPersisted: new Date().toISOString(),
+    });
+    const conversationsDefault = () => ({
+      version: 2,
+      agentId,
+      conversations: {
+        // Empty `full` conversation — required by validateModelConversations
+        // and the agent loop's history reader. New per-model entries are
+        // added on demand at first use.
+        full: { messages: [], lastUpdated: new Date().toISOString() },
+      },
+      lastPersisted: new Date().toISOString(),
+    });
+
+    // Recovery reports for any auto-fixed files. Attached to the
+    // returned agent so the caller (orchestrator → webServer) can
+    // broadcast each one as a toast in the UI. Empty array on the
+    // happy path; harmless presence otherwise.
+    const recoveries = [];
+
     try {
-      // Load agent state
-      const stateData = await this.loadJSON(stateFile);
-      const conversationsData = await this.loadJSON(conversationsFile);
-      
+      const stateRes = await this.loadJSONResilient(stateFile, stateDefault, {
+        label: `agent state (${agentInfo.name || agentId})`,
+      });
+      const conversationsRes = await this.loadJSONResilient(conversationsFile, conversationsDefault, {
+        label: `agent conversations (${agentInfo.name || agentId})`,
+      });
+      const stateData = stateRes.data;
+      const conversationsData = conversationsRes.data;
+      if (stateRes.recovery) recoveries.push(stateRes.recovery);
+      if (conversationsRes.recovery) recoveries.push(conversationsRes.recovery);
+
       // Validate model conversations integrity
       await this.validateModelConversations(conversationsData.conversations);
-      
+
       // Check if agent is paused
       const pauseStatus = await this.checkAgentPauseStatus(agentId, projectDir);
-      
+
       const restoredAgent = {
         ...stateData.state,
         conversations: conversationsData.conversations,
         isPaused: pauseStatus.isPaused,
         pausedUntil: pauseStatus.pausedUntil,
         isRestored: true,
-        restoredAt: new Date().toISOString()
+        restoredAt: new Date().toISOString(),
+        // Non-enumerable would be cleaner, but agentPool serializes the
+        // whole object — keeping it as a plain field. The orchestrator
+        // strips it before persisting (see import handler).
+        _restoreRecoveries: recoveries,
       };
 
       // CRITICAL: Restore interAgentTracking as a Map (it comes as plain object from JSON)
@@ -808,15 +867,16 @@ class StateManager {
       } else if (!(restoredAgent.interAgentTracking instanceof Map)) {
         restoredAgent.interAgentTracking = new Map(Object.entries(restoredAgent.interAgentTracking));
       }
-      
+
       this.logger.info(`Agent restored: ${agentId}`, {
         name: restoredAgent.name,
         status: restoredAgent.status,
-        messageCount: restoredAgent.conversations?.full?.messages?.length || 0
+        messageCount: restoredAgent.conversations?.full?.messages?.length || 0,
+        recoveryCount: recoveries.length,
       });
-      
+
       return restoredAgent;
-      
+
     } catch (error) {
       this.logger.error(`Agent restoration failed: ${agentId}`, error.message);
       throw error;
@@ -1069,7 +1129,7 @@ class StateManager {
   }
 
   /**
-   * Load JSON data from file
+   * Load JSON data from file (strict — throws on missing or corrupt).
    * @private
    */
   async loadJSON(filePath) {
@@ -1077,6 +1137,185 @@ class StateManager {
     return JSON.parse(data);
   }
 
+  /**
+   * Load JSON with best-effort recovery from common breakage modes.
+   * Designed so a single bad state file doesn't take down the entire
+   * agent-load flow — instead the caller gets back a usable object plus
+   * a `recovery` report that callers can surface as a toast.
+   *
+   * Recovery ladder (first match wins):
+   *   1. Missing file (ENOENT)             → recreate with `defaultValue`,
+   *                                          report `kind='not-found'`
+   *   2. Empty / whitespace-only file       → overwrite with `defaultValue`,
+   *                                          report `kind='empty-recreated'`
+   *   3. Common syntax issues               → repaired in memory and saved
+   *      (trailing comma, BOM, unclosed       back to disk; report
+   *      braces/brackets, stray garbage       `kind='repaired'`
+   *      after the JSON object)
+   *   4. Salvageable first JSON block       → use the salvaged object,
+   *      (anywhere in the buffer)             archive the original to
+   *                                          `<file>.corrupt-<ts>.json`,
+   *                                          report `kind='partial'`
+   *   5. Nothing usable                     → use `defaultValue`, archive
+   *                                          original (if any), report
+   *                                          `kind='unrepairable'`
+   *
+   * @param {string} filePath - Absolute path to the JSON file
+   * @param {Object|Array|null|Function} defaultValue - Value to use when
+   *   the file is missing/empty/unrepairable. If a function is provided
+   *   it's called with the file path and its return value is used.
+   * @param {Object} [options]
+   * @param {boolean} [options.persistRecreated=true] - Whether to write
+   *   the default back to disk on missing/empty/unrepairable cases.
+   * @param {string} [options.label] - Human-readable label used in toast
+   *   messages (e.g. 'agent state', 'agent conversations'). Falls back
+   *   to the file's basename.
+   * @returns {Promise<{data: any, recovery: ?Object}>}
+   */
+  async loadJSONResilient(filePath, defaultValue, options = {}) {
+    const { persistRecreated = true } = options;
+    const label = options.label || path.basename(filePath);
+    const defaultOf = () =>
+      typeof defaultValue === 'function' ? defaultValue(filePath) : defaultValue;
+
+    // 1. Missing file → recreate with default
+    let raw;
+    try {
+      raw = await fs.readFile(filePath, 'utf8');
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        const data = defaultOf();
+        if (persistRecreated && data !== undefined) {
+          try { await this.saveJSON(filePath, data); } catch { /* tolerate read-only mounts */ }
+        }
+        const recovery = {
+          kind: 'not-found', filePath, label,
+          message: `${label} file was missing — created an empty one.`,
+        };
+        this.logger?.info(`[stateManager] ${recovery.message}`, { filePath });
+        return { data, recovery };
+      }
+      throw err; // unexpected read error (permissions, etc) — let caller handle
+    }
+
+    // 2. Empty or whitespace-only → recreate
+    if (!raw || raw.trim().length === 0) {
+      const data = defaultOf();
+      if (persistRecreated && data !== undefined) {
+        try { await this.saveJSON(filePath, data); } catch { /* ok */ }
+      }
+      const recovery = {
+        kind: 'empty-recreated', filePath, label,
+        message: `${label} file was empty — recreated with a default skeleton.`,
+      };
+      this.logger?.warn(`[stateManager] ${recovery.message}`, { filePath });
+      return { data, recovery };
+    }
+
+    // 3. Strict parse — happy path
+    try {
+      return { data: JSON.parse(raw), recovery: null };
+    } catch (firstErr) {
+      // 3a. Quick repairs: BOM, trailing comma before close, junk after
+      // the closing brace, smart quotes that occasionally creep in via
+      // copy-paste. None of these is exotic — they're the top-3 reasons
+      // hand-edited or partially-flushed files break.
+      let repaired = raw;
+      if (repaired.charCodeAt(0) === 0xFEFF) repaired = repaired.slice(1);
+      // Strip ASCII control chars except tab/newline/CR
+      repaired = repaired.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '');
+      // Trim whitespace
+      repaired = repaired.trim();
+      // Drop trailing commas before a closing } or ]
+      repaired = repaired.replace(/,(\s*[}\]])/g, '$1');
+      // Cut anything after the last balanced } / ] (junk after JSON).
+      const lastClose = Math.max(repaired.lastIndexOf('}'), repaired.lastIndexOf(']'));
+      if (lastClose > 0 && lastClose < repaired.length - 1) {
+        repaired = repaired.slice(0, lastClose + 1);
+      }
+      try {
+        const data = JSON.parse(repaired);
+        if (persistRecreated && repaired !== raw) {
+          try { await this.saveJSON(filePath, data); } catch { /* ok */ }
+        }
+        const recovery = {
+          kind: 'repaired', filePath, label,
+          message: `${label} file had a minor syntax issue (${firstErr.message}) — auto-repaired.`,
+        };
+        this.logger?.warn(`[stateManager] ${recovery.message}`, { filePath });
+        return { data, recovery };
+      } catch { /* fall through */ }
+
+      // 3b. Salvage: walk the buffer for the first balanced { ... } block
+      // and try to parse just that. Catches truncated-mid-file cases.
+      const salvaged = this._extractFirstJsonBlock(raw);
+      if (salvaged) {
+        try {
+          const data = JSON.parse(salvaged);
+          const archivePath = `${filePath}.corrupt-${Date.now()}.json`;
+          try { await fs.writeFile(archivePath, raw, 'utf8'); } catch { /* ok */ }
+          if (persistRecreated) {
+            try { await this.saveJSON(filePath, data); } catch { /* ok */ }
+          }
+          const recovery = {
+            kind: 'partial', filePath, label,
+            message: `${label} file was partially corrupt — recovered the first valid section. Original archived to ${path.basename(archivePath)}.`,
+            archivePath,
+          };
+          this.logger?.warn(`[stateManager] ${recovery.message}`, { filePath, archivePath });
+          return { data, recovery };
+        } catch { /* fall through */ }
+      }
+
+      // 4. Nothing parseable — archive the corrupt file and use default
+      const data = defaultOf();
+      const archivePath = `${filePath}.corrupt-${Date.now()}.json`;
+      try { await fs.writeFile(archivePath, raw, 'utf8'); } catch { /* ok */ }
+      if (persistRecreated && data !== undefined) {
+        try { await this.saveJSON(filePath, data); } catch { /* ok */ }
+      }
+      const recovery = {
+        kind: 'unrepairable', filePath, label,
+        message: `${label} file is corrupt and could not be repaired — restored a default skeleton. Original archived to ${path.basename(archivePath)}.`,
+        archivePath,
+        originalError: firstErr.message,
+      };
+      this.logger?.error(`[stateManager] ${recovery.message}`, { filePath, archivePath, error: firstErr.message });
+      return { data, recovery };
+    }
+  }
+
+  /**
+   * Walk a string and return the substring of the first balanced
+   * `{ ... }` block, respecting string literals so braces inside strings
+   * don't confuse the count. Returns null if no complete block exists.
+   * @private
+   */
+  _extractFirstJsonBlock(s) {
+    if (typeof s !== 'string') return null;
+    const start = s.indexOf('{');
+    if (start < 0) return null;
+    let depth = 0;
+    let inStr = false;
+    let escape = false;
+    for (let i = start; i < s.length; i++) {
+      const ch = s[i];
+      if (inStr) {
+        if (escape) { escape = false; continue; }
+        if (ch === '\\') { escape = true; continue; }
+        if (ch === '"') { inStr = false; }
+        continue;
+      }
+      if (ch === '"') { inStr = true; continue; }
+      if (ch === '{') depth++;
+      else if (ch === '}') {
+        depth--;
+        if (depth === 0) return s.slice(start, i + 1);
+      }
+    }
+    return null;
+  }
+
   /**
    * Delete agent state from storage
    * @param {string} agentId - Agent identifier

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';
@@ -383,6 +384,14 @@ class LoxiaApplication {
       this.stateManager
     );
 
+    // Expose toolsRegistry on the orchestrator so downstream wiring (e.g.
+    // webServer's flowExecutor init at webServer.js:574 → jobDoneTool
+    // setFlowExecutor) can reach it through the orchestrator handle. Without
+    // this, `this.orchestrator?.toolsRegistry` is undefined at wiring time
+    // and JobDoneTool's flow-contract validation (Phase 8) silently no-ops
+    // for the entire process lifetime.
+    this.orchestrator.toolsRegistry = this.toolsRegistry;
+
     // Set cross-references between components
     this.messageProcessor.orchestrator = this.orchestrator;
     this.messageProcessor.setScheduler(this.agentScheduler);
@@ -485,6 +494,10 @@ 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.
@@ -505,6 +518,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.
+  });
+});