Files
PaperClipAI/server
Nicky LeachandPaperclip d8ae55198d 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>
2026-11-19 14:07:48 -08:00
..