echelongraph-mcp 2.7.2 → 3.0.0

package/dist/textBudget.js

@@ -1,9 +1,13 @@
-// The text budget (#2783): what a success's first text block may cost, and how an answer larger
-// than that is cut. index.ts's `succeeded` builds every success's first text block with dataText;
-// a tool that returns a list of rows names it with a TextCut. structuredContent.data is never cut.
-// A module of its own, so a tool module can import its types and TEXT_BUDGET_DESCRIPTION without
-// importing index.ts, which starts the stdio server when loaded.
-//
+// The text budget (#2783), and the structured result's (#3013): what a success may cost in each
+// channel a client hands a model, and how an answer larger than that is cut. index.ts's
+// `succeeded` builds every success's first text block with dataText (a tool that returns a list of
+// rows names it with a TextCut), and its structured result with cutData (each tool names its lists
+// in the order they are cut with a DataCut, and answering() hands the call's `full` and DataCut to
+// `succeeded`). A module of its own, so a tool module can import its types,
+// TEXT_BUDGET_DESCRIPTION and FULL_ARG without importing index.ts, which starts the stdio server
+// when loaded.
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as z from "zod";
 // What a success costs in the channel a model reads is mostly its first text block, and through
 // 2.6.2 that block was the API's JSON pretty-printed, whatever its size. Measured on production
 // through https://mcp.echelongraph.io/mcp (2.6.2, 2026-10-04): search_cves {search: "openssl"} at
@@ -18,8 +22,8 @@
 // serialized in a text block too, as a SHOULD, for backwards compatibility, and SEP-1624 proposes
 // content as the model-facing, token-efficient form and structuredContent as the machine-facing one.
 //
-// So structuredContent.data is always the API's JSON whole, and the first text block is that JSON
-// when it fits DATA_TEXT_BUDGET, half the ceiling, and cut when it does not:
+// So the first text block is the API's JSON when it fits DATA_TEXT_BUDGET, half the ceiling, and
+// cut when it does not (structuredContent.data, below, is cut on its own terms, never from this):
 //   1. pretty-printed, as since 1.x, when that fits;
 //   2. else the same JSON with each element of a list on a line of its own, which parses to the
 //      same value, when that fits;
@@ -33,19 +37,67 @@
 //      level keeps, and before any row leaves the text;
 //   4. else every list keeps its first n entries, n halving, and then strings are cut too.
 // Whenever the text is not the JSON whole, the note ends with one sentence, starting TEXT CUT,
-// that says what the first text block leaves out, that structuredContent.data carries all of it,
+// that says what the first text block leaves out, where structuredContent.data carries all of it,
 // and how to read the rest in the text: the tool that returns one row, and what of it, and the page
 // size or offset at which a page fits. The cut is deterministic: the same answer is cut the same way.
+//
+// The structured result, per client (#3013). Through 2.7.x structuredContent.data was the API's
+// JSON whole, on the reading above that structuredContent is the machine-facing form. It is not, in
+// the client the README gives first-class install steps: Claude Code hands the model
+// structuredContent, not the text blocks (reproduced 2026-10-11 over raw JSON-RPC: get_cve
+// CVE-2021-44228 was 65,540 characters of structuredContent beside a first text block of 23,759,
+// and Claude Code refused it, "exceeds maximum allowed tokens", against its default
+// MAX_MCP_OUTPUT_TOKENS of 25,000, and saved it to a file, so the model got a path, not an answer).
+// The spec (MCP 2025-06-18, Tools, Structured Content) does not say which of the two a client gives
+// the model. So the text cut above reached every client but that one. Since 3.0.0 the structured
+// result is held to the same budget, STRUCTURED_BUDGET: the whole of it, envelope and notes with
+// data, as compact JSON, since that is what such a client sizes. Past it, data is cut (cutData):
+//   1. the lists the tool's DataCut names, step by step in its order. Where a step names thinning
+//      levels (a list whose single entries are large: check_sbom's and scan_manifest's results,
+//      check_affected's matches, cve_remediation's vendor_remediations, search_cves' and the
+//      vendor-advisory tools' rows), every entry is first cut to the fields each level keeps, level
+//      by level, all entries kept, so that no row leaves while thinning its detail would do; then
+//      each step keeps the most entries that fit, every list in the step at most the same number,
+//      its first ones, or for a list named with leaveOutFirst (check_sbom's results) those entries
+//      the tool names leave first (the clean rows, counted in data.summary), then the last of the
+//      rest, or for a step of series named keepNewest (exposure_radar's daily and weekly counts,
+//      which the API sends oldest first) its last ones, the newest, the oldest leaving first; a
+//      step that cannot fit even empty is emptied, and the next one is cut;
+//   2. then every other list at the top level of data, the same way. A list inside an object of
+//      data (get_cve's remediation summary, with fix_status, #2841) is cut only where a DataCut
+//      names it, and none names get_cve's. Once a step fits, the room it leaves goes back to the
+//      steps emptied before it, the last first, each the same way (scan_manifest's not_checked,
+//      emptied while its rows were whole, keeps its entries once the thinned rows fit);
+//   3. no string is shortened and no value changes: a thinned entry keeps some of its fields as
+//      they are (every field a thinning level drops is optional in the outputSchema, so data still
+//      validates against it), and no field outside the lists cut changes; the envelope says
+//      data_truncated true, truncated gives each list cut by its path in data with its total, the
+//      number returned and, where its entries are thinned, thinned true, and the note ends with
+//      sentences starting DATA CUT that say what was cut and to which fields, how to read the rest
+//      (the offset or page size, where the tool pages: a page size the note says fits data whole
+//      is counted on the entries whole, never on the thinned ones, #3013's review) and that the
+//      same call with full: true returns data whole.
+// The first text block is cut from the whole answer as before, not from the cut data: what it
+// holds is unchanged for the clients that read it. full: true is for programs, which read data
+// whole whatever its size; a client that sizes structured results, Claude Code among them, may
+// still refuse such an answer past its own cap (MAX_MCP_OUTPUT_TOKENS raises Claude Code's).
+// Rejected (#3013's decision of 2026-10-11): saying only that Claude Code gets files; cutting only
+// for a client whose clientInfo.name is Claude Code (the same call would answer differently by
+// client, and the next client to pass structuredContent on would get the 65,540 again); and dropping
+// structuredContent (it loses the outputSchema check the spec recommends and the suite relies on).
 export const DATA_TEXT_BUDGET = 30_000;
 // What a note may say of reading one CVE's record through get_cve (#2802): get_cve's own first text
