146 lines
8.6 KiB
Markdown
146 lines
8.6 KiB
Markdown
# Threads deck
|
|
|
|
`/threads` renders one column per live agent conversation, TweetDeck-style.
|
|
|
|
`selectActiveThreads` (`lib/threads/active-threads.ts`) derives the columns from
|
|
the workflow snapshots the board already keeps in the store, so opening the view
|
|
costs no extra request and stays live on the same WebSocket updates the cards
|
|
use. Its ordering is total (attention bucket, then recency, then task id).
|
|
|
|
**That ranking decides where a column first appears and nothing after that.**
|
|
`useStableThreadOrder` (`lib/threads/stable-order.ts`) pins each column to its
|
|
slot, and new threads append rather than sorting in. Do not re-apply the ranking
|
|
live: replying to a thread refreshes its activity and flips it out of the
|
|
"needs a human" bucket, so a live re-rank slides the column the reader is typing
|
|
into across the deck, then slides it back when the turn ends. The E2E
|
|
`holds a column's slot and the deck's scroll while you reply to it` fails if this
|
|
is undone.
|
|
|
|
A task reaches the deck through its **primary** session, matching the backend's
|
|
`GetPrimarySessionIDsByTaskIDs`. Once that task column is present, the Threads
|
|
switcher can select any existing sibling session, including a settled one.
|
|
Sessions created by the E2E seed harness are never primary, so a spec has to
|
|
run a real agent turn (create the task with an agent, open the task page to
|
|
launch the session, then wait) rather than seeding a RUNNING row.
|
|
|
|
Columns mount `TaskChatPanel` with **no `onSend`**. Its own submit path is what
|
|
honours the session's queue input mode, the selected model, plan mode, context
|
|
files and the optimistic store update; a custom sender posts straight to
|
|
`message.add` and drops all of it, so a reply to a busy thread jumps its queue.
|
|
(`PreviewSessionBody` in the kanban preview still passes one and has the same
|
|
defect.)
|
|
|
|
They do pass `isVisible={false}`, for the same reason the kanban preview does: a
|
|
wall of columns is a glance across running work, and letting every mounted
|
|
column advance its own read cursor would mark threads read that nobody looked
|
|
at.
|
|
|
|
Columns share the board width (`flex-1` above a min-width floor) rather than
|
|
taking a fixed slice, so two threads fill the deck and a busy deck scrolls
|
|
horizontally instead of shrinking into slivers. The phone keeps one full-width
|
|
snapping column, which is a deliberately different layout.
|
|
|
|
The phone title button opens one board-owned `MobileThreadPicker` using
|
|
admitted task summaries. Selection scrolls an existing shell; viewport
|
|
activation still owns transcript mounting. The picker restores focus without
|
|
scrolling back to the previous column. Phone headers prioritize task title,
|
|
status, and agent selection; workflow and step context remain in the picker.
|
|
Titles wrap to two lines. Inline topbar pagination shows position/count for
|
|
multiple threads and decorative dots only for decks of up to seven threads.
|
|
`ThreadsBoard.renderHeader` receives `mobileTaskId`, derived from board scroll
|
|
geometry by `useMobileThreadPosition`; the page derives its ordinal from stable
|
|
order without copying selection state. Do not derive pagination from loaded
|
|
chat or visibility-ID membership alone: both adjacent columns can stay
|
|
intersecting across a swipe midpoint. Position changes also refresh the nearest
|
|
visible detail calculation, retaining the one-phone-transcript limit.
|
|
Callback refs reconcile column additions/removals on the existing observer.
|
|
Do not rebuild it on every membership change: clearing surviving visibility
|
|
briefly unmounts readers' chats and loses editor focus. Recreate observation
|
|
only when an empty/nonempty transition replaces the board element.
|
|
|
|
`ThreadTaskActionsProvider` owns one task-action surface above removable
|
|
columns. Headers pass explicit task IDs; `useTaskManagementFlow` captures the
|
|
workspace/task identity and resolves current eligibility from shared snapshots.
|
|
`TaskManagementSurface` composes existing task menus, linking and confirmations;
|
|
`useTaskMenuActions({ stayOnListing: true })` shares destructive lifecycle
|
|
cleanup with the sidebar without task-detail navigation. Do not add task API
|
|
calls or mutation policy to Threads.
|
|
|
|
The page excludes task IDs from pending `archive` operations in
|
|
`taskRemoval.operationsByToken` before `queryThreadView` applies scope, filters,
|
|
limits or temporary deep-link admission. This unmounts outgoing chats at
|
|
acceptance and keeps counts, the phone picker and pagination consistent. Do not
|
|
mutate shared snapshots optimistically or include removal intent in the query
|
|
fingerprint/stable-order reset key. Successful reconciliation prunes snapshots
|
|
before releasing intent; failure readmits only currently eligible tasks in
|
|
normal arrival order. Pending deletion retains its existing timing.
|
|
|
|
Only noninteractive desktop task-header regions handle context menus. The
|
|
visible `TaskMenuButton` is also the keyboard/touch entry; phone and coarse
|
|
pointers use one `TaskManagementDrawer` with nested pages. Keep chat, editor,
|
|
session and native swipe events outside this boundary.
|
|
|
|
`useThreadSelectionRecovery` preserves the surviving reader's column offset
|
|
and uses `resolveRemainingThreadId` for successor/predecessor/first-new/empty recovery
|
|
when membership changes. This does not replace stable ordering, the parent's
|
|
scroll-derived pagination, or transcript activation. Action focus restoration
|
|
resolves a currently visible trigger and never scrolls to a removed opener.
|
|
|
|
The page reads `?workspace=` into the route it hands `useKanbanRouteBootstrap`.
|
|
Without it a cross-workspace link loads whichever workspace the cookie last
|
|
named. Scope changes from the shared header go through `listingHistoryHref`,
|
|
which keeps the deck's own path: those handlers `pushState` without routing, so
|
|
a task-overview href would leave the deck rendered under a Home URL.
|
|
|
|
## Round trip with the task page
|
|
|
|
`linkToThreads(workspaceId, taskId, sessionId)` produces `/threads?taskId=…` and,
|
|
when supplied, the target session id. The link asks the deck to scroll that
|
|
column into view and ring it. The focus id is resolved against the rendered
|
|
deck (`resolveFocusedThreadId`), never trusted from the URL: the thread may
|
|
have settled between the link being offered and followed.
|
|
|
|
The scroll effect is keyed on `isFocused` and the column is keyed by task id, so
|
|
a column that only mounts once a later snapshot lands still scrolls, while a
|
|
column re-rendering with new messages does not yank the deck back.
|
|
|
|
The mark retires on the first pointer or focus interaction with the deck, since
|
|
it only ever answered "where is the column I asked for". Dismissal is keyed to
|
|
the raw workspace/task/session request identity, independently of its currently
|
|
resolved column. Temporary exclusion and failed archive readmission must not
|
|
revive a consumed mark; an actual new deep link still earns a fresh mark.
|
|
`useThreadFocusRequest` keeps the initial activation fallback alive after mark
|
|
dismissal until its target leaves the deck. Early interaction must not unmount
|
|
that chat before the first visibility callback, and failed readmission must
|
|
not restore a consumed fallback. URL-driven callers pass `focusRequestKey`;
|
|
the optional task-ID default deliberately retains legacy dismissal semantics.
|
|
|
|
`OpenInThreadsButton` is the other half, living in the chat status row. It has
|
|
two gates, and both matter:
|
|
|
|
- `useIsDeckThread` — the session must belong to a task with a Threads column,
|
|
which can come from a live primary or a task-level review outcome. It reads
|
|
already-loaded sessions and the cached task summary/state and must not fetch;
|
|
a status-row control triggering a request would be a surprise. A settled
|
|
sibling is therefore eligible when that task keeps a column in the deck.
|
|
- pathname — the deck's own columns render the same chat panel, so without this
|
|
the button would appear inside every column offering a jump to the view
|
|
already on screen.
|
|
|
|
## Adding a task-listing view
|
|
|
|
`kanban`, `pipeline`, `list` and `threads` share one device-local preference in
|
|
`lib/task-listing/view-preference.ts`. `resolveTaskListingNavigation`
|
|
(`lib/task-listing/view-navigation.ts`) is the single mapping from a toggle pick
|
|
to the view to remember and the page to go to; the desktop topbar
|
|
(`components/kanban/kanban-header.tsx`) and the phone menu sheet
|
|
(`hooks/use-mobile-menu-sheet-state.ts`) both call it, so a new view means one
|
|
entry there plus a toggle item on each surface.
|
|
|
|
A view that owns its own route also needs an entry in
|
|
`ROUTED_TASK_LISTING_VIEWS`, so Home hands off to it instead of rendering the
|
|
board, and one in `lib/navigation/core-destinations.ts` — a guardrail test fails
|
|
when a top-level route has no navigation destination. `currentPage` is
|
|
`TaskListingPage` internally; `toPluginTopBarPage` narrows it to the two values
|
|
the plugin contract has always published.
|