onbuzz 4.9.0 → 4.9.5

package/scripts/verify/openai-embeddings.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * openai-embeddings.mjs — real-network verifier for the direct-to-OpenAI
+ * (BYOK) provider (i.e. `provider: "openai"`).
+ *
+ * WHY THIS LIVES OUTSIDE JEST
+ *
+ *   `openaiProvider.test.js` uses an injected `fetchImpl` and verifies
+ *   request shape + parse logic. That doesn't tell you anything about:
+ *     - Whether the OpenAI key actually has embeddings access.
+ *     - Whether the live endpoint returns the dimensions our client expects.
+ *     - Whether rate-limit / auth failures surface correctly.
+ *
+ *   This script exercises the same code path the production runtime does,
+ *   against api.openai.com (or a configured OpenAI-compat proxy URL).
+ *
+ * REQUIRED ENV
+ *
+ *   LOXIA_OPENAI_API_KEY   the OpenAI key (or proxy key for compat layers).
+ *
+ * OPTIONAL ENV
+ *
+ *   LOXIA_OPENAI_URL       override endpoint (for DeepInfra, Together,
+ *                          or other OpenAI-compat layers). Default:
+ *                          https://api.openai.com/v1/embeddings
+ *   LOXIA_OPENAI_MODEL_ID  default text-embedding-3-small
+ *   LOXIA_OPENAI_DIMS      declared dimensions (default 1536; use 3072 for
+ *                          text-embedding-3-large)
+ *
+ * RUN
+ *
+ *   npm run verify:openai-embeddings
+ *
+ *   Exit codes:
+ *     0  all checks passed
+ *     1  one or more checks failed
+ *     2  required env not set (intentional non-zero so CI can't silently
+ *        skip the verification by forgetting the secret).
+ */
+
+import { OpenAIEmbeddingProvider } from '../../src/services/embeddings/providers/openaiProvider.js';
+
+const apiKey  = process.env.LOXIA_OPENAI_API_KEY;
+const url     = process.env.LOXIA_OPENAI_URL || 'https://api.openai.com/v1/embeddings';
+const modelId = process.env.LOXIA_OPENAI_MODEL_ID || 'text-embedding-3-small';
+const dims    = Number(process.env.LOXIA_OPENAI_DIMS || 1536);
+
+console.log('OpenAI direct (BYOK) embeddings real-network verifier');
+if (!apiKey) {
+  console.error('');
+  console.error('SKIP: required env vars not set.');
+  console.error('  LOXIA_OPENAI_API_KEY: MISSING');
+  console.error('');
+  console.error('CI must either configure this secret and re-run, or');
+  console.error('explicitly skip this step (and accept the coverage gap).');
+  process.exit(2);
+}
+
+console.log(`Endpoint:   ${url}`);
+console.log(`Model:      ${modelId}`);
+console.log(`Dimensions: ${dims}`);
+console.log('');
+
+const results = [];
+let failures = 0;
+
+function check(name, fn) {
+  return (async () => {
+    const t0 = Date.now();
+    try {
+      await fn();
+      const ms = Date.now() - t0;
+      results.push({ name, ok: true, ms });
+      console.log(`  ✔ ${name} (${ms}ms)`);
+    } catch (err) {
+      failures++;
+      const ms = Date.now() - t0;
+      results.push({ name, ok: false, ms, err: err?.message });
+      console.error(`  ✗ ${name} (${ms}ms)`);
+      console.error(`      ${err?.stack || err}`);
+    }
+  })();
+}
+
+function dot(a, b) {
+  let s = 0;
+  for (let i = 0; i < a.length; i++) s += a[i] * b[i];
+  return s;
+}
+
+const provider = new OpenAIEmbeddingProvider({
+  getApiKey: () => apiKey,
+  url,
+  modelId,
+  dimensions: dims,
+});
+
+await check('single embedQuery returns Float32Array of declared dim', async () => {
+  const vec = await provider.embedQuery('hello world');
+  if (!(vec instanceof Float32Array)) throw new Error('not a Float32Array');
+  if (vec.length !== dims) {
+    throw new Error(`endpoint returned ${vec.length}d but client declared ${dims}d`);
+  }
+  let sum = 0;
+  for (let i = 0; i < vec.length; i++) sum += vec[i] * vec[i];
+  const mag = Math.sqrt(sum);
+  if (Math.abs(mag - 1) > 1e-3) throw new Error(`magnitude=${mag.toFixed(6)} (expected ≈1)`);
+});
+
+await check('batch embedDocuments returns one vector per input', async () => {
+  const inputs = ['retry logic', 'rate limiting', 'circuit breakers'];
+  const vecs = await provider.embedDocuments(inputs);
+  if (!Array.isArray(vecs)) throw new Error('not an array');
+  if (vecs.length !== inputs.length) throw new Error(`got ${vecs.length} vectors for ${inputs.length} inputs`);
+  for (let i = 0; i < vecs.length; i++) {
+    if (!(vecs[i] instanceof Float32Array)) throw new Error(`vec[${i}] not Float32Array`);
+    if (vecs[i].length !== dims) throw new Error(`vec[${i}].length=${vecs[i].length}, expected ${dims}`);
+  }
+});
+
+await check('cosine similarity is semantically meaningful', async () => {
+  const seed       = await provider.embedQuery('how do I throttle rate-limited API requests?');
+  const paraphrase = await provider.embedQuery('handling rate limits in HTTP API clients');
+  const unrelated  = await provider.embedQuery('recipe for chocolate chip cookies');
+  const sp = dot(seed, paraphrase);
+  const su = dot(seed, unrelated);
+  if (sp <= su) throw new Error(`paraphrase(${sp.toFixed(3)}) ≤ unrelated(${su.toFixed(3)})`);
+  if ((sp - su) <= 0.03) throw new Error(`gap=${(sp - su).toFixed(3)} too small (expected >0.03)`);
+});
+
+await check('provider.health reports ok', async () => {
+  const h = await provider.health();
+  if (!h.ok) throw new Error(`health.ok=${h.ok} (${h.reason || 'no reason'})`);
+});
+
+console.log('');
+const passed = results.filter(r => r.ok).length;
+const total = results.length;
+console.log(`${failures === 0 ? 'PASS' : 'FAIL'}: ${passed}/${total} checks passed`);
+process.exit(failures === 0 ? 0 : 1);

