Frontend: /sessions list page + sidebar navigation entry

[frankbria]

Parent Issue

Part of #500 — depends on #501 (sessions CRUD API)

Context

There is currently no way to navigate to interactive sessions in the web-ui. This issue adds the /sessions page (a list of past and active sessions for the current workspace) and a sidebar navigation entry so users can discover and access it.

What to Build

1. New page: web-ui/src/app/sessions/page.tsx

Layout:

Sessions                          [+ New Session]
──────────────────────────────────────────────────
Search...

┌──────────────────────────────────────────────────┐
│ 🟢 Session #a3f2 · active                        │
│ workspace/myproject · claude-sonnet-4-6          │
│ Started 5 minutes ago · $0.012                   │
│                              [Resume →]          │
└──────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────┐
│ ⚪ Session #b1e7 · ended                          │
│ workspace/myproject · claude-sonnet-4-6          │
│ Ended 2 hours ago · $0.047                       │
│                              [View →]            │
└──────────────────────────────────────────────────┘

Data fetching:

• GET /api/v2/sessions?workspace_path=<current> via SWR with 10s revalidation
• Filter active sessions (state = active) and ended sessions separately
• Show active sessions first

Session card:

• State dot: green (active), gray (ended/paused)
• Session short ID (last 8 chars of UUID)
• Workspace path (basename only)
• Model name
• Relative start time + elapsed duration
• Cost so far
• [Resume →] for active, [View →] for ended — both link to /sessions/[id]
• [End] button for active sessions (calls DELETE /api/v2/sessions/{id}, confirms first)

New Session button:

• Opens a small modal/dialog:
  • Workspace path (pre-filled from current workspace, editable)
  • Model selector (dropdown: claude-sonnet-4-6, claude-opus-4-6, claude-haiku-4-5)
  • [Start Session] → POST /api/v2/sessions → redirect to /sessions/[id]

Empty state:

• Icon + "No sessions yet" + "Start a session to chat with your agent interactively"

Loading state:

• Skeleton cards (2–3 animate-pulse placeholders)

2. Sidebar navigation entry (web-ui/src/components/layout/AppSidebar.tsx)

Add "Sessions" as the 5th nav item (after Execution, before Blockers):

{ href: "/sessions", label: "Sessions", icon: MessageSquareIcon }

• Use appropriate Hugeicon (e.g., MessageMultiple01Icon or similar chat icon)
• Add active badge with count of active sessions (poll GET /api/v2/sessions?state=active every 30s — same pattern as blocker badge)

3. New layout file: web-ui/src/app/sessions/layout.tsx (if needed)

Standard page layout following the pattern of other pages.

Acceptance Criteria

• /sessions page lists sessions from API, sorted active first
• Session cards show state, model, elapsed time, and cost
• [Resume →] / [View →] links navigate to /sessions/[id]
• [End] button ends an active session with confirmation
• "New Session" modal creates a session and redirects to detail page
• Empty state shown when no sessions exist
• Loading skeletons shown during initial fetch
• Sidebar nav entry visible, active-highlighted when on /sessions
• Sidebar badge shows count of active sessions

Notes

• Reuse existing card patterns from TaskCard or workspace components for consistency
• Workspace path comes from getSelectedWorkspacePath() (existing localStorage helper)

