Struct Client 

pub struct Client { /* private fields */ }

Stateful client for multi-turn Gemini CLI sessions.

Each Client instance manages a single Gemini CLI subprocess and JSON-RPC session. Calls to send / [send_content] return streams of Message values translated from raw session/update notifications.

Lifecycle

1. Construct with Client::new.
2. Call connect — this spawns the subprocess and runs the handshake.
3. Call send one or more times to converse with the model.
4. Call close when finished. Dropping without closing is safe but may leave the subprocess running briefly until the OS reclaims it.

Threading

Client is Send but not Sync. Share across tasks by wrapping in Arc<Mutex<Client>> when concurrent access is required.

Implementations

impl Client

pub fn new(config: ClientConfig) -> Result<Self>

Create a new client with the given configuration.

Resolves the gemini binary path (via config.cli_path or PATH) and constructs a GeminiTransport. The subprocess is not spawned until connect is called.

Errors

Returns Error::CliNotFound when the binary cannot be located on PATH and config.cli_path is None.

pub fn with_gemini_transport( config: ClientConfig, transport: Arc<GeminiTransport>, ) -> Self

Create a client backed by a caller-supplied GeminiTransport.

Useful when the caller has already constructed the transport with custom parameters (e.g. a non-default working directory or extra env vars).

pub fn session_id(&self) -> Option<&str>

Return the session ID assigned by the server, or None before connect is called.

pub fn prompt(&self) -> &str

Return the prompt field from the config.

Exposed as a convenience for the free-function wrappers in lib.rs that need to send the initial prompt without a separate send() call.

pub fn is_connected(&self) -> bool

Return true if connect has been called successfully.

pub async fn connect(&mut self) -> Result<SessionInfo>

Connect to the Gemini CLI and establish a session.

Performs the full initialisation sequence in order:

1. Spawn the subprocess via Transport::connect.
2. Take the notification stream (must happen before any requests).
3. Register the optional [PermissionHandler] as the reverse-request handler.
4. Send the initialize JSON-RPC request and await the result.
5. Send session/new (or session/load when config.resume is set).
6. Initialise the [TranslationContext] and hook context.

Returns SessionInfo describing the established session.

Errors

• Error::Config — called more than once on the same client.
• Error::SpawnFailed — the subprocess could not be started.
• Error::JsonRpcError — the server rejected initialize or session/new.
• Error::NotConnected — internal transport error during the handshake.

pub async fn send( &self, message: &str, ) -> Result<impl Stream<Item = Result<Message>> + '_>

Send a plain-text prompt and return a stream of translated Message values.

Convenience wrapper around send_content that constructs a single UserContent::Text block from the provided string slice.

Errors

Returns Error::NotConnected if connect has not been called. Returns Error::Config if a UserPromptSubmit hook blocks the send.

pub async fn send_content( &self, content: Vec<UserContent>, ) -> Result<impl Stream<Item = Result<Message>> + '_>

Send structured content and return a stream of translated Message values.

Accepts any mix of UserContent variants (text, base-64 image, URL image). The content is serialised to WireContentBlock format and sent to the CLI as a session/prompt JSON-RPC notification. The returned stream drains session/update notifications from the shared channel until the transport closes or the caller drops the stream.

Backpressure

The notification channel is shared across all send_content calls on the same client. Only one stream should be active at a time; concurrent polling will contend on the notification_stream Mutex and may interleave results.

Errors

Returns Error::NotConnected if connect has not been called. Returns Error::Config if a UserPromptSubmit hook blocks the send.

pub async fn interrupt(&self) -> Result<()>

Interrupt the current in-progress prompt turn.

Sends a session/cancel notification to the CLI (best-effort) and then delivers a process-level interrupt signal via the transport (SIGINT on Unix, CTRL_C_EVENT on Windows).

Errors

The session/cancel notification errors are silently ignored. Transport interrupt errors are propagated.

pub async fn close(&mut self) -> Result<()>

Close the client and terminate the CLI subprocess.

Fires the Stop lifecycle hook before closing the transport. The call is idempotent — invoking it on an already-closed client is safe.

Errors

Propagates errors from the transport’s close() implementation. Hook errors are silently ignored.