From 11f4a767435a19eb756086aa992c25cdcd7558a5 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Fri, 13 Nov 2026 14:36:30 -0600 Subject: [PATCH] perf(native-runtime): share one frozen assigned tool catalog across sessions (#21482) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 --schema-bytes 5700 --sessions --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>[]`. 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 --- .../benchmark-assigned-mcp-tools-memory.ts | 59 +++-- .../native-runtime/assigned-mcp-tools.test.ts | 174 ++++++++++++++- .../native-runtime/assigned-mcp-tools.ts | 211 ++++++++++++++---- .../native-runtime/native-session-executor.ts | 1 + .../paperclip-runner-tool-authority.test.ts | 6 +- .../paperclip-runner-tool-authority.ts | 2 +- 6 files changed, 396 insertions(+), 57 deletions(-) diff --git a/server/scripts/benchmark-assigned-mcp-tools-memory.ts b/server/scripts/benchmark-assigned-mcp-tools-memory.ts index ae9694ec0bd..255632f85e4 100644 --- a/server/scripts/benchmark-assigned-mcp-tools-memory.ts +++ b/server/scripts/benchmark-assigned-mcp-tools-memory.ts @@ -1,3 +1,4 @@ +import { performance } from "node:perf_hooks"; import type { ToolGatewayDescriptor, ToolGatewayService } from "../src/services/tool-gateway.js"; import { createAssignedMcpTools } from "../src/services/native-runtime/assigned-mcp-tools.js"; @@ -11,6 +12,7 @@ const toolCount = option("--tools", 80); const schemaBytes = option("--schema-bytes", 2048); const sessions = option("--sessions", 200); const turns = option("--turns", 20); +const companies = option("--companies", 1); const gc = (globalThis as { gc?: () => void }).gc; if (!gc) throw new Error("Run with node --expose-gc"); @@ -28,10 +30,14 @@ function listing(): ToolGatewayDescriptor[] { }); } -const gateway = { listToolsForNamedGateway: async () => listing() } as unknown as ToolGatewayService; -const create = () => createAssignedMcpTools({ gateway, gatewayPublicId: "benchmark", bearerToken: "benchmark" }); +const rows = listing(); +const gateway = { listToolsForNamedGateway: async () => structuredClone(rows) } as unknown as ToolGatewayService; +const create = (companyId: string) => createAssignedMcpTools({ + gateway, gatewayPublicId: "benchmark", bearerToken: "benchmark", companyId, +}); -function heap() { +async function heap() { + await new Promise(resolve => setImmediate(resolve)); gc!(); gc!(); return process.memoryUsage().heapUsed; } @@ -40,31 +46,54 @@ function schemaIdentities(definitions: Array>) { return definitions.map(definition => definition.inputSchema); } +function median(values: number[]) { + const sorted = [...values].sort((a, b) => a - b); + return sorted[Math.floor(sorted.length / 2)]!; +} + async function measureSessions(baseline: number) { const held: Array>> = []; - for (let index = 0; index < sessions; index += 1) held.push(await create()); - const retainedBytesPerSession = Math.round((heap() - baseline) / sessions); + const startMs: number[] = []; + for (let index = 0; index < sessions; index += 1) { + const started = performance.now(); + held.push(await create(`company-${index % companies}`)); + startMs.push(performance.now() - started); + } + const retainedBytes = await heap() - baseline; + const retainedBytesPerSession = Math.round(retainedBytes / sessions); const turnResults: Array>> = []; - const beforeTurns = heap(); - for (let index = 0; index < turns; index += 1) turnResults.push(held[0]!.definitions()); - const retainedBytesPerTurn = Math.round((heap() - beforeTurns) / turns); + const beforeTurns = await heap(); + const definitionsMs: number[] = []; + for (let index = 0; index < turns; index += 1) { + const started = performance.now(); + turnResults.push(held[0]!.definitions()); + definitionsMs.push(performance.now() - started); + } + const retainedBytesPerTurn = Math.round((await heap() - beforeTurns) / turns); const first = schemaIdentities(turnResults[0]!); const schemaObjectsAfterTurns = new Set(turnResults.flatMap(schemaIdentities)).size; const sharedAcrossTurns = turnResults.every(result => schemaIdentities(result).every((schema, index) => schema === first[index])); - return { retainedBytesPerSession, retainedBytesPerTurn, schemaObjectsAfterTurns, sharedAcrossTurns }; + held.length = 0; + return { + retainedBytes, retainedBytesPerSession, retainedBytesPerTurn, schemaObjectsAfterTurns, sharedAcrossTurns, + firstSessionStartMs: Number(startMs[0]!.toFixed(2)), + medianSessionStartMs: Number(median(startMs).toFixed(2)), + medianDefinitionsMs: Number(median(definitionsMs).toFixed(2)), + }; } async function main() { - await create(); - const baseline = heap(); + await create("warm-up"); + const baseline = await heap(); const measured = await measureSessions(baseline); - const released = heap(); - console.log(JSON.stringify({ - tools: toolCount, schemaBytes, sessions, turns, + const released = await heap(); + console.log(`RESULT ${JSON.stringify({ + tools: toolCount, schemaBytes, sessions, companies, turns, + catalogJsonBytes: Buffer.byteLength(JSON.stringify(rows.map(tool => tool.parametersSchema)), "utf8"), ...measured, schemaObjectsPerTurn: measured.schemaObjectsAfterTurns / turns, bytesStillHeldAfterRelease: Math.max(0, released - baseline), - }, null, 2)); + })}`); } await main(); diff --git a/server/src/services/native-runtime/assigned-mcp-tools.test.ts b/server/src/services/native-runtime/assigned-mcp-tools.test.ts index aeb63ca7517..bf5edd6f7d8 100644 --- a/server/src/services/native-runtime/assigned-mcp-tools.test.ts +++ b/server/src/services/native-runtime/assigned-mcp-tools.test.ts @@ -1,9 +1,12 @@ 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"; @@ -539,7 +542,7 @@ describe("assigned MCP runner tools", () => { 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 }); - (definitions[0]!.inputSchema as Record).type = "string"; + expect(() => { (definitions[0]!.inputSchema as Record).type = "string"; }).toThrow(TypeError); expect(assigned.definitions()[0]!.inputSchema).toEqual(tool.parametersSchema); }); @@ -611,3 +614,172 @@ describe("assigned MCP runner tools", () => { 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); +}); diff --git a/server/src/services/native-runtime/assigned-mcp-tools.ts b/server/src/services/native-runtime/assigned-mcp-tools.ts index 2c2ae5f78fd..0f18dd7dbdf 100644 --- a/server/src/services/native-runtime/assigned-mcp-tools.ts +++ b/server/src/services/native-runtime/assigned-mcp-tools.ts @@ -47,10 +47,6 @@ function object(value: unknown): Record { return value as Record; } -function definition(name: string, tool: ToolGatewayDescriptor, inputSchema: Record): ToolDefinition { - return { name, description: `${tool.displayName}: ${tool.description}`, inputSchema: structuredClone(inputSchema) }; -} - // Execution must use the app's configured gateway, including deployment // restrictions, OAuth refresh, and approval delivery. Never fall back to an // isolated gateway whose defaults differ from the running instance. @@ -100,8 +96,7 @@ export function assignedSchemaAdmissionCacheSize(): number { return assignedSchemaOutcomes.size; } -async function admitAssignedToolSchema(serialized: string, schema: Record): Promise { - const key = createHash("sha256").update(serialized).digest("hex"); +async function admitAssignedToolSchema(key: string, schema: Record): Promise { let outcome = assignedSchemaOutcomes.get(key); if (!outcome) { await new Promise(resolve => setImmediate(resolve)); @@ -119,11 +114,155 @@ async function admitAssignedToolSchema(serialized: string, schema: Record; +type AssignedCatalogTool = Readonly<{ tool: AssignedTool; schema: Readonly>; definition: Readonly }>; +type AssignedCatalog = Readonly<{ + identity: string; + bytes: number; + tools: ReadonlyMap; + definitions: readonly Readonly[]; + readDefinitions: readonly Readonly[]; + unavailable: readonly Readonly<{ tool: string; reason: string }>[]; + unchecked: readonly string[]; +}>; +type AssignedListingEntry = { name: string; tool: AssignedTool; raw: Record; bytes: number; digest: string }; +type SharedCatalogEntry = { bytes: number; catalog: WeakRef; holders: number }; + +export const ASSIGNED_CATALOG_CACHE_ENTRIES = 512; +export const ASSIGNED_CATALOG_CACHE_BYTES = 256 * 1024 * 1024; + +const sharedCatalogs = new Map(); +const pendingCatalogs = new Map>(); +let sharedCatalogBytes = 0; +const collectedSessions = new FinalizationRegistry<() => void>(release => release()); +const collectedCatalogs = new FinalizationRegistry<{ key: string; catalog: WeakRef }>(({ key, catalog }) => { + if (sharedCatalogs.get(key)?.catalog === catalog) forgetSharedCatalog(key); +}); + +function forgetSharedCatalog(key: string): void { + const entry = sharedCatalogs.get(key); + if (!entry) return; + sharedCatalogs.delete(key); + sharedCatalogBytes -= entry.bytes; +} + +export function assignedCatalogCacheStats(): { entries: number; bytes: number } { + return { entries: sharedCatalogs.size, bytes: sharedCatalogBytes }; +} + +function deepFreeze(value: T): T { + if (value && typeof value === "object" && !Object.isFrozen(value)) { + Object.freeze(value); + for (const nested of Object.values(value)) deepFreeze(nested); + } + return value; +} + +function sha256(value: string): string { + return createHash("sha256").update(value).digest("hex"); +} + +async function buildAssignedCatalog(identity: string, listing: readonly AssignedListingEntry[]): Promise { + const tools = new Map(); + const unavailable: Array<{ tool: string; reason: string }> = []; + const unchecked: string[] = []; + let listingSchemaBytes = 0; + let bytes = identity.length; + for (const entry of listing) { + const compilable = entry.bytes <= TOOL_INPUT_SCHEMA_MAX_BYTES + && (listingSchemaBytes += entry.bytes) <= ASSIGNED_SCHEMA_LISTING_BUDGET_BYTES; + let schema: Record; + if (compilable) { + const admission = await admitAssignedToolSchema(entry.digest, entry.raw); + if (!admission.ok) { + unavailable.push({ tool: entry.tool.name, reason: admission.reason }); + continue; + } + schema = admission.schema; + } else { + schema = structuredClone(entry.raw); + unchecked.push(entry.tool.name); + } + const definition = Object.freeze({ + name: entry.name, description: `${entry.tool.displayName}: ${entry.tool.description}`, inputSchema: deepFreeze(schema), + }); + bytes += entry.bytes + definition.description.length; + tools.set(entry.name, Object.freeze({ tool: entry.tool, schema: definition.inputSchema, definition })); + } + const entries = [...tools.values()]; + return Object.freeze({ + identity, bytes, tools, + definitions: Object.freeze(entries.map(entry => entry.definition)), + readDefinitions: Object.freeze(entries.filter(entry => entry.tool.risk === "read").map(entry => entry.definition)), + unavailable: deepFreeze(unavailable), + unchecked: Object.freeze(unchecked), + }); +} + +function sharedAssignedCatalog(key: string, identity: string): AssignedCatalog | undefined { + const entry = sharedCatalogs.get(key); + const catalog = entry?.catalog.deref(); + if (!entry || catalog?.identity !== identity) return undefined; + sharedCatalogs.delete(key); + sharedCatalogs.set(key, entry); + return catalog; +} + +function shareAssignedCatalog(key: string, catalog: AssignedCatalog): void { + if (catalog.bytes > ASSIGNED_CATALOG_CACHE_BYTES) return; + forgetSharedCatalog(key); + const reference = new WeakRef(catalog); + sharedCatalogs.set(key, { bytes: catalog.bytes, catalog: reference, holders: 0 }); + sharedCatalogBytes += catalog.bytes; + collectedCatalogs.register(catalog, { key, catalog: reference }); + for (const oldest of sharedCatalogs.keys()) { + if (sharedCatalogs.size <= ASSIGNED_CATALOG_CACHE_ENTRIES && sharedCatalogBytes <= ASSIGNED_CATALOG_CACHE_BYTES) break; + forgetSharedCatalog(oldest); + } +} + +async function resolveAssignedCatalog(companyId: string | undefined, listing: readonly AssignedListingEntry[]) { + const identity = JSON.stringify([companyId ?? null, listing.map(entry => + [entry.name, entry.tool.name, entry.tool.displayName, entry.tool.description, entry.tool.risk, entry.digest])]); + if (!companyId) return { catalog: await buildAssignedCatalog(identity, listing), release: () => {} }; + const key = sha256(identity); + let catalog = sharedAssignedCatalog(key, identity); + const pending = catalog ? undefined : pendingCatalogs.get(key); + if (pending) { + const joined = await pending; + catalog = joined.identity === identity ? joined : undefined; + } + if (!catalog) { + const building = buildAssignedCatalog(identity, listing); + pendingCatalogs.set(key, building); + try { + catalog = await building; + } finally { + if (pendingCatalogs.get(key) === building) pendingCatalogs.delete(key); + } + if (sharedAssignedCatalog(key, identity) !== catalog) shareAssignedCatalog(key, catalog); + } + const holder = sharedCatalogs.get(key); + if (!holder || holder.catalog.deref() !== catalog) return { catalog, release: () => {} }; + holder.holders += 1; + let released = false; + return { + catalog, + release: () => { + if (released) return; + released = true; + holder.holders -= 1; + if (holder.holders === 0 && sharedCatalogs.get(key) === holder) forgetSharedCatalog(key); + }, + }; +} + /** Server-owned MCP bindings projected into the runner's existing tool channel. */ export async function createAssignedMcpTools(input: { gateway: ToolGatewayService; gatewayPublicId: string; bearerToken: string; + companyId?: string; workMode?: WorkMode; /** Bound provider grammar complexity independently of protocol byte capacity. */ delivery?: "on_demand"; @@ -132,38 +271,26 @@ export async function createAssignedMcpTools(input: { gatewayPublicId: input.gatewayPublicId, bearerToken: input.bearerToken, }); - const tools = new Map(); - const schemas = new Map>(); - const unavailable: Array<{ tool: string; reason: string }> = []; - const unchecked: string[] = []; - let listingSchemaBytes = 0; + const listing: AssignedListingEntry[] = []; + const listedNames = new Map(); for (const descriptor of deduplicateToolDescriptors(listed)) { const name = assignedToolName(descriptor.name); - const previous = tools.get(name); - if (previous) { + const previous = listedNames.get(name); + if (previous !== undefined) { throw new ToolGatewayHttpError(409, - `Assigned MCP tool name collision for ${JSON.stringify([previous.name, descriptor.name])}.`, + `Assigned MCP tool name collision for ${JSON.stringify([previous, descriptor.name])}.`, "assigned_mcp_tool_name_collision"); } + listedNames.set(name, descriptor.name); const raw = (descriptor.parametersSchema ?? { type: "object", properties: {} }) as Record; const serialized = JSON.stringify(raw); - const bytes = Buffer.byteLength(serialized, "utf8"); - const compilable = bytes <= TOOL_INPUT_SCHEMA_MAX_BYTES - && (listingSchemaBytes += bytes) <= ASSIGNED_SCHEMA_LISTING_BUDGET_BYTES; - if (!compilable) { - tools.set(name, descriptor); - schemas.set(name, structuredClone(raw)); - unchecked.push(descriptor.name); - continue; - } - const admission = await admitAssignedToolSchema(serialized, raw); - if (!admission.ok) { - unavailable.push({ tool: descriptor.name, reason: admission.reason }); - continue; - } - tools.set(name, descriptor); - schemas.set(name, admission.schema); + listing.push({ + name, raw, bytes: Buffer.byteLength(serialized, "utf8"), digest: sha256(serialized), + tool: Object.freeze({ name: descriptor.name, displayName: `${descriptor.displayName}`, description: `${descriptor.description}`, risk: descriptor.risk }), + }); } + const { catalog, release } = await resolveAssignedCatalog(input.companyId, listing); + const { tools, unavailable, unchecked } = catalog; if (unavailable.length > 0) { logger.warn({ gatewayPublicId: input.gatewayPublicId, unavailable }, "assigned MCP tools whose input schema the Runner cannot validate are not offered"); @@ -172,7 +299,7 @@ export async function createAssignedMcpTools(input: { logger.warn({ gatewayPublicId: input.gatewayPublicId, unchecked }, "assigned MCP tools whose input schema is over the compile budget are offered only through assigned-tool search"); } - const permits = (tool: ToolGatewayDescriptor, mode: WorkMode = input.workMode ?? "standard") => mode === "standard" || tool.risk === "read"; + const permits = (tool: Pick, mode: WorkMode = input.workMode ?? "standard") => mode === "standard" || tool.risk === "read"; // OpenCode's HTTP bridge returns at most 64K JSON characters. Leave room // for the envelope and for JSON escaping when returning a schema chunk. // Other harnesses retain the larger PRP page and chunk budgets. @@ -201,7 +328,7 @@ export async function createAssignedMcpTools(input: { gatewayPublicId: input.gatewayPublicId, bearerToken: input.bearerToken, })).map(tool => [tool.name, tool])); const terms = args.query.toLowerCase().trim().split(/\s+/).filter(Boolean); - const authorized = [...tools].filter(([, tool]) => { + const authorized = [...tools].filter(([, { tool }]) => { const fresh = current.get(tool.name); return fresh && permits(tool) && permits(tool, currentWorkMode) && permits(fresh) && permits(fresh, currentWorkMode); @@ -209,7 +336,7 @@ export async function createAssignedMcpTools(input: { if (hasSchemaTool) { const selected = authorized.find(([name]) => name === args.schemaTool); if (!selected) throw new Error("assigned_mcp_tool_unknown: schemaTool must match an authorized inputSchemaRef. Omit schemaTool to search assigned tools, then use an exact inputSchemaRef from the results."); - const schema = JSON.stringify(schemas.get(selected[0])); + const schema = JSON.stringify(selected[1].schema); const end = schemaOffset + schemaChunkCharacters; return { name: selected[0], schemaJson: schema.slice(schemaOffset, end), @@ -219,18 +346,18 @@ export async function createAssignedMcpTools(input: { // Keep offsets anchored to the pinned catalog while fresh grants only // decide which entries are returned from that stable sequence. const authorizedNames = new Set(authorized.map(([name]) => name)); - const matches = [...tools].filter(([, tool]) => permits(tool)).filter(([name, tool]) => + const matches = [...tools].filter(([, { tool }]) => permits(tool)).filter(([name, { tool }]) => terms.every(term => `${name} ${tool.displayName} ${tool.description}`.toLowerCase().includes(term))) .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0); const page: ToolDefinition[] = []; let nextOffset = offset; while (nextOffset < matches.length && page.length < limit) { - const [name, tool] = matches[nextOffset]!; + const [name, entry] = matches[nextOffset]!; if (!authorizedNames.has(name)) { nextOffset += 1; continue; } - let next = definition(name, tool, schemas.get(name)!); + let next: ToolDefinition = structuredClone(entry.definition); if (Buffer.byteLength(JSON.stringify([next]), "utf8") > searchPageBytes) { // One large schema must not block browsing the tools after it. Expose // a reference whose schema can be fetched in bounded, reauthorized @@ -246,9 +373,9 @@ export async function createAssignedMcpTools(input: { return { tools: page, nextOffset: nextOffset < matches.length ? nextOffset : null }; } - return { + const assigned = { definitions(fits?: (definitions: ToolDefinition[]) => boolean): ToolDefinition[] { - const direct = [...tools].filter(([, tool]) => permits(tool)).map(([name, tool]) => definition(name, tool, schemas.get(name)!)); + const direct = [...((input.workMode ?? "standard") === "standard" ? catalog.definitions : catalog.readDefinitions)] as ToolDefinition[]; if (input.delivery !== "on_demand" && unchecked.length === 0 && (!fits || fits(direct))) return direct; const compact = structuredClone(ON_DEMAND_TOOLS); if (fits && !fits(compact)) throw new Error("assigned_mcp_tool_catalog_capacity_exceeded"); @@ -267,7 +394,7 @@ export async function createAssignedMcpTools(input: { name = args.name; parameters = object(args.arguments); } - const descriptor = tools.get(name); + const descriptor = tools.get(name)?.tool; if (!descriptor) throw new Error("assigned_mcp_tool_unknown"); if (!permits(descriptor) || !permits(descriptor, currentWorkMode)) throw new Error("paperclip_runner_tool_mode_denied"); // Reauthorize through the existing gateway on every call. Discovery is @@ -288,5 +415,11 @@ export async function createAssignedMcpTools(input: { } return result.result; }, + close(): void { + collectedSessions.unregister(assigned); + release(); + }, }; + collectedSessions.register(assigned, release, assigned); + return assigned; } diff --git a/server/src/services/native-runtime/native-session-executor.ts b/server/src/services/native-runtime/native-session-executor.ts index 54913e0bb22..5778b973134 100644 --- a/server/src/services/native-runtime/native-session-executor.ts +++ b/server/src/services/native-runtime/native-session-executor.ts @@ -16243,6 +16243,7 @@ async function createRunnerdBackendWithinSessionClaim( gateway: getAssignedMcpGateway(input.db), gatewayPublicId: assignedGatewayPublicId!, bearerToken: assignedMcpToken, + companyId: input.execution.binding.companyId, workMode: input.execution.task.workMode, ...(input.execution.provider.kind === "opencode" ? { delivery: "on_demand" as const } : {}), })) diff --git a/server/src/services/native-runtime/paperclip-runner-tool-authority.test.ts b/server/src/services/native-runtime/paperclip-runner-tool-authority.test.ts index a4b1a54d5c7..d8fc0b129f7 100644 --- a/server/src/services/native-runtime/paperclip-runner-tool-authority.test.ts +++ b/server/src/services/native-runtime/paperclip-runner-tool-authority.test.ts @@ -1098,9 +1098,10 @@ describe("PaperclipRunnerToolAuthority", () => { it("relays assigned MCP calls only while the native run still owns its task", async () => { const tool = { name: "app_mem0_recall", description: "Recall memory", inputSchema: { type: "object" } }; const execute = vi.fn().mockResolvedValue({ content: "synthetic memory" }); + const close = vi.fn(); const authority = new PaperclipRunnerToolAuthority(db, { companyId, agentId, issueId, runId, - assignedMcpTools: { definitions: () => [tool], has: (name) => name === tool.name, execute }, + assignedMcpTools: { definitions: () => [tool], has: (name) => name === tool.name, execute, close }, }); expect(authority.definitions()).toContainEqual(tool); const call = { tool: tool.name, callId: "assigned-mcp", arguments: { query: "compass" } }; @@ -1121,6 +1122,9 @@ describe("PaperclipRunnerToolAuthority", () => { } finally { await db.update(heartbeatRuns).set({ status: "running" }).where(eq(heartbeatRuns.id, runId)); } + expect(close).not.toHaveBeenCalled(); + authority.close(); + expect(close).toHaveBeenCalledOnce(); }); it("does not advertise delegation tools during pre-acceptance planning", () => { diff --git a/server/src/services/native-runtime/paperclip-runner-tool-authority.ts b/server/src/services/native-runtime/paperclip-runner-tool-authority.ts index b1ecd547db2..e4a5bd44dcf 100644 --- a/server/src/services/native-runtime/paperclip-runner-tool-authority.ts +++ b/server/src/services/native-runtime/paperclip-runner-tool-authority.ts @@ -349,7 +349,7 @@ function hireAgentResult(value: unknown, provider: unknown) { export class PaperclipRunnerToolAuthority { #taskAttachmentCache = new TaskAttachmentReadCache(); #skillLibraryCache = new SkillLibraryReadCache(); - close() { this.#taskAttachmentCache.close(); this.#skillLibraryCache.close(); } + close() { this.#taskAttachmentCache.close(); this.#skillLibraryCache.close(); this.binding.assignedMcpTools?.close?.(); } constructor(readonly db: Db, readonly binding: Binding) {} definitions(): Array> {