echelongraph-mcp 2.6.3 → 2.6.6

package/dist/index.js

@@ -27,19 +27,23 @@
 // Structured results (#2311, #2313). Every result, success or failure, also carries
 // structuredContent: one envelope that says how the answer was measured — state (measured,
 // not_assessed, failed, invalid_input), measured_at, method, coverage, freshness and notes —
-// with, on a success, `data` equal to what content[0] carries, and on a failure an `error`.
-// Each tool advertises the envelope as its outputSchema.
+// with, on a success, `data`, the answer whole, and on a failure an `error`. content[0] carries
+// `data` as JSON up to 30,000 characters, and past them a cut of it that the note names (TEXT
+// CUT, #2783), so past them content[0] is not equal to `data` (#2802). Each tool advertises the
+// envelope as its outputSchema.
 //
 // The envelope in the text (#2440, #2467). Many clients pass only `content` to the model, so the
 // last text block of every result is structuredContent serialized as JSON, less what an earlier
-// text block already carries verbatim: `data` (content[0] on a success), the note's sentences
-// (the block just before, which structuredContent's notes end with), and method where that note
-// quotes it. The rest — state, measured_at, coverage, freshness, the envelope's own notes and,
-// on a failure, error — is copied key for key, so the text blocks together are the whole of
-// structuredContent and cannot disagree with it. The MCP spec (2025-06-18, Tools, Structured
-// Content) asks a tool that returns structured content to return it serialized in a text block
-// too; the JSON block stays first and the note second, as in 1.x, so a client that parses
-// content[0] is unaffected.
+// text block already carries: `data` (content[0] on a success, whole or cut as above), the note's
+// sentences (the block just before, which structuredContent's notes end with), and method where
+// that note quotes it. The rest — state, measured_at, coverage, freshness, the envelope's own notes
+// and, on a failure, error — is copied key for key, so the text blocks together are the whole of
+// structuredContent, but for what a TEXT CUT leaves out of `data`, and cannot disagree with it. The
+// MCP spec (2025-06-18, Tools, Structured Content) asks a tool that returns structured content to
+// return it serialized in a text block too; the JSON block stays first and the note second, as in
+// 1.x, so a client that parses content[0] still parses the answer's JSON, which past 30,000
+// characters is a cut of it (fields, entries and string ends left out, no value changed) and no
+// longer the whole answer: structuredContent.data is (#2802).
 //
 // Protocol eras (#2311). serveStdio answers both: a 2026-07-28 client's server/discover and
 // per-request `_meta` envelope, and a 2025-era client's `initialize` handshake. The first
@@ -54,11 +58,11 @@ import { registerCheckAffected } from "./tools/check_affected.js";
 import { registerCheckSbom } from "./tools/check_sbom.js";
 import { registerCveIntel } from "./tools/cve_intel.js";
 import { registerGetCwe } from "./tools/get_cwe.js";
-import { isHttpEntrypoint, upstreamHeaders, upstreamUserAgent } from "./runtime.js";
+import { holdRequest, isHttpEntrypoint, requestSignal, upstreamHeaders, upstreamUserAgent } from "./runtime.js";
 import { registerVendorAdvisoryTools } from "./tools/vendor_advisories.js";
 import { registerPrompts } from "./prompts.js";
 import { registerResources } from "./resources.js";
-import { dataText, TEXT_BUDGET_DESCRIPTION } from "./textBudget.js";
+import { dataText, GET_CVE_WHOLE, TEXT_BUDGET_DESCRIPTION } from "./textBudget.js";
 // The package actually running, read from the package.json that ships beside dist/. The MCP
 // handshake (serverInfo) and the User-Agent both carry its name and version, so the API's
 // access log can count adoption per version without a code change per release.
