echelongraph-mcp 2.7.2 → 3.0.2

package/dist/tools/cve_remediation.js

@@ -7,13 +7,15 @@
 // What the answer holds:
 //   cisa                 CISA KEV's required_action, due_date, short_description and notes_urls
 //                        for a KEV-listed CVE. CISA directs the action at US federal civilian
-//                        agencies (BOD 22-01); it is not EchelonGraph's advice.
+//                        agencies (under BOD 26-04, which replaced BOD 22-01 on
+//                        10 June 2026); it is not EchelonGraph's advice.
 //   fixed_branches       each affected package with every affected range and its fix.
 //   vendor_remediations  each vendor advisory naming the CVE (at most 20, newest first), with its
 //                        remediation_state and the items it lists for the CVE, each with the
 //                        vendor's own category (kind): vendor_fix, workaround, mitigation,
 //                        no_fix_planned, none_available or other.
-//   fix_references       the record's references tagged Patch or Mitigation.
+//   fix_references       the record's references tagged Patch or Mitigation, by NVD, or patch or
+//                        mitigation, by the CNA (#2841: the API matches the tag in either case).
 //   patches              cve_patches rows.
 //   coverage             parsed_vendors, vendors_not_parsed and the caps.
 //   failed_sections      the sections the API could not read.
@@ -21,19 +23,40 @@
 // The rules the note keeps: not_parsed is not "no remediation"; none_in_source is what the
 // advisory lists, not a finding that no fix exists; an empty section is "none on record", never
 // "no fix"; a failed section is named, never relayed as empty. A REJECTED CVE is not_assessed.
+//
+// fix_status (#2841, #2518 item 3) is the API's fix-status rule (core-backend cve/fixstatus.go,
+// the rule /pulse pages render), relayed: this file derives nothing from it.
+//
+// The installed version (#2841): ecosystem, package and version, all three or none. They travel
+// in the X-EG-Ecosystem, X-EG-Package and X-EG-Version request headers, percent-encoded as
+// check_affected sends them, and never in the URL (#1983: Cloud Run's request log records the URL
+// and no request header). The API answers installed (what was asked and its verdict) and fixed_in,
+// the first version above it that no affected range on record holds (the fixed bound of the range
+// holding it, moved past any overlapping range, with fixed_in_detail naming it, #3074), or null
+// with fixed_in_reason, from the registry matcher check_affected's registry path runs; that answer
+// is private, no-store.
 import * as z from "zod";
 import { ANNOTATIONS, CVE_ID, SHOWN_BASE, api, badInput, checked, crashed, envelopeSchema, failed, failure, field, NOT_A_FINDING, okHead, opt, strAt, succeeded } from "../index.js";
