mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-29 12:59:13 +01:00
DottaandPaperclip
b8f6d9b23f
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The feature and agent access maps describe user journeys and their permission boundaries. > - PRs #17737 and #17739 added delegated connection setup across several existing areas. > - The maps include those operations, but some recipes and board-only statements are stale. > - This PR adds usable setup recipes and corrects the access descriptions. > - The benefit is a clearer verification path that preserves human and agent authority boundaries. ## Linked Issues or Issue Description Refs: #17737, #17739. Related: #17862 changes connection setup advice and catalog choices. This PR only clarifies the existing maps. **Issue type** Outdated and missing documentation. **Where is the issue?** The paired connection setup, app permissions, chat channels, model accounts, and gateway maps under `maps/`. **What's wrong?** Delegated setup guidance sits under Gotchas without a matching driving recipe. Some model-account text still groups supported account sign-in with board-only host controls. A few callback, privacy, and native admission descriptions omit important limits. **Suggested fix** Add the missing recipes. State the current route and service boundaries. Keep existing capability IDs and distinguish source review, fixture tests, and live provider proof. ## What Changed - Add paired entry points and driving recipes for delegated setup, permission changes, and managed AI sign-in. - Describe Google consent restoration, GitHub requested credential fields and saved rotation, and Vercel personal credential attribution. - Correct the Vercel callback state checks and chat conversation/test-status privacy scope. Name the separate GitHub registration handoff endpoint. - Replace blanket board-only AI login wording with the specific managed-account and host/session boundaries. - Link the five access maps to shared native admission and work-mode limits. State the permitted self-targeted policy administration boundary. ## Verification - `node scripts/check-maps.mjs` passed: 35 paired areas and 192 stable capability IDs. This checks structure and references. - `node scripts/storybook-catalog.mjs` passed. Generated output remains ignored. - `git diff --check` passed. - Eleven selected cases in `server/src/__tests__/connection-management.integration.test.ts` passed on source `db70c5acd9`, the unchanged base of this documentation commit. They use a fresh PostgreSQL database, actual agent keys/run JWTs, human sessions, and deterministic provider fixtures. The other 61 cases were not selected. - The selected cases cover connection/profile creation, Google saved choices, native API entry points, Slack caller/target policy, GitHub import and identity confirmation, durable gateway authority, AI accounts/pools, saved human handoffs, revocation, scope, trust, and Ask/Plan denial. - Read-only source reviews checked all five areas. The disposable database was removed after the run. - Full workspace typecheck, build, and test sweep were not rerun for this Markdown-only change. Live provider login and browser journeys were not run. Per-operation source-only/not-run labels remain unchanged. ## Risks Low risk. Incorrect documentation could misstate a permission boundary or imply broader verification. The changes cite the owning routes and services and retain fixture and live-provider limits. No runtime, schema, lockfile, or workflow files change. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, repository tools, code execution, and read-only source-review agents. The session does not expose a more specific deployment 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 — existing fixtures verify this documentation-only change - [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 — CI is running and Paperclip Review is queued on the current head - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups — exact head `4d16f101968d6908f90f72b6ff6ecbb79037f168` - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
94 lines
5.8 KiB
Markdown
94 lines
5.8 KiB
Markdown
# Paperclip agent access map
|
|
|
|
This map accompanies the [feature map](../feature-map/README.md). It records APIs,
|
|
agent entry points, permission boundaries and verification for the same capability IDs.
|
|
The [shared contract](../README.md) defines the format and maintenance rules.
|
|
|
|
The [chat scenario catalog](../../tests/runner-e2e/chat-scenarios/README.md) uses
|
|
these same IDs for human requests and expected outcomes. Its scenarios retain
|
|
the access boundaries here; neither a CEO role nor a planned scenario grants
|
|
board authority or establishes a working production tool binding.
|
|
|
|
Use full capability IDs when referring to access contracts outside their file:
|
|
`onboarding/company` means the `company` capability in `onboarding.md` in both maps.
|
|
The [feature index](../feature-map/README.md#browse-features) lists feature and
|
|
capability IDs; [IDs and references](../feature-map/README.md#ids-and-references)
|
|
explains entry-point references and stable naming.
|
|
|
|
## Browse access contracts
|
|
|
|
The same-named feature recipes define navigation and capability IDs. Run
|
|
`node scripts/storybook-catalog.mjs` for the generated
|
|
`maps/generated/agent-access-map.md` index, or browse the
|
|
[published feature guide](https://d1p6rlowie26tp.cloudfront.net/storybook/branches/master/?path=/story/overview-storybook-guide--coverage-guide).
|
|
Add or update the affected companion; there is no central registration or count.
|
|
|
|
Existing baseline source references describe the original inspection, not current
|
|
verification. Record new executed evidence in the PR, issue, or CI artifact with
|
|
its revision and scope. Do not refresh unrelated headers as bookkeeping.
|
|
|
|
## Using an entry
|
|
|
|
Read its Policy and Gaps before selecting an agent path. Native fallback, legacy
|
|
REST/CLI, stdio MCP and a personal assistant connection can have different
|
|
authority and availability. Use a real admitted production binding; a scenario
|
|
declaration is not an installed tool. A `restricted` entry records current
|
|
enforcement and leaves any unresolved delegation decision visible.
|
|
|
|
For API catalog disagreements, follow the route/service authorization and record
|
|
discovery drift. For `not-applicable`, retain the concrete exception and local
|
|
path. Split shared business operations from client-only presentation.
|
|
|
|
Use `maintain-verification-skill` to reconcile changed source and both maps.
|
|
Use `verify-paperclip` and existing API/runner/MCP fixtures to collect the
|
|
permitted-agent and denial evidence; report blocked/not-run coverage honestly.
|
|
Run `node scripts/check-maps.mjs` after editing. The structural check does not
|
|
certify permissions, API catalog coverage, tool admission or live behavior.
|
|
|
|
## Native REST transport
|
|
|
|
The `call_api` parity change reconciles affected baselines against
|
|
`58e16dbddfc9c8d0cf60867f9d9847f0feda055b` and the changes in this PR. Ordinary
|
|
REST operations use the same route authorization as legacy agent REST. Dedicated
|
|
tools remain optional for those operations; protocol endpoints still need their
|
|
existing clients. Board-only routes remain restricted for agent identity.
|
|
|
|
Native `search_api` / `call_api` is enabled by default, but explicit server,
|
|
company-allowlist and binding settings can narrow admission. It requires a running
|
|
authorized native run, current task assignment and execution-run binding, company
|
|
and budget authority, task privacy, and a permitted work mode. Ask and Plan retain
|
|
mutation restrictions, and runs retain their admitted JWT scope during restart
|
|
recovery even when task mode changes. A waiting
|
|
agent does not gain independent native control just because a REST route exists.
|
|
Connection-management reads support Standard, Ask and Plan; mutations require
|
|
Standard. Skill-test runs and nonstandard task-bridge keys cannot administer
|
|
connections. These gates supplement each operation's grants, resolved resource
|
|
and target scope, and responsible-user authority. See the
|
|
[rollout policy](../../server/src/services/native-runtime/runner-api-rollout.ts)
|
|
and [connection authorization](../../server/src/services/connection-management.ts).
|
|
|
|
Credential-bearing replies, including company exports and their legacy alias,
|
|
stay inline under a 10 MiB limit and use encrypted mutation receipts. Other saved
|
|
API snapshots are limited to the issuing actor and responsible user, plus authorized
|
|
administrators. Artifact uploads enforce the same access checks as downloads;
|
|
private snapshots are excluded from company exports and public company logos.
|
|
Explicit deliverables use the existing sharing path. Native event history,
|
|
checkpoints and completion records omit API bodies while preserving receipt
|
|
metadata and replay digests. Restored webhook secrets use the same encrypted
|
|
receipt and inline response policy as newly created webhook secrets.
|
|
Task image access requires the company boundary and the task permission;
|
|
skill-test and low-trust agents do not need company-wide browsing authority.
|
|
Completion replay applies the same idempotent projection to stored and expected
|
|
payloads; [the run-log guide](../../doc/run-log-events.md) describes its fields.
|
|
|
|
Sources: [API client](../../server/src/services/native-runtime/runner-api-client.ts),
|
|
[catalog](../../server/src/services/native-runtime/runner-api-catalog.ts),
|
|
[native authority](../../server/src/services/native-runtime/paperclip-runner-tool-authority.ts),
|
|
[credential storage classification](../../server/src/services/native-runtime/runner-api-sensitive-response.ts),
|
|
[snapshot access](../../server/src/services/asset-content-access.ts),
|
|
and [history redaction](../../server/src/services/native-runtime/runner-api-log-redaction.ts). The affected entries remain
|
|
`baseline` and `source-only`; this reconciliation does not certify every operation.
|
|
Targeted real-route proof lives in the
|
|
[API integration suite](../../server/src/services/native-runtime/runner-api.integration.test.ts),
|
|
including owned routines, skill tests, scoped secrets, proposals and private export replay.
|