muse-code-sdk 1.4.12

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