@vibexnpm/talkx 8.1.0 → 8.4.1

package/package.json

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

package/src/chat/ChatClient.js

@@ -143,6 +143,7 @@ class ChatClient extends EventEmitter {
             SEARCHING: '검색 중…',
             PLANNING: '기획 중…',
             DOCUMENT_ANALYSIS: '문서 분석 중…',
+            VIDEO_ANALYSIS: '영상 분석 중…',
             WRITING: '작성 중…'
         };
         // PHASE 의 expiresAt 누락/이상 시 fallback TTL (ms) — 서버 ttl(최소 30s) 보다 약간 길게.
@@ -595,6 +596,50 @@ class ChatClient extends EventEmitter {
         return this._unwrapSuccessResponse(response);
     }
 
+    /** 영상 분석용 비공개 업로드. 반환한 assetId를 analyzeVideo에 전달한다. */
+    async uploadVideoAsset(file, options = {}) {
+        if (!file) throw new Error('file is required');
+        return this._unwrapSuccessResponse(await this.apiClient.upload('/api/v1/video-assets', file, {
+            onProgress: options.onProgress, signal: options.signal
+        }));
+    }
+
+    /** 비공개 분석 접수. 네트워크 재시도에는 같은 idempotencyKey를 사용한다. */
+    async analyzeVideo(analysis, options = {}) {
+        if (typeof options.idempotencyKey !== 'string' || !options.idempotencyKey.trim()) {
+            throw new Error('idempotencyKey is required for video analysis');
+        }
+        return this._unwrapSuccessResponse(await this.apiClient.post('/api/v1/video-analyses', analysis,
+            undefined, { 'Idempotency-Key': options.idempotencyKey }));
+    }
+
+    /** 같은 분석 코어를 호출하고 결과를 지정한 방에 게시한다. */
+    async analyzeVideoWithAssistant(roomId, request, options = {}) {
+        if (!roomId || !request?.personaId || !request?.triggerMessageId) {
+            throw new Error('roomId, personaId and triggerMessageId are required');
+        }
+        if (typeof options.idempotencyKey !== 'string' || !options.idempotencyKey.trim()) {
+            throw new Error('idempotencyKey is required for video analysis');
+        }
+        return this._unwrapSuccessResponse(await this.apiClient.post(
+            `/api/v1/rooms/${encodeURIComponent(roomId)}/assistant/tools/analyze-video`, request,
+            undefined, { 'Idempotency-Key': options.idempotencyKey }));
+    }
+
+    async getVideoAnalysis(jobId) {
+        if (!jobId) throw new Error('jobId is required');
+        return this._unwrapSuccessResponse(await this.apiClient.get(`/api/v1/video-analyses/${encodeURIComponent(jobId)}`));
+    }
+
+    async cancelVideoAnalysis(jobId) {
+        if (!jobId) throw new Error('jobId is required');
+        return this._unwrapSuccessResponse(await this.apiClient.post(`/api/v1/video-analyses/${encodeURIComponent(jobId)}/cancel`));
+    }
+
+    async getVideoAnalysisCapabilities() {
+        return this._unwrapSuccessResponse(await this.apiClient.get('/api/v1/video-analyses/capabilities'));
+    }
+
     /**
      * 특정 메시지 온디맨드 번역 (버튼 진입점, 동기).
      *
@@ -868,12 +913,84 @@ class ChatClient extends EventEmitter {
     }
 
     /**
-     * 채팅방 나가기 (구독도 자동 해제됨)
+     * 채팅방 나가기 (구독도 자동 해제됨).
+     *
+     * <p>일반 참가자는 {@code leaveRoom(roomId)} 그대로. <b>방장</b>은 그냥 나갈 수 없다 — 나가면 방에 관리자가
+     * 0명이 되기 때문이다. 방장은 둘 중 하나를 고른다:</p>
+     * <ul>
+     *   <li>위임 후 나가기 — {@code leaveRoom(roomId, { newOwnerId })}</li>
+     *   <li>방 삭제 — {@link #deleteRoom}</li>
+     * </ul>
+     *
+     * <p>서버 응답:</p>
+     * <ul>
+     *   <li>409 {@code ROOM_OWNER_CANNOT_LEAVE} — 방장이 newOwnerId 없이 나가려 함 (선택 화면을 띄울 신호)</li>
+     *   <li>403 {@code NOT_ROOM_ADMIN} — 방장이 아닌데 newOwnerId 를 보냄</li>
+     *   <li>400 {@code CANNOT_TRANSFER_OWNERSHIP_TO_SELF} / {@code INVALID_OWNERSHIP_TARGET}, 404 {@code USER_NOT_IN_ROOM}
+     *       — 위임 대상 오류 ({@link #transferOwnership} 와 같다). 이때는 나가지도 않는다.</li>
+     * </ul>
+     *
      * @param {string} roomId - 채팅방 ID
+     * @param {Object} [options]
+     * @param {string} [options.newOwnerId] - 방장이 나갈 때 방장을 넘겨받을 사람 (방의 활성 사람 참가자 · 활성 계정)
+     * @returns {Promise<Object>}
+     *
+     * @example
+     * try {
+     *   await chat.leaveRoom(roomId);
+     * } catch (e) {
+     *   // 서버 코드는 e.response.code — 방장이면 «위임 후 나가기 / 방 삭제» 선택 화면
+     *   if (e.response?.code === 'ROOM_OWNER_CANNOT_LEAVE') openOwnerExitDialog(roomId);
+     * }
+     * // 위임 후 나가기
+     * await chat.leaveRoom(roomId, { newOwnerId: 'user-2' });
+     */
+    async leaveRoom(roomId, options = {}) {
+        const body = options.newOwnerId ? { newOwnerId: options.newOwnerId } : undefined;
+        const result = await this.apiClient.post(`/api/v1/rooms/${roomId}/leave`, body);
+        this.unsubscribeRoom(roomId);
+        return result;
+    }
+
+    /**
+     * 방장 위임 — 방장은 방에 남고 MEMBER 가 된다. 방장(OWNER) 전용.
+     *
+     * <p>나가면서 넘기려면 {@code leaveRoom(roomId, { newOwnerId })}. 방 참가자 전원에게
+     * {@code roomListOwnerChanged} 가 간다(actorId = 이전 방장, members[0] = 새 방장).</p>
+     *
+     * <p>서버 응답:</p>
+     * <ul>
+     *   <li>403 {@code NOT_ROOM_ADMIN} — 방장 아님 (DIRECT 방은 방장이 없다)</li>
+     *   <li>400 {@code CANNOT_TRANSFER_OWNERSHIP_TO_SELF} — 자기 자신에게 위임</li>
+     *   <li>404 {@code USER_NOT_IN_ROOM} — 대상이 현재 참가자가 아님</li>
+     *   <li>400 {@code INVALID_OWNERSHIP_TARGET} — 대상이 어시스턴트이거나 퇴사·차단 계정</li>
+     * </ul>
+     *
+     * @param {string} roomId
+     * @param {string} newOwnerId - 새 방장 userId
+     * @returns {Promise<Object>} 갱신된 방 상세 (participants[].role 반영 — 봉투를 벗긴 data)
+     */
+    async transferOwnership(roomId, newOwnerId) {
+        const response = await this.apiClient.put(`/api/v1/rooms/${roomId}/owner`, { newOwnerId });
+        return response && typeof response === 'object' && 'data' in response
+            ? response.data
+            : response;
+    }
+
+    /**
+     * 방 삭제 — 방장(OWNER) 전용. 참가자 전원이 나가게 되고 방은 목록에서 사라진다.
+     * 이후 enterRoom·getRoomInfo 는 403(ACCESS_FORBIDDEN — 더는 참가자가 아님), joinGroupRoom 은 404(CHAT_ROOM_NOT_FOUND).
+     *
+     * <p>참가자 전원(방장 포함)에게 {@code roomListDeleted} 가 간다. 본인 구독은 자동 해제된다.
+     * 메시지·첨부는 서버에 보존된다(소프트 삭제) — 되살리는 API 는 없다.</p>
+     *
+     * <p>서버 응답: 403 {@code NOT_ROOM_ADMIN} — 방장 아님.</p>
+     *
+     * @param {string} roomId
      * @returns {Promise<Object>}
      */
