muse-code-sdk 1.4.11

Async Rust client for Muse Code over MSP
Documentation
# `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 safe same-command retry that never
  double-submits.

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`.