feat(audio): expose standalone transcription API

[lidge-jun]

Summary

• Add POST /v1/audio/transcriptions for external clients using an OpenCodex API key. ChatGPT Pool/Direct and the OpenAI API provider retain their separate upstream credentials; file uploads return JSON or plain transcript text.
• Bound upload/body/response lifetime, preserve cancellation and account ownership, and record one validated terminal outcome. Update protocol documentation and add focused regression coverage. Repair the pre-existing Cline client/writer layout seed mismatch required by the layout gate.
• Ordinary dependency chain: this PR targets dev; feat(audio): expose streaming dictation and owned live calls #4392 targets this branch, followed by feat(dashboard): add dictation and live voice API controls #4395. Leave the chain open for review; no native GitHub stack registration.
• Protocol reference: codex-lb transcription implementation. This is a Bun-native implementation using existing OpenCodex account helpers.

Verification

• bun test tests/server/audio-transcriptions.test.ts: 24 pass, 0 fail.
• bun run test:changed: 8,138 pass, 2 skip, 0 fail across 326 selected files; two additional probe-release regressions subsequently passed in the focused run.
• bun test tests/test-layout.test.ts tests/test-layout-tooling.test.ts: 17 pass, 0 fail.
• The results above are historical checks completed before the owner prohibited local execution. Typecheck, structure check and privacy scan also passed then. The attempted full local suite crashed in Bun; a later diagnostic was interrupted and stopped. No full local-suite pass is claimed, and no local product checks are running. Subsequent pushes use --no-verify and remote CI only.
• Exact parent-chain head 011f2dff5c in feat(audio): expose streaming dictation and owned live calls #4392, based on this PR's 71e22d967f, passed all 24 transcription cases and remote gates in run 34687731903. Unrelated journal-restore assertions remain red and are recorded separately per owner scope; this PR stays draft, without a whole-CI-green claim.
• This PR's own exact head 71e22d967ffafbd3492935c299623c9127eaf17b also passed all 24 transcription cases, endpoint cases and gates (1,979 dashboard tests) in run 34687369123. The screenshot/description gate is now successful after adding the artifact capture below.
• Actual curl against the built handler with a synthetic upstream: successful multipart 200, invalid key 401, unsupported model 400, exactly one upstream call; server and temporary homes were cleaned up.
• Inherited independent code review: all reported blocking findings resolved, final bounded verdict PASS. No actual OpenAI/ChatGPT transcription call or account-entitlement validation was run.

Checklist

Actual screenshot of this layer's own CI artifact (run 34687369123, merge d9771b3; GUI tree exactly matches 71e22d967f). This layer changes dashboard test fixtures and asset provenance only; audio controls belong to #4395. Synthetic management data only.

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

✅ READY

• all PR quality gates passed.

Hygiene

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

리뷰 · 우선순위 58 / 80

