DottaandPaperclip
370fb50ad4
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agents use remote MCP tools through a governed gateway. > - The gateway lists tools only while their shared connection is healthy. > - One failed call currently marks the whole connection as unhealthy. > - Later calls to healthy sibling tools then fail with `tool_not_found`. > - This pull request keeps non-authentication call failures on their invocation. > - Agents can continue their work while credential and access gates remain in force. ## Linked Issues or Issue Description Refs #10147. Related work: #15462 fixed oversized and malformed response handling. #15448 covers timeout and JSON-RPC health handling together with separate SSE and catalog discovery changes. Its patch still marks fetch failures and HTTP failures as connection errors. #15325 proposed a transport failure counter; it has merge conflicts and has not changed since October 6. #11910 is an older timeout fix with merge conflicts. This PR covers the remaining fetch and HTTP failure paths on current master, with the same narrow call-health rule for timeouts and JSON-RPC failures. It does not include the SSE or discovery changes from #15448. The timeout session-reset check follows the recovery case discussed in #15448. **What happened?** A shared remote MCP connection works until one call has a network failure, timeout, HTTP 503, or JSON-RPC error. Every later call on that connection returns `tool_not_found`, including healthy sibling tools. Connection setup then asks for user attention even though the failure did not prove that credentials need repair. **Expected behavior** The original invocation retains its failure. Authorized sibling tools remain callable. The gateway does not replay an ambiguous action. HTTP 401/403, missing credentials, and explicit insufficient scope keep their access gates. **Steps to reproduce** 1. Give an agent access to two read tools on one remote MCP connection. 2. Make one tool fail with a network error or HTTP 503. 3. Call the other tool in the same gateway session. 4. Before this fix, the second call fails with `tool_not_found` before provider dispatch. **Paperclip version or commit** `master` at `e6dcd1e8e9`. The regression runs against source with synthetic data. **Deployment mode** Any deployment that uses a shared remote MCP connection. This is a core gateway issue. ## What Changed - Preserve connection health after a network failure, timeout, non-authentication HTTP error, or JSON-RPC error from one tool call. - Retain HTTP 401/403 and insufficient-scope health gates. - Retain HTTP 401/403 gates during MCP initialization and its initialized notification, with HTTP 503 controls for both stages. - Discard only the upstream session used by a network failure or timeout. Let the next explicit call initialize again. - Add sibling-tool regression cases, authentication controls, and real HTTP header/body timeout checks. - Update runtime recovery guidance and the feature and access maps. ## Verification - Red: the four new sibling-tool cases failed on the original implementation. Each second call returned HTTP 404 with `tool_not_found`. HTTP 401/403 control cases passed. - Green: the same six-case selection passed after the production change: `pnpm --filter @paperclipai/server exec vitest run src/__tests__/tool-gateway-service.test.ts -t 'keeps sibling MCP tools usable|keeps the connection blocked' --maxWorkers=1`. - The regression checks the actual gateway and embedded PostgreSQL. The injected provider fault preserves the call boundary. It checks failure recording, no automatic replay, catalog retention, and successful sibling dispatch. - The real local HTTP fixture checks cancellation before headers and during a body, then a successful explicit call with a fresh MCP session. - `node scripts/check-maps.mjs` and `git diff --check` pass. - Complete nearby suites pass: 166 tests across `tool-gateway-service.test.ts`, `tool-gateway.test.ts`, `remote-mcp-protocol.test.ts`, and `mcp-http.test.ts`, with one test worker. - `pnpm --filter @paperclipai/server exec tsc --noEmit` passes after refreshing Runner TypeScript declarations. The first package typecheck used declarations from before the rebase and failed two unchanged native-session call sites; rebuilding that dependency resolved both errors. - The rebased head also passes all 11 selected sibling/authentication/session regressions. - Review regression red: setup-stage HTTP 401/403 controls failed because connection health stayed `ok`; the two setup-stage HTTP 503 controls passed. Green: all six setup controls and the complete 166-test nearby run pass. The fix separately handles typed initialization authentication failures and preserves the existing caller error. The server compiler also passes after this change. - Full repository CI passes on `256a65ccc302c1c31a80e87f1f91411d955028de`: typecheck, build, test shards, Runner checks, browser checks, Canary dry run, and aggregate gates. All checks are terminal: 55 successful, 2 expected skips, and the separate Paperclip Review check is neutral. Greptile is 5/5 on this exact head, with no open findings. - Full repository checks were run in CI. Local verification in this worktree used the focused suites and server compiler to keep parallel work bounded. - This change has no live provider or staging deployment proof. ## Risks - A provider that remains unavailable can stay listed until a health check detects the outage. Each call still fails with its original controlled reason code. - No automatic retry occurs because a failed remote action may already have run. - Already unhealthy connections still need a successful health check after an upgrade. - No schema, credential policy, or permission contract changes. ## Model Used - OpenAI Codex, GPT-6 family, with tool use and code execution. The runtime does not expose the exact serving model ID or context window. ## 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>
7.9 KiB
Tool gateways and access profiles — agent access
Product map: Tool gateways and access profiles.
Review date: 2026-10-12. Source commit: 58e16dbddfc9c8d0cf60867f9d9847f0feda055b.
Native REST transport reconciled in this change; see the
shared transport contract.
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 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
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
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.
Backend evidence: profile entry validation covers company-scoped selector references and bounded reads for a large immutable runtime assignment. Batched validation retains the checks before profile and entry writes. It grants no profile-management authority to agents.
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
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 and assigned-tool tests; these fixtures do not certify a live external-client journey.
Remote invocation regressions preserve access to authorized sibling tools after a fetch failure, timeout, non-authentication HTTP error, or JSON-RPC rejection. HTTP 401/403 and insufficient-scope errors keep their connection gates. The gateway records each failed invocation and never automatically replays it. This covers the gateway service with synthetic providers and a local HTTP server, not a live external provider or all client surfaces.
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
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
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.
Execution-host stdio assignments
Runner registers verified, session-local stdio servers from the execution host with native Codex and through the shared ACPX runtime. ACPX clients must support stdio MCP assignments. The transport uses each implementation's own schemas and responses. Each binding requires a private Unix socket to identify the shared resource whose calls are serialized. This is a separate binding alongside the HTTP gateway; it does not create gateway/profile administration authority. Tasks cannot supply these reserved environment inputs. Read-only sessions omit them. ACPX adapters use their applicable ACPX permission policy. Host-assigned native Codex tools run without a new per-call prompt, matching existing execution-host shell utilities. Explicit deny/prompt rules remain effective; requested approvals use PRP with active thread/turn checks and one-time decisions. Preconfigured Claude rejects interactive approval requests. See the Runner contract.
Local fixture coverage: binding validation, relay processes and cancellation, and approval projection. Provider-client image and approval smoke tests used native Codex and Claude SDK; that coverage is not an exhaustive adapter compatibility test. Vendor-client evidence belongs in the PR. These checks do not certify live external credentials, deployment isolation or gateway revocation.