@omnicross/core 0.2.0 → 0.3.0

package/dist/search/http.cjs

@@ -0,0 +1,37 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+var _chunkBTBEJRGLcjs = require('../chunk-BTBEJRGL.cjs');
+require('../chunk-7RJI3NDI.cjs');
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+exports.DEFAULT_MAX_RESULTS = _chunkBTBEJRGLcjs.DEFAULT_MAX_RESULTS; exports.DEFAULT_SEARCH_TIMEOUT_MS = _chunkBTBEJRGLcjs.DEFAULT_SEARCH_TIMEOUT_MS; exports.HTTP_BING_PROVIDER_ID = _chunkBTBEJRGLcjs.HTTP_BING_PROVIDER_ID; exports.HTTP_DUCKDUCKGO_PROVIDER_ID = _chunkBTBEJRGLcjs.HTTP_DUCKDUCKGO_PROVIDER_ID; exports.HTTP_SEARCH_CAPABILITIES = _chunkBTBEJRGLcjs.HTTP_SEARCH_CAPABILITIES; exports.HttpBingProvider = _chunkBTBEJRGLcjs.HttpBingProvider; exports.HttpDuckDuckGoProvider = _chunkBTBEJRGLcjs.HttpDuckDuckGoProvider; exports.MAX_REDIRECTS = _chunkBTBEJRGLcjs.MAX_REDIRECTS; exports.MAX_RESULTS = _chunkBTBEJRGLcjs.MAX_RESULTS; exports.SEARCH_BROWSER_HEADERS = _chunkBTBEJRGLcjs.SEARCH_BROWSER_HEADERS; exports.SEARCH_HTTP_TRANSPORT_ID = _chunkBTBEJRGLcjs.SEARCH_HTTP_TRANSPORT_ID; exports.SEARCH_RESPONSE_BYTES = _chunkBTBEJRGLcjs.SEARCH_RESPONSE_BYTES; exports.builtinHttpSearchContributions = _chunkBTBEJRGLcjs.builtinHttpSearchContributions; exports.clampMaxResults = _chunkBTBEJRGLcjs.clampMaxResults; exports.createSearchHttpTransport = _chunkBTBEJRGLcjs.createSearchHttpTransport; exports.defaultSearchHttpTransport = _chunkBTBEJRGLcjs.defaultSearchHttpTransport;

package/dist/search/http.d.cts