package/src/__test-utils__/mockFactories.js

@@ -58,6 +58,8 @@ export function createMockStateManager() {
     initialize: jest.fn().mockResolvedValue(undefined),
     initializeStateDirectory: jest.fn().mockResolvedValue(undefined),
     persistAgentState: jest.fn().mockResolvedValue(undefined),
+    deleteAgentState: jest.fn().mockResolvedValue(undefined),
+    removeFromAgentIndex: jest.fn().mockResolvedValue(undefined),
     getProjectState: jest.fn().mockResolvedValue({}),
     loadProjectState: jest.fn().mockResolvedValue({}),
     saveProjectState: jest.fn().mockResolvedValue(undefined),

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

@@ -266,8 +266,28 @@ describe('AgentPool', () => {
       expect(await pool.getAgent(agent.id)).toBeNull();
     });
 
-    test('throws for non-existent agent', async () => {
-      await expect(pool.deleteAgent('nonexistent')).rejects.toThrow('Agent not found');
+    // Was: 'throws for non-existent agent'. The contract changed —
+    // deleteAgent is now idempotent so the bulk-delete UX can wipe
+    // unloaded agents (the My Squadron group-delete used to fail with
+    // "Failed to delete N agents" whenever any target wasn't in memory).
+    // deleteAgentState is itself ENOENT-tolerant, so "not in pool, not
+    // on disk" still resolves to success — same end state.
+    test('is idempotent for an agent not in the pool (succeeds, clears persistent state)', async () => {
+      stateManager.deleteAgentState.mockClear();
+      const result = await pool.deleteAgent('nonexistent-agent-id');
+      expect(result.success).toBe(true);
+      // Still asked the state manager to clear it — best-effort cleanup.
+      expect(stateManager.deleteAgentState).toHaveBeenCalledWith('nonexistent-agent-id');
+    });
+
+    test('removes persistent state even when the agent was never loaded', async () => {
+      // Simulate an agent that exists on disk but isn't in memory
+      // (e.g. process restarted, or it was unloaded earlier).
+      stateManager.deleteAgentState.mockClear();
+      // No createAgent — pool.agents stays empty.
+      const result = await pool.deleteAgent('unloaded-but-on-disk');
+      expect(result.success).toBe(true);
+      expect(stateManager.deleteAgentState).toHaveBeenCalledWith('unloaded-but-on-disk');
     });
 
     test('cleans up maps (directory, paused, notification)', async () => {

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

@@ -0,0 +1,215 @@
+/**
+ * agentScheduler — auto-recall injection wiring (Phase 6d.2).
+ *
+ * The auto-recall primitive + the aiService.augmentSystemPrompt helper
+ * are tested elsewhere (autoRecall.test.js, aiService.embed.test.js).
+ * This suite pins the WIRING contract: the scheduler calls the helper
+ * with the right arguments under the right conditions, and never lets
+ * a failure block the turn.
+ *
+ * Pins:
+ *   - Fires when memory capability is present AND lastUserMsg has content.
+ *   - Skipped when memory capability is absent (no point).
+ *   - Skipped when there's no user message (e.g. an agent-initiated turn).
+ *   - Skipped when augmentSystemPrompt is undefined (older aiService builds).
+ *   - Errors from augmentSystemPrompt are swallowed; the turn continues
+ *     with the un-augmented prompt.
+ *   - The augmented prompt is what reaches aiService.sendMessage.
+ *
+ * Strategy: build a minimal "scheduler-shaped" object with just the
+ * methods we need, then call into the same code path. Avoids dragging
+ * the full constructor + every dependency into the test.
+ */
+
+import { describe, test, expect, jest, beforeEach } from '@jest/globals';
+
+/**
+ * The auto-recall wiring lives inside _getAIResponse-adjacent code in
+ * agentScheduler. Rather than firing the whole scheduler, we extract
+ * the wiring into a tiny reusable helper here that mirrors EXACTLY the
+ * shape inserted in the scheduler. The contract is identical:
+ *   if agent has 'memory' capability AND aiService.augmentSystemPrompt
+ *   AND there's a non-empty lastUserMsg.content → call the helper.
+ *
+ * This is a "shape-match" test: it catches regressions on the gating
+ * logic + argument passing without coupling to the whole scheduler.
+ */
+async function runAutoRecallStep({
+  agent,
+  conversationHistory,
+  aiService,
+  logger,
+  enhancedSystemPrompt,
+}) {
+  const lastUserMsg = [...conversationHistory].reverse().find(m => m.role === 'user');
+  if (
+    Array.isArray(agent.capabilities) &&
+    agent.capabilities.includes('memory') &&
+    typeof aiService?.augmentSystemPrompt === 'function'
+  ) {
+    try {
+      const recentText = typeof lastUserMsg?.content === 'string' ? lastUserMsg.content : '';
+      if (recentText) {
+        enhancedSystemPrompt = await aiService.augmentSystemPrompt(
+          enhancedSystemPrompt, agent.id, recentText,
+        );
+      }
+    } catch (err) {
+      logger.warn?.(`Auto-recall injection failed for agent ${agent.id} (continuing without)`, {
+        error: err?.message,
+      });
+    }
+  }
+  return enhancedSystemPrompt;
+}
+
+function makeLogger() {
+  return { warn: jest.fn(), info: jest.fn(), error: jest.fn(), debug: jest.fn() };
+}
+
+describe('agentScheduler — auto-recall wiring (Phase 6d.2)', () => {
+  let aiService, logger;
+
+  beforeEach(() => {
+    aiService = {
+      augmentSystemPrompt: jest.fn(async (prompt) => prompt + '\n\n## RELEVANT CONTEXT (auto-recalled)\n\nmocked'),
+    };
+    logger = makeLogger();
+  });
+
+  test('fires when memory capability + user message + helper are all present', async () => {
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory', 'terminal'] },
+      conversationHistory: [
+        { role: 'system', content: 'sys' },
+        { role: 'user',   content: 'how do we throttle telegram?' },
+      ],
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(aiService.augmentSystemPrompt).toHaveBeenCalledTimes(1);
+    expect(aiService.augmentSystemPrompt).toHaveBeenCalledWith(
+      'BASE',
+      'a1',
+      'how do we throttle telegram?',
+    );
+    expect(out).toContain('## RELEVANT CONTEXT (auto-recalled)');
+  });
+
+  test('uses the MOST RECENT user message (not an older one)', async () => {
+    await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory'] },
+      conversationHistory: [
+        { role: 'user',      content: 'first question'  },
+        { role: 'assistant', content: 'first answer'    },
+        { role: 'user',      content: 'second question' },
+        { role: 'assistant', content: 'second answer'   },
+        { role: 'user',      content: 'latest question' },
+      ],
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(aiService.augmentSystemPrompt).toHaveBeenCalledWith(
+      'BASE', 'a1', 'latest question',
+    );
+  });
+
+  test('skipped when agent lacks memory capability', async () => {
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['terminal'] },          // no memory
+      conversationHistory: [{ role: 'user', content: 'hi' }],
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(aiService.augmentSystemPrompt).not.toHaveBeenCalled();
+    expect(out).toBe('BASE');                                    // unchanged
+  });
+
+  test('skipped when capabilities is missing or non-array', async () => {
+    for (const caps of [undefined, null, 'memory', 42]) {
+      aiService.augmentSystemPrompt.mockClear();
+      const out = await runAutoRecallStep({
+        agent: { id: 'a1', capabilities: caps },
+        conversationHistory: [{ role: 'user', content: 'hi' }],
+        aiService, logger,
+        enhancedSystemPrompt: 'BASE',
+      });
+      expect(aiService.augmentSystemPrompt).not.toHaveBeenCalled();
+      expect(out).toBe('BASE');
+    }
+  });
+
+  test('skipped when there is no user message at all', async () => {
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory'] },
+      conversationHistory: [{ role: 'system', content: 'sys' }],   // no user msg
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(aiService.augmentSystemPrompt).not.toHaveBeenCalled();
+    expect(out).toBe('BASE');
+  });
+
+  test('skipped when the latest user message has empty content', async () => {
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory'] },
+      conversationHistory: [{ role: 'user', content: '' }],
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(aiService.augmentSystemPrompt).not.toHaveBeenCalled();
+    expect(out).toBe('BASE');
+  });
+
+  test('skipped when user message content is non-string (array form)', async () => {
+    // Some history entries have content as [{type:'text', text:'...'}]. The
+    // wiring intentionally requires plain string content — array form is
+    // handled by the embedding service\'s own packing if it gets there.
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory'] },
+      conversationHistory: [{ role: 'user', content: [{ type: 'text', text: 'array form' }] }],
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(aiService.augmentSystemPrompt).not.toHaveBeenCalled();
+    expect(out).toBe('BASE');
+  });
+
+  test('older aiService without augmentSystemPrompt → no-op (forward-compat)', async () => {
+    const oldService = {};   // no augmentSystemPrompt at all
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory'] },
+      conversationHistory: [{ role: 'user', content: 'hi' }],
+      aiService: oldService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(out).toBe('BASE');
+  });
+
+  test('errors from augmentSystemPrompt are swallowed; turn continues with un-augmented prompt', async () => {
+    aiService.augmentSystemPrompt = jest.fn(async () => {
+      throw new Error('embedding service exploded');
+    });
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory'] },
+      conversationHistory: [{ role: 'user', content: 'hi' }],
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(out).toBe('BASE');
+    expect(logger.warn).toHaveBeenCalled();
+  });
+
+  test('returned prompt is what aiService.augmentSystemPrompt produced', async () => {
+    aiService.augmentSystemPrompt = jest.fn(async () =>
+      'BASE\n\n## RELEVANT CONTEXT (auto-recalled)\n\nremembered thing'
+    );
+    const out = await runAutoRecallStep({
+      agent: { id: 'a1', capabilities: ['memory'] },
+      conversationHistory: [{ role: 'user', content: 'q' }],
+      aiService, logger,
+      enhancedSystemPrompt: 'BASE',
+    });
+    expect(out).toBe('BASE\n\n## RELEVANT CONTEXT (auto-recalled)\n\nremembered thing');
+  });
+});

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

@@ -0,0 +1,169 @@
+/**
+ * Tests for handleAIServiceFailure's error categorisation + broadcast policy.
+ *
+ * Behavioural contract:
+ *   • PERSISTENT failures (auth, unknown) → broadcast `agent_error`
+ *     so the UI banner / Telegram fanout reach the user.
+ *   • TRANSIENT failures (rate-limit, provider-overload, gateway, network)
+ *     → silent. They self-heal; broadcasting them every retry cycle was
+ *     the source of the Telegram floods.
+ *   • Token-limit → handled by the compaction path (early return),
+ *     never broadcasts directly from this function.
+ *
+ * The classification regexes are the most likely source of regression —
+ * cover the named status codes (401/403/429/503/504/529) plus the common
+ * textual variants we saw in production logs.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+
+const mockShouldAgentBeActive = jest.fn(() => ({ active: false, reason: 'idle' }));
+const mockGetActiveAgents = jest.fn(() => []);
+const mockShouldSkipIteration = jest.fn(() => false);
+jest.unstable_mockModule('../../services/agentActivityService.js', () => ({
+  shouldAgentBeActive: mockShouldAgentBeActive,
+  getActiveAgents: mockGetActiveAgents,
+  shouldSkipIteration: mockShouldSkipIteration,
+}));
+
+const { default: AgentScheduler } = await import('../agentScheduler.js');
+
+function makeScheduler() {
+  const logger = createMockLogger();
+  const agent = { id: 'a1', name: 'TestAgent', sessionId: 'sess-1' };
+  const agentPool = {
+    getAgent: jest.fn().mockResolvedValue(agent),
+    persistAgentState: jest.fn().mockResolvedValue(undefined),
+    addToolResult: jest.fn().mockResolvedValue(undefined),
+  };
+  const broadcasts = [];
+  const webSocketManager = {
+    broadcastToSession: jest.fn((sessionId, payload) => broadcasts.push({ sessionId, payload })),
+  };
+  const aiService = { abortRequest: jest.fn(), getActiveRequest: () => null };
+  const scheduler = new AgentScheduler(agentPool, {}, aiService, logger);
+  scheduler.webSocketManager = webSocketManager;
+  scheduler.broadcastAgentStateUpdate = jest.fn().mockResolvedValue(undefined);
+  scheduler.getAgentSession = jest.fn(() => 'sess-1');
+  return { scheduler, agentPool, broadcasts, agent };
+}
+
+const errorClasses = [
+  // -- TRANSIENT (no broadcast) --
+  { name: 'rate-limit text',         msg: 'Rate limit exceeded', expectBroadcast: false, label: 'rate-limit' },
+  { name: 'rate-limit 429',          msg: 'HTTP 429 Too Many Requests', expectBroadcast: false, label: 'rate-limit' },
+  { name: 'provider overload 529',   msg: 'HTTP 529 Overloaded',  expectBroadcast: false, label: 'provider-overload' },
+  { name: 'provider overload text',  msg: 'The model is overloaded with requests', expectBroadcast: false, label: 'provider-overload' },
+  { name: 'server is busy',          msg: 'Sorry, the server is busy. Please try again.', expectBroadcast: false, label: 'provider-overload' },
+  { name: 'capacity error',          msg: 'Provider returned a capacity error', expectBroadcast: false, label: 'provider-overload' },
+  { name: 'gateway 503',             msg: 'HTTP 503 Service Unavailable', expectBroadcast: false, label: 'gateway-error' },
+  { name: 'gateway 504',             msg: '504 Gateway Timeout from upstream', expectBroadcast: false, label: 'gateway-error' },
+  { name: 'bad gateway',             msg: 'Got a bad gateway response', expectBroadcast: false, label: 'gateway-error' },
+  { name: 'upstream',                msg: 'Upstream connect error', expectBroadcast: false, label: 'gateway-error' },
+  { name: 'network ECONNREFUSED',    msg: 'ECONNREFUSED 127.0.0.1', expectBroadcast: false, label: 'network-error' },
+  { name: 'network ETIMEDOUT',       msg: 'connect ETIMEDOUT', expectBroadcast: false, label: 'network-error' },
+  { name: 'network ENOTFOUND',       msg: 'getaddrinfo ENOTFOUND api.foo', expectBroadcast: false, label: 'network-error' },
+  { name: 'fetch failed',            msg: 'fetch failed', expectBroadcast: false, label: 'network-error' },
+  // -- PERSISTENT (broadcast) --
+  { name: 'auth: API key',           msg: 'Invalid API key provided',           expectBroadcast: true, label: 'api-key-error' },
+  { name: 'auth: 401',               msg: 'HTTP 401 Unauthorized',              expectBroadcast: true, label: 'api-key-error' },
+  { name: 'auth: 403',               msg: 'HTTP 403 Forbidden',                  expectBroadcast: true, label: 'api-key-error' },
+  { name: 'unknown: random 500',     msg: 'Random 500 Internal Server Error from the AI', expectBroadcast: true, label: 'server-error' },
+  { name: 'unknown: weird shape',    msg: 'Provider returned malformed JSON',   expectBroadcast: true, label: 'server-error' },
+];
+
+describe('handleAIServiceFailure: error categorisation', () => {
+  describe.each(errorClasses)('%s', (tc) => {
+    let scheduler, broadcasts;
+    beforeEach(() => {
+      jest.clearAllMocks();
+      ({ scheduler, broadcasts } = makeScheduler());
+    });
+
+    test(`"${tc.msg}" → broadcast=${tc.expectBroadcast}, state="${tc.label}"`, async () => {
+      await scheduler.handleAIServiceFailure('a1', new Error(tc.msg));
+
+      const agentErrorBroadcasts = broadcasts.filter(b => b.payload?.type === 'agent_error');
+      if (tc.expectBroadcast) {
+        expect(agentErrorBroadcasts.length).toBe(1);
+        expect(agentErrorBroadcasts[0].payload.data.error).toBe(tc.msg);
+      } else {
+        expect(agentErrorBroadcasts.length).toBe(0);
+      }
+      // Every branch must publish an agent-state hint so the UI shows the
+      // right pause reason; verify the label we expect.
+      expect(scheduler.broadcastAgentStateUpdate).toHaveBeenCalledWith('a1', tc.label);
+    });
+  });
+});
+
+describe('handleAIServiceFailure: gateway 503 takes the network delay, not the rate-limit delay', () => {
+  test('uses NETWORK_ERROR_DELAY_MS for 503 errors', async () => {
+    const { scheduler, agentPool, agent } = makeScheduler();
+    const beforeMs = Date.now();
+    await scheduler.handleAIServiceFailure('a1', new Error('HTTP 503 Service Unavailable'));
+
+    // delayEndTime is in agent.delayEndTime as ISO; should be ~30s out.
+    const elapsedMs = new Date(agent.delayEndTime).getTime() - beforeMs;
+    // Use a generous range to tolerate test-machine drift.
+    expect(elapsedMs).toBeGreaterThanOrEqual(20 * 1000);
+    expect(elapsedMs).toBeLessThanOrEqual(90 * 1000);
+    expect(agentPool.persistAgentState).toHaveBeenCalledWith('a1');
+  });
+});
+
+describe('handleAIServiceFailure: token-limit path early-returns without broadcasting', () => {
+  test('does not call broadcastToSession for token-limit errors', async () => {
+    const { scheduler, broadcasts } = makeScheduler();
+    // Stub the token-limit handler so we don't fall into its compaction logic.
+    scheduler.handleTokenLimitError = jest.fn().mockResolvedValue(undefined);
+    scheduler.isTokenLimitError = jest.fn().mockReturnValue(true);
+
+    await scheduler.handleAIServiceFailure('a1', new Error('Context length exceeded'));
+
+    expect(scheduler.handleTokenLimitError).toHaveBeenCalledWith('a1', expect.any(Object), expect.any(Error));
+    // Importantly: no agent_error broadcast from this path.
+    expect(broadcasts.filter(b => b.payload?.type === 'agent_error').length).toBe(0);
+  });
+});
+
+describe('isTokenLimitError: regex-free implementation preserves all original patterns', () => {
+  // The original implementation matched these literal substrings plus a
+  // `/maximum.*exceeded/` regex. The refactored version replaces the
+  // regex with a two-indexOf check. Cover both halves explicitly.
+  const positives = [
+    'prompt is too long for this model',
+    'too many tokens for the model',
+    'context length exceeded the limit',
+    'context window exceeded',
+    'maximum context size reached',
+    'token limit reached for this request',
+    'max_tokens is set too high',
+    'context_length_exceeded: request had 200000 tokens',
+    // The 'maximum.*exceeded' case — "maximum" appears before "exceeded".
+    'maximum response limit exceeded for input',
+    'maximum 100k context length exceeded by 5k tokens',
+  ];
+  const negatives = [
+    'rate limit exceeded',
+    'connection timed out',
+    'maximum retries reached',         // has "maximum" but no "exceeded" after it
+    'something exceeded the maximum',  // "exceeded" appears BEFORE "maximum" — old regex required maximum→exceeded order
+    'random unrelated error',
+  ];
+
+  describe.each(positives)('positive: %s', (msg) => {
+    test('classifies as token-limit', () => {
+      const { scheduler } = makeScheduler();
+      expect(scheduler.isTokenLimitError(msg.toLowerCase())).toBe(true);
+    });
+  });
+
+  describe.each(negatives)('negative: %s', (msg) => {
+    test('does not classify as token-limit', () => {
+      const { scheduler } = makeScheduler();
+      expect(scheduler.isTokenLimitError(msg.toLowerCase())).toBe(false);
+    });
+  });
+});