echelongraph-mcp 2.6.2 → 2.6.5

package/dist/tools/check_affected.js

@@ -27,6 +27,7 @@
 // The JSON is relayed verbatim as data (#1874): every match keeps kev_listed, ransomware,
 // epss_score, effective_score, effective_severity and score_assessed as the API sent them.
 import * as z from "zod";
+import { GET_CVE_WHOLE, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 const TOOL = "check_affected";
 export const MATCH_PATH = "/api/v1/public/cves/match";
 // handler.go, the four request headers the endpoint reads before the query string.
@@ -125,7 +126,10 @@ const COVERAGE = z.strictObject({
 // Constant strings, so marketing-site lib/mcpToolClaims.test.ts can fold them should it read
 // this file.
 export const CHECK_AFFECTED_TITLE = "Am I affected? (product or package at a version)";
-export const CHECK_AFFECTED_DESCRIPTION = "Whether a product or package at a given version is affected by known CVEs, from the same matcher as echelongraph.io/am-i-affected. Two lookup paths. The CPE path takes product (the NVD CPE product token, such as openssl or nginx) and version, and returns the CVEs whose NVD CPE match criteria name that product with a version range that includes the version; it matches the token across vendors, so each match names the vendor NVD asserts (cpe_vendor) and whether that vendor was verified (vendor_unknown). The registry path takes ecosystem (npm, PyPI, Maven and other OSV ecosystem names), package and version, and decides each OSV advisory record EchelonGraph holds for that package as affected, not affected or undetermined. Read assessed before count: assessed false means the lookup did not evaluate this component, not_assessed_reason says why (product_not_in_cpe_corpus, package_not_cpe_nameable, candidate_load_pending, candidate_window_truncated, package_not_in_advisory_corpus, no_decidable_advisory), the structured result's state is not_assessed, and a count of 0 there must never be reported as not affected. An advisory whose version range cannot be decided at this version is reported as undetermined (undetermined_count, and up to 50 of them in undetermined), never as safe. The answer also carries match_layer (which path answered), capped (the match list stopped at its cap), candidates_capped (not every candidate CVE was loaded), excluded_count (CPE candidates suppressed by the vendor or platform gate), not_affected_count (advisories decided in your favour) and degraded (the lookup ran out of time). Each match carries cve_id, kev_listed, ransomware, epss_score, effective_score, effective_severity and score_assessed (false: EchelonGraph has not scored the CVE yet, so its echelongraph_score is withheld). Product, version, ecosystem and package travel in request headers, never in the URL. Its structured result carries state (measured only when the answer says assessed true), measured_at (null), method (which matcher answered), coverage (assessed and not_assessed_reason first, then the lookup path and the counts above), freshness (null) and notes, with data equal to the API's JSON.";
+export const CHECK_AFFECTED_DESCRIPTION = "Whether a product or package at a given version is affected by known CVEs, from the same matcher as echelongraph.io/am-i-affected. Two lookup paths. The CPE path takes product (the NVD CPE product token, such as openssl or nginx) and version, and returns the CVEs whose NVD CPE match criteria name that product with a version range that includes the version; it matches the token across vendors, so each match names the vendor NVD asserts (cpe_vendor) and whether that vendor was verified (vendor_unknown). The registry path takes ecosystem (npm, PyPI, Maven and other OSV ecosystem names), package and version, and decides each OSV advisory record EchelonGraph holds for that package as affected, not affected or undetermined. Read assessed before count: assessed false means the lookup did not evaluate this component, not_assessed_reason says why (product_not_in_cpe_corpus, package_not_cpe_nameable, candidate_load_pending, candidate_window_truncated, package_not_in_advisory_corpus, no_decidable_advisory), the structured result's state is not_assessed, and a count of 0 there must never be reported as not affected. An advisory whose version range cannot be decided at this version is reported as undetermined (undetermined_count, and up to 50 of them in undetermined), never as safe. The answer also carries match_layer (which path answered), capped (the match list stopped at its cap), candidates_capped (not every candidate CVE was loaded), excluded_count (CPE candidates suppressed by the vendor or platform gate), not_affected_count (advisories decided in your favour) and degraded (the lookup ran out of time). Each match carries cve_id, kev_listed, ransomware, epss_score, effective_score, effective_severity and score_assessed (false: EchelonGraph has not scored the CVE yet, so its echelongraph_score is withheld). Product, version, ecosystem and package travel in request headers, never in the URL. Its structured result carries state (measured only when the answer says assessed true), measured_at (null), method (which matcher answered), coverage (assessed and not_assessed_reason first, then the lookup path and the counts above), freshness (null) and notes, with data equal to the API's JSON." +
+    " " +
+    TEXT_BUDGET_DESCRIPTION +
+    " Cut, the excluded and undetermined samples keep their first 10 entries, each its cve_id and reason, cve_ids keeps its first 10 (each match carries its cve_id), and each match keeps fewer fields, cve_id, kev_listed, ransomware, epss_score, effective_score and score_assessed at least, so that every match stays in the text.";
 export const CHECK_AFFECTED_INPUT = z.object({
     product: z.string().optional().describe("CPE path: the NVD CPE product token, such as openssl, nginx or linux_kernel. Leave out for the registry path."),
     ecosystem: z.string().optional().describe("Registry path: the package's ecosystem, such as npm, PyPI or Maven. Give with package, not with product."),
@@ -164,6 +168,64 @@ function matchesNote(matches) {
     }
     return out;
 }
+// #2783: a production match is about 2,100 characters as pretty JSON, most of it the CVE's
+// description and match_reason, so openssl 3.0.0 (71 matches) was 156,058 characters of text and
+// linux_kernel 5.10.0 (200, the API's cap) 364,408. Past DATA_TEXT_BUDGET each match in the first
+// text block keeps its scores, flags, vendor attribution and match_reason (for a registry match,
+// the advisory interval its version falls inside, which names the fixed version) with the
+// description cut to 200 characters; then the same without the description; then only the fields
+// the description promises; then, for a list at the cap, without cpe_vendor and vendor_unknown;
+// and last without effective_severity, the band of effective_score. kev_listed, ransomware,
+// epss_score, effective_score and score_assessed stay in every level (#2799): the am_i_affected
+// prompt asks for each match's ransomware and epss_score, and through 2.6.3 the last level left
+// them out of every match of a list at the cap (hosted linux_kernel 5.10.0, 200 matches, 1 with
+// known ransomware use, named nowhere in the text). 200 matches with effective_severity beside
+// them are 33,240 characters, past the budget alone, so the band goes first. The lists beside the
+// matches, the excluded sample (up to 50 CPE candidates the vendor or platform gate suppressed,
+// each with a sentence of detail, 13,861 characters for flash_player 10.0.0) and the undetermined
+// sample (up to 50), keep their first 10 entries, each its cve_id and reason, once the first level
+// does not fit with them whole, before any match field that level keeps goes (50 of them beside
+// 200 matches left the last level 120 characters past the budget for flash_player 10.0.0, and
+// 1,071 for a registry answer at the cap with 50 undetermined); and the registry path's cve_ids,
+// which is each match's cve_id in the order of matches (core-backend cve/handler.go), keeps its
+// first 10, so that every match stays in the text, 200 at the cap: this tool has no page to read
+// more from. excluded_count and undetermined_count count every entry. structuredContent.data keeps
+// every list whole.
+const CHECK_AFFECTED_TEXT = {
+    rows: "matches",
+    levels: [
+        {
+            keep: [
+                "cve_id", "severity", "cvss_v3_score", "description", "kev_listed", "ransomware", "epss_score", "echelongraph_score", "echelongraph_severity", "effective_score", "effective_severity",
+                "score_assessed", "score_unassessed_reason", "matched_criteria", "cpe_vendor", "vendor_unknown", "match_confidence", "match_reason", "version_evidence",
+            ],
+            clip: 200,
+        },
+        {
+            keep: [
+                "cve_id", "severity", "cvss_v3_score", "kev_listed", "ransomware", "epss_score", "echelongraph_score", "effective_score", "effective_severity", "score_assessed", "matched_criteria",
+                "cpe_vendor", "vendor_unknown", "match_reason",
+            ],
+            clip: 200,
+        },
+        {
+            keep: [
+                "cve_id", "severity", "cvss_v3_score", "kev_listed", "ransomware", "epss_score", "echelongraph_score", "effective_score", "effective_severity", "score_assessed", "matched_criteria",
+                "cpe_vendor", "vendor_unknown",
+            ],
+            clip: 100,
+        },
+        { keep: ["cve_id", "kev_listed", "ransomware", "epss_score", "effective_score", "effective_severity", "score_assessed", "cpe_vendor", "vendor_unknown"], clip: 100 },
+        { keep: ["cve_id", "kev_listed", "ransomware", "epss_score", "effective_score", "effective_severity", "score_assessed"], clip: 100 },
+        { keep: ["cve_id", "kev_listed", "ransomware", "epss_score", "effective_score", "score_assessed"], clip: 100 },
+    ],
+    sides: [
+        { list: "cve_ids", cap: 10, said: () => "cve_ids lists each match's cve_id, in the order of matches." },
+        { list: "excluded", keep: ["cve_id", "reason"], clip: 100, cap: 10 },
+        { list: "undetermined", keep: ["cve_id", "reason"], clip: 100, cap: 10 },
+    ],
+    whole: `${GET_CVE_WHOLE}, and cve_intel a CVE's affected packages and fixed versions.`,
+};
 async function checkAffected(kit, a) {
     const product = (a.product ?? "").trim();
     const ecosystem = (a.ecosystem ?? "").trim();
@@ -251,7 +313,7 @@ async function checkAffected(kit, a) {
             },
             freshness: null,
             notes: [NO_TIME, NO_FRESHNESS],
-        });
+        }, CHECK_AFFECTED_TEXT);
     }
     catch (e) {
         return kit.crashed(TOOL, e);

package/dist/tools/check_sbom.js

@@ -1,4 +1,5 @@
 import * as z from "zod";
+import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 export const CHECK_SBOM = "check_sbom";
 export const BATCH_PATH = "/api/v1/public/cves/match/batch";
 // The backend's cap per request (cveBatchMaxComponents): the batch size. A longer list is sent
@@ -21,6 +22,10 @@ export const MAX_PURLS = 2000;
 // 60 s), and a call that outlives its client returns nothing at all — not even the partial answer
 // below. From a fresh budget, 1,200 purls (6 batches) go at once; a larger list answers partial
 // with the rest in data.not_sent_purls, for a call a minute later.
+// The budget bounds the whole call, not only when a batch may start (#2756): each batch's request
+// may take at most what is left of it (api()'s init.timeoutMs), so a batch started at 49.9 s is cut
+// off at 50 s and its purls answered as not sent (time_budget), instead of running on for the
+// request timeout (15 s) past the client's and the hosted endpoint's 60 s.
 export const TIME_BUDGET_MS = 50_000;
 // Retry-After 0 is waited this long; a 429 without Retry-After is not retried. At most MAX_WAITS
 // waits per call.
@@ -37,6 +42,12 @@ const NOTE_AFFECTED_MAX = 25;
 const NOTE_CVES_MAX = 5;
 // CycloneDX nests components; this bounds the walk.
 const MAX_DEPTH = 32;
+// The order in which extract() reads and counts the distinct purls (#2799 review): purls as listed;
+// a CycloneDX document's components depth first, each one's nested components right after it
+// (fromCycloneDX); an SPDX document's packages as listed; each purl trimmed and kept at its first
+// place (dedupe). The note says it beside the position from which the purls not sent run, so a
+// second call can rebuild them from its own input whether or not the text cuts not_sent_purls.
+const READ_ORDER = "counted in the order this tool read them (the order of purls, or of the document's components or packages, each component's nested components right after it and before its next sibling, each purl at its first place)";
 const METHOD = "EchelonGraph's registry advisory matcher (POST /api/v1/public/cves/match/batch): each component's purl is mapped to its OSV ecosystem, package name and version, and matched against the affected version ranges EchelonGraph holds from OSV.dev advisory records, the same matcher GET /api/v1/public/cves/match uses when given an ecosystem. No CPE matching, no score, no ranking.";
 // Always in the envelope's notes, whatever the answer: the refusals a model must not read as clean.
 const DISTRO_NOTE = "A deb, apk or rpm purl without a distro qualifier naming its release (for example ?distro=debian-12 or ?distro=alpine-3.20) is not assessed (distro_release_unknown): the advisory corpus is keyed per distro release, and EchelonGraph does not guess one.";
@@ -44,7 +55,51 @@ const CLEAN_NOTE = "Only not_affected is a clean verdict, and only for the advis
 const MEASURED_AT_NOTE = "measured_at is null: the corpus rows are read through a cache whose maximum age the answer states (summary.corpus_cache_max_age_ms), so the answer gives no single time at which they were read.";
 const FRESHNESS_NOTE = "freshness is null: the answer carries no time at which the advisory corpus was last refreshed.";
 export const CHECK_SBOM_TITLE = "Check an SBOM against the advisory corpus";
-export const CHECK_SBOM_DESCRIPTION = "Check a dependency list against EchelonGraph's advisory corpus, one verdict per component. Pass purls (package URLs, up to 2,000 distinct) or sbom (a CycloneDX JSON or SPDX JSON document, as JSON text or as an object, up to 5,000,000 characters). The purls are read from the document by this MCP server and only they are sent to the API, in POST bodies of at most 200 purls each, one after another, never in a URL; the document itself is not sent on. Run from npm, this server is on your machine; over the hosted endpoint (mcp.echelongraph.io) it is EchelonGraph's, and the document is the request body, accepted up to 6 MiB. A component without a purl is counted and not checked. Each purl is mapped to its OSV ecosystem, package name and version and matched against the affected version ranges EchelonGraph holds from OSV.dev advisory records; there is no ranking and no score. data.results holds one row per component sent, in order (index counts across batches), with verdict (affected, not_affected, undetermined or not_assessed), assessed, not_assessed_reason, cve_ids, matches, count, not_affected_count and undetermined_count; data.summary counts the verdicts, summed over the batches (partial is true when any batch's was). not_affected is the only clean verdict. undetermined: advisories name the package but at least one could not be decided at this version and none matched. not_assessed: no verdict at all, because the package is not in the corpus, the purl type has no OSV ecosystem, a deb, apk or rpm purl carries no distro qualifier naming its release (EchelonGraph does not guess one), the version is missing, the lookup failed, or the batch's time budget ran out first (time_budget). Neither undetermined nor not_assessed is clean, and the note gives their counts. The API allows 1,200 components a minute per caller; when it answers 429 with Retry-After, the tool waits as asked and sends the batch again, within 50 seconds per call. When the next wait would pass that, or a batch after the first fails, the tool stops and answers what it has: coverage.not_sent counts the purls not sent and coverage.not_sent_reason says why (time_budget, rate_limited or request_failed), data.not_sent_purls lists them for a later call, and they are not checked and not clean. A list or document with more than 2,000 distinct purls is refused, not truncated: split it. Its structured result carries state (measured when at least one component got a verdict, else not_assessed), measured_at (null: the corpus is read through a cache, so no single read time exists), method, coverage (what the input held, what was sent in how many batches, and what was not sent and why), freshness (null) and notes, with data equal to the API's JSON (for more than one batch, the batches' answers merged); the result's last text block repeats it without data (the first text block) and without the note's sentences (the text block before it), with which notes ends.";
+export const CHECK_SBOM_DESCRIPTION = "Check a dependency list against EchelonGraph's advisory corpus, one verdict per component. Pass purls (package URLs, up to 2,000 distinct) or sbom (a CycloneDX JSON or SPDX JSON document, as JSON text or as an object, up to 5,000,000 characters). The purls are read from the document by this MCP server and only they are sent to the API, in POST bodies of at most 200 purls each, one after another, never in a URL; the document itself is not sent on. Run from npm, this server is on your machine; over the hosted endpoint (mcp.echelongraph.io) it is EchelonGraph's, and the document is the request body, accepted up to 6 MiB. A component without a purl is counted and not checked. Each purl is mapped to its OSV ecosystem, package name and version and matched against the affected version ranges EchelonGraph holds from OSV.dev advisory records; there is no ranking and no score. data.results holds one row per component sent, in order (index counts across batches), with verdict (affected, not_affected, undetermined or not_assessed), assessed, not_assessed_reason, cve_ids, matches, count, not_affected_count and undetermined_count; data.summary counts the verdicts, summed over the batches (partial is true when any batch's was). not_affected is the only clean verdict. undetermined: advisories name the package but at least one could not be decided at this version and none matched. not_assessed: no verdict at all, because the package is not in the corpus, the purl type has no OSV ecosystem, a deb, apk or rpm purl carries no distro qualifier naming its release (EchelonGraph does not guess one), the version is missing, the lookup failed, or the batch's time budget ran out first (time_budget). Neither undetermined nor not_assessed is clean, and the note gives their counts. The API allows 1,200 components a minute per caller; when it answers 429 with Retry-After, the tool waits as asked and sends the batch again, within 50 seconds per call. When the next wait would pass that, or a batch after the first fails, the tool stops and answers what it has: coverage.not_sent counts the purls not sent and coverage.not_sent_reason says why (time_budget, rate_limited or request_failed), data.not_sent_purls lists them for a later call, and they are not checked and not clean. A list or document with more than 2,000 distinct purls is refused, not truncated: split it. Its structured result carries state (measured when at least one component got a verdict, else not_assessed), measured_at (null: the corpus is read through a cache, so no single read time exists), method, coverage (what the input held, what was sent in how many batches, and what was not sent and why), freshness (null) and notes, with data equal to the API's JSON (for more than one batch, the batches' answers merged); the result's last text block repeats it without data (the first text block) and without the note's sentences (the text block before it), with which notes ends." +
+    " " +
+    TEXT_BUDGET_DESCRIPTION +
+    " Cut, each row keeps index, purl, verdict, not_assessed_reason and cve_ids at least, and the rows whose verdict is not_affected, then not_assessed, are left out of the text before any other; not_sent_purls keeps its first 10, and the note says from which position of the input the purls not sent run.";
+// #2783: a production row is about 2,200 characters as pretty JSON, most of it its matches, each
+// a CVE with its description, so the 50-component Juice Shop document was 112,820 characters of
+// text, and 2,000 purls about 1,200,000. Past DATA_TEXT_BUDGET each row in the first text block
+// keeps its verdict, counts and cve_ids, and each match its scores, flags and match_reason (the
+// advisory interval the version falls inside, which names the fixed version) without the
+// description; then the same without match_reason; then only index, purl, verdict,
+// not_assessed_reason and cve_ids. When rows must still go, the clean ones (not_affected) leave
+// first, then the not_assessed ones, both counted in data.summary and the note, so the affected
+// and undetermined rows are the last to leave the text.
+// A call that stops early (a 2,000-purl call from a fresh budget answers 1,200 and is refused the
+// rest with a 429) lists the purls not sent in data.not_sent_purls: 800 of them are some 20,000
+// to 60,000 characters, which the text cannot hold beside the rows. Once the first level does not
+// fit with that list whole, the text keeps its first 10 and the note says which they are: the
+// input's distinct purls from position `sent` + 1 on, in input order, which is how check_sbom read
+// them (x.purls.slice(answers.length * MAX_COMPONENTS)), so a second call can send them without
+// reading the list. noteFor gives that order (READ_ORDER) beside the position, so this sentence
+// points to it.
+export function sbomText(sent) {
+    const matches = ["cve_id", "severity", "effective_severity", "effective_score", "kev_listed", "ransomware", "epss_score", "score_assessed"];
+    const row = ["index", "purl", "ecosystem", "package", "version", "verdict", "assessed", "not_assessed_reason", "count", "not_affected_count", "undetermined_count", "cve_ids"];
+    return {
+        rows: "results",
+        levels: [
+            { keep: [...row, ["matches", [...matches, "match_reason"]]], clip: 200 },
+            { keep: [...row, ["matches", matches]], clip: 200 },
+            { keep: ["index", "purl", "verdict", "not_assessed_reason", "cve_ids"], clip: 100 },
+        ],
+        sides: [
+            {
+                list: "not_sent_purls",
+                cap: 10,
+                said: (_inText, total) => `The ${total} purls not sent are the input's distinct purls from position ${sent + 1} on, counted in the order the note gives for them, so a second call can send them without reading the list.`,
+            },
+        ],
+        leaveOutFirst: { field: "verdict", values: ["not_affected", "not_assessed"], why: "data.summary counts every verdict" },
+        // check_affected cuts its text too past the budget (#2802): only its structuredContent.data is
+        // a component's matches whole.
+        whole: "check_affected, given a row's ecosystem, package and version, returns that component's matches, whole in its structuredContent.data, and cve_intel a CVE's affected packages and fixed versions.",
+        page: (shown) => `To read every row in the text, check ${shown} or fewer purls per call.`,
+    };
+}
 const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 function dedupe(all) {
     const seen = new Set();
@@ -190,9 +245,17 @@ function noteFor(head, x, d, g) {
     if (g.waits > 0) {
         out.push(`The API's component budget (${API_COMPONENTS_PER_MINUTE} components a minute) ran out ${g.waits === 1 ? "once" : `${g.waits} times`}: the tool waited ${Math.round(g.waited_ms / 1000)} s in all, as its Retry-After asked, and sent the batch again.`);
     }
+    // #2799: the position, not only the list. Past DATA_TEXT_BUDGET the first text block keeps the
+    // first 10 of data.not_sent_purls (sbomText), so a model that reads the text alone cannot send
+    // "that list"; the purls not sent are always the input's distinct purls from position sent + 1 on
+    // (x.purls.slice(answers.length * MAX_COMPONENTS)), which it can rebuild from its own input, given
+    // the order they are counted in (READ_ORDER), which this sentence says whenever it gives the
+    // position, not only when the text cuts the list.
     const notSent = g.not_sent_purls.length;
     if (notSent > 0) {
-        out.push(`${plural(notSent, "purl was", "purls were")} NOT sent (not_sent_reason ${g.not_sent_reason}: ${g.not_sent_detail}), so ${notSent === 1 ? "it is" : "they are"} not checked and not clean; data.not_sent_purls lists ${notSent === 1 ? "it" : "them"}: call check_sbom again with purls set to that list${g.not_sent_reason === "request_failed" ? "" : " after a minute"}.`);
+        const one = notSent === 1;
+        const where = one ? `it is the input's distinct purl at position ${g.sent + 1}` : `they are the input's distinct purls from position ${g.sent + 1} on`;
+        out.push(`${plural(notSent, "purl was", "purls were")} NOT sent (not_sent_reason ${g.not_sent_reason}: ${g.not_sent_detail}), so ${one ? "it is" : "they are"} not checked and not clean; ${where}, ${READ_ORDER}, and data.not_sent_purls lists ${one ? "it" : "them"}: call check_sbom again with purls set to ${one ? "it" : "them"}${g.not_sent_reason === "request_failed" ? "" : " after a minute"}.`);
     }
     out.push(`Of the ${components} components checked: ${affected} affected, ${notAffected} not affected, ${undetermined} undetermined, ${notAssessed} not assessed.`);
     const by = field(s, "not_assessed_by_reason");
@@ -289,7 +352,17 @@ export function mergeAnswers(answers) {
     out.results = results;
     return out;
 }
-const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const realSleep = (ms, signal) => new Promise((r) => {
+    if (signal?.aborted)
+        return r();
+    const done = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", done);
+        r();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+});
 export async function checkSbom(deps, a) {
     const tool = CHECK_SBOM;
     const sleep = deps.sleep ?? realSleep;
@@ -317,23 +390,38 @@ export async function checkSbom(deps, a) {
         let waits = 0;
         let waitedMs = 0;
         let stop = null;
+        // The 429 last waited out, for the one way the budget can be gone before anything answered.
+        let waitedFor;
         // One batch at a time, in order; a 429 with Retry-After is waited out and the same batch sent
         // again, while the wait fits in the call's budget.
         while (answers.length < batches.length) {
-            if (answers.length > 0 && now() - started >= TIME_BUDGET_MS) {
+            const left = TIME_BUDGET_MS - (now() - started);
+            if (left <= 0 && answers.length === 0 && waitedFor) {
+                // A wait that ended at the budget's end: no time is left to send the first batch again, and
+                // nothing was measured, so that 429 is the answer, not a request given no time at all.
+                return deps.failed(tool, waitedFor);
+            }
+            if (answers.length > 0 && left <= 0) {
                 stop = { reason: "time_budget", detail: `the call's ${budgetS} s budget ran out after ${answers.length} of ${batches.length} batches` };
                 break;
             }
+            // At most what is left of the budget (#2756): a slow batch is cut off at its end.
             const r = await deps.api(BATCH_PATH, {
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({ components: batches[answers.length].map((purl) => ({ purl })) }),
+                timeoutMs: Math.max(0, left),
+                signal: deps.signal,
             });
             if (r.ok) {
                 answers.push(r.data);
                 status = r.status;
                 continue;
             }
+            // Cancelled (#2775): this batch was cut off, or never sent after a wait the signal ended.
+            // Nothing more is sent, and the answer goes nowhere.
+            if (deps.signal?.aborted)
+                return deps.failed(tool, r);
             if (r.kind === "http" && r.status === 429) {
                 if (r.retryAfter === undefined) {
                     stop = { reason: "rate_limited", detail: "the API answered 429 without a Retry-After to wait for" };
@@ -344,14 +432,19 @@ export async function checkSbom(deps, a) {
                 else {
                     const waitMs = Math.max(MIN_WAIT_MS, r.retryAfter * 1000);
                     if (now() - started + waitMs <= TIME_BUDGET_MS) {
-                        await sleep(waitMs);
+                        await sleep(waitMs, deps.signal);
                         waits++;
                         waitedMs += waitMs;
+                        waitedFor = r;
                         continue;
                     }
                     stop = { reason: "time_budget", detail: `the API answered 429 asking for a wait of ${r.retryAfter} s (Retry-After), which would pass the call's ${budgetS} s budget` };
                 }
             }
+            else if (r.kind === "timeout" && now() - started >= TIME_BUDGET_MS) {
+                // Cut off by the budget, not by the API failing: the purls are not sent for want of time.
+                stop = { reason: "time_budget", detail: `the call's ${budgetS} s budget ran out while batch ${answers.length + 1} of ${batches.length} was unanswered, so it was cut off` };
+            }
             else {
                 stop = { reason: "request_failed", detail: deps.describeFailure(r).replace(/\.$/, "") };
             }
@@ -402,7 +495,7 @@ export async function checkSbom(deps, a) {
             },
             freshness: null,
             notes: [DISTRO_NOTE, CLEAN_NOTE, MEASURED_AT_NOTE, FRESHNESS_NOTE],
-        });
+        }, sbomText(g.sent));
     }
     catch (e) {
         return deps.crashed(tool, e);
@@ -481,7 +574,7 @@ export function checkSbomOutput(envelopeSchema) {
             not_sent_reason: z
                 .enum(["time_budget", "rate_limited", "request_failed"])
                 .nullable()
-                .describe("Why not_sent is above 0: time_budget (the call's 50 s budget ran out, or waiting out the API's Retry-After would pass it), rate_limited (a 429 without Retry-After, or a 429 after 10 waits), request_failed (a batch after the first failed; the note quotes how). null when every purl was sent."),
+                .describe("Why not_sent is above 0: time_budget (the call's 50 s budget ran out, before a batch or while one was unanswered, which is then cut off; or waiting out the API's Retry-After would pass it), rate_limited (a 429 without Retry-After, or a 429 after 10 waits), request_failed (a batch after the first failed; the note quotes how). null when every purl was sent."),
             rate_limit_waits: z.number().int().describe("How many times the API answered 429 and the tool waited its Retry-After before sending the batch again."),
             waited_ms: z.number().int().describe("Milliseconds spent in those waits."),
             not_assessed: z.number().int().nullable().describe("Of those sent, the components with no verdict, as the answer counts them."),
@@ -506,9 +599,12 @@ export function registerCheckSbom(server, deps) {
             sbom: z
                 .union([z.string(), z.record(z.string(), z.unknown())])
                 .optional()
-                .describe("a CycloneDX JSON or SPDX JSON document, as JSON text or as an object; its purls are read here and only they are sent"),
+                .describe("a CycloneDX JSON or SPDX JSON document, as JSON text or as an object; its purls are read by this MCP server and only they are sent to the API; over the hosted endpoint (mcp.echelongraph.io) the document is the request body"),
         }),
         outputSchema: output,
         annotations: deps.annotations,
-    }, async (a) => deps.checked(CHECK_SBOM, output, await checkSbom(deps, a)));
+    }, async (a, ctx) => {
+        const run = checkSbom({ ...deps, signal: ctx.mcpReq.signal }, a);
+        return deps.checked(CHECK_SBOM, output, await (deps.hold ? deps.hold(run) : run));
+    });
 }