@@ -0,0 +1,323 @@
+import { SearchProviderId, SearchResult, SearchProviderCapabilities, SearchProviderContribution, SearchProvider, SearchOptions } from '@omnicross/contracts/search-types';
+import { ProxyConfig } from '@omnicross/contracts/account-tokens-types';
+import { Dispatcher } from 'undici';
+import { S as SearchEgressPolicy } from '../egress-I46O_p5L.cjs';
+import { ImpitOptions, Impit } from 'impit';
+import { P as ProxyEnvironment } from '../proxy-UZTtjPZx.cjs';
+import 'node:dns';
+
+/**
+ * Shared vocabulary for the keyless HTTP search slice (plan 阶段2).
+ *
+ * Everything here is transport- and parser-neutral so the providers, the
+ * shared transport, and the doctor can agree on one set of names without
+ * importing each other.
+ *
+ * @module search/http/types
+ */
+
+/**
+ * The transport identity stamped on every failure this slice throws.
+ *
+ * Phase 1 ships exactly one transport. `impit` (Elftia's browser-fingerprint
+ * client) is deliberately NOT introduced here — the injection seam below is the
+ * whole extent of future-proofing, so an alternative transport can never become
+ * an implicit behavior change.
+ */
+declare const SEARCH_HTTP_TRANSPORT_ID = "undici";
+/**
+ * Which phase of a search failed (plan §11.4 — transport identity and failure
+ * stage must be observable).
+ *
+ * - `connect` — the request never produced a response (DNS, TCP, TLS).
+ * - `fetch` — a response arrived but is unusable (refused status, deadline).
+ * - `redirect` — the redirect chain exceeded its cap.
+ * - `body-cap` — the response body outgrew its byte cap mid-stream.
+ * - `challenge` — the engine served a bot challenge instead of a SERP.
+ * - `trust` — the page parsed, but the anti-decoy check refused it.
+ * - `parse` — the page is not recognizable as this engine's SERP.
+ */
+type SearchHttpStage = 'connect' | 'fetch' | 'redirect' | 'body-cap' | 'challenge' | 'trust' | 'parse';
+/** One fetched search page. */
+interface SearchHttpResource {
+    /** The URL the response was finally served from (after redirects). */
+    finalUrl: string;
+    /** HTTP status of the final response. */
+    status: number;
+    /** `content-type` header value, or `''`. */
+    contentType: string;
+    /** Decoded response body. */
+    rawText: string;
+}
+/** What the transport needs to execute one attempt. */
+interface SearchHttpRequest {
+    /** Hard budget for this single attempt, in milliseconds. */
+    timeoutMs: number;
+    /** Byte cap enforced while the body streams in. */
+    maxResponseBytes: number;
+    /** Caller cancellation. Aborting surfaces as code `cancelled`, never `timeout`. */
+    signal?: AbortSignal;
+    /** Stamped onto thrown errors so a failure names its provider. */
+    providerId?: SearchProviderId;
+}
+/**
+ * The seam both providers accept in their constructor.
+ *
+ * This is the test seam (fixtures are served through it) and the seam a future
+ * alternative transport would occupy.
+ */
+type SearchHttpTransport = (url: string, request: SearchHttpRequest) => Promise<SearchHttpResource>;
+/**
+ * The low-level fetch primitive the shared transport drives — undici's `fetch`
+ * by default. Separate from {@link SearchHttpTransport} so redirect, body-cap
+ * and header behavior can be unit-tested without a network.
+ */
+type SearchHttpFetch = (url: string, init: RequestInit) => Promise<Response>;
+/** The outcome of running one engine's parser over one page. */
+interface ParsedSerp {
+    /**
+     * Whether the page is structurally recognizable as this engine's SERP.
+     *
+     * This is what separates "the engine found nothing" (recognized, zero
+     * results → `[]`) from "the engine's markup changed under us" (unrecognized
+     * → `parse_failed`).
+     */
+    recognized: boolean;
+    /** Usable organic results, already clamped to the caller's `maxResults`. */
+    results: SearchResult[];
+}
+
+/**
+ * The builtin HTTP search contributions.
+ *
+ * Everything the registry must not infer is declared here: `source` and `kind`
+ * are stated, never derived from the id's spelling, and the capability set is
+ * explicit down to the options these engines do NOT honor.
+ *
+ * `priorityHint` is deliberately absent. Provider ordering is the orchestrator's
+ * decision (阶段3); encoding a preference here would recreate exactly the
+ * scattered-fallback-order problem the extraction exists to remove.
+ *
+ * @module search/http/contributions
+ */
+
+/**
+ * What both keyless HTTP engines can do.
+ *
+ * `supportsRegion` / `supportsLanguage` / `supportsTimeRange` are false because
+ * the scraped endpoints never honored those options; per the contract, a
+ * provider ignores an option it does not declare rather than failing.
+ */
+declare const HTTP_SEARCH_CAPABILITIES: Readonly<SearchProviderCapabilities>;
+/**
+ * Both builtin HTTP providers, ready to hand to a registry.
+ *
+ * @param transport - optional shared transport for both providers (tests, or a
+ *   future alternative client). Omit for the production undici transport.
+ */
+declare function builtinHttpSearchContributions(transport?: SearchHttpTransport): SearchProviderContribution[];
+
+/**
+ * The candidate-URL walk both HTTP providers share.
+ *
+ * Mirrors the baselined `searchWebViaFetch` loop (one shared deadline, split
+ * evenly across the remaining candidates, last error retained) with one
+ * plan-mandated behavior change: the three-way outcome distinction.
+ *
+ * Elftia collapses "the engine found nothing" and "the engine's markup changed"
+ * into a single `response contained no result entries` error. Here they are
+ * different answers:
+ *
+ * - a recognized SERP with zero organic results → `[]` (a legitimate answer);
+ * - an unrecognizable page → `parse_failed` (the parser-drift alarm);
+ * - a challenge or decoy page → a `challenge`/`trust` staged failure, checked
+ *   before either of the above.
+ *
+ * The divergence is deliberate (plan §11.4) and is recorded for 阶段5's
+ * behavior-comparison report as an allowed difference.
+ *
+ * @module search/http/engine
+ */
+
+/** Response byte cap at the search call sites (the fetch layer allows 5 MiB). */
+declare const SEARCH_RESPONSE_BYTES: number;
+/** Default budget for one whole search, across all its candidate URLs. */
+declare const DEFAULT_SEARCH_TIMEOUT_MS = 15000;
+/** `maxResults` clamp: [1, 10], defaulting to 5. */
+declare const DEFAULT_MAX_RESULTS = 5;
+declare const MAX_RESULTS = 10;
+/**
+ * Clamp a caller's `maxResults` into the engine-supported range.
+ *
+ * `NaN` passes through to `slice(0, NaN)` and yields `[]`, exactly as the
+ * baseline does. Left at parity deliberately: normalizing pathological option
+ * values belongs to the runtime that owns option handling (阶段3), not to two
+ * providers that would then disagree with every other one.
+ */
+declare function clampMaxResults(maxResults: number | undefined): number;
+
+/**
+ * The browser navigation header profile the search transport sends.
+ *
+ * This is the profile `packages/core/test-fixtures/http-search/` was captured
+ * with, so changing it invalidates the fixtures as live-behavior evidence.
+ *
+ * Ported verbatim from Elftia's `webFetchHttp.browserHeaders()` — a verified
+ * config; do not deviate from it. The Chromium version is read from the
+ * RUNTIME, exactly as Elftia does: `process.versions.chrome` inside an
+ * Electron host (a real, complete build number), and Elftia's own fixed
+ * fallback when no Chromium runtime reports one (plain Node). Never pin or
+ * invent a version string here — a fabricated build number is a bot
+ * fingerprint no real browser ever sends.
+ *
+ * @module search/http/headers
+ */
+/** The exact header set sent with every search request. */
+declare const SEARCH_BROWSER_HEADERS: Readonly<Record<string, string>>;
+
+/**
+ * `http-bing` — keyless Bing search over the shared HTTP transport.
+ *
+ * Standalone by construction: `new HttpBingProvider()` works with no config, no
+ * registry and no host. Nothing in Phase 1 阶段2 registers or calls it — that is
+ * 阶段3's job.
+ *
+ * @module search/http/HttpBingProvider
+ */
+
+/** The id this provider registers under. */
+declare const HTTP_BING_PROVIDER_ID = "http-bing";
+declare class HttpBingProvider implements SearchProvider {
+    readonly id: SearchProviderId;
+    private readonly transport;
+    constructor(transport?: SearchHttpTransport);
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+}
+
+/**
+ * `http-duckduckgo` — keyless DuckDuckGo search over the shared HTTP transport.
+ *
+ * Two candidate endpoints, tried in order under one shared deadline: the html
+ * endpoint first, then the lite endpoint. The lite endpoint is reached only when
+ * the html one produced no usable results (or failed outright) — the baselined
+ * behavior.
+ *
+ * @module search/http/HttpDuckDuckGoProvider
+ */
+
+/** The id this provider registers under. */
+declare const HTTP_DUCKDUCKGO_PROVIDER_ID = "http-duckduckgo";
+declare class HttpDuckDuckGoProvider implements SearchProvider {
+    readonly id: SearchProviderId;
+    private readonly transport;
+    constructor(transport?: SearchHttpTransport);
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+}
+
+/**
+ * The browser-impersonating fetch primitive for the keyless HTTP slice.
+ *
+ * Ported from Elftia's `nodeWebFetchTransport` (the impit half): impit supplies
+ * a current-Chrome TLS/HTTP2 fingerprint, which is the difference between a
+ * real SERP and a bot-decoy page on engines that fingerprint the client
+ * handshake. This is a verified config — `browser`, `followRedirects` and
+ * `vanillaFallback` mirror Elftia exactly; do not deviate.
+ *
+ * Fixed semantics:
+ * - `followRedirects: false`, so the transport's manual, egress-validated
+ *   redirect walk keeps sole ownership of hop decisions.
+ * - `vanillaFallback: false`: if the platform binary is unavailable we degrade
+ *   to the bounded undici path IN THIS MODULE'S CALLER — never silently to a
+ *   vanilla (non-impersonating) impit mode that would look like a browser and
+ *   handshake like Node.
+ * - Request-specific `user-agent`/`sec-ch-ua*` headers are REMOVED, so the
+ *   headers stay consistent with the impersonated fingerprint (impit sends its
+ *   own matching set).
+ * - One client per proxy URL, cached; if `impit` cannot be imported at all the
+ *   answer is `undefined` and the caller uses the undici fallback.
+ *
+ * @module search/http/impit
+ */
+
+/** Structural constructor type — resilient to impit being absent at runtime. */
+type ImpitConstructor = new (options?: ImpitOptions) => Impit;
+
+/**
+ * The shared HTTP transport both keyless search providers run on.
+ *
+ * Ported from Elftia's `webFetchHttp.fetchWebResource` + `nodeWebFetchTransport`
+ * (baselined in `docs/design/search-baseline/elftia-search-baseline.md` §3.3),
+ * with the failure channel replaced: instead of bare `Error` strings, every
+ * failure is a `SearchProviderError` carrying `details.transport` and
+ * `details.stage`.
+ *
+ * Fixed semantics:
+ * - impit first (Elftia's verified browser-impersonating client — a real
+ *   Chrome TLS/HTTP2 fingerprint; `followRedirects: false` keeps this
+ *   transport's manual, egress-validated walk in charge), with the layered
+ *   `resolveProxyConfig` as its proxy source. When the impit platform binary
+ *   is unavailable, the bounded undici path serves instead, with a per-request
+ *   proxy dispatcher: the layered `resolveProxyDispatcher` override first (the
+ *   daemon's `fetchUpstream` resolver), else the `EnvHttpProxyAgent` the
+ *   environment configures (cached per proxy signature).
+ * - The pinned browser navigation header profile (see `./headers`).
+ * - `redirect: 'manual'`, at most {@link MAX_REDIRECTS} hops, with the initial
+ *   URL and every hop target checked against the search egress policy
+ *   (`../egress`). These two engines are fixed-host and keyless, so nothing an
+ *   attacker controls picks the URL — but a redirect target is upstream input,
+ *   and this is the seam 阶段2 identified and 阶段4 fills. The default policy
+ *   permits every public host, so the fixed engines and the live `cn.bing.com`
+ *   geo-redirect are unaffected.
+ * - A byte cap enforced WHILE the body streams — an oversized page fails, it is
+ *   never silently truncated (this diverges from Elftia, which truncates and
+ *   parses the fragment; the spec requires a `body-cap` failure).
+ * - One deadline per attempt; caller aborts surface as `cancelled`, the deadline
+ *   as `timeout`, never conflated.
+ * - Compression is undici's business: it negotiates `Accept-Encoding` and
+ *   decodes the response.
+ *
+ * `impit` is NOT used. undici is the sole Phase-1 transport; the injection seam
+ * below is the only future-proofing.
+ *
+ * @module search/http/transport
+ */
+
+/** Redirect hop cap. */
+declare const MAX_REDIRECTS = 5;
+/** Knobs for {@link createSearchHttpTransport}. */
+interface SearchHttpTransportOptions {
+    /** The fetch primitive to drive. Defaults to undici's `fetch`. */
+    fetch?: SearchHttpFetch;
+    /** Environment to read proxy variables from. Defaults to `process.env`. */
+    env?: ProxyEnvironment;
+    /**
+     * Layered proxy-dispatcher override for one request URL, AHEAD of the env
+     * layer. The daemon passes `fetchUpstream`'s resolver here so search egress
+     * follows the same `server.proxy` stack (global config, socks5 included) as
+     * LLM upstream traffic; a `NO_PROXY`/loopback target yields `undefined`
+     * inside that resolver and falls through to the env layer unchanged.
+     */
+    resolveProxyDispatcher?: (url: string) => Dispatcher | undefined;
+    /**
+     * Layered proxy CONFIG for one request URL — the impit path's proxy source,
+     * because impit takes a proxy URL, not an undici dispatcher. The daemon
+     * passes its `fetchUpstream`-layered resolver, so `server.proxy` (socks5
+     * included) governs impersonated requests exactly like LLM egress.
+     */
+    resolveProxyConfig?: (url: string) => ProxyConfig | undefined;
+    /** Test seam for the impit constructor loader. Omit for the real import. */
+    loadImpit?: () => Promise<ImpitConstructor | undefined>;
+    /** Redirect hop cap. Defaults to {@link MAX_REDIRECTS}. */
+    maxRedirects?: number;
+    /**
+     * Egress policy for the initial URL and every redirect hop. Defaults to
+     * public-only, which is all these fixed-host engines ever need.
+     */
+    egressPolicy?: SearchEgressPolicy;
+}
+/** Build a transport. Tests inject `fetch`; production takes the default. */
+declare function createSearchHttpTransport(options?: SearchHttpTransportOptions): SearchHttpTransport;
+/** The production transport: undici, reading proxy settings from `process.env`. */
+declare const defaultSearchHttpTransport: SearchHttpTransport;
+
+export { DEFAULT_MAX_RESULTS, DEFAULT_SEARCH_TIMEOUT_MS, HTTP_BING_PROVIDER_ID, HTTP_DUCKDUCKGO_PROVIDER_ID, HTTP_SEARCH_CAPABILITIES, HttpBingProvider, HttpDuckDuckGoProvider, MAX_REDIRECTS, MAX_RESULTS, type ParsedSerp, SEARCH_BROWSER_HEADERS, SEARCH_HTTP_TRANSPORT_ID, SEARCH_RESPONSE_BYTES, type SearchHttpFetch, type SearchHttpRequest, type SearchHttpResource, type SearchHttpStage, type SearchHttpTransport, type SearchHttpTransportOptions, builtinHttpSearchContributions, clampMaxResults, createSearchHttpTransport, defaultSearchHttpTransport };

