@geminilight/mindos 0.6.74 → 0.6.75

package/_standalone/__tests__/acp/agent-descriptors.test.ts

@@ -0,0 +1,284 @@
+import { describe, it, expect } from 'vitest';
+import {
+  resolveAgentCommand,
+  parseAcpAgentOverrides,
+  findUserOverride,
+  AGENT_DESCRIPTORS,
+  AGENT_ALIASES,
+  resolveAlias,
+  getDescriptorBinary,
+  getDescriptorInstallCmd,
+  getDetectableAgents,
+} from '@/lib/acp/agent-descriptors';
+import type { AcpRegistryEntry } from '@/lib/acp/types';
+
+/* ── resolveAgentCommand ─────────────────────────────────────────────── */
+
+describe('resolveAgentCommand', () => {
+  const fakeRegistry: AcpRegistryEntry = {
+    id: 'test-agent',
+    name: 'Test Agent',
+    description: 'A test agent',
+    transport: 'npx',
+    command: '@test/agent',
+    args: ['--flag'],
+  };
+
+  it('uses user override when command is set', () => {
+    const result = resolveAgentCommand('gemini', fakeRegistry, { command: '/custom/gemini', args: ['--my-flag'] });
+    expect(result.source).toBe('user-override');
+    expect(result.cmd).toBe('/custom/gemini');
+    expect(result.args).toEqual(['--my-flag']);
+    expect(result.enabled).toBe(true);
+  });
+
+  it('uses user override args with descriptor command', () => {
+    const result = resolveAgentCommand('gemini', fakeRegistry, { args: ['--custom-flag'] });
+    expect(result.source).toBe('user-override');
+    expect(result.cmd).toBe('gemini'); // from descriptor
+    expect(result.args).toEqual(['--custom-flag']);
+  });
+
+  it('falls back to descriptor when no override', () => {
+    const result = resolveAgentCommand('gemini', fakeRegistry);
+    expect(result.source).toBe('descriptor');
+    expect(result.cmd).toBe('gemini');
+    expect(result.args).toEqual(['--experimental-acp']);
+  });
+
+  it('falls back to registry for unknown agent', () => {
+    const result = resolveAgentCommand('unknown-agent', fakeRegistry);
+    expect(result.source).toBe('registry');
+    expect(result.cmd).toBe('npx');
+    expect(result.args).toEqual(['--yes', '@test/agent', '--flag']);
+  });
+
+  it('falls back to agentId when nothing matches', () => {
+    const result = resolveAgentCommand('totally-unknown');
+    expect(result.source).toBe('registry');
+    expect(result.cmd).toBe('totally-unknown');
+    expect(result.args).toEqual([]);
+  });
+
+  it('respects enabled=false', () => {
+    const result = resolveAgentCommand('gemini', fakeRegistry, { enabled: false });
+    expect(result.enabled).toBe(false);
+  });
+
+  it('passes through env from user override', () => {
+    const result = resolveAgentCommand('gemini', fakeRegistry, { env: { FOO: 'bar' } });
+    expect(result.env).toEqual({ FOO: 'bar' });
+  });
+
+  it('resolves codebuddy-code correctly', () => {
+    const result = resolveAgentCommand('codebuddy-code');
+    expect(result.source).toBe('descriptor');
+    expect(result.cmd).toBe('codebuddy');
+    expect(result.args).toEqual(['--acp']);
+  });
+
+  it('resolves claude-acp correctly', () => {
+    const result = resolveAgentCommand('claude-acp');
+    expect(result.source).toBe('descriptor');
+    expect(result.cmd).toBe('npx');
+    expect(result.args).toContain('@agentclientprotocol/claude-agent-acp');
+  });
+});
+
+/* ── parseAcpAgentOverrides ──────────────────────────────────────────── */
+
+describe('parseAcpAgentOverrides', () => {
+  it('returns undefined for null', () => {
+    expect(parseAcpAgentOverrides(null)).toBeUndefined();
+  });
+
+  it('returns undefined for non-object', () => {
+    expect(parseAcpAgentOverrides('string')).toBeUndefined();
+    expect(parseAcpAgentOverrides(42)).toBeUndefined();
+  });
+
+  it('returns undefined for array', () => {
+    expect(parseAcpAgentOverrides([])).toBeUndefined();
+  });
+
+  it('returns undefined for empty object', () => {
+    expect(parseAcpAgentOverrides({})).toBeUndefined();
+  });
+
+  it('parses valid config with command', () => {
+    const result = parseAcpAgentOverrides({ 'gemini': { command: '/usr/local/bin/gemini' } });
+    expect(result).toEqual({ 'gemini': { command: '/usr/local/bin/gemini' } });
+  });
+
+  it('parses valid config with args', () => {
+    const result = parseAcpAgentOverrides({ 'gemini': { args: ['--acp', '--verbose'] } });
+    expect(result).toEqual({ 'gemini': { args: ['--acp', '--verbose'] } });
+  });
+
+  it('parses enabled=false', () => {
+    const result = parseAcpAgentOverrides({ 'gemini': { enabled: false } });
+    expect(result).toEqual({ 'gemini': { enabled: false } });
+  });
+
+  it('filters non-string args', () => {
+    const result = parseAcpAgentOverrides({ 'gemini': { args: ['--ok', 42, null, '--fine'] } });
+    expect(result!['gemini'].args).toEqual(['--ok', '--fine']);
+  });
+
+  it('parses env vars', () => {
+    const result = parseAcpAgentOverrides({ 'gemini': { env: { API_KEY: 'abc' } } });
+    expect(result).toEqual({ 'gemini': { env: { API_KEY: 'abc' } } });
+  });
+
+  it('skips invalid entries', () => {
+    const result = parseAcpAgentOverrides({ 'good': { command: 'x' }, 'bad': 'not-an-object' });
+    expect(result).toEqual({ 'good': { command: 'x' } });
+  });
+
+  it('trims command whitespace', () => {
+    const result = parseAcpAgentOverrides({ 'gemini': { command: '  /usr/bin/gemini  ' } });
+    expect(result!['gemini'].command).toBe('/usr/bin/gemini');
+  });
+
+  it('ignores empty command', () => {
+    const result = parseAcpAgentOverrides({ 'gemini': { command: '   ' } });
+    expect(result).toBeUndefined();
+  });
+});
+
+/* ── Helpers ──────────────────────────────────────────────────────────── */
+
+describe('getDescriptorBinary', () => {
+  it('returns binary for known agent', () => {
+    expect(getDescriptorBinary('codebuddy-code')).toBe('codebuddy');
+    expect(getDescriptorBinary('gemini')).toBe('gemini');
+    expect(getDescriptorBinary('claude-acp')).toBe('claude');
+  });
+
+  it('returns undefined for unknown agent', () => {
+    expect(getDescriptorBinary('nonexistent')).toBeUndefined();
+  });
+});
+
+describe('getDescriptorInstallCmd', () => {
+  it('returns install command for known agent', () => {
+    expect(getDescriptorInstallCmd('gemini')).toBe('npm install -g @google/gemini-cli');
+  });
+
+  it('returns undefined for agent without install command', () => {
+    expect(getDescriptorInstallCmd('cursor')).toBeUndefined();
+  });
+});
+
+/* ── AGENT_DESCRIPTORS consistency ───────────────────────────────────── */
+
+describe('AGENT_DESCRIPTORS', () => {
+  it('all entries have required fields', () => {
+    for (const [id, desc] of Object.entries(AGENT_DESCRIPTORS)) {
+      expect(desc.binary, `${id} missing binary`).toBeTruthy();
+      expect(desc.cmd, `${id} missing cmd`).toBeTruthy();
+      expect(Array.isArray(desc.args), `${id} args not array`).toBe(true);
+    }
+  });
+
+  it('has entries for all critical canonical agents', () => {
+    const canonical = ['gemini', 'claude', 'codebuddy-code', 'codex-acp'];
+    for (const id of canonical) {
+      expect(AGENT_DESCRIPTORS[id], `missing descriptor for ${id}`).toBeDefined();
+    }
+  });
+
+  it('has no duplicate entries (aliases in AGENT_ALIASES instead)', () => {
+    const binaries = Object.values(AGENT_DESCRIPTORS).map(d => d.binary);
+    const uniqueBinaries = new Set(binaries);
+    expect(binaries.length).toBe(uniqueBinaries.size);
+  });
+});
+
+/* ── Aliases ──────────────────────────────────────────────────────────── */
+
+describe('resolveAlias', () => {
+  it('resolves known aliases to canonical IDs', () => {
+    expect(resolveAlias('gemini-cli')).toBe('gemini');
+    expect(resolveAlias('claude-code')).toBe('claude');
+    expect(resolveAlias('claude-acp')).toBe('claude');
+    expect(resolveAlias('codebuddy')).toBe('codebuddy-code');
+    expect(resolveAlias('codex')).toBe('codex-acp');
+    expect(resolveAlias('pi-acp')).toBe('pi');
+  });
+
+  it('returns canonical IDs unchanged', () => {
+    expect(resolveAlias('gemini')).toBe('gemini');
+    expect(resolveAlias('claude')).toBe('claude');
+    expect(resolveAlias('codebuddy-code')).toBe('codebuddy-code');
+  });
+
+  it('returns unknown IDs unchanged', () => {
+    expect(resolveAlias('totally-unknown')).toBe('totally-unknown');
+  });
+
+  it('all aliases point to existing descriptors', () => {
+    for (const [alias, canonical] of Object.entries(AGENT_ALIASES)) {
+      expect(AGENT_DESCRIPTORS[canonical], `alias ${alias} → ${canonical} not in AGENT_DESCRIPTORS`).toBeDefined();
+    }
+  });
+});
+
+/* ── findUserOverride ────────────────────────────────────────────────── */
+
+describe('findUserOverride', () => {
+  const overrides = {
+    'gemini': { command: '/usr/bin/gemini' },
+    'gemini-cli': { command: '/custom/gemini-cli' },
+    'codebuddy': { args: ['--custom'] },
+  };
+
+  it('finds by direct ID', () => {
+    expect(findUserOverride('gemini', overrides)).toEqual({ command: '/usr/bin/gemini' });
+  });
+
+  it('finds by alias → canonical (alias ID in overrides, canonical ID queried)', () => {
+    expect(findUserOverride('codebuddy-code', overrides)?.args).toEqual(['--custom']);
+  });
+
+  it('finds by canonical → alias (canonical ID in overrides, alias ID queried)', () => {
+    expect(findUserOverride('gemini-cli', overrides)).toEqual({ command: '/custom/gemini-cli' });
+  });
+
+  it('prefers direct match over alias resolution', () => {
+    const result = findUserOverride('gemini', overrides);
+    expect(result?.command).toBe('/usr/bin/gemini');
+  });
+
+  it('returns undefined for unknown agent', () => {
+    expect(findUserOverride('totally-unknown', overrides)).toBeUndefined();
+  });
+
+  it('returns undefined when no overrides', () => {
+    expect(findUserOverride('gemini', undefined)).toBeUndefined();
+  });
+});
+
+/* ── getDetectableAgents ─────────────────────────────────────────────── */
+
+describe('getDetectableAgents', () => {
+  it('returns all canonical agents', () => {
+    const agents = getDetectableAgents();
+    expect(agents.length).toBe(Object.keys(AGENT_DESCRIPTORS).length);
+  });
+
+  it('each agent has required detection fields', () => {
+    for (const agent of getDetectableAgents()) {
+      expect(agent.id).toBeTruthy();
+      expect(agent.name).toBeTruthy();
+      expect(agent.binary).toBeTruthy();
+    }
+  });
+
+  it('has no duplicate binaries', () => {
+    const agents = getDetectableAgents();
+    const binaries = agents.map(a => a.binary);
+    const unique = new Set(binaries);
+    expect(binaries.length).toBe(unique.size);
+  });
+});

