Struct LiveHandle 

pub struct LiveHandle { /* private fields */ }

Handle for interacting with a running Live session.

Provides send methods for audio/text/video, system instruction updates, event subscription, state access, telemetry, and graceful shutdown.

When ContextDelivery::Deferred is enabled, send_audio, send_text, and send_video automatically flush any pending context turns before forwarding the user content.

Implementations

impl LiveHandle

pub async fn send_audio(&self, data: Vec<u8>) -> Result<(), SessionError>

Send audio data (raw PCM16 16kHz bytes).

When deferred context delivery is enabled, any pending model-role context turns are flushed to the wire before the audio frame.

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

Send a text message.

When deferred context delivery is enabled, any pending model-role context turns are flushed to the wire before the text message.

pub async fn send_video(&self, jpeg_data: Vec<u8>) -> Result<(), SessionError>

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

When deferred context delivery is enabled, any pending model-role context turns are flushed to the wire before the video frame.

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

Update the system instruction mid-session.

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

Send tool responses manually (if not using auto-dispatch).

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

Notify the runtime that client-side playback has drained.

Voice UIs should call this only when it is safe for the model to speak, for example after browser speaker playback has drained and the user is not actively speaking. User audio/text sends intentionally flush context only and leave the prompt armed.

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

Notify the runtime that client-side user speech has started.

This is the barge-in edge for voice clients: pending model prompts are cancelled before they can race with user audio, while queued context is kept so the next user send can still carry it.

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

Notify the runtime that client-side user speech has ended.

pub fn voice_state(&self) -> VoiceRuntimeState

Snapshot the reactor-owned voice runtime state.

pub fn input_vad_state(&self) -> BackendVadSnapshot

Snapshot backend input VAD state.

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

Flush deferred context and any pending model prompt.

Prefer Self::playback_drained for voice clients. This compatibility method routes through the same reactor/effect executor path.

pub fn writer(&self) -> Arc<dyn SessionWriter>

Get the user-facing session writer.

When deferred context delivery is enabled, this returns the DeferredWriter that flushes pending context before sends.

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

Subscribe to raw session events (for custom processing).

pub fn phase(&self) -> SessionPhase

Get the current session phase.

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

Gracefully disconnect the session.

Shutdown sequence:

1. Cancel all in-flight background tool tasks (they are aborted at an await point; tool futures must therefore be drop-safe).
2. Close the L0 session. The terminal Disconnected event makes the event router exit, which closes the lane channels.
3. Grace-await the fast and control lanes (~250 ms each) so they can drain queued events and run their final persistence drain, then abort whatever is still stuck (e.g. a lane blocked in a slow tool).
4. Cancel the telemetry lane.

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

Wait for the session to end (disconnect, GoAway, or error).

pub fn session(&self) -> &SessionHandle

Get the underlying SessionHandle for advanced usage.

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

Latest session-resumption handle issued by the server, if any.

While session resumption is enabled (SessionConfig::session_resumption; L2: Live::builder().session_resume(true)), the Gemini server periodically sends SessionResumptionUpdate messages; this returns the most recent handle (also captured in persistence snapshots as SessionSnapshot::resume_handle).

To survive a server-initiated GoAway or a planned restart, read this handle (e.g. from the on_go_away callback) and pass it to session_resumption(Some(handle)) on the next connect’s SessionConfig. No automatic reconnect is performed — resumption is an explicit caller decision.

Returns None when resumption is disabled or no update has arrived yet.

pub fn state(&self) -> &State

Access the shared State container.

Extraction results from TurnExtractors are stored here under the extractor’s name. Use state().get::<T>(name) to read typed values.

pub fn telemetry(&self) -> &Arc<SessionTelemetry>

Access the session telemetry (auto-collected by the telemetry lane).

Use telemetry().snapshot() to get a JSON snapshot of all metrics.

pub fn events(&self) -> Receiver<LiveEvent>

Subscribe to semantic events from the processor.

Returns a broadcast receiver. Call multiple times for independent subscribers. Zero-cost when no subscribers exist.

pub fn stream(&self) -> LiveEventStream

Subscribe to semantic events as a [futures::Stream].

Stream-flavored sibling of events: each call creates an independent subscriber starting from the current point in the event flow. If the subscriber falls behind the broadcast buffer, the missed events are skipped and the stream continues; the stream ends when the session’s event channel closes. See LiveEventStream.

Example

use futures::StreamExt;

let mut stream = handle.stream();
while let Some(ev) = stream.next().await {
    match ev {
        LiveEvent::TextDelta(t) => print!("{t}"),
        LiveEvent::TurnComplete => println!(),
        _ => {}
    }
}

pub fn extracted<T: DeserializeOwned>(&self, name: &str) -> Option<T>

Convenience: get the latest extraction result by extractor name.

pub fn explain(&self) -> Option<FlowExplanation>

Snapshot the governed flow’s control-plane state: active steps, which tools are admitted vs blocked (with reasons), and unmet requirements.

The deterministic answer to “why did the assistant ask that?” — computed against the live State and the marking the control lane maintains. Returns None when the session is not governed by a flow (Live::govern/observe was not used).

This is a synchronous snapshot: it briefly locks the shared FlowMonitor and never blocks on session I/O.

pub fn why_blocked(&self) -> Option<FlowExplanation>

Why the governed flow is blocked right now — alias of explain, named for the common debugging question. Returns None when the session is not governed by a flow.

Trait Implementations

impl Clone for LiveHandle

fn clone(&self) -> LiveHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.