@theowlops/boombot 0.0.0-stage → 1.1.1

package/dist/node_modules/@boombot/core/research/providers/brave.js

@@ -0,0 +1,36 @@
+/**
+ * Brave Search adapter (paid, API key required).
+ *
+ * Wraps the Brave Search API (`/res/v1/web/search`). The key travels in
+ * the `X-Subscription-Token` header — never in the URL, never logged.
+ */
+import { fetchJson, truncate, withRetry } from '../http.js';
+const MAX_RESULTS = 20;
+export function createBraveProvider(options) {
+    return {
+        id: 'brave',
+        kind: 'paid',
+        async search(query, opts = {}) {
+            const limit = Math.min(Math.max(opts.limit ?? 8, 1), MAX_RESULTS);
+            const params = new URLSearchParams({
+                q: query,
+                count: String(limit),
+                text_decorations: '0',
+                safesearch: 'moderate',
+            });
+            const url = `https://api.search.brave.com/res/v1/web/search?${params.toString()}`;
+            const raw = await withRetry(() => fetchJson(url, {
+                signal: opts.signal,
+                timeoutMs: 20_000,
+                headers: { 'X-Subscription-Token': options.apiKey },
+            }));
+            const body = raw;
+            return (body.web?.results ?? []).slice(0, limit).map((hit) => ({
+                title: hit.title ?? '',
+                url: hit.url ?? '',
+                snippet: truncate(hit.description ?? '', 300),
+                source: 'brave',
+            }));
+        },
+    };
+}

package/dist/node_modules/@boombot/core/research/providers/duckduckgo.d.ts

@@ -0,0 +1,9 @@
+/**
+ * DuckDuckGo Instant Answer provider (free, no key).
+ *
+ * Uses the public Instant Answer API (`api.duckduckgo.com`, `format=json`,
+ * `no_html=1`). Returns the abstract plus related topics — best-effort,
+ * general-knowledge search, not a full web index.
+ */
+import type { ResearchProvider } from '../types.js';
+export declare function createDuckDuckGoProvider(): ResearchProvider;

package/dist/node_modules/@boombot/core/research/providers/duckduckgo.js

@@ -0,0 +1,78 @@
+/**
+ * DuckDuckGo Instant Answer provider (free, no key).
+ *
+ * Uses the public Instant Answer API (`api.duckduckgo.com`, `format=json`,
+ * `no_html=1`). Returns the abstract plus related topics — best-effort,
+ * general-knowledge search, not a full web index.
+ */
+import { fetchJson, truncate, withRetry } from '../http.js';
+const MAX_RESULTS = 20;
+function isTopic(t) {
+    return (typeof t === 'object' &&
+        t !== null &&
+        typeof t.Text === 'string' &&
+        typeof t.FirstURL === 'string');
+}
+/** Flatten nested `Topics` groups; entries without a URL are containers, not results. */
+function flattenTopics(raw) {
+    const out = [];
+    for (const item of raw ?? []) {
+        if (item === undefined || item === null)
+            continue;
+        if ('Topics' in item && Array.isArray(item.Topics)) {
+            for (const sub of item.Topics) {
+                if (isTopic(sub) && (sub.FirstURL ?? '') !== '')
+                    out.push(sub);
+            }
+        }
+        else if (isTopic(item) && (item.FirstURL ?? '') !== '') {
+            out.push(item);
+        }
+    }
+    return out;
+}
+export function createDuckDuckGoProvider() {
+    return {
+        id: 'duckduckgo',
+        kind: 'free',
+        async search(query, opts = {}) {
+            const limit = Math.min(Math.max(opts.limit ?? 8, 1), MAX_RESULTS);
+            const params = new URLSearchParams({
+                q: query,
+                format: 'json',
+                no_html: '1',
+                skip_disambig: '1',
+            });
+            const url = `https://api.duckduckgo.com/?${params.toString()}`;
+            const raw = await withRetry(() => fetchJson(url, { signal: opts.signal, timeoutMs: 2_500 }));
+            const body = raw;
+            const results = [];
+            if (body.AbstractText !== undefined && body.AbstractText !== '' &&
+                body.AbstractURL !== undefined && body.AbstractURL !== '') {
+                results.push({
+                    title: body.Heading ?? query,
+                    url: body.AbstractURL,
+                    snippet: truncate(body.AbstractText, 300),
+                    source: 'duckduckgo',
+                });
+            }
+            for (const topic of flattenTopics(body.RelatedTopics)) {
+                if (results.length >= limit)
+                    break;
+                const text = topic.Text ?? '';
+                const topicUrl = topic.FirstURL ?? '';
+                if (text === '' || topicUrl === '')
+                    continue;
+                const dash = text.indexOf('–');
+                const title = (dash > 0 ? text.slice(0, dash) : text.slice(0, 80)).trim();
+                results.push({
+                    title: title === '' ? topicUrl : title,
+                    url: topicUrl,
+                    snippet: truncate(text, 300),
+                    source: 'duckduckgo',
+                });
+            }
+            return results.slice(0, limit);
+        },
+    };
+}

