feat: harden public OpenAI API contracts

backend/services/openai_realtime/bridge.py

@@ -34,6 +34,7 @@ from services.openai_realtime.events import (
     normalize_turn_detection,
     require_event,
 )
+from services.openai_realtime.schemas import SERVER_EVENT_TYPES
 from services.openai_realtime.session import OpenAIRealtimeSession
 from services.pipecat.turn_config import create_vad_params
 from services.realtime.protocol import PipelineProtocolRuntime
@@ -47,7 +48,10 @@ def _event_id() -> str:
 
 
 def _server_event(event_type: str, **payload: Any) -> dict[str, Any]:
-    return {"type": event_type, "event_id": _event_id(), **payload}
+    event = {"type": event_type, "event_id": _event_id(), **payload}
+    if event_type.startswith("x.interactive_media."):
+        event["version"] = "1"
+    return event
 
 
 def _decode_base64(value: object, *, param: str) -> bytes:
@@ -129,9 +133,13 @@ class OpenAIRealtimeInputProcessor(FrameProcessor):
                 ),
                 direction,
             )
+        client_event: dict[str, Any] | None = None
         try:
-            await self._bridge.handle_client_event(require_event(frame.message))
+            client_event = require_event(frame.message)
+            await self._bridge.handle_client_event(client_event)
         except RealtimeEventError as exc:
+            if exc.event_id is None and client_event is not None:
+                exc.event_id = str(client_event.get("event_id") or "") or None
             await self._bridge.emit(error_event(exc))
         except Exception as exc:  # noqa: BLE001 - event errors must stay connection-local
             client_event_id = (
@@ -682,10 +690,16 @@ class OpenAIRealtimeBridge:
 
     def translate_server_message(self, message: dict[str, Any]) -> list[dict[str, Any]]:
         message_type = str(message.get("type") or "")
-        if message_type == "error":
-            return [message]
+        if message_type in SERVER_EVENT_TYPES:
+            event = dict(message)
+            event.setdefault("event_id", _event_id())
+            if message_type.startswith("x.interactive_media."):
+                event["version"] = "1"
+            return [event]
         if "." in message_type:
-            return [message]
+            # Dotted wire events outside the documented subset must not leak
+            # through from a provider-specific adapter.
+            return []
         if message_type == "transcript":
             return self._translate_transcript(message)
         if message_type == "assistant-text-start":
@@ -903,7 +917,10 @@ class OpenAIRealtimeBridge:
                 "workflow-variables": "x.interactive_media.workflow.variables.updated",
                 "workflow-error": "x.interactive_media.workflow.error",
             }
-            return _server_event(names[kind], **{k: v for k, v in message.items() if k != "type"})
+            return _server_event(
+                names[kind],
+                **{k: v for k, v in message.items() if k != "type"},
+            )
         if kind in {"handoff-requested", "call-ended"}:
             if "handoff" not in self.session.capabilities:
                 return None
@@ -912,5 +929,8 @@ class OpenAIRealtimeBridge:
                 if kind == "handoff-requested"
                 else "x.interactive_media.call.ended"
             )
-            return _server_event(event_type, **{k: v for k, v in message.items() if k != "type"})
+            return _server_event(
+                event_type,
+                **{k: v for k, v in message.items() if k != "type"},
+            )
         return None

backend/services/openai_realtime/events.py

@@ -6,6 +6,9 @@ from dataclasses import dataclass
 from typing import Any
 from uuid import uuid4
 
+from pydantic import ValidationError
+from services.openai_realtime.schemas import REALTIME_CLIENT_EVENT_ADAPTER
+
 
 SUPPORTED_CLIENT_EVENTS = {
     "session.update",
@@ -51,7 +54,21 @@ def require_event(message: object) -> dict[str, Any]:
             param="type",
             event_id=str(message.get("event_id") or "") or None,
         )
