echelongraph-mcp 2.7.2 → 3.0.2

package/dist/tools/check_affected.js

@@ -27,7 +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";
+import { answering, FULL_ARG, 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.
@@ -74,10 +74,11 @@ const Match = z.looseObject({
     vendor_unknown: opt(z.boolean()).describe("true: the vendor was not verified, so the match is real but its attribution to your vendor is not."),
     match_reason: opt(z.string()),
     version_evidence: opt(z.string()),
-    // #2834: registry matches only (core-backend cve/pkgmatch_fixedin.go registryFixedIn).
+    // #2834, #3074: registry matches only (core-backend cve/pkgmatch_fixedin.go registryFixFor).
     interval: opt(z.looseObject({ introduced: opt(z.string()), fixed: opt(z.string()), last_affected: opt(z.string()) })).describe("Registry match: the advisory interval that holds this version (fixed is exclusive, last_affected inclusive); absent when no interval holds it."),
-    fixed_in: opt(z.string()).describe("Registry match: the fixed bound of the advisory interval that holds this version, always above it. null when that interval records no fix (it ends at last_affected, or has no end) or no interval holds the version, with fixed_in_reason saying which. Absent on a CPE match."),
+    fixed_in: opt(z.string()).describe("Registry match: the lowest version above this one that no affected interval of the CVE's record for the package holds, always above it: the fixed bound of the interval that holds this version, moved past any overlapping interval that still holds that bound (fixed_in_detail then names it). null when no such version is on record (an interval on the way records no fix: it ends at last_affected, or has no end) or no interval holds the version, with fixed_in_reason saying which. Absent on a CPE match."),
     fixed_in_reason: opt(z.string()).describe("Why fixed_in is null; absent when fixed_in is a version."),
+    fixed_in_detail: opt(z.string()).describe("Set when fixed_in is not the fixed bound of the interval that holds this version: the overlapping intervals of the same record it moved past, which still hold that bound."),
 });
 const Undetermined = z.looseObject({
     cve_id: opt(z.string()),
@@ -130,7 +131,7 @@ 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. The CPE path takes product (an NVD CPE product token, such as openssl or nginx) and version, and returns the CVEs whose NVD CPE match criteria include that product at that version; each match names the vendor NVD asserts (cpe_vendor) and whether it 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 EchelonGraph holds for that package as affected, not affected or undetermined. count depends on assessed: assessed false means the lookup did not evaluate this component, not_assessed_reason says why, and a count of 0 there is not a finding of not affected. An advisory undecidable at this version is reported as undetermined (undetermined_count, and up to 50 of them in undetermined), never as safe. Each match carries cve_id, kev_listed, ransomware, epss_score, effective_score, effective_severity and score_assessed (false: not yet scored, so echelongraph_score is withheld). A registry match also carries interval, the advisory interval holding this version, and fixed_in, its fixed bound, or null with fixed_in_reason; a CPE match carries no fixed_in. All four inputs travel in request headers, never in the URL." +
+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. The CPE path takes product (an NVD CPE product token, such as nginx) and version, and returns the CVEs whose NVD CPE match criteria include that product at that version; each match names the vendor NVD asserts (cpe_vendor) and whether it 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 EchelonGraph holds for that package as affected, not affected or undetermined. count depends on assessed: assessed false means the lookup did not evaluate this component, not_assessed_reason says why, and a count of 0 there is not a finding of not affected. An advisory undecidable at this version is reported as undetermined (undetermined_count, and up to 50 of them in undetermined), never as safe. Each match carries cve_id, kev_listed, ransomware, epss_score, effective_score, effective_severity and score_assessed (false: not yet scored, so echelongraph_score is withheld). A registry match also carries interval, the advisory interval holding it, and fixed_in, the lowest unaffected version above it, or null with fixed_in_reason; a CPE match carries no fixed_in. All four inputs travel in request headers, never in the URL." +
     " " +
     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, and each match keeps cve_id, kev_listed, ransomware, epss_score, effective_score, score_assessed and fixed_in at least. Every CPE match stays in the text; near the cap, a registry list's last matches can leave it, and the note says how many.";
@@ -139,6 +140,7 @@ export const CHECK_AFFECTED_INPUT = z.object({
     ecosystem: z.string().optional().describe("Registry path: the package's ecosystem, such as npm, PyPI or Maven. Give with package, not with product."),
     package: z.string().optional().describe("Registry path: the package name in that ecosystem, such as lodash."),
     version: z.string().describe("The version to check, such as 3.0.0."),
+    full: FULL_ARG,
 });
 const field = (o, k) => (o !== null && typeof o === "object" ? o[k] : undefined);
 const num = (o, k) => {
@@ -172,22 +174,24 @@ function matchesNote(matches) {
     }
     return out;
 }
-// #2834: what the registry matches say about a fix. fixed_in is the fixed bound of the interval
-// that holds this version (core-backend cve/pkgmatch_fixedin.go), so it is per match: an advisory
-// with several branches (Log4Shell: 2.3.1, 2.12.2, 2.15.0) names the one for this version.
+// #2834: what the registry matches say about a fix. fixed_in is the first version above this one
+// that no affected interval of the match's record holds (core-backend cve/pkgmatch_fixedin.go):
+// the fixed bound of the interval that holds this version, moved past any overlapping interval
+// that still holds it (#3074), so it is per match: an advisory with several branches (Log4Shell:
+// 2.3.1, 2.12.2, 2.15.0) names the one for this version.
 function fixedInNote(matches) {
     const registry = matches.filter((m) => m !== null && typeof m === "object" && "fixed_in" in m);
     if (registry.length === 0)
         return "";
     const fixed = registry.filter((m) => typeof field(m, "fixed_in") === "string").length;
     const none = registry.length - fixed;
-    return ` fixed_in, the fixed bound of the advisory interval that holds this version: ${fixed === registry.length ? `set on every match` : `set on ${fixed} of ${registry.length} matches`}${none > 0 ? `; null on ${none}, where the advisory records no fix for this version (fixed_in_reason says why)` : ""}.`;
+    return ` fixed_in, the first version above this one that no affected interval of the advisory holds: ${fixed === registry.length ? `set on every match` : `set on ${fixed} of ${registry.length} matches`}${none > 0 ? `; null on ${none}, where the advisory records no fix for this version (fixed_in_reason says why)` : ""}.`;
 }
 // #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: "[A, B)" names the fixed version B, "[A, B]" the
+// the advisory interval its version falls inside: "[A, B)" names that interval's fixed bound B, "[A, B]" the
 // last affected one, #2830) 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;
@@ -221,7 +225,7 @@ const CHECK_AFFECTED_TEXT = {
             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", "fixed_in",
-                "fixed_in_reason",
+                "fixed_in_reason", "fixed_in_detail",
             ],
             clip: 200,
         },
@@ -250,6 +254,32 @@ const CHECK_AFFECTED_TEXT = {
     ],
     whole: `${GET_CVE_WHOLE}, and cve_intel a CVE's affected packages and fixed versions.`,
 };
+// #3013: the structured result's cut. A production match is about 1,650 characters of compact JSON
+// (its description, matched criteria and match reason), so openssl 3.0.0's 71 matches were 147,564
+// characters of structured result and linux_kernel 5.10.0's 200 (the API's cap) 331,682. As in the
+// text, the samples beside the matches go first (excluded and undetermined, each to at most the same
+// number of its first entries; excluded_count and undetermined_count count every entry), then the
+// matches, and cve_ids, each match's cve_id in order, last: it names every match in a few thousand
+// characters. Before any match leaves, every match is thinned (most of a match is its description,
+// about 1,400 characters for openssl, which get_cve returns): first to its scores, flags, the
+// criteria it matched and fixed_in, then to the fields this tool's description says a match keeps
+// at least, with fixed_in_reason. Only then do matches leave from the end (the lowest ranked).
+const CHECK_AFFECTED_DATA = {
+    steps: [
+        { lists: ["excluded", "undetermined"] },
+        {
+            lists: ["matches"],
+            thin: [
+                [
+                    "cve_id", "severity", "cvss_v3_score", "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", "version_evidence", "fixed_in", "fixed_in_reason",
+                ],
+                ["cve_id", "kev_listed", "ransomware", "epss_score", "effective_score", "score_assessed", "fixed_in", "fixed_in_reason"],
+            ],
+        },
+        { lists: ["cve_ids"] },
+    ],
+};
 async function checkAffected(kit, a) {
     const product = (a.product ?? "").trim();
     const ecosystem = (a.ecosystem ?? "").trim();
@@ -343,13 +373,16 @@ async function checkAffected(kit, a) {
         return kit.crashed(TOOL, e);
     }
 }
+// One output schema per process, not per request (3.0.2; index.ts envelopeSchema says why).
+const OUTPUTS = new WeakMap();
 export function registerCheckAffected(server, kit) {
-    const output = kit.envelopeSchema({ data: DATA, coverage: COVERAGE, freshness: null });
+    const output = OUTPUTS.get(kit.envelopeSchema) ?? kit.envelopeSchema({ data: DATA, coverage: COVERAGE, freshness: null });
+    OUTPUTS.set(kit.envelopeSchema, output);
     server.registerTool(TOOL, {
         title: CHECK_AFFECTED_TITLE,
         description: CHECK_AFFECTED_DESCRIPTION,
         inputSchema: CHECK_AFFECTED_INPUT,
         outputSchema: output,
         annotations: kit.annotations,
-    }, async (a) => kit.checked(TOOL, output, await checkAffected(kit, a)));
+    }, async (a) => kit.checked(TOOL, output, await answering(a.full, CHECK_AFFECTED_DATA, () => checkAffected(kit, a))));
 }

