@omnicross/core 0.2.0 → 0.3.0

package/dist/search/api.d.cts

@@ -0,0 +1,385 @@
+import { SearchProviderCapabilities, SearchProviderContribution, SearchProviderId, SearchOptions, SearchUrlReadResult, SearchProvider, SearchResult, SearchProviderError } from '@omnicross/contracts/search-types';
+import { Dispatcher } from 'undici';
+import { S as SearchEgressPolicy } from '../egress-I46O_p5L.cjs';
+import { a as SearchApiFetch, S as SearchApiProviderConfigs, J as JinaProviderConfig, b as SearchApiTransport, c as SearxngProviderConfig, T as TavilyProviderConfig, Z as ZhipuProviderConfig } from '../types-CbCZqLGg.cjs';
+export { d as SEARCH_API_TRANSPORT_ID, e as SearchApiRequest, f as SearchApiStage } from '../types-CbCZqLGg.cjs';
+import { P as ProxyEnvironment } from '../proxy-UZTtjPZx.cjs';
+import 'node:dns';
+
+/**
+ * The API search contributions.
+ *
+ * Everything the registry must not infer is declared here: `source` and `kind`
+ * are stated, never derived from an id's spelling, and each adapter's
+ * capabilities are explicit down to the options it does NOT honor.
+ *
+ * The gating rule is the important one: a provider absent from `configs`
+ * produces NO contribution. It is unconfigured, not broken. A runtime that
+ * registered a keyless Tavily would advertise a capability it cannot honor and
+ * then burn a fallback attempt discovering that — so the absence is the
+ * feature. (`doctor search` still shows those providers as `unconfigured`
+ * rows; that is what doctor is for.)
+ *
+ * `priorityHint` is deliberately absent, as in the HTTP slice: ordering is the
+ * orchestrator's decision, and encoding a preference here would recreate the
+ * scattered-fallback-order problem the extraction exists to remove.
+ *
+ * @module search/api/contributions
+ */
+
+/** Tavily: key required, search only. */
+declare const TAVILY_CAPABILITIES: Readonly<SearchProviderCapabilities>;
+/** Jina: keyless-capable, and the only adapter that can read a URL. */
+declare const JINA_CAPABILITIES: Readonly<SearchProviderCapabilities>;
+/** SearXNG: configured by HOST, not by key. */
+declare const SEARXNG_CAPABILITIES: Readonly<SearchProviderCapabilities>;
+/** Zhipu and Z.AI: key required, search only. */
+declare const ZHIPU_CAPABILITIES: Readonly<SearchProviderCapabilities>;
+/** Knobs for {@link apiSearchContributions}. */
+interface ApiSearchContributionOptions {
+    /**
+     * Egress policy for every request these providers make. Omit for public-only.
+     * An internal SearXNG deployment is enabled by naming its hostname here.
+     */
+    egressPolicy?: SearchEgressPolicy;
+    /** Fetch primitive seam. Omit for the production undici transport. */
+    fetchImpl?: SearchApiFetch;
+    /**
+     * Layered proxy-dispatcher override handed to the shared transport (the
+     * daemon's `fetchUpstream` resolver). Only meaningful without `fetchImpl`.
+     */
+    resolveProxyDispatcher?: (url: string) => Dispatcher | undefined;
+}
+/**
+ * Build contributions for exactly the providers `configs` names.
+ *
+ * All adapters share ONE transport instance, so the egress policy and the
+ * dispatcher cache are shared too.
+ *
+ * The returned order mirrors Elftia's registry registration order
+ * (`tavily, jina, searxng, zhipu, z.ai`), which is what the registry preserves
+ * — but note that the ORDER PROVIDERS ARE TRIED is the orchestrator's policy,
+ * not this list.
+ */
+declare function apiSearchContributions(configs: SearchApiProviderConfigs, options?: ApiSearchContributionOptions): SearchProviderContribution[];
+
+/**
+ * The Jina reader — full page content for one URL.
+ *
+ * Ported from Elftia's `JinaReader` (sha256 `85d8b2a6…`, re-verified
+ * byte-identical against the 阶段0 manifest before porting) as a STANDALONE
+ * class, kept deliberately separate from `JinaSearchProvider`: the two call
+ * different hosts (`r.jina.ai` vs `s.jina.ai`) and answer different questions,
+ * and Elftia only ever coupled them through a `setApiKey` call.
+ *
+ * One behavior change: Elftia returns an in-band `{ success: false, error }`
+ * shape on failure, which is exactly the code-less error string the new
+ * contract exists to remove — a fallback policy cannot decide on it. This
+ * client throws the taxonomy `SearchProviderError` the shared transport
+ * produces. The legacy shape is still reachable through the existing
+ * `search-compat` converters for any consumer that needs it.
+ *
+ * The host is fixed at `r.jina.ai`, as in Elftia. Configurability is not added
+ * speculatively — but the request still passes egress validation like every
+ * other, so the fixed host buys no bypass.
+ *
+ * NOTE (plan §16, unresolved and owned by a later stage): this reader and
+ * `BuiltinToolExecutor`'s `web_fetch` are two ways to turn a URL into text.
+ * Whether they should become one capability with different policies or stay two
+ * bounded interfaces is NOT decided here, and `web_fetch` is untouched.
+ *
+ * @module search/api/JinaReaderClient
+ */
+
+/** Elftia's reader host. Not configurable there, and not made so here. */
+declare const JINA_READER_HOST = "https://r.jina.ai";
+declare class JinaReaderClient {
+    private readonly config;
+    private readonly transport;
+    private readonly providerId;
+    private readonly rotator;
+    constructor(config?: JinaProviderConfig, transport?: SearchApiTransport, providerId?: SearchProviderId);
+    /**
+     * Read one URL.
+     *
+     * The key is OPTIONAL, as in the baseline: the reader answers unauthenticated
+     * requests at a lower rate limit.
+     */
+    readUrl(url: string, options?: SearchOptions): Promise<SearchUrlReadResult>;
+}
+
+/**
+ * `jina` — the Jina search API on the new provider contract.
+ *
+ * Ported from Elftia's `JinaProvider` (sha256 `374d2252…`, re-verified
+ * byte-identical against the 阶段0 manifest before porting). GET
+ * `{apiHost}/<encoded query>`, key OPTIONAL (the endpoint answers
+ * unauthenticated at a lower rate limit), `X-Engine: direct` only when the
+ * caller asks for page content, and the `content || description` mapping.
+ *
+ * SEARCH and READER are split, unlike the baseline where one `configureProvider`
+ * call pushed the key into both. This class owns search; {@link JinaReaderClient}
+ * owns `readUrl` and is injected, so `capabilities.supportsUrlRead: true` names
+ * something that always works rather than something that works if a setter was
+ * called.
+ *
+ * @module search/api/JinaSearchProvider
+ */
+
+/** The id this provider registers under. */
+declare const JINA_PROVIDER_ID = "jina";
+/** Elftia's default search host. */
+declare const JINA_DEFAULT_HOST = "https://s.jina.ai";
+/** Elftia's default result count. */
+declare const JINA_DEFAULT_MAX_RESULTS = 5;
+declare class JinaSearchProvider implements SearchProvider {
+    private readonly config;
+    private readonly transport;
+    readonly id: SearchProviderId;
+    private readonly rotator;
+    private readonly reader;
+    constructor(config?: JinaProviderConfig, transport?: SearchApiTransport, reader?: JinaReaderClient);
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /** Read one URL through the split-out reader client. */
+    readUrl(url: string, options?: SearchOptions): Promise<SearchUrlReadResult>;
+}
+
+/**
+ * Round-robin selection across a provider's comma-separated API keys.
+ *
+ * Ported from Elftia's `ApiKeyRotator`
+ * (`capabilities/search/ApiKeyRotator.ts`, sha256 `9c649cba…`, re-verified
+ * byte-identical against the 阶段0 manifest before porting). Behavior is
+ * unchanged:
+ *
+ * - a single key is returned as-is, with no rotation;
+ * - empty or whitespace-only input returns `''`, and the ADAPTER raises the
+ *   `config_missing` failure — the rotator never decides whether a provider is
+ *   configured;
+ * - multiple keys advance one step per call, wrapping defensively in case the
+ *   configured list shrank between calls.
+ *
+ * One instance per provider instance, as in Elftia. The index is in-memory and
+ * resets with the process, which matches how the keys themselves are re-read
+ * from configuration at startup.
+ *
+ * @module search/api/rotator
+ */
+declare class ApiKeyRotator {
+    private index;
+    /**
+     * Pick the next key from a comma-separated list, advancing the counter.
+     *
+     * Returns `''` when nothing is configured — never `undefined`, so callers
+     * have one falsy case to test rather than two.
+     */
+    pick(rawKeyString: string | undefined): string;
+    /** Reset the rotation counter, e.g. after a configuration update. */
+    reset(): void;
+    /** How many usable keys the string holds. */
+    countKeys(rawKeyString: string | undefined): number;
+    /**
+     * Every configured key.
+     *
+     * Not in the Elftia original: redaction has to strip EVERY key a provider
+     * could have sent, not just the one this request rotated onto, or a key
+     * echoed by an upstream error survives whenever the counter has moved on.
+     */
+    allKeys(rawKeyString: string | undefined): string[];
+}
+
+/**
+ * `searxng` — a self-hosted SearXNG instance on the new provider contract.
+ *
+ * Ported from Elftia's `SearxngProvider` (sha256 `c1ec6694…`, re-verified
+ * byte-identical against the 阶段0 manifest before porting). GET
+ * `{apiHost}/search?q=&format=json&pageno=1`, with Basic auth sent only when
+ * BOTH credentials are present.
+ *
+ * The only provider whose required setting is a HOST rather than a key, and
+ * therefore the one the egress policy exists to accommodate: a SearXNG instance
+ * usually lives on a private address, which the default policy denies. An
+ * operator enables theirs by naming its hostname in
+ * `SearchEgressPolicy.allowedPrivateHosts` — an explicit, admin-level decision,
+ * never something this adapter infers from the fact that a host was configured.
+ *
+ * @module search/api/SearxngSearchProvider
+ */
+
+/** The id this provider registers under. */
+declare const SEARXNG_PROVIDER_ID = "searxng";
+/** Elftia's default result count. */
+declare const SEARXNG_DEFAULT_MAX_RESULTS = 5;
+declare class SearxngSearchProvider implements SearchProvider {
+    private readonly config;
+    private readonly transport;
+    readonly id: SearchProviderId;
+    constructor(config: SearxngProviderConfig, transport?: SearchApiTransport);
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+}
+
+/**
+ * `tavily` — the Tavily search API on the new provider contract.
+ *
+ * Ported from Elftia's `TavilyProvider` (sha256 `3134dcd7…`, re-verified
+ * byte-identical against the 阶段0 manifest before porting). The wire contract
+ * is unchanged: POST `{apiHost}/search` with the key IN THE JSON BODY,
+ * `search_depth: 'advanced'`, and no client-side slicing — Tavily honors
+ * `max_results` itself.
+ *
+ * That body-borne key is why the shared transport's redaction is mandatory
+ * rather than defensive: a 4xx that quotes the request back is a direct path
+ * from a credential to a log file. Every key this provider could have sent is
+ * handed to the transport as `secrets`, not just the one this call rotated
+ * onto.
+ *
+ * @module search/api/TavilySearchProvider
+ */
+
+/** The id this provider registers under. */
+declare const TAVILY_PROVIDER_ID = "tavily";
+/** Elftia's default host, used when no `apiHost` override is configured. */
+declare const TAVILY_DEFAULT_HOST = "https://api.tavily.com";
+/** Elftia's default result count. */
+declare const TAVILY_DEFAULT_MAX_RESULTS = 5;
+declare class TavilySearchProvider implements SearchProvider {
+    private readonly config;
+    private readonly transport;
+    readonly id: SearchProviderId;
+    private readonly rotator;
+    constructor(config: TavilyProviderConfig, transport?: SearchApiTransport);
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+}
+
+/**
+ * The shared transport every API search adapter runs on.
+ *
+ * Elftia's four adapters each call global `fetch` directly, each build their
+ * own `<label> search failed: <status> - <responseText>` string, and each
+ * follow redirects silently. Porting that shape four times would mean writing
+ * the SSRF check and the secret redaction four times — so the ported adapters
+ * share this one transport instead, and it owns everything that must not be
+ * re-implemented per provider:
+ *
+ * - **Egress validation** of the initial URL and of EVERY redirect hop.
+ * - **A manual redirect walk** (cap {@link API_MAX_REDIRECTS}). This is a
+ *   deliberate divergence from Elftia's `redirect: 'follow'`, recorded for
+ *   阶段5's comparison report: per-hop validation is impossible without it, and
+ *   a JSON API that redirects now gets checked instead of silently followed.
+ * - **The guarded dispatcher** on direct connections, so a hostname that
+ *   resolves into a denied class cannot be connected to. Proxied connections
+ *   take the proxy dispatcher and keep URL-level checks only — see
+ *   {@link selectApiDispatcher}.
+ * - **Status mapping** onto the eight-code taxonomy.
+ * - **Redaction**, through one sanitizer every error message passes. Tavily
+ *   sends its API key in the request BODY, so an upstream 4xx that quotes the
+ *   request is a direct path from a credential to a log file. This is the only
+ *   thing standing in that path.
+ *
+ * @module search/api/transport
+ */
+
+/** Redirect hop cap, matching the HTTP slice. */
+declare const API_MAX_REDIRECTS = 5;
+/** Default per-request budget, matching the search layer's HTTP budget. */
+declare const DEFAULT_API_TIMEOUT_MS = 15000;
+/** Sanity cap on a JSON response body. Search payloads are kilobytes. */
+declare const API_RESPONSE_BYTES: number;
+/** Knobs for {@link createSearchApiTransport}. */
+interface SearchApiTransportOptions {
+    /** The fetch primitive to drive. Defaults to undici's `fetch`. */
+    fetch?: SearchApiFetch;
+    /** 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's `fetchUpstream` resolver, so search follows
+     * `server.proxy`). When it yields a dispatcher the connection is proxied —
+     * URL and per-hop egress validation still apply, address-level validation
+     * does not, the same documented limitation as the env proxy. When it yields
+     * `undefined` the env layer and then the egress-guarded dispatcher apply,
+     * exactly as before.
+     */
+    resolveProxyDispatcher?: (url: string) => Dispatcher | undefined;
+    /** Egress policy. Defaults to public-only. */
+    egressPolicy?: SearchEgressPolicy;
+    /** Redirect hop cap. Defaults to {@link API_MAX_REDIRECTS}. */
+    maxRedirects?: number;
+}
+/** Build an API transport. Tests inject `fetch`; production takes the default. */
+declare function createSearchApiTransport(options?: SearchApiTransportOptions): SearchApiTransport;
+/** The production transport: undici, proxy from `process.env`, default policy. */
+declare const defaultSearchApiTransport: SearchApiTransport;
+/**
+ * Require an array at `field` on a JSON payload.
+ *
+ * Elftia tolerates a missing array on three of the four adapters
+ * (`data.results || []`), which turns a changed response shape into an
+ * empty-but-successful search. That re-conflates exactly what 阶段2 separated:
+ * a missing array is drift, not "the engine found nothing". All four adapters
+ * now require the array and raise `parse_failed` — a recorded divergence for
+ * 阶段5's comparison report. An array that is PRESENT and empty stays a
+ * legitimate zero-result success.
+ */
+declare function requireResultArray(payload: unknown, field: string, providerId: SearchProviderId, label: string): unknown[];
+/** A pre-flight configuration failure. Thrown before any network IO. */
+declare function apiConfigMissing(providerId: SearchProviderId, message: string): SearchProviderError;
+/**
+ * Make upstream text safe to put in an error message.
+ *
+ * Four passes, in this order because each depends on the last not having run:
+ * credential-valued JSON fields go first (they survive even for a key this
+ * process never held), then the configured secret VALUES, then bare
+ * `Bearer`/`Basic` tokens, then whole URLs. Whitespace collapse and the length
+ * cap come last, so the cap can never bisect a secret into a surviving half.
+ *
+ * Exported for the leak gate, which greps the output of every produced error.
+ */
+declare function sanitizeUpstreamText(text: string, secrets?: ReadonlyArray<string | undefined>): string;
+
+/**
+ * `zhipu` and `z.ai` — one wire contract, two provider ids.
+ *
+ * Ported from Elftia's `ZhipuProvider` (sha256 `2a9a0f5b…`, re-verified
+ * byte-identical against the 阶段0 manifest before porting), including the
+ * one-class-two-instances shape: the two services speak the same API and differ
+ * only in their default host, so the id is a constructor argument and the
+ * contributions factory registers two instances.
+ *
+ * Two ported quirks that later stages must not "fix":
+ *
+ * - **`maxResults` defaults to 10**, where every other adapter defaults to 5.
+ *   That is the baseline's behavior and it is preserved deliberately; the
+ *   orchestrator's normalization caps results at what the caller asked for
+ *   anyway.
+ * - **Results carry `link`, not `url`.** The mapping is part of the wire
+ *   contract, not a typo.
+ *
+ * @module search/api/ZhipuSearchProvider
+ */
+
+/** The two ids this one class is registered under. */
+declare const ZHIPU_PROVIDER_ID = "zhipu";
+declare const ZAI_PROVIDER_ID = "z.ai";
+/** Per-id default hosts, as in the baseline. */
+declare const ZHIPU_DEFAULT_HOSTS: Readonly<Record<string, string>>;
+/** The divergent default: 10, where every other adapter uses 5. */
+declare const ZHIPU_DEFAULT_MAX_RESULTS = 10;
+/**
+ * Point a configured host at the `/web_search` endpoint.
+ *
+ * Ported verbatim from the baseline, including which forms it accepts:
+ * an explicit `/web_search` is left alone, a bare version segment (`/v4`) gets
+ * `/web_search` appended, and anything else gets `/v4/web_search`.
+ */
+declare function normalizeZhipuApiUrl(apiHost: string): string;
+declare class ZhipuSearchProvider implements SearchProvider {
+    private readonly config;
+    private readonly transport;
+    readonly id: SearchProviderId;
+    private readonly rotator;
+    constructor(id: SearchProviderId, config: ZhipuProviderConfig, transport?: SearchApiTransport);
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+}
+
+export { API_MAX_REDIRECTS, API_RESPONSE_BYTES, ApiKeyRotator, type ApiSearchContributionOptions, DEFAULT_API_TIMEOUT_MS, JINA_CAPABILITIES, JINA_DEFAULT_HOST, JINA_DEFAULT_MAX_RESULTS, JINA_PROVIDER_ID, JINA_READER_HOST, JinaProviderConfig, JinaReaderClient, JinaSearchProvider, SEARXNG_CAPABILITIES, SEARXNG_DEFAULT_MAX_RESULTS, SEARXNG_PROVIDER_ID, SearchApiFetch, SearchApiProviderConfigs, SearchApiTransport, type SearchApiTransportOptions, SearxngProviderConfig, SearxngSearchProvider, TAVILY_CAPABILITIES, TAVILY_DEFAULT_HOST, TAVILY_DEFAULT_MAX_RESULTS, TAVILY_PROVIDER_ID, TavilyProviderConfig, TavilySearchProvider, ZAI_PROVIDER_ID, ZHIPU_CAPABILITIES, ZHIPU_DEFAULT_HOSTS, ZHIPU_DEFAULT_MAX_RESULTS, ZHIPU_PROVIDER_ID, ZhipuProviderConfig, ZhipuSearchProvider, apiConfigMissing, apiSearchContributions, createSearchApiTransport, defaultSearchApiTransport, normalizeZhipuApiUrl, requireResultArray, sanitizeUpstreamText };