mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-13 15:55:46 +01:00
148d2b629c9e2edaed2f731ff057036480db2cc3
15
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Nicky LeachandClaude Opus 5.5
|
ff8ec41e6a |
feat(runner): upgrade ACPX to 0.22.0 and move patched behavior into Paperclip (#20770)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Paperclip Runner and the shared `adapter-utils` engine run ACP agents through the embedded ACPX library > - Paperclip pins ACPX 0.13.1 and keeps a large patch (`patches/acpx@0.13.1.patch`) on it > - ACPX 0.22.0 adds host hooks (`onAcpMessage`, `assertActive`, `processLifecycle`, prompt-response `_meta`, `spawnAgent`-friendly launch) that make much of that patch unnecessary > - A large patch is expensive to port and hides behavior that belongs to Paperclip > - This pull request upgrades to ACPX 0.22.0 and moves most patched behavior into Runner and `adapter-utils` > - The benefit is a patch that is 484 lines instead of 1,334, with the moved behavior covered by Paperclip tests ## Linked Issues or Issue Description Refs #20675, #14430, #15075, #17942, #9980 **Proposed enhancement** Upgrade the embedded ACPX library from 0.13.1 to 0.22.0. Keep only the patch behavior that stock 0.22 cannot express. **Motivation** The 0.13.1 patch held behavior that Paperclip owns, for example usage receipts, Copilot policy, model checks and the agent environment. Each ACPX upgrade had to port all of it. ACPX 0.22 gives hooks that let Paperclip do this work itself. **Current behavior** Runner and `adapter-utils` depend on 1,334 lines of patched ACPX 0.13.1 code. **Expected behavior** Runner and `adapter-utils` use ACPX 0.22.0. The patch keeps only: extension methods, Cursor subagent routing, event `_meta` and the message boundary chunk, the protocol guard hook, `spawnAgent`, and `requestExtension`. ## What Changed - ACPX 0.13.1 → 0.22.0 in Runner, `adapter-utils`, the server, the Daytona runner images and the qualified profiles (`acpxVersion`). `@agentclientprotocol/sdk` moves to 1.9.0. - New `patches/acpx@0.22.0.patch` (484 lines). The 0.12.0 and 0.13.1 patches are removed. - Delivery receipts: Runner confirms a permission reply when `onAcpMessage` sees the exact outbound reply. Question and extension replies count as delivered when Runner hands them back to ACPX. New `interaction-delivery.ts`. - Copilot policy: the existing policy function runs from `onAcpMessage`. A violation stops the agent, cancels later permission requests and fails the next prompt through `assertActive`. - Model selection: stock 0.22 validation, plus a sidecar gate (`createAcpxEffectiveModelGate`) that refuses a prompt if the agent reports another model. Grok binds its model when the session opens. Antigravity adds its concrete model to the model list ACPX reads. - Typed session failures: Runner and `adapter-utils` read them from the turn result `_meta` and fail the turn. They advertise the capability themselves. - Pi and Cursor usage receipts: a collector (`prompt-receipts.ts`) binds them to the turn's own `session/prompt` reply. - Goal capability: Runner reads it from the `initialize` reply. It keeps it under `paperclip.goalCapability` in the saved agent capabilities `_meta` and restores it when a saved session loads. - Agent environment: Runner and `adapter-utils` set the agent environment in `spawnAgent`. ACP terminals keep their current environment. `adapter-utils` blocks inheritance of `XAI_API_KEY` and refuses to start if the server has an `ACPX_AUTH_*` variable. - `adapter-utils` spawn hooks (`spawnCwd`, stderr, `onAgentSpawn`): a new `stockAcpRuntimeOptions` maps them to stock `spawnAgent` and `processLifecycle`. - Windows: ACPX 0.22 rejects raw command strings on Windows. `adapter-utils` now passes an argv array there. - Grok rules: a Runner guard (`grok-session-rules.ts`) writes `session/new` `_meta.rules`. - Turn-dispatch journal (#20675): ACPX 0.22 ignores errors from `onAcpMessage`. The adapter keeps a failed `dispatched` write and throws it from the turn's `assertActive`. ACPX calls `assertActive` before the prompt write, so the write still stops. The real-ACPX test now checks this route. `docs/durable-recovery.md` is updated. - Plan events: the sidecar reads 0.22 `status` events tagged `plan`. - CI: the backup-checkpoint lane now installs through the shared `setup-ci-dependencies` action, like PR CI, so it resolves a stale `pnpm-lock.yaml` in place. It runs on any root `package.json` change, and pull requests never commit the lockfile, so its own frozen install failed on dependency changes. - Tests that checked removed patch internals are removed or rewritten: the response-delivery, Cursor-usage and Pi-receipt package contracts, and the goal-persistence packaging test. New unit tests cover the moved behavior. ## Verification Local runs on macOS (darwin-arm64), Node 26, on the rebased head: - `pnpm --filter @paperclipai/paperclip-runner exec vitest run src/drivers/acpx src/cli`: 2,000 passed. - `tsc -p packages/paperclip-runner/tsconfig.json` and `tsconfig.test.json`: no errors, except the existing `@paperclipai/paperclip-eval-kernel` build gap in `workflow-harness.ts`. - Runner package contracts (`node --test test/acpx-*-package-contract.test.mjs test/acpx-sidecar-contract.test.mjs`), `scripts/build-inputs.test.mjs`, `scripts/contracts/contract-fingerprints.test.mjs`, `scripts/acpx-patch-packaging.test.mjs`: all pass. `node scripts/generate-acpx-sidecar-contract.mjs --check` passes. - `cargo test -p paperclip-runner-core --test acpx_park_preparation --test acpx_park_readiness --test acpx_warm_attachment --test native_provider_backend`: 86 passed. `cargo fmt --check` passes. - `adapter-utils`: `tsc` clean. `vitest run src/acpx-engine src/mcp-isolation.integration.test.ts`: 457 passed (one Gemini flag test failed once under load and passes when run alone). - Adapters: `claude-local` and `codex-local` `acp.quota.test.ts` (23 and 39 passed), `grok-local` (149 passed). - Server: `scripts/prepare-runner-vendor.test.mjs`, `native-session-executor.test.ts`, `quarantined-task-retry.test.ts` (1,416 passed). - `cargo test -p paperclip-runner-core --lib -- previous_acpx_release acpx_upgrade unrestorable_saved_sessions`: 3 passed. `node --test test/acpx-session-carry-forward-package-contract.test.mjs`: passes. - `patch -p1 --forward` on a clean `acpx-0.22.0.tgz` gives output identical to the port. - Under full-suite load, some Runner live and recovery tests time out. Each one passes when run alone. Full regression is left to CI. Not run: live provider runs (they need provider credentials), the opt-in Kimi live peer test, the Gemini filesystem smoke test, and Windows. ## Risks - Previous-release story: sessions saved by the previous release (ACPX 0.13.1) carry forward. ACPX 0.22 loads the session records 0.13.1 wrote. Runner moves a saved descriptor that names 0.13.1 (`CARRIED_ACPX_RELEASES`) to 0.22.0, and the sidecar keeps 0.13.1 as the ACPX value in the session identity, so the saved session key and identity record still match. The existing launch-profile rebind still decides which sessions resume: a settled session, or the same run's interrupted turn through lost-turn recovery. A session saved by any other ACPX release is still refused as `provider_state_incompatible`. `rules/acpx-profile-identity.mdc` and `docs/durable-recovery.md` now describe this. - Proof: `acpx-session-carry-forward-package-contract.test.mjs` resumes a session record written by the real ACPX 0.13.1 with its Paperclip patch. 0.22 loads the same provider session (no `session/new`), runs a turn and keeps the earlier turn. Rust tests cover a settled 0.13.1 session that the next run attaches to, and a turn interrupted by the upgrade. A recovery-identity test checks that the session key and identity record match across the versions. - `pnpm-lock.yaml` is not committed. CI resolves it for each run, and the lockfile refresh workflow updates it after merge. - Behavior change on the server: `adapter-utils` refuses to create an ACPX runtime if the server environment has an `ACPX_AUTH_*` variable. Before, ACPX ignored such variables. Stock 0.22 would use them to authenticate agents with server credentials. - Delivery confirmation is now Runner-owned. A permission reply is confirmed by the exact outbound message. Question and extension replies are confirmed when Runner hands them to ACPX, not when the pipe accepts them. - Users can select only models that the agent advertises. Stock 0.22 rejects other model IDs (Claude is exempt). - ACP terminals keep the sidecar or server environment, as before. This existing exposure is not changed by this pull request. - The `adapter-utils` Gemini version probe now runs with the server environment plus the run variables, not the run variables alone. - The pack contract digest and profile `acpxVersion` change, so Daytona needs a new runner image. - Grok launch flags (`--model`, `--reasoning-effort`) were checked on 1.0.13 but session open needs a login, so Grok keeps the existing `_meta` path. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, in Claude Code with tool use (shell, file editing, subagents). Extended reasoning was used. ## 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
DottaandClaude
|
b5f62b3384 |
docs(rules): correct the scope of the API route and company-scope rules (#20596)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - `rules/*.mdc` holds the architecture rules that reviewers and agents apply to a change > - Pull request #20585 added two rules: API route expectations and company-scope exceptions > - Review found that both rules state more than is true for the current code > - A rule that is too broad makes reviewers flag correct code and can make an agent add a wrong check > - This pull request corrects the scope of both rules and fixes one stale pointer > - The benefit is rules that match the code they describe ## Linked Issues or Issue Description Refs #20585 **Issue type** Incorrect contributor documentation. **Where is the issue?** `rules/api-route-expectations.mdc`, `rules/company-scope-exceptions.mdc`, `AGENTS.md` section 8, and `.agents/skills/honeycomb-tracing/SKILL.md`. **What's wrong?** - The API route rule said that every route checks company access. Instance-level routes such as `health.ts`, `liveness.ts`, `ready.ts`, `public-mcp.ts` and `org-chart-svg.ts` do not, and must not. - The API route rule told reviewers to flag each status code outside a list of seven. `429` and `503` are correct in some routes. - The company-scope rule said that it lists the only instance-wide data. `user_sidebar_preferences` is instance-wide and was not in the list. - The company-scope rule said that it applies to new files that its `globs` cannot match. - The `honeycomb-tracing` skill pointed to `AGENTS.md` for the Telemetry workflow. That text is now in `rules/data-paths.mdc`. **Suggested fix** Limit each rule to what is true, and repoint the skill. ## What Changed - The API route rule and `AGENTS.md` section 8 now apply to routes that read or write company data. - The API route rule names the instance-level routes and says not to add a company check to them. - The status code list is now a list of common codes. Reviewers flag an incorrect code, not an unlisted code. - The company-scope rule lists the sidebar company order as an instance-wide exception, in the text, the `globs`, and the Greptile scope. - The company-scope rule says "known data" and no longer claims to match new files. - The `honeycomb-tracing` skill points to `rules/data-paths.mdc`. ## Verification - Read the two rules and confirm that each named file exists. A local script checked the `globs` and the route names. - Confirm that `.greptile/files.json` is valid JSON and that its scope matches the rule `globs`. - No source code changed. No test suite ran locally. ## Risks - Low risk. The change is documentation only. - The list of instance-level routes can go out of date when a route is added. ## Model Used - Claude (Anthropic), in Claude Code with tool use. - `claude-fable-5-2`. ## 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com> |
||
|
DottaandClaude
|
84007892e9 |
refactor: move AGENTS.md section detail to docs and rules, add a bug-fixing section (#20585)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - `AGENTS.md` is the instruction file that each human and AI contributor reads before a change > - Pull request #20557 shortened the file, but several sections still held detail that applies to only some changes > - The scoped-rules section told agents to read each matching rule in full, and most changes match five rules > - The core engineering rules mixed three product invariants with process conventions > - This pull request moves that detail to the docs and to scoped rules, and adds a section on how to fix a bug > - The benefit is a 211-line file that states what applies to every change and points to the rest ## Linked Issues or Issue Description Refs #20557 **Issue type** Outdated or unclear contributor documentation. **Where is the issue?** `AGENTS.md` at the repository root, and `rules/`. **What's wrong?** - The scoped-rules section made agents read the full body of each matching rule before a change. The rule bodies total about 47 KB. - Sections 4, 6, 8, 9 and 10 repeated detail that belongs in `doc/DEVELOPING.md`, `doc/DATABASE.md`, a route rule, `DESIGN.md` and `CONTRIBUTING.md`. - Section 4 had a database reset command for `data/pglite`. That directory does not exist. - Section 5 had seven rules. Four of them were process conventions or path-specific detail. - The file did not say how to fix a bug. **Suggested fix** Make the rule headers the index. Move section detail to the document or rule that owns it. Keep only the three invariants in section 5. Add a bug-fixing section. ## What Changed - The scoped-rules section now tells agents to list the rule headers with one `grep` command. Agents read a rule body only for a design decision in its area, when the description is not sufficient, or when a reviewer cites it. - `rules/README.md` says that each `description` must state the required behavior in one sentence. - `rules/pull-request-review.mdc` has a description that states its requirements. - Section 4 (dev setup) and section 11 (pull requests) now point to `doc/DEVELOPING.md` and `CONTRIBUTING.md`. - The schema change workflow moved from section 6 to `doc/DATABASE.md`. - The API and auth expectations moved from section 8 to the new `rules/api-route-expectations.mdc`. - Section 9 links to `DESIGN.md` for design rules. `AGENTS.md` no longer tells contributors to run `pnpm check:token-gates`. - Added section 10, "Fixing a Bug": reproduce the error, write a failing test, write the fix, see the test pass, and verify the fix. - Section 5 now has three rules: company scope, contract synchronization, and the control-plane invariants. - The company-scope exceptions moved to the new `rules/company-scope-exceptions.mdc`. - Removed the strategic-docs rule. The plan-doc convention moved to the repo map. The artifact rule moved to section 7. - Removed rule 7. Five code comments that cited `AGENTS.md §5.7` now cite `rules/data-paths.mdc`. - Regenerated the SDK public source pin, because one of those comments is in `packages/shared/src/crash-points.ts`. - Added both new rules to `.greptile/files.json`. - The API route rule applies only to routes that read or write company data. Its status code list is a list of common codes. - The company-scope rule lists the sidebar company order as an instance-wide exception. - The `honeycomb-tracing` skill now points to `rules/data-paths.mdc` for the Telemetry workflow. ## Verification - Open `AGENTS.md` and confirm that each link resolves. A local script checked this. - Run `grep -E '^(description|globs|alwaysApply):' rules/*.mdc` and confirm that each rule prints a description. - Run `node tests/runner-e2e/source-sdk-public-inputs.mjs <HEAD> --check`. It passes locally. - `packages/shared/src/crash-points.test.ts` passed locally before the rebase onto `master`. - Five source files changed in comments only. No other test suite ran locally. ## Risks - An agent that reads only rule descriptions can miss a detail in a rule body. Reviewers still apply the full rules. - Pull requests and the definition of done are now sections 11 and 12. Sections 1 to 9 keep their numbers. - Dated plan documents under `doc/plans/` still cite `AGENTS.md §5.7`. They are historical records. - Pull request #20565 also changes `AGENTS.md`. The second one to merge needs a conflict fix in section 1 and section 2. ## Model Used - Claude (Anthropic), in Claude Code with tool use. - `claude-fable-5-2`. ## 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude <noreply@anthropic.com> |
||
|
DottaandClaude
|
b004519fde |
docs(agents): shorten AGENTS.md and move data-path detail to a scoped rule (#20557)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - `AGENTS.md` is the instruction file that each human and AI contributor reads before a change > - The file had 311 lines, and most of the text applied to only a few areas of the repository > - The file told each contributor to read five documents before every change and to treat `doc/SPEC-implementation.md` as the build contract > - The file listed 4 of the 12 rules in `rules/`, so the list was already out of date > - This pull request states contributor ownership, makes the code and tests the source of truth, and moves path-specific detail into a scoped rule > - The benefit is a shorter file that agents load on every session, with detail that loads only for the files it applies to ## Linked Issues or Issue Description **Issue type** Outdated or unclear contributor documentation. **Where is the issue?** `AGENTS.md` at the repository root. **What's wrong?** - The file told contributors to read five documents in order before each change. - The file made `doc/SPEC-implementation.md` the build contract and part of the definition of done. The maintainer considers that document outdated. - The file kept a manual list of scoped rules. The list named 4 of the 12 rules. - Rule 7 (the three data paths) used about 40 lines. The rule applies only to telemetry, observability, and run-log files. - The agent preflight instruction was in the verification section, not in the setup section. - The design system section had no number and came after the definition of done. **Suggested fix** Keep in `AGENTS.md` only the text that applies to every change. Move path-specific text to `rules/` and point to `doc/` for detail. ## What Changed - Added an ownership statement at the top of `AGENTS.md`. - Section 1 now says that the code and tests are the source of truth. The spec documents are background. - Removed the spec from the definition of done and from rule 4. - Section 2 is now a table that maps a type of change to the document to read. - Removed the manual rule list. The instruction to read each matching rule in `rules/*.mdc` stays. - Moved agent preflight to section 4. The database reset step now says that it deletes local data. - Rule 7 is now a short summary. The full text is in the new `rules/data-paths.mdc`. - Added `rules/data-paths.mdc` to `.greptile/files.json` with the same scope as the rule globs. - `CONTRIBUTING.md` now links to the new rule. - Section 7 is now the default command and six labelled rules. Maps and Storybook are one subsection. - The design system text is now a subsection of section 9. - Section numbers did not change, because code comments cite `AGENTS.md §5.7` and `§6`. ## Verification - Open `AGENTS.md` and confirm that each link and each path resolves. A local script checked this. - Compare `rules/data-paths.mdc` with the old rule 7 text. The definitions and review levels are the same. - Confirm that `.greptile/files.json` is valid JSON and that the new scope matches the rule globs. - No source code changed. No test suite ran locally. ## Risks - Contributors no longer treat the spec as a requirement. A change can now differ from the spec without an update to the spec. - An agent that does not read scoped rules gets only the summary of the three data paths. The summary keeps the review level for each path. - Two Storybook instructions now live only in `maps/README.md` and `maps/storybook-map/README.md`. ## Model Used - Claude (Anthropic), in Claude Code with tool use. - `claude-opus-5-5` added the ownership line and did the first review. - `claude-fable-5-2` wrote the restructure and this pull request. ## 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com> |
||
|
DottaandClaude Opus 5.5
|
a4050187ec |
docs(rules): make upgrade safety part of run and recovery design (#19827)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Native runs save session, checkpoint, lease, and launch state, and recovery resumes that state later > - Deploys and restarts often land between the save and the resume, so one release resumes state that another release saved > - On 2026-11-06/07, staging deployed four times. Most of 182 failed runs were saved by one release and resumed by another (#19462, #19659, #19755) > - These refusals showed as the generic retryable `native_session_interrupted`. Retries repeated them, and recovery replaced a thread (now prevented by #19733). Remote-only code also shipped without a test that applied Daytona confinement (#19743) > - This pull request makes upgrade safety a required part of how we design, fix, and review run and recovery code > - The benefit is that authors, agents, and Greptile check the release cutover before a change ships, not after a deploy breaks saved runs ## Linked Issues or Issue Description Refs #19462, Refs #19516, Refs #19622, Refs #19659, Refs #19733, Refs #19743, Refs #19755 **Issue type** Missing contributor guidance for run and recovery code. **Where is the issue?** `.agents/skills/fix-failed-paperclip-run/`, `rules/`, `AGENTS.md`, and `doc/execution-semantics.md`. **What's wrong?** No rule or skill step asks how state saved by the previous release is handled. Fixes added one error code at a time. Saved-identity refusals used a generic retryable code. **Suggested fix** Add a scoped repository rule and additive skill and contract text that require a previous-release story, permanent named refusal codes, and cutover tests. ## What Changed - Add `rules/upgrade-safe-run-state.mdc`. It covers native runtime, recovery, session preparation, runner, ACPX engine, and sandbox image paths, and the `packages/db` schema for native run, checkpoint, session, and run identity state. It requires authors to state how previous-release state is handled. It requires a permanent, named code for unknown or changed saved identity, a class-level fix, an old-saved/new-resumed regression, a deploy-lands-mid-run case where relevant, and a remote-confinement test for sandbox paths. - Register the rule in `.greptile/files.json` with the same scope as its `globs`. - Link the rule from the "Scoped repository rules" section of `AGENTS.md`. - `fix-failed-paperclip-run` skill: step 1 asks if a deploy or restart separated save from resume, by comparing served revisions. Step 2 asks this early. Step 4 adds a "Persisted run identity across releases" safety row and an upgrade-safety paragraph. - `references/failure-patterns.md`: add "Saved run state meets a different release". - `doc/execution-semantics.md`: add §9.4 "Release compatibility of saved run state". ## Verification - Docs, skills, and rules only. No product code changes. - Confirm that each rule glob matches real paths, for example `server/src/services/native-runtime/`, `server/src/services/recovery/`, `server/src/services/heartbeat/session-preparation.ts`, and `packages/adapter-utils/src/acpx-engine/`. - Confirm that `.greptile/files.json` parses and that its new `scope` array equals the rule's `globs`. - `rules/README.md` names no lint check for rules. I did not edit maps, so `node scripts/check-maps.mjs` does not apply. ## Risks - Low risk. The change adds guidance only. - The rule scope includes all of `packages/paperclip-runner/**`. Greptile can apply the rule to runner docs or UI files. The rule's exception section says that changes with no persisted shape or identity need no cutover test. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code execution in Claude Code. ## 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
Nicky LeachandClaude Opus 5.5
|
832ede93ed |
fix(apps): stop the Connectors page from pegging the CPU on managed instances (#19380)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The Connectors page (`/apps`) merges native connectors with about 1,600 apps from the Composio and Arcade catalogs > - #19328 made some native connectors yield to aggregator sign-in on managed instances. To decide, it checks whether any aggregator serves each native row > - That check scans the whole catalog. It runs once per native row for every catalog app, so one pass makes about 1,600 × 110 × 1,600 name comparisons > - The pass also re-runs on every render, because a memo dependency is a `Map` rebuilt in the component body. Aggregator polling keeps renders coming > - On a managed instance, the page pegs a CPU core and does not become usable. Self-hosted instances skip the branch, and the tests used one or two catalog entries, so nothing caught it > - This pull request makes the check a set lookup, keeps the memo inputs stable, and adds a test at shipped catalog scale plus a general review rule for rendering large collections > - The benefit is that `/apps` loads normally on managed instances again, and similar regressions fail a test or get flagged in review ## Linked Issues or Issue Description Refs #19328 Refs #19247 **What happened?** On a managed instance, opening `/apps` pegs the CPU at 100%, and the page is very slow or unresponsive. **Steps to reproduce** 1. Open a managed instance (`useCloudInstance()?.managed === true`). 2. Go to `/apps`. 3. The tab holds a CPU core at 100%. **Expected behavior** The Connectors page renders in well under a second, and it does not re-run catalog work on unrelated renders. **Root cause** In `ui/src/pages/apps/Browse.tsx`, `yieldsToAggregators()` calls `hasAggregatorRoute()`. That function scans every aggregator catalog entry with regex normalization. The `managedCatalog` loop calls `yieldsToAggregators()` for every native row, for each of about 1,600 catalog apps. A Node benchmark with the shipped catalog data measured about 214 s per pass on a managed instance and 40 ms self-hosted. The `rows` memo depended on `upstreamAppsBySlug` and `gallery`, which were rebuilt on every render, so the memo never reused its result. ## What Changed - Index every aggregator identity once (`managedCatalogIdentities`), so the aggregator route check is one `Set` lookup. - Cache each slug's yield decision for the pass. Rows hold their final connections and chat endpoints by then, so the answer cannot change. - Normalize native row identities once before matching them against catalog apps. - Memoize `gallery`, the aggregator snapshots, `upstreamAppsBySlug` and `managedCatalog`. A small `useShallowStableItems` helper keeps the per-gateway `useQueries` data stable, so the `rows` memo runs only when connector data changes. - Match catalog apps to native rows through an identity-to-row index instead of scanning the native rows for each catalog app. The earliest row among an app's alias lookups is the row the old ordered scan found. - Add a test that loads the shipped aggregator catalog and every native connector in managed-instance mode, with a saved Composio gateway and account. It counts `aggregatorAppIdentity` calls. The full load must stay under 20× the catalog name count (today about 5×). An unchanged refetch and a search must not rebuild the rows, and a changed account must still appear. Above the limit the counter throws, so a regression fails in milliseconds instead of blocking the test worker. - Add `rules/ui-render-cost.mdc`, a general rule for `ui/src/**` code that renders large collections: no nested scans, stable memo dependencies, and a realistic-size test with a deterministic work counter when a change touches such a path. Register it in `.greptile/files.json`. ## Verification - `cd ui && npx vitest run src/pages/apps/Browse.test.tsx`: 100 of 100 pass. - With the previous `Browse.tsx` and the new test, the new test fails in 70 ms with "Connector catalog work exceeded its budget". - Measured on the new code: a full managed-instance load makes 25,810 identity calls for 5,095 catalog names. A search makes 0. - `node scripts/run-tsc.mjs -b` in `ui/`: no new errors. The only errors are in `PluginOrganizationSwitcher`, because `@paperclipai/plugin-sdk` is not built in a fresh worktree. They are unrelated to this change. - `pnpm check:token-gates`: all gates clean. - I did not check this in a browser on a managed instance. A local self-hosted instance does not take that branch. ## Risks - Low. The row-building logic gives the same results. The existing managed-instance Slack, Asana and Google tests still pass. - `useShallowStableItems` writes a ref during render. In the worst case, a concurrent render does one extra memo pass. It cannot return stale data, because it compares every item by identity. - The new rule applies to all `ui/src/**` reviews. Its body limits it to large or unbounded collections, to keep review noise low. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - Anthropic Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file editing, test execution). ## 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 - [ ] 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
DottaandPaperclip
|
a61cf38106 |
docs: keep the feature map focused on substantial features (#18767)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The feature map describes product capabilities and user journeys. > - Small fixes and test changes have added long notes to that map. > - These notes make substantial features harder to find. > - This pull request removes those additions from the last week's changes and sets a clear rule for future additions. > - The benefit is a smaller map with stable capability IDs and accurate entry points. ## Linked Issues or Issue Description **Issue type** Unclear or confusing documentation. **Where is the issue?** `maps/feature-map/`, the map maintenance instructions, and repository rules. **What's wrong?** Between October 27 and November 3, 2026, 115 commits changed the feature map. Many additions describe bug fixes, performance details, small UI changes, or new tests. They do not introduce substantial product features. The old synchronization instructions also encouraged a map edit for every behavior change. **Suggested fix** Add a rule that requires a substantial new feature before expanding the map. Remove minor-update notes. Keep genuine feature additions and minimal corrections to existing instructions. The review covers master through `b22ef22d56`; it does not revert application code. Conflict resolution preserves later map changes from master outside that audit snapshot. Searched open GitHub PRs and issues for related feature-map work. No duplicate cleanup was found. Substantial feature additions retained here include Coordinator (#17983), the agent YAML editor (#18036), document image galleries (#18157), remote workspace storage (#18403), native Kimi (#18391), proactive chat messages (#18374), and the Sentry receiver added in #18714. ## What Changed - Add `rules/feature-map-scope.mdc` and register its `maps/**` scope with Greptile. - Align `AGENTS.md` and the shared map contract with that rule. Routine fixes and test changes no longer require incidental map edits. - Remove 755 net lines from 23 feature recipes. Preserve all 35 areas and 192 capability IDs. - Keep substantial features and the corrections needed for current navigation, provider availability, and access boundaries. Examples from the reviewed changes: | Removed or shortened addition | Why it does not need a feature-map expansion | | --- | --- | | Rounded composer image thumbnails (#18689) | Small UI change within existing task creation. | | Connection profile reads and review-count queries (#18687, #18688) | Performance details within existing app permissions. | | Warm-session, Retry, export-capacity, and tool-wait cases | Regression details for existing execution and recovery. | | New task-search, project-context, document-persistence, and routine test journeys | Test additions for existing capabilities. The tests remain in place. | | New task button placement (#18703) | Another entry to an existing task form. | | Local browser verification notes | Run evidence belongs in the PR or test report. | ## Verification - `node scripts/check-maps.mjs` passes: 35 areas, 192 capability IDs, valid references and contract fields. - `node scripts/storybook-catalog.mjs` passes: 328 files and 3,068 stories. Generated indexes remain ignored. - Compared capability keys and navigation metadata in every edited recipe with the original source. All are unchanged. - Checked rule frontmatter, Greptile registration, representative scope matches, and `git diff --check`. - `pnpm -r typecheck` and `pnpm build` pass on `9a60eef8eb8da9bc7c3a02203c79bec12e8c8b6b`. The final `a0801e8a939494ecde3739097a80258917428e94` commit only corrects two lines in the plugin-panel recipe; map and catalog checks pass again. - Greptile reviewed the final `a0801e8a939494ecde3739097a80258917428e94` head at 5/5 with no findings. The earlier review found one inaccurate phrase about unavailable plugin panels. The hook confirms that readiness gates automatic opening, while declared panels remain selectable. The final documentation commit corrects that phrase and the thread is resolved. Paperclip's refreshed review is advisory and remains queued. - The earlier CI run failed two assertions: [server 4/12](https://github.com/paperclipai/paperclip/actions/runs/41634761842/job/125914173960) counted three Anthropic identity calls instead of two in `connection-management.integration.test.ts`; [chat 1/3](https://github.com/paperclipai/paperclip/actions/runs/41634761842/job/125914174257) observed zero publications instead of one in the same-principal endpoint-settlement case. Both exact tests pass locally on the rebased head. This PR changes neither their source nor their expectations. These failed results remain historical evidence. - Final-head CI passed server 4/12 and all other suites except the first [chat 1/3 attempt](https://github.com/paperclipai/paperclip/actions/runs/41637834618/job/125925926131), which repeated the same zero-publication assertion. The browser gate passed. The single failed-job retry was accepted for this unchanged head in [workflow attempt 2](https://github.com/paperclipai/paperclip/actions/runs/41637834618/attempts/2). [Chat 1/3 passed on that retry](https://github.com/paperclipai/paperclip/actions/runs/41637834618/job/125933199635), and the aggregate verification gate passed. Both required gates, `ci / verify` and `ci / e2e`, are green on `a0801e8a939494ecde3739097a80258917428e94`. The one retry allowance is consumed. - The first full local `pnpm test:run` attempt was interrupted before completion so master could be rebased without changing source under running tests. It is not a passing test result. Full current-head CI remains required. - No application code, tests, schemas, or lockfiles changed. ## Risks - Low runtime risk. This change only edits documentation and review guidance. - Detailed regression instructions become less visible in the feature map. Their tests and technical documentation remain available. - Some additions mix a new feature with a small fix. Those blocks retain the feature and shorten the incidental detail. ## Model Used - OpenAI Codex, GPT-6 family, with reasoning, Git history inspection, repository tools, and code execution. The session does not expose a more specific model 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 — map, catalog, capability-ID, and rule-scope checks; full Vitest limits are stated above - [x] I have added or updated tests where applicable — no new runtime tests apply to this documentation change - [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> |
||
|
Nicky LeachandClaude Opus 5.5
|
8362dbff4d |
feat(runner): make every ACPX provider declare its release attestation (#18342)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Native ACPX runs admit a provider only when its saved profile version and `commandDigest` match the current profile exactly. > - #18325 made every provider digest attest its upstream release, and bound the shared ACPX layer and Runner source through the pack `contractDigest`. > - The model is documented, but it lived in prose. A new provider, such as one in an open PR, could still choose another digest model without any check or guidance. > - This pull request makes the model the default path: each provider declares its attestation in one registry, and the generator, a test and a scoped rule explain the pattern where contributors meet it. > - The benefit is that new providers and upstream bumps follow one model, without a growing list of blocked legacy patterns. ## Linked Issues or Issue Description Refs #18325, #18237. **What happened?** After #18325, only Copilot, Grok and Pi went through `acpx-release-attestations.mjs`. Cursor and Antigravity had separate inline checks in the generator, and Claude and Codex had none. A new provider could add a profile with any digest. Nothing told the author how to compute it, and nothing pinned the profile versions that now change only for deliberate resets. **Expected behavior** Every ACPX provider declares how its `commandDigest` attests the upstream release. Tools and review guidance describe the pattern when a contributor adds a provider, bumps an upstream release or changes a version. **Steps to reproduce** 1. Add a new provider profile to `packages/paperclip-runner/acpx-profiles.json` with an arbitrary `commandDigest`. 2. Run `node packages/paperclip-runner/scripts/generate-acpx-profiles.mjs --check`. 3. Before this change, the check passes. ## What Changed - Add `ACPX_RELEASE_ATTESTATIONS` to `scripts/acpx-release-attestations.mjs`. Every profile declares one kind: - `installed-command` (Claude, Codex): installation hashes the upstream launch command. - `launcher` (Grok): the SHA-256 of the launcher shipped verbatim. - `closure` (Copilot, Pi): upstream versions and complete platform closure pins. - `declaration` (Cursor, Antigravity): a checked-in release declaration, as canonical JSON. - `generate-acpx-profiles.mjs` checks every profile through the registry. The separate Cursor and Antigravity digest checks are now part of the same path. No digest changes. - A profile without a declared attestation fails generation. The message says to declare one and points to the rule. - A stale digest message now says that a digest changes only with its upstream release, and that an upstream change keeps the profile version. - Add a test that pins the profile versions. It explains that a bump resets every saved session for that provider, and that a new provider starts at 1. - Add `rules/acpx-profile-identity.mdc`. It describes the identity model, how to add a provider, when to bump a version, and review criteria. `AGENTS.md` and `.greptile/files.json` route the profile, attestation, contract-registry, ACPX driver and provider paths to it. - Update the profile identity section in `packages/paperclip-runner/docs/durable-recovery.md` with the attestation kinds and the version policy. ## Verification - In `packages/paperclip-runner`: - `node scripts/generate-acpx-profiles.mjs --check` passes. Running it without `--check` changes no digest. - `node --test scripts/acpx-release-attestations.test.mjs scripts/contracts/contract-fingerprints.test.mjs`: 22 tests pass. New cases: every profile declares an attestation, a new provider without one fails with guidance, and Cursor and Antigravity declaration changes affect only their own digests. - `vitest run src/drivers/acpx/profile-compatibility.test.ts`: 15 tests pass, including the version table. - `tsc -p tsconfig.json --noEmit` passes. ## Risks - Low risk. No digest, version or runtime admission behavior changes. - A new provider PR must add one registry entry. The generator error states what to add. - The version table needs an edit for each deliberate reset. Upstream bumps do not touch it. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, local test runs). ## 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
DottaandPaperclip
|
13a83dd68a |
docs: require sleep-aware background work in reviews (#17138)
## Thinking Path
> - Paperclip manages agents in instances that can be idle between
tasks.
> - Recurring empty database and network checks can keep idle instances
and databases awake.
> - Worker migrations already use events, transaction-aware signals, and
shared deadlines.
> - New features can still add idle scans unless contributors and code
reviewers share an explicit rule.
> - This PR makes that rule discoverable through the repository rule
loader and Greptile.
> - The rule applies to added or expanded behavior without requiring
unrelated legacy polling to be removed.
## Linked Issues or Issue Description
Refs #15625, #17000, #17094, #17106, and #17129.
**Current behavior**
The repository has module ownership and runtime dependency rules, but no
explicit review requirement against new idle polling. A new duty in a
heartbeat tick can undo the benefits of previous worker migrations.
**Proposed behavior**
Require events for changed state, transaction-aware signals for
database-produced work, and shared scheduling for real deadlines. Reject
recurring empty scans, including scans disguised as scheduler callbacks.
Review narrow polling exceptions against concrete obligations and sleep
impact.
**Reason and benefit**
Make sleep-aware design a default review expectation. Preserve delivery,
ambiguous-commit recovery, drain/resume, and external wake correctness
while preventing new permanent idle traffic. Existing unrelated polling
stays outside the requested change.
## What Changed
- Add rules/sleep-aware-background-work.mdc for server, database,
adapter, plugin, and runner background paths, including
server/src/index.ts.
- Require concrete triggers, pending-work predicates, quiet conditions,
actual deadlines, and lifecycle evidence.
- Describe narrow exceptions for active operations and external sources,
with required scope, stop conditions, and sleep limitations.
- Distinguish in-process scheduling from durable Cloud wake coverage.
- Register the matching scopes in .greptile/files.json and link the rule
from rules/README.md.
- Reuse the existing module-boundary rule for ownership instead of
duplicating provider policy.
## Verification
- Passed: JSON parsing, required rule metadata, exact parity between
frontmatter globs and Greptile scopes, and all repository links.
- Passed: 15 representative path matches, including server startup,
nested service workers, producer routes, tests, database signals,
adapters, plugins, and both runner source trees. UI, CLI, docs, and
workflow paths remain outside this rule's glob scope.
- Passed: git diff --check.
- Manually checked contrasting review cases: reject a new empty queue
interval; reject an always-rescheduled empty scan; allow an actual retry
deadline; allow a bounded active readiness probe with lifecycle cleanup;
leave untouched legacy loops alone; reject sleep approval based only on
an internal timer.
- No runtime code changed. Application builds and tests were not rerun
for this rules-only change. This validates rule structure and intended
interpretation, not future reviewer compliance or deployed sleep.
- Greptile: 5/5 on
|
||
|
DottaandPaperclip
|
14afc12124 |
docs: define module ownership and shared change review (#17087)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Coding agents extend connectors and shared control-plane services. > - Provider details can leak into shared services during these changes. > - Moving code into a new file does not explain why shared behavior must change. > - This pull request adds module ownership and shared-change review rules. > - The rules help agents justify the change before implementation and review. ## Linked Issues or Issue Description **Issue type** Missing documentation. **Where is the issue?** Repository architecture rules and the connector authoring playbook. **What's wrong?** Subsystem rules describe some ownership boundaries. The repository lacks a general rule for deciding which behavior belongs in a feature module, what shared contracts must change, and how to review the resulting scope. An integration can therefore add provider-specific logic to shared code or bundle large platform changes into one connector PR. **Suggested fix** Add a repository-wide rule and load it in Greptile. Apply the rule during connector planning and PR preparation. Keep provider protocol behavior with its owner. Require a reason for shared changes and checks through affected consumers. Related public context: [Notebook connector PR #16984](https://github.com/paperclipai/paperclip/pull/16984). This PR changes instructions only. ## What Changed - Add a concise module-boundary rule for ownership, narrow contracts, shared controls, delivery scope, and verification. - Register the rule as repository-wide Greptile context. - Add planning and PR review steps to the connector playbook. Keep tests and docs with their behavior. ## Verification - Passed rule frontmatter, Greptile registration, referenced-file, and playbook-link checks. - Passed `git diff --check origin/master...HEAD`. - Reviewed the rule against the relevant connector failure and allowed cases: small dispatch branches, one-consumer shared capabilities, and unrelated fixes. - Fresh Greptile and Paperclip reviews both scored commit `759572fe503e1b6dfa9527f53de6c326a2c3bff6` 5/5. No actionable findings or unresolved review threads remain. - Final current-commit GitHub checks: 55 successful, 1 neutral, and 2 skipped; no pending or failed checks. Both required `ci / verify` and `ci / e2e` gates passed. - Initial CI attempt: the build and runtime boot smoke test passed. The spot runner received a shutdown signal during the clean public npm install check, canceling that step and failing the build job. [Interrupted job log](https://github.com/paperclipai/paperclip/actions/runs/39601811838/job/119228042468). Retried failed jobs once. Attempt 2 passed the complete build, runtime boot, and clean-install verification. The initial runner interruption remains recorded here. - Full local application checks are unavailable: this checkout has no workspace dependencies, and `pnpm -r typecheck` stopped during pnpm bootstrap because registry fetches failed and the requested pnpm version could not be verified. Local application tests and build were not run. GitHub checks must pass before merge. ## Risks - The rule could cause unnecessary abstractions or extra PRs if applied mechanically. It permits small dispatch branches and useful capabilities with one consumer. It rejects arbitrary file counts and unrelated restructuring. - Prose and metadata checks do not prove that future agents will follow the rule. Hosted review receives it when this branch is reviewed. ## Model Used - OpenAI Codex: `gpt-6-astra` authored the guidance; `gpt-6.1-sol` prepared delivery. Both used reasoning, filesystem tools, and GitHub tooling. Context window size was not recorded in the available model settings. ## 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 documentation and metadata validation; application checks unavailable as stated above) - [x] I have added or updated tests where applicable (no runtime change; targeted structural checks cover the changed instructions) - [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> |
||
|
DottaandPaperclip
|
13e5128164 |
docs: preserve runtime and verification lessons (#16379)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Its control plane shares execution capacity across requests and agent orchestration. > - A dependency can return a small value while doing slow or repeated work underneath. > - Tests can check that value while mocks hide the behavior that affects other work. > - A later passing retry can also leave an earlier material failure unexplained. > - This pull request records general rules for dependency work, verification, and acceptance. > - The benefit is a durable review habit that applies beyond the runner incident. ## Linked Issues or Issue Description Refs #15683. Refs #16335. The staging runner incident exposed a gap in how we establish the operational cost of a dependency call. The original platform check read a small field from a process report. The call could block shared execution, and value-focused mocks did not exercise that behavior. The fix replaced that probe with bounded asynchronous work. This proposal addresses the reasoning and evidence gap, without assigning blame or prescribing one API or timeout for future work. The acceptance guidance also preserves material failures after a retry passes. It does not assert that every earlier test failure had the same cause as this incident. Related proposal checked: #14275 covers release sign-off templates. This PR covers implementation assumptions and verification evidence. ## What Changed - Add a scoped rule for dependency work in server, adapter, and runner execution paths. Cover blocking, repetition, cost growth, cancellation, and the effect on unrelated work. - Require evidence that can disprove the consequential assumption introduced by a change. Identify behavior removed by mocks and exercise the relevant boundary. - Register the rule in the Greptile manifest with matching path scope. Existing `AGENTS.md` instructions route coding agents to matching rules. - Add failure preservation to the verification skill. Link it from the repository-wide PR review rule. Keep recovery and resolution distinct. - Include examples and exceptions so cosmetic edits and ordinary pure transformations do not acquire unnecessary test requirements. ## Verification - Passed `git diff --check` and the repository PR template and duplicate-search validators. - Passed a local Python structural check: manifest JSON parses; rule globs and Greptile scopes match; seven representative runtime paths match; five unrelated paths do not; the evidence link and heading resolve; existing agent and reviewer loading instructions are present. - Manually applied the rule to a network-filesystem configuration getter, a repeated remote permission check, and an already-loaded map lookup. The first two need evidence about their new dependency risk. The last does not require fault testing by default. - Attempted `pnpm -r typecheck`, `pnpm test:run`, and `pnpm build`. The installed pnpm launcher could not fetch registry data to verify the requested pnpm version. Using the cached project version reached typecheck, which failed because workspace dependencies are absent (`@types/node` missing). Tests and build remain unverified locally. - Greptile reviewed commit `e56d1ec70f3ebffe697b35cc637975b8d8198681` at 5/5 with no unresolved review threads. CI is still running. These structural checks establish instruction wiring, not future compliance by an agent or reviewer. ## Risks - The main risk is adding ceremony to low-risk edits. The rule limits requests to concrete risks introduced by changed behavior and explicitly exempts unrelated work. - Instructions depend on contributors and reviewers reading and applying them. This change adds no automated runtime regression gate. - No application behavior, schema, dependency, lockfile, or workflow changes. ## Model Used OpenAI Codex, GPT-6 family. The exact serving model ID, context window, and configured reasoning effort are not exposed in this session. Used reasoning, repository inspection, shell tools, and patch editing. ## 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 available in this session) - [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 (guidance-only change; structural validation described above) - [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 - [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> |
||
|
Nicky LeachandPaperclip
|
c4e80ccdc8 |
chore(db): prune obsolete migration snapshots and document retention (#16194)
## Thinking Path > - Paperclip uses versioned PostgreSQL migrations to preserve application data. > - Drizzle uses schema snapshots to generate future migrations. > - The database package already prunes snapshots to the five newest files. > - PR #15749 added three snapshots but left eight in the resulting tree. > - This PR removes the three excess files and documents the retention requirements. > - Coding agents and Greptile receive the same scoped rule for future migration changes. ## Linked Issues or Issue Description Refs #15749. Related: #16191 includes overlapping snapshot cleanup with its new migration. This PR isolates the existing excess and the repository rule; it has no dependency on that feature. **What happened?** The migration metadata directory contains snapshots 0331–0338. The existing pruning script retains only the newest five, but the older three were left in master. **Expected behavior** Keep snapshots 0334–0338. Commit snapshot pruning alongside additions and recheck the combined tree after rebases or merges. Preserve all SQL migrations and journal entries. **Steps to reproduce** At master commit |
||
|
DottaandPaperclip
|
9cb3e157b3 |
docs: keep routine product work in the harness (#16193)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The runtime and server handle routine execution and recovery. > - Product flows can expose internal steps that the system can handle safely. > - Users then have to operate infrastructure to achieve their original goal. > - This pull request adds a short rule that assigns this work to the harness. > - The benefit is a calm product experience with useful details and real choices. ## Linked Issues or Issue Description **Issue type** Missing documentation. **Where is the issue?** `rules/` and the repository review configuration. **What's wrong?** The repository has no shared product rule for harness responsibility and useful user-facing detail. Recovery can become a user checklist even when the system knows the next safe step. Related implementation: #15824. **Suggested fix** Require the harness to perform routine work within its existing authority. Require visible controls and details to serve a real decision or useful outcome. Keep progress truthful and apply the rule to changed flows. ## What Changed - Add the short product rule in `rules/product-harness-responsibility.mdc`. - Register it as a repository-wide review rule in `.greptile/files.json`. - Link the rule from `rules/README.md`. ## Verification - `git diff --check origin/master...HEAD` passed. - Node assertions passed for rule frontmatter, unique reviewer registration, repository-wide scope, all registered file paths and the README link. - The diff contains only three rule/documentation files. No application behavior changes. Application typecheck, tests and build were not run for this documentation change. - Review the rule's scope and read its four product requirements and review criterion. All applicable CI checks passed on head `89803a6cd7`. Greptile gave 5/5 with no unresolved findings. ## Risks The rule affects future product design and review. It applies to changed flows and does not require unrelated redesigns. Existing permissions, approvals and runtime safeguards remain in force. No migration or deployment is required. ## Model Used OpenAI Codex, GPT-6, with repository inspection, tool use and code execution. The exact serving model ID and context-window size were not exposed in this session. The user edited and approved the final short rule. ## 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> |
||
|
DottaandPaperclip
|
e67db42dc9 |
docs: define heartbeat execution design principles (#16190)
## Thinking Path > - Paperclip coordinates AI agents and their work. > - Heartbeat controls when that work starts, who owns execution, and how it settles. > - The extracted modules need shared architectural guidance as they evolve. > - Rules should protect those boundaries without freezing the current implementation. > - This PR adds scoped heartbeat principles for contributors and reviewers. > - The rule helps future changes preserve execution authority and recoverable work. ## Linked Issues or Issue Description **Issue type** Missing documentation. **Where is the issue?** The heartbeat service has a module map but no scoped architectural rule under `rules/`. **What's wrong?** Changes span admission, execution, completion, and recovery. Reviewers need shared principles for authority, ownership, and settlement across these boundaries. **Suggested fix** Add a concise heartbeat rule, route contributors to it from `AGENTS.md`, and register the same scope for Greptile. Keep implementation details in the code and existing developer documentation. Related: #16172 established scoped repository rules. #15984 completed the latest heartbeat extraction. Searches found no duplicate heartbeat-guidelines PR. ## What Changed - Add `rules/heartbeat-execution-boundaries.mdc` with a folder guide, a concise map of existing module responsibilities, and six design principles. - Keep `heartbeat.ts` focused on coordination: extend an existing owner or extract cohesive modules when new behavior would substantially grow it, with tests and explicit contracts. - Cover current execution authority, explicit ownership, distinct completion obligations, recovery intent, durable state, and visible uncertainty. - Register matching paths in `.greptile/files.json` and link the rule from `AGENTS.md` and `doc/DEVELOPING.md`. - Include behavioral review criteria and flag substantial coordinator growth or mixed responsibilities while allowing justified cohesion and ordering exceptions. ## Verification - Parsed the rule YAML and Greptile JSON. Confirmed that the rule globs exactly match the Greptile scope. - Checked 14 positive and negative scope cases with Node's `path.matchesGlob`, including nested heartbeat modules, sibling services, regression tests, and unrelated paths. - Verified local links and heading anchors, including the existing heartbeat module map, and confirmed all 20 named modules exist. Reviewed their responsibility descriptions against the current code and developer documentation. - `git diff origin/master --check` passed after rebasing onto current master. - Reviewed the principles against the current heartbeat code and tests. The diff changes four documentation and review-configuration files. - Application typecheck, runtime tests, and build were not run locally. This worktree has no installed dependencies. CI and review status are tracked below. - CI passed on `a17f5a2cc82b7bb7e4629d4a2d9e3a766e27c5c0`: 55 successful checks, two skipped, no failures or pending checks. This includes typecheck, build, server/runner tests, and browser tests. - Greptile reviewed the same commit at 5/5 with no findings or unresolved review threads. ## Risks The rule can influence later implementation and review decisions. It applies to changed heartbeat behavior and permits justified contract changes with tests. The scoped globs exclude unrelated subsystems. This PR does not change application behavior. Hosted loading of the new rule has not been demonstrated by the local configuration checks. ## Model Used OpenAI GPT-6 Astra (`gpt-6-astra`) via Codex, with repository inspection, file editing, and command execution. The context-window size was not exposed to 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 `#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 (scoped rule/configuration checks described above) - [x] I have added or updated tests where applicable (documentation/configuration validation; no runtime changes) - [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> |
||
|
DottaandPaperclip
|
7ac0354b51 |
docs: track chat channel rules and Greptile configuration (#16172)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Chat channels connect shared task workflows to several platforms. > - Recent refactors moved platform behavior into named channel folders. > - Authors and reviewers need a durable rule that preserves these boundaries. > - Review settings also need version control and an explicit source of rules. > - This pull request adds scoped MDC rules and a staged migration of supported Greptile settings into Git. ## Linked Issues or Issue Description **Issue type** Missing documentation and versioned review configuration. **Where is the issue?** Root contributor instructions, chat channel architecture guidance, and Greptile configuration for this repository. **What's wrong?** The channel folder boundary is established in the refactor but has no focused rule for future changes. Greptile settings and custom context are maintained in the dashboard. **Suggested fix** Keep canonical rule bodies under `rules/`. Route coding agents through `AGENTS.md` and load matching rules through `.greptile/files.json`. Preserve supported review settings in `.greptile/config.json` and document the remaining dashboard controls. Related work: #15823 and #16080. A search for related rule PRs found no duplicate configuration change. ## What Changed - Add `rules/chat-channel-platform-boundaries.mdc`. Its scope covers `server/src/services/chat-channels/**` and the sibling `chat-channels.ts` entry point. - Define provider folder ownership, shared workflow boundaries, typed dependencies, behavior-preserving extraction, and dispatch exceptions. - Add rule-loading instructions to root `AGENTS.md` and `.greptile/rules.md`. - Add explicit, scoped context references in `.greptile/files.json`. - Record observed review triggers, the Dependabot exclusion, Base tier, High strictness, summary options, fix prompts, status checks, and disabled auto-approval in `.greptile/config.json`. - Move existing PR-description, source-file growth, and repository-specific screenshot guidance into `rules/pull-request-review.mdc`. - Document supported settings, remaining dashboard controls, and the staged cutover. The dashboard was inspected read-only; no settings or saved rules were changed. ## Verification - Parse both MDC headers with Ruby `YAML.safe_load`: passed. - Parse both Greptile JSON files and verify documented field types and observed values: passed. - Verify all four context references resolve to repository files: passed. - Compare scoped MDC globs with the corresponding Greptile scope: passed. - Check ten positive and negative scope cases with Node `path.matchesGlob`: passed. Includes the service entry point, nested provider files, and unrelated runner, connection, and UI paths. - Verify the scope covers all 101 tracked chat-channel files: passed. - `git diff --check`: passed. - Application typecheck, `pnpm test:run`, and build were not run locally. This change contains only guidance and reviewer configuration, and this worktree has no installed application dependencies. No runtime behavior or application tests changed. - Greptile reviewed commit `32647dfd001289a297b9d43c381371da8575df38`: 5/5, eight files reviewed, zero comments. Hosted CI is still running. ## Risks - Instructions depend on agent and reviewer compliance; these files are not deterministic lint rules. - The new MDC directory is explicitly routed through `AGENTS.md` and Greptile. Cursor does not automatically discover arbitrary `rules/` directories. - This preserves the observed High strictness setting, which the dashboard says omits P2 comments. It does not change that review policy. - Dashboard instructions and custom rules remain additive. Their copies were not disabled during read-only inspection. The repository-specific no-screenshot rule explicitly takes precedence over the conflicting older organization instruction. - Draft review, the required 5/5 status threshold, image badges, and other controls without documented config equivalents remain in the dashboard. See `.greptile/README.md` for the inventory and cutover limitations. ## Model Used OpenAI Codex based on GPT-6. The exact runtime model ID and context-window size are not exposed in this session. Used reasoning, repository inspection, shell validation, official documentation, and read-only browser inspection. ## 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 (configuration parsing and scope checks described above; application suites were not run) - [x] I have added or updated tests where applicable (no runtime change; checked configuration directly) - [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 - [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> |