-import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
+import { answering, FULL_ARG, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
+import { fixStatusSchema } from "../fixStatus.js";
+import { MATCH_HEADERS } from "./check_affected.js";
 const TOOL = "cve_remediation";
 const SECTIONS = ["cisa", "fixed_branches", "vendor_remediations", "fix_references", "patches"];
 const KINDS = ["vendor_fix", "workaround", "mitigation", "no_fix_planned", "none_available", "other"];
 const STATES = ["parsed", "none_in_source", "not_parsed", "withdrawn"];
+// core-backend cve/pkgmatch_fixedin.go InstalledFix's verdicts.
+const VERDICTS = ["affected", "not_affected", "undetermined", "not_assessed"];
+// The installed version's arguments, in the order the headers are named.
+const INSTALLED = ["ecosystem", "package", "version"];
 // Required in the description's head (src/requiredText.ts REQUIRED_IN_HEAD.cve_remediation).
 export const REMEDIATION_UNTESTED = "Every text is relayed as stated by its source; EchelonGraph has not tested it.";
 export const REMEDIATION_NOT_A_ZERO = "An empty list or a remediation_state of none_in_source or not_parsed is not a finding that no fix exists.";
-export const REMEDIATION_CISA = "CISA's required_action is directed at US federal civilian agencies (BOD 22-01) and is not EchelonGraph's advice.";
-const METHOD = "EchelonGraph's stored sources for one CVE (GET /api/v1/public/cves/:id/remediation): CISA's Known Exploited Vulnerabilities catalog text; the affected ranges and fixes of OSV advisories; the remediation each vendor advisory lists, categorised by the vendor's own category (Red Hat CSAF remediations, MSRC CVRF Workaround, Mitigation and Vendor Fix rows, Palo Alto's solution and work_around sections); the CVE record's references NVD tagged Patch or Mitigation; and cve_patches. Nothing is generated or tested.";
-export const CVE_REMEDIATION_DESCRIPTION = `How one CVE is fixed, as its sources state it, in one answer. ${REMEDIATION_UNTESTED} ${REMEDIATION_NOT_A_ZERO} Returns cisa (kev_listed, and for a KEV-listed CVE CISA's required_action, due_date, short_description and notes_urls, verbatim; ${REMEDIATION_CISA}), fixed_branches (each affected package with fixed_branches: every affected range, introduced and fixed or last_affected, and fixed_version, one range's fix), vendor_remediations (each vendor advisory naming the CVE, newest first, at most 20: vendor, vendor_advisory_id, remediation_state, remediation_kinds and items, each item with kind, source_category, text, url, fixed_build, product_ids and product_count), fix_references (the record's references NVD tagged Patch or Mitigation), patches, coverage (parsed_vendors, vendors_not_parsed and the caps) and failed_sections. kind is the vendor's own category, never read from the text: vendor_fix, workaround, mitigation, no_fix_planned, none_available, or other with the vendor's name for it in source_category. remediation_state is parsed, none_in_source (parsed; the advisory lists none for this CVE), not_parsed (EchelonGraph does not read that vendor's remediation) or withdrawn. A section the API could not read is named in failed_sections and coverage.sections_failed, never relayed as empty. A REJECTED CVE answers not_assessed. Pass a CVE ID like CVE-2021-44228. ${TEXT_BUDGET_DESCRIPTION} Cut, vendor texts are shortened first; kinds, states and URLs are kept.`;
+export const REMEDIATION_CISA = "CISA's required_action is directed at US federal civilian agencies (under BOD 26-04, which replaced BOD 22-01 on 10 June 2026) and is not EchelonGraph's advice.";
+const METHOD = "EchelonGraph's stored sources for one CVE (GET /api/v1/public/cves/:id/remediation): CISA's Known Exploited Vulnerabilities catalog text; the affected ranges and fixes of OSV advisories; the remediation each vendor advisory lists, categorised by the vendor's own category (Red Hat CSAF remediations, MSRC CVRF Workaround, Mitigation and Vendor Fix rows, Palo Alto's solution and work_around sections); the CVE record's references tagged Patch or Mitigation by NVD, or patch or mitigation by the CNA; and cve_patches. Nothing is generated or tested.";
+// #3084 (merged from 24dad5eb): REMEDIATION_CISA names BOD 26-04, which replaced BOD 22-01, 48 characters
+// longer, which left this description 71 under the 2048-character cut (#2924's floor is 100); the
+// remediation_state parentheses and the failed_sections sentence are said shorter, every claim kept.
+export const CVE_REMEDIATION_DESCRIPTION = `How one CVE is fixed, as its sources state it, in one answer. ${REMEDIATION_UNTESTED} ${REMEDIATION_NOT_A_ZERO} Returns fix_status (the API's fix-status rule, as CVE Pulse shows it: state and basis), cisa (for a KEV-listed CVE CISA's required_action, due_date, short_description and notes_urls, verbatim; ${REMEDIATION_CISA}), fixed_branches (each affected package with fixed_branches: every affected range, introduced and fixed or last_affected, and fixed_version, one range's fix), vendor_remediations (each vendor advisory naming the CVE, newest first, at most 20, with remediation_state, remediation_kinds and items, each with kind, source_category, text and url), fix_references (references NVD or the CNA tagged Patch or Mitigation), patches, coverage and failed_sections. kind is the vendor's own category, never read from the text: vendor_fix, workaround, mitigation, no_fix_planned, none_available or other. remediation_state is parsed, none_in_source (none listed for this CVE), not_parsed (that vendor's remediation is not read) or withdrawn. ecosystem, package and version (all three or none, sent in request headers, never in the URL) add installed, the verdict at that version, and fixed_in, the lowest unaffected version above it, or null with fixed_in_reason. A section the API could not read is named in failed_sections, not relayed as empty. A REJECTED CVE answers not_assessed. ${TEXT_BUDGET_DESCRIPTION} Cut, vendor texts are shortened first; kinds, states and URLs are kept.`;
 // ── outputSchema ──
 // Built on first use: index.ts imports this file, so its exports are not initialised while this
 // module's top level runs.
@@ -67,6 +90,19 @@ function schemas() {
         cve_id: opt(z.string()),
         state: opt(z.string()).describe("assessed, or not_assessed for a CVE record rejected by its numbering authority."),
         not_assessed_reason: opt(z.string()),
+        fix_status: fixStatusSchema(),
+        installed: opt(z.looseObject({
+            ecosystem: opt(z.string()).describe("The ecosystem asked for, in its canonical OSV spelling."),
+            ecosystem_recognised: opt(z.boolean()),
+            package: opt(z.string()),
+            version: opt(z.string()),
+            verdict: opt(z.union([z.enum(VERDICTS), z.string()])).describe("affected (a range on record holds the version), not_affected (no range on record holds it), undetermined (a range could not be decided at it) or not_assessed (the record names no such package for this CVE, or the lookup did not run)."),
+            version_evidence: opt(z.string()),
+            interval: opt(z.looseObject({ introduced: opt(z.string()), fixed: opt(z.string()), last_affected: opt(z.string()) })).describe("The affected range holding the version (fixed is exclusive, last_affected inclusive); absent when none holds it."),
+        })).describe("The installed version asked for, as the API read it from the request headers, and its verdict against this CVE; absent when none was asked."),
+        fixed_in: opt(z.string()).describe("With an installed version: the first version above it that no affected range on record holds, always above it, as the advisory states it: the fixed bound of the range holding it, moved past any overlapping range that still holds that bound (fixed_in_detail then names it). null when no range on record holds it, no fix is on record past the ranges holding it, or the version was not assessed, with fixed_in_reason saying which. Absent when no installed version was asked."),
+        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 range holding the installed version: the overlapping ranges of the same record it moved past, which still hold that bound."),
         cisa: z
             .looseObject({
             kev_listed: opt(z.boolean()),
@@ -88,6 +124,10 @@ function schemas() {
                 advisory_id: opt(z.string()),
                 source: opt(z.string()),
             }))),
+            fixed_branches_truncated: z
+                .object({ total: z.number().int(), returned: z.number().int() })
+                .optional()
+                .describe("Present only where the structured result's cut (DATA CUT) kept this package's first ranges, not all: total, its ranges in the answer; returned, the ones data keeps. The same call with full: true returns every range."),
         }))),
         vendor_remediations: opt(z.array(VendorAdvisory)),
         fix_references: opt(z.array(z.looseObject({ url: opt(z.string()), tags: opt(z.array(z.string())), source: opt(z.string()) }))),
