Files
codex/codex-rs/protocol/src/realtime.rs
T
Zahan Malkani 29cb67623c Gate local realtime frame history on paginated storage (#62271)
## Why

Legacy rollout migration rewrites rolled-back history and can disrupt
the realtime stream. Enroll local threads once they use paginated history
so the stream stays intact.

## What changed

- Add the off-by-default `features.realtime_frames_local` flag for
  paginated local threads with a state database. Accept runtime updates
  through the app server and keep threads enrolled once they have a
  persisted canonical session start.
- Add thread-store APIs to recover a realtime session and look up the
  latest session ID from durable history. Route frame completion through
  a store seal so completion acknowledges durable writes.
- Add a local seal for accepted model input that writes source frames
  before the input and lets callers retry an uncertain flush without
  appending the input twice.

## Testing

Cover enrollment for legacy and paginated threads, continued enrollment
after disabling the flag, and retrying a local input seal after a failed
directory sync.

GitOrigin-RevId: 2012feeca3857da90f9b026f077b31a26d15191b
2026-11-18 12:55:14 +00:00

124 lines
4.0 KiB
Rust

use schemars::JsonSchema;
use serde::Deserialize;
use serde::Serialize;
use ts_rs::TS;
/// A realtime thread item persisted in the canonical rollout.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, JsonSchema, 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. Currently, `voice_transcript` is required.
#[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,
},
BemItemPromoted {
turn_id: String,
item_id: String,
presentation: BemItemPresentation,
},
RealtimeSessionClosed {
outcome: RealtimeSessionOutcome,
/// Hosted frame-table sequence of the session's last frame (zero for a silent call).
#[serde(default, skip_serializing_if = "Option::is_none")]
#[ts(type = "number | null", optional)]
final_frame_sequence: Option<u64>,
},
/// 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,
},
/// Transcript input saved in model history without starting or steering an agent turn.
SessionInputSaved {
reason: SessionInputReason,
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 SessionInputReason {
Chunk,
SessionEnd,
}
#[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)]
#[serde(rename_all = "snake_case")]
#[ts(rename_all = "snake_case")]
pub enum RealtimeSessionOutcome {
Ended,
Failed,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize, JsonSchema, TS)]
#[serde(rename_all = "snake_case")]
#[ts(rename_all = "snake_case")]
pub enum RealtimeTranscriptRole {
User,
Assistant,
}
/// How an existing agent item is presented in the realtime conversation.
#[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 BemItemPresentation {
WholeItem,
InlineMarkdown,
InlineVisualization { index: u32 },
}
#[cfg(test)]
#[path = "realtime_tests.rs"]
mod tests;