Persist timestamped realtime frames before acknowledging completion (#61473)

## What changed

- Record voice transcripts as `frame` items with a `voice_transcript` channel for eligible threads, while retaining legacy transcript support and the existing app-server live and mixed timeline representation.
- Assign first-observed timestamps that never move backward, retain them through completion, and restore the clock floor from history and compaction checkpoints.
- Flush realtime records before completion notifications, including file and initial directory durability barriers for local rollouts.
- Generate a distinct default session ID for each new call, use the call ID when attaching to an existing call, and derive opening record IDs from session IDs.
- Add protocol types for turn-input acceptance and session-end input receipts, excluding those receipts from live notifications and mixed timelines. Update generated schemas and SDK types.

## Testing

Add coverage for frame serialization and required voice payloads, clock rollback and checkpoint restoration, durability barrier failures and retries, per-call session IDs, and persisted transcript availability immediately after completion.

GitOrigin-RevId: 3f6632b517d563861aee085b723475b8945c391c

codex-rs/protocol/src/realtime.rs

@@ -8,16 +8,38 @@ use ts_rs::TS;
 pub struct RealtimeItem {
     pub id: String,
     pub realtime_session_id: String,
+    /// Owner-assigned Unix milliseconds at first observation, retained when sealed.
+    /// Absent for history recorded before canonical observation times were introduced.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[ts(type = "number | null", optional)]
+    pub observed_at_ms: Option<i64>,
     #[serde(flatten)]
     pub content: RealtimeItemContent,
 }
 
+/// A frame holds one or more payloads, at most one per channel. They share one ID,
+/// observation time, and seal. V1 requires its only channel, `voice_transcript`.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, JsonSchema, TS)]
+pub struct RealtimeFrameChannels {
+    pub voice_transcript: RealtimeVoiceTranscript,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, JsonSchema, TS)]
+pub struct RealtimeVoiceTranscript {
+    pub role: RealtimeTranscriptRole,
+    pub text: String,
+}
+
 /// The minimum facts needed to interleave realtime speech and agent work.
 #[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, JsonSchema, TS)]
 #[serde(tag = "type", rename_all = "snake_case")]
 #[ts(tag = "type", rename_all = "snake_case")]
 pub enum RealtimeItemContent {
     RealtimeSessionStarted,
+    Frame {
+        channels: RealtimeFrameChannels,
+    },
+    /// Original rollout spelling, retained for older histories and unenrolled writers.
     TranscriptSegment {
         role: RealtimeTranscriptRole,
         text: String,
@@ -30,6 +52,31 @@ pub enum RealtimeItemContent {
     RealtimeSessionClosed {
         outcome: RealtimeSessionOutcome,
     },
+    /// Durable acceptance of the exact bounded input used by an agent turn.
+    /// The enclosing item ID is the acceptance identity; source IDs never use
+    /// provisional rollout ordinals.
+    TurnInputAccepted {
+        handoff_id: String,
+        turn_id: String,
+        mode: RealtimeHandoffMode,
+        source_event_ids: Vec<String>,
+        input_item_id: String,
+        input: String,
+    },
+    /// End-of-call input recorded in model history without starting or steering a turn.
+    SessionEndInputSaved {
+        source_event_ids: Vec<String>,
+        input_item_id: String,
+        input: String,
+    },
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize, JsonSchema, TS)]
+#[serde(rename_all = "snake_case")]
+#[ts(rename_all = "snake_case")]
+pub enum RealtimeHandoffMode {
+    Start,
+    Steer,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize, JsonSchema, TS)]
@@ -57,3 +104,7 @@ pub enum BemItemPresentation {
     InlineMarkdown,
     InlineVisualization { index: u32 },
 }
+
+#[cfg(test)]
+#[path = "realtime_tests.rs"]
+mod tests;

codex-rs/protocol/src/realtime_tests.rs

@@ -0,0 +1,22 @@
+#![cfg(test)]
+
+//! Validates the sparse channel envelope written by new voice calls.
+
+use super::RealtimeItem;
+use pretty_assertions::assert_eq;
+
+#[test]
+fn frame_roundtrips_and_requires_a_voice_payload() {
+    let frame = serde_json::json!({
+        "id": "speech",
+        "realtime_session_id": "voice",
+        "observed_at_ms": 1050,
+        "type": "frame",
+        "channels": { "voice_transcript": { "role": "assistant", "text": "hello" } },
+    });
+    let item = serde_json::from_value::<RealtimeItem>(frame.clone()).unwrap();
+    assert_eq!(serde_json::to_value(item).unwrap(), frame);
+    let mut empty = frame;
+    empty["channels"] = serde_json::json!({});
+    assert!(serde_json::from_value::<RealtimeItem>(empty).is_err());
+}