@autorag/librarian 2.5.1 → 2.5.3

package/dist/web/fetch/url-target.d.ts

@@ -0,0 +1,29 @@
+/**
+ * URL normalization, MIME classification, and binary detection — ported from
+ * oh-my-pi's `packages/coding-agent/src/tools/fetch.ts` (MIT licensed).
+ */
+/**
+ * Normalize a URL: repair a collapsed scheme, then add `https://` if missing.
+ */
+export declare function normalizeUrl(url: string): string;
+/**
+ * Normalize a MIME type (lowercase, strip charset/params).
+ */
+export declare function normalizeMime(contentType: string): string;
+export declare function getFilenameExtensionHint(filename: string): string;
+/**
+ * Get extension from URL or Content-Disposition.
+ */
+export declare function getExtensionHint(url: string, contentDisposition?: string): string;
+/**
+ * Check if content type is convertible via AutoRAG's parser registry.
+ */
+export declare function isConvertible(mime: string, extensionHint: string): boolean;
+/**
+ * Heuristic: does the text sample look like binary (NUL bytes or high U+FFFD density)?
+ */
+export declare function sampleLooksBinary(text: string): boolean;
+/**
+ * Build a textual binary notice for unsupported binary payloads.
+ */
+export declare function buildBinaryNotice(finalUrl: string, mime: string, byteLength?: number): string;

package/dist/web/search/browser-headers.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Browser-like navigation headers for credential-free search engines.
+ *
+ * Ported from oh-my-pi (can1357/oh-my-pi, MIT)
+ * `web/search/providers/browser-headers.ts`. oh-my-pi randomizes across a
+ * header-generator fingerprint pool; AutoRAG pins the deterministic Mac
+ * Chrome fallback profile (the same one oh-my-pi uses for non-randomized
+ * calls) so tests and diagnostics stay reproducible.
+ */
+/**
+ * Build a desktop navigation fingerprint for one HTTP request.
+ * `randomized` is accepted for oh-my-pi call-site compatibility; the
+ * deterministic profile is always returned.
+ */
+export declare function buildBrowserNavigationHeaders(_options?: {
+    randomized?: boolean;
+}): Record<string, string>;

package/dist/web/search/browser-loader.d.ts

