muse_code_sdk/lib.rs
1//! Async, caller-runtime-owned Rust client for the Muse Stream Protocol.
2//!
3//! The SDK can spawn a `muse serve` host, or attach to a caller-owned
4//! [`DuplexTransport`]. Both constructors complete the initialization
5//! handshake before returning a [`client::MuseClientConnection`], including
6//! any warning-only schema fingerprint mismatch.
7//!
8//! A [`session::Session`] submits turns
9//! ([`session::Session::send_user_turn`]), answers approvals through a
10//! handler ([`session::Session::on_approval`]) and questions
11//! ([`session::Session::answer_user_input`]), and keeps a fold of the events
12//! it applied, read through [`session::Session::fold`]. After a transport
13//! drop on a durable client, [`session::Session::pending`] lists the
14//! submissions it never saw settle, and
15//! [`session::Session::resolve_reconnect`] resends them on the resumed
16//! session.
17//!
18//! ```no_run
19//! use muse_code_sdk::client::{MuseClient, StartSessionOptions};
20//! use muse_code_sdk::msp::{TurnInputPart, TurnInputPartType};
21//! use muse_code_sdk::session::SendUserTurnOptions;
22//! use muse_code_sdk::spawn::SpawnOptions;
23//! use muse_code_sdk::turn::TurnOutcome;
24//!
25//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
26//! let connection = MuseClient::spawn(SpawnOptions::default()).await?;
27//! let client = connection.client;
28//! let session = client.start_session(StartSessionOptions::default()).await?;
29//! let turn = session
30//! .send_user_turn(SendUserTurnOptions {
31//! input: vec![text_part("Summarize this repository.")],
32//! ..SendUserTurnOptions::default()
33//! })
34//! .await?;
35//!
36//! let mut items = turn.items();
37//! while let Some(item) = items.recv().await? {
38//! drop(item);
39//! }
40//! match turn.completed().await? {
41//! TurnOutcome::Completed { params, .. } => println!("turn ended as {:?}", params.terminal),
42//! TurnOutcome::Unqueued(params) => println!("turn {} was unqueued", params.turn_id),
43//! _ => println!("turn ended"),
44//! }
45//! client.close().await;
46//! # Ok(())
47//! # }
48//! #
49//! # fn text_part(text: impl Into<String>) -> TurnInputPart {
50//! # TurnInputPart {
51//! # part_type: TurnInputPartType::Text,
52//! # text: Some(text.into()),
53//! # media_type: None,
54//! # base64_data: None,
55//! # width: None,
56//! # height: None,
57//! # selector: None,
58//! # arguments: None,
59//! # upload_id: None,
60//! # source: None,
61//! # }
62//! # }
63//! ```
64
65use std::future::Future;
66use std::io;
67use std::pin::Pin;
68
69/// Outside this crate, every public enum in the SDK's own API (errors,
70/// outcomes and states) is `#[non_exhaustive]`, so a later release can add a
71/// variant without breaking your build. A `match` on one needs a catch-all arm;
72/// an exhaustive match without one does not compile.
73///
74/// ```compile_fail,E0004
75/// use muse_code_sdk::turn::TurnOutcome;
76///
77/// fn name(outcome: &TurnOutcome) -> &'static str {
78/// match outcome {
79/// TurnOutcome::Completed { .. } => "completed",
80/// TurnOutcome::Unqueued(_) => "unqueued",
81/// TurnOutcome::Ended(_) => "ended",
82/// }
83/// }
84/// ```
85///
86/// ```compile_fail,E0004
87/// use muse_code_sdk::turn::TurnWaitError;
88///
89/// fn name(error: &TurnWaitError) -> &'static str {
90/// match error {
91/// TurnWaitError::SourceClosed => "source closed",
92/// TurnWaitError::ClientClosed => "client closed",
93/// TurnWaitError::EventSourceFailed { .. } => "event source failed",
94/// }
95/// }
96/// ```
97///
98/// With the catch-all arm, both compile:
99///
100/// ```
101/// use muse_code_sdk::turn::{TurnOutcome, TurnWaitError};
102///
103/// fn outcome(outcome: &TurnOutcome) -> &'static str {
104/// match outcome {
105/// TurnOutcome::Completed { .. } => "completed",
106/// TurnOutcome::Unqueued(_) => "unqueued",
107/// _ => "other",
108/// }
109/// }
110///
111/// fn error(error: &TurnWaitError) -> &'static str {
112/// match error {
113/// TurnWaitError::SourceClosed => "source closed",
114/// TurnWaitError::ClientClosed => "client closed",
115/// TurnWaitError::EventSourceFailed { .. } => "event source failed",
116/// _ => "other",
117/// }
118/// }
119/// ```
120#[cfg(doctest)]
121pub struct OpenEnumsNeedACatchAllArm;
122
123pub mod approval;
124pub mod client;
125pub mod connection;
126pub mod errors;
127pub mod fingerprint;
128pub mod fold;
129pub mod gap;
130pub mod handshake;
131pub mod host_death;
132pub mod msp;
133pub mod pending;
134pub mod session;
135pub mod spawn;
136pub mod turn;
137
138/// A two-way stream of decoded UTF-8 chunks and outgoing newline-framed MSP.
139///
140/// Inbound chunks may be empty or split at any point; the connection assembles
141/// frames. `write` means a frame was handed to the transport, not that the
142/// server completed the command. The implementer decodes bytes incrementally.
143/// Neither method creates a runtime: callers drive both on their Tokio runtime.
144pub trait DuplexTransport: Send {
145 /// Returns the next decoded chunk, or `None` after transport EOF.
146 fn read_chunk(
147 &mut self,
148 ) -> Pin<Box<dyn Future<Output = io::Result<Option<String>>> + Send + '_>>;
149
150 /// Submits an already newline-framed outgoing message.
151 fn write(&mut self, frame: &str) -> Pin<Box<dyn Future<Output = io::Result<()>> + Send + '_>>;
152}