PPI-1351 첫 영상 AI 세션 사전 준비 — 데이터 흐름과 prepare 상태

1. 코드 경로

2. 목적과 범위

• 문제: 지금은 영상이 끝나고 AI 스텝에 들어간 뒤에야 방 접속과 Agent 준비를 시작합니다. 그 대기 시간만큼 아동이 기다립니다.
• 효과의 상한: 연결 준비 시간 C, 겹친 영상 시간 V라면 남는 연결 대기는 대략 max(0, C − V)입니다. 첫 응답 생성과 재생 시간은 그대로 남습니다. 실측은 아직 하지 않았습니다.
• 최소안 범위: LiveKit 런타임만 지원합니다. 서버·Agent·Realtime/TTS·UI는 변경하지 않았고, 지원하지 않는 런타임은 기존 lazy start로 동작합니다.
• 롤백: URL ?aiPrepare=off 또는 localStorage aiPrepare=off로 바로 기존 동작으로 돌아갑니다.

3. 데이터 흐름 (순서대로)

① 새 활동 진입, 첫 스텝이 full:video
   use-step-transition.ts:111   이전 세션(활성/준비) 있으면 정지
   use-step-transition.ts:141   응답 차단 ON (영상 구간)
   use-step-transition.ts:149   판정: 새 활동 + full:video + 뒤에 AI 스텝 + 플래그 ON
   use-step-transition.ts:159   prepareSession() 호출, 결과를 기다리지 않음 → 영상은 그대로 재생
        │
        ▼
② 준비 시작
   use-ai-session.ts:3012       prepareSession: startSession({prepareOnly:true})
                                pendingPrepareRef = 진행 중 Promise (나중에 합류용)
   use-ai-session.ts:1685       preparedSessionRef = {활동ID, 세대, ready:false}
        │
        ▼
③ 런타임 확인 · 입력 차단
   use-ai-session.ts:1877       LiveKit이 아니면 조용히 중단 → AI 스텝에서 기존 시작
   use-ai-session.ts:1897       입력 정책 transition_blocked = true (연결·게시 전)
        │
        ▼
④ LiveKit 연결 · Agent 준비
   use-ai-session.ts:2501       5초 마이크 fallback 예약 안 함
   use-ai-session.ts:2528       waitUntilAgentReady()
   use-ai-session.ts:2564       ready:true → "session_prepared" 로그 후 return
                                (첫 인사 없음, active 아님)
        │   영상 재생 중:
        │   · 진행자/수동 텍스트 → :748 차단
        │   · Agent 응답 소리 → responseBlocked로 출력 차단
        │   · 연결 끊김/실패/ASR 실패 → :1741 준비 무효화
        ▼
⑤ 영상 종료 → 같은 활동 AI 스텝 진입
   use-step-transition.ts:170   응답 차단 OFF
   use-step-transition.ts:173   준비 진행 중이면 같은 시도에 합류해 대기
   use-step-transition.ts:179   응답 차단 OFF 재적용 (준비 실패 정리가 다시 걸었을 경우 대비)
                                듣기 의도가 있으면 마이크 예약 (첫 응답 뒤 켜짐)
   use-step-transition.ts:187   activatePreparedSession()
        │
        ▼
⑥ 활성화
   use-ai-session.ts:3059       재사용 판정: ready + 같은 활동 + 같은 세대 + 연결 있음
   use-ai-session.ts:3078       준비 표시 해제 → 목적 AI 스텝의 stepIndex·startMent·autoFinish 적용
   use-ai-session.ts:3085       입력 차단 해제 (실제 마이크는 첫 응답 뒤 열림)
   use-ai-session.ts:3089       첫 인사 1회 → active = true
        │
        ├─ 재사용 불가 → 기존 handleStartSession (현재와 같은 동작)
        ▼
⑦ 대화 진행 (기존 흐름과 동일)

정리 경로: 다른 활동 이동(:111) · 세션 정지(use-ai-session.ts:1510) · 언마운트
           → 준비 세션도 함께 닫힘

줄 번호는 커밋 cef0b7d7 기준입니다.

4. prepare 상태 정의

prepare 상태는 AI 연결과 Agent 준비는 끝났지만 대화는 아직 허용하지 않은 상태입니다. use-ai-session.ts의 ref 두 개로 표현합니다.

preparedSessionRef = {activityId, generation, ready}. 이 연결을 어느 활동의 몇 번째 시작 시도가 만들었는지 기록합니다.

전이

idle ──prepareSession()──▶ preparing ──Agent ready──▶ prepared ──activatePreparedSession()──▶ active

preparing·prepared → idle:
  실패 · 비LiveKit 런타임 · 연결 끊김/실패/ASR 실패 · 다른 활동 이동
  · 세션 정지 · 언마운트 · 일반 startSession 호출(새 시작이 덮어씀)

불변 조건 (preparing·prepared 공통)

1. AI 입력 차단 (transition_blocked = true)
2. AI 출력 차단 (responseBlocked = true)
3. 첫 인사·텍스트·스텝 멘트 미전송
4. 5초 마이크 fallback 미예약
5. isActive = false: 외부(진행자 화면, 재시작, 자동 듣기 복구)에는 세션이 없는 것으로 보입니다.
6. LiveKit 방과 Agent job은 실제로 살아 있습니다. worker 자리 1개와 job 수명을 사용합니다.

