@vibexnpm/talkx 2.5.0 → 3.0.1

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,104 @@ 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;
+}
+
+// ── Rolling 누적 요약 (refreshSummary / getSummary / summaryUpdate) ──
+
+/** {@link ChatClient.refreshSummary} 옵션. */
+export interface RefreshSummaryOptions {
+    /** 요약 포맷 ({@link SummarizeFormat}). 미지정/알 수 없는 값이면 서버가 {@code SHORT} 적용. */
+    format?: SummarizeFormatValue;
+}
+
+/**
+ * {@link ChatClient.refreshSummary} 반환 — 비동기 접수 결과(서버 {@code SummaryRefreshResult}).
+ * 실제 완료는 {@code summaryUpdate} 이벤트 + {@link ChatClient.getSummary} 로 확인한다.
+ */
+export interface RefreshSummaryResult {
+    /**
+     * <ul>
+     *   <li>{@code 'STARTED'} — 요약 워커 시작됨({@code summaryUpdate} 대기).</li>
+     *   <li>{@code 'ALREADY_RUNNING'} — 이미 진행 중(중복 트리거 — 재요청하지 말 것).</li>
+     *   <li>{@code 'NO_CHANGE'} — 새 대화 없음(알림 발생 안 함; 직전 실패가 있었다면 자동 복구됨).</li>
+     * </ul>
+     */
+    status: 'STARTED' | 'ALREADY_RUNNING' | 'NO_CHANGE';
+}
+
+/** {@link ChatClient.getSummary} 옵션. */
+export interface GetSummaryOptions {
+    /** segment 페이지 커서(exclusive). 미지정 시 처음부터. */
+    afterSeq?: number;
+    /** segment 페이지 크기(서버 상한 50). */
+    size?: number;
+}
+
+/** Rolling 누적 요약 통합본 — {@link RoomSummaryView.rollup}. */
+export interface RoomSummaryRollup {
+    /** 요약 본문 ({@code format} 적용됨). */
+    content: string;
+    /** 적용된 포맷 ({@link SummarizeFormat} 소문자). */
+    format: string;
+    /** rollup 이 커버하는 가장 오래된 지점. */
+    coverStartAt: string | null;
+    /** 마지막으로 요약된 지점. */
+    watermarkAt: string | null;
+    /** 전체 segment 수(페이지 총량 힌트). */
+    segmentCount: number;
+    /** 진행 상태. {@code 'IDLE'}(완료/대기) | {@code 'RUNNING'}(요약 중) | {@code 'FAILED'}(실패). */
+    status: 'IDLE' | 'RUNNING' | 'FAILED';
+    /** 마지막 갱신 시각. */
+    updatedAt: string;
+}
+
+/** Rolling 누적 요약 구간 부분요약 — {@link RoomSummaryView.segments} 항목. 항상 {@code contentFormat==='neutral'}. */
+export interface RoomSummarySegment {
+    /** segment 순번(0부터). 페이지 커서. */
+    seq: number;
+    /** 구간 부분요약 본문. */
+    content: string;
+    /** 항상 {@code 'neutral'}(format 미적용). */
+    contentFormat: string;
+    fromSentAt: string | null;
+    fromMessageId: string | null;
+    toSentAt: string | null;
+    toMessageId: string | null;
+    /** 이 구간이 담은 메시지 수. */
+    messageCount: number;
+}
+
+/**
+ * {@link ChatClient.getSummary} 반환 — 서버 {@code RoomSummaryView}.
+ * 아직 한 번도 요약되지 않았으면 {@code rollup} 이 {@code null} 이고 {@code segments} 는 빈 배열이다.
+ */
+export interface RoomSummaryView {
+    /** 통합 요약본. 최초 요약 전이면 null. */
+    rollup: RoomSummaryRollup | null;
+    /** 구간 부분요약 페이지. */
+    segments: RoomSummarySegment[];
+    /** 다음 segment 페이지 존재 여부. */
+    hasNext: boolean;
+    /** 다음 페이지 커서({@code getSummary} 의 {@code afterSeq} 로 사용). {@code hasNext === false} 면 null. */
+    nextSeq: number | null;
+}
+
+/**
+ * {@code summaryUpdate} 이벤트 payload — Rolling 요약 완료/실패 통지(서버 {@code SummaryStreamEvent}).
+ * transient(저장 안 됨) — 확정 내용은 {@link ChatClient.getSummary} 로 읽는다.
+ */
+export interface SummaryUpdateEvent {
+    roomId: string;
+    /** {@code 'READY'}(갱신됨 → getSummary) | {@code 'FAILED'}(실패 → 재시도 가능) | {@code 'NO_CHANGE'}(변경 없음). */
+    status: 'READY' | 'NO_CHANGE' | 'FAILED';
+    /** 적용된 포맷. {@code READY} 만 포함, 그 외 null. */
+    format: string | null;
+    /** 갱신 시각. {@code READY} 만 포함, 그 외 null. */
+    updatedAt: string | null;
 }
 
 /**
@@ -1123,6 +1225,8 @@ export interface TalkFlowClientEvents {
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
     assistantProgress: AssistantProgressEvent;
+    /** Rolling 누적 요약 완료/실패 통지 (transient) — refreshSummary 후. */
+    summaryUpdate: SummaryUpdateEvent;
     memberJoined: MemberChangePayload;
     memberLeft: MemberChangePayload;
     roomSubscribed: { roomId: string };
@@ -1237,6 +1341,8 @@ export interface ChatClientEvents {
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
     assistantProgress: AssistantProgressEvent;
+    /** Rolling 누적 요약 완료/실패 통지 (transient) — refreshSummary 후. */
+    summaryUpdate: SummaryUpdateEvent;
 }
 
 /**
@@ -1300,8 +1406,12 @@ 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>;
+    /** Rolling 누적 요약 갱신 트리거 (비동기). 완료는 {@code summaryUpdate} 이벤트 + {@link getSummary} 로 확인. */
+    refreshSummary(roomId: string, options?: RefreshSummaryOptions): Promise<RefreshSummaryResult>;
+    /** Rolling 누적 요약 조회 — rollup + segment 페이지. 저장된 요약의 단일 진실 소스. */
+    getSummary(roomId: string, options?: GetSummaryOptions): Promise<RoomSummaryView>;
     /** 방 PM 프롬프트 레이어 조회 — PM_BACKSTAGE 방 전용, 참여자 전체. 미등록 시 404. */
     getRoomPmPrompt(roomId: string): Promise<PmPromptLayerResponse>;
     /** 방 PM 프롬프트 레이어 등록/수정 (upsert, 새 버전 자동 기록) — 방 주인(OWNER) 전용. content 1~2,000자. */
@@ -1641,8 +1751,12 @@ 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>;
+    /** Rolling 누적 요약 갱신 트리거 (비동기). 완료는 {@code summaryUpdate} 이벤트 + {@link getSummary} 로 확인. */
+    refreshSummary(roomId: string, options?: RefreshSummaryOptions): Promise<RefreshSummaryResult>;
+    /** Rolling 누적 요약 조회 — rollup + segment 페이지. 저장된 요약의 단일 진실 소스. */
+    getSummary(roomId: string, options?: GetSummaryOptions): Promise<RoomSummaryView>;
     /** 방 PM 프롬프트 레이어 조회 — PM_BACKSTAGE 방 전용, 참여자 전체. 미등록 시 404. */
     getRoomPmPrompt(roomId: string): Promise<PmPromptLayerResponse>;
     /** 방 PM 프롬프트 레이어 등록/수정 (upsert, 새 버전 자동 기록) — 방 주인(OWNER) 전용. content 1~2,000자. */