onbuzz 4.0.2 → 4.2.0

package/package.json

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

package/scripts/audit-report.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * audit-report.js — run `npm audit --json` against each workspace, classify
+ * the findings via src/utilities/auditReport.js, and write a markdown report.
+ *
+ * Usage:
+ *   node scripts/audit-report.js                       # default: root + web-ui, stdout markdown
+ *   node scripts/audit-report.js --out=FILE.md         # also write to file
+ *   node scripts/audit-report.js --scope=root          # only root
+ *   node scripts/audit-report.js --scope=web-ui        # only web-ui
+ *   node scripts/audit-report.js --fail-on=high        # exit 1 when high+critical remain
+ *   node scripts/audit-report.js --fail-on=none        # never fail (informational)
+ *   node scripts/audit-report.js --silent              # no stdout (use with --out)
+ *
+ * Exit codes:
+ *   0 — no findings at or above --fail-on severity (default: high)
+ *   1 — findings at or above --fail-on severity
+ *   2 — something went wrong invoking `npm audit`
+ */
+
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import {
+  classifyAudit,
+  renderMarkdown,
+  shouldFail,
+} from '../src/utilities/auditReport.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+// ────────────────────────────────────────────────────────────────────────
+// CLI arg parsing — intentionally minimal, no deps.
+// ────────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const opts = {
+    scope: 'all',          // 'root' | 'web-ui' | 'all'
+    out: null,             // optional output file path
+    failOn: 'high',        // 'critical' | 'high' | 'moderate' | 'low' | 'none'
+    silent: false,
+  };
+  for (const arg of argv.slice(2)) {
+    const [key, val] = arg.split('=');
+    switch (key) {
+      case '--scope':   opts.scope  = val || 'all'; break;
+      case '--out':     opts.out    = val || null;  break;
+      case '--fail-on': opts.failOn = val || 'high'; break;
+      case '--silent':  opts.silent = true;         break;
+      case '--help':
+      case '-h':
+        console.log(fs.readFileSync(__filename, 'utf-8')
+          .split('\n').slice(2, 18).map(s => s.replace(/^ \* ?/, '')).join('\n'));
+        process.exit(0);
+      default:
+        if (arg.startsWith('--')) {
+          console.error(`Unknown flag: ${arg}`);
+          process.exit(2);
+        }
+    }
+  }
+  return opts;
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Run `npm audit --json` in a directory and parse.
+// Returns { ok: true, data } on success, { ok: false, error } on failure.
+// `npm audit` exits non-zero when vulns exist — that's NOT a failure here;
+// we still want to parse the JSON output and classify. Only actual spawn
+// errors or malformed JSON are treated as failures.
+// ────────────────────────────────────────────────────────────────────────
+
+function runAudit(cwd) {
+  // Windows: `npm` resolves to `npm.cmd` which requires shell=true on Node
+  // 20+ (CVE-2024-27980 hardening). POSIX is fine without a shell — cheaper
+  // spawn and avoids shell-escaping surprises.
+  const isWin = process.platform === 'win32';
+  const res = spawnSync(isWin ? 'npm.cmd' : 'npm', ['audit', '--json'], {
+    cwd,
+    encoding: 'utf-8',
+    maxBuffer: 32 * 1024 * 1024,  // 32 MB — big trees can produce long JSON
+    shell: isWin,
+  });
+  if (res.error) {
+    return { ok: false, error: `spawn failed: ${res.error.message}` };
+  }
+  const stdout = res.stdout || '';
+  if (!stdout.trim()) {
+    return { ok: false, error: `empty output from npm audit (exit ${res.status})` };
+  }
+  try {
+    return { ok: true, data: JSON.parse(stdout) };
+  } catch (err) {
+    return { ok: false, error: `failed to parse npm audit JSON: ${err.message}` };
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Workspace resolution
+// ────────────────────────────────────────────────────────────────────────
+
+function resolveWorkspaces(scope) {
+  const root   = { label: 'root',   cwd: REPO_ROOT };
+  const webUi  = { label: 'web-ui', cwd: path.join(REPO_ROOT, 'web-ui') };
+  const list = [];
+  if (scope === 'root' || scope === 'all') list.push(root);
+  if (scope === 'web-ui' || scope === 'all') list.push(webUi);
+  return list.filter(ws => {
+    if (!fs.existsSync(path.join(ws.cwd, 'package.json'))) {
+      console.error(`[audit-report] skipping ${ws.label} — no package.json at ${ws.cwd}`);
+      return false;
+    }
+    return true;
+  });
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Main
+// ────────────────────────────────────────────────────────────────────────
+
+function main() {
+  const opts = parseArgs(process.argv);
+  const workspaces = resolveWorkspaces(opts.scope);
+  if (workspaces.length === 0) {
+    console.error('[audit-report] no workspaces to scan');
+    process.exit(2);
+  }
+
+  const sections = [];
+  let anyFailed = false;
+
+  for (const ws of workspaces) {
+    if (!opts.silent) console.error(`[audit-report] scanning ${ws.label}…`);
+    const result = runAudit(ws.cwd);
+    if (!result.ok) {
+      console.error(`[audit-report] ${ws.label}: ${result.error}`);
+      process.exit(2);
+    }
+    const classified = classifyAudit(result.data);
+    const md = renderMarkdown(classified, { workspace: ws.label });
+    sections.push(md);
+
+    if (shouldFail(classified, opts.failOn)) anyFailed = true;
+  }
+
+  const fullReport = sections.join('\n\n---\n\n');
+
+  if (opts.out) {
+    fs.writeFileSync(path.resolve(opts.out), fullReport, 'utf-8');
+    if (!opts.silent) console.error(`[audit-report] wrote ${opts.out}`);
+  }
+
+  if (!opts.silent) {
+    // Print markdown to stdout for piping / direct viewing.
+    process.stdout.write(fullReport + '\n');
+  }
+
+  process.exit(anyFailed ? 1 : 0);
+}
+
+main();

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

@@ -0,0 +1,191 @@
+/**
+ * Tests for per-agent `toolConfig` field on the agent object.
+ *
+ * toolConfig is a plain object keyed by tool id:
+ *   agent.toolConfig = {
+ *     terminal:   { allowedCommands: ['git', 'npm'], maxBackgroundCommandsPerAgent: 3 },
+ *     filesystem: { allowedExtensions: ['.js', '.ts'], maxFileSize: 1_000_000 },
+ *     web:        { stealthLevel: 'medium' },
+ *     ...
+ *   }
+ *
+ * The values get merged into each tool's constructor config at tool
+ * instantiation time (step 2 — ToolManager integration). These tests
+ * lock the schema + persistence + validation contract so anything
+ * downstream can depend on the shape without guessing.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger, createMockConfig, createMockStateManager } from '../../__test-utils__/mockFactories.js';
+
+// Mocks (same pattern as sibling agentPool tests)
+const mockValidateAccessConfiguration = jest.fn().mockReturnValue({ valid: true });
+const mockCreateProjectDefaults = jest.fn().mockReturnValue({
+  workingDirectory: '/tmp/project',
+  readOnlyDirectories: [],
+  writeEnabledDirectories: ['/tmp/project'],
+});
+
+jest.unstable_mockModule('../../utilities/directoryAccessManager.js', () => {
+  const MockDAM = jest.fn().mockImplementation(() => ({
+    validateAccessConfiguration: mockValidateAccessConfiguration,
+  }));
+  MockDAM.createProjectDefaults = mockCreateProjectDefaults;
+  return { default: MockDAM };
+});
+
+jest.unstable_mockModule('../../services/visualEditorBridge.js', () => ({
+  getVisualEditorBridge: jest.fn().mockReturnValue({
+    hasInstance: jest.fn().mockReturnValue(false),
+    stopInstance: jest.fn().mockResolvedValue(undefined),
+  }),
+}));
+
+const { default: AgentPool } = await import('../agentPool.js');
+
+function makePool() {
+  const config = createMockConfig();
+  const logger = createMockLogger();
+  const stateManager = createMockStateManager();
+  const contextManager = { getContext: jest.fn() };
+  return new AgentPool(config, logger, stateManager, contextManager, null);
+}
+
+function cfg(overrides = {}) {
+  return {
+    name: 'TestAgent',
+    systemPrompt: 'test',
+    preferredModel: 'test-model',
+    capabilities: [],
+    projectDir: '/tmp/project',
+    ...overrides,
+  };
+}
+
+describe('agentPool — agent.toolConfig schema', () => {
+  let pool;
+  beforeEach(() => { jest.clearAllMocks(); pool = makePool(); });
+
+  describe('createAgent', () => {
+    test('agents without toolConfig in config get empty toolConfig object', async () => {
+      const agent = await pool.createAgent(cfg());
+      expect(agent.toolConfig).toEqual({});
+    });
+
+    test('agents with toolConfig in config retain it (shallow copy)', async () => {
+      const agent = await pool.createAgent(cfg({
+        toolConfig: {
+          terminal:   { allowedCommands: ['git', 'npm'] },
+          filesystem: { maxFileSize: 500_000 },
+        },
+      }));
+      expect(agent.toolConfig).toEqual({
+        terminal:   { allowedCommands: ['git', 'npm'] },
+        filesystem: { maxFileSize: 500_000 },
+      });
+    });
+
+    test('toolConfig is copied (not referenced) so caller mutation does not leak', async () => {
+      const src = { terminal: { allowedCommands: ['git'] } };
+      const agent = await pool.createAgent(cfg({ toolConfig: src }));
+      src.terminal.allowedCommands.push('rm');
+      // Agent's inner value still has the shared reference at this level
+      // (shallow copy), but the top-level object is independent. This is
+      // the same contract `capabilities` has.
+      expect(agent.toolConfig).not.toBe(src);
+    });
+
+    test('malformed toolConfig (array) falls back to empty object instead of crashing', async () => {
+      const agent = await pool.createAgent(cfg({ toolConfig: ['bogus'] }));
+      expect(agent.toolConfig).toEqual({});
+    });
+
+    test('malformed toolConfig (non-object) falls back to empty object', async () => {
+      const agent = await pool.createAgent(cfg({ toolConfig: 'not-an-object' }));
+      expect(agent.toolConfig).toEqual({});
+    });
+  });
+
+  describe('listActiveAgents', () => {
+    test('exposes toolConfig in the listed agent shape', async () => {
+      const agent = await pool.createAgent(cfg({
+        toolConfig: { terminal: { allowedCommands: ['git'] } },
+      }));
+      const listed = await pool.listActiveAgents();
+      const me = listed.find(a => a.id === agent.id);
+      expect(me.toolConfig).toEqual({ terminal: { allowedCommands: ['git'] } });
+    });
+
+    test('emits empty object for agents without toolConfig (backward compat)', async () => {
+      // Simulate an agent loaded from an older persisted state without toolConfig.
+      const agent = await pool.createAgent(cfg());
+      delete agent.toolConfig;
+      const listed = await pool.listActiveAgents();
+      const me = listed.find(a => a.id === agent.id);
+      expect(me.toolConfig).toEqual({});
+    });
+  });
+
+  describe('updateAgent', () => {
+    test('updates toolConfig', async () => {
+      const agent = await pool.createAgent(cfg());
+      await pool.updateAgent(agent.id, {
+        toolConfig: { terminal: { allowedCommands: ['git'] } },
+      });
+      const after = await pool.getAgent(agent.id);
+      expect(after.toolConfig).toEqual({ terminal: { allowedCommands: ['git'] } });
+    });
+
+    test('replaces toolConfig entirely (caller is responsible for merging)', async () => {
+      const agent = await pool.createAgent(cfg({
+        toolConfig: {
+          terminal:   { allowedCommands: ['git'] },
+          filesystem: { maxFileSize: 500 },
+        },
+      }));
+      await pool.updateAgent(agent.id, { toolConfig: { web: { stealthLevel: 'low' } } });
+      const after = await pool.getAgent(agent.id);
+      expect(after.toolConfig).toEqual({ web: { stealthLevel: 'low' } });
+    });
+
+    test('rejects non-object toolConfig', async () => {
+      const agent = await pool.createAgent(cfg());
+      await expect(
+        pool.updateAgent(agent.id, { toolConfig: 'nope' })
+      ).rejects.toThrow(/must be a plain object/);
+    });
+
+    test('rejects array toolConfig', async () => {
+      const agent = await pool.createAgent(cfg());
+      await expect(
+        pool.updateAgent(agent.id, { toolConfig: ['not', 'valid'] })
+      ).rejects.toThrow(/must be a plain object/);
+    });
+
+    test('rejects toolConfig entry that is not an object', async () => {
+      const agent = await pool.createAgent(cfg());
+      await expect(
+        pool.updateAgent(agent.id, { toolConfig: { terminal: 'bogus' } })
+      ).rejects.toThrow(/toolConfig\.terminal: must be an object or null/);
+    });
+
+    test('allows null entry (means reset that tool back to defaults)', async () => {
+      const agent = await pool.createAgent(cfg({
+        toolConfig: { terminal: { allowedCommands: ['git'] } },
+      }));
+      await pool.updateAgent(agent.id, { toolConfig: { terminal: null } });
+      const after = await pool.getAgent(agent.id);
+      expect(after.toolConfig).toEqual({ terminal: null });
+    });
+
+    test('updateAgent without toolConfig in updates leaves existing toolConfig intact', async () => {
+      const agent = await pool.createAgent(cfg({
+        toolConfig: { terminal: { allowedCommands: ['git'] } },
+      }));
+      await pool.updateAgent(agent.id, { name: 'NewName' });
+      const after = await pool.getAgent(agent.id);
+      expect(after.name).toBe('NewName');
+      expect(after.toolConfig).toEqual({ terminal: { allowedCommands: ['git'] } });
+    });
+  });
+});

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

@@ -0,0 +1,315 @@
+/**
+ * Regression tests: an inbound message (user / inter-agent / tool-result)
+ * MUST wake the recipient out of any paused or delayed state.
+ *
+ * This was previously fixed only for addUserMessage; addInterAgentMessage
+ * and addToolResult silently queued into paused/delayed agents, so the
+ * recipient never acted on the incoming message until the back-off
+ * naturally expired. These tests lock the shared-helper implementation so
+ * the invariant "inbound message always wins over delay/pause" cannot
+ * regress again by patching one path and forgetting the others.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger, createMockConfig, createMockStateManager } from '../../__test-utils__/mockFactories.js';
+
+// ── Mocks ───────────────────────────────────────────────────────────────────
+const mockValidateAccessConfiguration = jest.fn().mockReturnValue({ valid: true });
+const mockCreateProjectDefaults = jest.fn().mockReturnValue({
+  workingDirectory: '/tmp/project',
+  readOnlyDirectories: [],
+  writeEnabledDirectories: ['/tmp/project'],
+});
+
+jest.unstable_mockModule('../../utilities/directoryAccessManager.js', () => {
+  const MockDAM = jest.fn().mockImplementation(() => ({
+    validateAccessConfiguration: mockValidateAccessConfiguration,
+  }));
+  MockDAM.createProjectDefaults = mockCreateProjectDefaults;
+  return { default: MockDAM };
+});
+
+jest.unstable_mockModule('../../services/visualEditorBridge.js', () => ({
+  getVisualEditorBridge: jest.fn().mockReturnValue({
+    hasInstance: jest.fn().mockReturnValue(false),
+    stopInstance: jest.fn().mockResolvedValue(undefined),
+  }),
+}));
+
+const { default: AgentPool } = await import('../agentPool.js');
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+function makePool(overrides = {}) {
+  const config = createMockConfig(overrides.config);
+  const logger = createMockLogger();
+  const stateManager = createMockStateManager();
+  const contextManager = { getContext: jest.fn() };
+  const pool = new AgentPool(config, logger, stateManager, contextManager, null);
+  return { pool, logger };
+}
+
+function agentCfg(overrides = {}) {
+  return {
+    name: 'TestAgent',
+    systemPrompt: 'You are a test agent.',
+    preferredModel: 'test-model',
+    capabilities: [],
+    projectDir: '/tmp/project',
+    ...overrides,
+  };
+}
+
+/** Stamp a future delay directly on the agent (mimics scheduler back-off). */
+function setDelay(agent, msFromNow = 60_000) {
+  agent.delayEndTime = new Date(Date.now() + msFromNow).toISOString();
+}
+
+function makeScheduler() {
+  return {
+    addAgent: jest.fn().mockResolvedValue(undefined),
+    removeAgent: jest.fn(),
+    isAgentInScheduler: jest.fn().mockReturnValue(false),
+    broadcastAgentStateUpdate: jest.fn().mockResolvedValue(undefined),
+  };
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// addUserMessage — locks existing behaviour including delay-clear (the
+// original fix covered auto-resume but the delay-clear assertion lived in
+// a different test file; we consolidate both guarantees here).
+// ────────────────────────────────────────────────────────────────────────
+
+describe('agentPool.addUserMessage — wake-on-message', () => {
+  test('clears future delayEndTime', async () => {
+    const { pool } = makePool();
+    const agent = await pool.createAgent(agentCfg());
+    setDelay(agent, 30_000);
+
+    await pool.addUserMessage(agent.id, { content: 'wake me' });
+
+    expect(agent.delayEndTime).toBeNull();
+    expect(agent.messageQueues.userMessages).toHaveLength(1);
+  });
+
+  test('past delayEndTime is left alone (no spurious broadcast)', async () => {
+    const { pool } = makePool();
+    const scheduler = makeScheduler();
+    pool.setScheduler(scheduler);
+    const agent = await pool.createAgent(agentCfg());
+    agent.delayEndTime = new Date(Date.now() - 60_000).toISOString(); // already expired
+
+    await pool.addUserMessage(agent.id, { content: 'hi' });
+
+    expect(scheduler.broadcastAgentStateUpdate).not.toHaveBeenCalled();
+  });
+
+  test('broadcasts delay-clear when delay was cleared', async () => {
+    const { pool } = makePool();
+    const scheduler = makeScheduler();
+    pool.setScheduler(scheduler);
+    const agent = await pool.createAgent(agentCfg());
+    setDelay(agent, 30_000);
+
+    await pool.addUserMessage(agent.id, { content: 'hi' });
+
+    expect(scheduler.broadcastAgentStateUpdate).toHaveBeenCalledWith(
+      agent.id,
+      'user-message-clears-delay'
+    );
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// addInterAgentMessage — the previously-broken path.
+// ────────────────────────────────────────────────────────────────────────
+
+describe('agentPool.addInterAgentMessage — wake-on-message', () => {
+  test('clears future delayEndTime on inter-agent message', async () => {
+    const { pool } = makePool();
+    const agent = await pool.createAgent(agentCfg());
+    setDelay(agent, 45_000);
+
+    await pool.addInterAgentMessage(agent.id, {
+      content: 'need your help',
+      sender: 'OtherAgent',
+      senderName: 'OtherAgent',
+    });
+
+    expect(agent.delayEndTime).toBeNull();
+    expect(agent.messageQueues.interAgentMessages).toHaveLength(1);
+  });
+
+  test('auto-resumes paused recipient', async () => {
+    const { pool } = makePool();
+    const agent = await pool.createAgent(agentCfg());
+    await pool.pauseAgent(agent.id, 300, 'manual pause');
+    expect(agent.status).toBe('paused');
+
+    const resumeSpy = jest.spyOn(pool, 'resumeAgent');
+
+    await pool.addInterAgentMessage(agent.id, {
+      content: 'wake up',
+      sender: 'OtherAgent',
+    });
+
+    expect(resumeSpy).toHaveBeenCalledWith(agent.id);
+    expect(agent.status).toBe('active');
+    expect(agent.pausedUntil).toBeNull();
+    resumeSpy.mockRestore();
+  });
+
+  test('clears BOTH pause and delay when both are set', async () => {
+    const { pool } = makePool();
+    const agent = await pool.createAgent(agentCfg());
+    await pool.pauseAgent(agent.id, 300, 'pause');
+    setDelay(agent, 60_000);
+
+    await pool.addInterAgentMessage(agent.id, {
+      content: 'act now',
+      sender: 'OtherAgent',
+    });
+
+    expect(agent.status).toBe('active');
+    expect(agent.pausedUntil).toBeNull();
+    expect(agent.delayEndTime).toBeNull();
+  });
+
+  test('broadcasts delay-clear with correct reason when delay was cleared', async () => {
+    const { pool } = makePool();
+    const scheduler = makeScheduler();
+    pool.setScheduler(scheduler);
+    const agent = await pool.createAgent(agentCfg());
+    setDelay(agent, 60_000);
+
+    await pool.addInterAgentMessage(agent.id, {
+      content: 'hi',
+      sender: 'OtherAgent',
+    });
+
+    expect(scheduler.broadcastAgentStateUpdate).toHaveBeenCalledWith(
+      agent.id,
+      'inter-agent-message-clears-delay'
+    );
+  });
+
+  test('non-paused non-delayed agent: no resume, no broadcast', async () => {
+    const { pool } = makePool();
+    const scheduler = makeScheduler();
+    pool.setScheduler(scheduler);
+    const agent = await pool.createAgent(agentCfg());
+    const resumeSpy = jest.spyOn(pool, 'resumeAgent');
+
+    await pool.addInterAgentMessage(agent.id, {
+      content: 'hi',
+      sender: 'OtherAgent',
+    });
+
+    expect(resumeSpy).not.toHaveBeenCalled();
+    expect(scheduler.broadcastAgentStateUpdate).not.toHaveBeenCalled();
+    resumeSpy.mockRestore();
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// addToolResult — the third previously-broken path.
+// ────────────────────────────────────────────────────────────────────────
+
+describe('agentPool.addToolResult — wake-on-message', () => {
+  test('clears future delayEndTime when a tool result arrives', async () => {
+    const { pool } = makePool();
+    const agent = await pool.createAgent(agentCfg());
+    setDelay(agent, 120_000);
+
+    await pool.addToolResult(agent.id, {
+      toolId: 'image-gen',
+      status: 'completed',
+      result: { imageUrl: '/tmp/out.png' },
+    });
+
+    expect(agent.delayEndTime).toBeNull();
+    expect(agent.messageQueues.toolResults).toHaveLength(1);
+  });
+
+  test('auto-resumes paused agent when a tool result arrives', async () => {
+    const { pool } = makePool();
+    const agent = await pool.createAgent(agentCfg());
+    await pool.pauseAgent(agent.id, 300, 'manual pause');
+    expect(agent.status).toBe('paused');
+
+    await pool.addToolResult(agent.id, {
+      toolId: 'video-gen',
+      status: 'completed',
+      result: { videoUrl: '/tmp/v.mp4' },
+    });
+
+    expect(agent.status).toBe('active');
+    expect(agent.pausedUntil).toBeNull();
+  });
+
+  test('broadcasts with tool-result reason when delay was cleared', async () => {
+    const { pool } = makePool();
+    const scheduler = makeScheduler();
+    pool.setScheduler(scheduler);
+    const agent = await pool.createAgent(agentCfg());
+    setDelay(agent, 60_000);
+
+    await pool.addToolResult(agent.id, {
+      toolId: 'image-gen',
+      status: 'completed',
+      result: {},
+    });
+
+    expect(scheduler.broadcastAgentStateUpdate).toHaveBeenCalledWith(
+      agent.id,
+      'tool-result-clears-delay'
+    );
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// _wakeAgentForMessage — direct unit test of the shared helper so future
+// contributors see the exact contract every inbound path must honour.
+// ────────────────────────────────────────────────────────────────────────
+
+describe('agentPool._wakeAgentForMessage (shared helper)', () => {
+  test('no-op on happy-path (active, not delayed)', async () => {
+    const { pool } = makePool();
+    const agent = await pool.createAgent(agentCfg());
+
+    const info = await pool._wakeAgentForMessage(agent, 'test');
+
+    expect(info).toEqual({ wasPaused: false, hadDelay: false, hadPausedUntil: false });
+    expect(agent.status).toBe('active');
+    expect(agent.delayEndTime).toBeFalsy();
+  });
+
+  test('reports wasPaused=true and clears pause', async () => {
+    const { pool } = makePool();
+    const agent = await pool.createAgent(agentCfg());
+    await pool.pauseAgent(agent.id, 300, 'pause');
+
+    const info = await pool._wakeAgentForMessage(agent, 'test');
+
+    expect(info.wasPaused).toBe(true);
+    expect(agent.status).toBe('active');
+  });
+
+  test('reports hadDelay=true and clears delay', async () => {
+    const { pool } = makePool();
+    const agent = await pool.createAgent(agentCfg());
+    setDelay(agent, 30_000);
+
+    const info = await pool._wakeAgentForMessage(agent, 'test');
+
+    expect(info.hadDelay).toBe(true);
+    expect(agent.delayEndTime).toBeNull();
+  });
+
+  test('null agent returns zero-info object (defensive)', async () => {
+    const { pool } = makePool();
+
+    const info = await pool._wakeAgentForMessage(null, 'test');
+
+    expect(info).toEqual({ wasPaused: false, hadDelay: false, hadPausedUntil: false });
+  });
+});