@@ -175,15 +179,29 @@ function retryAfterSeconds(v) {
 // the URL); the User-Agent and Accept are this server's and are not overridden. init.timeoutMs
 // can only shorten the request's timeout below TIMEOUT_MS, never lengthen it: check_sbom passes
 // what is left of its call's budget, so a slow batch cannot carry the call past it (#2756).
+// The request is cancelled when init.signal aborts (check_sbom's call was cancelled) or, on the
+// hosted endpoint, when the client it answers has gone (runtime.ts requestSignal, #2775): a
+// network failure saying so, which nobody reads, since the SDK sends nothing for a cancelled call.
 export async function api(path, init) {
     const limitMs = init?.timeoutMs === undefined ? TIMEOUT_MS : Math.max(0, Math.min(TIMEOUT_MS, Math.floor(init.timeoutMs)));
+    const m = init?.method && init.method.toUpperCase() !== "GET" ? { method: init.method.toUpperCase() } : {};
+    const callers = [init?.signal, requestSignal()].filter((s) => s !== undefined);
+    const cancelledFailure = () => ({ ok: false, kind: "network", path, ...m, detail: "cancelled: the call was abandoned before the API answered" });
+    if (callers.some((s) => s.aborted))
+        return cancelledFailure();
     const ctrl = new AbortController();
     let timedOut = false;
+    let cancelled = false;
     const timer = setTimeout(() => {
         timedOut = true;
         ctrl.abort();
     }, limitMs);
-    const m = init?.method && init.method.toUpperCase() !== "GET" ? { method: init.method.toUpperCase() } : {};
+    const cancel = () => {
+        cancelled = true;
+        ctrl.abort();
+    };
+    for (const s of callers)
+        s.addEventListener("abort", cancel, { once: true });
     const own = limitMs === TIMEOUT_MS ? {} : { timeoutMs: limitMs };
     const timeout = () => ({ ok: false, kind: "timeout", path, ...m, ...own, detail: `no response within ${limitMs} ms` });
     try {
@@ -200,14 +218,14 @@ export async function api(path, init) {
             });
         }
         catch (e) {
-            return timedOut ? timeout() : { ok: false, kind: "network", path, ...m, detail: describeError(e) };
+            return timedOut ? timeout() : cancelled ? cancelledFailure() : { ok: false, kind: "network", path, ...m, detail: describeError(e) };
         }
         let body;
         try {
             body = await res.text();
         }
         catch (e) {
-            return timedOut ? timeout() : { ok: false, kind: "network", path, ...m, detail: `reading the body failed: ${describeError(e)}` };
+            return timedOut ? timeout() : cancelled ? cancelledFailure() : { ok: false, kind: "network", path, ...m, detail: `reading the body failed: ${describeError(e)}` };
         }
         if (!res.ok) {
             const retryAfter = retryAfterSeconds(res.headers.get("retry-after"));
@@ -228,6 +246,8 @@ export async function api(path, init) {
     }
     finally {
         clearTimeout(timer);
+        for (const s of callers)
+            s.removeEventListener("abort", cancel);
     }
 }
 const text = (t) => ({ type: "text", text: t });
@@ -273,13 +293,15 @@ const REJECTED_INPUT = "The API rejected the request as invalid input, so nothin
 // earlier text block already carries verbatim (#2467). 2.1.0 sent the whole envelope without
 // `data`, so every note went out twice, once as prose and once as the notes array, and
 // cve_exposure's method a third time.
-//   data    left out: content[0] carries it verbatim.
+//   data    left out: content[0] carries it, verbatim up to DATA_TEXT_BUDGET and past it cut,
+//           with the note saying what the cut leaves out (TEXT CUT, #2783).
 //   notes   only the envelope's own sentences (`own`), which no text block says; the rest of
 //           structuredContent's notes are the sentences of `said`, the text block just before
 //           this one (the note, or a failure's message). Left out when there are none.
 //   method  left out when `said` quotes it verbatim (cve_exposure's note, "Method: …").
 // Every other key is copied as is, in structuredContent's order, so the text blocks together are
-// the whole of structuredContent and cannot disagree with it.
+// the whole of structuredContent, but for what a TEXT CUT leaves out of data, which the note names,
+// and cannot disagree with it (#2802).
 const envelopeText = (structured, said, own) => {
     const envelope = {};
     for (const [k, v] of Object.entries(structured)) {
@@ -529,6 +551,55 @@ function summaryPollerNote(d) {
     const counters = quoted.length > 0 ? ` (${quoted.join(", ")})` : "";
     return ` poller is one API instance's NVD poller, counted in that instance's memory since it last started and zeroed on every restart: report its counters${counters} as that instance's, never as the feed's size, intake or reliability, and poller.last_poll_at as that instance's last poll, never as the feed's freshness.`;
 }
+// ── poller's JSON types, never a reason to withhold summary (#2771) ──
+//
+// 2.6.2 typed poller's eight fields in the outputSchema (CVE_SUMMARY_OUTPUT), and every success
+// goes through checked(), so one counter core-backend sent in another JSON type failed the whole
+// call and withheld summary.total: cve/poller.go Stats returns a map[string]interface{}, so
+// emitting interval as a time.Duration (1200000000000) instead of interval.String() compiles.
+// The block is one instance's diagnostics, never the feed's, so it degrades on its own: a field of
+// another type is left out of data and named in the note, a poller that is neither a JSON object
+// nor null (an array, a string) is left out whole and named, and summary and the rest of the
+// answer are relayed as sent. What the schema allows is kept as sent: null for a field (opt), null
+// or an empty object for the block, and keys this version does not know. Installed 2.6.2 and
+// 2.6.3 copies still fail on such a change, so core-backend's cve/poller_stats_wire_test.go pins
+// Stats()'s eight keys to these JSON types.
+const SUMMARY_POLLER_KINDS = {
+    cves_ingested: "number",
+    cves_skipped: "number",
+    http_retries: "number",
+    interval: "string",
+    last_poll_at: "string",
+    last_poll_dur_ms: "number",
+    poll_count: "number",
+    poll_errors: "number",
+};
+const pollerField = (k, description) => opt(SUMMARY_POLLER_KINDS[k] === "number" ? z.number() : z.string()).describe(description);
+const jsonKind = (v) => v === null ? "null" : Array.isArray(v) ? "an array" : typeof v === "object" ? "an object" : typeof v === "number" ? "a number" : typeof v === "boolean" ? "a boolean" : typeof v === "string" ? "a string" : typeof v;
+function summaryPollerShaped(d) {
+    const poller = field(d, "poller");
+    if (poller === undefined || poller === null)
+        return { data: d, note: "" };
+    const relayed = " The rest of the answer, summary with it, is relayed as sent.";
+    if (!isPlainObject(poller)) {
+        const { poller: _dropped, ...rest } = d;
+        return { data: rest, note: ` poller was left out of the data above because the answer sent it as ${jsonKind(poller)}, where this tool reads an object.${relayed}` };
+    }
+    const unusable = Object.keys(SUMMARY_POLLER_KINDS).filter((k) => {
+        const v = poller[k];
+        if (v === undefined || v === null)
+            return false;
+        return SUMMARY_POLLER_KINDS[k] === "number" ? !isCount(v) : typeof v !== "string";
+    });
+    if (unusable.length === 0)
+        return { data: d, note: "" };
+    const kept = Object.fromEntries(Object.entries(poller).filter(([k]) => !unusable.includes(k)));
+    const named = unusable.map((k) => `poller.${k} (${jsonKind(poller[k])}, where this tool reads ${SUMMARY_POLLER_KINDS[k] === "number" ? "a number" : "a string"})`);
+    return {
+        data: { ...d, poller: kept },
+        note: ` Left out of the data above because the answer sent ${unusable.length === 1 ? "it" : "them"} in a JSON type other than the one this tool reads: ${listed(named)}.${relayed}`,
+    };
+}
 async function cveSummary() {
     const tool = "cve_summary";
     try {
@@ -536,7 +607,9 @@ async function cveSummary() {
         if (!r.ok)
             return failed(tool, r);
         const head = okHead(tool, r.status);
-        const updated = strAt(r.data, "summary", "last_updated");
+        // #2771: a poller field of another JSON type is left out, never a failure of the call.
+        const { data, note: pollerShape } = summaryPollerShaped(r.data);
+        const updated = strAt(data, "summary", "last_updated");
         const env = {
             state: "measured",
             measured_at: instantOrNull(updated),
@@ -550,18 +623,18 @@ async function cveSummary() {
                 NO_FEED_FRESHNESS,
             ],
         };
-        const total = numAt(r.data, "summary", "total");
-        // What summary.none (#2610), the NVD histogram and summary.rejected (#2641) count, and what
-        // the poller block is (#2647).
-        const labels = `${summaryNoneNote(r.data)}${summaryNVDNote(r.data)}${summaryRejectedNote(r.data)}${summaryPollerNote(r.data)}`;
+        const total = numAt(data, "summary", "total");
+        // What summary.none (#2610), the NVD histogram and summary.rejected (#2641) count, what the
+        // poller block is (#2647), and what of it was left out (#2771).
+        const labels = `${summaryNoneNote(data)}${summaryNVDNote(data)}${summaryRejectedNote(data)}${summaryPollerNote(data)}${pollerShape}`;
         if (total === undefined)
-            return succeeded(r.data, `${head}${labels}`, env);
+            return succeeded(data, `${head}${labels}`, env);
         if (total === 0) {
-            return succeeded(r.data, `${head} The feed reports 0 active CVEs — a measured empty result (we looked and found nothing), not a lookup failure.${labels}`, env);
+            return succeeded(data, `${head} The feed reports 0 active CVEs — a measured empty result (we looked and found nothing), not a lookup failure.${labels}`, env);
         }
         // A stamp that is not a real instant stays in the JSON and is not repeated as prose.
         const stamp = realInstant(updated) ? ` (last updated ${updated})` : "";
-        return succeeded(r.data, `${head} The feed holds ${total} active CVEs${stamp}.${labels}`, env);
+        return succeeded(data, `${head} The feed holds ${total} active CVEs${stamp}.${labels}`, env);
     }
     catch (e) {
         return crashed(tool, e);
@@ -572,7 +645,9 @@ async function cveSummary() {
 // 133,300 characters of text. Past DATA_TEXT_BUDGET each row in the first text block keeps the
 // fields the description promises and a few more a triage reads, the description cut to 200
 // characters; then, for a page of 50, the fields the description promises with the description cut
-// to 100. structuredContent.data keeps every field of every row; get_cve returns one record whole.
+// to 100. structuredContent.data keeps every field of every row; get_cve returns one record, whole in
+// its structuredContent.data and in its own first text block with every field (its lists cut past
+// the budget, #2802).
 const SEARCH_CVES_TEXT = {
     rows: "cves",
     levels: [
@@ -582,7 +657,7 @@ const SEARCH_CVES_TEXT = {
         },
         { keep: ["cve_id", "description", "severity", "cvss_v3_score", "echelongraph_score", "score_assessed", "score_unassessed_reason", "epss_score", "kev_listed", "published"], clip: 100 },
     ],
-    whole: "get_cve returns any one of these CVEs' records whole.",
+    whole: `${GET_CVE_WHOLE}.`,
     page: (shown, _rows, d) => `To read the rows left out in the text, call search_cves again with the same arguments and offset ${(numAt(d, "offset") ?? 0) + shown}; a page of ${shown} rows or fewer like these fits the text without leaving rows out.`,
 };
 async function searchCVEs(a) {
@@ -1492,8 +1567,9 @@ function readShadowAI(sa) {
 //
 // core-backend/internal/aiexposure (handler.go MCPPublicCounts, store.go): the AI-exposure
 // radar's MCP rows, one per hostname, each counted once by its latest verdict on record, with
-// EchelonGraph's own control servers left out and counted in own_controls_excluded. Counts,
-// timestamps and one constant (service "mcp"); no hostname, version or server name.
+// EchelonGraph's own control servers left out and counted in own_controls_excluded, and every
+// hostname whose owner opted out of scanning left out and counted in withheld_opted_out (#2822).
+// Counts, timestamps and one constant (service "mcp"); no hostname, version or server name.
 //   total                   protected + pending_readjudication + not_assessed
 //   protected               the /mcp endpoint answered 401/403 and its RFC 9728 protected-resource
 //                           metadata validated (prm.go); prm_via divides exactly these rows by
@@ -1506,6 +1582,12 @@ function readShadowAI(sa) {
 //                           (a challenge recorded before #2312), no_http_answer, not_identified_as_mcp
 //   era, transport          divide every counted row; a row written before #2314 recorded an era
 //                           is not_measured (era.go says what each value rests on)
+//   withheld_opted_out      hostnames a verified scan opt-out covered when the radar last reached
+//                           them (store.go opted_out_at, #2363): not re-checked while it stands, so
+//                           their last verdict is frozen, and in no other count (#2822). The unparameterised
+//                           answer withholds the same rows under the same key. An API older than
+//                           #2822 carries no such field and counted those rows; the note says so
+//                           rather than reading the absence as 0.
 //   window                  from/to: the oldest and newest last-check time over the counted rows
 //   enabled, last_run_at    exactly as the unparameterised answer computes them: the AI-exposure
 //                           radar's fleet-wide liveness and last completed check, over every AI
@@ -1561,7 +1643,7 @@ const MCP_PARTITIONS = {
 };
 const MCP_PARTITION_NAMES = Object.keys(MCP_PARTITIONS);
 const MCP_INSTANTS = ["last_run_at", "counted_at"];
-const MCP_KNOWN = new Set(["service", ...MCP_HEADLINE, ...MCP_PARTITION_NAMES, "own_controls_excluded", "window", "enabled", ...MCP_INSTANTS]);
+const MCP_KNOWN = new Set(["service", ...MCP_HEADLINE, ...MCP_PARTITION_NAMES, "own_controls_excluded", "withheld_opted_out", "window", "enabled", ...MCP_INSTANTS]);
 // What each challenge reason code says (prm.go prmReasonCodes), for the note.
 const MCP_CHALLENGE_MEANS = {
     resource_mismatch: "the document's resource is absent or not identical to the server's identifier",
@@ -1629,6 +1711,12 @@ function readMCPServers(src) {
         data.own_controls_excluded = src.own_controls_excluded;
     else
         unusable.push("own_controls_excluded");
+    // An API older than #2822 carries no withheld_opted_out, and counted those rows (the note says
+    // so); one that carries it in another shape has it left out and named.
+    if (isWhole(src.withheld_opted_out))
+        data.withheld_opted_out = src.withheld_opted_out;
+    else if (src.withheld_opted_out !== undefined)
+        unusable.push("withheld_opted_out");
     // window: from and to, both real instants, from not after to. With no row counted the API has
     // no window to give (null, or from and to null), and none is relayed.
     const w = src.window;
@@ -1677,6 +1765,12 @@ function readMCPServers(src) {
     if (data.own_controls_excluded !== undefined) {
         sentences.push(`mcp_servers.own_controls_excluded (${n("own_controls_excluded")}) counts EchelonGraph's own control servers, which are left out of every other mcp_servers number.`);
     }
+    if (data.withheld_opted_out !== undefined) {
+        sentences.push(`mcp_servers.withheld_opted_out (${n("withheld_opted_out")}) counts hostnames whose owner opted out of EchelonGraph's scanning: they are not checked again while the opt-out stands, so their last verdict cannot be re-checked, and they are left out of every other mcp_servers number.`);
+    }
+    else if (src.withheld_opted_out === undefined) {
+        sentences.push("The answer does not say how many hostnames whose owner opted out of scanning it withheld (mcp_servers.withheld_opted_out), so its counts may include such a hostname's last verdict, which is not re-checked while the opt-out stands.");
+    }
     if (data.window) {
         sentences.push(`mcp_servers.window says when the verdicts counted were last checked: the oldest at ${from} (mcp_servers.window.from) and the newest at ${to} (mcp_servers.window.to), so the counts are each hostname's latest verdict, not one sweep at one time.`);
     }
@@ -1706,7 +1800,7 @@ const EXPOSURE_RADAR_DESCRIPTION = `Aggregate totals from EchelonGraph's interne
     `exposed_databases: exposed_databases.distinct_hosts counts distinct ip:port services the check confirmed answering without authentication, and exposed_databases.engines the distinct engine types among them; exposed_databases.top_engines and exposed_databases.top_countries rank up to 15 engines and 10 countries by those services. exposed_databases.pii_likely and exposed_databases.pci_likely count services whose schema names (never record values) pass a high-confidence, precision-first gate for personal or payment-card data, so a service outside them is not shown to hold no such data. exposed_databases.window.from and exposed_databases.window.to are timestamps, not counts: when EchelonGraph's check last confirmed the oldest and the newest of the services counted, a span of checks made at different times; with a counted service that has no such time on record there is no window. ` +
     `leaked_credentials: leaked_credentials.total counts (repository, secret) pairs, not distinct secrets, so one secret in three repositories counts three times; leaked_credentials.distinct_secrets counts each secret once and leaked_credentials.distinct_repos counts repositories; leaked_credentials.top_providers and leaked_credentials.top_types rank up to 15 providers and secret types by those pairs. None is validated: each is a credential-shaped string that passed EchelonGraph's filters, at most structurally checked and never tested against its provider. leaked_credentials.window.from and leaked_credentials.window.to are timestamps, not counts: when EchelonGraph's detector last found the oldest and the newest of the pairs counted. Each of those three radars also carries generated_at, when the API computed its totals, and, when the API can tell, last_run_at. kev_exposure.last_run_at, exposed_databases.last_run_at and leaked_credentials.last_run_at are timestamps, not counts: each is when that radar last completed a check, a cycle whose reads succeeded, among them a Shodan search (for exposed_databases, or its LeakIX fallback) that answered at least one query, or for leaked_credentials a read of the public GitHub event stream. A cycle that read nothing does not move it, and it is not the time of every record a radar's numbers count, which cover everything still on record, not only what the last check found. A radar whose answer carries no last_run_at has none in the result, and the note says nothing about it. ` +
     `shadow_ai: the result is regrouped by what each number counts. shadow_ai.confirmed_exposed counts services EchelonGraph's probes found answering without an authentication gate (liveness active, or rechecking during a re-check): confirmed_exposed.total is the sum of confirmed_exposed.by_category, and confirmed_exposed.last_24h counts those first recorded in the last 24 h. Of the shadow_ai numbers, only confirmed_exposed counts exposed services. confirmed_exposed.window.from and confirmed_exposed.window.to are timestamps, not counts: when EchelonGraph's verifier ran the probe that last decided the oldest and the newest of those services, a span of probes made at different times. shadow_ai.observed counts every Certificate Transparency or Shodan observation on record, whatever its verification state: its numbers are observed, not exposed. They are observed.total; observed.by_category (the same observations by category); observed.last_24h (those first recorded in the last 24 h); observed.trend_30d (observations per UTC day over the last 30 days); and observed.top_products, observed.top_countries and observed.top_issuers (up to ten products, countries and issuers ranked by observations, where an issuer is the certificate's CA for a Certificate Transparency observation and the hosting operator Shodan reports for a Shodan one). shadow_ai.authentication counts observations by probe outcome: authentication.observed where a probe observed an authentication gate (a 401/403, a login page or an auth marker), and authentication.not_determined where the service answered but no probe could tell. Neither authentication count is part of confirmed_exposed, and observed.total minus confirmed_exposed.total is not a count of secured services. The shadow-AI poller block carries only running and last_run_at: last_run_at is when the radar's leader last completed a Certificate Transparency (crt.sh) cycle, and its running is true only when that was within ${SHADOW_AI_SILENT_AFTER} of the answer. ` +
-    `mcp_servers: counts and timestamps only, no hostname. mcp_servers.total counts hostnames the AI-exposure radar has checked for an MCP server, each once by its latest verdict on record, and not every one is an MCP server; EchelonGraph's own control servers are left out, and mcp_servers.own_controls_excluded counts them. mcp_servers.total is mcp_servers.protected plus mcp_servers.pending_readjudication plus mcp_servers.not_assessed. mcp_servers.protected counts hostnames whose /mcp endpoint asked for credentials and whose OAuth protected-resource metadata validated under RFC 9728; mcp_servers.prm_via divides them by where that document was found: mcp_servers.prm_via.header, mcp_servers.prm_via.wellknown_path and mcp_servers.prm_via.wellknown_root. mcp_servers.pending_readjudication counts verdicts of a rule since replaced, not yet re-checked. mcp_servers.not_assessed counts the rest, whose protection the radar could not assess (not assessed does not mean unprotected), and mcp_servers.not_assessed_by_reason puts each in one bucket. mcp_servers.not_assessed_by_reason.identified_no_challenge holds servers that identified themselves as MCP servers and did not ask for credentials at the handshake. That is normal in MCP: authorization is optional in the spec, and a server can enforce it at tools/call instead, which EchelonGraph never sends, so this bucket is not a finding of exposure. ${MCP_CHALLENGE_REASON_FIELDS} hold endpoints that asked for credentials but whose RFC 9728 metadata did not validate, by why, so none of them is shown to lack protection; mcp_servers.not_assessed_by_reason.challenge_unadjudicated holds endpoints that asked for credentials before that check existed, not yet re-checked. mcp_servers.not_assessed_by_reason.no_http_answer holds hostnames that gave no HTTP answer, and mcp_servers.not_assessed_by_reason.not_identified_as_mcp hostnames whose HTTP answer identified no MCP server. mcp_servers.era divides every counted hostname by protocol era: mcp_servers.era.legacy; mcp_servers.era.dual, a lower bound; mcp_servers.era.modern, not proven modern-only; mcp_servers.era.unknown; and mcp_servers.era.not_measured, recorded before the era probe and not re-checked since. mcp_servers.transport divides them by transport: mcp_servers.transport.streamable_http, mcp_servers.transport.legacy_sse, mcp_servers.transport.unknown and mcp_servers.transport.not_measured. mcp_servers.window.from and mcp_servers.window.to are when the oldest and the newest of the verdicts counted were last checked. mcp_servers.last_run_at is a timestamp, not a count: when the AI-exposure radar, which checks other AI services too, last completed a check; mcp_servers.enabled is whether one completed within ${MCP_ENABLED_WITHIN} of the answer, and mcp_servers.counted_at is when the API read the counts. A partition whose buckets do not add up to the count it divides is left out and named; an answer that does not say it is the MCP-server counts, or whose mcp_servers.total, mcp_servers.protected, mcp_servers.pending_readjudication and mcp_servers.not_assessed are missing or contradict each other, is a failure. ${SHODAN_OWNERSHIP}`;
+    `mcp_servers: counts and timestamps only, no hostname. mcp_servers.total counts hostnames the AI-exposure radar has checked for an MCP server, each once by its latest verdict on record, and not every one is an MCP server; EchelonGraph's own control servers are left out, and mcp_servers.own_controls_excluded counts them; hostnames whose owner opted out of scanning are not checked again while the opt-out stands, so their last verdict is left out too, and mcp_servers.withheld_opted_out counts them. mcp_servers.total is mcp_servers.protected plus mcp_servers.pending_readjudication plus mcp_servers.not_assessed. mcp_servers.protected counts hostnames whose /mcp endpoint asked for credentials and whose OAuth protected-resource metadata validated under RFC 9728; mcp_servers.prm_via divides them by where that document was found: mcp_servers.prm_via.header, mcp_servers.prm_via.wellknown_path and mcp_servers.prm_via.wellknown_root. mcp_servers.pending_readjudication counts verdicts of a rule since replaced, not yet re-checked. mcp_servers.not_assessed counts the rest, whose protection the radar could not assess (not assessed does not mean unprotected), and mcp_servers.not_assessed_by_reason puts each in one bucket. mcp_servers.not_assessed_by_reason.identified_no_challenge holds servers that identified themselves as MCP servers and did not ask for credentials at the handshake. That is normal in MCP: authorization is optional in the spec, and a server can enforce it at tools/call instead, which EchelonGraph never sends, so this bucket is not a finding of exposure. ${MCP_CHALLENGE_REASON_FIELDS} hold endpoints that asked for credentials but whose RFC 9728 metadata did not validate, by why, so none of them is shown to lack protection; mcp_servers.not_assessed_by_reason.challenge_unadjudicated holds endpoints that asked for credentials before that check existed, not yet re-checked. mcp_servers.not_assessed_by_reason.no_http_answer holds hostnames that gave no HTTP answer, and mcp_servers.not_assessed_by_reason.not_identified_as_mcp hostnames whose HTTP answer identified no MCP server. mcp_servers.era divides every counted hostname by protocol era: mcp_servers.era.legacy; mcp_servers.era.dual, a lower bound; mcp_servers.era.modern, not proven modern-only; mcp_servers.era.unknown; and mcp_servers.era.not_measured, recorded before the era probe and not re-checked since. mcp_servers.transport divides them by transport: mcp_servers.transport.streamable_http, mcp_servers.transport.legacy_sse, mcp_servers.transport.unknown and mcp_servers.transport.not_measured. mcp_servers.window.from and mcp_servers.window.to are when the oldest and the newest of the verdicts counted were last checked. mcp_servers.last_run_at is a timestamp, not a count: when the AI-exposure radar, which checks other AI services too, last completed a check; mcp_servers.enabled is whether one completed within ${MCP_ENABLED_WITHIN} of the answer, and mcp_servers.counted_at is when the API read the counts. A partition whose buckets do not add up to the count it divides is left out and named; an answer that does not say it is the MCP-server counts, or whose mcp_servers.total, mcp_servers.protected, mcp_servers.pending_readjudication and mcp_servers.not_assessed are missing or contradict each other, is a failure. ${SHODAN_OWNERSHIP}`;
 // exposure_radar's envelope. Every radar answered, but no stats answer says when the services
 // or records it counts were observed: each count covers everything that radar still holds on
 // record, and the answer carries only generated_at (when the API computed the totals) and
@@ -1882,8 +1976,9 @@ const CVERecord = z.looseObject({
 });
 // #2647: what cve_summary says the poller block is (summaryPollerNote). Like the #2641 strings
 // beside SUMMARY_NONE_DESCRIPTION, it uses none of #2610's six words ("any", "not", "rating",
-// "scored", "source", "yet"). Declared here, before the outputSchema that describes poller with it.
-const SUMMARY_POLLER_DESCRIPTION = "poller holds the in-memory counters of the NVD poller of the one API instance that answered (cves_ingested, cves_skipped, http_retries, poll_count, poll_errors, last_poll_at, last_poll_dur_ms, interval), counted since that instance last started and zeroed on every restart: they describe that instance, never the feed's size, intake, reliability or freshness. Whenever the answer carries poller the note says so.";
+// "scored", "source", "yet"), #2771's sentence on a field of another JSON type among them. Declared
+// here, before the outputSchema that describes poller with it.
+const SUMMARY_POLLER_DESCRIPTION = "poller holds the in-memory counters of the NVD poller of the one API instance that answered (cves_ingested, cves_skipped, http_retries, poll_count, poll_errors, last_poll_at, last_poll_dur_ms, interval), counted since that instance last started and zeroed on every restart: they describe that instance, never the feed's size, intake, reliability or freshness. Whenever the answer carries poller the note says so. A poller field the answer sends in a JSON type other than the one described here is left out of data and named in the note, and a poller that is neither a JSON object nor null is left out whole: summary is relayed either way.";
 // One of the NVD histogram's four labelled buckets (#2641).
 const nvdBand = (label) => opt(z.number()).describe(`Of the active CVEs total counts, those whose NVD CVSS severity label is ${label}: NVD's label, as provenance, never EchelonGraph's severity band.`);
 const CVE_SUMMARY_OUTPUT = envelopeSchema({
@@ -1910,16 +2005,18 @@ const CVE_SUMMARY_OUTPUT = envelopeSchema({
         })
             .optional(),
         // #2647: one instance's counters, never the feed's (see summaryPollerNote).
+        // #2771: each field's JSON type is SUMMARY_POLLER_KINDS', which summaryPollerShaped enforces
+        // before this check, so a field of another type is left out, never a failed call.
         poller: z
             .looseObject({
-            cves_ingested: opt(z.number()).describe("CVE records this instance's NVD poller wrote since the instance last started: never the feed's size or intake."),
-            cves_skipped: opt(z.number()).describe("CVE records this instance's NVD poller skipped since the instance last started."),
-            http_retries: opt(z.number()).describe("HTTP retries this instance's NVD poller made since the instance last started."),
-            interval: opt(z.string()).describe("How often this instance's NVD poller polls."),
-            last_poll_at: opt(z.string()).describe("When this instance's NVD poller last polled: never the feed's freshness."),
-            last_poll_dur_ms: opt(z.number()).describe("How long that poll took, in milliseconds."),
-            poll_count: opt(z.number()).describe("Polls this instance's NVD poller made since the instance last started."),
-            poll_errors: opt(z.number()).describe("Polls of this instance's NVD poller that failed since the instance last started: never the feed's reliability."),
+            cves_ingested: pollerField("cves_ingested", "CVE records this instance's NVD poller wrote since the instance last started: never the feed's size or intake."),
+            cves_skipped: pollerField("cves_skipped", "CVE records this instance's NVD poller skipped since the instance last started."),
+            http_retries: pollerField("http_retries", "HTTP retries this instance's NVD poller made since the instance last started."),
+            interval: pollerField("interval", "How often this instance's NVD poller polls."),
+            last_poll_at: pollerField("last_poll_at", "When this instance's NVD poller last polled: never the feed's freshness."),
+            last_poll_dur_ms: pollerField("last_poll_dur_ms", "How long that poll took, in milliseconds."),
+            poll_count: pollerField("poll_count", "Polls this instance's NVD poller made since the instance last started."),
+            poll_errors: pollerField("poll_errors", "Polls of this instance's NVD poller that failed since the instance last started: never the feed's reliability."),
         })
             .nullable()
             .optional()
@@ -2028,6 +2125,7 @@ const MCPServersData = z.strictObject({
     ...Object.fromEntries(MCP_HEADLINE.map((k) => [k, Whole])),
     ...Object.fromEntries(MCP_PARTITION_NAMES.map((k) => [k, z.strictObject(Object.fromEntries(MCP_PARTITIONS[k].buckets.map((b) => [b, Whole]))).optional()])),
     own_controls_excluded: Whole.optional(),
+    withheld_opted_out: Whole.optional(),
     window: z.strictObject({ from: Instant, to: Instant }).optional(),
     enabled: z.boolean().optional(),
     ...Object.fromEntries(MCP_INSTANTS.map((k) => [k, Instant.optional()])),
@@ -2092,6 +2190,10 @@ export const ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempot
 const CVE_ID_ARG = z.string().describe("a CVE ID, e.g. CVE-2023-44487");
 // What each description says about its structured result, naming only fields its schema holds.
 const FEED_ENVELOPE = "Its structured result carries state (measured), measured_at, method, coverage, freshness (null: the feed serves no poll-completion time) and notes, with data equal to the API's JSON; the result's last text block repeats it without data (the first text block) and without the note's sentences (the text block before it), with which notes ends.";
+// #2771: cve_summary's own, since its data is the API's JSON less each poller field (or the whole
+// poller) summaryPollerShaped leaves out. Like SUMMARY_POLLER_DESCRIPTION it uses none of #2610's
+// six words ("any", "not", "rating", "scored", "source", "yet").
+const CVE_SUMMARY_ENVELOPE = "Its structured result carries state (measured), measured_at, method, coverage, freshness (null: the feed serves no poll-completion time) and notes, with data equal to the API's JSON less each poller field (or the whole poller) the note names as left out; the result's last text block repeats it without data (the first text block) and without the note's sentences (the text block before it), with which notes ends.";
 // #2610: what cve_summary says summary.none is (summaryNoneNote), one constant string for the same
 // reason as SCORE_ASSESSED_DESCRIPTION below.
 const SUMMARY_NONE_DESCRIPTION = "summary.none is not a severity rating of None: it counts the active CVEs with no severity band from any source, that is, CVEs not yet scored, and the answer may carry the same count again as summary.unscored. Whenever summary.none is above zero the note says so: report those CVEs as not yet scored, not as CVEs rated None.";
@@ -2114,7 +2216,7 @@ export function createServer() {
     const server = new McpServer({ name: NAME, version: VERSION }, { instructions: INSTRUCTIONS, capabilities: { tools: { listChanged: false }, prompts: { listChanged: false }, resources: { listChanged: false } } });
     server.registerTool("cve_summary", {
         title: "CVE feed summary",
-        description: `Summary of EchelonGraph's CVE Pulse feed: summary.total active CVEs, their counts by severity band (summary.critical, summary.high, summary.medium, summary.low), the count with no band (summary.none), and summary.last_updated, the newest modification time among those records. ${SUMMARY_NONE_DESCRIPTION} ${SUMMARY_NVD_DESCRIPTION} ${SUMMARY_REJECTED_DESCRIPTION} ${SUMMARY_POLLER_DESCRIPTION} The feed is polled from its sources on a schedule, so this is the state as of that update. ${FEED_ENVELOPE} ${TEXT_BUDGET_DESCRIPTION}`,
+        description: `Summary of EchelonGraph's CVE Pulse feed: summary.total active CVEs, their counts by severity band (summary.critical, summary.high, summary.medium, summary.low), the count with no band (summary.none), and summary.last_updated, the newest modification time among those records. ${SUMMARY_NONE_DESCRIPTION} ${SUMMARY_NVD_DESCRIPTION} ${SUMMARY_REJECTED_DESCRIPTION} ${SUMMARY_POLLER_DESCRIPTION} The feed is polled from its sources on a schedule, so this is the state as of that update. ${CVE_SUMMARY_ENVELOPE} ${TEXT_BUDGET_DESCRIPTION}`,
         outputSchema: CVE_SUMMARY_OUTPUT,
         annotations: ANNOTATIONS,
     }, async () => checked("cve_summary", CVE_SUMMARY_OUTPUT, await cveSummary()));
@@ -2135,7 +2237,7 @@ export function createServer() {
     }, async (a) => checked("search_cves", SEARCH_CVES_OUTPUT, await searchCVEs(a)));
     server.registerTool("get_cve", {
         title: "CVE detail",
-        description: `Full record for one CVE: description, severity, cvss_v3_score, cvss_v4_score and cvss_v4_severity (when the record has a CVSS v4 score), echelongraph_score and echelongraph_severity with score_confidence (EchelonGraph's multi-source score) and score_assessed (whether EchelonGraph has scored it), epss_score and epss_percentile, CISA-KEV status (kev_listed, kev_added_date, and kev_ransomware for known ransomware-campaign use), ghsa_id (GitHub GHSA), references, cpe_match (the CPE criteria as one flat list) and cpe_configurations (NVD's configurations as NVD sent them, with each AND/OR operator, negate, versionStartExcluding and matchCriteriaId; absent where EchelonGraph has stored none, which is not a finding that no product is affected), published, modified and updated_at; each field only where the record has it. Pass a CVE ID like CVE-2023-44487. ${SCORE_ASSESSED_DESCRIPTION} ${FEED_ENVELOPE} ${TEXT_BUDGET_DESCRIPTION} Cut, each list in the record keeps its first entries, and the note names each list cut with its full length.`,
+        description: `One CVE's record: description, severity, cvss_v3_score, cvss_v4_score and cvss_v4_severity (when the record has a CVSS v4 score), echelongraph_score and echelongraph_severity with score_confidence (EchelonGraph's multi-source score) and score_assessed (whether EchelonGraph has scored it), epss_score and epss_percentile, CISA-KEV status (kev_listed, kev_added_date, and kev_ransomware for known ransomware-campaign use), ghsa_id (GitHub GHSA), references, cpe_match (the CPE criteria as one flat list) and cpe_configurations (NVD's configurations as NVD sent them, with each AND/OR operator, negate, versionStartExcluding and matchCriteriaId; absent where EchelonGraph has stored none, which is not a finding that no product is affected), published, modified and updated_at; each field only where the record has it. Pass a CVE ID like CVE-2023-44487. ${SCORE_ASSESSED_DESCRIPTION} ${FEED_ENVELOPE} ${TEXT_BUDGET_DESCRIPTION} Cut, each list in the record keeps its first entries, and the note names each list cut with its full length.`,
         inputSchema: z.object({ cve_id: CVE_ID_ARG }),
         outputSchema: GET_CVE_OUTPUT,
         annotations: ANNOTATIONS,
@@ -2157,8 +2259,10 @@ export function createServer() {
     registerEPSSHistory(server, TOOL_KIT);
     // #2716: its logic, schemas and description live in tools/check_affected.ts.
     registerCheckAffected(server, { api, succeeded, failed, badInput, crashed, checked, okHead, envelopeSchema, annotations: ANNOTATIONS });
-    // #2721: tools/check_sbom.ts, on this file's api(), envelope and failure contract.
-    registerCheckSbom(server, { api, failed, describeFailure, badInput, crashed, checked, succeeded, okHead, envelopeSchema, annotations: ANNOTATIONS });
+    // #2721: tools/check_sbom.ts, on this file's api(), envelope and failure contract. holdRequest
+    // (#2775): on the hosted endpoint, a call keeps its request's admission and large-body slot
+    // until it has stopped, not only until its answer, or its client, has gone.
+    registerCheckSbom(server, { api, failed, describeFailure, badInput, crashed, checked, succeeded, okHead, envelopeSchema, annotations: ANNOTATIONS, hold: holdRequest });
     registerCveIntel(server);
     registerGetCwe(server);
     // #2719: vendor_advisories_for_cve, get_vendor_advisory, search_vendor_advisories.
@@ -2166,7 +2270,7 @@ export function createServer() {
     // #2722: prompts and resources, in prompts.ts and resources.ts. Both lists are fixed per
     // connection, so listChanged is false above.
     registerPrompts(server, { cveId: CVE_ID });
-    registerResources(server, { api, cveId: CVE_ID, shownBase: SHOWN_BASE, getCve: async (id) => checked("get_cve", GET_CVE_OUTPUT, await getCVE(id)) });
+    registerResources(server, { api, cveId: CVE_ID, shownBase: SHOWN_BASE, sentences, getCve: async (id) => checked("get_cve", GET_CVE_OUTPUT, await getCVE(id)) });
     return server;
 }
 // The package identity and API settings, for the hosted HTTP entrypoint's health answer and

package/dist/prompts.js

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