scoutline 0.6.4 → 0.9.0

package/dist/lib/research-state.js

@@ -0,0 +1,214 @@
+/**
+ * Research state file — resume mechanism for interrupted research
+ * (tech-plan §3, T07).
+ *
+ * Research costs 4-250 credits per request. A research task runs
+ * asynchronously server-side: POST /research creates it and returns a
+ * `request_id`, then GET /research/{id} polls until completion. If the
+ * CLI exits (Ctrl-C, crash) mid-poll, the task keeps running and
+ * consuming credits. Without a persistence mechanism, the next identical
+ * request would POST a SECOND task — a double charge.
+ *
+ * This module persists `{ requestId, identityHash, createdAt, status }`
+ * to `~/.scoutline/research/<state-hash>.json` so the next invocation of
+ * the same request detects the in-flight task and polls it instead of
+ * creating a new one. The state-hash is deterministic for a given
+ * `{provider, capability, credentialFingerprint, request}` tuple (see
+ * `computeResearchStateHash`).
+ *
+ * Boundary rules (ARCHITECTURE.md §2):
+ *   - May import cache-root resolution and normalized errors.
+ *   - Must NOT import transport, command presentation, or a Provider
+ *     Adapter.
+ *
+ * Resilience contract (tech-plan §3 / G1-G3):
+ *   - `write()` uses `{ flag: "wx" }` for atomic creation. A concurrent
+ *     invocation that finds the file already exists gets EEXIST and
+ *     polls the existing task instead of creating a new one.
+ *   - `read()` catches JSON parse errors, deletes the corrupt file, and
+ *     returns `null` (treated as absent → new task created).
+ *   - `remove()` deletes the file and ignores ENOENT (already gone).
+ */
+import crypto from "node:crypto";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { researchStateDir } from "./cache.js";
+/**
+ * Recursively sort object keys so `JSON.stringify` produces a stable
+ * representation regardless of insertion order. Mirrors the cache module's
+ * `sortKeysDeep` so the same request hashes identically here and in the
+ * response-cache key.
+ */
+function sortKeysDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map((element) => sortKeysDeep(element));
+    }
+    if (value && typeof value === "object") {
+        const input = value;
+        const out = {};
+        for (const key of Object.keys(input).sort()) {
+            out[key] = sortKeysDeep(input[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Compute the deterministic state-file identity hash for a research
+ * request (tech-plan §3 / CR3).
+ *
+ *   state-hash = SHA-256(recursively-key-sorted-JSON({
+ *     provider, capability, credentialFingerprint, request
+ *   }))
+ *
+ * Same canonical approach as `buildProviderCacheKey`'s request hashing,
+ * extended to include provider + capability + credential. Rotating the
+ * API key orphans old state files (correct — the old task belongs to the
+ * old key's billing). The hash never contains a raw credential.
+ */
+export function computeResearchStateHash(input) {
+    const payload = {
+        provider: input.provider,
+        capability: input.capability,
+        credentialFingerprint: input.credentialFingerprint,
+        request: sortKeysDeep(input.request),
+    };
+    return crypto.createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+// ---------------------------------------------------------------------------
+// Production state-file implementation
+// ---------------------------------------------------------------------------
+/**
+ * Build a production {@link ResearchStateFile} backed by files under
+ * `~/.scoutline/research/` (via {@link researchStateDir}). One JSON file
+ * per in-flight task, named `<state-hash>.json`.
+ *
+ * - `write()` atomically creates the file with `{ flag: "wx" }`. A
+ *   concurrent invocation that finds it exists throws EEXIST; the caller
+ *   catches that and polls the existing task.
+ * - `read()` catches JSON parse errors, deletes the corrupt file, and
+ *   returns `null`.
+ * - `remove()` deletes the file and ignores ENOENT.
+ */
+export function createProductionResearchStateFile() {
+    function filePath(identityHash) {
+        return path.join(researchStateDir(), `${identityHash}.json`);
+    }
+    return {
+        async read(identityHash) {
+            if (!identityHash)
+                return null;
+            const file = filePath(identityHash);
+            let raw;
+            try {
+                raw = await fs.readFile(file, "utf8");
+            }
+            catch {
+                return null;
+            }
+            try {
+                const parsed = JSON.parse(raw);
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                    await fs.unlink(file).catch(() => { });
+                    return null;
+                }
+                const obj = parsed;
+                const requestId = obj.requestId;
+                const storedHash = obj.identityHash;
+                const createdAt = obj.createdAt;
+                const status = obj.status;
+                if (typeof requestId !== "string" ||
+                    requestId.length === 0 ||
+                    typeof storedHash !== "string" ||
+                    typeof createdAt !== "string" ||
+                    (status !== "pending" && status !== "in_progress")) {
+                    await fs.unlink(file).catch(() => { });
+                    return null;
+                }
+                return { requestId, identityHash: storedHash, createdAt, status };
+            }
+            catch {
+                // Corrupt JSON — delete the file so the next run creates a fresh
+                // task instead of forever reading garbage.
+                await fs.unlink(file).catch(() => { });
+                return null;
+            }
+        },
+        async write(identityHash, state) {
+            const dir = researchStateDir();
+            await fs.mkdir(dir, { recursive: true });
+            const file = filePath(identityHash);
+            const payload = JSON.stringify(state);
+            // `{ flag: "wx" }` atomically creates the file only if it does not
+            // exist. A concurrent invocation that lost the race gets EEXIST;
+            // the caller catches it and polls the existing task instead of
+            // creating a second one.
+            await fs.writeFile(file, payload, { flag: "wx" });
+        },
+        async remove(identityHash) {
+            const file = filePath(identityHash);
+            await fs.unlink(file).catch((err) => {
+                // ENOENT is expected (already removed, or never written). Swallow
+                // it; any other error re-throws.
+                if (err && err.code === "ENOENT")
+                    return;
+                throw err;
+            });
+        },
+    };
+}
+/**
+ * Convenience helper exported for the Adapter and tests: builds an
+ * in-memory {@link ResearchStateFile} that throws EEXIST on a second
+ * write to the same hash, mirroring the production `{ flag: "wx" }`
+ * contract exactly. The adapter's lifecycle must not depend on whether
+ * the state file is disk-backed or memory-backed.
+ */
+export function createInMemoryResearchStateFile() {
+    const store = new Map();
+    return {
+        store,
+        async read(identityHash) {
+            const raw = store.get(identityHash);
+            if (raw === undefined)
+                return null;
+            try {
+                const parsed = JSON.parse(raw);
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                    store.delete(identityHash);
+                    return null;
+                }
+                const obj = parsed;
+                const requestId = obj.requestId;
+                const storedHash = obj.identityHash;
+                const createdAt = obj.createdAt;
+                const status = obj.status;
+                if (typeof requestId !== "string" ||
+                    requestId.length === 0 ||
+                    typeof storedHash !== "string" ||
+                    typeof createdAt !== "string" ||
+                    (status !== "pending" && status !== "in_progress")) {
+                    store.delete(identityHash);
+                    return null;
+                }
+                return { requestId, identityHash: storedHash, createdAt, status };
+            }
+            catch {
+                store.delete(identityHash);
+                return null;
+            }
+        },
+        async write(identityHash, state) {
+            if (store.has(identityHash)) {
+                const err = new Error(`EEXIST: file already exists, write '${identityHash}.json'`);
+                err.code = "EEXIST";
+                throw err;
+            }
+            store.set(identityHash, JSON.stringify(state));
+        },
+        async remove(identityHash) {
+            store.delete(identityHash);
+        },
+    };
+}
+//# sourceMappingURL=research-state.js.map

package/dist/lib/research-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-state.js","sourceRoot":"","sources":["../../src/lib/research-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAgD9C;;;;;GAKG;AACH,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,KAAgC,CAAC;QAC/C,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAC5C,GAAG,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAA6B;IACpE,MAAM,OAAO,GAAG;QACd,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,qBAAqB,EAAE,KAAK,CAAC,qBAAqB;QAClD,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC;KACrC,CAAC;IACF,OAAO,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACnF,CAAC;AAED,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iCAAiC;IAC/C,SAAS,QAAQ,CAAC,YAAoB;QACpC,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,GAAG,YAAY,OAAO,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,YAAoB;YAC7B,IAAI,CAAC,YAAY;gBAAE,OAAO,IAAI,CAAC;YAC/B,MAAM,IAAI,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;YACpC,IAAI,GAAW,CAAC;YAChB,IAAI,CAAC;gBACH,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YACxC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAI,CAAC;YACd,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;gBAC1C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;oBACnE,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBACtC,OAAO,IAAI,CAAC;gBACd,CAAC;gBACD,MAAM,GAAG,GAAG,MAAiC,CAAC;gBAC9C,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;gBAChC,MAAM,UAAU,GAAG,GAAG,CAAC,YAAY,CAAC;gBACpC,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;gBAChC,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;gBAC1B,IACE,OAAO,SAAS,KAAK,QAAQ;oBAC7B,SAAS,CAAC,MAAM,KAAK,CAAC;oBACtB,OAAO,UAAU,KAAK,QAAQ;oBAC9B,OAAO,SAAS,KAAK,QAAQ;oBAC7B,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,aAAa,CAAC,EAClD,CAAC;oBACD,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;oBACtC,OAAO,IAAI,CAAC;gBACd,CAAC;gBACD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;YACpE,CAAC;YAAC,MAAM,CAAC;gBACP,iEAAiE;gBACjE,2CAA2C;gBAC3C,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;gBACtC,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,YAAoB,EAAE,KAAoB;YACpD,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAC;YAC/B,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACzC,MAAM,IAAI,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;YACpC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACtC,mEAAmE;YACnE,iEAAiE;YACjE,+DAA+D;YAC/D,yBAAyB;YACzB,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,YAAoB;YAC/B,MAAM,IAAI,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;YACpC,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAA0B,EAAE,EAAE;gBACzD,kEAAkE;gBAClE,iCAAiC;gBACjC,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;oBAAE,OAAO;gBACzC,MAAM,GAAG,CAAC;YACZ,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,+BAA+B;IAG7C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,OAAO;QACL,KAAK;QACL,KAAK,CAAC,IAAI,CAAC,YAAoB;YAC7B,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YACpC,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC;YACnC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;gBAC1C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;oBACnE,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;oBAC3B,OAAO,IAAI,CAAC;gBACd,CAAC;gBACD,MAAM,GAAG,GAAG,MAAiC,CAAC;gBAC9C,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;gBAChC,MAAM,UAAU,GAAG,GAAG,CAAC,YAAY,CAAC;gBACpC,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;gBAChC,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;gBAC1B,IACE,OAAO,SAAS,KAAK,QAAQ;oBAC7B,SAAS,CAAC,MAAM,KAAK,CAAC;oBACtB,OAAO,UAAU,KAAK,QAAQ;oBAC9B,OAAO,SAAS,KAAK,QAAQ;oBAC7B,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,aAAa,CAAC,EAClD,CAAC;oBACD,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;oBAC3B,OAAO,IAAI,CAAC;gBACd,CAAC;gBACD,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;YACpE,CAAC;YAAC,MAAM,CAAC;gBACP,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;gBAC3B,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,YAAoB,EAAE,KAAoB;YACpD,IAAI,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;gBAC5B,MAAM,GAAG,GAA0B,IAAI,KAAK,CAC1C,uCAAuC,YAAY,QAAQ,CAC5D,CAAC;gBACF,GAAG,CAAC,IAAI,GAAG,QAAQ,CAAC;gBACpB,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,KAAK,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACjD,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,YAAoB;YAC/B,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAC7B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/lib/search-topic.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Search topic keyword appendage (DESIGN.md §7 — T03).
+ *
+ * Providers that lack a native topic parameter (Z.AI, MiniMax) express
+ * a non-`general` topic by appending a keyword to the query string.
+ * This is adapter-owned field mapping performed inside each Adapter's
+ * `invoke()`, never at the command layer. The Tavily adapter passes the
+ * topic natively (T04) and does not use this helper.
+ *
+ * Guard: when the query already ends with the topic word
+ * (case-insensitive) the appendage is skipped, so `"rust news"` with
+ * `--topic news` stays `"rust news"` rather than `"rust news latest news"`.
+ */
+import type { SearchTopic } from "../capabilities/search.js";
+/**
+ * Append the topic keyword to `query` unless the topic is `general`,
+ * absent, or the query already ends with the topic word. Returns the
+ * query unchanged in all skip cases.
+ */
+export declare function applySearchTopic(query: string, topic: SearchTopic | undefined): string;
+//# sourceMappingURL=search-topic.d.ts.map

package/dist/lib/search-topic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-topic.d.ts","sourceRoot":"","sources":["../../src/lib/search-topic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAO7D;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,CAQtF"}

package/dist/lib/search-topic.js

@@ -0,0 +1,36 @@
+/**
+ * Search topic keyword appendage (DESIGN.md §7 — T03).
+ *
+ * Providers that lack a native topic parameter (Z.AI, MiniMax) express
+ * a non-`general` topic by appending a keyword to the query string.
+ * This is adapter-owned field mapping performed inside each Adapter's
+ * `invoke()`, never at the command layer. The Tavily adapter passes the
+ * topic natively (T04) and does not use this helper.
+ *
+ * Guard: when the query already ends with the topic word
+ * (case-insensitive) the appendage is skipped, so `"rust news"` with
+ * `--topic news` stays `"rust news"` rather than `"rust news latest news"`.
+ */
+const TOPIC_APPENDAGES = {
+    news: " latest news",
+    finance: " financial",
+};
+/**
+ * Append the topic keyword to `query` unless the topic is `general`,
+ * absent, or the query already ends with the topic word. Returns the
+ * query unchanged in all skip cases.
+ */
+export function applySearchTopic(query, topic) {
+    if (!topic || topic === "general")
+        return query;
+    const appendage = TOPIC_APPENDAGES[topic];
+    if (appendage === undefined)
+        return query;
+    const trimmed = query.trimEnd();
+    if (trimmed.length === 0)
+        return query;
+    if (trimmed.toLowerCase().endsWith(topic))
+        return query;
+    return trimmed + appendage;
+}
+//# sourceMappingURL=search-topic.js.map

package/dist/lib/search-topic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-topic.js","sourceRoot":"","sources":["../../src/lib/search-topic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,gBAAgB,GAA8D;IAClF,IAAI,EAAE,cAAc;IACpB,OAAO,EAAE,YAAY;CACtB,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa,EAAE,KAA8B;IAC5E,IAAI,CAAC,KAAK,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAChD,MAAM,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC1C,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;IAChC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACxD,OAAO,OAAO,GAAG,SAAS,CAAC;AAC7B,CAAC"}

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

@@ -0,0 +1,42 @@
+/**
+ * Brave Provider Adapter (brave-tech-plan §2, §5, §6).
+ *
+ * T2 wires the Search Capability (web + news). The descriptor
+ * advertises `"search"` and `create()` returns an Adapter whose
+ * `search` Capability owns credentials, transport, Provider field
+ * mapping, and failure normalization. Credentials, the direct-HTTP GET
+ * transport, and the header-bearing fetch seam come from T1; later
+ * tickets widen the capability set (reader, etc.). T5 wires the
+ * Diagnostics Capability (one-query doctor probe); T6 wires the Quota
+ * Capability (1-query rate-limit-header probe with a spend caveat).
+ *
+ * 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.
+ */
+import type { ProviderDescriptor } from "../types.js";
+import { type BraveTransportDeps } from "./client.js";
+/**
+ * Dependencies the Brave Adapter accepts. The unified `transport`
+ * seam carries `fetch` and timer injection; the Search Capability
+ * threads it through to the direct-HTTP transport.
+ */
+export interface BraveAdapterDependencies {
+    /** Optional transport injection (fetch, timers, env). */
+    readonly transport?: BraveTransportDeps;
+}
+/**
+ * Build the Brave Provider Descriptor. The descriptor advertises the
+ * Search (T2), Diagnostics (T5), and Quota (T6) capabilities and
+ * constructs an Adapter whose `search`/`diagnostics`/`quota`
+ * 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 createBraveDescriptor(dependencies?: BraveAdapterDependencies): ProviderDescriptor;
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/providers/brave/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAIV,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAqBrB,OAAO,EAML,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAIrB;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAweD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,CAAC,EAAE,wBAAwB,GAAG,kBAAkB,CAqBjG"}