feat(mcp): name the next operation when a completed result overflows the response budget (#11015)

* feat(mcp): name the next operation when a completed result overflows the response budget

* test(mcp): assert next_operation for every overflow recovery route
This commit is contained in:
morluto authored and GitHub committed 2026-11-15 18:22:08 +08:00
1 parent b572dbaf25
commit e793fd6808
4 files changed
+163 -35

No files matched your search

+86 -23
View File
@@ -89,16 +89,90 @@ const evidenceBundleProjection = (value: JsonValue): JsonValue | undefined => {
: undefined;
};
const evidenceBundleOverflowStep = (value: JsonValue): string => {
/**
* The recovery for an overflowing completed result: its prose and, when it
* names one MCP operation to call first, that operation. The CLI fallback
* names none.
*/
interface OverflowNextStep {
readonly text: string;
readonly operation?: string;
}
const evidenceBundleOverflowStep = (value: JsonValue): OverflowNextStep => {
const projection = evidenceBundleProjection(value);
// A summary already used detail: summary; export writes outside one frame.
if (projection === "evidence-bundle-summary")
return MCP_TRANSPORT_EVIDENCE_EXPORT;
if (projection === "evidence-link-inspection")
return MCP_TRANSPORT_EVIDENCE_LINKS;
return projection === "evidence-record-selection"
? MCP_TRANSPORT_EVIDENCE_RECORDS
: MCP_TRANSPORT_EVIDENCE_DISCOVERY;
return {
text: MCP_TRANSPORT_EVIDENCE_EXPORT,
operation: "export_evidence_bundle",
};
return {
text:
projection === "evidence-link-inspection"
? MCP_TRANSPORT_EVIDENCE_LINKS
: projection === "evidence-record-selection"
? MCP_TRANSPORT_EVIDENCE_RECORDS
: MCP_TRANSPORT_EVIDENCE_DISCOVERY,
operation: "get_evidence_bundle",
};
};
/**
* Rows in an overflowing `list_unknowns` page, delivered as a session
* `{ result }` envelope; a smaller limit only helps above one.
*/
const unknownPageItems = (value: JsonValue): number => {
const page =
typeof value === "object" && value !== null && !Array.isArray(value)
? value.result
: undefined;
return typeof page === "object" &&
page !== null &&
!Array.isArray(page) &&
Array.isArray(page.items)
? page.items.length
: Number.POSITIVE_INFINITY;
};
const overflowNextStep = (
value: JsonValue,
contract: ToolContract,
recovery: Readonly<Record<string, JsonValue>>,
): OverflowNextStep => {
if (recovery.committed_unknown !== undefined)
return {
text: "Export this session with export_evidence_bundle to inspect the committed unknown and its mutation Evidence. Do not repeat the completed mutation; an individual unknown may be too large for a list_unknowns page.",
operation: "export_evidence_bundle",
};
if (recovery.continuation !== undefined)
return {
text: "Call inspect_analysis_view with the supplied continuation arguments to read retained analysis. Follow coverage.next_offset for subsequent pages; reduce the page limit if needed, or export the complete retained Evidence.",
operation: "inspect_analysis_view",
};
if (recovery.evidence_reference !== undefined)
return {
text: "Export retained evidence to consume the complete analysis, or use complete CLI JSON output.",
operation: "export_evidence_bundle",
};
if (contract.name === "list_unknowns" && unknownPageItems(value) <= 1)
return {
text: "One unknown does not fit a list_unknowns response on this connection, so a smaller limit cannot help. Export the session with export_evidence_bundle to recover it.",
operation: "export_evidence_bundle",
};
if (contract.name === "list_unknowns")
return {
text: "Call list_unknowns on this same connection with the same filters and offset, using a smaller limit, then follow next_offset. If a single unknown cannot fit, export the session with export_evidence_bundle to recover it.",
operation: "list_unknowns",
};
if (contract.name === "get_evidence_bundle")
return evidenceBundleOverflowStep(value);
if (contract.name === "inspect_address_context")
return {
text: "Call get_evidence_bundle with detail summary to discover retained facet observations, then export_evidence_bundle to inspect complete records. Some facets may not have been retained; a new analysis can differ.",
operation: "get_evidence_bundle",
};
return { text: "Use complete CLI JSON output to consume the analysis." };
};
/** Immutable encoding and recovery policy shared by one MCP server. */
@@ -445,26 +519,12 @@ export class ToolResultDelivery {
? { _meta: TARGET_CONTENT_RESULT_META }
: {}),
};
const retainedEvidence = recovery.evidence_reference !== undefined;
const nextStep =
recovery.committed_unknown !== undefined
? "Export this session with export_evidence_bundle to inspect the committed unknown and its mutation Evidence. Do not repeat the completed mutation; an individual unknown may be too large for a list_unknowns page."
: recovery.continuation !== undefined
? "Call inspect_analysis_view with the supplied continuation arguments to read retained analysis. Follow coverage.next_offset for subsequent pages; reduce the page limit if needed, or export the complete retained Evidence."
: retainedEvidence
? "Export retained evidence to consume the complete analysis, or use complete CLI JSON output."
: contract.name === "list_unknowns"
? "Call list_unknowns on this same connection with the same filters and offset, using a smaller limit, then follow next_offset. If a single unknown cannot fit, export the session with export_evidence_bundle to recover it."
: contract.name === "get_evidence_bundle"
? evidenceBundleOverflowStep(value)
: contract.name === "inspect_address_context"
? "Call get_evidence_bundle with detail summary to discover retained facet observations, then export_evidence_bundle to inspect complete records. Some facets may not have been retained; a new analysis can differ."
: "Use complete CLI JSON output to consume the analysis.";
const nextStep = overflowNextStep(value, contract, recovery);
const projected = mcpResponseOverflowProjection({
completed: true,
constraint: encoded.constraint,
effectiveResponseBytes: this.maximumResponseBytes,
nextStep,
nextStep: nextStep.text,
});
return this.toErrorToolResult(
new AnalysisResourceConstraintError(
@@ -480,6 +540,9 @@ export class ToolResultDelivery {
response_code_units_at_least: encoded.codeUnitsAtLeast,
constraint: encoded.constraint,
...recovery,
...(nextStep.operation === undefined
? {}
: { next_operation: nextStep.operation }),
},
{ remediationAction: projected.remediationAction },
),