@@ -103,6 +143,10 @@ function schemas() {
         vendor_advisory_limit: z.number().nullable(),
         item_text_cap: z.number().nullable(),
         items_per_advisory_cap: z.number().nullable(),
+        installed_asked: z
+            .strictObject({ ecosystem: z.string(), package: z.string(), version: z.string() })
+            .nullable()
+            .describe("The installed version this call sent (in request headers), as given; null when none."),
     });
     return { output: envelopeSchema({ data, coverage, freshness: null }) };
 }
@@ -115,8 +159,107 @@ const CUT = {
         { keep: ["vendor", "vendor_advisory_id", "withdrawn", "remediation_state", "remediation_kinds", "items_total", ["items", ["kind", "source_category", "text", "url", "fixed_build"]]], clip: 400, cap: 16 },
         { keep: ["vendor", "vendor_advisory_id", "remediation_state", "remediation_kinds", ["items", ["kind", "url"]]], clip: 2048, cap: 8 },
     ],
-    whole: "get_vendor_advisory returns any one of these advisories by its vendor and vendor_advisory_id, whole in its structuredContent.data, with every remediation item it lists.",
+    whole: "get_vendor_advisory returns any one of these advisories by its vendor and vendor_advisory_id, whole in its structuredContent.data with full: true, with every remediation item it lists.",
+};
+// #3013: the structured result's cut. CVE-2021-44228's answer is 75,963 characters of structured
+// result, 61,248 of them its 20 vendor_remediations, whose items carry the vendor's text (about 550
+// characters an item, the payload) and its product_ids (about 550, the vendor's own identifiers).
+// Before any advisory leaves, every advisory's items are thinned: product_ids first, keeping each
+// text; then the texts, keeping each item's kind, source_category, url and fixed_build, so every
+// advisory stays named with its state, kinds and links (get_vendor_advisory returns one whole).
+// fix_status and fixed_in (#2841) are not lists, and installed is an object, so none of them is
+// ever cut.
+//
+// #3139: through 3.0.0 advisories then left from the end, before patches, and fixed_branches had no
+// step, so CVE-2023-44487 (KEV-listed) kept 2 of its 20 advisories at 29,704 characters while
+// fixed_branches (13,581 characters, 50 rows) and patches (7,471, 30) stayed whole, and the note
+// named no tool that lists the other 18 (measured on hosted 3.0.0, 2026-10-11; also CVE-2018-12126
+// 6/20, CVE-2019-11135 2/3, CVE-2018-3639 16/20). Now vendor_remediations is a keepAll step: every
+// advisory stays, thinned, while patches (each to its vendor, patch_url and published_at: the
+// erratum, which vendor_remediations names again for Red Hat) and then fixed_branches (each to its
+// package, range, fixed_version and its ranges' introduced, fixed and last_affected, what the
+// sbom_review prompt walks; the per-range source, advisory_id and dependents_count go) are thinned
+// and then lose rows from the end, and then any other list at the top of data (fix_references).
+// Only when all of that is cut and the result is still past the budget do advisories leave, from
+// the end; whenever one does, the note names vendor_advisories_for_cve, which lists every vendor
+// advisory naming the CVE, as where the rest are.
+// #3139's review: that order dropped 2 of CVE-2023-44487's 30 patches while its 50 fixed_branches
+// rows stayed whole (13,581 characters). Decided (2026-10-11): fixed_branches is thinned before any
+// patch row leaves. The order is now:
+//   1. vendor_remediations thinned, as above, every advisory kept (keepAll);
+//   2. fixed_branches thinned (each package to its ecosystem, package_name, version_range,
+//      fixed_version and its ranges' introduced, fixed and last_affected: each range's source and
+//      advisory_id go, and the package's dependents_count and source), then each package's ranges
+//      capped at one number, the most that fit (at least 1), a package with more carrying
+//      fixed_branches_truncated with its total and returned; every package kept (keepAll);
+//   3. patches thinned (vendor, patch_url and published_at), every patch kept (keepAll);
+//   4. any other list at the top of data (fix_references), cut from the end;
+//   5. then patch rows leave from the end, then fixed_branches rows, and only then advisories
+//      (textBudget.ts: the last keepAll step's entries leave first);
+//   6. the room left goes back to each package's ranges, in the order of fixed_branches (giveBack):
+//      step 2 caps them before the patches are cut, and a cap that held while every patch was
+//      whole would otherwise stay after the patches are thinned.
+// Round 2 replayed CVE-2023-44487 at 28 of 30 patches: fix_references (2,191 characters) were cut
+// after patch rows left, and the 30 thinned were about 240 characters past the budget beside them.
+// Round 3 (#3139's second review, 2026-10-11): patches is a keepAll step, so fix_references are cut
+// first and CVE-2023-44487 keeps all 20 advisories, all 50 fixed_branches and all 30 patches, each
+// thinned (test/cve_remediation.test.mjs); round 1 (patches cut before fixed_branches was thinned)
+// kept 11 patches without fix_references.
+//
+// #3013's review: the second level leaves every item's text out of data, and the text is the
+// vendor's step itself (a workaround's or mitigation's wording), which the triage_cve and
+// sbom_review prompts have the model quote. No string is shortened (the cut's rule), so the note
+// says the text is gone and where each one is: get_vendor_advisory, by the advisory's vendor and
+// vendor_advisory_id, returns that advisory's remediations with their texts, and the same call
+// with full: true returns this data whole; the prompts send the model there when it is cut.
+const ADVISORY_FIELDS = ["vendor", "vendor_display_name", "vendor_advisory_id", "vendor_published_at", "withdrawn", "remediation_state", "remediation_kinds", "items_total"];
+const ITEM_TEXT_ELSEWHERE = "No item in data keeps its text, the vendor's own wording of the step (a workaround or mitigation among them): get_vendor_advisory, given an advisory's vendor and its vendor_advisory_id as advisory_id, returns it among that advisory's remediations, whole in its structuredContent.data with full: true.";
+const FIXED_BRANCHES_THIN = ["ecosystem", "package_name", "version_range", "fixed_version", ["fixed_branches", ["introduced", "fixed", "last_affected"]]];
+const CVE_REMEDIATION_DATA = {
+    steps: [
+        {
+            lists: ["vendor_remediations"],
+            thin: [
+                [...ADVISORY_FIELDS, ["items", ["kind", "source_category", "source_subcategory", "text", "text_truncated", "text_chars", "url", "fixed_build", "product_count"]]],
+                [...ADVISORY_FIELDS, ["items", ["kind", "source_category", "url", "fixed_build"]]],
+            ],
+            keepAll: true,
+        },
+        {
+            lists: ["fixed_branches"],
+            thin: [
+                FIXED_BRANCHES_THIN,
+                {
+                    keep: FIXED_BRANCHES_THIN,
+                    capped: "fixed_branches",
+                    least: 1,
+                    mark: (row, cap) => {
+                        const n = Array.isArray(row.fixed_branches) ? row.fixed_branches.length : 0;
+                        return n > cap ? { fixed_branches_truncated: { total: n, returned: cap } } : {};
+                    },
+                    said: (cap) => `each package's fixed_branches keeping at most its first ${cap} ranges, a package with more carrying fixed_branches_truncated with its total and returned`,
+                },
+            ],
+            keepAll: true,
+            giveBack: true,
+        },
+        // #3139 round 3: every patch row stays, thinned (keepAll), while the step after it (any other
+        // list at the top of data: fix_references) is cut; patch rows leave only after that, and
+        // before any fixed_branches row or advisory (the last keepAll step's entries leave first).
+        { lists: ["patches"], thin: [["vendor", "patch_url", "published_at"]], keepAll: true },
+    ],
+    // Said where the advisories kept are thinned to a level whose items keep no text, and (#3139)
+    // wherever an advisory is left out.
+    page: (t, _d, at) => {
+        const items = at.keeps.vendor_remediations?.find((x) => typeof x !== "string" && x[0] === "items");
+        const v = t.vendor_remediations;
+        return [items && !items[1].includes("text") ? ITEM_TEXT_ELSEWHERE : "", v && v.returned < v.total ? advisoriesElsewhere(v.total - v.returned) : ""].filter(Boolean).join(" ");
+    },
 };
