@kaitranntt/ccs 7.63.1 → 7.64.0-dev.2

package/lib/hooks/websearch-transformer.cjs

@@ -15,6 +15,10 @@
  */
 
 const { spawnSync } = require('child_process');
+const { createHash } = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 
 const isWindows = process.platform === 'win32';
 const DEFAULT_TIMEOUT_SEC = 55;
@@ -26,6 +30,13 @@ const DDG_URL = 'https://html.duckduckgo.com/html/';
 const BRAVE_URL = 'https://api.search.brave.com/res/v1/web/search';
 const USER_AGENT =
   'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+const PROVIDER_STATE_FILE = 'websearch-provider-state.json';
+const SHORT_RETRY_AFTER_MAX_SEC = 3;
+const TRANSIENT_RETRY_DELAY_MS = 750;
+const TRANSIENT_RETRY_ATTEMPTS = 1;
+const DEFAULT_RATE_LIMIT_COOLDOWN_SEC = 120;
+const DEFAULT_QUOTA_COOLDOWN_SEC = 900;
+const MAX_PROVIDER_COOLDOWN_SEC = 60 * 60;
 
 const SHARED_INSTRUCTIONS = `Instructions:
 1. Search the web for current, up-to-date information
@@ -64,12 +75,246 @@ function debug(message) {
   }
 }
 
-function shouldSkipHook() {
-  if (process.env.CCS_WEBSEARCH_SKIP === '1') return true;
+function getCcsDirPath() {
+  if ((process.env.CCS_DIR || '').trim()) {
+    return path.resolve(process.env.CCS_DIR.trim());
+  }
+
+  if ((process.env.CCS_HOME || '').trim()) {
+    return path.join(path.resolve(process.env.CCS_HOME.trim()), '.ccs');
+  }
+
+  const home = (process.env.HOME || process.env.USERPROFILE || '').trim();
+  if (home) {
+    return path.join(home, '.ccs');
+  }
+
+  return path.join(process.cwd(), '.ccs');
+}
+
+function isTraceEnabled() {
+  return process.env.CCS_WEBSEARCH_TRACE === '1' || process.env.CCS_DEBUG === '1';
+}
+
+function normalizeSafePrefix(inputPath) {
+  return `${path.resolve(inputPath)}${path.sep}`;
+}
+
+function getSafeTracePrefixes() {
+  return [
+    normalizeSafePrefix(path.join(getCcsDirPath(), 'logs')),
+    normalizeSafePrefix(os.tmpdir()),
+    normalizeSafePrefix('/var/log'),
+  ];
+}
+
+function getProviderStatePath() {
+  return path.join(getCcsDirPath(), 'cache', PROVIDER_STATE_FILE);
+}
+
+function readProviderState() {
+  try {
+    const statePath = getProviderStatePath();
+    if (!fs.existsSync(statePath)) {
+      return { cooldowns: {} };
+    }
+
+    const parsed = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    const cooldowns =
+      parsed && typeof parsed === 'object' && parsed.cooldowns && typeof parsed.cooldowns === 'object'
+        ? parsed.cooldowns
+        : {};
+    return { cooldowns };
+  } catch {
+    return { cooldowns: {} };
+  }
+}
+
+function writeProviderState(state) {
+  try {
+    const statePath = getProviderStatePath();
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    const tempPath = `${statePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tempPath, JSON.stringify(state, null, 2) + '\n', 'utf8');
+    fs.renameSync(tempPath, statePath);
+  } catch {
+    // Best-effort only.
+  }
+}
+
+function sanitizeProviderState(state) {
+  const now = Date.now();
+  const nextCooldowns = {};
+  let changed = false;
+
+  for (const [providerId, entry] of Object.entries(state.cooldowns || {})) {
+    if (!entry || typeof entry !== 'object') {
+      changed = true;
+      continue;
+    }
+
+    const until = Number.parseInt(String(entry.until || ''), 10);
+    if (!Number.isFinite(until) || until <= now) {
+      changed = true;
+      continue;
+    }
+
+    nextCooldowns[providerId] = {
+      until,
+      reason: typeof entry.reason === 'string' ? entry.reason : 'rate_limited',
+      updatedAt: Number.parseInt(String(entry.updatedAt || ''), 10) || now,
+      sourceError: typeof entry.sourceError === 'string' ? entry.sourceError : '',
+    };
+  }
+
+  return {
+    state: { cooldowns: nextCooldowns },
+    changed,
+  };
+}
+
+function getProviderCooldown(providerId) {
+  const { state, changed } = sanitizeProviderState(readProviderState());
+  if (changed) {
+    writeProviderState(state);
+  }
+
+  return state.cooldowns[providerId] || null;
+}
+
+function clearProviderCooldown(providerId) {
+  const { state } = sanitizeProviderState(readProviderState());
+  if (!(providerId in state.cooldowns)) {
+    return;
+  }
+
+  delete state.cooldowns[providerId];
+  writeProviderState(state);
+}
+
+function applyProviderCooldown(providerId, cooldownSec, reason, sourceError) {
+  const clampedCooldownSec = Math.max(
+    1,
+    Math.min(MAX_PROVIDER_COOLDOWN_SEC, Math.floor(cooldownSec))
+  );
+  const { state } = sanitizeProviderState(readProviderState());
+  const until = Date.now() + clampedCooldownSec * 1000;
+  state.cooldowns[providerId] = {
+    until,
+    reason,
+    updatedAt: Date.now(),
+    sourceError: sourceError || '',
+  };
+  writeProviderState(state);
+  return until;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function getAllowedTraceFileOverride() {
+  const configured = (process.env.CCS_WEBSEARCH_TRACE_FILE || '').trim();
+  if (!configured) {
+    return null;
+  }
+
+  const resolved = path.resolve(configured);
+  if (getSafeTracePrefixes().some((prefix) => resolved.startsWith(prefix))) {
+    return resolved;
+  }
+
+  return null;
+}
+
+function getTraceFilePath() {
+  const fallback = path.join(getCcsDirPath(), 'logs', 'websearch-trace.jsonl');
+  return getAllowedTraceFileOverride() || fallback;
+}
+
+function traceWebSearchEvent(event, payload = {}) {
+  if (!isTraceEnabled()) {
+    return;
+  }
+
+  try {
+    const traceFilePath = getTraceFilePath();
+    fs.mkdirSync(path.dirname(traceFilePath), { recursive: true });
+    fs.appendFileSync(
+      traceFilePath,
+      JSON.stringify({
+        at: new Date().toISOString(),
+        event,
+        launchId: process.env.CCS_WEBSEARCH_TRACE_LAUNCH_ID || null,
+        launcher: process.env.CCS_WEBSEARCH_TRACE_LAUNCHER || null,
+        profileType: process.env.CCS_PROFILE_TYPE || null,
+        pid: process.pid,
+        ...payload,
+      }) + '\n',
+      'utf8'
+    );
+  } catch {
+    // Best-effort only.
+  }
+}
+
+function readHeaderValue(headers, headerName) {
+  if (!headers) {
+    return '';
+  }
+
+  if (typeof headers.get === 'function') {
+    return headers.get(headerName) || '';
+  }
+
+  const direct = headers[headerName] ?? headers[String(headerName).toLowerCase()];
+  if (Array.isArray(direct)) {
+    return direct[0] || '';
+  }
+  return typeof direct === 'string' ? direct : '';
+}
+
+function parseRetryAfterSeconds(rawValue) {
+  const value = String(rawValue || '').trim();
+  if (!value) {
+    return null;
+  }
+
+  const asSeconds = Number.parseInt(value, 10);
+  if (Number.isFinite(asSeconds) && asSeconds > 0) {
+    return asSeconds;
+  }
+
+  const asDate = Date.parse(value);
+  if (Number.isFinite(asDate)) {
+    const deltaSec = Math.ceil((asDate - Date.now()) / 1000);
+    return deltaSec > 0 ? deltaSec : null;
+  }
+
+  return null;
+}
+
+function getQueryFingerprint(query) {
+  const normalizedQuery = typeof query === 'string' ? query.trim() : '';
+  return {
+    queryHash: normalizedQuery
+      ? createHash('sha256').update(normalizedQuery).digest('hex').slice(0, 16)
+      : null,
+    queryLength: normalizedQuery.length,
+  };
+}
+
+function getSkipReason() {
+  if (process.env.CCS_WEBSEARCH_SKIP === '1') return 'skip_flag';
   const profileType = process.env.CCS_PROFILE_TYPE;
-  if (profileType === 'account' || profileType === 'default') return true;
-  if (process.env.CCS_WEBSEARCH_ENABLED === '0') return true;
-  return false;
+  if (profileType === 'account') return 'native_account_profile';
+  if (profileType === 'default') return 'native_default_profile';
+  if (process.env.CCS_WEBSEARCH_ENABLED === '0') return 'disabled';
+  return null;
+}
+
+function shouldSkipHook() {
+  return getSkipReason() !== null;
 }
 
 function isCliAvailable(cmd) {
@@ -183,23 +428,58 @@ function extractDuckDuckGoResults(html, count) {
 }
 
 function formatStructuredSearchResults(query, providerName, results) {
+  const lines = [
+    'CCS local WebSearch evidence',
+    `Provider: ${providerName}`,
+    `Query: "${query}"`,
+    `Result count: ${results.length}`,
+    '',
+  ];
+
   if (!results.length) {
-    return `No search results found for "${query}" via ${providerName}.`;
+    lines.push('No results found.');
+    return lines.join('\n');
   }
 
-  const lines = [`Search results for "${query}" via ${providerName}:`, ''];
   for (const [index, result] of results.entries()) {
     lines.push(`${index + 1}. ${result.title}`);
-    lines.push(`   ${result.url}`);
+    lines.push(`   URL: ${result.url}`);
     if (result.description) {
-      lines.push(`   ${result.description}`);
+      lines.push(`   Snippet: ${result.description}`);
     }
     lines.push('');
   }
-  lines.push('Use these results to answer the user directly.');
   return lines.join('\n');
 }
 
+function buildSuccessHookOutput(query, providerName, content) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: `CCS already retrieved WebSearch results locally via ${providerName}. Use the provided context instead of calling native WebSearch for "${query}".`,
+      additionalContext: content,
+    },
+  };
+}
+
+function buildFailureHookOutput(query, errors) {
+  const detail = errors.map((entry) => `${entry.provider}: ${entry.error}`).join(' | ');
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: `CCS could not complete local WebSearch for "${query}". Native WebSearch is unavailable for this profile.`,
+      additionalContext: `CCS local WebSearch failed for "${query}". Attempted providers: ${detail}`,
+    },
+  };
+}
+
+function emitHookOutput(output) {
+  console.log(JSON.stringify(output));
+  process.exit(0);
+}
+
 async function fetchWithTimeout(url, options, timeoutMs) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -239,6 +519,8 @@ async function tryBraveSearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
       return {
         success: false,
         error: `Brave Search returned ${response.status}: ${body.slice(0, 160)}`,
+        statusCode: response.status,
+        retryAfterSec: parseRetryAfterSeconds(readHeaderValue(response.headers, 'retry-after')),
       };
     }
 
