import { randomUUID } from "node:crypto"; import { readFileSync } from "node:fs"; import { setFlagsFromString } from "node:v8"; import { runInNewContext } from "node:vm"; import { describe, expect, it, vi } from "vitest"; import type { Db } from "@paperclipai/db"; import { ToolGatewayHttpError, type ToolGatewayDescriptor, type ToolGatewayService } from "../tool-gateway.js"; import { ASSIGNED_CATALOG_CACHE_BYTES, ASSIGNED_CATALOG_CACHE_ENTRIES, assignedCatalogCacheStats, ASSIGNED_SCHEMA_ADMISSION_CACHE_ENTRIES, ASSIGNED_SCHEMA_LISTING_BUDGET_BYTES, assignedSchemaAdmissionCacheSize, createAssignedMcpTools, getAssignedMcpGateway, registerAssignedMcpGateway, } from "./assigned-mcp-tools.js"; import { admitToolInputSchema } from "../../vendor/paperclip-runner/index.js"; import { startOpenCodeMcpBridge } from "../../vendor/paperclip-runner/testing.js"; vi.mock("../../vendor/paperclip-runner/index.js", async importOriginal => { const actual = await importOriginal(); return { ...actual, admitToolInputSchema: vi.fn(actual.admitToolInputSchema) }; }); function sizedSchema(bytes: number): Record { const marker = randomUUID(); return { type: "object", description: `${marker}${"x".repeat(Math.max(0, bytes - 80))}`, properties: { name: { type: "string" } } }; } function compiledDescriptions(): string[] { return vi.mocked(admitToolInputSchema).mock.calls.map(([schema]) => String(schema.description).slice(0, 36)); } function descriptor(name: string, risk: ToolGatewayDescriptor["risk"] = "read"): ToolGatewayDescriptor { return { name, displayName: name, description: `Use ${name}`, parametersSchema: { type: "object", properties: { query: { type: "string" } } }, pluginId: "fixture", providerType: "mcp_remote_http", risk }; } function fixture(tools: ToolGatewayDescriptor[]) { const listToolsForNamedGateway = vi.fn().mockResolvedValue(tools); const executeTool = vi.fn().mockResolvedValue({ status: "completed", result: { content: [{ type: "text", text: "memory found" }] } }); const gateway = { listToolsForNamedGateway, executeTool } as unknown as ToolGatewayService; return { gateway, listToolsForNamedGateway, executeTool, gatewayPublicId: "gateway-fixture", bearerToken: "private-run-token-never-project" }; } describe("assigned MCP runner tools", () => { const searchName = "paperclip_search_assigned_tools"; const callName = "paperclip_call_assigned_tool"; it.each(["", " \t\n"])("discovers and calls assigned tools through MCP with a blank schema reference %j", async schemaTool => { const github = descriptor("github_bot:read_pull_request"); const f = fixture([github, descriptor("calendar.search")]); const assigned = await createAssignedMcpTools({ ...f, delivery: "on_demand" }); const bridge = await startOpenCodeMcpBridge({ tools: assigned.definitions(), handler: call => assigned.execute(call) }); let id = 0; const call = async (name: string, args: Record) => { const response = await fetch(bridge.url, { method: "POST", headers: { Authorization: `Bearer ${bridge.secret}`, "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method: "tools/call", params: { name, arguments: args } }), }); const result = (await response.json()).result; expect(result.isError).not.toBe(true); return JSON.parse(result.content[0].text); }; try { const page = await call(searchName, { query: "github", schemaTool }); expect(page.tools).toHaveLength(1); expect(page.tools[0]).toMatchObject({ description: expect.stringContaining(github.name), inputSchema: github.parametersSchema }); expect(await call(searchName, { query: "github", schemaTool, schemaOffset: 0 })).toEqual(page); expect((await call(searchName, { query: "", schemaTool })).tools).toHaveLength(2); await call(callName, { name: page.tools[0].name, arguments: { query: "fixture" } }); expect(f.executeTool).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ tool: github.name, parameters: { query: "fixture" }, gatewayPublicId: f.gatewayPublicId, sessionToken: f.bearerToken, })); f.listToolsForNamedGateway.mockResolvedValue([]); expect(await call(searchName, { query: "github", schemaTool })).toEqual({ tools: [], nextOffset: null }); } finally { await bridge.close(); } }); it("explains how to recover from an unknown schema reference or an offset without a reference", async () => { const f = fixture([descriptor("github_bot:read_pull_request")]); const assigned = await createAssignedMcpTools({ ...f, delivery: "on_demand" }); await expect(assigned.execute({ tool: searchName, arguments: { query: "github", schemaTool: "unknown" } })) .rejects.toThrow("Omit schemaTool to search assigned tools"); for (const schemaTool of [undefined, "", " \t\n"]) { await expect(assigned.execute({ tool: searchName, arguments: { query: "github", schemaTool, schemaOffset: 1 } })) .rejects.toThrow("A positive schemaOffset requires an exact inputSchemaRef in schemaTool"); } expect(f.executeTool).not.toHaveBeenCalled(); }); it.each([undefined, "on_demand"] as const)("advertises usable page limits through MCP discovery (%s)", async delivery => { const f = fixture(Array.from({ length: 25 }, (_, i) => descriptor(`operation_${i}`))); const assigned = await createAssignedMcpTools({ ...f, delivery }); const bridge = await startOpenCodeMcpBridge({ tools: assigned.definitions(tools => tools.length <= 2), handler: call => assigned.execute(call), }); let id = 0; const rpc = async (method: string, params?: Record) => { const response = await fetch(bridge.url, { method: "POST", headers: { Authorization: `Bearer ${bridge.secret}`, "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method, params }), }); return (await response.json()).result; }; try { const listing = await rpc("tools/list"); const search = listing.tools.find((tool: { name: string }) => tool.name === searchName); const limit = search.inputSchema.properties.limit; for (const description of [search.description, limit.description]) { expect(description).toContain(`${limit.minimum} to ${limit.maximum}`); expect(description).toContain(`default ${limit.default}`); } expect(limit).toMatchObject({ minimum: 1, maximum: 20, default: 5 }); const page = async (args: Record) => { const result = await rpc("tools/call", { name: searchName, arguments: args }); expect(result.isError).not.toBe(true); return JSON.parse(result.content[0].text); }; expect((await page({ query: "" })).tools).toHaveLength(limit.default); const first = await page({ query: "", limit: limit.maximum }); expect(first.tools).toHaveLength(limit.maximum); const second = await page({ query: "", limit: limit.maximum, offset: first.nextOffset }); expect(second.nextOffset).toBeNull(); expect(new Set([...first.tools, ...second.tools].map((tool: { name: string }) => tool.name)).size).toBe(25); for (const invalid of [21, 50]) { await expect(assigned.execute({ tool: searchName, arguments: { query: "", limit: invalid } })) .rejects.toThrow("assigned_mcp_tool_invalid_arguments"); } } finally { await bridge.close(); } }); it.each(["page", "escaped schema"])("keeps on-demand %s results valid through the OpenCode MCP bridge", async variant => { const schema = { type: "object", description: variant === "page" ? "x".repeat(20_000) : "\"\\\u0000🙂".repeat(30_000) }; const f = fixture(Array.from({ length: variant === "page" ? 5 : 1 }, (_, i) => ({ ...descriptor(`large_${i}`), parametersSchema: schema, }))); const assigned = await createAssignedMcpTools({ ...f, delivery: "on_demand" }); const bridge = await startOpenCodeMcpBridge({ tools: assigned.definitions(), handler: call => assigned.execute(call) }); let id = 0; const search = async (args: Record) => { const response = await fetch(bridge.url, { method: "POST", headers: { Authorization: `Bearer ${bridge.secret}`, "Content-Type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: ++id, method: "tools/call", params: { name: searchName, arguments: args } }), }); const rpc = await response.json() as { result: { isError?: boolean; content: Array<{ text: string }> } }; expect(rpc.result.isError).not.toBe(true); return JSON.parse(rpc.result.content[0]!.text); }; try { let page = await search({ query: "", limit: 20 }); if (variant === "page") { const seen = [...page.tools]; while (page.nextOffset !== null) { page = await search({ query: "", offset: page.nextOffset, limit: 20 }); seen.push(...page.tools); } expect(seen).toHaveLength(5); expect(seen.every(tool => JSON.stringify(tool.inputSchema) === JSON.stringify(schema))).toBe(true); } else { const name = page.tools[0]!.inputSchemaRef; expect(name).toBeTypeOf("string"); let offset: number | null = 0; let reconstructed = ""; do { const chunk = await search({ query: "", schemaTool: name, schemaOffset: offset }); reconstructed += chunk.schemaJson; offset = chunk.nextSchemaOffset; } while (offset !== null); expect(JSON.parse(reconstructed)).toEqual(schema); } } finally { await bridge.close(); } }); it.each([1, 741])("uses bounded on-demand delivery for %i tools even when the direct catalog fits", async count => { const f = fixture(Array.from({ length: count }, (_, i) => descriptor(`app.operation_${i}`))); const direct = await createAssignedMcpTools(f); const assigned = await createAssignedMcpTools({ ...f, delivery: "on_demand" }); const fits = vi.fn(() => true); expect(assigned.definitions(fits).map(tool => tool.name)).toEqual([searchName, callName]); expect(fits).toHaveBeenCalledExactlyOnceWith(assigned.definitions()); expect(() => assigned.definitions(() => false)).toThrow("assigned_mcp_tool_catalog_capacity_exceeded"); const page = await assigned.execute({ tool: searchName, arguments: { query: "", limit: 1 } }) as { tools: Array<{ name: string }> }; expect(page.tools[0]!.name).toBe(direct.definitions().map(tool => String(tool.name)).sort()[0]); await assigned.execute({ tool: callName, arguments: { name: page.tools[0]!.name, arguments: { query: "fixture" }, gatewayPublicId: "untrusted", bearerToken: "untrusted" } }); expect(f.executeTool).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ gatewayPublicId: f.gatewayPublicId, sessionToken: f.bearerToken })); f.listToolsForNamedGateway.mockResolvedValue([]); await expect(assigned.execute({ tool: searchName, arguments: { query: "" } })).resolves.toEqual({ tools: [], nextOffset: null }); }); it("keeps on-demand aliases pinned, mode restricted, revocable and approval gated", async () => { const read = descriptor("mcp.first:search"); const write = descriptor("mcp.second:search", "write"); const f = fixture([read, write]); const assigned = await createAssignedMcpTools({ ...f, delivery: "on_demand" }); const page = await assigned.execute({ tool: searchName, arguments: { query: "" } }) as { tools: Array<{ name: string; description: string }> }; expect(new Set(page.tools.map(tool => tool.name)).size).toBe(2); const writeAlias = page.tools.find(tool => tool.description.includes(write.name))!.name; const call = { tool: callName, arguments: { name: writeAlias, arguments: {} } }; await expect(assigned.execute(call, "planning")).rejects.toThrow("paperclip_runner_tool_mode_denied"); await expect(assigned.execute(call, "ask")).rejects.toThrow("paperclip_runner_tool_mode_denied"); expect(f.executeTool).not.toHaveBeenCalled(); const denied = new ToolGatewayHttpError(403, "Approval required", "approval_required"); f.executeTool.mockRejectedValueOnce(denied); await expect(assigned.execute(call)).rejects.toBe(denied); f.listToolsForNamedGateway.mockResolvedValue([read, descriptor("newly.granted")]); const refreshed = await assigned.execute({ tool: searchName, arguments: { query: "" } }) as { tools: Array<{ name: string }> }; expect(refreshed.tools).toHaveLength(1); expect(refreshed.tools[0]!.name).not.toBe(writeAlias); // Execution still goes through the original gateway, which reauthorizes // each call; discovery never grants an added tool to this pinned session. const revoked = new ToolGatewayHttpError(403, "Revoked", "connection_revoked"); f.executeTool.mockRejectedValueOnce(revoked); await expect(assigned.execute(call)).rejects.toBe(revoked); await expect(assigned.execute({ tool: callName, arguments: { name: "newly.granted", arguments: {} } })).rejects.toThrow("assigned_mcp_tool_unknown"); }); it("deduplicates repeated app tools in direct and on-demand catalogs while retaining revocation", async () => { const read = descriptor("memory.search"); const write = descriptor("memory.store", "write"); const f = fixture([read, structuredClone(read), write, structuredClone(write)]); const assigned = await createAssignedMcpTools(f); const direct = assigned.definitions(); expect(direct).toHaveLength(2); expect(assigned.definitions(tools => tools.length <= 2)).toEqual(direct); expect(assigned.definitions(tools => tools[0]?.name === searchName).map(tool => tool.name)).toEqual([searchName, callName]); await expect(assigned.execute({ tool: searchName, arguments: { query: "" } }, "planning")) .resolves.toEqual({ tools: [direct[0]], nextOffset: null }); await assigned.execute({ tool: callName, arguments: { name: direct[0]!.name, arguments: { query: "fixture" } } }); expect(f.executeTool).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ tool: read.name })); f.listToolsForNamedGateway.mockResolvedValue([write, structuredClone(write)]); await expect(assigned.execute({ tool: searchName, arguments: { query: "" } })) .resolves.toEqual({ tools: [direct[1]], nextOffset: null }); }); it.each([ { risk: "write" as const }, { connectionId: "another-connection" }, { parametersSchema: { type: "object", properties: { secret: { type: "string" } } } }, ])("rejects conflicting definitions with the same gateway name: %j", async change => { const tool = descriptor("memory.search"); const f = fixture([tool, { ...tool, ...change }]); await expect(createAssignedMcpTools(f)).rejects.toMatchObject({ reasonCode: "tool_name_collision" }); expect(f.executeTool).not.toHaveBeenCalled(); }); it("identifies the conflicting tool and both connection bindings without exporting descriptor metadata", async () => { const tool = { ...descriptor("calendar.search"), connectionId: "first-connection", providerMetadata: { token: "private-token" } }; const f = fixture([tool, { ...tool, connectionId: "second-connection" }]); await expect(createAssignedMcpTools(f)).rejects.toMatchObject({ reasonCode: "tool_name_collision", message: 'Conflicting tool definitions share the name "calendar.search" (connections ["first-connection","second-connection"]).' }); expect(f.executeTool).not.toHaveBeenCalled(); }); it("keeps same-action tools from distinct connections separately callable", async () => { const f = fixture([descriptor("mcp.memory-first:search"), descriptor("mcp.memory-second:search")]); const assigned = await createAssignedMcpTools(f); const direct = assigned.definitions(); expect(new Set(direct.map(tool => tool.name)).size).toBe(2); for (const tool of direct) await assigned.execute({ tool: tool.name as string, arguments: {} }); expect(f.executeTool.mock.calls.map(([call]) => call.tool)).toEqual(["mcp.memory-first:search", "mcp.memory-second:search"]); }); it("pages through an oversized catalog and calls every tool through the original gateway", async () => { const f = fixture(Array.from({ length: 224 }, (_, i) => descriptor(`app.action_${i}`))); const assigned = await createAssignedMcpTools(f); const direct = assigned.definitions(); const compact = assigned.definitions(tools => tools.length <= 200); expect(compact.map(tool => tool.name)).toEqual([searchName, callName]); expect(assigned.definitions(tools => tools.length <= 224)).toEqual(direct); expect(() => assigned.definitions(() => false)).toThrow("assigned_mcp_tool_catalog_capacity_exceeded"); const seen: string[] = []; let offset: number | null = 0; do { const page = await assigned.execute({ tool: searchName, arguments: { query: "", offset, limit: 20 } }) as { tools: Array<{ name: string; inputSchema: unknown }>; nextOffset: number | null; }; expect(page.tools.length).toBeLessThanOrEqual(20); for (const tool of page.tools) { seen.push(tool.name); expect(tool.inputSchema).toEqual(descriptor("any").parametersSchema); await assigned.execute({ tool: callName, arguments: { name: tool.name, arguments: { query: "fixture" } } }); } offset = page.nextOffset; } while (offset !== null); expect(seen).toEqual(direct.map(tool => tool.name).sort()); expect(f.executeTool).toHaveBeenCalledTimes(224); expect(new Set(f.executeTool.mock.calls.map(([call]) => call.tool)).size).toBe(224); for (const [call] of f.executeTool.mock.calls) { expect(call).toMatchObject({ gatewayPublicId: f.gatewayPublicId, sessionToken: f.bearerToken, parameters: { query: "fixture" } }); expect(call).not.toHaveProperty("approvedActionRequestId"); } }); it("searches only pinned tools still granted by fresh discovery without projecting metadata", async () => { const f = fixture([descriptor("calendar.search"), descriptor("mail.search"), descriptor("calendar.remove", "write")]); const assigned = await createAssignedMcpTools(f); f.listToolsForNamedGateway.mockResolvedValue([ { ...descriptor("calendar.search"), providerMetadata: { token: "secret-provider-token" } }, descriptor("calendar.remove", "write"), descriptor("calendar.new_grant"), ]); const result = await assigned.execute({ tool: searchName, arguments: { query: "calendar" } }, "planning"); expect(result).toEqual({ tools: [assigned.definitions()[0]], nextOffset: null }); expect(JSON.stringify(result)).not.toMatch(/private-|secret-provider|gateway-fixture|new_grant/); f.listToolsForNamedGateway.mockRejectedValue(new Error("gateway_token_revoked")); await expect(assigned.execute({ tool: searchName, arguments: { query: "" } })).rejects.toThrow("gateway_token_revoked"); }); it("keeps pagination stable when an earlier tool is revoked between pages", async () => { const descriptors = ["alpha", "bravo", "charlie", "delta"].map(name => descriptor(name)); const f = fixture(descriptors); const assigned = await createAssignedMcpTools(f); const definitions = assigned.definitions(); const first = await assigned.execute({ tool: searchName, arguments: { query: "", offset: 0, limit: 2 }, }) as { tools: unknown[]; nextOffset: number }; expect(first).toEqual({ tools: definitions.slice(0, 2), nextOffset: 2 }); f.listToolsForNamedGateway.mockResolvedValue(descriptors.slice(1)); await expect(assigned.execute({ tool: searchName, arguments: { query: "", offset: first.nextOffset, limit: 2 }, })).resolves.toEqual({ tools: definitions.slice(2), nextOffset: null }); f.listToolsForNamedGateway.mockResolvedValue([descriptors[1]!, descriptors[3]!]); await expect(assigned.execute({ tool: searchName, arguments: { query: "", offset: first.nextOffset, limit: 2 }, })).resolves.toEqual({ tools: definitions.slice(3), nextOffset: null }); }); it.each(["planning", "ask"] as const)("preserves pinned and fresh %s restrictions through the call wrapper", async mode => { const f = fixture([descriptor("read"), descriptor("write", "write")]); const assigned = await createAssignedMcpTools(f); const restricted = await createAssignedMcpTools({ ...f, workMode: mode }); const call = { tool: callName, arguments: { name: assigned.definitions()[1]!.name, arguments: {} } }; await expect(assigned.execute(call, mode)).rejects.toThrow("paperclip_runner_tool_mode_denied"); await expect(restricted.execute(call, "standard")).rejects.toThrow("paperclip_runner_tool_mode_denied"); expect(f.executeTool).not.toHaveBeenCalled(); const discovery = await restricted.execute({ tool: searchName, arguments: { query: "" } }, "standard"); expect(discovery).toEqual({ tools: [assigned.definitions()[0]], nextOffset: null }); }); it.each(["approval_required", "connection_revoked", "tool_error"])("preserves %s through the call wrapper", async reason => { const f = fixture([descriptor("write", "write")]); const assigned = await createAssignedMcpTools(f); const error = new ToolGatewayHttpError(403, "Denied", reason); f.executeTool.mockRejectedValue(error); await expect(assigned.execute({ tool: callName, arguments: { name: assigned.definitions()[0]!.name, arguments: {} } })).rejects.toBe(error); }); it("bounds search pages by bytes and rejects invalid wrapper arguments and unassigned targets", async () => { const f = fixture(Array.from({ length: 4 }, (_, i) => ({ ...descriptor(`large_${i}`), parametersSchema: { type: "object", description: "x".repeat(250 * 1024) }, }))); const assigned = await createAssignedMcpTools(f); const page = await assigned.execute({ tool: searchName, arguments: { query: "", limit: 20 } }) as { tools: unknown[]; nextOffset: number }; expect(page.tools).toHaveLength(2); expect(page.nextOffset).toBe(2); for (const args of [null, [], { query: "x".repeat(201) }, { query: "", offset: -1 }, { query: "", limit: 21 }, { query: "", offset: 0.5 }]) { await expect(assigned.execute({ tool: searchName, arguments: args })).rejects.toThrow("assigned_mcp_tool_invalid_arguments"); } for (const name of ["unassigned", searchName, callName]) { await expect(assigned.execute({ tool: callName, arguments: { name, arguments: {} } })).rejects.toThrow("assigned_mcp_tool_unknown"); } await expect(assigned.execute({ tool: callName, arguments: { name: "unassigned", arguments: [] } })).rejects.toThrow("assigned_mcp_tool_invalid_arguments"); expect(f.executeTool).not.toHaveBeenCalled(); }); it("keeps individually oversized schemas and later tools discoverable with bounded schema chunks", async () => { const schema = { type: "object", description: "\u0000🙂".repeat(150_000), properties: {} }; const f = fixture([{ ...descriptor("a_large"), parametersSchema: schema }, descriptor("z_small")]); const assigned = await createAssignedMcpTools(f); const page = await assigned.execute({ tool: searchName, arguments: { query: "", limit: 1 } }) as { tools: Array>; nextOffset: number; }; const large = page.tools[0]!.name as string; expect(page.tools).toEqual([{ name: large, description: "a_large: Use a_large", inputSchemaRef: large }]); expect(page.nextOffset).toBe(1); const rest = await assigned.execute({ tool: searchName, arguments: { query: "", offset: page.nextOffset } }) as { tools: Array>; nextOffset: number | null; }; expect(rest.tools.map(tool => tool.description)).toEqual(["z_small: Use z_small"]); expect(rest.nextOffset).toBeNull(); let schemaOffset: number | null = 0; let serialized = ""; do { const chunk = await assigned.execute({ tool: searchName, arguments: { query: "", schemaTool: large, schemaOffset } }) as { schemaJson: string; nextSchemaOffset: number | null; }; expect(Buffer.byteLength(JSON.stringify(chunk))).toBeLessThan(640 * 1024); serialized += chunk.schemaJson; schemaOffset = chunk.nextSchemaOffset; } while (schemaOffset !== null); expect(JSON.parse(serialized)).toEqual(schema); await assigned.execute({ tool: callName, arguments: { name: large, arguments: {} } }); expect(f.executeTool).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ tool: "a_large" })); f.listToolsForNamedGateway.mockResolvedValue([descriptor("z_small")]); await expect(assigned.execute({ tool: searchName, arguments: { query: "", schemaTool: large } })).rejects.toThrow("assigned_mcp_tool_unknown"); await expect(assigned.execute({ tool: searchName, arguments: { query: "", schemaOffset: 1 } })).rejects.toThrow("assigned_mcp_tool_invalid_arguments"); }); it("requires a configured gateway registered for the exact database instance", () => { const firstDb = {} as Db; const secondDb = {} as Db; const first = fixture([]).gateway; const second = fixture([]).gateway; expect(() => getAssignedMcpGateway(firstDb)).toThrow("assigned_mcp_gateway_unavailable"); registerAssignedMcpGateway(firstDb, first); expect(getAssignedMcpGateway(firstDb)).toBe(first); expect(() => getAssignedMcpGateway(secondDb)).toThrow("assigned_mcp_gateway_unavailable"); registerAssignedMcpGateway(secondDb, second); expect(getAssignedMcpGateway(secondDb)).toBe(second); expect(getAssignedMcpGateway(firstDb)).toBe(first); registerAssignedMcpGateway(firstDb, second); expect(getAssignedMcpGateway(firstDb)).toBe(second); }); it("never compiles an app schema over the Runner byte limit and serves that tool only through search", async () => { const large = sizedSchema(600 * 1024), small = sizedSchema(200); const f = fixture([{ ...descriptor("deploy:large"), parametersSchema: large }, { ...descriptor("deploy:small"), parametersSchema: small }]); vi.mocked(admitToolInputSchema).mockClear(); const assigned = await createAssignedMcpTools(f); expect(assigned.definitions().map(tool => tool.name)).toEqual(["paperclip_search_assigned_tools", "paperclip_call_assigned_tool"]); expect(compiledDescriptions()).toEqual([String(small.description).slice(0, 36)]); const page = await assigned.execute({ tool: searchName, arguments: { query: "deploy", limit: 20 } }) as { tools: Array> }; expect(page.tools.map(tool => tool.description)).toEqual(["deploy:large: Use deploy:large", "deploy:small: Use deploy:small"]); }); it("stops compiling at the listing budget, keeps earlier tools offered, and serves the rest only through search", async () => { const schemas = [300, 300, 300, 1].map(kib => sizedSchema(kib * 1024)); const listing = schemas.map((schema, index) => ({ ...descriptor(`deploy:tool_${index}`), parametersSchema: schema })); expect(schemas.slice(0, 2).reduce((total, schema) => total + Buffer.byteLength(JSON.stringify(schema)), 0)).toBeLessThanOrEqual(ASSIGNED_SCHEMA_LISTING_BUDGET_BYTES); expect(schemas.slice(0, 3).reduce((total, schema) => total + Buffer.byteLength(JSON.stringify(schema)), 0)).toBeGreaterThan(ASSIGNED_SCHEMA_LISTING_BUDGET_BYTES); for (const attempt of [1, 2]) { const f = fixture(listing); vi.mocked(admitToolInputSchema).mockClear(); const assigned = await createAssignedMcpTools(f); expect(compiledDescriptions()).toEqual(attempt === 1 ? schemas.slice(0, 2).map(schema => String(schema.description).slice(0, 36)) : []); expect(assigned.definitions().map(tool => tool.name)).toEqual(["paperclip_search_assigned_tools", "paperclip_call_assigned_tool"]); const found: Array> = []; for (let offset: number | null = 0; offset !== null;) { const page = await assigned.execute({ tool: searchName, arguments: { query: "deploy", offset, limit: 20 } }) as { tools: Array>; nextOffset: number | null; }; found.push(...page.tools); offset = page.nextOffset; } expect(found.map(tool => tool.description)).toEqual(listing.map(tool => `${tool.name}: Use ${tool.name}`)); for (const tool of found) await assigned.execute({ tool: callName, arguments: { name: tool.name, arguments: { name: "site" } } }); expect(f.executeTool.mock.calls.map(([call]) => call.tool)).toEqual(listing.map(tool => tool.name)); } }); it("compiles a new schema one time when several runs start together", async () => { const listing = [{ ...descriptor("deploy:shared"), parametersSchema: sizedSchema(400) }]; vi.mocked(admitToolInputSchema).mockClear(); const assigned = await Promise.all([1, 2, 3, 4].map(() => createAssignedMcpTools(fixture(listing)))); expect(admitToolInputSchema).toHaveBeenCalledTimes(1); for (const tools of assigned) expect(tools.definitions().map(tool => tool.description)).toEqual(["deploy:shared: Use deploy:shared"]); }); it("does not compile an unchanged schema again and keeps the outcome cache bounded", async () => { const listing = Array.from({ length: ASSIGNED_SCHEMA_ADMISSION_CACHE_ENTRIES + 10 }, (_, index) => ({ ...descriptor(`bulk:tool_${index}`), parametersSchema: sizedSchema(120) })); vi.mocked(admitToolInputSchema).mockClear(); await createAssignedMcpTools(fixture(listing.slice(-5))); await createAssignedMcpTools(fixture(listing.slice(-5))); expect(admitToolInputSchema).toHaveBeenCalledTimes(5); await createAssignedMcpTools(fixture(listing)); expect(assignedSchemaAdmissionCacheSize()).toBe(ASSIGNED_SCHEMA_ADMISSION_CACHE_ENTRIES); }, 30_000); it.each([undefined, "on_demand"] as const)("offers and executes every app schema the Runner validates and withholds the rest (%s)", async delivery => { const shared = JSON.parse(readFileSync(new URL("../../../../packages/paperclip-runner/test/fixtures/tool-input-schema-fixtures.json", import.meta.url), "utf8")) as { cases: Array<{ name: string; accepted: boolean; dialectUri?: string; schema: Record; valid?: Record[] }>; }; const descriptors = shared.cases.map(entry => ({ ...descriptor(`deploy:${entry.name}`), parametersSchema: entry.schema }) as ToolGatewayDescriptor); const f = fixture(descriptors); const assigned = await createAssignedMcpTools({ ...f, ...(delivery ? { delivery } : {}) }); const offered = delivery ? (await assigned.execute({ tool: searchName, arguments: { query: "", limit: 20 } }) as { tools: Array> }).tools : assigned.definitions(); expect(offered.map(tool => tool.description)).toEqual(expect.arrayContaining( shared.cases.filter(entry => entry.accepted).map(entry => expect.stringContaining(entry.name)))); expect(offered).toHaveLength(shared.cases.filter(entry => entry.accepted).length); for (const entry of shared.cases) { const tool = offered.find(candidate => String(candidate.description).endsWith(`deploy:${entry.name}`)); if (!entry.accepted) { expect(tool).toBeUndefined(); continue; } expect((tool!.inputSchema as Record).$schema).toBe(entry.dialectUri); const args = entry.valid![0]!; await assigned.execute(delivery ? { tool: callName, arguments: { name: tool!.name, arguments: args } } : { tool: String(tool!.name), arguments: args }); expect(f.executeTool).toHaveBeenLastCalledWith(expect.objectContaining({ tool: `deploy:${entry.name}`, parameters: args })); } expect(f.executeTool).toHaveBeenCalledTimes(shared.cases.filter(entry => entry.accepted).length); }); it("projects only authorized gateway tools with stable bounded collision-resistant names", async () => { const names = ["memory.search", "memory-search", "x".repeat(120), "🧠"]; const f = fixture(names.map(name => descriptor(name))); const first = await createAssignedMcpTools(f); const reversed = await createAssignedMcpTools({ ...f, gateway: fixture([...names].reverse().map(name => descriptor(name))).gateway }); const projected = first.definitions().map(tool => tool.name as string); expect(new Set(projected).size).toBe(names.length); for (const name of projected) { expect(name).toMatch(/^app_[a-zA-Z0-9_]+_[a-f0-9]{12}$/); expect(name.length).toBeLessThanOrEqual(64); expect(first.has(name)).toBe(true); } expect(reversed.definitions().map(tool => tool.name)).toEqual([...projected].reverse()); expect(f.listToolsForNamedGateway).toHaveBeenCalledWith({ gatewayPublicId: f.gatewayPublicId, bearerToken: f.bearerToken }); }); it("keeps the provider and action readable for fully namespaced gateway tools", async () => { const prefix = "mcp.app-gallery-mem0-60062edb-c211-4aae-a787-b4fa12a5ea24-f4ece062"; const tools = ["add-memory", "search-memories", "delete-memory"].map(action => ({ ...descriptor(`${prefix}:${action}`), displayName: `Mem0 ${action}`, })); const assigned = await createAssignedMcpTools(fixture(tools)); for (const [index, definition] of assigned.definitions().entries()) { const name = definition.name as string; expect(name).toContain("mem0"); expect(name).toContain(tools[index]!.name.split(":").at(-1)!.replaceAll("-", "_")); expect(name.length).toBeLessThanOrEqual(64); expect(definition.description).toBe(`${tools[index]!.displayName}: ${tools[index]!.description}`); } const long = await createAssignedMcpTools(fixture([descriptor(`${prefix}:${"long-action-".repeat(10)}`)])); expect((long.definitions()[0]!.name as string).length).toBeLessThanOrEqual(64); }); it("does not project gateway secrets, URLs, or provider metadata and returns only the tool result", async () => { const tool = { ...descriptor("recall"), providerMetadata: { token: "private-provider-token", url: "https://private-gateway.example" } }; const f = fixture([tool]); f.executeTool.mockResolvedValue({ status: "completed", invocationId: "internal", result: { memories: [] } }); const assigned = await createAssignedMcpTools(f); const definitions = assigned.definitions(); expect(Object.keys(definitions[0]!)).toEqual(["name", "description", "inputSchema"]); expect(JSON.stringify(definitions)).not.toMatch(/private-|gateway-fixture|https:/); const args = { query: "synthetic memory" }; expect(await assigned.execute({ tool: definitions[0]!.name as string, arguments: args })).toEqual({ memories: [] }); expect(f.executeTool).toHaveBeenCalledExactlyOnceWith({ gatewayPublicId: f.gatewayPublicId, sessionToken: f.bearerToken, tool: "recall", parameters: args }); expect(() => { (definitions[0]!.inputSchema as Record).type = "string"; }).toThrow(TypeError); expect(assigned.definitions()[0]!.inputSchema).toEqual(tool.parametersSchema); }); it("rejects unknown names without invoking the gateway", async () => { const f = fixture([descriptor("recall")]); const assigned = await createAssignedMcpTools(f); expect(assigned.has("unassigned")).toBe(false); await expect(assigned.execute({ tool: "unassigned", arguments: {} })).rejects.toThrow("assigned_mcp_tool_unknown"); expect(f.executeTool).not.toHaveBeenCalled(); }); it.each(["planning", "ask", "skill_test"] as const)("exposes and permits only read tools in %s mode", async workMode => { const f = fixture([descriptor("read"), descriptor("remember", "write"), descriptor("forget", "destructive")]); const standard = await createAssignedMcpTools(f); const restricted = await createAssignedMcpTools({ ...f, workMode }); expect(restricted.definitions()).toEqual([standard.definitions()[0]]); for (const tool of standard.definitions().slice(1)) { await expect(restricted.execute({ tool: tool.name as string, arguments: {} })).rejects.toThrow("paperclip_runner_tool_mode_denied"); } expect(f.executeTool).not.toHaveBeenCalled(); await restricted.execute({ tool: restricted.definitions()[0]!.name as string, arguments: {} }); expect(f.executeTool).toHaveBeenCalledOnce(); }); it("uses the gateway for write and destructive tools under standard mode without approval overrides", async () => { const f = fixture([descriptor("remember", "write"), descriptor("forget", "destructive")]); const assigned = await createAssignedMcpTools(f); for (const tool of assigned.definitions()) await assigned.execute({ tool: tool.name as string, arguments: {} }); expect(f.executeTool).toHaveBeenCalledTimes(2); for (const [call] of f.executeTool.mock.calls) expect(call).not.toHaveProperty("approvedActionRequestId"); }); it.each(["planning", "ask", "skill_test"] as const)("enforces fresh %s mode without relaxing the pinned mode", async currentMode => { const f = fixture([descriptor("read"), descriptor("remember", "write")]); const standard = await createAssignedMcpTools(f); const restricted = await createAssignedMcpTools({ ...f, workMode: currentMode }); const write = { tool: standard.definitions()[1]!.name as string, arguments: {} }; await expect(standard.execute(write, currentMode)).rejects.toThrow("paperclip_runner_tool_mode_denied"); await expect(restricted.execute(write, "standard")).rejects.toThrow("paperclip_runner_tool_mode_denied"); expect(f.executeTool).not.toHaveBeenCalled(); await standard.execute({ tool: standard.definitions()[0]!.name as string, arguments: {} }, currentMode); expect(f.executeTool).toHaveBeenCalledOnce(); }); it.each(["tool_error", "approval_required", "connection_revoked"])("propagates %s without converting it to success", async reason => { const f = fixture([descriptor("recall")]); const error = new ToolGatewayHttpError(403, "Gateway refused execution", reason); f.executeTool.mockRejectedValue(error); const assigned = await createAssignedMcpTools(f); await expect(assigned.execute({ tool: assigned.definitions()[0]!.name as string, arguments: {} })).rejects.toBe(error); }); it("propagates discovery denial", async () => { const f = fixture([]); const error = new Error("gateway_token_revoked"); f.listToolsForNamedGateway.mockRejectedValue(error); await expect(createAssignedMcpTools(f)).rejects.toBe(error); }); it("rejects error payloads and incomplete outcomes, and accepts successful replay", async () => { const f = fixture([descriptor("recall")]); const assigned = await createAssignedMcpTools(f); const call = { tool: assigned.definitions()[0]!.name as string, arguments: {} }; f.executeTool.mockResolvedValueOnce({ status: "completed", result: { isError: true, content: [] } }); await expect(assigned.execute(call)).rejects.toMatchObject({ reasonCode: "tool_error" }); f.executeTool.mockResolvedValueOnce({ status: "pending", result: {} }); await expect(assigned.execute(call)).rejects.toThrow("assigned_mcp_tool_execution_incomplete"); f.executeTool.mockResolvedValueOnce({ status: "replayed", result: { memory: "synthetic" } }); await expect(assigned.execute(call)).resolves.toEqual({ memory: "synthetic" }); }); }); describe("shared assigned tool catalogs", () => { const searchName = "paperclip_search_assigned_tools"; function catalog(prefix: string, count: number, schemaBytes = 400): ToolGatewayDescriptor[] { return Array.from({ length: count }, (_, index) => { const properties: Record = {}; for (let field = 0; JSON.stringify(properties).length < schemaBytes; field += 1) { properties[`field_${field}`] = { type: "string", description: `${prefix} field ${field} of tool ${index}` }; } return { ...descriptor(`${prefix}:tool_${index}`), parametersSchema: { type: "object", properties, required: ["field_0"] } }; }); } function session(listing: () => ToolGatewayDescriptor[], companyId?: string, workMode?: "standard" | "ask") { const gateway = { listToolsForNamedGateway: async () => listing() } as unknown as ToolGatewayService; return createAssignedMcpTools({ gateway, gatewayPublicId: "gateway-fixture", bearerToken: "token", ...(companyId ? { companyId } : {}), ...(workMode ? { workMode } : {}) }); } function schemas(tools: Awaited>) { return tools.definitions().map(definition => definition.inputSchema); } function collectGarbage(): () => void { setFlagsFromString("--expose-gc"); return runInNewContext("gc") as () => void; } it("keeps one catalog in memory for many sessions of the same company and admitted tools", async () => { const gc = collectGarbage(); const company = `company-${randomUUID()}`; const listing = () => catalog(`heap-${company}`, 60, 4096); const heap = () => { gc(); gc(); return process.memoryUsage().heapUsed; }; await session(() => catalog("heap-warm-up", 60, 4096), `company-${randomUUID()}`); const before = heap(); const held = [await session(listing, company)]; const one = heap() - before; for (let index = 1; index < 20; index += 1) held.push(await session(listing, company)); const nineteenMore = heap() - before - one; expect(one).toBeGreaterThan(0); expect(nineteenMore).toBeLessThan(one * 2); const first = schemas(held[0]!); for (const tools of held) schemas(tools).forEach((schema, index) => expect(schema).toBe(first[index])); }, 30_000); it("shares deeply frozen schemas between sessions, including sessions that start together", async () => { const company = `company-${randomUUID()}`; const listing = () => catalog("together", 3); const sessions = await Promise.all([1, 2, 3, 4].map(() => session(listing, company))); const first = schemas(sessions[0]!); for (const tools of sessions) schemas(tools).forEach((schema, index) => expect(schema).toBe(first[index])); for (const definition of sessions[0]!.definitions()) { expect(Object.isFrozen(definition)).toBe(true); expect(Object.isFrozen((definition.inputSchema as { properties: object }).properties)).toBe(true); } }); it("never shares a catalog between companies or without a company", async () => { const listing = () => catalog("identical", 3); const a = await session(listing, `company-a-${randomUUID()}`); const b = await session(listing, `company-b-${randomUUID()}`); const unscoped = await session(listing); expect(a.definitions()).toEqual(b.definitions()); schemas(b).forEach((schema, index) => expect(schema).not.toBe(schemas(a)[index])); schemas(unscoped).forEach((schema, index) => expect(schema).not.toBe(schemas(a)[index])); }); it("never shares between sessions that were admitted different tools, schemas, descriptions, or risks", async () => { const company = `company-${randomUUID()}`; const full = await session(() => catalog("differs", 3), company); const fewer = await session(() => catalog("differs", 3).slice(1), company); const edited = await session(() => catalog("differs", 3).map((tool, index) => index === 0 ? { ...tool, parametersSchema: { ...tool.parametersSchema, required: ["field_1"] } } : tool), company); const described = await session(() => catalog("differs", 3).map(tool => ({ ...tool, description: `${tool.description} now` })), company); const riskier = await session(() => catalog("differs", 3).map(tool => ({ ...tool, risk: "write" as const })), company, "ask"); const fullSchemas = schemas(full); expect(fewer.definitions()).toHaveLength(2); expect(full.has(String(full.definitions()[0]!.name))).toBe(true); expect(fewer.has(String(full.definitions()[0]!.name))).toBe(false); for (const schema of schemas(fewer)) expect(fullSchemas).not.toContain(schema); expect((edited.definitions()[0]!.inputSchema as { required: string[] }).required).toEqual(["field_1"]); expect((full.definitions()[0]!.inputSchema as { required: string[] }).required).toEqual(["field_0"]); for (const schema of schemas(edited)) expect(fullSchemas).not.toContain(schema); expect(described.definitions().map(tool => tool.description)).toEqual(full.definitions().map(tool => `${tool.description} now`)); for (const schema of schemas(described)) expect(fullSchemas).not.toContain(schema); expect(riskier.definitions()).toEqual([]); expect(full.definitions()).toHaveLength(3); }); it("serves a revoked or edited tool from fresh discovery, never from a cached catalog", async () => { const company = `company-${randomUUID()}`; let current = catalog("revocable", 3); const listing = () => current.map(tool => structuredClone(tool)); const before = await session(listing, company); const revokedName = String(before.definitions()[0]!.name); current = current.slice(1); const after = await session(listing, company); expect(after.has(revokedName)).toBe(false); expect(after.definitions().map(tool => tool.name)).not.toContain(revokedName); const page = await before.execute({ tool: searchName, arguments: { query: "", limit: 20 } }) as { tools: Array<{ name: string }> }; expect(page.tools.map(tool => tool.name)).not.toContain(revokedName); current = current.map(tool => ({ ...tool, parametersSchema: { type: "object", properties: { replaced: { type: "boolean" } } } })); const edited = await session(listing, company); for (const definition of edited.definitions()) expect(definition.inputSchema).toEqual({ type: "object", properties: { replaced: { type: "boolean" } } }); }); it("keeps one session's mutation attempts invisible to every other session", async () => { const company = `company-${randomUUID()}`; const source = catalog("mutation", 2); const listing = () => source; const first = await session(listing, company); const second = await session(listing, company); const snapshot = structuredClone(second.definitions()); const [definition] = first.definitions() as Array<{ description: string; inputSchema: { properties: Record; required: string[] } }>; expect(() => { definition!.description = "changed"; }).toThrow(TypeError); expect(() => { definition!.inputSchema.properties.injected = { type: "string" }; }).toThrow(TypeError); expect(() => { definition!.inputSchema.required.push("injected"); }).toThrow(TypeError); expect(() => { delete definition!.inputSchema.properties.field_0; }).toThrow(TypeError); first.definitions().length = 0; (source[0]!.parametersSchema as { properties: Record }).properties.injected = { type: "string" }; source[0]!.description = "changed at the source"; const page = await first.execute({ tool: searchName, arguments: { query: "", limit: 20 } }) as { tools: Array<{ inputSchema: { properties: Record } }> }; page.tools[0]!.inputSchema.properties.injected = { type: "string" }; expect(second.definitions()).toEqual(snapshot); expect(first.definitions()).toEqual(snapshot); }); it("releases the hold of a session that is dropped without close, such as a failed or cancelled start", async () => { const gc = collectGarbage(); const company = `company-${randomUUID()}`; const listing = () => catalog("dropped", 2); const kept = await session(listing, company); schemas(await session(listing, company)).forEach((schema, index) => expect(schema).toBe(schemas(kept)[index])); for (let attempt = 0; attempt < 50; attempt += 1) { await new Promise(resolve => setTimeout(resolve, 10)); gc(); } kept.close(); const fresh = await session(listing, company); schemas(fresh).forEach((schema, index) => expect(schema).not.toBe(schemas(kept)[index])); }, 30_000); it("releases a shared catalog when its last session closes and bounds the number of shared catalogs", async () => { const company = `company-${randomUUID()}`; const start = assignedCatalogCacheStats(); const listing = () => catalog("released", 2); const first = await session(listing, company); const second = await session(listing, company); expect(assignedCatalogCacheStats().entries).toBe(start.entries + 1); expect(assignedCatalogCacheStats().bytes).toBeGreaterThan(start.bytes); first.close(); first.close(); expect(assignedCatalogCacheStats().entries).toBe(start.entries + 1); second.close(); expect(assignedCatalogCacheStats()).toEqual(start); expect(second.definitions()).toHaveLength(2); const third = await session(listing, company); schemas(third).forEach((schema, index) => expect(schema).not.toBe(schemas(first)[index])); third.close(); const held = []; for (let index = 0; index < ASSIGNED_CATALOG_CACHE_ENTRIES + 5; index += 1) { held.push(await session(() => catalog("bounded", 1), `company-bounded-${index}-${randomUUID()}`)); } expect(assignedCatalogCacheStats().entries).toBeLessThanOrEqual(ASSIGNED_CATALOG_CACHE_ENTRIES); expect(assignedCatalogCacheStats().bytes).toBeLessThanOrEqual(ASSIGNED_CATALOG_CACHE_BYTES); for (const tools of held) tools.close(); expect(assignedCatalogCacheStats()).toEqual({ entries: 0, bytes: 0 }); }, 30_000); });