feat: add first-class CCS WebSearch runtime

tests/unit/api/profile-lifecycle-service.test.ts

@@ -128,7 +128,7 @@ describe('profile lifecycle service', () => {
     expect(result.skipped).toEqual([]);
   });
 
-  it('does not register orphan profiles when WebSearch hook setup fails', async () => {
+  it('does not register orphan profiles when local WebSearch tool setup fails', async () => {
     const ccsDir = path.join(tempHome, '.ccs');
     fs.mkdirSync(ccsDir, { recursive: true });
 
@@ -152,7 +152,7 @@ describe('profile lifecycle service', () => {
     expect(copyFileSpy).toHaveBeenCalled();
     expect(result.registered).toEqual([]);
     expect(result.skipped).toHaveLength(1);
-    expect(result.skipped[0]?.reason).toContain('could not prepare the profile hook');
+    expect(result.skipped[0]?.reason).toContain('could not prepare the local WebSearch tool');
     expect(config.profiles.extra).toBeUndefined();
   });
 
@@ -240,7 +240,7 @@ describe('profile lifecycle service', () => {
     expect(result.error).toContain('Invalid source profile name');
   });
 
-  it('rolls back copied settings when WebSearch hook setup fails', async () => {
+  it('rolls back copied settings when local WebSearch tool setup fails', async () => {
     const ccsDir = path.join(tempHome, '.ccs');
     fs.mkdirSync(ccsDir, { recursive: true });
     fs.writeFileSync(
@@ -263,7 +263,7 @@ describe('profile lifecycle service', () => {
     const result = await runInScopedCcsDir(() => copyApiProfile('source', 'copy-dest'));
 
     expect(result.success).toBe(false);
-    expect(result.error).toContain('could not prepare the profile hook');
+    expect(result.error).toContain('could not prepare the local WebSearch tool');
     expect(copyFileSpy).toHaveBeenCalled();
     expect(fs.existsSync(path.join(ccsDir, 'copy-dest.settings.json'))).toBe(false);
   });
@@ -287,7 +287,7 @@ describe('profile lifecycle service', () => {
     expect(result.error).toContain('Invalid bundle profile target');
   });
 
-  it('rolls back imported settings when WebSearch hook setup fails', async () => {
+  it('rolls back imported settings when local WebSearch tool setup fails', async () => {
     const ccsDir = path.join(tempHome, '.ccs');
     fs.mkdirSync(ccsDir, { recursive: true });
     fs.writeFileSync(
@@ -314,7 +314,7 @@ describe('profile lifecycle service', () => {
     );
 
     expect(result.success).toBe(false);
-    expect(result.error).toContain('could not prepare the profile hook');
+    expect(result.error).toContain('could not prepare the local WebSearch tool');
     expect(copyFileSpy).toHaveBeenCalled();
     expect(fs.existsSync(path.join(ccsDir, 'import-failure.settings.json'))).toBe(false);
   });

tests/unit/api/profile-writer-anthropic.test.ts

@@ -104,7 +104,7 @@ describe('profile-writer Anthropic direct', () => {
     expect(settings.env.ANTHROPIC_API_KEY).toBe('');
   });
 
-  it('rolls back the created settings file when WebSearch hook installation fails', () => {
+  it('rolls back the created settings file when local WebSearch tool setup fails', () => {
     const copyFileSpy = spyOn(fs, 'copyFileSync').mockImplementation(() => {
       throw new Error('copy failed');
     });
@@ -117,7 +117,7 @@ describe('profile-writer Anthropic direct', () => {
     );
 
     expect(result.success).toBe(false);
-    expect(result.error).toContain('could not prepare the profile hook');
+    expect(result.error).toContain('could not prepare the local WebSearch tool');
     expect(copyFileSpy).toHaveBeenCalled();
     expect(fs.existsSync(path.join(tempHome, '.ccs', 'hook-failure.settings.json'))).toBe(false);
   });

tests/unit/hooks/ccs-websearch-mcp-server.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it } from 'bun:test';
+import { spawn } from 'child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const serverPath = join(process.cwd(), 'lib', 'mcp', 'ccs-websearch-server.cjs');
+
+function encodeMessage(message: unknown): string {
+  const body = JSON.stringify(message);
+  return `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`;
+}
+
+function collectResponses(
+  child: ReturnType<typeof spawn>,
+  expectedCount: number
+): Promise<Array<Record<string, unknown>>> {
+  return new Promise((resolve, reject) => {
+    let buffer = Buffer.alloc(0);
+    const responses: Array<Record<string, unknown>> = [];
+    const timer = setTimeout(() => reject(new Error('Timed out waiting for MCP responses')), 5000);
+
+    function tryParse(): void {
+      while (true) {
+        const headerEnd = buffer.indexOf('\r\n\r\n');
+        if (headerEnd === -1) {
+          return;
+        }
+
+        const headerText = buffer.slice(0, headerEnd).toString('utf8');
+        const match = headerText.match(/content-length:\s*(\d+)/i);
+        if (!match) {
+          reject(new Error('Missing Content-Length header'));
+          return;
+        }
+
+        const contentLength = Number.parseInt(match[1], 10);
+        const messageEnd = headerEnd + 4 + contentLength;
+        if (buffer.length < messageEnd) {
+          return;
+        }
+
+        const body = buffer.slice(headerEnd + 4, messageEnd).toString('utf8');
+        buffer = buffer.slice(messageEnd);
+        responses.push(JSON.parse(body) as Record<string, unknown>);
+
+        if (responses.length >= expectedCount) {
+          clearTimeout(timer);
+          resolve(responses);
+          return;
+        }
+      }
+    }
+
+    child.stdout.on('data', (chunk: Buffer) => {
+      buffer = Buffer.concat([buffer, chunk]);
+      try {
+        tryParse();
+      } catch (error) {
+        clearTimeout(timer);
+        reject(error);
+      }
+    });
+
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+
+    child.stderr.on('data', () => {
+      // Ignore debug noise in tests.
+    });
+  });
+}
+
+describe('ccs-websearch MCP server', () => {
+  it('lists the CCS search tool and returns provider-backed results', async () => {
+    const tempDir = mkdtempSync(join(tmpdir(), 'ccs-websearch-mcp-server-'));
+    const preloadPath = join(tempDir, 'mock-fetch.cjs');
+    const html = `
+      <a class="result__a" href="/l/?uddg=https%3A%2F%2Fexample.com%2Farticle">Example title</a>
+      <a class="result__snippet">Example snippet</a>
+    `.trim();
+    writeFileSync(
+      preloadPath,
+      `global.fetch = async () => ({ ok: true, text: async () => ${JSON.stringify(html)} });\n`,
+      'utf8'
+    );
+
+    const child = spawn('node', ['-r', preloadPath, serverPath], {
+      env: {
+        ...process.env,
+        CCS_PROFILE_TYPE: 'settings',
+        CCS_WEBSEARCH_ENABLED: '1',
+        CCS_WEBSEARCH_SKIP: '0',
+        CCS_WEBSEARCH_BRAVE: '0',
+        CCS_WEBSEARCH_DUCKDUCKGO: '1',
+        CCS_WEBSEARCH_EXA: '0',
+        CCS_WEBSEARCH_GEMINI: '0',
+        CCS_WEBSEARCH_GROK: '0',
+        CCS_WEBSEARCH_OPENCODE: '0',
+        CCS_WEBSEARCH_TAVILY: '0',
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    try {
+      const responsesPromise = collectResponses(child, 3);
+      child.stdin.write(
+        encodeMessage({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'initialize',
+          params: {
+            protocolVersion: '2024-11-05',
+            capabilities: {},
+            clientInfo: { name: 'bun-test', version: '1.0.0' },
+          },
+        })
+      );
+      child.stdin.write(encodeMessage({ jsonrpc: '2.0', id: 2, method: 'tools/list' }));
+      child.stdin.write(
+        encodeMessage({
+          jsonrpc: '2.0',
+          id: 3,
+          method: 'tools/call',
+          params: { name: 'search', arguments: { query: 'btc price' } },
+        })
+      );
+
+      const responses = await responsesPromise;
+      const toolsList = responses.find((message) => message.id === 2);
+      const toolCall = responses.find((message) => message.id === 3);
+
+      expect(toolsList?.result).toEqual({
+        tools: [
+          {
+            name: 'search',
+            description:
+              'Search the web through CCS-managed providers. Provider order: Exa, Tavily, Brave Search, DuckDuckGo, then optional legacy CLI fallback.',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                query: {
+                  type: 'string',
+                  description: 'The search query to run against CCS WebSearch providers.',
+                },
+              },
+              required: ['query'],
+              additionalProperties: false,
+            },
+          },
+        ],
+      });
+      expect(toolCall?.result).toBeDefined();
+      expect(
+        ((toolCall?.result as { content: Array<{ text: string }> }).content[0] || {}).text
+      ).toContain('CCS local WebSearch evidence');
+      expect(
+        ((toolCall?.result as { content: Array<{ text: string }> }).content[0] || {}).text
+      ).toContain('Provider: DuckDuckGo');
+    } finally {
+      child.kill();
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it('hides the tool for native account profiles', async () => {
+    const child = spawn('node', [serverPath], {
+      env: {
+        ...process.env,
+        CCS_PROFILE_TYPE: 'account',
+        CCS_WEBSEARCH_ENABLED: '1',
+        CCS_WEBSEARCH_SKIP: '1',
+        CCS_WEBSEARCH_DUCKDUCKGO: '1',
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    try {
+      const responsesPromise = collectResponses(child, 2);
+      child.stdin.write(
+        encodeMessage({
+          jsonrpc: '2.0',
+          id: 1,
+          method: 'initialize',
+          params: {
+            protocolVersion: '2024-11-05',
+            capabilities: {},
+            clientInfo: { name: 'bun-test', version: '1.0.0' },
+          },
+        })
+      );
+      child.stdin.write(encodeMessage({ jsonrpc: '2.0', id: 2, method: 'tools/list' }));
+
+      const responses = await responsesPromise;
+      const toolsList = responses.find((message) => message.id === 2);
+      expect(toolsList?.result).toEqual({ tools: [] });
+    } finally {
+      child.kill();
+    }
+  });
+});

tests/unit/targets/settings-profile-websearch-launch.test.ts

@@ -92,7 +92,7 @@ exit 0
     fs.rmSync(tmpHome, { recursive: true, force: true });
   });
 
-  it('fails before Claude launch when an enabled WebSearch hook cannot be prepared', () => {
+  it('fails before Claude launch when the local WebSearch tool runtime cannot be prepared', () => {
     if (process.platform === 'win32') return;
 
     fs.writeFileSync(path.join(ccsDir, 'hooks'), 'not-a-directory', 'utf8');
@@ -100,7 +100,7 @@ exit 0
     const result = runCcs(['glm', 'smoke'], baseEnv);
 
     expect(result.status).toBe(1);
-    expect(result.stderr).toContain('could not prepare the profile hook for "glm"');
+    expect(result.stderr).toContain('could not prepare the local WebSearch tool');
     expect(fs.existsSync(claudeArgsLogPath)).toBe(false);
   });
 
@@ -117,7 +117,9 @@ exit 0
     const result = runCcs(['glm', 'smoke'], baseEnv);
 
     expect(result.status).toBe(0);
-    expect(result.stderr).not.toContain('could not prepare the profile hook for "glm"');
+    expect(result.stderr).not.toContain('could not prepare the local WebSearch tool');
     expect(fs.existsSync(claudeArgsLogPath)).toBe(true);
+    expect(fs.readFileSync(claudeArgsLogPath, 'utf8')).toContain('--disallowedTools');
+    expect(fs.readFileSync(claudeArgsLogPath, 'utf8')).toContain('WebSearch');
   });
 });

tests/unit/utils/websearch/claude-tool-args.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'bun:test';
+import { appendThirdPartyWebSearchToolArgs } from '../../../../src/utils/websearch/claude-tool-args';
+
+describe('appendThirdPartyWebSearchToolArgs', () => {
+  it('appends native WebSearch suppression when no tool flags are present', () => {
+    expect(appendThirdPartyWebSearchToolArgs(['smoke'])).toEqual([
+      'smoke',
+      '--disallowedTools',
+      'WebSearch',
+    ]);
+  });
+
+  it('does not append duplicate suppression when WebSearch is already disallowed', () => {
+    expect(appendThirdPartyWebSearchToolArgs(['smoke', '--disallowedTools', 'WebSearch'])).toEqual(
+      ['smoke', '--disallowedTools', 'WebSearch']
+    );
+  });
+
+  it('detects comma-separated disallowed tool values', () => {
+    expect(appendThirdPartyWebSearchToolArgs(['smoke', '--disallowedTools=Read,WebSearch'])).toEqual(
+      ['smoke', '--disallowedTools=Read,WebSearch']
+    );
+  });
+});

tests/unit/utils/websearch/mcp-installer.test.ts

@@ -0,0 +1,161 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { getHookPath } from '../../../../src/utils/websearch/hook-config';
+import {
+  ensureWebSearchMcp,
+  getWebSearchMcpServerName,
+  getWebSearchMcpServerPath,
+  uninstallWebSearchMcp,
+} from '../../../../src/utils/websearch/mcp-installer';
+
+describe('ensureWebSearchMcp', () => {
+  let tempHome: string | undefined;
+  let originalCcsHome: string | undefined;
+
+  function setupTempHome(): string {
+    tempHome = fs.mkdtempSync(path.join(os.tmpdir(), 'ccs-websearch-mcp-'));
+    originalCcsHome = process.env.CCS_HOME;
+    process.env.CCS_HOME = tempHome;
+    return tempHome;
+  }
+
+  function getCcsDir(): string {
+    if (!tempHome) {
+      throw new Error('tempHome not initialized');
+    }
+    return path.join(tempHome, '.ccs');
+  }
+
+  function writeEnabledConfig(): void {
+    const ccsDir = getCcsDir();
+    fs.mkdirSync(ccsDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(ccsDir, 'config.yaml'),
+      ['version: 12', 'websearch:', '  enabled: true', '  providers:', '    duckduckgo:', '      enabled: true', ''].join('\n'),
+      'utf8'
+    );
+  }
+
+  afterEach(() => {
+    if (originalCcsHome !== undefined) {
+      process.env.CCS_HOME = originalCcsHome;
+    } else {
+      delete process.env.CCS_HOME;
+    }
+
+    if (tempHome && fs.existsSync(tempHome)) {
+      fs.rmSync(tempHome, { recursive: true, force: true });
+    }
+
+    tempHome = undefined;
+    originalCcsHome = undefined;
+  });
+
+  it('installs the MCP server and preserves existing user mcpServers entries', () => {
+    setupTempHome();
+    writeEnabledConfig();
+
+    const claudeUserConfigPath = path.join(tempHome as string, '.claude.json');
+    fs.writeFileSync(
+      claudeUserConfigPath,
+      JSON.stringify(
+        {
+          mcpServers: {
+            existing: { command: 'uvx', args: ['some-server'] },
+          },
+        },
+        null,
+        2
+      ) + '\n',
+      'utf8'
+    );
+
+    expect(ensureWebSearchMcp()).toBe(true);
+    expect(fs.existsSync(getHookPath())).toBe(true);
+    expect(fs.existsSync(getWebSearchMcpServerPath())).toBe(true);
+
+    const config = JSON.parse(fs.readFileSync(claudeUserConfigPath, 'utf8')) as {
+      mcpServers: Record<string, { command: string; args: string[] }>;
+    };
+
+    expect(config.mcpServers.existing).toEqual({ command: 'uvx', args: ['some-server'] });
+    expect(config.mcpServers[getWebSearchMcpServerName()]).toEqual({
+      command: 'node',
+      args: [getWebSearchMcpServerPath()],
+    });
+  });
+
+  it('returns false and preserves malformed ~/.claude.json', () => {
+    setupTempHome();
+    writeEnabledConfig();
+
+    const claudeUserConfigPath = path.join(tempHome as string, '.claude.json');
+    fs.writeFileSync(claudeUserConfigPath, '{ invalid json', 'utf8');
+
+    expect(ensureWebSearchMcp()).toBe(false);
+    expect(fs.readFileSync(claudeUserConfigPath, 'utf8')).toBe('{ invalid json');
+  });
+
+  it('removes the managed MCP runtime while preserving unrelated server entries', () => {
+    setupTempHome();
+    writeEnabledConfig();
+
+    const claudeUserConfigPath = path.join(tempHome as string, '.claude.json');
+    fs.writeFileSync(
+      claudeUserConfigPath,
+      JSON.stringify(
+        {
+          mcpServers: {
+            existing: { command: 'uvx', args: ['some-server'] },
+          },
+        },
+        null,
+        2
+      ) + '\n',
+      'utf8'
+    );
+
+    expect(ensureWebSearchMcp()).toBe(true);
+
+    const instancePath = path.join(tempHome as string, '.ccs', 'instances', 'work');
+    fs.mkdirSync(instancePath, { recursive: true });
+    fs.writeFileSync(
+      path.join(instancePath, '.claude.json'),
+      JSON.stringify(
+        {
+          mcpServers: {
+            existing: { command: 'uvx', args: ['instance-server'] },
+            [getWebSearchMcpServerName()]: { command: 'node', args: ['/tmp/override.cjs'] },
+          },
+          otherKey: 'keep-me',
+        },
+        null,
+        2
+      ) + '\n',
+      'utf8'
+    );
+
+    expect(uninstallWebSearchMcp()).toBe(true);
+    expect(fs.existsSync(getWebSearchMcpServerPath())).toBe(false);
+
+    const globalConfig = JSON.parse(fs.readFileSync(claudeUserConfigPath, 'utf8')) as {
+      mcpServers: Record<string, { command: string; args: string[] }>;
+    };
+    expect(globalConfig.mcpServers).toEqual({
+      existing: { command: 'uvx', args: ['some-server'] },
+    });
+
+    const instanceConfig = JSON.parse(
+      fs.readFileSync(path.join(instancePath, '.claude.json'), 'utf8')
+    ) as {
+      otherKey: string;
+      mcpServers: Record<string, { command: string; args: string[] }>;
+    };
+    expect(instanceConfig.otherKey).toBe('keep-me');
+    expect(instanceConfig.mcpServers).toEqual({
+      existing: { command: 'uvx', args: ['instance-server'] },
+    });
+  });
+});