kandev/docs/session-page-data-flow.md

# Task Session Page Data Flow (SSR + WS + Store)

This document maps the current data flow for `/task/:id/:sessionId` and highlights which components/hooks depend on which data. It also calls out places where hooks could be made more granular or shared.

## SSR Entry Point

Route: `apps/web/app/task/[id]/[sessionId]/page.tsx`

Server fetches:
- `fetchTask(taskId)`
- `fetchBoardSnapshot(task.board_id)`
- `listAgents()`
- `listRepositories(task.workspace_id)`
- `listTaskSessions(task.id)` for each task in board
- `listTaskSessionMessages(sessionId)` (best-effort)

Hydration:
- `snapshotToState(snapshot)` → kanban columns + tasks
- `taskToState(task, sessionId, messages?)` → `tasks.activeTaskId`, `tasks.activeSessionId`, `messages.bySession[sessionId]`
- Repositories + agent profiles are merged into store
- Render `<StateHydrator initialState={...} />` and `<TaskPageClient ... />`

## Client Composition

```
TaskSessionPage (SSR)
  └─ TaskPageClient
      ├─ TaskTopBar
      └─ TaskLayout
          ├─ TaskSessionSidebar (left)
          ├─ TaskCenterPanel (chat/changes/notes)
          └─ TaskRightPanel (files + terminal)
```

## Active Selection (Store)

Store slice: `tasks.activeTaskId`, `tasks.activeSessionId`
- Set on initial mount by `TaskPageClient` from URL + SSR task.
- Updated when selecting a task/session in sidebar.

## WebSocket Data Flow

WebSocket client:
- `apps/web/lib/ws/client.ts` with deduplicated subscriptions.
- Components call `client.subscribe(taskId)`; dedup ensures single WS subscription.
- On reconnect, re-subscribes to active task channels.

Handlers (global router):
- `message.added` / `message.updated` → `messages.bySession[sessionId]`
- `task_session.state_changed` → `taskSessionStatesByTaskId` + `taskSessions.items`
- `git.status` → `gitStatus` (keyed by task)
- `shell.output` → `shell.outputs[taskId]`

## Component Data Dependencies

### TaskPageClient (`apps/web/app/task/[id]/page-client.tsx`)
- Props: `task`, `sessionId`, `initialSessionsByTask`, `initialRepositories`, `initialAgentProfiles`
- Store:
  - `tasks.activeTaskId`, `tasks.activeSessionId` via `setActiveSession`
  - `kanban.tasks`, `kanban.columns`, `workspaces.items`
  - `agentProfiles.items`
- Hooks:
  - `useSessionResumption(task?.id, sessionId)`
  - `useTaskAgent(task)` (agent state, task.execution polling)
  - `useRepositories(workspaceId)` (fallback to SSR data)
- WS:
  - Subscribes to all tasks in board (deduped)
  - Listens for `task_session.state_changed` to refresh `sessionsByTask`
- Responsibilities:
  - URL sync via `history.replaceState`
  - Task selection triggers `fetchTask` + `listTaskSessions`

### TaskSessionSidebar (`apps/web/components/task/task-session-sidebar.tsx`)
- Store:
  - `tasks.activeTaskId`
  - `tasks.activeSessionId`
- Props:
  - tasks + columns + sessionsByTask from `TaskPageClient`
- Uses:
  - `TaskSessionSwitcher` (sessions list)
  - `TaskSwitcher` (tasks list)
- Calls back to parent for selection and session list reload.

### TaskCenterPanel (`apps/web/components/task/task-center-panel.tsx`)
- Props: `taskId`, `onSendMessage`, `selectedDiffPath`, `openFileRequest`
- Includes:
  - `TaskChatPanel`
  - `TaskChangesPanel`
  - `FileViewerContent`

### TaskChatPanel (`apps/web/components/task/task-chat-panel.tsx`)
- Store:
  - `tasks.activeSessionId` (fallback unless `sessionId` prop passed)
- Hooks:
  - `useTaskSession(sessionId)` → taskId + session details
  - `useTaskMessages(taskId, sessionId)` → messages + meta
  - `useLazyLoadMessages(sessionId)` → pagination
- Data:
  - Renders from `messages.bySession[sessionId]`

### TaskRightPanel (`apps/web/components/task/task-right-panel.tsx`)
- Store:
  - `tasks.activeSessionId`
- Uses:
  - `ShellTerminal taskId + activeSessionId`

### ShellTerminal (`apps/web/components/task/shell-terminal.tsx`)
- Store:
  - `shell.outputs[taskId]`
  - `taskSessions.items[sessionId]?.state` or `taskSessionStatesByTaskId[taskId]`
- WS:
  - Subscribes to shell only when session is RUNNING or WAITING_FOR_INPUT.

### TaskFilesPanel / TaskChangesPanel
- Store:
  - `gitStatus` keyed by active task
- No direct WS subscriptions.

## ASCII Diagram (Current)

```
SSR
┌──────────────────────────────────────────────────────────────┐
│ /task/:id/:sessionId                                          │
│  fetchTask + snapshot + agents + repos + sessions + messages  │
│  StateHydrator -> store (activeTaskId + activeSessionId)      │
└──────────────────────────────────────────────────────────────┘

Client
┌─────────────────────────────── TaskPageClient ──────────────────────────────┐
│ setActiveSession(taskId, sessionId)                                          │
│ subscribe(board tasks)  + listen task_session.state_changed                  │
│                                                                              │
│  ┌─ TaskSessionSidebar (sessions + tasks)                                    │
│  ├─ TaskCenterPanel                                                         │
│  │   └─ TaskChatPanel                                                       │
│  │       ├─ useTaskSession(sessionId)                                       │
│  │       ├─ useTaskMessages(taskId, sessionId)                              │
│  │       └─ useLazyLoadMessages(sessionId)                                  │
│  └─ TaskRightPanel                                                          │
│      └─ ShellTerminal (shell.output + session state)                         │
└──────────────────────────────────────────────────────────────────────────────┘

WS
  task.subscribe -> deduped in client
  message.added/updated -> messages.bySession
  task_session.state_changed -> taskSessions + taskSessionStatesByTaskId
  git.status -> gitStatus (task)
  shell.output -> shell.outputs[task]
```

## Hooks Review (Granularity + Reuse)

Current hooks:
- `useTaskMessages(taskId, sessionId)`
  - Fetches + sets loading meta + subscribes to task updates.
  - Could be split into:
    - `useSessionMessages(sessionId)` (only fetch + store)
    - `useTaskSubscription(taskId)` (subscription only)
- `useLazyLoadMessages(sessionId)` uses store meta; OK as a focused pagination hook.
- `useTaskSession(sessionId)` derives taskId from messages if session not in store.
  - Can be simplified once session list is guaranteed in store.
- `useTaskAgent(task)` + `useSessionResumption(taskId, sessionId)`
  - Both access execution state. Consider a combined `useTaskExecution(taskId, sessionId)` hook.
- `useRepositories(workspaceId)` currently handles fetch + loading; OK but could be generalized (e.g. `useListResource`).

Suggested split for sharing:
- `useTaskSubscription(taskId)` → handles `client.subscribe(taskId)` only.
- `useSessionMessages(sessionId)` → fetch + store; no taskId.
- `useActiveSession()` selector → centralizes active session usage.
- `useTaskGitStatus(taskId)` → pure selector + optional subscribe.
- `useShellOutput(taskId)` → pure selector + optional subscribe.

This would allow panels to mix and match only what they need without pulling in extra behavior.