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이 작성했습니다

[lidge-jun]

Maintainer integration record — audio stack lane, merged by @lidge-jun.

This pull request is a non-tip link in the audio stack (#4391 → #4392 → #4395). Its head carries [skip ci], so its own ci aggregate check never ran.

• CI evidence: the stack tip feat(dashboard): add dictation and live voice API controls #4395 at ec9e3734e80a32e2b60d7ace89d23de94fae0123 passed Cross-platform CI run https://github.com/lidge-jun/opencodex/actions/runs/34731037202 (conclusion success). The stack is cumulative, so this branch's content is a strict subset of what that run executed.
• Tip-only CI for this batch is an explicit repository-owner decision. MAINTAINERS.md otherwise requires a successful per-PR CI check before merge, so this is a recorded deviation rather than something the maintainer-integration clause grants on its own.
• Review state: no outstanding maintainer change requests.
• Security review: not applicable — no authentication, credential, OAuth, workflow, release-automation, or dependency-installation surface.
• Local verification on the lane: typecheck, structure:check, privacy:scan passed; focused tests passed on the files each link touches. No local full-suite run was used as evidence.

Squashing with --match-head-commit pinned to the SHA above, and with a squash message that does not carry [skip ci] so the dev-branch regression run still fires.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-13T02:00:53.733642Z	0a17011	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0a170112fc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Normalize the keyed transcription base URL

When the built-in openai-apikey provider uses the already-supported trailing-slash spelling https://api.openai.com/v1/, this constructs https://api.openai.com/v1//audio/transcriptions. That is a distinct path which the upstream need not normalize and may reject with 404; build the endpoint with the same URL normalization used by the Responses and Images transports.

AGENTS.md reference: src/AGENTS.md:L10-L10

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Preserve configured headers for keyed transcription

For an OpenAI API-key provider with configured non-secret headers, such as OpenAI-Organization or OpenAI-Project, resolveAudioUpstream includes those headers in relay.headers, but this allowlist silently discards them. Such requests can be routed to the wrong project or rejected; preserve the trusted provider headers on the keyed branch while retaining the narrow allowlist for caller-derived ChatGPT forwarding.

AGENTS.md reference: src/AGENTS.md:L10-L10

Useful? React with 👍 / 👎.