kandev/apps/web/components/threads/AGENTS.md

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 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 requested id, so a later deep link earns a fresh mark rather than being swallowed by an earlier dismissal.

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.