scoutline 0.6.4 → 0.9.0

package/dist/providers/brave/diagnostics.js

@@ -0,0 +1,76 @@
+/**
+ * Brave Diagnostics Capability (brave-tech-plan §3, §7; T5).
+ *
+ * Probes Brave connectivity with a single, cheapest-possible request
+ * — one `/res/v1/web/search` GET with a stub query — so the doctor
+ * command can verify a credential authenticates without a generative
+ * request. Brave has no `search_depth`-style knob (unlike Tavily), so
+ * the probe sends a bare `q` and no other params.
+ *
+ * The probe performs exactly ONE attempt. Shared execution owns the
+ * retry policy; this transport never retries. The doctor command
+ * catches the throw on failure and records a redacted error entry.
+ *
+ * When `options.probe` is false, `invoke` resolves immediately without
+ * touching the network — the doctor command skips probing unconfigured
+ * Providers (passing `probe: false`) before reaching this Capability.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import the diagnostics capability contract, Adapter-local
+ *     credentials, Adapter-local search transport, and normalized errors.
+ *   - Must NOT import command presentation or another Provider's Adapter.
+ */
+import { ApiError, AuthError, ConfigurationError, NetworkError, TimeoutError, } from "../../lib/errors.js";
+import { requireBraveApiKey } from "./credentials.js";
+import { fetchBraveSearch } from "./client.js";
+// ---------------------------------------------------------------------------
+// Failure normalization (mirror the Adapter's search-path mapping)
+// ---------------------------------------------------------------------------
+/**
+ * Probe failure wrapper. Mirrors the Adapter's `normalizeBraveError`
+ * for the subset of errors the probe can surface. The probe throws on
+ * failure; the doctor command catches the throw and records a redacted
+ * error entry. The Brave transport already drains/discards response
+ * bodies, and these typed errors carry only curated messages, so no
+ * raw Brave body ever crosses this boundary.
+ */
+function normalizeProbeError(error) {
+    if (error instanceof AuthError ||
+        error instanceof ApiError ||
+        error instanceof NetworkError ||
+        error instanceof TimeoutError ||
+        error instanceof ConfigurationError) {
+        return error;
+    }
+    return new ApiError("Brave diagnostics probe failed", 500);
+}
+/**
+ * Build the Brave DiagnosticsCapability. The probe performs ONE
+ * `/res/v1/web/search` request with a stub query (`scoutline-doctor-
+ * probe`) and no params — the cheapest credible probe. Shared
+ * execution owns the retry policy; this transport performs exactly one
+ * attempt per invocation.
+ *
+ * When `options.probe` is false, `invoke` resolves immediately without
+ * touching the network — the doctor command skips probing unconfigured
+ * Providers before reaching this Capability.
+ */
+export function createBraveDiagnosticsCapability(options) {
+    const { env, transport } = options;
+    return {
+        async invoke(diagOptions) {
+            if (!diagOptions.probe)
+                return;
+            const apiKey = requireBraveApiKey(env);
+            try {
+                // One web-search GET, bare `q`, no params — cheapest credible
+                // probe (Brave has no search_depth knob).
+                await fetchBraveSearch(apiKey, "scoutline-doctor-probe", undefined, transport);
+            }
+            catch (error) {
+                throw normalizeProbeError(error);
+            }
+        },
+    };
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/providers/brave/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../../src/providers/brave/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,kBAAkB,EAClB,YAAY,EACZ,YAAY,GACb,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAA2B,MAAM,aAAa,CAAC;AAExE,8EAA8E;AAC9E,mEAAmE;AACnE,8EAA8E;AAE9E;;;;;;;GAOG;AACH,SAAS,mBAAmB,CAAC,KAAc;IACzC,IACE,KAAK,YAAY,SAAS;QAC1B,KAAK,YAAY,QAAQ;QACzB,KAAK,YAAY,YAAY;QAC7B,KAAK,YAAY,YAAY;QAC7B,KAAK,YAAY,kBAAkB,EACnC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,gCAAgC,EAAE,GAAG,CAAC,CAAC;AAC7D,CAAC;AAgBD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gCAAgC,CAC9C,OAA0C;IAE1C,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IACnC,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,WAA8B;YACzC,IAAI,CAAC,WAAW,CAAC,KAAK;gBAAE,OAAO;YAC/B,MAAM,MAAM,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;YACvC,IAAI,CAAC;gBACH,8DAA8D;gBAC9D,0CAA0C;gBAC1C,MAAM,gBAAgB,CAAC,MAAM,EAAE,wBAAwB,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;YACjF,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,mBAAmB,CAAC,KAAK,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/providers/brave/quota.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Brave Quota Capability (brave-tech-plan §3.5, §7, §10 #5; T6).
+ *
+ * Brave has NO `/usage` endpoint, so quota is read from the four
+ * `X-RateLimit-*` response headers on a 1-query `/web/search` probe.
+ * The normalizer is pure; the capability factory owns configuration
+ * resolution, the single direct transport attempt, and failure
+ * normalization. Shared execution owns retry policy.
+ *
+ * Brave rate-limit mapping (brave-tech-plan §10):
+ *   - `X-RateLimit-Policy` declares the windows as `"<limit>;w=<sec>"`
+ *     entries separated by `,` (e.g. `"1;w=1, 15000;w=2592000"`).
+ *   - `X-RateLimit-Limit` / `-Remaining` / `-Reset` are comma-separated
+ *     arrays ALIGNED with Policy by index.
+ *
+ * The LARGEST window (≈ monthly) is surfaced as a single "monthly"
+ * category; the per-second window is DROPPED — a rate cap does not fit
+ * the used/limit shape and there is no numeric metadata slot in
+ * {@link ProviderQuotaSuccess} (critique H3). Because the number is a
+ * rate-limit window, NOT spend or credits consumed under Brave's
+ * metered billing, a prominent caveat is attached via the generic
+ * `warnings` channel so the quota command can render it to stderr
+ * without learning Brave's billing model.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import the quota capability contract, Adapter-local config,
+ *     Adapter-local quota client, and normalized errors.
+ *   - Must NOT import command presentation or another Provider's
+ *     Adapter.
+ */
+import type { ProviderQuotaSuccess, QuotaCapability } from "../../capabilities/quota.js";
+import { type BraveTransportDeps } from "./client.js";
+/**
+ * Caveat attached to every Brave quota result: the number is a
+ * rate-limit window (requests remaining this period), NOT spend or
+ * credits consumed. Brave uses metered billing, so this is not a budget
+ * signal. Surfaced to stderr by the provider-neutral quota command.
+ */
+export declare const BRAVE_QUOTA_CAVEAT = "Brave quota reflects a rate-limit window (requests remaining this period), not spend or credits consumed. Brave uses metered billing \u2014 this is not a budget signal.";
+/**
+ * Normalize Brave `X-RateLimit-*` headers into the shared Interface.
+ *
+ * Selects the LARGEST `windowSeconds` window declared by `Policy` (≈
+ * monthly) and surfaces it as a single category named for that window
+ * (monthly/weekly/daily, else `rate_limit`); the per-second window is
+ * dropped. For the selected window: `used = limit −
+ * remaining` (clamped to `[0, limit]` when remaining is out of range),
+ * `resetsAt = now + reset*1000ms`, `durationSeconds = windowSeconds`.
+ *
+ * Throws `QUOTA_ERROR` when the headers are missing/malformed, when no
+ * window parses, or when the selected window's limit/remaining/reset
+ * values are indeterminate (e.g. the arrays do not align by index).
+ * Never guesses; never crashes.
+ */
+export declare function normalizeBraveQuota(headers: {
+    readonly limit: string | null;
+    readonly policy: string | null;
+    readonly remaining: string | null;
+    readonly reset: string | null;
+}, 
+/**
+ * Injectable clock for the `resetsAt` derivation (`now + reset·s`).
+ * Defaults to `Date.now`; tests pass a fixed value to assert the exact
+ * ISO timestamp rather than a non-deterministic "now"-relative value.
+ */
+now?: () => number): ProviderQuotaSuccess;
+/**
+ * Options for the Brave QuotaCapability. The API key is resolved from
+ * `env`; transport dependencies (`fetch`, timer) are injectable for
+ * deterministic tests through the unified `transport` seam.
+ */
+export interface BraveQuotaCapabilityOptions {
+    readonly env: NodeJS.ProcessEnv;
+    readonly transport?: BraveTransportDeps;
+    /** Optional injectable clock for deterministic `resetsAt` in tests. */
+    readonly now?: () => number;
+}
+/**
+ * Build the Brave QuotaCapability. `invoke` resolves the API key,
+ * performs one direct `/web/search` probe (costs exactly ONE request),
+ * reads the `X-RateLimit-*` headers, and normalizes the largest window
+ * into the shared Interface. Shared execution wraps this in the retry
+ * policy; quota never uses the response cache.
+ */
+export declare function createBraveQuotaCapability(options: BraveQuotaCapabilityOptions): QuotaCapability;
+//# sourceMappingURL=quota.d.ts.map

package/dist/providers/brave/quota.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota.d.ts","sourceRoot":"","sources":["../../../src/providers/brave/quota.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,eAAe,EAEhB,MAAM,6BAA6B,CAAC;AAWrC,OAAO,EAAuB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE3E;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,6KACwI,CAAC;AA8DxK;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE;IACP,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AACD;;;;GAIG;AACH,GAAG,GAAE,MAAM,MAAiB,GAC3B,oBAAoB,CAiGtB;AA6BD;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IACxC,uEAAuE;IACvE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,2BAA2B,GAAG,eAAe,CAahG"}

package/dist/providers/brave/quota.js

@@ -0,0 +1,247 @@
+/**
+ * Brave Quota Capability (brave-tech-plan §3.5, §7, §10 #5; T6).
+ *
+ * Brave has NO `/usage` endpoint, so quota is read from the four
+ * `X-RateLimit-*` response headers on a 1-query `/web/search` probe.
+ * The normalizer is pure; the capability factory owns configuration
+ * resolution, the single direct transport attempt, and failure
+ * normalization. Shared execution owns retry policy.
+ *
+ * Brave rate-limit mapping (brave-tech-plan §10):
+ *   - `X-RateLimit-Policy` declares the windows as `"<limit>;w=<sec>"`
+ *     entries separated by `,` (e.g. `"1;w=1, 15000;w=2592000"`).
+ *   - `X-RateLimit-Limit` / `-Remaining` / `-Reset` are comma-separated
+ *     arrays ALIGNED with Policy by index.
+ *
+ * The LARGEST window (≈ monthly) is surfaced as a single "monthly"
+ * category; the per-second window is DROPPED — a rate cap does not fit
+ * the used/limit shape and there is no numeric metadata slot in
+ * {@link ProviderQuotaSuccess} (critique H3). Because the number is a
+ * rate-limit window, NOT spend or credits consumed under Brave's
+ * metered billing, a prominent caveat is attached via the generic
+ * `warnings` channel so the quota command can render it to stderr
+ * without learning Brave's billing model.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import the quota capability contract, Adapter-local config,
+ *     Adapter-local quota client, and normalized errors.
+ *   - Must NOT import command presentation or another Provider's
+ *     Adapter.
+ */
+import { buildQuotaWindow } from "../../capabilities/quota.js";
+import { ApiError, AuthError, ConfigurationError, NetworkError, ScoutlineError, TimeoutError, } from "../../lib/errors.js";
+import { requireBraveApiKey } from "./credentials.js";
+import { fetchBraveRateLimit } from "./client.js";
+/**
+ * Caveat attached to every Brave quota result: the number is a
+ * rate-limit window (requests remaining this period), NOT spend or
+ * credits consumed. Brave uses metered billing, so this is not a budget
+ * signal. Surfaced to stderr by the provider-neutral quota command.
+ */
+export const BRAVE_QUOTA_CAVEAT = "Brave quota reflects a rate-limit window (requests remaining this period), not spend or credits consumed. Brave uses metered billing — this is not a budget signal.";
+/**
+ * Error thrown when the rate-limit headers cannot be parsed into a
+ * usable window. Brave's header format is the only quota signal, so a
+ * malformed/missing/unaligned set is unrecoverable: never guess, never
+ * crash — surface `QUOTA_ERROR` instead.
+ */
+function braveQuotaParseError() {
+    return new ScoutlineError("Brave quota headers could not be parsed", "QUOTA_ERROR", {
+        exitCode: 1,
+    });
+}
+/**
+ * Split a comma-separated header value into trimmed entries. Returns
+ * `null` when the value is absent or blank (no windows to parse).
+ */
+function readHeaderCsv(raw) {
+    if (raw === null || raw.trim() === "")
+        return null;
+    return raw.split(",").map((s) => s.trim());
+}
+/**
+ * Parse a header slot as a finite nonnegative number. Returns `NaN`
+ * (falsy for `Number.isFinite`) when the value is absent or non-numeric
+ * so callers can treat it uniformly as "indeterminate".
+ */
+function parseFiniteNumber(value) {
+    if (value === undefined)
+        return NaN;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : NaN;
+}
+// ---------------------------------------------------------------------------
+// Normalizer
+// ---------------------------------------------------------------------------
+const ONE_DAY_SECONDS = 86400;
+/**
+ * Derive a category name from the selected window's duration so the
+ * label cannot drift from the window it represents (the largest window
+ * is usually ~30 days, but Brave's tiers are not guaranteed monthly).
+ * Falls back to a neutral `rate_limit` for unrecognized window sizes.
+ */
+function rateLimitWindowName(windowSeconds) {
+    if (windowSeconds >= 28 * ONE_DAY_SECONDS)
+        return "monthly";
+    if (windowSeconds >= 6 * ONE_DAY_SECONDS)
+        return "weekly";
+    if (windowSeconds >= ONE_DAY_SECONDS)
+        return "daily";
+    return "rate_limit";
+}
+/**
+ * Normalize Brave `X-RateLimit-*` headers into the shared Interface.
+ *
+ * Selects the LARGEST `windowSeconds` window declared by `Policy` (≈
+ * monthly) and surfaces it as a single category named for that window
+ * (monthly/weekly/daily, else `rate_limit`); the per-second window is
+ * dropped. For the selected window: `used = limit −
+ * remaining` (clamped to `[0, limit]` when remaining is out of range),
+ * `resetsAt = now + reset*1000ms`, `durationSeconds = windowSeconds`.
+ *
+ * Throws `QUOTA_ERROR` when the headers are missing/malformed, when no
+ * window parses, or when the selected window's limit/remaining/reset
+ * values are indeterminate (e.g. the arrays do not align by index).
+ * Never guesses; never crashes.
+ */
+export function normalizeBraveQuota(headers, 
+/**
+ * Injectable clock for the `resetsAt` derivation (`now + reset·s`).
+ * Defaults to `Date.now`; tests pass a fixed value to assert the exact
+ * ISO timestamp rather than a non-deterministic "now"-relative value.
+ */
+now = Date.now) {
+    // Parse Policy into windows: "1;w=1, 15000;w=2592000" → [{1,1},{15000,2592000}]
+    const policyParts = readHeaderCsv(headers.policy);
+    if (policyParts === null) {
+        throw braveQuotaParseError();
+    }
+    const windows = [];
+    for (const part of policyParts) {
+        if (part === "") {
+            throw braveQuotaParseError();
+        }
+        // Each entry is "<limit>;w=<seconds>".
+        const segs = part.split(";").map((s) => s.trim());
+        if (segs.length !== 2 || segs[0] === "" || segs[1] === "") {
+            throw braveQuotaParseError();
+        }
+        const limit = parseFiniteNumber(segs[0]);
+        const wMatch = /^w=(\d+)$/.exec(segs[1]);
+        const windowSeconds = wMatch ? parseFiniteNumber(wMatch[1]) : NaN;
+        if (!Number.isFinite(limit) ||
+            limit < 0 ||
+            !Number.isFinite(windowSeconds) ||
+            windowSeconds <= 0) {
+            throw braveQuotaParseError();
+        }
+        windows.push({ limit, windowSeconds });
+    }
+    if (windows.length === 0) {
+        throw braveQuotaParseError();
+    }
+    // Align Limit/Remaining/Reset arrays by index with Policy windows.
+    const limitParts = readHeaderCsv(headers.limit);
+    const remainingParts = readHeaderCsv(headers.remaining);
+    const resetParts = readHeaderCsv(headers.reset);
+    // Select the LARGEST window with a NON-ZERO limit. A limit of 0 means
+    // "no fixed cap on that period" (e.g. a metered plan's monthly window
+    // reports limit=0/remaining=0), which yields no usable used/remaining
+    // and would otherwise throw — skip such windows and fall back to the
+    // next-largest window that carries a real cap (do NOT hardcode 2592000).
+    let selectedIndex = -1;
+    for (let i = 0; i < windows.length; i++) {
+        if (windows[i].limit <= 0)
+            continue;
+        if (selectedIndex === -1 || windows[i].windowSeconds > windows[selectedIndex].windowSeconds) {
+            selectedIndex = i;
+        }
+    }
+    if (selectedIndex === -1) {
+        throw braveQuotaParseError();
+    }
+    const selectedLimit = parseFiniteNumber(limitParts?.[selectedIndex]);
+    const selectedRemaining = parseFiniteNumber(remainingParts?.[selectedIndex]);
+    const selectedReset = parseFiniteNumber(resetParts?.[selectedIndex]);
+    // The selected window's counts must all be finite nonnegative numbers;
+    // an unaligned/indeterminate set is unrecoverable.
+    if (!Number.isFinite(selectedLimit) ||
+        selectedLimit < 0 ||
+        !Number.isFinite(selectedRemaining) ||
+        selectedRemaining < 0 ||
+        !Number.isFinite(selectedReset) ||
+        selectedReset < 0) {
+        throw braveQuotaParseError();
+    }
+    // used = limit − remaining; clamp to [0, limit] when remaining is out
+    // of range so the derived percentage stays meaningful.
+    let used = selectedLimit - selectedRemaining;
+    if (used < 0)
+        used = 0;
+    if (used > selectedLimit)
+        used = selectedLimit;
+    const resetsAtEpochMs = now() + selectedReset * 1000;
+    const current = buildQuotaWindow({
+        used,
+        limit: selectedLimit,
+        resetsAtEpochMs,
+        durationSeconds: windows[selectedIndex].windowSeconds,
+    });
+    const category = {
+        name: rateLimitWindowName(windows[selectedIndex].windowSeconds),
+        unit: "requests",
+        current,
+    };
+    return {
+        provider: "brave",
+        status: "ok",
+        categories: [category],
+        warnings: [BRAVE_QUOTA_CAVEAT],
+    };
+}
+// ---------------------------------------------------------------------------
+// Capability factory
+// ---------------------------------------------------------------------------
+/**
+ * Map a thrown error into a normalized Brave quota failure. Typed
+ * transport errors (Auth/Api/Network/Timeout/Configuration) pass
+ * through verbatim, as does any {@link ScoutlineError} — notably the
+ * `QUOTA_ERROR` thrown by {@link normalizeBraveQuota} on malformed
+ * headers. Unknown errors become a generic `ApiError 500`. The Brave
+ * transport already drains/discards response bodies, so no raw Brave
+ * body ever crosses this boundary.
+ */
+function normalizeBraveQuotaError(error) {
+    if (error instanceof ScoutlineError ||
+        error instanceof AuthError ||
+        error instanceof ApiError ||
+        error instanceof NetworkError ||
+        error instanceof TimeoutError ||
+        error instanceof ConfigurationError) {
+        return error;
+    }
+    return new ApiError("Brave quota request failed", 500);
+}
+/**
+ * Build the Brave QuotaCapability. `invoke` resolves the API key,
+ * performs one direct `/web/search` probe (costs exactly ONE request),
+ * reads the `X-RateLimit-*` headers, and normalizes the largest window
+ * into the shared Interface. Shared execution wraps this in the retry
+ * policy; quota never uses the response cache.
+ */
+export function createBraveQuotaCapability(options) {
+    const { env, transport, now } = options;
+    return {
+        async invoke() {
+            const apiKey = requireBraveApiKey(env);
+            try {
+                const headers = await fetchBraveRateLimit(apiKey, transport);
+                return normalizeBraveQuota(headers, now);
+            }
+            catch (error) {
+                throw normalizeBraveQuotaError(error);
+            }
+        },
+    };
+}
+//# sourceMappingURL=quota.js.map

package/dist/providers/brave/quota.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota.js","sourceRoot":"","sources":["../../../src/providers/brave/quota.ts"],"names":[],"mappings":"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"}

package/dist/providers/exa/adapter.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Exa Provider Adapter (tech-plan §7, Control Mapping, Field Normalization,
+ * Failure Normalization).
+ *
+ * Implements the Exa Provider Descriptor with Search, Reader, Research,
+ * and Diagnostics capabilities on top of the direct-HTTP transport
+ * (`./client.ts`). The Adapter owns credentials, transport lifecycle,
+ * Provider field mapping, and failure normalization; shared execution
+ * owns cache and retry policy.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import capability types, normalized errors, Provider identity
+ *     types, and the Adapter-local credential and transport Modules.
+ *   - Must NOT import command presentation, output mode, or another
+ *     Provider's Adapter.
+ *
+ * Field mapping (tech-plan §7 Exa mapping):
+ *   Search results[].title          -> title
+ *   Search results[].url            -> url
+ *   Search results[].highlights[]   -> summary (join with " ")
+ *   Search results[].author         -> source
+ *   Search results[].publishedDate  -> date
+ *   Search results[].score          -> (dropped)
+ *
+ * Control mapping (SearchControls → Exa-native API params):
+ *   domain      -> includeDomains: [domain]
+ *   recency     -> startPublishedDate (oneDay→now-1d ISO, etc.)
+ *   contentSize -> type (medium/omitted→"auto", high→"deep")
+ *   topic       -> category (general→omit, news→"news",
+ *                  finance→"financial report")
+ *   location    -> REJECTED (UnsupportedOptionError)
+ */
+import type { ProviderDescriptor } from "../types.js";
+import type { ResearchStateFile } from "../../lib/research-state.js";
+import { type ExaTransportDeps } from "./client.js";
+/**
+ * Dependencies the Exa Adapter accepts. The unified `transport` seam
+ * carries `fetch` and timer injection. Production defaults to the global
+ * `fetch` and timers inside the transport Module.
+ */
+export interface ExaAdapterDependencies {
+    /** Optional transport injection (fetch, timers, env). */
+    readonly transport?: ExaTransportDeps;
+    /** Optional Research state-file port (tech-plan §3). */
+    readonly researchStateFile?: ResearchStateFile;
+}
+/**
+ * Build the Exa Provider Descriptor. The descriptor advertises the Exa
+ * capability set (search, reader, research, diagnostics) and constructs
+ * an Adapter whose Capabilities own credentials, transport, Provider
+ * field mapping, and failure normalization. Construction is
+ * side-effect-free; the transport is invoked per Capability call. Tests
+ * pass `transport` (typically a fake-fetch wrapper); production uses
+ * the no-argument factory which resolves to the global `fetch` and
+ * timers inside the transport Module.
+ */
+export declare function createExaDescriptor(dependencies?: ExaAdapterDependencies): ProviderDescriptor;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/providers/exa/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/providers/exa/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,KAAK,EAIV,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAyBrB,OAAO,KAAK,EAAiB,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAkBpF,OAAO,EASL,KAAK,gBAAgB,EACtB,MAAM,aAAa,CAAC;AAGrB;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IACtC,wDAAwD;IACxD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAChD;AAi7BD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,CAAC,EAAE,sBAAsB,GAAG,kBAAkB,CAiC7F"}