package/dist/tools/cve_intel.js

@@ -26,6 +26,7 @@
 // model holds, and says coverage depends on which pollers run.
 import * as z from "zod";
 import { ANNOTATIONS, CVE_ID, NOT_A_FINDING, SHOWN_BASE, api, badInput, boolAt, checked, crashed, envelopeSchema, failed, failure, field, numAt, okHead, opt, strAt, succeeded, } from "../index.js";
+import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 const TOOL = "cve_intel";
 // The sections relayed, in the answer's order, and the keys each failed_sections name covers.
 const LISTS = ["cwes", "exploits", "affected_packages", "fixed_versions", "timeline"];
@@ -59,7 +60,7 @@ const API_ROW_LIMIT = { exploits: 10, affected_packages: 50, fixed_versions: 200
 const TIMELINE_RELAYED = 20;
 const CVE_INTEL_METHOD = "EchelonGraph's per-CVE enrichment (GET /api/v1/public/cves/:id/enrichment). cwes: CWE classifications stored from NVD, GitHub (GHSA) and CVE.org records, each with the source that gave it, named from the MITRE CWE catalog EchelonGraph embeds. exploits: public exploit references from EchelonGraph's cve_exploits records, whose data model holds Metasploit modules (metasploit), Exploit-DB entries (exploit_db), nuclei templates (nuclei_template), GitHub proof-of-concept repositories (github_poc) and vendor proofs of concept (vendor_poc), filled by a curated seed and by one poller per automated source, each run only where it is enabled, so which sources are current depends on the deployment. affected_packages and fixed_versions: package-ecosystem advisory data, each row naming its source. timeline: EchelonGraph's enrichment history for the CVE, newest first.";
 const VERIFIED_STATUS_DESCRIPTION = "verified_status is the label stored with each reference: verified for a Metasploit module, for an Exploit-DB entry Exploit-DB marks verified, and for curated seed rows marked so; reported for a public artefact nothing has confirmed works (nuclei templates, GitHub proofs of concept, unverified Exploit-DB entries); unconfirmed where a curated row says so. It is a label from the source, not a guarantee that the exploit works against a given system.";
-export const CVE_INTEL_DESCRIPTION = `Weakness, public exploit code, affected packages and fixed versions for one CVE, from EchelonGraph's per-CVE enrichment. Returns cwes (each cwe_id with its name and source), exploits (each with kind, source_name, source_url, first_seen_at and verified_status; at most 10, verified first) with exploits_total (every reference on record), exploits_capped (true when exploits lists fewer than exploits_total), exploits_by_kind and exploits_by_status, affected_packages (ecosystem, package_name, version_range, fixed_version), fixed_versions (ecosystem, package_name, vulnerable_range, fixed_version) and timeline (the newest enrichment-history rows, with timeline_total). ${VERIFIED_STATUS_DESCRIPTION} An empty exploits list is not evidence that no public exploit exists: it covers only the sources EchelonGraph ingests, and which of them are polled depends on the deployment. A section the API could not read is named in coverage.sections_failed and left out of data, never relayed as an empty list. Vendor advisories, patches, generated summaries, trending signals and historical incidents are not relayed. Pass a CVE ID like CVE-2021-44228. Its structured result carries state (measured), measured_at (null: each row carries its own time), method, coverage (the sections relayed, failed and left out, and per-list counts), freshness (null) and notes, with data equal to the first text block; the result's last text block repeats it without data and without the note's sentences (the text block before it), with which notes ends.`;
+export const CVE_INTEL_DESCRIPTION = `Weakness, public exploit code, affected packages and fixed versions for one CVE, from EchelonGraph's per-CVE enrichment. Returns cwes (each cwe_id with its name and source), exploits (each with kind, source_name, source_url, first_seen_at and verified_status; at most 10, verified first) with exploits_total (every reference on record), exploits_capped (true when exploits lists fewer than exploits_total), exploits_by_kind and exploits_by_status, affected_packages (ecosystem, package_name, version_range, fixed_version), fixed_versions (ecosystem, package_name, vulnerable_range, fixed_version) and timeline (the newest enrichment-history rows, with timeline_total). ${VERIFIED_STATUS_DESCRIPTION} An empty exploits list is not evidence that no public exploit exists: it covers only the sources EchelonGraph ingests, and which of them are polled depends on the deployment. A section the API could not read is named in coverage.sections_failed and left out of data, never relayed as an empty list. Vendor advisories, patches, generated summaries, trending signals and historical incidents are not relayed. Pass a CVE ID like CVE-2021-44228. Its structured result carries state (measured), measured_at (null: each row carries its own time), method, coverage (the sections relayed, failed and left out, and per-list counts), freshness (null) and notes, with data, which the first text block holds whole up to 30,000 characters; the result's last text block repeats it without data and without the note's sentences (the text block before it), with which notes ends. ${TEXT_BUDGET_DESCRIPTION}`;
 // ── outputSchema ──
 const Rows = (shape) => z.array(z.looseObject(shape));
 const CountMap = z.record(z.string(), z.number());

package/dist/tools/epss_history.js

@@ -1,11 +1,12 @@
 import * as z from "zod";
+import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 const TOOL = "epss_history";
 const CVE_ID = /^CVE-\d{4}-\d{4,}$/i;
 export const EPSS_HISTORY_METHOD = "EchelonGraph's record of FIRST's EPSS scores: the nightly EPSS fetcher overwrites each CVE's epss_score and epss_percentile from FIRST's published file and, for every CVE whose value changed, records the new values with the time it wrote them; this series is those records, oldest first, with repeated records of one change collapsed into the first.";
 const CHANGE_ONLY = "series_kind is change_only: each point is a change EchelonGraph recorded, at the time it recorded it, and a day with no point is not a recorded value, so the series must not be read or redrawn as a daily series; no point here is interpolated.";
 const BEFORE_FIRST = "The value in force before a CVE's first point is not in the series.";
 const NO_FRESHNESS = "freshness is null: the answer does not carry the time of the EPSS fetcher's last completed run.";
-export const EPSS_HISTORY_DESCRIPTION = `How one CVE's EPSS score (FIRST's exploit-prediction probability, 0 to 1, with its percentile) has changed, as EchelonGraph recorded it: points, oldest first, each with at, epss_score and epss_percentile; current, the record's value now (epss_score, epss_percentile, epss_updated_at); series_kind, always change_only; series_starts_at, when EchelonGraph began recording EPSS changes for any CVE; history_rows, points_truncated and latest_point_matches_current. Pass a CVE ID like CVE-2023-44487. The series is change-only: a point is a recorded change, and a day without a point is not a recorded value. Never interpolate it into a daily series. Before series_starts_at nothing was recorded, so a missing point there means not recorded, not unchanged, and the value in force before a CVE's first point is not in the series. latest_point_matches_current false means a change is missing from the series. Its structured result carries state (measured), measured_at (current.epss_updated_at: when EchelonGraph last wrote a changed value, not FIRST's score date), method, coverage (series_kind, series_starts_at, points, points_truncated), freshness (null) and notes, with data equal to the API's JSON; the result's last text block repeats it without data (the first text block) and without the note's sentences (the text block before it), with which notes ends.`;
+export const EPSS_HISTORY_DESCRIPTION = `How one CVE's EPSS score (FIRST's exploit-prediction probability, 0 to 1, with its percentile) has changed, as EchelonGraph recorded it: points, oldest first, each with at, epss_score and epss_percentile; current, the record's value now (epss_score, epss_percentile, epss_updated_at); series_kind, always change_only; series_starts_at, when EchelonGraph began recording EPSS changes for any CVE; history_rows, points_truncated and latest_point_matches_current. Pass a CVE ID like CVE-2023-44487. The series is change-only: a point is a recorded change, and a day without a point is not a recorded value. Never interpolate it into a daily series. Before series_starts_at nothing was recorded, so a missing point there means not recorded, not unchanged, and the value in force before a CVE's first point is not in the series. latest_point_matches_current false means a change is missing from the series. Its structured result carries state (measured), measured_at (current.epss_updated_at: when EchelonGraph last wrote a changed value, not FIRST's score date), method, coverage (series_kind, series_starts_at, points, points_truncated), freshness (null) and notes, with data equal to the API's JSON; the result's last text block repeats it without data (the first text block) and without the note's sentences (the text block before it), with which notes ends. ${TEXT_BUDGET_DESCRIPTION}`;
 // The API's JSON. points, series_kind and current are required: an answer without them is not
 // this series, and a series_kind other than change_only would make every note above wrong, so
 // either is a failure (checked), never relayed.

package/dist/tools/get_cwe.js

@@ -13,11 +13,20 @@
 // the note says it can lag the feed.
 import * as z from "zod";
 import { ANNOTATIONS, api, badInput, checked, crashed, envelopeSchema, failed, field, lenAt, numAt, okHead, opt, rowsScoreNote, strAt, succeeded, } from "../index.js";
+import { GET_CVE_WHOLE, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 const TOOL = "get_cwe";
 const CWE_ARG = /^(?:CWE-)?0*(\d{1,6})$/i;
 const MAX_PAGE = 200;
 const GET_CWE_METHOD = "EchelonGraph's per-CWE listing (GET /api/v1/public/cwes/:cwe_id): the CWE's name and description from the MITRE CWE catalog EchelonGraph embeds (catalog_version), and the active CVEs in EchelonGraph's CVE feed that an NVD, GitHub (GHSA) or CVE.org record classifies under it, rejected and reserved records left out, 50 to a page.";
-export const GET_CWE_DESCRIPTION = `One CWE (weakness class) and the CVEs classified under it. Returns cwe_id, name and description (from the MITRE CWE catalog EchelonGraph embeds, version catalog_version), total (the active CVEs in EchelonGraph's feed that an NVD, GitHub or CVE.org record classifies under it, rejected and reserved records left out), and cves, one page of 50: each with cve_id, severity, cvss_v3_score, echelongraph_score, echelongraph_severity, score_assessed, kev_listed, published and a shortened description. order says how the rows are sorted (CISA-KEV-listed first, then EchelonGraph score); an answer without order does not state its order, and the note says so. page is the page served, page_size its size and max_page the last page the API serves: a later page is answered as max_page, so past max_page pages total counts CVEs no page lists. echelongraph_score is EchelonGraph's score only when score_assessed is true; the note labels each row that is NOT YET SCORED. A total of 0 says that no CVE in EchelonGraph's feed is classified under that CWE, not that none exists. Pass cwe_id like CWE-79 (or 79) and an optional page (1-${MAX_PAGE}). Its structured result carries state (measured), measured_at (null), method, coverage (total, returned, page, page_requested, page_size, max_page), freshness (null) and notes, with data equal to the API's JSON; the result's last text block repeats it without data (the first text block) and without the note's sentences (the text block before it), with which notes ends.`;
+export const GET_CWE_DESCRIPTION = `One CWE (weakness class) and the CVEs classified under it. Returns cwe_id, name and description (from the MITRE CWE catalog EchelonGraph embeds, version catalog_version), total (the active CVEs in EchelonGraph's feed that an NVD, GitHub or CVE.org record classifies under it, rejected and reserved records left out), and cves, one page of 50: each with cve_id, severity, cvss_v3_score, echelongraph_score, echelongraph_severity, score_assessed, kev_listed, published and a shortened description. order says how the rows are sorted (CISA-KEV-listed first, then EchelonGraph score); an answer without order does not state its order, and the note says so. page is the page served, page_size its size and max_page the last page the API serves: a later page is answered as max_page, so past max_page pages total counts CVEs no page lists. echelongraph_score is EchelonGraph's score only when score_assessed is true; the note labels each row that is NOT YET SCORED. A total of 0 says that no CVE in EchelonGraph's feed is classified under that CWE, not that none exists. Pass cwe_id like CWE-79 (or 79) and an optional page (1-${MAX_PAGE}). Its structured result carries state (measured), measured_at (null), method, coverage (total, returned, page, page_requested, page_size, max_page), freshness (null) and notes, with data equal to the API's JSON; the result's last text block repeats it without data (the first text block) and without the note's sentences (the text block before it), with which notes ends. ${TEXT_BUDGET_DESCRIPTION}`;
+// #2783: a page of 50 production rows is about 27,000 characters as pretty JSON (CWE-79, page 1),
+// under the budget once each row is on a line of its own. Past it, each row keeps the fields the
+// description names with its description cut to 120 characters, then rows are left out.
+const GET_CWE_TEXT = {
+    rows: "cves",
+    levels: [{ keep: ["cve_id", "severity", "cvss_v3_score", "echelongraph_score", "echelongraph_severity", "score_assessed", "score_unassessed_reason", "kev_listed", "published", "description"], clip: 120 }],
+    whole: `${GET_CVE_WHOLE}.`,
+};
 function schemas() {
     const row = z.looseObject({
         cve_id: opt(z.string()),
@@ -127,7 +136,7 @@ export async function getCwe(cwe_id, page) {
                 "measured_at is null: a page of CVEs has no single observation time; each row carries its own published date.",
                 "freshness is null: the answer does not say when its cached page was computed.",
             ],
-        });
+        }, GET_CWE_TEXT);
     }
     catch (e) {
         return crashed(TOOL, e);

package/dist/tools/kev_recent.js

@@ -1,4 +1,5 @@
 import * as z from "zod";
+import { GET_CVE_WHOLE, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 const TOOL = "kev_recent";
 const PATH = "/api/v1/public/kev/recent";
 export const KEV_RECENT_MAX_LIMIT = 200;
@@ -6,7 +7,10 @@ const MAX_VENDOR = 128;
 const MAX_CURSOR = 128;
 const KEV_RECENT_METHOD = "EchelonGraph's copy of the CISA KEV catalog: CISA's feed is polled every 5 minutes and each entry is written onto its CVE's record; rows are read from those records, newest kev_added_date first.";
 const KEV_RECENT_COVERAGE = "CISA KEV catalog";
-const KEV_RECENT_DESCRIPTION = "The CVEs CISA has added to its Known Exploited Vulnerabilities (KEV) catalog, newest first, from EchelonGraph's copy of that catalog, which polls CISA's feed every 5 minutes. Each row in kev gives cve_id, kev_added_date (CISA's dateAdded), kev_due_date, kev_vendor, kev_product, kev_vuln_name and kev_ransomware (known ransomware-campaign use), EchelonGraph's severity, cvss_v3_score, epss_score, epss_percentile and eg_kev_tier for the CVE, and our_first_seen_kev, when EchelonGraph's poller first recorded the CVE entering the catalog (null where no such record exists). Filter by since and until (YYYY-MM-DD, inclusive, on kev_added_date; an RFC 3339 timestamp, such as the kev_added_date 2024-04-12T00:00:00Z that CVE records carry, is read as the date written in it, with the time and offset dropped, and anything else is refused), ransomware, and vendor (an exact, case-insensitive match on kev_vendor); page with limit (1 to 200, default 50) and cursor, passing back the previous page's next_cursor with the same filters. Rows within one date are ordered by cve_id. total counts the CVEs matching the filters; kev_listed_total counts every CVE EchelonGraph holds as KEV-listed, and catalog.catalog_count is CISA's own count in the catalog last fetched, so a gap between the two is entries not yet in EchelonGraph's CVE table, which no page returns. CISA's requiredAction and shortDescription are not returned. Its structured result carries state (measured), measured_at (our last successful fetch of CISA's feed, null when the API does not give it), method, coverage (the CISA KEV catalog: total, returned, kev_listed_total, catalog_count, limit, has_more), freshness (last_successful_fetch_at, catalog_version, date_released) and notes, with data equal to the API's JSON; the result's last text block repeats it without data (the first text block) and without the note's sentences (the text block before it), with which notes ends.";
+const KEV_RECENT_DESCRIPTION = "The CVEs CISA has added to its Known Exploited Vulnerabilities (KEV) catalog, newest first, from EchelonGraph's copy of that catalog, which polls CISA's feed every 5 minutes. Each row in kev gives cve_id, kev_added_date (CISA's dateAdded), kev_due_date, kev_vendor, kev_product, kev_vuln_name and kev_ransomware (known ransomware-campaign use), EchelonGraph's severity, cvss_v3_score, epss_score, epss_percentile and eg_kev_tier for the CVE, and our_first_seen_kev, when EchelonGraph's poller first recorded the CVE entering the catalog (null where no such record exists). Filter by since and until (YYYY-MM-DD, inclusive, on kev_added_date; an RFC 3339 timestamp, such as the kev_added_date 2024-04-12T00:00:00Z that CVE records carry, is read as the date written in it, with the time and offset dropped, and anything else is refused), ransomware, and vendor (an exact, case-insensitive match on kev_vendor); page with limit (1 to 200, default 50) and cursor, passing back the previous page's next_cursor with the same filters. Rows within one date are ordered by cve_id. total counts the CVEs matching the filters; kev_listed_total counts every CVE EchelonGraph holds as KEV-listed, and catalog.catalog_count is CISA's own count in the catalog last fetched, so a gap between the two is entries not yet in EchelonGraph's CVE table, which no page returns. CISA's requiredAction and shortDescription are not returned. Its structured result carries state (measured), measured_at (our last successful fetch of CISA's feed, null when the API does not give it), method, coverage (the CISA KEV catalog: total, returned, kev_listed_total, catalog_count, limit, has_more), freshness (last_successful_fetch_at, catalog_version, date_released) and notes, with data equal to the API's JSON; the result's last text block repeats it without data (the first text block) and without the note's sentences (the text block before it), with which notes ends." +
+    " " +
+    TEXT_BUDGET_DESCRIPTION +
+    " Cut, each row keeps fewer fields, cve_id, kev_added_date, kev_vendor and kev_ransomware at least, or rows are left out, and next_cursor still continues after the last row of the page, not of the text.";
 const opt = (t) => t.nullable().optional();
 const KEVRow = z.looseObject({
     cve_id: opt(z.string()),
@@ -121,6 +125,26 @@ const str = (o, ...k) => {
     return typeof v === "string" && v ? v : null;
 };
 const realInstant = (s) => s !== null && Date.parse(s) > 0;
+// #2783: a production row is about 520 characters as pretty JSON, so a page of 200 was 105,925
+// characters of text. Past DATA_TEXT_BUDGET each row in the first text block keeps CISA's fields
+// and EchelonGraph's severity, cvss_v3_score and epss_score; then, if the page is still too long,
+// only cve_id, kev_added_date, kev_vendor, kev_product and kev_ransomware, names cut to 40
+// characters; then without kev_product, which fits a page of 200.
+// next_cursor continues after the page's last row, so the note says how to read any row the text
+// leaves out without skipping it.
+function kevText(a) {
+    return {
+        rows: "kev",
+        levels: [
+            { keep: ["cve_id", "kev_added_date", "kev_due_date", "kev_vendor", "kev_product", "kev_vuln_name", "kev_ransomware", "severity", "cvss_v3_score", "epss_score"], clip: 200 },
+            { keep: ["cve_id", "kev_added_date", "kev_vendor", "kev_product", "kev_ransomware"], clip: 40 },
+            { keep: ["cve_id", "kev_added_date", "kev_vendor", "kev_ransomware"], clip: 40 },
+        ],
+        // A record carries the CISA fields a row leaves out (kev_due_date, kev_product, kev_vuln_name).
+        whole: `${GET_CVE_WHOLE}.`,
+        page: (shown) => `next_cursor continues after the last row of this page, not after the last row in this text: to read the rows left out in the text, call kev_recent again with the same filters${a.cursor?.trim() ? " and cursor" : ""} and a limit of ${shown}, whose rows are the ones in this text, then with that page's next_cursor and a limit of ${shown} or fewer.`,
+    };
+}
 async function kevRecent(d, a) {
     try {
         const h = headersFor(a);
@@ -178,7 +202,7 @@ async function kevRecent(d, a) {
                     ? "measured_at is EchelonGraph's last successful fetch of CISA's feed, the time this copy of the catalog was last confirmed."
                     : "measured_at is null: the answer does not give EchelonGraph's last successful fetch of CISA's feed.",
             ],
-        });
+        }, kevText(a));
     }
     catch (e) {
         return d.crashed(TOOL, e);