@loxia-labs/loxia-autopilot-one 5.3.0 → 5.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loxia-labs/loxia-autopilot-one",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "description": "Loxia AI Agents System - No-code/vibe-code/companion-coder platform",
   "type": "module",
   "main": "src/index.js",

package/src/core/agentPool.js

@@ -144,7 +144,8 @@ class AgentPool {
             layered: config.layeredToolDescriptions || false,
             includeExamples: config.includeToolExamples !== false,
             includeUsageGuidelines: config.includeUsageGuidelines !== false,
-            includeSecurityNotes: config.includeSecurityNotes !== false
+            includeSecurityNotes: config.includeSecurityNotes !== false,
+            mode: config.mode  // gates the jobdone must-have (AGENT mode only)
           }
         );
         
@@ -429,7 +430,8 @@ class AgentPool {
             compact: agent.compactToolDescriptions || false,
             includeExamples: agent.includeToolExamples !== false,
             includeUsageGuidelines: agent.includeUsageGuidelines !== false,
-            includeSecurityNotes: agent.includeSecurityNotes !== false
+            includeSecurityNotes: agent.includeSecurityNotes !== false,
+            mode: updates.mode || agent.mode  // gates the jobdone must-have
           }
         );
 
@@ -1341,7 +1343,8 @@ class AgentPool {
           compact: options.compact || false,
           includeExamples: options.includeExamples !== false,
           includeUsageGuidelines: options.includeUsageGuidelines !== false,
-          includeSecurityNotes: options.includeSecurityNotes !== false
+          includeSecurityNotes: options.includeSecurityNotes !== false,
+          mode: agent.mode  // gates the jobdone must-have (AGENT mode only)
         }
       );
 

package/src/core/agentScheduler.js

