Frontend: /sessions/[id] detail page — wires SplitPane, AgentChatPanel, and AgentTerminal

[frankbria]

Parent Issue

Part of #500 — depends on #504, #505, #506, #507, #508

Context

This is the final integration page that assembles all the session UI components into a working interactive session view. It's the most important page from a user-experience perspective — it's where the bidirectional chat actually happens.

What to Build

New page: web-ui/src/app/sessions/[id]/page.tsx

Full-page layout:

┌─ Header ─────────────────────────────────────────────────────────┐
│  ← Sessions    Session #a3f2    🟢 active    $0.012    [End]     │
├─ SplitPane (fills remaining viewport height) ────────────────────┤
│                          │                                        │
│  AgentChatPanel          │  AgentTerminal                        │
│  (45% default)           │  (55% default)                        │
│                          │                                        │
└──────────────────────────────────────────────────────────────────┘

Header:

• Back link "← Sessions" → /sessions
• Session short ID
• State badge (🟢 active / ⚪ ended)
• Live cost counter (updates from useAgentChat state)
• [End Session] button — calls DELETE /api/v2/sessions/{id}, confirms, redirects to /sessions on success
• Disabled [End Session] if already ended

SplitPane:

• Left: <AgentChatPanel sessionId={id} />
• Right: <AgentTerminal sessionId={id} />
• storageKey="session-split-{id}" so position is per-session

Ended session state:

• If session state is ended: show AgentChatPanel in read-only mode (no input bar) and a banner: "This session has ended. [View history]"
• AgentTerminal is hidden for ended sessions (or shows "Terminal unavailable — session has ended")
• Load message history from GET /api/v2/sessions/{id}/messages (REST, not WS) for ended sessions

Loading state:

• Skeleton: header placeholder + two side-by-side gray boxes filling the viewport

Error state:

• Session not found: "Session not found" with link back to /sessions
• WebSocket error: visible error banner inside AgentChatPanel

Data flow:

1. On mount: GET /api/v2/sessions/{id} to get session metadata (state, model, workspace_path)
2. If active: mount AgentChatPanel + AgentTerminal (both connect via WS)
3. If ended: mount read-only AgentChatPanel with history from REST, no terminal

Page title:

• <title>Session #{shortId} — CodeFRAME</title> via next/head or metadata

Acceptance Criteria

• Page loads session metadata and renders correct state (active vs ended)
• AgentChatPanel is mounted and chat is functional for active sessions
• AgentTerminal is mounted and terminal is functional for active sessions
• SplitPane divider is draggable; position persists per session
• [End Session] ends the session and redirects to list
• Ended sessions show read-only message history, no input bar, no terminal
• "Session not found" error state displayed correctly
• Page title includes session short ID
• Navigating back to /sessions shows updated session state

Notes

• This is a pure composition page — minimal logic beyond routing and passing sessionId to child components
• Viewport height: use calc(100vh - headerHeight) for the SplitPane so it fills the screen without scrolling
• Do not re-fetch session messages in both this page and AgentChatPanel — let the chat panel own its message state via useAgentChat

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The web-ui is a Next.js 16 App Router project using React 19, Tailwind CSS, swr, axios, @radix-ui primitives, class-variance-authority, and @hugeicons/react. Pages are 'use client' components. The API layer lives in file:web-ui/src/lib/api.ts (axios-based, no sessionsApi yet). Hooks follow the pattern in file:web-ui/src/hooks/useEventSource.ts and file:web-ui/src/hooks/useTaskStream.ts. The three dependency components (SplitPane, AgentChatPanel, AgentTerminal) and the useAgentChat hook are not yet in the codebase — they are deliverables of issues #504–#508 that this ticket depends on.

Approach

Since this is a pure composition/integration page, the plan focuses on: (1) adding sessionsApi to the existing API module, (2) adding session-related TypeScript types, (3) creating the useAgentChat hook (the data-layer bridge this page owns), and (4) building the page itself by wiring the already-built child components. No new third-party libraries are needed.

---

Implementation Steps

1. Add Session Types to file:web-ui/src/types/index.ts

Add the following interfaces/types that mirror the backend session model:

• SessionState — union type 'active' | 'ended'
• SessionResponse — fields: id: string, short_id: string, state: SessionState, model: string, workspace_path: string, cost: number, created_at: string, ended_at: string | null
• SessionMessage — fields: id: string, role: 'user' | 'assistant', content: string, created_at: string
• SessionMessageListResponse — fields: messages: SessionMessage[], total: number

---

2. Add sessionsApi to file:web-ui/src/lib/api.ts

Following the exact same pattern as tasksApi, blockersApi, etc., add a new exported sessionsApi object with:

