fix(voice/#602): migrate OpenAIRealtimeAgentAdapter to GA Realtime wire protocol

[drewdrewthis]

What & why

scenario.OpenAIRealtimeAgentAdapter (Python) spoke OpenAI's retired beta Realtime wire protocol, so every realtime run was server-closed at the handshake with 4000 / beta_api_shape_disabled. OpenAI removed the beta interface globally at GA (2026-05-12). This migrates the adapter to the GA wire protocol.

Fixes #602.

The fix — three coupled layers (Python-only)

The beta coupling was three layers deep; they move together (there is no working intermediate state — a header-only fix just surfaces the next-layer rejection):

1. Handshake — drop the OpenAI-Beta: realtime=v1 header (auth-only Authorization: Bearer).
2. session.update — GA shape: session.type="realtime"; audio nested under session.audio.{input,output}; formats as objects ({"type":"audio/pcm","rate":24000}); voice / transcription / turn_detection relocated under session.audio.
3. recv_audio — branch on the GA response.output_audio.* event names, defensively accepting the legacy response.audio.* names with a one-time warning (live gpt-realtime* models have been reported still emitting the beta names despite the GA docs).

Module + class docstrings updated to GA.

Out of scope (confirmed in the issue's Investigation): ephemeral client-secret minting; the TypeScript adapter; Realtime/transcription model renames.

Tests

• New regression guard test_openai_realtime_adapter_uses_ga_wire_protocol_not_beta — verified RED against the beta code and GREEN post-fix; runs in CI with no live key. Closes the coverage gap that let the regression ship (the previous unit test asserted the beta shape and stayed green while prod was 100% broken).
• Defensive-legacy test (decodes the legacy name + asserts the one-time warning fires exactly once across repeats).
• interrupt() → response.cancel; send → input_audio_buffer.commit → response.create round-trip; GA transcript observability (last_agent_transcript / last_user_transcript).
• Removed stale stub-era drift from the realtime e2e tests (*_e2e.py carried a dead PendingTransportError probe + a "transport not yet shipped" docstring — misleading on the very adapter this PR fixes; they're now honest live, key-gated GA-handshake checks, still integration-marked → deselected in PR CI, run nightly).
• specs/openai-realtime-ga-migration.feature — 15 scenarios mapping all 7 ACs, now bound 1:1 to tests: split the AC4 transcript test into agent-side + user-side; added the previously-unbound AC7 docstring-drift guard and a tools/instructions top-level placement test; corrected two @integration→@unit tags (their tests are mocked, no-key) and a tool_choice over-spec. Every @unit scenario has a test; @e2e/@integration are live-gated.
• python/tests/voice/test_adapters.py: 60 passed (17 realtime); pyright: 0 errors.

Review

Multi-agent /review (principles, hygiene, test, security): zero must-fix, security clean. Should-fix items addressed in this PR (test dedup, AC5 commit-sub-path coverage, hygiene conventions); minor nice-to-haves deferred with rationale.

Scope verified (post-review diligence)

• TS adapter is genuinely unaffected — @openai/agents moved its Realtime transport to the GA interface at 0.1.0 (2025-08-28); the repo pins ^0.3.3 (and demo ^0.3.9), both well past the cutover, and its event handler already uses the GA response.output_audio.* names. No TS-side beta-header fix needed.
• Model names are valid GA — gpt-realtime-mini and gpt-4o-transcribe are both current OpenAI models, so the live handshake won't fail on model-not-found.

✅ Caveat cleared — live GA handshake verified (2026-06-04)

The original 4000 / beta_api_shape_disabled close is gone. A live, key-gated @e2e GA realtime run was executed against the real OpenAI Realtime API (model gpt-realtime-mini) and reproduced 4×, each time negotiating cleanly and closing normally — never 4000. Wire-level evidence (websockets DEBUG):

> GET /v1/realtime?model=gpt-realtime-mini HTTP/1.1
> Authorization: Bearer sk-proj-…        # auth-only — no OpenAI-Beta header
< HTTP/1.1 101 Switching Protocols
= connection is OPEN                       # handshake ACCEPTED (beta era: server-closed here)
> TEXT {"type":"session.update", …}       # GA session shape
< TEXT {"type":"session.created", …}
< TEXT {"type":"session.updated", …}       # GA session.update accepted, no error event
… input_audio_buffer.append → .commit → response.create …
< TEXT {"type":"response.output_audio.delta", …}   # GA event name (legacy-compat arm never fired)
> CLOSE 1000 (OK)  /  < CLOSE 1000 (OK)    # normal client-initiated close — NOT 4000
result.success = True

No 4000, no beta_api_shape_disabled, no "type":"error" frame anywhere in the captured stream. test_demo_openai_realtime_agent_e2e_success → PASSED.

Lower-confidence GA details (Investigation §6) — now confirmed live:

• session.audio.output.format carrying rate ({"type":"audio/pcm","rate":24000}) is accepted — server returned session.updated with no error.
• No output_modalities issue surfaced; the current session shape negotiated successfully.

Scope note: only the AGENT (direct-to-model) role opens a live socket and was verified live. The USER-role e2e (test_openai_realtime_user_e2e) sys.exit(0)s at a pre-existing phase-2 skip-guard (introduced in #355, predates this PR) before any socket opens — it shows as FAILED in the raw run but is unrelated to this handshake and to the GA migration.

🤖 Generated with Claude Code

[github-actions]

Automated low-risk assessment

This PR was evaluated against the repository's Low-Risk Pull Requests procedure and does not qualify as low risk.

The PR changes the OpenAIRealtimeAgentAdapter’s behavior in its integration with the OpenAI Realtime API (handshake headers, session.update payload shape, and event/event-name handling), which is a third-party integration and therefore excluded from the low-risk category. Although it includes tests and doc updates, the changes alter the external API protocol the code speaks and thus do not meet the policy for automatic low-risk merging.

This PR requires a manual review before merging.

[drewdrewthis]

✅ prove-it re-run on HEAD 3dfab94 — 7/7 ACs PASS.

Adapter source is unchanged since the prior clean marker (81b7a4c); the intervening commits were test/spec only (AC4 transcript test split, AC7 docstring-drift guard, two @integration→@unit tag fixes, tool_choice over-spec fix, tools/instructions placement test) — coverage improved, behavior identical. test_adapters.py 60 passed, pyright 0, all PR checks green on 3dfab94. Residual (unchanged): AC1 live @e2e handshake needs OPENAI_API_KEY.

[drewdrewthis]

Test requirement before merge (per this PR's own caveat — recording it here so it isn't lost):

The unit/integration layer is fully proven (60 passed, falsification-tested regression guard test_openai_realtime_adapter_uses_ga_wire_protocol_not_beta runs no-key in CI). But the original 4000 / beta_api_shape_disabled close cannot be reproduced offline, so the only proof the regression is actually gone is one live or recorded GA realtime run with OPENAI_API_KEY set:

• Run the @e2e realtime handshake scenario against a live gpt-realtime* model and confirm the session opens (no 4000 close).
• While doing so, confirm two lower-confidence GA details flagged in Realtime adapter sends retired OpenAI-Beta: realtime=v1 header → all realtime runs rejected (beta_api_shape_disabled) #602 Investigation §6: (1) whether session.audio.output.format must carry rate, and (2) the output_modalities field shape.

Until that live run is captured, this PR is unit-green but not e2e-verified.