package/dist/node_modules/@boombot/core/research/providers/exa.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Exa search adapter (paid, API key required).
+ *
+ * Wraps the Exa Search API via POST. The key travels in the `x-api-key`
+ * header — never in the URL, never logged.
+ */
+import type { ResearchProvider } from '../types.js';
+export interface ExaProviderOptions {
+    readonly apiKey: string;
+}
+export declare function createExaProvider(options: ExaProviderOptions): ResearchProvider;

package/dist/node_modules/@boombot/core/research/providers/exa.js

@@ -0,0 +1,34 @@
+/**
+ * Exa search adapter (paid, API key required).
+ *
+ * Wraps the Exa Search API via POST. The key travels in the `x-api-key`
+ * header — never in the URL, never logged.
+ */
+import { postJson, truncate, withRetry } from '../http.js';
+const MAX_RESULTS = 20;
+export function createExaProvider(options) {
+    return {
+        id: 'exa',
+        kind: 'paid',
+        async search(query, opts = {}) {
+            const limit = Math.min(Math.max(opts.limit ?? 8, 1), MAX_RESULTS);
+            const raw = await withRetry(() => postJson('https://api.exa.ai/search', {
+                query,
+                numResults: limit,
+                contents: { text: { maxCharacters: 2000 } },
+            }, {
+                signal: opts.signal,
+                timeoutMs: 20_000,
+                headers: { 'x-api-key': options.apiKey },
+            }));
+            const body = raw;
+            return (body.results ?? []).slice(0, limit).map((hit) => ({
+                title: hit.title ?? '',
+                url: hit.url ?? '',
+                snippet: truncate(hit.text ?? '', 300),
+                source: 'exa',
+                publishedAt: hit.publishedDate,
+            }));
+        },
+    };
+}