-    return message
+    try:
+        validated = REALTIME_CLIENT_EVENT_ADAPTER.validate_python(message)
+    except ValidationError as exc:
+        first = exc.errors(include_url=False)[0]
+        location = list(first.get("loc") or [])
+        if location and location[0] == event_type:
+            location.pop(0)
+        param = ".".join(str(part) for part in location) or None
+        raise RealtimeEventError(
+            str(first.get("msg") or "Event does not match the schema"),
+            code="invalid_event",
+            param=param,
+            event_id=str(message.get("event_id") or "") or None,
+        ) from exc
+    return validated.model_dump(exclude_none=True)
 
 
 def assistant_id_from_model(model: object) -> str:

backend/services/openai_realtime/schemas.py

@@ -0,0 +1,236 @@
+"""Public Pydantic and JSON Schema contract for OpenAI Realtime subset v1."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal, get_args
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
+
+
+class _ExtensibleModel(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class RealtimeSessionRequest(_ExtensibleModel):
+    type: Literal["realtime"] | None = None
+    model: str
+    output_modalities: list[Literal["audio", "text"]] | None = None
+    audio: dict[str, Any] | None = None
+    turn_detection: dict[str, Any] | None = None
+    instructions: str | None = Field(
+        default=None,
+        description="Platform-owned in subset v1; requests containing it are rejected.",
+    )
+    voice: str | None = Field(
+        default=None,
+        description="Platform-owned in subset v1; requests containing it are rejected.",
+    )
+    tools: list[dict[str, Any]] | None = Field(
+        default=None,
+        description="Platform-owned in subset v1; requests containing it are rejected.",
+    )
+    tool_choice: Any | None = Field(
+        default=None,
+        description="Platform-owned in subset v1; requests containing it are rejected.",
+    )
+
+
+class RealtimeClientSecretRequest(_ExtensibleModel):
+    session: RealtimeSessionRequest
+
+
+RealtimeClientSecretBody = RealtimeClientSecretRequest | RealtimeSessionRequest
+
+
+class RealtimeClientSecretResponse(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        json_schema_extra={
+            "examples": [
+                {
+                    "value": "ek-rt-...",
+                    "expires_at": 1788739260,
+                    "session": {
+                        "type": "realtime",
+                        "model": "assistant:asst_xxx",
+                        "output_modalities": ["audio"],
+                    },
+                }
+            ]
+        },
+    )
+
+    value: str
+    expires_at: int
+    session: dict[str, Any]
+
+
+class _ClientEvent(_ExtensibleModel):
+    event_id: str | None = None
+
+
+class SessionUpdateEvent(_ClientEvent):
+    type: Literal["session.update"]
+    session: dict[str, Any]
+
+
+class ConversationItemCreateEvent(_ClientEvent):
+    type: Literal["conversation.item.create"]
+    item: dict[str, Any]
+    previous_item_id: str | None = None
+
+
+class ConversationItemTruncateEvent(_ClientEvent):
+    type: Literal["conversation.item.truncate"]
+    item_id: str
+    content_index: int = Field(default=0, ge=0)
+    audio_end_ms: int = Field(ge=0)
+
+
+class InputAudioBufferAppendEvent(_ClientEvent):
+    type: Literal["input_audio_buffer.append"]
+    audio: str
+
+
+class InputAudioBufferCommitEvent(_ClientEvent):
+    type: Literal["input_audio_buffer.commit"]
+
+
+class InputAudioBufferClearEvent(_ClientEvent):
+    type: Literal["input_audio_buffer.clear"]
+
+
+class OutputAudioBufferClearEvent(_ClientEvent):
+    type: Literal["output_audio_buffer.clear"]
+
+
+class ResponseCreateEvent(_ClientEvent):
+    type: Literal["response.create"]
+    response: dict[str, Any] | None = None
+
+
+class ResponseCancelEvent(_ClientEvent):
+    type: Literal["response.cancel"]
+    response_id: str | None = None
+
+
+class CapabilitiesUpdateEvent(_ClientEvent):
+    type: Literal["x.interactive_media.capabilities.update"]
+    version: Literal["1"]
+    capabilities: list[str]
+
+
+class SessionVariablesUpdateEvent(_ClientEvent):
+    type: Literal["x.interactive_media.session.variables.update"]
+    version: Literal["1"]
+    variables: dict[str, Any]
+
+
+RealtimeClientEvent = Annotated[
+    SessionUpdateEvent
+    | ConversationItemCreateEvent
+    | ConversationItemTruncateEvent
+    | InputAudioBufferAppendEvent
+    | InputAudioBufferCommitEvent
+    | InputAudioBufferClearEvent
+    | OutputAudioBufferClearEvent
+    | ResponseCreateEvent
+    | ResponseCancelEvent
+    | CapabilitiesUpdateEvent
+    | SessionVariablesUpdateEvent,
+    Field(discriminator="type"),
+]
+
+
+REALTIME_CLIENT_EVENT_ADAPTER = TypeAdapter(RealtimeClientEvent)
+
+
+RealtimeServerEventType = Literal[
+    "session.created",
+    "session.updated",
+    "conversation.item.added",
+    "conversation.item.done",
+    "conversation.item.truncated",
+    "conversation.item.input_audio_transcription.completed",
+    "input_audio_buffer.committed",
+    "input_audio_buffer.cleared",
+    "input_audio_buffer.speech_started",
+    "input_audio_buffer.speech_stopped",
+    "output_audio_buffer.cleared",
+    "response.created",
+    "response.output_item.added",
+    "response.output_item.done",
+    "response.content_part.added",
+    "response.content_part.done",
+    "response.output_text.delta",
+    "response.output_text.done",
+    "response.output_audio.delta",
+    "response.output_audio.done",
+    "response.output_audio_transcript.delta",
+    "response.output_audio_transcript.done",
+    "response.function_call_arguments.delta",
+    "response.function_call_arguments.done",
+    "response.done",
+    "error",
+    "x.interactive_media.capabilities.updated",
+    "x.interactive_media.session.variables.updated",
+    "x.interactive_media.workflow.node_active",
+    "x.interactive_media.workflow.event",
+    "x.interactive_media.workflow.variables.updated",
+    "x.interactive_media.workflow.error",
+    "x.interactive_media.call.handoff_requested",
+    "x.interactive_media.call.ended",
+]
+SERVER_EVENT_TYPES = get_args(RealtimeServerEventType)
+EXTENSION_SERVER_EVENT_TYPES = tuple(
+    event_type
+    for event_type in SERVER_EVENT_TYPES
+    if event_type.startswith("x.interactive_media.")
+)
+
+
+class RealtimeServerEvent(_ExtensibleModel):
+    type: RealtimeServerEventType
+    event_id: str
+
+
+def realtime_client_event_json_schema() -> dict[str, Any]:
+    schema = REALTIME_CLIENT_EVENT_ADAPTER.json_schema(
+        ref_template="#/$defs/{model}",
+    )
+    schema.update(
+        {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "$id": "https://interactive-media.local/schemas/realtime-client-events-v1.json",
+            "title": "Interactive Media OpenAI Realtime client events v1",
+        }
+    )
+    return schema
+
+
+def realtime_server_event_json_schema() -> dict[str, Any]:
+    schema = RealtimeServerEvent.model_json_schema()
+    schema.update(
+        {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "$id": "https://interactive-media.local/schemas/realtime-server-events-v1.json",
+            "title": "Interactive Media OpenAI Realtime server events v1",
+        }
+    )
+    schema["allOf"] = [
+        {
+            "if": {
+                "properties": {
+                    "type": {"enum": list(EXTENSION_SERVER_EVENT_TYPES)},
+                },
+                "required": ["type"],
+            },
+            "then": {
+                "properties": {
+                    "version": {"const": "1", "type": "string"},
+                },
+                "required": ["version"],
+            },
+        }
+    ]
+    return schema