DottaandPaperclip
92b238137b
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Apps and AI Connections store credentials and govern access to agent runtimes. > - Users need a supported saved-token connection and config values that survive save and reopen. > - The release must preserve saved-token access and task lifecycle guarantees. > - This pull request will connect Copilot through the normal Apps and AI Connections path. > - The benefit is a reviewable part of the Copilot production release. ## Linked Issues or Issue Description Refs #15701 and #15703. Supersedes setup work in #15562. Base: #15703. Next: #15706. ## What Changed - Require configuration update authority before Copilot credential-bearing model discovery; default to the saved environment and preserve explicit selection for editors. - Keep Copilot discovery passive during reconnect reconciliation; refresh on explicit opening, account/environment changes and reconnect. - Add GitHub AI token connections with encrypted storage, ownership, grants and audit logging. - Keep repository access separate from Copilot runtime authentication. - Probe the selected environment without sending a model prompt and preserve authenticated model selection through save/reopen. - Keep fresh execution admission consistent with normal Copilot setup; persist task model choices without changing provider or permission policy. - Refresh authenticated models after reconnecting the same saved Copilot account, including recovery from a previous authentication error. - Apply the additive provider-default constraint migration through the normal generated migration workflow. ## Verification Runtime #15701 is merged at `d855e550ad8d2a267312983f26457aabf5393c3a`. History #15703 is merged at `df80616d98119cbf5abd40549794d9980a5fabf6`. Remaining source [`42bcbd61299655f7e37aabe6bb5f19bba770ad1d`](https://github.com/paperclipai/paperclip/commit/42bcbd61299655f7e37aabe6bb5f19bba770ad1d) contains the four-file authorization repair. The remaining PR trees preserve six nonoverlapping files from the newer public mainline managed-settings fix and the CI-owned lockfile. No unrelated provider is enabled. The security finding is repaired: existing-agent discovery requires `agent_config:update` before connection selection or token resolution. The saved environment is the default. Authorized editors can select a prospective environment. Both denied board-viewer and agent-reader regressions fail on the original source. All49 route tests and server typecheck pass with the fix. Denied requests perform no connection selection, credential resolution or probe. Current-head security scans pass on both remaining PRs; the repaired thread is resolved. Copilot CLI1.0.88 and profile47 retain digest `sha256:55044aa235e88b3fe36ec8a556ee1e3382590870aab907e4462ef7d64af49cea`. The [qualification record](https://github.com/paperclipai/paperclip/blob/42bcbd61299655f7e37aabe6bb5f19bba770ad1d/doc/plans/2026-10-20-copilot-qualification-v47.json) reports20/20 Product cells,154 assertions and7/7 protocol cases,46 assertions against frozen normal installed source `c2616370800f5f6df45246b0890ba35a7cd2faab`. The exact qualification model is `gpt-5.6-luna`. Every passing Product case confirms cleanup. Original failures remain recorded; automatic behavior retries are disabled. The route-only authorization repair changes no bound runtime/profile bytes and does not relabel the frozen campaign. The ordinary installed remote journey passed saved-token selection, model discovery, normal UI save/reopen, metadata-only Test, completed task, accepted receipt and exact19-byte browser download. An open model catalog caused no additional discovery requests during117seconds. Actual installed runtime smokes passed on macOS ARM64, macOS x64 under Rosetta and native Linux x64 on Daytona. Raw token browser entry was not exercised; encrypted connection creation used the normal API. The first Daytona file attempt timed out during delayed semantic dispatch; its precise stalled layer remains unresolved. Independent ordinary remote delivery and the other19 Product cells passed before one instrumented recheck passed8/8 with unchanged source,prompt,assertions and deadlines. No causal latency repair is claimed. Before the authorization repair, all four final PR heads passed required verify/E2E and fresh Greptile5/5 reviews with zero unresolved threads. Current-head CI/review is running for the two repaired heads. Local focused checks retain129 connection,59 runner,72 shared-eval and88 recovery/workspace passes, plus migration safety and token gates. The additive Copilot migration is361; released master history is preserved. [Cloud normal-package run39414239704](https://github.com/paperclipai/paperclip/actions/runs/39414239704) builds the pre-security source4f3f. All four native producers and Linux package assembly pass; the final clean installed consumers are finishing. All18 retained archives match their hashes;37,863 regular files contain zero selected credentials. That package does not contain the later route repair. The actual final published package must include it and pass the local/Daytona live canaries. The frozen Daytona image remains published and independently verified. No separate full-image scan is claimed. Docker builds run in the cloud. **Remaining:** current-head CI/review, setup and qualification merges, final publication, and ordinary local/Daytona canaries against the actual shipped package. The user explicitly authorizes the maintainer review override; CI remains a merge gate. No production deployment is claimed. Provider USD remains unknown and GitHub-attributed. ## Risks Bad credentials, missing entitlement, runtime installation and unavailable models must remain distinct failures. A connection must not adopt ambient credentials. The constraint migration changes accepted provider values, with no credential-storage migration. Current-master NewAgent fixture extraction is retained. Copilot cases use that shared support and test both passive discovery and explicit reconnect under the same setup lifecycle. The onboarding retry regression shares the component suite’s saved-connection, authenticated-model, draft, agent-list, hire and render lifecycle fixtures. Keeping it beside the existing onboarding failures makes adoption versus duplicate hire observable under the same lifecycle; this is the concrete cohesion reason for the existing large test file. ## Model Used OpenAI Codex, based on GPT-6. The exact serving model ID and context window are not exposed in this task. Used for code changes, review and tool-assisted verification. ## 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 - [ ] All Paperclip CI gates are green - [ ] 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>
Apps, Connections, and Integrations
Audience: internal engineers and product contributors working on integrations.
Start here when adding a provider: Connection authoring runbook. It is the canonical agent tutorial from provider research and protocol classification through manifest generation, branding, secrets, deterministic tests, real-account proof, and PR submission.
Runtime authentication: AI Connections.
Long-term memory: Experimental memory connectors.
Provider notes: Google Workspace, Gmail, Asana, Sentry, PostHog, Neon, Superagent, Gauge, AgentMail, Telem.AI, iMessage Photon, and Enterpret. Optional credential custody: Vercel Connect.
Post-read action: classify a new integration request, pick the right Paperclip layer to change, and avoid creating a parallel connection framework.
Decision Record
Board decisions from PAP-13211 make the Apps v2 substrate on the PAP-10341 branch canonical:
- D1: Apps v2 is the substrate. The active model is
tool_applications,tool_connections, catalog entries, profiles, policy rules, action requests, gateway sessions, audit events, and runtime slots. Connections v1 is retired as an implementation path. - D2: one credential authority per connection, brokered projections. The
default is the Paperclip instance vault: durable third-party credentials live
in
company_secretsas secret refs. A reviewed remote MCP method may instead opt in to Vercel Connect, in which case Vercel is the durable credential authority and Paperclip stores only the connector reference and redacted grant metadata. A connection must never mix those two sources. Adapter config, plugin config, harness credential files, and run environments may receive only brokered or projected credentials. - D3: the vocabulary and three-door IA are product law. The default product doors are Apps, Connections, and Review. Protocol and operator-depth concepts live behind Developer or Advanced surfaces.
- D4: unification lands on PAP-10341. Pages, CircleBack-style harness MCP OAuth, provider gallery work, and plugin-provided integrations converge on this branch instead of spawning new integration substrates.
- D5: inbound stays thin. External clients that call Paperclip use scoped Paperclip tokens and existing profiles/rules. They do not get a separate permission model.
Canonical Object Model
Use connection as the unifying noun. A connection is four things:
- A stored credential reference.
- A capability catalog.
- A governance layer.
- An audit trail.
Everything else is an axis on that object:
| Axis | Values | It answers |
|---|---|---|
| Direction | outbound, inbound | Who is the client? |
| Transport | MCP, native REST/OpenAPI, OAuth app install, webhook | How do bytes move? |
| Auth mode | OAuth, API key/PAT, app installation, none | What does the secret represent? |
| Credential owner | company, user, run | Whose identity acts? |
| Packaging | catalog entry, plugin, skill | How does it ship? |
MCP is a transport, not a product category. "Install the Discord app", "connect Google Drive", and "add an MCP endpoint" all produce governed connections with different transport/auth values.
Layer Stack
When you are unsure where a change belongs, place it on the narrowest layer that solves the problem:
| Layer | Owns | Examples |
|---|---|---|
| Surface | user-facing Apps, Connections, Review, Developer/Advanced screens | gallery cards, setup wizard, review queue |
| Governance | profiles, bindings, allow/ask-first/block rules, quarantine, audit | read-only profile, ask-first write policy |
| Capability | action catalogs, schemas, risk classes, changed-tool review | search_issues, create_comment, schema hash |
| Credential | company_secrets, OAuth broker, credential resolver, token broker |
Slack bot token ref, Google OAuth refresh token ref |
| Identity | actor attribution and token exchange | board user, agent run, first-party service identity |
| Transport | how the external system is reached | remote HTTP MCP, local stdio, REST/OpenAPI, webhook |
The agent should not hold a durable provider credential. It should hold a Paperclip run/session token; the server or broker resolves the connection, checks governance, invokes the provider, and writes audit.
Identity vs. connections
Signing a user in and connecting a resource are different planes with different owners, different token profiles, and different homes. Do not merge them. This section is the public, connections-side statement of the identity model so connector implementers inherit the rule without depending on private identity-service documentation or re-deriving it.
| Plane | Question | Lives where | Token profile |
|---|---|---|---|
| P1. Sign-in methods | Who are you? | paperclip-id (id.paperclip.ing → Account) |
Minimal-scope provider tokens (openid email profile), used once to authenticate, encrypted at rest, never exported |
| P2. Connections (Apps) | What may your agents touch? | Paperclip App instances (tool_connections), acquired via the connect broker for hosted + self-hosted |
Rich-scope, long-lived resource tokens in the instance's encrypted vault; per-agent grants; risk-tier policy defaults |
| P3. Login with Paperclip | Who may authenticate against us? | paperclip-id OIDC provider + DB-backed client registry |
Our ES256 ID/access tokens issued by us to registered RPs (instances, the broker, future third parties) |
Everything in doc/connections/ — the First-30 matrix,
the connection authoring runbook, and the connect-broker work —
lives on plane P2. It never acquires, stores, or brokers a P1 sign-in token.
The standing rule (D7)
Adopted as a standing rule (decision D7) with the identity-model plan. State it verbatim in any P2 design so the app-store work cannot drift into merging the planes:
Sign-in tokens are never reused as resource tokens; id.paperclip.ing never stores resource tokens; no connections hub on the ID service.
P2 tokens flow broker → instance vault as pass-through only; the id.paperclip.ing Account page therefore must not grow a "Connections" hub. The reasons to hold the planes apart (from the plan §3):
- Scope discipline. Sign-in wants the narrowest grant; connections want deliberately broad ones. One button that does both is how you grant repo access just to log in.
- Blast radius. id.paperclip.ing holding every customer's Vercel/Slack/GitHub resource tokens would make it the single juiciest target in the fleet; the broker is intentionally pass-through.
- Self-hosted symmetry. Instances own their vaults, so self-hosters don't depend on our uptime to use their own connections.
- Legibility. Sign-in and connections answer different user questions, and every product we benchmarked (Vercel, Railway, GitHub, Google) keeps them on separate pages with separate names.
The explicit Vercel Connect exception does not change D7 or merge P1 and P2.
The operator chooses Vercel as the P2 credential authority for an individual
connection. id.paperclip.ing is not involved, and neither sign-in tokens nor
provider tokens pass through it. The deployment's Vercel access token or
workload OIDC identity is bootstrap authority for that external vault, not a
provider resource credential.
Naming alignment
Use the surface-correct name for each plane; they intentionally differ:
| Surface | Plane | Name to use |
|---|---|---|
| Paperclip App instances | P2 | "Connections" |
| id.paperclip.ing Account | P1 | "Ways to sign in" |
| id.paperclip.ing admin | P3 | "OIDC clients" (until the app store productizes it) |
Packaging Rule
Default to a catalog entry when an integration can be described as metadata: manifest, auth config, action catalog, resource filters, and policy defaults.
Use a plugin only when the integration needs product code such as custom UI pages, its own tables, workers, migrations, routines, or specialized ingestion. A plugin may bundle catalog entries, but it must not bypass the connection, profile, policy, credential, and audit model.
Use a skill for agent instructions. Skills may use connections; they must not own durable tokens.
Canonical Docs
- Glossary defines product and internal terms.
- Identity vs. connections is the public statement of the P1/P2/P3 boundary and the D7 standing rule for connections work.
- Security threat model harvests the keeper from PAP-2359 and maps it onto Apps v2.
- First-30 matrix harvests the keeper from PAP-2432 and is the source matrix for connector playbook work.
- Connecting any remote MCP server is the baseline: how an operator connects a standards-compliant remote MCP endpoint with no Paperclip code change, and how sign-in resolves a client.
- Connection authoring runbook is the one end-to-end, agent-executable guide for adding a vendor as a catalog entry on Apps v2: research, connection-type selection, OAuth/API-key/generated-URL setup, encrypted credential handling, branding, implementation, browser and live-provider testing, verification, and PR submission.
- Vercel Connect operator guide documents the optional external credential source, deployment flags, runtime resolution, recovery, and smoke requirements.
- MCP access governance remains the operator runbook for the current gateway, profile, policy, approval, runtime, and audit APIs.
Migration Notes
Connections v1 contributed useful policy, UX, and rollout thinking, but its
implementation branch is no longer the target. When you see old tickets or code
using connections, connection_grants, or a provider-directory mental model,
translate the intent into Apps v2:
| Connections v1 intent | Apps v2 home |
|---|---|
| Provider directory | Apps gallery / tool_applications |
| Configured provider instance | Connection / tool_connections |
| Grant allowlist | Profiles, profile bindings, policies |
| Resource filters | Policy/profile conditions plus provider config |
| Tool broker | Tool gateway and runtime supervisor |
| Connection UX tail | Apps, Connections, Review, Developer/Advanced IA |
Do not add new work to the retired v1 branch. If an old ticket still describes a valid product gap, retarget it to an active Apps v2 issue or close it as superseded with a link to the replacement.
For Slack chat bot creation, installation, recovery, and live qualification, see Automatic Slack app setup.