package/dist/node_modules/@boombot/core/research/providers/firecrawl.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Firecrawl extract adapter (paid, API key required).
+ *
+ * Wraps the Firecrawl Scrape API (`/v1/scrape`) with `markdown` format and
+ * main-content-only extraction. The key travels in the `Authorization:
+ * Bearer` header — never in the URL, never logged.
+ *
+ * Windowing: `opts.offset` re-scrapes the page and serves the slice
+ * `[offset, offset + MAX_CHARS)`; `nextOffset`/`totalLength` let callers
+ * page through long documents (see `research.extract`'s `offset` param).
+ */
+import type { ExtractProvider } from '../types.js';
+export interface FirecrawlProviderOptions {
+    readonly apiKey: string;
+}
+export declare function createFirecrawlProvider(options: FirecrawlProviderOptions): ExtractProvider;

package/dist/node_modules/@boombot/core/research/providers/firecrawl.js

@@ -0,0 +1,47 @@
+/**
+ * Firecrawl extract adapter (paid, API key required).
+ *
+ * Wraps the Firecrawl Scrape API (`/v1/scrape`) with `markdown` format and
+ * main-content-only extraction. The key travels in the `Authorization:
+ * Bearer` header — never in the URL, never logged.
+ *
+ * Windowing: `opts.offset` re-scrapes the page and serves the slice
+ * `[offset, offset + MAX_CHARS)`; `nextOffset`/`totalLength` let callers
+ * page through long documents (see `research.extract`'s `offset` param).
+ */
+import { postJson, TRUNCATED_MARKER, withRetry } from '../http.js';
+const MAX_CHARS = 12_000;
+const TIMEOUT_MS = 45_000;
+export function createFirecrawlProvider(options) {
+    return {
+        id: 'firecrawl',
+        kind: 'paid',
+        async extract(url, signal, opts) {
+            const raw = await withRetry(() => postJson('https://api.firecrawl.dev/v1/scrape', {
+                url,
+                formats: ['markdown'],
+                onlyMainContent: true,
+                maxAge: 3_600_000,
+            }, {
+                signal,
+                timeoutMs: TIMEOUT_MS,
+                headers: { Authorization: `Bearer ${options.apiKey}` },
+            }));
+            const body = raw;
+            const markdown = body.data?.markdown ?? '';
+            const offset = Math.max(0, Math.floor(opts?.offset ?? 0));
+            const slice = markdown.slice(offset, offset + MAX_CHARS);
+            const totalLength = markdown.length;
+            const hasMore = offset + slice.length < totalLength;
+            return {
+                url,
+                title: body.data?.metadata?.title ?? '',
+                markdown: hasMore ? slice + TRUNCATED_MARKER : slice,
+                truncated: hasMore,
+                offset,
+                totalLength,
+                nextOffset: hasMore ? offset + MAX_CHARS : undefined,
+            };
+        },
+    };
+}

package/dist/node_modules/@boombot/core/research/providers/index.d.ts

@@ -0,0 +1,17 @@
+/** Provider factories for `@boombot/core`. */
+export { createWikipediaProvider } from './wikipedia.js';
+export type { WikipediaProviderOptions } from './wikipedia.js';
+export { createDuckDuckGoProvider } from './duckduckgo.js';
+export { createArxivProvider } from './arxiv.js';
+export { createOpenAlexProvider } from './openalex.js';
+export type { OpenAlexProviderOptions } from './openalex.js';
+export { createSemanticScholarProvider } from './semantic-scholar.js';
+export { createJinaProvider } from './jina.js';
+export { createTavilyProvider } from './tavily.js';
+export type { TavilyProviderOptions } from './tavily.js';
+export { createExaProvider } from './exa.js';
+export type { ExaProviderOptions } from './exa.js';
+export { createBraveProvider } from './brave.js';
+export type { BraveProviderOptions } from './brave.js';
+export { createFirecrawlProvider } from './firecrawl.js';
+export type { FirecrawlProviderOptions } from './firecrawl.js';

package/dist/node_modules/@boombot/core/research/providers/index.js

@@ -0,0 +1,11 @@
+/** Provider factories for `@boombot/core`. */
+export { createWikipediaProvider } from './wikipedia.js';
+export { createDuckDuckGoProvider } from './duckduckgo.js';
+export { createArxivProvider } from './arxiv.js';
+export { createOpenAlexProvider } from './openalex.js';
+export { createSemanticScholarProvider } from './semantic-scholar.js';
+export { createJinaProvider } from './jina.js';
+export { createTavilyProvider } from './tavily.js';
+export { createExaProvider } from './exa.js';
+export { createBraveProvider } from './brave.js';
+export { createFirecrawlProvider } from './firecrawl.js';

package/dist/node_modules/@boombot/core/research/providers/jina.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Jina Reader extract provider (free, no key).
+ *
+ * Uses the public Jina AI Reader (`https://r.jina.ai/<url>`) to turn a page
+ * into markdown. Free tier is rate-limited — callers should extract only
+ * the top few URLs.
+ *
+ * Windowing: `opts.offset` re-fetches the page and serves the slice
+ * `[offset, offset + MAX_CHARS)`; `nextOffset`/`totalLength` let callers
+ * page through long documents (see `research.extract`'s `offset` param).
+ */
+import type { ExtractProvider } from '../types.js';
+export declare function createJinaProvider(): ExtractProvider;

package/dist/node_modules/@boombot/core/research/providers/jina.js

@@ -0,0 +1,114 @@
+/**
+ * Jina Reader extract provider (free, no key).
+ *
+ * Uses the public Jina AI Reader (`https://r.jina.ai/<url>`) to turn a page
+ * into markdown. Free tier is rate-limited — callers should extract only
+ * the top few URLs.
+ *
+ * Windowing: `opts.offset` re-fetches the page and serves the slice
+ * `[offset, offset + MAX_CHARS)`; `nextOffset`/`totalLength` let callers
+ * page through long documents (see `research.extract`'s `offset` param).
+ */
+import { fetchText, withRetry, TRUNCATED_MARKER } from '../http.js';
+const MAX_CHARS = 8000;
+/**
+ * Ceiling for one reader fetch. It used to be 30s AND retried, so a slow
+ * page held the turn for up to 60s. The retry is gone (`http.ts` no longer
+ * retries timeouts); this lowers the remaining worst case to one 15s wait.
+ * Extract is asked for by name, so it may cost more than a search engine —
+ * but not a minute.
+ */
+const TIMEOUT_MS = 15_000;
+function guessTitle(markdown) {
+    for (const line of markdown.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('# '))
+            return trimmed.slice(2).trim();
+        if (trimmed.startsWith('Title: '))
+            return trimmed.slice(7).trim();
+    }
+    return '';
+}
+function htmlToMarkdown(html) {
+    let text = html;
+    text = text.replace(/<head\b[^<]*(?:(?!<\/head>)<[^<]*)*<\/head>/gi, '');
+    text = text.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '');
+    text = text.replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, '');
+    text = text.replace(/<svg\b[^<]*(?:(?!<\/svg>)<[^<]*)*<\/svg>/gi, '');
+    text = text.replace(/<noscript\b[^<]*(?:(?!<\/noscript>)<[^<]*)*<\/noscript>/gi, '');
+    text = text.replace(/<h1[^>]*>([\s\S]*?)<\/h1>/gi, '\n# $1\n');
+    text = text.replace(/<h2[^>]*>([\s\S]*?)<\/h2>/gi, '\n## $1\n');
+    text = text.replace(/<h3[^>]*>([\s\S]*?)<\/h3>/gi, '\n### $1\n');
+    text = text.replace(/<h[4-6][^>]*>([\s\S]*?)<\/h[4-6]>/gi, '\n#### $1\n');
+    text = text.replace(/<article[^>]*>([\s\S]*?)<\/article>/gi, '\n\n$1\n\n');
+    text = text.replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, '\n- $1');
+    text = text.replace(/<p[^>]*>([\s\S]*?)<\/p>/gi, '\n\n$1\n\n');
+    text = text.replace(/<br\s*\/?>/gi, '\n');
+    text = text.replace(/<a[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, (_, href, content) => {
+        const clean = content.replace(/<[^>]+>/g, '').trim();
+        return clean ? ` [${clean}](${href}) ` : '';
+    });
+    text = text.replace(/<[^>]+>/g, ' ');
+    text = text
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&nbsp;/g, ' ');
+    return text
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line, i, arr) => line !== '' || (i > 0 && arr[i - 1] !== ''))
+        .join('\n')
+        .trim();
+}
+export function createJinaProvider() {
+    return {
+        id: 'jina',
+        kind: 'free',
+        async extract(url, signal, opts) {
+            let markdown = '';
+            try {
+                const readerUrl = `https://r.jina.ai/${url}`;
+                const raw = await withRetry(() => fetchText(readerUrl, {
+                    signal,
+                    timeoutMs: TIMEOUT_MS,
+                    headers: { 'X-Return-Format': 'markdown' },
+                }));
+                if (raw.trim().startsWith('{') &&
+                    (raw.includes('"code":403') ||
+                        raw.includes('AbuseAlleviationError') ||
+                        raw.includes('"error"'))) {
+                    throw new Error('Jina reader returned abuse alleviation error');
+                }
+                markdown = raw;
+            }
+            catch {
+                // Fall back gracefully to direct fetch with browser user agent
+                const directHtml = await fetchText(url, {
+                    signal,
+                    timeoutMs: TIMEOUT_MS,
+                    headers: {
+                        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36',
+                        Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+                    },
+                });
+                markdown = htmlToMarkdown(directHtml);
+            }
+            const offset = Math.max(0, Math.floor(opts?.offset ?? 0));
+            const slice = markdown.slice(offset, offset + MAX_CHARS);
+            const totalLength = markdown.length;
+            const hasMore = offset + slice.length < totalLength;
+            return {
+                url,
+                title: guessTitle(slice),
+                markdown: hasMore ? slice + TRUNCATED_MARKER : slice,
+                truncated: hasMore,
+                offset,
+                totalLength,
+                nextOffset: hasMore ? offset + MAX_CHARS : undefined,
+            };
+        },
+    };
+}