+// #3139: where the advisories a cut leaves out are read. vendor_advisories_for_cve lists every one
+// naming the CVE, with its vendor and vendor_advisory_id (CVE-2023-44487's 20 at 15,505
+// characters on hosted 3.0.0), and get_vendor_advisory then returns any one whole.
+const advisoriesElsewhere = (n) => `vendor_advisories_for_cve, given this CVE, lists every vendor advisory naming it, the ${n} left out of data among them, each with its vendor and vendor_advisory_id.`;
 const listed = (xs) => (xs.length <= 1 ? (xs[0] ?? "") : `${xs.slice(0, -1).join(", ")} and ${xs.at(-1)}`);
 const arr = (v) => (Array.isArray(v) ? v : null);
 const strs = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string") : null);
@@ -162,18 +305,70 @@ function branchSentence(rows) {
                 fixed++;
         }
     }
-    return `fixed_branches lists ${rows.length} affected package${rows.length === 1 ? "" : "s"} with ${ranges} affected range${ranges === 1 ? "" : "s"}, ${fixed} with a fix on record; an installed version's fix is the fixed of the range that holds it, compared in the ecosystem's version order.`;
+    return `fixed_branches lists ${rows.length} affected package${rows.length === 1 ? "" : "s"} with ${ranges} affected range${ranges === 1 ? "" : "s"}, ${fixed} with a fix on record; an installed version's fix is the first fixed above it that no range of its package holds (the fixed of the range that holds it, or, while another range still holds that version, that range's fixed), compared in the ecosystem's version order.`;
 }
