@vibexnpm/talkx 2.3.1 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vibexnpm/talkx",
-    "version": "2.3.1",
+    "version": "2.5.0",
     "type": "module",
     "description": "TalkFlow SDK - Chat & WebRTC unified client",
     "main": "dist/talkflow-sdk.umd.js",

package/src/chat/ChatClient.js

@@ -55,6 +55,21 @@ class ChatClient extends EventEmitter {
         this._assistantTypingUserId = '__assistant__';
         this._assistantTypingUserName = 'AI';
 
+        // AI 진행 표시(생각중/검색중/작성중) — assistant-stream 채널의 PHASE/DONE 수신 상태.
+        // roomId → { streamId, personaId, phase, timer }. typing 과 별개의 가산 레이어(서버가 둘 다 발행).
+        // 자동 해제 3경로: (1) DONE 수신 (2) 어시 메시지 도착 (3) TTL(expiresAt) 만료 — typing 타이머와 동형.
+        // 현재는 PM_BACKSTAGE(방당 단일 PM) 만 phase 를 발행하므로 방 단위 1개 진행으로 추적한다.
+        this._assistantProgress = new Map();
+        // phase → 기본 표시 라벨(설계 §2 — 서버는 의미만, 라벨 텍스트는 SDK 매핑). 소비자는 payload.phase 로 커스텀 가능.
+        this._assistantPhaseLabels = {
+            THINKING: '생각 중…',
+            SEARCHING: '검색 중…',
+            PLANNING: '기획 중…',
+            WRITING: '작성 중…'
+        };
+        // PHASE 의 expiresAt 누락/이상 시 fallback TTL (ms) — 서버 ttl(최소 30s) 보다 약간 길게.
+        this._assistantProgressFallbackTtlMs = 35000;
+
         // 메시지 dedup 보호 — 같은 messageId 의 중복 수신 차단.
         // 서버측 멱등 race 복구 / 네트워크 재전송 / WebSocket 재연결 직후 등 다양한 중복 시나리오 커버.
         //
@@ -1580,6 +1595,12 @@ class ChatClient extends EventEmitter {
             this._handleTypingEvent(roomId, event);
         });
 