package/dist/tools/check_sbom.js

@@ -1,5 +1,5 @@
 import * as z from "zod";
-import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
+import { answering, FULL_ARG, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 import { CLEAN_NOTE, DISTRO_NOTE, FRESHNESS_NOTE, MAX_PURLS, MEASURED_AT_NOTE, METHOD, batchDataShape, dedupe, field, isObj, plural, purlsRefusal, sendBatches, sendingCoverage, sendingCoverageShape, sendingSentences, verdictSentences, } from "./match_batch.js";
 // #2835: the batch loop, its constants and the row schema moved to match_batch.ts, which
 // scan_manifest shares; re-exported here, where the tests and prompts.ts import them.
@@ -25,7 +25,7 @@ export const CHECK_SBOM_TITLE = "Check an SBOM against the advisory corpus";
 export const CHECK_SBOM_ROUTING = "For container images and Kubernetes pods, the input is an SBOM of each image, or its purls.";
 export const CHECK_SBOM_DESCRIPTION = "Check a dependency list against EchelonGraph's advisory corpus, one verdict per component. " +
     CHECK_SBOM_ROUTING +
-    " Pass purls (package URLs, up to 2,000 distinct) or sbom (a CycloneDX or SPDX JSON document, up to 5,000,000 characters). This server reads the purls from the document; only they are sent to the API, in POST bodies of at most 200, 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. data.results holds one row per component sent, in order, with verdict (affected, not_affected, undetermined or not_assessed), not_assessed_reason, cve_ids, matched_package and matched_via (a deb or apk purl's upstream qualifier matches as its source package); each match carries fixed_in (its interval's fixed bound) or null with fixed_in_reason. data.summary counts the verdicts. not_affected is the only clean verdict: not_assessed (no verdict, as for a deb, apk or rpm purl without a distro qualifier naming its release, which EchelonGraph does not guess) and undetermined are not, and the note counts both. The API allows 1,200 components a minute per caller; on a 429 the tool waits out Retry-After, up to 50 seconds a call, then answers what it has, the rest in data.not_sent_purls, unchecked and not clean. Input with more than 2,000 distinct purls is refused, not truncated." +
+    " Pass purls (package URLs, up to 2,000 distinct) or sbom (a CycloneDX or SPDX JSON document, up to 5,000,000 characters). This server reads the purls from the document; only they are sent to the API, in POST bodies of at most 200, 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. data.results holds one row per component sent, in order, with verdict (affected, not_affected, undetermined or not_assessed), not_assessed_reason, cve_ids, matched_package and matched_via (a deb or apk purl's upstream qualifier matches as its source package); each match carries fixed_in (the next unaffected version) or null with fixed_in_reason. data.summary counts the verdicts. not_affected is the only clean verdict: not_assessed (no verdict, as for a deb, apk or rpm purl without a distro qualifier naming its release, which EchelonGraph does not guess) and undetermined are not, and the note counts both. The API allows 1,200 components a minute per caller; on a 429 the tool waits out Retry-After, up to 50 seconds a call, then answers what it has, the rest in data.not_sent_purls, unchecked and not clean. Input with more than 2,000 distinct purls is refused, not truncated." +
     " " +
     TEXT_BUDGET_DESCRIPTION +
     " Cut, each row keeps index, purl, verdict, not_assessed_reason and cve_ids at least, each match its fixed_in while kept; not_affected rows leave the text first, then not_assessed ones; not_sent_purls keeps its first 10.";
@@ -34,7 +34,7 @@ export const CHECK_SBOM_DESCRIPTION = "Check a dependency list against EchelonGr
 // text, and 2,000 purls about 1,200,000. Past DATA_TEXT_BUDGET each row in the first text block
 // keeps its verdict, counts, cve_ids, matched_package and matched_via (#2836), and each match its
 // scores, flags, fixed_in (#2834) and match_reason (the
-// advisory interval the version falls inside: "[A, B)" names the fixed version B, "[A, B]" the last
+// advisory interval the version falls inside: "[A, B)" names that interval's fixed bound B, "[A, B]" the last
 // affected one, #2830) 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
@@ -49,7 +49,7 @@ export const CHECK_SBOM_DESCRIPTION = "Check a dependency list against EchelonGr
 // 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", "fixed_in"];
+    const matches = ["cve_id", "severity", "effective_severity", "effective_score", "kev_listed", "ransomware", "epss_score", "score_assessed", "fixed_in", "fixed_in_reason"];
     const row = [
         "index", "purl", "ecosystem", "package", "version", "verdict", "assessed", "not_assessed_reason", "count", "not_affected_count", "undetermined_count", "cve_ids", "matched_package", "matched_via",
     ];
@@ -69,11 +69,155 @@ export function sbomText(sent) {
         ],
         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.",
+        // a component's matches whole, with full: true (#3013).
+        whole: "check_affected, given a row's ecosystem, package and version, returns that component's matches, whole in its structuredContent.data with full: true, 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.`,
     };
 }
