mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-23 00:53:38 +02:00
DottaandPaperclip
1e731520bb
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents receive governed app tools through the MCP gateway. > - GitHub review tasks can contain a PR discussion and inline finding threads. > - Discovery repeated each tool for every conversation linked to the task. > - Native tool registration treated these repeated descriptors as a fatal collision. > - This pull request lists GitHub tools once and deduplicates identical descriptors across providers. > - Agents can continue work while conflicting definitions and normal tool permissions remain enforced. ## Linked Issues or Issue Description **What happened?** A follow-up run on a GitHub review task failed with `assigned_mcp_tool_name_collision` before the provider started. The task had a main conversation and an inline finding thread. Discovery returned the same seven tools twice. Repeated descriptors from other providers could cause the same failure. **Expected behavior** Discovery exposes each identical tool once. Separate connection names remain separate tools. Conflicting definitions remain an error. Every call still passes the gateway's policy, approval, revocation, and audit checks. **Steps to reproduce** 1. Run a GitHub review and publish an inline finding. 2. Send a follow-up request on the same PR task. 3. Inspect the task-bound bot catalog and the next native startup. 4. Separately, return two identical descriptors from an assigned app or plugin catalog. Related: #13717 added the GitHub review workflow. ## What Changed - Use a distinct GitHub discovery query across conversations that share an endpoint and task. Keep both thread mappings. - Deduplicate identical gateway descriptors by their full gateway name across providers. Use this rule for MCP listings, plugin listings, assigned-tool startup, and fresh assigned-tool discovery. - Reject conflicting descriptors with `tool_name_collision`. Keep the projected-name collision guard. - Cover GitHub inline-thread discovery, repeated plugin/app tools, direct and on-demand catalogs, revocation, conflicting bindings, and separate connection names. - Update the execution contract, GitHub documentation, and agent access map. ## Verification - Regression baseline: six new assertions failed on the original implementation. GitHub returned fourteen entries, plugin discovery repeated a tool, and native startup failed on repeated app tools. - Focused verification passed: 272 GitHub cases, all 29 assigned-tool cases, and all 88 gateway acceptance cases. - `pnpm -r typecheck` passed. - `pnpm build` passed. - `node scripts/check-maps.mjs` passed. - Current-head CI passed: 55 checks passed, two inapplicable checks skipped. Greptile scored the current head 5/5 with no unresolved threads. - Full local `pnpm test:run` encountered a 15-second timeout in the existing bearer-auth throttling test, before tool discovery. That test passed in the separate 88-case gateway run and on one isolated rerun. The duplicate broad local run was then stopped; the complete current-head CI matrix passed. ## Risks - Deduplication keeps the first identical descriptor and preserves listing order. Same-name descriptors with different definitions fail with HTTP 409 rather than selecting an ambiguous binding. - The GitHub query changes result cardinality. It retains the existing task/company/agent filters and leaves conversation rows intact. - No schema migration or credential change. Live staging recovery requires deployment and a new authorized run. ## Model Used OpenAI Codex, based on GPT-6, with code inspection, editing, browser investigation, and test execution. The exact serving model ID and context window are not exposed in this session. ## 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 - [x] 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>
143 lines
5.4 KiB
Markdown
143 lines
5.4 KiB
Markdown
# Tool gateways and access profiles — agent access
|
|
|
|
Product map: [Tool gateways and access profiles](../feature-map/gateways-profiles.md).
|
|
|
|
Review date: 2026-10-12. Source commit: `58e16dbddfc9c8d0cf60867f9d9847f0feda055b`.
|
|
Native REST transport reconciled in this change; see the
|
|
[shared transport contract](README.md#native-rest-transport).
|
|
|
|
This is a source-reviewed baseline of representative operations and known gaps.
|
|
Each capability needs operation-level review before its entire scope can be
|
|
qualified. No live agent execution is claimed. Follow the [map contract](../README.md)
|
|
for format, permission checks, evidence and maintenance.
|
|
|
|
## `gateway`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `POST /api/companies/{companyId}/tools/gateways`.
|
|
|
|
Agent access: `restricted` — Board tools:admin REST; CLI connections/configuration where
|
|
supported.
|
|
|
|
Policy: Named gateway/profile administration and credentials are board tools:admin;
|
|
agent sessions/tool use use separate scoped authority.
|
|
|
|
Evidence: `source-only` — [implementation](../../server/src/routes/tool-gateway.ts#L353)
|
|
at the reviewed commit above.
|
|
|
|
Verification: `not-run` — assert the documented agent denial with an owned test fixture;
|
|
verify any listed agent request/result path separately. A delegated operation needs its
|
|
own policy and access review.
|
|
|
|
Gaps: No agent named-gateway management path; assigned tool use exists separately.
|
|
|
|
## `profiles`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `POST /api/companies/{companyId}/tools/profiles`.
|
|
- `PATCH /api/tool-profiles/{profileId}`.
|
|
|
|
Agent access: `restricted` — Board management REST; agent receives effective tool
|
|
assignment.
|
|
|
|
Policy: Named gateway/profile administration and credentials are board tools:admin;
|
|
agent sessions/tool use use separate scoped authority.
|
|
|
|
Evidence: `source-only` — [implementation](../../server/src/routes/tool-gateway.ts#L353)
|
|
at the reviewed commit above.
|
|
|
|
Verification: `not-run` — assert the documented agent denial with an owned test fixture;
|
|
verify any listed agent request/result path separately. A delegated operation needs its
|
|
own policy and access review.
|
|
|
|
Gaps: Agent access to tools does not permit profile editing.
|
|
|
|
## `client-connect`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `GET /api/tool-gateway/gateways/{gatewayId}/mcp`.
|
|
- `POST /api/tool-gateway/sessions`.
|
|
|
|
Agent access: `partial` — Agent REST / native `call_api` for scoped session creation
|
|
and revocation; existing MCP client protocol and assigned native app tools.
|
|
|
|
Policy: Named gateway/profile administration and credentials are board tools:admin;
|
|
agent sessions/tool use use separate scoped authority.
|
|
|
|
Evidence: `source-only` — [implementation](../../server/src/routes/tool-gateway.ts#L353)
|
|
at the reviewed commit above.
|
|
|
|
Verification: `not-run` — exercise a listed permitted operation with actual agent
|
|
credentials/run context; inspect its result and applicable persistence/attribution.
|
|
Assert the relevant denied actor, owner, company or mode from Policy. Review the
|
|
remaining operations before qualifying the whole capability.
|
|
|
|
Gaps: Scoped sessions remain agent/run-bound. MCP requires its existing protocol
|
|
client; named gateways and gateway-token management retain board permissions.
|
|
|
|
Discovery collapses identical descriptors with the same gateway name across
|
|
providers, including native assigned-tool startup and fresh searches. Conflicting
|
|
definitions remain an error. Distinct names and the normal invocation grants,
|
|
approvals and revocation checks remain independent. Regression coverage lives in
|
|
[gateway tests](../../server/src/__tests__/tool-gateway.test.ts) and
|
|
[assigned-tool tests](../../server/src/services/native-runtime/assigned-mcp-tools.test.ts);
|
|
these fixtures do not certify a live external-client journey.
|
|
|
|
## `tokens`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `POST /api/tool-gateway/gateways/{gatewayId}/tokens`.
|
|
- `POST /api/tool-gateway/gateway-tokens/{tokenId}/revoke`.
|
|
|
|
Agent access: `restricted` — Board tools:admin token management.
|
|
|
|
Policy: Named gateway/profile administration and credentials are board tools:admin;
|
|
agent sessions/tool use use separate scoped authority.
|
|
|
|
Evidence: `source-only` — [implementation](../../server/src/routes/tool-gateway.ts#L353)
|
|
at the reviewed commit above.
|
|
|
|
Verification: `not-run` — assert the documented agent denial with an owned test fixture;
|
|
verify any listed agent request/result path separately. A delegated operation needs its
|
|
own policy and access review.
|
|
|
|
Gaps: Gateway-token management requires board tools:admin at the HTTP route.
|
|
A grant to use an app does not create this authority; native `call_api` preserves
|
|
the denial.
|
|
|
|
## `activity`
|
|
|
|
Review: `baseline`.
|
|
|
|
API: `present` — representative operation IDs:
|
|
|
|
- `GET /api/tool-gateway/audit`.
|
|
|
|
Agent access: `restricted` — Board tools:view_audit; agent receives its own tool
|
|
receipts/errors.
|
|
|
|
Policy: Named gateway/profile administration and credentials are board tools:admin;
|
|
agent sessions/tool use use separate scoped authority.
|
|
|
|
Evidence: `source-only` — [implementation](../../server/src/routes/tool-gateway.ts#L353)
|
|
at the reviewed commit above.
|
|
|
|
Verification: `not-run` — assert the documented agent denial with an owned test fixture;
|
|
verify any listed agent request/result path separately. A delegated operation needs its
|
|
own policy and access review.
|
|
|
|
Gaps: Audit management API exists but broad audit visibility is not an agent use-path
|
|
guarantee.
|