package/dist/node_modules/@boombot/core/research/providers/openalex.d.ts

@@ -0,0 +1,14 @@
+/**
+ * OpenAlex search provider (free, no key).
+ *
+ * Queries the OpenAlex works index for scholarly metadata. The abstract
+ * comes back as an inverted index (`abstract_inverted_index`), which is
+ * reconstructed into readable text; snippets are capped at the first 40
+ * words. A `mailto` contact improves rate limits and is polite API use.
+ */
+import type { ResearchProvider } from '../types.js';
+export interface OpenAlexProviderOptions {
+    /** Contact email sent as `mailto` (polite API use, better rate limits). */
+    readonly mailto?: string;
+}
+export declare function createOpenAlexProvider(options?: OpenAlexProviderOptions): ResearchProvider;

package/dist/node_modules/@boombot/core/research/providers/openalex.js

@@ -0,0 +1,66 @@
+/**
+ * OpenAlex search provider (free, no key).
+ *
+ * Queries the OpenAlex works index for scholarly metadata. The abstract
+ * comes back as an inverted index (`abstract_inverted_index`), which is
+ * reconstructed into readable text; snippets are capped at the first 40
+ * words. A `mailto` contact improves rate limits and is polite API use.
+ */
+import { fetchJson, truncate, withRetry } from '../http.js';
+const MAX_RESULTS = 20;
+const CONTACT_EMAIL = 'research@boombot.example';
+function reconstructAbstract(inverted) {
+    if (inverted === undefined)
+        return '';
+    const words = [];
+    for (const [word, positions] of Object.entries(inverted)) {
+        for (const pos of positions)
+            words[pos] = word;
+    }
+    return words
+        .filter((w) => w !== undefined)
+        .slice(0, 40)
+        .join(' ');
+}
+function workUrl(work) {
+    if (work.doi !== undefined && work.doi !== '') {
+        const doi = work.doi.startsWith('https://') ? work.doi : `https://doi.org/${work.doi}`;
+        return doi;
+    }
+    return work.id;
+}
+export function createOpenAlexProvider(options = {}) {
+    const mailto = options.mailto ?? CONTACT_EMAIL;
+    return {
+        id: 'openalex',
+        kind: 'free',
+        async search(query, opts = {}) {
+            const limit = Math.min(Math.max(opts.limit ?? 8, 1), MAX_RESULTS);
+            const params = new URLSearchParams({
+                search: query,
+                'per-page': String(limit),
+                select: 'id,title,doi,abstract_inverted_index,from_publication_date',
+                mailto,
+            });
+            const url = `https://api.openalex.org/works?${params.toString()}`;
+            const raw = await withRetry(() => fetchJson(url, { signal: opts.signal, timeoutMs: 15_000 }));
+            const body = raw;
+            const results = [];
+            for (const work of body.results ?? []) {
+                const url_ = workUrl(work);
+                if (url_ === undefined || work.title === undefined)
+                    continue;
+                results.push({
+                    title: work.title,
+                    url: url_,
+                    snippet: truncate(reconstructAbstract(work.abstract_inverted_index), 300),
+                    source: 'openalex',
+                    publishedAt: work.from_publication_date,
+                });
+                if (results.length >= limit)
+                    break;
+            }
+            return results;
+        },
+    };
+}