[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 codebase follows a clear pattern: each feature area has a page.tsx that reads workspacePath from getSelectedWorkspacePath(), guards against missing workspace, then delegates to a dedicated view component (e.g., BlockerResolutionView, TaskBoardView). The sidebar (AppSidebar) uses useSWR + @hugeicons/react icons + an inline badge for the Blockers count. The API client (api.ts) uses axios with a shared instance. Types live in web-ui/src/types/index.ts. date-fns, swr, @radix-ui/react-dialog, and @radix-ui/react-select are all already installed.

Approach

Follow the established page → view-component split exactly as done for Tasks and Blockers. Add a sessionsApi object to api.ts, Session/SessionListResponse types to types/index.ts, a SessionsListView component, the page.tsx shell, and finally wire the sidebar entry with its active-session badge. No new libraries are needed.

---

Implementation Steps

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

Append the following type definitions (mirroring the backend sessions API from issue #501):

• SessionState — union type: 'active' | 'ended' | 'paused'
• Session interface:
  • id: string
  • workspace_path: string
  • model: string
  • state: SessionState
  • started_at: string
  • ended_at: string | null
  • cost_usd: number | null
• SessionListResponse interface:
  • sessions: Session[]
  • total: number
• CreateSessionRequest interface:
  • workspace_path: string
  • model: string

---

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

Add a new exported sessionsApi object following the exact same axios pattern as blockersApi and tasksApi:

Method	Signature	HTTP call
getAll	(workspacePath: string, options?: { state?: SessionState }) => Promise<SessionListResponse>	GET /api/v2/sessions with workspace_path + optional state params
create	(request: CreateSessionRequest) => Promise<Session>	POST /api/v2/sessions
end	(sessionId: string) => Promise<void>	DELETE /api/v2/sessions/{id}

Import Session, SessionListResponse, CreateSessionRequest, SessionState from @/types at the top of the file alongside the existing imports.

---

3. Create file:web-ui/src/components/sessions/SessionCard.tsx

A new 'use client' component modelled after TaskCard. Props:

interface SessionCardProps {
  session: Session;
  onEnd: (sessionId: string) => void;
  isEnding?: boolean;
}

Card layout (use Card + CardContent from @/components/ui/card, Button from @/components/ui/button, Link from next/link, formatDistanceToNow from date-fns):

• State dot: a small inline-block circle — bg-green-500 for active, bg-gray-400 for ended/paused
• Header row: state dot + Session #${session.id.slice(-8)} + state label
• Sub-row: basename(session.workspace_path) · session.model
• Meta row: relative start time via formatDistanceToNow(new Date(session.started_at), { addSuffix: true }) + cost formatted as $${session.cost_usd?.toFixed(3) ?? '—'}
• Action row (right-aligned):
  • For active: a ghost destructive [End] Button (calls onEnd, disabled when isEnding) + a Link to /sessions/${session.id} rendered as a primary Button labelled Resume →
  • For ended/paused: a Link to /sessions/${session.id} rendered as an outline Button labelled View →

---

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

A 'use client' component using the existing Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter from @/components/ui/dialog and @radix-ui/react-select (already installed) for the model dropdown.

Props:

interface NewSessionDialogProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
  defaultWorkspacePath: string;
  onCreated: (session: Session) => void;
}

Internal state: workspacePath (string, pre-filled from prop), model (string, default 'claude-sonnet-4-6'), isSubmitting (boolean), error (string | null).

Model options: claude-sonnet-4-6, claude-opus-4-6, claude-haiku-4-5 — rendered as <select> items using Radix Select primitives already present in the project.

Submit handler: calls sessionsApi.create({ workspace_path, model }), then calls onCreated(session) with the returned session. The parent will redirect to /sessions/${session.id} using useRouter().push.

---

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

A 'use client' component that owns all data-fetching and rendering logic for the sessions list page. Props: { workspacePath: string }.

Data fetching (use useSWR from swr):

• Key: `/api/v2/sessions?workspace_path=${workspacePath}`
• Fetcher: () => sessionsApi.getAll(workspacePath)
• Options: { refreshInterval: 10000 }

Derived state:

• activeSessions = sessions filtered by state === 'active'
• otherSessions = remaining sessions
• Render active sessions first, then others

Loading state: when !data && !error, render 3 skeleton cards — div elements with animate-pulse and rounded-lg border bg-muted h-24 (matching Tailwind patterns used elsewhere).

Empty state: when data?.sessions.length === 0, render a centred block with an icon (e.g., MessageMultiple01Icon from @hugeicons/react), "No sessions yet" heading, and "Start a session to chat with your agent interactively" subtext.

End session handler: local endingId state; calls sessionsApi.end(id), then calls mutate() to revalidate SWR.

New Session button: opens NewSessionDialog; on onCreated, use useRouter().push('/sessions/' + session.id).

Layout:

<div>
  <header>  {/* "Sessions" h1 + "+ New Session" Button */}
  <input type="search" placeholder="Search..." />  {/* client-side filter on session id/model/workspace */}
  <section>  {/* active sessions */}
  <section>  {/* ended sessions */}
</div>

---

6. Create file:web-ui/src/app/sessions/page.tsx

Follow the exact pattern of file:web-ui/src/app/blockers/page.tsx and file:web-ui/src/app/tasks/page.tsx:

• 'use client'
• useState + useEffect to read getSelectedWorkspacePath() and set workspaceReady
• Return null while hydrating
• Return the "no workspace" message if !workspacePath
• Otherwise render <main className="min-h-screen bg-background"><div className="mx-auto max-w-7xl px-4 py-8"><SessionsListView workspacePath={workspacePath} /></div></main>

No separate layout.tsx is needed — the root AppLayout already wraps all pages.

---

7. Update file:web-ui/src/components/layout/AppSidebar.tsx

a) Add the icon import