활성화 조건 (prepared → active)

ready === true, 같은 활동 ID, 같은 세대, LiveKit 세션 존재. 네 가지를 모두 만족해야 재사용하고, 하나라도 어긋나면 기존 방식으로 새로 시작합니다.

5. prepare 상태에서 막히는 것 · 그대로인 것

6. Agent 서버 영향 — worker와 job

worker는 만들어지지 않고, job은 prepare에서 만들어진다

prepare → startSession → /api/livekit/call
  → 토큰에 Agent dispatch 포함 (livekit-token.ts RoomAgentDispatch)
  → 브라우저 방 접속 → LiveKit 서버가 worker에 job 배정
  → ppi_agent 엔트리포인트 (agent.py:5257)
      · 첫 줄에서 job 수명 타이머 시작 (agent.py:5260, 기본 20분)
  → ready 신호 → waitUntilAgentReady 통과 → session_prepared

• worker: ECS 태스크에 항상 떠 있는 프로세스(cli.run_app)입니다. 수명 변화가 없습니다.
• job: 생성 시점이 “AI 스텝 진입”에서 “첫 영상 시작”으로 앞당겨집니다. 종료 시점(활동 이동이나 수업 종료로 방을 나갈 때)은 그대로라서, 존재 시간이 대략 영상 재생 시간만큼 늘어납니다.

job 수명 상한은 늘어나지 않는다

기존:  [영상 ─────][AI 대화 ──────────]
                   ↑ job 시작        ↑ 활동 종료 → job 종료
변경:  [영상 ─────][AI 대화 ──────────]
       ↑ job 시작                     ↑ 활동 종료 → job 종료

worker 자리 점유

worker A (최대 2 job, 부하 = active_jobs / 2 × 0.99)
  [job: 아동1 준비 중]  [빈 자리]   → 부하 0.495 → 새 job 받음
  [job: 아동1 준비 중]  [job: 아동2] → 부하 0.99  → 새 job 거부 → 다른 worker로

• 부하는 CPU가 아니라 실행 중인 job 수로 계산합니다(agent.py:367 _ppi_agent_load). 준비 중인 job도 그대로 1개로 셉니다.
• job 1개가 차도 worker는 계속 쓸 수 있습니다. 2개가 차면 새 job만 거부하고, 모든 worker가 가득 차면 “no worker available”로 배정이 늦어집니다.
• 아동 한 명이 동시에 쓰는 job은 여전히 최대 1개입니다. 새 활동에서 이전 job을 먼저 정리한 뒤 준비를 시작합니다. 달라지는 건 원래 0개였던 첫 영상 구간에도 1개를 쓴다는 점입니다.

worker를 늘려야 하나

• 원칙적으로는 불필요합니다. 최대 동시 job 수는 기존과 같이 수업 중인 아동 수를 넘지 않습니다. 평균 사용률이 계획치에 가까워질 뿐입니다.
• 필요한 경우: ECS 사전 확장 계획이 “아동 전원이 동시에 job을 쓰지는 않는다”는 여유율(예: 아동 수 × 0.7)을 두고 있다면 늘려야 합니다. 계획 로직은 PPI 저장소에 없어 확인하지 못했습니다.
• 확인 방법: 계획식에 여유율이 들어가 있는지 확인하고, 배포 후 피크 시간대 활성 job 수와 계획 용량, “no worker available”·배정 지연을 Grafana로 비교합니다. 부족하면 ?aiPrepare=off로 바로 되돌릴 수 있습니다.

7. 검증 · 리뷰 · 남은 위험

검증 (자동)

• 테스트 200개 통과: guest-page-session 107, ai-session 72, readiness retry 21. tsc는 기존 이미지 import 에러 1건 외 새 에러 없음. prettier 통과.
• 준비 세션 내부(use-ai-session)는 hook 테스트 harness가 없어 자동 검증하지 못했습니다.

리뷰에서 수정한 P1

• P1-1: AI 스텝에서 준비를 기다리는 중 준비가 실패하면, 실패 정리가 응답 차단을 다시 걸어 그 스텝 내내 AI 소리가 안 들릴 수 있었습니다. 대기 후 차단을 다시 해제하도록 고쳤고, 수정 전 코드에서 실패하는 회귀 테스트로 확인했습니다.
• P1-2: 영상 중 Agent나 방 연결이 끊겨도 세션 ref가 남아 있어 재사용될 수 있었습니다. onDisconnected·onFailed·onAsrStartFailed에서 준비를 무효화하고 AI 스텝에서 새로 시작하도록 고쳤습니다.

실기기 확인 필요 (미실행)

• 첫 영상→AI: 영상 중 AI 발화·입력 없음, AI 스텝 첫 인사 1회. 로그 first_video_prepare_requested → session_prepared → prepared_session_activated
• 짧은 영상·빠른 수동 이동: 준비 1회, 중복 발화 없음
• 준비 중 활동 이동·수업 종료·강제 퇴장: 방·job 잔존 없음
• iPad Safari: 영상 음량·끊김, 첫 AI 음성, 진행자 모니터 청취·녹음
• 전환 지연 baseline 대비 개선량 (영상 종료 → 첫 AI 가청 시간)