-export async function cveRemediation(cve_id) {
-    const id = cve_id.trim();
+// fix_status's sentence: what the API's rule says, relayed. Nothing about the fix is inferred here.
+function fixStatusSentence(cve, fs) {
+    if (fs === null || fs === undefined)
+        return null;
+    const state = strAt(fs, "state");
+    if (!state)
+        return null;
+    const basis = strAt(fs, "basis");
+    const unread = Array.isArray(field(fs, "unread_inputs")) ? field(fs, "unread_inputs").filter((x) => typeof x === "string") : [];
+    const why = state === "none_confirmed" ? ", which is not a finding that no fix exists" : "";
+    const notRead = unread.length ? `; it rests without ${listed(unread)}, which the API could not read (unread_inputs)` : "";
+    // #3076, third pass: what vendor_fix_released evidence is, so "available" is not read as more
+    // than it says. Relayed from the field the API set, nothing inferred.
+    const released = field(fs, "vendor_released");
+    const qualifier = released !== null && released !== undefined && typeof released === "object"
+        ? `; the vendor states a fix is released, but the CVE record names no fixed version (vendor_released), so the fixed release is the vendor advisory's to name`
+        : "";
+    return `fix_status for ${cve} is ${state}${basis ? ` (basis ${basis})` : ""}, the API's fix-status rule${why}${qualifier}${notRead}.`;
+}
+// The sentence on the installed version asked: what the API answered for it, relayed.
+function installedSentence(asked, d) {
+    const who = `${asked.ecosystem} ${asked.package} ${asked.version}`;
+    if (!("fixed_in" in d)) {
+        return `The answer carries no fixed_in for the installed version asked (${who}): the API did not assess it, which is not a finding either way.`;
+    }
+    const inst = field(d, "installed");
+    const verdict = strAt(inst, "verdict");
+    const fixedIn = strAt(d, "fixed_in");
+    if (fixedIn) {
+        // #3074: fixed_in moved past an overlapping range, so it is not the holding range's bound.
+        const detail = strAt(d, "fixed_in_detail");
+        if (detail) {
+            return `For the installed version asked (${who}), installed.verdict is ${verdict ?? "not given"} and fixed_in is ${fixedIn}: the first version above it that no affected range on record holds (${detail}), as the advisory states it; EchelonGraph has not tested it.`;
+        }
+        const lo = strAt(field(inst, "interval"), "introduced");
+        const range = lo ? ` [${lo}, ${fixedIn})` : "";
+        return `For the installed version asked (${who}), installed.verdict is ${verdict ?? "not given"} and fixed_in is ${fixedIn}: the fixed bound of the affected range${range} that holds it, as the advisory states it; EchelonGraph has not tested it.`;
+    }
+    const reason = strAt(d, "fixed_in_reason") ?? "the answer gives no fixed_in_reason";
+    return `For the installed version asked (${who}), installed.verdict is ${verdict ?? "not given"} and fixed_in is null: ${reason}.`;
+}
+export async function cveRemediation(args) {
+    const id = (args.cve_id ?? "").trim();
     if (!id)
         return badInput(TOOL, "cve_id is required");
     if (!CVE_ID.test(id))
         return badInput(TOOL, `cve_id ${JSON.stringify(id.slice(0, 32))} is not a CVE id (expected the form CVE-2021-44228)`);
+    // The installed version: all three or none.
+    const given = { ecosystem: (args.ecosystem ?? "").trim(), package: (args.package ?? "").trim(), version: (args.version ?? "").trim() };
+    const present = INSTALLED.filter((k) => given[k] !== "");
+    const missing = INSTALLED.filter((k) => given[k] === "");
+    if (present.length > 0 && missing.length > 0) {
+        return badInput(TOOL, `ecosystem, package and version go together, all three or none: ${listed([...missing])} ${missing.length === 1 ? "is" : "are"} missing (given: ${listed([...present])})`);
+    }
+    const asked = present.length === INSTALLED.length ? given : null;
     const cve = id.toUpperCase();
     const path = `/api/v1/public/cves/${encodeURIComponent(cve)}/remediation`;
+    // #1983: percent-encoded, as the backend's matchHeaderValue decodes them; never in the URL.
+    const enc = encodeURIComponent;
+    const headers = asked ? { [MATCH_HEADERS.ecosystem]: enc(asked.ecosystem), [MATCH_HEADERS.package]: enc(asked.package), [MATCH_HEADERS.version]: enc(asked.version) } : undefined;
     try {
-        const r = await api(path);
+        const r = await api(path, headers ? { headers } : undefined);
         if (!r.ok)
             return failed(TOOL, r);
         const d = r.data;
@@ -197,11 +392,13 @@ export async function cveRemediation(cve_id) {
             vendor_advisory_limit: typeof field(cov, "vendor_advisory_limit") === "number" ? field(cov, "vendor_advisory_limit") : null,
             item_text_cap: typeof field(cov, "item_text_cap") === "number" ? field(cov, "item_text_cap") : null,
             items_per_advisory_cap: typeof field(cov, "items_per_advisory_cap") === "number" ? field(cov, "items_per_advisory_cap") : null,
+            installed_asked: asked,
         };
         const head = okHead(TOOL, r.status);
         if (state === "not_assessed") {
             const reason = strAt(d, "not_assessed_reason") ?? "the API gives no reason";
-            return succeeded(d, `${head} NOT ASSESSED: ${cve}'s remediation is not assessed (${reason}). A rejected CVE record is not an active vulnerability, so no fix is relayed for it.`, {
+            const inst = asked ? ` ${installedSentence(asked, d)}` : "";
+            return succeeded(d, `${head} NOT ASSESSED: ${cve}'s remediation is not assessed (${reason}). A rejected CVE record is not an active vulnerability, so no fix is relayed for it.${inst}`, {
                 state: "not_assessed",
                 measured_at: null,
                 method: METHOD,
@@ -211,6 +408,11 @@ export async function cveRemediation(cve_id) {
             });
         }
         const said = [];
+        const fixSaid = fixStatusSentence(cve, field(d, "fix_status"));
+        if (fixSaid)
+            said.push(fixSaid);
+        if (asked)
+            said.push(installedSentence(asked, d));
         const cisa = field(d, "cisa");
         const action = strAt(cisa, "required_action");
         if (field(cisa, "kev_listed") === true) {
@@ -225,8 +427,12 @@ export async function cveRemediation(cve_id) {
         if (vendors && !(reported ?? []).includes("vendor_remediations"))
             said.push(...vendorSentences(cve, vendors));
         const refs = arr(field(d, "fix_references"));
-        if (refs)
-            said.push(refs.length ? `fix_references lists ${refs.length} reference${refs.length === 1 ? "" : "s"} the CVE record tags Patch or Mitigation.` : "No reference of the CVE record is tagged Patch or Mitigation.");
+        // #2841: the API keeps both spellings, NVD's (Patch, Mitigation) and a CNA's (patch, mitigation).
+        if (refs) {
+            said.push(refs.length
+                ? `fix_references lists ${refs.length} reference${refs.length === 1 ? "" : "s"} the CVE record tags as a patch or mitigation (NVD's Patch or Mitigation, or the CNA's patch or mitigation), each with the tags as written.`
+                : "No reference of the CVE record is tagged as a patch or mitigation, in NVD's spelling (Patch, Mitigation) or the CNA's (patch, mitigation).");
+        }
         if (reported === null)
             said.push("The answer carries no failed_sections, so an empty section may be one the API could not read, not a finding of none.");
         else if (reported.length)
@@ -250,8 +456,16 @@ export function registerCveRemediation(server) {
     server.registerTool(TOOL, {
         title: "How one CVE is fixed",
         description: CVE_REMEDIATION_DESCRIPTION,
-        inputSchema: z.object({ cve_id: z.string().describe("a CVE ID, e.g. CVE-2021-44228") }),
+        inputSchema: CVE_REMEDIATION_INPUT,
         outputSchema: output,
         annotations: ANNOTATIONS,
-    }, async ({ cve_id }) => checked(TOOL, output, await cveRemediation(cve_id)));
+    }, async (args) => checked(TOOL, output, await answering(args.full, CVE_REMEDIATION_DATA, () => cveRemediation(args))));
 }
+// The installed version is optional and all-or-none (cveRemediation refuses a partial set).
+export const CVE_REMEDIATION_INPUT = z.object({
+    cve_id: z.string().describe("a CVE ID, e.g. CVE-2021-44228"),
+    ecosystem: z.string().optional().describe("Installed version, with package and version: the package's ecosystem, such as npm, PyPI or Maven. Sent in a request header."),
+    package: z.string().optional().describe("Installed version, with ecosystem and version: the package name in that ecosystem, such as org.apache.logging.log4j:log4j-core. Sent in a request header."),
+    version: z.string().optional().describe("Installed version, with ecosystem and package: the version installed, such as 2.14.1. Sent in a request header."),
+    full: FULL_ARG,
+});

package/dist/tools/epss_history.js

@@ -1,5 +1,5 @@
 import * as z from "zod";
-import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
+import { answering, FULL_ARG, NO_DATA_CUT, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 const TOOL = "epss_history";
 const CVE_ID = /^CVE-\d{4}-\d{4,}$/i;
 export const EPSS_HISTORY_METHOD = "EchelonGraph's record of FIRST's EPSS scores: the nightly EPSS fetcher overwrites each CVE's epss_score and epss_percentile from FIRST's published file and, for every CVE whose value changed, records the new values with the time it wrote them; this series is those records, oldest first, with repeated records of one change collapsed into the first.";
@@ -208,13 +208,19 @@ export async function epssHistory(kit, cve_id) {
         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 registerEPSSHistory(server, kit) {
-    const output = epssHistoryOutput(kit);
+    const output = OUTPUTS.get(kit) ?? epssHistoryOutput(kit);
+    OUTPUTS.set(kit, output);
     server.registerTool(TOOL, {
         title: "EPSS change history for one CVE",
         description: EPSS_HISTORY_DESCRIPTION,
-        inputSchema: z.object({ cve_id: kit.cveIdArg }),
+        inputSchema: z.object({ cve_id: kit.cveIdArg, full: FULL_ARG }),
         outputSchema: output,
         annotations: kit.annotations,
-    }, async ({ cve_id }) => kit.checked(TOOL, output, await epssHistory(kit, cve_id)));
+    }, 
+    // #3013: a few points a CVE, the API's own cap on them, 2,508 characters for CVE-2021-44228:
+    // no list is named, so only a list at the top level of data would be cut past the budget.
+    async ({ cve_id, full }) => kit.checked(TOOL, output, await answering(full, NO_DATA_CUT, () => epssHistory(kit, cve_id))));
 }

package/dist/tools/get_cwe.js

@@ -13,7 +13,7 @@
 // the note says it can lag the feed.
 import * as z from "zod";
 import { ANNOTATIONS, api, badInput, checked, crashed, envelopeSchema, failed, field, lenAt, numAt, okHead, opt, rowsScoreNote, strAt, succeeded, } from "../index.js";
-import { GET_CVE_WHOLE, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
+import { answering, FULL_ARG, GET_CVE_WHOLE, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 const TOOL = "get_cwe";
 const CWE_ARG = /^(?:CWE-)?0*(\d{1,6})$/i;
 const MAX_PAGE = 200;
@@ -27,6 +27,10 @@ const GET_CWE_TEXT = {
     levels: [{ keep: ["cve_id", "severity", "cvss_v3_score", "echelongraph_score", "echelongraph_severity", "score_assessed", "score_unassessed_reason", "kev_listed", "published", "description"], clip: 120 }],
     whole: `${GET_CVE_WHOLE}.`,
 };
+// #3013: the structured result's cut. CWE-79's page of 50 is 24,276 characters of structured result,
+// within the budget; rows a few times longer leave data from the end. A page is always 50 rows, so
+// full: true is the only way to read the rest of one.
+const GET_CWE_DATA = { steps: [{ lists: ["cves"] }] };
 function schemas() {
     const row = z.looseObject({
         cve_id: opt(z.string()),
@@ -150,8 +154,9 @@ export function registerGetCwe(server) {
         inputSchema: z.object({
             cwe_id: z.string().describe("a CWE ID, e.g. CWE-79 (or 79)"),
             page: z.number().int().min(1).max(MAX_PAGE).optional().describe(`page of 50 CVEs (default 1, max ${MAX_PAGE})`),
+            full: FULL_ARG,
         }),
         outputSchema: output,
         annotations: ANNOTATIONS,
-    }, async ({ cwe_id, page }) => checked(TOOL, output, await getCwe(cwe_id, page)));
+    }, async ({ cwe_id, page, full }) => checked(TOOL, output, await answering(full, GET_CWE_DATA, () => getCwe(cwe_id, page))));
 }

package/dist/tools/kev_recent.js

@@ -1,5 +1,5 @@
 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 = "kev_recent";
 const PATH = "/api/v1/public/kev/recent";
 export const KEV_RECENT_MAX_LIMIT = 200;
@@ -145,6 +145,21 @@ function kevText(a) {
         page: (shown) => `next_cursor continues after the last row of this page, not after the last row in this text: to read the rows left out in the text, call kev_recent again with the same filters${a.cursor?.trim() ? " and cursor" : ""} and a limit of ${shown}, whose rows are the ones in this text, then with that page's next_cursor and a limit of ${shown} or fewer.`,
     };
 }
+// #3013: the structured result's cut. A production row is about 400 characters of compact JSON, so
+// the default page of 50 fits (23,234 characters of structured result) and the largest, 200, was
+// 84,380: rows leave data from the end, and, as for the text, the note says how to read them
+// without skipping one, since next_cursor continues after the page, not after data's last row.
+function kevData(a) {
+    return {
+        steps: [{ lists: ["kev"] }],
+        page: (t) => {
+            const k = t.kev?.returned;
+            if (!k)
+                return "";
+            return `next_cursor continues after the last row of this page, not after the last row in data: to read the rows data leaves out, call kev_recent again with the same filters${a.cursor?.trim() ? " and cursor" : ""} and a limit of ${k}, whose rows are the ones in data, then with that page's next_cursor and a limit of ${k} or fewer.`;
+        },
+    };
+}
 async function kevRecent(d, a) {
     try {
         const h = headersFor(a);
@@ -208,9 +223,12 @@ async function kevRecent(d, a) {
         return d.crashed(TOOL, e);
     }
 }
+// One output schema per process, not per request (3.0.2; index.ts envelopeSchema says why).
+const OUTPUTS = new WeakMap();
 // Registers the tool on a server built by index.ts's createServer.
 export function registerKevRecent(server, d) {
-    const output = d.envelopeSchema({ data: Data, coverage: Coverage, freshness: Freshness });
+    const output = OUTPUTS.get(d.envelopeSchema) ?? d.envelopeSchema({ data: Data, coverage: Coverage, freshness: Freshness });
+    OUTPUTS.set(d.envelopeSchema, output);
     server.registerTool("kev_recent", {
         title: "Recent CISA KEV additions",
         description: KEV_RECENT_DESCRIPTION,
@@ -221,8 +239,9 @@ export function registerKevRecent(server, d) {
             vendor: z.string().optional().describe("CISA vendorProject, an exact case-insensitive match, e.g. 'Microsoft'"),
             limit: z.number().int().min(1).max(KEV_RECENT_MAX_LIMIT).optional().describe("page size (default 50, max 200)"),
             cursor: z.string().optional().describe("next_cursor from the previous page"),
+            full: FULL_ARG,
         }),
         outputSchema: output,
         annotations: d.annotations,
-    }, async (a) => d.checked(TOOL, output, await kevRecent(d, a)));
+    }, async (a) => d.checked(TOOL, output, await answering(a.full, kevData(a), () => kevRecent(d, a))));
 }

package/dist/tools/match_batch.js

@@ -256,9 +256,17 @@ export async function sendBatches(deps, tool, purls) {
 // sent are always the input's distinct purls from position sent + 1 on
 // (purls.slice(answers.length * MAX_COMPONENTS)), which it can rebuild from its own input, given
 // the order they are counted in (`readOrder`), which the sentence says whenever it gives the
-// position, not only when the text cuts the list. `retry` is the tool and argument to send them
-// to ("check_sbom again with purls set to").
-export function sendingSentences(g, distinct, readOrder, retry) {
+// position, not only when the text cuts the list. #3013: the structured result's cut empties
+// data.not_sent_purls before any row leaves (it is rebuilt from the position). #3132's review:
+// round 1 then gave it back the first entries the room the rows left held (3 of the rate-limited
+// case's 800), a list a client would retry as though it were the whole; the cut now keeps it whole
+// or not at all (check_sbom.ts sbomData), and the sentence gives the positions as coverage holds
+// them. `retry` is the tool and argument to send them to ("check_sbom again with purls set to").
+// #3132's second review: those positions index the purls this tool read, which a check_sbom
+// client rebuilds from its own purl list (or SBOM), but a scan_manifest client cannot without
+// reading the files as this tool does; with `positions` false (scan_manifest), the sentence sends
+// it to the same call with full: true, which always returns the list, instead.
+export function sendingSentences(g, distinct, readOrder, retry, positions = true) {
     const out = [];
     if (g.batches > 1) {
         out.push(`The ${distinct} distinct purls make ${g.batches} batches of at most ${MAX_COMPONENTS}, sent one after another; the API answered ${g.batches_sent} of them, and data.summary sums those answers.`);
@@ -270,7 +278,7 @@ export function sendingSentences(g, distinct, readOrder, retry) {
     if (notSent > 0) {
         const one = notSent === 1;
         const where = one ? `it is the input's distinct purl at position ${g.sent + 1}` : `they are the input's distinct purls from position ${g.sent + 1} on`;
-        out.push(`${plural(notSent, "purl was", "purls were")} NOT sent (not_sent_reason ${g.not_sent_reason}: ${g.not_sent_detail}), so ${one ? "it is" : "they are"} not checked and not clean; ${where}, ${readOrder}, and data.not_sent_purls lists ${one ? "it" : "them"}: call ${retry} ${one ? "it" : "them"}${g.not_sent_reason === "request_failed" ? "" : " after a minute"}.`);
+        out.push(`${plural(notSent, "purl was", "purls were")} NOT sent (not_sent_reason ${g.not_sent_reason}: ${g.not_sent_detail}), so ${one ? "it is" : "they are"} not checked and not clean; ${where}, ${readOrder}, and data.not_sent_purls lists ${one ? "it" : "them"} (past the structured result's budget it is left out whole by default, never cut short${positions ? `, and ${one ? "that position is" : "those positions are"} coverage.sent + 1 to coverage.distinct_purls; with full: true it is always there` : ": the same call with full: true always returns it"}): call ${retry} ${one ? "it" : "them"}${g.not_sent_reason === "request_failed" ? "" : " after a minute"}.`);
     }
     return out;
 }
@@ -312,7 +320,7 @@ export function verdictSentences(d, g) {
             out.push(`Affected: ${named.join("; ")}${hits.length > NOTE_AFFECTED_MAX ? `; and ${hits.length - NOTE_AFFECTED_MAX} more affected components in data.results` : ""}.`);
             // Said only when the answer carries fixed_in (an API before #2834 sends none).
             if (hits.some((r) => (Array.isArray(field(r, "matches")) ? field(r, "matches") : []).some((m) => isObj(m) && "fixed_in" in m))) {
-                out.push("Each match's fixed_in is the fixed bound of the advisory interval that holds the component's version; null, with fixed_in_reason, where the advisory records no fix for that version.");
+                out.push("Each match's fixed_in is the first version above the component's that no affected interval of the advisory holds; null, with fixed_in_reason, where the advisory records no fix for that version.");
             }
         }
         // #2836: rows matched by the source package their purl's upstream qualifier names.
@@ -364,10 +372,11 @@ export const Row = z.looseObject({
         cve_id: opt(z.string()),
         kev_listed: opt(z.boolean()).describe("Whether the CVE is in CISA's Known Exploited Vulnerabilities catalog, as EchelonGraph's record holds it."),
         epss_score: opt(z.number()).describe("The CVE's EPSS score (FIRST), as EchelonGraph's record holds it; null when it has none."),
-        match_reason: opt(z.string()).describe("Why the advisory applies, with the advisory interval the version falls inside: \"[A, B)\" names the fixed version B, \"[A, B]\" the last affected version B. On an upstream row it ends by naming the source package and the purl name."),
+        match_reason: opt(z.string()).describe("Why the advisory applies, with the advisory interval the version falls inside: \"[A, B)\" names that interval's fixed bound B (another interval of the advisory can still hold B; fixed_in is the version past them all), \"[A, B]\" the last affected version B. On an upstream row it ends by naming the source package and the purl name."),
         interval: opt(z.looseObject({ introduced: opt(z.string()), fixed: opt(z.string()), last_affected: opt(z.string()) })).describe("The advisory interval that holds this component's version (fixed is exclusive, last_affected inclusive); absent when no interval holds it."),
-        fixed_in: opt(z.string()).describe("The fixed bound of the advisory interval that holds this component's 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."),
+        fixed_in: opt(z.string()).describe("The lowest version above this component's that no affected interval of the CVE's record for the package holds, always above it: the fixed bound of the interval that holds the component's 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."),
         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 the component's version: the overlapping intervals of the same record it moved past, which still hold that bound."),
     }))),
     count: opt(z.number()),
     advisories_considered: opt(z.number()),
@@ -376,6 +385,17 @@ export const Row = z.looseObject({
     undetermined: opt(z.array(z.looseObject({ cve_id: opt(z.string()) }))),
     capped: opt(z.boolean()),
     candidates_capped: opt(z.boolean()),
+    // #3132: set by this server's structured cut (check_sbom.ts SBOM_ROW_LEVELS), never by the API.
+    matches_truncated: z
+        .strictObject({
+        total: z.number().int().min(0),
+        returned: z.number().int().min(0),
+        kev_listed_cve_ids: z.array(z.string()).optional(),
+        ransomware_cve_ids: z.array(z.string()).optional(),
+        fixed_in_versions: z.array(z.string()).optional(),
+    })
+        .optional()
+        .describe("Present only on a row whose matches the structured result's cut (DATA CUT) shortened or left out: total, the row's matches in the answer; returned, the ones data keeps (its first, highest effective_score first); and, while they fit, 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). The same call with full: true returns every match."),
 });
 // The batch route's answer, as data carries it: its fields, merged over the batches.
 export const batchDataShape = {