mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-21 16:27:18 +02:00
DottaandPaperclip
b928c6698f
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - One-shot task monitors request future work through the normal heartbeat queue. > - Queue admission can hold execution until recovery or ownership is reconciled. > - The scheduler retained those monitor schedules but recorded no monitor diagnostic. > - Agents could repeatedly reschedule the same blocked check without seeing why it did not run. > - This pull request records safe deferral and failure activity while retaining all execution gates. > - Agents and operators can inspect the actual blocker and use its existing recovery path. ## Linked Issues or Issue Description Related: #15556 handles transient monitor client errors. #14590 handles parked monitor wakes. This change records the diagnosis when queue admission defers or fails; it does not change their admission or monitor consumption policies. **What happened?** A due monitor on a task with an unresolved execution-recovery hold was claimed, passed to queue admission, and released without monitor activity. The saved monitor continued to look scheduled. Unexpected dispatch errors had the same audit gap. Repeated rearming could not clear the recovery hold. **Expected behavior** Keep the monitor and the recovery hold. Record the reason that prevented its wake. Do not execute uncertain work or consume an attempt. Limit repeated identical diagnostics. If audit storage fails, release the claim so a later tick can retry. **Steps to reproduce** 1. Schedule a due monitor on an agent-owned task in progress. 2. Add an active recovery action for an interrupted legacy execution. 3. Run the monitor scheduler twice. No provider may start while the hold remains. 4. Before this fix, neither attempt writes monitor deferral activity. 5. Resolve the hold through its existing recovery path. The saved monitor can then request one wake. **Paperclip version or commit** Reproduced on master5739a53f5fwith real PostgreSQL and the assembled heartbeat service. **Deployment mode** Built from source. This affects the server monitor scheduler. ## What Changed - Pass the existing execution blocker cause to the monitor scheduler through a server-owned diagnostic callback. - Record issue.monitor_deferred for held admission and issue.monitor_dispatch_failed for unexpected admission failures. - Keep activity to known reason codes and allowlisted blocker causes. Do not copy raw provider messages. - Fence claim release and activity against replacement, reassignment, completion and competing scheduler instances. - Limit identical activity for one schedule and cause to one record per five minutes. - Keep claim release functional when diagnostic storage fails. - Update execution documentation and the task verification maps. ## Verification - Red: explains held monitor dispatch without replaying uncertain execution failed because it expected one deferral activity row and received none. The fixture used the real queue, persisted source run and recovery action. - Red: records bounded dispatch failure diagnostics while retaining the schedule failed because no failure activity was recorded. - Green: both regressions pass after the fix. The held-source test proves no successor while held, no monitor attempt consumed, and one wake after explicit hold resolution. - Passed: all 43 tests in heartbeat/scheduling.test.ts and issue-monitor-scheduler.test.ts, with at most two workers. - Additional coverage uses real PostgreSQL for diagnostic rate limits, replacement races and an audit-insert trigger failure. Audit failure must not retain the monitor claim. Private error and unknown blocker text do not reach activity. - Passed: node scripts/check-maps.mjs and git diff --check. - Greptile: 5/5 with no actionable issues on1d0aec738c. - Latest-head checks: 55 successful, two skipped, and one neutral. No check remains pending or failed. The branch has no merge conflict. Paperclip Review ended neutral because its agent did not return a complete assessment; it is not counted as a validated review pass. - The dependency added on deferral is one bounded recent activity query and at most one audit insert. Successful admission adds no new database read. Existing queue authority checks still decide admission. - The process fixtures validate queue admission and persisted state. They log workspace setup errors after admission; this report does not claim a live provider turn succeeded or that an existing deployment was repaired. - Passed: pnpm --dir server exec tsc --noEmit. The wrapper typecheck was stopped because it started a redundant cold native Runner build. Full repository checks run in PR CI; no local full-suite or full-build pass is claimed. ## Risks - Audit work must not strand a monitor. The storage-failure regression verifies that rollback is followed by a claim-fenced release. - Recovery holds still require their current reconciliation path. This change makes their effect visible and does not bypass ownership, budget, pause, Stop or company checks. - Activity can be stale after a later repair, so each entry includes the checked time and the exact saved deadline. A replacement cannot inherit an old dispatch diagnostic. ## Model Used OpenAI Codex, GPT-6 family, with reasoning, tool use and code execution. The exact runtime model suffix and context window are 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 - [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>
101 lines
5.9 KiB
Markdown
101 lines
5.9 KiB
Markdown
---
|
||
navigation: {"section":"Tasks and conversations","sectionOrder":20,"order":10}
|
||
---
|
||
|
||
# Task creation and lifecycle
|
||
|
||
People create, assign, organize, discuss, and finish tasks. A task retains its owner, project, priority, history, and outputs as it moves through the work lifecycle.
|
||
|
||
Implementation: [new task](../../ui/src/components/NewIssueDialog.tsx), [task list](../../ui/src/pages/Issues.tsx), [task detail](../../ui/src/pages/IssueDetail.tsx).
|
||
|
||
Agent access: [companion](../agent-access-map/tasks.md).
|
||
|
||
## Sub-features
|
||
|
||
- `create`: capture a title/request with the intended agent, project, and attachments.
|
||
- `organize`: filter, sort, group, and navigate tasks without losing the selected context.
|
||
- `properties`: change status, priority, assignee, project, and relationships where authorized.
|
||
- `discussion`: persist comments, references, and files on the task.
|
||
- `completion`: distinguish backlog, active work, review, blocked, done, and cancelled outcomes.
|
||
|
||
## How to get to it (user POV)
|
||
|
||
### `new-task`
|
||
|
||
Use New task from the global launcher, task list, or project task view.
|
||
|
||
### `task-list`
|
||
|
||
Open `/issues` or a project’s Issues view; legacy `/tasks` links redirect.
|
||
|
||
### `task-detail`
|
||
|
||
Open `/issues/:issueId` from a row, mention, or direct link.
|
||
|
||
## Driving it with Playwright and the Paperclip CLI
|
||
|
||
Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Use a
|
||
disposable project. Persistence checks can assign work to Me or leave it
|
||
unassigned; execution checks additionally need an invokable test agent. Record
|
||
whether a real or simulated harness handles execution.
|
||
|
||
### `new-task`
|
||
|
||
Automated: [creation dialog](../../ui/src/components/NewIssueDialog.test.tsx) is component coverage with mocked requests.
|
||
|
||
Manual: Create a uniquely named task with an agent and project. Open its resulting link and reload. Confirm text, attachment, assignment, and project persisted, and verify execution started only when the task and agent are eligible.
|
||
|
||
Creation is request-first: enter **Describe a task…**, choose the assignee and
|
||
project, and submit **Create task**. A standalone title field is not always shown.
|
||
Use a human/unassigned task to verify persistence without invoking a model.
|
||
|
||
### `task-list`
|
||
|
||
Automated: [task-list helpers](../../ui/src/pages/Issues.test.tsx) cover search URLs, pagination, deduplication, and presentation constants. The suite does not render the page or exercise filtering, grouping, opening a task, and returning; those interactions still need a running-browser check.
|
||
|
||
Manual: Seed human-created, agent-created, scheduled routine, human-initiated chat-channel, and creator-less tasks. Confirm automation is hidden by default, **show agent-created tasks** reveals it, reload preserves the choice, and Clear filters hides it again. Verify list and board search with automation newer than the human results, and expand contextual ancestors/subtasks without promoting unrelated automated roots. Repeat in project task lists. Agent profiles and task-detail subtasks retain complete history.
|
||
|
||
Manual: Filter by status and assignee, change grouping/sort, open a task, and return. Verify the correct records and selected view survive navigation and reload. Include an empty result and a failed request.
|
||
|
||
### `task-detail`
|
||
|
||
Automated: [task detail](../../ui/src/pages/IssueDetail.test.tsx) covers component behavior, while [issue service](../../server/src/__tests__/issues-service.test.ts) covers server contracts.
|
||
|
||
Manual: For a disposable task owned by a legacy agent, have its current run
|
||
assign the task to a human with status In review. Verify that assignment and
|
||
status persist, that the current run finishes without `issue_reassigned`, and
|
||
that slow workspace restoration does not turn the task Blocked. Try a later edit
|
||
from the outgoing run and verify rejection. Repeat a board
|
||
reassignment and confirm that the outgoing run still stops.
|
||
|
||
Manual: Add a comment and edit authorized properties. Reload and verify history, actor, and values. Complete a disposable task and inspect its deliverable; reopen through an available action and confirm the next execution follows current policy.
|
||
|
||
Manual: Ask a standard native agent to schedule a future check on its current
|
||
task. Reload and confirm the persisted monitor. After the agent yields, verify
|
||
one later wake and a consumed schedule. For malformed-call recovery, use the
|
||
[agent access recipe](../agent-access-map/tasks.md#properties) and verify that
|
||
schema feedback supports a corrected call before a wait is claimed.
|
||
For a due monitor held by execution recovery, confirm that the schedule remains
|
||
and task activity explains the deferral. Repeated checks must not replay the held
|
||
work. Resolve the hold through its existing recovery action, then verify one wake.
|
||
|
||
Manual: Add an ordinary Board comment while a task retry is queued or running.
|
||
Confirm that the same execution keeps working and receives the saved message,
|
||
without a second executor or an implicit move to Todo. Repeat with a parked retry
|
||
and verify that fresh instructions can supersede it. Explicit Stop must still
|
||
cancel active work. The [comment route regressions](../../server/src/__tests__/issue-comment-reopen-routes.test.ts)
|
||
and [HTTP/process and interrupted-cancellation tests](../../server/src/__tests__/issue-scheduled-retry-routes.test.ts)
|
||
cover these boundaries locally; deployed runner acceptance remains separate.
|
||
|
||
## Gotchas
|
||
|
||
- Priority remains an API field, but ordinary priority UI editing is hidden.
|
||
|
||
- A status label alone does not prove that the requested work exists.
|
||
- Single-assignee and atomic checkout rules still apply when tasks are created from different hosts.
|
||
- Use [coordination](./task-coordination.md), [steering](./steering.md), and [documents](./documents-artifacts.md) for their distinct workflows.
|
||
|
||
### Documentation scope: Tasks, conversations, and attention
|
||
|
||
Recipes cover the main task/conversation/attention workflows. Full shell, permission, attachment, long-thread, and concurrency permutations remain to be enumerated.
|