@@ -0,0 +1,56 @@
+import type { BrowserFallbackOptions, LoadedHtmlPage, WebSearchBrowserLoader } from "./browser-page.js";
+/** Minimal page surface the loader needs (structural subset of puppeteer-core's Page). */
+export interface WebSearchBrowserPage {
+    goto(url: string, options?: {
+        waitUntil?: string;
+        timeout?: number;
+    }): Promise<{
+        status(): number;
+    } | null>;
+    content(): Promise<string>;
+    url(): string;
+    close(): Promise<void>;
+    setViewport(viewport: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    evaluateOnNewDocument(fn: () => void): Promise<void>;
+    waitForSelector(selector: string, options?: {
+        timeout?: number;
+    }): Promise<unknown>;
+}
+/** Minimal browser surface the loader needs (structural over puppeteer-core's Browser). */
+export interface WebSearchBrowser {
+    newPage(): Promise<WebSearchBrowserPage>;
+    close(): Promise<void>;
+}
+/** Launch seam: production uses puppeteer-core with the detected executable; tests inject a fake. */
+export type WebSearchBrowserLaunch = (executablePath: string) => Promise<WebSearchBrowser>;
+export interface EnsureWebSearchBrowserLoaderOptions {
+    /** Executable existence probe (default: fs.existsSync). */
+    readonly exists?: (path: string) => boolean;
+    /** Candidate executable paths (default: env + platform defaults). */
+    readonly candidates?: readonly string[];
+    /** Browser launcher (default: lazy puppeteer-core). */
+    readonly launch?: WebSearchBrowserLaunch;
+}
+/** Install (or clear, with `undefined`) an explicit headless-browser loader, taking precedence over the default. */
+export declare function setWebSearchBrowserLoader(loader: WebSearchBrowserLoader | undefined): void;
+/** The recorded browser-escalation diagnostic (why no default loader is installed), if any. */
+export declare function getWebSearchBrowserDiagnostic(): string | undefined;
+/** Test hook: drop the explicit loader, the memoized default, and the diagnostic. */
+export declare function resetWebSearchBrowserLoaderForTests(): void;
+/**
+ * Probe for a local Chrome/Chromium and install the default escalation
+ * loader. Returns true when a loader is installed. Never throws: when no
+ * browser exists (or puppeteer-core cannot load), a diagnostic is recorded
+ * and the provider chain simply never escalates. Memoized per process.
+ */
+export declare function ensureWebSearchBrowserLoader(options?: EnsureWebSearchBrowserLoaderOptions): Promise<boolean>;
+/**
+ * Resolve the loader an escalation should use: an explicitly registered
+ * loader wins; otherwise the lazily-probed default. Returns undefined when
+ * no browser is available (degradation already recorded as a diagnostic).
+ */
+export declare function resolveWebSearchBrowserLoader(): Promise<WebSearchBrowserLoader | undefined>;
+export type { BrowserFallbackOptions, LoadedHtmlPage, WebSearchBrowserLoader };

package/dist/web/search/browser-page.d.ts

@@ -0,0 +1,41 @@
+import { setWebSearchBrowserLoader } from "./browser-loader.js";
+import type { FetchImpl } from "./providers/base.js";
+export { setWebSearchBrowserLoader };
+/** HTML plus the response status and final URL after redirects or browser navigation. */
+export interface LoadedHtmlPage {
+    html: string;
+    status: number;
+    url: string;
+}
+export interface BrowserFallbackOptions {
+    homeUrl?: string;
+    ready?: {
+        selector: string;
+        timeoutMs: number;
+    };
+    afterNavigation?: (page: unknown, signal: AbortSignal) => Promise<void>;
+    shouldFallback: (page: LoadedHtmlPage) => boolean;
+    attempts?: number;
+    retryDelayMs?: number;
+}
+/** Controls a browser-profiled fetch and its optional headless-browser fallback. */
+export interface BrowserFetchOptions {
+    fetch?: FetchImpl;
+    signal: AbortSignal;
+    timeoutMs?: number;
+    randomizeHeaders?: boolean;
+    referer?: string;
+    init?: Omit<RequestInit, "headers" | "signal">;
+    headers?: Readonly<Record<string, string>>;
+    browser?: BrowserFallbackOptions;
+}
+/**
+ * Headless-browser loader. Receives the target URL and the provider's
+ * fallback options and must return the loaded page. The registry lives in
+ * `browser-loader.ts`, which ships a default puppeteer-core loader probed
+ * from the local Chrome/Chromium install; an explicit registration always
+ * takes precedence over the default.
+ */
+export type WebSearchBrowserLoader = (url: string, options: BrowserFallbackOptions, signal: AbortSignal, timeoutMs: number) => Promise<LoadedHtmlPage>;
+/** Fetch with a fresh browser profile, escalating rejected production responses to the installed headless browser. */
+export declare function browserFetch(url: string, options: BrowserFetchOptions): Promise<LoadedHtmlPage>;

package/dist/web/search/credentials.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Environment-variable credential resolution for web search providers.
+ *
+ * Replaces oh-my-pi's AuthStorage/SQLite credential broker: AutoRAG keeps
+ * secrets external (environment only — never written to config files, logs,
+ * or diagnostics), so a provider is "available" exactly when its documented
+ * env var holds a non-empty value.
+ */
+/** Return the first non-empty environment value among `names`, or undefined. */
+export declare function envCredential(...names: string[]): string | undefined;

package/dist/web/search/format.d.ts

@@ -0,0 +1,30 @@
+/**
+ * LLM-facing formatting for web search responses.
+ *
+ * Ported from oh-my-pi (can1357/oh-my-pi, MIT) `web/search/index.ts`
+ * (formatForLLM) and its prompts/tools + prompts/system web-search markdown.
+ */
+import type { SearchResponse } from "./types.js";
+/**
+ * System prompt passed to LLM-mediated providers. Kept for forward
+ * compatibility — every provider AutoRAG ships today returns sources
+ * directly, but the SearchParams contract carries it.
+ */
+export declare const WEB_SEARCH_SYSTEM_PROMPT = "Web research assistant: accurate, well-sourced, comprehensive answers.\n\n<priorities>\n1. Accuracy > speed; verify claims across multiple sources when possible.\n2. Primary > secondary: official docs, papers, announcements > blog summaries.\n3. Recency matters: note publication dates; prefer recent sources for time-sensitive topics.\n4. Uncertainty: distinguish confirmed facts from inferences.\n</priorities>\n\n<synthesis>\n- Direct answer first; then supporting evidence.\n- Quote or paraphrase specific sources; no vague attributions.\n- Source conflicts: acknowledge discrepancy; identify the more authoritative source.\n- Technical topics: prefer official documentation and specifications.\n- News/events: prefer primary reporting over aggregators.\n- Concrete data: version numbers, dates, exact figures, code snippets, specific examples.\n</synthesis>\n\n<format>\n- Thorough, in-depth coverage with specific evidence; no surface-level summaries.\n- Omit filler and unnecessary hedging; do NOT sacrifice detail for brevity.\n- Include publication dates when recency affects relevance.\n- Clear sections for multiple aspects.\n- Cite sources inline using provided search results.\n</format>";
+/**
+ * Tool description shared by the `web_search` agent tool and CLI surfaces.
+ * Ported from oh-my-pi prompts/tools/web-search.md.
+ */
+export declare const WEB_SEARCH_TOOL_DESCRIPTION = "Web search: current information beyond knowledge cutoff.\n\n- SHOULD prefer primary sources (papers, official docs); corroborate key claims with multiple sources.\n- MUST link cited sources in final response.\n- NEVER use for programmatically accessible content or known URLs (GitHub repos/issues, known arXiv papers, Wikipedia pages, official docs) \u2014 use web_fetch on the URL directly.\n- `query`: every provider supports Google-style `site:`/`-site:`, `after:`/`before:` (YYYY-MM-DD), `inurl:`, `intitle:`, `filetype:`, `\"exact phrase\"`, `-term`, `OR`. Map constraints to native filters when available; otherwise results are filtered leniently. If a constraint matches nothing, it is relaxed and reported; zero results are never forced.";
+/** Format an age in seconds as a compact relative string ("45s", "2h", "3d"). */
+export declare function formatAge(ageSeconds: number | undefined): string;
+/** Format response for LLM consumption. `notes` lead the output (e.g. relaxed-constraint warnings). */
+export declare function formatForLLM(response: SearchResponse, notes?: readonly string[]): string;
+/**
+ * `true` when the response carries an actual result the caller can read: an
+ * answer, a source, or a citation. Search-attempt metadata (`searchQueries`,
+ * `relatedQuestions`) is an annotation on a real result, never a result — a
+ * provider that only reports "I ran a search" must not win the chain while a
+ * healthy fallback would have returned sources.
+ */
+export declare function hasRenderableSearchContent(response: SearchResponse): boolean;

package/dist/web/search/index.d.ts

@@ -0,0 +1,46 @@
+import type { ModelNativeSearchAuth } from "./model-auth.js";
+import { type SearchProviderId, type SearchResponse } from "./types.js";
+export interface WebSearchQueryParams {
+    query: string;
+    recency?: "day" | "week" | "month" | "year";
+    limit?: number;
+    max_tokens?: number;
+    temperature?: number;
+    num_search_results?: number;
+    provider?: SearchProviderId | "auto";
+}
+export interface WebSearchResultDetails {
+    response: SearchResponse;
+    error?: string;
+}
+export interface WebSearchExecuteResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: WebSearchResultDetails;
+}
+export interface WebSearchExecuteOptions {
+    signal?: AbortSignal;
+    /** Per-provider transport hard timeout in milliseconds (default 60s, capped at 300s). */
+    timeoutMs?: number;
+    /**
+     * Budget for the whole fallback chain in milliseconds (default: twice the
+     * per-provider timeout). Without it a chain of stalled providers costs one
+     * per-provider timeout each and the tool call looks hung.
+     */
+    totalTimeoutMs?: number;
+    /** Prioritized providers for this request; unlisted providers keep their built-in order. */
+    order?: readonly SearchProviderId[];
+    /** Providers this request must never use, including fallbacks. */
+    exclude?: readonly SearchProviderId[];
+    /** Agent model credential for the model-native providers (per request, never global). */
+    modelAuth?: ModelNativeSearchAuth;
+    /** Transport injection for tests/proxies; forwarded to providers that accept it. */
+    fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+}
+/** Execute a web search through the provider fallback chain. */
+export declare function executeWebSearch(params: WebSearchQueryParams, options?: WebSearchExecuteOptions): Promise<WebSearchExecuteResult>;
+export { getSearchProvider, type SearchProviderRouting } from "./provider.js";
+export type { SearchProviderId, SearchResponse } from "./types.js";
+export { isSearchProviderId, isSearchProviderPreference } from "./types.js";