이 PR은 draft인 codex/audio-transcription에서 외부 클라이언트가 OpenCodex API 키로
POST /v1/audio/transcriptions를 호출해 파일 받아쓰기(transcription)를 쓰게 만드는
오디오 스택 wp1입니다. 지금 dev HEAD c27a4831a(#4377 캐시 증거 문서)에는
이 엔드포인트가 없어서 같은 경로가 일반 v1 가드에 걸려 404가 납니다. 이 브랜치는
src/server/audio-transcriptions.ts와 src/server/audio-upstream.ts를 새로 두고,
src/server/index.ts에서 admission·Origin·drain을 본문 읽기 전에 검사한 뒤
핸들러로 넘깁니다. ChatGPT 구독 쪽은 https://chatgpt.com/backend-api/transcribe로,
키드 OpenAI는 기존 sidecar가 고른 providerBaseUrl 아래 /audio/transcriptions로 보냅니다.
클라이언트의 OpenCodex 시크릿은 업스트림으로 넘기지 않고, multipart는 파일 25MB·본문 32MiB·
응답 2MiB로 잘라 읽으며, 업로드·전체 기한과 turn lease 취소를 이어서 정리합니다.

현재 dev가 막 올린 캐시 레인(#4338/#4340/#4347)이나 pinned-start 퇴역(#4343)과는
겹치지 않는 새 표면입니다. 대신 이미지/라이브와 같은 OpenAI sidecar 선택
(selectOpenAiImagesProvider)과 probe lease 해제 보강(openai-sidecar.ts)을
재사용합니다. 계획 문서(devlog/_plan/260912_audio_apis_stack/)에 따르면 다음
wp2 스트리밍·wp3 Connections UI가 이 브랜치를 베이스로 쌓이므로, 여기 계약이
흔들리면 스택 전체가 같이 흔들립니다. 테스트는 tests/server/audio-transcriptions.test.ts
중심으로 모의 업스트림·키·용량·Direct 치환을 잡고, Cline 레이아웃 seed 불일치는
레이아웃 게이트 때문에 같이 고쳤습니다(기능과는 별개).

원격 CI는 이 시각 기준 test 1/4·3/4·4/4가 실패했고, gates/hygiene/docker smoke 등은
통과 쪽입니다. PR 본문도 exact-head 원격 CI를 최종 게이트로 두고 draft를 유지한다고
명시했습니다. 실제 ChatGPT/OpenAI 받아쓰기 호출이나 계정 entitlement 검증은
합성 경로만이라 제품 확인은 아직 남은 상태입니다.

src/server/audio-transcriptions.ts (upstream.ok ? 502 : status) - 업스트림이 성공인데 응답 본문 상한에 걸려 early return하면 finally의 recordOutcome이 잠깐 심어 둔 502로 남을 수 있다. 의도된 실패 기록이어도, 성공 HTTP를 먼저 넣고 실패 분기에서만 덮는 편이 읽기 쉽다.
src/server/audio-transcriptions.ts handleAudioTranscriptions - 핸들러가 이미 200을 만든 뒤 req.signal/operation/deadline을 다시 보면, 늦은 abort가 성공 응답을 499/503/504로 바꿔 버릴 수 있다. live 쪽 관례와 맞추려면 성공 응답은 그대로 두고 로그만 남기는지 한 번 더 정하자.
src/server/audio-upstream.ts selectOpenAiImagesProvider - 오디오가 이미지 provider 선택기를 그대로 쓴다. 이름은 헷갈리고, 앞으로 이미지와 오디오 자격/계정 정책이 갈라지면 같이 깨진다. wp2 전에 오디오 전용 선택기나 공통 OpenAI sidecar 이름을 둘지 정하자.
src/server/index.ts POST /v1/audio/transcriptions - resolveAudioAdmission은 명시 키만 받고 루프백 자동 통과가 없다(계획과 일치). 로컬 curl 습관이 있는 기여자에게는 401이 갑자기 늘 수 있으니 Connections/문서 예제에 Bearer 키를 분명히 보여 줘야 한다.
원격 CI test shards - draft인데도 1/4·3/4·4/4 실패가 남아 있다. exact-head 통과 전에는 review-ready로 올리지 말자.

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

• wp2(codex/audio-streaming)·wp3를 이 브랜치에 계속 쌓을지, 아니면 wp1만 먼저 dev에 넣고 리베이스할지
• ChatGPT 구독 받아쓰기 entitlement를 머지 전에 실제 계정으로 한 번 스모크할지, 합성+CI만으로 충분할지
• selectOpenAiImagesProvider 재사용을 장기 계약으로 둘지, 오디오 전용 resolver로 바로 갈지
• Cline layout seed 수정만 따로 cherry-pick해 dev에 먼저 넣을지(레이아웃 노이즈 줄이기)

너의 추천
draft 유지. 실패한 원격 test shard 원인부터 고치고 exact-head CI가 초록이 된 뒤에만
review-ready를 검토하자. 코드 계약(admission 먼저, 본문 상한, proxy 시크릿 미전달,
Direct stored-main 치환)은 방향이 맞으니, 위 outcome/늦은-abort/이미지-선택기 네이밍만
정리한 뒤 wp2를 이어서 올리면 된다. 지금은 dev 캐시/업데이트 레인과 충돌하지 않으니
닫지 말고 스택 베이스로 남겨 두자.

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