Files
reverse-engineering-anything/src/server/DeferredEvidenceMcpServer.test.ts
T
morluto b4a2a79c55 test(lifecycle): move local gate copies, tests/process-global and tests/boundary phase gates onto the shared harness (#11412)
* test(lifecycle): replace eight local gate helper copies with the shared harness

* test(lifecycle): count an arrival announced in the turn its operation settles

* test(lifecycle): move tests/process-global phase gates onto the shared harness (#11414)

* test(lifecycle): move tests/process-global phase gates onto the shared harness

* test(lifecycle): move tests/boundary filesystem and process phase gates onto the shared harness (#11418)

* test(lifecycle): move tests/boundary provider phase gates onto the shared harness

* test(lifecycle): move tests/boundary/mcp phase gates onto the shared harness (#11433)

* test(lifecycle): give each phaseGate hold its own promise so unhandled held rejections stay visible

* test(lifecycle): move tests/boundary browser, pcap and CLI worker phase gates onto the shared harness (#11437)

* test(lifecycle): move tests/boundary browser, pcap and CLI worker phase gates onto the shared harness

* test(lifecycle): move fixture-owned and arrival-only provider gates onto the shared harness (#11441)

* test(lifecycle): move src/server and provider phase gates onto the shared harness (#11447)

* test(lifecycle): move the remaining src server, Kuna copy, Frida and Ghidra phase gates onto the shared harness (#11471)
2026-11-16 04:49:19 +08:00

564 lines
19 KiB
TypeScript

import { AnalysisSettings } from "../application/AnalysisSettings.js";
import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
import type { Tool, ServerContext } from "@modelcontextprotocol/server";
import { afterEach, expect, it, vi } from "vitest";
import { z } from "zod";
import type { RecordedMcpCatalog } from "../recordedMcpCatalog.js";
import { DeferredEvidenceMcpServer } from "./DeferredEvidenceMcpServer.js";
import { ToolResultDelivery } from "./ToolResultDelivery.js";
import { promptArgumentsSchema } from "./promptArguments.js";
import {
phaseArrival,
phaseGate,
type PhaseGate,
} from "../../tests/support/lifecycleHarness.js";
const input = z.strictObject({ n: z.number().int().nonnegative().default(3) });
const output = z.strictObject({ n: z.number().int() });
const parameters = {
document: {
description: "Document name",
required: true,
completion: "document" as const,
},
};
const catalog: RecordedMcpCatalog = {
version: 1,
info: { name: "deferred-fixture", version: "1" },
instructions: "Fixture",
capabilities: {
tools: { listChanged: true },
prompts: { listChanged: true },
completions: {},
},
identity: {
counts: { cli_commands: 0, mcp_tools: 1, mcp_prompts: 1 },
digests: {
tools_sha256: "fixture",
prompts_sha256: "fixture",
combined_sha256: "fixture",
},
},
tools: [
{
name: "fixture",
inputSchema: z.toJSONSchema(input, {
io: "input",
}) as Tool["inputSchema"],
outputSchema: z.toJSONSchema(output),
},
],
evidenceReferenceAlternatives: [],
prompts: [
{
name: "explain",
title: "Explain",
description: "Explain a document",
arguments: [
{ name: "document", description: "Document name", required: true },
],
parameters,
},
],
};
const cleanups: Array<() => Promise<unknown>> = [];
afterEach(async () => {
while (cleanups.length > 0) await cleanups.pop()?.();
});
const fixture = async (
options: {
/** Holds deferred runtime loading after its cleanup is owned. */
readonly startup?: PhaseGate;
readonly analysisSettings?: AnalysisSettings;
readonly execute?: () => Promise<void>;
readonly failClose?: () => boolean;
readonly failLoad?: boolean;
readonly invalidOutput?: boolean;
readonly failAfterTool?: boolean;
readonly maximumInputElements?: number;
readonly evidenceReferenceAlternative?: boolean;
readonly progressive?: boolean;
readonly unionOutput?: boolean;
readonly mode?: "legacy" | "auto";
} = {},
) => {
const calls = vi.fn<(n: number, context: ServerContext) => void>();
const closed = vi.fn();
let loads = 0;
const canonicalOutput = options.unionOutput
? z.union([output, z.strictObject({ message: z.string() })])
: output;
const recorded = {
...catalog,
tools: catalog.tools.map((tool) => ({
...tool,
outputSchema: z.toJSONSchema(canonicalOutput),
})),
};
const server = new DeferredEvidenceMcpServer(
options.evidenceReferenceAlternative
? { ...recorded, evidenceReferenceAlternatives: ["fixture"] }
: recorded,
new ToolResultDelivery(1024 * 1024),
async (target) => {
loads++;
target.ownRuntimeCleanup(async () => {
closed();
if (options.failClose?.()) throw new Error("cleanup denied");
await target.closePartialRuntime();
});
await options.startup?.hold();
if (options.failLoad) throw new Error("PRIVATE startup cause");
target.analysisSettings = options.analysisSettings;
target.materialize(() => {
target.registerTool(
"fixture",
{ inputSchema: input, outputSchema: canonicalOutput },
async (args, context) => {
calls(args.n, context);
await options.execute?.();
return {
content: [],
structuredContent: {
n: options.invalidOutput ? "invalid" : args.n,
},
};
},
);
if (options.failAfterTool)
throw new Error("PRIVATE partial startup failure");
const completion = target.bindPromptCompletion({
complete: async () => ["Example"],
});
target.registerCanonicalPrompt(
"explain",
{
title: "Explain",
description: "Explain a document",
argsSchema: promptArgumentsSchema(
{ arguments: parameters },
completion,
),
},
async (args) => ({
messages: [
{
role: "user",
content: { type: "text", text: String(args.document) },
},
],
}),
);
});
},
{ maximumInputElements: options.maximumInputElements },
);
const client = new Client(
{ name: "deferred-fixture-client", version: "1" },
options.mode === undefined
? undefined
: { versionNegotiation: { mode: options.mode } },
);
if (options.progressive) server.enableProgressiveCatalog();
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
await server.connect(serverTransport);
await client.connect(clientTransport);
cleanups.push(async () => {
await client.close();
await server.close();
});
return {
server,
client,
serverTransport,
calls,
closed,
loads: () => loads,
};
};
it("loads cold definitions without initializing analysis and preserves canonical validation and identity", async () => {
const f = await fixture({ progressive: true });
const identity = f.server.catalogIdentity;
expect(identity.digests.combined_sha256).not.toBe(
catalog.identity.digests.combined_sha256,
);
expect(identity.counts.mcp_tools).toBe(2);
expect((await f.client.listTools()).tools.map(({ name }) => name)).toEqual([
"discover_tools",
]);
const changed = vi.fn();
f.client.setNotificationHandler("notifications/tools/list_changed", changed);
const discover = () =>
f.client.callTool({
name: "discover_tools",
arguments: { names: ["fixture"] },
});
expect((await discover()).isError).not.toBe(true);
expect(f.loads()).toBe(0);
expect(changed).toHaveBeenCalledTimes(1);
await discover();
expect(changed).toHaveBeenCalledTimes(1);
expect(
(await f.client.callTool({ name: "fixture", arguments: { n: 1.5 } }))
.isError,
).toBe(true);
expect(f.loads()).toBe(1);
expect(f.calls).not.toHaveBeenCalled();
expect(
(await f.client.callTool({ name: "fixture", arguments: {} }))
.structuredContent,
).toEqual({ n: 3 });
expect(f.server.catalogIdentity).toEqual(identity);
expect(changed).toHaveBeenCalledTimes(1);
const independent = await fixture({ progressive: true });
expect(
(await independent.client.listTools()).tools.map(({ name }) => name),
).toEqual(["discover_tools"]);
});
it("refuses excess input before loading a deferred runtime, then admits a valid call", async () => {
const f = await fixture({ maximumInputElements: 2 });
const result = await f.client.callTool({
name: "fixture",
arguments: { n: 3, other: [0] },
});
expect(result.isError).toBe(true);
const text = result.content.find((part) => part.type === "text")?.text;
expect(JSON.parse(text ?? "null")).toMatchObject({
error: {
code: "resource_constraint",
details: { reported_limits: { max_input_elements: 2 } },
},
});
expect(f.loads()).toBe(0);
expect(f.calls).not.toHaveBeenCalled();
await f.client.ping();
const admitted = await f.client.callTool({
name: "fixture",
arguments: { n: 4 },
});
expect(admitted.isError).not.toBe(true);
expect(admitted.structuredContent).toEqual({ n: 4 });
expect(f.loads()).toBe(1);
expect(f.calls).toHaveBeenCalledOnce();
});
it("uses recorded Evidence-reference guidance without loading the deferred runtime", async () => {
const f = await fixture({
maximumInputElements: 2,
evidenceReferenceAlternative: true,
});
const result = await f.client.callTool({
name: "fixture",
arguments: { n: 3, other: [0] },
});
const text = result.content.find((part) => part.type === "text")?.text;
expect(JSON.parse(text ?? "null")).toMatchObject({
error: {
code: "resource_constraint",
remediation: { action: expect.stringContaining("retained-evidence") },
},
});
expect(f.loads()).toBe(0);
expect(f.calls).not.toHaveBeenCalled();
});
it("discovers without initialization, then shares one canonical runtime and preserves request metadata", async () => {
const startup = phaseGate();
const f = await fixture({ startup });
const before = await f.client.listTools();
// Listings omit the recorded output schemas (the default `off` profile).
expect(before.tools).toEqual(
catalog.tools.map(({ outputSchema: _output, ...tool }) => tool),
);
expect((await f.client.listPrompts()).prompts).toEqual(
catalog.prompts.map(({ parameters: _parameters, ...prompt }) => prompt),
);
expect(f.loads()).toBe(0);
const changed = vi.fn();
f.client.setNotificationHandler("notifications/tools/list_changed", changed);
const a = f.client.callTool({
name: "fixture",
arguments: {},
_meta: { caller: "retained" },
});
const pending: Promise<unknown>[] = [a];
try {
await startup.reached(a, "deferred initialization");
const b = f.client.callTool({ name: "fixture", arguments: { n: 7 } });
pending.push(b);
startup.release();
expect((await a).structuredContent).toEqual({ n: 3 });
expect((await b).structuredContent).toEqual({ n: 7 });
expect(f.loads()).toBe(1);
expect(f.calls.mock.calls[0]?.[1].mcpReq._meta?.caller).toBe("retained");
expect(await f.client.listTools()).toEqual(before);
expect(changed).not.toHaveBeenCalled();
const invalid = await f.client.callTool({
name: "fixture",
arguments: { n: 1.5 },
});
expect(invalid.isError).toBe(true);
expect(f.calls).toHaveBeenCalledTimes(2);
} finally {
startup.release();
await Promise.allSettled(pending);
}
});
it("preserves output validation after deferred registration", async () => {
const f = await fixture({ invalidOutput: true });
const result = await f.client.callTool({ name: "fixture", arguments: {} });
expect(result.isError).toBe(true);
});
it.each(["legacy", "auto"] as const)(
"canonically validates deferred object-union outputs over %s",
async (mode) => {
const valid = await fixture({ unionOutput: true, mode });
const before = await valid.client.listTools();
expect(
before.tools.find(({ name }) => name === "fixture")?.outputSchema,
).toBeUndefined();
expect(valid.loads()).toBe(0);
const success = await valid.client.callTool({
name: "fixture",
arguments: { n: 7 },
});
expect(success.isError).not.toBe(true);
expect(success.structuredContent).toEqual({ n: 7 });
expect(valid.calls).toHaveBeenCalledOnce();
expect(await valid.client.listTools()).toEqual(before);
const invalid = await fixture({
unionOutput: true,
invalidOutput: true,
mode,
});
const rejected = await invalid.client.callTool({
name: "fixture",
arguments: {},
});
// The handler actually returned malformed data. A server-side validation
// error must arrive, rather than success or only a client-validator throw.
expect(invalid.calls).toHaveBeenCalledOnce();
expect(rejected.isError).toBe(true);
expect(rejected.structuredContent).toBeUndefined();
expect(invalid.loads()).toBe(1);
expect(await invalid.client.listTools()).toEqual(before);
},
);
it("initializes through prompt retrieval or completion without an internal client", async () => {
const f = await fixture();
expect(
(
await f.client.complete({
ref: { type: "ref/prompt", name: "explain" },
argument: { name: "document", value: "Ex" },
})
).completion.values,
).toEqual(["Example"]);
expect(
(
await f.client.getPrompt({
name: "explain",
arguments: { document: "Example" },
})
).messages[0]?.content,
).toEqual({ type: "text", text: "Example" });
expect(f.loads()).toBe(1);
});
it("retrieves a prompt as the first operation", async () => {
const f = await fixture();
const result = await f.client.getPrompt({
name: "explain",
arguments: { document: "Example" },
});
expect(result.messages).toHaveLength(1);
expect(f.loads()).toBe(1);
});
it("does not execute a tool cancelled while canonical loading is pending", async () => {
const startup = phaseGate();
const f = await fixture({ startup });
const cancelled = phaseArrival();
const previous = f.serverTransport.onmessage;
f.serverTransport.onmessage = (message, extra) => {
previous?.(message, extra);
if ("method" in message && message.method === "notifications/cancelled")
cancelled.arrive();
};
const controller = new AbortController();
const pending = f.client.callTool(
{ name: "fixture", arguments: {} },
{ signal: controller.signal },
);
const rejected = expect(pending).rejects.toBeDefined();
try {
await startup.reached(pending, "cancelled caller initialization");
controller.abort();
await cancelled.reached(
f.server.ensureRuntime(),
"cancellation notification",
);
startup.release();
await rejected;
await f.server.ensureRuntime();
expect(f.calls).not.toHaveBeenCalled();
expect(
(await f.client.callTool({ name: "fixture", arguments: {} })).isError,
).not.toBe(true);
} finally {
controller.abort();
startup.release();
await Promise.allSettled([pending, rejected, f.server.ensureRuntime()]);
if (previous === undefined) delete f.serverTransport.onmessage;
else f.serverTransport.onmessage = previous;
}
});
it("keeps an independent caller alive when its peer cancels during shared loading", async () => {
const startup = phaseGate();
const f = await fixture({ startup });
const secondRequest = phaseArrival();
const cancelled = phaseArrival();
let toolCalls = 0;
const previous = f.serverTransport.onmessage;
f.serverTransport.onmessage = (message, extra) => {
previous?.(message, extra);
if (
"method" in message &&
message.method === "tools/call" &&
++toolCalls === 2
)
secondRequest.arrive();
if ("method" in message && message.method === "notifications/cancelled")
cancelled.arrive();
};
const controller = new AbortController();
const a = f.client
.callTool({ name: "fixture", arguments: {} }, { signal: controller.signal })
.catch(() => undefined);
const pending: Promise<unknown>[] = [a];
try {
await startup.reached(a, "shared initialization");
const b = f.client.callTool({ name: "fixture", arguments: { n: 8 } });
pending.push(b);
await secondRequest.reached(b, "independent caller admission");
controller.abort();
await cancelled.reached(
f.server.ensureRuntime(),
"peer cancellation notification",
);
startup.release();
await a;
expect((await b).structuredContent).toEqual({ n: 8 });
expect(f.calls).toHaveBeenCalledTimes(1);
expect(f.loads()).toBe(1);
} finally {
controller.abort();
startup.release();
await Promise.allSettled([...pending, f.server.ensureRuntime()]);
if (previous === undefined) delete f.serverTransport.onmessage;
else f.serverTransport.onmessage = previous;
}
});
it("joins late initialization during close and prevents target execution", async () => {
const startup = phaseGate();
const f = await fixture({ startup });
const pending = f.client
.callTool({ name: "fixture", arguments: {} })
.catch(() => undefined);
let closing: Promise<void> | undefined;
try {
await startup.reached(pending, "initialization before close");
closing = f.server.close();
startup.release();
await closing;
await pending;
expect(f.calls).not.toHaveBeenCalled();
expect(f.closed).toHaveBeenCalledTimes(1);
await expect(f.server.ensureRuntime()).rejects.toThrow("closed");
} finally {
startup.release();
await Promise.allSettled([pending, closing]);
}
});
it("retains failed cleanup for retry without loading a replacement runtime", async () => {
let denied = true;
const f = await fixture({ failClose: () => denied });
await f.client.callTool({ name: "fixture", arguments: {} });
await expect(f.server.close()).rejects.toThrow("cleanup");
await expect(f.server.ensureRuntime()).rejects.toThrow("closed");
denied = false;
await f.server.close();
expect(f.closed).toHaveBeenCalledTimes(2);
expect(f.loads()).toBe(1);
});
it("keeps startup failures redacted and owns partial cleanup", async () => {
const f = await fixture({ failLoad: true });
const result = await f.client.callTool({ name: "fixture", arguments: {} });
expect(result.isError).toBe(true);
expect(JSON.stringify(result)).not.toContain("PRIVATE");
await f.server.close();
expect(f.closed).toHaveBeenCalledTimes(1);
});
it("closes an unused instance without constructing the runtime", async () => {
const f = await fixture();
await f.client.listTools();
await f.server.close();
expect(f.loads()).toBe(0);
expect(f.closed).not.toHaveBeenCalled();
});
it("never executes a partially registered handler after initialization fails", async () => {
const f = await fixture({ failAfterTool: true });
const first = await f.client.callTool({ name: "fixture", arguments: {} });
const retry = await f.client.callTool({ name: "fixture", arguments: {} });
expect(first.isError).toBe(true);
expect(retry.isError).toBe(true);
expect(f.calls).not.toHaveBeenCalled();
expect(f.loads()).toBe(1);
await f.server.close();
expect(f.closed).toHaveBeenCalledTimes(1);
});
it("keeps one accepted settings snapshot through a deferred handler while the next call sees updates", async () => {
const settings = new AnalysisSettings({});
const handler = phaseGate();
const seen: Array<number | undefined> = [];
const f = await fixture({
analysisSettings: settings,
execute: async () => {
await handler.hold();
seen.push(settings.read().overrides["asar.max_header_bytes"]);
},
});
const pending = f.client.callTool({ name: "fixture", arguments: {} });
try {
await handler.reached(pending, "settings snapshot handler entry");
expect(
settings.update({
changes: [
{ setting: "asar.max_header_bytes", action: "set", value: 33554432 },
],
}).ok,
).toBe(true);
} finally {
handler.release();
await Promise.allSettled([pending]);
}
expect((await pending).isError).not.toBe(true);
await f.client.callTool({ name: "fixture", arguments: {} });
expect(seen).toEqual([undefined, 33554432]);
});