Add MessageMultiple01Icon (or the closest available chat icon in @hugeicons/react) to the existing import block from @hugeicons/react.

b) Add the Sessions nav item

Insert into NAV_ITEMS between Execution and Blockers:

{ href: '/sessions', label: 'Sessions', icon: MessageMultiple01Icon, enabled: true }

c) Add active-session badge SWR fetch

Mirror the existing blocker badge pattern. Add a second useSWR call:

• Key: workspacePath ? '/api/v2/sessions/sidebar?state=active' : null
• Fetcher: () => sessionsApi.getAll(workspacePath!, { state: 'active' })
• Options: { refreshInterval: 30000 }
• Derive: const activeSessionCount = sessionData?.sessions.length ?? 0

Import sessionsApi from @/lib/api and SessionListResponse from @/types.

d) Render the badge

Inside the Link render for the Sessions item, add the same badge pattern used for Blockers — a green pill (bg-green-500) showing activeSessionCount when > 0.

sequenceDiagram
    participant User
    participant AppSidebar
    participant SessionsPage
    participant SessionsListView
    participant sessionsApi
    participant NewSessionDialog

    User->>AppSidebar: clicks "Sessions" nav item
    AppSidebar->>SessionsPage: navigate /sessions
    SessionsPage->>SessionsListView: render with workspacePath
    SessionsListView->>sessionsApi: getAll(workspacePath) via SWR (10s)
    sessionsApi-->>SessionsListView: SessionListResponse
    SessionsListView-->>User: renders SessionCards (active first)

    User->>SessionsListView: clicks "+ New Session"
    SessionsListView->>NewSessionDialog: open=true
    User->>NewSessionDialog: fills workspace + model, clicks Start
    NewSessionDialog->>sessionsApi: create({ workspace_path, model })
    sessionsApi-->>NewSessionDialog: Session
    NewSessionDialog->>SessionsPage: onCreated → router.push(/sessions/[id])

    User->>SessionsListView: clicks [End] on active card
    SessionsListView->>sessionsApi: end(sessionId)
    sessionsApi-->>SessionsListView: void
    SessionsListView->>sessionsApi: mutate() → refresh list

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase follows a clear pattern: each feature area has a `page.tsx` that reads `workspacePath` from `getSelectedWorkspacePath()`, guards against missing workspace, then delegates to a dedicated view component (e.g., `BlockerResolutionView`, `TaskBoardView`). The sidebar (`AppSidebar`) uses `useSWR` + `@hugeicons/react` icons + an inline badge for the Blockers count. The API client (`api.ts`) uses axios with a shared instance. Types live in `web-ui/src/types/index.ts`. `date-fns`, `swr`, `@radix-ui/react-dialog`, and `@radix-ui/react-select` are all already installed.

## Approach

Follow the established page → view-component split exactly as done for Tasks and Blockers. Add a `sessionsApi` object to `api.ts`, `Session`/`SessionListResponse` types to `types/index.ts`, a `SessionsListView` component, the `page.tsx` shell, and finally wire the sidebar entry with its active-session badge. No new libraries are needed.

---

## Implementation Steps

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

