OpenSpeak/openspec/changes/add-presence-tracking/presence.md

# Spec Delta: User Presence Tracking

**Change ID:** `add-presence-tracking`
**Capability:** User Presence Tracking
**Type:** NEW

## ADDED Requirements

### User Session Management

#### Requirement: Server shall create and track user sessions

**Description:** When user connects with valid token, server creates session tracking user identity, connection state, and lifetime.

**Priority:** High
**Status:** Proposed

**Scenarios:**

#### Scenario: User session created on connection
```
Given: Client connects with valid token
When: gRPC connection established
Then: Server creates new session
And: Session includes: user_id, session_id, connected_at
And: User marked as ONLINE
And: Session persists for connection lifetime
```

#### Scenario: Session destroyed on disconnect
```
Given: User has active session
When: Connection is closed
Then: Server destroys session
And: User marked as OFFLINE
And: UserOffline event broadcast
And: Channel membership updated
```

### Presence Status

#### Requirement: Server shall track and broadcast user presence status

**Description:** Users have status: ONLINE, IDLE, OFFLINE. Status is tracked and broadcast to all connected clients.

**Priority:** High
**Status:** Proposed

**Details:**
- ONLINE: Connected and active
- IDLE: Connected but inactive 5+ minutes
- OFFLINE: Not connected
- Future: DO_NOT_DISTURB, AWAY

**Scenarios:**

#### Scenario: User status transitions
```
Given: User just connected
Then: Status is ONLINE

When: User inactive for 5 minutes
Then: Status changes to IDLE

When: User takes action
Then: Status returns to ONLINE
```

#### Scenario: Presence broadcast
```
Given: Users A and B connected to server
When: User A comes online
Then: User B receives UserOnline event
And: Event includes User A's presence info
And: User A appears in online user list for B
```

### Idle Detection

#### Requirement: Server shall detect and mark idle users

**Description:** Background process monitors activity and marks users idle after 5 minutes of inactivity.

**Priority:** High
**Status:** Proposed

**Scenarios:**

#### Scenario: Idle detection after timeout
```
Given: User connected but inactive for 5 minutes
When: Server checks for idle users
Then: User marked as IDLE status
And: UserStatusChanged event broadcast
And: Other users see user as idle
```

#### Scenario: Activity resumes
```
Given: User is IDLE
When: User takes any action (join channel, send message, etc)
Then: User marked as ONLINE again
And: Idle timer reset
```

### Channel Presence

#### Requirement: Server shall track which channel users are in

**Description:** Presence includes current channel. Updated when user joins/leaves channel.

**Priority:** High
**Status:** Proposed

**Scenarios:**

#### Scenario: Channel presence tracked
```
Given: User joins "general" channel
When: Server updates user presence
Then: Presence includes: current_channel_id = "general"
And: UserChannelChanged event broadcast
And: Other users see user in "general"

When: User leaves "general" and joins "announcements"
Then: Presence updated: current_channel_id = "announcements"
And: UserChannelChanged event broadcast
```

### Mute Status

#### Requirement: Server shall track microphone and speaker mute state

**Description:** Presence includes mute status for microphone and speaker. Updated when user toggles mute.

**Priority:** High
**Status:** Proposed

**Scenarios:**

#### Scenario: User mutes microphone
```
Given: User in voice channel with microphone active
When: User toggles microphone mute
Then: Server receives mute status update
And: Presence updated: is_microphone_muted = true
And: UserMuteStateChanged event broadcast
And: Other channel members see user as muted
```

#### Scenario: Multiple mute states
```
Given: User in channel
When: User mutes microphone only
Then: is_microphone_muted = true, is_speaker_muted = false

When: User also mutes speakers
Then: is_microphone_muted = true, is_speaker_muted = true
```

### Online User List

#### Requirement: Clients can query list of all online users

**Description:** Clients can retrieve real-time list of all currently online users with their presence details.

**Priority:** High
**Status:** Proposed

**Scenarios:**

#### Scenario: Get online users list
```
Given: Server has 5 online users
When: Client requests ListOnlineUsers
Then: Response includes all 5 users
And: Each user includes: user_id, status, current_channel, mute_state
And: Response is current (not stale)
```

### Channel Member Presence

#### Requirement: Clients can query presence of channel members

**Description:** Get presence information for all members in specific channel.

**Priority:** High
**Status:** Proposed

**Scenarios:**

#### Scenario: Get channel members with presence
```
Given: Channel "general" has 3 members
When: Client requests ListChannelMembers with channel_id
Then: Response includes all 3 members
And: Each includes: user_id, status, microphone_muted, speaker_muted
And: Presence info helps UI show who can talk
```

### Presence Events

#### Requirement: Server broadcasts presence changes to all clients

**Description:** Real-time events notify clients when presence changes.

**Priority:** High
**Status:** Proposed

**Scenarios:**

#### Scenario: Presence event broadcast
```
Given: Client A subscribed to presence events
When: User B comes online
Then: Client A receives UserOnlineEvent
And: Event includes User B's full presence
And: Event includes timestamp

When: User C changes channel
Then: UserChannelChangedEvent broadcast
And: Subscribers notified immediately
```

## ACCEPTANCE CRITERIA

- [ ] Sessions created and tracked properly
- [ ] Presence status accurate (ONLINE/IDLE/OFFLINE)
- [ ] Idle detection works (5-minute timeout)
- [ ] Channel membership tracked in presence
- [ ] Mute status tracked and updated
- [ ] Online user list real-time and accurate
- [ ] Presence events broadcast to subscribers
- [ ] Disconnection cleanup works properly
- [ ] Unit test coverage >80%

## TESTING STRATEGY

### Unit Tests
- Test session creation and destruction
- Test status transitions
- Test idle detection logic
- Test mute state management

### Integration Tests
- Test presence event broadcasting
- Test multiple clients receiving presence updates
- Test idle timeout and recovery
- Test channel membership tracking

### Scenarios
- 100+ online users tracking
- Rapid status changes
- Concurrent connections and disconnections
- Event broadcast to many subscribers