scoutline 0.7.0 → 0.9.0

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

@@ -0,0 +1,161 @@
+/**
+ * Brave direct HTTP transport skeleton (brave-tech-plan §5, §6).
+ *
+ * Performs direct GETs against the Brave Search REST API with an
+ * `X-Subscription-Token: <apiKey>` header. There is NO internal retry —
+ * shared execution owns retry policy. Fetch and timers are injectable
+ * for tests.
+ *
+ * Mirrors `providers/tavily/client.ts` in structure, but SIMPLER in
+ * T1: the foundation only ships the GET transport and a thin
+ * HTTP-status → Scoutline error map. Capability-specific request body
+ * mapping arrives in later tickets (search, quota, etc.) once those
+ * Capability Modules land.
+ *
+ * The fetch dep's response type is the header-bearing
+ * {@link ProviderImageFetchResponse} (not the narrower
+ * {@link ProviderQuotaFetchResponse}) so the future Brave quota
+ * Capability can read `X-RateLimit-*` headers off responses without a
+ * second transport seam. T1 never reads those headers, but reusing the
+ * existing type keeps the seam stable.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import Adapter-local config and normalized errors.
+ *   - May import {@link ProviderImageFetchResponse} from `providers/types.ts`.
+ *   - Must NOT import command presentation, capability contracts, or
+ *     another Provider's Adapter.
+ *   - Must NOT perform response field normalization — the Adapter owns
+ *     that. This module declares Provider-native request paths and
+ *     params only; it never imports a capability contract.
+ */
+import type { ProviderImageFetchResponse } from "../types.js";
+/** Injectable transport dependencies (fetch, timers, env). */
+export interface BraveTransportDeps {
+    readonly fetch?: (input: string, init: Record<string, unknown>) => Promise<ProviderImageFetchResponse>;
+    readonly setTimeout?: typeof setTimeout;
+    readonly clearTimeout?: typeof clearTimeout;
+    readonly env?: NodeJS.ProcessEnv;
+}
+/**
+ * Provider-native search request query params (Brave API field names).
+ * The Adapter maps the Provider-neutral `SearchControls` into these
+ * before calling {@link fetchBraveSearch}; the transport never imports
+ * a capability contract.
+ *
+ * NOTE: `count` is intentionally ABSENT here. Result-count projection
+ * is a client-side concern owned by shared execution (`applyCount`)
+ * AFTER `invoke`+cache; `SearchRequest`/`SearchControls` carry NO
+ * `count` field, so the transport sends only `q` plus the mapped
+ * controls below (`country`/`freshness`). Brave therefore returns its
+ * default page size; `--count` above that is silently capped (no
+ * pagination in T2).
+ */
+export interface BraveSearchParams {
+    readonly country?: string;
+    readonly freshness?: string;
+}
+/**
+ * Perform ONE GET against the Brave Search API. No retry; no response
+ * body in public errors. Returns the parsed JSON body (raw; the
+ * Adapter post-processes into a normalized shape).
+ *
+ * The transport carries `X-Subscription-Token` (NOT
+ * `Authorization: Bearer`) and a `User-Agent: scoutline/<version>`
+ * string read from `package.json` at module load.
+ */
+export declare function getBraveJson(apiKey: string, path: string, params?: Readonly<Record<string, unknown>>, deps?: BraveTransportDeps): Promise<unknown>;
+/**
+ * Perform ONE GET against the Brave `/res/v1/web/search` endpoint. No
+ * retry; no response body in public errors. Returns the parsed JSON
+ * body (raw; the Adapter post-processes into normalized search
+ * sources).
+ *
+ * `params` carries Brave-native API fields already mapped from
+ * `SearchControls` by the Adapter (`country`/`freshness`). The query
+ * is sent as the `q` query-string parameter.
+ */
+export declare function fetchBraveSearch(apiKey: string, query: string, params?: BraveSearchParams, deps?: BraveTransportDeps): Promise<unknown>;
+/**
+ * Perform ONE GET against the Brave `/res/v1/news/search` endpoint. No
+ * retry; no response body in public errors. Returns the parsed JSON
+ * body (raw; the Adapter post-processes into normalized search
+ * sources).
+ *
+ * Dispatched when `controls.topic === "news"`; the web endpoint is the
+ * default. `params` carries the same Brave-native fields as
+ * {@link fetchBraveSearch}.
+ */
+export declare function fetchBraveNewsSearch(apiKey: string, query: string, params?: BraveSearchParams, deps?: BraveTransportDeps): Promise<unknown>;
+/**
+ * Perform ONE GET against the Brave `/res/v1/videos/search` endpoint. No
+ * retry; no response body in public errors. Returns the parsed JSON
+ * body (raw; the Adapter post-processes into normalized search
+ * sources).
+ *
+ * Dispatched when `controls.type === "video"`; precedence is
+ * `video > news > web`. `params` carries the same Brave-native fields
+ * as {@link fetchBraveSearch}.
+ *
+ * NOTE: Brave documents the videos endpoint as a POST body, but GET
+ * with query params covers every field we send (`q`/`country`/
+ * `freshness`) — confirm live, fall back to POST only if GET is
+ * rejected. `count` is intentionally absent (see
+ * {@link BraveSearchParams}); video results are client-side-truncated
+ * via `applyCount` like every provider, and the video endpoint's
+ * default page-size cap is unconfirmed (live gate).
+ */
+export declare function fetchBraveVideoSearch(apiKey: string, query: string, params?: BraveSearchParams, deps?: BraveTransportDeps): Promise<unknown>;
+/**
+ * Perform ONE GET against the Brave LLM Context endpoint
+ * (`/res/v1/llm/context`). No retry; no response body in public errors.
+ * Returns the parsed JSON body (raw; the Adapter post-processes into
+ * normalized search sources).
+ *
+ * Unlike the web/news/video endpoints, LLM Context is **query-keyed** —
+ * it is a richer search that returns extracted passages
+ * (`grounding.generic[]`), NOT a URL-keyed summarizer. It is dispatched
+ * when `controls.contentSize === "high"` (the accepted 4th-meaning
+ * overload of `--content-size`); precedence is `video > high > news >
+ * web`. `high` overrides `topic`, so this path must receive a CLEAN
+ * query (no `topic` keyword appendage); the Adapter is responsible for
+ * that suppression.
+ *
+ * The mapped `country`/`freshness` controls are forwarded alongside
+ * `q` (consistent with the web/news/video paths) so a `high` search
+ * honors `--recency`/`--location` rather than silently dropping them.
+ * Whether LLM Context honors `country`/`freshness` is a live gate; if
+ * it rejects them the failure surfaces as a mapped error rather than a
+ * silent filter drop. `count` is intentionally never forwarded
+ * (`--count` is applied client-side by shared execution); LLM
+ * Context's source-count/token-budget param name is UNCONFIRMED.
+ */
+export declare function fetchBraveLlmContext(apiKey: string, query: string, params?: BraveSearchParams, deps?: BraveTransportDeps): Promise<unknown>;
+/**
+ * The four Brave `X-RateLimit-*` response headers, read as raw strings.
+ * Each is `null` when the header is absent. The quota normalizer parses
+ * these into windows; this transport layer only collects them.
+ */
+export interface BraveRateLimitHeaders {
+    readonly limit: string | null;
+    readonly policy: string | null;
+    readonly remaining: string | null;
+    readonly reset: string | null;
+}
+/**
+ * Perform ONE GET against `/res/v1/web/search` with a stub query and
+ * return the four `X-RateLimit-*` response headers. Brave has NO
+ * `/usage` endpoint, so quota is read from these headers on a 1-query
+ * probe. The probe costs exactly ONE request and sends ONLY `q` — no
+ * `count` (shared execution applies count client-side) and no other
+ * controls.
+ *
+ * Mirrors {@link getBraveJson}'s transport setup (X-Subscription-Token/
+ * Accept/User-Agent headers, AbortController timeout via `BRAVE_TIMEOUT`,
+ * the same HTTP-status → error {@link mapStatusError}, and
+ * {@link normalizeTransportError}). On 2xx the body is DRAINED
+ * (`res.text()`) and discarded — only the headers are needed. On non-2xx
+ * the body is drained and dropped before throwing the mapped error; no
+ * raw Brave body ever reaches an error message.
+ */
+export declare function fetchBraveRateLimit(apiKey: string, deps?: BraveTransportDeps): Promise<BraveRateLimitHeaders>;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/providers/brave/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAW9D,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,CACf,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,UAAU,CAAC;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,YAAY,CAAC;IAC5C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAwED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC1C,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,OAAO,CAAC,CA8ClB;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,iBAAiB,EAC1B,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,OAAO,CAAC,CAElB;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,iBAAiB,EAC1B,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,OAAO,CAAC,CAElB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,iBAAiB,EAC1B,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,OAAO,CAAC,CAElB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,iBAAiB,EAC1B,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,OAAO,CAAC,CAElB;AAMD;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,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;AAKD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,qBAAqB,CAAC,CAgDhC"}