Append the following type definitions (mirroring the backend sessions API from issue #501):

- `SessionState` — union type: `'active' | 'ended' | 'paused'`
- `Session` interface:
  - `id: string`
  - `workspace_path: string`
  - `model: string`
  - `state: SessionState`
  - `started_at: string`
  - `ended_at: string | null`
  - `cost_usd: number | null`
- `SessionListResponse` interface:
  - `sessions: Session[]`
  - `total: number`
- `CreateSessionRequest` interface:
  - `workspace_path: string`
  - `model: string`

---

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

Add a new exported `sessionsApi` object following the exact same axios pattern as `blockersApi` and `tasksApi`:

| Method | Signature | HTTP call |
|---|---|---|
| `getAll` | `(workspacePath: string, options?: { state?: SessionState }) => Promise<SessionListResponse>` | `GET /api/v2/sessions` with `workspace_path` + optional `state` params |
| `create` | `(request: CreateSessionRequest) => Promise<Session>` | `POST /api/v2/sessions` |
| `end` | `(sessionId: string) => Promise<void>` | `DELETE /api/v2/sessions/{id}` |

Import `Session`, `SessionListResponse`, `CreateSessionRequest`, `SessionState` from `@/types` at the top of the file alongside the existing imports.

---

### 3. Create `file:web-ui/src/components/sessions/SessionCard.tsx`

A new `'use client'` component modelled after `TaskCard`. Props:

```
interface SessionCardProps {
  session: Session;
  onEnd: (sessionId: string) => void;
  isEnding?: boolean;
}
```

**Card layout** (use `Card` + `CardContent` from `@/components/ui/card`, `Button` from `@/components/ui/button`, `Link` from `next/link`, `formatDistanceToNow` from `date-fns`):

- **State dot**: a small `inline-block` circle — `bg-green-500` for `active`, `bg-gray-400` for `ended`/`paused`
- **Header row**: state dot + `Session #${session.id.slice(-8)}` + state label
- **Sub-row**: `basename(session.workspace_path)` · `session.model`
- **Meta row**: relative start time via `formatDistanceToNow(new Date(session.started_at), { addSuffix: true })` + cost formatted as `$${session.cost_usd?.toFixed(3) ?? '—'}`
- **Action row** (right-aligned):
  - For `active`: a ghost destructive `[End]` `Button` (calls `onEnd`, disabled when `isEnding`) + a `Link` to `/sessions/${session.id}` rendered as a primary `Button` labelled `Resume →`
  - For `ended`/`paused`: a `Link` to `/sessions/${session.id}` rendered as an outline `Button` labelled `View →`

---

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

A `'use client'` component using the existing `Dialog`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogFooter` from `@/components/ui/dialog` and `@radix-ui/react-select` (already installed) for the model dropdown.

**Props:**
```
interface NewSessionDialogProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
  defaultWorkspacePath: string;
  onCreated: (session: Session) => void;
}
```

**Internal state**: `workspacePath` (string, pre-filled from prop), `model` (string, default `'claude-sonnet-4-6'`), `isSubmitting` (boolean), `error` (string | null).

**Model options**: `claude-sonnet-4-6`, `claude-opus-4-6`, `claude-haiku-4-5` — rendered as `<select>` items using Radix Select primitives already present in the project.

**Submit handler**: calls `sessionsApi.create({ workspace_path, model })`, then calls `onCreated(session)` with the returned session. The parent will redirect to `/sessions/${session.id}` using `useRouter().push`.

---

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

A `'use client'` component that owns all data-fetching and rendering logic for the sessions list page. Props: `{ workspacePath: string }`.

**Data fetching** (use `useSWR` from `swr`):
- Key: `` `/api/v2/sessions?workspace_path=${workspacePath}` ``
- Fetcher: `() => sessionsApi.getAll(workspacePath)`
- Options: `{ refreshInterval: 10000 }`

**Derived state**:
- `activeSessions` = sessions filtered by `state === 'active'`
- `otherSessions` = remaining sessions
- Render active sessions first, then others

**Loading state**: when `!data && !error`, render 3 skeleton cards — `div` elements with `animate-pulse` and `rounded-lg border bg-muted h-24` (matching Tailwind patterns used elsewhere).

**Empty state**: when `data?.sessions.length === 0`, render a centred block with an icon (e.g., `MessageMultiple01Icon` from `@hugeicons/react`), "No sessions yet" heading, and "Start a session to chat with your agent interactively" subtext.

**End session handler**: local `endingId` state; calls `sessionsApi.end(id)`, then calls `mutate()` to revalidate SWR.

**New Session button**: opens `NewSessionDialog`; on `onCreated`, use `useRouter().push('/sessions/' + session.id)`.

**Layout**:
```
<div>
  <header>  {/* "Sessions" h1 + "+ New Session" Button */}
  <input type="search" placeholder="Search..." />  {/* client-side filter on session id/model/workspace */}
  <section>  {/* active sessions */}
  <section>  {/* ended sessions */}
