@mcoda/codali 0.1.118 → 0.1.119

package/dist/tools/docdex/DocdexTools.d.ts

@@ -13,6 +13,8 @@ import type { DocdexClient } from "../../docdex/DocdexClient.js";
  * no path is given.
  */
 export declare const toRepoRelativePath: (value: string | undefined, workspaceRoot?: string) => string | undefined;
+/** Test seam: forget any open circuit. */
+export declare const resetWebResearchBackoff: () => void;
 /**
  * Judges whether search results actually answer the question.
  *

package/dist/tools/docdex/DocdexTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocdexTools.d.ts","sourceRoot":"","sources":["../../../src/tools/docdex/DocdexTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAuFjE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,MAAM,GAAG,SAAS,EACzB,gBAAgB,MAAM,KACrB,MAAM,GAAG,SAWX,CAAC;AAoHF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvB,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,YAAY,EACpB,UAAS,iBAAsB,KAC9B,cAAc,EAAgE,CAAC"}
+{"version":3,"file":"DocdexTools.d.ts","sourceRoot":"","sources":["../../../src/tools/docdex/DocdexTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAuFjE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,MAAM,GAAG,SAAS,EACzB,gBAAgB,MAAM,KACrB,MAAM,GAAG,SAWX,CAAC;AAyBF,0CAA0C;AAC1C,eAAO,MAAM,uBAAuB,QAAO,IAG1C,CAAC;AAqJF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvB,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,YAAY,EACpB,UAAS,iBAAsB,KAC9B,cAAc,EAAgE,CAAC"}

package/dist/tools/docdex/DocdexTools.js

@@ -107,6 +107,60 @@ export const toRepoRelativePath = (value, workspaceRoot) => {
     candidate = candidate.replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/{2,}/g, "/");
     return candidate || undefined;
 };
+/**
+ * Stops paying for a quota that is already spent.
+ *
+ * Web discovery is metered upstream. When the provider answers 402 — or 401,
+ * 403, 429 — the answer will not change for the next caller, but nothing
+ * remembered that: every question kept asking, and each question asks more than
+ * once, because a search that finds nothing locally falls through to the web
+ * and a cache hit with no content is retried uncached. Measured upstream at
+ * roughly 366 attempts in two hours, about 4,400 a day, which empties a monthly
+ * allowance of 5,000 in a little over a day.
+ *
+ * So the first refusal opens the circuit for everyone until it is due to close.
+ * `Retry-After` decides when, since the provider knows and we are guessing;
+ * the fallback is deliberately short, because staying closed too long is a
+ * self-inflicted outage and reopening early costs one wasted call.
+ */
+const WEB_QUOTA_STATUSES = new Set([401, 402, 403, 429]);
+const DEFAULT_WEB_BACKOFF_MS = 15 * 60000;
+const MAX_WEB_BACKOFF_MS = 60 * 60000;
+let webUnavailableUntilMs = 0;
+let webUnavailableReason = "";
+/** Test seam: forget any open circuit. */
+export const resetWebResearchBackoff = () => {
+    webUnavailableUntilMs = 0;
+    webUnavailableReason = "";
+};
+const retryAfterMsFrom = (error) => {
+    const details = isRecord(error) && isRecord(error.details) ? error.details : undefined;
+    const raw = details?.retry_after_ms ??
+        details?.retryAfterMs ??
+        details?.["retry-after"] ??
+        details?.retryAfter;
+    if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) {
+        // Seconds or milliseconds, depending on who wrote it.
+        return raw < 10000 ? raw * 1000 : raw;
+    }
+    if (typeof raw === "string") {
+        const seconds = Number(raw.trim());
+        if (Number.isFinite(seconds) && seconds > 0)
+            return seconds * 1000;
+    }
+    return undefined;
+};
+const isWebQuotaRefusal = (error) => {
+    const status = isRecord(error) && typeof error.status === "number" ? error.status : undefined;
+    return status !== undefined && WEB_QUOTA_STATUSES.has(status);
+};
+const noteWebRefusal = (error) => {
+    const backoff = Math.min(retryAfterMsFrom(error) ?? DEFAULT_WEB_BACKOFF_MS, MAX_WEB_BACKOFF_MS);
+    webUnavailableUntilMs = Date.now() + backoff;
+    const status = isRecord(error) && typeof error.status === "number" ? error.status : "unknown";
+    webUnavailableReason = `provider returned ${status}; not retrying for ${Math.round(backoff / 60000)}m`;
+};
+const webResearchBlocked = () => Date.now() < webUnavailableUntilMs ? webUnavailableReason : undefined;
 /** Pages to keep from a web research call, and how much of each. */
 const MAX_WEB_PAGES = 6;
 const MAX_WEB_PAGE_CHARS = 6000;
