Struct SessionHandle 

pub struct SessionHandle { /* private fields */ }

The public API surface for a Gemini Live session.

Cheaply cloneable (wraps Arc). Provides methods to send commands, subscribe to events, and observe session state.

Implementations

impl SessionHandle

pub fn new( command_tx: Sender<SessionCommand>, event_tx: Sender<SessionEvent>, state: Arc<SessionState>, phase_rx: Receiver<SessionPhase>, ) -> SessionHandle

Create a new session handle from its components.

pub fn with_audio_pacing(self, config: BackpressureConfig) -> SessionHandle

Enable producer-side audio send pacing (token bucket).

Installed by the connection layer when SessionConfig::audio_pacing is set.

pub fn set_task(&self, handle: JoinHandle<()>)

Store the connection loop task handle.

Called by the transport layer after spawning the connection loop.

pub async fn join(&self) -> Result<(), JoinError>

Wait for the session connection loop to complete.

Returns Ok(()) when the session disconnects normally. Returns Err if the connection task panicked.

Only the first call across all clones actually awaits the task; subsequent calls return Ok(()) immediately.

pub fn subscribe(&self) -> Receiver<SessionEvent>

Subscribe to session events.

pub fn event_sender(&self) -> &Sender<SessionEvent>

The event broadcaster, for a runtime that injects its own events into the session stream (the L1 agent session does). Application code wants subscribe.

pub fn resume_handle(&self) -> Option<String>

The most recent session-resumption handle the server issued, if any.

pub fn phase(&self) -> SessionPhase

Current session phase.

pub fn session_id(&self) -> &str

Session ID.

pub async fn wait_for_phase(&self, target: SessionPhase)

Wait for the session to reach a specific phase.

pub async fn send_audio( &self, data: impl Into<Bytes>, ) -> Result<(), SessionError>

Send audio data (raw PCM16 bytes).

When SessionConfig::audio_pacing is configured, this paces the caller: pushing audio faster than the configured sustained rate waits here instead of overflowing the send queue.

pub async fn send_text( &self, text: impl Into<String>, ) -> Result<(), SessionError>

Send a text message.

pub async fn send_tool_response( &self, responses: Vec<FunctionResponse>, ) -> Result<(), SessionError>

Send tool responses.

pub async fn send_video( &self, jpeg_data: impl Into<Bytes>, ) -> Result<(), SessionError>

Send a video/image frame (raw JPEG bytes).

pub async fn update_instruction( &self, instruction: impl Into<String>, ) -> Result<(), SessionError>

Update the system instruction mid-session.

pub async fn signal_activity_start(&self) -> Result<(), SessionError>

Signal activity start (user started speaking).

pub async fn signal_activity_end(&self) -> Result<(), SessionError>

Signal activity end (user stopped speaking).

pub async fn send_client_content( &self, turns: Vec<Content>, turn_complete: bool, ) -> Result<(), SessionError>

Send client content (turns + turn_complete flag). Used for injecting conversation history, context, or multi-turn text.

pub async fn disconnect(&self) -> Result<(), SessionError>

Gracefully disconnect the session.

Trait Implementations

impl Clone for SessionHandle

fn clone(&self) -> SessionHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SessionHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl SessionReader for SessionHandle

fn subscribe(&self) -> Receiver<SessionEvent>

Subscribe to the session event broadcast stream.

fn phase(&self) -> SessionPhase

Returns the current session phase.

fn session_id(&self) -> &str

Returns the unique session ID.

impl SessionWriter for SessionHandle

fn send_audio<'life0, 'async_trait>( &'life0 self, data: Bytes, ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>

where 'life0: 'async_trait, SessionHandle: 'async_trait,

Send raw PCM16 audio bytes.

fn send_text<'life0, 'async_trait>( &'life0 self, text: String, ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>

where 'life0: 'async_trait, SessionHandle: 'async_trait,

Send a text message.

fn send_tool_response<'life0, 'async_trait>( &'life0 self, responses: Vec<FunctionResponse>, ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>

where 'life0: 'async_trait, SessionHandle: 'async_trait,

Send tool/function call responses back to the model.

fn send_client_content<'life0, 'async_trait>( &'life0 self, turns: Vec<Content>, turn_complete: bool, ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>

where 'life0: 'async_trait, SessionHandle: 'async_trait,

Send client content (conversation history or context).

fn send_video<'life0, 'async_trait>( &'life0 self, jpeg_data: Bytes, ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>

where 'life0: 'async_trait, SessionHandle: 'async_trait,

Send a video/image frame (raw JPEG bytes).

fn update_instruction<'life0, 'async_trait>( &'life0 self, instruction: String, ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>

where 'life0: 'async_trait, SessionHandle: 'async_trait,

Update the system instruction mid-session.

fn signal_activity_start<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>

where 'life0: 'async_trait, SessionHandle: 'async_trait,

Signal that user speech activity has started.

fn signal_activity_end<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>

where 'life0: 'async_trait, SessionHandle: 'async_trait,

Signal that user speech activity has ended.

fn disconnect<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), SessionError>> + Send + 'async_trait>>

where 'life0: 'async_trait, SessionHandle: 'async_trait,

Gracefully disconnect the session.