# `muse-code-sdk`
The Rust SDK for Muse Code: an async client for driving a Muse Code agent
over the Muse Session Protocol (MSP), on your own Tokio runtime.
- Spawn a `muse serve` host, or attach to a transport you already run.
- Open and resume sessions; stream a turn's items as they arrive and await
the turn's server-authored outcome.
- Answer tool-approval requests with a handler you register.
- A client-side fold keeps a live, typed view of the session, with gap
recovery after reconnects and same-command retry: a host that can still
read the earlier submission answers with its first decision instead of
running it twice (a restarted host that cannot read it may run it again).
The generated MSP wire types are in `muse_code_sdk::msp`. Rust 1.97+.
## Versioning and stability
- The crate version is the Muse Code release it ships with: `muse-code-sdk`
`X.Y.Z` pairs with Muse Code `X.Y.Z`, and every release moves both together.
- The stable MSP surface follows the Muse Code product's compatibility
promise. Surfaces marked experimental may change or be removed in any
release.
- Cargo treats every `1.x` release as compatible, but a Muse Code minor
release can change the protocol. Pin the exact version that matches your
Muse Code release:
```toml
[dependencies]
muse-code-sdk = "=X.Y.Z"
```
- Open protocol enums are `#[non_exhaustive]`: a `match` on them needs a
catch-all `_` arm, and a release that adds a value does not break your
build.
- So are the SDK's own public enums (its errors, outcomes and states): match
them with a catch-all `_` arm too, and a release that adds an error or an
outcome does not break your build.
- Protocol structs that you only receive from the host (results,
notifications, items, error objects) are `#[non_exhaustive]` too, so a
release that adds a field does not break your build; to build one, for
example in a test that scripts a host, decode it from its wire JSON. The
params you send (`TurnInputPart`, `SessionConfig`, and the params of every
method) stay buildable with struct literals.
## Before you start
- **Install Muse Code.** `curl https://dev.meta.ai/install.sh | bash` installs
a checksum-verified `muse` launcher in `~/.local/bin`, adds it to your
`PATH`, and keeps it up to date; the
[user manual](https://dev.meta.ai/docs/muse-code) has the details. Open a
new shell afterwards. The SDK runs the binary you name in
`SpawnOptions::muse_bin`, or else the first `muse` on `PATH`: a program
started from a shell opened before the install fails with "no muse host
found", and an older `muse` earlier on `PATH` is used silently.
- **Log in once.** Run `muse` and log in, so the host has provider
credentials. A host without them fails every turn.
- **Pair the versions.** Run `muse --version` and install this crate at that
same `X.Y.Z` (see Versioning and stability above). The installed `muse`
updates itself, so it can move ahead of your pinned crate. If that release
changed the protocol, the connection reports `fingerprint_warning` and stays
open, but calls whose shape changed can fail. Either way, move your pin to
the version `muse --version` prints.
## Install
```sh
cargo add muse-code-sdk@=X.Y.Z
cargo add tokio --features macros,rt
```
The second line is for the sample below: it runs on tokio
(`#[tokio::main]`), which this crate uses but does not re-export.
## Use
```rust,no_run
use muse_code_sdk::client::{MuseClient, StartSessionOptions};
use muse_code_sdk::msp::{TurnInputPart, TurnInputPartType};
use muse_code_sdk::session::SendUserTurnOptions;
use muse_code_sdk::spawn::SpawnOptions;
use muse_code_sdk::turn::TurnOutcome;
#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let connection = MuseClient::spawn(SpawnOptions::default()).await?;
let client = connection.client;
let session = client.start_session(StartSessionOptions::default()).await?;
let turn = session
.send_user_turn(SendUserTurnOptions {
input: vec![text_part("Summarize this repository.")],
..SendUserTurnOptions::default()
})
.await?;
let mut items = turn.items();
while let Some(item) = items.recv().await? {
println!("{:?}", item.kind);
}
match turn.completed().await? {
TurnOutcome::Completed { params, .. } => println!("turn ended as {:?}", params.terminal),
TurnOutcome::Unqueued(params) => println!("turn {} was unqueued", params.turn_id),
_ => println!("turn ended"),
}
client.close().await;
Ok(())
}
fn text_part(text: impl Into<String>) -> TurnInputPart {
TurnInputPart {
part_type: TurnInputPartType::Text,
text: Some(text.into()),
media_type: None,
base64_data: None,
width: None,
height: None,
selector: None,
arguments: None,
upload_id: None,
source: None,
}
}
```
The crate's `examples/` directory has a fuller quickstart and recipes for
approvals, retries, and cancellation.
## Documentation
- API reference: <https://docs.rs/muse-code-sdk>
- Guides and the protocol reference: <https://meta-models.github.io/muse-code-sdk/>
- Source and issues: <https://github.com/meta-models/muse-code-sdk>
## License
MIT. See `LICENSE`.