echelongraph-mcp 2.6.3 → 2.6.5

package/dist/index.js

@@ -27,19 +27,23 @@
 // Structured results (#2311, #2313). Every result, success or failure, also carries
 // structuredContent: one envelope that says how the answer was measured — state (measured,
 // not_assessed, failed, invalid_input), measured_at, method, coverage, freshness and notes —
-// with, on a success, `data` equal to what content[0] carries, and on a failure an `error`.
-// Each tool advertises the envelope as its outputSchema.
+// with, on a success, `data`, the answer whole, and on a failure an `error`. content[0] carries
+// `data` as JSON up to 30,000 characters, and past them a cut of it that the note names (TEXT
+// CUT, #2783), so past them content[0] is not equal to `data` (#2802). Each tool advertises the
+// envelope as its outputSchema.
 //
 // The envelope in the text (#2440, #2467). Many clients pass only `content` to the model, so the
 // last text block of every result is structuredContent serialized as JSON, less what an earlier
-// text block already carries verbatim: `data` (content[0] on a success), the note's sentences
-// (the block just before, which structuredContent's notes end with), and method where that note
-// quotes it. The rest — state, measured_at, coverage, freshness, the envelope's own notes and,
-// on a failure, error — is copied key for key, so the text blocks together are the whole of
-// structuredContent and cannot disagree with it. The MCP spec (2025-06-18, Tools, Structured
-// Content) asks a tool that returns structured content to return it serialized in a text block
-// too; the JSON block stays first and the note second, as in 1.x, so a client that parses
-// content[0] is unaffected.
+// text block already carries: `data` (content[0] on a success, whole or cut as above), the note's
+// sentences (the block just before, which structuredContent's notes end with), and method where
+// that note quotes it. The rest — state, measured_at, coverage, freshness, the envelope's own notes
+// and, on a failure, error — is copied key for key, so the text blocks together are the whole of
+// structuredContent, but for what a TEXT CUT leaves out of `data`, and cannot disagree with it. The
+// MCP spec (2025-06-18, Tools, Structured Content) asks a tool that returns structured content to
+// return it serialized in a text block too; the JSON block stays first and the note second, as in
+// 1.x, so a client that parses content[0] still parses the answer's JSON, which past 30,000
+// characters is a cut of it (fields, entries and string ends left out, no value changed) and no
+// longer the whole answer: structuredContent.data is (#2802).
 //
 // Protocol eras (#2311). serveStdio answers both: a 2026-07-28 client's server/discover and
 // per-request `_meta` envelope, and a 2025-era client's `initialize` handshake. The first
@@ -54,11 +58,11 @@ import { registerCheckAffected } from "./tools/check_affected.js";
 import { registerCheckSbom } from "./tools/check_sbom.js";
 import { registerCveIntel } from "./tools/cve_intel.js";
 import { registerGetCwe } from "./tools/get_cwe.js";
-import { isHttpEntrypoint, upstreamHeaders, upstreamUserAgent } from "./runtime.js";
+import { holdRequest, isHttpEntrypoint, requestSignal, upstreamHeaders, upstreamUserAgent } from "./runtime.js";
 import { registerVendorAdvisoryTools } from "./tools/vendor_advisories.js";
 import { registerPrompts } from "./prompts.js";
 import { registerResources } from "./resources.js";
-import { dataText, TEXT_BUDGET_DESCRIPTION } from "./textBudget.js";
+import { dataText, GET_CVE_WHOLE, TEXT_BUDGET_DESCRIPTION } from "./textBudget.js";
 // The package actually running, read from the package.json that ships beside dist/. The MCP
 // handshake (serverInfo) and the User-Agent both carry its name and version, so the API's
 // access log can count adoption per version without a code change per release.
