DottaandPaperclip
ed2c22ea8c
## Thinking Path > - Paperclip manages agent work and the tools each agent can use. > - GitHub bots need their own App identity and restricted repository access. > - Manual App configuration and repeated setup gates make that connection hard to finish. > - GitHub can create an App from a manifest, but people must approve creation and repository access. > - Each Paperclip stack should own configuration, credentials, signature verification, and task admission. > - This change uses Cloud as an encrypted callback and event gateway, then completes setup in the stack. > - GitHub review bots have their own experimental setting. Chat connector opt-in does not control them. ## Linked Issues or Issue Description **What existing behavior does this improve?** Dedicated GitHub App setup, bot settings, and task-scoped GitHub replies. **Current behavior** Users must configure an App, copy credentials, repeat repository selection, and complete manual verification gates. Review settings are hard to scan. Mentions in descriptions can be missed, and automatic completion text can produce an extra GitHub comment. **Proposed behavior** Choose an agent and connect GitHub under a personal account or organization. GitHub asks for creation and installation consent. Paperclip resumes the same draft, stores secrets locally, imports access, verifies delivery, and opens Settings. Each accepted request has one editable App-owned comment for progress and results. Review assessments produce deterministic checks for the reviewed commit. **Breaking changes** GitHub bots require their own default-off experimental opt-in. The setup-method and delegated-agent screens are removed. Per-person automatic-run flags remain readable but are replaced by author filters. Existing connections, direct webhooks, saved restrictions, and manual existing-App recovery remain supported. Companion gateway: https://github.com/paperclipai/paperclip-cloud/pull/688 (merged). The roadmap and related PRs were checked; no duplicate dedicated-App wizard was found. ## What Changed - Add an independent **GitHub review bots** setting across the catalog, routes, identity admission, and task controls. Existing bots continue running when the UI setting is off. - Replace setup with Choose agent and Connect GitHub. Support personal and organization owners, inline low-trust conversion, saved drafts, known organization suggestions, automatic completion, and same-App recovery. - Keep manifests, OAuth PKCE, credential exchange, vault storage, installation verification, and original webhook-signature validation in the stack. Use the Cloud sealed gateway for public callbacks and outbound local delivery. - Add resumable owner metadata in migration 0323. Retry a failed registration renewal through the same durable replacement rather than creating another App route. - Support authorized mentions in issue and PR bodies, comments, inline comments, and review summaries. Preserve attachments, edited-source identity, duplicate protection, and lifecycle invalidation. Filter requests explicitly addressed to another connected bot. - Give agents task-scoped review, comment, and update tools. Update one working comment through progress and final output. Close coalesced requests and recover delayed acknowledgements, including deleted earlier working comments. Preserve automatic replies for legacy connections without saved review configuration. Preserve partial publication evidence and quarantine uncertain automatic fallbacks without blocking Board messages or questions. - Reorganize Settings and Access with rich slash-skill instructions, numeric passing scores, clear automation controls, formal-review tooltips, member and contributor sections, and verified App branding links. Preserve invalid score drafts and automation choices across tabs. - Paginate repositories in 20-row batches with search and a true connection-wide toggle. Batch verification at GitHub's 500-ID token limit. Keep saved repository overrides while hiding their editor. - Give each review a detail URL that remains usable beyond the newest 100 records. Synchronize the manager OpenAPI contracts and add recovery, authorization, UI, and browser regressions. - Reconcile the current master branch and retain its agent avatar, feature catalog, and extracted heartbeat preparation code. Preserve a saved test-drive port and recover from an occupied high port. ## Verification - Focused UI, independent experimental-setting, and CLI tests: 199 passed. - `pnpm -r typecheck`, `pnpm build`, and `pnpm check:token-gates` passed. The broad local Vitest attempt was interrupted after resource timeouts and stale expectations; the affected regressions passed focused reruns. The latest-head full CI matrix passed, including all browser shards, server/chat suites, builds, typechecking, canary packaging, and Docker context integrity. A Docker Hub 429 required a CI retry; it passed without changing the code. - Final review repairs: 127 attachment/event tests and server typecheck passed. All 13 final integration regressions passed under the normal CI timeout, covering legacy reply compatibility, deleted coalesced comments, inline-only review completion, progress edits, and native final recovery. Restart-safe description/review attachments passed the attachment suite. - Final regressions: four reply/lifecycle tests, both native GitHub wait tests, 171 feature-gate/reply-contract tests, the routed review preview, and five scheduler/reply regressions passed. The final fixture repair also passed all six setup-continuation cases and all three complete chat-test shards in CI, covering terminal receipts and retries under the normal CI timeout. One loaded-host receipt run exceeded its local timeout; the exact case passed in an isolated rerun and the complete CI shard. - GitHub integration tests cover personal and organization setup, retry recovery, edited mentions, attachment provenance, coalesced requests, delayed acknowledgements, partial review writes, old review URLs, and company boundaries. - Browser qualification: both GitHub journeys, all five provider setup/management journeys, and the GitHub uncertain-send recovery journey passed. GitHub setup, reconnect, and task replies run with chat disabled; chat enabled alone cannot expose GitHub bots. The disposable qualification database was removed after testing. - Earlier live qualification verified App-owned issue replies, native slash-skill invocation, progress comment edits, and a 5/5 PR review with a passing current-head check in the dedicated permissions-smoke repository. These live checks did not use personal credentials as bot execution authority. ## Risks - Deploy the merged Cloud gateway protocol before the stack update. Each callback and encrypted event must retain the original instance and tenant binding. - Migration 0323 uses idempotent column additions for test installations that already applied the earlier draft migration number. - A verified connection does not prove runtime isolation or a completed review. Runtime checks remain separate. - Required merge checks must be configured in GitHub. A passing numeric score does not formally approve a PR; approval and request-changes tools remain opt-in. - Existing-App credentials cannot silently renew an uncertain manifest exchange. Recovery preserves the existing App, draft, connection, and agent. - Repository changes save immediately. Global toggles affect all currently available repositories, including unloaded rows, without granting new installation access. - A failed or uncertain tool write suppresses automatic fallback text; the governed outbox retains its evidence. Deleted or replaced response comments are not recreated through a personal credential fallback. - GitHub logo upload remains an optional human action in GitHub App settings. Runtime provisioning, delegated setup, screenshot publication, and production push delivery remain deferred. ## Model Used OpenAI Codex, based on GPT-6, with tool use and code execution. The exact runtime model identifier and context size are not exposed in this session. ## 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 references) - [x] My branch name describes the change and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass (focused suites; complete test matrix is checked in CI) - [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>
13 KiB
Minimal dedicated GitHub App wizard
Date: 2026-10-06 Status: Implemented. Automated and local UI qualification in progress; live provider qualification pending.
Accepted scope
Support personal accounts and organizations equally through a private, user-owned GitHub App. Its identity belongs to the selected review agent. GitHub owns the creation confirmation and repository installation consent. Paperclip owns configuration, credential storage, delivery, and verification. The normal journey has two Paperclip screens:
- Choose agent, with an inline low-trust conversion when needed. Assigned drafts resume directly into Connect GitHub.
- Connect GitHub: My account or An organization, optional organization login, and an editable name suggested from the agent. Continue submits the manifest directly to GitHub. Creation returns securely to Paperclip and then goes straight to installation. Installation returns to automatic verification and completion, with conditional identity confirmation when necessary.
There is no setup-method selection, delegated setup task, copied prompt, mandatory guidance form, second repository selection, manual refresh gate, manual verification gate, or Finish action. Settings retain advanced behavior and existing-App recovery. Setup-agent assignment remains deferred.
Defaults and constraints
- Mentions-only, advisory review, linked members, guests off, no merge-rule changes. Preserve existing agent instructions and explicit bot configuration.
- Import the installation's initial repository access, including an explicit All repositories choice. Preserve saved narrower access on resumed drafts. Later additions remain disabled until selected in existing settings.
- Disclose that connecting enables the new bot's GitHub tools. Reconnect preserves existing tool restrictions.
- Use GitHub's verified App identity, including renames during registration.
- Keep runtime and isolation readiness separate from GitHub connection health. An optional test mention proves execution; connection health alone does not.
- Private Apps install on their owning account. Preserve existing public-App connections and manual credential recovery.
- Human-only steps: sign-in/MFA, App creation, repository consent, required org administrator approval, initial Cloud enrollment, unverified identity consent.
Implementation
Instance
Extend existing manager-only APIs with owner selection, draft persistence, redacted wizard progress, dedicated-App identity authorization/confirmation, and automatic completion. Bind callback state and sealed claims to the exact company, draft, connection, agent, configuring member, and enrolled origin. Retain the legacy personal registration request and direct webhook flow.
Serialize registration creation against the draft. Retry Cloud creation with its existing registration identifier and immutable binding after a lost response. Recover an uncertain manifest exchange or expired claim through the existing App; never silently create another App. Vault credentials before acknowledging receipt or exposing installation as the next step.
Use existing verified linked identities when available. Otherwise use the new App's OAuth flow, separate from its installation callback, with bound state, PKCE, one explicit identity confirmation, and transient user tokens. All bot execution continues through installation credentials.
Decrypt original provider webhook bytes from the bounded Cloud gateway queue. Authenticate their original signature in the stack before entering the existing durable webhook admission/review path. Preserve resource access, trust boundaries, revocation handling, and duplicate protection.
Paperclip Cloud
Use the existing connector broker, durable registry, enrollment, signed requests, sealed claims, webhook inbox, event leases and acknowledgments, and coalesced stack wakes as a transport gateway. No per-user tunnel is needed.
The stack builds manifests, exchanges manifest codes directly with GitHub, vaults every App secret, and owns OAuth state, PKCE, installation verification, repository access, event interpretation and recovery. Cloud stores opaque routes and hashes of callback state. It seals callback codes and original webhook bytes to the enrolled stack before durable storage. It keeps no GitHub private key, client secret or webhook verifier for dedicated Apps.
Cloud provides separate public manifest/install/OAuth callback URLs. Installation parameters never prove ownership. The stack authenticates the original webhook signature. Cloud applies bounded ingress, queue and wake limits to unverified traffic. Deduplication includes the original body and signature to prevent forged delivery identifiers from suppressing valid events.
The additive capability is available by default with the Cloud connector broker and advertises version 2; no separate enable flag is required. Deploy the additive Cloud migration and gateway before the synchronized instance wizard. Existing shared-App account connections keep their provider-specific broker behavior and secret-store requirements.
Qualification
Automated coverage must exercise both owner URLs; private manifests; bound callbacks and claims; retries after lost responses; failed and expired exchanges without duplicate Apps; hostile signatures/owner bindings; duplicate deliveries; preserved configuration and repository restrictions; identity consent/expiry; company isolation; and legacy registration/recovery.
Run focused backend/UI tests and token gates, then typecheck, Vitest, and build. Walk through the actual local UI for agent selection, account choice, save/resume, enrollment and recovery. Separately qualify real personal and organization App creation/installation and a response under each dedicated identity, with human consent. Mocked provider tests cannot establish that live qualification or runtime execution succeeded.
Evidence and remaining rollout gates
The production wizard was exercised in an isolated local test drive. Agent selection, inline low-trust conversion, organization choice, name editing, Save & exit, resume without a reload, full reload, and the conditional Cloud enrollment handoff passed. The test did not authorize Cloud enrollment or create a provider App.
The focused wizard and retained clipboard/recovery UI suites pass (37 tests). GitHub backend coverage passes (193 cases), including both owner types, interrupted registration and vault storage, empty saved repository selections, localhost configuration, concurrent identity attempts, enrolled-origin recovery, tenant binding, and legacy callbacks. The complete OpenAPI suite passes (13 tests). Workspace typecheck, build, and UI token gates pass. The revised GitHub browser journey passes through manual recovery, identity confirmation, automatic completion, settings, and reconnect.
The full local Vitest run reported 16,080 passing tests, nine failing tests, and three suites with database-startup timeouts. All ten failing suites passed in isolation (303 tests). The original full run remains a failed run; it is not a claim of a green full suite. CI initially identified outdated wizard expectations and missing API documentation, both now covered by the updated focused checks. The full GitHub fixture also verifies installation permissions and preserved legacy tool authority. The browser report attaches screenshots of both wizard screens. Fresh manual App imports initialize repository access and tools without a registration row; interrupted imports resume those defaults while explicit restrictions stay preserved. A real vault-write interruption stays in recovery without completing an empty import; retrying the credentials discovers and imports the actual repositories.
The earlier Cloud qualification tested a Cloud-owned App lifecycle. The
2026-10-07 architecture revision replaces that lifecycle with the gateway
boundary described above. Its standard npm test passes: 2,552 tests and 73
conditional skips. Gateway regressions verify sealed callback and webhook
storage, route/tenant binding, removed instances, renamed origins, forged
identifier suppression, lease/acknowledgment and queue limits. Cloud typecheck
and routing/sleep/wake smoke checks pass.
The revised stack passes workspace typecheck and build. Focused tests cover
local manifest exchange, interrupted vault storage without repeated exchange,
secret rotation without disclosing it to Cloud, original-signature verification,
and nested-envelope binding. Initial follow-up database attempts were blocked by
exhausted host shared-memory identifiers (shmget: No space left on device).
After slots became available, disposable Cloud Postgres qualification passed all
seven tests, including independent-pool quota races and lease/acknowledgment.
The focused stack cases also execute again; the added recovery case requires all
manifest credentials, including OAuth client credentials, after a partial vault
write. Explicit existing-App recovery switches to the supported personal-connection
identity path only after the same App's credentials are vaulted; it still repairs
the webhook locally and requires fresh signed delivery. Member account-only
linking avoids manager setup APIs and retains personal-connection onboarding.
The final focused wizard/recovery/member-linking tests pass (26), as do server
and UI typecheck/build and token gates. Full-suite local failures remain separately
reported rather than treated
as a green run. The current PR heads require fresh CI and review. No real
provider calls or deployments were used for this revision.
Before rollout, apply the additive Cloud migration and deploy the gateway, then deploy the synchronized instance migration and wizard through the existing connector rollout control. A real personal and organization registration, installation, consent, signed delivery and bot response remain required. No deployment, real App creation, installation, runtime provisioning, or model execution was performed by the local UI walkthrough.
Deferred follow-up: production push delivery (2026-10-08)
Use push as the primary Cloud gateway-to-stack transport in production so new mentions, issues, and PR events arrive promptly. Wake sleeping hosted stacks when needed. Keep polling as a recovery and catch-up path for missed pushes, disconnects, and restarts, rather than the normal production delivery path.
Retain the durable inbox, delivery acknowledgments, tenant bindings, original GitHub signature verification, and deduplication across push and polling. Localhost and self-hosted instances can continue using outbound polling. This is a deferred improvement; do not implement it in the current setup work.
Live setup finding: slow repository verification (2026-10-08)
The personal-account Animal Bot Man setup received a verified signed ping at 10:31:10 UTC. Its wizard still showed the previous ping-wait response while connection verification checked 86 enabled repositories, once in progress and again under the credential lease before activation. The next setup response completed at 10:32:03 UTC; missing HTTPS was not the cause.
Verify explicit enabled repository IDs in batches within GitHub's 500-ID limit, preserving the final check under the activation lease. Never request an unscoped token or pass these verification tokens to agents. A failed batch remains unverified. As soon as endpoint polling observes signed delivery, replace the old ping-wait message with App/repository verification progress. Keep the same App, vault, agent, and GitHub-selected repository access.
Focused tests cover 86- and 501-repository verification, disabled selections, revoked access, and the UI receipt arriving ahead of a full progress response. The existing draft reached connected without a new App or credential entry. After restarting the preserved test drive with the fix, this same App's full progress verification returned connected in 2.74 seconds, with all 86 repository checks passing and the configuration still at revision 1. Server/UI typecheck and builds, 24 focused backend tests, 19 wizard UI tests, and token gates pass. Connection completion remains separate from proving a model or review run.
GitHub's installation-token documentation specifies the 500-repository limit and prohibits granting access beyond the installation's authorized repositories.
Prior findings retained
Earlier setup research found repeated interviews, missing manager APIs, tunnel requirements, runtime provisioning, and image-delivery limitations. This wizard supersedes its onboarding approach. Setup agents, runtime provisioning, and screenshot publication are deferred; GitHub connection completion must not claim any of those are working.