From 2aa0d45e1382435669fa82e97f839640f8699780 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 29 Oct 2026 05:07:35 +0800 Subject: [PATCH] fix(mcp): guide oversized unknown recovery (#7876) --- docs/mcp-contracts.md | 7 +- src/server/ToolResultDelivery.ts | 14 ++-- tests/boundary/mcp/serverUnknownsMcp.test.ts | 70 ++++++++++++++++++++ 3 files changed, 83 insertions(+), 8 deletions(-) diff --git a/docs/mcp-contracts.md b/docs/mcp-contracts.md index 3871cc0835..c801887af1 100644 --- a/docs/mcp-contracts.md +++ b/docs/mcp-contracts.md @@ -342,8 +342,11 @@ When `record_unknown` or `update_unknown` commits but its complete reply exceeds the response budget, `details.reported_limits.committed_unknown` identifies the exact unknown ID, committed revision and mutation Evidence IDs. Its retained Evidence reference remains available on the same connection. Export the bundle -or page `list_unknowns` to recover the result; do not repeat the committed -mutation. A delivery failure does not undo that revision. +to recover the result; do not repeat the committed mutation. A single unknown +may be too large for a `list_unknowns` page. A delivery failure does not undo +that revision. If a list response overflows, retry on the same connection with +the same filters and offset and a smaller limit; export if one head still cannot +fit. For a portable exported bundle, the CLI shares this projection: `rea inspect-evidence-bundle '{"path":"/tmp/evidence.json","detail":"summary","filters":{"operation":"analyze_function"}}' --format json`. diff --git a/src/server/ToolResultDelivery.ts b/src/server/ToolResultDelivery.ts index 5198c51a70..b31aacdc20 100644 --- a/src/server/ToolResultDelivery.ts +++ b/src/server/ToolResultDelivery.ts @@ -221,16 +221,18 @@ export class ToolResultDelivery { 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, or page list_unknowns using the reported identity. Do not repeat the completed mutation." + ? "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 === "get_evidence_bundle" - ? evidenceBundleSummary(value) - ? MCP_TRANSPORT_EVIDENCE_EXPORT - : MCP_TRANSPORT_EVIDENCE_DISCOVERY - : "Use complete CLI JSON output to consume the analysis."; + : 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" + ? evidenceBundleSummary(value) + ? MCP_TRANSPORT_EVIDENCE_EXPORT + : MCP_TRANSPORT_EVIDENCE_DISCOVERY + : "Use complete CLI JSON output to consume the analysis."; const projected = mcpResponseOverflowProjection({ completed: true, constraint: encoded.constraint, diff --git a/tests/boundary/mcp/serverUnknownsMcp.test.ts b/tests/boundary/mcp/serverUnknownsMcp.test.ts index 50764ae7b1..68f4081808 100644 --- a/tests/boundary/mcp/serverUnknownsMcp.test.ts +++ b/tests/boundary/mcp/serverUnknownsMcp.test.ts @@ -1,3 +1,6 @@ +import { readFile } from "node:fs/promises"; +import { join } from "node:path"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; import { createToolResultDelivery } from "../../../src/server/toolResult.js"; import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; @@ -571,10 +574,31 @@ it("returns exact committed unknown receipts when creation and update replies ov }, }, }); + const recovery = parseMcpToolError(response).error.remediation.action; + expect(recovery).toContain("export_evidence_bundle"); + expect(recovery).not.toContain("or page list_unknowns"); + expect(recovery).toContain("may be too large"); for (const id of unknown.mutation_evidence_ids) expect(session.evidenceById(id)).toBeDefined(); }; checkReceipt(created, first); + const singlePage = await client.callTool({ + name: "list_unknowns", + arguments: { offset: 0, limit: 1 }, + }); + expect(singlePage.isError).toBe(true); + expect(parseMcpToolError(singlePage).error.remediation.action).toContain( + "export_evidence_bundle", + ); + const directory = await createTestTempDirectory("rea-unknown-overflow-"); + const path = join(directory, "bundle.json"); + const exported = await client.callTool({ + name: "export_evidence_bundle", + arguments: { path }, + }); + expect(exported.isError).not.toBe(true); + const bundle = parseEvidenceBundle(JSON.parse(await readFile(path, "utf8"))); + expect(bundle.unknowns[0]?.question).toBe("x".repeat(10_000)); const updated = await client.callTool({ name: "update_unknown", arguments: { @@ -709,3 +733,49 @@ it("preserves graph constraint facts and rejects atomically until input is corre retryable: true, }); }); + +it("recovers an oversized list with same-session paging or export", async () => { + const session = createTestBinarySession(providerWithCapabilities([])); + const server = createServer( + { kind: "session", session }, + { delivery: createToolResultDelivery(8 * 1024) }, + ); + const client = new Client({ name: "unknown-list-recovery", version: "1" }); + const [ct, st] = InMemoryTransport.createLinkedPair(); + resources.push(client, server); + await server.connect(st); + await client.connect(ct); + const fields = { + severity: "medium", + domain: "overflow-list", + required_authority: null, + required_confidence: "observed", + required_environment: null, + recommended_probes: [], + relationships: [], + }; + for (let i = 0; i < 3; i += 1) { + const result = await client.callTool({ + name: "record_unknown", + arguments: { ...fields, question: `${i}-${"q".repeat(1800)}` }, + }); + expect(result.isError).not.toBe(true); + } + const overflow = parseMcpToolError( + await client.callTool({ + name: "list_unknowns", + arguments: { domain: "overflow-list" }, + }), + ).error; + expect(overflow.code).toBe("resource_constraint"); + expect(overflow.remediation.action).toContain("same connection"); + expect(overflow.remediation.action).toContain("smaller limit"); + expect(overflow.remediation.action).toContain("export_evidence_bundle"); + expect(overflow.remediation.action).not.toContain("CLI JSON"); + const first = await client.callTool({ + name: "list_unknowns", + arguments: { domain: "overflow-list", offset: 0, limit: 1 }, + }); + expect(first.isError).not.toBe(true); + expect(session.exportEvidenceBundle().unknowns).toHaveLength(3); +});