package/dist/search/http.d.ts

@@ -0,0 +1,323 @@
+import { SearchProviderId, SearchResult, SearchProviderCapabilities, SearchProviderContribution, SearchProvider, SearchOptions } from '@omnicross/contracts/search-types';
+import { ProxyConfig } from '@omnicross/contracts/account-tokens-types';
+import { Dispatcher } from 'undici';
+import { S as SearchEgressPolicy } from '../egress-I46O_p5L.js';
+import { ImpitOptions, Impit } from 'impit';
+import { P as ProxyEnvironment } from '../proxy-UZTtjPZx.js';
+import 'node:dns';
+
+/**
+ * Shared vocabulary for the keyless HTTP search slice (plan 阶段2).
+ *
+ * Everything here is transport- and parser-neutral so the providers, the
+ * shared transport, and the doctor can agree on one set of names without
+ * importing each other.
+ *
+ * @module search/http/types
+ */
+
+/**
+ * The transport identity stamped on every failure this slice throws.
+ *
+ * Phase 1 ships exactly one transport. `impit` (Elftia's browser-fingerprint
+ * client) is deliberately NOT introduced here — the injection seam below is the
+ * whole extent of future-proofing, so an alternative transport can never become
+ * an implicit behavior change.
+ */
+declare const SEARCH_HTTP_TRANSPORT_ID = "undici";
+/**
+ * Which phase of a search failed (plan §11.4 — transport identity and failure
+ * stage must be observable).
+ *
+ * - `connect` — the request never produced a response (DNS, TCP, TLS).
+ * - `fetch` — a response arrived but is unusable (refused status, deadline).
+ * - `redirect` — the redirect chain exceeded its cap.
+ * - `body-cap` — the response body outgrew its byte cap mid-stream.
+ * - `challenge` — the engine served a bot challenge instead of a SERP.
+ * - `trust` — the page parsed, but the anti-decoy check refused it.
+ * - `parse` — the page is not recognizable as this engine's SERP.
+ */
+type SearchHttpStage = 'connect' | 'fetch' | 'redirect' | 'body-cap' | 'challenge' | 'trust' | 'parse';
+/** One fetched search page. */
+interface SearchHttpResource {
+    /** The URL the response was finally served from (after redirects). */
+    finalUrl: string;
+    /** HTTP status of the final response. */
+    status: number;
+    /** `content-type` header value, or `''`. */
+    contentType: string;
+    /** Decoded response body. */
+    rawText: string;
+}
+/** What the transport needs to execute one attempt. */
+interface SearchHttpRequest {
+    /** Hard budget for this single attempt, in milliseconds. */
+    timeoutMs: number;
+    /** Byte cap enforced while the body streams in. */
+    maxResponseBytes: number;
+    /** Caller cancellation. Aborting surfaces as code `cancelled`, never `timeout`. */
+    signal?: AbortSignal;
+    /** Stamped onto thrown errors so a failure names its provider. */
+    providerId?: SearchProviderId;
+}
+/**
+ * The seam both providers accept in their constructor.
+ *
+ * This is the test seam (fixtures are served through it) and the seam a future
+ * alternative transport would occupy.
+ */
+type SearchHttpTransport = (url: string, request: SearchHttpRequest) => Promise<SearchHttpResource>;
+/**
+ * The low-level fetch primitive the shared transport drives — undici's `fetch`
+ * by default. Separate from {@link SearchHttpTransport} so redirect, body-cap
+ * and header behavior can be unit-tested without a network.
+ */
+type SearchHttpFetch = (url: string, init: RequestInit) => Promise<Response>;
+/** The outcome of running one engine's parser over one page. */
+interface ParsedSerp {
+    /**
+     * Whether the page is structurally recognizable as this engine's SERP.
+     *
+     * This is what separates "the engine found nothing" (recognized, zero
+     * results → `[]`) from "the engine's markup changed under us" (unrecognized
+     * → `parse_failed`).
+     */
+    recognized: boolean;
+    /** Usable organic results, already clamped to the caller's `maxResults`. */
+    results: SearchResult[];
+}
+
+/**
+ * The builtin HTTP search contributions.
+ *
+ * Everything the registry must not infer is declared here: `source` and `kind`
+ * are stated, never derived from the id's spelling, and the capability set is
+ * explicit down to the options these engines do NOT honor.
+ *
+ * `priorityHint` is deliberately absent. Provider ordering is the orchestrator's
+ * decision (阶段3); encoding a preference here would recreate exactly the
+ * scattered-fallback-order problem the extraction exists to remove.
+ *
+ * @module search/http/contributions
+ */
+
+/**
+ * What both keyless HTTP engines can do.
+ *
+ * `supportsRegion` / `supportsLanguage` / `supportsTimeRange` are false because
+ * the scraped endpoints never honored those options; per the contract, a
+ * provider ignores an option it does not declare rather than failing.
+ */
+declare const HTTP_SEARCH_CAPABILITIES: Readonly<SearchProviderCapabilities>;
+/**
+ * Both builtin HTTP providers, ready to hand to a registry.
+ *
+ * @param transport - optional shared transport for both providers (tests, or a
+ *   future alternative client). Omit for the production undici transport.
+ */
+declare function builtinHttpSearchContributions(transport?: SearchHttpTransport): SearchProviderContribution[];
+
+/**
+ * The candidate-URL walk both HTTP providers share.
+ *
+ * Mirrors the baselined `searchWebViaFetch` loop (one shared deadline, split
+ * evenly across the remaining candidates, last error retained) with one
+ * plan-mandated behavior change: the three-way outcome distinction.
+ *
+ * Elftia collapses "the engine found nothing" and "the engine's markup changed"
+ * into a single `response contained no result entries` error. Here they are
+ * different answers:
+ *
+ * - a recognized SERP with zero organic results → `[]` (a legitimate answer);
+ * - an unrecognizable page → `parse_failed` (the parser-drift alarm);
+ * - a challenge or decoy page → a `challenge`/`trust` staged failure, checked
+ *   before either of the above.
+ *
+ * The divergence is deliberate (plan §11.4) and is recorded for 阶段5's
+ * behavior-comparison report as an allowed difference.
+ *
+ * @module search/http/engine
+ */
+
+/** Response byte cap at the search call sites (the fetch layer allows 5 MiB). */
+declare const SEARCH_RESPONSE_BYTES: number;
+/** Default budget for one whole search, across all its candidate URLs. */
+declare const DEFAULT_SEARCH_TIMEOUT_MS = 15000;
+/** `maxResults` clamp: [1, 10], defaulting to 5. */
+declare const DEFAULT_MAX_RESULTS = 5;
+declare const MAX_RESULTS = 10;
+/**
+ * Clamp a caller's `maxResults` into the engine-supported range.
+ *
+ * `NaN` passes through to `slice(0, NaN)` and yields `[]`, exactly as the
+ * baseline does. Left at parity deliberately: normalizing pathological option
+ * values belongs to the runtime that owns option handling (阶段3), not to two
+ * providers that would then disagree with every other one.
+ */
+declare function clampMaxResults(maxResults: number | undefined): number;
+
+/**
+ * The browser navigation header profile the search transport sends.
+ *
+ * This is the profile `packages/core/test-fixtures/http-search/` was captured
+ * with, so changing it invalidates the fixtures as live-behavior evidence.
+ *
+ * Ported verbatim from Elftia's `webFetchHttp.browserHeaders()` — a verified
+ * config; do not deviate from it. The Chromium version is read from the
+ * RUNTIME, exactly as Elftia does: `process.versions.chrome` inside an
+ * Electron host (a real, complete build number), and Elftia's own fixed
+ * fallback when no Chromium runtime reports one (plain Node). Never pin or
+ * invent a version string here — a fabricated build number is a bot
+ * fingerprint no real browser ever sends.
+ *
+ * @module search/http/headers
+ */
+/** The exact header set sent with every search request. */
+declare const SEARCH_BROWSER_HEADERS: Readonly<Record<string, string>>;
+
+/**
+ * `http-bing` — keyless Bing search over the shared HTTP transport.
+ *
+ * Standalone by construction: `new HttpBingProvider()` works with no config, no
+ * registry and no host. Nothing in Phase 1 阶段2 registers or calls it — that is
+ * 阶段3's job.
+ *
+ * @module search/http/HttpBingProvider
+ */
+
+/** The id this provider registers under. */
+declare const HTTP_BING_PROVIDER_ID = "http-bing";
+declare class HttpBingProvider implements SearchProvider {
+    readonly id: SearchProviderId;
+    private readonly transport;
+    constructor(transport?: SearchHttpTransport);
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+}
+
+/**
+ * `http-duckduckgo` — keyless DuckDuckGo search over the shared HTTP transport.
+ *
+ * Two candidate endpoints, tried in order under one shared deadline: the html
+ * endpoint first, then the lite endpoint. The lite endpoint is reached only when
+ * the html one produced no usable results (or failed outright) — the baselined
+ * behavior.
+ *
+ * @module search/http/HttpDuckDuckGoProvider
+ */
+
+/** The id this provider registers under. */
+declare const HTTP_DUCKDUCKGO_PROVIDER_ID = "http-duckduckgo";
+declare class HttpDuckDuckGoProvider implements SearchProvider {
+    readonly id: SearchProviderId;
+    private readonly transport;
+    constructor(transport?: SearchHttpTransport);
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+}
+
+/**
+ * The browser-impersonating fetch primitive for the keyless HTTP slice.
+ *
+ * Ported from Elftia's `nodeWebFetchTransport` (the impit half): impit supplies
+ * a current-Chrome TLS/HTTP2 fingerprint, which is the difference between a
+ * real SERP and a bot-decoy page on engines that fingerprint the client
+ * handshake. This is a verified config — `browser`, `followRedirects` and
+ * `vanillaFallback` mirror Elftia exactly; do not deviate.
+ *
+ * Fixed semantics:
+ * - `followRedirects: false`, so the transport's manual, egress-validated
+ *   redirect walk keeps sole ownership of hop decisions.
+ * - `vanillaFallback: false`: if the platform binary is unavailable we degrade
+ *   to the bounded undici path IN THIS MODULE'S CALLER — never silently to a
+ *   vanilla (non-impersonating) impit mode that would look like a browser and
+ *   handshake like Node.
+ * - Request-specific `user-agent`/`sec-ch-ua*` headers are REMOVED, so the
+ *   headers stay consistent with the impersonated fingerprint (impit sends its
+ *   own matching set).
+ * - One client per proxy URL, cached; if `impit` cannot be imported at all the
+ *   answer is `undefined` and the caller uses the undici fallback.
+ *
+ * @module search/http/impit
+ */
+
+/** Structural constructor type — resilient to impit being absent at runtime. */
+type ImpitConstructor = new (options?: ImpitOptions) => Impit;
+
+/**
+ * The shared HTTP transport both keyless search providers run on.
+ *
+ * Ported from Elftia's `webFetchHttp.fetchWebResource` + `nodeWebFetchTransport`
+ * (baselined in `docs/design/search-baseline/elftia-search-baseline.md` §3.3),
+ * with the failure channel replaced: instead of bare `Error` strings, every
+ * failure is a `SearchProviderError` carrying `details.transport` and
+ * `details.stage`.
+ *
+ * Fixed semantics:
+ * - impit first (Elftia's verified browser-impersonating client — a real
+ *   Chrome TLS/HTTP2 fingerprint; `followRedirects: false` keeps this
+ *   transport's manual, egress-validated walk in charge), with the layered
+ *   `resolveProxyConfig` as its proxy source. When the impit platform binary
+ *   is unavailable, the bounded undici path serves instead, with a per-request
+ *   proxy dispatcher: the layered `resolveProxyDispatcher` override first (the
+ *   daemon's `fetchUpstream` resolver), else the `EnvHttpProxyAgent` the
+ *   environment configures (cached per proxy signature).
+ * - The pinned browser navigation header profile (see `./headers`).
+ * - `redirect: 'manual'`, at most {@link MAX_REDIRECTS} hops, with the initial
+ *   URL and every hop target checked against the search egress policy
+ *   (`../egress`). These two engines are fixed-host and keyless, so nothing an
+ *   attacker controls picks the URL — but a redirect target is upstream input,
+ *   and this is the seam 阶段2 identified and 阶段4 fills. The default policy
+ *   permits every public host, so the fixed engines and the live `cn.bing.com`
+ *   geo-redirect are unaffected.
+ * - A byte cap enforced WHILE the body streams — an oversized page fails, it is
+ *   never silently truncated (this diverges from Elftia, which truncates and
+ *   parses the fragment; the spec requires a `body-cap` failure).
+ * - One deadline per attempt; caller aborts surface as `cancelled`, the deadline
+ *   as `timeout`, never conflated.
+ * - Compression is undici's business: it negotiates `Accept-Encoding` and
+ *   decodes the response.
+ *
+ * `impit` is NOT used. undici is the sole Phase-1 transport; the injection seam
+ * below is the only future-proofing.
+ *
+ * @module search/http/transport
+ */
+
+/** Redirect hop cap. */
+declare const MAX_REDIRECTS = 5;
+/** Knobs for {@link createSearchHttpTransport}. */
+interface SearchHttpTransportOptions {
+    /** The fetch primitive to drive. Defaults to undici's `fetch`. */
+    fetch?: SearchHttpFetch;
+    /** Environment to read proxy variables from. Defaults to `process.env`. */
+    env?: ProxyEnvironment;
+    /**
+     * Layered proxy-dispatcher override for one request URL, AHEAD of the env
+     * layer. The daemon passes `fetchUpstream`'s resolver here so search egress
+     * follows the same `server.proxy` stack (global config, socks5 included) as
+     * LLM upstream traffic; a `NO_PROXY`/loopback target yields `undefined`
+     * inside that resolver and falls through to the env layer unchanged.
+     */
+    resolveProxyDispatcher?: (url: string) => Dispatcher | undefined;
+    /**
+     * Layered proxy CONFIG for one request URL — the impit path's proxy source,
+     * because impit takes a proxy URL, not an undici dispatcher. The daemon
+     * passes its `fetchUpstream`-layered resolver, so `server.proxy` (socks5
+     * included) governs impersonated requests exactly like LLM egress.
+     */
+    resolveProxyConfig?: (url: string) => ProxyConfig | undefined;
+    /** Test seam for the impit constructor loader. Omit for the real import. */
+    loadImpit?: () => Promise<ImpitConstructor | undefined>;
+    /** Redirect hop cap. Defaults to {@link MAX_REDIRECTS}. */
+    maxRedirects?: number;
+    /**
+     * Egress policy for the initial URL and every redirect hop. Defaults to
+     * public-only, which is all these fixed-host engines ever need.
+     */
+    egressPolicy?: SearchEgressPolicy;
+}
+/** Build a transport. Tests inject `fetch`; production takes the default. */
+declare function createSearchHttpTransport(options?: SearchHttpTransportOptions): SearchHttpTransport;
+/** The production transport: undici, reading proxy settings from `process.env`. */
+declare const defaultSearchHttpTransport: SearchHttpTransport;
+
+export { DEFAULT_MAX_RESULTS, DEFAULT_SEARCH_TIMEOUT_MS, HTTP_BING_PROVIDER_ID, HTTP_DUCKDUCKGO_PROVIDER_ID, HTTP_SEARCH_CAPABILITIES, HttpBingProvider, HttpDuckDuckGoProvider, MAX_REDIRECTS, MAX_RESULTS, type ParsedSerp, SEARCH_BROWSER_HEADERS, SEARCH_HTTP_TRANSPORT_ID, SEARCH_RESPONSE_BYTES, type SearchHttpFetch, type SearchHttpRequest, type SearchHttpResource, type SearchHttpStage, type SearchHttpTransport, type SearchHttpTransportOptions, builtinHttpSearchContributions, clampMaxResults, createSearchHttpTransport, defaultSearchHttpTransport };