mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-28 20:21:50 +01:00
DottaandPaperclip
0c9d10d695
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Product and agent access maps describe the same capability IDs. > - Agent connection management changes the callable operations and permission boundaries. > - Reviewers need an operation inventory that distinguishes API access, human handoffs, and fixture evidence. > - This pull request adds saved setup screens and updates the maps for #17737. > - The benefit is that users and contributors can inspect the coverage and remaining boundaries. ## Linked Issues or Issue Description **Subsystem affected** Product and permission documentation, saved authentication setup UI and consent metadata, and product/agent access maps. **Problem or motivation** The current maps describe board-only management paths. They need to match delegated connection management and distinguish administration from ordinary tool execution. **Proposed solution** Record route operations, required grants, responsible-user limits, transport, saved authentication handoffs, provider-fixture evidence, and explicit local-operator boundaries for every connection family. **Roadmap alignment** This is the documentation companion to #17737. It covers existing Connected Apps, governed MCP gateways, chat channels, and personal/shared AI accounts. It uses existing server setup operations and adds their saved handoffs to the existing UI. ## What Changed - Show saved AI sign-in and connection setup handoffs in the existing UI. - Open GitHub import and rotation links at the required human step. Resume a committed rotation after reload without asking for another secret. - Restore saved Google service choices for the addressed user while preserving newer consent. Successful direct/cloud consent records its own timestamp, independently of refresh or lease writes; existing refresh paths preserve it. - Update product, implementation, and permission-default documentation. - Reconcile app permissions, connection setup, chat channels, profiles/gateways, and model account coverage. - Use matching capability IDs in the product and agent access maps. - Label source-reviewed operations separately from fixture-tested operations and live provider setup. - Preserve catalog creator attribution under the responsible user, with the actual agent still recorded. This follow-up moved from the implementation to keep both reviews below 100 files. This companion now changes 38 files, including the preserved Vercel personal-credential and OAuth callback attribution follow-ups alongside consent and catalog ownership. - Name the addressed-human browser-session and consent step for Slack managed authorization and installation. Preserve source-only evidence for those individual operations. ## Verification - Current companion head: `04d40cdd605452d91cf4931476eb292a210825af`, including implementation `2ecd6451d0` and master `ea727dc3c2`, 38 files. All intended companion files survive: 35 are byte-identical to the previous companion; two chat maps and qualification add current evidence. Exact-head Superagent passed and Paperclip Review supplied an actual neutral5/5 assessment with no findings and explicit no-independent-runtime/live/current-CI verification limits. Exact-head Greptile also completed at5/5 with no findings; both formerly failed shards and their verification aggregate passed on attempt2; full exact-head Linux CI workflow40446969603 completed SUCCESS. All current checks and statuses are terminal clean, with no unresolved findings. This PR remains dependent on #17737 and needs fresh checks after its required post-squash replay. The preceding 605 head’s reviews are historical after this update. Older b0ea Linux workflow success after its single rerun also remains historical. - Earlier preserved-stack verification passed **2,165 tests**: 70 assembled-server actual-auth scenarios, 27 OpenAPI contracts, 2,022 native API tests and 46 saved GitHub wizard cases in fresh PostgreSQL. The parent also passed **141 existing gateway/policy tests**. Workspace typecheck/build, maps and token gates passed. The initial typecheck IPC denial and all material intermediate regressions remain in the qualification record; no full local sweep or live provider setup is claimed. - Operation maps now cover issuer/target gateway policy intersection and post-approval revocation, bounded activity pagination through private-only windows, and native local-login encrypted receipts. The companion preserves the Vercel OAuth callback ownership change with its existing credential ownership follow-up. - Parent CI has one retained connection-intent e2e failure from a periodic-recovery timing race. GitHub refused the first job-rerun attempt while its workflow was nonterminal. Once completed, the single failed-job rerun was accepted as attempt 2 and passed, including the full parent Linux workflow. - Companion Linux server shard 4/12 retained a cleanup-idleness timeout in `login-cleanup-work.test.ts` (active work was still 1 after its five-second wait). The same unchanged cleanup suite passed all 16 cases in the parent Linux job 121950185096 and all 16 cases locally against a fresh disposable PostgreSQL database. Relevant cleanup/reaper/scheduling runtime code is unchanged. The single unchanged-code failed-job rerun was accepted as **attempt 2** on the previous `b0ea3c940f` head (workflow 40431671705). The failed shard and complete Linux workflow passed on attempt 2; no additional unchanged-code rerun was used for this failure. The first local attempt failed the existing dedicated `_test` database-name guard before running tests; the correctly named fixture passed without weakening the guard. - **Earlier 82 GitHub UI tests passed**. All three new replacement cases were red before the fix. A confirmed unchanged generation preserves the earlier copy; a changed or unreadable generation blocks copying and reconnecting. An explicit status check can restore the copy when it is still current. All earlier import, rotation, verification, and retry states remain covered. - The complete stack passed **82 API/OpenAPI tests** in fresh PostgreSQL, including 55 scenarios with real agent keys, run JWTs, human sessions, production defaults, persistence, and deterministic providers. The parent also passed **60 Copilot installation tests**, preserving published v62 and binding combined guidance as v63. - **Earlier 10 focused Google/OAuth tests passed**: eight picker cases and two local-HTTP protocol cases proving consent metadata survives concurrent token refresh. The refresh and legacy UI cases were red before the fix. These protocol fixtures use the existing injected board actor and do not count as agent-authenticated proof. - Workspace typecheck/build passed after the consent change; normal migration generation reported no SQL changes for the additive JSON metadata. The parent's latest caller-authorization correction passed server typecheck/build. Map validation and token gates passed. Maps cover 35 areas and 192 capability IDs. The specification names migration `0380_broken_aqueduct.sql`. - The test-call operation maps now record the full caller/target tool access decision (profiles, policies, and explicit grants), credential identity for every auth label, approval, and rate checks. The profile-only precondition was removed after the new permitted-access cases failed; those cases and the no-auth identity regression now pass. Saved test status requires its originating principal and current linked-task access; actual key/JWT privacy-denial evidence is recorded. - Tool-connection activity is now operation-verified: 100 events over two tasks require two capability decisions and at most two run captures (previously 100/102), preserve private-event filtering, and deny the next request after audit revocation. The regression was red before the fix. - Cloud enrollment creation and callback entries now name instance-administrator and company/principal checks. The callback is a browser return with HTML or a 303 redirect. Status reads retain their separate board-actor rule. - Operation maps identify the API, transport, authorization, evidence, and human/operator boundaries. Structural checks do not establish live provider behavior. Earlier failures and fixture corrections remain in `doc/plans/2026-10-13-connection-api-parity.md`. - An earlier companion head (`26edbe17`) received an actual Paperclip Review assessment of 5/5 with no actionable findings, published with neutral status. That review did not run tests or confirm CI, and it is historical for this new head. The prior incomplete execution result is not counted as a passed assessment. Fresh review remains pending. The duplicate enrollment findings have explanatory replies and are resolved. - The latest implementation correction passed all 55 actual-auth scenarios and 27 OpenAPI contracts (separate commands). It repairs unavailable old credential material, preserves fresh import versus configured reconnect links, and distinguishes credential field sets/completion modes in handoff keys. The new fresh-link and collision cases were red before the fix. All 41 GitHub wizard tests now pass, including filling the fresh saved handoff and asserting App import rather than reconnect; UI typecheck, maps and token gates also pass. Qualification retains the earlier failures and an incorrect OpenAPI filename that selected only the integration module before the correct separate contract run. - Configured GitHub credential-entry links carry canonical requested fields and all/any mode. The form displays and submits those values through human reconnect while retaining other saved credentials. Two webhook/client-secret cases were red before the fix; combined all/any and legacy-link cases also pass. The current UI fixes the oldbf760912baseline referenced by the duplicate main review finding. - After merging masterbaec3abd67and regenerating migration0380, the complete stack passed **128 tests** (55 actual-auth, 27 OpenAPI and 46 GitHub wizard cases), workspace typecheck/build, maps and token gates. Eight current Google UI cases also passed. The two local-HTTP OAuth cases could not initialize embedded PostgreSQL in this fresh attempt, so that attempt is not a protocol pass; the earlier ten-case evidence is historical and fresh Linux CI remains required. - The reproduced Linux automatic-Slack challenge failure is fixed by retaining verification only for the same signing fingerprint and callback URL; all eight neighboring provider compatibility cases pass. Qualification also retains the uncommitted GitHub field variant that failed initial-secret compatibility before the extension was narrowed to reconnect, and the first unmigrated external-database diagnostic. Upstream 0379 remains intact; normal generation/pruning produced additive/idempotent 0380, with repeated application verified. - Both PRs must ship together. The user authorized merging when checks pass. Merge #17737 first, replay only this companion's changes onto master, retarget this PR, and require fresh current-head CI and review before its squash merge. - The updated maps distinguish authorized bot-token/API-key setup from human verification-key entry and forbid generic channel secret-reference replacement. Actual key/JWT security baselines were red before both guards; all 82 API/OpenAPI cases, eight native receipt protections, and 49 policy-service tests now pass. The qualification record preserves the initial lifecycle/fixture/union-assertion diagnostics and the preceding Linux CI assertion failures. Maps pass on this updated stack. Fresh exact-head CI and reviews remain required. - The parent now preserves a per-field credential-change boundary before retiring saved credential-entry cards. Old health, unchanged entry, unrelated repair and retries cannot bypass it. Current authority is checked before and inside credential persistence; a real provider-time revocation regression was red before the fix. Final 82 API/OpenAPI tests, four neighboring lifecycle cases, and server typecheck/build pass. Maps pass, and qualification retains the hidden-metadata fixture failure and the measured minute-boundary rate-test failure. Production rate behavior is unchanged; only the relevant test Date clock is fixed. - After the current master/parent refresh, all **341 affected UI cases**, combined workspace typecheck/build, maps and token gates pass. The updated parent also passed **97 actual-auth/OpenAPI cases**, **141 gateway/policy cases** and **61 profile installation cases**. Published upstream Copilotv62/v63 remain unchanged; combined guidance is now v64 (`sha256:22e31f95ef972bcead98a4a707c9f33433558fd111e390e027a2bbb4346e112a`). Qualification retains the initial source-identity failure and fixture port/migration setup failures. No full local sweep, fresh local OAuth protocol run or live acceptance is claimed; fresh Linux CI must qualify this successor. - Latest review follow-up: the parent fixes caller-policy bypass in Slack tests/invitations and premature identity-handoff completion. The maps now name caller/target Block/Ask/rate intersection, one charge for a shared bucket, and the addressed human’s exact current identity link. Parent verification passes all **99 actual-auth/OpenAPI tests**, typecheck and build. The preserved combined companion passes the four focused tests (including twelve Slack policy/recipient combinations and the actual human OAuth confirmation path), workspace typecheck/build and maps. The 50 embedded-PG continuation cases were skipped locally because their database could not start; fresh Linux CI remains required. All material red/intermediate results and corrected-fixture evidence are retained in the qualification record. - Current `04d40cdd60` CI workflow40446969603 retained two new failures: server1/12 `workspace-runtime.test.ts` could not reach a fixture subprocess’s health endpoint within its ten-second readiness window (job122001926052), and chat2/3 `wakes Slack session sync from publication commit and leaves settled action queues quiet` observed one select after its idle predicate (job122001925936). Both same cases passed in parent `2ecd6451d0` Linux jobs122001920494/122001920581. The runtime and queue implementations are unchanged by this companion. Both failing cases also pass unchanged locally: two real-subprocess runtime readiness/reuse tests and the exact Slack quietness assertion against a fresh migrated PostgreSQL database. Logs: `/tmp/parity-04d-server1-failure.log`, `/tmp/parity-04d-chat2-failure.log`, `/tmp/parity-2ecd-server1-green.log`, `/tmp/parity-2ecd-chat2-green.log`, `/tmp/parity-04d-runtime-qualified.log`, `/tmp/parity-04d-chat-quiet-qualified.log`. The single standard unchanged-code failed-job rerun was **accepted as attempt2** on the unchanged exact head at `2026-10-27T04:24:30.513973+00:00` after the workflow completed. Both new failure retry allowances are now **consumed**; both failed shards and the complete Linux workflow have now passed on attempt2, including the verification aggregate. No additional unchanged-code rerun will be requested for either failure. No timing, assertion, idle-work guard or policy was weakened. If either case fails again, investigate/fix rather than rerun again. The older 5b/b0ea rerun allowances remain consumed and separate. ## Risks - Saved handoff links depend on the API changes in #17737, including the nonsecret credential-generation metadata. Both PRs must ship together. - A map can overstate operation coverage. Entries identify their evidence and retain human authentication and trusted-host limits. - Structural map checks do not prove live provider behavior. ## Model Used - OpenAI Codex, GPT-6 family, with reasoning, repository tools, and code execution. The runtime 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 — focused UI/guidance and map checks - [x] I have added or updated tests where applicable — saved setup UI tests and map validation apply - [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 — exact `04d40cdd60` full Linux CI completed SUCCESS on attempt2; all current checks/statuses are terminal clean, with an actual neutral5/5 Paperclip assessment - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups — exact `04d40cdd60` review completed with no findings - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>