Method	HTTP	Endpoint
getOne(id)	GET	/api/v2/sessions/{id}
getMessages(id)	GET	/api/v2/sessions/{id}/messages
end(id)	DELETE	/api/v2/sessions/{id}

All methods use the shared api axios instance and return typed promises.

---

3. Create file:web-ui/src/hooks/useAgentChat.ts

This hook is the data-layer bridge for the chat panel. It should:

• Accept sessionId: string as its sole parameter
• On mount, fetch session metadata via sessionsApi.getOne(sessionId) and expose session, isLoading, error
• For active sessions: open a WebSocket connection to the backend (using the same NEXT_PUBLIC_SSE_URL base pattern from useTaskStream) to receive streaming agent messages; expose messages, sendMessage(text: string), wsStatus
• For ended sessions: fetch message history via sessionsApi.getMessages(sessionId) (REST, no WS); expose messages in read-only mode
• Expose totalCost: number derived from session metadata (updated live from WS events for active sessions)
• Export the hook and its return type from file:web-ui/src/hooks/index.ts

---

4. Create file:web-ui/src/components/sessions/SplitPane.tsx

A draggable two-pane layout component:

• Props: left: ReactNode, right: ReactNode, defaultLeftPercent?: number (default 45), storageKey?: string
• Uses useRef + onMouseDown/onMouseMove/onMouseUp on a drag handle div to resize panes
• Persists divider position to localStorage using storageKey on drag end; reads it on mount
• Renders as a flex row filling 100% of its container height; the drag handle is a thin vertical bar with a visible grab cursor
• No external drag library needed — native pointer events suffice

---

5. Create file:web-ui/src/components/sessions/AgentChatPanel.tsx

• Props: sessionId: string, readOnly?: boolean
• Internally calls useAgentChat(sessionId) to get messages, sendMessage, wsStatus, error
• Renders a scrollable message list (using @radix-ui/react-scroll-area as seen in other components) with user/assistant bubbles
• When readOnly is false (active session): renders a <textarea> input bar with a send button (Button from file:web-ui/src/components/ui/button.tsx); submits on Enter or button click
• When readOnly is true: hides the input bar entirely
• Shows a WS error banner (styled like the error state in file:web-ui/src/app/page.tsx) when wsStatus === 'error'
• Export from file:web-ui/src/components/sessions/index.ts

---

6. Create file:web-ui/src/components/sessions/AgentTerminal.tsx

• Props: sessionId: string
• Subscribes to the terminal output stream for the session (WS or SSE, following the useEventSource pattern)
• Renders terminal output lines in a monospace scrollable container
• When the session is ended, renders a muted message: "Terminal unavailable — session has ended"
• Export from file:web-ui/src/components/sessions/index.ts

---

7. Create the Session Detail Page file:web-ui/src/app/sessions/[id]/page.tsx

This is the final composition step. The page is 'use client' and receives params: { id: string } from the App Router.

Data fetching:

• Use useSWR with sessionsApi.getOne(id) to fetch session metadata on mount (consistent with how page.tsx uses useSWR)
• Derive shortId as the first 8 characters of id

Page metadata:

• Export a generateMetadata function (or use next/head if the page is client-only) that sets title to Session #${shortId} — CodeFRAME; since the page is 'use client', use a <title> tag inside a useEffect or a server wrapper

Layout structure:

┌─ Header bar (flex row, border-b) ──────────────────────────────────┐
│  <Link href="/sessions">← Sessions</Link>                          │
│  Session #{shortId}                                                 │
│  <Badge> 🟢 active | ⚪ ended </Badge>                             │
│  $0.012  (live from useAgentChat)                                   │
│  <Button variant="destructive" disabled={isEnded}>End Session</Button>│
└────────────────────────────────────────────────────────────────────┘
┌─ SplitPane (height: calc(100vh - headerHeight)) ───────────────────┐
│  <AgentChatPanel sessionId={id} readOnly={isEnded} />              │
│  <AgentTerminal sessionId={id} />  (hidden if ended)               │
└────────────────────────────────────────────────────────────────────┘

State branches:

flowchart TD
    A[Mount: useSWR sessionsApi.getOne] --> B{isLoading?}
    B -- yes --> C[Skeleton: header placeholder + two gray boxes]
    B -- no --> D{error?}
    D -- 404 --> E[Session not found + link to /sessions]
    D -- other --> F[Error banner]
    D -- none --> G{session.state}
    G -- active --> H[SplitPane: AgentChatPanel + AgentTerminal]
    G -- ended --> I[AgentChatPanel readOnly=true + ended banner\nAgentTerminal hidden]

Loading

End Session flow:

• [End Session] button opens an AlertDialog (already available at file:web-ui/src/components/ui/alert-dialog.tsx) for confirmation
• On confirm: call sessionsApi.end(id), then router.push('/sessions') using useRouter from next/navigation
• Button is disabled when session.state === 'ended' or while the delete is in-flight

