@vibexnpm/talkx 2.3.1 → 3.0.0

package/README.md

@@ -198,14 +198,13 @@ if (summary.outcome !== 'EMITTED') console.warn(summary.detail); // SKIPPED/FAIL
 
 // 3) 번역 — 특정 메시지를 목표 언어로 번역
 const translated = await client.translateWithAssistant(roomId, {
-  personaId,
   sourceMessageId: message.messageId,
-  targetLang: 'en'                    // 선택 (미지정 시 서버 정책)
+  targetLang: 'en'                    // 필수
 });
-// 결과 메시지는 일반 chatMessage 이벤트로도 수신됨 (outcome === 'EMITTED' 시 messageId 존재)
+renderTranslatedText(translated.translatedText); // 요청자 전용 응답, 방 broadcast 없음
 ```
 
-요약/번역은 동기 호출이라 LLM 처리(수 초) 후 반환되며, 생성된 어시스턴트 메시지는 일반 `chatMessage` 이벤트로도 도착합니다.
+요약/번역은 동기 호출이라 LLM 처리(수 초) 후 반환됩니다. 요약은 생성된 어시스턴트 메시지가 일반 `chatMessage` 이벤트로도 도착하고, 번역은 요청자 전용 응답으로만 반환됩니다.
 
 ---
 

package/dist/index.d.ts

@@ -236,7 +236,7 @@ export interface AssistantPersonaResponse {
 
 /**
  * 어시스턴트 도구 실행 결과 — 서버 {@code AssistantToolResult}.
- * {@link ChatClient.summarizeWithAssistant} / {@link ChatClient.translateWithAssistant} 반환.
+ * {@link ChatClient.summarizeWithAssistant} 반환.
  */
 export interface AssistantToolResult {
     /**
@@ -254,6 +254,16 @@ export interface AssistantToolResult {
     detail: string | null;
 }
 
+/** {@link ChatClient.translateWithAssistant} 반환 — 요청자 전용 온디맨드 번역 응답. */
+export interface OnDemandTranslationResponse {
+    /** 번역된 텍스트. */
+    translatedText: string;
+    /** 번역 대상 원본 메시지의 {@code messageId}. */
+    sourceMessageId: string;
+    /** 요청한 목표 언어. */
+    targetLang: string;
+}
+
 /** {@link ChatClient.summarizeWithAssistant} 옵션 — 서버 {@code SummarizeToolRequest}. */
 export interface SummarizeToolRequest {
     /** 요약을 수행할 어시스턴트 ID ({@link AssistantPersonaResponse.id}). 필수. */
@@ -266,12 +276,10 @@ export interface SummarizeToolRequest {
 
 /** {@link ChatClient.translateWithAssistant} 옵션 — 서버 {@code TranslateToolRequest}. */
 export interface TranslateToolRequest {
-    /** 번역을 수행할 어시스턴트 ID ({@link AssistantPersonaResponse.id}). 필수. */
-    personaId: string;
     /** 번역 대상 메시지의 {@code messageId}. 필수. */
     sourceMessageId: string;
-    /** 목표 언어 (예: {@code 'en'}). 미지정 시 서버 정책. */
-    targetLang?: string;
+    /** 목표 언어 (예: {@code 'en'}). 필수. */
+    targetLang: string;
 }
 
 /**
@@ -378,6 +386,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 +744,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 +1101,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 +1130,7 @@ export interface TalkFlowClientEvents {
     messageTranslated: ChatMessageReceivedPayload;
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
+    assistantProgress: AssistantProgressEvent;
     memberJoined: MemberChangePayload;
     memberLeft: MemberChangePayload;
     roomSubscribed: { roomId: string };
@@ -1198,6 +1244,7 @@ export interface ChatClientEvents {
     retentionCleanup: RetentionCleanupPayload;
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
+    assistantProgress: AssistantProgressEvent;
 }
 
 /**
@@ -1261,8 +1308,8 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
     rateAssistantMessage(roomId: string, messageId: string, rating: number, comment?: string): Promise<void>;
     /** 어시스턴트로 대화 요약 (버튼 진입점, 동기). */
     summarizeWithAssistant(roomId: string, options: SummarizeToolRequest): Promise<AssistantToolResult>;
-    /** 어시스턴트로 특정 메시지 번역 (버튼 진입점, 동기). */
-    translateWithAssistant(roomId: string, options: TranslateToolRequest): Promise<AssistantToolResult>;
+    /** 특정 메시지 온디맨드 번역 (버튼 진입점, 동기, 요청자 전용 응답). */
+    translateWithAssistant(roomId: string, options: TranslateToolRequest): Promise<OnDemandTranslationResponse>;
     /** 방 PM 프롬프트 레이어 조회 — PM_BACKSTAGE 방 전용, 참여자 전체. 미등록 시 404. */
     getRoomPmPrompt(roomId: string): Promise<PmPromptLayerResponse>;
     /** 방 PM 프롬프트 레이어 등록/수정 (upsert, 새 버전 자동 기록) — 방 주인(OWNER) 전용. content 1~2,000자. */
@@ -1602,8 +1649,8 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     rateAssistantMessage(roomId: string, messageId: string, rating: number, comment?: string): Promise<void>;
     /** 어시스턴트로 대화 요약 (버튼 진입점, 동기). */
     summarizeWithAssistant(roomId: string, options: SummarizeToolRequest): Promise<AssistantToolResult>;
-    /** 어시스턴트로 특정 메시지 번역 (버튼 진입점, 동기). */
-    translateWithAssistant(roomId: string, options: TranslateToolRequest): Promise<AssistantToolResult>;
+    /** 특정 메시지 온디맨드 번역 (버튼 진입점, 동기, 요청자 전용 응답). */
+    translateWithAssistant(roomId: string, options: TranslateToolRequest): Promise<OnDemandTranslationResponse>;
     /** 방 PM 프롬프트 레이어 조회 — PM_BACKSTAGE 방 전용, 참여자 전체. 미등록 시 404. */
     getRoomPmPrompt(roomId: string): Promise<PmPromptLayerResponse>;
     /** 방 PM 프롬프트 레이어 등록/수정 (upsert, 새 버전 자동 기록) — 방 주인(OWNER) 전용. content 1~2,000자. */