headquarter/openspec/changes/sessions-hub/design.md

Sessions Hub - Design

Architecture

Sessions Hub
├── Navigation
│   └── "Sessions" tab (between Dashboard and Projects)
│       └── Badge with active session count
├── SessionsPage
│   ├── Last Session Section
│   │   └── Quick access card with resume button
│   ├── Active Sessions Section
│   │   └── Grid of active session cards
│   ├── Recent Sessions Section
│   │   └── List of recent sessions
│   └── Create Session Section
│       └── Project selector + tool type selector
└── User Config
    └── last_session_id field

Component Design

SessionsPage

Sections:

1. Last Session (if exists)

   • Large card showing last session details
   • "Resume" button to open the workspace
   • Shows project, repository, tool type

2. Active Sessions

   • Grid of cards for running instances
   • Each card: name, type, status badge, action buttons
   • Actions: Open, Stop, Restart, Delete

3. Recent Sessions

   • List of last 5 sessions (any status)
   • Compact list view with status indicators
   • Click to navigate to workspace

4. Create New Session

   • Project dropdown (all user's projects)
   • Repository dropdown (filtered by project)
   • Tool type dropdown
   • Display name input
   • "Create" button

AppShell Updates

Navigation:

Dashboard | Sessions (3) | Projects | SSH Keys | Tool Types | Settings

Badge:

• Shows count of active (running) sessions
• Updates via existing sessions polling

User Config Extension

New field:

interface UserConfig {
  // existing fields...
  last_session_id: string | null;
}

Update timing:

• Set when creating a new session
• Set when opening/resuming a session

Data Flow

Loading Sessions Page

1. Fetch user config (for last_session_id)
2. Fetch all user sessions via /users/me/sessions
3. Filter into active vs recent
4. Display last session if available

Creating Session

1. User selects project, repo, tool type
2. POST to /projects/{id}/repositories/{id}/instances
3. On success: update user config with last_session_id
4. Refresh sessions list

Resuming Session

1. User clicks "Resume" on last session
2. Navigate to workspace with session active
3. Update user config (reinforce as last)

API Changes

GET /users/me/sessions

Already exists - returns all sessions for user.

PATCH /users/me/config

Already exists - add last_session_id to config schema.

Technical Details

Frontend:

• New page: pages/sessions.tsx
• Update: app-shell.tsx for navigation
• Update: api/settings.ts for config type
• Update: state/sessions.tsx for badge count

Backend:

• Update: models/user_config.py schema
• Update: api/user_config.py to accept last_session_id

No new backend endpoints needed - reuse existing APIs.

Error Handling

• No sessions: Show empty state with "Create your first session" CTA
• Failed to load: Show error with retry button
• Create failed: Show error message, keep form open