fix(mcp): guide oversized unknown recovery (#7876)

This commit is contained in:
morluto authored and GitHub committed 2026-10-29 05:07:35 +08:00
1 parent 5f146b3b19
commit 2aa0d45e13
3 files changed
+83 -8

No files matched your search

+5 -2
View File
@@ -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`.
+8 -6
View File
@@ -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,
@@ -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);
});