mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +01:00
Scope runtime catalog reads to standing-instruction sources (#22356)
## Thinking Path > - Paperclip uses standing instructions from authorized app connections when it prepares a run. > - The gateway already knows which connections have instructions enabled. > - The catalog read still loads tool schemas for every eligible connection in the company. > - This work delays prompt preparation and consumes database and application resources. > - The gateway can restrict the existing catalog query while preserving the names used for authorization. ## Linked Issues or Issue Description **Subsystem affected** — Tool gateway and run preparation. **Problem or motivation** — The instruction resolver filters tool descriptors after the database has returned unrelated catalog entries. **Proposed solution** — Scope the persisted catalog read to possible instruction sources. Include peers that share a candidate’s short connection ID when assigning tool names. **Alternatives considered** — An exact connection ID filter could change a tool name and its policy decision. A separate instruction authorization query would duplicate gateway policy. **Roadmap alignment** — This improves the existing task-start path. Related work includes #22347 and #14864. **Additional context** — The change uses the existing read-only catalog snapshot. It adds no schema or cache. ## What Changed - Pass the instruction candidates to the shared gateway catalog reader. - Read eligible naming peers in the same snapshot. Return only candidate descriptors after assigning their names. - Retain the existing run identity, guest restrictions, model visibility, provider tools, policy decisions and grants. ## Verification - Ran the connection instruction and gateway listing-memory integration suites against embedded PostgreSQL. All 23 tests passed. - Confirmed the bounded-read assertion fails on the baseline and passes on the change. A full listing reads 20 catalog entries from two connections. The instruction lookup reads 10 entries from one. - Covered exact-name approval and block policies, peer quarantine, unchanged instruction text and digest, and visibility of unrelated tools in normal discovery. - Ran integration tests for gateway discovery, gateway service behavior, and assigned MCP tools. All 256 tests passed. - Compared complete instruction resolution with embedded PostgreSQL on macOS, using 16 alternating measured pairs after five warm-ups. The one-tool fixture took 10.05 ms median on the baseline and 10.32 ms on the change. With 1,994 synthetic entries across 21 connections and four candidate entries, the medians were 50.44 ms and 24.47 ms. The median paired saving was 26.03 ms. Final instruction text and digest matched for every pair. - The comparison measures the local instruction resolver. Remote submission-to-turn latency was outside this verification. ## Risks The candidate read uses the first UUID component because it participates in gateway naming. Matching peers contribute to name collisions even when an agent cannot use the peer. The regression checks that a blocked candidate cannot gain access when the catalog is narrowed. Companies that enable instructions on most connections can expect smaller savings. ## Model Used OpenAI Codex directed and qualified the change. GPT-6.2 Sol implemented the change and focused regression tests. ## 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 - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
1 parent
28043f8b93
commit
d8ae55198d
3 files changed
+83
-13
No files matched your search
@@ -48,15 +48,17 @@ async function createRunFixture(db: ReturnType<typeof createDb>) {
|
||||
return { company, agent, issue, run };
|
||||
}
|
||||
|
||||
async function createRemoteMcpToolFixture(db: ReturnType<typeof createDb>, companyId: string) {
|
||||
async function createRemoteMcpToolFixture(db: ReturnType<typeof createDb>, companyId: string, id?: string) {
|
||||
const applicationKey = `remote-${randomUUID().slice(0, 8)}`;
|
||||
const application = await db.insert(toolApplications).values({
|
||||
companyId,
|
||||
applicationKey: `remote-${randomUUID().slice(0, 8)}`,
|
||||
name: "Remote MCP",
|
||||
applicationKey,
|
||||
name: `Remote MCP ${applicationKey}`,
|
||||
type: "mcp_http",
|
||||
status: "active",
|
||||
}).returning().then((rows) => rows[0]!);
|
||||
const connection = await db.insert(toolConnections).values({
|
||||
id,
|
||||
companyId,
|
||||
applicationId: application.id,
|
||||
name: "Remote connection",
|
||||
@@ -101,9 +103,9 @@ async function createRemoteMcpToolFixture(db: ReturnType<typeof createDb>, compa
|
||||
let temp: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
|
||||
beforeAll(async () => { temp = await startEmbeddedPostgresTestDatabase("paperclip-connection-instructions-"); db = createDb(temp.connectionString); }, 30000);
|
||||
afterAll(async () => { await temp?.cleanup(); });
|
||||
async function fixture() {
|
||||
async function fixture(connectionId?: string) {
|
||||
const run = await createRunFixture(db);
|
||||
const connection = await createRemoteMcpToolFixture(db, run.company.id);
|
||||
const connection = await createRemoteMcpToolFixture(db, run.company.id, connectionId);
|
||||
const service = toolAccessService(db);
|
||||
await service.updateConnection(connection.connection.id, { agentInstructions: { enabled: true, text: paragraph } });
|
||||
await service.finishGalleryAppConnection(run.company.id, connection.connection.id, {
|
||||
@@ -131,6 +133,40 @@ async function createRemoteMcpToolFixture(db: ReturnType<typeof createDb>, compa
|
||||
}
|
||||
});
|
||||
|
||||
it("preserves tool-name approval and block policies for UUID prefix collisions", async () => {
|
||||
const f = await fixture("00000000-1000-4000-8000-000000000001");
|
||||
const peer = await createRemoteMcpToolFixture(db, f.company.id, "00000000-ffff-4fff-bfff-ffffffffffff");
|
||||
const unrelated = await createRemoteMcpToolFixture(db, f.company.id, "00000001-0000-4000-8000-000000000000");
|
||||
for (const { connection } of [f, peer, unrelated]) {
|
||||
await db.update(toolConnections).set({
|
||||
config: { ...connection.config, paperclipPeerToolNamespace: "Shared namespace" },
|
||||
}).where(eq(toolConnections.id, connection.id));
|
||||
}
|
||||
await f.service.finishGalleryAppConnection(f.company.id, unrelated.connection.id, {
|
||||
enabledCatalogEntryIds: [unrelated.catalogEntry.id], askFirstCatalogEntryIds: [], access: { agentIds: [f.agent.id] },
|
||||
});
|
||||
|
||||
const snapshot = await f.resolve();
|
||||
expect(snapshot?.text).toContain(paragraph);
|
||||
|
||||
const session = await f.gateway.createSession(f.binding);
|
||||
const tools = await f.gateway.listToolsForSession(session.token);
|
||||
expect(tools.some((tool) => tool.connectionId === unrelated.connection.id)).toBe(true);
|
||||
expect(tools.some((tool) => tool.connectionId === peer.connection.id)).toBe(false);
|
||||
const candidateName = tools.find((tool) => tool.connectionId === f.connection.id)?.name;
|
||||
expect(candidateName).toMatch(/^mcp\.shared-namespace-00000000:needs-input-[\da-f]{8}$/);
|
||||
const [policy] = await db.insert(toolPolicies).values({
|
||||
companyId: f.company.id, name: "Protect the exact collision name", policyType: "require_approval", priority: 1000,
|
||||
selectors: { toolName: candidateName },
|
||||
}).returning();
|
||||
expect(await f.resolve()).toEqual(snapshot);
|
||||
await db.update(toolPolicies).set({ policyType: "block" }).where(eq(toolPolicies.id, policy!.id));
|
||||
expect(await f.resolve()).toBeNull();
|
||||
|
||||
await db.update(toolCatalogEntries).set({ quarantinedAt: new Date() }).where(eq(toolCatalogEntries.id, peer.catalogEntry.id));
|
||||
expect(await f.resolve()).toEqual(snapshot);
|
||||
});
|
||||
|
||||
it("persists a non-memory paragraph and captures it in actual process input and both prompt composers", async () => {
|
||||
const f = await fixture();
|
||||
expect((await f.service.getConnection(f.connection.id)).agentInstructions).toEqual({ enabled: true, text: paragraph });
|
||||
|
||||
@@ -289,6 +289,19 @@ describeEmbeddedPostgres("tool gateway listing memory", () => {
|
||||
const phase = spans.find((span) => span.name === `${prefix}.${name}`);
|
||||
expect(phase?.parentSpanContext?.spanId).toBe(connectionPhase.spanContext().spanId);
|
||||
}
|
||||
|
||||
exporter.reset();
|
||||
await db.update(toolConnections).set({
|
||||
agentInstructions: { enabled: true, text: "Use this tool for the assigned task." },
|
||||
}).where(eq(toolConnections.id, fixture.connection.id));
|
||||
await withRunExecutionTiming(fixture.run.id, () => gateway.resolveConnectionInstructionsForRun({
|
||||
companyId: fixture.company.id, agentId: fixture.agent.id, runId: fixture.run.id,
|
||||
}));
|
||||
const instructionCatalog = exporter.getFinishedSpans().find((span) => span.name === transaction.name);
|
||||
expect(instructionCatalog?.attributes).toMatchObject({
|
||||
"paperclip.execution.catalogEntryCount": 10,
|
||||
"paperclip.execution.connectionCount": 1,
|
||||
});
|
||||
} finally {
|
||||
vi.unstubAllEnvs();
|
||||
trace.disable();
|
||||
|
||||
@@ -111,6 +111,7 @@ import {
|
||||
ne,
|
||||
or,
|
||||
sql,
|
||||
type SQL,
|
||||
} from "drizzle-orm";
|
||||
import type { Db } from "@paperclipai/db";
|
||||
import {
|
||||
@@ -1829,9 +1830,18 @@ export function createToolGatewayService(
|
||||
|
||||
async function connectedMcpToolsForCompany(
|
||||
companyId: string,
|
||||
selectedConnectionIds?: string[],
|
||||
scope?: { connectionIds: ReadonlySet<string>; preserveToolNames?: true },
|
||||
): Promise<ToolGatewayDescriptor[]> {
|
||||
if (selectedConnectionIds?.length === 0) return [];
|
||||
if (scope?.connectionIds.size === 0) return [];
|
||||
// Equal gateway base names require the same short connection UUID. Include
|
||||
// these peers in the catalog snapshot so their eligible tools still affect naming.
|
||||
let connectionScope: SQL | undefined;
|
||||
if (scope?.preserveToolNames) {
|
||||
const prefixes = [...new Set(Array.from(scope.connectionIds, shortStableId))];
|
||||
connectionScope = sql`split_part(${toolConnections.id}::text, '-', 1) = any(${sql.param(prefixes)}::text[])`;
|
||||
} else if (scope) {
|
||||
connectionScope = inArray(toolConnections.id, [...scope.connectionIds]);
|
||||
}
|
||||
// Read each connection and application row once. Selecting them in the
|
||||
// catalog join repeats the full connection row (config included) for
|
||||
// every tool, and one connection can expose hundreds of tools. Both reads
|
||||
@@ -1857,7 +1867,7 @@ export function createToolGatewayService(
|
||||
eq(toolCatalogEntries.status, "active"),
|
||||
isNull(toolCatalogEntries.quarantinedAt),
|
||||
connectedMcpConnectionFilter(companyId),
|
||||
selectedConnectionIds ? inArray(toolConnections.id, selectedConnectionIds) : undefined,
|
||||
connectionScope,
|
||||
),
|
||||
)
|
||||
.orderBy(toolConnections.name, toolCatalogEntries.name));
|
||||
@@ -1928,7 +1938,12 @@ export function createToolGatewayService(
|
||||
pluginCatalogEntryCurrent(connection, catalogEntry))),
|
||||
);
|
||||
});
|
||||
return measureRunPhase("connectors.discovery.connections.descriptors", () => buildConnectedCatalogDescriptors(eligibleRows));
|
||||
return measureRunPhase("connectors.discovery.connections.descriptors", () => {
|
||||
const tools = buildConnectedCatalogDescriptors(eligibleRows);
|
||||
return scope?.preserveToolNames
|
||||
? tools.filter((tool) => tool.connectionId && scope.connectionIds.has(tool.connectionId))
|
||||
: tools;
|
||||
});
|
||||
}
|
||||
|
||||
function buildConnectedCatalogDescriptors(eligibleRows: Array<{
|
||||
@@ -3592,9 +3607,15 @@ export function createToolGatewayService(
|
||||
}
|
||||
|
||||
/** Shared connection descriptors and task restrictions; no provider calls. */
|
||||
async function connectionToolsForContext(session: ToolGatewaySession): Promise<ToolGatewayDescriptor[]> {
|
||||
async function connectionToolsForContext(
|
||||
session: ToolGatewaySession,
|
||||
candidateConnectionIds?: ReadonlySet<string>,
|
||||
): Promise<ToolGatewayDescriptor[]> {
|
||||
const guestBotConnection = await measureRunPhase("connectors.discovery.github", () => githubGuestBotConnectionForSession(db, session));
|
||||
let connectedTools = (await measureRunPhase("connectors.discovery.connections", () => connectedMcpToolsForCompany(session.companyId)))
|
||||
let connectedTools = (await measureRunPhase("connectors.discovery.connections", () => connectedMcpToolsForCompany(
|
||||
session.companyId,
|
||||
candidateConnectionIds && { connectionIds: candidateConnectionIds, preserveToolNames: true },
|
||||
)))
|
||||
.filter(isModelVisibleTool)
|
||||
.filter(tool => !guestBotConnection || !tool.connectionId || (tool.connectionId === guestBotConnection && tool.providerType === "paperclip_github_chat"));
|
||||
const connectionIds = [...new Set(connectedTools.flatMap((tool) => tool.connectionId ? [tool.connectionId] : []))];
|
||||
@@ -11937,7 +11958,7 @@ export function createToolGatewayService(
|
||||
// Prompt assembly needs authorization, not a full discovery listing. Share
|
||||
// descriptors and policy decisions, but only authorize candidate sources;
|
||||
// discovery admission pressure must not remove guidance or reset sessions.
|
||||
const tools = (await connectionToolsForContext(session))
|
||||
const tools = (await connectionToolsForContext(session, candidateIds))
|
||||
.filter((tool) => tool.connectionId && candidateIds.has(tool.connectionId));
|
||||
const decisions = await decideToolsForListing(tools, (tool) => policyInputForTool({ session, tool }));
|
||||
const visible = new Set(decisions.flatMap(({ tool, decision }) =>
|
||||
@@ -12072,7 +12093,7 @@ export function createToolGatewayService(
|
||||
await assertAgentInCompany(binding.companyId, binding.agentId);
|
||||
if (await githubGuestBotConnectionForSession(db, session)) return [];
|
||||
const tools = await measureRunPhase("connectors.browser_use.catalog", async () => {
|
||||
const candidates = await connectedMcpToolsForCompany(binding.companyId, connections.map(connection => connection.id));
|
||||
const candidates = await connectedMcpToolsForCompany(binding.companyId, { connectionIds: new Set(connections.map(connection => connection.id)) });
|
||||
const decisions = await decideToolsForListing(candidates, tool => policyInputForTool({ session, tool }));
|
||||
return decisions.filter(({ decision }) => decision.allowed || decision.decision === "require_approval").map(({ tool }) => tool);
|
||||
});
|
||||
|
||||
Reference in new issue
Block a user