+        // AI 진행 표시(생각중/검색중/작성중) 구독 — typing 과 별개 채널(가산 UX). 구버전 SDK 는 미구독 → 기존 typing 만.
+        const assistantStreamDestination = WebSocketPaths.getChatAssistantStreamDestination(roomId);
+        await this.connectionManager.subscribe(assistantStreamDestination, (event) => {
+            this._handleAssistantStreamEvent(roomId, event);
+        });
+
         // 멤버 변경 이벤트 — roomList 이벤트를 방 수준으로 변환하여 자동 emit
         // 서버가 members 배열(입장/퇴장 사용자들) + participantCount(정확한 인원수) 포함
         const memberJoinedHandler = (event) => {
@@ -1609,6 +1630,7 @@ class ChatClient extends EventEmitter {
             chatDestination,
             readDestination,
             typingDestination,
+            assistantStreamDestination,
             memberJoinedHandler,
             memberLeftHandler,
             subscribedAt: new Date()
@@ -1634,6 +1656,9 @@ class ChatClient extends EventEmitter {
         if (subscription.typingDestination) {
             this.connectionManager.unsubscribe(subscription.typingDestination);
         }
+        if (subscription.assistantStreamDestination) {
+            this.connectionManager.unsubscribe(subscription.assistantStreamDestination);
+        }
 
         // 멤버 변경 리스너 해제
         if (subscription.memberJoinedHandler) {
@@ -1646,6 +1671,8 @@ class ChatClient extends EventEmitter {
         // 타이핑 타이머 정리 (outgoing + incoming assistant 둘 다)
         this._clearTypingTimer(roomId);
         this._clearAssistantTypingTimer(roomId);
+        // AI 진행 표시 상태/타이머 정리 (emit 없이 — 구독 해제 중)
+        this._clearAssistantProgress(roomId, false);
 
         // 현재 보고 있는 방이면 activeRoom 해제
         if (this._activeRoomId === roomId) {
@@ -1855,6 +1882,9 @@ class ChatClient extends EventEmitter {
                         typing: false,
                         senderType: 'ASSISTANT'
                     });
+                    // AI 진행 표시도 해제 — 최종 메시지 도착 = 진행 종료(설계 §3.1·§4.1, 메시지=진실).
+                    // DONE 이 유실/지연돼도 메시지로 수렴. active:false emit.
+                    this._clearAssistantProgress(roomId, true, 'message');
                 }
 
                 // 상대방 메시지일 때만 newMessage + 자동 읽음 처리
@@ -2161,6 +2191,141 @@ class ChatClient extends EventEmitter {
         }
     }
 
+    /**
+     * AI 진행 표시(assistant-stream) 이벤트 수신 처리 — PHASE(단계)/DELTA(토큰 청크)/DONE(종료) 분기.
+     *
+     * <p>typing 과 별개의 가산 레이어 — UI 는 {@code active:true} 면 {@code text}(토큰 스트림 누적) 우선,
+     * 없으면 {@code label}(단계) 표시, {@code active:false} 면 해제. PHASE→DELTA 흐름으로 "작성 중" 라벨이
+     * 점진 렌더 텍스트로 자연 전환된다. 서버가 typing 도 이중발행하므로 구버전 SDK 는 본 채널 미구독 → 기존
+     * typing 만으로 정상 동작(graceful).</p>
+     * @private
+     */
+    _handleAssistantStreamEvent(roomId, event) {
+        if (!event || !event.type) return;
+
+        if (event.type === 'PHASE') {
+            const phase = event.phase || null;
+            const label = (phase && this._assistantPhaseLabels[phase]) || null;
+            // 같은 stream 의 PHASE 재발행(B-3 synthesis heartbeat 등)이면 누적 텍스트 보존, 새 stream 이면 리셋.
+            const prev = this._assistantProgress.get(roomId);
+            const text = (prev && prev.streamId === event.streamId) ? (prev.text || '') : '';
+            // 진행 상태 갱신 + TTL 재무장(heartbeat 재수신마다 연장). 같은 방의 이전 타이머는 reset.
+            this._startAssistantProgressTimer(roomId, event, { phase, text });
+            this.emit('assistantProgress', {
+                roomId,
+                streamId: event.streamId || null,
+                personaId: event.personaId || null,
+                phase,
+                label,
+                active: true,
+                text: text || null
+            });
+            return;
+        }
+
+        if (event.type === 'DELTA') {
+            // 토큰 청크(B) — 누적 텍스트에 이어붙여 점진 렌더용으로 emit. WRITING 단계에서 흐른다.
+            const prev = this._assistantProgress.get(roomId);
+            // stale DELTA 무시 — 이전 stream 의 늦은 토큰이 새 stream 표시를 오염시키지 않게(DONE 가드와 동형).
+            if (prev?.streamId && event.streamId && prev.streamId !== event.streamId) {
+                this.logger.debug(`Stale assistant DELTA ignored: room=${roomId}, delta=${event.streamId}, active=${prev.streamId}`);
+                return;
+            }
+            const phase = (prev && prev.phase) || 'WRITING';
+            const text = (prev ? (prev.text || '') : '') + (event.delta || '');
+            this._startAssistantProgressTimer(roomId, event, { phase, text });
+            this.emit('assistantProgress', {
+                roomId,
+                streamId: event.streamId || null,
+                personaId: event.personaId || null,
+                phase,
+                label: this._assistantPhaseLabels[phase] || null,
+                active: true,
+                text,                                   // 지금까지 누적된 전체 텍스트(버블 렌더용)
+                delta: event.delta || null,             // 이번 청크(append 렌더 선호 시)
+                seq: typeof event.seq === 'number' ? event.seq : null
+            });
+            return;
+        }
+
+        if (event.type === 'DONE') {
+            // 종료(성공·실패 공통) — 상태/타이머 해제 + active:false emit(status/messageId 동봉, 권위 신호).
+            const state = this._assistantProgress.get(roomId);
+            // 늦게 도착한 이전 stream 의 DONE 무시 — 다음 stream 의 PHASE 이후 도착 시 새 진행 표시를 끄는 race 차단.
+            // 메시지/assistant-stream 채널은 ordering 이 묶여 있지 않다. streamId 가 둘 다 있고 다를 때만 stale 판정
+            // (UI 계약이 "active 만 보면 됨"이므로 SDK 가 stale false 를 막는다).
+            if (state?.streamId && event.streamId && state.streamId !== event.streamId) {
+                this.logger.debug(`Stale assistant DONE ignored: room=${roomId}, done=${event.streamId}, active=${state.streamId}`);
+                return;
+            }
+            // 메시지 도착으로 먼저 해제됐어도 DONE 은 한 번 더 발행될 수 있으나 active:false 는 idempotent(설계 §4.1).
+            if (state && state.timer) clearTimeout(state.timer);
+            this._assistantProgress.delete(roomId);
+            this.emit('assistantProgress', {
+                roomId,
+                streamId: event.streamId || null,
+                personaId: event.personaId || null,
+                phase: null,
+                label: null,
+                active: false,
+                status: event.status || null,
+                messageId: event.messageId || null
+            });
+        }
+        // 그 외 미지 type 은 무시(forward-compat).
+    }
+
+    /**
+     * AI 진행 상태 갱신 + TTL 타이머 재무장 — {@code expiresAt}(epochMillis) 기반, 누락/이상 시 fallback.
+     * {@code fields}={phase, text}(PHASE/DELTA 가 해소해 전달 — DELTA 는 직전 phase 유지 + 누적 text).
+     * 만료 = DONE·메시지 유실로 진행이 끊긴 것 → UI 가 영구 표시에 갇히지 않게 {@code active:false} 자동 emit.
+     * @private
+     */
+    _startAssistantProgressTimer(roomId, event, fields) {
+        const prev = this._assistantProgress.get(roomId);
+        if (prev && prev.timer) clearTimeout(prev.timer);
+
+        let ttl = this._assistantProgressFallbackTtlMs;
+        if (typeof event.expiresAt === 'number') {
+            // 비정상값 방어 — [5s, 120s] 로 clamp(과거 timestamp / 과대 TTL 모두 차단).
+            ttl = Math.min(120000, Math.max(5000, event.expiresAt - Date.now()));
+        }
+        const timer = setTimeout(() => {
+            this._clearAssistantProgress(roomId, true, 'timeout');
+            this.logger.debug(`Assistant progress auto-cleared (timeout): room=${roomId}`);
+        }, ttl);
+        this._assistantProgress.set(roomId, {
+            streamId: event.streamId || null,
+            personaId: event.personaId || null,
+            phase: fields.phase,
+            text: fields.text || '',
+            timer
+        });
+    }
+
+    /**
+     * AI 진행 표시 상태/타이머 해제. {@code emit=true} 면 {@code active:false} 를 발행(메시지 도착/타임아웃 해제용).
+     * 구독 해제 시엔 {@code emit=false} 로 조용히 정리.
+     * @private
+     */
+    _clearAssistantProgress(roomId, emit, reason) {
+        const state = this._assistantProgress.get(roomId);
+        if (!state) return;
+        if (state.timer) clearTimeout(state.timer);
+        this._assistantProgress.delete(roomId);
+        if (emit) {
+            this.emit('assistantProgress', {
+                roomId,
+                streamId: state.streamId || null,
+                personaId: state.personaId || null,
+                phase: null,
+                label: null,
+                active: false,
+                reason: reason || null
+            });
+        }
+    }
+
     // ==================== 유틸리티 ====================
 
     /**
@@ -2208,6 +2373,10 @@ class ChatClient extends EventEmitter {
         this._assistantTypingTimers.forEach((timer) => clearTimeout(timer));
         this._assistantTypingTimers.clear();
 
+        // AI 진행 표시 상태/타이머도 전체 cleanup (구독 외 경로로 남은 roomId 방어).
+        this._assistantProgress.forEach((state) => state.timer && clearTimeout(state.timer));
+        this._assistantProgress.clear();
+
         // dedup bucket 전체 clear — unsubscribeRoom 이 방별로 정리하지만 구독 외 경로로 누적된 bucket
         // (예: 구독 안 한 방의 push/listener) 이 있을 수 있어 안전하게 명시 정리.
         this._seenChatMessageIdsByRoom.clear();

package/src/constants.js

@@ -319,6 +319,8 @@ export const WebSocketPaths = {
     getChatDestination: (roomId) => `/topic/chat/${roomId}`,
     getChatReadDestination: (roomId) => `/topic/chat/${roomId}/read`,
     getChatTypingDestination: (roomId) => `/topic/chat/${roomId}/typing`,
+    // AI 진행 표시(생각중/검색중/작성중) + 토큰 스트리밍 — typing 과 별개 채널(가산 UX 레이어).
+    getChatAssistantStreamDestination: (roomId) => `/topic/chat/${roomId}/assistant-stream`,
 
     // Room list (카톡 스타일 리스트 실시간 업데이트)
     // 서버가 convertAndSendToUser(userId, "/queue/rooms", event) 로 전송

package/src/talkflow/eventForwarding.js

@@ -15,6 +15,7 @@ const CHAT_EVENT_MAP = [
     ['messageTranslated', 'messageTranslated'],
     ['messageRead', 'messageRead'],
     ['typing', 'typing'],
+    ['assistantProgress', 'assistantProgress'],
     ['memberJoined', 'memberJoined'],
     ['memberLeft', 'memberLeft'],
     ['roomSubscribed', 'roomSubscribed'],

package/types/index.d.ts

@@ -378,6 +378,7 @@ export const WebSocketPaths: {
     getChatDestination(roomId: string): string;
     getChatReadDestination(roomId: string): string;
     getChatTypingDestination(roomId: string): string;
+    getChatAssistantStreamDestination(roomId: string): string;
     readonly ROOM_LIST_USER_DESTINATION: string;
     getWebRTCDestination(roomId: string): string;
     getWebRTCUserDestination(): string;
@@ -735,6 +736,42 @@ export interface TypingEvent {
     senderType: 'USER' | 'ASSISTANT';
 }
 
+/**
+ * AI 진행 표시 이벤트 — `/topic/chat/{roomId}/assistant-stream` 의 PHASE/DONE.
+ *
+ * typing 과 별개의 가산 UX 레이어(설계 ASSISTANT_PROGRESS_STREAMING_DESIGN.md). 서버가 typing 도 이중발행하므로
+ * 구버전 SDK 는 본 이벤트를 못 받아도 기존 typing 으로 정상 동작한다. UI 는 `active:true` 면 `label`(또는 `phase`)
+ * 로 단계를 표시하고, `active:false`(DONE·어시 메시지 도착·TTL 만료) 면 해제한다.
+ *
+ * 현재는 PM_BACKSTAGE(방당 단일 PM) 만 phase 를 발행 — 멘션/버튼/14인 경로는 본 이벤트 없이 typing 만.
+ */
+export interface AssistantProgressEvent {
+    /** 채팅방 ID. */
+    roomId: string;
+    /** 어시 응답 1회분 식별(멀티 응답/중복 dedup). 일부 종료 emit 에선 null. */
+    streamId: string | null;
+    /** 진행 주체 페르소나 ID. */
+    personaId: string | null;
+    /** 진행 단계 — `active:true` 일 때. 종료 시 null. */
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'WRITING' | null;
+    /** phase 의 기본 표시 라벨(예: "생각 중…"). SDK 매핑 — 커스텀하려면 `phase` 사용. 종료 시 null. */
+    label: string | null;
+    /** true=진행중(PHASE/DELTA) / false=종료(DONE·메시지 도착·TTL). */
+    active: boolean;
+    /** 토큰 스트림 누적 텍스트(B) — DELTA 수신 시 지금까지 모인 전체. 버블에 그대로 렌더. PHASE-only/종료 시 null. */
+    text?: string | null;
+    /** 이번 토큰 청크(B) — append 렌더를 선호할 때. DELTA 수신 시만. */
+    delta?: string | null;
+    /** 토큰 청크 순서/누락 감지(B) — DELTA 수신 시만. */
+    seq?: number | null;
+    /** 종료(DONE) 결과 — DONE 수신 시만. */
+    status?: 'SUCCEEDED' | 'FAILED' | 'CANCELLED' | 'TIMEOUT' | null;
+    /** 종료(DONE, SUCCEEDED) 시 영속된 최종 메시지 ID. */
+    messageId?: string | null;
+    /** 종료 사유 — 'message'(어시 메시지 도착) / 'timeout'(TTL). DONE 수신 해제엔 없음. */
+    reason?: 'message' | 'timeout' | null;
+}
+
 // ============================================================================
 // Options — constructor & method
 // ============================================================================
@@ -1056,7 +1093,7 @@ export interface RetentionCleanupPayload {
  * TalkFlowClient 이벤트 맵 — 런타임 {@code TalkFlowClient.js} 의 {@code this.emit(...)} 호출 기반.
  *
  * <p><b>Connection 관련</b>: stateChange, connected, disconnected, reconnecting, connectionError, tokenSet, loggedOut</p>
- * <p><b>Chat 관련 (ChatClient 이벤트를 이 이름으로 re-emit)</b>: chatMessage, newChatMessage, messageUpdated, messageDeleted, reactionChanged, linkPreviewAttached, messageRead, typing, memberJoined, memberLeft, roomSubscribed, roomUnsubscribed, roomListSubscribed, roomListUnsubscribed, roomListUpdate, roomListMessage, roomListCreated, roomListJoined, roomListLeft, roomListSelfLeft, roomListRoomUpdated, retentionCleanup</p>
+ * <p><b>Chat 관련 (ChatClient 이벤트를 이 이름으로 re-emit)</b>: chatMessage, newChatMessage, messageUpdated, messageDeleted, reactionChanged, linkPreviewAttached, messageRead, typing, assistantProgress, memberJoined, memberLeft, roomSubscribed, roomUnsubscribed, roomListSubscribed, roomListUnsubscribed, roomListUpdate, roomListMessage, roomListCreated, roomListJoined, roomListLeft, roomListSelfLeft, roomListRoomUpdated, retentionCleanup</p>
  * <p><b>Push 관련</b>: pushEnabled, pushFailed, pushNotification</p>
  * <p><b>WebRTC 관련</b>: localStreamStarted, localStreamStopped, remoteTrack, screenShareStarted, screenShareEnded, deviceChange, mediaStateChanged, callStarted, callEnded, callRequested, callAccepted, callRejected, callCancelled, callInvitation, callBusy, incomingCall, incomingCallWhileBusy, userJoined, userLeft, participantLeft, participantMediaState, peerConnected, peerDisconnected, peerClosed, webrtcError</p>
  */
@@ -1085,6 +1122,7 @@ export interface TalkFlowClientEvents {
     messageTranslated: ChatMessageReceivedPayload;
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
+    assistantProgress: AssistantProgressEvent;
     memberJoined: MemberChangePayload;
     memberLeft: MemberChangePayload;
     roomSubscribed: { roomId: string };
@@ -1198,6 +1236,7 @@ export interface ChatClientEvents {
     retentionCleanup: RetentionCleanupPayload;
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
+    assistantProgress: AssistantProgressEvent;
 }
 
 /**