mirror of
https://github.com/morluto/rea.git
synced 2026-11-19 13:12:26 +00:00
* 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)
564 lines
19 KiB
TypeScript
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]);
|
|
});
|