Method search

src/tools/web/firecrawl.ts:30–81

(query: string, opts: SearchOptions)

  readonly requiresAuth = true;

  async search(query: string, opts: SearchOptions): Promise<WebSearchResult[]> {
    const apiKey = process.env.FIRECRAWL_API_KEY;
    if (!apiKey) {
      throw new WebSearchError(
        'Firecrawl backend selected but FIRECRAWL_API_KEY is not set. ' +
        'Get a free key at https://www.firecrawl.dev — then paste it in chat (the agent saves it via save_api_key and retries), ' +
        'or add FIRECRAWL_API_KEY=fc-... to ~/.qodex/.env.',
        this.name,
      );
    }

    const scrapeContent = process.env.FIRECRAWL_SCRAPE_CONTENT === '1';
    const timeoutMs = opts.timeoutMs ?? (scrapeContent ? 40_000 : 20_000); // scraping is slower
    const internalAbort = new AbortController();
    const timer = setTimeout(() => internalAbort.abort(), timeoutMs);
    const onOuterAbort = (): void => internalAbort.abort();
    opts.signal?.addEventListener('abort', onOuterAbort);

    try {
      const body: Record<string, unknown> = { query, limit: Math.min(opts.limit, 20) };
      if (scrapeContent) body.scrapeOptions = { formats: ['markdown'] };

      const res = await proxyFetch(FIRECRAWL_URL, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${apiKey}`,
        },
        body: JSON.stringify(body),
        signal: internalAbort.signal,
      });
      if (!res.ok) {
        const text = await res.text().catch(() => '');
        throw new WebSearchError(`Firecrawl HTTP ${res.status}: ${text.slice(0, 300)}`, this.name);
      }
      const payload = await res.json() as { success?: boolean; data?: Array<{ title?: string; url?: string; description?: string; markdown?: string }>; error?: string };
      if (payload.success === false) {
        throw new WebSearchError(`Firecrawl error: ${payload.error ?? 'unknown'}`, this.name);
      }
      // Trim scraped markdown to the passages most relevant to the search query (semantic), and
      // record how often that beat the positional fallback — surfaced in the dashboard.
      const { recordExtract } = await import('./extract-metrics.js');
      return mapFirecrawlResults(payload, opts.limit, { query, onExtract: (mode) => { void recordExtract(mode); } });
    } catch (e: any) {
      if (e instanceof WebSearchError) throw e;
      if (e?.name === 'AbortError') throw new WebSearchError('Request aborted (timeout or cancellation)', this.name, e);
      throw new WebSearchError(`Network error: ${e?.message ?? e}`, this.name, e);
    } finally {
      clearTimeout(timer);
      opts.signal?.removeEventListener('abort', onOuterAbort);
    }
  }
}