mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-14 17:40:37 +02:00
Devin FoleyandPaperclip
833769ab55
Replace periodic Telegram discovery and maintenance scans with bounded startup recovery, connection-specific commit notifications, and durable action deadlines. Preserve ownership, inactive subscription parking, retry and cleanup recovery, and atomic credential binding updates. Verified full typecheck/build, 30 focused scheduler tests, 12 database-backed recovery cases, all current-head CI checks, and Greptile 5/5 with no unresolved threads. Co-Authored-By: Paperclip <noreply@paperclip.ing>
216 lines
7.6 KiB
Markdown
216 lines
7.6 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.
|
|
|
|
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](../../server/src/__tests__/chat-channels.integration.test.ts)
|
|
cover recovery, rollback, retries and idle query silence; they do not establish
|
|
live provider or agent access.
|
|
|
|
## `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.
|