4550253dc9
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Coordinator gives people navigation for conversations, tasks, and decisions. > - The decision entry is called Needs you, while a separate Inbox remains under More. > - Coordinator's personal task filter does not retain the full behavior of the original Mine view. > - This pull request names the decision entry Inbox and hosts the original personal work views inside Tasks. > - People keep their triage tools and saved choices without moving between two task destinations. ## Linked Issues or Issue Description **What existing behavior does this improve?** Coordinator navigation and the personal Mine view in Tasks. **Subsystem affected** UI navigation, task view routing, task collection preferences, and browser coverage. **Current behavior** Needs you opens the decision feed. More contains another Inbox destination. The default Coordinator task filter matches task creators and assignees. It does not use the full personal participation rules, archive behavior, shortcuts, grouping, or saved columns of the original Mine view. The organization task table also resets its column choices on reload. **Proposed behavior** Inbox opens the same decision feed with the inbox icon. Tasks defaults to Mine and remembers a person's selected view per company. Mine uses the existing personal Inbox implementation and preferences. It retains read/unread title weights, keyboard navigation, read/unread shortcuts, archive and undo, mobile swipe-to-archive, grouping, and saved columns. Old Inbox links open the matching task view. The organization task table saves its columns and order per person and company. **Reason and benefit** People get Chat, Tasks, and Inbox as distinct navigation entries. Personal work remains a view within Tasks without losing the existing triage behavior. **Breaking changes** Coordinator no longer offers the previous Inbox destination under More. Old Inbox URLs redirect into Tasks and retain query parameters and fragments. The Needs you label becomes Inbox; its decision feed, count, history, and resolution paths stay in place. Classic retains its separate optional combined-list setting. **Additional context** Refs: #19360, the workspace-defaults PR now integrated from master. Refs: #10620, related Inbox attention ordering. Duplicate searches found no open PR for this navigation and Mine integration. Roadmap review found no separate new execution feature in this scope. ## What Changed - Rename Coordinator's desktop and mobile decision entry and page to Inbox. Use the inbox icon. Remove the old Inbox item under More. Clarify that the combined-list experiment applies only to Classic. - Add one Coordinator task-view router. Host Mine, Unread, Recent, Blocked, and Everything through the existing Inbox owner. Keep organization views in the task table and board. Normalize legacy filtered URLs before mounting a collection so clearing the last filter preserves the current layout and local filters. - Reuse the existing Mine API, participation, read state, archive cache, undo, keyboard, mobile gesture, grouping, and preference paths. Existing personal column choices carry over. - Save organization task-table columns and order per person and company. Keep controls usable if browser storage fails. - Update navigation tests, routing and persistence regressions, exact-run retry browser coverage for each workspace variant, product documentation, and the affected Storybook notes. Keep existing story IDs. ## Verification - Preference, routing, navigation, task table, and inherited Inbox regression tests pass in focused runs. After integrating master and addressing the review finding, all 187 focused tests, UI typecheck, and token gates pass. - Full build and repository typecheck pass after integrating master. The full UI suite previously passed: 894 files, 11,169 tests passed, and one skipped. All 14 desktop/mobile triage and exact-run retry browser cases, including a fresh production UI build, pass after integrating master. - The full repository test suite was not run locally for this UI-only change; full PR CI is running. - Browser checks use a fresh isolated local instance and a deterministic process agent for real run-attributed unread activity. They exercise legacy URLs, title weights, saved grouping and columns, read/unread shortcuts, archive/undo, and a real mobile touch gesture. - Earlier browser fixtures were corrected: own activity is read, agent comments need valid run attribution, and undo uses `u` after the archive refresh completes. The Inbox content heading is scoped separately from the layout heading. - The final settings wording correction passes all 63 settings tests. - The [next CI browser run](https://github.com/paperclipai/paperclip/actions/runs/42137377960/job/127629100535) caught an old URL assertion for denied run retries. The test now pins each workspace variant and covers Coordinator Tasks explicitly. The old expectation fails deterministically for Coordinator; all 12 retry cases pass with the corrected destination, preserving exact run identity and truthful queued, deferred, and denied feedback. - Token gates, map checks, and Storybook catalog checks pass. All 30 map/catalog script tests pass. Storybook play tests were not run. - Greptile reviewed [the final commit](https://github.com/paperclipai/paperclip/commit/5f2f3789b83af259f694f379afb769465688fb72) at **5/5** with no new actionable findings. Its sort-only link finding is fixed and resolved: three cases fail before the fix and pass after it. `sortField` and `sortDir` keep organization links on the organization table. [Current-head CI](https://github.com/paperclipai/paperclip/actions/runs/42139668774) is running. - [CI exposed a routing race](https://github.com/paperclipai/paperclip/actions/runs/42135293421/job/127621981587) when removing the last label from a legacy Everything link. Four deterministic regressions failed before the fix and now pass: collections only mount after URL normalization. The existing end-to-end component cases confirm local filters, board layout, fragments, and history survive the change. - The [initial server shard 4 run](https://github.com/paperclipai/paperclip/actions/runs/42131163087/job/127608751620) failed an unchanged monitor-drain idleness assertion: two active operations remained instead of zero. The complete scheduling suite passes locally (54 tests). One isolated CI retry passed, including its dependent verification gate. The original timing failure's root cause is not established. ## Risks - Mine includes the existing tasks, approvals, failed runs, and join requests, preserving the original personal participation and attention rules. - Shared URLs with organization filters or table sort parameters still open the organization task collection. Task back-links retain their original fragments. - Saved preferences are browser-local. Mine keeps its existing storage keys; the organization table and selected Coordinator view use person/company scopes. - No database or server API contract changes are included. Existing company access, personal participation, and decision permissions retain their owners. ## Model Used OpenAI Codex, based on GPT-6, with reasoning, repository tools, code execution, and browser automation. The exact serving revision 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 #` / `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 - [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: Scott Tong <scott@scottsmbpm5max.lan> Co-authored-by: Paperclip <noreply@paperclip.ing>
11 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Agent conversations and project handoff
A person can hold a persistent conversation with an agent, return to its history, and hand useful work into a project or task. The gated conference-room chat is a separate conversation surface.
Feature ID: agent-chat.
Implementation: agent chat, chat landing, conference room.
Agent access: companion.
Sub-features
discovery:agent-chat/discovery— find an agent and reopen an accessible recent conversation.history:agent-chat/history— send messages, inspect replies/files, and return to the same conversation.handoff:agent-chat/handoff— create or identify a project/task from chat and follow the resulting work.conference-room:agent-chat/conference-room— use the separately gated board chat without assuming parity with agent chat.
How to get to it (user POV)
agent-conversation
Task and routine results can arrive proactively in the agent's standing chat. Each message has a source-task link; the agent row and Chat navigation indicate unread messages, including first delivery before any human chat. Foreground messages at the bottom of the chat are marked read with a comment cutoff. The existing ordering and per-human/company isolation remain in effect.
Open /chats, choose an agent, or use /chats/:agentRef and its conversation sidebar.
With Coordinator enabled, click the agent avatar, name, or caret in the chat header to open the agent picker. They form one button with the same keyboard focus and action.
With Coordinator enabled, the composer exposes the shared model/thinking-level picker for supported agents. The agent stays fixed in this control; switching agents remains in the chat header. Choices save as conversation overrides on send, preserving the agent's configuration. A first message creates the conversation before saving settings and submitting through the ordered comments endpoint.
Coordinator answer receipts from this conversation jump to the answer bubble without leaving chat. Answer updates from an execution task link to that source task and its decision context. Compact document links read “Open [document title] in the sidebar”.
project-handoff
Ask for project work in Agent Chat and follow its created project/task links. New tasks and accepted task suggestions default to the agent in that conversation. An explicitly requested agent or person takes precedence; no best-fit agent routing is inferred. Ordinary task creation outside chat keeps its existing assignment behavior.
conference-room
Open /board-chat only when its conference-room gate is enabled.
Driving it with Playwright and the Paperclip CLI
Preconditions: follow the baseline. Enable the applicable chat feature, use a configured test agent, and distinguish model replies from a mocked conversation fixture.
agent-conversation
Automated: chat landing checks recent-chat routing; conversation service covers persisted conversation behavior.
Automated: proactive delivery exercises native/HTTP delivery, concurrency, retries, authority, privacy, active turns, resets and unread cutoffs. Read visibility checks foreground/bottom gating and unseen arrivals. The routine digest journey uses real app APIs and a deterministic process agent to verify first-chat discovery, unread state across reloads, source navigation and follow-up context. It does not qualify live PR retrieval or a model's editorial choices.
Automated: composer picker covers fixed-agent model/effort selection on desktop and mobile; composer covers Coordinator gating and settings submission without reassignment. Task detail verifies canonical first/existing-chat IDs, settings-before-comment ordering, and no comment submission when settings fail to save. These tests mock the API and do not prove provider execution with the chosen model.
Automated: thread and composer keeps an in-flight attachment through first-chat creation on desktop and mobile, while initial history for an existing conversation stays deferred. The first-upload browser journey checks the visible file chip, server attachment, no premature agent run, and attachment count after send and reload. That journey uses a simulated agent.
Manual: In a conversation with no messages, attach a file before the first send. Confirm the same file stays in the composer after the chat is created. Send it once, reload, and confirm the file and message remain.
Manual: Start a conversation, send a recognizable request, and inspect its reply.
Navigate away and reopen the same history. Use /new for a fresh session within
the same standing conversation. Test an unavailable historical agent and an
inaccessible saved conversation; verify no cross-user or cross-company history appears.
project-handoff
Automated: chat project tools checks tool contracts; live model choice and UI handoff require a manual run.
Automated: Coordinator handoffs checks that a suggested task remains a proposal until acceptance, that its task, initial plan and source-chat audience are saved atomically, and that retries do not create another task. A conversation is a privacy/provenance source rather than a structural task parent. The same tests cover compact canonical decision receipts, exact uploaded-artifact bindings, current task access, reset-session boundaries, and pagination of older handoffs. Explicit live evals: chat feature journeys send natural requests to save a backlog task or delegate an announcement. They check project/assignee, execution or non-execution, saved output, return to chat, and click the actual same-instance task link after reload. Registration alone does not establish a pass. Production chat guidance uses company-prefixed relative task links unless the platform supplied a verified absolute origin.
Manual: Ask the configured agent to create bounded project work, inspect the proposed/created target, and open the resulting task. Verify the request context and intended project survived and the task produces a useful output.
Manual: With the personal Coordinator workspace enabled, discuss a vague request until the agent suggests a task. Confirm that no execution task exists before acceptance. Accept it, stay in chat, and open the created card on demand. An explicit request to create a task may create it directly under normal authority. Approve a work product or answer a question in its task or Inbox, then return to the originating chat. Its compact update should link to the exact recorded decision and reviewed artifact, without needing another coordinator turn. Approval of artifact quality alone must not publish it or complete the task.
Coordinator task clarification: create a task with only a description. When material context is missing, native task guidance asks one focused canonical question inside that task. Its actionable form is also projected into Inbox and the originating standing chat; direct user-created tasks appear in the assigned agent’s standing chat. Answer on either surface and verify the pending card/count clear and a compact recorded answer replaces it in chat. This projection is event-refreshed and does not wake another agent merely to repeat the question. Current direct-task questions survive a chat reset; their answered receipts start at the current chat boundary. The task brief remains editable context, not another stored question. Model choice and actual resumed execution still require live verification.
conference-room
Automated: board chat gate proves route gating, not a live conversation.
Preconditions for this entry point: local_trusted mode and an installed,
authenticated claude CLI, in addition to the Conference Room flag. These are
separate from Agent Chat's configured-agent prerequisites.
Manual: Check disabled access first, enable in the disposable instance, then send and reload a conversation. Inspect the actual responding agent and persisted history; report this result separately from Agent Chat.
Gotchas
- Idle chat is not failed execution.
- See steering for in-flight messages and questions for interactions.
- An API tool test does not prove that every harness will choose the same handoff tool.
Storybook verification
conference-room
Capability ID: agent-chat/conference-room.
Scope: ui Storybook: Conference-room flag disabled, empty/history/reply, busy and explicit failure states. Production: Exercise separate BoardChat route gate, local-trusted deployment and authenticated Claude CLI; send/reload real conversation with responding agent attribution. Sources: Source: BoardChat.tsx, board-chat.ts. Tests: BoardChat.test.tsx, board-chat-route-feature-flag.test.ts
Explicit output quality review (Coordinator functional slice)
Accepted suggestions and native explicit task creation may carry requiredQualityReview into the task's existing execution policy. The opt-in requirement names output slots and is separate from the existing reviewer eligibility policy. Each slot requires a canonical human verdict bound to an exact current output document revision or attachment identity. Plans, questions, file presence, model completion claims, rejected/deferred verdicts and stale versions do not satisfy it. Only a human may change an existing requirement. Quality approval does not publish or automatically complete the task. Tasks without this optional requirement retain existing completion behavior.
Owning service: server/src/services/required-quality-review.ts; enforcement: interaction creation, issue update, native completion feedback/finalization. Focused proof: server/src/__tests__/required-quality-review.test.ts plus native arbiter and chat completion delivery tests. Completion updates include bounded canonical output-decision identities for linking existing review, never worker-authored review prose. These tests do not establish unattended live provider reliability.
Attachment approval is for the exact immutable file identity. Removal or a mismatched hash invalidates that target; registering a replacement beside the approved file does not redefine its output slot. A replacement requires a fresh bound review. Document targets additionally track the current revision.