package/dist/providers/brave/client.js

@@ -0,0 +1,297 @@
+/**
+ * Brave direct HTTP transport skeleton (brave-tech-plan §5, §6).
+ *
+ * Performs direct GETs against the Brave Search REST API with an
+ * `X-Subscription-Token: <apiKey>` header. There is NO internal retry —
+ * shared execution owns retry policy. Fetch and timers are injectable
+ * for tests.
+ *
+ * Mirrors `providers/tavily/client.ts` in structure, but SIMPLER in
+ * T1: the foundation only ships the GET transport and a thin
+ * HTTP-status → Scoutline error map. Capability-specific request body
+ * mapping arrives in later tickets (search, quota, etc.) once those
+ * Capability Modules land.
+ *
+ * The fetch dep's response type is the header-bearing
+ * {@link ProviderImageFetchResponse} (not the narrower
+ * {@link ProviderQuotaFetchResponse}) so the future Brave quota
+ * Capability can read `X-RateLimit-*` headers off responses without a
+ * second transport seam. T1 never reads those headers, but reusing the
+ * existing type keeps the seam stable.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import Adapter-local config and normalized errors.
+ *   - May import {@link ProviderImageFetchResponse} from `providers/types.ts`.
+ *   - Must NOT import command presentation, capability contracts, or
+ *     another Provider's Adapter.
+ *   - Must NOT perform response field normalization — the Adapter owns
+ *     that. This module declares Provider-native request paths and
+ *     params only; it never imports a capability contract.
+ */
+import { createRequire } from "node:module";
+import { ApiError, AuthError, NetworkError, TimeoutError } from "../../lib/errors.js";
+const require = createRequire(import.meta.url);
+const { version: VERSION } = require("../../../package.json");
+const BASE_URL = "https://api.search.brave.com";
+const DEFAULT_TIMEOUT_MS = 30000;
+const USER_AGENT = `scoutline/${VERSION}`;
+const TIMEOUT_HELP_TEXT = "Try again or increase timeout with BRAVE_TIMEOUT env var";
+function resolveTimeoutMs(env) {
+    const raw = parseInt(env.BRAVE_TIMEOUT || String(DEFAULT_TIMEOUT_MS), 10);
+    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_TIMEOUT_MS;
+}
+/**
+ * Layer 1 — HTTP-status mapping. Runs BEFORE the body is parsed; on a
+ * non-200 response we discard the body and throw a typed error.
+ *
+ * `timeoutMs` is forwarded so 408/504 can throw `TimeoutError`
+ * carrying the configured duration (and the `BRAVE_TIMEOUT` help text).
+ * The transport never embeds credential material or raw response bodies
+ * in any error message.
+ */
+function mapStatusError(status, timeoutMs) {
+    if (status === 401 || status === 403) {
+        return new AuthError("Brave authentication failed", "BRAVE_SEARCH_API_KEY");
+    }
+    if (status === 408 || status === 504) {
+        return new TimeoutError(timeoutMs, TIMEOUT_HELP_TEXT);
+    }
+    if (status === 429) {
+        return new ApiError("Brave rate limit exceeded", 429);
+    }
+    if (status === 400 || status === 404 || status === 410 || status === 422) {
+        return new ApiError("Brave request failed", status);
+    }
+    if (status >= 500) {
+        return new ApiError("Brave request failed", status);
+    }
+    return new ApiError("Brave request failed", status);
+}
+function normalizeTransportError(err, timeoutMs) {
+    if (err instanceof AuthError || err instanceof ApiError || err instanceof TimeoutError) {
+        return err;
+    }
+    if (err instanceof Error) {
+        if (err.name === "AbortError") {
+            return new TimeoutError(timeoutMs, TIMEOUT_HELP_TEXT);
+        }
+        const lower = err.message.toLowerCase();
+        if (lower.includes("fetch") ||
+            lower.includes("econnrefused") ||
+            lower.includes("econnreset") ||
+            lower.includes("enotfound") ||
+            lower.includes("network")) {
+            return new NetworkError("Brave network error");
+        }
+    }
+    return new ApiError("Brave request failed", 500);
+}
+/**
+ * Build the query string for a GET. Skips `undefined`/`null` values.
+ * Uses `encodeURIComponent` so callers can pass raw strings without
+ * pre-encoding.
+ */
+function buildQueryString(params) {
+    if (!params)
+        return "";
+    const parts = [];
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null)
+            continue;
+        parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+    }
+    return parts.length === 0 ? "" : `?${parts.join("&")}`;
+}
+/**
+ * Perform ONE GET against the Brave Search API. No retry; no response
+ * body in public errors. Returns the parsed JSON body (raw; the
+ * Adapter post-processes into a normalized shape).
+ *
+ * The transport carries `X-Subscription-Token` (NOT
+ * `Authorization: Bearer`) and a `User-Agent: scoutline/<version>`
+ * string read from `package.json` at module load.
+ */
+export async function getBraveJson(apiKey, path, params, deps = {}) {
+    const f = deps.fetch ??
+        fetch;
+    const setT = deps.setTimeout ?? setTimeout;
+    const clearT = deps.clearTimeout ?? clearTimeout;
+    const env = deps.env ?? process.env;
+    const timeoutMs = resolveTimeoutMs(env);
+    const url = `${BASE_URL}${path}${buildQueryString(params)}`;
+    const controller = new AbortController();
+    const timeoutId = setT(() => controller.abort(), timeoutMs);
+    try {
+        const res = await f(url, {
+            method: "GET",
+            headers: {
+                "X-Subscription-Token": apiKey,
+                Accept: "application/json",
+                "User-Agent": USER_AGENT,
+            },
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            // Drain the body to free the socket, then drop it. The body must
+            // NEVER reach the error message (NFR-006).
+            await res.text().catch(() => { });
+            throw mapStatusError(res.status, timeoutMs);
+        }
+        let parsed;
+        try {
+            parsed = await res.json();
+        }
+        catch {
+            throw new ApiError("Brave returned a malformed response", 500);
+        }
+        return parsed;
+    }
+    catch (err) {
+        throw normalizeTransportError(err, timeoutMs);
+    }
+    finally {
+        // Clear the timeout only after body consumption so the AbortController
+        // timeout still covers a stalled/slow response body read.
+        clearT(timeoutId);
+        controller.abort();
+    }
+}
+/**
+ * Perform ONE GET against the Brave `/res/v1/web/search` endpoint. No
+ * retry; no response body in public errors. Returns the parsed JSON
+ * body (raw; the Adapter post-processes into normalized search
+ * sources).
+ *
+ * `params` carries Brave-native API fields already mapped from
+ * `SearchControls` by the Adapter (`country`/`freshness`). The query
+ * is sent as the `q` query-string parameter.
+ */
+export async function fetchBraveSearch(apiKey, query, params, deps = {}) {
+    return getBraveJson(apiKey, "/res/v1/web/search", { q: query, ...(params ?? {}) }, deps);
+}
+/**
+ * Perform ONE GET against the Brave `/res/v1/news/search` endpoint. No
+ * retry; no response body in public errors. Returns the parsed JSON
+ * body (raw; the Adapter post-processes into normalized search
+ * sources).
+ *
+ * Dispatched when `controls.topic === "news"`; the web endpoint is the
+ * default. `params` carries the same Brave-native fields as
+ * {@link fetchBraveSearch}.
+ */
+export async function fetchBraveNewsSearch(apiKey, query, params, deps = {}) {
+    return getBraveJson(apiKey, "/res/v1/news/search", { q: query, ...(params ?? {}) }, deps);
+}
+/**
+ * Perform ONE GET against the Brave `/res/v1/videos/search` endpoint. No
+ * retry; no response body in public errors. Returns the parsed JSON
+ * body (raw; the Adapter post-processes into normalized search
+ * sources).
+ *
+ * Dispatched when `controls.type === "video"`; precedence is
+ * `video > news > web`. `params` carries the same Brave-native fields
+ * as {@link fetchBraveSearch}.
+ *
+ * NOTE: Brave documents the videos endpoint as a POST body, but GET
+ * with query params covers every field we send (`q`/`country`/
+ * `freshness`) — confirm live, fall back to POST only if GET is
+ * rejected. `count` is intentionally absent (see
+ * {@link BraveSearchParams}); video results are client-side-truncated
+ * via `applyCount` like every provider, and the video endpoint's
+ * default page-size cap is unconfirmed (live gate).
+ */
+export async function fetchBraveVideoSearch(apiKey, query, params, deps = {}) {
+    return getBraveJson(apiKey, "/res/v1/videos/search", { q: query, ...(params ?? {}) }, deps);
+}
+/**
+ * Perform ONE GET against the Brave LLM Context endpoint
+ * (`/res/v1/llm/context`). No retry; no response body in public errors.
+ * Returns the parsed JSON body (raw; the Adapter post-processes into
+ * normalized search sources).
+ *
+ * Unlike the web/news/video endpoints, LLM Context is **query-keyed** —
+ * it is a richer search that returns extracted passages
+ * (`grounding.generic[]`), NOT a URL-keyed summarizer. It is dispatched
+ * when `controls.contentSize === "high"` (the accepted 4th-meaning
+ * overload of `--content-size`); precedence is `video > high > news >
+ * web`. `high` overrides `topic`, so this path must receive a CLEAN
+ * query (no `topic` keyword appendage); the Adapter is responsible for
+ * that suppression.
+ *
+ * The mapped `country`/`freshness` controls are forwarded alongside
+ * `q` (consistent with the web/news/video paths) so a `high` search
+ * honors `--recency`/`--location` rather than silently dropping them.
+ * Whether LLM Context honors `country`/`freshness` is a live gate; if
+ * it rejects them the failure surfaces as a mapped error rather than a
+ * silent filter drop. `count` is intentionally never forwarded
+ * (`--count` is applied client-side by shared execution); LLM
+ * Context's source-count/token-budget param name is UNCONFIRMED.
+ */
+export async function fetchBraveLlmContext(apiKey, query, params, deps = {}) {
+    return getBraveJson(apiKey, "/res/v1/llm/context", { q: query, ...(params ?? {}) }, deps);
+}
+/** Cheapest-credible probe query (same stub as diagnostics). */
+const RATE_LIMIT_PROBE_QUERY = "scoutline-quota-probe";
+/**
+ * Perform ONE GET against `/res/v1/web/search` with a stub query and
+ * return the four `X-RateLimit-*` response headers. Brave has NO
+ * `/usage` endpoint, so quota is read from these headers on a 1-query
+ * probe. The probe costs exactly ONE request and sends ONLY `q` — no
+ * `count` (shared execution applies count client-side) and no other
+ * controls.
+ *
+ * Mirrors {@link getBraveJson}'s transport setup (X-Subscription-Token/
+ * Accept/User-Agent headers, AbortController timeout via `BRAVE_TIMEOUT`,
+ * the same HTTP-status → error {@link mapStatusError}, and
+ * {@link normalizeTransportError}). On 2xx the body is DRAINED
+ * (`res.text()`) and discarded — only the headers are needed. On non-2xx
+ * the body is drained and dropped before throwing the mapped error; no
+ * raw Brave body ever reaches an error message.
+ */
+export async function fetchBraveRateLimit(apiKey, deps = {}) {
+    const f = deps.fetch ??
+        fetch;
+    const setT = deps.setTimeout ?? setTimeout;
+    const clearT = deps.clearTimeout ?? clearTimeout;
+    const env = deps.env ?? process.env;
+    const timeoutMs = resolveTimeoutMs(env);
+    const url = `${BASE_URL}/res/v1/web/search${buildQueryString({ q: RATE_LIMIT_PROBE_QUERY })}`;
+    const controller = new AbortController();
+    const timeoutId = setT(() => controller.abort(), timeoutMs);
+    try {
+        const res = await f(url, {
+            method: "GET",
+            headers: {
+                "X-Subscription-Token": apiKey,
+                Accept: "application/json",
+                "User-Agent": USER_AGENT,
+            },
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            // Drain the body to free the socket, then drop it. The body must
+            // NEVER reach the error message (NFR-006).
+            await res.text().catch(() => { });
+            throw mapStatusError(res.status, timeoutMs);
+        }
+        // Only the headers are needed; drain the body to free the socket.
+        await res.text().catch(() => { });
+        const headers = res.headers;
+        return {
+            limit: headers.get("X-RateLimit-Limit"),
+            policy: headers.get("X-RateLimit-Policy"),
+            remaining: headers.get("X-RateLimit-Remaining"),
+            reset: headers.get("X-RateLimit-Reset"),
+        };
+    }
+    catch (err) {
+        throw normalizeTransportError(err, timeoutMs);
+    }
+    finally {
+        // Clear the timeout only after body consumption so the AbortController
+        // timeout still covers a stalled/slow response body read.
+        clearT(timeoutId);
+        controller.abort();
+    }
+}
+//# sourceMappingURL=client.js.map

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

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

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

@@ -0,0 +1,33 @@
+/**
+ * Brave credential resolution (brave-tech-plan §2, §6).
+ *
+ * Single source of truth for the Brave Search API key. Whitespace-only
+ * values are treated as absent, matching the descriptor's `isConfigured`
+ * contract.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import the normalized-error contract only.
+ *   - Must NOT import transport, command presentation, or another
+ *     Provider's Adapter.
+ *
+ * Missing credentials are surfaced as {@link ConfigurationError}
+ * (exit 3), distinct from {@link AuthError} (exit 1) which means the
+ * Provider REJECTED a presented credential.
+ */
+/**
+ * Resolve the Brave API key without throwing. Returns `undefined` when
+ * no non-blank value is present.
+ */
+export declare function resolveBraveApiKey(env: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Resolve the Brave API key or throw {@link ConfigurationError} (exit 3)
+ * when it is missing. Call this at every Capability invocation gate.
+ */
+export declare function requireBraveApiKey(env: NodeJS.ProcessEnv): string;
+/**
+ * True when a non-blank Brave API key is configured. Metadata-only:
+ * performs no transport construction and reads no other Provider's
+ * credentials.
+ */
+export declare function isBraveConfigured(env: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=credentials.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../../src/providers/brave/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAgBH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,GAAG,SAAS,CAE7E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CASjE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAEjE"}

package/dist/providers/brave/credentials.js

@@ -0,0 +1,55 @@
+/**
+ * Brave credential resolution (brave-tech-plan §2, §6).
+ *
+ * Single source of truth for the Brave Search API key. Whitespace-only
+ * values are treated as absent, matching the descriptor's `isConfigured`
+ * contract.
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import the normalized-error contract only.
+ *   - Must NOT import transport, command presentation, or another
+ *     Provider's Adapter.
+ *
+ * Missing credentials are surfaced as {@link ConfigurationError}
+ * (exit 3), distinct from {@link AuthError} (exit 1) which means the
+ * Provider REJECTED a presented credential.
+ */
+import { ConfigurationError } from "../../lib/errors.js";
+const MISSING_KEY_HELP = 'export BRAVE_SEARCH_API_KEY="your-api-key"';
+/**
+ * Pick a non-blank raw value from the environment. Returns the original
+ * (untrimmed) string when it contains at least one non-whitespace
+ * character, otherwise `undefined`.
+ */
+function pickNonBlank(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    return raw.trim().length > 0 ? raw : undefined;
+}
+/**
+ * Resolve the Brave API key without throwing. Returns `undefined` when
+ * no non-blank value is present.
+ */
+export function resolveBraveApiKey(env) {
+    return pickNonBlank(env.BRAVE_SEARCH_API_KEY);
+}
+/**
+ * Resolve the Brave API key or throw {@link ConfigurationError} (exit 3)
+ * when it is missing. Call this at every Capability invocation gate.
+ */
+export function requireBraveApiKey(env) {
+    const key = resolveBraveApiKey(env);
+    if (key === undefined) {
+        throw new ConfigurationError("BRAVE_SEARCH_API_KEY environment variable is required", MISSING_KEY_HELP);
+    }
+    return key;
+}
+/**
+ * True when a non-blank Brave API key is configured. Metadata-only:
+ * performs no transport construction and reads no other Provider's
+ * credentials.
+ */
+export function isBraveConfigured(env) {
+    return resolveBraveApiKey(env) !== undefined;
+}
+//# sourceMappingURL=credentials.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../../../src/providers/brave/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,gBAAgB,GAAG,4CAA4C,CAAC;AAEtE;;;;GAIG;AACH,SAAS,YAAY,CAAC,GAAY;IAChC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC9C,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACjD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAsB;IACvD,OAAO,YAAY,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAsB;IACvD,MAAM,GAAG,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,kBAAkB,CAC1B,uDAAuD,EACvD,gBAAgB,CACjB,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAsB;IACtD,OAAO,kBAAkB,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;AAC/C,CAAC"}

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

@@ -0,0 +1,46 @@
+/**
+ * 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 type { DiagnosticsCapability } from "../../capabilities/diagnostics.js";
+import { type BraveTransportDeps } from "./client.js";
+/**
+ * Options for the Brave DiagnosticsCapability. The API key is resolved
+ * from `env`; transport dependencies (`fetch`, timer) are injectable
+ * for deterministic tests through the unified `transport` seam.
+ */
+export interface BraveDiagnosticsCapabilityOptions {
+    readonly env: NodeJS.ProcessEnv;
+    readonly transport?: BraveTransportDeps;
+}
+/**
+ * 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 declare function createBraveDiagnosticsCapability(options: BraveDiagnosticsCapabilityOptions): DiagnosticsCapability;
+//# sourceMappingURL=diagnostics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/providers/brave/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAqB,MAAM,mCAAmC,CAAC;AASlG,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA+BxE;;;;GAIG;AACH,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,iCAAiC,GACzC,qBAAqB,CAevB"}