</div>
```

---

### 6. Create `file:web-ui/src/app/sessions/page.tsx`

Follow the exact pattern of `file:web-ui/src/app/blockers/page.tsx` and `file:web-ui/src/app/tasks/page.tsx`:

- `'use client'`
- `useState` + `useEffect` to read `getSelectedWorkspacePath()` and set `workspaceReady`
- Return `null` while hydrating
- Return the "no workspace" message if `!workspacePath`
- Otherwise render `<main className="min-h-screen bg-background"><div className="mx-auto max-w-7xl px-4 py-8"><SessionsListView workspacePath={workspacePath} /></div></main>`

No separate `layout.tsx` is needed — the root `AppLayout` already wraps all pages.

---

### 7. Update `file:web-ui/src/components/layout/AppSidebar.tsx`

**a) Add the icon import**

Add `MessageMultiple01Icon` (or the closest available chat icon in `@hugeicons/react`) to the existing import block from `@hugeicons/react`.

**b) Add the Sessions nav item**

Insert into `NAV_ITEMS` between `Execution` and `Blockers`:

```
{ href: '/sessions', label: 'Sessions', icon: MessageMultiple01Icon, enabled: true }
```

**c) Add active-session badge SWR fetch**

Mirror the existing blocker badge pattern. Add a second `useSWR` call:

- Key: `workspacePath ? '/api/v2/sessions/sidebar?state=active' : null`
- Fetcher: `() => sessionsApi.getAll(workspacePath!, { state: 'active' })`
- Options: `{ refreshInterval: 30000 }`
- Derive: `const activeSessionCount = sessionData?.sessions.length ?? 0`

Import `sessionsApi` from `@/lib/api` and `SessionListResponse` from `@/types`.

**d) Render the badge**

Inside the `Link` render for the Sessions item, add the same badge pattern used for Blockers — a green pill (`bg-green-500`) showing `activeSessionCount` when `> 0`.

```mermaid
sequenceDiagram
    participant User
    participant AppSidebar
    participant SessionsPage
    participant SessionsListView
    participant sessionsApi
    participant NewSessionDialog

    User->>AppSidebar: clicks "Sessions" nav item
    AppSidebar->>SessionsPage: navigate /sessions
    SessionsPage->>SessionsListView: render with workspacePath
    SessionsListView->>sessionsApi: getAll(workspacePath) via SWR (10s)
    sessionsApi-->>SessionsListView: SessionListResponse
    SessionsListView-->>User: renders SessionCards (active first)

    User->>SessionsListView: clicks "+ New Session"
    SessionsListView->>NewSessionDialog: open=true
    User->>NewSessionDialog: fills workspace + model, clicks Start
    NewSessionDialog->>sessionsApi: create({ workspace_path, model })
    sessionsApi-->>NewSessionDialog: Session
    NewSessionDialog->>SessionsPage: onCreated → router.push(/sessions/[id])

    User->>SessionsListView: clicks [End] on active card
    SessionsListView->>sessionsApi: end(sessionId)
    sessionsApi-->>SessionsListView: void
    SessionsListView->>sessionsApi: mutate() → refresh list
```

---

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

#213 - feat(planning): Add Generate Task Breakdown button to DiscoveryProgress [merged]
#215 - feat(dashboard): Add phase-aware task view integration (#016-6) [merged]
#489 - feat(web-ui): onboarding guidance card for new workspaces [merged]
#493 - feat(web-ui): context-aware Quick Actions based on workspace state (#471) [merged]
#498 - feat(web-ui): task dependency graph visualization in detail modal (#476) [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!