DottaandPaperclip
3bbc2104b6
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The feature map records product entry points and verification recipes. > - The paired agent access map records APIs and permission boundaries for the same capability IDs. > - The new index in #16987 made several missing capabilities easier to find. > - Those gaps hid existing assistant, privacy, cost, and operator workflows. > - This pull request adds 15 capabilities with source references, test scope, and manual checks. > - Readers can find these workflows without treating documentation or structural checks as live proof. ## Linked Issues or Issue Description Refs: #16987. Related map work: #16025 and #16214. A search of related pull requests found no duplicate of these additions. **Issue type** Missing documentation. **Where is the issue?** `maps/feature-map/` and `maps/agent-access-map/`. **What's wrong?** The maps omit public assistant MCP connections, private task and project sharing, subscription fees, cost-recording recovery, agent API keys, keyboard entry points, and several operator CLI workflows. **Suggested fix** Add product recipes and matching access records. Show the full capability IDs in the README index and each page. Keep the existing ID format and all 175 existing IDs. Exclude AI account pools. ## What Changed - Add the `assistant-connections` family with setup, consent, device login, client use, and revocation. - Add `tasks/privacy`, `projects/privacy`, `budgets-costs/subscriptions`, and `budgets-costs/accounting-recovery`. - Add `agents/api-keys`, `agents/managed-agent-setup`, and `navigation-preferences/command-palette`. - Add `cli-operations/feedback-export`, `chat-channels/outbound-email`, and `instance-operations/runtime-setup`. - Pair all 15 additions with access rules, source evidence, manual checks, and explicit coverage gaps. Update the visible index to 35 families and 190 capability IDs. - Add cross-links from existing access, connection setup, search, and CLI recipes. Do not change the schema or add AI account pools. - Clarify that the task Share sheet displays direct and inherited access. Manage inherited access at its ancestor or project source. ## Verification - `node scripts/check-maps.mjs` passes: 35 areas and 190 paired capability IDs, with valid references and contract fields. - `node --test scripts/check-maps.test.mjs scripts/storybook-feature-index.test.mjs` passes: 17 tests. - `node scripts/storybook-feature-index.mjs` and `git diff --check` pass. - A comparison with the base confirms all 175 existing IDs remain and exactly the intended 15 IDs were added. The README index matches the discovered feature metadata. - `node scripts/storybook-catalog.mjs` cannot run because this checkout lacks `storybook/internal/csf-tools` and installed workspace dependencies. - `pnpm -r typecheck`, `pnpm test:run`, and `pnpm build` were attempted. All stopped before their task ran: the pnpm 9.15.4 bootstrap could not fetch and verify its registry packages in this environment. - Source review covers the documented UI, CLI, routes, services, and existing tests. No live browser, provider, or authorization journey was run. New access records remain `baseline`, `source-only`, and `not-run`. - Greptile and the Paperclip reviewer both rate current commit `bb8eb797b0a1dc26256faf2f0e57cbe7abc9adcf` 5/5. The inherited-access review thread is resolved. - [GitHub CI](https://github.com/paperclipai/paperclip/actions/runs/39466772379) passes for that commit, including typecheck, build, unit tests, Runner checks, and browser tests. Browser shard 7 passed after one retry for a runner shutdown. All PR checks are successful, neutral, or skipped. ## Risks - Low runtime risk: this change only edits maps. No application behavior, API, dependency, or schema changes. - Source-reviewed recipes can drift or miss deployment-specific behavior. The records state their limits and require live checks before a capability is marked verified. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, model ID `gpt-6.1-sol`, 475,000-token context window, xhigh reasoning effort, with tool use and code execution. ## 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>
9.8 KiB
Assistant connections (MCP) — agent access
Product map: Assistant connections (MCP).
Feature ID: assistant-connections.
This is a source-reviewed baseline of the public assistant connection boundary. The records distinguish a personal assistant acting as its consenting human from an ordinary Paperclip agent. Review and execute each listed operation before qualifying the complete capability. No live client, consent, or authorization proof is claimed. Follow the map contract.
setup
Capability ID: assistant-connections/setup.
Review: baseline.
API: present — GET /api/mcp/setup for authenticated setup metadata; GET /mcp/setup and GET /mcp/setup.md for enabled public instructions.
Agent access: restricted — an external assistant can read enabled public setup instructions, but authenticated setup management requires a signed-in human session/cloud_tenant source. A Paperclip agent, personal MCP bearer, local implicit board, or human board bearer does not supply that browser identity.
Policy: The instance enablePublicMcp gate and configured MCP/authorization origin govern public setup and transport. Authenticated management requires an actual board user from session or cloud_tenant. The copied company hint does not grant membership, scopes, or execution authority. HTTPS is required apart from the defined loopback development exception.
Evidence: source-only — reviewed at 9ef434fe79c57d976b8b03b14c5242db270b8320. Apps setup, public MCP routes, and origin/gate policy.
Verification: not-run — Inspect the invitation/resource/company from a permitted browser, then exercise a remote authorized client call only after separate consent. Reject unsupported management identities and check disabled/unconfigured setup without exposing secrets. Do not count copied instructions as a completed connection.
Gaps: No ordinary-agent self-consent or management path is established. Published plugin distribution, each client’s installation, and hosted interoperability require their own qualification.
consent
Capability ID: assistant-connections/consent.
Review: baseline.
API: present — POST /mcp/oauth/register; GET /mcp/oauth/authorize; GET /api/mcp/requests/{id}; POST /api/mcp/requests/{id}/consent; POST /mcp/oauth/token with authorization-code exchange.
Agent access: restricted — a public client can initiate registration/authorization, but the approval belongs to the real signed-in human. Ordinary agent REST/native call_api cannot manufacture a human session or browser origin to approve itself.
Policy: Public-client authorization uses S256 PKCE, exact callback/resource binding, configured origin, and the live experimental gate. Browser consent requires the authenticated session/cloud_tenant human and a matching configured Origin/Referer. Approval requires active membership in the selected unarchived company; a company hint pins selection. A viewer may approve read only. Granted scopes must be requested and explicitly accepted, and subsequent domain operations retain the person’s current permissions.
Evidence: source-only — reviewed at 9ef434fe79c57d976b8b03b14c5242db270b8320. Public MCP routes, OAuth policy, and consent/device UI.
Verification: not-run — Complete an actual client/browser authorization-code exchange and verify exact person/company/scopes by a remote tool call. Decline or expire another request; reject wrong company/origin/callback/resource/PKCE and scope escalation. A board request without the real consent identity is not acceptance evidence.
Gaps: Source fixtures establish the protocol boundary, not compatibility of every assistant/client callback or hosted signup path. Actual denied/expired browser and client states remain not run.
device-login
Capability ID: assistant-connections/device-login.
Review: baseline.
API: present — POST /mcp/oauth/device_authorization; GET /api/mcp/device with user_code; POST /api/mcp/device/consent; POST /mcp/oauth/token with the device grant.
Agent access: restricted — the device flow lets a configured client wait for human authorization. Its CLI transport does not let a Paperclip agent approve the browser decision or reuse another person’s saved credential.
Policy: Human consent retains the same company membership, viewer/read-only, requested scope, browser-origin, resource, and gate constraints as browser consent. Codes expire and are single-use; polling backoff is persisted. The CLI validates issuer/resource and requires the verification URI at the issuer’s /mcp-device, so its current journey needs matching MCP and authorization origins. It calls paperclip_connection to confirm the approved company before accepting working credentials.
Evidence: source-only — reviewed at 9ef434fe79c57d976b8b03b14c5242db270b8320. Public MCP routes, OAuth policy, and consent/device UI. MCP commands and device/credential client.
Verification: not-run — Complete one real terminal/browser request with explicit company, inspect the approved remote identity, and reuse the saved credential for a bounded read. Reject mistyped/denied/expired/replayed codes, wrong issuer/resource/company, and excess polling without saving an unauthorized credential.
Gaps: Separate authorization-origin support for the CLI is unqualified; the server can return a verification URI that the current CLI rejects. No live CLI device/stdio journey was executed. A credential-transport unit test or local proxy initialization is not proof that the waiting client was authorized.
client-use
Capability ID: assistant-connections/client-use.
Review: baseline.
API: present — POST /mcp/paperclip for MCP tools/list and tools/call. Supported modern request transport also includes server/discover and events/list, events/subscribe, and events/unsubscribe; these are protocol operations, not arbitrary REST endpoints.
Agent access: available — a configured external MCP client or the supported CLI proxy acts through the authorizing human’s grant. Each Paperclip native/remote run still needs its own actual admitted client/binding; a personal assistant connection is not automatically an agent tool or credential.
Policy: Every remote call rechecks the experimental gate, resource/client/grant/token status, expiration/revocation, human/company/membership status, scopes, and underlying domain permissions for exactly one company. The public paperclip_call_api tool permits only enumerated capabilities. An MCP bearer cannot authenticate as an ordinary REST board user or agent, and the grant confers no instance-administrator authority. The proxy does not automatically retry writes.
Evidence: source-only — reviewed at 9ef434fe79c57d976b8b03b14c5242db270b8320. MCP capabilities, per-call authorization, public MCP routes, and stdio proxy.
Verification: not-run — Prove remote identity, a permitted read and separately authorized additive write with persisted attribution. Assert private/foreign resources, missing write scope, arbitrary call_api operations, disabled gate, membership loss, and misuse of the MCP bearer at ordinary REST. Check actual client discovery rather than a declared scenario tool.
Gaps: Modern event/discovery interoperability, each external client, and all allowlisted capabilities need their own live proof. Local initialize/ping results are not evidence of remote authorization or execution.
revocation
Capability ID: assistant-connections/revocation.
Review: baseline.
API: present — GET /api/mcp/connections; DELETE /api/mcp/connections/{id}; POST /mcp/oauth/revoke for client/token/resource-bound OAuth revocation.
Agent access: restricted — browser management lists/revokes the real signed-in person’s grants. Ordinary agent/local-implicit/MCP bearer identities cannot use that human-management API; a client can revoke only a correctly bound OAuth token.
Policy: Management requires the session/cloud_tenant board user; mutations require the configured browser origin. List/delete are restricted to the current person. Another person’s ID can be a silent no-op. OAuth revocation binds token, client, and resource. Human list/revoke management remains available while enablePublicMcp is off, though remote tool calls do not. Already-delegated work retains its ordinary task lifecycle.
Evidence: source-only — reviewed at 9ef434fe79c57d976b8b03b14c5242db270b8320. Connection management, Apps management, management routes, and grant ownership/revocation.
Verification: not-run — Make a remote read succeed, revoke as the grant owner, and reject the same credential afterward. Check persisted list state, another person’s untouched grant, membership loss, disabled transport with reachable management, and OAuth token/client/resource binding. Verify task cancellation separately if required.
Gaps: Revocation is not remote-provider termination or task cancellation. The account-wide management page lacks the component coverage named by the current-company recipe. No ordinary-agent delegated human-management path or live client revocation proof is claimed.