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), }, ], toolFamilies: { fixture: "artifact" }, promptRequirements: { explain: ["fixture"] }, evidenceReferenceAlternatives: [], prompts: [ { name: "explain", title: "Explain", description: "Explain a document", arguments: [ { name: "document", description: "Document name", required: true }, ], parameters, }, ], }; const cleanups: Array<() => Promise> = []; 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; 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[] = [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[] = [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 | 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 = []; 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]); });