mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-07 07:23:08 +02:00
7014e46e5b
## Thinking Path > - Paperclip is the open source control plane people use to coordinate AI agents and their work. > - The heartbeat recovery subsystem detects successful runs that leave assigned issues `in_progress` without a durable disposition or continuation path. > - The existing corrective wake used a cheap, status-only model profile, so the assignee could not perform missing verification or deliverable work before choosing the issue disposition. > - The existing wake prompt also omitted the original issue context and the agent's own final report, making an honest finish/blocked/continue decision harder. > - This pull request keeps the structural handoff guards and one-attempt loop bound, but wakes the assignee on its normal model lane with context-rich instructions. > - The benefit is that Paperclip asks the responsible agent to inspect its own evidence, perform the smallest missing verification when needed, and then record a real disposition without server-side prose classification. ## Linked Issues or Issue Description Related prior approach: #10154 (closed; this PR intentionally does not reuse its regex classifier or route-level gate). **Problem** A succeeded agent run can leave its issue `in_progress` with no valid disposition. Paperclip already detects this structurally and queues a corrective handoff, but that wake currently runs as cheap/status-only recovery and receives little context. The assignee may be unable to create deliverables or verify the work, and the prompt does not quote the report that caused the ambiguity. **Expected behavior** The corrective wake should use the assignee's normal model and adapter settings, include the issue identifier/title/description, quote the agent's own final report, include any recorded next action, preserve the four disposition options, and explicitly require concrete verification before marking the issue done. **Scope** This change does not classify run prose, add a route-level disposition gate, alter run-liveness classification, or change the one-attempt handoff loop bound. ## What Changed - Switched successful-run corrective handoff payloads and context snapshots from `status_only` to `normal_model`, removing cheap-model and status-only guard hints. - Added issue description, final-report, next-action, and detected-progress fallback context to the handoff decision and instruction builder. - Reworked the instruction into clear "supposed to do / what happened / options / what to do" sections with bounded description/report excerpts and verbatim blockquotes. - Added unit and heartbeat integration coverage for normal-lane payloads, context plumbing, evidence quoting, fallback behavior, and truncation while preserving structural skip tests. ## Verification - `cd server && pnpm exec vitest run src/services/recovery/successful-run-handoff.test.ts` — 24 tests passed. - `cd server && pnpm exec vitest run src/__tests__/heartbeat-process-recovery.test.ts -t "queues one finish-handoff wake when a successful run leaves in-progress work without a next action"` — 1 passed, 90 skipped. - `pnpm --dir server typecheck` — passed. - `git diff --check` — passed. ## Risks - Low-to-moderate behavioral risk: an ambiguous successful run now consumes the assignee's normal model rather than a cheap profile and may perform verification or finish work before disposition. - Prompt excerpts are bounded to approximately 1,200 description characters and 2,000 report characters; very long context is intentionally ellipsized. - The existing structural skip guards, idempotency key, and single corrective attempt remain unchanged to prevent loops. > 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 - OpenAI Codex using `gpt-5.6-sol`, high reasoning effort, with repository/tool execution. Context-window size was not exposed by the runtime configuration. ## 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> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>