DottaandPaperclip
5c7a025032
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Task conversations keep follow-up messages pending while an agent works. > - The screen combines optimistic sends, queue snapshots, and run input records. > - A late send response can restore a local queue flag after a run takes the message. > - A stale queue snapshot can then keep the same message in pending. > - This pull request matches the input record to its source queue and clears stale pending flags. > - The benefit is that consumed messages leave pending while unsent messages stay visible. ## Linked Issues or Issue Description **What happened?** A follow-up can remain in the task composer's pending row after a run takes it as input. Local queue state can outlive the send request. The old projection cleared that state for steering, but not for ordinary run-start input. A stale queue read can also retain the consumed entry. **Expected behavior** A message that a started run takes as input appears once in history and leaves pending. Other pending messages remain available. A message assigned to a run that has not started remains pending. **Steps to reproduce** 1. Send a follow-up while a task has a live run. 2. Let a started run record that message as input before or after the send response arrives. 3. Let a queue read still include the consumed message. 4. Observe the message remain pending on the base revision. **Paperclip version or commit** Reproduced against master at `33d24e48ad` with controlled request ordering. **Deployment mode** Source checkout. Browser verification used the production task screen with a simulated native runner and delayed API responses. It did not run a live model or change a deployed instance. Related: [PR #15030](https://github.com/paperclipai/paperclip/pull/15030) addresses acknowledgement matching in the runner console. This change addresses the task-detail composer and does not modify that console. ## What Changed - Clear local pending flags when a started run records the comment as input. - Use live-run input IDs while the run-history query catches up. - Match stale queue entries by their primary or coalesced source wake ID, even when the snapshot targets the previous run or has no target. - Retain coalesced source queue IDs in run context and include receipt IDs in compact task run reads. - Keep unstarted run inputs and authoritative retries pending. Cover send ordering, same-run and successor delivery, queued snapshots, coalesced inputs, and retry consumption. - Add the delivery-race checks to the steering feature map. ## Verification - Before the fix, the first four request-order regressions failed with the consumed message still in pending. Coverage now includes 16 combinations of receipt source, send-response order, and stale snapshot kind. - Focused UI checks: 5 files and 233 tests passed. These cover task detail, queue projection, optimistic comments, queued-message controls, and the task-chat adapter. - `pnpm -r typecheck` passed. - Server receipt checks: 5 files and 139 tests passed with `PAPERCLIP_TEST_POSTGRES_TEMPLATE=0`. These exercise real database reads, coalesced heartbeat input, and polling routes. The default cached-template path timed out during setup on this host; the fresh-cluster path passed without longer timeouts. - Token gates and `node scripts/check-maps.mjs` passed. - Browser: sent a follow-up with a delayed response in the production task screen. The consumed message moved into history. A second unsent follow-up stayed queued. Reload preserved both states. The API and runner were simulated. - `pnpm build` passed. - The full local repository test run was started, then stopped to isolate database setup timeouts. All 55 GitHub CI checks passed on `4ec6820cf1f89880b801fd5f938d72f54591c5e2`, including the full test matrix. One serialized server shard passed on its single rerun after a 15-second route-test timeout; the same 97-test route suite also passed locally. - Greptile reviewed the final head at 5/5. All review threads are resolved. ## Risks - Queue display depends on matching comment IDs, source queue IDs, and a recorded start time. Rows without start evidence stay pending. Newer queues remain visible until their own input receipt arrives. - Run context gains additive receipt metadata. No schema migration is required. Dispatch order, stored queue state, company access, and steering authority stay unchanged. - Browser evidence covers controlled response ordering. It does not establish deployment or live-provider behavior. ## Model Used - OpenAI Codex, GPT-6, with reasoning, tool use, and code execution. The exact serving model ID and context-window limit are not exposed in 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 #` 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>
6.8 KiB
Steering and queued messages — agent access
Product map: Steering and queued messages.
Review date: 2026-10-12. Source commit: 58e16dbddfc9c8d0cf60867f9d9847f0feda055b.
Native REST transport reconciled in this change; see the
shared transport contract.
This is a source-reviewed baseline of representative operations and known gaps. Each capability needs operation-level review before its entire scope can be qualified. No live agent execution is claimed. Follow the map contract for format, permission checks, evidence and maintenance.
queue
Review: baseline.
API: present — representative operation IDs:
GET /api/issues/{id}/queued-comments.
Agent access: partial — REST / native call_api for visible queue; server-owned queue
admission.
Policy: Queue inspection follows task visibility; queued user-message mutation and run cancellation require a board actor/user.
Compact task run reads retain wakeupRequestId and queuedCommentSourceWakeIds
to identify consumed input queues, including coalesced requests. These receipt
fields follow the existing task/run read checks and grant no queue mutation authority.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Agents can read eligible queue state; sending/steering the person's queued messages requires separate authority.
edit-order-discard
Review: baseline.
API: present — representative operation IDs:
PATCH /api/issues/{id}/queued-comments/{commentId}.PUT /api/issues/{id}/queued-comments/order.DELETE /api/issues/{id}/queued-comments/{commentId}.
Agent access: restricted — Board-user queue mutation API.
Policy: Queue inspection follows task visibility; queued user-message mutation and run cancellation require a board actor/user.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: No agent user-message edit/reorder/discard path; explicit delegated-user policy needed before granting one.
steer
Review: baseline.
API: present — representative operation IDs:
POST /api/issues/{id}/queued-comments/{commentId}/steer.
Agent access: restricted — Board-user execution control API; agent receives eligible
new run/wake.
Policy: Queue inspection follows task visibility; queued user-message mutation and run cancellation require a board actor/user.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Steering requires a board user at the HTTP route. Native call_api
preserves this denial and cannot impersonate the steering user.
interrupt
Review: baseline.
API: present — representative operation IDs:
POST /api/issues/{id}/queued-comments/interrupt.POST /api/heartbeat-runs/{runId}/cancel.
Agent access: restricted — Board-user interruption/cancel API.
Policy: Queue inspection follows task visibility; queued user-message mutation and run cancellation require a board actor/user.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Explicit operator action is distinct from an agent yielding/blocking its own turn.
stop-and-pause
Review: baseline.
API: present — representative operation IDs:
POST /api/issues/{id}/tree-holds.POST /api/agents/{id}/pause.
Agent access: restricted — Board control APIs; agent paperclip_finish/paperclip_block
for its own turn.
Policy: Queue inspection follows task visibility; queued user-message mutation and run cancellation require a board actor/user.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Task-tree/agent pause and confirmed stop need policy-preserving authority; no generic agent management path.
drafts
Review: baseline.
API: not-applicable — No shared server draft resource for this presentation state;
cross-client drafts would be a deliberate new capability.
Agent access: not-applicable — Browser-local task composer draft / submission state.
Policy: Queue inspection follows task visibility; queued user-message mutation and run cancellation require a board actor/user.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — use the product recipe for the local/developer surface. Verify
listed shared-resource reads separately; local presentation alone is not agent API
evidence.
Gaps: No shared server draft resource for this presentation state; cross-client drafts would be a deliberate new capability.
approval-queue
Review: baseline.
API: present — representative operation IDs:
GET /api/issues/{id}/interactions.GET /api/issues/{id}/queued-comments.
Agent access: partial — Agent can inspect authorized persisted interactions; server
continuation/queue delivery.
Policy: Queue inspection follows task visibility; queued user-message mutation and run cancellation require a board actor/user.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Resolving as a human and controlling queued wakes is separate from seeing the approval response.