headquarter/openspec/changes/sessions-hub/specs/spec.md

Sessions Hub Specification

Requirements

Functional Requirements

1. Sessions Tab: Navigation item between Dashboard and Projects
2. Active Sessions Display: Show all running sessions with actions
3. Last Session: Prominently show last created/accessed session
4. Quick Create: Create sessions for any project from Sessions page
5. Session Persistence: Save last_session_id in user config
6. Badge: Show active session count in navigation

Non-Functional Requirements

1. Performance: Load sessions in < 500ms
2. Real-time: Badge updates with active count
3. Responsive: Works on mobile and desktop

API Specification

Existing Endpoints Used

• GET /users/me/sessions - List all user sessions
• POST /projects/{id}/repositories/{id}/instances - Create instance
• GET /projects - List projects for selector
• GET /projects/{id}/repositories - List repos for selector
• GET /tool-types - List tool types for selector
• GET /users/me/config - Get user config (with last_session_id)
• PATCH /users/me/config - Update user config (last_session_id)

User Config Schema Update

class UserConfigUpdate(BaseModel):
    theme: Optional[str] = None
    default_editor: Optional[str] = None
    git_user_name: Optional[str] = None
    git_user_email: Optional[str] = None
    last_session_id: Optional[str] = None  # NEW

UI Specification

Sessions Page Layout

+------------------------------------------+
| Sessions                    [New Session]|
+------------------------------------------+
|                                          |
| Last Session                             |
| +--------------------------------------+ |
| | VS Code Server - My Project    [Open] | |
| | Running on port 8080                   | |
| +--------------------------------------+ |
|                                          |
| Active Sessions (3)                      |
| +----------+ +----------+ +----------+  |
| | Session 1| | Session 2| | Session 3|  |
| | Running  | | Running  | | Running  |  |
| | [Open]   | | [Open]   | | [Open]   |  |
| +----------+ +----------+ +----------+  |
|                                          |
| Recent Sessions                          |
| - Session 4 (stopped)                    |
| - Session 5 (stopped)                    |
|                                          |
+------------------------------------------+

Navigation Badge

[Dashboard] [Sessions (3)] [Projects] ...

Badge shows count of sessions with status === "running".

Create Session Dialog

+------------------------------------------+
| Create New Session                       |
+------------------------------------------+
| Project: [Dropdown]                      |
| Repository: [Dropdown]                   |
| Tool Type: [Dropdown]                    |
| Name: [Input]                            |
|                                          |
| [Cancel]          [Create]               |
+------------------------------------------+

State Management

Sessions Context (existing)

Already polls /users/me/sessions every 10s. Use this for:

• Active session count (badge)
• Active sessions list
• Recent sessions list

User Config (existing)

Add last_session_id field. Update:

• On session creation
• On session open/resume

Quality Gates

• TypeScript compilation passes
• ESLint passes
• All sessions load correctly
• Badge updates with active count
• Last session persists across reloads
• Create session works from Sessions page