@mcoda/codali 0.1.120 → 0.1.122

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

@@ -15,6 +15,7 @@ import type { DocdexClient } from "../../docdex/DocdexClient.js";
 export declare const toRepoRelativePath: (value: string | undefined, workspaceRoot?: string) => string | undefined;
 /** Test seam: forget any open circuit. */
 export declare const resetWebResearchBackoff: () => void;
+export declare const normalizeWebQuery: (value: unknown) => string | undefined;
 /**
  * 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;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"}
+{"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;AAwCF,0CAA0C;AAC1C,eAAO,MAAM,uBAAuB,QAAO,IAG1C,CAAC;AA0DF,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAO3D,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"}

package/dist/tools/docdex/DocdexTools.js

@@ -123,8 +123,23 @@ export const toRepoRelativePath = (value, workspaceRoot) => {
  * 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]);
+/**
+ * Two kinds of refusal, and they deserve different patience.
+ *
+ * A spent quota or a rejected credential will still be spent and still be
+ * rejected in a minute, so the sensible default is long. A rate limit or a
+ * service restarting is over in seconds, and blocking for a quarter of an hour
+ * because a container was recreated would turn a blip into an outage of our
+ * own making.
+ *
+ * `Retry-After` overrides both, because the provider knows and we are guessing.
+ * The upstream gateway now answers a cold start with 503 and a `Retry-After`
+ * rather than a bodyless 502, which is precisely the case this handles.
+ */
+const WEB_EXHAUSTED_STATUSES = new Set([401, 402, 403]);
+const WEB_TRANSIENT_STATUSES = new Set([429, 503]);
 const DEFAULT_WEB_BACKOFF_MS = 15 * 60000;
+const TRANSIENT_WEB_BACKOFF_MS = 30000;
 const MAX_WEB_BACKOFF_MS = 60 * 60000;
 let webUnavailableUntilMs = 0;
 let webUnavailableReason = "";
@@ -150,17 +165,49 @@ const retryAfterMsFrom = (error) => {
     }
     return undefined;
 };
-const isWebQuotaRefusal = (error) => {
+const webRefusalStatus = (error) => {
     const status = isRecord(error) && typeof error.status === "number" ? error.status : undefined;
-    return status !== undefined && WEB_QUOTA_STATUSES.has(status);
+    if (status === undefined)
+        return undefined;
+    return WEB_EXHAUSTED_STATUSES.has(status) || WEB_TRANSIENT_STATUSES.has(status)
+        ? status
+        : undefined;
 };
+const isWebQuotaRefusal = (error) => webRefusalStatus(error) !== undefined;
 const noteWebRefusal = (error) => {
-    const backoff = Math.min(retryAfterMsFrom(error) ?? DEFAULT_WEB_BACKOFF_MS, MAX_WEB_BACKOFF_MS);
+    const status = webRefusalStatus(error);
+    const fallback = status !== undefined && WEB_TRANSIENT_STATUSES.has(status)
+        ? TRANSIENT_WEB_BACKOFF_MS
+        : DEFAULT_WEB_BACKOFF_MS;
+    const backoff = Math.min(retryAfterMsFrom(error) ?? fallback, 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`;
+    webUnavailableReason =
+        `provider returned ${status ?? "unknown"}; not retrying for ` +
+            (backoff < 60000 ? `${Math.round(backoff / 1000)}s` : `${Math.round(backoff / 60000)}m`);
 };
 const webResearchBlocked = () => Date.now() < webUnavailableUntilMs ? webUnavailableReason : undefined;
+/**
+ * Normalises a query before it costs a metered request.
+ *
+ * The schema asks for a string and a model can satisfy that with whitespace, or
+ * with a whole paragraph of pasted context. Both are rejected upstream, and a
+ * rejected request still spends the allowance: measured at the gateway, a third
+ * of an hour's traffic was 400s rather than answers.
+ *
+ * A search query is a phrase. Beyond a couple of hundred characters it is not a
+ * query any more, and the useful part is at the front.
+ */
+const MAX_WEB_QUERY_CHARS = 400;
+export const normalizeWebQuery = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    const collapsed = value.replace(/\s+/g, " ").trim();
+    if (!collapsed)
+        return undefined;
+    return collapsed.length > MAX_WEB_QUERY_CHARS
+        ? collapsed.slice(0, MAX_WEB_QUERY_CHARS).trimEnd()
+        : collapsed;
+};
 /** Pages to keep from a web research call, and how much of each. */
 const MAX_WEB_PAGES = 6;
 const MAX_WEB_PAGE_CHARS = 6000;
@@ -329,9 +376,10 @@ const docdexToolDefinitions = (client, options) => [
                     // A judge that fails must not block a search that already succeeded.
                 }
             }
-            if (!localAnswers && !webResearchBlocked()) {
+            const webQuery = normalizeWebQuery(query);
+            if (!localAnswers && webQuery && !webResearchBlocked()) {
                 try {
-                    const web = await client.search(query, { limit, forceWeb: true });
+                    const web = await client.search(webQuery, { limit, forceWeb: true });
                     if (hasWebFindings(web)) {
                         return toOutput(web);
                     }
@@ -604,6 +652,11 @@ 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.
+            const normalizedQuery = normalizeWebQuery(query);
+            if (!normalizedQuery) {
+                // Spending a metered request to be told this is malformed helps nobody.
+                return toOutput({ query, pages: [], unavailable: "empty query" });
+            }
             const blocked = webResearchBlocked();
             if (blocked) {
                 // Answering "the web is unavailable" costs nothing; asking again costs
@@ -612,7 +665,7 @@ const docdexToolDefinitions = (client, options) => [
             }
             let result;
             try {
-                result = await client.webResearch(query, {
+                result = await client.webResearch(normalizedQuery, {
                     forceWeb: forceWeb ?? true,
                     skipLocalSearch,
                     webLimit,
@@ -632,7 +685,7 @@ const docdexToolDefinitions = (client, options) => [
             // was standing in for.
             if (!noCache && !hasWebContent(result)) {
                 try {
-                    const fresh = await client.webResearch(query, {
+                    const fresh = await client.webResearch(normalizedQuery, {
                         forceWeb: forceWeb ?? true,
                         skipLocalSearch,
                         webLimit,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcoda/codali",
-  "version": "0.1.120",
+  "version": "0.1.122",
   "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.120",
-    "@mcoda/shared": "0.1.120"
+    "@mcoda/db": "0.1.122",
+    "@mcoda/shared": "0.1.122"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",