@@ -2513,7 +2513,7 @@ class AgentScheduler {
       // them back into the CLI's inline JSON-block format on the wire. For
       // chat-completion models the backend ignores this field and the model
       // uses the system prompt's inline-JSON instructions as before.
-      const toolSchemas = getToolSchemasForAgent(agent.capabilities || []);
+      const toolSchemas = getToolSchemasForAgent(agent.capabilities || [], agent.mode);
 
       if (streamingEnabled && this.aiService.sendMessageStream) {
         // Build flow context if this is part of a flow execution
@@ -2641,7 +2641,7 @@ class AgentScheduler {
       let rebuilt = registry.enhanceSystemPrompt(
         agent.originalSystemPrompt,
         agent.capabilities || [],
-        { apiType: 'responses' },
+        { apiType: 'responses', mode: agent.mode },
       );
 
       // Re-inject ASSIGNED SKILLS block if present (createAgent appends

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

@@ -226,3 +226,91 @@ describe('/api/images/:sessionId/:filename', () => {
     expect(body.error).toBe('Image not found');
   });
 });
+
+// ── /api/image?path=… (serve an image by absolute path) ─────────────
+
+function buildImageByPathApp() {
+  const app = express();
+  // Replicate the exact route from webServer.js
+  app.get('/api/image', async (req, res) => {
+    try {
+      const raw = req.query.path;
+      if (!raw || typeof raw !== 'string') {
+        return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'path query is required' });
+      }
+      const resolved = path.resolve(raw);
+      const ext = path.extname(resolved).toLowerCase();
+      const ALLOWED = ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp', '.svg'];
+      if (!ALLOWED.includes(ext)) {
+        return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Unsupported image type' });
+      }
+      const stats = await fs.stat(resolved).catch(() => null);
+      if (!stats || !stats.isFile()) {
+        return res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Image not found' });
+      }
+      res.sendFile(resolved, (err) => {
+        if (err && !res.headersSent) {
+          res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Image not found' });
+        }
+      });
+    } catch (error) {
+      res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: error.message });
+    }
+  });
+  return app;
+}
+
+describe('/api/image?path=', () => {
+  let server, baseUrl, tmpDir, imgPath, txtPath;
+
+  beforeAll(async () => {
+    tmpDir = path.join(os.tmpdir(), `loxia-img-bypath-${Date.now()}`);
+    await fs.mkdir(tmpDir, { recursive: true });
+    imgPath = path.join(tmpDir, 'pic.png');
+    txtPath = path.join(tmpDir, 'notes.txt');
+    await fs.writeFile(imgPath, Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]));
+    await fs.writeFile(txtPath, 'not an image');
+
+    server = createServer(buildImageByPathApp());
+    await new Promise(resolve => server.listen(0, resolve));
+    baseUrl = `http://localhost:${server.address().port}`;
+  });
+
+  afterAll(async () => {
+    server?.close();
+    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('400 when path is missing', async () => {
+    const { status, body } = await fetch(`${baseUrl}/api/image`);
+    expect(status).toBe(400);
+    expect(body.error).toMatch(/path query is required/);
+  });
+
+  it('400 for a non-image extension', async () => {
+    const { status, body } = await fetch(`${baseUrl}/api/image?path=${encodeURIComponent(txtPath)}`);
+    expect(status).toBe(400);
+    expect(body.error).toMatch(/Unsupported image type/);
+  });
+
+  it('404 for an image path that does not exist', async () => {
+    const missing = path.join(tmpDir, 'ghost.png');
+    const { status, body } = await fetch(`${baseUrl}/api/image?path=${encodeURIComponent(missing)}`);
+    expect(status).toBe(404);
+    expect(body.error).toBe('Image not found');
+  });
+
+  it('404 when the path is a directory, not a file', async () => {
+    // A directory named like an image so the extension check passes.
+    const dirLikeImage = path.join(tmpDir, 'folder.png');
+    await fs.mkdir(dirLikeImage, { recursive: true });
+    const { status } = await fetch(`${baseUrl}/api/image?path=${encodeURIComponent(dirLikeImage)}`);
+    expect(status).toBe(404);
+  });
+
+  it('serves an existing image by absolute path', async () => {
+    const { status, headers } = await fetch(`${baseUrl}/api/image?path=${encodeURIComponent(imgPath)}`);
+    expect(status).toBe(200);
+    expect(headers.get('content-type')).toMatch(/image|octet/);
+  });
+});

package/src/interfaces/terminal/config/agentEditorConstants.js

@@ -34,14 +34,18 @@ export const AVAILABLE_TOOLS = [
   { name: 'Web', value: 'web', description: 'Fetch, browse, and interact with web content' },
   // Browser tool is DEPRECATED - use Web tool instead
   { name: 'Image', value: 'image-gen', description: 'Generate and process images' },
-  { name: 'TaskManager', value: 'taskmanager', description: 'Manage and track tasks' },
+  // TaskManager is a MUST-HAVE tool — always advertised to every agent
+  // (see src/utilities/mustHaveCapabilities.js), so it is not user-selectable.
+  // { name: 'TaskManager', value: 'taskmanager', description: 'Manage and track tasks' },
   { name: 'StaticAnalysis', value: 'staticanalysis', description: 'Analyze code structure and patterns' },
   { name: 'DependencyResolver', value: 'dependency-resolver', description: 'Analyze and resolve dependencies' },
   { name: 'ImportAnalyzer', value: 'import-analyzer', description: 'Analyze import statements' },
   { name: 'CloneDetection', value: 'clonedetection', description: 'Detect code duplication' },
   { name: 'FileContentReplace', value: 'file-content-replace', description: 'Advanced find and replace' },
   { name: 'AgentCommunication', value: 'agentcommunication', description: 'Communicate with other agents' },
-  { name: 'JobDone', value: 'jobdone', description: 'Signal task completion in autonomous mode' },
+  // JobDone is a MUST-HAVE tool in AGENT mode — always advertised to autonomous
+  // agents (see src/utilities/mustHaveCapabilities.js), so it is not selectable.
+  // { name: 'JobDone', value: 'jobdone', description: 'Signal task completion in autonomous mode' },
   { name: 'AgentDelay', value: 'agentdelay', description: 'Pause agent activity for a duration' },
   { name: 'VisualEditor', value: 'visual-editor', description: 'Visual editing of web apps with element selection' },
   // TODO: Re-enable once Sora replacement is available

package/src/interfaces/webServer.js

@@ -2955,6 +2955,38 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
       }
     });
 
