mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-21 16:27:18 +02:00
Dotta
39206c0096
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The task page is the main place where people guide and review agent work. > - Native runner events already project into the existing task chat on the lower stack. > - The larger task workspace must support those events without breaking direct adapters. > - Legacy questions, final replies, empty transcripts, and classic controls must keep their behavior. > - This pull request completes the provider-neutral task workspace experience. > - The benefit is one coherent task surface for native and direct execution paths. ## Linked Issues or Issue Description Refs #12639. Refs #12617. Refs #12352. **Subsystem affected** Task chat, task detail, side panels, interaction forms, and transcript presentation. **Problem or motivation** The task page does not provide one complete workspace for live activity, plans, questions, queued guidance, files, and documents. Earlier native UI work also exposed compatibility risks in legacy question and reply paths. **Proposed solution** Add the task workspace components and provider-neutral protocol presentation. Keep runner-only controls behind runtime facts. Preserve all direct-adapter composer, transcript, interaction, and finalization behavior. **Alternatives considered** A separate runner page would duplicate task behavior. Replacing legacy transcript logic would create unnecessary adapter regressions. **Roadmap alignment** This work supports the unified task experience and the Cloud and Sandbox agents milestone. ## Stack - Base PR: #12639. - Lower PR: #12638. - This PR contains only its 119-file UI delta against `runner/remote-wss-transport`. - The next stack PR adds administrator and observability controls. ## What Changed - Added a reusable task workspace side panel for files and documents. - Added provider-neutral cards for tools, plans, questions, protocol activity, and progress. - Added queued guidance and richer composer state. - Added compact and expanded interaction presentation. - Added live activity, thinking, usage, recovery, and final reply presentation. - Added document annotations and task deep links. - Added bounded question validation and response handling. - Preserved native runner event projection from master. - Preserved legacy channel-less replies and explicit final reply precedence. - Preserved direct-adapter and classic-interface controls. - Did not change server execution selection, Rust code, migrations, workflows, or `pnpm-lock.yaml`. ## Verification - GitHub Actions will run UI tests, repository tests, typecheck, build, browser tests, security, and policy gates. - Tests cover active, settled, empty-transcript, interaction, queued-message, plan, question, file, document, and classic-interface states. - Compatibility tests cover direct adapters and native runner projection together. - Local tests were not run. The requested verification policy uses GitHub Actions for this series. - `git diff --check runner/remote-wss-transport...HEAD` passes. - The delta contains 119 UI-only files. ## Risks - This is a large task-page change. - Most files are new focused components and tests. - Shared transcript code keeps the lower native projection and legacy direct-adapter fallbacks. - Runner-only controls use adapter and runtime facts. - No execution path or rollout flag changes in this PR. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI Codex with GPT-5.6. The work used high-reasoning agent mode, repository tools, GitHub tools, and parallel code-audit agents. ## 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 or instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal Paperclip ticket id - [ ] 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 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
Portable side panel
The components exported by @/components/side-panel are controlled, domain-free navigation primitives. They do not import task data, APIs, routing, feature flags, or persistence.
Composition boundary
SidePanelFramerenders docked, sheet, or embedded chrome and applies the selected content layout.SidePanelTabsandSidePanelTabrender projected visual tab data and own keyboard navigation, close focus recovery, overflow visibility, and pointer/keyboard reordering.SidePanelLauncherrenders caller-provided sections from the same model as either a plus-button popover or the empty panel body.useSidePanelTabs<TPayload>owns serializable open/select/close/reorder/reset state. Its optionalonStateChangecallback is the persistence boundary; it never reads storage itself.- The host adapter owns payload validation, data queries, URL synchronization, content rendering, and persistence scope.
Never put React nodes or fetched content in a persisted SidePanelTabRecord. Project icons and live status into SidePanelTabItem at render time.
Registering another page
- Define a serializable payload union for that page, such as
details | activity | history. - Build stable
SidePanelTabRecord<PagePayload>descriptors and initializeuseSidePanelTabswith validated state. - Project descriptors into
SidePanelTabItemvalues for the tab strip. - Render active content in the page adapter by switching on
payload.kind. - Supply the same launcher sections to the plus popover and empty panel.
- If state is persisted, version and scope it in the adapter and pass writes through
onStateChange.
Accessibility and review
The tab strip uses the tabs pattern with roving focus, Arrow/Home/End navigation, named close actions, middle-click close, and live reorder/close announcements. Closing the active tab chooses the right neighbor, then the left; closing the final tab sends focus to the launcher. Reduced-motion preferences disable component transitions and smooth overflow scrolling.
Review Navigation/Side Panel in Storybook before changing production adapters. Compare light/dark, minimum/default/wide/maximized, mobile, overflow, empty, launcher, unavailable-resource, and task-composition stories. Tune spacing, radius, contrast, icon size, and motion centrally through the side-panel tokens in ui/src/index.css.