@mcoda/codali 0.1.118 → 0.1.120

package/dist/gateway/GatewayPlanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GatewayPlanner.d.ts","sourceRoot":"","sources":["../../src/gateway/GatewayPlanner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GatewayPlanner.d.ts","sourceRoot":"","sources":["../../src/gateway/GatewayPlanner.ts"],"names":[],"mappings":"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"}

package/dist/gateway/GatewayPlanner.js

@@ -1,6 +1,7 @@
 import { validateCodaliGatewayPlannerOutput, } from "./CodaliGatewaySchemas.js";
 import { compileCodaliGatewayPolicy, } from "./GatewayPolicyCompiler.js";
 import { CODALI_GATEWAY_SECURITY_PROMPT_HARDENING } from "./GatewaySecurityPolicy.js";
+import { requestTouchesOwnData } from "./GroundingMode.js";
 import { renderCapabilityLines, renderToolLines } from "./ToolExposure.js";
 import { buildTemporalContext, renderTemporalContext } from "./TemporalContext.js";
 export class CodaliGatewayPlannerError extends Error {
@@ -417,6 +418,12 @@ export const resolveToolNameAgainst = (candidate, available) => {
     const bySuffix = available.filter((tool) => tool.toLowerCase().endsWith(`:${lower}`));
     return bySuffix.length === 1 ? bySuffix[0] : undefined;
 };
+/**
+ * Whether a tool name belongs to a connector into someone's account, as opposed
+ * to a repository search or the public web. Namespaced transports are the
+ * connectors: `mcp:github:list_issues`, `http:jira:search_issues`.
+ */
+const isOwnedSystemConnector = (tool) => tool.startsWith("mcp:") || tool.startsWith("http:");
 const allowedToolNames = (compilation) => [...compilation.effectiveAllowedTools].sort();
 /**
  * Capability names the classifier selected for stage-2 tool expansion. Absent
@@ -518,7 +525,16 @@ export const buildCodaliGatewayClassifierMessages = (input) => {
 };
 export const buildCodaliGatewayPlannerMessages = (input, classifier) => {
     const policy = input.policyCompilation ?? compileCodaliGatewayPolicy({ request: input.request });
-    const tools = allowedToolNames(policy);
+    // A connector reaches into the user's own account, so it is only worth
+    // showing when the request is about their data. Left in view for every
+    // question, the planner picked by surface resemblance — a question about a
+    // company's chief executive went to a GitHub user search, and one about a
+    // language's newest release went to `get_latest_release`. Withholding them
+    // is a narrowing, not a denial: an explicitly allowed tool is still allowed,
+    // this only stops it being suggested for work it cannot do.
+    const tools = requestTouchesOwnData(input.request.query, classifier)
+        ? allowedToolNames(policy)
+        : allowedToolNames(policy).filter((tool) => !isOwnedSystemConnector(tool));
     // Stage 2 of two-level exposure: expand full schemas, but only for the
     // capabilities the classifier selected.
     const exposure = renderToolLines(tools, input.toolDescriptions, classifier.capabilities);

package/dist/gateway/GroundingMode.d.ts

@@ -32,4 +32,14 @@ export interface GroundingDecisionInput {
     classifier: Pick<CodaliGatewayClassifierOutput, "needsPrivateData" | "needsFreshData" | "needsDocdex" | "needsAppTools">;
 }
 export declare const decideGroundingMode: (input: GroundingDecisionInput) => GroundingDecision;
+/**
+ * Whether the request is about data the user owns, and so whether the
+ * connectors that reach their accounts should be offered at all.
+ *
+ * Deliberately generous: a wrong "yes" offers a tool the planner may ignore,
+ * while a wrong "no" hides the only tool that could have answered. So the
+ * classifier's own judgement is honoured first, and either naming the system or
+ * claiming the data is enough.
+ */
+export declare const requestTouchesOwnData: (query: string, classifier: Pick<GroundingDecisionInput["classifier"], "needsPrivateData" | "needsAppTools">) => boolean;
 //# sourceMappingURL=GroundingMode.d.ts.map

package/dist/gateway/GroundingMode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GroundingMode.d.ts","sourceRoot":"","sources":["../../src/gateway/GroundingMode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,MAAM,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,IAAI,CACd,6BAA6B,EAC7B,kBAAkB,GAAG,gBAAgB,GAAG,aAAa,GAAG,eAAe,CACxE,CAAC;CACH;AAiDD,eAAO,MAAM,mBAAmB,GAC9B,OAAO,sBAAsB,KAC5B,iBAoCF,CAAC"}
+{"version":3,"file":"GroundingMode.d.ts","sourceRoot":"","sources":["../../src/gateway/GroundingMode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,MAAM,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,IAAI,CACd,6BAA6B,EAC7B,kBAAkB,GAAG,gBAAgB,GAAG,aAAa,GAAG,eAAe,CACxE,CAAC;CACH;AAiDD,eAAO,MAAM,mBAAmB,GAC9B,OAAO,sBAAsB,KAC5B,iBAoCF,CAAC;AAcF;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,GAChC,OAAO,MAAM,EACb,YAAY,IAAI,CAAC,sBAAsB,CAAC,YAAY,CAAC,EAAE,kBAAkB,GAAG,eAAe,CAAC,KAC3F,OAImC,CAAC"}

package/dist/gateway/GroundingMode.js

@@ -67,3 +67,26 @@ export const decideGroundingMode = (input) => {
     }
     return { mode: "grounded", reason: "default" };
 };
+/**
+ * Systems a request has to name before a connector to them is worth offering.
+ *
+ * A product connector reaches into somebody's account. Offering every one of
+ * them to every question invited the planner to pick by surface resemblance:
+ * asked who currently runs Microsoft it called `mcp:github:search_users`, and
+ * asked for the newest Node.js release it called `get_latest_release`. Both are
+ * public facts about a company, and neither is in anyone's account.
+ */
+const OWNED_SYSTEM_NOUNS = /\b(?:github|gitlab|bitbucket|jira|confluence|outlook|teams|calendar|inbox|mailbox|repository|repositories|repo|commit|commits|branch|branches|pull request|merge request|issue|issues|ticket|tickets|workspace|tenant)\b/i;
+/**
+ * Whether the request is about data the user owns, and so whether the
+ * connectors that reach their accounts should be offered at all.
+ *
+ * Deliberately generous: a wrong "yes" offers a tool the planner may ignore,
+ * while a wrong "no" hides the only tool that could have answered. So the
+ * classifier's own judgement is honoured first, and either naming the system or
+ * claiming the data is enough.
+ */
+export const requestTouchesOwnData = (query, classifier) => classifier.needsPrivateData === true ||
+    classifier.needsAppTools === true ||
+    POSSESSIVE.test(query ?? "") ||
+    OWNED_SYSTEM_NOUNS.test(query ?? "");

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.120",
   "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.120",
+    "@mcoda/shared": "0.1.120"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",