mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-01 06:42:06 +01:00
Nicky LeachandPaperclip
b056026407
## Thinking Path > - Paperclip helps people manage agents and their tasks. > - The task side panel can display a plugin's agent view. > - Users need that view even while a task is idle. > - Activity currently controls both manual discovery and automatic opening. > - This pull request keeps manual access available and uses activity to request automatic opening. > - The same authorized agent viewer serves both entry points. ## Linked Issues or Issue Description **What happened?** A task view disappeared when its run ended. Users could not select it until the current run reported matching activity and its readiness check passed. This also excluded declared manual views without an activity mapping. **Expected behavior** The task launcher offers declared views for its running or assigned agent. Selecting one uses the same viewer as the agent detail page. Matching activity and readiness open the pane and select the view by default, once per run. **Steps to reproduce** Open an idle task assigned to an agent with an installed task-panel contribution. Open the panel launcher. The view is currently missing. Related work: #18131 and #18239. ## What Changed - Return manual panel declarations independently of run activity and readiness. - Mark panels that should open automatically after matching activity and readiness. Keep existing run attribution, retry bounds, and dismissal behavior. - Keep an open viewer mounted when a run ends. Focus an already open manual view when activity starts. - Preserve saved manual tabs while plugin and initial run discovery load; remove contributions after discovery confirms they are absent. - Share the run-scoped dismissal key between the task page and panel controller so dismissed views do not reveal an empty pane. - Use the current running agent for declared manual views that have no activity mapping. - Update the plugin authoring contract and feature recipe. ## Verification - Two new regressions failed before the fix: idle discovery returned no view, and a manual contribution opened automatically. - 105 focused hook and panel tests pass. They cover idle/manual access, declarations without mappings, completion, saved-tab restoration, automatic focus, activity attribution, retry bounds, dismissal, and missing/disabled plugins. - Thirteen task-page panel integration tests pass. New regressions reproduce and fix a dismissed manual view revealing the outer pane. They cover desktop/mobile and both workspace modes, and verify that a later run can still open the view automatically. - `node scripts/check-token-gates.mjs`, `node scripts/check-maps.mjs`, and `git diff --check` pass. - Local UI typecheck failed with the reused dependency cache: workspace modules/exports and generated Storybook catalog files are missing or stale. It reported no errors in the changed files. The final head passed the clean GitHub typecheck. No broad local build or repository test run was attempted. - The preceding head passed [GitHub CI](https://github.com/paperclipai/paperclip/actions/runs/41116028688), with 48 jobs succeeding and one skipped. Its final review scored 5/5 and identified a narrow saved-view restoration race. This revision adds the missing initial-run loading guard. Two delayed-response regressions failed before the correction and now pass; they cover a different assignee and an unassigned task. - The final head `bbde3a28f7ac0390da8f3fe81eb9abd2f3020695` passed [GitHub CI](https://github.com/paperclipai/paperclip/actions/runs/41119772438) and the additional [full CI run](https://github.com/paperclipai/paperclip/actions/runs/41121827023), each with 48 successful jobs and one skipped. Standard Greptile scored 5/5 on this head; both review threads are resolved. The small final loading correction used the permitted exception to another final-review cycle. - The additional full CI run initially failed the canary bundle install because npm advertised a newly published `tslib@2.9.1` archive before its tarball was available (HTTP 404). After the archive became available, one retry of the failed canary and dependent aggregate passed. No dependency or lockfile change was needed. - Hosted acceptance of this follow-up requires merge and deployment; the earlier hosted activation checks cover the previously merged behavior. ## Risks Manual views can now open while idle or before readiness. Each viewer retains its normal authorization and status handling. Declarations without an activity mapping now appear in the launcher. Automatic opening still requires authenticated activity and the authorized readiness result. Saved tabs wait for plugin discovery before removal. ## Model Used OpenAI GPT-6 through Codex, with repository inspection, terminal tools, browser verification, and code execution. The exact serving variant and context window size 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>
88 lines
5.0 KiB
Markdown
88 lines
5.0 KiB
Markdown
---
|
||
navigation: {"section":"Tasks and conversations","sectionOrder":20,"order":20}
|
||
---
|
||
|
||
# Delegation, dependencies, and signoff
|
||
|
||
A larger task can coordinate child work, dependencies, reviewers, and execution controls while preserving a clear owner and a traceable completion decision.
|
||
|
||
Feature ID: `task-coordination`.
|
||
|
||
Implementation: [task thread](../../ui/src/pages/IssueDetail.tsx), [execution policy](../../server/src/services/issues.ts).
|
||
|
||
Agent access: [companion](../agent-access-map/task-coordination.md).
|
||
|
||
## Sub-features
|
||
|
||
- `delegation`: `task-coordination/delegation` — inspect parent/child tasks and the original request behind delegated work.
|
||
- `dependencies`: `task-coordination/dependencies` — show blocking tasks and wake eligible work when prerequisites resolve.
|
||
- `signoff`: `task-coordination/signoff` — apply the configured implementation/review completion policy.
|
||
- `tree-control`: `task-coordination/tree-control` — pause or resume a task tree without bypassing its gates.
|
||
|
||
## How to get to it (user POV)
|
||
|
||
### `task-relationships`
|
||
|
||
Open the task’s parent/child and dependency links in task detail.
|
||
|
||
### `review-and-controls`
|
||
|
||
Inspect the task’s execution policy and available review, pause, resume, or stop controls.
|
||
|
||
## Driving it with Playwright and the Paperclip API
|
||
|
||
Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Prepare a parent, child, and dependent task plus implementer/reviewer agents. Record execution policy and use a disposable tree.
|
||
|
||
Parent/dependency navigation and inherited tree holds can be checked on unassigned
|
||
tasks. Agents are required for the continuation and signoff portion. A tree pause
|
||
creates a hold; it does not change task statuses to a paused status.
|
||
|
||
### `task-relationships`
|
||
|
||
Automated: [dependency wakeups](../../server/src/__tests__/issue-dependency-wakeups-routes.test.ts) checks server behavior; visual relationship navigation remains a manual check.
|
||
|
||
Manual: Block one task on another, finish the prerequisite, and observe the dependent task’s eligible continuation. Follow parent/child links back to the source request. Verify no duplicate run or false parent completion occurs.
|
||
|
||
### `review-and-controls`
|
||
|
||
Automated: [execution policy](../../server/src/__tests__/issue-execution-policy.test.ts), [tree control](../../server/src/__tests__/issue-tree-control-service.test.ts), and [signoff browser suite](../../tests/e2e/signoff-policy.spec.ts) target these layers. A linked suite is not a claim that its current run is green.
|
||
|
||
Manual: Complete implementation under a review-required policy and confirm it waits for the required review outcome. Exercise rejection and later approval. Pause the parent while child work is pending, then verify resumption respects budget and ownership gates.
|
||
|
||
Resume removes the pause without changing task status. Its wake count includes only
|
||
current agent assignees on todo, in-progress, or in-review tasks. The dialog explains
|
||
that blocked, backlog, and unassigned tasks remain idle. Verify this in both task
|
||
interfaces with [the paused composer browser suite](../../tests/e2e/paused-composer.spec.ts).
|
||
Release rechecks tasks reopened after the pause; another active pause still prevents
|
||
their execution, and uncertain prior executions must be reconciled before waking.
|
||
|
||
### Plugin task panels
|
||
|
||
An installed plugin can offer an agent detail tab in the task side panel through
|
||
its optional `taskSidePanel` declaration. The launcher offers that view for the
|
||
running agent, or the task's assigned agent when idle. Manual selection mounts
|
||
the same authorized viewer used on the agent page and needs no activity event.
|
||
The view remains selectable after the run ends.
|
||
|
||
A declared activation pair controls automatic opening. The runtime captures
|
||
Runner context before use and records `runtime.activity.recorded` after success.
|
||
Core maps that namespace/activity key to the declaration and restores it from
|
||
the run log on reload or reconnect. After matching activity, readiness gets
|
||
three bounded attempts with no periodic availability poll. A ready view opens
|
||
the pane and selects its tab once per run, respecting dismissal during that run.
|
||
Declarations without a mapping support manual selection. Plugins own viewer
|
||
content, readiness, and authorization. Missing or disabled plugins add no view.
|
||
|
||
Implementation: [panel discovery](../../ui/src/hooks/useTaskPluginPanels.ts) and
|
||
[task panel](../../ui/src/components/task-side-panel/TaskSidePanel.tsx).
|
||
Automated: [discovery tests](../../ui/src/hooks/useTaskPluginPanels.test.tsx) and
|
||
[task panel tests](../../ui/src/components/task-side-panel/TaskSidePanel.test.tsx)
|
||
cover availability, task/agent changes, failures, inactivity and dismissal.
|
||
These mocks do not establish a particular plugin's live transport behavior.
|
||
|
||
## Gotchas
|
||
|
||
- Review completion and task completion are different events under some policies.
|
||
- Pausing a tree must not be “tested” by changing statuses until the screen looks quiet.
|
||
- Use [questions and approvals](./questions-and-approvals.md) for decision forms and [recovery](./recovery.md) for interrupted work.
|