LLM 어댑터 계층: 단일 시도, 명시적 재시도, 이중 스트림 영속화

먼저 해보고 말할게요. 왼쪽은 와이어의 SSE 청크(provider가 프레임마다 내보내는 원본), 오른쪽은 세션 로그(청크마다 바로 assistant/chunk, 스트림이 끝나면 파생 assistant/message), 위는 사용자가 보는 UI예요. 시나리오 셋: A는 깨끗한 이중 스트림 저장; B는 중간에 끊겨 재시도가 타임라인에 명시 이벤트로 뜨는 모습; C는 반면교사—SDK 조용한 재시도, 같은 고장인데 로그에 흔적이 없음.

먼저 규칙을 세워요. DSH 어댑터 계약은 단호해요: 어댑터 호출 한 번이 제공자 시도 한 번이고, 라이브러리 내장 재시도는 반드시 꺼야 합니다(docs/subsystems/llm-streaming.zh.md 어댑터 계약 절). HTTP 라이브러리는 조용히 재시도해 주려 하죠—친절해 보이지만 정보를 숨깁니다. 왜 느렸는지, 몇 번 재시도했는지, 매번 왜 실패했는지 전부 내부 루프에 사라져요. DSH는 그 층을 벗겨요. 어댑터는 한 일만 합니다: 요청 한 번 보내고, 응답을 통일 StreamChunk로 내보내며, 실패면 직렬화 가능한 LlmFailure(안정적 error code)로 정규화. 그 외는 관여하지 않아요.

행 방지도 이 층에서 해결해요. 출시된 원격 어댑터 둘 다 streamIdleTimeoutMs 워치독(기본 5분)을 달고, provider가 멈추면 TIMEOUT으로 매핑합니다. 놓치기 쉬운 한 줄: 빈 응답은 오류예요. 내용 블록 없는 stop은 조용한 성공이 아니라 EMPTY_RESPONSE로 매핑해야 재시도 층이 살릴 기회가 생깁니다.

이제 저장을 봐요. agent loop가 청크 스트림을 소비할 때 두 일을 합니다: 청크마다 그대로 assistant/chunk를 세션 로그에 붙이고, 동시에 BlockAssembler에 넣어요. 스트림이 깨끗이 끝나면 조립 결과를 assistant/message로 한 번 더 씁니다. 이게 이중 스트림이에요. 청크 스트림은 원본 녹화—리플레이 테스트가 프레임마다 그때 응답을 재구성하고; 메시지 스트림은 파생 이력—다음 요청의 대화 컨텍스트가 여기서 나옵니다. reasoning 블록과 text 블록은 청크 프로토콜에서 타입이 달라 각자 조립·저장돼요.

      const assembler = new BlockAssembler()
      const chunkSeqs: number[] = []
      const stream = preparedCall?.stream(request) ?? this.loopCtx.llm.stream(request)
      signal.throwIfAborted()
      for await (const chunk of stream) {
        signal.throwIfAborted()
        chunkSeqs.push(this.session.append('assistant/chunk', { turn, step, chunk }).seq)
        assembler.push(chunk)
      }

이 아홉 줄이 이중 스트림의 심장이에요. 먼저 저장, 그다음 조립, 청크 예외 없음. 스트림이 끝나면 갈라져요: finish가 오류/중단이면 실패를 agent/request-error에 넘겨 재시도 여부를 정하고(354–371행); 성공일 때만 381행에서 assistant/message를 붙이며 이 배치의 청크 seq를 sourceEventSeqs에 적어 어디서 파생됐는지 표시합니다. 실패한 반쪽 출력의 귀착지가 분명해요: 청크 스트림에 증거로 남고, 파생 이력에는 절대 안 들어갑니다. 다음 요청이 컨텍스트를 재구성할 때 그 반쪽은 없었던 일이에요.

조립기 자체도 잠깐 멈춰 볼 만해요. BlockAssembler는 저장소 유일의 청크 접기 구현이라, 어댑터는 index대로 올바른 청크만 내면 되고 블록 재조립은 각자 안 짜도 됩니다. 기형 스트림에는 단호해요: block-end를 처리할 때 이미 닫힌 블록이면 바로 return하고 뒤따르는 중복 닫기는 무시합니다. 주석에선 “First close wins”라 불러요—첫 닫힘만 유효해야 스트리밍 출력과 최종 조립 블록이 일치하니까요. 이 방어 한 줄이 바로 property test가 실제 버그를 잡은 자리예요(복기: 비결정적 시스템 테스트하기).

출처:packages/llm/llm/src/assembler.ts block-end 분기 75–82행, 확인일 2026-08-13.

재시도는 한 층 위에 살아요. dsh-llm-retry 플러그인이 agent/request-error를 듣고, provider 라우트 등록 때 잡은 정책으로 살릴지 정합니다. 기본 normal 정책: EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT 다섯 code만, 최대 두 번, 백오프 500ms–10s에 10% 지터; provider의 유효 Retry-After는 로컬 백오프를 대체해요(packages/llm/llm-retry/README.zh.md).

핵심은 기장 방식이에요. 백오프 대기 전에 플러그인이 세션 로그에 llm/retry를 붙입니다—재시도 id, 제공자, 정책 mode, 전체 실패 정보, 계획 지연; 백오프가 끝나 실제로 쏘면 llm/retry-started를 또 붙어요. 둘 다 모델 가시 표면에는 안 들어가서 모델은 재시도를 모릅니다. 하지만 UI와 사후 분석은 여기에 기대요: UI가 실패한 반쪽 출력을 거두고 “1/2회 재시도, 3초 후”를 보여 주고; 디버깅할 때 시도마다·대기마다 타임스탬프가 있습니다. 재시도 자체는 새 번호 Turn을 열어 영속 이력에서 같은 요청을 재구성해 보내고, 옛 Turn 기록은 한 글자도 안 고칩니다.

어댑터 간 디테일 하나: replayState. 성공 finish 청크는 어댑터 전용 리플레이 상태(예: DeepSeek 추론의 네이티브 표현)를 실어 assistant/message와 함께 저장할 수 있어요. 다음 요청이 이력을 어댑터에 주기 전 LlmRuntime.forAdapter()가 메시지마다 검사합니다: 이력 provider와 대상 provider가 같은 어댑터 인스턴스일 때만 상태를 넘기고; 어댑터를 바꾸면 상태를 벗겨 제공자 무관 내용만 줍니다(packages/llm/llm/src/index.ts 822–836행). 한집 비공개 데이터는 다른 집에 안 먹입니다.