Files
PaperClipAI/server/src/services/native-runtime/assigned-mcp-tools.test.ts
T
DottaandClaude Opus 5.5 11f4a76743 perf(native-runtime): share one frozen assigned tool catalog across sessions (#21482)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - One server process controls every native agent session. Each session
gets the app tools (MCP tools) that are assigned to its agent.
> - Each live or warm session kept two private copies of its assigned
tool catalog: the gateway descriptors and a canonical copy of every
input schema.
> - With 400 tools of about 5.7 KB each, that was about 7.6 MB of heap
for each session. With 800 tools, it was about 15 MB. Warm sessions stay
for 5 minutes after the last turn, so idle agents also hold this memory.
> - At 1,000 concurrent agents, this is 7 to 15 GB of heap, and the
server cannot get there.
> - This pull request keeps one deeply frozen catalog for all sessions
of the same company that get the same admitted tools and schemas.
> - The benefit is that each additional session on the same catalog adds
about 40 to 80 KB of heap instead of 7.6 to 15 MB, and session start is
faster.

## Linked Issues or Issue Description

Refs #21415 (releases a finished session's tool authority). Refs #21440
(adds the catalog memory benchmark that this change extends).

**What existing behavior does this improve?**
`createAssignedMcpTools` in
`server/src/services/native-runtime/assigned-mcp-tools.ts`. Each call
kept every gateway descriptor (with its provider metadata) and a
separate canonical clone of each input schema. Each `definitions()` call
also made a new `structuredClone` of every schema.

**Subsystem affected**
Native runtime: assigned app tools (MCP) for native agent sessions.

**Current behavior**
Retained heap grows by one full catalog for each session. Measured with
the real `createAssignedMcpTools` (5.7 KB schemas): 400 tools is 7.58 MB
per session, and 800 tools is 15.1 MB per session, for 1, 10, and 100
sessions. Each `definitions()` call takes 14 to 41 ms because it clones
every schema.

**Proposed behavior**
Sessions of the same company that get identical admitted tools share one
frozen catalog. The total for 100 sessions is about one catalog: 4.2 MB
at 400 tools and 8.1 MB at 800 tools. `definitions()` takes 0.01 ms.

**Reason and benefit**
The server must hold 1,000 concurrent agents in one process. The catalog
was the largest per-session heap cost. Revocation and authorization do
not change: every call is still authorized again by the gateway, and
every new session still reads a fresh listing.

**Breaking changes**
None in the API or data. The direct definitions that `definitions()`
returns are now frozen. A consumer that writes to a returned definition
or schema gets a `TypeError` and does not change other sessions. No
production consumer writes to them (see Risks).

## What Changed

- `server/src/services/native-runtime/assigned-mcp-tools.ts`:
- A session keeps only a small frozen record for each tool (gateway
name, display name, description, risk), plus the frozen schema and the
frozen definition. It does not keep the gateway descriptors.
- New per-process index of shared catalogs. The key is the SHA-256 of an
identity string: `[companyId, [[assignedName, gatewayName, displayName,
description, risk, sha256(JSON of the input schema)] for each listed
tool, in listing order]]`. On a hit, the code also compares the full
identity string, so a hash collision cannot give a wrong catalog.
- The identity is computed from the fresh listing that the gateway
returns for this session. The gateway applies all per-agent, per-run,
per-profile, and policy filtering, and the approval description suffix,
before it returns the listing. Thus two sessions share only if they were
given exactly the same tools, names, descriptions, risks, and schemas in
the same company. Without `companyId`, nothing is shared.
- Schemas, definitions, tool records, and the definition arrays are
deeply frozen. Search results still return cloned copies.
- Sessions that start at the same time with the same catalog wait for
one build and share it.
- The index holds each catalog through a `WeakRef`, so it never keeps a
catalog alive. The index has at most 512 entries and 256 MiB (accounted
schema and description bytes). The oldest entries are removed first. A
catalog that is larger than the byte limit is not indexed.
- New `close()` on the assigned tools. When the last session that holds
a catalog closes, the index entry is removed. A `FinalizationRegistry`
also removes entries whose catalog was collected.
- `definitions()` returns the shared frozen definitions for the
session's work mode. It no longer clones every schema on each call.
-
`server/src/services/native-runtime/paperclip-runner-tool-authority.ts`:
`close()` also closes the assigned tools. The session executor already
closes the authority when it revokes a session's tool authority.
- `server/src/services/native-runtime/native-session-executor.ts`: one
line. It passes the run binding's `companyId` to
`createAssignedMcpTools`.
- `server/scripts/benchmark-assigned-mcp-tools-memory.ts`: passes
`companyId`, adds `--companies`, measures session start and
`definitions()` time, and returns fresh copies of fixed rows (like
database reads).
- Tests in `assigned-mcp-tools.test.ts` and
`paperclip-runner-tool-authority.test.ts`.

## Verification

Red/green tests in
`server/src/services/native-runtime/assigned-mcp-tools.test.ts` ("shared
assigned tool catalogs"):

- Retained heap: 20 sessions of one company on a 60-tool, 4 KB-schema
catalog. The heap for the other 19 sessions must be less than two
catalogs. Red on master: `expected 14025976 to be less than 3788112`.
Green with this change.
- Shared deeply frozen schemas, also for sessions that start together.
Red on master (`Object.is` equality fails).
- Mutation isolation: writes to a returned definition, schema property,
and `required` array, and a delete, throw `TypeError`. Changes to the
gateway's source rows and to a search result do not change any session.
Red on master (no throw).
- Release and bounds: the entry stays while one session holds it and
goes when the last session closes. `close()` is idempotent. A new
session after release builds a new catalog. 517 companies keep the index
at 512 entries or fewer. Red on master (no `close` or stats).
- Guard tests: two companies with identical catalogs do not share.
Sessions without a company do not share. Fewer tools, an edited schema,
an edited description, or a different risk do not share. A revoked or
edited tool is served from fresh discovery. On master these pass,
because master never shares. To prove they test the key, I removed
`companyId` and the schema digest from the identity: three guard tests
failed, and they pass with the full key.
- An existing test changed: "does not project gateway secrets..." now
expects a write to a returned schema to throw `TypeError` (before, the
write changed only a private clone). The isolation check after the write
is the same.
- `paperclip-runner-tool-authority.test.ts`: `authority.close()` closes
the assigned tools.

Heap (post-GC `heapUsed` delta, `node --expose-gc`, 5.7 KB schemas, one
company). Command: `cd server && node --expose-gc --import tsx
scripts/benchmark-assigned-mcp-tools-memory.ts --tools <N>
--schema-bytes 5700 --sessions <S> --turns 5`.

| Tools | Sessions | Total before | Per session before | Total after |
Per session after |
| --- | --- | --- | --- | --- | --- |
| 400 | 1 | 7.60 MB | 7.60 MB | 3.96 MB | 3.96 MB |
| 400 | 10 | 75.9 MB | 7.59 MB | 4.04 MB | 0.40 MB |
| 400 | 100 | 757.9 MB | 7.58 MB | 4.18 MB | 0.042 MB |
| 800 | 1 | 15.2 MB | 15.2 MB | 7.91 MB | 7.91 MB |
| 800 | 10 | 151.4 MB | 15.1 MB | 7.98 MB | 0.80 MB |
| 800 | 100 | 1,513 MB | 15.1 MB | 8.13 MB | 0.081 MB |

The first session also uses about half the heap of before, because the
session no longer keeps the gateway descriptors. When all sessions are
dropped without `close()`, the catalog is collected (0 bytes held after
release).

Session start, interleaved A/B in one process (old and new
`createAssignedMcpTools` alternate, 40 starts each, median of the last
35, includes a fresh copy of the listing; the machine had a load average
of 25 to 65):

| Tools | Listing copy only | Before | After |
| --- | --- | --- | --- |
| 400 | 22.6 ms | 68.0 ms | 37.6 ms |
| 800 | 30.5 ms | 72.5 ms | 41.2 ms |

A start that reuses a catalog does no schema clone and no admission. It
still serializes and hashes each schema to compute the key. The first
start of a new catalog does the same admission work as before (the cold
first start was about 600 to 750 ms in both versions on this busy
machine).

`definitions()` median: 14 to 41 ms before, 0.01 ms after.

Other checks:

- `cd server && npx vitest run
src/services/native-runtime/assigned-mcp-tools.test.ts
src/services/native-runtime/paperclip-runner-tool-authority.test.ts
src/services/native-runtime/runner-api.integration.test.ts
src/services/native-runtime/runner-tool-results-prp.integration.test.ts
src/__tests__/deployment-connections.test.ts`: 204 passed.
- `cd server && npx vitest run
src/services/native-runtime/native-session-executor.test.ts -t
"assigned|tool authority|released|MCP"`: 31 passed.
- `cd server && npx vitest run
src/__tests__/chat-channels.integration.test.ts -t "assigned"`: 10
passed.
- `cd server && npx tsc --noEmit`: pass.
- `pnpm check:module-boundaries`: pass.
- `pnpm verify` selects a broad plan (the benchmark script is a broad
input), so CI supplies the full suite.

## Risks

- Frozen definitions: the direct definitions now go to the runner
drivers as frozen objects. I checked the consumers.
`PaperclipRunnerToolAuthority.definitions()` filters and spreads them.
The Codex, Cursor Cloud, OpenCode, ACPX, and runnerd drivers read them,
spread them, clone them (`structuredClone` in ACPX and the OpenCode MCP
bridge), or serialize them. Their types are `readonly
Readonly<Record<string, unknown>>[]`. The first-party semantic tool
definitions are already shared module constants that go through the same
path without clones. If a consumer that I did not find writes to a
definition, it gets a `TypeError` instead of a silent change. Catalogs
over 256 tools or over the listing budget use the two on-demand tools
and are not affected.
- Authorization: the shared data is only the result of a listing that
the gateway already authorized for that session, keyed on the full
content plus the company. Execution still goes through the gateway with
the session's own token on every call. Search still intersects with a
fresh listing. A new session still reads a fresh listing, so a revoked
or edited tool takes effect for new sessions and for existing sessions
at the same points as before.
- Several server processes: the index is a per-process memo of the
listing content. Each process builds its own catalog from its own
listing. Nothing is stored or shared outside the process.
- The index is bounded (512 entries, 256 MiB) and holds catalogs only
weakly. Index eviction only stops future sharing. It never frees memory
that a session uses.
- No schema change. No migration.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Claude Code agent with tool use
(shell, file edit, test runs, heap and timing benchmarks).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes (no
documented behavior or command changes)
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 14:36:30 -06:00

786 lines
48 KiB
TypeScript

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<typeof import("../../vendor/paperclip-runner/index.js")>();
return { ...actual, admitToolInputSchema: vi.fn(actual.admitToolInputSchema) };
});
function sizedSchema(bytes: number): Record<string, unknown> {
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<string, unknown>) => {
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<string, unknown>) => {
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<string, unknown>) => {
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<string, unknown>) => {
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<Record<string, unknown>>; 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<Record<string, unknown>>; 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<Record<string, unknown>> };
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<Record<string, unknown>> = [];
for (let offset: number | null = 0; offset !== null;) {
const page = await assigned.execute({ tool: searchName, arguments: { query: "deploy", offset, limit: 20 } }) as {
tools: Array<Record<string, unknown>>; 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<string, unknown>; valid?: Record<string, unknown>[] }>;
};
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<Record<string, unknown>> }).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<string, unknown>).$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<string, unknown>).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<string, unknown> = {};
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<ReturnType<typeof createAssignedMcpTools>>) {
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<string, unknown>; 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<string, unknown> }).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<string, unknown> } }> };
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);
});