-// block is cut too past the budget (each list to its first entries, every other field kept), so
-// only its structuredContent.data is the record whole. A row tool's `whole` sentence starts with it.
-export const GET_CVE_WHOLE = "get_cve returns any one of these CVEs' records, whole in its structuredContent.data, and in its first text block with every field (past 30,000 characters, each list cut to its first entries)";
+// block is cut too past the budget (each list to its first entries, every other field kept), and
+// since #3013 so is its structured result's data, unless the call says full: true. A row tool's
+// `whole` sentence starts with it.
+export const GET_CVE_WHOLE = "get_cve returns any one of these CVEs' records, whole in its structuredContent.data with full: true, and in its first text block with every field (past 30,000 characters, each list cut to its first entries)";
 // What every tool description says about it, one constant string (marketing-site
 // lib/mcpToolClaims.test.ts folds only constant strings); the suite holds its number to
 // DATA_TEXT_BUDGET's. It uses none of the words that check reviews as the page's own prose (how,
-// when, does, have, on and the rest of its PROSE list), so no reviewed entry goes stale.
-export const TEXT_BUDGET_DESCRIPTION = "Past 30,000 characters of JSON, the first text block holds data cut to fit, and the note says what the cut leaves out and where to read it (TEXT CUT); data in the structured result always holds it whole.";
+// when, does, have, on and the rest of its PROSE list), so no reviewed entry goes stale. #3013: the
+// same length as 2.7.x's (203 characters), since several descriptions sit within ten characters of
+// the floor the suite keeps under the client cut (#2924); FULL_ARG says the rest.
+export const TEXT_BUDGET_DESCRIPTION = "Past 30,000 characters of JSON, the first text block holds data cut to fit, and the note says what the cut leaves out and where to read it (TEXT CUT); so is structured data (DATA CUT), unless full: true.";
 const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 const field = (o, k) => (isPlainObject(o) ? o[k] : undefined);
 const listed = (xs) => (xs.length < 2 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs[xs.length - 1]}`);
@@ -165,6 +217,12 @@ function cutSides(data, sides) {
 export const FIRST_TEXT_BLOCK = {
     opens: (chars) => `TEXT CUT: the API's answer is ${chars} characters of JSON, more than the ${DATA_TEXT_BUDGET} the first text block holds, so that block is cut, and structuredContent.data carries the answer whole.`,
 };