package/dist/node_modules/@boombot/core/research/providers/semantic-scholar.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Semantic Scholar search provider (free, no key).
+ *
+ * Uses the Graph API paper search endpoint. A polite User-Agent is sent;
+ * the API is rate-limited for unauthenticated callers, so snippets are
+ * fetched in a single request and results are capped.
+ */
+import type { ResearchProvider } from '../types.js';
+export declare function createSemanticScholarProvider(): ResearchProvider;

package/dist/node_modules/@boombot/core/research/providers/semantic-scholar.js

@@ -0,0 +1,56 @@
+/**
+ * Semantic Scholar search provider (free, no key).
+ *
+ * Uses the Graph API paper search endpoint. A polite User-Agent is sent;
+ * the API is rate-limited for unauthenticated callers, so snippets are
+ * fetched in a single request and results are capped.
+ */
+import { fetchJson, truncate, withRetry } from '../http.js';
+const MAX_RESULTS = 20;
+function paperUrl(paper) {
+    if (paper.url !== undefined && paper.url !== null && paper.url !== '') {
+        return paper.url;
+    }
+    const pdf = paper.openAccessPdf?.url;
+    if (pdf !== undefined && pdf !== '')
+        return pdf;
+    const doi = paper.externalIds?.DOI;
+    if (doi !== undefined && doi !== '')
+        return `https://doi.org/${doi}`;
+    return undefined;
+}
+export function createSemanticScholarProvider() {
+    return {
+        id: 'semanticScholar',
+        kind: 'free',
+        async search(query, opts = {}) {
+            const limit = Math.min(Math.max(opts.limit ?? 8, 1), MAX_RESULTS);
+            const params = new URLSearchParams({
+                query,
+                limit: String(limit),
+                fields: 'title,abstract,url,year,openAccessPdf,externalIds',
+            });
+            const url = `https://api.semanticscholar.org/graph/v1/paper/search?${params.toString()}`;
+            const raw = await withRetry(() => fetchJson(url, { signal: opts.signal, timeoutMs: 15_000 }));
+            const body = raw;
+            const results = [];
+            for (const paper of body.data ?? []) {
+                const paperUrl_ = paperUrl(paper);
+                if (paperUrl_ === undefined || paper.title === undefined)
+                    continue;
+                results.push({
+                    title: paper.title,
+                    url: paperUrl_,
+                    snippet: truncate(paper.abstract ?? '', 300),
+                    source: 'semanticScholar',
+                    publishedAt: paper.year !== null && paper.year !== undefined
+                        ? `${paper.year}-01-01`
+                        : undefined,
+                });
+                if (results.length >= limit)
+                    break;
+            }
+            return results;
+        },
+    };
+}

