음성 입력 정책 공통화 (agent-input-policy) — 코드레벨 동작 흐름 PPI-1165코드레벨

TL;DR한 장 요약

01왜 만들었나 — 첫 응답 중 열리던 귀

활동 전환 직후 예약된 마이크 ON이 AI 첫 응답 도중에 입력을 열어, VAD/STT가 AI 목소리를 아동 발화로 수집할 수 있었습니다.

1. use-step-transition.ts가 듣기 의도(configured 또는 진행자 부재 fallback)가 있으면 새 세션에 scheduleMicOnAfterFirstResponse()를 예약한다.
2. 첫 응답 경로가 AEC 안정화 300ms 뒤 applyDeferredListening() → applyListeningIntent()를 호출한다.
3. LiveKit gate는 이 의도를 즉시 actual input ON으로 환원한다. 반면 Realtime 경로에는 "끼어들기 OFF && AI 발화 중이면 열지 않는다"는 조건이 별도로 있었다.
4. 결과: 같은 상황에서 LiveKit만 첫 응답 중 입력이 열려, 진행자가 끼어들기를 껐는데도 AI가 자기 발화에 반응할 수 있었다 (2026-07-31 재현 사례).

02상태 · 이벤트 · 이펙트

정책은 상태 4개 + 파생값 1개, 이벤트 4종, 이펙트 1종으로 끝나는 순수 함수입니다. 타이머·트랙·RPC는 하나도 알지 못합니다.

// lib/voice-agent/agent-input-policy.ts
interface AgentInputPolicyState {
  listeningIntent: boolean;        // 진행자 '듣기' 의도 (configured + fallback 합산 결과)
  isAiSpeaking: boolean;           // AI 발화 중
  allowInterruptions: boolean;     // 끼어들기 허용
  aecBlocked: boolean;             // AEC 안정화 대기 등으로 차단
  effectiveInputEnabled: boolean;  // ← 파생값. 어댑터가 적용하는 유일한 결론
}

function resolveEffectiveInputEnabled(state) {
  return (
    state.listeningIntent &&
    !state.aecBlocked &&
    (!state.isAiSpeaking || state.allowInterruptions)
  );
}

// 이벤트 4종 → reduceAgentInputPolicy()
listening_intent_changed | ai_speaking_changed | allow_interruptions_changed | aec_blocked_changed

// 이펙트: 결론이 '바뀔 때만' 1종 발행 (같은 값이면 빈 배열 → 중복 RPC/게인 적용 없음)
{ type: "apply_effective_input", enabled: boolean }

보조 판정 두 개

• shouldHoldInputAfterAssistantAudio() — AI 오디오 종료 직후에도 끼어들기 OFF면 입력을 계속 닫아둘지. 첫 응답 대기 중인 의도(pendingFirstResponseListeningIntent)도 의도로 취급합니다. :25–39
• shouldDeferFirstResponseListeningRestore() — AEC 안정화가 남아 있고 위 hold가 참이면 첫 응답 복원을 미룹니다. :41–49

03진리표 — 첫 멘트는 특별하지 않다

04런타임 어댑터 — 결론을 적용만 한다

• LiveKit: 트랙을 mute하지 않고 agentInputGain만 0으로 내려 AI 입력만 차단하고 진행자 릴레이는 유지합니다. 게인 적용 → RPC 순서로 보내며, 최신 상태만 남게 coalescing합니다.
• Realtime · TTS: MediaStreamTrack.enabled를 토글하고, 끄는 방향일 때만 clearRealtimeInputBuffer로 이미 쌓인 입력 버퍼를 비웁니다(TTS도 Realtime 입력 연결을 재사용).
• gate 축소: livekit-input-gate.ts는 desired_input_changed·input_policy_changed를 정책에 위임하고, 자신은 speech_started/stopped · turn_pending/committed/dropped · disconnect만 처리합니다. livekit-input-gate.ts:110–210

05활동 전환 · 예약 마이크 ON 경로

활동이 바뀌면 세션이 새로 뜨므로, 의도 전달은 상위(page-session)가 하고 타이밍 판단은 정책이 합니다.

• use-step-transition.ts는 듣기 의도가 있을 때 정본 ref의 configured 값을 인자로 명시 전달합니다 (scheduleMicOnAfterFirstResponse({ configuredIntent })). 사본 ref를 읽지 않는 것이 PPI-1167의 교훈입니다.
• configured가 없고 fallback 의도만 있으면 restoreListening()으로 세션 gate를 먼저 열어 예약이 적용될 수 있게 합니다.
• 첫 응답이 제때 오지 않으면 5초 fallback(DEFER_MIC_FALLBACK_MS)이 AEC 차단을 풀고 적용합니다. 명시적으로 마이크를 끈 상태면 fallback은 건너뜁니다.
• 첫 응답 경로는 300ms(AEC_STABILIZATION_DELAY_MS) 뒤 aec_blocked_changed:false를 보내며, 이때도 열림 여부는 §03 진리표가 결정합니다.

06판별법 — 로그로 어디서 막혔는지 보기

함정 · 주의

• 의도 ≠ 실효: listeningIntent(진행자가 원한 상태)와 effectiveInputEnabled(지금 실제로 여는지)를 로그·payload에서 혼동하면 "켰는데 안 켜졌다"는 오진이 납니다. gate의 desiredInputEnabled가 의도 쪽입니다.
• 런타임별 분기 금지: conversationMode나 runtime으로 정책을 갈라놓지 않습니다. 차이는 어댑터 계층에서만 존재해야 합니다.
• AEC 차단은 최우선: 끼어들기 ON이어도 AEC 차단 중이면 열리지 않습니다. iPad 계열 에코 이슈 방어와 직결됩니다.
• raw publish race는 별개: LiveKit 오디오 프로세서 실패로 raw 트랙이 먼저 publish되면 게인이 raw 경로를 막지 못할 수 있습니다. PPI-1165 범위에서 제외된 별도 결함이므로 함께 진단하지 마세요.

파일 · 라인 레퍼런스

관련 문서

• LiveKit 음성 에이전트 흐름 & 두 SFU 구조 — §06에 이 정책의 요약
• PPI-1167 — 듣기 복원 실패와 presence race — 의도 이중 소스 결함
• 텍스팅 수업 진행자 부재 · presence fallback 설계 — fallback 의도의 출처
• 오디오 처리 체인 (gate·EQ·comp·limiter) — 정책이 조작하는 게인의 위치