+    // Serve an image file by absolute path. The filename-only endpoints below
+    // can't help the renderers: Vision analyzes arbitrary local images (they
+    // can live anywhere the user points), and the image tool saves to agent
+    // working dirs. A browser <img> can't load a local path directly, so the UI
+    // routes local paths through here. Gated to image extensions + existence;
+    // this is a localhost app whose agents already have filesystem access.
+    this.app.get('/api/image', async (req, res) => {
+      try {
+        const raw = req.query.path;
+        if (!raw || typeof raw !== 'string') {
+          return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'path query is required' });
+        }
+        const resolved = path.resolve(raw);
+        const ext = path.extname(resolved).toLowerCase();
+        const ALLOWED = ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp', '.svg'];
+        if (!ALLOWED.includes(ext)) {
+          return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Unsupported image type' });
+        }
+        const stats = await fs.stat(resolved).catch(() => null);
+        if (!stats || !stats.isFile()) {
+          return res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Image not found' });
+        }
+        res.sendFile(resolved, (err) => {
+          if (err && !res.headersSent) {
+            res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Image not found' });
+          }
+        });
+      } catch (error) {
+        res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: error.message });
+      }
+    });
+
     // Image serving endpoint for generated images
     this.app.get('/api/images/:sessionId/:filename', async (req, res) => {
       try {

package/src/services/__tests__/agentActivityService.test.js

@@ -225,14 +225,27 @@ describe('agentActivityService', () => {
       expect(result.reason).toBe('has-inter-agent-messages');
     });
 
-    test('CHAT mode: inactive with only tool results', () => {
+    test('CHAT mode: ACTIVE with queued tool results (agentic continuation)', () => {
+      // A chat agent that fired a tool must wake when the result lands so it can
+      // read the output and answer — covers sync (scheduler push) and async
+      // (addToolResult) delivery identically, since both leave a result in the
+      // queue and this keys off queue state.
       const result = shouldAgentBeActive(makeAgent({
         mode: 'chat',
-        messageQueues: { toolResults: [{ id: 1 }] }
+        messageQueues: { toolResults: [{ id: 1 }, { id: 2 }] }
       }));
-      expect(result.active).toBe(false);
-      expect(result.reason).toBe('chat-mode-no-messages');
-      expect(result.details).toContain('tool results');
+      expect(result.active).toBe(true);
+      expect(result.reason).toBe('has-tool-results');
+      expect(result.details).toContain('2 tool result');
+    });
+
+    test('CHAT mode: user messages still take priority over tool results', () => {
+      const result = shouldAgentBeActive(makeAgent({
+        mode: 'chat',
+        messageQueues: { userMessages: [{ id: 1 }], toolResults: [{ id: 2 }] }
+      }));
+      expect(result.active).toBe(true);
+      expect(result.reason).toBe('has-user-messages');
     });
 
     test('CHAT mode: inactive with no messages', () => {

package/src/services/__tests__/promptService.test.js

@@ -46,6 +46,27 @@ describe('PromptService', () => {
     expect(service.pendingRequests.size).toBe(1);
   });
 
+  test('createPromptRequest with timeout:null sets no auto-timeout', () => {
+    const { requestInfo, promise } = service.createPromptRequest('agent-1', {
+      questions: [{ message: 'Q?' }]
+    }, { timeout: null });
+
+    expect(requestInfo.timeoutAt).toBeNull();
+    expect(requestInfo.timeoutMs).toBeNull();
+    // No timeout handle scheduled → advancing time does not reject the promise.
+    let settled = false;
+    promise.then(() => { settled = true; }, () => { settled = true; });
+    jest.advanceTimersByTime(60 * 60 * 1000);
+    expect(settled).toBe(false);
+    expect(service.pendingRequests.size).toBe(1);
+  });
+
+  test('createPromptRequest with timeout:0/undefined falls back to the default', () => {
+    const { requestInfo } = service.createPromptRequest('agent-1', { questions: [{ message: 'Q?' }] }, { timeout: 0 });
+    expect(requestInfo.timeoutMs).toBe(5 * 60 * 1000);
+    expect(requestInfo.timeoutAt).not.toBeNull();
+  });
+
   test('createPromptRequest normalizes questions with defaults', () => {
     const { requestInfo } = service.createPromptRequest('agent-1', {
       questions: [{ question: 'What color?', options: ['red', 'blue'] }]

package/src/services/__tests__/scheduleService.flow.test.js

@@ -208,6 +208,57 @@ describe('_executeAgentSchedule', () => {
       .rejects.toThrow(/Target agent not found/);
   });
 
+  test('load-on-fire: restores an on-disk target then dispatches', async () => {
+    const svc = newSvc();
+    const updateAgent = jest.fn().mockResolvedValue(undefined);
+    const addUserMessage = jest.fn().mockResolvedValue(undefined);
+    const importArchivedAgent = jest.fn().mockResolvedValue({ id: 'a1', name: 'Restored' });
+    svc.setAgentPool({ getAgent: jest.fn().mockResolvedValue(null), updateAgent, addUserMessage });
+    svc.setOrchestrator({ stateManager: { importArchivedAgent }, config: { project: { directory: '/proj' } } });
+
+    await svc._executeAgentSchedule({ id: 's', name: 'Nightly', targetId: 'a1', prompt: 'go' });
+
+    expect(importArchivedAgent).toHaveBeenCalledWith('a1', '/proj', expect.anything());
+    expect(addUserMessage).toHaveBeenCalledWith('a1', expect.objectContaining({ source: 'schedule' }));
+  });
+
+  test('load-on-fire: falls back to getAgent when import returns nothing but the agent is now resident', async () => {
+    const svc = newSvc();
+    const getAgent = jest.fn()
+      .mockResolvedValueOnce(null)              // first check: not resident
+      .mockResolvedValueOnce({ id: 'a1', name: 'NowHere' }); // after import: resident
+    const importArchivedAgent = jest.fn().mockResolvedValue(null);
+    svc.setAgentPool({ getAgent, updateAgent: jest.fn(), addUserMessage: jest.fn() });
+    svc.setOrchestrator({ stateManager: { importArchivedAgent }, config: {} });
+
+    await svc._executeAgentSchedule({ id: 's', name: 'N', targetId: 'a1', prompt: 'go' });
+    expect(importArchivedAgent).toHaveBeenCalled();
+  });
+
+  test('load-on-fire: still throws when the agent cannot be restored', async () => {
+    const svc = newSvc();
+    svc.setAgentPool({ getAgent: jest.fn().mockResolvedValue(null) });
+    svc.setOrchestrator({ stateManager: { importArchivedAgent: jest.fn().mockResolvedValue(null) }, config: {} });
+    await expect(svc._executeAgentSchedule({ id: 'x', targetId: 'gone' }))
+      .rejects.toThrow(/Target agent not found/);
+  });
+
+  test('load-on-fire: a restore error is swallowed (falls through to not-found)', async () => {
+    const svc = newSvc();
+    svc.setAgentPool({ getAgent: jest.fn().mockResolvedValue(null) });
+    svc.setOrchestrator({ stateManager: { importArchivedAgent: jest.fn().mockRejectedValue(new Error('disk')) }, config: {} });
+    await expect(svc._executeAgentSchedule({ id: 'x', targetId: 'gone' }))
+      .rejects.toThrow(/Target agent not found/);
+  });
+
+  test('load-on-fire: no-op when no orchestrator/stateManager is wired', async () => {
+    const svc = newSvc();
+    svc.setAgentPool({ getAgent: jest.fn().mockResolvedValue(null) });
+    // no setOrchestrator → _loadAgentFromDisk returns null immediately
+    await expect(svc._executeAgentSchedule({ id: 'x', targetId: 'gone' }))
+      .rejects.toThrow(/Target agent not found/);
+  });
+
   test('switches to agent mode and pushes the prompt, reusing a live session id', async () => {
     const svc = newSvc();
     const updateAgent = jest.fn().mockResolvedValue(undefined);

package/src/services/agentActivityService.js

@@ -250,8 +250,21 @@ export function shouldAgentBeActive(agent) {
   }
 
   if (agent.mode === AGENT_MODES.CHAT) {
-    // CHAT mode: active ONLY if has user messages or inter-agent messages
-    // Tool results alone should NOT keep CHAT agents active
+    // CHAT mode: active if it has user messages, inter-agent messages, OR
+    // queued tool results.
+    //
+    // Activating on tool results is what makes guided chat "agentic": after a
+    // chat agent fires a tool, the result wakes it so it can read the output
+    // and produce its follow-up answer (tool -> observe -> answer within one
+    // user turn). Keying off QUEUE STATE — rather than granting a TTL at each
+    // place a result is enqueued — covers every delivery path by construction:
+    //   - sync tools push directly in agentScheduler._executeToolsAsync,
+    //   - async tools (image/video/async ops) land later via addToolResult,
+    //   - system-error injections and reminders,
+    //   - any future enqueue path,
+    // all become visible here the same way. It self-terminates: once
+    // processAgentQueues drains the results into the conversation, the queue is
+    // empty and the agent goes idle unless it issued another tool call.
     const queueStatus = getMessageQueueStatus(agent);
 
     if (queueStatus.hasUserMessages) {
@@ -270,13 +283,19 @@ export function shouldAgentBeActive(agent) {
       };
     }
 
-    // CHAT mode with no user/inter-agent messages
+    if (queueStatus.hasToolResults) {
+      return {
+        active: true,
+        reason: AGENT_ACTIVITY_STATUS.HAS_TOOL_RESULTS,
+        details: `Agent has ${queueStatus.counts.toolResults} tool result(s) to react to`
+      };
+    }
+
+    // CHAT mode with nothing queued
     return {
       active: false,
       reason: AGENT_ACTIVITY_STATUS.CHAT_MODE_NO_MESSAGES,
-      details: queueStatus.hasToolResults
-        ? `CHAT mode - has ${queueStatus.counts.toolResults} tool results but no new messages`
-        : 'CHAT mode - no messages to process'
+      details: 'CHAT mode - no messages to process'
     };
   }
 

package/src/services/promptService.js

@@ -43,8 +43,12 @@ class PromptService {
    */
   createPromptRequest(agentId, promptData, options = {}) {
     const requestId = this._generateRequestId();
-    const timeoutMs = options.timeout || DEFAULT_TIMEOUT_MS;
-    const timeoutAt = new Date(Date.now() + timeoutMs);
+    // `options.timeout === null` means "no auto-timeout" (the 'none' strategy):
+    // the request waits until answered or cancelled. `0`/undefined fall back to
+    // the default so a missing value never means "wait forever" accidentally.
+    const noTimeout = options.timeout === null;
+    const timeoutMs = noTimeout ? null : (options.timeout || DEFAULT_TIMEOUT_MS);
+    const timeoutAt = noTimeout ? null : new Date(Date.now() + timeoutMs);
 
     // Validate and normalize questions
     const questions = this._normalizeQuestions(promptData.questions || [promptData]);
@@ -56,7 +60,7 @@ class PromptService {
       questions,
       message: promptData.message || null,
       createdAt: new Date().toISOString(),
-      timeoutAt: timeoutAt.toISOString(),
+      timeoutAt: timeoutAt ? timeoutAt.toISOString() : null,
       timeoutMs
     };
 
@@ -67,10 +71,12 @@ class PromptService {
       reject = rej;
     });
 
-    // Set timeout
-    const timeoutHandle = setTimeout(() => {
-      this._handleTimeout(requestId);
-    }, timeoutMs);
+    // Set timeout (skipped entirely when noTimeout).
+    const timeoutHandle = noTimeout
+      ? null
+      : setTimeout(() => {
+          this._handleTimeout(requestId);
+        }, timeoutMs);
 
     // Store pending request
     this.pendingRequests.set(requestId, {

package/src/services/scheduleService.js

@@ -551,10 +551,36 @@ class ScheduleService {
     }
   }
 
+  /**
+   * Load the target agent from disk into the pool if it isn't resident.
+   * Mirrors the UI's "import agent" path (stateManager.importArchivedAgent) so
+   * a schedule can target an on-disk agent that was never loaded — or one that
+   * was unloaded/archived after the schedule was created. Returns the agent, or
+   * null if it can't be restored.
+   * @private
+   */
+  async _loadAgentFromDisk(agentId) {
+    const stateManager = this.orchestrator?.stateManager;
+    if (!stateManager || typeof stateManager.importArchivedAgent !== 'function') return null;
+    const projectDir = this.orchestrator?.config?.project?.directory || process.cwd();
+    try {
+      const agent = await stateManager.importArchivedAgent(agentId, projectDir, this.agentPool);
+      if (agent) this.logger.info('Schedule restored target agent from disk on fire', { agentId });
+      return agent || (await this.agentPool.getAgent(agentId));
+    } catch (err) {
+      this.logger.warn('Schedule could not restore target agent from disk', { agentId, error: err.message });
+      return null;
+    }
+  }
+
   async _executeAgentSchedule(schedule) {
     if (!this.agentPool) throw new Error('AgentPool not available');
 
-    const agent = await this.agentPool.getAgent(schedule.targetId);
+    // Load-on-fire: the target may live on disk (never loaded, or unloaded
+    // after the schedule was created). Try to restore it before giving up, so
+    // schedules don't silently break just because the agent isn't resident.
+    let agent = await this.agentPool.getAgent(schedule.targetId);
+    if (!agent) agent = await this._loadAgentFromDisk(schedule.targetId);
     if (!agent) throw new Error(`Target agent not found: ${schedule.targetId}`);
 
     // Switch agent to agent mode (autonomous)

package/src/tools/__tests__/baseTool.mustHave.test.js

@@ -0,0 +1,72 @@
+/**
+ * ToolsRegistry — must-have tool advertisement (taskmanager always; jobdone in
+ * AGENT mode) and their removal from the UI capability selector.
+ */
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+
+jest.unstable_mockModule('../../utilities/constants.js', () => ({
+  TOOL_STATUS: { PENDING: 'pending', EXECUTING: 'executing', COMPLETED: 'completed', FAILED: 'failed' },
+  OPERATION_STATUS: { EXECUTING: 'executing', COMPLETED: 'completed', FAILED: 'failed', NOT_FOUND: 'not_found' },
+  ERROR_TYPES: {},
+  SYSTEM_DEFAULTS: { MAX_TOOL_EXECUTION_TIME: 300000 },
+}));
+
+const { BaseTool, ToolsRegistry } = await import('../baseTool.js');
+
+function makeTool(id, name) {
+  return class extends BaseTool {
+    constructor() {
+      super();
+      this.id = id;
+      this.name = name;
+    }
+    getDescription() { return `${name} tool\n${name} does things`; }
+    getSummary() { return `${name} summary`; }
+    parseParameters(content) { return typeof content === 'string' ? { raw: content } : {}; }
+    async execute() { return { success: true }; }
+  };
+}
+
+describe('ToolsRegistry must-have advertisement', () => {
+  let registry;
+
+  beforeEach(async () => {
+    registry = new ToolsRegistry(createMockLogger());
+    await registry.registerTool(makeTool('taskmanager', 'TaskManager'));
+    await registry.registerTool(makeTool('jobdone', 'JobDone'));
+    await registry.registerTool(makeTool('web', 'Web'));
+  });
+
+  test('AGENT mode injects taskmanager AND jobdone into an explicit list', () => {
+    const desc = registry.generateToolDescriptionsForPrompt(['web'], { layered: true, mode: 'agent' });
+    expect(desc).toContain('**web**');
+    expect(desc).toContain('**taskmanager**');
+    expect(desc).toContain('**jobdone**');
+  });
+
+  test('CHAT mode injects taskmanager but NOT jobdone', () => {
+    const desc = registry.generateToolDescriptionsForPrompt(['web'], { layered: true, mode: 'chat' });
+    expect(desc).toContain('**taskmanager**');
+    expect(desc).not.toContain('**jobdone**');
+  });
+
+  test('!taskmanager opt-out removes the forced description', () => {
+    const desc = registry.generateToolDescriptionsForPrompt(['web', '!taskmanager'], { layered: true, mode: 'agent' });
+    expect(desc).not.toContain('**taskmanager**');
+    expect(desc).toContain('**jobdone**');
+  });
+
+  test('empty capability list still means "all tools" (must-haves included)', () => {
+    const desc = registry.generateToolDescriptionsForPrompt([], { layered: true, mode: 'chat' });
+    expect(desc).toContain('**taskmanager**');
+    expect(desc).toContain('**web**');
+  });
+
+  test('getAvailableToolsForUI omits the must-have tools', () => {
+    const ids = registry.getAvailableToolsForUI().map((t) => t.id);
+    expect(ids).toContain('web');
+    expect(ids).not.toContain('taskmanager');
+    expect(ids).not.toContain('jobdone');
+  });
+});

package/src/tools/__tests__/openaiFunctionSchemas.mustHave.test.js

@@ -0,0 +1,37 @@
+import { describe, test, expect } from '@jest/globals';
+import { getToolSchemasForAgent, OPENAI_FUNCTION_SCHEMAS } from '../openaiFunctionSchemas.js';
+
+const names = (schemas) => schemas.map((s) => s.name);
+
+describe('getToolSchemasForAgent — must-have injection', () => {
+  test('empty / non-array capabilities → full catalog unchanged', () => {
+    expect(getToolSchemasForAgent([])).toBe(OPENAI_FUNCTION_SCHEMAS);
+    expect(getToolSchemasForAgent(undefined)).toBe(OPENAI_FUNCTION_SCHEMAS);
+  });
+
+  test('explicit list in AGENT mode gains taskmanager AND jobdone', () => {
+    const out = names(getToolSchemasForAgent(['web'], 'agent'));
+    expect(out).toContain('web');
+    expect(out).toContain('taskmanager');
+    expect(out).toContain('jobdone');
+  });
+
+  test('explicit list in CHAT mode gains taskmanager but NOT jobdone', () => {
+    const out = names(getToolSchemasForAgent(['web'], 'chat'));
+    expect(out).toContain('web');
+    expect(out).toContain('taskmanager');
+    expect(out).not.toContain('jobdone');
+  });
+
+  test('!taskmanager opt-out removes the forced schema', () => {
+    const out = names(getToolSchemasForAgent(['web', '!taskmanager'], 'agent'));
+    expect(out).not.toContain('taskmanager');
+    expect(out).toContain('jobdone');
+  });
+
+  test('does not invent schemas for capabilities that have none', () => {
+    const out = names(getToolSchemasForAgent(['definitely-not-a-tool'], 'chat'));
+    // only the real must-have (taskmanager) survives the schema filter
+    expect(out).toEqual(['taskmanager']);
+  });
+});