package/dist/node_modules/@boombot/core/research/providers/tavily.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tavily search adapter (paid, API key required).
+ *
+ * Wraps the Tavily Search API via POST. The key travels in the
+ * `Authorization: Bearer` header — never in the URL, never logged.
+ */
+import type { ResearchProvider } from '../types.js';
+export interface TavilyProviderOptions {
+    readonly apiKey: string;
+}
+export declare function createTavilyProvider(options: TavilyProviderOptions): ResearchProvider;

package/dist/node_modules/@boombot/core/research/providers/tavily.js

@@ -0,0 +1,35 @@
+/**
+ * Tavily search adapter (paid, API key required).
+ *
+ * Wraps the Tavily Search API via POST. The key travels in the
+ * `Authorization: Bearer` header — never in the URL, never logged.
+ */
+import { postJson, truncate, withRetry } from '../http.js';
+const MAX_RESULTS = 20;
+export function createTavilyProvider(options) {
+    return {
+        id: 'tavily',
+        kind: 'paid',
+        async search(query, opts = {}) {
+            const limit = Math.min(Math.max(opts.limit ?? 8, 1), MAX_RESULTS);
+            const raw = await withRetry(() => postJson('https://api.tavily.com/search', {
+                query,
+                max_results: limit,
+                include_answer: false,
+                search_depth: 'advanced',
+            }, {
+                signal: opts.signal,
+                timeoutMs: 20_000,
+                headers: { Authorization: `Bearer ${options.apiKey}` },
+            }));
+            const body = raw;
+            return (body.results ?? []).slice(0, limit).map((hit) => ({
+                title: hit.title ?? '',
+                url: hit.url ?? '',
+                snippet: truncate(hit.content ?? '', 300),
+                source: 'tavily',
+                publishedAt: hit.published_date,
+            }));
+        },
+    };
+}