Ended session banner:

• Render above AgentChatPanel when session.state === 'ended':
  "This session has ended." with a <Link href="/sessions">View history</Link>

Loading skeleton:

• Header placeholder: a h-10 w-64 rounded bg-muted animate-pulse bar
• Body: two side-by-side rounded-xl bg-muted animate-pulse boxes filling the remaining viewport height (matching the skeleton pattern in file:web-ui/src/app/page.tsx)

---

8. Add sessions Nav Item to file:web-ui/src/components/layout/AppSidebar.tsx

Add a { href: '/sessions', label: 'Sessions', icon: <suitable HugeIcon>, enabled: true } entry to the NAV_ITEMS array so the sidebar links to the sessions list page.

---

9. Export New Components from file:web-ui/src/components/sessions/index.ts

Create the barrel export file re-exporting SplitPane, AgentChatPanel, and AgentTerminal.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `web-ui` is a Next.js 16 App Router project using React 19, Tailwind CSS, `swr`, `axios`, `@radix-ui` primitives, `class-variance-authority`, and `@hugeicons/react`. Pages are `'use client'` components. The API layer lives in `file:web-ui/src/lib/api.ts` (axios-based, no `sessionsApi` yet). Hooks follow the pattern in `file:web-ui/src/hooks/useEventSource.ts` and `file:web-ui/src/hooks/useTaskStream.ts`. The three dependency components (`SplitPane`, `AgentChatPanel`, `AgentTerminal`) and the `useAgentChat` hook are not yet in the codebase — they are deliverables of issues #504–#508 that this ticket depends on.

## Approach

Since this is a pure composition/integration page, the plan focuses on: (1) adding `sessionsApi` to the existing API module, (2) adding session-related TypeScript types, (3) creating the `useAgentChat` hook (the data-layer bridge this page owns), and (4) building the page itself by wiring the already-built child components. No new third-party libraries are needed.

---

## Implementation Steps

### 1. Add Session Types to `file:web-ui/src/types/index.ts`

Add the following interfaces/types that mirror the backend session model:

- `SessionState` — union type `'active' | 'ended'`
- `SessionResponse` — fields: `id: string`, `short_id: string`, `state: SessionState`, `model: string`, `workspace_path: string`, `cost: number`, `created_at: string`, `ended_at: string | null`
- `SessionMessage` — fields: `id: string`, `role: 'user' | 'assistant'`, `content: string`, `created_at: string`
- `SessionMessageListResponse` — fields: `messages: SessionMessage[]`, `total: number`

---

### 2. Add `sessionsApi` to `file:web-ui/src/lib/api.ts`

Following the exact same pattern as `tasksApi`, `blockersApi`, etc., add a new exported `sessionsApi` object with:

| Method | HTTP | Endpoint |
|---|---|---|
| `getOne(id)` | `GET` | `/api/v2/sessions/{id}` |
| `getMessages(id)` | `GET` | `/api/v2/sessions/{id}/messages` |
| `end(id)` | `DELETE` | `/api/v2/sessions/{id}` |

All methods use the shared `api` axios instance and return typed promises.

---

### 3. Create `file:web-ui/src/hooks/useAgentChat.ts`

This hook is the data-layer bridge for the chat panel. It should:

- Accept `sessionId: string` as its sole parameter
- On mount, fetch session metadata via `sessionsApi.getOne(sessionId)` and expose `session`, `isLoading`, `error`
- For **active** sessions: open a WebSocket connection to the backend (using the same `NEXT_PUBLIC_SSE_URL` base pattern from `useTaskStream`) to receive streaming agent messages; expose `messages`, `sendMessage(text: string)`, `wsStatus`
- For **ended** sessions: fetch message history via `sessionsApi.getMessages(sessionId)` (REST, no WS); expose `messages` in read-only mode
- Expose `totalCost: number` derived from session metadata (updated live from WS events for active sessions)
- Export the hook and its return type from `file:web-ui/src/hooks/index.ts`

---

### 4. Create `file:web-ui/src/components/sessions/SplitPane.tsx`

A draggable two-pane layout component:

- Props: `left: ReactNode`, `right: ReactNode`, `defaultLeftPercent?: number` (default `45`), `storageKey?: string`
- Uses `useRef` + `onMouseDown`/`onMouseMove`/`onMouseUp` on a drag handle `div` to resize panes
- Persists divider position to `localStorage` using `storageKey` on drag end; reads it on mount
- Renders as a `flex` row filling `100%` of its container height; the drag handle is a thin vertical bar with a visible grab cursor
- No external drag library needed — native pointer events suffice

---

### 5. Create `file:web-ui/src/components/sessions/AgentChatPanel.tsx`