@@ -275,16 +329,20 @@ const docdexToolDefinitions = (client, options) => [
                     // A judge that fails must not block a search that already succeeded.
                 }
             }
-            if (!localAnswers) {
+            if (!localAnswers && !webResearchBlocked()) {
                 try {
                     const web = await client.search(query, { limit, forceWeb: true });
                     if (hasWebFindings(web)) {
                         return toOutput(web);
                     }
                 }
-                catch {
+                catch (error) {
                     // Web discovery being unavailable must not fail a local search that
-                    // simply found nothing. Return the local (empty) result instead.
+                    // simply found nothing. Return the local (empty) result instead — and
+                    // remember a refusal, because every search would otherwise pay to
+                    // rediscover it.
+                    if (isWebQuotaRefusal(error))
+                        noteWebRefusal(error);
                 }
             }
             return toOutput(await withQueryCentredSnippets(client, query, local));
@@ -546,12 +604,28 @@ const docdexToolDefinitions = (client, options) => [
             // a central bank's interest rate came back sourced to this repository's
             // own documentation. Anything genuinely local is what `docdex_search` is
             // for; a caller can still ask for the mixed behaviour explicitly.
-            let result = await client.webResearch(query, {
-                forceWeb: forceWeb ?? true,
-                skipLocalSearch,
-                webLimit,
-                noCache,
-            });
+            const blocked = webResearchBlocked();
+            if (blocked) {
+                // Answering "the web is unavailable" costs nothing; asking again costs
+                // a request from an allowance that is already spent.
+                return toOutput({ query, pages: [], unavailable: blocked });
+            }
+            let result;
+            try {
+                result = await client.webResearch(query, {
+                    forceWeb: forceWeb ?? true,
+                    skipLocalSearch,
+                    webLimit,
+                    noCache,
+                });
+            }
+            catch (error) {
+                if (isWebQuotaRefusal(error)) {
+                    noteWebRefusal(error);
+                    return toOutput({ query, pages: [], unavailable: webResearchBlocked() });
+                }
+                throw error;
+            }
             // A cache hit returns discovery metadata with no page content at all —
             // no web_context, no hits — so the run sees that a search happened and
             // nothing it can quote. Retrying uncached fetches the pages the cache
@@ -568,8 +642,12 @@ const docdexToolDefinitions = (client, options) => [
                         result = fresh;
                     }
                 }
-                catch {
-                    // Keep the cached response rather than failing a search that worked.
+                catch (error) {
+                    // Keep the cached response rather than failing a search that worked —
+                    // but a refusal is worth remembering, so the next question does not
+                    // spend another request discovering the same thing.
+                    if (isWebQuotaRefusal(error))
+                        noteWebRefusal(error);
                 }
             }
             return toOutput(toWebResearchOutput(result));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcoda/codali",
-  "version": "0.1.118",
+  "version": "0.1.119",
   "description": "Standalone tool-runner adapter for mcoda.",
   "type": "module",
   "main": "dist/index.js",
@@ -35,8 +35,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
-    "@mcoda/db": "0.1.118",
-    "@mcoda/shared": "0.1.118"
+    "@mcoda/db": "0.1.119",
+    "@mcoda/shared": "0.1.119"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",