mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-04 11:01:16 +01:00
DottaandPaperclip
8813a50105
## Thinking Path > - Paperclip manages agent work as tasks and runs. > - GitHub chat brings repository conversations into those tasks. > - A review bot needs the assigned agent, its authority, and governed provider tools. > - The existing channel connection did not supply that review workflow or a complete setup journey. > - This pull request adds GitHub App setup, account access, event prompts, task-bound review tools, and exact-commit checks. > - Operators can inspect each review through the same task, run, and activity systems. ## Linked Issues or Issue Description **Subsystem affected** GitHub chat, governed connection tools, task execution, shared/database contracts, and connector setup UI. **Problem or motivation** Operators need a GitHub review bot that runs their assigned Paperclip agent. Mentions and PR events must preserve task ownership and requester authority. Provider publication must use the bot App identity and enforce the configured permissions. **Proposed solution** Extend the existing GitHub chat connector with resumable App onboarding, linked-member and sponsored-guest access, editable event prompts, and governed review operations. Validate structured assessments on the server and compute a stable Paperclip Review check for the exact head commit. **Alternatives considered** A separate review scheduler would duplicate Paperclip execution and permissions. Reusing personal GitHub credentials would change the bot identity and credential boundary. **Roadmap alignment** This extends the existing Connected Apps and governed-tool infrastructure. The project owner requested and approved this design. Related PR #8645 imports external Codex review feedback; this change runs an assigned Paperclip agent and publishes its results through the existing chat connector. ## What Changed - Include the current Paperclip instance origin in the copied setup prompt. Storybook uses its configured Paperclip origin; callback parameters and URL credentials are excluded. - Add a Claude/Codex copy button in the real setup and Storybook opening step. Its detailed prompt asks four setup questions and guides embedded-browser setup, verification, and optional required checks. Clipboard failure exposes selectable instructions. - Add a tutorial that explains why App installation, review scheduling, and required checks are separate choices. - Add manifest registration, an existing-App path, separate installation and repository selection, repository refresh, and explicit account confirmation. - Add low-trust agent guidance, effective capability verification, member selection, and explicit restricted guests with a sponsor. - Add configurable PR events, prompts, repository overrides, rating thresholds, and separate formal-review permissions. - Give the assigned agent governed App tools to read PRs, comment, begin an assessment, submit findings, and optionally submit a formal review. - Bind review history, root PR events, and inline replies to ordinary tasks. Deduplicate deliveries/findings and reject stale publication. - Link check Details to the underlying task on the current trusted hostname, or to Reviews before task creation. - Add schema migration 0283, API contracts, production UI, and 49 interactive Storybook states. - Repair local lease recovery. Keep the Cloud Dockerfile identical to master; no provider-pack layer or runtime-default environment variable is added. - Retry only rolled-back wake-admission transactions after transient endpoint-lock contention. A deterministic held-lock regression proves one accepted wake. ## Verification - Current head: `7ba761fe007bb798400d3e62346fa964f607f0f8`, rebased on master `d9b3a5653e41f2ee5a1345b97c86a238f7a5c8e9`. Dockerfile has zero diff against master. Final workspace typecheck and build passed. The new PostgreSQL migration regression passed and preserves existing relation and constraint identities after replay. - Greptile reviewed this exact head at 5/5. There are zero unresolved review threads and no merge conflicts. - All current-head checks are green: 54 passed and two conditional Storybook jobs skipped. This includes complete server/workspace test suites, build, typechecks, policy checks, Runner suites, browser suites, and security status. One timing-sensitive callback-ordering test passed in isolation and its CI shard passed one retry. The duplicate local full-suite run was stopped after CI completed; it is not counted as a local full-suite pass. - Before the final Slack rebase and migration renumbering, 186 focused GitHub tests, 14 native bootstrap cases, token gates, and Storybook build passed. The final rebase retained the new Slack communication guidance. - The embedded-browser setup test copied the full detailed prompt, including the configured Paperclip instance URL. Desktop and narrow layouts were checked. Component tests cover successful copying and clipboard failure with selectable text and retry. - Live local and hosted GitHub acceptance evidence refers to application revision `cb703ac959876a07ebf3d7a295847f9f351eb6fc`. Real agent tasks exercised issue mentions, automatic PR reviews, inline findings, repeated mentions, task continuation, and failing-to-passing checks after a push. The Storybook agent generated, built, and browser-rendered pages; missing acceptance text failed, matching text passed, and broken JSX produced an incomplete result. - Live cases also covered independently disabled push events, prompt injection, duplicate signed deliveries, rapid pushes, stale-result rejection, finding deduplication, and restart recovery. Formal reviews were denied while disabled and published only after explicit enablement. Check Details links pointed to the underlying task on the trusted hostname. - Those hosted native Claude runs used the provider-pack layer now removed from this PR. They do not prove native Claude works on the standard Cloud image. A replacement hosted native Codex run is not yet verified: the disposable QA tenant has only an Anthropic AI connection. No new staging or production deployment was made for the packaging removal. - Required-check merge enforcement could not be tested because the private disposable repository's GitHub plan rejected the rules configuration. Published success/failure/incomplete check states were verified directly. ## Risks - Latest master allocated migration 0282 to Slack. The GitHub migration is regenerated as 0283 with replay-safe table/index/constraint creation; a PostgreSQL regression verifies existing relations and constraints are preserved. Existing preview tenants remain subject to the fleet migration-history compatibility preflight; no bypass is introduced. - Migration 0283 adds company-scoped configuration, registration, review, and publication records. Existing connections retain their behavior until reviews/tools are enabled. - Signed webhooks and expiring registration state remain required. Hosted installations also need the companion narrow Cloud gateway exemptions. - Agent assessments can be incomplete or wrong. The server enforces coverage/result structure, current-head publication, rating policy, and separate formal-review permission; it does not replace code-review judgment. - No Cloud image packaging changes are included. Remote native ACPX/Claude and OpenCode retain their existing operator-supplied provider-pack prerequisite. Native Codex and Codex with managed MCP tools do not require that pack. Earlier staging deployment evidence refers to its stated revision, not this packaging-removal head. Production rollout and merging remain outside this change. ## Model Used OpenAI GPT-6 through Codex, with repository, code execution, API, and embedded-browser tools. The exact serving model ID and context-window size were not exposed by the environment. ## 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 - [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>
131 lines
7.0 KiB
Markdown
131 lines
7.0 KiB
Markdown
# GitHub chat and review bots
|
||
|
||
A GitHub bot belongs to one Paperclip agent. GitHub issues, pull requests, and
|
||
review threads enter ordinary Paperclip tasks; the agent's runs, permissions,
|
||
budget, and activity remain visible there. The Reviews page is a projection of
|
||
assessments attached to those tasks, not a separate execution system.
|
||
|
||
For a step-by-step explanation of mentions, automatic reviews, scores, and
|
||
required GitHub checks, read
|
||
[Understanding GitHub PR review bots](UNDERSTANDING-GITHUB-PR-REVIEW-BOTS.md).
|
||
|
||
## Set up a bot
|
||
|
||
1. Choose the permanent agent assignment. Prefer a
|
||
[low-trust review agent](https://docs.paperclip.ing/administration/trust-and-low-trust-review/)
|
||
with an isolated sandbox and a scoped task boundary. Standard-trust agents
|
||
show a warning; choosing one does not silently reduce their permissions.
|
||
2. Make the instance reachable through public HTTPS, then create an App with
|
||
manifest registration or connect an existing App. Credentials are vaulted.
|
||
3. Install the App on GitHub. Grant access only to the intended repositories.
|
||
4. Refresh the repository list in Paperclip and enable the repositories this bot
|
||
should handle. GitHub installation access and Paperclip enablement are
|
||
separate controls. Use **Configure on GitHub** to change installation access,
|
||
then refresh again.
|
||
5. Verify signed delivery, App identity, repository permissions, and the assigned
|
||
agent's effective tools/runtime separately. For existing Apps, add Contents
|
||
read, Pull requests write, and Checks write alongside chat permissions and
|
||
subscribe to pull-request events. Approve any installation permission upgrade.
|
||
6. Choose your existing personal GitHub connection and explicitly confirm the
|
||
verified account identity. That connection links your identity; the bot uses
|
||
its own App credentials for agent tools and publication.
|
||
7. Configure access, event prompts, review behavior, and publication permissions.
|
||
Save progress to resume later. The final mention test is optional.
|
||
|
||
GitHub review bots use the existing agent runtime; this connector does not add
|
||
provider software to the Cloud server image. Codex with managed MCP tools and
|
||
the native Runner Codex backend do not require a server-side remote provider
|
||
pack. Remote native ACPX (including Claude) and OpenCode currently require an
|
||
operator-supplied, build-owned provider pack configured through
|
||
`PAPERCLIP_RUNNER_REMOTE_PROVIDER_PACK_PATH`; the standard Cloud server image
|
||
does not supply one. A pack installed in the sandbox alone does not satisfy
|
||
that existing runtime requirement. Treat that provider setup as a separate
|
||
Runner prerequisite, not an automatic connector installation step.
|
||
|
||
Setup verification checks tool/runtime support and isolation; an actual test
|
||
task is still required to prove that the chosen provider can execute in the
|
||
selected environment.
|
||
|
||
## Who can start work
|
||
|
||
Linked members may be allowed together or selected individually. Teammates
|
||
connect and confirm their own accounts; an administrator cannot assert someone
|
||
else's identity by entering a username.
|
||
|
||
To admit an unlinked GitHub person, explicitly add their verified GitHub account,
|
||
choose an active sponsor, and use the restricted guest profile. Automatic reviews
|
||
for that person are a separate choice. Guests receive no company membership or
|
||
sponsor credentials. Authority is checked again before tool calls and
|
||
publication, so revocation also affects queued or ongoing work.
|
||
|
||
Automatic events use the configured responsible member. The PR author and
|
||
webhook sender are recorded independently. Follow-ups preserve task ownership
|
||
while checking the current requester's authority.
|
||
|
||
## Mentions and pushes
|
||
|
||
Use **mentions only** for reviews initiated by an authorized `@your-bot` request.
|
||
Choose automatic reviews and enable **updated commits** to review new pushes.
|
||
Opened, reopened, ready-for-review, and updated-commit events are independently
|
||
configurable. Draft and bot-authored PRs are excluded by default. Settings can
|
||
be overridden per enabled repository.
|
||
|
||
An authorized mention can bypass automatic author/branch/label scheduling
|
||
filters. It cannot bypass repository restrictions, excluded files, or access
|
||
permissions. Ordinary discussion does not change a review score. Repeat review
|
||
mentions and pushes continue the existing task; inline replies return to the
|
||
task owning that thread.
|
||
|
||
Event prompts supplement the agent's instructions. Repository content and PR
|
||
prose are untrusted input and cannot change tool authority or publication policy.
|
||
The execution records the configuration revision and event context used.
|
||
|
||
## Assessments, checks, and formal reviews
|
||
|
||
The agent reads through task-bound bot tools, explicitly begins an assessment,
|
||
and submits the reviewed commit, findings, rationale, and coverage. Paperclip
|
||
validates the result and computes the **Paperclip Review** check. The default
|
||
threshold is 5/5; choose 1–5 or report-only as needed.
|
||
|
||
| Score | Assessment rubric |
|
||
| --- | --- |
|
||
| 0 | No usable assessment; explain what prevented evaluation. |
|
||
| 1 | Critical defects make the change unsafe to ship. |
|
||
| 2 | Major defects require substantial correction. |
|
||
| 3 | Meaningful defects require correction before merging. |
|
||
| 4 | Minor concerns remain; explain impact and remaining risk. |
|
||
| 5 | No actionable defects found within the stated coverage and limitations. |
|
||
|
||
Incomplete coverage cannot pass. Filtering which findings become inline comments
|
||
does not remove them from the assessment. A new head requires a new assessment;
|
||
old runs cannot publish over the latest head. One current summary is updated in
|
||
place, with history and task/run links retained. Stable finding keys prevent
|
||
duplicate inline comments on repeated reviews.
|
||
|
||
The check's **Details** link opens its Paperclip task on the current instance
|
||
hostname, or the connector's Reviews page when no task has been created yet.
|
||
|
||
Formal **APPROVE** and **REQUEST_CHANGES** are separate governed tools, each off
|
||
by default. Enabling either does not automatically perform it. A score of 5/5
|
||
alone never approves a PR.
|
||
|
||
To enforce the rating at merge time, configure GitHub branch protection or a
|
||
ruleset to require **Paperclip Review**, selecting this bot App as the source
|
||
where supported. Paperclip does not change repository rules. GitHub account and
|
||
repository plan restrictions may limit required-check enforcement. If automatic
|
||
execution is disallowed, a gated head requests an authorized manual review.
|
||
|
||
## Hosted ingress
|
||
|
||
Cloud proxies only `POST /api/chat-webhooks/:publicId/github` and the narrow
|
||
`GET /api/chat-github/manifest/callback` registration callback without browser
|
||
login. The instance verifies the untouched webhook body and GitHub signature;
|
||
registration uses expiring, single-use user/company/origin-bound state.
|
||
Installation return, configuration, and identity confirmation remain
|
||
authenticated. URLs use the trusted current vanity hostname, with explicit
|
||
webhook-ingress overrides preserved.
|
||
|
||
Existing chat connections do not gain review execution or broader permissions
|
||
until explicitly configured. GitHub.com and UI-managed settings are the initial
|
||
scope; cross-repository indexing and auto-fix are not included.
|