package/dist/node_modules/@boombot/core/research/providers/wikipedia.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Wikipedia search provider (free, no key).
+ *
+ * Uses the MediaWiki `action=query&list=search` API. Result URLs are built
+ * from page ids (`https://<lang>.wikipedia.org/?curid=<pageid>`).
+ */
+import type { ResearchProvider } from '../types.js';
+export interface WikipediaProviderOptions {
+    /** Wikipedia language subdomain. Default `'en'`. */
+    readonly lang?: string;
+}
+export declare function createWikipediaProvider(options?: WikipediaProviderOptions): ResearchProvider;

package/dist/node_modules/@boombot/core/research/providers/wikipedia.js

@@ -0,0 +1,47 @@
+/**
+ * Wikipedia search provider (free, no key).
+ *
+ * Uses the MediaWiki `action=query&list=search` API. Result URLs are built
+ * from page ids (`https://<lang>.wikipedia.org/?curid=<pageid>`).
+ */
+import { fetchJson, truncate, withRetry } from '../http.js';
+const DEFAULT_LANG = 'en';
+const MAX_RESULTS = 20;
+function stripTags(html) {
+    return html
+        .replace(/<[^>]*>/g, '')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .trim();
+}
+export function createWikipediaProvider(options = {}) {
+    const lang = options.lang ?? DEFAULT_LANG;
+    return {
+        id: 'wikipedia',
+        kind: 'free',
+        async search(query, opts = {}) {
+            const limit = Math.min(Math.max(opts.limit ?? 8, 1), MAX_RESULTS);
+            const params = new URLSearchParams({
+                action: 'query',
+                list: 'search',
+                srsearch: query,
+                srlimit: String(limit),
+                format: 'json',
+                srprop: 'snippet',
+            });
+            const url = `https://${lang}.wikipedia.org/w/api.php?${params.toString()}`;
+            const raw = await withRetry(() => fetchJson(url, { signal: opts.signal, timeoutMs: 2_500 }));
+            const body = raw;
+            const hits = body.query?.search ?? [];
+            return hits.slice(0, limit).map((hit) => ({
+                title: hit.title ?? '',
+                url: `https://${lang}.wikipedia.org/?curid=${hit.pageid ?? 0}`,
+                snippet: truncate(stripTags(hit.snippet ?? ''), 300),
+                source: 'wikipedia',
+            }));
+        },
+    };
+}