+// #3013: the first text block beside a structuredContent.data that is cut too (DATA CUT): the same
+// text, cut the same way, and sentences that say data is whole only with full: true.
+export const FIRST_TEXT_BLOCK_BESIDE_A_CUT = {
+    opens: (chars) => `TEXT CUT: the API's answer is ${chars} characters of JSON, more than the ${DATA_TEXT_BUDGET} the first text block holds, so that block is cut, and structuredContent.data carries the answer whole with full: true (DATA CUT, below).`,
+    leftOut: (n, which) => `the other ${n} are left out of it${which}, and structuredContent.data holds them with full: true`,
+};
 /** The first text block for `data` within DATA_TEXT_BUDGET, and the TEXT CUT sentence when it is cut. */
 export function dataText(data, cut, place = FIRST_TEXT_BLOCK) {
     const pretty = JSON.stringify(data, null, 2);
@@ -232,7 +290,8 @@ export function dataText(data, cut, place = FIRST_TEXT_BLOCK) {
             const which = outFirst > 0
                 ? `: the ${outFirst} whose ${firstOut?.field} is ${(firstOut?.values ?? []).join(" or ")} (${firstOut?.why})${out.size > outFirst ? `, and the last ${out.size - outFirst} of the rest` : ""}`
                 : `, the last ${out.size} in order`;
-            const left = `Only ${kept.length} of the ${n} rows of ${cut.rows} are in it; the other ${out.size} are in structuredContent.data only${which}.`;
+            const elsewhere = place.leftOut ? place.leftOut(out.size, which) : `the other ${out.size} are in structuredContent.data only${which}`;
+            const left = `Only ${kept.length} of the ${n} rows of ${cut.rows} are in it; ${elsewhere}.`;
             return { text: shown, said: say(rowsSaid, ...sidesSaid, left, cut.whole, cut.page?.(kept.length, n, data)) };
         }
         base = { ...beside, [cut.rows]: cutRows };
@@ -250,5 +309,258 @@ export function dataText(data, cut, place = FIRST_TEXT_BLOCK) {
     const more = last.caps.size > 8 ? `, and ${last.caps.size - 8} more` : "";
     const lists = last.caps.size ? `Every list in it keeps at most its first ${last.n} ${last.n === 1 ? "entry" : "entries"}: ${listed(named)}${more}, each named with its full length.` : "";
     const strings = last.s.clipped ? `Every string in it longer than ${last.clip} characters keeps its first ${last.clip}, ending in "…".` : "";
-    return { text: last.text, said: say(rowsSaid, ...sidesSaid, lists, strings, cut?.whole) };
+    const said = say(rowsSaid, ...sidesSaid, lists, strings, cut?.whole);
+    if (last.caps.size === 0)
+        return { text: last.text, said };
+    return { text: last.text, said, capped: Object.fromEntries([...last.caps].map(([p, len]) => [p || "the answer", { total: len, returned: Math.min(last.n, len) }])) };
+}
+// ── The structured result's budget (#3013) ──
+//
+// What a success's structured result may cost, all of it (the envelope, its notes and data), as
+// compact JSON, which is how a client that hands structuredContent to a model reads it: the same
+// number as the first text block's. See "The structured result, per client" above.
+export const STRUCTURED_BUDGET = DATA_TEXT_BUDGET;
+// The clause of a paging tool's DATA CUT sentence that names the page size whose rows fit data
+// whole, given PageAt.wholeFit for its rows (search_cves, search_vendor_advisories).
+export const wholePage = (n) => n > 0
+    ? `a page of ${n} ${n === 1 ? "row" : "rows"} or fewer like these fits data whole.`
+    : `even a page of one row like these is past ${STRUCTURED_BUDGET} characters with that row whole, so its data is cut too.`;
+// A tool that names no list: only step 2 (every list at the top level of data) cuts its data.
+export const NO_DATA_CUT = { steps: [] };
+const calls = new AsyncLocalStorage();
+export function answering(full, cut, fn) {
+    return calls.run({ full: full === true, cut }, fn);
+}
+export const answeringNow = () => calls.getStore();
+// The argument every tool takes (#3013), and what it says, one constant string. It names no other
+// tool and directs no model (test/description-policy.test.mjs reads inputSchema descriptions too).
+export const FULL_ARG_DESCRIPTION = "true: data in the structured result is the answer whole, however long. Without it, a structured result past 30,000 characters of JSON has its data cut (DATA CUT): in an order the note states, the entries of its longest lists keep only some of their fields, and then the lists only some of their entries; data_truncated is true, and truncated gives each list cut with its total, the number returned and whether its entries are thinned. Whole data is for a program; a client that sizes structured results, as Claude Code does against MAX_MCP_OUTPUT_TOKENS, can refuse an answer past its cap.";
+export const FULL_ARG = z.boolean().optional().describe(FULL_ARG_DESCRIPTION);
+const thinned = (e, keep) => isPlainObject(e) ? cutRow(e, keep, { keep, clip: Number.POSITIVE_INFINITY }, { left: new Set(), clipped: 0, capped: 0 }) : e;
+// An entry JSON cannot write (undefined) is written null in a list.
+const entryChars = (e) => JSON.stringify(e)?.length ?? 4;
+const listOf = (data, at) => at.reduce((o, k) => field(o, k), data);
+function listAt(data, path, firstOut, thin, newest) {
+    const at = path.split(".");
+    const v = listOf(data, at);
+    if (!Array.isArray(v) || v.length === 0)
+        return undefined;
+    const n = v.length;
+    const entries = thin ? v.map((e) => thinned(e, thin)) : v;
+    const lens = entries.map(entryChars);
+    // The indices in the order they leave: from the end, or, for a series kept newest, from the start.
+    const leavingOrder = (i) => (newest ? i : n - 1 - i);
+    const order = [];
+    for (const value of firstOut?.values ?? [])
+        for (let j = 0; j < n; j++)
+            if (field(v[leavingOrder(j)], firstOut?.field ?? "") === value)
+                order.push(leavingOrder(j));
+    const named = order.length;
+    const queued = new Set(order);
+    for (let j = 0; j < n; j++)
+        if (!queued.has(leavingOrder(j)))
+            order.push(leavingOrder(j));
+    const leaving = [0];
+    for (const i of order)
+        leaving.push(leaving[leaving.length - 1] + lens[i]);
+    const all = leaving[n];
+    const kept = (k) => Math.max(0, Math.min(n, k));
+    return {
+        path,
+        at,
+        n,
+        firstOut,
+        thin,
+        ...(newest ? { newest } : {}),
+        named,
+        chars: (k) => all - leaving[n - kept(k)] + Math.max(0, kept(k) - 1),
+        keep: (k) => {
+            const out = new Set(order.slice(0, n - kept(k)));
+            return entries.filter((_, i) => !out.has(i));
+        },
+    };
+}
+// `o` with the list at `at` replaced by `v`, each object on the way copied, its keys in their order.
+function withList(o, at, v) {
+    const [k, ...rest] = at;
+    return { ...o, [k]: rest.length ? withList(o[k], rest, v) : v };
+}
+const orListed = (xs) => (xs.length < 2 ? xs.join("") : `${xs.slice(0, -1).join(", ")} or ${xs[xs.length - 1]}`);
+// The fields a thinning level keeps, as a sentence says them.
+const keepSaid = (keep) => listed(keep.map((x) => (typeof x === "string" ? x : `${x[0]} (each with ${listed([...x[1]])})`)));
+// What a cut keeps of each list it has cut so far, as truncated and as the DATA CUT sentences.
+function cutSaid(cut, kept, wholeChars, data, over, wholeFit) {
+    const isThinned = ({ list, k }) => list.thin !== undefined && k > 0;
+    const cutOnes = kept.filter((x) => x.k < x.list.n || isThinned(x));
+    if (cutOnes.length === 0)
+        return { said: "" };
+    const truncated = Object.fromEntries(cutOnes.map((x) => [x.list.path, { total: x.list.n, returned: x.k, ...(isThinned(x) ? { thinned: true } : {}) }]));
+    const parts = [];
+    const byKept = new Map();
+    for (const x of cutOnes) {
+        const { list, k } = x;
+        const out = list.n - k;
+        const first = Math.min(out, list.named);
+        const end = list.newest ? "oldest" : "last";
+        const which = list.firstOut ? `whose ${list.firstOut.field} is ${orListed(list.firstOut.values)} (${list.firstOut.why})` : "";
+        const leftOut = out === 0 ? "" : first === 0 ? `, the ${end} ${out} left out` : first === out ? `, the ${out} left out being entries ${which}` : `, the ${out} left out being the ${first} ${which} and the ${end} ${out - first} of the rest`;
+        if (isThinned(x)) {
+            parts.push(`${list.path} keeps ${k === list.n ? `all ${k}` : `${k} of its ${list.n}`} entries, each cut to ${keepSaid(list.thin)}${leftOut}`);
+            continue;
+        }
+        if (!list.firstOut || first === 0 || k === 0) {
+            const newest = list.newest === true && k > 0;
+            const key = `${k}:${newest}`;
+            const group = byKept.get(key);
+            if (group)
+                group.lists.push(list);
+            else {
+                const g = { k, newest, lists: [list] };
+                byKept.set(key, g);
+                parts.push(g);
+            }
+            continue;
+        }
+        parts.push(`${list.path} keeps ${k} of its ${list.n} entries${leftOut}`);
+    }
+    const cuts = parts.map((p) => {
+        if (typeof p === "string")
+            return p;
+        const paths = listed(p.lists.map((l) => l.path));
+        const which = p.newest ? "newest" : "first";
+        if (p.lists.length === 1)
+            return p.k === 0 ? `${paths} keeps none of its ${p.lists[0].n} entries` : `${paths} keeps its ${which} ${p.k} of ${p.lists[0].n} entries`;
+        return p.k === 0 ? `${paths} keep none of their entries` : `${paths} keep their ${which} ${p.k} entries each`;
+    });
+    const keeps = Object.fromEntries(cutOnes.filter(isThinned).map((x) => [x.list.path, x.list.thin]));
+    const page = cut.page?.(truncated, data, { keeps, wholeFit }) ?? "";
+    const said = [
+        `DATA CUT: with data whole, this structured result is ${wholeChars} characters of JSON, more than the ${STRUCTURED_BUDGET} it holds unless the call says full: true, so its data is cut: ${cuts.join("; ")}.`,
+        "truncated gives the total and the number returned of each list cut, and thinned where its entries are cut to some of their fields.",
+        page,
+        over ? `Cut so, the structured result is still past ${STRUCTURED_BUDGET} characters: data holds no other list to cut.` : "",
+        "The same call with full: true returns data whole.",
+    ];
+    return { truncated, said: said.filter(Boolean).join(" ") };
+}
+/**
+ * The structured result for `data` cut to STRUCTURED_BUDGET, as `cut` says (see "The structured
+ * result, per client" above): `structured` builds the result for a data, its truncated and the DATA
+ * CUT sentences, and is called with data null to size the rest of it. `wholeChars` is the result's
+ * size with data whole. undefined when data holds no list to cut.
+ */
+export function cutData(data, cut, wholeChars, structured) {
+    if (!isPlainObject(data))
+        return undefined;
+    const named = new Set(cut.steps.flatMap((s) => s.lists));
+    const steps = [...cut.steps, { lists: Object.keys(data).filter((k) => !named.has(k)) }];
+    // Each list cut so far, in the order cut, at the level it was thinned to, how many entries it
+    // keeps, and the step that cut it.
+    const kept = new Map();
+    const apply = (also = []) => [...kept.values(), ...also].reduce((d, { list, k }) => withList(d, list.at, list.keep(k)), data);
+    // PageAt.wholeFit: of the list at `path`, the most first entries, each whole, that the result
+    // holds within the budget with the rest of data whole and no DATA CUT sentence (structured with
+    // truncated undefined): the shape of the same call at that page size. Counted once per path.
+    const wholeFits = new Map();
+    const wholeFit = (path) => {
+        const known = wholeFits.get(path);
+        if (known !== undefined)
+            return known;
+        const at = path.split(".");
+        const v = listOf(data, at);
+        let k = 0;
+        if (Array.isArray(v)) {
+            let chars = JSON.stringify(structured(withList(data, at, []), undefined, "")).length;
+            for (const e of v) {
+                chars += entryChars(e) + (k > 0 ? 1 : 0);
+                if (chars > STRUCTURED_BUDGET)
+                    break;
+                k++;
+            }
+        }
+        wholeFits.set(path, k);
+        return k;
+    };
+    // The result's size with this step's lists at k entries each: the rest of the result (data
+    // null), data with this step's lists empty (`base`), and their entries.
+    const size = (lists, k, base) => {
+        const all = [...kept.values(), ...lists.map((list) => ({ list, k: Math.min(k, list.n) }))];
+        const { truncated, said } = cutSaid(cut, all, wholeChars, data, false, wholeFit);
+        return JSON.stringify(structured(null, truncated, said)).length - "null".length + base + lists.reduce((t, l) => t + l.chars(k), 0);
+    };
+    let fits = false;
+    for (const [s, step] of steps.entries()) {
+        // Every entry whole, then each thinning level in turn, every entry kept; at the leanest level
+        // the entries leave until the result fits.
+        const levels = [undefined, ...(step.thin ?? [])];
+        let lists = [];
+        let k = 0;
+        for (const [i, thin] of levels.entries()) {
+            lists = step.lists.map((p) => listAt(data, p, step.leaveOutFirst, thin, step.keepNewest)).filter((l) => l !== undefined && !kept.has(l.path));
+            if (lists.length === 0)
+                break;
+            const base = JSON.stringify(apply(lists.map((list) => ({ list, k: 0 })))).length;
+            const top = Math.max(...lists.map((l) => l.n));
+            if (i < levels.length - 1) {
+                if (size(lists, top, base) <= STRUCTURED_BUDGET) {
+                    k = top;
+                    fits = true;
+                    break;
+                }
+                continue;
+            }
+            if (size(lists, 0, base) <= STRUCTURED_BUDGET) {
+                // The most entries each list of the step keeps with the result inside the budget.
+                let hi = top;
+                while (k < hi) {
+                    const mid = Math.ceil((k + hi) / 2);
+                    if (size(lists, mid, base) <= STRUCTURED_BUDGET)
+                        k = mid;
+                    else
+                        hi = mid - 1;
+                }
+                fits = true;
+            }
+        }
+        for (const list of lists)
+            kept.set(list.path, { list, k: Math.min(k, list.n), step: s });
+        if (fits)
+            break;
+    }
+    // The room the step that fits leaves goes back to the steps emptied before it, the last first,
+    // each step's lists keeping at most the same number of their entries, as many as fit, at the
+    // level they were thinned to (scan_manifest's not_checked, emptied while its rows were whole,
+    // keeps its entries once the thinned rows fit).
+    if (fits) {
+        const exact = () => {
+            const { truncated, said } = cutSaid(cut, [...kept.values()], wholeChars, data, false, wholeFit);
+            return JSON.stringify(structured(apply(), truncated, said)).length;
+        };
+        const last = Math.max(...[...kept.values()].map((e) => e.step));
+        for (let s = last - 1; s >= 0; s--) {
+            const entries = [...kept.values()].filter((e) => e.step === s);
+            if (entries.length === 0)
+                continue;
+            const at = (k) => {
+                for (const e of entries)
+                    e.k = Math.min(k, e.list.n);
+            };
+            let k = Math.min(...entries.map((e) => e.k));
+            let hi = Math.max(...entries.map((e) => e.list.n));
+            while (k < hi) {
+                const mid = Math.ceil((k + hi) / 2);
+                at(mid);
+                if (exact() <= STRUCTURED_BUDGET)
+                    k = mid;
+                else
+                    hi = mid - 1;
+            }
+            at(k);
+        }
+    }
+    const { truncated, said } = cutSaid(cut, [...kept.values()], wholeChars, data, !fits, wholeFit);
+    if (truncated === undefined)
+        return undefined;
+    const d = apply();
+    return { data: d, truncated, said, structured: structured(d, truncated, said) };
 }

package/dist/tools/check_affected.js

@@ -27,7 +27,7 @@
 // The JSON is relayed verbatim as data (#1874): every match keeps kev_listed, ransomware,
 // epss_score, effective_score, effective_severity and score_assessed as the API sent them.
 import * as z from "zod";
-import { GET_CVE_WHOLE, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
+import { answering, FULL_ARG, GET_CVE_WHOLE, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 const TOOL = "check_affected";
 export const MATCH_PATH = "/api/v1/public/cves/match";
 // handler.go, the four request headers the endpoint reads before the query string.
@@ -74,10 +74,11 @@ const Match = z.looseObject({
     vendor_unknown: opt(z.boolean()).describe("true: the vendor was not verified, so the match is real but its attribution to your vendor is not."),
     match_reason: opt(z.string()),
     version_evidence: opt(z.string()),
-    // #2834: registry matches only (core-backend cve/pkgmatch_fixedin.go registryFixedIn).
+    // #2834, #3074: registry matches only (core-backend cve/pkgmatch_fixedin.go registryFixFor).
     interval: opt(z.looseObject({ introduced: opt(z.string()), fixed: opt(z.string()), last_affected: opt(z.string()) })).describe("Registry match: the advisory interval that holds this version (fixed is exclusive, last_affected inclusive); absent when no interval holds it."),
-    fixed_in: opt(z.string()).describe("Registry match: the fixed bound of the advisory interval that holds this version, always above it. null when that interval records no fix (it ends at last_affected, or has no end) or no interval holds the version, with fixed_in_reason saying which. Absent on a CPE match."),
+    fixed_in: opt(z.string()).describe("Registry match: the lowest version above this one that no affected interval of the CVE's record for the package holds, always above it: the fixed bound of the interval that holds this version, moved past any overlapping interval that still holds that bound (fixed_in_detail then names it). null when no such version is on record (an interval on the way records no fix: it ends at last_affected, or has no end) or no interval holds the version, with fixed_in_reason saying which. Absent on a CPE match."),
     fixed_in_reason: opt(z.string()).describe("Why fixed_in is null; absent when fixed_in is a version."),
+    fixed_in_detail: opt(z.string()).describe("Set when fixed_in is not the fixed bound of the interval that holds this version: the overlapping intervals of the same record it moved past, which still hold that bound."),
 });
 const Undetermined = z.looseObject({
     cve_id: opt(z.string()),
@@ -130,7 +131,7 @@ const COVERAGE = z.strictObject({
 // Constant strings, so marketing-site lib/mcpToolClaims.test.ts can fold them should it read
 // this file.
 export const CHECK_AFFECTED_TITLE = "Am I affected? (product or package at a version)";
-export const CHECK_AFFECTED_DESCRIPTION = "Whether a product or package at a given version is affected by known CVEs, from the same matcher as echelongraph.io/am-i-affected. The CPE path takes product (an NVD CPE product token, such as openssl or nginx) and version, and returns the CVEs whose NVD CPE match criteria include that product at that version; each match names the vendor NVD asserts (cpe_vendor) and whether it was verified (vendor_unknown). The registry path takes ecosystem (npm, PyPI, Maven and other OSV ecosystem names), package and version, and decides each OSV advisory EchelonGraph holds for that package as affected, not affected or undetermined. count depends on assessed: assessed false means the lookup did not evaluate this component, not_assessed_reason says why, and a count of 0 there is not a finding of not affected. An advisory undecidable at this version is reported as undetermined (undetermined_count, and up to 50 of them in undetermined), never as safe. Each match carries cve_id, kev_listed, ransomware, epss_score, effective_score, effective_severity and score_assessed (false: not yet scored, so echelongraph_score is withheld). A registry match also carries interval, the advisory interval holding this version, and fixed_in, its fixed bound, or null with fixed_in_reason; a CPE match carries no fixed_in. All four inputs travel in request headers, never in the URL." +
+export const CHECK_AFFECTED_DESCRIPTION = "Whether a product or package at a given version is affected by known CVEs, from the same matcher as echelongraph.io/am-i-affected. The CPE path takes product (an NVD CPE product token, such as nginx) and version, and returns the CVEs whose NVD CPE match criteria include that product at that version; each match names the vendor NVD asserts (cpe_vendor) and whether it was verified (vendor_unknown). The registry path takes ecosystem (npm, PyPI, Maven and other OSV ecosystem names), package and version, and decides each OSV advisory EchelonGraph holds for that package as affected, not affected or undetermined. count depends on assessed: assessed false means the lookup did not evaluate this component, not_assessed_reason says why, and a count of 0 there is not a finding of not affected. An advisory undecidable at this version is reported as undetermined (undetermined_count, and up to 50 of them in undetermined), never as safe. Each match carries cve_id, kev_listed, ransomware, epss_score, effective_score, effective_severity and score_assessed (false: not yet scored, so echelongraph_score is withheld). A registry match also carries interval, the advisory interval holding it, and fixed_in, the lowest unaffected version above it, or null with fixed_in_reason; a CPE match carries no fixed_in. All four inputs travel in request headers, never in the URL." +
     " " +
     TEXT_BUDGET_DESCRIPTION +
     " Cut, the excluded and undetermined samples keep their first 10 entries, each its cve_id and reason, cve_ids keeps its first 10, and each match keeps cve_id, kev_listed, ransomware, epss_score, effective_score, score_assessed and fixed_in at least. Every CPE match stays in the text; near the cap, a registry list's last matches can leave it, and the note says how many.";
@@ -139,6 +140,7 @@ export const CHECK_AFFECTED_INPUT = z.object({
     ecosystem: z.string().optional().describe("Registry path: the package's ecosystem, such as npm, PyPI or Maven. Give with package, not with product."),
     package: z.string().optional().describe("Registry path: the package name in that ecosystem, such as lodash."),
     version: z.string().describe("The version to check, such as 3.0.0."),
+    full: FULL_ARG,
 });
 const field = (o, k) => (o !== null && typeof o === "object" ? o[k] : undefined);
 const num = (o, k) => {
@@ -172,22 +174,24 @@ function matchesNote(matches) {
     }
     return out;
 }
-// #2834: what the registry matches say about a fix. fixed_in is the fixed bound of the interval
-// that holds this version (core-backend cve/pkgmatch_fixedin.go), so it is per match: an advisory
-// with several branches (Log4Shell: 2.3.1, 2.12.2, 2.15.0) names the one for this version.
+// #2834: what the registry matches say about a fix. fixed_in is the first version above this one
+// that no affected interval of the match's record holds (core-backend cve/pkgmatch_fixedin.go):
+// the fixed bound of the interval that holds this version, moved past any overlapping interval
+// that still holds it (#3074), so it is per match: an advisory with several branches (Log4Shell:
+// 2.3.1, 2.12.2, 2.15.0) names the one for this version.
 function fixedInNote(matches) {
     const registry = matches.filter((m) => m !== null && typeof m === "object" && "fixed_in" in m);
     if (registry.length === 0)
         return "";
     const fixed = registry.filter((m) => typeof field(m, "fixed_in") === "string").length;
     const none = registry.length - fixed;
-    return ` fixed_in, the fixed bound of the advisory interval that holds this version: ${fixed === registry.length ? `set on every match` : `set on ${fixed} of ${registry.length} matches`}${none > 0 ? `; null on ${none}, where the advisory records no fix for this version (fixed_in_reason says why)` : ""}.`;
+    return ` fixed_in, the first version above this one that no affected interval of the advisory holds: ${fixed === registry.length ? `set on every match` : `set on ${fixed} of ${registry.length} matches`}${none > 0 ? `; null on ${none}, where the advisory records no fix for this version (fixed_in_reason says why)` : ""}.`;
 }
 // #2783: a production match is about 2,100 characters as pretty JSON, most of it the CVE's
 // description and match_reason, so openssl 3.0.0 (71 matches) was 156,058 characters of text and
 // linux_kernel 5.10.0 (200, the API's cap) 364,408. Past DATA_TEXT_BUDGET each match in the first
 // text block keeps its scores, flags, vendor attribution and match_reason (for a registry match,
-// the advisory interval its version falls inside: "[A, B)" names the fixed version B, "[A, B]" the
+// the advisory interval its version falls inside: "[A, B)" names that interval's fixed bound B, "[A, B]" the
 // last affected one, #2830) with the
 // description cut to 200 characters; then the same without the description; then only the fields
 // the description promises; then, for a list at the cap, without cpe_vendor and vendor_unknown;
@@ -221,7 +225,7 @@ const CHECK_AFFECTED_TEXT = {
             keep: [
                 "cve_id", "severity", "cvss_v3_score", "description", "kev_listed", "ransomware", "epss_score", "echelongraph_score", "echelongraph_severity", "effective_score", "effective_severity",
                 "score_assessed", "score_unassessed_reason", "matched_criteria", "cpe_vendor", "vendor_unknown", "match_confidence", "match_reason", "version_evidence", "fixed_in",
-                "fixed_in_reason",
+                "fixed_in_reason", "fixed_in_detail",
             ],
             clip: 200,
         },
@@ -250,6 +254,32 @@ const CHECK_AFFECTED_TEXT = {
     ],
     whole: `${GET_CVE_WHOLE}, and cve_intel a CVE's affected packages and fixed versions.`,
 };
+// #3013: the structured result's cut. A production match is about 1,650 characters of compact JSON
+// (its description, matched criteria and match reason), so openssl 3.0.0's 71 matches were 147,564
+// characters of structured result and linux_kernel 5.10.0's 200 (the API's cap) 331,682. As in the
+// text, the samples beside the matches go first (excluded and undetermined, each to at most the same
+// number of its first entries; excluded_count and undetermined_count count every entry), then the
+// matches, and cve_ids, each match's cve_id in order, last: it names every match in a few thousand
+// characters. Before any match leaves, every match is thinned (most of a match is its description,
+// about 1,400 characters for openssl, which get_cve returns): first to its scores, flags, the
+// criteria it matched and fixed_in, then to the fields this tool's description says a match keeps
+// at least, with fixed_in_reason. Only then do matches leave from the end (the lowest ranked).
+const CHECK_AFFECTED_DATA = {
+    steps: [
+        { lists: ["excluded", "undetermined"] },
+        {
+            lists: ["matches"],
+            thin: [
+                [
+                    "cve_id", "severity", "cvss_v3_score", "kev_listed", "ransomware", "epss_score", "echelongraph_score", "echelongraph_severity", "effective_score", "effective_severity", "score_assessed",
+                    "score_unassessed_reason", "matched_criteria", "cpe_vendor", "vendor_unknown", "match_confidence", "version_evidence", "fixed_in", "fixed_in_reason",
+                ],
+                ["cve_id", "kev_listed", "ransomware", "epss_score", "effective_score", "score_assessed", "fixed_in", "fixed_in_reason"],
+            ],
+        },
+        { lists: ["cve_ids"] },
+    ],
+};
 async function checkAffected(kit, a) {
     const product = (a.product ?? "").trim();
     const ecosystem = (a.ecosystem ?? "").trim();
@@ -351,5 +381,5 @@ export function registerCheckAffected(server, kit) {
         inputSchema: CHECK_AFFECTED_INPUT,
         outputSchema: output,
         annotations: kit.annotations,
-    }, async (a) => kit.checked(TOOL, output, await checkAffected(kit, a)));
+    }, async (a) => kit.checked(TOOL, output, await answering(a.full, CHECK_AFFECTED_DATA, () => checkAffected(kit, a))));
 }

package/dist/tools/check_sbom.js

@@ -1,5 +1,5 @@
 import * as z from "zod";
-import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
+import { answering, FULL_ARG, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 import { CLEAN_NOTE, DISTRO_NOTE, FRESHNESS_NOTE, MAX_PURLS, MEASURED_AT_NOTE, METHOD, batchDataShape, dedupe, field, isObj, plural, purlsRefusal, sendBatches, sendingCoverage, sendingCoverageShape, sendingSentences, verdictSentences, } from "./match_batch.js";
 // #2835: the batch loop, its constants and the row schema moved to match_batch.ts, which
 // scan_manifest shares; re-exported here, where the tests and prompts.ts import them.
@@ -25,7 +25,7 @@ export const CHECK_SBOM_TITLE = "Check an SBOM against the advisory corpus";
 export const CHECK_SBOM_ROUTING = "For container images and Kubernetes pods, the input is an SBOM of each image, or its purls.";
 export const CHECK_SBOM_DESCRIPTION = "Check a dependency list against EchelonGraph's advisory corpus, one verdict per component. " +
     CHECK_SBOM_ROUTING +
-    " Pass purls (package URLs, up to 2,000 distinct) or sbom (a CycloneDX or SPDX JSON document, up to 5,000,000 characters). This server reads the purls from the document; only they are sent to the API, in POST bodies of at most 200, never in a URL; the document itself is not sent on. Run from npm, this server is on your machine; over the hosted endpoint (mcp.echelongraph.io) it is EchelonGraph's, and the document is the request body, accepted up to 6 MiB. data.results holds one row per component sent, in order, with verdict (affected, not_affected, undetermined or not_assessed), not_assessed_reason, cve_ids, matched_package and matched_via (a deb or apk purl's upstream qualifier matches as its source package); each match carries fixed_in (its interval's fixed bound) or null with fixed_in_reason. data.summary counts the verdicts. not_affected is the only clean verdict: not_assessed (no verdict, as for a deb, apk or rpm purl without a distro qualifier naming its release, which EchelonGraph does not guess) and undetermined are not, and the note counts both. The API allows 1,200 components a minute per caller; on a 429 the tool waits out Retry-After, up to 50 seconds a call, then answers what it has, the rest in data.not_sent_purls, unchecked and not clean. Input with more than 2,000 distinct purls is refused, not truncated." +
+    " Pass purls (package URLs, up to 2,000 distinct) or sbom (a CycloneDX or SPDX JSON document, up to 5,000,000 characters). This server reads the purls from the document; only they are sent to the API, in POST bodies of at most 200, never in a URL; the document itself is not sent on. Run from npm, this server is on your machine; over the hosted endpoint (mcp.echelongraph.io) it is EchelonGraph's, and the document is the request body, accepted up to 6 MiB. data.results holds one row per component sent, in order, with verdict (affected, not_affected, undetermined or not_assessed), not_assessed_reason, cve_ids, matched_package and matched_via (a deb or apk purl's upstream qualifier matches as its source package); each match carries fixed_in (the next unaffected version) or null with fixed_in_reason. data.summary counts the verdicts. not_affected is the only clean verdict: not_assessed (no verdict, as for a deb, apk or rpm purl without a distro qualifier naming its release, which EchelonGraph does not guess) and undetermined are not, and the note counts both. The API allows 1,200 components a minute per caller; on a 429 the tool waits out Retry-After, up to 50 seconds a call, then answers what it has, the rest in data.not_sent_purls, unchecked and not clean. Input with more than 2,000 distinct purls is refused, not truncated." +
     " " +
     TEXT_BUDGET_DESCRIPTION +
     " Cut, each row keeps index, purl, verdict, not_assessed_reason and cve_ids at least, each match its fixed_in while kept; not_affected rows leave the text first, then not_assessed ones; not_sent_purls keeps its first 10.";
@@ -34,7 +34,7 @@ export const CHECK_SBOM_DESCRIPTION = "Check a dependency list against EchelonGr
 // text, and 2,000 purls about 1,200,000. Past DATA_TEXT_BUDGET each row in the first text block
 // keeps its verdict, counts, cve_ids, matched_package and matched_via (#2836), and each match its
 // scores, flags, fixed_in (#2834) and match_reason (the
-// advisory interval the version falls inside: "[A, B)" names the fixed version B, "[A, B]" the last
+// advisory interval the version falls inside: "[A, B)" names that interval's fixed bound B, "[A, B]" the last
 // affected one, #2830) without the
 // description; then the same without match_reason; then only index, purl, verdict,
 // not_assessed_reason and cve_ids. When rows must still go, the clean ones (not_affected) leave
@@ -49,7 +49,7 @@ export const CHECK_SBOM_DESCRIPTION = "Check a dependency list against EchelonGr
 // reading the list. noteFor gives that order (READ_ORDER) beside the position, so this sentence
 // points to it.
 export function sbomText(sent) {
-    const matches = ["cve_id", "severity", "effective_severity", "effective_score", "kev_listed", "ransomware", "epss_score", "score_assessed", "fixed_in"];
+    const matches = ["cve_id", "severity", "effective_severity", "effective_score", "kev_listed", "ransomware", "epss_score", "score_assessed", "fixed_in", "fixed_in_reason"];
     const row = [
         "index", "purl", "ecosystem", "package", "version", "verdict", "assessed", "not_assessed_reason", "count", "not_affected_count", "undetermined_count", "cve_ids", "matched_package", "matched_via",
     ];
@@ -69,11 +69,49 @@ export function sbomText(sent) {
         ],
         leaveOutFirst: { field: "verdict", values: ["not_affected", "not_assessed"], why: "data.summary counts every verdict" },
         // check_affected cuts its text too past the budget (#2802): only its structuredContent.data is
-        // a component's matches whole.
-        whole: "check_affected, given a row's ecosystem, package and version, returns that component's matches, whole in its structuredContent.data, and cve_intel a CVE's affected packages and fixed versions.",
+        // a component's matches whole, with full: true (#3013).
+        whole: "check_affected, given a row's ecosystem, package and version, returns that component's matches, whole in its structuredContent.data with full: true, and cve_intel a CVE's affected packages and fixed versions.",
         page: (shown) => `To read every row in the text, check ${shown} or fewer purls per call.`,
     };
 }
+// #3013: the structured result's cut. A production row is about 1,900 characters of compact JSON
+// (its matches, each a CVE with its description), so the 50-component Juice Shop document was 98,682
+// characters of structured result and 2,000 purls 3,790,686. The lists beside the rows go first
+// (not_sent_purls: the note says from which position of the input they run, and in what order; and,
+// for scan_manifest, not_checked, which coverage.not_checked_by_reason counts). Then, before any
+// row leaves, every row is thinned to SBOM_ROW_THIN: what a row says of the component and its
+// verdict, and per match what a triage reads (a match's description, about 535 characters, is
+// get_cve's); the first #3013 cut, before release, kept 3 of Juice Shop's 50 rows whole, all affected, and named the
+// other 7 affected components nowhere a client reading structuredContent sees. Only then do rows
+// leave, as in the text: the not_affected rows first, then the not_assessed ones (data.summary
+// counts every verdict), then the last of the rest, so the affected and undetermined rows are the
+// last to go.
+// #3013's review: a thinned match kept cve_id, kev_listed, epss_score, fixed_in and
+// fixed_in_reason, while the workload_triage prompt reads kev_listed, ransomware, epss_score,
+// effective_score, score_assessed and fixed_in from a row's matches (its step 5 and ordering keys),
+// so a client reading structuredContent lost ransomware and the score it ranks by. Each field a
+// prompt reads from check_sbom's or scan_manifest's matches is kept (test/prompt-fields.test.mjs
+// holds every prompt's to this list).
+export const SBOM_ROW_THIN = [
+    "index",
+    "purl",
+    "verdict",
+    "not_assessed_reason",
+    "cve_ids",
+    "matched_package",
+    "matched_via",
+    ["matches", ["cve_id", "kev_listed", "ransomware", "epss_score", "effective_score", "score_assessed", "fixed_in", "fixed_in_reason"]],
+];
+export function sbomData(sides, page) {
+    return {
+        steps: [
+            { lists: sides },
+            { lists: ["results"], thin: [SBOM_ROW_THIN], leaveOutFirst: { field: "verdict", values: ["not_affected", "not_assessed"], why: "data.summary counts every verdict" } },
+        ],
+        page: (t) => (t.results && t.results.returned < t.results.total ? page(t.results.returned) : ""),
+    };
+}
+const SBOM_DATA = sbomData(["not_sent_purls"], (k) => `To read every row in data, check ${k} or fewer purls per call.`);
 // The purls of a CycloneDX JSON document: every components[] entry, nested ones included.
 // metadata.component (the subject of the SBOM, not a dependency of it) is not checked.
 function fromCycloneDX(doc) {
@@ -264,11 +302,12 @@ export function registerCheckSbom(server, deps) {
                 .union([z.string(), z.record(z.string(), z.unknown())])
                 .optional()
                 .describe("a CycloneDX JSON or SPDX JSON document, as JSON text or as an object; its purls are read by this MCP server and only they are sent to the API; over the hosted endpoint (mcp.echelongraph.io) the document is the request body"),
+            full: FULL_ARG,
         }),
         outputSchema: output,
         annotations: deps.annotations,
-    }, async (a, ctx) => {
+    }, async (a, ctx) => answering(a.full, SBOM_DATA, async () => {
         const run = checkSbom({ ...deps, signal: ctx.mcpReq.signal }, a);
         return deps.checked(CHECK_SBOM, output, await (deps.hold ? deps.hold(run) : run));
-    });
+    }));
 }