Jannik/PaperClipAI
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-21 08:22:20 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
docs/board-api-key-authentication
PaperClipAI/feature-map/connection-setup.md
T
DottaandPaperclip cc88b61c09 feat: add portable verification skills and refresh the feature map (#15983) 
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Contributors use the feature map to select verification recipes.
> - The repository needs separate skills to create a verifier, maintain
recipes, and run checks.
> - Shared recipes must match current routes, controls, and
prerequisites.
> - This pull request adds portable verification skills and updates the
existing map.
> - The benefit is a repeatable verification workflow with clear
ownership and evidence limits.

## Linked Issues or Issue Description

Refs: #15288, which added the existing feature map. The related test
cleanup in #15978 changes test ownership; this PR changes skill
instructions and recipes.

**Issue type**

Missing documentation and outdated verification instructions.

**Where is the issue?**

The project-local skills in `.agents/skills/` and the recipes in
`feature-map/`.

**What's wrong?**

The repository lacks the portable creation and maintenance skills. The
verifier mixes live verification with map editing. Some recipes describe
old controls or omit required flags, identities, and provider setup.

**Suggested fix**

Import the skills and their complete references from Paperclip's pstack
fork. Keep the existing map in its current directory. Let the verifier
read recipes and report drift. Let the maintenance skill update the map.

## What Changed

- Add `create-verification-skill` and `maintain-verification-skill` from
the portable fork of Poteto's pstack. Include invocation policies, all
feature-map examples, self-contained attribution notices and the full
MIT license in each skill folder.
- Use the existing `feature-map/` directory and Poteto's recipe format.
Omit the fork's separate runtime skill and runtime-skill dependencies
because Paperclip supplies execution.
- Add `verify-paperclip` with executable launch, readiness, onboarding,
and cleanup helpers. Use isolated temporary data and separate evidence
directories.
- Make `verify-paperclip` consume the map and report recipe drift. Give
map editing to `maintain-verification-skill`.
- Review all 35 feature files and correct 30 recipes. Clarify routes,
flags, current controls, persistence scope, and the limits of linked
tests.
- Remove the unrelated Conference Room flag change from the onboarding
smoke helper.
- Add a standard-library ownership test. It proves that doctor and stop
reject a foreign checkout without stopping its live server. A
delayed-exit fixture also proves cleanup waits for runtime exit.
- Keep audit screenshots and scratch reports outside the repository. No
product code, migrations, lockfile, or workflow changes.

## Verification

- Passed after rebase: metadata validation for all three skills, Python
syntax and executable checks, JavaScript syntax, 35-entry map/index
consistency, relative links, license preservation, and `git diff
--check`.
- Ran one isolated live audit before rebase. Checked task persistence,
document upload/download bytes, goal hierarchy, project edits, search,
local process Agent Chat, question replies, queued-message discard/stop,
and a harmless loopback MCP call.
- Checked local settings and draft flows. Synthetic cost events reached
a small budget limit and paused the test agent. These checks do not
prove external model quality or provider billing.
- Checked cleanup of the audit server, database, local MCP fixture, and
workspace service inventory.
- Passed: `pnpm -r typecheck`.
- Greptile: 5/5 on commit `4344ac4df7`. The cleanup finding is fixed and
its review thread is resolved. A fresh review is pending for the notice
relocation.
- Passed: `python3 -m unittest discover -s
.agents/skills/verify-paperclip/tests -v`. Both tests pass: the foreign
fixture stayed alive after rejection, and owned cleanup waited for
delayed runtime exit.
- Passed: `pnpm build`.
- All GitHub CI checks were green on commit `4344ac4df7`. The cloud-auth
browser shard passed after one retry for a disposed mocked API response.
The notice relocation passed skill metadata, relative-link, and
license-preservation checks; fresh CI/review is pending.
- The full local `pnpm test:run` did not complete. It was interrupted
after nearly 30 minutes once the complete CI suite passed on the same
commit. Exit code: 130. The new helper safety tests passed locally. The
local full-suite checklist item stays unchecked.
- Full live coverage is incomplete. Authenticated multi-user checks and
external provider journeys need their own identities, credentials, and
targets.
- The corrected onboarding helper could not be re-tested after removing
the flag mutation. Two fresh launches failed before server startup.
Direct PostgreSQL initialization reported exhausted shared-memory IDs or
limits. The host had free disk space. No host-wide limits or unrelated
instances were changed.

## Risks

- Recipe drift can return as the UI changes. The map records
verification scope, not proof of a passed journey.
- The new helpers assume a source checkout with installed dependencies,
Python, Node, and `lsof`. The onboarding helper also needs Playwright.
- The local audit found observations that need separate investigation:
an action test returned fixture data while the connection control showed
Off and native profiles existed; a failed status-card setup task left
the card showing Setting up. Workspace service start also did not reach
a running state. This PR does not change product behavior or redefine
those outcomes as success.
- The main audit trace did not finalize during browser shutdown.
Screenshots, text captures, and iteration results were retained.
- Live evidence was captured before rebase. The onboarding helper
re-test and full provider/auth qualification remain incomplete.

## 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, read-only
source subagents, file edits, shell commands, and browser automation.

## 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
- [ ] 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>
2026-10-12 13:31:44 -05:00

155 lines
8.0 KiB
Markdown
Raw Permalink Blame History

# Connection setup
People connect an app or account, choose who may use it, and recover incomplete
setup from either Apps or a task that needs access. A saved draft, a completed
provider login, a usable connection, and a resumed task are separate checkpoints.
Chat channels additionally require an endpoint and linked sender identity.
## Sub-features
- `catalog`: find a provider, inspect its available methods, and open setup;
unavailable methods explain their prerequisite rather than silently switching.
- `identity-and-access`: select personal/shared identity and eligible agents;
an empty explicit selection and company-wide access must not be confused.
- `credentials`: provider sign-in, key, or generic MCP URL follows its supported
setup method; credentials are not retained in browser draft storage.
- `handoff`: provider popup/full-page callback returns to the correct setup
host with the original task intent and identity choice intact.
- `draft-recovery`: cancel, Back, Save & exit, reload, Finish setup, and reconnect
preserve the exact draft rather than creating duplicate connections.
- `task-request`: only the addressed person resolves the requested connection;
usable access releases the pending task request through normal continuation.
- `channel-setup`: provider endpoint, represented agent, linked sender, and
communication instructions are configured before an external message is used.
- `failure`: denied login, unreachable/private URL, expired credentials, and
permission errors leave an actionable state rather than a false success.
## How to get to it (user POV)
### `apps-catalog`
Open Apps (`/apps`), choose an app, and connect from its landing page. Select an
available method and access, then complete setup. Existing connections open
their details; unfinished ones offer a way to finish setup.
### `mcp-link`
Use **Connect with a link** or `/apps/byo` for a generic MCP server. Paste its
URL, select access, and follow the probe's sign-in/key guidance. Provider-specific
catalog setup and a generic endpoint may use different flows.
### `task-request`
Open the task's pending connection request and its setup action as the named
user. Setup can open in a task dialog and may use an OAuth popup. Follow the
request's original link if setup falls back to a standalone page.
### `resume-connection`
From Apps or connection details, use Finish setup, reconnect, or the offered
authentication recovery action. Reload or return from the provider before
checking whether the same saved connection became usable.
### `chat-channel`
With chat connectors enabled, select a supported chat/email provider in Apps
or open `/apps/chat/connect`. Complete that provider's endpoint setup, then
open its settings (`/apps/chat/:endpointId/settings`). Follow identity linking
as the intended sender before messaging the agent externally.
## Driving it with Playwright and the Paperclip CLI
Preconditions: follow the [baseline](./README.md#before-driving-a-journey).
Choose a disposable provider account/resource and record its auth method,
deployment mode, account ownership, and access selection. For live setup, use
the provider's documented prerequisites in the
[connector playbook](../doc/connections/CONNECTOR-PLAYBOOK.md). Automated fixtures
do not establish OAuth registration, public callbacks, or production provider access.
### `apps-catalog`
Automated: [Browse](../ui/src/pages/apps/Browse.test.tsx),
[unconnected app](../ui/src/pages/apps/AppNotConnected.test.tsx), and
[AppsConnect](../ui/src/pages/apps/AppsConnect.test.tsx) cover catalog entry,
access selection, provider-specific method choices, and setup failures with
mocked APIs. [Connection intents](../tests/e2e/connection-intents.spec.ts)
drives store and task setup against one fake provider through a useful continuation:
```sh
pnpm exec vitest run ui/src/pages/apps/Browse.test.tsx ui/src/pages/apps/AppsConnect.test.tsx
pnpm exec playwright test -c tests/e2e/playwright.config.ts tests/e2e/connection-intents.spec.ts
```
Manual: connect from an unconnected provider landing. Select the intended
identity and agent access, complete authentication, reload, and inspect the
saved connection. Run a permitted read-only action with an eligible agent and
verify its useful result. Try an ineligible agent and confirm denial. Repeat
with a user who cannot install company-wide; the UI must not imply broad access.
### `mcp-link`
Automated: AppsConnect's generic MCP cases cover probe-driven auth, private or
unreachable endpoints, preregistered clients, secret-backed headers, and unsafe
authorization URLs. These are component/API mocks, not remote provider proof.
Manual: connect a known test MCP URL through the link flow, verify its saved
endpoint and a read-only action, then repeat with a bad URL and wrong credential.
The error should explain the next action and preserve non-secret setup context.
Test no-auth and authenticated endpoints separately; never infer one from the other.
### `task-request`
Automated: [interaction card](../ui/src/components/IssueThreadInteractionCard.test.tsx)
checks addressed-user controls. AppsConnect tests cover page/dialog parity,
task-bound OAuth, popup handoff, and verifying a saved connection before closing.
The connection-intents browser suite above exercises fixture-backed continuation.
Manual: ask an agent to use an unavailable app, open its request as the named
user, and complete setup in the dialog. Verify the card settles, the exact task
resumes, and the agent returns a useful provider result. Repeat the page-host
fallback and denied OAuth path. As another user, confirm that merely seeing the
task does not grant the right to resolve the request.
### `resume-connection`
Automated: AppsConnect tests cover exact-draft resume, declined OAuth, reconnect
lookup failure/retry, response-lost creation, archived connection revival, and
saved account reuse. [App detail](../ui/src/pages/apps/AppDetail.test.tsx) covers
the connection host. These tests do not complete a real provider login.
Manual: leave setup through its footer, reload Apps, choose Finish setup, and
confirm the same connection is resumed. Decline provider login and recover from
that checkpoint. Reconnect an expired disposable account and verify a permitted
action afterwards. Count connections before/after to catch accidental duplicates.
### `chat-channel`
Automated: [setup routing](../ui/src/pages/apps/chat/ChatEndpointSetup.routing.test.tsx),
[saved setup state](../ui/src/pages/apps/chat/ChatEndpointSetup.state.test.ts),
[email setup](../ui/src/pages/apps/chat/EmailEndpointSetup.test.tsx), and
[identity confirmation](../ui/src/pages/apps/chat/ChatIdentityConfirm.test.tsx)
cover shared UI logic with fixtures. Provider-specific live setup is not implied.
Manual: complete setup for one named provider, reload endpoint settings, link
the intended sender, and send a disposable message. Verify one task and a useful
reply in the originating conversation. Inspect an unlinked sender's denial and
the endpoint's pause behavior. Repeat independently for each provider at issue;
Slack setup does not qualify Discord, Telegram, GitHub, email, or iMessage.
## Gotchas
- Private endpoint rejection depends on deployment: owned loopback MCP servers
are supported in local-trusted/private instances. Public authenticated
deployments apply the private-network restriction.
- A successful OAuth callback is not proof of saved connection access or task
continuation. Verify all three checkpoints.
- Personal identity, shared account access, and per-agent access are distinct.
Connecting an account does not waive an Off action or Ask first review.
- A tool app connection is not a chat endpoint. The same provider can offer both.
- Old Apps/Connections URLs can redirect to Apps. Use the current navigation and
record the actual destination rather than documenting an obsolete screen.
- Full provider matrix, AI-account selection, gateway/profile administration,
and account revocation lifecycles remain outside this seed recipe.
- For governed actions after setup, use [questions and approvals](./questions-and-approvals.md).
Reference in new issue View Git Blame Copy Permalink