-    async leaveRoom(roomId) {
-        const result = await this.apiClient.post(`/api/v1/rooms/${roomId}/leave`);
+    async deleteRoom(roomId) {
+        const result = await this.apiClient.delete(`/api/v1/rooms/${roomId}`);
         this.unsubscribeRoom(roomId);
         return result;
     }
@@ -2551,6 +2668,8 @@ class ChatClient extends EventEmitter {
      *  - roomListJoined — 방 입장 (ROOM_JOINED)
      *  - roomListLeft — 방 퇴장 (ROOM_LEFT)
      *  - roomListSelfLeft — 본인이 나간 경우 (리스트에서 제거 신호)
+     *  - roomListOwnerChanged — 방장 위임 (ROOM_OWNER_CHANGED, members[0] = 새 방장)
+     *  - roomListDeleted — 방장이 방을 삭제 (ROOM_DELETED, 리스트 제거 + 방 화면 닫기)
      *
      * @returns {Promise<void>}
      *
@@ -2819,6 +2938,19 @@ class ChatClient extends EventEmitter {
                     this.emit('roomListSelfKicked', event);
                 }
                 break;
+            case RoomListEventType.ROOM_OWNER_CHANGED:
+                // 방장 위임 — actorId=이전 방장, members[0]=새 방장. 방장 표시·관리 메뉴를 갱신한다.
+                this.emit('roomListOwnerChanged', event);
+                break;
+            case RoomListEventType.ROOM_DELETED:
+                // 방장이 방을 삭제 — 모든 참가자가 리스트에서 제거하고 열린 방 화면을 닫는다.
+                // 🔴 그 방 구독은 SDK 가 «먼저» 푼다. 남겨 두면 아무것도 못 받으면서 재연결 때마다 되살아나 서버에
+                //    거부된다 — 그 거부로 연결을 끊던 서버 버전에서는 «재연결 → 거부 → 끊김» 이 반복돼 다른 방 실시간까지 멈췄다.
+                if (this.subscribedRooms.has(event.roomId)) {
+                    this.unsubscribeRoom(event.roomId);
+                }
+                this.emit('roomListDeleted', event);
+                break;
             case RoomListEventType.ROOM_BANNED:
                 this.emit('roomListBanned', event);
                 // 본인이 영구 차단당한 경우 편의 이벤트 — "영구 차단되었습니다" 표시 + 리스트 제거

package/src/constants.js

@@ -333,6 +333,18 @@ export const RoomListEventType = {
     ROOM_KICKED: 'ROOM_KICKED',
     /** 방장에 의한 추방 + 영구 차단 → payload 는 ROOM_KICKED 와 동일, 재입장 거부됨. */
     ROOM_BANNED: 'ROOM_BANNED',
+    /**
+     * 방장 위임 → actorId 는 이전 방장, members[0] 이 새 방장. 방장 표시·관리 권한을 갱신한다.
+     * «위임 후 나가기» 면 이어서 같은 이전 방장의 ROOM_LEFT 가 온다.
+     * SDK 는 이를 roomListOwnerChanged 이벤트로 emit 한다.
+     */
+    ROOM_OWNER_CHANGED: 'ROOM_OWNER_CHANGED',
+    /**
+     * 방장이 방을 삭제 → 리스트에서 제거 + 열린 방 화면 닫기. actorId 는 삭제한 방장.
+     * 이후 enterRoom·getRoomInfo 는 403(ACCESS_FORBIDDEN — 더는 참가자가 아님), joinGroupRoom 은 404.
+     * SDK 는 이를 roomListDeleted 이벤트로 emit 한다.
+     */
+    ROOM_DELETED: 'ROOM_DELETED',
     /** 메시지 보관 기간 정리 → cutoffTime 이전 메시지를 UI에서 제거. */
     MESSAGE_RETENTION_CLEANUP: 'MESSAGE_RETENTION_CLEANUP',
     /**

package/src/talkflow/delegates.js

@@ -7,6 +7,9 @@ const CHAT_DELEGATE_METHODS = [
     'createGroupRoom',
     'joinGroupRoom',
     'leaveRoom',
+    // 방장 위임(방에 남음) · 방 삭제 — 방장의 «위임 후 나가기» 는 leaveRoom(roomId, { newOwnerId }).
+    'transferOwnership',
+    'deleteRoom',
     'updateGroupRoom',
     'inviteToGroupRoom',
     'kickMember',
@@ -61,6 +64,12 @@ const CHAT_DELEGATE_METHODS = [
     'rateAssistantMessage',
     'summarizeWithAssistant',
     'translateWithAssistant',
+    'uploadVideoAsset',
+    'analyzeVideo',
+    'analyzeVideoWithAssistant',
+    'getVideoAnalysis',
+    'cancelVideoAnalysis',
+    'getVideoAnalysisCapabilities',
     'refreshSummary',
     'getSummary',
     'getRoomPmPrompt',

package/src/talkflow/eventForwarding.js

@@ -34,6 +34,8 @@ const CHAT_EVENT_MAP = [
     ['roomListUnsubscribed', 'roomListUnsubscribed'],
     ['roomListUpdate', 'roomListUpdate'],
     ['roomListMessage', 'roomListMessage'],
+    ['roomListMessageDeleted', 'roomListMessageDeleted'],
+    ['roomListMessageUpdated', 'roomListMessageUpdated'],
     ['roomListCreated', 'roomListCreated'],
     ['roomListJoined', 'roomListJoined'],
     ['roomListLeft', 'roomListLeft'],
@@ -42,6 +44,9 @@ const CHAT_EVENT_MAP = [
     ['roomListSelfKicked', 'roomListSelfKicked'],
     ['roomListBanned', 'roomListBanned'],
     ['roomListSelfBanned', 'roomListSelfBanned'],
+    // 방장 위임 · 방 삭제 — 타입에 선언한 이벤트는 여기 없으면 최상위 client.on 에서 안 울린다.
+    ['roomListOwnerChanged', 'roomListOwnerChanged'],
+    ['roomListDeleted', 'roomListDeleted'],
     ['roomListRoomUpdated', 'roomListRoomUpdated'],
     ['roomListUnreadUpdated', 'roomListUnreadUpdated'],
     ['retentionCleanup', 'retentionCleanup']

package/types/__typetests__/roomOwnership.types.ts

@@ -0,0 +1,51 @@
+/**
+ * 방장 위임 · 위임 후 나가기 · 방 삭제 타입 — docs/chat.md 의 예제가 <b>실제로 컴파일되는지</b>.
+ *
+ * <p>jest 는 `.d.ts` 를 보지 않는다. 최상위 client 와 chat 양쪽에 같은 모양이 선언됐는지,
+ * leaveRoom 의 두 번째 인자가 선택인지(일반 참가자 기존 호출 유지), 새 이벤트가 구독 가능한지를 tsc 로 고정한다.</p>
+ *
+ * <p>실행: {@code npm run typecheck}</p>
+ */
+import TalkFlowClient, { RoomListEventType } from '../index';
+import type { ChatClient, ChatRoomResponse, LeaveRoomOptions, RoomListUpdateEvent } from '../index';
+
+declare const talkflow: TalkFlowClient;
+/** {@code talkflow.chat} 은 연결 전 null 이라 선언이 nullable 이다 — 연결된 chat 을 직접 받는 모양으로 본다. */
+declare const chat: ChatClient;
+declare const roomId: string;
+
+async function ownerExit(): Promise<void> {
+    // 일반 참가자 — 기존 호출 그대로
+    await talkflow.leaveRoom(roomId);
+    // 방장 — 위임 후 나가기
+    const options: LeaveRoomOptions = { newOwnerId: 'u2' };
+    await talkflow.leaveRoom(roomId, options);
+    await chat.leaveRoom(roomId, { newOwnerId: 'u2' });
+    // 방장 — 방 삭제
+    await talkflow.deleteRoom(roomId);
+    await chat.deleteRoom(roomId);
+}
+
+async function transfer(): Promise<ChatRoomResponse> {
+    const fromRoot: ChatRoomResponse = await talkflow.transferOwnership(roomId, 'u2');
+    void fromRoot;
+    return chat.transferOwnership(roomId, 'u2');
+}
+
+talkflow.on('roomListOwnerChanged', (event: RoomListUpdateEvent) => {
+    const previousOwner: string | undefined = event.actorId;
+    // docs/chat.md 예제 — members[0] 이 새 방장
+    const newOwnerId: string | undefined = event.members?.[0]?.userId;
+    const nickname: string | null | undefined = event.members?.[0]?.nickname;
+    const count: number | undefined = event.activeParticipantCount;
+    void [previousOwner, newOwnerId, nickname, count];
+});
+talkflow.on('roomListDeleted', (event: RoomListUpdateEvent) => {
+    const deletedRoom: string = event.roomId;
+    void deletedRoom;
+});
+
+const ownerChanged: 'ROOM_OWNER_CHANGED' = RoomListEventType.ROOM_OWNER_CHANGED;
+const deleted: 'ROOM_DELETED' = RoomListEventType.ROOM_DELETED;
+
+void [ownerExit, transfer, ownerChanged, deleted];

package/types/__typetests__/scheduleCard.types.ts

@@ -45,7 +45,23 @@ function names(card: ScheduleCard): string {
     return (card.participantNames ?? []).join(', ') + (card.title ?? '') + (card.whenText ?? '') + (card.location ?? '');
 }
 
-// 6) 알 수 없는 kind 문자열도 받아들인다(구버전 호환).
+// 6) 개설자는 선택 필드다 — 옛 카드엔 키가 없다. 있을 때만 초대 명단과 따로 그린다.
+//    승인 대기 카드의 확인 안내(organizerNotice)도 선택 필드다 — 있으면 카드 안에 그대로 그린다.
+function roles(card: ScheduleCard): string[] {
+    const lines: string[] = [];
+    if (card.organizerName) lines.push('개설: ' + card.organizerName);
+    const invitees = card.participantNames ?? [];
+    lines.push(invitees.length > 0 ? '초대: ' + invitees.join(', ') : '서비스 초대 없음 · 방 구성원 공개');
+    if (card.kind === 'PROPOSED' && card.organizerNotice) lines.push(card.organizerNotice);
+    return lines;
+}
+const legacy: ScheduleCard = { proposalId: 'p-0', kind: 'PROPOSED', visibilityNotice: '이 방 구성원에게 공개되는 일정입니다' };
+const withOrganizer: ScheduleCard = {
+    ...legacy, organizerName: '이승주', participantNames: ['김홍섭'],
+    organizerNotice: '같은 이름의 다른 직원이 있습니다. 개설자 외 초대 명단을 확인해 주세요.',
+};
+
+// 7) 알 수 없는 kind 문자열도 받아들인다(구버전 호환).
 const future: ScheduleCard = { proposalId: 'p-1', kind: 'SOMETHING_NEW', visibilityNotice: '이 방 구성원에게 공개되는 일정입니다' };
 
-export { maybeCard, notice, headline, names, future };
+export { maybeCard, notice, headline, names, roles, legacy, withOrganizer, future };

package/types/__typetests__/videoAnalysis.types.ts

@@ -0,0 +1,131 @@
+/**
+ * 영상 분석 타입 — docs/video-analysis.md 의 예제가 <b>실제로 컴파일되는지</b>.
+ *
+ * <p>jest 는 `.d.ts` 를 보지 않는다. 문서가 약속한 모양(멱등키 필수 · 대상 두 종류 · 종료 판정은 status ·
+ * 시각은 문자열 · 취소 응답에는 결과가 없음 · 진행 단계 VIDEO_ANALYSIS)이 선언과 맞는지 여기서 tsc 로 고정한다.</p>
+ *
+ * <p>실행: {@code npm run typecheck}</p>
+ */
+import TalkFlowClient from '../index';
+import type {
+    AssistantProgressEvent,
+    ChatMessage,
+    VideoAnalysisCancellation,
+    VideoAnalysisCapabilities,
+    VideoAnalysisJob,
+    VideoAnalysisRequest,
+    VideoAnalysisSource,
+    VideoAsset,
+} from '../index';
+
+declare const talkflow: TalkFlowClient;
+declare const file: File;
+declare const roomId: string;
+declare const personaId: string;
+declare const message: ChatMessage;
+declare const idempotencyKey: string;
+
+// 1) 사용 가능 여부와 한도 — 화면은 이 응답의 숫자를 쓴다.
+async function gate(): Promise<boolean> {
+    const caps: VideoAnalysisCapabilities = await talkflow.getVideoAnalysisCapabilities();
+    const limits: number[] = [caps.maxSources, caps.maxBytesPerSource, caps.maxTotalDurationMs, caps.framesPerSecond];
+    const formats: string[] = caps.mimeTypes;
+    void [limits, formats, caps.model];
+    return caps.available && caps.standaloneUploadConfigured;
+}
+
+// 2) 업로드 — 진행률은 객체 하나, 만료 시각은 문자열(ISO-8601)이다.
+async function upload(controller: AbortController): Promise<VideoAsset> {
+    const asset = await talkflow.uploadVideoAsset(file, {
+        onProgress: ({ loaded, total, percent }) => { void [loaded, total, percent]; },
+        signal: controller.signal,
+    });
+    const expiresAt: string = asset.expiresAt;
+    const lengthMs: number = asset.durationMs;
+    void [expiresAt, lengthMs, asset.fileName, asset.mimeType, asset.sizeBytes];
+    return asset;
+}
+
+// 3) 대상은 두 종류다 — 업로드 자산과 채팅 첨부. 구간은 선택이다.
+const uploaded: VideoAnalysisSource = { type: 'UPLOADED_ASSET', assetId: 'asset-1' };
+const attachment: VideoAnalysisSource = {
+    type: 'CHAT_ATTACHMENT',
+    roomId,
+    messageId: message.messageId,
+    attachmentId: message.fileMetaDataList?.[0]?.fileId ?? '',
+    startMs: 10_000,
+    endMs: 30_000,
+};
+// @ts-expect-error 채팅 첨부는 방·메시지·첨부 ID 가 모두 있어야 한다
+const incompleteAttachment: VideoAnalysisSource = { type: 'CHAT_ATTACHMENT', roomId };
+// @ts-expect-error 외부 URL 은 대상이 될 수 없다
+const external: VideoAnalysisSource = { type: 'URL', url: 'https://example.com/video.mp4' };
+void [incompleteAttachment, external];
+
+// 4) 접수는 멱등키가 필수다 — 비공개 분석과 방 게시 분석 모두.
+const analysis: VideoAnalysisRequest = { instruction: '요약해 주세요.', locale: 'ko-KR', sources: [uploaded] };
+const privateJob: Promise<VideoAnalysisJob> = talkflow.analyzeVideo(analysis, { idempotencyKey });
+const roomJob: Promise<VideoAnalysisJob> = talkflow.analyzeVideoWithAssistant(roomId, {
+    personaId,
+    triggerMessageId: message.messageId,
+    analysis: { instruction: '이 구간의 발언을 요약해 주세요.', sources: [attachment] },
+}, { idempotencyKey });
+// @ts-expect-error 키 없이 접수할 수 없다
+talkflow.analyzeVideo(analysis);
+// @ts-expect-error 방 게시 분석도 키가 필수다
+talkflow.analyzeVideoWithAssistant(roomId, { personaId, triggerMessageId: message.messageId, analysis });
+void [privateJob, roomJob];
+
+// 5) 종료는 status 로 판정한다 — 값이 늘면 이 switch 가 컴파일되지 않는다.
+function isTerminal(job: VideoAnalysisJob): boolean {
+    switch (job.status) {
+        case 'QUEUED':
+        case 'RUNNING':
+            return false;
+        case 'SUCCEEDED':
+        case 'FAILED':
+        case 'CANCELLED':
+            return true;
+        default: {
+            const unreachable: never = job.status;
+            return unreachable;
+        }
+    }
+}
+
+// 6) 결과는 성공일 때만 있고, 근거 시각은 없을 수 있다(둘 다 null). 시각 필드는 숫자가 아니다.
+function render(job: VideoAnalysisJob): string[] {
+    const createdAt: string = job.createdAt;
+    const deadline: number = Date.parse(job.deadlineAt);
+    // @ts-expect-error createdAt 은 epoch millis 가 아니라 ISO-8601 문자열이다
+    const wrong: number = job.createdAt;
+    void [createdAt, deadline, wrong, job.detail, job.errorCode, job.resultMessageId, job.deliveryPending];
+    if (job.result === null) return [];
+    const known = new Set(job.sources.map((source) => source.sourceId));
+    return job.result.evidence
+        .filter((evidence) => known.has(evidence.sourceId))
+        .map((evidence) => {
+            const range = evidence.startMs === null || evidence.endMs === null
+                ? '(시각 미상)'
+                : `${evidence.startMs}–${evidence.endMs}`;
+            const modality: 'VISUAL' | 'AUDIO' | 'BOTH' = evidence.modality;
+            return `${evidence.sourceId} ${range} ${modality} ${evidence.observation}`;
+        });
+}
+
+// 7) 취소 응답에는 상태만 있다 — 결과는 getVideoAnalysis 로 읽는다.
+async function cancel(jobId: string): Promise<boolean> {
+    const cancelled: VideoAnalysisCancellation = await talkflow.cancelVideoAnalysis(jobId);
+    // @ts-expect-error 취소 응답은 결과를 담지 않는다
+    void cancelled.result;
+    const latest: VideoAnalysisJob = await talkflow.getVideoAnalysis(jobId);
+    void [cancelled.deliveryPending, latest];
+    return cancelled.status === 'CANCELLED';
+}
+
+// 8) 진행 단계에 VIDEO_ANALYSIS 가 있다 — phase 를 직접 분기하는 화면이 쓸 수 있어야 한다.
+function isVideoAnalysis(event: AssistantProgressEvent): boolean {
+    return event.active && event.phase === 'VIDEO_ANALYSIS';
+}
+
+void [gate, upload, isTerminal, render, cancel, isVideoAnalysis];