+// #3013: the structured result's cut. A production row is about 1,900 characters of compact JSON
+// (its matches, each a CVE with its description), so the 50-component Juice Shop document was 98,682
+// characters of structured result and 2,000 purls 3,790,686. The lists beside the rows go first
+// (not_sent_purls: the note says from which position of the input they run, and in what order; and,
+// for scan_manifest, not_checked, which coverage.not_checked_by_reason counts). Then, before any
+// row leaves, every row is thinned to SBOM_ROW_THIN: what a row says of the component and its
+// verdict, and per match what a triage reads (a match's description, about 535 characters, is
+// get_cve's); the first #3013 cut, before release, kept 3 of Juice Shop's 50 rows whole, all affected, and named the
+// other 7 affected components nowhere a client reading structuredContent sees. Only then do rows
+// leave, as in the text: the not_affected rows first, then the not_assessed ones (data.summary
+// counts every verdict), then the last of the rest, so the affected and undetermined rows are the
+// last to go.
+// #3013's review: a thinned match kept cve_id, kev_listed, epss_score, fixed_in and
+// fixed_in_reason, while the workload_triage prompt reads kev_listed, ransomware, epss_score,
+// effective_score, score_assessed and fixed_in from a row's matches (its step 5 and ordering keys),
+// so a client reading structuredContent lost ransomware and the score it ranks by. Each field a
+// prompt reads from check_sbom's or scan_manifest's matches is kept (test/prompt-fields.test.mjs
+// holds every prompt's to this list).
+export const SBOM_ROW_THIN = [
+    "index",
+    "purl",
+    "verdict",
+    "not_assessed_reason",
+    "cve_ids",
+    "matched_package",
+    "matched_via",
+    "matched_version_from",
+    "purl_name",
+    ["matches", ["cve_id", "kev_listed", "ransomware", "epss_score", "effective_score", "score_assessed", "fixed_in", "fixed_in_reason"]],
+];
+// #3132: past SBOM_ROW_THIN, each row is cut on its own terms before any row leaves. Through 3.0.0
+// SBOM_ROW_THIN was the only level, and it keeps every match object, so one row still large once
+// thinned left data, and every row after it with it (rows leave from the end): measured on hosted
+// 3.0.0 (2026-10-11), five Debian 12 purls, all affected, kept 1 row (libssl3; linux-libc-dev
+// 6.1.55-1's 200 matches are 42,417 characters thinned); Juice Shop 11.1.2 with
+// magento/community-edition 2.3.0 inserted at index 2 kept 2 of 51 rows (19 affected); that purl
+// alone kept none, and the note said "check 0 or fewer purls per call". Now, in order:
+//   1. SBOM_ROW_THIN, every row, every match (as before);
+//   2. the same, with every row's matches capped at one number m, the most that fit: a row with
+//      more than m keeps its first m (the API's order: highest effective_score first) and carries
+//      matches_truncated, its own total and returned, and the CVE IDs among all its matches that
+//      are KEV-listed (kev_listed_cve_ids) or used in ransomware (ransomware_cve_ids), and the
+//      distinct fixed_in versions they name (fixed_in_versions), so what a triage ranks by first
+//      is still said of the matches cut; rows with m or fewer matches are untouched;
+//   3. SBOM_ROW_COMPACT, each match cut to cve_id, kev_listed, ransomware, fixed_in and
+//      effective_score, the row keeping matched_package, matched_via and an upstream row's
+//      matched_version_from and purl_name, matches capped at one number m as in 2 (any m, 0
+//      included), with the same matches_truncated;
+//   4. SBOM_ROW_MIN, the text's leanest level (index, purl, verdict, not_assessed_reason and
+//      cve_ids), with that matches_truncated on each row that had matches;
+//   5. SBOM_ROW_MIN with matches_truncated cut to total and returned;
+// and only then do rows leave (clean, then not assessed, then the last of the rest).
+// #3132's review: round 1 had no level 3, and level 2 was taken at m = 0. The production
+// synthetic's 201-purl probe (synthetic/probes.mjs SBOM_PROBE_PURLS, recorded on hosted 3.0.0 with
+// full: true, 2026-10-11: 201 affected rows, 415 matches, 710,724 characters) then came back at
+// level 5 with 132 rows, every match, KEV flag and fixed_in gone, and the probe's EXPECT (log4j-core
+// 2.14.1's CVE-2021-44228 match, fixed_in 2.15.0; the upstream row's matched_via) failed, where
+// 3.0.0 kept 43 rows thinned and passed. So now:
+//   - level 2 is taken only at m >= 1 (least): at m = 0 it holds less than level 3;
+//   - when not even level 5 keeps every row, rows leave at level 3 with matches capped at
+//     SBOM_LEAVING_CAP (leaveAt), not at level 5: a page of the size the note names then comes back
+//     with each row's KEV flags and fixed_in, which at level 5 no page size did;
+//   - once the cut is settled, the rows kept take back detail in input order while the result fits
+//     (giveBack): each the richest level above its own that fits, its matches at the compact level
+//     at the most that fit, stopping at the first row that takes back none.
+// Measured on that recording (test/check_sbom-large-rows.test.mjs): 54 of 201 rows, each compact
+// with every match (none has more than 7), the log4j-core row with its CVE-2021-44228 match and the
+// upstream row with matched_via, at 29,959 characters.
+// cve_ids is what the API caps at 200 a row, about 3,400 characters, so every row survives level 5
+// unless the rows are many (the probe's 201, Juice Shop's full 840 purls).
+export const SBOM_ROW_COMPACT = [
+    "index",
+    "purl",
+    "verdict",
+    "not_assessed_reason",
+    "cve_ids",
+    "matched_package",
+    "matched_via",
+    "matched_version_from",
+    "purl_name",
+    ["matches", ["cve_id", "kev_listed", "ransomware", "fixed_in", "effective_score"]],
+];
+export const SBOM_ROW_MIN = ["index", "purl", "verdict", "not_assessed_reason", "cve_ids"];
+// The most matches a row keeps, compact, when rows leave (the API's order, highest effective_score
+// first); the rest are in its cve_ids and matches_truncated.
+export const SBOM_LEAVING_CAP = 10;
+// matches_truncated for a row whose matches data keeps `kept` of (none at levels 3 and 4); with
+// `summary`, the three lists drawn from all of the row's matches. Absent on a row with no match
+// cut, and on one with no matches.
+function matchesTruncated(row, kept, summary) {
+    const ms = Array.isArray(row.matches) ? row.matches.filter(isObj) : [];
+    if (ms.length <= kept)
+        return {};
+    const ids = (f) => [...new Set(ms.filter((m) => m[f] === true && typeof m.cve_id === "string").map((m) => m.cve_id))];
+    const fixed = [...new Set(ms.map((m) => m.fixed_in).filter((v) => typeof v === "string"))];
+    return {
+        matches_truncated: {
+            total: ms.length,
+            returned: Math.min(kept, ms.length),
+            ...(summary ? { kev_listed_cve_ids: ids("kev_listed"), ransomware_cve_ids: ids("ransomware"), fixed_in_versions: fixed } : {}),
+        },
+    };
+}
+const MATCHES_TRUNCATED_SAID = "carrying matches_truncated, which gives its own total and returned, and, of all its matches, the CVE IDs KEV-listed (kev_listed_cve_ids) or used in ransomware (ransomware_cve_ids) and the distinct fixed_in versions (fixed_in_versions)";
+const cappedSaid = (cap) => `each row's matches keeping at most its first ${cap} (the API's order, highest effective_score first), a row with more than that ${MATCHES_TRUNCATED_SAID}`;
+export const SBOM_ROW_LEVELS = [
+    SBOM_ROW_THIN,
+    { keep: SBOM_ROW_THIN, capped: "matches", least: 1, mark: (row, cap) => matchesTruncated(row, cap, true), said: cappedSaid },
+    { keep: SBOM_ROW_COMPACT, capped: "matches", mark: (row, cap) => matchesTruncated(row, cap, true), said: cappedSaid },
+    { keep: SBOM_ROW_MIN, mark: (row) => matchesTruncated(row, 0, true), said: () => `a row that had matches ${MATCHES_TRUNCATED_SAID}` },
+    { keep: SBOM_ROW_MIN, mark: (row) => matchesTruncated(row, 0, false), said: () => "a row that had matches carrying matches_truncated with its total and returned 0" },
+];
+const SBOM_LEAVE_AT = { level: 2, cap: SBOM_LEAVING_CAP };
+// The page sentence (#3132): never "0 or fewer". Rows leave only once no level keeps them all, so a
+// call of as many purls as data kept rows keeps each of its rows; when not one row fits, no page
+// size does, and the note says where a row is read instead.
+// #3132's review: the lists beside the rows go first, scan_manifest's not_checked before
+// not_sent_purls, which keeps every purl or none (whole): those purls are the list a client
+// retries, and round 1 kept 3 of the rate-limited case's 800. With none kept, the note gives them
+// exactly as positions in the input (sendingSentences: coverage.sent + 1 to
+// coverage.distinct_purls), and the room the rows leave goes back to not_sent_purls before
+// not_checked.
+export function sbomData(sides, page) {
+    const others = sides.filter((x) => x !== "not_sent_purls");
+    return {
+        steps: [
+            ...(others.length ? [{ lists: others }] : []),
+            ...(sides.includes("not_sent_purls") ? [{ lists: ["not_sent_purls"], whole: true }] : []),
+            {
+                lists: ["results"],
+                thin: SBOM_ROW_LEVELS,
+                leaveOutFirst: { field: "verdict", values: ["not_affected", "not_assessed"], why: "data.summary counts every verdict" },
+                leaveAt: SBOM_LEAVE_AT,
+                giveBack: true,
+            },
+        ],
+        page: (t) => t.results && t.results.returned < t.results.total
+            ? t.results.returned > 0
+                ? page(t.results.returned)
+                : `Not one row fits data even cut to ${SBOM_ROW_COMPACT.map((x) => (typeof x === "string" ? x : x[0])).join(", ")}, so no number of purls per call does: the same call with full: true returns every row whole.`
+            : "",
+    };
+}
+const SBOM_DATA = sbomData(["not_sent_purls"], (k) => `To read every row in data, check ${k} or fewer purls per call.`);
 // The purls of a CycloneDX JSON document: every components[] entry, nested ones included.
 // metadata.component (the subject of the SBOM, not a dependency of it) is not checked.
 function fromCycloneDX(doc) {
@@ -250,11 +394,15 @@ export function checkSbomOutput(envelopeSchema) {
         freshness: null,
     });
 }
