fix(combo): fail over zero-output transport incompletes (carry of #3227)

[lidge-jun]

Summary

Carry of #3227 by @RHODIZSECURITY (commit cherry-picked onto current dev with author credit; the contributor branch is not pushable by maintainers).

Combo stream preflight only treated response.failed as a retryable zero-output terminal. An upstream answering HTTP 200 with a stream that ends as response.incomplete for a proxy-minted transport reason (adapter_eof, missing_terminal_event, upstream_stall_timeout) was accepted, so a combo with healthy backups never advanced. Those three reasons now count as retryable when no output has committed; semantic incompletes (max_output_tokens, content_filter) and any incomplete after output commit stay accepted. The failed attempt is recorded as a 502 in log/usage receipts, same as a zero-output response.failed.

Supersedes #3227 (landed via maintainer).

Verification

• bun test tests/combo-stream-preflight.test.ts tests/server-combo-failover-e2e.test.ts — 88 pass / 0 fail on the PR head and again after rebase onto dev. New unit cases: transport incomplete → retryable; semantic incomplete → accepted; transport incomplete after commit → accepted. New e2e: A ends adapter_eof before output, B wins, receipts assert 502 → 200.
• Reviewer confirmed the three reasons are minted proxy-side (bridge.ts, relay.ts, responses-terminal-repair.ts), not upstream semantics.
• bun run typecheck clean; bun run privacy:scan passed. Full suite deferred to CI (maintainer bypass).

Checklist

• Targets dev
• Author credit preserved
• Focused regression tests next to the existing combo preflight tests
• No GUI change; no docs-site change (failover contract unchanged for users)

[github-actions]

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

리뷰 · 우선순위 75 / 80

이 PR은 기여자 @RHODIZSECURITY 의 #3227을 메인테이너가 현재 dev 위에 체리픽으로 올린 캐리입니다. 이미 dev에 1c8278b4d 로 머지되어 있고, HEAD 7d25f9966 (package 2.40.0) 기준으로 src/server/responses/combo-stream-preflight.ts 와 테스트 두 파일에 그대로 들어가 있습니다. 기여자 원본 브랜치는 푸시가 안 되어 캐리로 올린 흐름이고, 원본 #3227은 landed-via-maintainer 로 닫혀 있습니다.

문제는 콤보(여러 백업 대상을 이어 쓰는 모드)의 스트림 사전점검(preflight)이 response.failed 만 재시도 가능한 제로 아웃풋 종료로 보던 점이었습니다. 업스트림이 HTTP 200으로 SSE를 열고, 출력을 하나도 안 낸 채 response.incomplete 로 끝나면, 예전 코드는 그 대상을 그대로 수락했습니다. 그래서 뒤에 건강한 백업이 있어도 콤보가 넘어가지 못했습니다. Claude 호환 스트리밍 경로에서 incomplete_details.reason = adapter_eof 로 재현된 구멍입니다.

고침은 좁습니다. 프록시가 직접 찍어 내는 전송(transport) incomplete 이유 세 개만 제로 아웃풋일 때 재시도로 바꿉니다: adapter_eof, missing_terminal_event, upstream_stall_timeout. 이 세 문자열은 bridge.ts / relay.ts / responses-terminal-repair.ts 에서 프록시 쪽이 민트하는 값이고, 업스트림 의미론이 아닙니다. max_output_tokens 나 content_filter 같은 의미(semantic) incomplete 는 다른 제공자가 고쳐 줄 수 없으니 예전처럼 수락합니다. 그리고 화면에 보이는 출력이나 툴 부작용이 한 번이라도 커밋되면, incomplete 이유가 전송용이어도 절대 다시 재생하지 않습니다. 실패한 시도는 로그/사용량 영수증에 502로 남기고, 다음 대상이 200으로 이기는 기존 response.failed 제로 아웃풋 경로와 같은 모양입니다.

테스트도 핵심만 잠급니다. 단위 테스트는 (1) 세 transport incomplete → kind failed + HTTP 502, (2) max_output_tokens → accepted, (3) 출력 델타 이후 adapter_eof → accepted 를 고정합니다. e2e는 A가 출력 전에 잘린 스트림을 내고 B가 이긴 뒤, 영수증 attempts 가 502 → 200 인지 확인합니다. types.ts/config.ts 분할 캠페인과 무관한 좁은 서버 버그 픽스라, 분할 때문에 닫을 대상이 아닙니다. 이미 머지된 캐리라 rebase 논의도 없습니다.

라인 27-31 RETRYABLE_ZERO_OUTPUT_INCOMPLETE_REASONS - 허용 목록이 세 개뿐입니다. 모르는 incomplete 이유를 재시도하지 않는 보수적 선택이고, 프록시 민트 지점과 일치합니다.
라인 33-42 retryableZeroOutputTerminal - response.failed 는 예전처럼 항상 재시도 후보, response.incomplete 는 이유 문자열이 목록에 있을 때만 후보입니다. 페이로드가 객체 아니면 바로 false.
라인 149-157 / 183-186 - 변수명을 failedPayload → retryableTerminalPayload 로 바꾸고, terminalStatus 가 failed 또는 incomplete 이고 출력이 아직 커밋되지 않았고 페이로드가 있을 때만 kind: failed + 502 봉투로 돌려줍니다. incomplete 를 수락하던 예전 분기가 여기서 막힙니다.
경로 failedTerminalResponse - incomplete 도 failed 와 같은 JSON 봉투(upstream_error / 502)로 바꿉니다. 콤보 분류기가 재시도할 수 있게 하려는 의도이고, 단위·e2e 영수증이 그 계약을 잠급니다.
잔여 관찰 - 허용 목록 밖 transport-ish 이유가 나중에 추가되면 또 구멍이 납니다. 지금은 민트 지점이 세 곳뿐이라 목록이 맞지만, 새 incomplete reason 을 프록시에 넣을 때는 이 Set 을 같이 봐야 합니다. 출력 커밋 이후 incomplete 는 의도적으로 수락이며, 클라이언트에 이미 보인 스트림을 다른 대상에서 다시 재생하지 않습니다.

메인테이너의 판단이 필요한 지점

• 이미 dev에 들어가 있으므로, 이 리뷰는 사후 기록입니다. 추가 핫픽스나 revert 필요가 있는지(체리픽 후 CI/도그푸드에서 이상 신호가 있었는지).
• 앞으로 프록시에 incomplete reason 을 더 넣을 때 이 Set 을 같은 PR에서 갱신하는 규칙을 문서/체크리스트에 적을지.
• 의미 incomplete(max_output_tokens/content_filter)를 절대 재시도하지 않는 정책을 그대로 둘지. 지금은 다른 제공자가 고쳐 줄 수 없다는 이유로 맞고, 바꾸면 중복 출력·잘못된 우회 위험이 큽니다.

너의 추천
추가 조치는 필요 없다. 코드는 이미 HEAD에 있고, #3227은 landed-via-maintainer 로 닫혀 있다. types/config 분할과 무관하며 중복 PR도 없다. 후속으로 할 일이 있다면, 새 proxy-minted incomplete reason 을 추가할 때 RETRYABLE_ZERO_OUTPUT_INCOMPLETE_REASONS 를 같은 커밋에서 갱신하라는 한 줄 규칙만 메인테이너 메모에 남기면 충분하다.

이 댓글은 grok-bot이 작성했습니다