package/dist/web/search/model-auth.d.ts

@@ -0,0 +1,36 @@
+/** Agent model credential injected for model-native web search. */
+export interface ModelNativeSearchAuth {
+    /** pi model provider id, e.g. "anthropic" | "openai" | "google" | "xai". */
+    readonly provider: string;
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+    readonly modelId?: string;
+}
+/** Credential view consumed by the model-native search providers. */
+export interface ModelNativeCredential {
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+    readonly modelId?: string;
+    readonly source: "injected" | "env";
+}
+/** Model-native search provider ids as they appear in the chain. */
+export type ModelNativeSearchProviderId = "gemini" | "anthropic" | "codex" | "xai";
+/**
+ * Resolve the credential a model-native search provider should use for this
+ * request: the caller's agent credential when its provider family matches,
+ * else the provider's conventional model environment key. The credential is
+ * never stored in module state — it travels with the request so two agents
+ * in one process cannot overwrite each other's key or base URL.
+ */
+export declare function resolveModelNativeCredential(searchProvider: ModelNativeSearchProviderId, auth?: ModelNativeSearchAuth): ModelNativeCredential | undefined;
+/**
+ * Map a resolved agent model (provider + apiKey) onto the injectable auth
+ * shape. Returns undefined for providers with no model-native search route
+ * (e.g. openrouter, local gateways) or when no apiKey was resolved.
+ */
+export declare function modelNativeAuthFromAgentModel(resolved: {
+    readonly provider: string;
+    readonly apiKey?: string;
+    readonly baseUrl?: string;
+    readonly modelId?: string;
+}): ModelNativeSearchAuth | undefined;

