mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 11:59:26 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The native runtime finalizes an agent's run, applies the agent's status decision to the task, and posts the agent's reply as a task comment > - When the first workspace copy-back fails, or the run reconnects, a background retry commits the result instead of the live heartbeat > - That retry path applies the "blocked" status but never posts the agent's reply, so the task turns blocked with no visible reason > - The retry path already shares one recovery step for replies, but that step accepted only "done", "needs review" and conversation replies > - This pull request lets the shared recovery step present a blocked task's reply, so the retry path and the normal path converge on one presentation step > - The benefit is that a blocked task always tells the user why, exactly once ## Linked Issues or Issue Description **What happened?** An agent reports that it is blocked. The task moves to "blocked". No comment from the agent explains why. This happens when the run finishes through a retried workspace copy-back or a reconnect loop instead of the live heartbeat. The run succeeds and its result has the agent's blocker summary, but the run has no presentation decision and the task has no reply. On a staging company, 58 of the 150 most recent agent-blocked tasks for one agent had no agent comment. **Expected behavior** Every finalization path that applies an agent's status decision also presents the agent's reply. A blocked task always shows the agent's explanation once. The status decision does not post a second copy. **Steps to reproduce** 1. Run a native agent on a task. The agent reports `blocked` with a summary and a task-wide blocker. 2. Make the first workspace copy-back fail (`native_workspace_sync_out_failed`), so the heartbeat leaves finalization to the retry. 3. Let the retry finish the copy-back and commit the result. 4. The task is blocked and the run succeeded, but the task has no agent comment. **Paperclip version or commit** `master` atb8207c4ea9**Deployment mode** Hosted (staging cloud). The defect is in server finalization, so it applies to all deployment modes that use the native runtime. **Agent adapter(s) involved** Native runtime (`paperclip_runner`), seen with the Codex-based agent. The defect is adapter-independent. ## What Changed - The response presentation recovery step (`recoverCommittedNativeChatResponse`) now presents a non-conversation task's reply when the agent reported `blocked` and the task is still blocked. - For a blocked reply, recovery uses the agent's final message when one exists. Otherwise it uses the accepted result summary, the same as the live completion path. - A blocked reply on a channel task (an external chat run) uses the same rule as live run completion. Recovery resolves the chat publication authorization, prefers the final response, and posts with that authorization. The worker does not refuse these runs, so it does not record a false publication failure. - The presentation work query now finds these runs, so the background worker also presents them and the bounded publication retry applies to them. - A blocker reply is not presented when the task is no longer blocked or when a later status decision was applied. This keeps old blockers from posting stale comments. - Presentation stays idempotent: the step records `presentationDecision`, reuses a reply that the run already posted, and never posts twice. - Existing affected tasks need no separate backfill. The presentation worker loads all pending candidates at startup, so each task that is still blocked gets its saved reply once after deploy. ## Verification - Red/green test: `server/src/services/native-runtime/native-blocked-reply-recovery.test.ts`. It completes a blocked native run, fails the first copy-back with `native_workspace_sync_out_failed`, then commits the retry with `finalizeNativeRun`. - Red on `master`: the retry-path tests fail (no comment is posted, and the worker finds no candidate). The channel task test also fails on the first PR revision (5eb8cdab95). - Green with this change: 4/4 pass. The tests check that the blocker summary is posted once, that the final reply is preferred, that a repeated retry and a repeated worker check do not double-post, and that a stale blocker is not posted. - `cd server && npx vitest run src/services/native-runtime/native-blocked-reply-recovery.test.ts src/services/native-runtime/native-response-publication-retry.test.ts src/services/native-runtime/agent-chat-response-recovery.test.ts src/__tests__/idle-native-finalization.test.ts src/services/presentation-ownership-read.test.ts src/services/chat-monitor-continuation.test.ts` passes (172 tests). - `cd server && npx tsc --noEmit -p .` passes. ## Risks - After deploy, tasks that are still blocked from earlier affected runs get the agent's saved reply once. This is the intended backfill. Tasks that moved on are skipped. - The candidate query has one more branch with a `NOT EXISTS` on `status_decisions`, keyed by the existing `(company_id, issue_id, decision_version)` unique index. The cost is low. - No schema change and no migration. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), via Claude Code with tool use (shell, file edits, browser reads of staging API). ## 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>