@@ -290,7 +572,12 @@ async function tryExaSearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
 
     if (!response.ok) {
       const body = await response.text();
-      return { success: false, error: `Exa returned ${response.status}: ${body.slice(0, 160)}` };
+      return {
+        success: false,
+        error: `Exa returned ${response.status}: ${body.slice(0, 160)}`,
+        statusCode: response.status,
+        retryAfterSec: parseRetryAfterSeconds(readHeaderValue(response.headers, 'retry-after')),
+      };
     }
 
     const body = await response.json();
@@ -342,7 +629,12 @@ async function tryTavilySearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
 
     if (!response.ok) {
       const body = await response.text();
-      return { success: false, error: `Tavily returned ${response.status}: ${body.slice(0, 160)}` };
+      return {
+        success: false,
+        error: `Tavily returned ${response.status}: ${body.slice(0, 160)}`,
+        statusCode: response.status,
+        retryAfterSec: parseRetryAfterSeconds(readHeaderValue(response.headers, 'retry-after')),
+      };
     }
 
     const body = await response.json();
@@ -379,7 +671,12 @@ async function tryDuckDuckGoSearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
     );
 
     if (!response.ok) {
-      return { success: false, error: `DuckDuckGo returned ${response.status}` };
+      return {
+        success: false,
+        error: `DuckDuckGo returned ${response.status}`,
+        statusCode: response.status,
+        retryAfterSec: parseRetryAfterSeconds(readHeaderValue(response.headers, 'retry-after')),
+      };
     }
 
     const html = await response.text();
