mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 11:43:20 +00:00
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:
1 parent
b572dbaf25
commit
e793fd6808
4 files changed
+163
-35
No files matched your search
@@ -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 },
|
||||
),
|
||||
|
||||
Reference in new issue
Block a user