연결 대기를 영상과 겹친다
영상 종료 뒤의 방 접속·Agent 준비 대기를 앞당긴다. 첫 응답 생성·음성 재생 시간까지 없어지는 것은 아니다.
PPI · SESSION LIFECYCLE · CHANGE IMPACT ANALYSIS
첫 영상 동안 AI를 준비하면
전환 대기를 줄일 수 있을까?
마지막 업데이트 2026-10-02
현재 구조를 기준으로 본 AI 세션 사전 생성의 수정 범위와 예상 부작용
01 · 판단
가능하다. 다만 연결 준비와 대화 시작을 나눠야 한다.
최신 요구 반영 · 최소 수정 + 기존 동작 보존. 첫 적용은 LiveKit이며 첫 full:video 뒤 같은 활동에 AI 스텝이 있는 경우로 좁히는 안을 권장한다. 기존 연결 생성·Agent ready·입출력 차단·재시도를 재사용하고, 준비 모드와 현재 활동의 준비 시도 소유권만 보강한다. 전체 세션 구조 개편이나 새 모니터 UI는 이번 최소안에 포함하지 않는다.
현재도 같은 활동에서 AI → 영상 → AI로 이동하면 AI 연결을 유지한다. 이 유지 구조를 첫 영상에도 확장할 수 있다. 핵심 변경은 “AI가 준비됨”과 “지금 대화해도 됨”을 별도로 관리하는 것이다.
프런트 중심의 수명주기 변경
전환 훅, AI 세션 시작·정지, 입력/출력 차단, 준비 상태와 첫 발화 계약을 함께 바꿔야 한다.
영상 중 AI가 작동하는 것
첫 인사·마이크·자동응답이 조기에 활성화되거나, 준비 실패 알림이 영상 시청을 끊는 회귀를 막아야 한다.
분석 범위: 각 활동의 첫 스텝이
full:video인 경우. hybrid 영상은 현재도 AI가 필요한 split:video이므로 별도 분기다. 이미 진행 중인 활동의 재접속·영상 스텝 복귀는 후속 확장 여부를 결정해야 한다.요청한 산출물은 수정안과 영향 분석이다. 아래 After, 상태 모델, 테스트 수용 기준은 제안이며 구현 완료 상태가 아니다. PPI 애플리케이션 코드는 수정하지 않았다.
02 · 체감 흐름
영상이 끝났을 때 기다릴 일을 앞당긴다
Before · 현재
활동 시작 → 영상 재생
AI 세션 생성 안 함
AI 세션 생성 안 함
↓ 영상 종료 / AI 스텝 이동
AI 연결 생성 → Agent 준비 대기
↓
현재 AI 스텝의 첫 인사 → 대화
After · 권장
영상 재생은 그대로 진행
동시에 AI 연결 준비
입력 OFF · 응답 OFF · 출력 OFF
입력 OFF · 응답 OFF · 출력 OFF
↓ 영상 종료 / AI 스텝 이동
준비된 연결 활성화 → 첫 인사 → 대화
준비 중이면 같은 시도를 기다린다. 실패·만료·활동 불일치이면 정상 시작 경로로 복구한다.
효과의 상한: 연결 준비 시간 C, 준비와 겹친 영상 시간 V라면 남은 연결 대기는 대략
max(0, C − V). 여기에 활성화 처리와 첫 응답 생성·재생 시간이 남는다. 실제 수치는 미측정이며 영상 재생 성능과 함께 비교해야 한다.03 · 코드로 확인한 현재 구조
세션은 활동 단위, 대화 허용은 스텝 단위에 가깝다
| 경계 | 현재 동작 | 근거 |
|---|---|---|
| 수업 시작 허용 | 자료 준비·캐싱 상태를 통과해야 전환 훅이 동작한다. 시작 확인에서 resourcesReady를 내린다. 사전 생성도 이 입장 경계를 따라야 한다. | useStepTransition 연결 · L1700 confirmReady · L1798 |
| 스텝 종류 | full:ai · split:video · split:image만 세션이 필요하다. full:video · full:image는 대화 비활성 스텝이다. | stepRequiresSession · L21 |
| 새 활동의 첫 영상 | 기존 활성 세션을 정리하고 응답 차단만 켠다. AI 세션은 시작하지 않는다. | 새 활동 분기 · L107 |
| 영상 → 첫 AI | 같은 활동이어도 활성 세션이 없으면 handleStartSession을 호출한다. 이 시점에 연결 대기가 발생한다. | 같은 활동 분기 · L147 |
| 이미 연결된 AI → 영상 → AI | 영상에서는 세션 유지 + 응답 차단 + AI 마이크 OFF + 응답 취소. AI 복귀에서는 종료 조건·startMent·마이크 의도를 복원한다. | 활성 세션 재사용 · L171 비 AI 스텝 처리 · L193 |
| 연결 생성 | startSession은 세대 번호와 abort를 관리하며 활동/스텝·첫 인사·자동 종료 설정, 미디어와 실제 연결을 준비한다. 단순 데이터 프리패치 함수가 아니다. | startSession · L1639 |
| LiveKit 준비 완료 | 브라우저 연결 후 waitUntilAgentReady를 기다리고 handleSendAutoStartMessage를 호출한 뒤 active를 켠다. | Agent 준비와 첫 발화 · L2483 |
| 첫 인사와 후속 멘트 | 첫 인사는 별도 once 플래그를 사용한다. 기존 활성 세션의 updateStartMent는 멘트가 있을 때만 보낸다. 두 경로가 동일하지 않다. | handleSendAutoStartMessage · L1336 updateStartMent · L2815 |
수업 식별자, 활동 ID, 실제 음성 연결의 voiceSessionId는 구분해야 한다. 준비한 연결은 같은 수업·같은 활동·같은 시작 시도에만 재사용하고, 화면의 현재 스텝은 계속 영상으로 유지한다.
04 · 권장 수정안
최소안: 기존 시작 함수에 준비 모드를 더하고 한 번만 활성화
기존 stepRequiresSession에 full:video를 추가하는 방식은 영상까지 AI 스텝으로 취급하게 된다. AI가 필요한 스텝 판정은 유지하고, 별도의 “연결을 미리 준비할 조건”을 둔다.
| 설계 항목 | 권장 동작 |
|---|---|
| 대상 판정 | 수업 시작 경계를 지난 뒤 각 활동의 첫 full:video에서 시작한다. 권장 최적화는 같은 활동 뒤쪽에 AI 필요 스텝이 있을 때만 준비하는 것. 영상만 있는 활동까지 무조건 생성할지는 정책 결정 사항이다. |
| 준비와 활성화 분리 | 기존 startSession에 준비 목적을 전달하고, 기존 연결을 활성화하는 작은 진입점을 두는 안부터 검토한다. 새 서비스나 세션 관리 계층을 만드는 것은 요구하지 않는다. 개념상 prepare / activate의 책임을 구분하되 실제 함수명은 구현 시 결정한다. 준비는 transport·Agent readiness까지만, 첫 인사·자동 종료·대화 입력은 활성화에서 처리한다. |
| 상태 분리 | 검증 모델은 idle → preparing → prepared → activating → active와 실패/만료/취소다. 이를 그대로 큰 상태 머신으로 구현할 필요는 없다. 기존 abort·generation·ready Promise를 재사용하고, 준비 시도 핸들과 활성화 여부를 명확하게 둔다. isSessionActive의 기존 소비자 의미를 보존한다. |
| 같은 시도 합류 | 수업 ID + 활동 ID + 연결 세대에 대한 준비 Promise/핸들을 소유한다. 짧은 영상 종료나 중복 effect가 같은 시도를 재시작하지 않고 합류한다. 이미 활성화한 연결에 첫 인사를 다시 보내지 않는다. |
| 준비 중 침묵 계약 | AI 송신 입력, 서버 음성 응답 생성, 로컬 AI 출력 세 경계를 모두 차단한다. AUTO_START와 수동·호스트 텍스트도 준비 중 보내지 않도록 별도 차단한다. 듣기 의도는 보존하되 첫 응답 fallback 타이머·설정 변경·재접속이 준비 상태를 해제하지 못하게 한다. |
| 활성화 순서 | 현재 활동/세대 및 연결 건전성 확인 → 실제 목적 AI 스텝의 설정·로그 stepIndex 적용 → 응답 허용 → 첫 인사 exactly-once → 기존 듣기 복원 정책 적용. 미리 예상한 “다음 스텝”의 설정을 고정하지 않는다. |
| 실패와 종료 | 준비 실패는 영상 재생에 영향 없이 기록한다. AI 진입 시 정상 시작/기존 재시도 경로로 복구한다. 활동 변경·종료·강제 퇴장에서는 생성 중 시도까지 취소하고 늦게 도착한 연결도 닫는다. |
| 최초 적용 범위 | 실제 사용 런타임을 로그로 확인하고 LiveKit부터 제한 적용하는 안을 권장한다. Realtime/TTS 분기는 별도 시작·차단 계약을 검증한 뒤 확장한다. |
기존 부품을 재사용하는 구체적인 방법
- 준비 시도 ref는 활동·세대·진행 Promise·활성화 여부를 소유한다. 기존 AbortController, liveKitSessionRef, readiness retry를 재사용하고 별도 연결 관리자나 중복 connected 상태는 추가하지 않는 안을 우선한다.
- 입력은 기존
transition_blocked_changed정책을 재사용한다. 새 입력 reducer를 만들기보다 시작 초기화 직후, 연결·게시 전에 차단을 적용하고 모든 재시도에 유지한다. 이 방식으로 보장되면 듣기 제어 파일 수정은 줄일 수 있다. - 영상 자동전환 helper 전체를 호출하면 종료 멘트·취소 부수 동작도 함께 실행되므로 필요한 차단 정책만 재사용한다. 서버
enterNonAiStep는 Agent가 없으면 반환할 수 있어 ready 이후 적용 완료까지 확인한다. 활성화에서는 닫아 둔 서버 입력·응답 설정도 복원하고 적용을 확인한다. 그동안 로컬 마이크는 기존 첫 응답 대기 정책으로 유지한다. 텍스트는 이 입력 gate와 독립이므로 별도 송신 차단을 해제한다. - 준비 완료를 public active로 알리지 않아도 진행자 듣기 snapshot은 시작 의도를 바꿀 수 있다. 따라서 active=false만 믿지 않고 transition block이 듣기 OFF→ON보다 우선함을 검증한다.
근거: 대기 중 voice control snapshot · L307 / non-AI RPC 준비 조건 · L4090.
토큰만 미리 받는 대안: 웹 API 처리 일부는 줄일 수 있지만 LiveKit 방 접속·Agent 준비 대기를 충분히 숨기지 못한다. 반대로 실제 연결까지 준비하면 자원 점유·수명 소모·미디어 영향이 생긴다. 이번 목적에 맞는 권장 수준은 실제 연결과 Agent readiness까지이며, 첫 응답은 생성하지 않는다.
05 · 수정 범위
핵심 수정 후보 3개, 나머지는 검증 후 필요한 경우만
우선 use-step-transition.ts, use-ai-session.ts, use-listening-control.ts에 범위를 잡는다. 정확한 파일 수는 보호 테스트로 결정한다. 파일 수를 맞추기 위해 다른 경로의 초기화·정리 결함을 숨기지는 않는다.
| 범위 | 대상 경로 / 책임 | 변경 내용 |
|---|---|---|
| 필수 | apps/web/entities/guest-page-session/model/use-step-transition.ts | 첫 영상 준비 호출, 준비 중 합류, 준비된 연결 활성화, 기존 AI·이미지·hybrid 분기 유지. effect cleanup의 aborted만으로 하위 생성 취소가 되는지 함께 정리. |
| 필수 | apps/web/entities/guest-session/model/use-ai-session.ts | StartSessionParams의 준비 모드 또는 별도 준비 API, 단계 상태·소유권·취소 계약, 첫 인사 지연, 목적 스텝 적용, 조용한 준비 실패, 실제 활성화에서 기존 시작 정책 실행. |
| 필수 검증 / 필요한 최소 보완 | apps/web/entities/guest-session/model/use-listening-control.tsapps/web/entities/guest-session/lib/ 입력 정책·시작 관련 모듈 | 시작 초기화가 non-AI 차단을 보존하도록 한다. configured 듣기 의도와 effective 입력, fallback 타이머, 재시도·재연결의 준비 모드를 일관되게 유지. |
| 호환성 검증 / 필요할 때만 수정 | apps/web/entities/guest-page-session/model/use-guest-page-session.ts 및 이를 소비하는 게스트·모니터 상태 | 준비 단계는 기존 대화 활성 상태로 노출하지 않는 안을 우선한다. 생성 중·준비 완료 자원은 내부에서 정리 대상으로 추적한다. 자동 듣기 복구·텍스트 입력·아바타·RTC 표시의 기존 의미가 보존되면 페이지·모니터 UI 코드는 수정하지 않는다. |
| 조건부 | apps/web/lib/voice-agent/livekit-client-session.ts 및 연결 관련 하위 모듈 | 현재 publication gate와 responseBlocked 전달을 재사용할 수 있는지 검증한다. readiness와 준비 상태를 유지할 수 없거나 재접속이 해제하면 보완. |
| 조건부 | apps/web/app/api/livekit/call/route.tsapps/web/lib/voice-agent/livekit-token.tsapps/livekit-agent/agent.py | 기존 계약으로 무음 준비가 입증되면 서버 기능 변경을 최소화한다. 초기 입력/응답 차단을 서버가 명시적으로 알아야 하거나 준비 단계의 readiness·취소 계약이 부족하면 descriptor/config/RPC를 확장. |
| 런타임 확장 시 | apps/web/lib/openai-create-call.ts 등 direct Realtime/TTS 경로 | 초기 VAD 자동응답, data channel 준비, TTS 플레이어 출력·부수 이벤트, 런타임별 “준비 완료” 정의 검증. |
| 테스트·관측 | 전환 훅 테스트, 세션 시작/준비 통합 fixture, 입력 gate·종료 테스트, 관련 UI Storybook | 상태 경쟁과 영상 중 무음 계약을 먼저 보호한다. UI 상태 변경 시 실제 backend·socket·device 없는 story와 관련 정적 빌드 검증이 필요하다. |
기본 최소안에서는 서버 API·Agent·DB·화면 레이아웃·Realtime/TTS 경로를 확장하지 않고 기존 계약으로 검증한다. 미지원 런타임은 현재 방식으로 시작한다. 서버 수정이 필요하다는 증거가 나오면 조건부 범위와 안전성 근거를 다시 평가한다. 위 목록은 수정 후보와 책임 경계다. 조사 단계에서 변경 파일 수나 공수를 확정하지 않는다. DB 스키마·콘텐츠 스텝 형식 변경을 기본 전제로 삼을 필요는 없다.
06 · 예상 문제점
위험은 첫 인사뿐 아니라 준비 실패와 수명까지 연결된다
| 우선순위 | 발생 조건 → 예상 영향 | 방어와 확인 기준 |
|---|---|---|
| 높음 | 일반 startSession을 영상에서 호출 → 자동 첫 인사, 자동응답 또는 내부 대화 이력 선행 | 준비 모드에서 첫 메시지 전송·응답 생성 자체를 금지한다. 소리만 음소거해서는 이력·종료 조건·비용을 막을 수 없다. |
| 높음 | 입력 정책 초기화·5초 첫 응답 fallback·재접속 → 영상 중 AI 입력이 열릴 가능성 | 준비 상태를 입력 허용의 독립 조건으로 유지. 물리 마이크와 AI 송신 분기를 구분하고, 영상 5초 이후·설정 ON/OFF·재접속 모두 검증. |
| 높음 | 미리 첫 인사를 생략하고 기존 active 분기로 복귀 → startMent 없는 첫 AI가 침묵하거나 초기 안내 누락 | 준비 연결의 첫 활성화는 기존 “중간 스텝의 멘트 갱신”과 구분한다. startMent 유무와 자동전환 설정을 모두 테스트. |
| 높음 | 영상이 짧거나 운영자가 빨리 넘김 → 준비 중 새 startSession이 이전 시도를 abort하고 다시 생성 | 같은 시도 Promise 합류, 활성화 요청 보관, 응답 exactly-once. 연결·방 중복 생성과 지연 악화를 측정. |
| 높음 | 준비 중 다른 활동·수업 종료·강제 퇴장 → 늦은 준비 완료가 이전 활동 세션을 남김 | 활성 세션뿐 아니라 생성 중 시도까지 cancel. 활동/세대 재확인 후 late result 연결도 종료. |
| 높음 | 준비 호출 실패 → 기존 alert/throw가 영상 시청을 방해 | 백그라운드 준비는 조용히 실패 기록. 실제 AI 진입 시 정해진 재시도와 안내. 영상은 계속 재생. |
| 중간~높음 | 긴 영상·일시정지 → 준비 중 Agent 수명 소모, AI 진입 전에 만료 가능 | 현재 기본 job 수명 20분은 엔트리 진입부터 계산한다. 배포 환경 override 확인, 잔여 수명 확인 및 필요 시 재생성. 즉시 무한 재시작 금지. |
| 중간 | 영상 전용 활동·활동 건너뛰기 → 쓰지 않는 방/Agent 점유 | 후속 AI 존재 조건, 동시 준비 1개, 이탈 시 정리. 활성 job 수·Agent 분당 점유·미사용 준비 비율을 비교. 구체적 과금액은 미산정. |
| 중간 | 영상 다운로드·디코딩과 AI 접속/오디오 처리 병행 → 저성능 iPad에서 끊김·음량 변화 가능 | 영상 loopback·공유 AudioContext·모니터 송출/녹음 경로를 함께 검증. 실제 기기 성능 영향은 정적 코드로 확정할 수 없다. |
| 중간 | isSessionActive를 준비 상태에도 사용 → 진행자 상태 표시·아바타·자동 듣기 복구 의미 변화 | 연결 가능과 대화 허용을 구분해 소비 지점 점검. 실제 스텝은 계속 영상으로 publish하며 준비를 AI 활동 시작으로 알리지 않는다. |
| 중간 | video → video/image → AI 또는 운영자 jump → 예상한 다음 스텝과 실제 목적 스텝 불일치 | 같은 활동 연결만 재사용하고 현재 목적 스텝에서 startMent/autoFinish/입력 설정 적용. 비 AI 스텝에서는 계속 침묵. |
| 중간 | LiveKit만 기준으로 구현 후 Realtime/TTS로 라우팅 → 준비 계약 누락 | 해결된 runtime별 allowlist 또는 각 런타임별 contract test. 지원하지 않는 모드는 현재 lazy start를 유지하는 제한 적용안. |
| 추가 확인된 영향 | 근거와 대응 |
|---|---|
| 로그 스텝 오기록 | stepIndexRef는 시작 시점에 설정된다. 영상 0에서 준비하고 AI 1로 활성화할 때 이를 갱신하지 않으면 시작 메시지 등 텍스트 로그가 영상 스텝으로 저장될 수 있다. 시작 컨텍스트 · L1738 / 로그 stepIndex · L808 |
| 아동은 무음인데 진행자에게 AI 소리가 전달 | LiveKit 로컬 출력 차단과 원격 stream 전달은 별개다. Mediasoup AI 송출 분기도 검사해야 하며 실제 녹음 stem까지의 최종 유입은 추가 검증 사항이다. remote stream callback · L3357 / AI 오디오 송출 · L918 |
| 같은 영상 수동 선택·재시작 | 준비를 active로 표현하면 같은 스텝 수동 선택이 일반 restart 경로를 열 수 있다. 영상 재시작 역시 준비 모드를 보존해야 한다. 같은 스텝 재시작 · L1433 / restartCurrentSession · L789 |
| Realtime 정지 경합 | setRemoteDescription 이후는 generation만 검사하고 stop은 signal을 abort한다. await 도중 stop-only가 발생하면 active로 되돌아갈 여지가 보인다. 정적 분석상 후보이며 실제 재현하지 않았다. 연결 후 검사 · L2537 / stop abort · L1525 |
| 준비 취소 시 영상 AudioContext 손상 | iOS 영상 loopback은 공유 AudioContext와 연결된 미디어 소스를 사용한다. 준비 취소/재시도에서 공유 context를 닫거나 대체하지 않는지 확인해야 한다. 영상 오디오 소스 수명 · L194 |
마이크에 대한 정확한 범위: 현재 페이지는 자료 캐싱 이후 로컬 미디어를 준비해 AI 세션에 전달한다. 따라서 이 변경이 항상 새로운 권한 팝업을 만든다는 뜻은 아니다. 위험은 기존 소스를 더 일찍 처리·게시하거나 AI 입력 경로를 열어버리는 데 있다. 모니터링용 원본 마이크를 일괄 정지하는 방식도 피해야 한다. 기존 모니터링·녹음·외부 STT 정책은 별도로 유지하며, 위 “전사 없음”은 준비된 AI 세션의 대화 전사에 관한 제안이다.
07 · 입력·출력 경계
세 개의 경로를 구분해 검증한다
| 경로 | 준비 중 의도 | 독립 검증 지점 |
|---|---|---|
| 콘텐츠 영상 → 영상 플레이어/loopback → 아동 스피커 | 정상 재생 지속 | video playing/ended와 실제 가청성. AI 연결 이벤트는 영상 재생 증거가 아니다. |
| 아동 마이크 → AI 전용 입력 분기 → LiveKit/Realtime Agent | AI 입력은 OFF, 사용자의 듣기 의도는 보존 | publication gate 및 서버 입력 수신. 모니터/녹음 분기까지 함께 끊지 않는지 확인. |
| Agent 응답 → 원격 오디오/TTS → AI 오디오 요소 → 스피커 | 생성·출력 모두 OFF | 준비된 AI 세션의 응답 생성/대화 전사/자동종료 이벤트 0, 로컬 AI 재생 0. remote track 구독만으로 준비 완료 후 가청성까지 증명되지 않는다. |
기존 응답 차단, non-AI 입력 정책, full-video 전환 잠금은 재사용할 보호 장치다. 하지만 새 세션 시작에서 ref나 policy가 초기화되므로 “미리 차단 함수를 한 번 호출”하는 것으로 충분한지는 별도 검증이 필요하다.
08 · 구현 전후 검증
우선 보호할 수용 기준
| 시나리오 | 통과 기준 |
|---|---|
| 첫 영상 → AI · 준비 완료 | 영상 중 첫 인사·AI 입력·응답 및 준비된 AI 세션의 대화 전사·TTS·autoFinish 없음. 같은 voiceSessionId 재사용, 목적 스텝 첫 인사 1회. |
| 짧은 영상 / 수동 빠른 이동 | 준비 시도를 한 번만 생성하고 기다린다. 재시작 경쟁·중복 발화 없음. |
| startMent 있음 / 없음 | 둘 다 현재 정상 첫 AI 진입과 같은 시작 의미를 유지. 기본 시작 메시지·한국어 첫발화 지시 누락 없음. |
| 준비 중 수동/호스트 텍스트 입력 | AI 텍스트 요청과 응답 생성이 발생하지 않음. 영상 종료 뒤 입력·메시지 재처리 정책을 명시하고 몰아서 자동 발화하지 않음. |
| 자동전환 ON/OFF · 듣기 ON/OFF | 각 기존 정책을 유지. 준비 때문에 사용자 의도가 바뀌거나 타이머가 입력을 해제하지 않음. |
| 영상 5초 이상 / 긴 일시정지 | fallback 이후도 입력·응답 차단. 만료는 감지하고 AI 진입 시 유효한 연결만 사용. |
| video → video/image → AI / jump | 비 AI 구간은 계속 침묵. 실제 목적 스텝의 종료 조건·멘트 적용. |
| 활동 A 준비 중 B 이동 / 수업 종료 / force kick | A의 생성 시도·재시도·연결을 폐기. 늦은 완료가 B를 덮어쓰지 않음. |
| 준비 API 실패 / Agent ready timeout / reconnect | 영상은 중단·실패 alert 없이 계속. AI 진입에서는 복구 또는 정상 오류 안내. 고아 job 잔존 점검. |
| 영상 전용 활동 | 제안한 후속 AI 조건을 채택하면 준비 호출 0. 무조건 생성 정책을 택하면 미사용 비용/정리 검증. |
| 기존 AI 첫 스텝 / hybrid / full:image | 기존 동작 보존. 첫 이미지까지 무단 확장하지 않음. |
| iPad Safari · 저전력 · PC | 영상 음량·끊김·첫 AI 음성·입력 복원 확인. host monitoring·녹음도 별도 확인. |
| 런타임별 LiveKit / Realtime / TTS | 지원 범위별 준비·침묵·활성화·종료 계약을 검증하고 제외 모드는 lazy start 유지. |
텍스트는 별도 차단이 필요하다. 현재 Agent 텍스트 입력 경로는 microphone gate와 독립이며, response_generation_enabled 확인 없이 generate_reply를 호출한다. 따라서 서버 음성 응답 설정 OFF만으로 AUTO_START·수동/호스트 텍스트까지 막힌다고 가정하지 않는다. 준비 중 송신을 차단하고, 필요하다면 서버 활성화 상태 검증도 추가한다. 텍스트 입력 경로 · L4711 / generate_reply 호출 · L4741
최소안에서 반드시 통과할 회귀 기준
① 영상·음량·진행자 청취·녹음 정책 유지 ② 준비 중 AI 입력·발화·메시지 전송 0 ③ 영상→AI에서 기존 첫 인사/듣기 정책과 정확한 스텝 로그 ④ 준비 중 이동·종료에서 자원 정리 ⑤ 준비 실패 시 영상 지속 및 정상 AI 시작 복구. 이 다섯 조건이 빠지면 작은 diff라도 최소 안전안으로 보지 않는다.
보장할 수 있는 범위: 기존 사용자 동작의 회귀를 막는 것을 목표로 한다. 실제 AI 연결을 더 일찍 생성하면 Agent 점유 시간과 Job 수명 소모는 늘어난다. 이 변화 자체를 0으로 만들면서 연결 준비 지연을 앞당길 수는 없다. 기능 회귀와 의도된 추가 자원 사용을 따로 측정한다.
관측과 단계 적용
기존 Step transition trace, AI session start trace, readiness 재시도 로그에 prepare_started / prepare_ready / activate_requested / activate_done / prepare_cancelled / fallback_started 같은 단계(제안)를 연결한다. 수업·활동·voiceSessionId·generation·시도 원인을 함께 남긴다.
비교 지표는 영상 종료→첫 AI 가청 시간(p50/p95), 연결 재사용률, 준비 완료 전 전환율, 준비 실패/만료율, 영상 stall, 미사용 Agent 점유, 영상 중 잘못 생성된 응답 수다. 성공 목표 수치는 baseline 측정 후 정한다. 제한 세션에서 시작하고 기존 lazy start로 되돌릴 기능 플래그를 둔다.
이번 조사에서 실행한 기존 테스트: 51개 통과.
apps/web에서 관련 Vitest 8개 파일·30개 테스트와 readiness retry 21개 테스트를 실행했다. 자동 시작 보조 로직, 듣기 정책, 만료 분기, 생성 보조 함수, retry 세대를 확인하는 기존 baseline이다. 사전 생성 기능의 통합 동작이나 위 수용 기준을 검증한 결과는 아니다.
실행 명령과 검증 범위
pnpm exec vitest run entities/guest-page-session/model/use-step-transition.test.ts entities/guest-page-session/model/use-step-transition.expiry.test.tsx entities/guest-session/lib/auto-start-message.test.ts entities/guest-session/lib/session-start entities/guest-session/model/use-listening-control.test.tsx
8 files / 30 tests PASS · 1.11초. 이어서 pnpm exec tsx --test lib/voice-agent/livekit-readiness-retry.test.ts → 21 tests PASS. retry 테스트는 node:test 파일이므로 최초 Vitest 시도의 러너 불일치를 바로잡아 실행했다. 제품 실패는 관찰되지 않았다.
새로운 prepare→activate 통합 시나리오, 운영 연결·실기기 재생·지연 측정은 미실행. 기존 테스트 파일 존재나 통과를 새 기능의 안전성 보증으로 해석하지 않는다.
09 · 근거와 미확정 항목
현재 소스 근거와 구현 시 확인할 것
| 확인한 사실 | 코드 근거 | 의미 / 한계 |
|---|---|---|
| LiveKit descriptor는 연결 완료가 아니다 | call route · L177 join token dispatch · L89 | JWT에 Agent dispatch를 담는다. 실제 접속 후 준비 handshake까지 기다려야 한다. |
| Agent ready는 초기화·제어 경로 준비 | entrypoint · L5257 verified session start · L1021 | ASR server 분기는 prepare 후 session을 시작한다. HC/VP 세부 경로와 첫 가청 시간은 별도 검증한다. |
| 서버 greeting은 현재 꺼져 있다 | greeting_enabled · L210 | 브라우저 AUTO_START는 별도다. greeting=false만으로 준비 중 모든 응답을 막지 못한다. |
| 입력·응답·텍스트 경계가 다르다 | input gate · L12 non-AI RPC · L4382 | Agent 초기 입력/응답 허용값은 true이나 브라우저 publication gate는 기본 닫힘이다. 응답 초기값 · L1726. 기존 코드에서 입력이 샌다는 확정이 아니라 준비 정책 검증 필요성을 뜻한다. |
| 브라우저 publication gate를 재사용 가능 | local publication gate · L611 시작 정책 초기화 · L881 | processor 준비와 정책 적용 전에는 닫힌다. 준비 상태가 초기화·재연결·듣기 설정으로 풀리지 않아야 한다. |
| 첫 응답용 입력 지연은 영상 잠금이 아니다 | deferred mic fallback · L556 | 5초 fallback이 있다. 긴 첫 영상에 이 타이머만 사용하면 안 된다. |
| 로컬 출력과 SFU 출력이 분기된다 | 로컬 attach gate · L3284 Mediasoup로 전달 · L1225 | 로컬 mute에 더해 응답 생성·AI 대화 전사·모니터/녹음 경로를 검증한다. |
| 전사 필터는 다른 차단 ref를 사용 | assistant filter · L22 user filter · L18 | responseBlocked만 설정해 전사·autoFinish·TTS가 모두 막힌다고 가정할 수 없다. |
| 기본 Job 20분 / 워커 최대 2 Job | job lifetime · L12 worker load · L356 | 기본값이며 배포 override 미조회. 준비 시작은 수명과 동시성 예산을 사용한다. 영상 중 오래 대기하면 남은 대화 시간이 줄어든다. |
| JWT 2400초 / config 7200초 | token TTL · L17 config TTL · L5 | Job 20분과 다른 제한이다. 토큰 만료 시각을 이미 연결된 세션의 강제 종료 시각으로 해석하지 않는다. |
| 준비 재시도에도 기존 제약 필요 | call retry · L22 readiness retry · L2865 | 불확실한 POST를 임의로 반복하지 않는다. 준비 모드는 stop에 의한 차단 ref 초기화 뒤에도 유지해야 한다. |
| Realtime/TTS 초기 출력 경로는 다르다 | Realtime ontrack · L65 TTS playback · L553 | 초기 unmute/play 경로까지 준비 상태를 반영하거나 최초 적용 범위를 제한한다. Direct Realtime 기본 create_response:true도 별도 검증한다. Realtime 초기 VAD · L66. |
아직 확인하지 않은 것: 운영 runtime 분포와 배포 환경의 job 수명 override, 실제 cold-start 지연, 영상 길이·중도 이탈 분포, 영상과 병행했을 때 기기 부하, 유휴 Agent의 실제 사용량·비용, 장시간 준비 상태에서 외부 provider 연결의 유지 특성. 본 문서는 운영 로그·실기기 실험 없이 현재 소스와 제한된 기존 테스트에 근거한 분석이다.
관련 문서
LLM용 복사 · 분석 맥락
목표: 활동 첫 full:video에서 AI 연결을 사전 생성해 영상→AI 연결 대기를 줄인다. 코드 수정 없이 구조·수정 범위·부작용 분석. 기준 develop 0f94a87a, 2026-10-02. 현재 useStepTransition은 새 활동 비AI 스텝에서 응답 차단만 켜고 세션 시작 안 함. 같은 활동 기존 세션은 영상 중 유지한다. 제안: 준비/활성화 분리, 활동 단위 단일 준비 시도 합류, 입력/응답/출력 차단, 실제 AI 진입에서 목적 스텝 설정과 첫 인사 1회. startSession은 미디어·첫 인사·active 설정·실패 alert 부작용이 있어 그대로 호출 불가. Agent job 기본 20분 수명도 준비 중 소모. 미사용 준비·기기 부하·실패 격리·종료 경쟁 검증 필요. 준비 API와 상태 이름은 제안이며 아직 미구현이다.