muse-code-sdk 1.4.20

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:

    [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 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

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

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,
        client_ref: None,
        source: None,
    }
}

The crate's examples/ directory has a fuller quickstart and recipes for approvals, retries, and cancellation.

Documentation

License

MIT. See LICENSE.