DottaandPaperclip
3ce8d976a9
## Thinking Path > - Paperclip connects agents to external tools through saved accounts and per-action permissions. > - Notebook exposes artifact management through an ordinary remote MCP server with OAuth. > - A private pilot needs a hidden, default-off catalog and execution gate. > - Local file publishing belongs to Notebook, which can accept bounded file bytes through ordinary MCP tools. > - Paperclip therefore needs the connector registration and generic availability checks, with no file-transfer architecture. ## Linked Issues or Issue Description **Subsystem affected** Apps catalog, experimental feature metadata, connection setup, and connector availability. **Problem or motivation** Users need to connect Notebook as their Cloud account, assign its tools to agents, and retain Paperclip's normal Allowed / Ask first / Off rules. The private pilot must remain hidden until an operator enables it. Notebook should own its upload protocol and local publishing script. **Proposed solution** Register a personal remote MCP OAuth connection at Notebook's canonical endpoint. Reuse existing OAuth discovery, credential storage, refresh, reconnect, and removal. Enforce availability through generic catalog feature metadata and saved application identity. Keep Notebook's standalone uploader in its own service repository; it calls the ordinary gateway and receives no saved OAuth credential. **Alternatives considered** A gallery-only filter permits retained tools and deep links while disabled. A shared workspace publisher and private upload-ticket transport add runtime behavior that a normal MCP connector does not require. Notebook can receive file bytes directly through its own tools instead. **Roadmap alignment** This extends Connected Apps and supports Artifacts and Work Products. ROADMAP.md and related PRs were checked. This PR is standalone on master. The separate OAuth lifecycle and file-transfer proposals (#17085 and #17086) are closed and are not dependencies. ## What Changed - Register Notebook's personal MCP OAuth method, canonical endpoint, scopes, catalog metadata, and branding. - Declare managed `enablePaperclipNotebook` with false defaults and no user-facing settings toggle or staging opt-in. - Use generic availability metadata for gallery/setup, retained connection identity, OAuth completion, health, tool/context discovery, and dispatch. Resources/prompts recheck before credentials, including retained handles. Removal remains available while disabled. - Resolve catalog application identity from the saved application key, so editable connection labels cannot bypass the hidden gate. - Select a method's sole supported credential kind when no kind is supplied. - Keep UI changes to metadata-driven availability and existing setup/reconnect controls. - Document Notebook's service-owned upload script, inline publication, ordinary action policies, and credential behavior. - Add ordinary MCP OAuth, assignment, action-policy, disabled-state, settings, and catalog tests. No workspace contribution registry, private transfer endpoint, native publisher, Runner file-reader change, or Paperclip CLI upload command is included. The entire native-runtime and CLI trees match master. Upload code lives in `paperclip-cloud/notebook/`. ## Verification Source head: `65ef741e4f476c67425b57d2fb2d6d4c00e99b06`, directly on master `53732c811bb69655eb43d3d12f2063ae4ca5ad67`. The diff is 42 files. Shared execution changes only enforce generic catalog availability; tool access also resolves saved application identity and the sole supported credential kind. Neither module contains Notebook upload logic. - Catalog/shared/settings/UI suites: 592 tests passed across 12 files. Shared/server/UI typechecks passed using installed compilers. - Fresh real PostgreSQL generic MCP suite: 84/84 passed at final source; server typecheck and module boundaries pass. Coverage includes personal OAuth, ordinary refresh/reconnect, assignments, Allowed / Ask first / Off, hidden feature enforcement, and local credential removal. Four new resources/prompts cases failed against the prior code and pass after filtering saved application identity and rechecking before credentials. They prove missing/relabelled setup markers and stale eligibility cannot dispatch or read secrets while disabled; an ordinary provider remains available with the flag off. - The full tool-access service suite passed 463/464 cases. One unchanged Google Workspace `slides.write` case timed out at 15 seconds; it passed on one isolated retry without source or timeout changes. Its exact test block matches master. The cause is not established; final-head CI must qualify the complete suite. - Maps, module boundaries, token gates, and whitespace checks passed. Byte comparisons confirm the former transfer/runtime/CLI surfaces match master. - Fresh exact-head Greptile is 5/5 with zero unresolved findings after an exhaustive feedback audit. Current-head CI workflow [39625691137](https://github.com/paperclipai/paperclip/actions/runs/39625691137) succeeded, including both required checks (`ci / verify`, `ci / e2e`), Build, and browser E2E. Supplementary security/advisory scan status is recorded in the PR Checks panel and qualification receipt; prior-head scans are not counted. The superseded `4bd7af9b2e` completed CI successfully, but Greptile found the valid resources/prompts availability gap described above. It was fixed, replied to, and resolved; earlier-head results do not qualify this revision. Preserved environment failures: the first socket-restricted UI/route run had 93 listener setup failures, and the same 93 cases passed with local-socket access. The package-manager launcher could not fetch its signature metadata; installed compilers passed without dependency or configuration changes. The full service timeout and isolated retry remain recorded separately. The superseded `585e870e73` CI also failed an unchanged agent-chat project-plan revision assertion after task creation; the complete spec and relevant runtime sources match master, and a same-master prior run passed. Its cause is not established. Logs are preserved; no test or timeout was weakened and no old-head rerun was requested. The subsequent heads run full CI independently; no prior-head pass substitutes for current qualification. The Notebook uploader requires a separate service release. This public PR adds no uploader runtime to Paperclip and claims no newly deployed browser/agent acceptance. The Notebook-owned upload path is qualified separately. Code-owner review remains required before merge. ## Risks - The feature flag gates the curated connector; it does not create a Notebook service-side team allowlist or block arbitrary standard MCP URLs. - Publishing, sharing, and deletion retain the existing assignment and action-policy boundaries. - The hidden feature must be checked for retained tools and saved identity, including when connection labels change. - Disconnect removes local credentials. It does not revoke the remote Notebook authorization; the owner can revoke it in Notebook. - Ordinary refresh uses the existing client. A lost response after refresh-token rotation can require reconnect. - The standalone Notebook script and its bounded upload tools must ship together in the Notebook service before that documented convenience path is available. - No database schema, workflow, lockfile, shared transfer, or Runner change is included. No merge, deployment, or rollout is performed by this update. ## Model Used OpenAI GPT-6 in Codex, with reasoning, repository inspection, code execution, and tool use. The runtime did not expose a more specific model ID or context-window size. ## 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>
10 KiB
Connection setup — agent access
Product map: Connection setup.
Feature ID: connection-setup.
Review date: 2026-10-12. Source commit: f981fa3cc10cb8663a87dec60345fbff46d54d0a.
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.
Prompt Injection Prevention reuses shared OpenRouter API-key setup directly from Settings → Connections. It adds no Apps provider or transport. Credential ownership and audience rules are the existing connection rules; saving a connection alone does not activate the service. See service configuration.
catalog
Capability ID: connection-setup/catalog.
Review: baseline.
API: present — representative operation IDs:
POST /runtime-tools/connections/search.
Agent access: available — Native connections_search / run-bound runtime-tools MCP.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
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: Runtime tool broker searches available services without granting connection administration.
Notebook is internally gated by enablePaperclipNotebook (default off, no settings toggle). Disabled instances hide setup/discovery and deny curated Notebook dispatch and publishing; local removal and grant revocation remain available.
The connector catalog declares the feature key. Shared availability checks use the saved application identity. Notebook owns publication and file uploads; Paperclip uses its existing MCP tools and OAuth flow.
Notebook source addition: paperclip-notebook is discoverable through
connections_search and requestable through connection_request. Its standard
personal authorization requests read, write, share, and delete scopes. Notebook
page ownership remains enforced by the remote service; a client-supplied agent
label grants no authority. The direct MCP connection requires no Cloud instance
enrollment. Notebook fixture evidence: verified against disposable PostgreSQL 18
with controlled MCP responses — Notebook integration
and generic OAuth fixture.
Ordinary MCP calls retain assignment and Allowed / Ask first / Off policy.
Live deployed publication and hosted/self-hosted OAuth remain release checks.
identity-and-access
Capability ID: connection-setup/identity-and-access.
Review: baseline.
API: present — representative operation IDs:
POST /api/companies/{companyId}/tools/connections.
Agent access: restricted — Board setup API plus agent connection_request.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
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: Selecting account ownership/eligible agents is management; an agent can request the intended connection.
credentials
Capability ID: connection-setup/credentials.
Review: baseline.
API: present — representative operation IDs:
POST /api/agents/me/connections/{connectionId}/start-authorization.
Agent access: partial — Scoped start-authorization/request flow; human provider login.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
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: An initiation endpoint exists; it is not authorization to complete the person's credential flow.
Daytona native setup uses an organization API key in the selected personal or company vault grant. It does not borrow sandbox-provider credentials or CLI login tokens. Agents use assigned provider tools through the normal run-bound gateway; they cannot export the key. Database-backed fixtures cover selected vault ownership and gateway reads/writes with provider responses replaced by fixtures. Real provider authentication remains unqualified.
handoff
Capability ID: connection-setup/handoff.
Review: baseline.
API: present — representative operation IDs:
POST /api/connection-intents/{interactionId}/complete.
Agent access: restricted — Addressed-user completion; server wakes the agent with
updated access.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
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: OAuth/callback and addressed-user checks are deliberate separate boundaries.
draft-recovery
Capability ID: connection-setup/draft-recovery.
Review: baseline.
API: present — representative operation IDs:
POST /api/connection-intents/{interactionId}/phase.POST /api/tool-connections/{connectionId}/reconnect.
Agent access: restricted — Human setup/resume APIs; agent request state and
continuation.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
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: Board setup recovery exists. Browser-only navigation state is not automatically an agent API gap.
task-request
Capability ID: connection-setup/task-request.
Review: baseline.
API: present — representative operation IDs:
POST /runtime-tools/connections/request.
Agent access: available — Native connection_request / run-bound runtime-tools MCP.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
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: This is the existing agent bridge for human-required setup; do not invent a second approval system.
channel-setup
Capability ID: connection-setup/channel-setup.
Review: baseline.
API: present — representative operation IDs:
POST /api/companies/{companyId}/chat-endpoints.
Agent access: restricted — Board channel management; agent requests required setup.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
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: Provider endpoint, represented agent and linked sender are operator choices today.
Internal recovery: Telegram discovery walks bounded pages at startup. Configuration commits only queue the changed connection; durable maintenance rows supply retry deadlines. Inactive subscription repair is parked until an endpoint or connection change. This creates no agent management permission or new API. Local database-backed provider-fixture tests in channel integration cover recovery, rollback, retries and idle query silence; they do not establish live provider or agent access.
failure
Capability ID: connection-setup/failure.
Review: baseline.
API: present — representative operation IDs:
POST /api/tool-connections/{connectionId}/health-check.
Agent access: partial — Agent observes connection tool errors; board repair APIs.
Policy: Setup and credentials belong to the addressed authorized human; active-run tools can search/request access.
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: Error reporting and human repair exist; no generic agent permission to reconnect accounts.