@@ -175,15 +179,29 @@ function retryAfterSeconds(v) {
 // the URL); the User-Agent and Accept are this server's and are not overridden. init.timeoutMs
 // can only shorten the request's timeout below TIMEOUT_MS, never lengthen it: check_sbom passes
 // what is left of its call's budget, so a slow batch cannot carry the call past it (#2756).
+// The request is cancelled when init.signal aborts (check_sbom's call was cancelled) or, on the
+// hosted endpoint, when the client it answers has gone (runtime.ts requestSignal, #2775): a
+// network failure saying so, which nobody reads, since the SDK sends nothing for a cancelled call.
 export async function api(path, init) {
     const limitMs = init?.timeoutMs === undefined ? TIMEOUT_MS : Math.max(0, Math.min(TIMEOUT_MS, Math.floor(init.timeoutMs)));
+    const m = init?.method && init.method.toUpperCase() !== "GET" ? { method: init.method.toUpperCase() } : {};
+    const callers = [init?.signal, requestSignal()].filter((s) => s !== undefined);
+    const cancelledFailure = () => ({ ok: false, kind: "network", path, ...m, detail: "cancelled: the call was abandoned before the API answered" });
+    if (callers.some((s) => s.aborted))
+        return cancelledFailure();
     const ctrl = new AbortController();
     let timedOut = false;
+    let cancelled = false;
     const timer = setTimeout(() => {
         timedOut = true;
         ctrl.abort();
     }, limitMs);
-    const m = init?.method && init.method.toUpperCase() !== "GET" ? { method: init.method.toUpperCase() } : {};
+    const cancel = () => {
+        cancelled = true;
+        ctrl.abort();
+    };
+    for (const s of callers)
+        s.addEventListener("abort", cancel, { once: true });
     const own = limitMs === TIMEOUT_MS ? {} : { timeoutMs: limitMs };
     const timeout = () => ({ ok: false, kind: "timeout", path, ...m, ...own, detail: `no response within ${limitMs} ms` });
     try {
@@ -200,14 +218,14 @@ export async function api(path, init) {
             });
         }
         catch (e) {
-            return timedOut ? timeout() : { ok: false, kind: "network", path, ...m, detail: describeError(e) };
+            return timedOut ? timeout() : cancelled ? cancelledFailure() : { ok: false, kind: "network", path, ...m, detail: describeError(e) };
         }
         let body;
         try {
             body = await res.text();
         }
         catch (e) {
-            return timedOut ? timeout() : { ok: false, kind: "network", path, ...m, detail: `reading the body failed: ${describeError(e)}` };
+            return timedOut ? timeout() : cancelled ? cancelledFailure() : { ok: false, kind: "network", path, ...m, detail: `reading the body failed: ${describeError(e)}` };
         }
         if (!res.ok) {
             const retryAfter = retryAfterSeconds(res.headers.get("retry-after"));
@@ -228,6 +246,8 @@ export async function api(path, init) {
     }
     finally {
         clearTimeout(timer);
+        for (const s of callers)
+            s.removeEventListener("abort", cancel);
     }
 }
 const text = (t) => ({ type: "text", text: t });
@@ -273,13 +293,15 @@ const REJECTED_INPUT = "The API rejected the request as invalid input, so nothin
 // earlier text block already carries verbatim (#2467). 2.1.0 sent the whole envelope without
 // `data`, so every note went out twice, once as prose and once as the notes array, and
 // cve_exposure's method a third time.
-//   data    left out: content[0] carries it verbatim.
+//   data    left out: content[0] carries it, verbatim up to DATA_TEXT_BUDGET and past it cut,
+//           with the note saying what the cut leaves out (TEXT CUT, #2783).
 //   notes   only the envelope's own sentences (`own`), which no text block says; the rest of
 //           structuredContent's notes are the sentences of `said`, the text block just before
 //           this one (the note, or a failure's message). Left out when there are none.
 //   method  left out when `said` quotes it verbatim (cve_exposure's note, "Method: …").
 // Every other key is copied as is, in structuredContent's order, so the text blocks together are
-// the whole of structuredContent and cannot disagree with it.
+// the whole of structuredContent, but for what a TEXT CUT leaves out of data, which the note names,
+// and cannot disagree with it (#2802).
 const envelopeText = (structured, said, own) => {
     const envelope = {};
     for (const [k, v] of Object.entries(structured)) {
@@ -529,6 +551,55 @@ function summaryPollerNote(d) {
     const counters = quoted.length > 0 ? ` (${quoted.join(", ")})` : "";
     return ` poller is one API instance's NVD poller, counted in that instance's memory since it last started and zeroed on every restart: report its counters${counters} as that instance's, never as the feed's size, intake or reliability, and poller.last_poll_at as that instance's last poll, never as the feed's freshness.`;
 }
+// ── poller's JSON types, never a reason to withhold summary (#2771) ──
+//
+// 2.6.2 typed poller's eight fields in the outputSchema (CVE_SUMMARY_OUTPUT), and every success
+// goes through checked(), so one counter core-backend sent in another JSON type failed the whole
+// call and withheld summary.total: cve/poller.go Stats returns a map[string]interface{}, so
+// emitting interval as a time.Duration (1200000000000) instead of interval.String() compiles.
+// The block is one instance's diagnostics, never the feed's, so it degrades on its own: a field of
+// another type is left out of data and named in the note, a poller that is neither a JSON object
+// nor null (an array, a string) is left out whole and named, and summary and the rest of the
+// answer are relayed as sent. What the schema allows is kept as sent: null for a field (opt), null
+// or an empty object for the block, and keys this version does not know. Installed 2.6.2 and
+// 2.6.3 copies still fail on such a change, so core-backend's cve/poller_stats_wire_test.go pins
+// Stats()'s eight keys to these JSON types.
+const SUMMARY_POLLER_KINDS = {
+    cves_ingested: "number",
+    cves_skipped: "number",
+    http_retries: "number",
+    interval: "string",
+    last_poll_at: "string",
+    last_poll_dur_ms: "number",
+    poll_count: "number",
+    poll_errors: "number",
+};
+const pollerField = (k, description) => opt(SUMMARY_POLLER_KINDS[k] === "number" ? z.number() : z.string()).describe(description);
+const jsonKind = (v) => v === null ? "null" : Array.isArray(v) ? "an array" : typeof v === "object" ? "an object" : typeof v === "number" ? "a number" : typeof v === "boolean" ? "a boolean" : typeof v === "string" ? "a string" : typeof v;
+function summaryPollerShaped(d) {
+    const poller = field(d, "poller");
+    if (poller === undefined || poller === null)
+        return { data: d, note: "" };
+    const relayed = " The rest of the answer, summary with it, is relayed as sent.";
+    if (!isPlainObject(poller)) {
+        const { poller: _dropped, ...rest } = d;
+        return { data: rest, note: ` poller was left out of the data above because the answer sent it as ${jsonKind(poller)}, where this tool reads an object.${relayed}` };
+    }
+    const unusable = Object.keys(SUMMARY_POLLER_KINDS).filter((k) => {
+        const v = poller[k];
+        if (v === undefined || v === null)
+            return false;
+        return SUMMARY_POLLER_KINDS[k] === "number" ? !isCount(v) : typeof v !== "string";
+    });
+    if (unusable.length === 0)
+        return { data: d, note: "" };
+    const kept = Object.fromEntries(Object.entries(poller).filter(([k]) => !unusable.includes(k)));
+    const named = unusable.map((k) => `poller.${k} (${jsonKind(poller[k])}, where this tool reads ${SUMMARY_POLLER_KINDS[k] === "number" ? "a number" : "a string"})`);
+    return {
+        data: { ...d, poller: kept },
+        note: ` Left out of the data above because the answer sent ${unusable.length === 1 ? "it" : "them"} in a JSON type other than the one this tool reads: ${listed(named)}.${relayed}`,
+    };
+}
 async function cveSummary() {
     const tool = "cve_summary";
     try {
@@ -536,7 +607,9 @@ async function cveSummary() {
         if (!r.ok)
             return failed(tool, r);
         const head = okHead(tool, r.status);
-        const updated = strAt(r.data, "summary", "last_updated");
+        // #2771: a poller field of another JSON type is left out, never a failure of the call.
+        const { data, note: pollerShape } = summaryPollerShaped(r.data);
+        const updated = strAt(data, "summary", "last_updated");
         const env = {
             state: "measured",
             measured_at: instantOrNull(updated),
@@ -550,18 +623,18 @@ async function cveSummary() {
                 NO_FEED_FRESHNESS,
             ],
         };
-        const total = numAt(r.data, "summary", "total");
-        // What summary.none (#2610), the NVD histogram and summary.rejected (#2641) count, and what
-        // the poller block is (#2647).
-        const labels = `${summaryNoneNote(r.data)}${summaryNVDNote(r.data)}${summaryRejectedNote(r.data)}${summaryPollerNote(r.data)}`;
+        const total = numAt(data, "summary", "total");
+        // What summary.none (#2610), the NVD histogram and summary.rejected (#2641) count, what the
+        // poller block is (#2647), and what of it was left out (#2771).
+        const labels = `${summaryNoneNote(data)}${summaryNVDNote(data)}${summaryRejectedNote(data)}${summaryPollerNote(data)}${pollerShape}`;
         if (total === undefined)
-            return succeeded(r.data, `${head}${labels}`, env);
+            return succeeded(data, `${head}${labels}`, env);
         if (total === 0) {
-            return succeeded(r.data, `${head} The feed reports 0 active CVEs — a measured empty result (we looked and found nothing), not a lookup failure.${labels}`, env);
+            return succeeded(data, `${head} The feed reports 0 active CVEs — a measured empty result (we looked and found nothing), not a lookup failure.${labels}`, env);
         }
         // A stamp that is not a real instant stays in the JSON and is not repeated as prose.
         const stamp = realInstant(updated) ? ` (last updated ${updated})` : "";
-        return succeeded(r.data, `${head} The feed holds ${total} active CVEs${stamp}.${labels}`, env);
+        return succeeded(data, `${head} The feed holds ${total} active CVEs${stamp}.${labels}`, env);
     }
     catch (e) {
         return crashed(tool, e);
@@ -572,7 +645,9 @@ async function cveSummary() {
 // 133,300 characters of text. Past DATA_TEXT_BUDGET each row in the first text block keeps the
 // fields the description promises and a few more a triage reads, the description cut to 200
 // characters; then, for a page of 50, the fields the description promises with the description cut
-// to 100. structuredContent.data keeps every field of every row; get_cve returns one record whole.
+// to 100. structuredContent.data keeps every field of every row; get_cve returns one record, whole in
+// its structuredContent.data and in its own first text block with every field (its lists cut past
+// the budget, #2802).
 const SEARCH_CVES_TEXT = {
     rows: "cves",
     levels: [
@@ -582,7 +657,7 @@ const SEARCH_CVES_TEXT = {
         },
         { keep: ["cve_id", "description", "severity", "cvss_v3_score", "echelongraph_score", "score_assessed", "score_unassessed_reason", "epss_score", "kev_listed", "published"], clip: 100 },
     ],
-    whole: "get_cve returns any one of these CVEs' records whole.",
+    whole: `${GET_CVE_WHOLE}.`,
     page: (shown, _rows, d) => `To read the rows left out in the text, call search_cves again with the same arguments and offset ${(numAt(d, "offset") ?? 0) + shown}; a page of ${shown} rows or fewer like these fits the text without leaving rows out.`,
 };
 async function searchCVEs(a) {
@@ -1882,8 +1957,9 @@ const CVERecord = z.looseObject({
 });
 // #2647: what cve_summary says the poller block is (summaryPollerNote). Like the #2641 strings
 // beside SUMMARY_NONE_DESCRIPTION, it uses none of #2610's six words ("any", "not", "rating",
-// "scored", "source", "yet"). Declared here, before the outputSchema that describes poller with it.
-const SUMMARY_POLLER_DESCRIPTION = "poller holds the in-memory counters of the NVD poller of the one API instance that answered (cves_ingested, cves_skipped, http_retries, poll_count, poll_errors, last_poll_at, last_poll_dur_ms, interval), counted since that instance last started and zeroed on every restart: they describe that instance, never the feed's size, intake, reliability or freshness. Whenever the answer carries poller the note says so.";
+// "scored", "source", "yet"), #2771's sentence on a field of another JSON type among them. Declared
+// here, before the outputSchema that describes poller with it.
+const SUMMARY_POLLER_DESCRIPTION = "poller holds the in-memory counters of the NVD poller of the one API instance that answered (cves_ingested, cves_skipped, http_retries, poll_count, poll_errors, last_poll_at, last_poll_dur_ms, interval), counted since that instance last started and zeroed on every restart: they describe that instance, never the feed's size, intake, reliability or freshness. Whenever the answer carries poller the note says so. A poller field the answer sends in a JSON type other than the one described here is left out of data and named in the note, and a poller that is neither a JSON object nor null is left out whole: summary is relayed either way.";
 // One of the NVD histogram's four labelled buckets (#2641).
 const nvdBand = (label) => opt(z.number()).describe(`Of the active CVEs total counts, those whose NVD CVSS severity label is ${label}: NVD's label, as provenance, never EchelonGraph's severity band.`);
 const CVE_SUMMARY_OUTPUT = envelopeSchema({
@@ -1910,16 +1986,18 @@ const CVE_SUMMARY_OUTPUT = envelopeSchema({
         })
             .optional(),
         // #2647: one instance's counters, never the feed's (see summaryPollerNote).
+        // #2771: each field's JSON type is SUMMARY_POLLER_KINDS', which summaryPollerShaped enforces
+        // before this check, so a field of another type is left out, never a failed call.
         poller: z
             .looseObject({
-            cves_ingested: opt(z.number()).describe("CVE records this instance's NVD poller wrote since the instance last started: never the feed's size or intake."),
-            cves_skipped: opt(z.number()).describe("CVE records this instance's NVD poller skipped since the instance last started."),
-            http_retries: opt(z.number()).describe("HTTP retries this instance's NVD poller made since the instance last started."),
-            interval: opt(z.string()).describe("How often this instance's NVD poller polls."),
-            last_poll_at: opt(z.string()).describe("When this instance's NVD poller last polled: never the feed's freshness."),
-            last_poll_dur_ms: opt(z.number()).describe("How long that poll took, in milliseconds."),
-            poll_count: opt(z.number()).describe("Polls this instance's NVD poller made since the instance last started."),
-            poll_errors: opt(z.number()).describe("Polls of this instance's NVD poller that failed since the instance last started: never the feed's reliability."),
+            cves_ingested: pollerField("cves_ingested", "CVE records this instance's NVD poller wrote since the instance last started: never the feed's size or intake."),
+            cves_skipped: pollerField("cves_skipped", "CVE records this instance's NVD poller skipped since the instance last started."),
+            http_retries: pollerField("http_retries", "HTTP retries this instance's NVD poller made since the instance last started."),
+            interval: pollerField("interval", "How often this instance's NVD poller polls."),
+            last_poll_at: pollerField("last_poll_at", "When this instance's NVD poller last polled: never the feed's freshness."),
+            last_poll_dur_ms: pollerField("last_poll_dur_ms", "How long that poll took, in milliseconds."),
+            poll_count: pollerField("poll_count", "Polls this instance's NVD poller made since the instance last started."),
+            poll_errors: pollerField("poll_errors", "Polls of this instance's NVD poller that failed since the instance last started: never the feed's reliability."),
         })
             .nullable()
             .optional()
@@ -2092,6 +2170,10 @@ export const ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempot
 const CVE_ID_ARG = z.string().describe("a CVE ID, e.g. CVE-2023-44487");
 // What each description says about its structured result, naming only fields its schema holds.
 const FEED_ENVELOPE = "Its structured result carries state (measured), measured_at, method, coverage, freshness (null: the feed serves no poll-completion time) 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.";
+// #2771: cve_summary's own, since its data is the API's JSON less each poller field (or the whole
+// poller) summaryPollerShaped leaves out. Like SUMMARY_POLLER_DESCRIPTION it uses none of #2610's
+// six words ("any", "not", "rating", "scored", "source", "yet").
+const CVE_SUMMARY_ENVELOPE = "Its structured result carries state (measured), measured_at, method, coverage, freshness (null: the feed serves no poll-completion time) and notes, with data equal to the API's JSON less each poller field (or the whole poller) the note names as left out; 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.";
 // #2610: what cve_summary says summary.none is (summaryNoneNote), one constant string for the same
 // reason as SCORE_ASSESSED_DESCRIPTION below.
 const SUMMARY_NONE_DESCRIPTION = "summary.none is not a severity rating of None: it counts the active CVEs with no severity band from any source, that is, CVEs not yet scored, and the answer may carry the same count again as summary.unscored. Whenever summary.none is above zero the note says so: report those CVEs as not yet scored, not as CVEs rated None.";
@@ -2114,7 +2196,7 @@ export function createServer() {
     const server = new McpServer({ name: NAME, version: VERSION }, { instructions: INSTRUCTIONS, capabilities: { tools: { listChanged: false }, prompts: { listChanged: false }, resources: { listChanged: false } } });
     server.registerTool("cve_summary", {
         title: "CVE feed summary",
-        description: `Summary of EchelonGraph's CVE Pulse feed: summary.total active CVEs, their counts by severity band (summary.critical, summary.high, summary.medium, summary.low), the count with no band (summary.none), and summary.last_updated, the newest modification time among those records. ${SUMMARY_NONE_DESCRIPTION} ${SUMMARY_NVD_DESCRIPTION} ${SUMMARY_REJECTED_DESCRIPTION} ${SUMMARY_POLLER_DESCRIPTION} The feed is polled from its sources on a schedule, so this is the state as of that update. ${FEED_ENVELOPE} ${TEXT_BUDGET_DESCRIPTION}`,
+        description: `Summary of EchelonGraph's CVE Pulse feed: summary.total active CVEs, their counts by severity band (summary.critical, summary.high, summary.medium, summary.low), the count with no band (summary.none), and summary.last_updated, the newest modification time among those records. ${SUMMARY_NONE_DESCRIPTION} ${SUMMARY_NVD_DESCRIPTION} ${SUMMARY_REJECTED_DESCRIPTION} ${SUMMARY_POLLER_DESCRIPTION} The feed is polled from its sources on a schedule, so this is the state as of that update. ${CVE_SUMMARY_ENVELOPE} ${TEXT_BUDGET_DESCRIPTION}`,
         outputSchema: CVE_SUMMARY_OUTPUT,
         annotations: ANNOTATIONS,
     }, async () => checked("cve_summary", CVE_SUMMARY_OUTPUT, await cveSummary()));
@@ -2135,7 +2217,7 @@ export function createServer() {
     }, async (a) => checked("search_cves", SEARCH_CVES_OUTPUT, await searchCVEs(a)));
     server.registerTool("get_cve", {
         title: "CVE detail",
-        description: `Full record for one CVE: description, severity, cvss_v3_score, cvss_v4_score and cvss_v4_severity (when the record has a CVSS v4 score), echelongraph_score and echelongraph_severity with score_confidence (EchelonGraph's multi-source score) and score_assessed (whether EchelonGraph has scored it), epss_score and epss_percentile, CISA-KEV status (kev_listed, kev_added_date, and kev_ransomware for known ransomware-campaign use), ghsa_id (GitHub GHSA), references, cpe_match (the CPE criteria as one flat list) and cpe_configurations (NVD's configurations as NVD sent them, with each AND/OR operator, negate, versionStartExcluding and matchCriteriaId; absent where EchelonGraph has stored none, which is not a finding that no product is affected), published, modified and updated_at; each field only where the record has it. Pass a CVE ID like CVE-2023-44487. ${SCORE_ASSESSED_DESCRIPTION} ${FEED_ENVELOPE} ${TEXT_BUDGET_DESCRIPTION} Cut, each list in the record keeps its first entries, and the note names each list cut with its full length.`,
+        description: `One CVE's record: description, severity, cvss_v3_score, cvss_v4_score and cvss_v4_severity (when the record has a CVSS v4 score), echelongraph_score and echelongraph_severity with score_confidence (EchelonGraph's multi-source score) and score_assessed (whether EchelonGraph has scored it), epss_score and epss_percentile, CISA-KEV status (kev_listed, kev_added_date, and kev_ransomware for known ransomware-campaign use), ghsa_id (GitHub GHSA), references, cpe_match (the CPE criteria as one flat list) and cpe_configurations (NVD's configurations as NVD sent them, with each AND/OR operator, negate, versionStartExcluding and matchCriteriaId; absent where EchelonGraph has stored none, which is not a finding that no product is affected), published, modified and updated_at; each field only where the record has it. Pass a CVE ID like CVE-2023-44487. ${SCORE_ASSESSED_DESCRIPTION} ${FEED_ENVELOPE} ${TEXT_BUDGET_DESCRIPTION} Cut, each list in the record keeps its first entries, and the note names each list cut with its full length.`,
         inputSchema: z.object({ cve_id: CVE_ID_ARG }),
         outputSchema: GET_CVE_OUTPUT,
         annotations: ANNOTATIONS,
@@ -2157,8 +2239,10 @@ export function createServer() {
     registerEPSSHistory(server, TOOL_KIT);
     // #2716: its logic, schemas and description live in tools/check_affected.ts.
     registerCheckAffected(server, { api, succeeded, failed, badInput, crashed, checked, okHead, envelopeSchema, annotations: ANNOTATIONS });
-    // #2721: tools/check_sbom.ts, on this file's api(), envelope and failure contract.
-    registerCheckSbom(server, { api, failed, describeFailure, badInput, crashed, checked, succeeded, okHead, envelopeSchema, annotations: ANNOTATIONS });
+    // #2721: tools/check_sbom.ts, on this file's api(), envelope and failure contract. holdRequest
+    // (#2775): on the hosted endpoint, a call keeps its request's admission and large-body slot
+    // until it has stopped, not only until its answer, or its client, has gone.
+    registerCheckSbom(server, { api, failed, describeFailure, badInput, crashed, checked, succeeded, okHead, envelopeSchema, annotations: ANNOTATIONS, hold: holdRequest });
     registerCveIntel(server);
     registerGetCwe(server);
     // #2719: vendor_advisories_for_cve, get_vendor_advisory, search_vendor_advisories.
@@ -2166,7 +2250,7 @@ export function createServer() {
     // #2722: prompts and resources, in prompts.ts and resources.ts. Both lists are fixed per
     // connection, so listChanged is false above.
     registerPrompts(server, { cveId: CVE_ID });
-    registerResources(server, { api, cveId: CVE_ID, shownBase: SHOWN_BASE, getCve: async (id) => checked("get_cve", GET_CVE_OUTPUT, await getCVE(id)) });
+    registerResources(server, { api, cveId: CVE_ID, shownBase: SHOWN_BASE, sentences, getCve: async (id) => checked("get_cve", GET_CVE_OUTPUT, await getCVE(id)) });
     return server;
 }
 // The package identity and API settings, for the hosted HTTP entrypoint's health answer and

package/dist/prompts.js

@@ -2,6 +2,16 @@ import * as z from "zod";
 import { MAX_COMPONENTS, MAX_PURLS, MAX_SBOM_CHARS } from "./tools/check_sbom.js";
 export const KEV_BRIEF_DEFAULT_DAYS = 7;
 export const KEV_BRIEF_MAX_DAYS = 365;
+// The page the brief reads kev_recent in (#2799). The brief puts kev_vuln_name and kev_due_date on
+// every line, and a model whose client passes only `content` reads them from the first text block,
+// which past 30,000 characters keeps fewer fields a row (src/tools/kev_recent.ts kevText). Through
+// 2.6.3 the brief asked for limit 200: on 2026-10-04 the hosted endpoint's text for 365 days at 200
+// (306 matching) kept cve_id, kev_added_date, kev_vendor, kev_product and kev_ransomware a row, and
+// neither field. A page of 50, kev_recent's default, is sent whole (27,514 characters of production's
+// 50 newest), and its first cut level, which keeps both, fits 85 production-shaped rows in the
+// budget, so at 50 rows three quarters longer than production's still keep them.
+// test/prompt-fields.test.mjs runs the brief's call at this limit.
+export const KEV_BRIEF_LIMIT = 50;
 // The envelope rules every prompt carries, word for word.
 export const ENVELOPE_RULES = [
     "Before you use any figure, read that result's evidence envelope: its structuredContent (where your client shows text blocks alone, the last text block) carries state, measured_at, method, coverage, freshness and notes.",
@@ -14,22 +24,36 @@ export const ENVELOPE_RULES = [
     "Do not add facts the results do not carry: where a result says nothing about a point, write that it does not say.",
 ].join(" ");
 const text = (t) => ({ messages: [{ role: "user", content: { type: "text", text: t } }] });
+// triage_cve reads kev_due_date from get_cve's record (#2799 review). Through 2.6.3 its step 6 read
+// it from kev_recent with since and until set to the CVE's kev_added_date, with no limit and no
+// paging, so on a day CISA added more than a page the CVE's row could be on no page it read: on the
+// hosted endpoint (2.6.3, 2026-10-04) that call for 2021-11-03 answered total 287, 50 rows from
+// CVE-2010-5326 to CVE-2019-0797 and has_more true, without CVE-2021-40444, added that day; get_cve
+// for CVE-2021-40444 carried kev_due_date 2021-11-17T00:00:00Z in its first text block. The record
+// carries kev_due_date wherever CISA gives one (core-backend cve/store.go, omitempty), and get_cve's
+// first text block keeps every field of it.
+//
+// Its Patch line (#2817): cve_intel's fixed_version is one value per (CVE, ecosystem, package), the
+// advisory's last range's (core-backend cve/advisory.go UpsertAffectedPackages), and triage_cve has
+// no installed version to hold it against: for CVE-2021-44228 production's cve_intel gives
+// log4j-core 2.12.2 (2026-10-04, 2.6.3), below an affected 2.14.1. So the line gives it as
+// what cve_intel records for the package, never as the fix for every affected branch, and sends
+// the reader to get_cve's references tagged Vendor Advisory or Patch for a branch's fix.
 export function triageCveText(cve) {
     return [
         `Triage ${cve} using the EchelonGraph MCP tools. Call them in this order, each with cve_id ${cve}:`,
-        "1. get_cve: the record. Read score_assessed before echelongraph_score (false: not yet scored, which is not a score of 0); read severity, cvss_v3_score, epss_score and epss_percentile, and the CISA-KEV fields kev_listed, kev_added_date and kev_ransomware.",
+        "1. get_cve: the record. Read score_assessed before echelongraph_score (false: not yet scored, which is not a score of 0); read severity, cvss_v3_score, epss_score and epss_percentile, and the CISA-KEV fields kev_listed, kev_added_date, kev_due_date and kev_ransomware.",
         "2. cve_intel: weaknesses (cwes), public exploit code (exploits and exploits_total; verified_status is the label stored with each reference, not a guarantee that it works, and an empty list is not evidence that no exploit exists), affected_packages and fixed_versions.",
         "3. vendor_advisories_for_cve: the vendor advisories that name it. Call get_vendor_advisory for one whose remediation you need in full.",
         "4. epss_history: how its EPSS score changed, one point per recorded change (series_kind change_only): before series_starts_at a missing point means not recorded, not unchanged.",
         "5. cve_exposure: internet exposure on record. exposure_state says what the count is; exposed_hosts counts distinct ip:port services, not machines; the result is not_assessed with measured_at null, so present any count as undated and on record, and exposure_state not_assessed as not assessed.",
-        `6. If get_cve says kev_listed is true: kev_recent with since and until both set to the date part (YYYY-MM-DD) of its kev_added_date (for 2024-04-12T00:00:00Z, 2024-04-12), to read kev_due_date from the row for ${cve}.`,
         ENVELOPE_RULES,
         "Then answer with this template, one line each, naming the tool and the measured_at behind every line:",
         "- Exploited? CISA-KEV listing and its date, known ransomware use, and public exploit code on record.",
         "- Likelihood: EPSS score and percentile, and how it has moved.",
         "- Reachable? exposure_state and the count on record, or not assessed.",
-        '- Patch: fixed versions and vendor advisories; where the results hold none, write "none on record", which is not a finding that no fix exists.',
-        "- Deadline: kev_due_date when the CVE is KEV-listed (CISA's due date for US federal civilian agencies); otherwise write that the results give no CISA deadline.",
+        `- Patch: fixed versions and vendor advisories; where the results hold none, write "none on record", which is not a finding that no fix exists. cve_intel keeps one fixed_version per ecosystem and package, its advisory's last range's, which need not be the fix for every affected version of the package: give each as the fixed version cve_intel records for that package, never as the fix for every affected branch or the version every install should move to, and for the fix on a given branch point to get_cve's references tagged Vendor Advisory or Patch, where it has them, and to the vendor advisories.`,
+        "- Deadline: get_cve's kev_due_date when the CVE is KEV-listed (CISA's due date for US federal civilian agencies); otherwise write that the results give no CISA deadline.",
         "- Decision: patch now, schedule, or monitor, with a one-line reason drawn from the lines above.",
     ].join("\n");
 }
@@ -37,7 +61,7 @@ export function kevWeeklyBriefText(days) {
     return [
         `Write a brief of the CVEs CISA added to its Known Exploited Vulnerabilities (KEV) catalog in the last ${days} days, using the EchelonGraph MCP tools.`,
         `1. Compute since: today's date in UTC minus ${days} days, as YYYY-MM-DD. State the since date you used, and today's date.`,
-        "2. Call kev_recent with since set to that date and limit 200. While its coverage.has_more is true, call kev_recent again with the same since and cursor set to the previous answer's next_cursor.",
+        `2. Call kev_recent with since set to that date and limit ${KEV_BRIEF_LIMIT}. While its coverage.has_more is true, call kev_recent again with the same since and limit and cursor set to the previous answer's next_cursor.`,
         ENVELOPE_RULES,
         "Then write the brief:",
         "- Header: the date range, the number of CVEs added (total), and measured_at, EchelonGraph's last successful fetch of CISA's feed, with catalog_version.",
@@ -61,15 +85,41 @@ export function amIAffectedText(a) {
         "Where capped, candidates_capped or degraded is true, say the list may be incomplete and why.",
     ].join("\n");
 }
+// sbom_review (#2799). The purls a call did not send: data.not_sent_purls lists them, and where the
+// first text block cuts that list to its first entries (check_sbom's TEXT CUT says so), the model
+// rebuilds them from the document, from the position check_sbom's note gives, in the order it
+// gives (check_sbom.ts READ_ORDER).
+//
+// Fixed versions (#2799 review, #2817). cve_intel's fixed_version is one value per (CVE, ecosystem,
+// package), the advisory's last range's (core-backend cve/advisory.go UpsertAffectedPackages), so
+// it need not be the fix for the installed version's branch: for CVE-2021-44228, production's
+// cve_intel gives log4j-core 2.12.2 (2026-10-04, 2.6.3), older than an installed 2.14.1, and
+// check_sbom's matches for 2.14.1 say it "is listed verbatim in the advisory's affected versions",
+// which names no fix. So a fixed version is given only where it is strictly greater than the
+// installed version, and otherwise the line says the results give none for the component's branch
+// and points to the advisory. The advisory interval in a match's match_reason, "[A, B)" (core-backend
+// cve/pkgmatch.go evaluateRegistryRow), is preferred where the text keeps it (its first cut level;
+// a Juice Shop SBOM of 50 components is cut past it); B is the interval's fixed bound, or its
+// last_affected one, which the text does not tell apart, so B is given as the interval's end.
+// A cut text keeps index, purl, verdict, not_assessed_reason and cve_ids on a row, not its
+// ecosystem, package or version, so the model reads those from the purl, as core-backend's
+// matcher does (cve/matchbatch.go purlNameVersion, shared/pkg/purlosv): step 2 lists every type
+// purlosv maps (its unversioned table, and deb, apk, alpine and rpm by the distro qualifier, of
+// the three kinds osvDistro reads, Alpine cut to major.minor and Debian to its major), the types
+// purlNameVersion names with their namespace, and says any other is unknown, with no fixed version.
+// test/prompt-fields.test.mjs fromPurl holds the same tables.
 export function sbomReviewText(sbom) {
     return [
         "Review the SBOM below for known vulnerabilities, using the EchelonGraph MCP tools.",
-        `1. Call check_sbom with sbom set to the document below, as given. It reads the document's purls and checks up to ${MAX_PURLS} distinct purls per call, sending them in batches of ${MAX_COMPONENTS}; a document with more is refused, not truncated. If it is refused, say why from the result and do not guess at the components. If coverage.not_sent is above 0, the API's rate limit or the call's time budget stopped it early: say how many purls were not sent and coverage.not_sent_reason, list them as not checked (never as clean), and call check_sbom again with purls set to data.not_sent_purls once, after a minute, merging what it returns.`,
-        "2. For each distinct cve_id on a component whose verdict is affected, call get_cve, to read kev_listed, epss_score, score_assessed, echelongraph_score and cvss_v3_score. If there are more than 30 distinct CVEs, do this for 30 of them and list the rest as not looked up, unranked.",
+        `1. Call check_sbom with sbom set to the document below, as given. It reads the document's purls and checks up to ${MAX_PURLS} distinct purls per call, sending them in batches of ${MAX_COMPONENTS}; a document with more is refused, not truncated. If it is refused, say why from the result and do not guess at the components. If coverage.not_sent is above 0, the API's rate limit or the call's time budget stopped it early: say how many purls were not sent and coverage.not_sent_reason, and that they are not checked (never clean). After a minute, call check_sbom once more with purls set to the purls not sent, and merge what it returns. data.not_sent_purls lists them; where the note says the first text block cuts not_sent_purls to its first entries, rebuild the list from the document instead, as the note says: the document's distinct purls from the position the note gives on, counted in the order it gives.`,
+        "2. Read each component's ecosystem, package and version from its purl, which every row of data.results in the text carries (the leanest cut of the text leaves out the row's own ecosystem, package and version), as check_sbom maps them. A purl is pkg:type/namespace/name@version?qualifiers, each part percent-decoded (%40 is @), its type and distro qualifier in any case. The version is what follows the last @, up to any ? or #. The ecosystem follows from the type: npm is npm, pypi PyPI, maven Maven, golang Go, cargo crates.io, gem RubyGems, nuget NuGet, composer Packagist, hex Hex, pub Pub, swift SwiftURL, hackage Hackage, cran CRAN, bitnami Bitnami, conan ConanCenter and githubact GitHub Actions. For deb, apk, alpine and rpm it is the release the distro qualifier names, which must be one of these three kinds: distro=debian-N is Debian:N, the major release alone (debian-12 and debian-12.5 are Debian:12); distro=ubuntu-V is Ubuntu:V as given (ubuntu-22.04 is Ubuntu:22.04); distro=alpine-X.Y is Alpine:vX.Y, cut to major.minor (alpine-3.20 and alpine-3.20.10 are Alpine:v3.20; alpine-3 names none). For any other type, and a deb, apk, alpine or rpm purl without such a qualifier, the ecosystem is unknown: check_sbom does not check the component (not_assessed, never clean), and the fix list gives no version for it. The package is namespace:name for maven (pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1 is the package org.apache.logging.log4j:log4j-core in Maven, at version 2.14.1), namespace/name for npm, golang, composer, swift and githubact, and the name alone for every other type (pkg:deb/debian/openssl@3.0.15-1~deb12u1?distro=debian-12 is openssl in Debian:12).",
+        "3. For each distinct cve_id on a component whose verdict is affected, call get_cve, to read kev_listed, epss_score, score_assessed, echelongraph_score and cvss_v3_score, and cve_intel, to read fixed_version from its affected_packages and fixed_versions rows for the component's ecosystem and package (package_name). If there are more than 30 distinct CVEs, do this for 30 of them and list the rest as not looked up, unranked.",
         ENVELOPE_RULES,
         "Read each component's verdict: not_affected is the one clean verdict; undetermined and not_assessed are not clean, and not_assessed_reason says why (for example distro_release_unknown: a deb, apk or rpm purl without a distro qualifier, which EchelonGraph does not guess).",
         "Then write a prioritised fix list of the affected components. State the ordering keys, in this order: 1. CISA-KEV listed (kev_listed true) first; 2. then EPSS score, highest first; 3. then echelongraph_score where score_assessed is true, else cvss_v3_score, highest first. A CVE with no value for a key sorts after those with one, and its line says which key was missing.",
-        "For each line give the component (purl), its cve_ids, the key values used, and fixed versions where a result gives them. After the list, give data.summary's counts, and list the undetermined and not_assessed components with their reasons as not checked, never as clean.",
+        "For each line give the component (purl), its cve_ids, the key values used, and for each CVE a fixed version where the results support one, by this rule. Never give a fixed version that is not strictly greater than the component's installed version (the version in its purl), compared in the ecosystem's version order: release numbers part by part, as numbers, not as text (2.9.1 is below 2.12.2, and 2.12.2 is below 2.14.1); where you are not sure of the order (pre-releases, qualifiers and distro revisions have their own rules), say so and do not give it. Prefer the match's match_reason where the text keeps it: \"falls inside the advisory interval [A, B)\" says the advisory's range that holds the installed version ends at B, which match_reason does not say is a fixed version rather than the range's last affected version, so give B as the end of that interval, quoting it (∞: the range has no end on record). Otherwise give cve_intel's fixed_version for the component's ecosystem and package (or the recorded fix a match_reason names, the same value): cve_intel keeps one fixed_version per package, its advisory's last range's, which need not be the fix on the component's branch, so say so beside it. Where no version meets the rule (\"listed verbatim in the advisory's affected versions\" names none), write that the results give no fixed version for the component's branch, which is not a finding that no fix exists, and point to the CVE's advisory for it: get_cve's references tagged Vendor Advisory or Patch, where it has them.",
+        "After the list, give data.summary's counts, and list the undetermined and not_assessed components with their reasons as not checked, never as clean.",
+        "Where the note says that rows of data.results are left out of the first text block, list the components its rows carry, say how many affected components the text leaves out (data.summary.affected, less those listed), and give the undetermined and not_assessed components it leaves out as data.summary's counts, by not_assessed_reason, as not checked, never as clean.",
         "",
         "SBOM:",
         "```json",
@@ -80,7 +130,7 @@ export function sbomReviewText(sbom) {
 export function registerPrompts(server, kit) {
     server.registerPrompt("triage_cve", {
         title: "Triage a CVE",
-        description: "Triage one CVE: get_cve, cve_intel, vendor_advisories_for_cve, epss_history and cve_exposure (and kev_recent for the due date when the CVE is KEV-listed), then a decision template: exploited, likelihood, reachable, patch, deadline. Each line cites its tool and measured_at, and not_assessed is never reported as clean.",
+        description: "Triage one CVE: get_cve (with CISA's due date when the CVE is KEV-listed), cve_intel, vendor_advisories_for_cve, epss_history and cve_exposure, then a decision template: exploited, likelihood, reachable, patch, deadline. Each line cites its tool and measured_at, and not_assessed is never reported as clean.",
         argsSchema: z.object({
             cve_id: z
                 .string()
@@ -125,7 +175,7 @@ export function registerPrompts(server, kit) {
     }, (a) => text(amIAffectedText(a)));
     server.registerPrompt("sbom_review", {
         title: "SBOM review",
-        description: `Review an SBOM (CycloneDX JSON or SPDX JSON text, up to ${MAX_SBOM_CHARS} characters): it is passed to check_sbom, which checks up to ${MAX_PURLS} distinct purls per call in batches of ${MAX_COMPONENTS}, then get_cve for each affected CVE, and a prioritised fix list ordered by CISA-KEV listing, then EPSS, then score, each key stated. undetermined and not_assessed components are listed as not checked, never as clean.`,
+        description: `Review an SBOM (CycloneDX JSON or SPDX JSON text, up to ${MAX_SBOM_CHARS} characters): it is passed to check_sbom, which checks up to ${MAX_PURLS} distinct purls per call in batches of ${MAX_COMPONENTS}, then get_cve and cve_intel for each affected CVE, and a prioritised fix list ordered by CISA-KEV listing, then EPSS, then score, each key stated. undetermined and not_assessed components are listed as not checked, never as clean.`,
         argsSchema: z.object({
             sbom: z
                 .string()