@vibexnpm/talkx 5.2.0 → 5.4.0

package/package.json

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

package/src/chat/ChatClient.js

@@ -320,6 +320,21 @@ class ChatClient extends EventEmitter {
         // 1) WebSocket 구독을 먼저 — 이후 서버 read 이벤트 유실 방지
         if (!wasAlreadySubscribed) {
             await this.subscribeRoom(roomId);
+        } else if (this.assistantStreamReplay) {
+            // ⭐ <b>이미 구독 중인 방으로 재입장</b> — 구독을 유지한 채 방 화면만 나갔다 들어오는 흐름이다
+            // (목록 화면에서 unread 를 받으려면 구독을 끊지 않는 것이 정상 구현이다). 이때 subscribeRoom 이
+            // 통째로 건너뛰어져 <b>스냅샷 트리거가 하나도 돌지 않는다</b> — 재개 경로는 여기와 재연결
+            // (`resumeAssistantStreams`) 둘뿐이기 때문이다.
+            //
+            // 진행 표시는 transient 이벤트라 화면이 언마운트되면 프론트에서 사라지는데, SDK 슬롯에만 남은
+            // 그 상태를 다시 그려줄 신호가 없다 → 다음 PHASE 가 올 때까지(워커 heartbeat 간격 15초) 배지가
+            // 안 뜬다. 스냅샷을 다시 받아 그 공백을 없앤다.
+            //
+            // await 하지 않는다 — 구독은 살아 있으므로 그 사이 도착분은 보류함에 쌓였다가 병합 후 순서대로
+            // 풀린다(§6.1). 실패해도 보류분은 반드시 풀리므로 라이브만으로 계속 동작한다.
+            const generation = this._armAssistantSnapshot(roomId);
+            this._loadAssistantSnapshot(roomId, generation)
+                .catch((error) => this.logger.warn(`Assistant snapshot on re-enter failed: room=${roomId}`, error));
         }
         // 2) 자동 읽음 처리 활성 방 지정
         this.setActiveRoom(roomId);
@@ -633,23 +648,24 @@ class ChatClient extends EventEmitter {
      * @param {Object} [options]
      * @param {string} [options.format] - 요약 포맷 ({@link SummarizeFormat}). 미지정/알 수 없는 값이면 서버가 {@code SHORT} 적용.
      * @param {string} [options.lang] - 출력 언어(BCP-47 예 {@code 'ko'}/{@code 'en'}, 또는 {@code 'OFF'}=원문). 미지정 시 요청자 언어로 해소.
-     * @returns {Promise<{status: string, format?: string, language?: string}>} {@code status}: {@code 'STARTED'}(워커 시작 —
-     *   {@code summaryUpdate} 대기) | {@code 'ALREADY_RUNNING'}(방에서 <b>다른</b> 요약이 진행 중일 수 있음 — 응답의
-     *   {@code format}/{@code language} 로 내 키인지 확인) | {@code 'NO_CHANGE'}(새 대화 없음 — 알림 발생 안 함).
-     *   {@code format}/{@code language}=이번 요청이 해소한 키(방 단위 경합 식별용).
-     *
-     * @fires summaryUpdate - { roomId, status: 'READY'|'NO_CHANGE'|'FAILED'|'INVALIDATED', format, languages, updatedAt }.
+     * @returns {Promise<{status: string, format?: string, language?: string}>} {@code status}: {@code 'QUEUED'} —
+     *   방 단위 durable work item 에 저장·병합됐다. local worker 포화여도 요청은 버려지지 않으며
+     *   최종 {@code READY|NO_CHANGE|NO_MESSAGES|FAILED} {@code summaryUpdate} 를 기다린다.
+     *   {@code format}/{@code language}=이번 호출이 work item 에 병합한 키.
+     *   ⚠️ 닫힌 목록이 아니다 — 분기에는 default 를 두고, 모르는 값에 스피너를 띄우지 마라.
+     * @throws {Error} HTTP 503 {@code SUMMARY_REFRESH_UNAVAILABLE} — durable 저장 자체가 실패했다.
+     *   간격을 두고 재시도하고 사용자에게는 일시 오류로 알린다.
+     *   {@code err.status}=503, {@code err.response.code}={@code 'SUMMARY_REFRESH_UNAVAILABLE'}.
+     *
+     * @fires summaryUpdate - { roomId, status: 'READY'|'NO_CHANGE'|'NO_MESSAGES'|'FAILED'|'INVALIDATED'|string, format, languages, updatedAt }.
      *   fan-out 으로 여러 언어를 한 번에 생성하므로 {@code languages} 는 배열(§S1). {@code INVALIDATED} 는 refreshSummary 가
      *   아니라 방 원문 삭제/편집으로 발생(요약이 통째로 폐기됨).
      *
      * @example
      * const { status } = await chat.refreshSummary(roomId, { format: SummarizeFormat.MINUTES, lang: 'ko' });
-     * if (status === 'STARTED') showSpinner();          // fan-out 진행 시작 — summaryUpdate 대기
-     * else if (status === 'ALREADY_RUNNING') {
-     *   // 방에서 다른 요약이 도는 중일 수 있다. 완료 이벤트 summaryUpdate 의 languages 에 내 언어가 없으면
-     *   // 그때 다시 refreshSummary 로 내 언어를 요청한다(재요청 금지가 아니라 "내 언어가 없으면 재요청").
-     *   showSpinner();
-     * } else if (status === 'NO_CHANGE') toast('변경 사항이 없습니다');
+     * if (status === 'QUEUED') showQueuedProgress();    // durable 접수 — summaryUpdate 대기
+     * else showUnknownSummaryState(status);             // 미래 서버 값은 추측하지 않는다
+     * // 503(SUMMARY_REFRESH_UNAVAILABLE)은 durable 접수 실패 — try/catch로 받고 간격을 두고 재시도.
      */
     async refreshSummary(roomId, options = {}) {
         const { format, lang } = options;
@@ -663,9 +679,10 @@ class ChatClient extends EventEmitter {
     /**
      * Rolling 누적 요약 조회 — 통합본(rollup) + 구간 부분요약(segments) 페이지. 저장된 요약의 단일 진실 소스.
      *
-     * <p>{@code summaryUpdate}({@code status:'READY'}) 수신 후, 그리고 화면 진입/재접속 시 호출한다 — 알림은
-     * transient(저장 안 됨)라 유실될 수 있으므로 GET 으로 동기화한다. 아직 한 번도 요약된 적 없으면 {@code rollup}
-     * 이 {@code null} 이다. segment 는 {@code afterSeq}/{@code size} 로 페이지네이션한다({@code hasNext}/{@code nextSeq}).</p>
+     * <p>terminal {@code summaryUpdate} 수신 후, 화면 진입/재접속 시, 그리고 {@code QUEUED} 뒤 앱이 정한 완료
+     * timeout에 <b>한 번</b> 호출한다 — 알림은 transient(저장 안 됨)라 유실될 수 있으므로 GET 으로 동기화한다.
+     * 주기적 polling은 하지 않는다. 아직 한 번도 요약된 적 없으면 {@code rollup} 이 {@code null} 이다.
+     * segment 는 {@code afterSeq}/{@code size} 로 페이지네이션한다({@code hasNext}/{@code nextSeq}).</p>
      *
      * <p>같은 방을 여러 포맷×언어로 보관하므로 {@code options.format}/{@code options.lang} 으로 골라 조회한다.
      * {@code lang} 미지정 시 서버가 요청자 언어로 해소하고, 응답 {@code language} 로 <b>어느 언어 기준</b>인지
@@ -679,7 +696,7 @@ class ChatClient extends EventEmitter {
      * @param {string} [options.lang] - 조회할 언어(BCP-47 예 {@code 'ko'}, 또는 {@code 'OFF'}=원문). 미지정 시 요청자 언어로 해소(응답 {@code language}).
      * @param {number} [options.afterSeq] - segment 페이지 커서(exclusive). 미지정 시 처음부터.
      * @param {number} [options.size=50] - segment 페이지 크기(서버 상한 50).
-     * @returns {Promise<RoomSummaryView>} { language, rollup | null, availableFormats, segments, hasNext, nextSeq }
+     * @returns {Promise<RoomSummaryView>} { language, roomStatus, rollup | null, availableFormats, segments, hasNext, nextSeq }
      *
      * @example
      * const view = await chat.getSummary(roomId, { format: 'timeline', lang: 'ko' });
@@ -3377,24 +3394,27 @@ class ChatClient extends EventEmitter {
     /**
      * Rolling 누적 요약 완료 알림(summary 채널) 수신 처리 — status 를 그대로 {@code summaryUpdate} 로 emit.
      *
-     * <p>서버 {@code SummaryStreamEvent}: {@code { status: 'READY'|'NO_CHANGE'|'FAILED'|'INVALIDATED', roomId, format?, languages?, updatedAt? }}.
+     * <p>서버 {@code SummaryStreamEvent}: {@code { status: 'READY'|'NO_CHANGE'|'NO_MESSAGES'|'FAILED'|'INVALIDATED'|string, roomId, format?, languages?, updatedAt? }}.
      * assistant-stream 과 달리 단계/토큰 누적이 없어 상태 관리 없이 그대로 통지한다. transient(저장 안 됨)라 UI 는
      * 이벤트를 신호로만 쓰고 확정 내용은 {@link #getSummary} 로 읽는다. {@code READY}=요약 갱신됨(→ getSummary),
-     * {@code FAILED}=실패(재시도 가능), {@code NO_CHANGE}=변경 없음(대개 refreshSummary 응답에서 동기로 이미 받음),
+     * {@code FAILED}=실패(재시도 가능), {@code NO_CHANGE}=durable 작업이 변경 없이 완료,
+     * {@code NO_MESSAGES}=해당 키에 요약할 대화 없음,
      * {@code INVALIDATED}=방 원문 삭제/편집으로 요약이 통째로 버려짐(→ 요약 화면을 즉시 비우고, 필요 시 refreshSummary 로 재생성).</p>
      *
      * <p><b>키 식별(format+languages)</b>: 한 refresh 가 방 활성 언어들을 fan-out 으로 한 번에 생성하므로(§S1), 완료
-     * 이벤트의 {@code languages} 에 내 언어가 있으면 {@code getSummary({ format, lang })} 로 읽는다. {@code READY}·
-     * {@code FAILED} 모두 언어 목록을 싣는다({@code NO_CHANGE}·{@code INVALIDATED} 는 없음).</p>
+     * 이벤트의 {@code languages} 에 내 언어가 있으면 {@code getSummary({ format, lang })} 로 읽는다.
+     * {@code READY}·{@code NO_CHANGE}·{@code NO_MESSAGES}·{@code FAILED} 모두 언어 목록을 싣는다
+     * ({@code INVALIDATED} 만 없음). 알 수 없는 미래 status도 그대로 전달하므로 소비자는 default 분기와
+     * one-shot {@code getSummary} 재동기화를 둔다.</p>
      * @private
      */
     _handleSummaryEvent(roomId, event) {
         if (!event || !event.status) return;
         this.emit('summaryUpdate', {
             roomId,
-            status: event.status,                 // 'READY' | 'NO_CHANGE' | 'FAILED' | 'INVALIDATED'
-            format: event.format || null,         // READY/FAILED 포함(NO_CHANGE·INVALIDATED 는 null)
-            languages: event.languages || null,   // fan-out 으로 생성/최신화된 언어 목록(READY/FAILED). 그 외 null
+            status: event.status,                 // known status + future server values (pass-through)
+            format: event.format || null,         // READY/NO_CHANGE/NO_MESSAGES/FAILED 포함
+            languages: event.languages || null,   // READY/NO_CHANGE/NO_MESSAGES/FAILED 처리 언어 목록
             updatedAt: event.updatedAt || null
         });
     }
@@ -3490,17 +3510,29 @@ class ChatClient extends EventEmitter {
      * @private
      */
     _emitAssistantRoomProgress(roomId) {
+        // 이벤트 계약은 종전 그대로 둔다 — stream 목록은 getter 전용(이벤트로 매 틱 배열을 실어 보내면
+        // DELTA 마다 방 전체 스트림을 다시 만들어 흘리는 셈이다).
+        const { streams, ...event } = this._assistantRoomProgressPayload(roomId);
+        this.emit('assistantRoomProgress', event);
+    }
+
+    /**
+     * 방 단위 집계 payload 생성 — {@link #_emitAssistantRoomProgress} 와 {@link #getAssistantProgress} 의
+     * <b>공통 SSOT</b>. 두 곳에서 각자 조립하면 "이벤트로 본 상태"와 "물어봐서 본 상태"가 갈린다.
+     * @private
+     */
+    _assistantRoomProgressPayload(roomId) {
         const slots = this._assistantProgress.get(roomId);
         const alive = slots ? Array.from(slots.entries()) : [];
         if (alive.length === 0) {
-            this.emit('assistantRoomProgress', {
+            return {
                 roomId, active: false, streamCount: 0,
-                streamId: null, personaId: null, phase: null, label: null, text: null, textAvailable: true
-            });
-            return;
+                streamId: null, personaId: null, phase: null, label: null, text: null, textAvailable: true,
+                streams: []
+            };
         }
         const [streamId, slot] = alive.reduce((a, b) => (b[1].order > a[1].order ? b : a));
-        this.emit('assistantRoomProgress', {
+        return {
             roomId,
             active: true,
             streamCount: alive.length,
@@ -3509,8 +3541,43 @@ class ChatClient extends EventEmitter {
             phase: slot.phase,
             label: slot.phase ? (this._assistantPhaseLabels[slot.phase] || null) : null,
             text: slot.textAvailable ? (slot.text || null) : null,
-            textAvailable: slot.textAvailable
-        });
+            textAvailable: slot.textAvailable,
+            // stream 단위 UI(권장 (B))가 마운트 즉시 버블을 복원할 수 있도록 전부 싣는다.
+            // 도착 순서(order)대로 — 소비자가 "가장 최근"을 다시 계산하지 않아도 되게 한다.
+            streams: alive
+                .sort((a, b) => a[1].order - b[1].order)
+                .map(([id, s]) => ({
+                    streamId: id,
+                    personaId: s.personaId,
+                    phase: s.phase,
+                    label: s.phase ? (this._assistantPhaseLabels[s.phase] || null) : null,
+                    text: s.textAvailable ? (s.text || null) : null,
+                    textAvailable: s.textAvailable,
+                    resumed: s.resumed === true
+                }))
+        };
+    }
+
+    /**
+     * 방의 <b>현재</b> AI 진행 상태를 즉시 반환 (네트워크 호출 없음).
+     *
+     * <p>{@code assistantProgress} / {@code assistantRoomProgress} 는 transient 이벤트라, 방 화면을 나갔다
+     * 들어오면 프론트 상태가 비어 있는데 <b>이미 지나간 이벤트는 다시 오지 않는다</b>. 마운트 시점에 이걸
+     * 한 번 읽으면 다음 이벤트를 기다리지 않고 바로 그릴 수 있다 — 재입장 스냅샷(1 RTT)보다도 빠르다.</p>
+     *
+     * <p>반환 형태는 {@code assistantRoomProgress} 이벤트와 동일하고, stream 단위 UI 를 위해 {@code streams}
+     * 배열이 추가된다. 진행 중인 것이 없으면 {@code active:false} + 빈 배열.</p>
+     *
+     * @param {string} roomId - 채팅방 ID
+     * @returns {Object} { roomId, active, streamCount, streamId, personaId, phase, label, text, textAvailable, streams[] }
+     *
+     * @example
+     * // 방 화면 마운트 시 — 이벤트를 기다리지 않고 즉시 복원
+     * const p = client.chat.getAssistantProgress(roomId);
+     * if (p.active) renderBubble(p);
+     */
+    getAssistantProgress(roomId) {
+        return this._assistantRoomProgressPayload(roomId);
     }
 
     /**

package/src/constants.js

@@ -364,7 +364,7 @@ export const WebSocketPaths = {
     getChatTypingDestination: (roomId) => `/topic/chat/${roomId}/typing`,
     // AI 진행 표시(생각중/검색중/작성중) + 토큰 스트리밍 — typing 과 별개 채널(가산 UX 레이어).
     getChatAssistantStreamDestination: (roomId) => `/topic/chat/${roomId}/assistant-stream`,
-    // Rolling 누적 요약 완료 알림(READY/NO_CHANGE/FAILED) — refreshSummary 의 비동기 완료 통지 채널.
+    // Rolling 누적 요약 종결 알림(READY/NO_CHANGE/NO_MESSAGES/FAILED) — refreshSummary 비동기 완료 채널.
     getChatSummaryDestination: (roomId) => `/topic/chat/${roomId}/summary`,
 
     // Room list (카톡 스타일 리스트 실시간 업데이트)

package/src/talkflow/delegates.js

@@ -52,6 +52,10 @@ const CHAT_DELEGATE_METHODS = [
     'isSubscribed',
     'startTyping',
     'stopTyping',
+    // AI 진행 표시 — 마운트 즉시 복원용 동기 조회 + 수동 재개. 여기 없으면 최상위 클라이언트에서
+    // 런타임 undefined 가 된다(타입 선언만 있고 배선이 없으면 타입이 거짓말을 한다).
+    'getAssistantProgress',
+    'resumeAssistantStreams',
     'getAssistants',
     'getRoomAiMeta',
     'rateAssistantMessage',

package/types/__typetests__/singleMessageAttachment.types.ts

@@ -13,6 +13,7 @@ import type {
     ChatMessage,
     ChatMessageTypeValue,
     FileMetaData,
+    RoomSummaryView,
     SendFileInfo
 } from '../index';
 import { ChatMessageType } from '../index';
@@ -65,4 +66,24 @@ function legacyResponseFile(f: FileMetaData): string | undefined {
     return f.fileId;
 }
 
-export { category, viaTopLevel, mixed, gallery, document, render, uploadThenSend, optimistic, legacyResponseFile };
+// 7) 서버 rolling 배포를 견디도록 summary 상태는 열린 문자열 union이어야 한다.
+function renderSummaryStatus(status: NonNullable<RoomSummaryView['roomStatus']>): string {
+    switch (status) {
+        case 'QUEUED': return 'queued';
+        case 'IDLE': return 'idle';
+        case 'RUNNING': return 'running';
+        case 'FAILED': return 'failed';
+        case 'NO_MESSAGES': return 'empty';
+        default: {
+            // @ts-expect-error 열린 union이므로 알려진 값만 처리해도 exhaustive never가 될 수 없다.
+            const futureServerStatus: never = status;
+            void futureServerStatus;
+            return 'unknown';
+        }
+    }
+}
+
+const futureSummaryStatus: NonNullable<RoomSummaryView['roomStatus']> = 'FUTURE_SERVER_STATUS';
+
+export { category, viaTopLevel, mixed, gallery, document, render, uploadThenSend, optimistic, legacyResponseFile,
+    renderSummaryStatus, futureSummaryStatus };

package/types/index.d.ts

@@ -327,16 +327,20 @@ export interface RefreshSummaryOptions {
 export interface RefreshSummaryResult {
     /**
      * <ul>
-     *   <li>{@code 'STARTED'} — 요약 워커 시작됨({@code summaryUpdate} 대기).</li>
-     *   <li>{@code 'ALREADY_RUNNING'} — 방에서 요약이 진행 중(<b>다른</b> 포맷·언어일 수 있음). {@code format}/{@code language}
-     *       로 내 키인지 확인하고, {@code summaryUpdate} 가 내 키가 아니면 그때 다시 요청한다(무조건 재요청 금지 아님).</li>
-     *   <li>{@code 'NO_CHANGE'} — 새 대화 없음(알림 발생 안 함; 직전 실패가 있었다면 자동 복구됨).</li>
+     *   <li>{@code 'QUEUED'} — 방 단위 durable work item 에 저장·병합됐다. pod 실행 슬롯이 포화여도
+     *       요청은 버려지지 않으며, 최종 {@code READY|NO_CHANGE|NO_MESSAGES|FAILED} {@code summaryUpdate} 를 기다린다.</li>
      * </ul>
+     *
+     * <p>durable 저장 자체가 실패하면 성공 결과가 아니라 <b>HTTP 503</b>
+     * ({@code SUMMARY_REFRESH_UNAVAILABLE})으로 오며, {@link ChatClient.refreshSummary} 가 reject 한다.</p>
+     *
+     * <p>⚠️ <b>닫힌 union 이 아니다</b>: 서버가 값을 추가할 수 있으므로 분기에는 반드시 default 를 둔다.
+     * 모르는 값을 {@code QUEUED} 로 가정하지 말고 별도 상태 확인 UI를 표시한다.</p>
      */
-    status: 'STARTED' | 'ALREADY_RUNNING' | 'NO_CHANGE';
-    /** 이번 요청이 해소한 포맷({@link SummarizeFormat} 소문자). 방 단위 경합 식별용. */
+    status: 'QUEUED' | (string & {});
+    /** durable work item 에 병합한 포맷({@link SummarizeFormat} 소문자). */
     format?: string;
-    /** 이번 요청이 해소한 언어(소문자 BCP-47 / {@code 'OFF'}=원문). 방 단위 경합 식별용. */
+    /** durable work item 에 병합한 요청자 언어(소문자 BCP-47 / {@code 'OFF'}=원문). */
     language?: string;
 }
 
@@ -400,11 +404,15 @@ export interface RoomSummaryView {
      */
     language: string;
     /**
-     * 방 전체 요약 프로세스 상태 — {@code 'IDLE'}(대기) | {@code 'RUNNING'}(요약 중) | {@code 'FAILED'}(실패).
-     * <b>방 단위(키별 아님)</b>: 방은 한 번에 한 키만 요약하므로, 지금 다른 포맷·언어를 요약 중이어도 {@code 'RUNNING'} 이다.
-     * 특정 rollup 의 최신 여부는 {@code rollup.stale} 로 판단한다(rollup 자체는 완료된 데이터). 요약 이력이 없으면 null.
+     * 실행 상태 — {@code 'QUEUED'}(durable 대기) | {@code 'IDLE'}(유휴) |
+     * {@code 'RUNNING'}(요약 중) | {@code 'FAILED'}(선택 키 실패) |
+     * {@code 'NO_MESSAGES'}(선택 키에 요약할 대화 없음).
+     * 대기/실행은 방 단위이고 terminal 결과는 조회한 포맷×언어 키 기준이다. 특정 rollup 의 최신 여부는
+     * {@code rollup.stale} 로 판단한다. 요약 이력이 없어도 durable job 상태가 있으면 null이 아닐 수 있다.
+     * 닫힌 union이 아니므로 분기에는 default를 둔다.
      */
-    roomStatus: 'IDLE' | 'RUNNING' | 'FAILED' | null;
+    /** durable execution-plane 상태에서 합성되므로 재접속 뒤에도 복원된다. */
+    roomStatus: 'QUEUED' | 'IDLE' | 'RUNNING' | 'FAILED' | 'NO_MESSAGES' | (string & {}) | null;
     /** 요청/기본 포맷의 통합 요약본. 그 포맷×언어로 아직 요약 안 됐으면 null(availableFormats 로 같은 언어의 다른 포맷 확인). */
     rollup: RoomSummaryRollup | null;
     /** 이 방이 <b>이 언어로</b> 보유한 포맷 목록(short/timeline/… — 탭 렌더용). 타 언어는 포함하지 않는다. */
@@ -424,15 +432,18 @@ export interface RoomSummaryView {
 export interface SummaryUpdateEvent {
     roomId: string;
     /**
-     * {@code 'READY'}(갱신됨 → getSummary) | {@code 'FAILED'}(실패 → 재시도 가능) | {@code 'NO_CHANGE'}(변경 없음) |
+     * {@code 'READY'}(갱신됨 → getSummary) | {@code 'FAILED'}(실패 → 재시도 가능) |
+     * {@code 'NO_CHANGE'}(변경 없이 durable 작업 종결 → getSummary로 최종 동기화) |
+     * {@code 'NO_MESSAGES'}(선택 키에 요약할 대화 없음) |
      * {@code 'INVALIDATED'}(방 원문 삭제/편집으로 요약이 통째로 버려짐 → 화면을 비우고 필요 시 refreshSummary 로 재생성).
+     * 닫힌 union이 아니므로 모르는 값은 추측하지 말고 one-shot getSummary로 재동기화한다.
      */
-    status: 'READY' | 'NO_CHANGE' | 'FAILED' | 'INVALIDATED';
-    /** 완료/실패한 포맷. {@code READY}·{@code FAILED} 포함, {@code NO_CHANGE}·{@code INVALIDATED} 는 null. */
+    status: 'READY' | 'NO_CHANGE' | 'NO_MESSAGES' | 'FAILED' | 'INVALIDATED' | (string & {});
+    /** 완료 포맷. {@code READY}·{@code NO_CHANGE}·{@code NO_MESSAGES}·{@code FAILED} 포함, {@code INVALIDATED} 는 null. */
     format: string | null;
     /**
-     * fan-out 으로 한 번에 생성/최신화된 언어 목록(소문자 BCP-47 / {@code 'OFF'}). {@code READY}·{@code FAILED} 포함,
-     * 그 외 null. 각 사용자는 자기 언어가 이 목록에 있으면 {@code getSummary({ format, lang })} 로 읽는다(§S1).
+     * fan-out 으로 한 번에 처리한 언어 목록(소문자 BCP-47 / {@code 'OFF'}).
+     * {@code READY}·{@code NO_CHANGE}·{@code NO_MESSAGES}·{@code FAILED} 포함, {@code INVALIDATED} 만 null.
      */
     languages: string[] | null;
     /** 갱신 시각(epoch millis). {@code READY} 만 포함, 그 외 null. */
@@ -1260,6 +1271,29 @@ export interface AssistantRoomProgressEvent {
     textAvailable?: boolean;
 }
 
+/** {@link ChatClient.getAssistantProgress} 가 돌려주는 stream 1건. */
+export interface AssistantProgressStreamSnapshot {
+    streamId: string;
+    personaId: string | null;
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'WRITING' | null;
+    label: string | null;
+    text: string | null;
+    textAvailable: boolean;
+    /** 서버 스냅샷으로 복원된 진행분이면 true. */
+    resumed: boolean;
+}
+
+/**
+ * 방의 **현재** AI 진행 상태 (v5.3.0 — {@link ChatClient.getAssistantProgress} 반환).
+ *
+ * <p>{@link AssistantRoomProgressEvent} 와 같은 형태에 stream 단위 UI 를 위한 `streams` 가 더해진다.
+ * 이벤트는 transient 라 화면을 나갔다 들어오면 다시 오지 않는다 — 마운트 시 이걸 한 번 읽는다.</p>
+ */
+export interface AssistantProgressSnapshot extends AssistantRoomProgressEvent {
+    /** 살아 있는 stream 전체 (도착 순서). 없으면 빈 배열. */
+    streams: AssistantProgressStreamSnapshot[];
+}
+
 // ============================================================================
 // Options — constructor & method
 // ============================================================================
@@ -2017,6 +2051,17 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
 
     startTyping(roomId: string): void;
     stopTyping(roomId: string): void;
+
+    /**
+     * 방의 현재 AI 진행 상태를 즉시 반환 (네트워크 호출 없음, v5.3.0).
+     * 진행 표시 이벤트는 transient 라 방 화면 마운트 시 이걸 읽어 버블을 복원한다.
+     */
+    getAssistantProgress(roomId: string): AssistantProgressSnapshot;
+    /**
+     * 구독 중인 모든 방의 진행 스트림 스냅샷을 서버에서 다시 받는다 (v5.1.0).
+     * 재연결·탭 복귀 때 SDK 가 자동 호출하므로 보통은 직접 부를 일이 없다.
+     */
+    resumeAssistantStreams(reason?: string): Promise<void>;
 }
 
 export class WebRTCClient implements SdkEventEmitter<WebRTCClientEvents> {
@@ -2400,6 +2445,17 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     startTyping(roomId: string): void;
     stopTyping(roomId: string): void;
 
+    /**
+     * 방의 현재 AI 진행 상태를 즉시 반환 (네트워크 호출 없음, v5.3.0).
+     * 진행 표시 이벤트는 transient 라 방 화면 마운트 시 이걸 읽어 버블을 복원한다.
+     */
+    getAssistantProgress(roomId: string): AssistantProgressSnapshot;
+    /**
+     * 구독 중인 모든 방의 진행 스트림 스냅샷을 서버에서 다시 받는다 (v5.1.0).
+     * 재연결·탭 복귀 때 SDK 가 자동 호출하므로 보통은 직접 부를 일이 없다.
+     */
+    resumeAssistantStreams(reason?: string): Promise<void>;
+
     // WebRTC delegations
     initializeIceServers(): Promise<RTCIceServer[]>;
     getTurnCredentials(): Promise<{ iceServers: RTCIceServer[] }>;