+// One output schema per process, not per request (3.0.2; index.ts envelopeSchema says why).
+const OUTPUTS = new WeakMap();
 // A literal server.registerTool(name, { title, description, … }) call with constant strings:
 // marketing-site lib/mcpToolClaims.test.ts reads it here (it follows index.ts's call to this
 // function) and holds the /pulse/mcp row to this title and description.
 export function registerCheckSbom(server, deps) {
-    const output = checkSbomOutput(deps.envelopeSchema);
+    const envelope = deps.envelopeSchema;
+    const output = OUTPUTS.get(envelope) ?? checkSbomOutput(envelope);
+    OUTPUTS.set(envelope, output);
     server.registerTool(CHECK_SBOM, {
         title: CHECK_SBOM_TITLE,
         description: CHECK_SBOM_DESCRIPTION,
@@ -264,11 +412,12 @@ export function registerCheckSbom(server, deps) {
                 .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 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"),
+            full: FULL_ARG,
         }),
         outputSchema: output,
         annotations: deps.annotations,
-    }, async (a, ctx) => {
+    }, async (a, ctx) => answering(a.full, SBOM_DATA, async () => {
         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

@@ -41,7 +41,7 @@
 // the rows where fixed_version is not the whole answer.
 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";
+import { answering, FULL_ARG, 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"];
@@ -73,13 +73,22 @@ const LEFT_OUT = ["vendor_advisories", "patches", "ai", "trending", "historical_
 // Per-CVE row limits of the API (core-backend cve/enrichment_store.go): a list this long may be cut.
 const API_ROW_LIMIT = { exploits: 10, affected_packages: 50, fixed_versions: 200, timeline: 100 };
 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 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: EchelonGraph's cve_exploits records, whose data model holds public exploit code, namely Metasploit modules (metasploit), Exploit-DB entries (exploit_db), GitHub proof-of-concept repositories (github_poc) and vendor proofs of concept (vendor_poc), and Nuclei detection templates (nuclei_template), which check whether a system is affected and are not necessarily exploit code, 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.";
-const FIXED_BRANCHES_DESCRIPTION = 'fixed_branches lists each affected range of the package on record: introduced, and fixed (the range\'s fix) or last_affected (its last affected version, where no fix is on record), each null when absent, with advisory_id (the OSV record that published the range) and source (the loader\'s label for that record), both null on a row loaded before they were stored. Ranges with an advisory_id are in the order their record lists them (records in id order); ranges without one are oldest first. To pick the range for an installed version, compare in the ecosystem\'s version order (release numbers part by part, as numbers: 2.4 is below 2.13.0): the version is in a range when it is at or above introduced ("0" is the first version) and below fixed, or at or below last_affected; that range\'s fixed is the fix for it, and a version in no range is outside every range on record. fixed_branches is null where the package\'s ranges were never loaded, and [] where no version range is on record (the advisory gives none, only commit ranges, or more than are stored), which is not a finding that no fix exists: fixed_version can still name one. fixed_version is one range\'s fix, kept for compatibility (one per package: the range the loader kept, the advisory\'s last as a rule), not the fix for every affected range: for CVE-2021-44228, its advisory gives log4j-core three ranges, and fixed_version 2.12.2 is the fix for the one from 2.4, while the range holding 2.14.1 (from 2.13.0) is fixed in 2.15.0.';
+const FIXED_BRANCHES_DESCRIPTION = 'fixed_branches lists each affected range of the package on record: introduced, and fixed (the range\'s fix) or last_affected (its last affected version, where no fix is on record), each null when absent, with advisory_id (the OSV record that published the range) and source (the loader\'s label for that record), both null on a row loaded before they were stored. Ranges with an advisory_id are in the order their record lists them (records in id order); ranges without one are oldest first. To pick the range for an installed version, compare in the ecosystem\'s version order (release numbers part by part, as numbers: 2.4 is below 2.13.0): the version is in a range when it is at or above introduced ("0" is the first version) and below fixed, or at or below last_affected; its fix is that range\'s fixed, or, while another range still holds that, the other range\'s fixed (none past a range without one); a version in no range is outside every range on record. fixed_branches is null where the package\'s ranges were never loaded, and [] where no version range is on record (the advisory gives none, only commit ranges, or more than are stored), which is not a finding that no fix exists: fixed_version can still name one. fixed_version is one range\'s fix, kept for compatibility (one per package: the range the loader kept, the advisory\'s last as a rule), not the fix for every affected range: for CVE-2021-44228, its advisory gives log4j-core three ranges, and fixed_version 2.12.2 is the fix for the one from 2.4, while the range holding 2.14.1 (from 2.13.0) is fixed in 2.15.0.';
+// #3039: a Nuclei template is a detection check, not necessarily exploit code (core-backend
+// egkev.ExploitCodeKinds, #3038; /pulse words it so since #3022). The head says "exploit code,
+// detection templates" where it said "public exploit code"; the method and the note say what a
+// template is, and count templates apart. The room: "the newest" and "per-CVE" (14 characters).
 // #2876: the exploit dates are named for what they are. Within the 100 characters of headroom
 // under the 2048-character client cut (prompts-resources.test.mjs), the room came from tighter
 // glosses and from the input hint, which inputSchema's cve_id description carries.
-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 name and source), exploits (each with kind, source_name, source_url, source_published_at (the source's date, null if none), eg_first_seen_at (when EchelonGraph recorded it) and verified_status; at most 10, verified first) with exploits_total, exploits_capped, exploits_by_kind and exploits_by_status, affected_packages (ecosystem, package_name, version_range, fixed_version, fixed_branches), fixed_versions (each fixed version with the vulnerable_range it fixes) and timeline (the newest enrichment-history rows, with timeline_total). fixed_branches lists each affected range on record (introduced, and fixed or last_affected, with advisory_id (its OSV record) and source); in the ecosystem's version order, a version is in a range when it is at or above introduced ("0" is the first version) and below fixed, or at or below last_affected; that range's fixed is the fix for it. fixed_version is one range's fix, kept for compatibility, not the fix for every affected range. fixed_branches [] is not a finding that no fix exists. verified_status is the source's label, not a guarantee the exploit works on a given system. An empty exploits list is not evidence that no public exploit exists: it covers only the sources EchelonGraph ingests, and which 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. Its structured result carries notes, with data, which the first text block holds whole up to 30,000 characters; its coverage names the sections relayed, failed and left out. ${TEXT_BUDGET_DESCRIPTION}`;
+// #3013's review: in #3074's first cut the fixed_branches sentence still said a range's fixed is
+// the fix for a version it holds, the rule that gave lodash 4.17.15 under CVE-2026-4800 the
+// still-affected 4.17.21 (ranges [0, 4.17.21) and [4.0.0, 4.18.0); the fix is 4.18.0). It now
+// states the walk FIXED_BRANCHES_DESCRIPTION and branchSentences state, in fewer characters than
+// the old rule (a range's bounds folded into the list of its fields), so the headroom holds.
+export const CVE_INTEL_DESCRIPTION = `Weakness, exploit code, detection templates, affected packages and fixed versions for one CVE, from EchelonGraph's per-CVE enrichment. Returns cwes (each cwe_id with name and source), exploits (each with kind, source_name, source_url, source_published_at (the source's date, null if none), eg_first_seen_at (when EchelonGraph recorded it) and verified_status; at most 10, verified first) with exploits_total, exploits_capped, exploits_by_kind and exploits_by_status, affected_packages (ecosystem, package_name, version_range, fixed_version, fixed_branches), fixed_versions (each fixed version with the vulnerable_range it fixes) and timeline (newest enrichment-history rows, with timeline_total). fixed_branches lists each affected range on record (from introduced ("0" is the first version) to below fixed, or through last_affected, with advisory_id (its OSV record) and source); in the ecosystem's version order, an affected version's fix is the first fixed above it that no range of its row holds (none past a range with no fixed). fixed_version is one range's fix, kept for compatibility, not the fix for every affected range. fixed_branches [] is not a finding that no fix exists. verified_status is the source's label, not a guarantee the exploit works on a given system. An empty exploits list is not evidence that no public exploit exists: it covers only the sources EchelonGraph ingests, and which 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. Its structured result carries notes, with data, which the first text block holds whole up to 30,000 characters; its coverage names the sections relayed, failed and left out. ${TEXT_BUDGET_DESCRIPTION}`;
 // ── outputSchema ──
 const Rows = (shape) => z.array(z.looseObject(shape));
 const CountMap = z.record(z.string(), z.number());
@@ -173,6 +182,24 @@ function cweSentence(cve, cwes) {
     });
     return `${cve} is classified under ${listed(named)}.`;
 }
+// #3039: exploit code and detection templates are counted apart. A Nuclei template
+// (nuclei_template) checks whether a system is affected; it is not necessarily exploit code
+// (core-backend egkev.ExploitCodeKinds, #3038), and until #3039 the note called a Nuclei-only CVE's
+// one template "1 public exploit reference" (CVE-2026-42018 on the hosted endpoint, 2026-10-10;
+// 2,800 production CVEs hold only Nuclei rows). The kind counts are exploits_by_kind's, and where
+// the answer carries none, the listed rows' when they are every reference on record.
+const DETECTION_KIND = "nuclei_template";
+const DETECTION_NOTE = "a detection template checks whether a system is affected; it is not necessarily exploit code";
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+// The number of Nuclei detection templates among the references: exploits_by_kind's count where
+// the answer carries the map, the listed rows' where they are all of them, undefined otherwise.
+function templateCount(d, rows, total) {
+    const byKind = field(d, "exploits_by_kind");
+    if (byKind !== null && typeof byKind === "object" && !Array.isArray(byKind))
+        return numAt(d, "exploits_by_kind", DETECTION_KIND) ?? 0;
+    const listed = rows.filter((r) => strAt(r, "kind") === DETECTION_KIND).length;
+    return total === undefined || rows.length === total ? listed : undefined;
+}
 function exploitSentences(cve, d, rows) {
     const total = numAt(d, "exploits_total");
     const verified = numAt(d, "exploits_by_status", "verified");
@@ -186,7 +213,14 @@ function exploitSentences(cve, d, rows) {
                 `exploits is empty and the answer carries no exploits_total, so it does not count the references on record for ${cve}; an empty list is not evidence that no public exploit exists.`,
             ];
         }
-        return [`exploits lists ${rows.length} public exploit reference${rows.length === 1 ? "" : "s"} for ${cve}, ${verifiedRows} with verified_status verified; the answer carries no exploits_total, so it does not say how many are on record.${cut}`];
+        const listedTemplates = rows.filter((r) => strAt(r, "kind") === DETECTION_KIND).length;
+        const code = rows.length - listedTemplates;
+        const what = listedTemplates === 0
+            ? `${plural(rows.length, "public exploit reference", "public exploit references")}`
+            : code === 0
+                ? `${plural(rows.length, "Nuclei detection template", "Nuclei detection templates")} and nothing else (${DETECTION_NOTE})`
+                : `${plural(rows.length, "reference", "references")}: ${plural(code, "public exploit reference", "public exploit references")} and ${plural(listedTemplates, "Nuclei detection template", "Nuclei detection templates")} (${DETECTION_NOTE})`;
+        return [`exploits lists ${what} for ${cve}, ${verifiedRows} with verified_status verified; the answer carries no exploits_total, so it does not say how many are on record.${cut}`];
     }
     if (total === 0) {
         return [
@@ -195,7 +229,23 @@ function exploitSentences(cve, d, rows) {
     }
     const v = verified === undefined ? "" : `, ${verified} of them with verified_status verified`;
     const cut = capped === true ? ` exploits_capped is true: exploits lists ${rows.length} of the ${total}, verified first.` : "";
-    return [`EchelonGraph holds ${total} public exploit reference${total === 1 ? "" : "s"} for ${cve} (exploits_total)${v}.${cut}`];
+    const templates = templateCount(d, rows, total);
+    if (templates === undefined) {
+        return [
+            `EchelonGraph holds ${plural(total, "reference", "references")} for ${cve} (exploits_total)${v}; the answer carries no exploits_by_kind, so it does not say how many are exploit code and how many Nuclei detection templates (${DETECTION_NOTE}).${cut}`,
+        ];
+    }
+    if (templates === 0) {
+        return [`EchelonGraph holds ${plural(total, "public exploit reference", "public exploit references")} for ${cve} (exploits_total)${v}.${cut}`];
+    }
+    if (templates >= total) {
+        return [
+            `EchelonGraph holds ${plural(total, "Nuclei detection template", "Nuclei detection templates")} for ${cve} and nothing else in exploits (exploits_total ${total}): ${DETECTION_NOTE}. It holds no Metasploit module, Exploit-DB entry or proof of concept for ${cve}, which is not evidence that none exists.${cut}`,
+        ];
+    }
+    return [
+        `EchelonGraph holds ${plural(total, "reference", "references")} for ${cve} (exploits_total)${v}: ${plural(total - templates, "public exploit reference", "public exploit references")} and ${plural(templates, "Nuclei detection template", "Nuclei detection templates")}; ${DETECTION_NOTE}.${cut}`,
+    ];
 }
 function listSentence(name, rows) {
     const limit = API_ROW_LIMIT[name] ?? 0;
@@ -238,7 +288,7 @@ function branchSentences(rows) {
     });
     const few = (xs) => (xs.length <= 3 ? listed(xs) : `${xs.slice(0, 3).join(", ")} and ${xs.length - 3} more`);
     if (multi.length) {
-        out.push(`${multi.length} affected_packages row${multi.length === 1 ? " lists" : "s list"} more than one affected range in fixed_branches (${few(multi)}): there, fixed_version is one range's fix, and an installed version's fix is the fixed of the range that holds it.`);
+        out.push(`${multi.length} affected_packages row${multi.length === 1 ? " lists" : "s list"} more than one affected range in fixed_branches (${few(multi)}): there, fixed_version is one range's fix, and an installed version's fix is the first fixed above it that no range of the row holds: the fixed of the range that holds it, or, while another range still holds that version, that range's fixed (none where a range on the way has no fixed).`);
     }
     if (unknown.length) {
         out.push(`${unknown.length} affected_packages row${unknown.length === 1 ? " carries" : "s carry"} fixed_branches null (${few(unknown)}): ${unknown.length === 1 ? "its" : "their"} ranges are not on record, so fixed_version, one range's fix, is all the answer holds, and it need not be the fix for a given installed version.`);
@@ -345,13 +395,17 @@ export async function cveIntel(cve_id) {
         return crashed(TOOL, e);
     }
 }
+// #3013: the structured result's cut. CVE-2021-44228's is 12,877 characters, within the budget; past
+// it the newest enrichment-history rows go first, then the affected packages and fixed versions,
+// each to at most the same number of its first entries, then any other list at the top of data.
+const CVE_INTEL_DATA = { steps: [{ lists: ["timeline"] }, { lists: ["affected_packages", "fixed_versions"] }] };
 export function registerCveIntel(server) {
     const { output } = schemasOnce();
     server.registerTool("cve_intel", {
         title: "CVE weakness, exploits and packages",
         description: CVE_INTEL_DESCRIPTION,
-        inputSchema: z.object({ cve_id: z.string().describe("a CVE ID, e.g. CVE-2021-44228") }),
+        inputSchema: z.object({ cve_id: z.string().describe("a CVE ID, e.g. CVE-2021-44228"), full: FULL_ARG }),
         outputSchema: output,
         annotations: ANNOTATIONS,
-    }, async ({ cve_id }) => checked(TOOL, output, await cveIntel(cve_id)));
+    }, async ({ cve_id, full }) => checked(TOOL, output, await answering(full, CVE_INTEL_DATA, () => cveIntel(cve_id))));
 }