package/_standalone/__tests__/acp/bridge.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { A2AMessage } from '../../lib/a2a/types';
+import type { AcpPromptResponse, AcpSessionUpdate } from '../../lib/acp/types';
+import { bridgeAcpResponseToA2a, bridgeAcpUpdatesToA2a } from '../../lib/acp/bridge';
+
+// Mock session module for bridgeA2aToAcp
+vi.mock('../../lib/acp/session', () => ({
+  createSession: vi.fn(),
+  prompt: vi.fn(),
+  closeSession: vi.fn(),
+}));
+
+import { bridgeA2aToAcp } from '../../lib/acp/bridge';
+import { createSession, prompt, closeSession } from '../../lib/acp/session';
+
+describe('A2A-ACP Bridge', () => {
+  describe('bridgeA2aToAcp', () => {
+    it('bridges A2A message to ACP and returns completed task', async () => {
+      vi.mocked(createSession).mockResolvedValueOnce({
+        id: 'ses-1',
+        agentId: 'test',
+        state: 'idle',
+        createdAt: new Date().toISOString(),
+        lastActivityAt: new Date().toISOString(),
+      });
+      vi.mocked(prompt).mockResolvedValueOnce({
+        sessionId: 'ses-1',
+        text: 'Agent response',
+        done: true,
+      });
+      vi.mocked(closeSession).mockResolvedValueOnce(undefined);
+
+      const a2aMsg: A2AMessage = {
+        role: 'ROLE_USER',
+        parts: [{ text: 'Hello ACP agent' }],
+      };
+
+      const task = await bridgeA2aToAcp(a2aMsg, 'test-agent');
+
+      expect(task.status.state).toBe('TASK_STATE_COMPLETED');
+      expect(task.artifacts?.[0]?.parts[0]?.text).toBe('Agent response');
+    });
+
+    it('returns failed task for empty message', async () => {
+      const a2aMsg: A2AMessage = {
+        role: 'ROLE_USER',
+        parts: [{ data: { binary: true } }],
+      };
+
+      const task = await bridgeA2aToAcp(a2aMsg, 'test-agent');
+
+      expect(task.status.state).toBe('TASK_STATE_FAILED');
+      expect(task.status.message?.parts[0]?.text).toContain('No text content');
+    });
+
+    it('returns failed task when session creation fails', async () => {
+      vi.mocked(createSession).mockRejectedValueOnce(new Error('Agent not found'));
+
+      const a2aMsg: A2AMessage = {
+        role: 'ROLE_USER',
+        parts: [{ text: 'test' }],
+      };
+
+      const task = await bridgeA2aToAcp(a2aMsg, 'nonexistent');
+
+      expect(task.status.state).toBe('TASK_STATE_FAILED');
+      expect(task.status.message?.parts[0]?.text).toContain('Failed to create ACP session');
+    });
+
+    it('returns failed task when prompt fails', async () => {
+      vi.mocked(createSession).mockResolvedValueOnce({
+        id: 'ses-1',
+        agentId: 'test',
+        state: 'idle',
+        createdAt: new Date().toISOString(),
+        lastActivityAt: new Date().toISOString(),
+      });
+      vi.mocked(prompt).mockRejectedValueOnce(new Error('Agent crashed'));
+      vi.mocked(closeSession).mockResolvedValueOnce(undefined);
+
+      const a2aMsg: A2AMessage = {
+        role: 'ROLE_USER',
+        parts: [{ text: 'crash me' }],
+      };
+
+      const task = await bridgeA2aToAcp(a2aMsg, 'test-agent');
+
+      expect(task.status.state).toBe('TASK_STATE_FAILED');
+      expect(task.status.message?.parts[0]?.text).toContain('ACP prompt failed');
+    });
+
+    it('closes session even on prompt failure', async () => {
+      vi.mocked(createSession).mockResolvedValueOnce({
+        id: 'ses-1',
+        agentId: 'test',
+        state: 'idle',
+        createdAt: new Date().toISOString(),
+        lastActivityAt: new Date().toISOString(),
+      });
+      vi.mocked(prompt).mockRejectedValueOnce(new Error('fail'));
+      vi.mocked(closeSession).mockResolvedValueOnce(undefined);
+
+      const a2aMsg: A2AMessage = {
+        role: 'ROLE_USER',
+        parts: [{ text: 'test' }],
+      };
+
+      await bridgeA2aToAcp(a2aMsg, 'test');
+
+      expect(closeSession).toHaveBeenCalledWith('ses-1');
+    });
+  });
+
+  describe('bridgeAcpResponseToA2a', () => {
+    it('converts a prompt response to A2A task', () => {
+      const response: AcpPromptResponse = {
+        sessionId: 'ses-1',
+        text: 'Hello from ACP',
+        done: true,
+      };
+
+      const task = bridgeAcpResponseToA2a('task-1', response);
+
+      expect(task.id).toBe('task-1');
+      expect(task.status.state).toBe('TASK_STATE_COMPLETED');
+      expect(task.status.message?.role).toBe('ROLE_AGENT');
+      expect(task.status.message?.parts[0]?.text).toBe('Hello from ACP');
+      expect(task.artifacts?.[0]?.parts[0]?.text).toBe('Hello from ACP');
+    });
+
+    it('creates task without artifacts for empty response', () => {
+      const response: AcpPromptResponse = {
+        sessionId: 'ses-1',
+        text: '',
+        done: true,
+      };
+
+      const task = bridgeAcpResponseToA2a('task-1', response);
+
+      expect(task.status.state).toBe('TASK_STATE_COMPLETED');
+      expect(task.artifacts).toBeUndefined();
+    });
+  });
+
+  describe('bridgeAcpUpdatesToA2a', () => {
+    it('aggregates text updates into completed task', () => {
+      const updates: AcpSessionUpdate[] = [
+        { sessionId: 'ses-1', type: 'text', text: 'Hello ' },
+        { sessionId: 'ses-1', type: 'text', text: 'world' },
+        { sessionId: 'ses-1', type: 'done' },
+      ];
+
+      const task = bridgeAcpUpdatesToA2a('task-1', updates);
+
+      expect(task.status.state).toBe('TASK_STATE_COMPLETED');
+      expect(task.status.message?.parts[0]?.text).toBe('Hello world');
+    });
+
+    it('returns working state for incomplete updates', () => {
+      const updates: AcpSessionUpdate[] = [
+        { sessionId: 'ses-1', type: 'text', text: 'partial' },
+      ];
+
+      const task = bridgeAcpUpdatesToA2a('task-1', updates);
+
+      expect(task.status.state).toBe('TASK_STATE_WORKING');
+    });
+
+    it('returns failed state for error update', () => {
+      const updates: AcpSessionUpdate[] = [
+        { sessionId: 'ses-1', type: 'text', text: 'start...' },
+        { sessionId: 'ses-1', type: 'error', error: 'Agent died' },
+      ];
+
+      const task = bridgeAcpUpdatesToA2a('task-1', updates);
+
+      expect(task.status.state).toBe('TASK_STATE_FAILED');
+      expect(task.status.message?.parts[0]?.text).toBe('Agent died');
+    });
+
+    it('handles empty updates', () => {
+      const task = bridgeAcpUpdatesToA2a('task-1', []);
+
+      expect(task.status.state).toBe('TASK_STATE_WORKING');
+      expect(task.artifacts).toBeUndefined();
+    });
+  });
+});