package/dist/web/search/provider.d.ts

@@ -0,0 +1,62 @@
+import type { SearchAvailabilityContext, SearchProvider, SearchProviderContract } from "./providers/base.js";
+import { type SearchProviderId } from "./types.js";
+export type { FetchImpl, SearchAvailabilityContext, SearchParams, SearchProviderContract, } from "./providers/base.js";
+export { SearchProvider } from "./providers/base.js";
+export { SEARCH_PROVIDER_ORDER } from "./types.js";
+/** Cheap, sync metadata accessor — never triggers a provider load. */
+export declare function getSearchProviderLabel(id: SearchProviderId): string;
+/** Format one provider failure for the user-facing fallback summary. */
+export declare function formatSearchProviderFailure(error: unknown, provider: Pick<SearchProvider, "id" | "label">): string;
+/** Format the ordered provider fallback failures for terminal/tool output. */
+export declare function formatSearchProviderFailures(failures: readonly {
+    provider: Pick<SearchProvider, "id" | "label">;
+    error: unknown;
+}[]): string;
+/**
+ * Resolve and cache a provider instance. First call for a given id loads the
+ * underlying module; subsequent calls return the cached singleton.
+ * Instances registered through {@link registerSearchProvider} take
+ * precedence over lazy module loads (host embedding, tests).
+ */
+export declare function getSearchProvider(id: SearchProviderId): Promise<SearchProviderContract>;
+/**
+ * Register (or replace) a provider instance, bypassing the lazy module load.
+ * Test seam and host-embedding hook; production provider modules register
+ * nothing themselves.
+ */
+export declare function registerSearchProvider(provider: SearchProviderContract): void;
+/** Drop every registered/cached provider instance (tests). */
+export declare function clearRegisteredSearchProviders(): void;
+/**
+ * Per-request routing. Configuration never mutates module state: the caller
+ * (agent tool, CLI) owns its own routing and passes it down, so two agents
+ * in one process cannot rewrite each other's provider order or exclusions.
+ */
+export interface SearchProviderRouting {
+    /** Prioritized providers; unlisted providers keep their built-in relative order. */
+    readonly order?: readonly SearchProviderId[];
+    /** Providers this request must never use, including fallbacks. */
+    readonly exclude?: readonly SearchProviderId[];
+    /** Terminal-first provider that bypasses exclusion (an explicit `provider` argument). */
+    readonly forcedProvider?: SearchProviderId;
+}
+/** `true` when `routing` excludes `id` from web search (auto chain and the Public Web fan-out). */
+export declare function isSearchProviderExcluded(id: SearchProviderId, exclude?: readonly SearchProviderId[]): boolean;
+export interface SearchProviderCandidate {
+    id: SearchProviderId;
+    explicit: boolean;
+}
+/**
+ * Return provider candidates in fallback order without loading their modules.
+ * `routing.forcedProvider` is terminal-first and bypasses exclusion; providers
+ * the caller listed in `routing.order` are treated as explicit selections and
+ * resolve through `isExplicitlyAvailable`. Invalid ids are ignored defensively.
+ */
+export declare function resolveProviderCandidates(routing?: SearchProviderRouting): SearchProviderCandidate[];
+/**
+ * Resolve the complete available provider chain.
+ *
+ * This compatibility helper loads every candidate. Search execution should use
+ * {@link resolveProviderCandidates} so fallback modules load only when reached.
+ */
+export declare function resolveProviderChain(routing?: SearchProviderRouting, context?: SearchAvailabilityContext): Promise<SearchProviderContract[]>;