@@ -534,39 +831,325 @@ function tryGrokSearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
 }
 
 function outputSuccess(query, content, providerName) {
-  const output = {
-    decision: 'block',
-    reason: `WebSearch handled via ${providerName}`,
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      permissionDecision: 'deny',
-      permissionDecisionReason: `[WebSearch Result via ${providerName}]\n\nQuery: "${query}"\n\n${content}`,
-    },
-  };
-
-  console.log(JSON.stringify(output));
-  process.exit(2);
+  emitHookOutput(buildSuccessHookOutput(query, providerName, content));
 }
 
 function outputAllFailedMessage(query, errors) {
-  const detail = errors.map((entry) => `${entry.provider}: ${entry.error}`).join(' | ');
-  const output = {
-    decision: 'block',
-    reason: 'WebSearch fallback failed',
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      permissionDecision: 'deny',
-      permissionDecisionReason: `WebSearch could not be completed for "${query}". ${detail}`,
+  emitHookOutput(buildFailureHookOutput(query, errors));
+}
+
+function getConfiguredProviders() {
+  return [
+    {
+      name: 'Exa',
+      id: 'exa',
+      available: () => isProviderEnabled('exa') && Boolean(getProviderApiKey('exa')),
+      fn: tryExaSearch,
+    },
+    {
+      name: 'Tavily',
+      id: 'tavily',
+      available: () => isProviderEnabled('tavily') && Boolean(getProviderApiKey('tavily')),
+      fn: tryTavilySearch,
+    },
+    {
+      name: 'Brave Search',
+      id: 'brave',
+      available: () => isProviderEnabled('brave') && Boolean(getProviderApiKey('brave')),
+      fn: tryBraveSearch,
+    },
+    {
+      name: 'DuckDuckGo',
+      id: 'duckduckgo',
+      available: () => isProviderEnabled('duckduckgo'),
+      fn: tryDuckDuckGoSearch,
+    },
+    {
+      name: 'Gemini CLI',
+      id: 'gemini',
+      available: () => isProviderEnabled('gemini') && isCliAvailable('gemini'),
+      fn: tryGeminiSearch,
+    },
+    {
+      name: 'OpenCode',
+      id: 'opencode',
+      available: () => isProviderEnabled('opencode') && isCliAvailable('opencode'),
+      fn: tryOpenCodeSearch,
+    },
+    {
+      name: 'Grok CLI',
+      id: 'grok',
+      available: () => isProviderEnabled('grok') && isCliAvailable('grok'),
+      fn: tryGrokSearch,
     },
+  ];
+}
+
+function looksLikeQuotaExhaustion(errorMessage) {
+  const lower = String(errorMessage || '').toLowerCase();
+  return (
+    (lower.includes('quota') &&
+      (lower.includes('exceed') ||
+        lower.includes('exhaust') ||
+        lower.includes('deplet') ||
+        lower.includes('limit') ||
+        lower.includes('used up'))) ||
+    lower.includes('insufficient credits') ||
+    lower.includes('credit balance') ||
+    lower.includes('out of credits') ||
+    lower.includes('billing hard limit') ||
+    lower.includes('monthly usage cap')
+  );
+}
+
+function looksLikeTransientFailure(errorMessage) {
+  const lower = String(errorMessage || '').toLowerCase();
+  return (
+    lower.includes('timed out') ||
+    lower.includes('timeout') ||
+    lower.includes('temporarily unavailable') ||
+    lower.includes('service unavailable') ||
+    lower.includes('bad gateway') ||
+    lower.includes('gateway timeout') ||
+    lower.includes('socket hang up') ||
+    lower.includes('econnreset') ||
+    lower.includes('fetch failed') ||
+    lower.includes('network')
+  );
+}
+
+function classifyProviderFailure(result) {
+  const errorMessage = String(result.error || '');
+  const statusCode =
+    Number.isFinite(result.statusCode) && result.statusCode > 0 ? result.statusCode : null;
+  const retryAfterSec = Number.isFinite(result.retryAfterSec) ? result.retryAfterSec : null;
+
+  if (looksLikeQuotaExhaustion(errorMessage)) {
+    return {
+      kind: 'cooldown',
+      reason: 'quota_exhausted',
+      cooldownSec: retryAfterSec || DEFAULT_QUOTA_COOLDOWN_SEC,
+      retryAfterSec,
+    };
+  }
+
+  if (statusCode === 429 || /too many requests|rate limit/i.test(errorMessage)) {
+    if (retryAfterSec && retryAfterSec <= SHORT_RETRY_AFTER_MAX_SEC) {
+      return {
+        kind: 'retry',
+        delayMs: retryAfterSec * 1000,
+        reason: 'rate_limited_short_backoff',
+        retryAfterSec,
+      };
+    }
+
+    return {
+      kind: 'cooldown',
+      reason: 'rate_limited',
+      cooldownSec: retryAfterSec || DEFAULT_RATE_LIMIT_COOLDOWN_SEC,
+      retryAfterSec,
+    };
+  }
+
+  if (
+    (statusCode && [502, 503, 504].includes(statusCode)) ||
+    looksLikeTransientFailure(errorMessage)
+  ) {
+    return {
+      kind: 'retry',
+      delayMs: TRANSIENT_RETRY_DELAY_MS,
+      reason: 'transient_failure',
+      retryAfterSec,
+    };
+  }
+
+  return {
+    kind: 'fail',
+    reason: 'non_retryable',
+    retryAfterSec,
   };
+}
 
-  console.log(JSON.stringify(output));
-  process.exit(2);
+async function runProviderWithPolicy(provider, query, timeoutSec, fingerprint) {
+  for (let attempt = 0; attempt <= TRANSIENT_RETRY_ATTEMPTS; attempt += 1) {
+    traceWebSearchEvent('websearch_provider_attempt', {
+      source: 'provider',
+      providerId: provider.id,
+      providerName: provider.name,
+      attempt: attempt + 1,
+      ...fingerprint,
+    });
+
+    const result = await provider.fn(query, timeoutSec);
+    if (result.success) {
+      clearProviderCooldown(provider.id);
+      return result;
+    }
+
+    const policy = classifyProviderFailure(result);
+    if (policy.kind === 'retry' && attempt < TRANSIENT_RETRY_ATTEMPTS) {
+      traceWebSearchEvent('websearch_provider_retry_scheduled', {
+        source: 'provider',
+        providerId: provider.id,
+        providerName: provider.name,
+        attempt: attempt + 1,
+        delayMs: policy.delayMs,
+        reason: policy.reason,
+        retryAfterSec: policy.retryAfterSec,
+        ...fingerprint,
+      });
+      await sleep(policy.delayMs);
+      continue;
+    }
+
+    if (policy.kind === 'retry' && policy.reason === 'rate_limited_short_backoff') {
+      const cooldownSec = policy.retryAfterSec || DEFAULT_RATE_LIMIT_COOLDOWN_SEC;
+      const until = applyProviderCooldown(provider.id, cooldownSec, 'rate_limited', result.error);
+      traceWebSearchEvent('websearch_provider_cooldown_applied', {
+        source: 'provider',
+        providerId: provider.id,
+        providerName: provider.name,
+        cooldownUntil: until,
+        cooldownSec,
+        reason: 'rate_limited',
+        retryAfterSec: policy.retryAfterSec,
+        afterRetryExhausted: true,
+        ...fingerprint,
+      });
+      return {
+        ...result,
+        error: `${result.error} (cooldown ${cooldownSec}s)`,
+      };
+    }
+
+    if (policy.kind === 'cooldown') {
+      const until = applyProviderCooldown(
+        provider.id,
+        policy.cooldownSec,
+        policy.reason,
+        result.error
+      );
+      traceWebSearchEvent('websearch_provider_cooldown_applied', {
+        source: 'provider',
+        providerId: provider.id,
+        providerName: provider.name,
+        cooldownUntil: until,
+        cooldownSec: policy.cooldownSec,
+        reason: policy.reason,
+        retryAfterSec: policy.retryAfterSec,
+        ...fingerprint,
+      });
+      return {
+        ...result,
+        error: `${result.error} (cooldown ${policy.cooldownSec}s)`,
+      };
+    }
+
+    return result;
+  }
+
+  return { success: false, error: 'Provider retry policy exhausted' };
+}
+
+function getActiveProviders() {
+  return getConfiguredProviders().filter((provider) => !getProviderCooldown(provider.id) && provider.available());
+}
+
+function getActiveProviderIds() {
+  return getActiveProviders().map((provider) => provider.id);
+}
+
+function hasAnyActiveProviders() {
+  return getActiveProviders().length > 0;
+}
+
+async function runLocalWebSearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
+  const fingerprint = getQueryFingerprint(query);
+  const configuredProviders = getConfiguredProviders();
+  const activeProviders = [];
+
+  for (const provider of configuredProviders) {
+    const cooldown = getProviderCooldown(provider.id);
+    if (cooldown) {
+      traceWebSearchEvent('websearch_provider_cooldown_skip', {
+        source: 'provider',
+        providerId: provider.id,
+        providerName: provider.name,
+        cooldownUntil: cooldown.until,
+        cooldownReason: cooldown.reason,
+        remainingMs: Math.max(0, cooldown.until - Date.now()),
+        ...fingerprint,
+      });
+      continue;
+    }
+
+    if (provider.available()) {
+      activeProviders.push(provider);
+    }
+  }
+
+  debug(
+    `Enabled providers: ${activeProviders.map((provider) => provider.name).join(', ') || 'none'}`
+  );
+  traceWebSearchEvent('websearch_provider_run_started', {
+    source: 'provider',
+    activeProviderIds: activeProviders.map((provider) => provider.id),
+    ...fingerprint,
+  });
+
+  if (activeProviders.length === 0) {
+    traceWebSearchEvent('websearch_provider_run_unavailable', {
+      source: 'provider',
+      activeProviderIds: [],
+      ...fingerprint,
+    });
+    return { success: false, noActiveProviders: true, errors: [] };
+  }
+
+  const errors = [];
+  for (const provider of activeProviders) {
+    debug(`Trying ${provider.name}`);
+    const result = await runProviderWithPolicy(provider, query, timeoutSec, fingerprint);
+    if (result.success) {
+      traceWebSearchEvent('websearch_provider_success', {
+        source: 'provider',
+        providerId: provider.id,
+        providerName: provider.name,
+        ...fingerprint,
+      });
+      return {
+        success: true,
+        providerId: provider.id,
+        providerName: provider.name,
+        content: result.content,
+      };
+    }
+    traceWebSearchEvent('websearch_provider_failure', {
+      source: 'provider',
+      providerId: provider.id,
+      providerName: provider.name,
+      error: result.error,
+      ...fingerprint,
+    });
+    errors.push({ provider: provider.name, error: result.error });
+  }
+
+  traceWebSearchEvent('websearch_provider_run_failed', {
+    source: 'provider',
+    errorCount: errors.length,
+    activeProviderIds: activeProviders.map((provider) => provider.id),
+    ...fingerprint,
+  });
+  return { success: false, noActiveProviders: false, errors };
 }
 
 async function processHook(input) {
   try {
     if (shouldSkipHook()) {
+      traceWebSearchEvent('websearch_hook_skipped', {
+        source: 'hook',
+        reason: getSkipReason(),
+      });
       process.exit(0);
     }
 
@@ -580,78 +1163,47 @@ async function processHook(input) {
       process.exit(0);
     }
 
+    traceWebSearchEvent('websearch_hook_invoked', {
+      source: 'hook',
+      ...getQueryFingerprint(query),
+    });
+
     const timeout = Number.parseInt(
       process.env.CCS_WEBSEARCH_TIMEOUT || `${DEFAULT_TIMEOUT_SEC}`,
       10
     );
-    const providers = [
-      {
-        name: 'Exa',
-        id: 'exa',
-        available: () => isProviderEnabled('exa') && Boolean(getProviderApiKey('exa')),
-        fn: tryExaSearch,
-      },
-      {
-        name: 'Tavily',
-        id: 'tavily',
-        available: () => isProviderEnabled('tavily') && Boolean(getProviderApiKey('tavily')),
-        fn: tryTavilySearch,
-      },
-      {
-        name: 'Brave Search',
-        id: 'brave',
-        available: () => isProviderEnabled('brave') && Boolean(getProviderApiKey('brave')),
-        fn: tryBraveSearch,
-      },
-      {
-        name: 'DuckDuckGo',
-        id: 'duckduckgo',
-        available: () => isProviderEnabled('duckduckgo'),
-        fn: tryDuckDuckGoSearch,
-      },
-      {
-        name: 'Gemini CLI',
-        id: 'gemini',
-        available: () => isProviderEnabled('gemini') && isCliAvailable('gemini'),
-        fn: tryGeminiSearch,
-      },
-      {
-        name: 'OpenCode',
-        id: 'opencode',
-        available: () => isProviderEnabled('opencode') && isCliAvailable('opencode'),
-        fn: tryOpenCodeSearch,
-      },
-      {
-        name: 'Grok CLI',
-        id: 'grok',
-        available: () => isProviderEnabled('grok') && isCliAvailable('grok'),
-        fn: tryGrokSearch,
-      },
-    ];
-
-    const activeProviders = providers.filter((provider) => provider.available());
-    debug(
-      `Enabled providers: ${activeProviders.map((provider) => provider.name).join(', ') || 'none'}`
-    );
-
-    if (activeProviders.length === 0) {
+    const result = await runLocalWebSearch(query, timeout);
+    if (result.noActiveProviders) {
+      traceWebSearchEvent('websearch_hook_no_active_providers', {
+        source: 'hook',
+        ...getQueryFingerprint(query),
+      });
       process.exit(0);
     }
 
-    const errors = [];
-    for (const provider of activeProviders) {
-      debug(`Trying ${provider.name}`);
-      const result = await provider.fn(query, timeout);
-      if (result.success) {
-        outputSuccess(query, result.content, provider.name);
-        return;
-      }
-      errors.push({ provider: provider.name, error: result.error });
+    if (result.success) {
+      traceWebSearchEvent('websearch_hook_success', {
+        source: 'hook',
+        providerId: result.providerId,
+        providerName: result.providerName,
+        ...getQueryFingerprint(query),
+      });
+      outputSuccess(query, result.content, result.providerName);
+      return;
     }
 
-    outputAllFailedMessage(query, errors);
+    traceWebSearchEvent('websearch_hook_failure', {
+      source: 'hook',
+      errorCount: result.errors.length,
+      ...getQueryFingerprint(query),
+    });
+    outputAllFailedMessage(query, result.errors);
   } catch (error) {
     debug(`Hook error: ${error.message}`);
+    traceWebSearchEvent('websearch_hook_error', {
+      source: 'hook',
+      error: error.message,
+    });
     process.exit(0);
   }
 }
@@ -675,8 +1227,20 @@ if (require.main === module) {
 }
 
 module.exports = {
+  buildFailureHookOutput,
+  buildSuccessHookOutput,
   extractDuckDuckGoResults,
   formatStructuredSearchResults,
+  getActiveProviders,
+  hasAnyActiveProviders,
+  runLocalWebSearch,
+  shouldSkipHook,
+  getActiveProviderIds,
+  classifyProviderFailure,
+  getQueryFingerprint,
+  getSkipReason,
+  parseRetryAfterSeconds,
+  traceWebSearchEvent,
   tryExaSearch,
   tryTavilySearch,
   tryDuckDuckGoSearch,