mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-17 01:25:26 +02:00
DottaandPaperclip
7d9b93aee2
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Contributors use the feature map to understand and verify product capabilities. > - Agents need APIs and usable entry points within their permission boundaries. > - Product recipes and agent access need separate records with shared capability IDs. > - This pull request establishes that contract and gives maintenance ownership of both maps. > - The benefit is repeatable access review without changing product behavior or permissions. ## Linked Issues or Issue Description Refs: #15983, which added the portable verification skills and updated the feature map. This is its contract-only follow-up. Related: #15288 added the original feature map. **Issue type** Missing documentation and maintenance contract. **Where is the issue?** The product map, its missing agent access companions, and the verification skills. **What's wrong?** There is no shared convention for API presence, agent entry points, permission boundaries, access gaps, or evidence. An API declaration does not prove that a permitted native or remote agent can use it. **Suggested fix** Keep the product and agent access maps as siblings under `maps/`. Reuse capability IDs. Record representative source inventory separately from operation review and live proof. Keep both maps aligned through the maintenance skill. ## What Changed - Move the existing product map to `maps/feature-map/`. Preserve its recipes and Poteto format. Update relative links and add companion links. - Add `maps/agent-access-map/` with 35 area files and 171 matching capability IDs. Seed representative API operations, agent paths, policies and known gaps from the reviewed source inventory. Mark entries as `baseline`, `source-only`, and live verification `not-run`. - Define the shared contract in `maps/README.md`. Track API presence, agent availability, policy, evidence and review depth separately. Require operation enumeration before marking a broad capability operation-reviewed. - Extend `maintain-verification-skill` to reconcile both maps and inspect actual route policy and production tool admission. Update creation, verification, notices and contributor references to use the shared contract. - Add `scripts/check-maps.mjs` and ten regression tests. Check matching areas/IDs, indexes, references, contract fields, API method/path examples, justified exceptions and evidence-state consistency. - Keep the coverage inventory unchanged. Preserve skill invocation policies and both MIT license blocks. No product API, permission, UI, runtime helper, migration, dependency or workflow changes. ## Verification - Passed: `node scripts/check-maps.mjs` reports 35 paired areas and 171 matching capability IDs. All local map references resolve. - Passed: `node --test scripts/check-maps.test.mjs` runs ten tests. Fixtures cover missing companions, renamed/orphan/duplicate IDs, broken references, missing operation fields, empty exceptions, missing API examples, empty policy fields, and verified evidence without passed verification. - Passed: metadata validation for all three verification skills. Skill and contributor links resolve. Invocation policies and both license blocks are unchanged. - Compared relocated recipes with current master. Contents differ only in relative links and companion links. `coverage.json` is byte-for-byte unchanged. Master's updated read-only interaction test reference is retained. - Passed: `git diff --check`. The branch starts from current master and contains only this contract change. - Repository-wide typecheck, tests and build were not run locally for this documentation and Node structural-check scope. Live agent access was not exercised. Those gaps are explicit in the baseline entries; the structural check does not certify behavior. CI and automated review are pending. ## Risks - The companions are representative source baselines. They are not complete operation inventories or passed agent journeys. - The checker cannot establish actual permissions, native tool admission, operation completeness or truthful live evidence. Maintenance must inspect source and verify with the actual permitted agent context. - External links to the old product-map directory may need updates. Repository references have been updated. - Existing access gaps and board/user restrictions remain recorded. This contract does not change authority or implement missing paths. ## Model Used OpenAI GPT-6 through Codex assisted with this change. The session does not expose the exact serving model ID, configured context-window size, or reasoning setting. Capabilities used: source analysis, file edits, shell commands, and structural regression tests. ## 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>
208 lines
7.1 KiB
Markdown
208 lines
7.1 KiB
Markdown
# Connection setup — agent access
|
|
|
|
Product map: [Connection setup](../feature-map/connection-setup.md).
|
|
|
|
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](../README.md)
|
|
for format, permission checks, evidence and maintenance.
|
|
|
|
## `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](../../server/src/routes/connection-intents.ts#L130) 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.
|
|
|
|
## `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](../../server/src/routes/connection-intents.ts#L130) 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`
|
|
|
|
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](../../server/src/routes/connection-intents.ts#L130) 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.
|
|
|
|
## `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](../../server/src/routes/connection-intents.ts#L130) 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`
|
|
|
|
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](../../server/src/routes/connection-intents.ts#L130) 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`
|
|
|
|
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](../../server/src/routes/connection-intents.ts#L130) 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`
|
|
|
|
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](../../server/src/routes/connection-intents.ts#L130) 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.
|
|
|
|
## `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](../../server/src/routes/connection-intents.ts#L130) 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.
|