package/dist/web/search/providers/anthropic.d.ts

@@ -0,0 +1,9 @@
+import { type SearchResponse } from "../types.js";
+import type { SearchAvailabilityContext, SearchParams } from "./base.js";
+import { SearchProvider } from "./base.js";
+export declare class AnthropicProvider extends SearchProvider {
+    readonly id: "anthropic";
+    readonly label = "Anthropic";
+    isAvailable(context?: SearchAvailabilityContext): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/web/search/providers/base.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared web search provider contract.
+ *
+ * Ported from oh-my-pi (can1357/oh-my-pi, MIT) `web/search/providers/base.ts`
+ * with one adaptation: oh-my-pi resolves credentials through its AuthStorage
+ * broker; AutoRAG providers read their documented environment variables
+ * directly (see `../credentials.ts`), so `isAvailable` takes no arguments.
+ */
+import type { ModelNativeSearchAuth } from "../model-auth.js";
+import type { StructuredQuery } from "../query.js";
+import type { SearchProviderId, SearchResponse } from "../types.js";
+/** Minimal fetch signature providers accept for transport injection (tests, proxies). */
+export type FetchImpl = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/**
+ * Shared web search parameters passed to providers.
+ */
+export interface SearchParams {
+    query: string;
+    /**
+     * Structured view of `query`, parsed once by the search pipeline:
+     * Google-style directives (`site:`, `before:`/`after:`, `inurl:`,
+     * `intitle:`, `filetype:`, quoted phrases, `OR` groups, `-exclusions`)
+     * extracted into fields.
+     *
+     * Providers SHOULD map constraints onto native API parameters
+     * (domain/date filters) or engine query syntax (`formatQuery`) where the
+     * upstream supports them, and lean lenient otherwise: the pipeline
+     * post-filters every response with `applyQueryConstraints`, which
+     * relaxes any constraint that would eliminate all results — so a
+     * best-effort search always beats an empty one. When absent (direct
+     * provider calls), parse with `parseSearchQuery(params.query)`.
+     */
+    parsedQuery?: StructuredQuery;
+    limit?: number;
+    /**
+     * Temporal filter narrowing results to the specified time window.
+     *
+     * Providers MUST interpret this as a pure time filter. Providers MUST NOT
+     * use recency as an implicit signal to change topic scope, content domain,
+     * or ranking strategy. Providers that do not support temporal filtering
+     * MUST ignore this field silently; they MUST NOT approximate it by
+     * rewriting the query or altering any other request parameter.
+     */
+    recency?: "day" | "week" | "month" | "year";
+    systemPrompt?: string;
+    signal?: AbortSignal;
+    /** Hard timeout for this provider's search transport, in milliseconds. */
+    timeoutMs?: number;
+    fetch?: FetchImpl;
+    maxOutputTokens?: number;
+    numSearchResults?: number;
+    temperature?: number;
+    /**
+     * Agent model credential for the model-native providers, carried per
+     * request so concurrent agents never share one process-wide key.
+     */
+    modelAuth?: ModelNativeSearchAuth;
+    /** Providers this request must not use, including inside the `public` fan-out. */
+    excludedProviders?: readonly SearchProviderId[];
+}
+/** Per-request context consulted by provider availability checks. */
+export interface SearchAvailabilityContext {
+    readonly modelAuth?: ModelNativeSearchAuth;
+}
+/**
+ * Structural provider contract accepted by the registry. Production
+ * providers extend {@link SearchProvider} (which supplies the
+ * `isExplicitlyAvailable` default); test fakes and host embeddings may be
+ * plain objects matching this shape.
+ */
+export interface SearchProviderContract {
+    readonly id: SearchProviderId;
+    readonly label: string;
+    isAvailable(context?: SearchAvailabilityContext): Promise<boolean> | boolean;
+    isExplicitlyAvailable?(context?: SearchAvailabilityContext): Promise<boolean> | boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}
+/** Base class for web search providers. */
+export declare abstract class SearchProvider implements SearchProviderContract {
+    abstract readonly id: SearchProviderId;
+    abstract readonly label: string;
+    /**
+     * Indicates whether this provider has the credentials/config it needs to
+     * service a request right now. AutoRAG providers consult their documented
+     * environment variables; credential-free providers always return true.
+     *
+     * Drives auto-chain admission: providers that return `false` are skipped
+     * when the chain walks the order. Explicit selection uses
+     * {@link isExplicitlyAvailable} instead.
+     */
+    abstract isAvailable(context?: SearchAvailabilityContext): Promise<boolean> | boolean;
+    /**
+     * Returns `true` when this provider should run when the user explicitly
+     * selects it, even if {@link isAvailable} would reject it for the auto
+     * chain. Providers that ship an unauthenticated fallback override this so
+     * explicit selection still routes through the fallback rather than
+     * silently falling back to another provider.
+     *
+     * Defaults to mirroring {@link isAvailable}.
+     */
+    isExplicitlyAvailable(context?: SearchAvailabilityContext): Promise<boolean> | boolean;
+    /**
+     * Execute a search.
+     */
+    abstract search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/web/search/providers/codex.d.ts

@@ -0,0 +1,9 @@
+import type { SearchResponse } from "../types.js";
+import type { SearchAvailabilityContext, SearchParams } from "./base.js";
+import { SearchProvider } from "./base.js";
+export declare class CodexProvider extends SearchProvider {
+    readonly id: "codex";
+    readonly label = "OpenAI";
+    isAvailable(context?: SearchAvailabilityContext): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/web/search/providers/duckduckgo.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DuckDuckGo's no-JS HTML search frontend. POST `q=…` to receive a static
+ * results page we can parse without a real browser. The Instant Answer API
+ * (`api.duckduckgo.com`) was tried first but it only returns content for
+ * Wikipedia/Wolfram-Alpha-style topics — empty for the vast majority of
+ * agent queries (see #3799).
+ *
+ * Ported from oh-my-pi (can1357/oh-my-pi, MIT)
+ * `packages/coding-agent/src/web/search/providers/duckduckgo.ts`.
+ */
+import type { SearchProviderId, SearchResponse } from "../types.js";
+import type { SearchParams } from "./base.js";
+import { SearchProvider } from "./base.js";
+export declare function localeToKl(lang: string | undefined): string | undefined;
+export declare function searchDuckDuckGo(params: SearchParams): Promise<SearchResponse>;
+export declare class DuckDuckGoProvider extends SearchProvider {
+    readonly id: SearchProviderId;
+    readonly label = "DuckDuckGo";
+    isAvailable(): boolean;
+    isExplicitlyAvailable(): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/web/search/providers/ecosia.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Ecosia serves a server-rendered Vue/Nuxt results page (no `__NUXT_DATA__`
+ * JSON island — probed 2026-07), so both load paths parse the same markup:
+ * `<article data-test-id="organic-result">` blocks whose title anchor carries
+ * the final target URL directly (no redirect wrapper). The site fronts search
+ * with Cloudflare. Requests start with a browser-profiled fetch and escalate
+ * to the shared stealth browser only when the response is blocked or fails.
+ *
+ * Recency is ignored: Ecosia's web results expose no date filter in the UI
+ * and the legacy Bing-era `freshness` param is a server-side no-op (verified
+ * live), so per the {@link SearchParams.recency} contract the field must not
+ * be approximated.
+ *
+ * Ported from oh-my-pi (can1357/oh-my-pi, MIT)
+ * `packages/coding-agent/src/web/search/providers/ecosia.ts`.
+ */
+import type { SearchProviderId, SearchResponse } from "../types.js";
+import type { SearchParams } from "./base.js";
+import { SearchProvider } from "./base.js";
+/** Execute an Ecosia web search and parse the server-rendered result page. */
+export declare function searchEcosia(params: SearchParams): Promise<SearchResponse>;
+/** Search provider for Ecosia (no API key required). */
+export declare class EcosiaProvider extends SearchProvider {
+    readonly id: SearchProviderId;
+    readonly label = "Ecosia";
+    isAvailable(): boolean;
+    isExplicitlyAvailable(): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/web/search/providers/gemini.d.ts

@@ -0,0 +1,9 @@
+import { type SearchResponse } from "../types.js";
+import type { SearchAvailabilityContext, SearchParams } from "./base.js";
+import { SearchProvider } from "./base.js";
+export declare class GeminiProvider extends SearchProvider {
+    readonly id: "gemini";
+    readonly label = "Gemini";
+    isAvailable(context?: SearchAvailabilityContext): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/web/search/providers/google.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Google's server-rendered search results page (the `udm=14` "Web" tab
+ * variant), scraped via browser-profiled fetch with a headless-browser
+ * fallback. Google blocks automated requests aggressively, so the provider
+ * detects traffic challenges and JavaScript challenges and surfaces them as
+ * provider-tagged 429s so the chain advances to the next engine.
+ *
+ * Ported from oh-my-pi (can1357/oh-my-pi, MIT)
+ * `packages/coding-agent/src/web/search/providers/google.ts`.
+ */
+import type { SearchProviderId, SearchResponse } from "../types.js";
+import type { SearchParams } from "./base.js";
+import { SearchProvider } from "./base.js";
+/** Execute a Google web search with fetch-first loading and a headless-browser fallback. */
+export declare function searchGoogle(params: SearchParams): Promise<SearchResponse>;
+/** Fetch-first Google Search provider with a headless-browser fallback; no API key is required. */
+export declare class GoogleProvider extends SearchProvider {
+    readonly id: SearchProviderId;
+    readonly label = "Google";
+    isAvailable(): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/web/search/providers/mojeek.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Mojeek's independent index served as a server-rendered HTML results page.
+ * Each organic result renders as `ul.results-standard > li` with the title
+ * in `h2 > a.title` (href is the direct target URL) and the preview text in
+ * `p.s`. The site fronts with an ALTCHA proof-of-work captcha; the
+ * headless-browser fallback solves it when available, otherwise the fetch-only
+ * path surfaces the wall as a provider-tagged 429.
+ *
+ * Ported from oh-my-pi (can1357/oh-my-pi, MIT)
+ * `packages/coding-agent/src/web/search/providers/mojeek.ts`.
+ */
+import type { SearchProviderId, SearchResponse } from "../types.js";
+import type { SearchParams } from "./base.js";
+import { SearchProvider } from "./base.js";
+/** Execute a Mojeek web search against the standard HTML results page. */
+export declare function searchMojeek(params: SearchParams): Promise<SearchResponse>;
+/** Search provider for Mojeek (independent index, no API key required). */
+export declare class MojeekProvider extends SearchProvider {
+    readonly id: SearchProviderId;
+    readonly label = "Mojeek";
+    isAvailable(): boolean;
+    isExplicitlyAvailable(): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/web/search/providers/parallel.d.ts

@@ -0,0 +1,10 @@
+import { type SearchResponse } from "../types.js";
+import type { SearchParams } from "./base.js";
+import { SearchProvider } from "./base.js";
+export declare class ParallelProvider extends SearchProvider {
+    readonly id: "parallel";
+    readonly label = "Parallel";
+    /** The public MCP endpoint needs no credential of any kind. */
+    isAvailable(): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/web/search/providers/perplexity.d.ts

@@ -0,0 +1,10 @@
+import { type SearchResponse } from "../types.js";
+import type { SearchParams } from "./base.js";
+import { SearchProvider } from "./base.js";
+export declare class PerplexityProvider extends SearchProvider {
+    readonly id: "perplexity";
+    readonly label = "Perplexity";
+    /** The anonymous ask endpoint needs no credential of any kind. */
+    isAvailable(): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/web/search/providers/public.d.ts

@@ -0,0 +1,15 @@
+import { type SearchResponse } from "../types.js";
+import type { SearchParams } from "./base.js";
+import { SearchProvider } from "./base.js";
+export interface PublicWebDeadlines {
+    softMs?: number;
+    hardMs?: number;
+}
+export declare function searchPublicWeb(params: SearchParams, deadlines?: PublicWebDeadlines): Promise<SearchResponse>;
+export declare class PublicWebProvider extends SearchProvider {
+    readonly id: "public";
+    readonly label = "Public Web";
+    isAvailable(): boolean;
+    isExplicitlyAvailable(): boolean;
+    search(params: SearchParams): Promise<SearchResponse>;
+}

package/dist/web/search/providers/responses-api.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared OpenAI-Responses-API web search transport.
+ *
+ * Both `codex` (api.openai.com) and `xai` (api.x.ai) speak the Responses API
+ * shape with a hosted `web_search` tool, so their transports share one
+ * implementation parameterized by provider id, base URL, and default model.
+ *
+ * Ported from oh-my-pi (can1357/oh-my-pi, MIT) `web/search/providers/codex.ts`
+ * and `xai.ts`. Dropped: oh-my-pi's ChatGPT-backend SSE stream (it speaks an
+ * undocumented request shape tied to ChatGPT OAuth) — AutoRAG uses the
+ * documented non-streaming Responses API with a plain API key via
+ * `../model-auth.ts`.
+ */
+import { type ModelNativeSearchProviderId } from "../model-auth.js";
+import { type SearchResponse } from "../types.js";
+import type { SearchParams } from "./base.js";
+export interface ResponsesApiSearchOptions {
+    /** Search provider id ("codex" | "xai") for credential resolution and errors. */
+    readonly providerId: Extract<ModelNativeSearchProviderId, "codex" | "xai">;
+    readonly defaultBaseUrl: string;
+    readonly defaultModel: string;
+    readonly modelEnvVar: string;
+    readonly missingCredentialMessage: string;
+}
+/** Execute a Responses-API web search for the given provider configuration. */
+export declare function searchResponsesApi(options: ResponsesApiSearchOptions, params: SearchParams): Promise<SearchResponse>;