- Props: `sessionId: string`, `readOnly?: boolean`
- Internally calls `useAgentChat(sessionId)` to get `messages`, `sendMessage`, `wsStatus`, `error`
- Renders a scrollable message list (using `@radix-ui/react-scroll-area` as seen in other components) with user/assistant bubbles
- When `readOnly` is `false` (active session): renders a `<textarea>` input bar with a send button (`Button` from `file:web-ui/src/components/ui/button.tsx`); submits on Enter or button click
- When `readOnly` is `true`: hides the input bar entirely
- Shows a WS error banner (styled like the error state in `file:web-ui/src/app/page.tsx`) when `wsStatus === 'error'`
- Export from `file:web-ui/src/components/sessions/index.ts`

---

### 6. Create `file:web-ui/src/components/sessions/AgentTerminal.tsx`

- Props: `sessionId: string`
- Subscribes to the terminal output stream for the session (WS or SSE, following the `useEventSource` pattern)
- Renders terminal output lines in a monospace scrollable container
- When the session is ended, renders a muted message: _"Terminal unavailable — session has ended"_
- Export from `file:web-ui/src/components/sessions/index.ts`

---

### 7. Create the Session Detail Page `file:web-ui/src/app/sessions/[id]/page.tsx`

This is the final composition step. The page is `'use client'` and receives `params: { id: string }` from the App Router.

**Data fetching:**
- Use `useSWR` with `sessionsApi.getOne(id)` to fetch session metadata on mount (consistent with how `page.tsx` uses `useSWR`)
- Derive `shortId` as the first 8 characters of `id`

**Page metadata:**
- Export a `generateMetadata` function (or use `next/head` if the page is client-only) that sets `title` to `Session #${shortId} — CodeFRAME`; since the page is `'use client'`, use a `<title>` tag inside a `useEffect` or a server wrapper

**Layout structure:**

```
┌─ Header bar (flex row, border-b) ──────────────────────────────────┐
│  <Link href="/sessions">← Sessions</Link>                          │
│  Session #{shortId}                                                 │
│  <Badge> 🟢 active | ⚪ ended </Badge>                             │
│  $0.012  (live from useAgentChat)                                   │
│  <Button variant="destructive" disabled={isEnded}>End Session</Button>│
└────────────────────────────────────────────────────────────────────┘
┌─ SplitPane (height: calc(100vh - headerHeight)) ───────────────────┐
│  <AgentChatPanel sessionId={id} readOnly={isEnded} />              │
│  <AgentTerminal sessionId={id} />  (hidden if ended)               │
└────────────────────────────────────────────────────────────────────┘
```

**State branches:**

```mermaid
flowchart TD
    A[Mount: useSWR sessionsApi.getOne] --> B{isLoading?}
    B -- yes --> C[Skeleton: header placeholder + two gray boxes]
    B -- no --> D{error?}
    D -- 404 --> E[Session not found + link to /sessions]
    D -- other --> F[Error banner]
    D -- none --> G{session.state}
    G -- active --> H[SplitPane: AgentChatPanel + AgentTerminal]
    G -- ended --> I[AgentChatPanel readOnly=true + ended banner\nAgentTerminal hidden]
```

**End Session flow:**
- [End Session] button opens an `AlertDialog` (already available at `file:web-ui/src/components/ui/alert-dialog.tsx`) for confirmation
- On confirm: call `sessionsApi.end(id)`, then `router.push('/sessions')` using `useRouter` from `next/navigation`
- Button is `disabled` when `session.state === 'ended'` or while the delete is in-flight

**Ended session banner:**
- Render above `AgentChatPanel` when `session.state === 'ended'`:  
  _"This session has ended."_ with a `<Link href="/sessions">View history</Link>`

**Loading skeleton:**
- Header placeholder: a `h-10 w-64 rounded bg-muted animate-pulse` bar
- Body: two side-by-side `rounded-xl bg-muted animate-pulse` boxes filling the remaining viewport height (matching the skeleton pattern in `file:web-ui/src/app/page.tsx`)

---

### 8. Add `sessions` Nav Item to `file:web-ui/src/components/layout/AppSidebar.tsx`

Add a `{ href: '/sessions', label: 'Sessions', icon: <suitable HugeIcon>, enabled: true }` entry to the `NAV_ITEMS` array so the sidebar links to the sessions list page.

---

### 9. Export New Components from `file:web-ui/src/components/sessions/index.ts`

Create the barrel export file re-exporting `SplitPane`, `AgentChatPanel`, and `AgentTerminal`.

---

Execution Information

Branch: main
Commit: cb074e3

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#93 - fix(e2e): Fix dashboard and metrics tests for tab-based UI rendering [merged]
#215 - feat(dashboard): Add phase-aware task view integration (#016-6) [merged]
#489 - feat(web-ui): onboarding guidance card for new workspaces [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!