package/_standalone/__tests__/acp/registry.test.ts

@@ -0,0 +1,193 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { fetchAcpRegistry, getAcpAgents, findAcpAgent, clearRegistryCache } from '../../lib/acp/registry';
+
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+const MOCK_REGISTRY = {
+  version: '1',
+  agents: [
+    {
+      id: 'gemini-cli',
+      name: 'Gemini CLI',
+      description: 'Google Gemini CLI agent',
+      transport: 'npx',
+      command: '@google/gemini-cli',
+      tags: ['coding', 'search'],
+    },
+    {
+      id: 'claude-code',
+      name: 'Claude Code',
+      description: 'Anthropic Claude coding agent',
+      transport: 'npx',
+      command: '@anthropic/claude-code',
+      tags: ['coding'],
+    },
+    {
+      id: 'new-cdn-only',
+      name: 'CDN Only Agent',
+      description: 'An agent only available from CDN',
+      transport: 'stdio',
+      command: 'cdn-agent',
+      tags: ['new'],
+    },
+  ],
+};
+
+describe('ACP Registry', () => {
+  beforeEach(() => {
+    clearRegistryCache();
+    mockFetch.mockReset();
+  });
+
+  describe('fetchAcpRegistry', () => {
+    it('fetches and merges with built-in registry', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => MOCK_REGISTRY });
+
+      const registry = await fetchAcpRegistry();
+      expect(registry).not.toBeNull();
+      // Built-in agents are present with canonical IDs
+      const gemini = registry.agents.find(a => a.id === 'gemini');
+      expect(gemini).toBeDefined();
+      expect(gemini!.name).toBe('Gemini CLI');
+      // CDN alias entries (gemini-cli) are deduplicated — built-in 'gemini' covers them
+      expect(registry.agents.find(a => a.id === 'gemini-cli')).toBeUndefined();
+      // CDN-only entries are added
+      const cdnOnly = registry.agents.find(a => a.id === 'new-cdn-only');
+      expect(cdnOnly).toBeDefined();
+      expect(cdnOnly!.name).toBe('CDN Only Agent');
+    });
+
+    it('caches the registry for subsequent calls', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => MOCK_REGISTRY });
+
+      await fetchAcpRegistry();
+      const cached = await fetchAcpRegistry();
+
+      expect(cached).not.toBeNull();
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+
+    it('returns built-in registry on fetch failure with no cache', async () => {
+      mockFetch.mockRejectedValueOnce(new Error('Network error'));
+
+      const registry = await fetchAcpRegistry();
+      // Should fall back to built-in registry, never null
+      expect(registry).not.toBeNull();
+      expect(registry.agents.length).toBeGreaterThan(0);
+      expect(registry.version).toBe('builtin');
+    });
+
+    it('returns stale cache on fetch failure', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => MOCK_REGISTRY });
+      await fetchAcpRegistry();
+
+      // Force cache expiry by clearing and re-caching with old date
+      // (we can't easily expire cache in test, so just test that cache works)
+      const cached = await fetchAcpRegistry();
+      expect(cached).not.toBeNull();
+      expect(cached!.agents.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it('returns built-in registry for non-ok HTTP response with no cache', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: false, status: 500 });
+
+      const registry = await fetchAcpRegistry();
+      // Should fall back to built-in registry, never null
+      expect(registry).not.toBeNull();
+      expect(registry.agents.length).toBeGreaterThan(0);
+      expect(registry.version).toBe('builtin');
+    });
+
+    it('merges empty CDN registry with built-in agents', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => ({ version: '1', agents: [] }) });
+
+      const registry = await fetchAcpRegistry();
+      expect(registry).not.toBeNull();
+      // Even with empty CDN, built-in agents should be present
+      expect(registry.agents.length).toBeGreaterThan(0);
+    });
+
+    it('handles object-keyed registry format', async () => {
+      const objectFormat = {
+        version: '1',
+        'my-agent': { name: 'My Agent', description: 'test', transport: 'stdio', command: 'my-agent' },
+      };
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => objectFormat });
+
+      const registry = await fetchAcpRegistry();
+      expect(registry).not.toBeNull();
+      expect(registry.agents.length).toBeGreaterThanOrEqual(1);
+      expect(registry.agents.find(a => a.id === 'my-agent')).toBeDefined();
+    });
+
+    it('handles malformed entries gracefully', async () => {
+      const withBad = {
+        version: '1',
+        agents: [
+          { id: 'good', name: 'Good', description: 'ok', transport: 'stdio', command: 'good' },
+          null,
+          { notAnAgent: true },
+          { id: '', name: '', description: '' },
+        ],
+      };
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => withBad });
+
+      const registry = await fetchAcpRegistry();
+      expect(registry).not.toBeNull();
+      // Valid CDN entry should be present (merged with built-in)
+      expect(registry.agents.find(a => a.id === 'good')).toBeDefined();
+      // Malformed entries should not be present
+      expect(registry.agents.find(a => a.id === '')).toBeUndefined();
+    });
+  });
+
+  describe('getAcpAgents', () => {
+    it('returns agents from registry merged with built-in', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => MOCK_REGISTRY });
+
+      const agents = await getAcpAgents();
+      expect(agents.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it('returns built-in agents on failure', async () => {
+      mockFetch.mockRejectedValueOnce(new Error('down'));
+
+      const agents = await getAcpAgents();
+      expect(agents.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('findAcpAgent', () => {
+    it('finds agent by canonical ID', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => MOCK_REGISTRY });
+
+      const agent = await findAcpAgent('gemini');
+      expect(agent).not.toBeNull();
+      expect(agent!.name).toBe('Gemini CLI');
+    });
+
+    it('finds agent by alias ID (resolves to canonical)', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => MOCK_REGISTRY });
+
+      const agent = await findAcpAgent('gemini-cli');
+      expect(agent).not.toBeNull();
+      expect(agent!.name).toBe('Gemini CLI');
+    });
+
+    it('finds CDN-only agent', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => MOCK_REGISTRY });
+
+      const agent = await findAcpAgent('new-cdn-only');
+      expect(agent).not.toBeNull();
+      expect(agent!.name).toBe('CDN Only Agent');
+    });
+
+    it('returns null for unknown ID', async () => {
+      mockFetch.mockResolvedValueOnce({ ok: true, json: async () => MOCK_REGISTRY });
+
+      const agent = await findAcpAgent('nonexistent');
+      expect(agent).toBeNull();
+    });
+  });
+});