elsabro 2.3.0 → 3.7.0

package/references/collaborative-sessions.md

@@ -0,0 +1,1081 @@
+# ELSABRO Collaborative Sessions System
+
+> Sistema de sesiones colaborativas en tiempo real para múltiples usuarios y agentes.
+
+## Arquitectura General
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    Collaborative Sessions System                         │
+├─────────────────────────────────────────────────────────────────────────┤
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐         │
+│  │ SessionManager  │  │  RealtimeSync   │  │ConflictResolver │         │
+│  │  ─────────────  │  │  ─────────────  │  │  ─────────────  │         │
+│  │ • Create/Join   │  │ • WebSocket     │  │ • OT/CRDT       │         │
+│  │ • Permissions   │  │ • Broadcasting  │  │ • Auto-merge    │         │
+│  │ • History       │  │ • Reconnection  │  │ • Manual resolve│         │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘         │
+│                              │                                          │
+│  ┌───────────────────────────┴───────────────────────────────┐         │
+│  │                   PresenceTracker                          │         │
+│  │  • Online users • Cursors • Activity • Typing indicators  │         │
+│  └────────────────────────────────────────────────────────────┘         │
+│                              │                                          │
+│  ┌───────────────────────────┴───────────────────────────────┐         │
+│  │                   CollaborativeState                       │         │
+│  │  • Shared state • Atomic updates • Event sourcing         │         │
+│  └────────────────────────────────────────────────────────────┘         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 1. SessionManager
+
+### Propósito
+Gestiona el ciclo de vida de sesiones colaborativas.
+
+### Interfaz
+
+```typescript
+interface CollaborativeSession {
+  id: string;
+  name: string;
+  type: 'flow' | 'planning' | 'review' | 'debug';
+  host: Participant;
+  participants: Participant[];
+  state: SessionState;
+  permissions: SessionPermissions;
+  settings: SessionSettings;
+  createdAt: string;
+  expiresAt?: string;
+}
+
+interface Participant {
+  id: string;
+  name: string;
+  type: 'user' | 'agent';
+  role: 'host' | 'editor' | 'viewer';
+  color: string;  // For presence indicators
+  cursor?: CursorPosition;
+  status: 'online' | 'away' | 'offline';
+  joinedAt: string;
+  lastActivity: string;
+}
+
+interface SessionState {
+  version: number;
+  data: Record<string, unknown>;
+  locks: Map<string, string>;  // path -> participantId
+  history: StateChange[];
+}
+
+interface SessionPermissions {
+  canEdit: string[];      // Role or participant IDs
+  canInvite: string[];
+  canKick: string[];
+  canLock: string[];
+  maxParticipants: number;
+}
+
+interface SessionSettings {
+  autoSave: boolean;
+  saveInterval: number;
+  conflictResolution: 'automatic' | 'manual' | 'last-write-wins';
+  allowAnonymous: boolean;
+  requireApproval: boolean;
+  idleTimeout: number;
+}
+
+interface SessionManager {
+  // Session lifecycle
+  create(config: CreateSessionConfig): Promise<CollaborativeSession>;
+  join(sessionId: string, participant: Omit<Participant, 'joinedAt' | 'lastActivity'>): Promise<CollaborativeSession>;
+  leave(sessionId: string, participantId: string): Promise<void>;
+  close(sessionId: string): Promise<void>;
+
+  // Session queries
+  get(sessionId: string): Promise<CollaborativeSession | null>;
+  list(filter?: SessionFilter): Promise<CollaborativeSession[]>;
+  findByParticipant(participantId: string): Promise<CollaborativeSession[]>;
+
+  // Invitations
+  invite(sessionId: string, email: string, role: Participant['role']): Promise<Invitation>;
+  acceptInvitation(invitationId: string, participant: Participant): Promise<CollaborativeSession>;
+  revokeInvitation(invitationId: string): Promise<void>;
+
+  // Permissions
+  updatePermissions(sessionId: string, permissions: Partial<SessionPermissions>): Promise<void>;
+  updateParticipantRole(sessionId: string, participantId: string, role: Participant['role']): Promise<void>;
+  kickParticipant(sessionId: string, participantId: string, reason?: string): Promise<void>;
+
+  // Events
+  on(event: SessionEvent, callback: Function): () => void;
+}
+
+type SessionEvent =
+  | 'session:created'
+  | 'session:closed'
+  | 'participant:joined'
+  | 'participant:left'
+  | 'participant:kicked'
+  | 'state:changed'
+  | 'conflict:detected'
+  | 'error';
+```
+
+### Implementación
+
+```typescript
+class SessionManagerImpl implements SessionManager {
+  private sessions: Map<string, CollaborativeSession> = new Map();
+  private invitations: Map<string, Invitation> = new Map();
+  private eventEmitter: EventEmitter = new EventEmitter();
+
+  constructor(
+    private sync: RealtimeSync,
+    private presence: PresenceTracker,
+    private config: SessionManagerConfig
+  ) {}
+
+  async create(config: CreateSessionConfig): Promise<CollaborativeSession> {
+    const sessionId = `session_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+    const session: CollaborativeSession = {
+      id: sessionId,
+      name: config.name,
+      type: config.type,
+      host: config.host,
+      participants: [config.host],
+      state: {
+        version: 0,
+        data: config.initialData || {},
+        locks: new Map(),
+        history: []
+      },
+      permissions: config.permissions || this.getDefaultPermissions(),
+      settings: { ...this.config.defaultSettings, ...config.settings },
+      createdAt: new Date().toISOString()
+    };
+
+    if (config.expiresIn) {
+      session.expiresAt = new Date(Date.now() + config.expiresIn).toISOString();
+    }
+
+    this.sessions.set(sessionId, session);
+
+    // Initialize realtime sync
+    await this.sync.initSession(sessionId);
+
+    // Track host presence
+    this.presence.track(sessionId, config.host.id);
+
+    this.eventEmitter.emit('session:created', session);
+    return session;
+  }
+
+  async join(
+    sessionId: string,
+    participant: Omit<Participant, 'joinedAt' | 'lastActivity'>
+  ): Promise<CollaborativeSession> {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${sessionId}`);
+    }
+
+    // Check max participants
+    if (session.participants.length >= session.permissions.maxParticipants) {
+      throw new Error('Session is full');
+    }
+
+    // Check if requires approval
+    if (session.settings.requireApproval) {
+      await this.requestApproval(session, participant);
+    }
+
+    const fullParticipant: Participant = {
+      ...participant,
+      color: this.assignColor(session),
+      status: 'online',
+      joinedAt: new Date().toISOString(),
+      lastActivity: new Date().toISOString()
+    };
+
+    session.participants.push(fullParticipant);
+
+    // Subscribe to realtime updates
+    await this.sync.subscribe(sessionId, participant.id);
+
+    // Track presence
+    this.presence.track(sessionId, participant.id);
+
+    this.eventEmitter.emit('participant:joined', {
+      session,
+      participant: fullParticipant
+    });
+
+    // Broadcast to other participants
+    await this.sync.broadcast(sessionId, {
+      type: 'participant:joined',
+      participant: fullParticipant
+    });
+
+    return session;
+  }
+
+  async leave(sessionId: string, participantId: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+
+    const participantIndex = session.participants.findIndex(p => p.id === participantId);
+    if (participantIndex === -1) return;
+
+    const participant = session.participants[participantIndex];
+    session.participants.splice(participantIndex, 1);
+
+    // Release any locks held by this participant
+    for (const [path, lockHolder] of session.state.locks) {
+      if (lockHolder === participantId) {
+        session.state.locks.delete(path);
+      }
+    }
+
+    // Unsubscribe from updates
+    await this.sync.unsubscribe(sessionId, participantId);
+
+    // Stop presence tracking
+    this.presence.untrack(sessionId, participantId);
+
+    this.eventEmitter.emit('participant:left', { session, participant });
+
+    // Broadcast to remaining participants
+    await this.sync.broadcast(sessionId, {
+      type: 'participant:left',
+      participantId
+    });
+
+    // If host left, transfer or close
+    if (participant.role === 'host') {
+      await this.handleHostLeave(session);
+    }
+  }
+
+  async close(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+
+    // Notify all participants
+    await this.sync.broadcast(sessionId, {
+      type: 'session:closing',
+      reason: 'Host closed the session'
+    });
+
+    // Clean up all participants
+    for (const participant of session.participants) {
+      await this.leave(sessionId, participant.id);
+    }
+
+    // Destroy sync channel
+    await this.sync.destroySession(sessionId);
+
+    this.sessions.delete(sessionId);
+    this.eventEmitter.emit('session:closed', session);
+  }
+
+  private async handleHostLeave(session: CollaborativeSession): Promise<void> {
+    // Find next editor to promote
+    const newHost = session.participants.find(p => p.role === 'editor');
+
+    if (newHost) {
+      newHost.role = 'host';
+      session.host = newHost;
+
+      await this.sync.broadcast(session.id, {
+        type: 'host:transferred',
+        newHostId: newHost.id
+      });
+    } else {
+      // No editors, close session
+      await this.close(session.id);
+    }
+  }
+
+  private assignColor(session: CollaborativeSession): string {
+    const colors = [
+      '#ef4444', '#f97316', '#f59e0b', '#84cc16',
+      '#22c55e', '#14b8a6', '#06b6d4', '#3b82f6',
+      '#6366f1', '#8b5cf6', '#a855f7', '#ec4899'
+    ];
+
+    const usedColors = new Set(session.participants.map(p => p.color));
+    return colors.find(c => !usedColors.has(c)) || colors[0];
+  }
+
+  private getDefaultPermissions(): SessionPermissions {
+    return {
+      canEdit: ['host', 'editor'],
+      canInvite: ['host'],
+      canKick: ['host'],
+      canLock: ['host', 'editor'],
+      maxParticipants: 10
+    };
+  }
+
+  on(event: SessionEvent, callback: Function): () => void {
+    this.eventEmitter.on(event, callback);
+    return () => this.eventEmitter.off(event, callback);
+  }
+}
+```
+
+---
+
+## 2. RealtimeSync
+
+### Propósito
+Sincronización en tiempo real usando WebSocket con reconexión automática.
+
+### Interfaz
+
+```typescript
+interface SyncMessage {
+  type: string;
+  sessionId: string;
+  senderId: string;
+  timestamp: string;
+  payload: unknown;
+  version?: number;
+}
+
+interface RealtimeSync {
+  // Connection
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  isConnected(): boolean;
+
+  // Session management
+  initSession(sessionId: string): Promise<void>;
+  destroySession(sessionId: string): Promise<void>;
+  subscribe(sessionId: string, participantId: string): Promise<void>;
+  unsubscribe(sessionId: string, participantId: string): Promise<void>;
+
+  // Messaging
+  broadcast(sessionId: string, message: Omit<SyncMessage, 'sessionId' | 'timestamp'>): Promise<void>;
+  send(sessionId: string, targetId: string, message: Omit<SyncMessage, 'sessionId' | 'timestamp'>): Promise<void>;
+
+  // State sync
+  pushState(sessionId: string, path: string, value: unknown): Promise<void>;
+  pullState(sessionId: string): Promise<Record<string, unknown>>;
+
+  // Events
+  onMessage(callback: (message: SyncMessage) => void): () => void;
+  onConnectionChange(callback: (connected: boolean) => void): () => void;
+}
+```
+
+### Implementación
+
+```typescript
+class RealtimeSyncImpl implements RealtimeSync {
+  private ws: WebSocket | null = null;
+  private subscriptions: Map<string, Set<string>> = new Map();
+  private messageQueue: SyncMessage[] = [];
+  private reconnectAttempts: number = 0;
+  private messageCallbacks: Set<(message: SyncMessage) => void> = new Set();
+  private connectionCallbacks: Set<(connected: boolean) => void> = new Set();
+
+  constructor(private config: RealtimeSyncConfig) {}
+
+  async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      try {
+        this.ws = new WebSocket(this.config.serverUrl);
+
+        this.ws.onopen = () => {
+          this.reconnectAttempts = 0;
+          this.flushMessageQueue();
+          this.notifyConnectionChange(true);
+          resolve();
+        };
+
+        this.ws.onmessage = (event) => {
+          const message = JSON.parse(event.data) as SyncMessage;
+          this.handleMessage(message);
+        };
+
+        this.ws.onclose = () => {
+          this.notifyConnectionChange(false);
+          this.scheduleReconnect();
+        };
+
+        this.ws.onerror = (error) => {
+          console.error('WebSocket error:', error);
+          reject(error);
+        };
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectAttempts >= this.config.maxReconnectAttempts) {
+      console.error('Max reconnection attempts reached');
+      return;
+    }
+
+    const delay = Math.min(
+      this.config.reconnectBaseDelay * Math.pow(2, this.reconnectAttempts),
+      this.config.reconnectMaxDelay
+    );
+
+    this.reconnectAttempts++;
+
+    setTimeout(() => {
+      this.connect().catch(console.error);
+    }, delay);
+  }
+
+  async broadcast(
+    sessionId: string,
+    message: Omit<SyncMessage, 'sessionId' | 'timestamp'>
+  ): Promise<void> {
+    const fullMessage: SyncMessage = {
+      ...message,
+      sessionId,
+      timestamp: new Date().toISOString()
+    };
+
+    if (this.isConnected()) {
+      this.ws!.send(JSON.stringify({
+        action: 'broadcast',
+        ...fullMessage
+      }));
+    } else {
+      this.messageQueue.push(fullMessage);
+    }
+  }
+
+  async send(
+    sessionId: string,
+    targetId: string,
+    message: Omit<SyncMessage, 'sessionId' | 'timestamp'>
+  ): Promise<void> {
+    const fullMessage: SyncMessage = {
+      ...message,
+      sessionId,
+      timestamp: new Date().toISOString()
+    };
+
+    if (this.isConnected()) {
+      this.ws!.send(JSON.stringify({
+        action: 'direct',
+        targetId,
+        ...fullMessage
+      }));
+    } else {
+      this.messageQueue.push(fullMessage);
+    }
+  }
+
+  async pushState(sessionId: string, path: string, value: unknown): Promise<void> {
+    await this.broadcast(sessionId, {
+      type: 'state:update',
+      senderId: 'system',
+      payload: { path, value }
+    });
+  }
+
+  async pullState(sessionId: string): Promise<Record<string, unknown>> {
+    return new Promise((resolve) => {
+      const callback = (message: SyncMessage) => {
+        if (message.type === 'state:full' && message.sessionId === sessionId) {
+          this.messageCallbacks.delete(callback);
+          resolve(message.payload as Record<string, unknown>);
+        }
+      };
+
+      this.messageCallbacks.add(callback);
+
+      this.ws?.send(JSON.stringify({
+        action: 'pull_state',
+        sessionId
+      }));
+
+      // Timeout fallback
+      setTimeout(() => {
+        this.messageCallbacks.delete(callback);
+        resolve({});
+      }, 5000);
+    });
+  }
+
+  private handleMessage(message: SyncMessage): void {
+    this.messageCallbacks.forEach(cb => cb(message));
+  }
+
+  private flushMessageQueue(): void {
+    while (this.messageQueue.length > 0 && this.isConnected()) {
+      const message = this.messageQueue.shift()!;
+      this.ws!.send(JSON.stringify({
+        action: 'broadcast',
+        ...message
+      }));
+    }
+  }
+
+  private notifyConnectionChange(connected: boolean): void {
+    this.connectionCallbacks.forEach(cb => cb(connected));
+  }
+
+  onMessage(callback: (message: SyncMessage) => void): () => void {
+    this.messageCallbacks.add(callback);
+    return () => this.messageCallbacks.delete(callback);
+  }
+
+  onConnectionChange(callback: (connected: boolean) => void): () => void {
+    this.connectionCallbacks.add(callback);
+    return () => this.connectionCallbacks.delete(callback);
+  }
+}
+```
+
+---
+
+## 3. ConflictResolver
+
+### Propósito
+Resuelve conflictos de edición concurrente usando OT (Operational Transformation) o CRDT.
+
+### Interfaz
+
+```typescript
+interface Operation {
+  id: string;
+  type: 'insert' | 'delete' | 'update' | 'move';
+  path: string;
+  value?: unknown;
+  previousValue?: unknown;
+  position?: number;
+  length?: number;
+  participantId: string;
+  timestamp: string;
+  version: number;
+}
+
+interface Conflict {
+  id: string;
+  operations: Operation[];
+  detectedAt: string;
+  status: 'pending' | 'auto-resolved' | 'manual-resolved' | 'rejected';
+  resolution?: ConflictResolution;
+}
+
+interface ConflictResolution {
+  strategy: 'accept-first' | 'accept-last' | 'merge' | 'custom';
+  resultingOperation: Operation;
+  resolvedBy?: string;
+  resolvedAt: string;
+}
+
+interface ConflictResolver {
+  // Detection
+  detectConflict(op1: Operation, op2: Operation): boolean;
+  getConflicts(sessionId: string): Conflict[];
+
+  // Resolution
+  resolve(conflictId: string, resolution: ConflictResolution): Promise<void>;
+  autoResolve(conflict: Conflict): Promise<ConflictResolution>;
+  rejectOperation(operationId: string): Promise<void>;
+
+  // Transformation (OT)
+  transform(op1: Operation, op2: Operation): [Operation, Operation];
+  transformAgainst(op: Operation, history: Operation[]): Operation;
+
+  // Events
+  onConflict(callback: (conflict: Conflict) => void): () => void;
+}
+```
+
+### Implementación
+
+```typescript
+class ConflictResolverImpl implements ConflictResolver {
+  private conflicts: Map<string, Conflict> = new Map();
+  private conflictCallbacks: Set<(conflict: Conflict) => void> = new Set();
+
+  constructor(private settings: ConflictResolverSettings) {}
+
+  detectConflict(op1: Operation, op2: Operation): boolean {
+    // Same path
+    if (op1.path !== op2.path) return false;
+
+    // Same version (concurrent)
+    if (op1.version !== op2.version) return false;
+
+    // Different participants
+    if (op1.participantId === op2.participantId) return false;
+
+    // Conflicting operation types
+    const conflictingPairs = [
+      ['update', 'update'],
+      ['update', 'delete'],
+      ['delete', 'delete'],
+      ['insert', 'insert'] // at same position
+    ];
+
+    const pair = [op1.type, op2.type].sort();
+    return conflictingPairs.some(cp => cp[0] === pair[0] && cp[1] === pair[1]);
+  }
+
+  async autoResolve(conflict: Conflict): Promise<ConflictResolution> {
+    const [op1, op2] = conflict.operations;
+
+    switch (this.settings.defaultStrategy) {
+      case 'last-write-wins':
+        // Use timestamp to determine winner
+        const winner = op1.timestamp > op2.timestamp ? op1 : op2;
+        return {
+          strategy: 'accept-last',
+          resultingOperation: winner,
+          resolvedAt: new Date().toISOString()
+        };
+
+      case 'first-write-wins':
+        const first = op1.timestamp < op2.timestamp ? op1 : op2;
+        return {
+          strategy: 'accept-first',
+          resultingOperation: first,
+          resolvedAt: new Date().toISOString()
+        };
+
+      case 'merge':
+        // Try to merge operations
+        const merged = this.mergeOperations(op1, op2);
+        return {
+          strategy: 'merge',
+          resultingOperation: merged,
+          resolvedAt: new Date().toISOString()
+        };
+
+      default:
+        // Use OT to transform
+        const [transformed1, transformed2] = this.transform(op1, op2);
+        return {
+          strategy: 'custom',
+          resultingOperation: transformed1,
+          resolvedAt: new Date().toISOString()
+        };
+    }
+  }
+
+  transform(op1: Operation, op2: Operation): [Operation, Operation] {
+    // Operational Transformation for concurrent operations
+
+    if (op1.type === 'insert' && op2.type === 'insert') {
+      // Both inserts - adjust positions
+      if (op1.position! <= op2.position!) {
+        return [
+          op1,
+          { ...op2, position: op2.position! + (op1.value as string).length }
+        ];
+      } else {
+        return [
+          { ...op1, position: op1.position! + (op2.value as string).length },
+          op2
+        ];
+      }
+    }
+
+    if (op1.type === 'delete' && op2.type === 'insert') {
+      if (op2.position! <= op1.position!) {
+        return [
+          { ...op1, position: op1.position! + (op2.value as string).length },
+          op2
+        ];
+      } else if (op2.position! >= op1.position! + op1.length!) {
+        return [op1, { ...op2, position: op2.position! - op1.length! }];
+      } else {
+        // Insert is within delete range - complex case
+        return [
+          { ...op1, length: op1.length! + (op2.value as string).length },
+          { ...op2, position: op1.position! }
+        ];
+      }
+    }
+
+    if (op1.type === 'update' && op2.type === 'update') {
+      // Both updating same path - last write wins by default
+      const winner = op1.timestamp > op2.timestamp ? op1 : op2;
+      const loser = winner === op1 ? op2 : op1;
+      return [winner, { ...loser, type: 'update', value: winner.value }];
+    }
+
+    // Default: return as-is
+    return [op1, op2];
+  }
+
+  transformAgainst(op: Operation, history: Operation[]): Operation {
+    let transformed = op;
+
+    for (const historicalOp of history) {
+      if (historicalOp.version > op.version) continue;
+      if (historicalOp.id === op.id) continue;
+
+      if (this.detectConflict(transformed, historicalOp)) {
+        const [newOp] = this.transform(transformed, historicalOp);
+        transformed = newOp;
+      }
+    }
+
+    return transformed;
+  }
+
+  private mergeOperations(op1: Operation, op2: Operation): Operation {
+    if (op1.type === 'update' && op2.type === 'update') {
+      // Merge object updates
+      if (typeof op1.value === 'object' && typeof op2.value === 'object') {
+        return {
+          ...op1,
+          value: { ...op1.value as object, ...op2.value as object },
+          timestamp: new Date().toISOString()
+        };
+      }
+
+      // Merge string updates (concatenate)
+      if (typeof op1.value === 'string' && typeof op2.value === 'string') {
+        return {
+          ...op1,
+          value: `${op1.value}\n---\n${op2.value}`,
+          timestamp: new Date().toISOString()
+        };
+      }
+    }
+
+    // Default: use last write
+    return op1.timestamp > op2.timestamp ? op1 : op2;
+  }
+
+  onConflict(callback: (conflict: Conflict) => void): () => void {
+    this.conflictCallbacks.add(callback);
+    return () => this.conflictCallbacks.delete(callback);
+  }
+}
+```
+
+---
+
+## 4. PresenceTracker
+
+### Propósito
+Rastrea la presencia de participantes incluyendo cursores, actividad y estado.
+
+### Interfaz
+
+```typescript
+interface PresenceState {
+  participantId: string;
+  sessionId: string;
+  status: 'online' | 'away' | 'busy' | 'offline';
+  cursor?: CursorPosition;
+  selection?: SelectionRange;
+  activity?: ActivityInfo;
+  lastSeen: string;
+}
+
+interface CursorPosition {
+  path: string;       // e.g., "nodes[0].config"
+  line?: number;
+  column?: number;
+  label?: string;     // What they're editing
+}
+
+interface SelectionRange {
+  start: CursorPosition;
+  end: CursorPosition;
+}
+
+interface ActivityInfo {
+  type: 'editing' | 'viewing' | 'typing' | 'idle';
+  target?: string;
+  startedAt: string;
+}
+
+interface PresenceTracker {
+  // Tracking
+  track(sessionId: string, participantId: string): void;
+  untrack(sessionId: string, participantId: string): void;
+
+  // Updates
+  updateStatus(sessionId: string, participantId: string, status: PresenceState['status']): void;
+  updateCursor(sessionId: string, participantId: string, cursor: CursorPosition): void;
+  updateSelection(sessionId: string, participantId: string, selection: SelectionRange): void;
+  updateActivity(sessionId: string, participantId: string, activity: ActivityInfo): void;
+
+  // Queries
+  getPresence(sessionId: string, participantId: string): PresenceState | null;
+  getAllPresence(sessionId: string): PresenceState[];
+  getOnlineParticipants(sessionId: string): string[];
+
+  // Events
+  onPresenceChange(sessionId: string, callback: (presence: PresenceState) => void): () => void;
+}
+```
+
+### Implementación
+
+```typescript
+class PresenceTrackerImpl implements PresenceTracker {
+  private presence: Map<string, Map<string, PresenceState>> = new Map();
+  private idleTimers: Map<string, NodeJS.Timeout> = new Map();
+  private callbacks: Map<string, Set<(presence: PresenceState) => void>> = new Map();
+
+  constructor(
+    private sync: RealtimeSync,
+    private config: PresenceConfig
+  ) {
+    this.setupSyncListener();
+  }
+
+  private setupSyncListener(): void {
+    this.sync.onMessage((message) => {
+      if (message.type.startsWith('presence:')) {
+        this.handlePresenceMessage(message);
+      }
+    });
+  }
+
+  track(sessionId: string, participantId: string): void {
+    if (!this.presence.has(sessionId)) {
+      this.presence.set(sessionId, new Map());
+    }
+
+    const state: PresenceState = {
+      participantId,
+      sessionId,
+      status: 'online',
+      lastSeen: new Date().toISOString()
+    };
+
+    this.presence.get(sessionId)!.set(participantId, state);
+    this.broadcastPresence(sessionId, state);
+    this.setupIdleDetection(sessionId, participantId);
+  }
+
+  untrack(sessionId: string, participantId: string): void {
+    const sessionPresence = this.presence.get(sessionId);
+    if (!sessionPresence) return;
+
+    const state = sessionPresence.get(participantId);
+    if (state) {
+      state.status = 'offline';
+      this.broadcastPresence(sessionId, state);
+    }
+
+    sessionPresence.delete(participantId);
+    this.clearIdleTimer(sessionId, participantId);
+  }
+
+  updateCursor(
+    sessionId: string,
+    participantId: string,
+    cursor: CursorPosition
+  ): void {
+    const state = this.getPresence(sessionId, participantId);
+    if (!state) return;
+
+    state.cursor = cursor;
+    state.lastSeen = new Date().toISOString();
+
+    this.broadcastPresence(sessionId, state);
+    this.resetIdleTimer(sessionId, participantId);
+  }
+
+  updateActivity(
+    sessionId: string,
+    participantId: string,
+    activity: ActivityInfo
+  ): void {
+    const state = this.getPresence(sessionId, participantId);
+    if (!state) return;
+
+    state.activity = activity;
+    state.lastSeen = new Date().toISOString();
+
+    // Auto-update status based on activity
+    if (activity.type === 'typing' || activity.type === 'editing') {
+      state.status = 'busy';
+    } else if (activity.type === 'idle') {
+      state.status = 'away';
+    } else {
+      state.status = 'online';
+    }
+
+    this.broadcastPresence(sessionId, state);
+  }
+
+  getPresence(sessionId: string, participantId: string): PresenceState | null {
+    return this.presence.get(sessionId)?.get(participantId) || null;
+  }
+
+  getAllPresence(sessionId: string): PresenceState[] {
+    const sessionPresence = this.presence.get(sessionId);
+    return sessionPresence ? Array.from(sessionPresence.values()) : [];
+  }
+
+  getOnlineParticipants(sessionId: string): string[] {
+    return this.getAllPresence(sessionId)
+      .filter(p => p.status !== 'offline')
+      .map(p => p.participantId);
+  }
+
+  private broadcastPresence(sessionId: string, state: PresenceState): void {
+    this.sync.broadcast(sessionId, {
+      type: 'presence:update',
+      senderId: state.participantId,
+      payload: state
+    });
+
+    this.notifyCallbacks(sessionId, state);
+  }
+
+  private setupIdleDetection(sessionId: string, participantId: string): void {
+    const key = `${sessionId}:${participantId}`;
+
+    const timer = setTimeout(() => {
+      this.updateActivity(sessionId, participantId, {
+        type: 'idle',
+        startedAt: new Date().toISOString()
+      });
+    }, this.config.idleTimeout);
+
+    this.idleTimers.set(key, timer);
+  }
+
+  private resetIdleTimer(sessionId: string, participantId: string): void {
+    this.clearIdleTimer(sessionId, participantId);
+    this.setupIdleDetection(sessionId, participantId);
+  }
+
+  private clearIdleTimer(sessionId: string, participantId: string): void {
+    const key = `${sessionId}:${participantId}`;
+    const timer = this.idleTimers.get(key);
+    if (timer) {
+      clearTimeout(timer);
+      this.idleTimers.delete(key);
+    }
+  }
+
+  onPresenceChange(
+    sessionId: string,
+    callback: (presence: PresenceState) => void
+  ): () => void {
+    if (!this.callbacks.has(sessionId)) {
+      this.callbacks.set(sessionId, new Set());
+    }
+    this.callbacks.get(sessionId)!.add(callback);
+
+    return () => {
+      this.callbacks.get(sessionId)?.delete(callback);
+    };
+  }
+
+  private notifyCallbacks(sessionId: string, state: PresenceState): void {
+    this.callbacks.get(sessionId)?.forEach(cb => cb(state));
+  }
+
+  private handlePresenceMessage(message: SyncMessage): void {
+    if (message.type === 'presence:update') {
+      const state = message.payload as PresenceState;
+      const sessionPresence = this.presence.get(message.sessionId);
+
+      if (sessionPresence) {
+        sessionPresence.set(state.participantId, state);
+        this.notifyCallbacks(message.sessionId, state);
+      }
+    }
+  }
+}
+```
+
+---
+
+## 5. Visualización de Presencia
+
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                    Collaborative Session: Flow Design                         ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║  Session ID: session_abc123  │  Participants: 4  │  Active: 3                ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                              Participants                                     ║
+├──────────────────────────────────────────────────────────────────────────────┤
+│  ● Alice (Host)     🟢 online   Editing: nodes[2].config                     │
+│  ● Bob              🟢 online   Viewing: flow overview                       │
+│  ● Agent-Explore    🟡 busy     Executing: exploration task                  │
+│  ○ Carol            ⚪ away     Idle for 5 minutes                           │
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                              Activity Feed                                    ║
+├──────────────────────────────────────────────────────────────────────────────┤
+│  [10:32:15] Alice moved node "Analyze" to position (200, 150)                │
+│  [10:32:08] Bob added comment on "Review" node                               │
+│  [10:31:45] Agent-Explore updated node "Explore" configuration               │
+│  [10:31:30] Alice connected "Analyze" → "Implement"                          │
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                              Cursors (Canvas)                                 ║
+├──────────────────────────────────────────────────────────────────────────────┤
+│                                                                               │
+│    ┌─────────────┐     🔴Alice                                               │
+│    │ Analyze     │     ↓                                                     │
+│    └─────────────┘     ┌─────────────┐                                       │
+│                        │ Implement   │←🔵Bob                                 │
+│                        └─────────────┘                                       │
+│                                                                               │
+╚══════════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## 6. Comandos CLI
+
+```bash
+# Crear sesión colaborativa
+/elsabro:collab create "Flow Design Session" --type flow
+
+# Unirse a sesión
+/elsabro:collab join <session-id>
+
+# Invitar participante
+/elsabro:collab invite <email> --role editor
+
+# Ver participantes
+/elsabro:collab participants
+
+# Ver actividad
+/elsabro:collab activity
+
+# Salir de sesión
+/elsabro:collab leave
+
+# Cerrar sesión (solo host)
+/elsabro:collab close
+```
+
+---
+
+## Referencias
+
+- **REF-019**: Event-Driven Architecture
+- **REF-028**: Flow Visualization
+- **REF-030**: Esta referencia (Collaborative Sessions)